@substrate-ai/factory 0.19.54

package/dist/graph/executor.js

@@ -0,0 +1,787 @@
+/**
+ * Graph executor — drives end-to-end traversal of a factory graph.
+ *
+ * Dispatches handlers, applies retry logic, writes checkpoints, selects edges,
+ * and emits FactoryEvents at each stage of execution.
+ *
+ * Story 42-14 (base executor).
+ * Story 42-16 (allowPartial demotion + ConvergenceController goal gate evaluation).
+ *
+ * NOTE: The executor uses `events.ts:Outcome` (StageStatus: 'SUCCESS' | 'FAIL' | ...)
+ * rather than `types.ts:Outcome` (OutcomeStatus: 'SUCCESS' | 'FAILURE' | ...) because:
+ * 1. The acceptance criteria specify status: 'FAIL' (from StageStatus, not OutcomeStatus)
+ * 2. All FactoryEvents payloads (graph:node-completed) use events.ts:Outcome
+ * NodeHandler returns types.ts:Outcome, which is cast via `as unknown as Outcome` where needed.
+ */
+import path from 'node:path';
+import { GraphContext } from './context.js';
+import { selectEdge } from './edge-selector.js';
+import { CheckpointManager } from './checkpoint.js';
+import { RunStateManager } from './run-state.js';
+import { createConvergenceController, SessionBudgetManager, PipelineBudgetManager, createPlateauDetector, checkPlateauAndEmit, buildRemediationContext, injectRemediationContext, computeBackoffDelay, createDualSignalCoordinator, CONTEXT_KEY_CODE_REVIEW_VERDICT, } from '../convergence/index.js';
+import { computeSatisfactionScore } from '../scenarios/scorer.js';
+import { upsertGraphRun, insertGraphNodeResult, insertScenarioResult } from '../persistence/factory-queries.js';
+import { parseFidelityLevel, resolveFidelity } from './fidelity.js';
+import { applyStylesheet } from './transformer.js';
+// ---------------------------------------------------------------------------
+// normalizeOutcomeStatus
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a types.ts:Outcome (OutcomeStatus) to an events.ts:Outcome (StageStatus).
+ *
+ * NodeHandler returns `types.ts:Outcome` whose status is `OutcomeStatus`
+ * ('SUCCESS' | 'PARTIAL_SUCCESS' | 'FAILURE' | 'NEEDS_RETRY' | 'ESCALATE').
+ * The executor operates on `events.ts:Outcome` whose status is `StageStatus`
+ * ('SUCCESS' | 'FAIL' | 'PARTIAL_SUCCESS' | 'RETRY' | 'SKIPPED').
+ *
+ * Mapping:
+ *   OutcomeStatus.FAILURE      → StageStatus.FAIL
+ *   OutcomeStatus.NEEDS_RETRY  → StageStatus.FAIL  (retry exhausted at this level)
+ *   OutcomeStatus.ESCALATE     → StageStatus.FAIL  (treated as failure for routing)
+ *   OutcomeStatus.SUCCESS      → StageStatus.SUCCESS
+ *   OutcomeStatus.PARTIAL_SUCCESS → StageStatus.PARTIAL_SUCCESS
+ */
+function normalizeOutcomeStatus(raw) {
+    let status;
+    switch (raw.status) {
+        case 'SUCCESS':
+            status = 'SUCCESS';
+            break;
+        case 'PARTIAL_SUCCESS':
+            status = 'PARTIAL_SUCCESS';
+            break;
+        case 'FAILURE':
+        case 'NEEDS_RETRY':
+        case 'ESCALATE':
+        default:
+            status = 'FAIL';
+            break;
+    }
+    return {
+        ...raw,
+        status,
+    };
+}
+// ---------------------------------------------------------------------------
+// dispatchWithRetry
+// ---------------------------------------------------------------------------
+/**
+ * Dispatch a node handler with exponential backoff retry on FAIL outcomes.
+ *
+ * Emits `graph:node-retried` before each retry attempt.
+ * Does NOT emit `graph:node-completed` or `graph:node-failed` — those are
+ * emitted by the main loop in `createGraphExecutor` AFTER the `allowPartial`
+ * demotion check, ensuring correct event semantics for demoted PARTIAL_SUCCESS.
+ *
+ * @param node         - Node to dispatch (may have fidelity override applied).
+ * @param context      - Current graph execution context.
+ * @param graph        - The full factory graph.
+ * @param config       - Executor configuration (handlerRegistry, eventBus, runId).
+ * @param nodeRetries  - Mutable retry counter map; mutated in place.
+ * @returns The final Outcome after all retry attempts.
+ */
+async function dispatchWithRetry(node, context, graph, config, nodeRetries) {
+    const maxRetries = node.maxRetries ?? 0;
+    const maxAttempts = maxRetries + 1;
+    let attempt = 0;
+    while (true) {
+        let outcome;
+        try {
+            const handler = config.handlerRegistry.resolve(node);
+            // NodeHandler returns types.ts:Outcome (OutcomeStatus).
+            // normalizeOutcomeStatus() maps to events.ts:Outcome (StageStatus) so that
+            // 'FAILURE' → 'FAIL', 'NEEDS_RETRY' → 'FAIL', 'ESCALATE' → 'FAIL',
+            // while 'SUCCESS' and 'PARTIAL_SUCCESS' pass through unchanged.
+            outcome = normalizeOutcomeStatus(await handler(node, context, graph));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            outcome = { status: 'FAIL', failureReason: msg };
+        }
+        const isFail = outcome.status === 'FAIL';
+        if (!isFail || attempt >= maxRetries) {
+            // Done: either succeeded or exhausted all retries.
+            // NOTE: event emission (graph:node-completed / graph:node-failed) is intentionally
+            // deferred to the main loop in createGraphExecutor, where it occurs AFTER the
+            // allowPartial demotion check. Emitting here would produce graph:node-completed
+            // for PARTIAL_SUCCESS outcomes that are subsequently demoted to FAIL (violating
+            // Dev Notes §"allow_partial Demotion — Placement in Executor").
+            return outcome;
+        }
+        // Retry path: increment counter, compute delay, emit event, await delay
+        nodeRetries[node.id] = (nodeRetries[node.id] ?? 0) + 1;
+        const delayMs = computeBackoffDelay(attempt);
+        config.eventBus?.emit('graph:node-retried', {
+            runId: config.runId,
+            nodeId: node.id,
+            attempt: attempt + 1, // 1-indexed: first retry = 1
+            maxAttempts,
+            delayMs,
+        });
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        attempt++;
+    }
+}
+// ---------------------------------------------------------------------------
+// createGraphExecutor
+// ---------------------------------------------------------------------------
+/**
+ * Create a new graph executor instance.
+ *
+ * The returned executor's `run()` method drives a factory graph from start node
+ * to exit node (or resumes from a checkpoint if `config.checkpointPath` is set),
+ * dispatching handlers, applying retry logic, writing checkpoints, and emitting
+ * FactoryEvents for full observability.
+ */
+export function createGraphExecutor() {
+    return {
+        async run(graph, config) {
+            // Apply model stylesheet to all nodes before any handler is dispatched.
+            // This is idempotent: nodes with explicit llmModel/llmProvider/reasoningEffort
+            // are never overwritten, so calling it twice (e.g., on resume) is safe.
+            applyStylesheet(graph, config.inheritedStylesheet);
+            const checkpointManager = new CheckpointManager();
+            // Checkpoint is always written to this path (filename is fixed by convention)
+            const checkpointFilePath = path.join(config.logsRoot, 'checkpoint.json');
+            // ConvergenceController for goal gate evaluation (story 42-16)
+            const controller = createConvergenceController();
+            // Convergence budget and plateau managers (story 45-8)
+            const sessionManager = new SessionBudgetManager();
+            const pipelineManager = new PipelineBudgetManager();
+            const plateauDetector = createPlateauDetector({
+                ...(config.plateauWindow !== undefined ? { window: config.plateauWindow } : {}),
+                ...(config.plateauThreshold !== undefined ? { threshold: config.plateauThreshold } : {}),
+            });
+            let convergenceIteration = 0;
+            // Persistence state (story 46-3)
+            const runStartedAt = new Date().toISOString();
+            // Tracks which node is currently executing — used by scenario:completed handler
+            // to populate node_id in scenario_results rows (event payload has no nodeId field).
+            let lastScenarioNodeId = '';
+            // Helper: persist a run exit (success or failure) when adapter is present.
+            // Called at every `return` path that terminates the run.
+            // Persistence errors must not crash the executor — log as warnings.
+            const persistExit = async (finalStatus, finalOutcome) => {
+                if (!config.adapter)
+                    return;
+                try {
+                    await upsertGraphRun(config.adapter, {
+                        id: config.runId,
+                        graph_file: graph.id || config.runId,
+                        ...(graph.goal ? { graph_goal: graph.goal } : {}),
+                        status: finalStatus,
+                        started_at: runStartedAt,
+                        completed_at: new Date().toISOString(),
+                        final_outcome: finalOutcome,
+                        total_cost_usd: pipelineManager.getTotalCost(),
+                        node_count: graph.nodes.size,
+                    });
+                }
+                catch (persistErr) {
+                    const msg = persistErr instanceof Error ? persistErr.message : String(persistErr);
+                    console.warn(`[executor] graph_runs upsert failed for run ${config.runId}: ${msg}`);
+                }
+            };
+            // Execution state
+            let completedNodes = [];
+            let nodeRetries = {};
+            let context = new GraphContext(config.initialContext);
+            let step = 0;
+            // Cycle detection: counts how many times each node is visited
+            const visitCount = new Map();
+            // Tracks FAIL-outcome conditional edge routing count per node (bounds review loops)
+            const failRouteCount = new Map();
+            // Resume state (non-null when config.checkpointPath is set)
+            let resumeCompletedSet = null;
+            // Fidelity override for the first resumed node ('summary:high' or '')
+            let firstResumedFidelity = '';
+            // loopRestart flags: suppress cycle check / completed push for intentional loops
+            let skipCycleCheck = false;
+            let skipCompletedPush = false;
+            // Tracks the edge that led to the current node (for fidelity resolution). Story 49-5.
+            let lastIncomingEdge = undefined;
+            // Capture scenario manifest for integrity checks (story 44-4).
+            // Only runs when scenarioStore is configured; otherwise skipped (backward-compatible).
+            let scenarioManifest = null;
+            if (config.scenarioStore) {
+                scenarioManifest = await config.scenarioStore.discover();
+            }
+            // RunStateManager for per-run artifact persistence (story 44-7).
+            // Opt-in: only instantiated when dotSource is provided. Backward-compatible.
+            const runStateManager = config.dotSource
+                ? new RunStateManager({ runDir: config.logsRoot })
+                : null;
+            if (runStateManager) {
+                await runStateManager.initRun(config.dotSource);
+            }
+            // -----------------------------------------------------------------------
+            // Persistence: subscribe to scenario:completed for score tracking (story 46-3)
+            // The event payload does not include nodeId, so we use lastScenarioNodeId
+            // which is set to currentNode.id each time a node starts executing.
+            // -----------------------------------------------------------------------
+            if (config.adapter && config.eventBus) {
+                const persistAdapter = config.adapter;
+                const scenarioHandler = (payload) => {
+                    const threshold = config.satisfactionThreshold ?? 0.8;
+                    const scored = computeSatisfactionScore(payload.results, threshold);
+                    insertScenarioResult(persistAdapter, {
+                        run_id: config.runId,
+                        node_id: lastScenarioNodeId || 'unknown',
+                        iteration: payload.iteration,
+                        total_scenarios: payload.results.summary.total,
+                        passed: payload.results.summary.passed,
+                        failed: payload.results.summary.failed,
+                        satisfaction_score: scored.score,
+                        threshold: scored.threshold,
+                        passes: scored.passes,
+                        details: JSON.stringify(scored.breakdown),
+                        executed_at: new Date().toISOString(),
+                    }).catch((err) => {
+                        // Persistence errors must not crash the executor — log at debug level only
+                        const msg = err instanceof Error ? err.message : String(err);
+                        console.warn(`[executor] scenario_results persistence failed for run ${config.runId}: ${msg}`);
+                    });
+                };
+                config.eventBus.on('scenario:completed', scenarioHandler);
+            }
+            // -----------------------------------------------------------------------
+            // Persistence: insert graph_runs row at run start (story 46-3)
+            // Persistence errors must not crash the executor — swallow silently.
+            // -----------------------------------------------------------------------
+            if (config.adapter) {
+                try {
+                    await upsertGraphRun(config.adapter, {
+                        id: config.runId,
+                        graph_file: graph.id || config.runId,
+                        ...(graph.goal ? { graph_goal: graph.goal } : {}),
+                        status: 'running',
+                        started_at: runStartedAt,
+                        node_count: graph.nodes.size,
+                    });
+                }
+                catch (persistErr) {
+                    const msg = persistErr instanceof Error ? persistErr.message : String(persistErr);
+                    console.warn(`[executor] graph_runs insert failed for run ${config.runId}: ${msg}`);
+                }
+            }
+            // -----------------------------------------------------------------------
+            // Determine starting node (normal start or resume)
+            // -----------------------------------------------------------------------
+            let currentNode;
+            if (config.checkpointPath) {
+                const checkpoint = await checkpointManager.load(config.checkpointPath);
+                const resumeState = checkpointManager.resume(graph, checkpoint);
+                context = resumeState.context;
+                completedNodes = [...resumeState.completedNodes];
+                nodeRetries = { ...resumeState.nodeRetries };
+                firstResumedFidelity = resumeState.firstResumedNodeFidelity;
+                resumeCompletedSet = resumeState.completedNodes;
+                if (resumeState.completedNodes.has(checkpoint.currentNode)) {
+                    // Last checkpoint node was fully completed — resume from the NEXT node
+                    const lastNode = graph.nodes.get(checkpoint.currentNode);
+                    if (lastNode) {
+                        // KNOWN LIMITATION: The Checkpoint type does not store the final outcome
+                        // status of the last completed node, so we must assume SUCCESS when calling
+                        // selectEdge() to advance past it during resume. If the checkpointed node's
+                        // actual last outcome was non-SUCCESS (e.g., FAILURE with a dedicated failure
+                        // edge), resume will select the SUCCESS edge rather than the FAILURE edge,
+                        // diverging from the original execution path. Storing `lastOutcomeStatus` in
+                        // the Checkpoint type would allow a faithful replay.
+                        const nextEdge = await selectEdge(lastNode, { status: 'SUCCESS' }, context, graph, {
+                            ...(config.eventBus !== undefined ? { eventBus: config.eventBus } : {}),
+                            runId: config.runId,
+                        });
+                        if (nextEdge) {
+                            const nextNode = graph.nodes.get(nextEdge.toNode);
+                            if (!nextNode) {
+                                throw new Error(`Edge target node "${nextEdge.toNode}" not found in graph`);
+                            }
+                            currentNode = nextNode;
+                        }
+                        else {
+                            // No outgoing edge from last completed node — may already be done
+                            currentNode = graph.startNode();
+                        }
+                    }
+                    else {
+                        currentNode = graph.startNode();
+                    }
+                }
+                else {
+                    // Last checkpoint node was NOT completed (process was interrupted mid-node)
+                    // Re-dispatch it from the resumed run
+                    const resumeNode = graph.nodes.get(checkpoint.currentNode);
+                    if (resumeNode) {
+                        currentNode = resumeNode;
+                    }
+                    else {
+                        currentNode = graph.startNode();
+                    }
+                }
+            }
+            else {
+                currentNode = graph.startNode();
+            }
+            // -----------------------------------------------------------------------
+            // Write runId to context so handlers can read it via context.getString("__runId")
+            // Set here (after all context assignments) so it covers both fresh-start and resume.
+            // Story 50-9 (AC4).
+            // -----------------------------------------------------------------------
+            context.set('__runId', config.runId ?? 'unknown');
+            // -----------------------------------------------------------------------
+            // Main traversal loop
+            // -----------------------------------------------------------------------
+            while (true) {
+                // --- Budget checks (story 45-8): session budget (highest priority), then pipeline ---
+                // Budget enforcement priority order: session > pipeline > per-node retries (dispatchWithRetry)
+                const sessionResult = sessionManager.checkBudget((config.wallClockCapMs ?? 0) / 1000);
+                if (!sessionResult.allowed) {
+                    config.eventBus?.emit('convergence:budget-exhausted', {
+                        runId: config.runId,
+                        level: 'session',
+                        reason: sessionResult.reason,
+                    });
+                    await persistExit('failed', `Session budget exceeded: ${sessionResult.reason}`);
+                    return { status: 'FAIL', failureReason: `Session budget exceeded: ${sessionResult.reason}` };
+                }
+                const pipelineResult = pipelineManager.checkBudget(config.pipelineBudgetCapUsd ?? 0);
+                if (!pipelineResult.allowed) {
+                    config.eventBus?.emit('convergence:budget-exhausted', {
+                        runId: config.runId,
+                        level: 'pipeline',
+                        reason: pipelineResult.reason,
+                    });
+                    await persistExit('failed', `Pipeline budget exceeded: ${pipelineResult.reason}`);
+                    return { status: 'FAIL', failureReason: `Pipeline budget exceeded: ${pipelineResult.reason}` };
+                }
+                // Exit condition: arrived at the exit node → evaluate goal gates (story 42-16)
+                const exitNode = graph.exitNode();
+                if (currentNode.id === exitNode.id) {
+                    // scenario-primary mode forces satisfaction score as the authoritative gate signal (story 46-6)
+                    const useScenarioPrimary = config.qualityMode === 'scenario-primary';
+                    const gateResult = controller.checkGoalGates(graph, config.runId, config.eventBus, (useScenarioPrimary || config.satisfactionThreshold !== undefined)
+                        ? { context, satisfactionThreshold: config.satisfactionThreshold ?? 0.8 }
+                        : undefined);
+                    // Emit scenario:advisory-computed when code review verdict is in context and mode is scenario-primary (story 46-6)
+                    if (useScenarioPrimary && config.eventBus) {
+                        const rawVerdict = context.getString(CONTEXT_KEY_CODE_REVIEW_VERDICT, '');
+                        if (rawVerdict !== '') {
+                            const codeReviewVerdict = rawVerdict;
+                            const coordinator = createDualSignalCoordinator({
+                                eventBus: config.eventBus,
+                                threshold: config.satisfactionThreshold ?? 0.8,
+                                qualityMode: 'scenario-primary',
+                            });
+                            const score = context.getNumber('satisfaction_score', 0);
+                            coordinator.evaluate(codeReviewVerdict, score, config.runId);
+                        }
+                    }
+                    if (!gateResult.satisfied) {
+                        // Use ConvergenceController.resolveRetryTarget (story 45-8 — replaces inline 4-step chain)
+                        const failingNodeId = gateResult.failedGates[0];
+                        const failingGateNode = graph.nodes.get(failingNodeId);
+                        const retryTargetId = failingGateNode
+                            ? controller.resolveRetryTarget(failingGateNode, graph)
+                            : null;
+                        if (!retryTargetId) {
+                            await persistExit('failed', 'Goal gate failed: no retry target');
+                            return { status: 'FAIL', failureReason: 'Goal gate failed: no retry target' };
+                        }
+                        const retryNode = graph.nodes.get(retryTargetId);
+                        if (!retryNode) {
+                            throw new Error(`Retry target node "${retryTargetId}" not found in graph`);
+                        }
+                        // Increment convergence iteration and record satisfaction score for plateau detection
+                        convergenceIteration++;
+                        const satisfactionScore = context.getNumber('satisfaction_score', 0.0);
+                        plateauDetector.recordScore(convergenceIteration, satisfactionScore);
+                        // Check for plateau (story 45-8, AC5)
+                        const plateauResult = checkPlateauAndEmit(plateauDetector, {
+                            runId: config.runId,
+                            nodeId: retryTargetId,
+                            ...(config.eventBus ? { eventBus: config.eventBus } : {}),
+                        });
+                        if (plateauResult.plateaued) {
+                            await persistExit('failed', `Convergence plateau detected after ${convergenceIteration} iteration(s)`);
+                            return {
+                                status: 'FAIL',
+                                failureReason: `Convergence plateau detected after ${convergenceIteration} iteration(s): scores plateaued at [${plateauResult.scores.join(', ')}]`,
+                            };
+                        }
+                        // Build and inject remediation context before routing to retry target (story 45-8, AC6)
+                        const remediation = buildRemediationContext({
+                            previousFailureReason: `Goal gate unsatisfied: ${gateResult.failedGates.join(', ')}`,
+                            iterationCount: convergenceIteration,
+                            satisfactionScoreHistory: plateauResult.scores,
+                        });
+                        injectRemediationContext(context, remediation);
+                        // Compress old iteration contexts if auto-summarizer threshold
+                        // exceeded (story 49-3). This prevents unbounded token growth in
+                        // long convergence loops by summarizing earlier iterations.
+                        await controller.prepareForIteration(convergenceIteration);
+                        // Route to retry target; suppress cycle check for convergence loop retry
+                        skipCycleCheck = true;
+                        currentNode = retryNode;
+                        continue;
+                    }
+                    await persistExit('completed', 'SUCCESS');
+                    return { status: 'SUCCESS' };
+                }
+                // Resume skip: nodes already completed in a prior run are advanced over
+                // without dispatching their handler again
+                if (resumeCompletedSet?.has(currentNode.id)) {
+                    // Cast to GraphOutcome (types.ts:Outcome) as required by selectEdge API.
+                    const skipEdge = await selectEdge(currentNode, { status: 'SUCCESS' }, context, graph, {
+                        ...(config.eventBus !== undefined ? { eventBus: config.eventBus } : {}),
+                        runId: config.runId,
+                    });
+                    if (!skipEdge) {
+                        await persistExit('failed', `No outgoing edge from node ${currentNode.id}`);
+                        return {
+                            status: 'FAIL',
+                            failureReason: `No outgoing edge from node ${currentNode.id}`,
+                        };
+                    }
+                    config.eventBus?.emit('graph:edge-selected', {
+                        runId: config.runId,
+                        fromNode: currentNode.id,
+                        toNode: skipEdge.toNode,
+                        step,
+                        ...(skipEdge.label !== '' ? { edgeLabel: skipEdge.label } : {}),
+                    });
+                    step++;
+                    const skipNextNode = graph.nodes.get(skipEdge.toNode);
+                    if (!skipNextNode) {
+                        throw new Error(`Edge target node "${skipEdge.toNode}" not found in graph`);
+                    }
+                    currentNode = skipNextNode;
+                    continue;
+                }
+                // Cycle detection — exempt for nodes reached via loopRestart edges
+                if (!skipCycleCheck) {
+                    const count = (visitCount.get(currentNode.id) ?? 0) + 1;
+                    visitCount.set(currentNode.id, count);
+                    if (count > graph.nodes.size * 3) {
+                        throw new Error(`Graph cycle detected: node ${currentNode.id} visited ${count} times`);
+                    }
+                }
+                skipCycleCheck = false;
+                // Integrity check: verify scenario files before dispatching any tool node (story 44-4)
+                if (currentNode.type === 'tool' && config.scenarioStore && scenarioManifest) {
+                    const integrityResult = await config.scenarioStore.verifyIntegrity(scenarioManifest);
+                    if (!integrityResult.valid) {
+                        config.eventBus?.emit('scenario:integrity-failed', {
+                            runId: config.runId,
+                            nodeId: currentNode.id,
+                            tampered: integrityResult.tampered,
+                        });
+                        await persistExit('failed', `Scenario integrity violation before node "${currentNode.id}"`);
+                        return {
+                            status: 'FAIL',
+                            failureReason: `Scenario integrity violation detected before node "${currentNode.id}": tampered files: ${integrityResult.tampered.join(', ')}`,
+                        };
+                    }
+                    config.eventBus?.emit('scenario:integrity-passed', {
+                        runId: config.runId,
+                        nodeId: currentNode.id,
+                        scenarioCount: scenarioManifest.scenarios.length,
+                    });
+                }
+                // ----------------------------------------------------------------
+                // Track current node ID for scenario:completed event handler (story 46-3)
+                // The scenario:completed event payload has no nodeId field, so we capture it here.
+                // ----------------------------------------------------------------
+                lastScenarioNodeId = currentNode.id;
+                // ----------------------------------------------------------------
+                // Emit graph:node-started before handler invocation
+                // ----------------------------------------------------------------
+                config.eventBus?.emit('graph:node-started', {
+                    runId: config.runId,
+                    nodeId: currentNode.id,
+                    nodeType: currentNode.type,
+                });
+                // ----------------------------------------------------------------
+                // Fidelity override for the first resumed node
+                // ----------------------------------------------------------------
+                const nodeToDispatch = firstResumedFidelity !== ''
+                    ? { ...currentNode, fidelity: firstResumedFidelity }
+                    : currentNode;
+                firstResumedFidelity = ''; // clear after first use
+                // ----------------------------------------------------------------
+                // Pre-dispatch context summarization based on node fidelity (story 49-5)
+                // ----------------------------------------------------------------
+                if (config.summaryEngine) {
+                    const effectiveFidelity = resolveFidelity(nodeToDispatch, lastIncomingEdge, graph);
+                    const summaryLevel = parseFidelityLevel(effectiveFidelity);
+                    if (summaryLevel !== null) {
+                        const nodeContextContent = context.getString('factory.nodeContext', '');
+                        if (nodeContextContent !== '') {
+                            const summary = await config.summaryEngine.summarize(nodeContextContent, summaryLevel);
+                            context.set('factory.compressedNodeContext', summary.content);
+                            // Replace the primary context so downstream handlers use the
+                            // compressed version. The original is preserved in
+                            // factory.compressedNodeContext.originalHash for cache expansion.
+                            context.set('factory.nodeContext', summary.content);
+                            config.eventBus?.emit('graph:context-summarized', {
+                                runId: config.runId,
+                                nodeId: nodeToDispatch.id,
+                                level: summaryLevel,
+                                originalTokenCount: summary.originalTokenCount ?? 0,
+                                summaryTokenCount: summary.summaryTokenCount ?? 0,
+                            });
+                        }
+                    }
+                }
+                // Record dispatch start time for artifact timing (story 44-7)
+                const startedAt = Date.now();
+                // ----------------------------------------------------------------
+                // Dispatch handler with retry logic
+                // ----------------------------------------------------------------
+                let outcome = await dispatchWithRetry(nodeToDispatch, context, graph, config, nodeRetries);
+                // ----------------------------------------------------------------
+                // Hot-spin guard: if the handler completed in under 50ms (e.g., default
+                // handler returning instantly), yield the event loop to prevent CPU
+                // saturation in convergence loops with no-op handlers. In real pipelines
+                // handlers take minutes, so this never fires.
+                // ----------------------------------------------------------------
+                if (Date.now() - startedAt < 50) {
+                    await new Promise((r) => setTimeout(r, 50));
+                }
+                // ----------------------------------------------------------------
+                // allowPartial demotion (story 42-16, AC2/AC3)
+                // After the retry loop exits and the final outcome is determined:
+                // if the node does not accept PARTIAL_SUCCESS, demote to FAIL.
+                // This check uses nodeToDispatch (which has the correct allowPartial value).
+                // ----------------------------------------------------------------
+                if (outcome.status === 'PARTIAL_SUCCESS' && !nodeToDispatch.allowPartial) {
+                    outcome = {
+                        ...outcome,
+                        status: 'FAIL',
+                        failureReason: outcome.failureReason
+                            ? `${outcome.failureReason} (PARTIAL_SUCCESS not accepted: allowPartial=false)`
+                            : 'PARTIAL_SUCCESS not accepted: allowPartial=false',
+                    };
+                }
+                // ----------------------------------------------------------------
+                // Write per-node artifacts (story 44-7)
+                // Called after allowPartial demotion so the persisted status reflects the final outcome.
+                // ----------------------------------------------------------------
+                if (runStateManager) {
+                    const completedAt = Date.now();
+                    const nodeArtifacts = {
+                        nodeId: nodeToDispatch.id,
+                        nodeType: nodeToDispatch.type,
+                        status: outcome.status,
+                        startedAt,
+                        completedAt,
+                        durationMs: completedAt - startedAt,
+                    };
+                    if (nodeToDispatch.type === 'codergen') {
+                        const rawPrompt = nodeToDispatch.prompt || nodeToDispatch.label;
+                        if (rawPrompt)
+                            nodeArtifacts.prompt = rawPrompt;
+                        if (typeof outcome.notes === 'string')
+                            nodeArtifacts.response = outcome.notes;
+                    }
+                    await runStateManager.writeNodeArtifacts(nodeArtifacts);
+                }
+                // ----------------------------------------------------------------
+                // Emit node completion/failure event AFTER allowPartial demotion (story 42-16)
+                // This placement ensures graph:node-failed is emitted when PARTIAL_SUCCESS is
+                // demoted to FAIL, and graph:node-completed is never emitted for a demoted node.
+                // ----------------------------------------------------------------
+                if (outcome.status === 'FAIL') {
+                    config.eventBus?.emit('graph:node-failed', {
+                        runId: config.runId,
+                        nodeId: nodeToDispatch.id,
+                        failureReason: outcome.failureReason ?? 'Unknown failure',
+                    });
+                }
+                else {
+                    config.eventBus?.emit('graph:node-completed', {
+                        runId: config.runId,
+                        nodeId: nodeToDispatch.id,
+                        outcome,
+                    });
+                }
+                // ----------------------------------------------------------------
+                // Record outcome with ConvergenceController (story 42-16)
+                // Map events.ts StageStatus to types.ts OutcomeStatus for the controller.
+                // ----------------------------------------------------------------
+                {
+                    const controllerStatus = outcome.status === 'SUCCESS' ? 'SUCCESS'
+                        : outcome.status === 'PARTIAL_SUCCESS' ? 'PARTIAL_SUCCESS'
+                            : 'FAILURE';
+                    controller.recordOutcome(nodeToDispatch.id, controllerStatus);
+                    // Record iteration context for auto-summarization (story 49-3).
+                    // The context string captures the outcome so compression can
+                    // preserve key facts from earlier iterations.
+                    const iterContent = context.getString('factory.nodeContext', '');
+                    controller.recordIterationContext({
+                        index: convergenceIteration,
+                        content: iterContent,
+                    });
+                }
+                // ----------------------------------------------------------------
+                // Apply context updates from outcome
+                // ----------------------------------------------------------------
+                if (outcome.contextUpdates) {
+                    for (const [key, value] of Object.entries(outcome.contextUpdates)) {
+                        context.set(key, value);
+                    }
+                }
+                // Set 'outcome' in context so conditional edges (e.g. condition="outcome=success")
+                // can reference the handler's result. Status is lowercased for consistency with
+                // DOT convention (outcome=success, outcome=fail).
+                // NOTE: This overwrites on every node. For sequential graphs this is correct — each
+                // node's outcome is available to its outgoing edge conditions. For future parallel
+                // subgraphs (Epic 50), this would need to be scoped per-subgraph to avoid clobbering.
+                context.set('outcome', outcome.status.toLowerCase());
+                // ----------------------------------------------------------------
+                // Accumulate per-node cost for pipeline budget tracking (story 45-8)
+                // Convention: CodergenBackend writes 'factory.lastNodeCostUsd' to contextUpdates.
+                // The key holds only the LAST node's cost; PipelineBudgetManager owns the running total.
+                // This must run AFTER contextUpdates are applied so context.getNumber reflects latest output.
+                // ----------------------------------------------------------------
+                const nodeCost = context.getNumber('factory.lastNodeCostUsd', 0);
+                if (nodeCost > 0) {
+                    pipelineManager.addCost(nodeCost);
+                }
+                // ----------------------------------------------------------------
+                // Persistence: write per-node result row (story 46-3, AC4)
+                // Written after allowPartial demotion (outcome.status is final here)
+                // and after cost accumulation so cost_usd reflects the actual node cost.
+                // ----------------------------------------------------------------
+                if (config.adapter) {
+                    const nodeCompletedAt = Date.now();
+                    try {
+                        await insertGraphNodeResult(config.adapter, {
+                            run_id: config.runId,
+                            node_id: nodeToDispatch.id,
+                            attempt: (nodeRetries[nodeToDispatch.id] ?? 0) + 1,
+                            status: outcome.status,
+                            started_at: new Date(startedAt).toISOString(),
+                            completed_at: new Date(nodeCompletedAt).toISOString(),
+                            duration_ms: nodeCompletedAt - startedAt,
+                            cost_usd: nodeCost,
+                            ...(outcome.failureReason !== undefined ? { failure_reason: outcome.failureReason } : {}),
+                        });
+                    }
+                    catch (persistErr) {
+                        const msg = persistErr instanceof Error ? persistErr.message : String(persistErr);
+                        console.warn(`[executor] graph_node_results insert failed for node ${currentNode.id}: ${msg}`);
+                    }
+                }
+                // ----------------------------------------------------------------
+                // Push completed node (skip for loopRestart re-entry nodes)
+                // ----------------------------------------------------------------
+                if (!skipCompletedPush) {
+                    completedNodes.push(currentNode.id);
+                }
+                skipCompletedPush = false;
+                // ----------------------------------------------------------------
+                // Save checkpoint after each node completion
+                // ----------------------------------------------------------------
+                await checkpointManager.save(config.logsRoot, {
+                    currentNode: currentNode.id,
+                    completedNodes,
+                    nodeRetries,
+                    context,
+                });
+                config.eventBus?.emit('graph:checkpoint-saved', {
+                    runId: config.runId,
+                    nodeId: currentNode.id,
+                    checkpointPath: checkpointFilePath,
+                });
+                // ----------------------------------------------------------------
+                // FAIL routing (story 42-16)
+                // When outcome is FAIL (including demoted PARTIAL_SUCCESS), route to
+                // the node-level retryTarget chain or return FAIL immediately.
+                // ----------------------------------------------------------------
+                if (outcome.status === 'FAIL') {
+                    // Resolves via 4-level chain: node.retryTarget → node.fallbackRetryTarget → graph.retryTarget → graph.fallbackRetryTarget → null (story 45-2)
+                    const retryTarget = controller.resolveRetryTarget(currentNode, graph);
+                    if (retryTarget) {
+                        const retryNode = graph.nodes.get(retryTarget);
+                        if (!retryNode) {
+                            throw new Error(`Retry target node "${retryTarget}" not found in graph`);
+                        }
+                        skipCycleCheck = true;
+                        currentNode = retryNode;
+                        continue;
+                    }
+                    // No retry target found. If this node has conditional outgoing edges
+                    // (e.g. code_review with shape=diamond), fall through to edge selection so
+                    // condition-based routing can handle the FAIL outcome. Otherwise return FAIL.
+                    const outgoing = graph.edges.filter((e) => e.fromNode === currentNode.id);
+                    const hasConditionalEdge = outgoing.some((e) => e.condition && e.condition.trim() !== '');
+                    if (!hasConditionalEdge) {
+                        await persistExit('failed', outcome.failureReason ?? 'FAIL');
+                        return {
+                            status: 'FAIL',
+                            ...(outcome.failureReason !== undefined && { failureReason: outcome.failureReason }),
+                        };
+                    }
+                    // Fall through to edge selection for conditional routing.
+                    // The cycle detection (visitCount) bounds this loop — conditional edge targets
+                    // with maxRetries>0 (e.g. dev_story set by --max-review-cycles) will eventually
+                    // hit the visit limit. Additionally, track fail-route count as a safeguard.
+                    const routeCount = (failRouteCount.get(currentNode.id) ?? 0) + 1;
+                    failRouteCount.set(currentNode.id, routeCount);
+                    // Safeguard: cap fail-route loops at graph.defaultMaxRetries or 3 (whichever is higher)
+                    if (routeCount > Math.max(graph.defaultMaxRetries || 0, 3)) {
+                        await persistExit('failed', outcome.failureReason ?? 'FAIL');
+                        return {
+                            status: 'FAIL',
+                            ...(outcome.failureReason !== undefined && { failureReason: outcome.failureReason }),
+                        };
+                    }
+                }
+                // ----------------------------------------------------------------
+                // Select next edge
+                // ----------------------------------------------------------------
+                // Cast outcome to GraphOutcome (types.ts:Outcome) as required by selectEdge API.
+                const edge = await selectEdge(currentNode, outcome, context, graph, {
+                    ...(config.eventBus !== undefined ? { eventBus: config.eventBus } : {}),
+                    runId: config.runId,
+                });
+                if (!edge) {
+                    await persistExit('failed', `No outgoing edge from node ${currentNode.id}`);
+                    return {
+                        status: 'FAIL',
+                        failureReason: `No outgoing edge from node ${currentNode.id}`,
+                    };
+                }
+                // ----------------------------------------------------------------
+                // Emit graph:edge-selected after edge selection
+                // ----------------------------------------------------------------
+                config.eventBus?.emit('graph:edge-selected', {
+                    runId: config.runId,
+                    fromNode: currentNode.id,
+                    toNode: edge.toNode,
+                    step,
+                    ...(edge.label !== '' ? { edgeLabel: edge.label } : {}),
+                });
+                step++;
+                // ----------------------------------------------------------------
+                // Handle loopRestart: next iteration skips cycle check and
+                // completed push (treating target as a fresh re-entry)
+                // ----------------------------------------------------------------
+                if (edge.loopRestart) {
+                    skipCycleCheck = true;
+                    skipCompletedPush = true;
+                }
+                // ----------------------------------------------------------------
+                // Advance to next node
+                // ----------------------------------------------------------------
+                const nextNode = graph.nodes.get(edge.toNode);
+                if (!nextNode) {
+                    throw new Error(`Edge target node "${edge.toNode}" not found in graph`);
+                }
+                lastIncomingEdge = edge;
+                currentNode = nextNode;
+            }
+        },
+    };
+}
+//# sourceMappingURL=executor.js.map