@interf/compiler 0.6.1 → 0.6.4

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

@@ -0,0 +1,210 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { isWorkflowId, listLocalWorkflowDefinitions, loadLocalWorkflowDefinition, loadWorkflowDefinitionFromDir, } from "./local-workflows.js";
+import { warnInterf } from "../shared/logger.js";
+import { workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
+import { resolveSourceControlPath } from "../project-model/interf.js";
+import { PACKAGE_ROOT } from "./lib/package-root.js";
+import { deriveWorkflowInputsFromContextInterface, } from "./context-interface.js";
+import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
+let builtinInterfWorkflowCache = null;
+function toWorkflowStages(stages, fallbackStages) {
+    if (!stages || stages.length === 0)
+        return [...fallbackStages];
+    return stages.map((stage) => ({
+        id: stage.id,
+        label: stage.label,
+        description: stage.description ?? stage.label,
+        contractType: stage.contract_type,
+        skillDir: stage.skill_dir ?? stage.id,
+        reads: [...stage.reads],
+        writes: [...stage.writes],
+        ...(stage.acceptance ? { acceptance: stage.acceptance } : {}),
+    }));
+}
+export function standaloneWorkflowDefinitionFromLocalPackage(local) {
+    if (!local.stages || local.stages.length === 0) {
+        throw new Error(`Workflow package "${local.id}" is missing explicit stages. Compiled-local and portable workflow packages must be standalone.`);
+    }
+    const stages = toWorkflowStages(local.stages, []);
+    const contextInterface = local.workflow_schema;
+    const inputs = local.inputs?.length
+        ? [...local.inputs]
+        : deriveWorkflowInputsFromContextInterface(contextInterface);
+    return {
+        id: local.id,
+        compilerApi: local.compiler_api ?? {
+            kind: "compiled",
+            version: 1,
+        },
+        ...(local.purpose
+            ? {
+                purpose: {
+                    label: local.purpose.label,
+                    taskHint: local.purpose.task_hint,
+                },
+            }
+            : {}),
+        inputs,
+        label: local.label,
+        hint: local.hint,
+        recommended: false,
+        contextInterface,
+        ...(contextInterface ? { schema: contextInterface } : {}),
+        stages,
+        stagePolicyNotes: mergeStagePolicyNotesForStages(stages, undefined, local.stage_policy_notes),
+        starterDocs: [...local.starter_docs],
+        scope: "local",
+    };
+}
+function builtinWorkflowPackagePath(workflowId) {
+    return join(PACKAGE_ROOT, "builtin-workflows", workflowId);
+}
+function getBuiltinInterfWorkflow() {
+    if (builtinInterfWorkflowCache)
+        return builtinInterfWorkflowCache;
+    const local = loadWorkflowDefinitionFromDir(builtinWorkflowPackagePath("interf"));
+    if (!local) {
+        throw new Error("Missing built-in Interf workflow package at builtin-workflows/interf.");
+    }
+    const resolved = standaloneWorkflowDefinitionFromLocalPackage(local);
+    builtinInterfWorkflowCache = {
+        ...resolved,
+        id: "interf",
+        recommended: true,
+        scope: "builtin",
+    };
+    return builtinInterfWorkflowCache;
+}
+function listBuiltinCompiledWorkflows() {
+    return [getBuiltinInterfWorkflow()];
+}
+function resolveCompiledWorkflowFromLocal(workflowId, sourcePath) {
+    const local = loadLocalWorkflowDefinition(sourcePath, workflowId);
+    if (!local)
+        return null;
+    if (local.extends) {
+        throw new Error(`Workflow "${workflowId}" uses legacy extends. Rewrite it as a standalone package before creating or compiling a compiled context.`);
+    }
+    const resolved = standaloneWorkflowDefinitionFromLocalPackage(local);
+    return resolved;
+}
+export function listCompiledWorkflowChoices(sourcePath) {
+    const builtins = listBuiltinCompiledWorkflows();
+    if (!sourcePath)
+        return builtins;
+    const locals = listLocalWorkflowDefinitions(sourcePath)
+        .filter((definition) => definition.id !== "interf")
+        .map((definition) => {
+        try {
+            return resolveCompiledWorkflowFromLocal(definition.id, sourcePath);
+        }
+        catch (error) {
+            warnInterf(`Warning: skipping local workflow "${definition.id}" because it could not be resolved cleanly: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    })
+        .filter((definition) => definition !== null);
+    return [...builtins, ...locals];
+}
+export function getCompiledWorkflow(workflowId, options = {}) {
+    const builtin = listBuiltinCompiledWorkflows().find((candidate) => candidate.id === workflowId);
+    if (builtin)
+        return builtin;
+    if (options.sourcePath) {
+        const local = resolveCompiledWorkflowFromLocal(workflowId, options.sourcePath);
+        if (local)
+            return local;
+        throw new Error(`No local workflow package found for "${workflowId}" under ${join(options.sourcePath, "interf", "workflows", workflowId)}.`);
+    }
+    throw new Error(`Workflow "${workflowId}" is not built-in. Provide a source path so Interf can resolve a local workflow package.`);
+}
+export function getActiveCompiledWorkflow(compiledPath, fallbackWorkflowId) {
+    const workflowPath = workflowPackagePathForCompiled(compiledPath);
+    if (existsSync(join(workflowPath, "workflow.json"))) {
+        const local = loadWorkflowDefinitionFromDir(workflowPath);
+        if (!local) {
+            throw new Error(`Local workflow package at ${workflowPath} is missing or invalid. Interf compile runs the local package directly; recreate or reseed this compiled context instead of relying on source-root fallback.`);
+        }
+        if (local.extends) {
+            throw new Error(`Local workflow package at ${workflowPath} still uses legacy extends. Materialize it as a standalone package before compiling this compiled context.`);
+        }
+        return standaloneWorkflowDefinitionFromLocalPackage(local);
+    }
+    throw new Error(`Missing local workflow package at ${workflowPath}. Interf compile runs the local package directly, so recreate or reseed this compiled context instead of relying on source-root workflow "${fallbackWorkflowId}" under ${resolveSourceControlPath(compiledPath)}.`);
+}
+export function resolveCompiledWorkflowId(value) {
+    if (typeof value === "string" && isWorkflowId(value)) {
+        return value;
+    }
+    return null;
+}
+export function resolveCompiledWorkflowFromConfig(config) {
+    if (!config || typeof config !== "object")
+        return null;
+    const raw = config;
+    return resolveCompiledWorkflowId(raw.workflow);
+}
+export function resolveRequiredCompiledWorkflowFromConfig(config, label = "compiled config") {
+    const workflowId = resolveCompiledWorkflowFromConfig(config);
+    if (!workflowId) {
+        throw new Error(`Missing or invalid workflow in ${label}.`);
+    }
+    return workflowId;
+}
+export function formatCompiledWorkflowStageStep(workflowId, stage, options = {}) {
+    return formatWorkflowStageStep(getCompiledWorkflow(workflowId, options), stage);
+}
+function resolveWorkflowDefinitionForStageMetadata(workflowId, sourcePath) {
+    if (sourcePath &&
+        existsSync(join(workflowPackagePathForCompiled(sourcePath), "workflow.json"))) {
+        return getActiveCompiledWorkflow(sourcePath, workflowId);
+    }
+    return getCompiledWorkflow(workflowId, { sourcePath });
+}
+function formatWorkflowStageStep(workflow, stage) {
+    const stageIndex = workflow.stages.findIndex((candidate) => candidate.id === stage);
+    if (stageIndex === -1) {
+        throw new Error(`Stage "${stage}" is not part of the compiled runtime.`);
+    }
+    const stageDefinition = workflow.stages[stageIndex];
+    if (!stageDefinition) {
+        throw new Error(`Stage "${stage}" is not part of the compiled runtime.`);
+    }
+    return `Step ${stageIndex + 1}/${workflow.stages.length} - ${stageDefinition.label}`;
+}
+export function getWorkflowStageDefinition(workflowId, stage, sourcePath) {
+    const workflow = resolveWorkflowDefinitionForStageMetadata(workflowId, sourcePath);
+    return workflow.stages.find((candidate) => candidate.id === stage) ?? null;
+}
+export function getWorkflowStagePosition(workflowId, stage, sourcePath) {
+    const stages = getWorkflowStages(workflowId, sourcePath);
+    const stageIndex = stages.findIndex((candidate) => candidate === stage);
+    if (stageIndex === -1)
+        return null;
+    return {
+        stageIndex: stageIndex + 1,
+        stageTotal: stages.length,
+        stages: [...stages],
+    };
+}
+export function getWorkflowStages(workflowId, sourcePath) {
+    return resolveWorkflowDefinitionForStageMetadata(workflowId, sourcePath).stages.map((definition) => definition.id);
+}
+export function getActiveCompiledStages(compiledPath, fallbackWorkflowId) {
+    return getActiveCompiledWorkflow(compiledPath, fallbackWorkflowId).stages.map((definition) => definition.id);
+}
+export function getWorkflowStagePolicyNotes(workflowId, stage, sourcePath) {
+    const workflow = resolveWorkflowDefinitionForStageMetadata(workflowId, sourcePath);
+    return [...(workflow.stagePolicyNotes?.[stage] ?? [])];
+}
+export function getActiveCompiledStagePolicyNotes(compiledPath, fallbackWorkflowId, stage) {
+    const workflow = getActiveCompiledWorkflow(compiledPath, fallbackWorkflowId);
+    return [...(workflow.stagePolicyNotes?.[stage] ?? [])];
+}
+export function resolveActiveCompiledStageAcceptance(compiledPath, fallbackWorkflowId, stage) {
+    return getActiveCompiledWorkflow(compiledPath, fallbackWorkflowId).stages.find((candidate) => candidate.id === stage)?.acceptance;
+}
+export function formatActiveCompiledWorkflowStageStep(compiledPath, fallbackWorkflowId, stage) {
+    return formatWorkflowStageStep(getActiveCompiledWorkflow(compiledPath, fallbackWorkflowId), stage);
+}

package/dist/packages/workflow-package/workflow-helpers.d.ts

@@ -0,0 +1,38 @@
+import { type LocalInstructionMode, type RuntimeInstructionMode, type RuntimeStageInstructions } from "../compiler/lib/schema.js";
+import { type WorkflowStageDefinition } from "./workflow-definitions.js";
+export interface WorkflowReporter {
+    line?: (message: string) => void;
+    blankLine?: () => void;
+}
+export interface WorkflowStageResult {
+    ok: boolean;
+    code: number;
+    summary?: string | null;
+}
+export declare function workflowQueryDirectory(): string;
+export declare function workflowImproveDirectory(): string;
+export declare function workflowCompileStageDirectory(stageDir: string): string;
+export interface LocalSkillContractExtension {
+    reads: string[];
+    count: number;
+    notes: string[];
+    localMode: LocalInstructionMode | null;
+    effectiveMode: RuntimeInstructionMode;
+    modeSources: string[];
+}
+export declare function emptyLocalSkillContractExtension(): LocalSkillContractExtension;
+export declare function buildLocalSkillContractExtension(rootPath: string, directories: string[], purpose: string): LocalSkillContractExtension;
+export declare function buildLocalSkillContractExtensionRelativeTo(rootPath: string, relativeToPath: string, directories: string[], purpose: string): LocalSkillContractExtension;
+export declare function mergeLocalSkillContractExtensions(extensions: LocalSkillContractExtension[]): LocalSkillContractExtension;
+export declare function buildStageInstructions(stageSkillDir: string, localSkills: LocalSkillContractExtension): RuntimeStageInstructions;
+export declare function reportLine(reporter: WorkflowReporter | undefined, message: string): void;
+export declare function reportBlankLine(reporter: WorkflowReporter | undefined): void;
+export declare function reportValidationFailure(reporter: WorkflowReporter | undefined, summary: string, errors?: string[]): void;
+export declare function resolveStageAcceptance(workflowId: string, stageId: string, sourcePath?: string): WorkflowStageDefinition["acceptance"] | undefined;
+export declare function validateStageOutcome(_dirPath: string, validation: {
+    ok: boolean;
+    summary: string;
+}): {
+    ok: boolean;
+    summary: string;
+};

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

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { listFilesRecursive } from "../shared/filesystem.js";
+import { parseJsonFrontmatter } from "../shared/parse.js";
+import { isMarkdownFile } from "../shared/file-types.js";
+import { getCompiledWorkflow, } from "./workflow-definitions.js";
+import { workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
+const LOCAL_SKILL_READ_LIMIT = 50;
+export function workflowQueryDirectory() {
+    return "workflow/use/query";
+}
+export function workflowImproveDirectory() {
+    return "workflow/improve";
+}
+export function workflowCompileStageDirectory(stageDir) {
+    return `workflow/compile/stages/${stageDir}`;
+}
+export function emptyLocalSkillContractExtension() {
+    return {
+        reads: [],
+        count: 0,
+        notes: [],
+        localMode: null,
+        effectiveMode: "builtin",
+        modeSources: [],
+    };
+}
+function readLocalInstructionMode(filePath) {
+    try {
+        const parsed = parseJsonFrontmatter(readFileSync(filePath, "utf8"));
+        const mode = parsed?.frontmatter.mode;
+        return mode === "extend" || mode === "override" ? mode : null;
+    }
+    catch {
+        return null;
+    }
+}
+function collectLocalSkillDocs(rootPath, directories) {
+    return collectLocalSkillDocsRelativeTo(rootPath, rootPath, directories);
+}
+function collectLocalSkillDocsRelativeTo(rootPath, relativeToPath, directories) {
+    const docs = new Map();
+    const workflowRoot = workflowPackagePathForCompiled(rootPath);
+    const rootReadme = join(workflowRoot, "README.md");
+    if (existsSync(rootReadme)) {
+        const read = projectWorkflowReadPath(rootPath, relativeToPath, rootReadme);
+        docs.set(read, {
+            read,
+            absolutePath: rootReadme,
+            mode: readLocalInstructionMode(rootReadme),
+        });
+    }
+    for (const directory of directories) {
+        const absoluteDirectory = resolveAuthoringDirectory(rootPath, directory);
+        for (const filePath of listFilesRecursive(absoluteDirectory, isMarkdownFile)) {
+            const read = projectWorkflowReadPath(rootPath, relativeToPath, filePath);
+            docs.set(read, {
+                read,
+                absolutePath: filePath,
+                mode: readLocalInstructionMode(filePath),
+            });
+        }
+    }
+    return Array.from(docs.values())
+        .sort((a, b) => a.read.localeCompare(b.read))
+        .slice(0, LOCAL_SKILL_READ_LIMIT);
+}
+function resolveAuthoringDirectory(rootPath, directory) {
+    if (directory === "workflow") {
+        return workflowPackagePathForCompiled(rootPath);
+    }
+    if (directory.startsWith(`workflow${sep}`) || directory.startsWith("workflow/")) {
+        const relativeWorkflowPath = directory.replace(/^workflow[\\/]/, "");
+        return join(workflowPackagePathForCompiled(rootPath), relativeWorkflowPath);
+    }
+    return join(rootPath, directory);
+}
+function projectWorkflowReadPath(rootPath, relativeToPath, absolutePath) {
+    const workflowRoot = workflowPackagePathForCompiled(rootPath);
+    const normalizedWorkflowRoot = `${workflowRoot}${sep}`;
+    if (absolutePath === workflowRoot || absolutePath.startsWith(normalizedWorkflowRoot)) {
+        const relativeWorkflowPath = relative(workflowRoot, absolutePath);
+        return relative(relativeToPath, join(rootPath, "workflow", relativeWorkflowPath));
+    }
+    return relative(relativeToPath, absolutePath);
+}
+export function buildLocalSkillContractExtension(rootPath, directories, purpose) {
+    const docs = collectLocalSkillDocs(rootPath, directories);
+    return buildContractExtensionFromDocs(docs, directories, purpose);
+}
+export function buildLocalSkillContractExtensionRelativeTo(rootPath, relativeToPath, directories, purpose) {
+    const docs = collectLocalSkillDocsRelativeTo(rootPath, relativeToPath, directories);
+    return buildContractExtensionFromDocs(docs, directories, purpose);
+}
+function buildContractExtensionFromDocs(docs, directories, purpose) {
+    const reads = docs.map((doc) => doc.read);
+    const modeSources = docs.filter((doc) => doc.mode !== null).map((doc) => doc.read);
+    const localMode = docs.some((doc) => doc.mode === "override")
+        ? "override"
+        : docs.some((doc) => doc.mode === "extend")
+            ? "extend"
+            : null;
+    if (docs.length === 0) {
+        return emptyLocalSkillContractExtension();
+    }
+    const readNotice = directories.length > 0
+        ? `Read any local instruction docs listed under ${directories.join(", ")} before executing the core stage.`
+        : "Read any local instruction docs listed by the stage contract before executing the core stage.";
+    return {
+        reads,
+        count: reads.length,
+        notes: [
+            readNotice,
+            localMode === "override"
+                ? `${purpose} One or more local docs declare \`mode: override\`, so their workflow instructions replace Interf's bundled stage instructions for this run. They still do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`
+                : `${purpose} These local workflow docs can refine the stage, but they do not bypass coverage proof, evidence weighting, required writes, or deterministic runtime reconciliation.`,
+        ],
+        localMode,
+        effectiveMode: localMode ?? "builtin",
+        modeSources,
+    };
+}
+export function mergeLocalSkillContractExtensions(extensions) {
+    const reads = Array.from(new Set(extensions.flatMap((extension) => extension.reads)));
+    const notes = Array.from(new Set(extensions.flatMap((extension) => extension.notes)));
+    const modeSources = Array.from(new Set(extensions.flatMap((extension) => extension.modeSources)));
+    const localMode = extensions.some((extension) => extension.localMode === "override")
+        ? "override"
+        : extensions.some((extension) => extension.localMode === "extend")
+            ? "extend"
+            : null;
+    return {
+        reads,
+        count: reads.length,
+        notes,
+        localMode,
+        effectiveMode: localMode ?? "builtin",
+        modeSources,
+    };
+}
+export function buildStageInstructions(stageSkillDir, localSkills) {
+    return {
+        stage_skill_dir: stageSkillDir,
+        effective_mode: localSkills.effectiveMode,
+        local_mode: localSkills.localMode,
+        local_docs: localSkills.reads,
+        mode_sources: localSkills.modeSources,
+    };
+}
+export function reportLine(reporter, message) {
+    reporter?.line?.(message);
+}
+export function reportBlankLine(reporter) {
+    reporter?.blankLine?.();
+}
+export function reportValidationFailure(reporter, summary, errors = []) {
+    reportLine(reporter, summary);
+    for (const error of errors) {
+        reportLine(reporter, `- ${error}`);
+    }
+}
+export function resolveStageAcceptance(workflowId, stageId, sourcePath) {
+    return getCompiledWorkflow(workflowId, { sourcePath }).stages.find((stage) => stage.id === stageId)?.acceptance;
+}
+export function validateStageOutcome(_dirPath, validation) {
+    return validation;
+}

package/dist/packages/workflow-package/workflow-review-paths.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowImprovementContext } from "../compiler/lib/schema.js";
+export interface WorkflowImprovementReviewSourcePaths {
+    compiledRuntime: string | null;
+    testComparisons: string | null;
+    executionShells: string | null;
+    targetTestRuns: string | null;
+    targetTestSandboxes: string | null;
+}
+export declare function resolveWorkflowImprovementReviewSourcePaths(compiledPath: string): WorkflowImprovementReviewSourcePaths;
+export declare function resolveWorkflowImprovementReviewPaths(compiledPath: string): WorkflowImprovementContext["review_paths"];

package/dist/packages/workflow-package/workflow-review-paths.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { testRootForCompiled, targetTestRunsRootForCompiled, targetTestSandboxesRootForCompiled, stageExecutionShellsRoot, compiledRuntimeRoot, } from "../compiler/compiled-paths.js";
+export function resolveWorkflowImprovementReviewSourcePaths(compiledPath) {
+    const compiledRuntime = compiledRuntimeRoot(compiledPath);
+    const testComparisons = testRootForCompiled(compiledPath);
+    const executionShells = stageExecutionShellsRoot(compiledPath);
+    const targetTestRuns = targetTestRunsRootForCompiled(compiledPath);
+    const targetTestSandboxes = targetTestSandboxesRootForCompiled(compiledPath);
+    return {
+        compiledRuntime: existsSync(compiledRuntime) ? compiledRuntime : null,
+        testComparisons: existsSync(testComparisons) ? testComparisons : null,
+        executionShells: existsSync(executionShells) ? executionShells : null,
+        targetTestRuns: existsSync(targetTestRuns) ? targetTestRuns : null,
+        targetTestSandboxes: existsSync(targetTestSandboxes) ? targetTestSandboxes : null,
+    };
+}
+export function resolveWorkflowImprovementReviewPaths(compiledPath) {
+    const sources = resolveWorkflowImprovementReviewSourcePaths(compiledPath);
+    return {
+        workflow_root: "workflow",
+        compiled_runtime: sources.compiledRuntime ? "artifacts/compiled-runtime" : null,
+        test_comparisons: sources.testComparisons ? "artifacts/test-comparisons" : null,
+        execution_shells: sources.executionShells ? "artifacts/execution-shells" : null,
+        test_runs: sources.targetTestRuns ? "artifacts/test-runs" : null,
+        test_sandboxes: sources.targetTestSandboxes ? "artifacts/test-sandboxes" : null,
+    };
+}

package/dist/packages/workflow-package/workflow-stage-policy.d.ts

@@ -0,0 +1,5 @@
+export interface StagePolicyStageLike {
+    id: string;
+}
+export declare function normalizeStagePolicyNotes(value: unknown): Record<string, string[]> | undefined;
+export declare function mergeStagePolicyNotesForStages(stages: readonly StagePolicyStageLike[], baseNotes: unknown, overrideNotes: Record<string, string[]> | undefined): Record<string, string[]> | undefined;

package/dist/packages/workflow-package/workflow-stage-policy.js

@@ -0,0 +1,31 @@
+export function normalizeStagePolicyNotes(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const normalized = {};
+    for (const [stageId, notes] of Object.entries(value)) {
+        if (!Array.isArray(notes))
+            continue;
+        const cleaned = Array.from(new Set(notes
+            .filter((note) => typeof note === "string")
+            .map((note) => note.trim())
+            .filter((note) => note.length > 0)));
+        if (cleaned.length > 0) {
+            normalized[stageId] = cleaned;
+        }
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+export function mergeStagePolicyNotesForStages(stages, baseNotes, overrideNotes) {
+    const normalizedBase = normalizeStagePolicyNotes(baseNotes);
+    const merged = {};
+    for (const stage of stages) {
+        const combined = Array.from(new Set([
+            ...(normalizedBase?.[stage.id] ?? []),
+            ...((overrideNotes?.[stage.id] ?? []).map((note) => note.trim()).filter((note) => note.length > 0)),
+        ]));
+        if (combined.length > 0) {
+            merged[stage.id] = combined;
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}

package/dist/packages/workflow-package/workflow-stage-runner.d.ts

@@ -0,0 +1,41 @@
+import { type WorkflowExecutor } from "../agents/lib/executors.js";
+import { type RuntimeContractType, type RuntimeStageInstructions } from "../compiler/lib/schema.js";
+import { type RuntimeStageContractDraft } from "../compiler/runtime.js";
+import { type WorkflowReporter, type WorkflowStageResult } from "./workflow-helpers.js";
+interface WorkflowStageShape<TContractType extends RuntimeContractType> {
+    id: string;
+    label: string;
+    contractType: TContractType;
+}
+interface ExecuteValidatedStageOptions<TContractType extends RuntimeContractType> {
+    executor: WorkflowExecutor;
+    compiledPath: string;
+    executionPath?: string;
+    targetName: string;
+    workflow: string;
+    workflowSourcePath?: string;
+    stageDefinition: WorkflowStageShape<TContractType>;
+    instructions: RuntimeStageInstructions;
+    summary: string;
+    contract: RuntimeStageContractDraft;
+    statusLines: string[];
+    reporter?: WorkflowReporter;
+    completionCheck?: (() => boolean) | null;
+    syncWrites?: (() => void) | null;
+    reconcile?: (() => boolean) | null;
+    refreshArtifacts?: (() => void) | null;
+    validate: () => {
+        ok: boolean;
+        summary: string;
+    };
+}
+interface ExecuteValidatedSummarizeStageOptions<TContractType extends RuntimeContractType> extends ExecuteValidatedStageOptions<TContractType> {
+    startingSummaryCount: number;
+    targetCount: number;
+}
+export declare function findStageByContractType<TStage extends {
+    contractType: string;
+}>(stages: TStage[], contractType: TStage["contractType"]): TStage;
+export declare function executeValidatedStage<TContractType extends RuntimeContractType>(options: ExecuteValidatedStageOptions<TContractType>): Promise<WorkflowStageResult>;
+export declare function executeValidatedSummarizeStage<TContractType extends RuntimeContractType>(options: ExecuteValidatedSummarizeStageOptions<TContractType>): Promise<WorkflowStageResult>;
+export {};

package/dist/packages/workflow-package/workflow-stage-runner.js

@@ -0,0 +1,109 @@
+import { markRuntimeRunSucceededAfterValidation, buildStagePrompt, markRuntimeRunFailedAfterValidation, runExecutorStage, runExecutorSummarizeStage, } from "../compiler/runtime.js";
+import { reportValidationFailure, validateStageOutcome, } from "./workflow-helpers.js";
+export function findStageByContractType(stages, contractType) {
+    const stage = stages.find((candidate) => candidate.contractType === contractType);
+    if (!stage) {
+        throw new Error(`Missing workflow stage for contract type: ${contractType}`);
+    }
+    return stage;
+}
+export async function executeValidatedStage(options) {
+    const completionCheck = options.completionCheck
+        ? () => {
+            options.syncWrites?.();
+            options.reconcile?.();
+            return options.completionCheck?.() === true;
+        }
+        : undefined;
+    const code = await runExecutorStage({
+        executor: options.executor,
+        compiledPath: options.compiledPath,
+        executionPath: options.executionPath,
+        compiledName: options.targetName,
+        workflow: options.workflow,
+        workflowSourcePath: options.workflowSourcePath,
+        stage: options.stageDefinition.id,
+        stageLabel: options.stageDefinition.label,
+        contractType: options.stageDefinition.contractType,
+        summary: options.summary,
+        contract: options.contract,
+        buildPrompt: (contractPath) => buildStagePrompt(options.instructions, contractPath, options.statusLines),
+        completionCheck,
+    });
+    return finalizeValidatedStage(options, code);
+}
+export async function executeValidatedSummarizeStage(options) {
+    const completionCheck = options.completionCheck
+        ? () => {
+            options.syncWrites?.();
+            options.reconcile?.();
+            return options.completionCheck?.() === true;
+        }
+        : undefined;
+    const code = await runExecutorSummarizeStage({
+        executor: options.executor,
+        compiledPath: options.compiledPath,
+        executionPath: options.executionPath,
+        compiledName: options.targetName,
+        workflow: options.workflow,
+        workflowSourcePath: options.workflowSourcePath,
+        stage: options.stageDefinition.id,
+        stageLabel: options.stageDefinition.label,
+        contractType: options.stageDefinition.contractType,
+        summary: options.summary,
+        contract: options.contract,
+        buildPrompt: (contractPath) => buildStagePrompt(options.instructions, contractPath, options.statusLines),
+        completionCheck,
+        startingSummaryCount: options.startingSummaryCount,
+        targetCount: options.targetCount,
+    });
+    return finalizeValidatedStage(options, code);
+}
+function finalizeValidatedStage(options, code) {
+    const refreshAndValidate = () => {
+        options.syncWrites?.();
+        options.reconcile?.();
+        options.refreshArtifacts?.();
+        return validateStageOutcome(options.compiledPath, options.validate());
+    };
+    if (code !== 0) {
+        let completionSatisfied = false;
+        try {
+            options.syncWrites?.();
+            options.reconcile?.();
+            completionSatisfied = options.completionCheck?.() === true;
+        }
+        catch {
+            completionSatisfied = false;
+        }
+        if (completionSatisfied) {
+            const validation = refreshAndValidate();
+            if (validation.ok) {
+                markRuntimeRunSucceededAfterValidation(options.compiledPath, validation.summary);
+                return {
+                    ok: true,
+                    code: 0,
+                    summary: validation.summary,
+                };
+            }
+            reportValidationFailure(options.reporter, validation.summary);
+            markRuntimeRunFailedAfterValidation(options.compiledPath, validation.summary);
+            return {
+                ok: false,
+                code,
+                summary: validation.summary,
+            };
+        }
+        return { ok: false, code };
+    }
+    const validation = refreshAndValidate();
+    if (!validation.ok) {
+        reportValidationFailure(options.reporter, validation.summary);
+        markRuntimeRunFailedAfterValidation(options.compiledPath, validation.summary);
+    }
+    return {
+        ok: validation.ok,
+        code: validation.ok ? 0 : 1,
+        summary: validation.summary,
+    };
+}