@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/generator/{scope-function-generator.d.ts → node-arguments.d.ts}

@@ -1,4 +1,79 @@
+/**
+ * Node argument generation.
+ *
+ * buildNodeArgumentsWithContext resolves the argument list of a node call and
+ * decides its order: execute first, then every data input in declaration
+ * order, then one closure per scope, then the abort signal and runtime
+ * context the node asks for. Each step is delegated:
+ * - input-port-values: where a data input's value comes from
+ * - connection-reads: how a connected value (and the execute signal) is read
+ * - scope-closure / scoped-child: the closure a scoped port becomes
+ *
+ * A scope closure builds each child's arguments with
+ * buildNodeArgumentsWithContext again. The closure modules receive it as a
+ * parameter (generateScopeFunctionClosure passes it), so the recursion needs
+ * no import cycle.
+ */
 import type { TNodeTypeAST, TWorkflowAST, TNodeInstanceAST } from '../ast/index.js';
+export type TBuildNodeArgsOptions = {
+    node: TNodeTypeAST;
+    workflow: TWorkflowAST;
+    id: string;
+    lines: string[];
+    indent?: string;
+    getCall?: string;
+    isAsync?: boolean;
+    instanceParent?: string;
+    skipPorts?: Set<string>;
+    emitInputEvents?: boolean;
+    setCall?: string;
+    nodeTypeName?: string;
+    bundleMode?: boolean;
+    production?: boolean;
+    abortSignalExpression?: string;
+    runtimeContextExpression?: string;
+};
+/**
+ * Builds the argument list for a node function call by resolving input port values.
+ *
+ * This function is central to code generation - it determines where each input port
+ * gets its value from: connections, expressions, defaults, or execution strategies.
+ *
+ * ## Resolution Priority (per port):
+ * 1. **Skip Ports**: If port is in skipPorts set, use pre-declared variable
+ * 2. **Instance Expression**: Check instance.config.portConfigs for constant expressions
+ * 3. **Connection**: Get value from connected output port via ctx.getVariable()
+ * 4. **Node Type Expression**: Check nodeType.inputs[port].expression
+ * 5. **Default Value**: Use nodeType.inputs[port].default if available
+ * 6. **Undefined**: No value source found (may cause runtime error)
+ *
+ * ## Special Handling:
+ * - **execute port**: Always first, handles CONJUNCTION/DISJUNCTION strategies
+ * - **Scoped INPUT ports**: Skipped (they're return values from scope functions)
+ * - **STEP ports (onSuccess/onFailure)**: Use executionSignal config if present
+ * - **Scope functions**: Generated via generateScopeFunctionClosure() for FUNCTION ports
+ *
+ * ## STEP Port Execution Strategies:
+ * - **CONJUNCTION (AND)**: `execute = stepA && stepB && stepC`
+ * - **DISJUNCTION (OR)**: `execute = stepA || stepB || stepC`
+ * - **CUSTOM**: Uses executionSignal expression
+ *
+ * @param opts - Configuration object with node, workflow, and generation settings
+ * @param opts.node - The node type definition with input/output port specs
+ * @param opts.workflow - The workflow AST containing connections and instances
+ * @param opts.id - The node instance ID being generated
+ * @param opts.lines - Array to push generated code lines into
+ * @param opts.indent - Indentation prefix for generated lines (default: "    ")
+ * @param opts.getCall - Method to get variables (default: "await ctx.getVariable")
+ * @param opts.isAsync - Whether generating async code
+ * @param opts.instanceParent - Parent node ID if this node is in a scope
+ * @param opts.skipPorts - Ports to skip (already pre-handled)
+ * @param opts.emitInputEvents - Whether to emit VARIABLE_SET events for inputs
+ * @param opts.setCall - Method to set variables (default: "await ctx.setVariable")
+ * @param opts.nodeTypeName - Override for node type name in events
+ * @returns Array of argument expressions to pass to the node function
+ */
+export declare function buildNodeArgumentsWithContext(opts: TBuildNodeArgsOptions): string[];
 /**
  * Generate a scope function closure for a scoped port (e.g., forEach iteration callback).
  *
@@ -75,4 +150,4 @@ import type { TNodeTypeAST, TWorkflowAST, TNodeInstanceAST } from '../ast/index.
  * @returns Generated closure code string to be used as a function argument
  */
 export declare function generateScopeFunctionClosure(scopeName: string, parentNodeId: string, parentNodeType: TNodeTypeAST, workflow: TWorkflowAST, childInstances: TNodeInstanceAST[], isAsync: boolean, production: boolean): string;
-//# sourceMappingURL=scope-function-generator.d.ts.map
+//# sourceMappingURL=node-arguments.d.ts.map

package/dist/generator/node-invocation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @module generator/node-invocation
+ *
+ * The emitted text that calls a node and stores what it returned. The regular
+ * path, branching nodes, pull executors and scope children all run nodes, and
+ * each of them used to spell these lines out on its own. Every function here
+ * only pushes lines; the caller owns the surrounding `try` block and events.
+ */
+import type { TNodeTypeAST } from '../ast/types';
+/** One node invocation as the emitters see it. */
+export interface NodeInvocation {
+    nodeType: TNodeTypeAST;
+    instanceId: string;
+    /** The instance id as an identifier; `${safeId}Idx` holds the execution index. */
+    safeId: string;
+    /** The function the call names, also recorded as `nodeTypeName`. */
+    functionName: string;
+    /** The local that receives the call's result. */
+    resultVar: string;
+    /** Argument expressions, as buildNodeArgumentsWithContext returned them. */
+    args: string[];
+    /** The execution context variable (`ctx`, `scopedCtx`, ...). */
+    ctxVar: string;
+    /** The full prefix of every emitted line. */
+    indent: string;
+    lines: string[];
+}
+/**
+ * Emit the call for a durable gate or durable effect node and return true, or
+ * return false without emitting anything for any other node.
+ *
+ * @param gateResultType - The type the gate's result is cast to.
+ */
+export declare function emitDurableNodeCall(call: NodeInvocation, gateResultType: string): boolean;
+/**
+ * Emit the call for a node that is neither durable nor handled as an
+ * expression. A MAP_ITERATOR iterates inline with no user function; a workflow
+ * takes `(execute, params)` with its data inputs in one params object plus the
+ * recursion depth; anything else, scoped nodes included, takes positional
+ * arguments (the `_impl` signature in bundle mode).
+ *
+ * @param isAsync - Whether the scope function is awaited inside a MAP_ITERATOR loop.
+ * @param awaitKeyword - `await ` when the node function itself is async.
+ */
+export declare function emitPlainNodeCall(call: NodeInvocation, isAsync: boolean, awaitKeyword: string): void;
+/**
+ * Store each output port from the result object, including onSuccess and
+ * onFailure. Scoped output ports are skipped: they are parameters of the scope
+ * function, not return values.
+ *
+ * @param skip - Further ports to leave out.
+ */
+export declare function emitResultOutputs(call: NodeInvocation, setCall: string, skip?: (portName: string) => boolean): void;
+export interface NodeInvocationOptions {
+    setCall: string;
+    /** Whether the scope function is awaited inside a MAP_ITERATOR loop. */
+    isAsync: boolean;
+    /** `await ` when the node function itself is async. */
+    awaitKeyword: string;
+    /** The type a durable gate's result is cast to. */
+    gateResultType: string;
+    /**
+     * Emit a runtime throw for STUB nodes and an inline expression for
+     * COERCION nodes. Without it they are called like any other node.
+     */
+    inlineStubAndCoercion: boolean;
+}
+/**
+ * Emit a node's call and the storing of its outputs, for every node variant:
+ * durable gate or effect, stub and coercion (when asked), expression,
+ * MAP_ITERATOR, workflow, and positional calls.
+ */
+export declare function emitNodeInvocation(call: NodeInvocation, options: NodeInvocationOptions): void;
+//# sourceMappingURL=node-invocation.d.ts.map

package/dist/{node-types-generator.d.ts → generator/node-types-generator.d.ts}

@@ -1,4 +1,4 @@
-import type { TNodeTypeAST } from "./ast/types.js";
+import type { TNodeTypeAST } from "../ast/types";
 export interface TNodeTypePort {
     name: string;
     defaultLabel: string;
@@ -36,7 +36,7 @@ export interface TLocalFunctionNodeType {
     function: string;
     parameters: string[];
 }
-export declare class NodeTypesGenerator {
+declare class NodeTypesGenerator {
     generateNodeType(node: TNodeTypeAST, filePath: string, projectPath: string): TLocalFunctionNodeType;
     generateAllNodeTypes(nodes: TNodeTypeAST[], filePath: string, projectPath: string): TLocalFunctionNodeType[];
     generateNodeTypesModule(nodes: TNodeTypeAST[], filePath: string, projectPath: string): string;
@@ -46,4 +46,5 @@ export declare class NodeTypesGenerator {
     private determineSynchronicity;
 }
 export declare const nodeTypesGenerator: NodeTypesGenerator;
+export {};
 //# sourceMappingURL=node-types-generator.d.ts.map

package/dist/generator/scope-closure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The closure a scoped port becomes (e.g. a forEach iteration callback).
+ *
+ * Decides the closure's frame: its parameters (the parent's scoped OUTPUT
+ * ports) and return object (the parent's scoped INPUT ports), the isolated
+ * scope context it runs its children in, the order the children run in, and
+ * how their results are read back after the scope is merged. Each child's
+ * execution block is emitted by scoped-child.
+ *
+ * The children's arguments are built by buildNodeArgumentsWithContext, which
+ * itself calls back into this module for a child that declares scopes of its
+ * own. That recursion goes through the `buildArgs` parameter, so this module
+ * never imports node-arguments.
+ */
+import type { TNodeTypeAST, TWorkflowAST, TNodeInstanceAST } from '../ast/index.js';
+import { type ScopedChildArgumentBuilder } from './scoped-child';
+/**
+ * Generate a scope function closure for a scoped port. See
+ * generateScopeFunctionClosure in node-arguments for the architecture; this is
+ * its implementation with the child argument builder passed in.
+ */
+export declare function emitScopeClosure(scopeName: string, parentNodeId: string, parentNodeType: TNodeTypeAST, workflow: TWorkflowAST, childInstances: TNodeInstanceAST[], isAsync: boolean, production: boolean, buildArgs: ScopedChildArgumentBuilder): string;
+//# sourceMappingURL=scope-closure.d.ts.map

package/dist/generator/scoped-child.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One child node's execution block inside a scope closure.
+ *
+ * Decides what surrounds the child's call: the debug hooks outside
+ * production, the abort check and execution index, the shouldExecute guard,
+ * the RUNNING / SUCCEEDED / FAILED-or-CANCELLED status events, the commit, and
+ * the catch that lets a durable gate's yield pass through untouched. Also
+ * decides how the child reads the scope's parameters (at the parameter's own
+ * index, pre-handled before its other arguments) and how its outputs are
+ * stored (an expression child's control-flow outputs are constants).
+ */
+import type { TNodeTypeAST, TWorkflowAST, TNodeInstanceAST } from '../ast/index.js';
+/** What a scoped child asks the argument builder for. */
+export interface ScopedChildArguments {
+    node: TNodeTypeAST;
+    workflow: TWorkflowAST;
+    id: string;
+    lines: string[];
+    indent: string;
+    getCall: string;
+    isAsync: boolean;
+    instanceParent: string | undefined;
+    skipPorts: Set<string>;
+    emitInputEvents: boolean;
+    setCall: string;
+    nodeTypeName: string;
+    production: boolean;
+    runtimeContextExpression: string;
+}
+/**
+ * Builds a child's argument list (buildNodeArgumentsWithContext). Passed in
+ * rather than imported: it is the caller of this module's closure generator.
+ */
+export type ScopedChildArgumentBuilder = (request: ScopedChildArguments) => string[];
+/** The scope closure a child runs in. */
+export interface ScopeFrame {
+    scopeName: string;
+    parentNodeId: string;
+    parentNodeType: TNodeTypeAST;
+    /** The whole workflow: node types and the parent's connections come from here. */
+    workflow: TWorkflowAST;
+    /** The children plus a virtual parent; the child's arguments are built against it. */
+    scopeWorkflow: TWorkflowAST;
+    isAsync: boolean;
+    production: boolean;
+}
+/** Emits the execution block of one child of a scope closure. */
+export declare function emitScopedChild(lines: string[], frame: ScopeFrame, child: TNodeInstanceAST, buildArgs: ScopedChildArgumentBuilder): void;
+//# sourceMappingURL=scoped-child.d.ts.map

package/dist/{sugar-optimizer.d.ts → generator/sugar-optimizer.d.ts}

@@ -5,7 +5,7 @@
  * that can be expressed as @path macros. @connect is the escape hatch for
  * connections that @path can't cover.
  */
-import type { TConnectionAST, TNodeInstanceAST, TNodeTypeAST, TWorkflowMacro, TPathMacro, TPortDefinition } from './ast/types.js';
+import type { TConnectionAST, TNodeInstanceAST, TNodeTypeAST, TWorkflowMacro, TPathMacro, TPortDefinition } from '../ast/types';
 export interface DetectedSugar {
     paths: TPathMacro[];
 }

package/dist/generator/unified.d.ts

@@ -1,4 +1,13 @@
-import type { TNodeTypeAST, TWorkflowAST } from '../ast/types.js';
+import type { TNodeTypeAST, TWorkflowAST } from '../ast/types';
+/**
+ * What a gated body declares to the engine before its first node: the
+ * fingerprint of the graph it was compiled from (`graphIdentity`), so the
+ * continuation it yields names the graph and a resume against another one
+ * is refused.
+ */
+export interface GraphIdentityStamp {
+    readonly graphFingerprint: string;
+}
 /**
  * Generates executable TypeScript code from a workflow AST using ExecutionContext for state management.
  *
@@ -19,6 +28,9 @@ import type { TNodeTypeAST, TWorkflowAST } from '../ast/types.js';
  *    - Pull nodes: Generate lazy executors registered with context
  * 7. **Exit Node**: Collect outputs and return result object
  *
+ * Steps 3 to 5 are `analyzeControlFlow`, which returns a plan; step 6 is
+ * `emitNodes` and step 7 is `emitExitAssembly`, which both only read it.
+ *
  * ## Key Concepts:
  * - **Parallel Execution**: Independent async nodes at the same topological level run concurrently
  *   via Promise.all(). Sync workflows skip this since there's no event loop concurrency.
@@ -43,5 +55,5 @@ import type { TNodeTypeAST, TWorkflowAST } from '../ast/types.js';
  * @param production - If true, omits debug instrumentation for smaller output
  * @returns Generated TypeScript function body (without function signature)
  */
-export declare function generateControlFlowWithExecutionContext(workflow: TWorkflowAST, nodeTypes: TNodeTypeAST[], isAsync: boolean, production?: boolean, bundleMode?: boolean): string;
+export declare function generateControlFlowWithExecutionContext(workflow: TWorkflowAST, nodeTypes: TNodeTypeAST[], isAsync: boolean, production?: boolean, bundleMode?: boolean, durableSequential?: boolean, identity?: GraphIdentityStamp): string;
 //# sourceMappingURL=unified.d.ts.map

package/dist/generator/workflow-generator.d.ts

@@ -0,0 +1,37 @@
+import { type GenerateResult } from '../api/generate';
+export interface GeneratorOptions {
+    production?: boolean;
+    sourceMap?: boolean;
+}
+export type GeneratorResult = GenerateResult;
+/**
+ * Parse, validate and generate one workflow in a single call.
+ *
+ * A convenience over the api/* modules for callers that want the whole
+ * pipeline and an exception on the first problem: parse errors and
+ * validation errors both throw, with every message in the error text. It
+ * prints nothing; a caller that wants progress output uses the api modules
+ * directly (parseWorkflow, validateWorkflow, generateCode).
+ */
+export declare class WorkflowGenerator {
+    /**
+     * Generate executable TypeScript code from a workflow file.
+     *
+     * @param filePath - Path to the workflow file
+     * @param workflowName - Name of the workflow to generate
+     * @param options - Generation options (production mode, source maps)
+     * @returns The generated code, or with `sourceMap: true` the code and its map
+     * @throws Error when the file does not parse, the workflow is not found, or validation fails
+     */
+    generate(filePath: string, workflowName: string, options: GeneratorOptions & {
+        sourceMap: true;
+    }): Promise<GeneratorResult>;
+    generate(filePath: string, workflowName: string, options?: GeneratorOptions): Promise<string>;
+    private parse;
+    private validate;
+}
+/**
+ * Default generator instance for convenience
+ */
+export declare const generator: WorkflowGenerator;
+//# sourceMappingURL=workflow-generator.d.ts.map

package/dist/index.d.ts

@@ -56,34 +56,37 @@
  * @module @synergenius/flow-weaver
  */
 export * from './api/index.js';
-export { parser, resolveNpmNodeTypes } from './parser.js';
-export type { TExternalNodeType } from './parser.js';
-export { TagHandlerRegistry } from './parser/tag-registry.js';
-export type { TTagHandlerFn, TTagHandlerContext } from './parser/tag-registry.js';
-export { ValidationRuleRegistry } from './validation/rule-registry.js';
-export type { TValidationRuleSet } from './validation/rule-registry.js';
-export type { TConnectionAST, TNodeTypeAST, TNodeInstanceAST, TNodeInstanceConfig, TPortConfig, TWorkflowAST, TPortReference, TPortDefinition, TDataType, TExecuteWhen, TBranchingStrategy, TSerializableValue, TSerializableObject, TSerializableArray, TImportDeclaration, TImportSpecifier, TSourceLocation, TValidationError, TAnalysisResult, TControlFlowGraph, TControlFlowEdge, TBranchingNodeInfo, TBranchRegion, TMergeNodeInfo, TWorkflowMetadata, TNodeMetadata, TConnectionMetadata, TASTTransformer, TASTVisitor, TParseOptions, TValidationRule, TGenerateOptions, TCompileResult, TCompilationMetadata, TNodeTypeDefaultConfig, TNodeTypePort, TPortDirection, TNodeParent, TPullExecutionConfig, TWorkflowFileExtension, TPortPlacement, TPortUI, TNodeTypeUI, TNodeUI, TWorkFlowFunctionUI, TPortType, } from './ast/types.js';
-export { WorkflowBuilder, NodeTypeBuilder, NodeInstanceBuilder, ConnectionBuilder, } from './ast/builder.js';
-export { portRef, port, workflow, nodeType, nodeInstance } from './ast/builder.js';
-export { GeneratedExecutionContext } from './runtime/ExecutionContext.js';
-export type { TDebugger } from './runtime/events.js';
-export type { TLocalFunctionNodeType } from './node-types-generator.js';
+export { parser, resolveNpmNodeTypes } from './parser/annotation-parser';
+export type { TExternalNodeType } from './parser/annotation-parser';
+export { TagHandlerRegistry } from './parser/tag-registry';
+export type { TTagHandlerFn, TTagHandlerContext, TTagSerializerFn } from './parser/tag-registry';
+export { ValidationRuleRegistry } from './validation/rule-registry';
+export type { TValidationRuleSet } from './validation/rule-registry';
+export type { TConnectionAST, TNodeTypeAST, TNodeInstanceAST, TNodeInstanceConfig, TPortConfig, TWorkflowAST, TPortReference, TPortDefinition, TDataType, TExecuteWhen, TBranchingStrategy, TSerializableValue, TSerializableObject, TSerializableArray, TImportDeclaration, TImportSpecifier, TSourceLocation, TValidationError, TAnalysisResult, TControlFlowGraph, TControlFlowEdge, TBranchingNodeInfo, TBranchRegion, TMergeNodeInfo, TWorkflowMetadata, TNodeMetadata, TConnectionMetadata, TASTTransformer, TASTVisitor, TParseOptions, TValidationRule, TGenerateOptions, TCompileResult, TCompilationMetadata, TNodeTypeDefaultConfig, TNodeTypePort, TPortDirection, TNodeParent, TPullExecutionConfig, TWorkflowFileExtension, TPortPlacement, TPortUI, TNodeTypeUI, TNodeUI, TWorkFlowFunctionUI, TPortType, } from './ast/types';
+export { WorkflowBuilder, NodeTypeBuilder, NodeInstanceBuilder, ConnectionBuilder, } from './ast/builder';
+export { portRef, port, workflow, nodeType, nodeInstance } from './ast/builder';
+export { GeneratedExecutionContext } from './runtime/ExecutionContext';
+export type { TDebugger } from './runtime/events';
+export { createWorkflowRuntime, DurableExecution, DurableGateYield, AmbiguousEffectError, } from './runtime/durable-execution';
+export type { WorkflowRuntime, WorkflowRuntimeServices, CreateWorkflowRuntimeOptions, DurableEngine, GateResolution, EffectAdapter, EffectRecovery, } from './runtime/durable-execution';
+export { isDurableGateYield, isAmbiguousEffectError } from './runtime/durable-execution';
+export * from './runtime/continuation';
+export type { TLocalFunctionNodeType } from './generator/node-types-generator';
 export { configureGeneratedBranding, getGeneratedBranding } from './generated-branding.js';
 export type { GeneratedBranding } from './generated-branding.js';
-export * from './type-mappings.js';
+export * from './types/type-mappings';
 export * from './constants.js';
-export { validator, WorkflowValidator } from './validator.js';
-export { getFriendlyError, formatFriendlyDiagnostics } from './friendly-errors.js';
-export type { TFriendlyError } from './friendly-errors.js';
-export { generator, WorkflowGenerator } from './generator.js';
-export { AnnotationGenerator } from './annotation-generator.js';
-export type { GenerateAnnotationsOptions } from './annotation-generator.js';
-export * as GeneratorUtils from './generator.js';
+export { validator, WorkflowValidator } from './validation/validator';
+export { getFriendlyError, formatFriendlyDiagnostics } from './validation/friendly-errors';
+export type { TFriendlyError } from './validation/friendly-errors';
+export { generator, WorkflowGenerator } from './generator/workflow-generator';
+export { AnnotationGenerator } from './generator/annotation-generator';
+export type { GenerateAnnotationsOptions } from './generator/annotation-generator';
 export { parsePortsFromFunctionText, updatePortsInFunctionText, formatPortsInFunctionText, syncCodeRenames, renamePortInCode, parseReturnTypeFields, parseFunctionSignature, parseReturnFields, } from './jsdoc-port-sync/index.js';
-export { workflowTemplates, nodeTemplates, getWorkflowTemplate, getNodeTemplate, toCamelCase, toPascalCase, } from './cli/templates/index.js';
-export type { WorkflowTemplate, NodeTemplate, WorkflowTemplateOptions } from './cli/templates/index.js';
-export { WorkflowDiffer } from './diff/WorkflowDiffer.js';
-export { formatDiff, type TDiffFormat } from './diff/formatDiff.js';
-export { IMPACT_DESCRIPTIONS, IMPACT_COLORS, getImpactReasons, hasBreakingChanges, getNodeTypeChanges, getCriticalConnections, } from './diff/impact.js';
-export type { TWorkflowDiff, TNodeTypeDiff, TInstanceDiff, TConnectionDiff, TWorkflowPortsDiff, TScopeDiff, TPortChange, TImpactLevel, TChangeType, TChange, TInstanceConfigChange, TPortRef, } from './diff/types.js';
+export { workflowTemplates, nodeTemplates, getWorkflowTemplate, getNodeTemplate, toCamelCase, toPascalCase, } from './cli/templates';
+export type { WorkflowTemplate, NodeTemplate, WorkflowTemplateOptions } from './cli/templates';
+export { WorkflowDiffer } from './diff/WorkflowDiffer';
+export { formatDiff, type TDiffFormat } from './diff/formatDiff';
+export { IMPACT_DESCRIPTIONS, IMPACT_COLORS, getImpactReasons, hasBreakingChanges, getNodeTypeChanges, getCriticalConnections, } from './diff/impact';
+export type { TWorkflowDiff, TNodeTypeDiff, TInstanceDiff, TConnectionDiff, TWorkflowPortsDiff, TScopeDiff, TPortChange, TImpactLevel, TChangeType, TChange, TInstanceConfigChange, TPortRef, } from './diff/types';
 //# sourceMappingURL=index.d.ts.map