@substrate-ai/factory 0.19.54

package/dist/handlers/parallel.js

@@ -0,0 +1,362 @@
+/**
+ * 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 { evaluateJoinPolicy, BranchCancellationManager, } from './join-policy.js';
+// ---------------------------------------------------------------------------
+// Branch outcome → StageStatus conversion helper (story 50-9)
+// ---------------------------------------------------------------------------
+/**
+ * Maps a BranchResult outcome string to a StageStatus for event payloads.
+ *
+ * BranchResult.outcome: 'SUCCESS' | 'FAIL' | 'CANCELLED'
+ * StageStatus:          'SUCCESS' | 'FAIL' | 'PARTIAL_SUCCESS' | 'RETRY' | 'SKIPPED'
+ *
+ * Mapping:
+ *   'SUCCESS'   → 'SUCCESS'
+ *   'CANCELLED' → 'SKIPPED'
+ *   'FAIL'      → 'FAIL'
+ */
+function branchOutcomeToStatus(outcome) {
+    if (outcome === 'SUCCESS')
+        return 'SUCCESS';
+    if (outcome === 'CANCELLED')
+        return 'SKIPPED';
+    return 'FAIL';
+}
+// ---------------------------------------------------------------------------
+// Fan-in bridge helper (story 50-3 fix)
+// ---------------------------------------------------------------------------
+/**
+ * Enrich a join-policy `BranchResult` with fan-in-compatible fields so that
+ * `fan-in.ts` can read `parallel.results` without type-shape mismatch.
+ *
+ * The returned object is a superset of `BranchResult` — it preserves every
+ * original field (index, outcome, contextSnapshot, error) AND adds the fields
+ * that `fan-in.ts` requires (branch_id, status, context_updates, failure_reason).
+ *
+ * Mapping:
+ *   index          → branch_id        (same numeric value)
+ *   outcome        → status           ('SUCCESS' | 'FAIL'/'CANCELLED' → 'SUCCESS' | 'FAILURE')
+ *   contextSnapshot → context_updates  (shallow context snapshot)
+ *   error          → failure_reason   (human-readable failure description)
+ */
+function toBridgeBranchResult(result) {
+    return {
+        ...result,
+        branch_id: result.index,
+        status: result.outcome === 'SUCCESS' ? 'SUCCESS' : 'FAILURE',
+        context_updates: result.contextSnapshot,
+        failure_reason: result.error,
+    };
+}
+// ---------------------------------------------------------------------------
+// Bounded concurrency helper (AC2 — story 50-1)
+// ---------------------------------------------------------------------------
+/**
+ * Run an array of async task factories with at most `limit` executing
+ * concurrently at any point in time, preserving result order.
+ */
+async function runWithConcurrencyLimit(tasks, limit) {
+    const results = new Array(tasks.length);
+    const executing = new Set();
+    for (let i = 0; i < tasks.length; i++) {
+        const idx = i;
+        const p = tasks[idx]()
+            .then((r) => {
+            results[idx] = r;
+        })
+            .finally(() => {
+            executing.delete(p);
+        });
+        executing.add(p);
+        if (executing.size >= limit)
+            await Promise.race(executing);
+    }
+    await Promise.all(executing);
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Join policy parsing helpers (story 50-3)
+// ---------------------------------------------------------------------------
+function parseJoinPolicyConfig(node) {
+    const policyRaw = node.attrs?.['join_policy'] ?? node.joinPolicy ?? 'wait_all';
+    const policy = policyRaw === 'first_success' || policyRaw === 'quorum' ? policyRaw : 'wait_all';
+    const quorumSizeRaw = node.attrs?.['quorum_size'];
+    const quorum_size = quorumSizeRaw !== undefined ? parseInt(quorumSizeRaw, 10) : undefined;
+    const drainRaw = node.attrs?.['cancel_drain_timeout_ms'];
+    const cancel_drain_timeout_ms = drainRaw !== undefined ? parseInt(drainRaw, 10) : undefined;
+    return {
+        policy,
+        ...(quorum_size !== undefined && { quorum_size }),
+        ...(cancel_drain_timeout_ms !== undefined && { cancel_drain_timeout_ms }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Branch execution helper (shared by all join policies)
+// ---------------------------------------------------------------------------
+/**
+ * Build an async task that executes a single branch node and returns a
+ * `BranchResult`. Isolation is guaranteed via `context.clone()`.
+ */
+function makeBranchTask(edge, index, signal, context, graph, options) {
+    return async () => {
+        if (signal.aborted) {
+            return { index, outcome: 'CANCELLED' };
+        }
+        const branchNode = graph.nodes.get(edge.toNode);
+        if (!branchNode) {
+            return {
+                index,
+                outcome: 'FAIL',
+                error: `Branch node "${edge.toNode}" not found in graph`,
+            };
+        }
+        // AC3 (story 50-1): each branch gets its own independent context copy
+        const branchCtx = context.clone();
+        branchCtx.set('_branch.abort_signal', signal);
+        branchCtx.set('_branch.index', index);
+        const handler = options.handlerRegistry.resolve(branchNode);
+        let branchOutcome;
+        try {
+            branchOutcome = await handler(branchNode, branchCtx, graph);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                index,
+                outcome: 'FAIL',
+                error: msg,
+                contextSnapshot: branchCtx.snapshot(),
+            };
+        }
+        if (signal.aborted) {
+            return { index, outcome: 'CANCELLED', contextSnapshot: branchCtx.snapshot() };
+        }
+        const isSuccess = branchOutcome.status === 'SUCCESS' || branchOutcome.status === 'PARTIAL_SUCCESS';
+        const result = {
+            index,
+            outcome: isSuccess ? 'SUCCESS' : 'FAIL',
+            contextSnapshot: branchCtx.snapshot(),
+        };
+        if (!isSuccess) {
+            const reason = branchOutcome.failureReason;
+            if (reason !== undefined)
+                result.error = reason;
+        }
+        return result;
+    };
+}
+// ---------------------------------------------------------------------------
+// Parallel handler factory
+// ---------------------------------------------------------------------------
+/**
+ * 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 function createParallelHandler(options) {
+    return async (node, context, graph) => {
+        const branchEdges = graph.outgoingEdges(node.id);
+        const branchCount = branchEdges.length;
+        if (branchCount === 0) {
+            context.set('parallel.results', []);
+            return { status: 'SUCCESS' };
+        }
+        const config = parseJoinPolicyConfig(node);
+        const maxParallel = node.maxParallel ?? 0;
+        const drainMs = config.cancel_drain_timeout_ms ?? 5000;
+        const cancellationManager = new BranchCancellationManager(branchCount);
+        // Read runId from context (written by executor, story 50-9 AC4)
+        const runId = context.getString('__runId', 'unknown');
+        // Emit graph:parallel-started once before any branch launches (story 50-9 AC1)
+        options.eventBus?.emit('graph:parallel-started', {
+            runId,
+            nodeId: node.id,
+            branchCount,
+            maxParallel: maxParallel > 0 ? maxParallel : branchCount,
+            policy: config.policy,
+        });
+        // -----------------------------------------------------------------------
+        // wait_all — all branches must complete (supports maxParallel semaphore)
+        // -----------------------------------------------------------------------
+        if (config.policy === 'wait_all') {
+            const tasks = branchEdges.map((edge, index) => {
+                const baseTask = makeBranchTask(edge, index, cancellationManager.getSignal(index), context, graph, options);
+                // Wrap with event emission (story 50-9 AC1)
+                return async () => {
+                    options.eventBus?.emit('graph:parallel-branch-started', {
+                        runId,
+                        nodeId: node.id,
+                        branchIndex: index,
+                    });
+                    const branchStart = Date.now();
+                    const result = await baseTask();
+                    const durationMs = Date.now() - branchStart;
+                    options.eventBus?.emit('graph:parallel-branch-completed', {
+                        runId,
+                        nodeId: node.id,
+                        branchIndex: index,
+                        status: branchOutcomeToStatus(result.outcome),
+                        durationMs,
+                    });
+                    return result;
+                };
+            });
+            const results = maxParallel > 0
+                ? await runWithConcurrencyLimit(tasks, maxParallel)
+                : await Promise.all(tasks.map((t) => t()));
+            context.set('parallel.results', results.map(toBridgeBranchResult));
+            const completedCount = results.filter(r => r.outcome === 'SUCCESS').length;
+            const cancelledCount = results.filter(r => r.outcome === 'CANCELLED').length;
+            options.eventBus?.emit('graph:parallel-completed', {
+                runId,
+                nodeId: node.id,
+                completedCount,
+                cancelledCount,
+                policy: config.policy,
+            });
+            return { status: 'SUCCESS' };
+        }
+        // -----------------------------------------------------------------------
+        // first_success / quorum — incremental fan-out with early termination
+        // -----------------------------------------------------------------------
+        const completed = [];
+        const completedIndices = new Set();
+        const pendingEvents = [];
+        const waiters = [];
+        function push(event) {
+            const w = waiters.shift();
+            if (w !== undefined) {
+                w(event);
+            }
+            else {
+                pendingEvents.push(event);
+            }
+        }
+        function waitForNext() {
+            return new Promise(resolve => {
+                const e = pendingEvents.shift();
+                if (e !== undefined) {
+                    resolve(e);
+                }
+                else {
+                    waiters.push(resolve);
+                }
+            });
+        }
+        // Launch all branches immediately, emitting branch-started and branch-completed (story 50-9)
+        const branchStarts = new Map();
+        const activeTasks = branchEdges.map((edge, index) => {
+            const task = makeBranchTask(edge, index, cancellationManager.getSignal(index), context, graph, options);
+            options.eventBus?.emit('graph:parallel-branch-started', {
+                runId,
+                nodeId: node.id,
+                branchIndex: index,
+            });
+            branchStarts.set(index, Date.now());
+            return task().then(result => {
+                const branchStart = branchStarts.get(index) ?? Date.now();
+                const durationMs = Date.now() - branchStart;
+                options.eventBus?.emit('graph:parallel-branch-completed', {
+                    runId,
+                    nodeId: node.id,
+                    branchIndex: index,
+                    status: branchOutcomeToStatus(result.outcome),
+                    durationMs,
+                });
+                push({ result });
+            });
+        });
+        let joinOutcome = 'SUCCESS';
+        let settled = false;
+        let joinErrorMsg;
+        for (let i = 0; i < branchCount; i++) {
+            const { result } = await waitForNext();
+            if (completedIndices.has(result.index))
+                continue;
+            completed.push(result);
+            completedIndices.add(result.index);
+            const decision = evaluateJoinPolicy(config, completed, branchCount);
+            if (decision.action === 'wait')
+                continue;
+            settled = true;
+            joinOutcome = decision.action === 'continue' ? 'SUCCESS' : 'FAIL';
+            if (decision.action === 'fail')
+                joinErrorMsg = decision.reason;
+            const uncancelledCount = branchCount - completedIndices.size;
+            cancellationManager.cancelRemaining(completedIndices);
+            if (uncancelledCount > 0) {
+                await cancellationManager.drainAsync(drainMs);
+                // Collect results that arrived during drain window
+                while (pendingEvents.length > 0) {
+                    const e = pendingEvents.shift();
+                    if (e !== undefined && !completedIndices.has(e.result.index)) {
+                        completed.push(e.result);
+                        completedIndices.add(e.result.index);
+                    }
+                }
+                // Synthetic CANCELLED for branches still outstanding after drain
+                for (let j = 0; j < branchCount; j++) {
+                    if (!completedIndices.has(j)) {
+                        completed.push({ index: j, outcome: 'CANCELLED' });
+                        completedIndices.add(j);
+                    }
+                }
+            }
+            context.set('parallel.results', completed.map(toBridgeBranchResult));
+            if (decision.action === 'continue') {
+                if (config.policy === 'first_success') {
+                    const winner = completed.find(r => r.outcome === 'SUCCESS');
+                    if (winner !== undefined) {
+                        context.set('parallel.winner_index', winner.index);
+                    }
+                }
+                if (config.policy === 'quorum') {
+                    const successCount = completed.filter(r => r.outcome === 'SUCCESS').length;
+                    context.set('parallel.quorum_reached', successCount);
+                }
+            }
+            else {
+                context.set('parallel.join_error', joinErrorMsg ?? decision.reason);
+            }
+            break;
+        }
+        // Do not block on cancelled branches — fire and forget
+        void Promise.allSettled(activeTasks);
+        if (!settled) {
+            context.set('parallel.results', completed.map(toBridgeBranchResult));
+        }
+        // Emit graph:parallel-completed with final branch counts (story 50-9 AC1)
+        const finalCompletedCount = completed.filter(r => r.outcome === 'SUCCESS').length;
+        const finalCancelledCount = completed.filter(r => r.outcome === 'CANCELLED').length;
+        options.eventBus?.emit('graph:parallel-completed', {
+            runId,
+            nodeId: node.id,
+            completedCount: finalCompletedCount,
+            cancelledCount: finalCancelledCount,
+            policy: config.policy,
+        });
+        return { status: joinOutcome === 'SUCCESS' ? 'SUCCESS' : 'FAILURE' };
+    };
+}
+//# sourceMappingURL=parallel.js.map

package/dist/handlers/parallel.js.map

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

package/dist/handlers/registry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * HandlerRegistry — maps node types and shapes to handler functions.
+ *
+ * Resolution priority (3-step chain):
+ *   1. Explicit type: `node.type` is non-empty and a handler is registered for it
+ *   2. Shape-based: `node.shape` maps to a registered type via the shape map
+ *   3. Default: `_default` if set; throws otherwise
+ *
+ * Story 42-9.
+ */
+import type { GraphNode } from '../graph/types.js';
+import type { IHandlerRegistry, NodeHandler } from './types.js';
+import type { CodergenHandlerOptions } from './codergen-handler.js';
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+export declare class HandlerRegistry implements IHandlerRegistry {
+    /** Maps node type → handler function */
+    private _handlers;
+    /** Maps DOT shape name → canonical node type */
+    private _shapeMap;
+    /** Fallback handler when no type or shape match is found */
+    private _default;
+    /**
+     * Register a handler for the given node type.
+     * Overwrites if already registered.
+     */
+    register(type: string, handler: NodeHandler): void;
+    /**
+     * Register a shape → type mapping.
+     * Overwrites if already registered.
+     */
+    registerShape(shape: string, type: string): void;
+    /**
+     * Set the default handler used when no type or shape match is found.
+     */
+    setDefault(handler: NodeHandler): void;
+    /**
+     * Resolve the handler for the given node.
+     * Priority: explicit type → shape-based fallback → default → throw
+     */
+    resolve(node: GraphNode): NodeHandler;
+}
+/**
+ * Extended options for `createDefaultRegistry` — backward-compatible with `CodergenHandlerOptions`.
+ * Story 50-5 adds `baseDir` for resolving relative graph_file paths in subgraph nodes.
+ * Story 50-9 adds `eventBus` and `runId` forwarded to parallel and subgraph handler factories.
+ */
+export interface DefaultRegistryOptions extends CodergenHandlerOptions {
+    /** Base directory for resolving relative graph_file paths in subgraph nodes. Default: process.cwd() */
+    baseDir?: string;
+    /** Optional event bus forwarded to parallel and subgraph handler factories (story 50-9). */
+    eventBus?: TypedEventBus<FactoryEvents>;
+    /** Optional run identifier forwarded to parallel and subgraph handler factories (story 50-9). */
+    runId?: string;
+    /**
+     * Injectable LLM call for manager loop's llm:-prefixed stop conditions.
+     * Passed through to createManagerLoopHandler.
+     * Story 50-8.
+     */
+    llmCall?: (prompt: string) => Promise<string>;
+}
+/**
+ * Factory function that creates a `HandlerRegistry` pre-wired with:
+ * - `start`, `exit`, `conditional`, and `codergen` handlers
+ * - Shape mappings: `Mdiamond→start`, `Msquare→exit`, `diamond→conditional`, `box→codergen`
+ * - Default handler: codergen (catches all unrecognised type/shape combinations)
+ *
+ * Story 42-10 adds codergen as the explicit "codergen" type, as the handler for
+ * `shape=box` nodes, and as the registry-level default for any node that has no
+ * recognised type or shape mapping.
+ *
+ * Story 50-5 extends options to `DefaultRegistryOptions` and registers the `subgraph` type.
+ */
+export declare function createDefaultRegistry(options?: DefaultRegistryOptions): HandlerRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/handlers/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAcjD,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,wCAAwC;IACxC,OAAO,CAAC,SAAS,CAAiC;IAClD,gDAAgD;IAChD,OAAO,CAAC,SAAS,CAA4B;IAC7C,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAyB;IAEzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAIlD;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAItC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW;CA6BtC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB;IACpE,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACvC,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CA6CvF"}

package/dist/handlers/registry.js

@@ -0,0 +1,132 @@
+/**
+ * HandlerRegistry — maps node types and shapes to handler functions.
+ *
+ * Resolution priority (3-step chain):
+ *   1. Explicit type: `node.type` is non-empty and a handler is registered for it
+ *   2. Shape-based: `node.shape` maps to a registered type via the shape map
+ *   3. Default: `_default` if set; throws otherwise
+ *
+ * Story 42-9.
+ */
+import { startHandler } from './start.js';
+import { exitHandler } from './exit.js';
+import { conditionalHandler } from './conditional.js';
+import { createCodergenHandler } from './codergen-handler.js';
+import { createToolHandler } from './tool.js';
+import { createWaitHumanHandler } from './wait-human.js';
+import { createParallelHandler } from './parallel.js';
+import { createFanInHandler } from './fan-in.js';
+// Story 50-5: subgraph handler
+import { createSubgraphHandler } from './subgraph.js';
+// Story 50-8: manager loop handler
+import { createManagerLoopHandler } from './manager-loop.js';
+export class HandlerRegistry {
+    /** Maps node type → handler function */
+    _handlers = new Map();
+    /** Maps DOT shape name → canonical node type */
+    _shapeMap = new Map();
+    /** Fallback handler when no type or shape match is found */
+    _default;
+    /**
+     * Register a handler for the given node type.
+     * Overwrites if already registered.
+     */
+    register(type, handler) {
+        this._handlers.set(type, handler);
+    }
+    /**
+     * Register a shape → type mapping.
+     * Overwrites if already registered.
+     */
+    registerShape(shape, type) {
+        this._shapeMap.set(shape, type);
+    }
+    /**
+     * Set the default handler used when no type or shape match is found.
+     */
+    setDefault(handler) {
+        this._default = handler;
+    }
+    /**
+     * Resolve the handler for the given node.
+     * Priority: explicit type → shape-based fallback → default → throw
+     */
+    resolve(node) {
+        // Step 1: Explicit type match
+        if (node.type) {
+            const handler = this._handlers.get(node.type);
+            if (handler !== undefined) {
+                return handler;
+            }
+        }
+        // Step 2: Shape-based fallback
+        if (node.shape) {
+            const mappedType = this._shapeMap.get(node.shape);
+            if (mappedType !== undefined) {
+                const handler = this._handlers.get(mappedType);
+                if (handler !== undefined) {
+                    return handler;
+                }
+            }
+        }
+        // Step 3: Default handler
+        if (this._default !== undefined) {
+            return this._default;
+        }
+        throw new Error(`No handler for node "${node.id}" (type="${node.type}", shape="${node.shape}")`);
+    }
+}
+/**
+ * Factory function that creates a `HandlerRegistry` pre-wired with:
+ * - `start`, `exit`, `conditional`, and `codergen` handlers
+ * - Shape mappings: `Mdiamond→start`, `Msquare→exit`, `diamond→conditional`, `box→codergen`
+ * - Default handler: codergen (catches all unrecognised type/shape combinations)
+ *
+ * Story 42-10 adds codergen as the explicit "codergen" type, as the handler for
+ * `shape=box` nodes, and as the registry-level default for any node that has no
+ * recognised type or shape mapping.
+ *
+ * Story 50-5 extends options to `DefaultRegistryOptions` and registers the `subgraph` type.
+ */
+export function createDefaultRegistry(options) {
+    const registry = new HandlerRegistry();
+    // Register parallel handler first — safe because resolve() is only called at
+    // invocation time, not at registration time (story 50-1 Dev Notes).
+    registry.register('parallel', createParallelHandler({
+        handlerRegistry: registry,
+        ...(options?.eventBus !== undefined ? { eventBus: options.eventBus } : {}),
+        ...(options?.runId !== undefined ? { runId: options.runId } : {}),
+    }));
+    registry.registerShape('component', 'parallel');
+    // Register built-in type handlers
+    registry.register('start', startHandler);
+    registry.register('exit', exitHandler);
+    registry.register('conditional', conditionalHandler);
+    registry.register('codergen', createCodergenHandler(options));
+    registry.register('tool', createToolHandler());
+    registry.register('wait.human', createWaitHumanHandler());
+    registry.register('parallel.fan_in', createFanInHandler());
+    // Story 50-5: subgraph handler registration
+    registry.register('subgraph', createSubgraphHandler({
+        handlerRegistry: registry,
+        baseDir: options?.baseDir ?? process.cwd(),
+        ...(options?.eventBus !== undefined ? { eventBus: options.eventBus } : {}),
+        ...(options?.runId !== undefined ? { runId: options.runId } : {}),
+    }));
+    // Story 50-8: manager loop handler
+    registry.register('stack.manager_loop', createManagerLoopHandler({
+        handlerRegistry: registry,
+        baseDir: options?.baseDir ?? process.cwd(),
+        ...(options?.llmCall !== undefined ? { llmCall: options.llmCall } : {}),
+    }));
+    // Register DOT shape → canonical type mappings
+    registry.registerShape('Mdiamond', 'start');
+    registry.registerShape('Msquare', 'exit');
+    registry.registerShape('diamond', 'conditional');
+    registry.registerShape('box', 'codergen');
+    registry.registerShape('tripleoctagon', 'parallel.fan_in');
+    // Set codergen as default for nodes with no recognised type or shape
+    registry.setDefault(createCodergenHandler(options));
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

package/dist/handlers/registry.js.map

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

package/dist/handlers/start.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Handler for start nodes.
+ * No side effects — edge selection drives the next step.
+ *
+ * Story 42-9.
+ */
+import type { NodeHandler } from './types.js';
+/** Handler for start nodes; no side effects; edge selection drives next step. */
+export declare const startHandler: NodeHandler;
+//# sourceMappingURL=start.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/handlers/start.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,iFAAiF;AACjF,eAAO,MAAM,YAAY,EAAE,WAE1B,CAAA"}

package/dist/handlers/start.js

@@ -0,0 +1,11 @@
+/**
+ * Handler for start nodes.
+ * No side effects — edge selection drives the next step.
+ *
+ * Story 42-9.
+ */
+/** Handler for start nodes; no side effects; edge selection drives next step. */
+export const startHandler = async (_node, _context, _graph) => {
+    return { status: 'SUCCESS' };
+};
+//# sourceMappingURL=start.js.map

package/dist/handlers/start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.js","sourceRoot":"","sources":["../../src/handlers/start.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAgB,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE;IACzE,OAAO,EAAE,MAAM,EAAE,SAAkB,EAAE,CAAA;AACvC,CAAC,CAAA"}