@substrate-ai/factory 0.19.54

package/dist/graph/executor.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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 type { Graph, ParsedStylesheet } from './types.js';
+import type { IHandlerRegistry } from '../handlers/types.js';
+import type { TypedEventBus, DatabaseAdapter } from '@substrate-ai/core';
+import type { FactoryEvents, Outcome } from '../events.js';
+import type { QualityMode } from '../convergence/index.js';
+import type { ScenarioStore } from '../scenarios/index.js';
+import type { SummaryEngine } from '../context/summary-engine.js';
+/**
+ * Configuration for a single graph execution run.
+ */
+export interface GraphExecutorConfig {
+    /** Unique identifier for this run — included in every emitted event */
+    runId: string;
+    /** Directory where checkpoint.json and node log subdirs are written */
+    logsRoot: string;
+    /** Handler registry used to resolve node type → handler function */
+    handlerRegistry: IHandlerRegistry;
+    /**
+     * Typed event bus for emitting graph:* events.
+     * Optional — if not provided, event emission is a no-op (safe to omit in tests).
+     */
+    eventBus?: TypedEventBus<FactoryEvents>;
+    /**
+     * If provided, the executor loads this checkpoint file and resumes
+     * from the last completed node rather than starting at the start node.
+     */
+    checkpointPath?: string;
+    /**
+     * When provided, the executor captures a scenario manifest at run start and
+     * verifies integrity before each `tool` node executes (story 44-4).
+     * Omit to skip all scenario integrity checks (backward-compatible default).
+     */
+    scenarioStore?: ScenarioStore;
+    /**
+     * Raw DOT source string of the executed graph.
+     * When provided, written to `graph.dot` in the run directory at execution start.
+     * Also enables per-node artifact writing via RunStateManager (story 44-7).
+     */
+    dotSource?: string;
+    /**
+     * Session wall-clock budget in milliseconds (0 = unlimited).
+     * Checked at the top of each main loop iteration — highest budget priority.
+     * Wired to FactoryConfig.wall_clock_cap_ms in the factory run command.
+     */
+    wallClockCapMs?: number;
+    /**
+     * Pipeline cost budget in USD (0 = unlimited).
+     * Checked after the session budget — second-highest priority.
+     * Accumulates per-node costs read from context key 'factory.lastNodeCostUsd'.
+     */
+    pipelineBudgetCapUsd?: number;
+    /**
+     * Plateau detector window size — number of satisfaction scores to compare.
+     * Defaults to 3 when omitted. Passed to createPlateauDetector().
+     */
+    plateauWindow?: number;
+    /**
+     * Plateau detector threshold — max−min delta below which plateau is declared.
+     * Defaults to 0.05 when omitted. Passed to createPlateauDetector().
+     */
+    plateauThreshold?: number;
+    /**
+     * Satisfaction score threshold for goal gate evaluation (0–1).
+     * When set, checkGoalGates() compares satisfaction_score from context against
+     * this threshold. Wired from FactoryConfig.satisfaction_threshold in the factory run command.
+     */
+    satisfactionThreshold?: number;
+    /**
+     * Quality mode for goal gate evaluation — wired from FactoryConfig.quality_mode. Story 46-6.
+     *   'scenario-primary' — satisfaction score is authoritative; code review is advisory only.
+     *   'dual-signal'      — default; falls back to outcome-status-based evaluation.
+     *   'code-review'      — code review verdict drives the gate (legacy Phase 2).
+     *   'scenario-only'    — satisfaction score only; code review skipped.
+     */
+    qualityMode?: QualityMode;
+    /**
+     * Optional database adapter for persisting graph run and node result records.
+     * When omitted, all persistence is skipped (backward-compatible default).
+     * Must be imported as a type only — do not import concrete adapter implementations.
+     */
+    adapter?: DatabaseAdapter;
+    /**
+     * Optional summary engine for fidelity-based context compression.
+     * When provided, nodes with a non-'full' fidelity level will have their
+     * 'factory.nodeContext' compressed to the target level before dispatch.
+     * When absent, all fidelity-related summarization is skipped (backward-compatible).
+     * Story 49-5.
+     */
+    summaryEngine?: SummaryEngine;
+    /**
+     * Optional initial key-value pairs seeded into the GraphContext at execution start.
+     * Used by the SDLC graph orchestrator to inject storyKey, runId, projectRoot, etc.
+     * into the context before the first node handler executes.
+     */
+    initialContext?: Record<string, unknown>;
+    /**
+     * Stylesheet rules inherited from a parent graph. Prepended before the graph's
+     * own model_stylesheet; child rules win at equal specificity via source order.
+     * Used by createSubgraphHandler.
+     */
+    inheritedStylesheet?: ParsedStylesheet;
+}
+/**
+ * Graph executor interface — drives a factory graph from start to exit node.
+ */
+export interface GraphExecutor {
+    run(graph: Graph, config: GraphExecutorConfig): Promise<Outcome>;
+}
+/**
+ * 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 declare function createGraphExecutor(): GraphExecutor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/graph/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/graph/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAwG,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAK/J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAqB,MAAM,cAAc,CAAA;AAa7E,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,yBAAyB,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,uBAAuB,CAAA;AAG5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAQjE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,eAAe,EAAE,gBAAgB,CAAA;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACvC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAMlB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IAMzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IAEzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAE7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAExC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,gBAAgB,CAAA;CACvC;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACjE;AAsHD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAgsBnD"}