@farmslot/recipe-harness 0.1.0

package/dist/runner.js

@@ -0,0 +1,1172 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { getRecipeActionManifestActionNames, validateRecipeActionManifestDocument, validateRecipeArtifactPackage, validateRecipeWithManifest, } from '@farmslot/protocol';
+import { isRecord, normalizeRelativePath, readJsonFile } from './json.js';
+import { JsonArtifactWriter, JsonSummaryWriter, JsonTraceWriter } from './writers.js';
+const HARNESS_VERSION = '0.1.0';
+const RUNNER_BUILT_IN_ACTIONS = new Set(['call']);
+const DEFAULT_MAX_FLOW_CALL_DEPTH = 8;
+const noopLogger = {
+    info() { },
+    warn() { },
+    error() { },
+};
+export function defineActionAdapter(adapter) {
+    if (!adapter.action.trim())
+        throw new Error('Action adapter action must be a non-empty string.');
+    return adapter;
+}
+export function createRecipeRunner(options) {
+    assertManifestIsValid(options.actionManifest);
+    const declaredActions = new Set(getRecipeActionManifestActionNames(options.actionManifest));
+    const adapterMap = new Map();
+    const preconditionMap = new Map();
+    const declaredPreconditions = new Set((options.actionManifest.pre_conditions ?? []).map((entry) => entry.id));
+    for (const checker of options.preconditions ?? []) {
+        if (!checker.id.trim())
+            throw new Error('Precondition checker id must be a non-empty string.');
+        if (!declaredPreconditions.has(checker.id)) {
+            throw new Error(`Precondition checker ${checker.id} is not declared by the action manifest.`);
+        }
+        if (preconditionMap.has(checker.id)) {
+            throw new Error(`Precondition checker ${checker.id} is registered more than once.`);
+        }
+        preconditionMap.set(checker.id, checker);
+    }
+    for (const adapter of options.adapters) {
+        if (!adapter.action.trim())
+            throw new Error('Action adapter action must be a non-empty string.');
+        if (!declaredActions.has(adapter.action) && adapter.testOnly !== true) {
+            throw new Error(`Adapter ${adapter.action} is not declared by the recipe action manifest.`);
+        }
+        if (adapterMap.has(adapter.action)) {
+            throw new Error(`Adapter ${adapter.action} is registered more than once.`);
+        }
+        adapterMap.set(adapter.action, adapter);
+    }
+    for (const action of declaredActions) {
+        if (!adapterMap.has(action) && !RUNNER_BUILT_IN_ACTIONS.has(action)) {
+            throw new Error(`Manifest action ${action} has no registered adapter.`);
+        }
+    }
+    return new DefaultRecipeRunner(options.actionManifest, adapterMap, preconditionMap, options.logger ?? noopLogger, options.hud, options.runner);
+}
+class DefaultRecipeRunner {
+    #actionManifest;
+    #adapters;
+    #preconditions;
+    #logger;
+    #hud;
+    #runnerProvenance;
+    constructor(actionManifest, adapters, preconditions, logger, hud, runnerProvenance) {
+        this.#actionManifest = actionManifest;
+        this.#adapters = adapters;
+        this.#preconditions = preconditions;
+        this.#logger = logger;
+        this.#hud = hud;
+        this.#runnerProvenance = runnerProvenance;
+    }
+    async run(request) {
+        if (!request.recipePath && request.recipeDocument == null) {
+            throw new Error('Recipe run requires recipePath or recipeDocument.');
+        }
+        const projectRoot = path.resolve(request.projectRoot ?? process.cwd());
+        const artifactsDir = path.resolve(request.artifactsDir);
+        const startedAt = new Date();
+        await mkdir(artifactsDir, { recursive: true });
+        const sourceRecipePath = request.recipePath ? path.resolve(request.recipePath) : undefined;
+        const recipe = request.recipeDocument ?? (await readJsonFile(sourceRecipePath));
+        assertRecipeMatchesManifest(recipe, this.#actionManifest);
+        const graph = extractWorkflowGraph(recipe);
+        const flowCatalog = await collectFlows(recipe, {
+            projectRoot,
+            recipeDir: sourceRecipePath ? path.dirname(sourceRecipePath) : projectRoot,
+        });
+        const artifactWriter = new JsonArtifactWriter(artifactsDir);
+        const traceWriter = new JsonTraceWriter(artifactsDir, this.#runnerProvenance);
+        const summaryWriter = new JsonSummaryWriter(artifactsDir);
+        const outputs = new Map();
+        const recipePath = await artifactWriter.copyRecipe(recipe);
+        let status = 'unknown';
+        let currentNodeId = graph.entry;
+        let mainStatus = 'unknown';
+        let runningTeardown = false;
+        const visited = new Set();
+        let transitionCount = 0;
+        const maxTransitions = Object.keys(graph.nodes).length * 3;
+        const preconditionStatus = await this.#runPreconditions({
+            graph,
+            recipe,
+            projectRoot,
+            artifactsDir,
+            request,
+            outputs,
+            artifactWriter,
+            traceWriter,
+        });
+        if (preconditionStatus === 'fail') {
+            status = 'fail';
+            currentNodeId = undefined;
+        }
+        while (currentNodeId) {
+            const activeNodeId = currentNodeId;
+            transitionCount += 1;
+            if (transitionCount > maxTransitions) {
+                const error = new Error('Recipe graph exceeded its maximum transition count.');
+                recordSyntheticFailure(traceWriter, activeNodeId, error);
+                status = 'fail';
+                break;
+            }
+            visited.add(activeNodeId);
+            const node = graph.nodes[activeNodeId];
+            if (!node) {
+                const error = new Error(`Recipe node ${activeNodeId} does not exist.`);
+                recordSyntheticFailure(traceWriter, activeNodeId, error);
+                status = 'fail';
+                break;
+            }
+            const action = String(node.action);
+            const adapter = action === 'call' ? undefined : this.#adapters.get(action);
+            if (action !== 'call' && !adapter) {
+                const error = new Error(`No adapter registered for action ${action}.`);
+                recordSyntheticFailure(traceWriter, activeNodeId, error, action);
+                status = 'fail';
+                break;
+            }
+            const nodeStartedAt = new Date();
+            const context = {
+                nodeId: activeNodeId,
+                recipe,
+                projectRoot,
+                artifactsDir,
+                env: request.env ?? {},
+                outputs,
+                getOutput(nodeId) {
+                    if (!outputs.has(nodeId))
+                        throw new Error(`No output recorded for node ${nodeId}.`);
+                    return outputs.get(nodeId);
+                },
+                resolveProjectPath(relativePath) {
+                    return path.join(projectRoot, normalizeRelativePath(relativePath));
+                },
+                resolveArtifactPath(relativePath) {
+                    return path.join(artifactsDir, normalizeRelativePath(relativePath));
+                },
+                registerArtifact(entry) {
+                    artifactWriter.register(entry);
+                },
+                logger: this.#logger,
+            };
+            try {
+                const gate = evaluateNodeGate(node, context.outputs);
+                if (!gate.run) {
+                    const next = resolveNextNode(node, {});
+                    traceWriter.record({
+                        nodeId: activeNodeId,
+                        action,
+                        ...traceNodeMetadata(node),
+                        startedAt: nodeStartedAt.toISOString(),
+                        endedAt: new Date().toISOString(),
+                        durationMs: Date.now() - nodeStartedAt.getTime(),
+                        ok: true,
+                        next,
+                        output: { skipped: true, reason: gate.reason },
+                    });
+                    currentNodeId = next;
+                    continue;
+                }
+                const hudStarted = await this.#publishHudProgressOrRecord(traceWriter, 'running', {
+                    nodeId: activeNodeId,
+                    action,
+                    node,
+                    recipe,
+                    index: transitionCount,
+                    total: Object.keys(graph.nodes).length,
+                    context,
+                });
+                if (!hudStarted) {
+                    status = 'fail';
+                    break;
+                }
+                const result = action === 'call'
+                    ? await executeInlineFlowCall({
+                        callNodeId: activeNodeId,
+                        node,
+                        context,
+                        flowCatalog,
+                        adapters: this.#adapters,
+                        traceWriter,
+                        callStack: [],
+                        maxCallDepth: DEFAULT_MAX_FLOW_CALL_DEPTH,
+                    })
+                    : await adapter.execute(node, context);
+                if (result.output !== undefined)
+                    outputs.set(activeNodeId, result.output);
+                for (const artifact of result.artifacts ?? [])
+                    artifactWriter.register(artifact);
+                const next = resolveNextNode(node, result);
+                traceWriter.record({
+                    nodeId: activeNodeId,
+                    action,
+                    ...traceNodeMetadata(node, result),
+                    startedAt: nodeStartedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - nodeStartedAt.getTime(),
+                    ok: true,
+                    next,
+                    status: result.status,
+                    output: result.output,
+                });
+                const hudCompleted = await this.#publishHudProgressOrRecord(traceWriter, result.status === 'fail' ? 'fail' : 'pass', {
+                    nodeId: activeNodeId,
+                    action,
+                    node,
+                    recipe,
+                    index: transitionCount,
+                    total: Object.keys(graph.nodes).length,
+                    context,
+                });
+                if (!hudCompleted) {
+                    status = 'fail';
+                    break;
+                }
+                if (result.status) {
+                    if (runningTeardown) {
+                        status = mainStatus === 'fail' ? 'fail' : result.status;
+                        break;
+                    }
+                    mainStatus = result.status;
+                    if (graph.teardownEntry) {
+                        runningTeardown = true;
+                        currentNodeId = graph.teardownEntry;
+                        continue;
+                    }
+                    status = result.status;
+                    break;
+                }
+                currentNodeId = next;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                traceWriter.record({
+                    nodeId: activeNodeId,
+                    action,
+                    ...traceNodeMetadata(node),
+                    startedAt: nodeStartedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - nodeStartedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                this.#logger.error(message);
+                await this.#publishHudProgressOrRecord(traceWriter, 'fail', {
+                    nodeId: activeNodeId,
+                    action,
+                    node,
+                    recipe,
+                    index: transitionCount,
+                    total: Object.keys(graph.nodes).length,
+                    context,
+                    error: message,
+                });
+                status = 'fail';
+                if (!runningTeardown && graph.teardownEntry) {
+                    mainStatus = 'fail';
+                    runningTeardown = true;
+                    currentNodeId = graph.teardownEntry;
+                    continue;
+                }
+                break;
+            }
+        }
+        artifactWriter.register({
+            path: 'summary.json',
+            type: 'summary',
+            label: 'Run summary',
+            category: 'system',
+        });
+        artifactWriter.register({
+            path: 'trace.json',
+            type: 'trace',
+            label: 'Execution trace',
+            category: 'system',
+        });
+        if (status === 'pass') {
+            const runHudStartedAt = new Date();
+            try {
+                await this.#publishRunHud(status, {
+                    recipe,
+                    projectRoot,
+                    artifactsDir,
+                    env: request.env ?? {},
+                    outputs,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                traceWriter.record({
+                    nodeId: 'recipe-complete:hud',
+                    action: 'app.hud',
+                    startedAt: runHudStartedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - runHudStartedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                this.#logger.error(`app.hud complete update failed: ${message}`);
+                status = 'fail';
+            }
+        }
+        const endedAt = new Date();
+        const tracePath = await traceWriter.write();
+        const trace = traceWriter.list();
+        const summary = {
+            status,
+            total: trace.length,
+            passed: trace.filter((entry) => entry.ok).length,
+            failed: trace.filter((entry) => !entry.ok).length,
+            startedAt: startedAt.toISOString(),
+            endedAt: endedAt.toISOString(),
+            durationMs: endedAt.getTime() - startedAt.getTime(),
+            harness: {
+                name: '@farmslot/recipe-harness',
+                version: HARNESS_VERSION,
+                runner_protocol_version: this.#actionManifest.runner_protocol_version,
+                action_registry_version: this.#actionManifest.action_registry_version,
+            },
+            ...(this.#runnerProvenance ? { runner: this.#runnerProvenance } : {}),
+        };
+        const summaryPath = await summaryWriter.write(summary);
+        const artifactManifestPath = await artifactWriter.write(status, this.#runnerProvenance);
+        const packageValidation = validateRecipeArtifactPackage({
+            recipe,
+            manifest: {
+                version: 1,
+                runStatus: status,
+                ...(this.#runnerProvenance ? { provenance: { runner: this.#runnerProvenance } } : {}),
+                artifacts: artifactWriter.list(),
+            },
+            artifactPaths: [
+                'recipe.json',
+                'summary.json',
+                'trace.json',
+                'artifact-manifest.json',
+                ...artifactWriter.list().map((entry) => entry.path),
+            ],
+        });
+        if (packageValidation.status === 'invalid') {
+            throw new Error(`Generated artifact package is invalid: ${packageValidation.findings
+                .map((finding) => `${finding.code} ${finding.path}`)
+                .join(', ')}`);
+        }
+        return { status, summaryPath, tracePath, artifactManifestPath, recipePath };
+    }
+    async #runPreconditions({ graph, recipe, projectRoot, artifactsDir, request, outputs, artifactWriter, traceWriter, }) {
+        for (const gate of graph.preconditions) {
+            const nodeId = `pre_conditions:${gate.id}`;
+            const checker = this.#preconditions.get(gate.id);
+            if (!checker) {
+                recordSyntheticFailure(traceWriter, nodeId, new Error(`Precondition ${gate.id} is declared by the recipe but has no checker registered.`), 'pre_condition');
+                return 'fail';
+            }
+            const startedAt = new Date();
+            const context = this.#createExecutionContext({
+                nodeId,
+                recipe,
+                projectRoot,
+                artifactsDir,
+                env: request.env ?? {},
+                outputs,
+                artifactWriter,
+            });
+            try {
+                const rawResult = await checker.execute(gate, context);
+                const result = normalizePreconditionResult(rawResult);
+                if (result.output !== undefined)
+                    outputs.set(nodeId, result.output);
+                if (result.ok === false) {
+                    throw new Error(result.error ?? `Precondition ${gate.id} failed.`);
+                }
+                traceWriter.record({
+                    nodeId,
+                    action: 'pre_condition',
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: true,
+                    output: result.output,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                traceWriter.record({
+                    nodeId,
+                    action: 'pre_condition',
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: false,
+                    error: message,
+                });
+                return 'fail';
+            }
+        }
+        return 'pass';
+    }
+    #createExecutionContext({ nodeId, recipe, projectRoot, artifactsDir, env, outputs, artifactWriter, }) {
+        return {
+            nodeId,
+            recipe,
+            projectRoot,
+            artifactsDir,
+            env,
+            outputs,
+            getOutput(nodeId) {
+                if (!outputs.has(nodeId))
+                    throw new Error(`No output recorded for node ${nodeId}.`);
+                return outputs.get(nodeId);
+            },
+            resolveProjectPath(relativePath) {
+                return path.join(projectRoot, normalizeRelativePath(relativePath));
+            },
+            resolveArtifactPath(relativePath) {
+                return path.join(artifactsDir, normalizeRelativePath(relativePath));
+            },
+            registerArtifact(entry) {
+                artifactWriter.register(entry);
+            },
+            logger: this.#logger,
+        };
+    }
+    #hudAction() {
+        if (this.#hud === false || this.#hud?.enabled === false)
+            return undefined;
+        return this.#adapters.has('app.hud') ? 'app.hud' : undefined;
+    }
+    async #publishHudProgressOrRecord(traceWriter, status, event) {
+        const startedAt = new Date();
+        try {
+            await this.#publishHudProgress(status, event);
+            return true;
+        }
+        catch (error) {
+            // HUD is first-class when advertised, so rendering failures fail the run.
+            // They are still recorded instead of aborting artifact package writing.
+            const message = error instanceof Error ? error.message : String(error);
+            traceWriter.record({
+                nodeId: `${event.nodeId}:hud:${status}`,
+                action: 'app.hud',
+                startedAt: startedAt.toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Date.now() - startedAt.getTime(),
+                ok: false,
+                error: message,
+            });
+            this.#logger.error(`app.hud ${status} update failed for ${event.nodeId}: ${message}`);
+            return false;
+        }
+    }
+    async #publishHudProgress(status, event) {
+        const hudAction = this.#hudAction();
+        if (!hudAction || event.action === hudAction)
+            return;
+        const adapter = this.#adapters.get(hudAction);
+        if (!adapter)
+            return;
+        await adapter.execute(buildHudNode(status, event, this.#hud), event.context);
+    }
+    async #publishRunHud(status, request) {
+        const hudAction = this.#hudAction();
+        if (!hudAction)
+            return;
+        const adapter = this.#adapters.get(hudAction);
+        if (!adapter)
+            return;
+        const context = {
+            nodeId: 'recipe-complete',
+            recipe: request.recipe,
+            projectRoot: request.projectRoot,
+            artifactsDir: request.artifactsDir,
+            env: request.env,
+            outputs: request.outputs,
+            getOutput(nodeId) {
+                if (!request.outputs.has(nodeId))
+                    throw new Error(`No output recorded for node ${nodeId}.`);
+                return request.outputs.get(nodeId);
+            },
+            resolveProjectPath(relativePath) {
+                return path.join(request.projectRoot, normalizeRelativePath(relativePath));
+            },
+            resolveArtifactPath(relativePath) {
+                return path.join(request.artifactsDir, normalizeRelativePath(relativePath));
+            },
+            registerArtifact() { },
+            logger: this.#logger,
+        };
+        await adapter.execute({
+            action: hudAction,
+            title: this.#hudTitle(request.recipe),
+            status,
+            node_id: 'recipe-complete',
+            phase: 'complete',
+            flow: 'run',
+            detail: status === 'pass' ? 'Recipe completed' : 'Recipe failed',
+            text: status === 'pass' ? 'Recipe completed' : 'Recipe failed',
+            progress: { complete: true },
+        }, context);
+    }
+    #hudTitle(recipe) {
+        if (this.#hud && this.#hud.title)
+            return this.#hud.title;
+        if (isRecord(recipe) && typeof recipe.title === 'string')
+            return recipe.title;
+        return 'Recipe run';
+    }
+}
+function buildHudNode(status, event, options) {
+    const title = options && options.title
+        ? options.title
+        : isRecord(event.recipe) && typeof event.recipe.title === 'string'
+            ? event.recipe.title
+            : 'Recipe run';
+    const flow = hudFlow(event.action, event.node);
+    const subIntent = hudSubIntent(event.node);
+    const text = hudText(event.node);
+    const detail = normalizeHudSecondary(hudDetail(event.node), text, subIntent || flow);
+    const phase = typeof event.node.phase === 'string' && event.node.phase.trim()
+        ? event.node.phase
+        : lifecyclePhase(status);
+    return {
+        action: 'app.hud',
+        title,
+        status,
+        node_id: event.nodeId,
+        phase,
+        flow: flow || undefined,
+        detail,
+        text,
+        sub_intent: subIntent || undefined,
+        action_name: event.action,
+        proofTarget: event.node.proofTarget,
+        record: event.node.record,
+        intent: text,
+        error: event.error ? hudErrorSummary(event.error) : undefined,
+        display: isRecord(event.node.display) ? event.node.display : hudDisplay(options),
+        progress: {
+            current: event.index,
+            total: event.total,
+        },
+    };
+}
+function hudDisplay(options) {
+    if (!options || !options.display)
+        return {};
+    return { ...options.display };
+}
+function lifecyclePhase(status) {
+    if (status === 'running')
+        return 'running';
+    if (status === 'fail')
+        return 'failed';
+    return 'passed';
+}
+function hudFlow(_action, node) {
+    for (const key of ['flow', 'domain', 'group']) {
+        const value = node[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return '';
+}
+function hudSubIntent(node) {
+    for (const key of ['sub_intent', 'subIntent']) {
+        const value = node[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return '';
+}
+function hudText(node) {
+    for (const key of ['intent', 'label', 'title', 'description', 'text']) {
+        const value = node[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return 'Executing recipe step';
+}
+function hudDetail(node) {
+    const explicitDetail = node.detail;
+    if (typeof explicitDetail === 'string' && explicitDetail.trim())
+        return explicitDetail;
+    const fragments = [];
+    for (const key of ['target', 'destination', 'selector', 'test_id', 'testID']) {
+        const value = node[key];
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            fragments.push(`${key}=${String(value)}`);
+        }
+    }
+    return fragments.length ? fragments.join(' · ') : undefined;
+}
+function normalizeHudSecondary(value, intent, flow) {
+    const normalized = value?.trim();
+    if (!normalized)
+        return undefined;
+    if (normalized === intent || normalized === flow)
+        return undefined;
+    return normalized;
+}
+function hudErrorSummary(error) {
+    const nestedError = error.match(/"error":"([^"]+)"/)?.[1];
+    const lines = error
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => {
+        if (!line)
+            return false;
+        if (line.includes("Warning: The 'NO_COLOR' env"))
+            return false;
+        if (line.startsWith('(Use `node --trace-warnings'))
+            return false;
+        if (line.startsWith('file://'))
+            return false;
+        if (line.startsWith('at '))
+            return false;
+        if (line.startsWith('Node.js '))
+            return false;
+        return true;
+    });
+    const errorLine = [...lines].reverse().find((line) => line.startsWith('Error: ')) ??
+        lines.find((line) => line.includes('Error: ')) ??
+        lines[0] ??
+        error;
+    let summary = errorLine.includes('Error: ')
+        ? errorLine.slice(errorLine.indexOf('Error: ') + 'Error: '.length)
+        : errorLine;
+    const resultIndex = summary.indexOf('. Result:');
+    if (resultIndex > 0)
+        summary = summary.slice(0, resultIndex);
+    if (nestedError && !summary.includes(nestedError))
+        summary = `${summary}: ${nestedError}`;
+    const maxLength = 180;
+    return summary.length > maxLength ? `${summary.slice(0, maxLength - 1)}…` : summary;
+}
+function assertManifestIsValid(manifest) {
+    const result = validateRecipeActionManifestDocument(manifest);
+    if (result.status === 'invalid') {
+        throw new Error(`Recipe action manifest is invalid: ${result.findings
+            .map((finding) => `${finding.code} ${finding.path}: ${finding.message}`)
+            .join('; ')}`);
+    }
+}
+function assertRecipeMatchesManifest(recipe, manifest) {
+    const result = validateRecipeWithManifest(recipe, manifest);
+    if (result.status === 'invalid') {
+        throw new Error(`Recipe is invalid for the action manifest: ${result.findings
+            .map((finding) => `${finding.code} ${finding.path}: ${finding.message}`)
+            .join('; ')}`);
+    }
+}
+function extractWorkflowGraph(recipe) {
+    if (!isRecord(recipe) || !isRecord(recipe.validate) || !isRecord(recipe.validate.workflow)) {
+        throw new Error('Recipe must include validate.workflow.');
+    }
+    const workflow = recipe.validate.workflow;
+    if (typeof workflow.entry !== 'string' || !isRecord(workflow.nodes)) {
+        throw new Error('Recipe workflow must include entry and nodes.');
+    }
+    const nodes = Object.create(null);
+    for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+        if (isRecord(node))
+            nodes[nodeId] = node;
+    }
+    const mainEntry = workflow.entry;
+    const setupNodes = parseLifecycleNodes(workflow.setup, 'setup');
+    const startState = isRecord(recipe.startState)
+        ? [{ id: 'startState', node: recipe.startState }]
+        : [];
+    const teardownNodes = parseLifecycleNodes(workflow.teardown, 'teardown');
+    const preconditions = parsePreconditions(workflow.pre_conditions);
+    let entry = mainEntry;
+    const setupChain = [...setupNodes, ...startState];
+    if (setupChain.length > 0) {
+        entry = setupChain[0].id;
+        linkLifecycleNodes(nodes, setupChain, mainEntry);
+    }
+    let teardownEntry;
+    if (teardownNodes.length > 0) {
+        teardownEntry = teardownNodes[0].id;
+        linkLifecycleNodes(nodes, teardownNodes, 'teardown:end');
+        nodes['teardown:end'] = { action: 'end', status: 'pass', phase: 'teardown' };
+    }
+    return { entry, nodes, preconditions, teardownEntry };
+}
+function parsePreconditions(value) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error('validate.workflow.pre_conditions must be an array.');
+    }
+    return value.map((entry, index) => {
+        if (typeof entry === 'string' && entry.trim())
+            return { id: entry.trim() };
+        if (!isRecord(entry)) {
+            throw new Error(`validate.workflow.pre_conditions[${index}] must be a string or object.`);
+        }
+        if (typeof entry.id !== 'string' || !entry.id.trim()) {
+            throw new Error(`validate.workflow.pre_conditions[${index}].id must be a non-empty string.`);
+        }
+        if (entry.params != null && !isRecord(entry.params)) {
+            throw new Error(`validate.workflow.pre_conditions[${index}].params must be an object.`);
+        }
+        return {
+            id: entry.id.trim(),
+            description: typeof entry.description === 'string' ? entry.description : undefined,
+            params: isRecord(entry.params) ? entry.params : undefined,
+            required: typeof entry.required === 'boolean' ? entry.required : undefined,
+        };
+    });
+}
+function normalizePreconditionResult(result) {
+    if (typeof result === 'boolean')
+        return { ok: result };
+    if (result === undefined)
+        return { ok: true };
+    return result;
+}
+function parseLifecycleNodes(value, phase) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`validate.workflow.${phase} must be an array.`);
+    return value.map((entry, index) => {
+        if (!isRecord(entry)) {
+            throw new Error(`validate.workflow.${phase}[${index}] must be an action node object.`);
+        }
+        const authoredId = typeof entry.id === 'string' && entry.id.trim() ? entry.id.trim() : `${phase}:${index}`;
+        return {
+            id: authoredId,
+            node: {
+                phase,
+                ...entry,
+            },
+        };
+    });
+}
+function linkLifecycleNodes(nodes, lifecycleNodes, nextAfterLifecycle) {
+    lifecycleNodes.forEach((entry, index) => {
+        if (nodes[entry.id])
+            throw new Error(`Lifecycle node id ${entry.id} conflicts with graph node.`);
+        if (entry.node.next != null) {
+            throw new Error(`Lifecycle node ${entry.id} must not declare next; setup and teardown arrays are ordered lists.`);
+        }
+        const next = lifecycleNodes[index + 1]?.id ?? nextAfterLifecycle;
+        nodes[entry.id] = {
+            ...entry.node,
+            next,
+        };
+    });
+}
+function resolveNextNode(node, result) {
+    if (result.next)
+        return result.next;
+    if (result.case && isRecord(node.cases)) {
+        const target = node.cases[result.case];
+        if (typeof target === 'string')
+            return target;
+    }
+    if (typeof node.next === 'string')
+        return node.next;
+    if (typeof node.default === 'string')
+        return node.default;
+    return undefined;
+}
+async function collectFlows(recipe, options) {
+    const flows = new Map();
+    if (!isRecord(recipe))
+        return flows;
+    for (const catalogPath of collectUsePaths(recipe.uses)) {
+        const catalog = await readJsonFile(resolveUsePath(catalogPath, options));
+        addCatalogFlows(flows, catalog, catalogPath);
+    }
+    if (isRecord(recipe.flows)) {
+        addCatalogFlows(flows, { flows: recipe.flows }, 'recipe.flows');
+    }
+    return flows;
+}
+function collectUsePaths(value) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('uses must be an array of flow catalog paths.');
+    return value.map((entry, index) => {
+        if (typeof entry !== 'string' || !entry.trim()) {
+            throw new Error(`uses[${index}] must be a non-empty flow catalog path.`);
+        }
+        return entry;
+    });
+}
+function resolveUsePath(catalogPath, options) {
+    const normalized = normalizeRelativePath(catalogPath);
+    const fromRecipe = path.join(options.recipeDir, normalized);
+    if (path.isAbsolute(catalogPath)) {
+        throw new Error(`uses entry ${catalogPath} must be relative.`);
+    }
+    const relativeToProject = path.relative(options.projectRoot, fromRecipe);
+    if (!relativeToProject.startsWith('..') && !path.isAbsolute(relativeToProject)) {
+        return fromRecipe;
+    }
+    return path.join(options.projectRoot, normalized);
+}
+function addCatalogFlows(flows, catalog, source) {
+    if (!isRecord(catalog) || !isRecord(catalog.flows)) {
+        throw new Error(`Flow catalog ${source} must contain a flows object.`);
+    }
+    for (const [ref, flow] of Object.entries(catalog.flows)) {
+        const normalized = normalizeFlow(ref, flow, source);
+        if (flows.has(ref))
+            throw new Error(`Flow ${ref} is declared more than once.`);
+        flows.set(ref, normalized);
+    }
+}
+function normalizeFlow(ref, flow, source) {
+    if (!isRecord(flow))
+        throw new Error(`Flow ${ref} in ${source} must be an object.`);
+    const workflow = isRecord(flow.workflow) ? flow.workflow : flow;
+    if (typeof workflow.entry !== 'string' || !workflow.entry.trim() || !isRecord(workflow.nodes)) {
+        throw new Error(`Flow ${ref} in ${source} must include workflow.entry and workflow.nodes.`);
+    }
+    const nodes = Object.create(null);
+    for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+        if (isRecord(node))
+            nodes[nodeId] = node;
+    }
+    return {
+        entry: workflow.entry,
+        nodes,
+        paramsSchema: flow.paramsSchema,
+        postcondition: flow.postcondition,
+    };
+}
+async function executeInlineFlowCall({ callNodeId, node, context, flowCatalog, adapters, traceWriter, callStack, maxCallDepth, }) {
+    const ref = typeof node.ref === 'string' && node.ref.trim() ? node.ref.trim() : '';
+    if (!ref)
+        throw new Error('call.ref must be a non-empty flow id.');
+    if (callStack.includes(ref)) {
+        throw new Error(`Flow call cycle detected: ${[...callStack, ref].join(' -> ')}.`);
+    }
+    if (callStack.length >= maxCallDepth) {
+        throw new Error(`Flow call depth exceeded maximum ${maxCallDepth}.`);
+    }
+    const flow = flowCatalog.get(ref);
+    if (!flow)
+        throw new Error(`Flow ${ref} is not available from recipe uses or inline flows.`);
+    const params = isRecord(node.params) ? node.params : {};
+    validateParamsSchema(params, flow.paramsSchema, ref);
+    const nextCallStack = [...callStack, ref];
+    const output = await executeInlineFlow({
+        callNodeId,
+        flowRef: ref,
+        flow,
+        params,
+        context,
+        flowCatalog,
+        adapters,
+        traceWriter,
+        callStack: nextCallStack,
+        maxCallDepth,
+    });
+    if (flow.postcondition != null && !evaluatePredicate(output, flow.postcondition)) {
+        throw new Error(`Flow ${ref} failed its postcondition.`);
+    }
+    return { output };
+}
+async function executeInlineFlow({ callNodeId, flowRef, flow, params, context, flowCatalog, adapters, traceWriter, callStack, maxCallDepth, }) {
+    let currentNodeId = flow.entry;
+    let transitionCount = 0;
+    const maxTransitions = Object.keys(flow.nodes).length * 3;
+    const flowOutputs = {};
+    const flowOutputMap = new Map();
+    flowOutputMap.set('params', params);
+    flowOutputMap.set(`${callNodeId}/params`, params);
+    while (currentNodeId) {
+        transitionCount += 1;
+        if (transitionCount > maxTransitions) {
+            throw new Error(`Flow ${flowRef} exceeded its maximum transition count.`);
+        }
+        const localNodeId = currentNodeId;
+        const rawFlowNode = flow.nodes[localNodeId];
+        if (!rawFlowNode)
+            throw new Error(`Flow ${flowRef} node ${localNodeId} does not exist.`);
+        const flowNode = resolveParams(rawFlowNode, params);
+        const action = String(flowNode.action);
+        const adapter = action === 'call' ? undefined : adapters.get(action);
+        if (action !== 'call' && !adapter)
+            throw new Error(`No adapter registered for flow action ${action}.`);
+        const startedAt = new Date();
+        const namespacedNodeId = `${callNodeId}/${localNodeId}`;
+        try {
+            const mergedOutputs = new Map([...context.outputs, ...flowOutputMap]);
+            const gate = evaluateNodeGate(flowNode, mergedOutputs);
+            if (!gate.run) {
+                const next = resolveNextNode(flowNode, {});
+                traceWriter.record({
+                    nodeId: namespacedNodeId,
+                    action,
+                    ...traceNodeMetadata(flowNode),
+                    startedAt: startedAt.toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt.getTime(),
+                    ok: true,
+                    next,
+                    output: { skipped: true, reason: gate.reason },
+                });
+                currentNodeId = next;
+                continue;
+            }
+            const childContext = {
+                ...context,
+                nodeId: namespacedNodeId,
+                outputs: mergedOutputs,
+                getOutput(nodeId) {
+                    if (flowOutputMap.has(nodeId))
+                        return flowOutputMap.get(nodeId);
+                    const namespacedLookup = `${callNodeId}/${nodeId}`;
+                    if (flowOutputMap.has(namespacedLookup))
+                        return flowOutputMap.get(namespacedLookup);
+                    return context.getOutput(nodeId);
+                },
+            };
+            const result = action === 'call'
+                ? await executeInlineFlowCall({
+                    callNodeId: namespacedNodeId,
+                    node: flowNode,
+                    context: childContext,
+                    flowCatalog,
+                    adapters,
+                    traceWriter,
+                    callStack,
+                    maxCallDepth,
+                })
+                : await adapter.execute(flowNode, childContext);
+            if (result.output !== undefined) {
+                flowOutputs[localNodeId] = result.output;
+                flowOutputMap.set(localNodeId, result.output);
+                flowOutputMap.set(namespacedNodeId, result.output);
+            }
+            traceWriter.record({
+                nodeId: namespacedNodeId,
+                action,
+                ...traceNodeMetadata(flowNode, result),
+                startedAt: startedAt.toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Date.now() - startedAt.getTime(),
+                ok: true,
+                next: resolveNextNode(flowNode, result),
+                status: result.status,
+                output: result.output,
+            });
+            if (result.status) {
+                if (result.status === 'fail')
+                    throw new Error(`Flow ${flowRef} failed at ${localNodeId}.`);
+                return { ref: flowRef, status: result.status, outputs: flowOutputs };
+            }
+            currentNodeId = resolveNextNode(flowNode, result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            traceWriter.record({
+                nodeId: namespacedNodeId,
+                action,
+                ...traceNodeMetadata(flowNode),
+                startedAt: startedAt.toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: Date.now() - startedAt.getTime(),
+                ok: false,
+                error: message,
+            });
+            throw error;
+        }
+    }
+    return { ref: flowRef, status: 'unknown', outputs: flowOutputs };
+}
+function validateParamsSchema(params, schema, flowRef) {
+    if (schema == null)
+        return;
+    if (!isRecord(schema))
+        throw new Error(`Flow ${flowRef} paramsSchema must be an object.`);
+    if (schema.type != null && schema.type !== 'object') {
+        throw new Error(`Flow ${flowRef} paramsSchema.type must be object.`);
+    }
+    if (Array.isArray(schema.required)) {
+        for (const key of schema.required) {
+            if (typeof key !== 'string')
+                continue;
+            if (!Object.prototype.hasOwnProperty.call(params, key)) {
+                throw new Error(`Flow ${flowRef} params missing required field ${key}.`);
+            }
+        }
+    }
+    if (!isRecord(schema.properties))
+        return;
+    for (const [key, propertySchema] of Object.entries(schema.properties)) {
+        if (!Object.prototype.hasOwnProperty.call(params, key))
+            continue;
+        validateParamValue(params[key], propertySchema, `Flow ${flowRef} params.${key}`);
+    }
+}
+function validateParamValue(value, schema, label) {
+    if (!isRecord(schema))
+        return;
+    if (Array.isArray(schema.enum) && !schema.enum.some((entry) => isDeepStrictEqual(entry, value))) {
+        throw new Error(`${label} must be one of ${JSON.stringify(schema.enum)}.`);
+    }
+    if (schema.type == null)
+        return;
+    const actualType = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
+    if (actualType !== schema.type) {
+        throw new Error(`${label} must be ${String(schema.type)}, received ${actualType}.`);
+    }
+}
+function resolveParams(node, params) {
+    return resolveParamValue(node, params);
+}
+function resolveParamValue(value, params) {
+    if (typeof value === 'string') {
+        const fullMatch = /^\{\{params\.([A-Za-z0-9_.-]+)\}\}$/.exec(value);
+        if (fullMatch)
+            return getPathValue(params, fullMatch[1]);
+        return value.replace(/\{\{params\.([A-Za-z0-9_.-]+)\}\}/g, (_match, key) => String(getPathValue(params, key) ?? ''));
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => resolveParamValue(entry, params));
+    if (!isRecord(value))
+        return value;
+    const resolved = {};
+    for (const [key, entry] of Object.entries(value)) {
+        resolved[key] = resolveParamValue(entry, params);
+    }
+    return resolved;
+}
+function evaluateNodeGate(node, outputs) {
+    const root = Object.fromEntries(outputs);
+    if (node.when != null && !evaluatePredicate(root, node.when)) {
+        return { run: false, reason: 'when predicate was false' };
+    }
+    if (node.unless != null && evaluatePredicate(root, node.unless)) {
+        return { run: false, reason: 'unless predicate was true' };
+    }
+    return { run: true };
+}
+function evaluatePredicate(root, predicate) {
+    if (!isRecord(predicate))
+        throw new Error('Predicate must be an assertion object.');
+    if (Array.isArray(predicate.all))
+        return predicate.all.every((entry) => evaluatePredicate(root, entry));
+    if (Array.isArray(predicate.any))
+        return predicate.any.some((entry) => evaluatePredicate(root, entry));
+    if (Array.isArray(predicate.none))
+        return !predicate.none.some((entry) => evaluatePredicate(root, entry));
+    const pathValue = typeof predicate.path === 'string' ? predicate.path : '$';
+    const actual = pathValue === '$' ? root : getPathValue(root, pathValue.replace(/^\$\./, ''));
+    const operator = typeof predicate.operator === 'string' ? predicate.operator : 'truthy';
+    const expected = predicate.value;
+    switch (operator) {
+        case 'exists':
+            return actual !== undefined;
+        case 'not_null':
+            return actual != null;
+        case 'truthy':
+            return Boolean(actual);
+        case 'falsy':
+            return !actual;
+        case 'eq':
+            return actual === expected;
+        case 'ne':
+        case 'neq':
+            return actual !== expected;
+        case 'deep_eq':
+            return isDeepStrictEqual(actual, expected);
+        case 'contains':
+            return containsValue(actual, expected);
+        case 'not_contains':
+            return !containsValue(actual, expected);
+        case 'matches':
+            return typeof expected === 'string' && new RegExp(expected).test(String(actual ?? ''));
+        case 'one_of':
+            return Array.isArray(expected) && expected.some((entry) => isDeepStrictEqual(entry, actual));
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte':
+            return compareNumbers(actual, expected, operator);
+        case 'length_eq':
+        case 'length_gt':
+        case 'length_gte':
+        case 'length_lt':
+        case 'length_lte':
+            return compareNumbers(lengthOf(actual), expected, operator.replace('length_', ''));
+        default:
+            throw new Error(`Unsupported predicate operator ${operator}.`);
+    }
+}
+function getPathValue(root, dottedPath) {
+    return dottedPath
+        .split('.')
+        .filter(Boolean)
+        .reduce((current, segment) => {
+        if (!isRecord(current) && !Array.isArray(current))
+            return undefined;
+        if (Array.isArray(current))
+            return current[Number(segment)];
+        return current[segment];
+    }, root);
+}
+function containsValue(actual, expected) {
+    if (typeof actual === 'string')
+        return actual.includes(String(expected));
+    if (Array.isArray(actual))
+        return actual.some((entry) => isDeepStrictEqual(entry, expected));
+    return false;
+}
+function lengthOf(actual) {
+    if (typeof actual === 'string' || Array.isArray(actual))
+        return actual.length;
+    if (isRecord(actual))
+        return Object.keys(actual).length;
+    return Number.NaN;
+}
+function compareNumbers(actual, expected, operator) {
+    if (typeof actual !== 'number' || typeof expected !== 'number')
+        return false;
+    if (operator === 'gt')
+        return actual > expected;
+    if (operator === 'gte')
+        return actual >= expected;
+    if (operator === 'lt')
+        return actual < expected;
+    return actual <= expected;
+}
+function recordSyntheticFailure(traceWriter, nodeId, error, action = 'unknown') {
+    const now = new Date().toISOString();
+    traceWriter.record({
+        nodeId,
+        action,
+        startedAt: now,
+        endedAt: now,
+        durationMs: 0,
+        ok: false,
+        error: error.message,
+    });
+}
+function traceNodeMetadata(node, result) {
+    const metadata = {};
+    if (typeof node.phase === 'string')
+        metadata.phase = node.phase;
+    if (node.record !== undefined)
+        metadata.record = node.record;
+    if (result?.artifacts?.length)
+        metadata.artifacts = result.artifacts;
+    return metadata;
+}
+//# sourceMappingURL=runner.js.map