@framers/agentos 0.1.69 → 0.1.71

package/dist/orchestration/runtime/NodeExecutor.js

@@ -0,0 +1,227 @@
+/**
+ * @file NodeExecutor.ts
+ * @description Dispatches execution to the appropriate handler based on `GraphNode.executorConfig.type`.
+ *
+ * The executor is intentionally thin — it contains no retry logic (handled by `GraphRuntime`),
+ * no state mutation (handled by `StateManager`), and no event emission (handled by the caller).
+ * Each private method maps one-to-one with a `NodeExecutorConfig` variant.
+ *
+ * Execution flow:
+ *   `execute()` → optional timeout race → `executeNode()` → variant handler
+ *
+ * Placeholders for `gmi`, `extension`, and `subgraph` nodes are wired in `GraphRuntime`
+ * after the `LoopController` and extension managers are available.
+ */
+// ---------------------------------------------------------------------------
+// NodeExecutor
+// ---------------------------------------------------------------------------
+/**
+ * Stateless executor that dispatches a `GraphNode` to the appropriate handler.
+ *
+ * One `NodeExecutor` instance is typically shared across the lifetime of a `GraphRuntime`
+ * and reused for every node invocation within every run. All state is passed through
+ * `GraphState` and returned via `NodeExecutionResult`.
+ *
+ * @example
+ * ```ts
+ * const executor = new NodeExecutor({ toolOrchestrator, guardrailEngine });
+ * const result = await executor.execute(node, graphState);
+ * if (!result.success) console.error(result.error);
+ * ```
+ */
+export class NodeExecutor {
+    /**
+     * @param deps - External service adapters. All fields are optional; missing services
+     *               cause graceful degradation rather than hard failures.
+     */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Execute `node` against the provided `state`, optionally racing against a timeout.
+     *
+     * If `node.timeout` is set, execution races against a timer that resolves with a
+     * `success: false` result after the specified number of milliseconds.
+     *
+     * @param node  - Immutable node descriptor from the compiled graph IR.
+     * @param state - Current (partial) graph state threaded from the runtime.
+     * @returns A `NodeExecutionResult` describing the outcome.
+     */
+    async execute(node, state) {
+        if (node.timeout) {
+            return Promise.race([
+                this.executeNode(node, state),
+                this.buildTimeoutPromise(node.timeout, node.id),
+            ]);
+        }
+        return this.executeNode(node, state);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal dispatch
+    // ---------------------------------------------------------------------------
+    /**
+     * Dispatches to the correct private handler based on `executorConfig.type`.
+     *
+     * Each branch receives only the narrowed config type it needs, keeping handler
+     * signatures precise and avoiding accidental access to unrelated fields.
+     */
+    async executeNode(node, state) {
+        const config = node.executorConfig;
+        switch (config.type) {
+            case 'tool':
+                return this.executeTool(config, state);
+            case 'router':
+                return this.executeRouter(config, state);
+            case 'guardrail':
+                return this.executeGuardrail(config, state);
+            case 'human':
+                return this.executeHuman(config);
+            case 'gmi':
+                // GMI execution is delegated to `LoopController` and wired in `GraphRuntime`.
+                // This placeholder allows the executor to be used before the LLM subsystem is ready.
+                return { success: true, output: 'gmi-placeholder' };
+            case 'extension':
+                // Extension execution is wired by `GraphRuntime` once the extension manager is available.
+                return { success: true, output: 'extension-placeholder' };
+            case 'subgraph':
+                // Subgraph delegation is wired by `GraphRuntime` once nested graph lookup is available.
+                return { success: true, output: 'subgraph-placeholder' };
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Variant handlers
+    // ---------------------------------------------------------------------------
+    /**
+     * Invokes a registered `ITool` via `ToolOrchestrator.processToolCall()`.
+     *
+     * Static args from `config.args` are merged into the call. The orchestrator
+     * is responsible for argument validation and schema enforcement.
+     *
+     * @param config - `{ type: 'tool'; toolName: string; args?: Record<string, unknown> }`
+     * @param state  - Current graph state (not used directly but available for future extension).
+     */
+    async executeTool(config, _state) {
+        if (!this.deps.toolOrchestrator) {
+            return {
+                success: false,
+                error: 'No ToolOrchestrator configured',
+            };
+        }
+        const result = await this.deps.toolOrchestrator.processToolCall({
+            toolCallRequest: {
+                toolName: config.toolName,
+                arguments: config.args ?? {},
+            },
+        });
+        return {
+            success: result.success ?? !result.isError,
+            output: result.output,
+            error: result.error,
+        };
+    }
+    /**
+     * Evaluates a `GraphCondition` and returns the resolved target node id as `routeTarget`.
+     *
+     * Two condition strategies are supported:
+     * - `function` — calls the runtime-registered TypeScript `fn` directly.
+     * - `expression` — delegates to `evaluateExpression()` for DSL string evaluation.
+     *
+     * @param config - `{ type: 'router'; condition: GraphCondition }`
+     * @param state  - Current graph state passed to the condition function/evaluator.
+     */
+    async executeRouter(config, state) {
+        let target;
+        if (config.condition.type === 'function') {
+            // The function condition receives the full state and returns a node id.
+            target = config.condition.fn(state);
+        }
+        else {
+            // Expression-based conditions are evaluated by the minimal DSL interpreter.
+            target = this.evaluateExpression(config.condition.expr, state);
+        }
+        return { success: true, routeTarget: target };
+    }
+    /**
+     * Evaluates a set of guardrails against `state.scratch` and either passes through
+     * or triggers the configured violation action.
+     *
+     * When no `guardrailEngine` is configured, the node always passes (permissive default).
+     * Violation handling currently supports `'reroute'`; `'block'`, `'warn'`, and `'sanitize'`
+     * are propagated via `success: false` for the runtime to handle.
+     *
+     * @param config - Guardrail node config with `guardrailIds`, `onViolation`, and optional `rerouteTarget`.
+     * @param state  - Current graph state; `state.scratch` is passed to the engine as the content payload.
+     */
+    async executeGuardrail(config, state) {
+        if (!this.deps.guardrailEngine) {
+            // Permissive fallback: no engine means no enforcement.
+            return {
+                success: true,
+                output: { passed: true, message: 'No guardrail engine configured' },
+            };
+        }
+        const result = await this.deps.guardrailEngine.evaluate(state.scratch, config.guardrailIds);
+        if (!result.passed && config.onViolation === 'reroute' && config.rerouteTarget) {
+            // Soft violation: redirect the graph to the recovery branch.
+            return { success: true, routeTarget: config.rerouteTarget };
+        }
+        // For all other violation actions (block, warn, sanitize) the runtime inspects
+        // `success: false` and acts according to its own policy.
+        return {
+            success: result.passed,
+            output: result,
+        };
+    }
+    /**
+     * Suspends execution and surfaces a prompt to a human operator.
+     *
+     * The runtime must treat `interrupt: true` as a signal to persist state, emit an
+     * `interrupt` event, and halt the current run until the operator provides a response.
+     *
+     * @param config - `{ type: 'human'; prompt: string }`
+     */
+    executeHuman(config) {
+        return Promise.resolve({
+            success: false,
+            interrupt: true,
+            error: 'Awaiting human input',
+            output: { prompt: config.prompt },
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Utilities
+    // ---------------------------------------------------------------------------
+    /**
+     * Minimal DSL expression evaluator for `{ type: 'expression' }` routing conditions.
+     *
+     * Current implementation is a stub that returns the expression string unchanged.
+     * A full implementation would parse `"scratch.confidence > 0.8 ? 'approve' : 'review'"`
+     * using a sandboxed interpreter with dot-path access to `state` fields.
+     *
+     * @param expr  - The DSL expression string from `GraphConditionExpr`.
+     * @param state - Current graph state (available for a real implementation to traverse).
+     * @returns The resolved target node id (or the raw expression until the evaluator is complete).
+     *
+     * @todo Implement a sandboxed expression interpreter (tracked separately).
+     */
+    evaluateExpression(expr, _state) {
+        return expr;
+    }
+    /**
+     * Builds a `Promise` that resolves with a timeout-failure result after `ms` milliseconds.
+     *
+     * Races against `executeNode()` inside `execute()` to enforce `GraphNode.timeout`.
+     *
+     * @param ms     - Timeout duration in milliseconds.
+     * @param nodeId - Node id included in the error message for debugging.
+     */
+    buildTimeoutPromise(ms, nodeId) {
+        return new Promise((resolve) => {
+            setTimeout(() => resolve({ success: false, error: `Node ${nodeId} timeout after ${ms}ms` }), ms);
+        });
+    }
+}
+//# sourceMappingURL=NodeExecutor.js.map

package/dist/orchestration/runtime/NodeExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeExecutor.js","sourceRoot":"","sources":["../../../src/orchestration/runtime/NodeExecutor.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/runtime/NodeScheduler.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file NodeScheduler.ts
+ * @description Topological ordering, cycle detection, and ready-node detection
+ * for compiled execution graph scheduling in the AgentOS Unified Orchestration Layer.
+ *
+ * Uses Kahn's algorithm (BFS-based) for topological sorting, which also serves
+ * as the foundation for cycle detection. The scheduler treats START and END as
+ * virtual nodes that participate in edge traversal but are excluded from the
+ * returned topological order.
+ */
+import type { GraphNode, GraphEdge } from '../ir/types.js';
+/**
+ * Schedules graph node execution by computing topological ordering, detecting
+ * structural issues (cycles, unreachable nodes), and determining which nodes
+ * are ready to run given a set of already-completed nodes.
+ *
+ * All methods are pure and stateless with respect to execution — the scheduler
+ * only reads the static graph structure provided at construction time.
+ */
+export declare class NodeScheduler {
+    /** Maps each node id to its outgoing neighbour ids. Includes START and END. */
+    private adjacency;
+    /** Maps each node id to the ids of nodes that have edges pointing into it. Includes START and END. */
+    private predecessors;
+    /** Set of real (non-sentinel) node ids derived from the provided GraphNode array. */
+    private nodeIds;
+    /**
+     * Constructs a NodeScheduler from a compiled graph's node and edge lists.
+     *
+     * @param nodes - All real (non-sentinel) graph nodes.
+     * @param edges - All directed edges, including those from/to START or END sentinels.
+     */
+    constructor(nodes: GraphNode[], edges: GraphEdge[]);
+    /**
+     * Returns real node ids in a valid topological execution order using Kahn's
+     * algorithm (BFS over in-degree).
+     *
+     * START and END sentinels are intentionally excluded from the returned array
+     * because they are virtual control-flow markers, not executable nodes.
+     *
+     * If the graph contains a cycle, the returned array will be shorter than
+     * `nodeIds.size` — use {@link hasCycles} to distinguish this case explicitly.
+     *
+     * @returns Ordered array of real node ids; empty if there are no real nodes.
+     */
+    topologicalSort(): string[];
+    /**
+     * Returns `true` if the graph contains at least one directed cycle among the
+     * real nodes (sentinels are excluded from cycle detection).
+     *
+     * Implemented by comparing the length of the topological sort result against
+     * the total number of real nodes: Kahn's algorithm processes every node in a
+     * DAG, so any shortfall indicates nodes trapped inside a cycle.
+     *
+     * @returns `true` when a cycle exists; `false` for a valid DAG.
+     */
+    hasCycles(): boolean;
+    /**
+     * Returns the ids of all real nodes that are eligible to execute next, given
+     * the set of nodes that have already finished (completed or skipped).
+     *
+     * A node is "ready" when:
+     * 1. It has not already completed or been skipped.
+     * 2. Every one of its predecessors is either the START sentinel or a member of
+     *    the completed/skipped set.
+     *
+     * @param completedNodeIds - Node ids that have successfully finished execution.
+     * @param skippedNodeIds   - Node ids that were bypassed (e.g. via conditional routing).
+     * @returns Array of node ids that can be dispatched for execution immediately.
+     */
+    getReadyNodes(completedNodeIds: string[], skippedNodeIds?: string[]): string[];
+    /**
+     * Returns the ids of all real nodes that are not reachable from the START
+     * sentinel via a BFS traversal of the adjacency list.
+     *
+     * Unreachable (orphan) nodes indicate a structural authoring error: they can
+     * never execute because no execution path leads to them.  The runtime may
+     * choose to warn, error, or prune these nodes before starting a run.
+     *
+     * @returns Array of node ids that cannot be reached from START; empty for a
+     *          well-formed graph.
+     */
+    getUnreachableNodes(): string[];
+}
+//# sourceMappingURL=NodeScheduler.d.ts.map

package/dist/orchestration/runtime/NodeScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeScheduler.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/NodeScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3D;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAoC;IAErD,sGAAsG;IACtG,OAAO,CAAC,YAAY,CAAoC;IAExD,qFAAqF;IACrF,OAAO,CAAC,OAAO,CAAc;IAE7B;;;;;OAKG;gBACS,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE;IAoBlD;;;;;;;;;;;OAWG;IACH,eAAe,IAAI,MAAM,EAAE;IAwD3B;;;;;;;;;OASG;IACH,SAAS,IAAI,OAAO;IAQpB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,gBAAgB,EAAE,MAAM,EAAE,EAAE,cAAc,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE;IAuBlF;;;;;;;;;;OAUG;IACH,mBAAmB,IAAI,MAAM,EAAE;CAmBhC"}

package/dist/orchestration/runtime/NodeScheduler.js

@@ -0,0 +1,180 @@
+/**
+ * @file NodeScheduler.ts
+ * @description Topological ordering, cycle detection, and ready-node detection
+ * for compiled execution graph scheduling in the AgentOS Unified Orchestration Layer.
+ *
+ * Uses Kahn's algorithm (BFS-based) for topological sorting, which also serves
+ * as the foundation for cycle detection. The scheduler treats START and END as
+ * virtual nodes that participate in edge traversal but are excluded from the
+ * returned topological order.
+ */
+import { START, END } from '../ir/types.js';
+/**
+ * Schedules graph node execution by computing topological ordering, detecting
+ * structural issues (cycles, unreachable nodes), and determining which nodes
+ * are ready to run given a set of already-completed nodes.
+ *
+ * All methods are pure and stateless with respect to execution — the scheduler
+ * only reads the static graph structure provided at construction time.
+ */
+export class NodeScheduler {
+    /**
+     * Constructs a NodeScheduler from a compiled graph's node and edge lists.
+     *
+     * @param nodes - All real (non-sentinel) graph nodes.
+     * @param edges - All directed edges, including those from/to START or END sentinels.
+     */
+    constructor(nodes, edges) {
+        /** Maps each node id to its outgoing neighbour ids. Includes START and END. */
+        this.adjacency = new Map();
+        /** Maps each node id to the ids of nodes that have edges pointing into it. Includes START and END. */
+        this.predecessors = new Map();
+        this.nodeIds = new Set(nodes.map(n => n.id));
+        // Initialise adjacency and predecessor lists for every real node plus the
+        // two virtual sentinels so edge lookups never need a null-check.
+        for (const id of [START, END, ...this.nodeIds]) {
+            this.adjacency.set(id, []);
+            this.predecessors.set(id, []);
+        }
+        for (const edge of edges) {
+            this.adjacency.get(edge.source)?.push(edge.target);
+            this.predecessors.get(edge.target)?.push(edge.source);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Topological ordering
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns real node ids in a valid topological execution order using Kahn's
+     * algorithm (BFS over in-degree).
+     *
+     * START and END sentinels are intentionally excluded from the returned array
+     * because they are virtual control-flow markers, not executable nodes.
+     *
+     * If the graph contains a cycle, the returned array will be shorter than
+     * `nodeIds.size` — use {@link hasCycles} to distinguish this case explicitly.
+     *
+     * @returns Ordered array of real node ids; empty if there are no real nodes.
+     */
+    topologicalSort() {
+        // Compute in-degree for every real node (edges from sentinels count too).
+        const inDegree = new Map();
+        for (const id of this.nodeIds) {
+            const preds = this.predecessors.get(id) ?? [];
+            inDegree.set(id, preds.length);
+        }
+        // Seed the queue with nodes that have no predecessors at all, or whose
+        // only predecessors are START (treated as "already satisfied" at t=0).
+        const queue = [];
+        for (const [id, _degree] of inDegree) {
+            // A node is initially ready when all its predecessors are sentinels
+            // (START/END) or it has no predecessors.
+            const realPredCount = (this.predecessors.get(id) ?? []).filter(p => p !== START && p !== END).length;
+            if (realPredCount === 0) {
+                queue.push(id);
+            }
+        }
+        const sorted = [];
+        // Track a "virtual" in-degree that only counts real predecessors so that
+        // START/END sentinel edges don't artificially inflate the degree.
+        const realInDegree = new Map();
+        for (const id of this.nodeIds) {
+            realInDegree.set(id, (this.predecessors.get(id) ?? []).filter(p => p !== START && p !== END).length);
+        }
+        while (queue.length > 0) {
+            const current = queue.shift();
+            sorted.push(current);
+            for (const neighbour of this.adjacency.get(current) ?? []) {
+                // Skip sentinel targets — they have no real in-degree entry.
+                if (!this.nodeIds.has(neighbour))
+                    continue;
+                const remaining = (realInDegree.get(neighbour) ?? 0) - 1;
+                realInDegree.set(neighbour, remaining);
+                if (remaining === 0) {
+                    queue.push(neighbour);
+                }
+            }
+        }
+        return sorted;
+    }
+    // ---------------------------------------------------------------------------
+    // Cycle detection
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns `true` if the graph contains at least one directed cycle among the
+     * real nodes (sentinels are excluded from cycle detection).
+     *
+     * Implemented by comparing the length of the topological sort result against
+     * the total number of real nodes: Kahn's algorithm processes every node in a
+     * DAG, so any shortfall indicates nodes trapped inside a cycle.
+     *
+     * @returns `true` when a cycle exists; `false` for a valid DAG.
+     */
+    hasCycles() {
+        return this.topologicalSort().length < this.nodeIds.size;
+    }
+    // ---------------------------------------------------------------------------
+    // Ready-node detection
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the ids of all real nodes that are eligible to execute next, given
+     * the set of nodes that have already finished (completed or skipped).
+     *
+     * A node is "ready" when:
+     * 1. It has not already completed or been skipped.
+     * 2. Every one of its predecessors is either the START sentinel or a member of
+     *    the completed/skipped set.
+     *
+     * @param completedNodeIds - Node ids that have successfully finished execution.
+     * @param skippedNodeIds   - Node ids that were bypassed (e.g. via conditional routing).
+     * @returns Array of node ids that can be dispatched for execution immediately.
+     */
+    getReadyNodes(completedNodeIds, skippedNodeIds = []) {
+        // Build a unified "done" set that includes the START sentinel so that nodes
+        // whose only predecessor is START are treated as immediately satisfiable.
+        const done = new Set([START, ...completedNodeIds, ...skippedNodeIds]);
+        const ready = [];
+        for (const nodeId of this.nodeIds) {
+            // Skip nodes that are already done.
+            if (done.has(nodeId))
+                continue;
+            const preds = this.predecessors.get(nodeId) ?? [];
+            if (preds.every(p => done.has(p))) {
+                ready.push(nodeId);
+            }
+        }
+        return ready;
+    }
+    // ---------------------------------------------------------------------------
+    // Reachability analysis
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the ids of all real nodes that are not reachable from the START
+     * sentinel via a BFS traversal of the adjacency list.
+     *
+     * Unreachable (orphan) nodes indicate a structural authoring error: they can
+     * never execute because no execution path leads to them.  The runtime may
+     * choose to warn, error, or prune these nodes before starting a run.
+     *
+     * @returns Array of node ids that cannot be reached from START; empty for a
+     *          well-formed graph.
+     */
+    getUnreachableNodes() {
+        const visited = new Set();
+        const queue = [START];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            for (const neighbour of this.adjacency.get(current) ?? []) {
+                if (!visited.has(neighbour)) {
+                    queue.push(neighbour);
+                }
+            }
+        }
+        // Return real nodes that BFS never visited.
+        return [...this.nodeIds].filter(id => !visited.has(id));
+    }
+}
+//# sourceMappingURL=NodeScheduler.js.map

package/dist/orchestration/runtime/NodeScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeScheduler.js","sourceRoot":"","sources":["../../../src/orchestration/runtime/NodeScheduler.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/runtime/StateManager.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @file StateManager.ts
+ * @description Manages the mutable {@link GraphState} partitions for an active graph run.
+ *
+ * Responsibilities:
+ *  - Creating a clean initial state from caller-supplied input.
+ *  - Applying node output patches to the `scratch` partition, honoring per-field
+ *    {@link StateReducers} for deterministic conflict resolution.
+ *  - Applying node output patches to the `artifacts` partition (last-write-wins by default).
+ *  - Merging states produced by parallel branches using the same reducer logic.
+ *  - Tracking the ordered list of visited node ids and the global iteration counter.
+ *
+ * `StateManager` is intentionally stateless between calls — it receives the current
+ * {@link GraphState} as an argument and returns a *new* object; it never mutates in place.
+ * This makes it straightforward to unit-test and safe to use in concurrent contexts.
+ */
+import type { StateReducers, GraphState } from '../ir/types.js';
+/**
+ * Manages the {@link GraphState} partitions (`input`, `scratch`, `artifacts`,
+ * `memory`, `diagnostics`) for a single graph run.
+ *
+ * All methods return a *new* `GraphState` object; the original is never mutated.
+ *
+ * @example
+ * ```ts
+ * const manager = new StateManager({ 'scratch.messages': 'concat' });
+ * let state = manager.initialize({ prompt: 'Hello' });
+ * state = manager.updateScratch(state, { messages: ['first'] });
+ * state = manager.updateScratch(state, { messages: ['second'] });
+ * // state.scratch.messages === ['first', 'second']
+ * ```
+ */
+export declare class StateManager {
+    private readonly reducers;
+    /**
+     * @param reducers - Field-level reducer configuration keyed by dot-notation paths
+     *                   (e.g. `'scratch.messages'`).  Determines how conflicting values
+     *                   are merged during {@link updateScratch} and {@link mergeParallelBranches}.
+     */
+    constructor(reducers: StateReducers);
+    /**
+     * Create a clean initial {@link GraphState} from the caller-supplied `input` value.
+     *
+     * The `input` partition is frozen with {@link Object.freeze} so that no node can
+     * accidentally mutate it.  All other partitions start empty.
+     *
+     * @param input - Arbitrary value provided by the graph caller; becomes `state.input`.
+     * @returns A fully initialised `GraphState` ready for the first node execution.
+     */
+    initialize(input: unknown): GraphState;
+    /**
+     * Apply a `patch` to the `scratch` partition, honoring any registered reducers.
+     *
+     * For each key in `patch`:
+     *  - If a reducer is registered at `scratch.<key>` **and** the key already exists
+     *    in the current scratch, the reducer is called to merge the existing and incoming
+     *    values.
+     *  - Otherwise the incoming value simply overwrites (last-write-wins semantics).
+     *
+     * @param state - Current graph state (not mutated).
+     * @param patch - Partial scratch update emitted by a completed node.
+     * @returns New `GraphState` with the merged scratch partition.
+     */
+    updateScratch(state: GraphState, patch: Record<string, unknown>): GraphState;
+    /**
+     * Apply a `patch` to the `artifacts` partition using last-write-wins semantics.
+     *
+     * Artifact fields are intended for caller-facing outputs and are not subject to
+     * reducer logic in this method.  If you need reducer-aware artifact merging, use
+     * {@link mergeParallelBranches} instead.
+     *
+     * @param state - Current graph state (not mutated).
+     * @param patch - Partial artifacts update emitted by a completed node.
+     * @returns New `GraphState` with the updated artifacts partition.
+     */
+    updateArtifacts(state: GraphState, patch: Record<string, unknown>): GraphState;
+    /**
+     * Record that execution has entered `nodeId`.
+     *
+     * Updates `currentNodeId`, appends to `visitedNodes`, and increments `iteration`.
+     *
+     * @param state  - Current graph state (not mutated).
+     * @param nodeId - Id of the node that is about to execute.
+     * @returns New `GraphState` reflecting the visit.
+     */
+    recordNodeVisit(state: GraphState, nodeId: string): GraphState;
+    /**
+     * Merge the `scratch` partitions of one or more parallel branch states back into
+     * a single `GraphState`.
+     *
+     * The algorithm walks every key present in any branch's scratch object and applies
+     * the registered reducer for that key (if any) against the accumulator.  When no
+     * reducer is registered, the last branch's value wins.
+     *
+     * The `artifacts`, `memory`, `diagnostics`, `visitedNodes`, and `iteration` fields
+     * of `baseState` are preserved unchanged — the caller is responsible for merging
+     * those separately if needed.
+     *
+     * @param baseState    - State prior to the parallel fan-out (provides the baseline scratch).
+     * @param branchStates - States produced by each parallel branch.
+     * @returns New `GraphState` with the merged scratch partition.
+     */
+    mergeParallelBranches(baseState: GraphState, branchStates: GraphState[]): GraphState;
+    /**
+     * Dispatch to a {@link BuiltinReducer} strategy or call a custom {@link ReducerFn}.
+     *
+     * @param reducer  - The reducer to apply.
+     * @param existing - Value currently stored in `GraphState`.
+     * @param incoming - New value emitted by the most recently completed node.
+     * @returns The merged value.
+     */
+    private applyReducer;
+    /**
+     * Construct an empty {@link MemoryView} used during state initialisation.
+     */
+    private emptyMemoryView;
+    /**
+     * Construct a zeroed {@link DiagnosticsView} used during state initialisation.
+     */
+    private emptyDiagnostics;
+}
+//# sourceMappingURL=StateManager.d.ts.map

package/dist/orchestration/runtime/StateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateManager.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/StateManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,aAAa,EAGb,UAAU,EAGX,MAAM,gBAAgB,CAAC;AAMxB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IAMX,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALrC;;;;OAIG;gBAC0B,QAAQ,EAAE,aAAa;IAMpD;;;;;;;;OAQG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU;IAatC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU;IAmB5E;;;;;;;;;;OAUG;IACH,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU;IAO9E;;;;;;;;OAQG;IACH,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU;IAS9D;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,UAAU;IAyBpF;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAwDpB;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAYzB"}