@substrate-ai/factory 0.19.54

package/dist/handlers/join-policy.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Join policy types, pure evaluator, and branch cancellation manager
+ * for parallel node fan-out/fan-in coordination.
+ *
+ * Design constraints:
+ *   - Zero external package imports (pure TypeScript/built-ins only)
+ *   - `evaluateJoinPolicy` is a pure synchronous function (no I/O, no side effects)
+ *   - `BranchCancellationManager` uses the globally-available AbortController (Node 18+)
+ *
+ * Story 50-3 (AC6).
+ */
+/**
+ * The coordination strategy used by a parallel node's fan-in stage.
+ *
+ * - `wait_all`      — all branches must complete before the parallel node resolves
+ * - `first_success` — resolve as soon as the first branch succeeds; cancel the rest
+ * - `quorum`        — resolve after `quorum_size` branches succeed; cancel the rest
+ */
+export type JoinPolicy = 'wait_all' | 'first_success' | 'quorum';
+/**
+ * The result record produced when a single branch finishes execution.
+ */
+export interface BranchResult {
+    /** Zero-based index of the branch within the parallel node's fan-out set. */
+    index: number;
+    /** Terminal status for this branch. */
+    outcome: 'SUCCESS' | 'FAIL' | 'CANCELLED';
+    /**
+     * Shallow snapshot of the branch's context values at completion time.
+     * Omitted for CANCELLED branches that were aborted before producing output.
+     */
+    contextSnapshot?: Record<string, unknown>;
+    /** Human-readable error string when `outcome === 'FAIL'`. */
+    error?: string;
+}
+/**
+ * Configuration parsed from a parallel node's DOT attributes.
+ */
+export interface JoinPolicyConfig {
+    /** The coordination strategy to apply when fan-in branches complete. */
+    policy: JoinPolicy;
+    /**
+     * Minimum number of successful branches required before fan-in resolves.
+     * Required when `policy === 'quorum'`; ignored for other policies.
+     */
+    quorum_size?: number;
+    /**
+     * How long (ms) to wait for in-flight branches to clean up after cancellation.
+     * Defaults to 5000 ms when omitted.
+     */
+    cancel_drain_timeout_ms?: number;
+}
+/**
+ * Discriminated union returned by `evaluateJoinPolicy` after each branch completes.
+ *
+ * - `continue` — the join condition is satisfied; proceed to fan-in output
+ * - `wait`     — the join condition is not yet met; wait for the next branch
+ * - `fail`     — the join condition can never be met; abort the parallel node
+ */
+export type JoinDecision = {
+    action: 'continue';
+    results: BranchResult[];
+} | {
+    action: 'wait';
+} | {
+    action: 'fail';
+    reason: string;
+};
+/**
+ * Pure synchronous function that decides what the parallel handler should do
+ * after a set of branches has completed.
+ *
+ * Called incrementally after each branch finishes: pass the full `completed`
+ * array (including all branches resolved so far) and the `total` branch count.
+ *
+ * @param config    - Join policy configuration parsed from the parallel node.
+ * @param completed - All branch results collected so far (any order).
+ * @param total     - Total number of branches in the fan-out set.
+ * @returns A `JoinDecision` indicating whether to continue, wait, or fail.
+ */
+export declare function evaluateJoinPolicy(config: JoinPolicyConfig, completed: BranchResult[], total: number): JoinDecision;
+/**
+ * Manages one `AbortController` per branch in a parallel fan-out execution.
+ *
+ * Typical usage:
+ *   1. Construct with the total branch count.
+ *   2. Pass `getSignal(i)` to the i-th branch executor.
+ *   3. After the join condition is met, call `cancelRemaining(completedSet)`.
+ *   4. Await `drainAsync(timeoutMs)` to give cancelled branches time to clean up.
+ */
+export declare class BranchCancellationManager {
+    private readonly controllers;
+    /**
+     * @param branchCount - Total number of branches; allocates one AbortController per branch.
+     */
+    constructor(branchCount: number);
+    /**
+     * Return the AbortSignal for the branch at the given zero-based index.
+     * The signal is not yet aborted; it becomes aborted when `cancelRemaining` includes the index.
+     */
+    getSignal(index: number): AbortSignal;
+    /**
+     * Abort all branches whose index is NOT in `completedIndices`.
+     * Branches that have already completed are not re-aborted.
+     *
+     * @param completedIndices - Set of branch indices that finished successfully/naturally.
+     */
+    cancelRemaining(completedIndices: Set<number>): void;
+    /**
+     * Wait `timeoutMs` milliseconds for in-flight branches to honour their AbortSignals
+     * and finish any cleanup work before the parallel handler resolves.
+     *
+     * @param timeoutMs - Drain window in milliseconds (default 5000).
+     */
+    drainAsync(timeoutMs: number): Promise<void>;
+}
+//# sourceMappingURL=join-policy.d.ts.map

package/dist/handlers/join-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-policy.d.ts","sourceRoot":"","sources":["../../src/handlers/join-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,eAAe,GAAG,QAAQ,CAAA;AAMhE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,OAAO,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,CAAA;IACzC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,MAAM,EAAE,UAAU,CAAA;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAA;CACjC;AAMD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAMtC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,YAAY,EAAE,EACzB,KAAK,EAAE,MAAM,GACZ,YAAY,CAiDd;AAMD;;;;;;;;GAQG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAE/C;;OAEG;gBACS,WAAW,EAAE,MAAM;IAI/B;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAQrC;;;;;OAKG;IACH,eAAe,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAQpD;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnD"}

package/dist/handlers/join-policy.js

@@ -0,0 +1,129 @@
+/**
+ * Join policy types, pure evaluator, and branch cancellation manager
+ * for parallel node fan-out/fan-in coordination.
+ *
+ * Design constraints:
+ *   - Zero external package imports (pure TypeScript/built-ins only)
+ *   - `evaluateJoinPolicy` is a pure synchronous function (no I/O, no side effects)
+ *   - `BranchCancellationManager` uses the globally-available AbortController (Node 18+)
+ *
+ * Story 50-3 (AC6).
+ */
+// ---------------------------------------------------------------------------
+// evaluateJoinPolicy
+// ---------------------------------------------------------------------------
+/**
+ * Pure synchronous function that decides what the parallel handler should do
+ * after a set of branches has completed.
+ *
+ * Called incrementally after each branch finishes: pass the full `completed`
+ * array (including all branches resolved so far) and the `total` branch count.
+ *
+ * @param config    - Join policy configuration parsed from the parallel node.
+ * @param completed - All branch results collected so far (any order).
+ * @param total     - Total number of branches in the fan-out set.
+ * @returns A `JoinDecision` indicating whether to continue, wait, or fail.
+ */
+export function evaluateJoinPolicy(config, completed, total) {
+    const successes = completed.filter(r => r.outcome === 'SUCCESS');
+    const failures = completed.filter(r => r.outcome === 'FAIL');
+    switch (config.policy) {
+        case 'wait_all': {
+            if (completed.length < total)
+                return { action: 'wait' };
+            return { action: 'continue', results: completed };
+        }
+        case 'first_success': {
+            // Any success → resolve immediately
+            if (successes.length >= 1)
+                return { action: 'continue', results: completed };
+            // All non-CANCELLED slots have completed with FAIL (or total === 0)
+            if (completed.length >= total) {
+                return {
+                    action: 'fail',
+                    reason: `first_success: all ${total} branches failed`,
+                };
+            }
+            return { action: 'wait' };
+        }
+        case 'quorum': {
+            const needed = config.quorum_size ?? 1;
+            // Guard against nonsensical quorum_size values
+            if (needed <= 0) {
+                return { action: 'fail', reason: 'quorum_size must be >= 1' };
+            }
+            // Quorum met
+            if (successes.length >= needed)
+                return { action: 'continue', results: completed };
+            // Can we still reach quorum?
+            const remaining = total - completed.length;
+            if (successes.length + remaining < needed) {
+                return {
+                    action: 'fail',
+                    reason: `quorum unreachable: ${failures.length} failed, needed ${needed} of ${total}`,
+                };
+            }
+            return { action: 'wait' };
+        }
+        default: {
+            // TypeScript exhaustiveness guard
+            const _exhaustive = config.policy;
+            return { action: 'fail', reason: `unknown join policy: ${String(_exhaustive)}` };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// BranchCancellationManager
+// ---------------------------------------------------------------------------
+/**
+ * Manages one `AbortController` per branch in a parallel fan-out execution.
+ *
+ * Typical usage:
+ *   1. Construct with the total branch count.
+ *   2. Pass `getSignal(i)` to the i-th branch executor.
+ *   3. After the join condition is met, call `cancelRemaining(completedSet)`.
+ *   4. Await `drainAsync(timeoutMs)` to give cancelled branches time to clean up.
+ */
+export class BranchCancellationManager {
+    controllers;
+    /**
+     * @param branchCount - Total number of branches; allocates one AbortController per branch.
+     */
+    constructor(branchCount) {
+        this.controllers = Array.from({ length: branchCount }, () => new AbortController());
+    }
+    /**
+     * Return the AbortSignal for the branch at the given zero-based index.
+     * The signal is not yet aborted; it becomes aborted when `cancelRemaining` includes the index.
+     */
+    getSignal(index) {
+        const ctrl = this.controllers[index];
+        if (ctrl === undefined) {
+            throw new RangeError(`Branch index ${index} is out of range (branchCount=${this.controllers.length})`);
+        }
+        return ctrl.signal;
+    }
+    /**
+     * Abort all branches whose index is NOT in `completedIndices`.
+     * Branches that have already completed are not re-aborted.
+     *
+     * @param completedIndices - Set of branch indices that finished successfully/naturally.
+     */
+    cancelRemaining(completedIndices) {
+        this.controllers.forEach((ctrl, i) => {
+            if (!completedIndices.has(i)) {
+                ctrl.abort();
+            }
+        });
+    }
+    /**
+     * Wait `timeoutMs` milliseconds for in-flight branches to honour their AbortSignals
+     * and finish any cleanup work before the parallel handler resolves.
+     *
+     * @param timeoutMs - Drain window in milliseconds (default 5000).
+     */
+    async drainAsync(timeoutMs) {
+        await new Promise(resolve => setTimeout(resolve, timeoutMs));
+    }
+}
+//# sourceMappingURL=join-policy.js.map

package/dist/handlers/join-policy.js.map

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

package/dist/handlers/manager-loop.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Manager Loop handler — supervises and repeatedly executes a body subgraph,
+ * implementing autonomous refinement cycles with configurable stop conditions
+ * and stall-recovery steering.
+ *
+ * Story 50-8.
+ *
+ * Reads:  `node.attrs['graph_file']`   — path to the body .dot file
+ * Reads:  `node.attrs['max_cycles']`   — maximum number of loop iterations (default 10)
+ * Reads:  `node.attrs['stop_condition']` — context key or `llm:` prefixed question
+ * Writes: `manager_loop.cycle`          — current 1-based cycle number
+ * Writes: `manager_loop.cycles_completed` — count of completed cycles
+ * Writes: `manager_loop.last_outcome`  — body executor outcome status
+ * Writes: `manager_loop.stop_reason`   — "max_cycles" or "stop_condition"
+ * Writes: `manager_loop.steering.mode`  — "normal" or "recovery"
+ * Writes: `manager_loop.steering.hints` — hint strings for stall recovery
+ */
+import type { NodeHandler, IHandlerRegistry } from './types.js';
+export interface ManagerLoopHandlerOptions {
+    /** Registry used to resolve node handlers inside the body graph each cycle. */
+    handlerRegistry: IHandlerRegistry;
+    /**
+     * Injectable LLM call function for `llm:` prefix stop conditions.
+     * When absent, LLM stop conditions always evaluate to `false`.
+     */
+    llmCall?: (prompt: string) => Promise<string>;
+    /** Base directory for resolving relative graph_file paths. Default: process.cwd() */
+    baseDir?: string;
+    /**
+     * Injectable file loader for testability.
+     * Defaults to `(fp) => readFile(fp, 'utf-8')`.
+     */
+    graphFileLoader?: (filePath: string) => Promise<string>;
+    /**
+     * Root directory for body executor checkpoint/log files.
+     * Defaults to `os.tmpdir()`.
+     */
+    logsRoot?: string;
+    /**
+     * Number of consecutive non-SUCCESS cycles before steering is injected.
+     * Default: 2.
+     */
+    maxStallCycles?: number;
+}
+/**
+ * Factory function that creates a handler for `type="stack.manager_loop"` nodes.
+ *
+ * Each invocation loads the body graph once, then executes it in a loop for up
+ * to `max_cycles` cycles (default 10). Stop conditions (context key or LLM-based)
+ * allow early exit. Stall detection injects recovery steering after consecutive
+ * non-SUCCESS body executions.
+ */
+export declare function createManagerLoopHandler(options: ManagerLoopHandlerOptions): NodeHandler;
+//# sourceMappingURL=manager-loop.d.ts.map

package/dist/handlers/manager-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-loop.d.ts","sourceRoot":"","sources":["../../src/handlers/manager-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAO/D,MAAM,WAAW,yBAAyB;IACxC,+EAA+E;IAC/E,eAAe,EAAE,gBAAgB,CAAA;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7C,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACvD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAMD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,WAAW,CAuJxF"}

package/dist/handlers/manager-loop.js

@@ -0,0 +1,177 @@
+/**
+ * Manager Loop handler — supervises and repeatedly executes a body subgraph,
+ * implementing autonomous refinement cycles with configurable stop conditions
+ * and stall-recovery steering.
+ *
+ * Story 50-8.
+ *
+ * Reads:  `node.attrs['graph_file']`   — path to the body .dot file
+ * Reads:  `node.attrs['max_cycles']`   — maximum number of loop iterations (default 10)
+ * Reads:  `node.attrs['stop_condition']` — context key or `llm:` prefixed question
+ * Writes: `manager_loop.cycle`          — current 1-based cycle number
+ * Writes: `manager_loop.cycles_completed` — count of completed cycles
+ * Writes: `manager_loop.last_outcome`  — body executor outcome status
+ * Writes: `manager_loop.stop_reason`   — "max_cycles" or "stop_condition"
+ * Writes: `manager_loop.steering.mode`  — "normal" or "recovery"
+ * Writes: `manager_loop.steering.hints` — hint strings for stall recovery
+ */
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { parseGraph } from '../graph/parser.js';
+import { createGraphExecutor } from '../graph/executor.js';
+import { createValidator } from '../graph/validator.js';
+import { isLlmCondition, evaluateLlmCondition, extractLlmQuestion } from '../graph/llm-evaluator.js';
+// ---------------------------------------------------------------------------
+// createManagerLoopHandler
+// ---------------------------------------------------------------------------
+/**
+ * Factory function that creates a handler for `type="stack.manager_loop"` nodes.
+ *
+ * Each invocation loads the body graph once, then executes it in a loop for up
+ * to `max_cycles` cycles (default 10). Stop conditions (context key or LLM-based)
+ * allow early exit. Stall detection injects recovery steering after consecutive
+ * non-SUCCESS body executions.
+ */
+export function createManagerLoopHandler(options) {
+    return async (node, context, _graph) => {
+        // -----------------------------------------------------------------------
+        // Step 1: Validate graph_file attribute
+        // -----------------------------------------------------------------------
+        const graphFile = node.attrs?.['graph_file'];
+        if (!graphFile) {
+            return {
+                status: 'FAILURE',
+                failureReason: `Manager loop node "${node.id}" is missing required attribute graph_file`,
+            };
+        }
+        // -----------------------------------------------------------------------
+        // Step 2: Parse max_cycles (default 10, NaN → 10, clamp to ≥1)
+        // -----------------------------------------------------------------------
+        const rawMaxCycles = node.attrs?.['max_cycles'];
+        let maxCycles = 10;
+        if (rawMaxCycles !== undefined && rawMaxCycles !== '') {
+            const parsed = parseInt(rawMaxCycles, 10);
+            maxCycles = isNaN(parsed) ? 10 : Math.max(1, parsed);
+        }
+        // -----------------------------------------------------------------------
+        // Step 3: Resolve body graph file path
+        // -----------------------------------------------------------------------
+        const filePath = path.isAbsolute(graphFile)
+            ? graphFile
+            : path.join(options.baseDir ?? process.cwd(), graphFile);
+        // -----------------------------------------------------------------------
+        // Step 4: Load body graph ONCE (injectable loader for testability)
+        // -----------------------------------------------------------------------
+        const loader = options.graphFileLoader ?? ((fp) => readFile(fp, 'utf-8'));
+        let dotSource;
+        try {
+            dotSource = await loader(filePath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'FAILURE',
+                failureReason: `Manager loop node "${node.id}": failed to load "${filePath}": ${msg}`,
+            };
+        }
+        // -----------------------------------------------------------------------
+        // Step 5: Parse body graph
+        // -----------------------------------------------------------------------
+        let bodyGraph;
+        try {
+            bodyGraph = parseGraph(dotSource);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'FAILURE',
+                failureReason: `Manager loop node "${node.id}": failed to parse "${filePath}": ${msg}`,
+            };
+        }
+        // -----------------------------------------------------------------------
+        // Step 6: Validate body graph
+        // -----------------------------------------------------------------------
+        try {
+            createValidator().validateOrRaise(bodyGraph);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'FAILURE',
+                failureReason: `Manager loop node "${node.id}": validation failed for "${filePath}": ${msg}`,
+            };
+        }
+        // -----------------------------------------------------------------------
+        // Step 7: Read stop condition attribute
+        // -----------------------------------------------------------------------
+        const stopCondition = node.attrs?.['stop_condition'];
+        // -----------------------------------------------------------------------
+        // Step 8: Main cycle loop
+        // -----------------------------------------------------------------------
+        let consecutiveFailures = 0;
+        for (let cycle = 1; cycle <= maxCycles; cycle++) {
+            // 8.1: Update current cycle number
+            context.set('manager_loop.cycle', cycle);
+            // 8.2: Build body executor config (no checkpointPath — always fresh)
+            const bodyConfig = {
+                runId: randomUUID(),
+                logsRoot: options.logsRoot ?? tmpdir(),
+                handlerRegistry: options.handlerRegistry,
+                initialContext: context.snapshot(),
+            };
+            // 8.3: Execute body graph
+            const bodyOutcome = await createGraphExecutor().run(bodyGraph, bodyConfig);
+            // 8.4: Merge body context updates into parent
+            if (bodyOutcome.contextUpdates) {
+                context.applyUpdates(bodyOutcome.contextUpdates);
+            }
+            // 8.5: Update telemetry
+            context.set('manager_loop.cycles_completed', cycle);
+            context.set('manager_loop.last_outcome', bodyOutcome.status);
+            // 8.6: Stall detection (before stop condition evaluation)
+            if (bodyOutcome.status === 'SUCCESS') {
+                consecutiveFailures = 0;
+                context.set('manager_loop.steering.mode', 'normal');
+                context.set('manager_loop.steering.hints', []);
+            }
+            else {
+                consecutiveFailures++;
+                if (consecutiveFailures >= (options.maxStallCycles ?? 2)) {
+                    context.set('manager_loop.steering.mode', 'recovery');
+                    context.set('manager_loop.steering.hints', [
+                        `Previous ${consecutiveFailures} attempts returned ${bodyOutcome.status}. Consider a different strategy.`,
+                        'Review context state and adjust approach before retrying.',
+                    ]);
+                }
+            }
+            // 8.7: Stop condition evaluation (after stall detection)
+            if (stopCondition) {
+                let shouldStop = false;
+                if (isLlmCondition(stopCondition)) {
+                    // LLM-evaluated stop condition
+                    if (options.llmCall !== undefined) {
+                        const question = extractLlmQuestion(stopCondition);
+                        shouldStop = await evaluateLlmCondition(question, context.snapshot(), options.llmCall);
+                    }
+                    // If no llmCall provided, always false — loop continues
+                }
+                else {
+                    // Context key truthiness
+                    shouldStop = Boolean(context.get(stopCondition));
+                }
+                if (shouldStop) {
+                    context.set('manager_loop.stop_reason', 'stop_condition');
+                    return { status: 'SUCCESS' };
+                }
+            }
+        }
+        // -----------------------------------------------------------------------
+        // Step 9: Max cycles reached
+        // -----------------------------------------------------------------------
+        context.set('manager_loop.stop_reason', 'max_cycles');
+        return { status: 'SUCCESS' };
+    };
+}
+//# sourceMappingURL=manager-loop.js.map

package/dist/handlers/manager-loop.js.map

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

package/dist/handlers/parallel.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Parallel handler — fan-out with isolated branch contexts and configurable
+ * join policies.
+ *
+ * Executes all outgoing branches of a `parallel` node (shape=component)
+ * concurrently, each in its own cloned context so mutations never leak
+ * between branches or back to the parent context.
+ *
+ * Join policies (story 50-3, read from `node.joinPolicy` or `node.attrs`):
+ *   - `wait_all` (default) — all branches complete before fan-in
+ *   - `first_success`      — fan-in resolves on first SUCCESS; rest cancelled
+ *   - `quorum`             — fan-in resolves after `quorum_size` SUCCESSes; rest cancelled
+ *
+ * Context outputs:
+ *   - `parallel.results`        — `BranchResult[]` for every branch
+ *   - `parallel.winner_index`   — winning branch index (first_success policy)
+ *   - `parallel.quorum_reached` — number of successes (quorum policy)
+ *   - `parallel.join_error`     — failure reason when join condition cannot be met
+ *
+ * Story 50-1 (AC1–AC7), extended by Story 50-3 (AC1–AC5).
+ */
+import type { NodeHandler, ParallelHandlerOptions } from './types.js';
+/**
+ * Create a `parallel` node handler that fans out to all outgoing branch nodes
+ * concurrently, applies a configurable join policy, and writes results to context.
+ *
+ * @param options.handlerRegistry  Registry used to resolve each branch node's
+ *   handler at invocation time.
+ */
+export declare function createParallelHandler(options: ParallelHandlerOptions): NodeHandler;
+//# sourceMappingURL=parallel.d.ts.map

package/dist/handlers/parallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/handlers/parallel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAqB,MAAM,YAAY,CAAA;AAyLxF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,WAAW,CAwNlF"}