@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/runtime/ExecutionContext.d.ts

@@ -1,20 +1,35 @@
-import type { TDebugger, TStatusType, TVariableIdentification } from './events.js';
 /**
- * Address for accessing a variable in the execution context
+ * The execution context a generated workflow body runs against: variable
+ * storage, per-node execution indices, scopes, pull execution, debug events,
+ * and the calls into the durable engine.
  *
- * Variables are stored with key format: `nodeName:portName:executionIndex`
+ * This module is written to be inlined, and there is one copy of the class:
+ * `scripts/generate-inline-engine.ts` turns this file into text, and
+ * `generateInlineRuntime` in `src/api/inline-runtime.ts` writes that text
+ * into every compiled file. The class the package exports and the one a
+ * compiled workflow runs are therefore the same code. The rules of
+ * `durable-execution.ts` apply here too: no Node API, nothing past ES2020,
+ * and imports of types only, except `CancellationError`, which the inlined
+ * runtime declares ahead of this class. Every comment below this header is
+ * copied into compiled files; this header is the one comment the inliner
+ * drops.
  *
- * @example
- * ```typescript
- * const address: VariableAddress = {
- *   nodeName: 'adder1',
- *   portName: 'result',
- *   executionIndex: 0,
- *   nodeTypeName: 'Add'
- * };
- * const value = await ctx.getVariable(address);
- * // Key used internally: "adder1:result:0"
- * ```
+ * A production build of a compiled file carries no debug instrumentation,
+ * and two comment markers say what it leaves out:
+ * - a region opened by `inline: development only` and closed by
+ *   `inline: end` is removed;
+ * - a region opened by `inline: development only, a no-op stub in
+ *   production` becomes one `name(_args: unknown): void` stub for each
+ *   method in it, so generated calls to those methods still resolve.
+ * The package and the development build keep both kinds of region and drop
+ * only the marker lines.
+ */
+import type { TStatusType } from './events';
+import type { WorkflowRuntime } from './durable-execution.js';
+import type { DurableGateKind, ExecutionAddress, WireValue } from './continuation.js';
+/**
+ * Address of a variable in the execution context. Variables are stored under
+ * the key `id:portName:executionIndex`.
  */
 export interface VariableAddress {
     id: string;
@@ -23,6 +38,8 @@ export interface VariableAddress {
     nodeTypeName?: string | undefined;
     scope?: string | undefined;
     side?: 'start' | 'exit' | undefined;
+    /** Inputs remain live/debug-visible but are never serialized as durable outputs. */
+    durable?: boolean | undefined;
 }
 export interface ExecutionInfo {
     id: string;
@@ -32,92 +49,82 @@ export interface ExecutionInfo {
 }
 type VariableValue = unknown | (() => unknown) | (() => Promise<unknown>);
 /**
- * Runtime execution context for generated workflows
- *
- * Manages variable storage, execution tracking, and pull execution (lazy evaluation).
- * This class is used internally by generated workflow code.
- *
- * Key Features:
- * - Variable storage with execution-scoped addressing
- * - Pull execution support (lazy evaluation)
- * - Debug event emission
- * - Async and sync execution modes
+ * Variable storage with execution-scoped addressing, per-node execution
+ * indices, pull execution (lazy evaluation), scopes and parallel lanes, debug
+ * events, and the durable engine calls a generated body makes.
  *
- * @example
- * ```typescript
- * const ctx = new GeneratedExecutionContext(true, debugger);
- * const execIndex = ctx.addExecution('node1');
- * ctx.setVariable({ nodeName: 'node1', portName: 'result', executionIndex: execIndex }, 42);
- * const value = await ctx.getVariable({ nodeName: 'node1', portName: 'result', executionIndex: execIndex });
- * ```
+ * Scope counters start at 0 on every construction. A resume replays the body
+ * from its first node, skipping what the continuation holds, and so reaches
+ * the same iteration ordinals the first run assigned
+ * (`tests/continuation/durable-loops.test.ts`).
  */
 export declare class GeneratedExecutionContext {
     private variables;
     private executions;
     private executionCounter;
+    private nodeExecutionCounts;
     private isAsync;
     private flowWeaverDebugger?;
     private pullExecutors;
     private nodeExecutionIndices;
-    private abortSignal?;
-    /**
-     * Create a new execution context
-     * @param isAsync - Whether the workflow runs in async mode (default: true)
-     * @param flowWeaverDebugger - Optional debugger for emitting execution events
-     * @param abortSignal - Optional AbortSignal for cancellation support
-     */
-    constructor(isAsync?: boolean, flowWeaverDebugger?: TDebugger, abortSignal?: AbortSignal);
+    private runtime;
+    private scopeInvocationCounts;
+    private nestedInvocationCounts;
+    private branchStack;
+    private allowAncestorDurableVariables;
+    /** `isAsync` is the workflow's async mode; `runtime` is the execution-scoped runtime. */
+    constructor(isAsync: boolean | undefined, runtime: WorkflowRuntime);
     registerPullExecutor(id: string, executor: () => void | Promise<void>): void;
+    /** Record one execution of a node; each node counts its own executions from 0. */
     addExecution(id: string, parentIndex?: number, scopeName?: string): number;
     setVariable(address: VariableAddress, value: VariableValue): void | Promise<void>;
     getVariable(address: VariableAddress): unknown | Promise<unknown>;
     private retrieveVariable;
     hasVariable(address: VariableAddress): boolean;
-    getExecution(id: string, index: number): ExecutionInfo | undefined;
+    executionAddress(address: Pick<VariableAddress, 'id' | 'executionIndex' | 'nodeTypeName'>): ExecutionAddress;
+    shouldExecute(nodeId: string, nodeType: string, executionIndex: number): boolean;
+    commitNode(nodeId: string, nodeType: string, executionIndex: number): void;
+    /** The first thing a gated body does: name its workflow and graph to the engine. */
+    bindWorkflow(workflowId: string, graphFingerprint: string): void;
+    resolveGate(kind: DurableGateKind, nodeId: string, nodeType: string, executionIndex: number, payload: WireValue): WireValue;
+    executeEffect<T extends WireValue>(nodeId: string, nodeType: string, executionIndex: number, execute: (operationKey: string) => Promise<{
+        result: T;
+        receipt: WireValue;
+    }>): Promise<T>;
+    createNestedRuntime(workflowId: string, callerNodeId: string, callerExecutionIndex: number): WorkflowRuntime;
+    enterBranch(nodeId: string, executionIndex: number, arm: string): void;
+    exitBranch(): void;
+    getRuntime(): WorkflowRuntime;
     /**
-     * Create an isolated execution scope for container nodes
-     *
-     * Scopes provide isolated variable storage for nodes like ForEach loops.
-     * Child nodes execute within the scope, then variables are merged back.
-     *
-     * @param _parentNodeName - ID of the container node creating the scope
-     * @param _parentIndex - Execution index of the container
-     * @param _scopeName - Name of the scope (e.g., 'iteration')
-     * @param cleanScope - If true, create fresh scope without parent variables (per-port scopes). If false, inherit parent variables (node-level scopes).
-     * @returns New ExecutionContext for the scoped execution
-     *
-     * @example
-     * ```typescript
-     * // Per-port scope (clean=true): isolated variables
-     * const scopedCtx = ctx.createScope('forEach1', 0, 'iteration', true);
-     *
-     * // Node-level scope (clean=false): inherited variables
-     * const scopedCtx = ctx.createScope('container1', 0, 'block', false);
-     * ```
+     * Fork the mutable bookkeeping for one lane of a parallel group. Durable
+     * state stays execution-scoped and shared through `runtime`, while the
+     * branch and scope address stacks are copied so concurrent lanes cannot
+     * corrupt one another's continuation addresses.
      */
-    createScope(_parentNodeName: string, _parentIndex: number, _scopeName: string, cleanScope?: boolean): GeneratedExecutionContext;
+    forkParallel(): GeneratedExecutionContext;
+    mergeParallel(parallelContext: GeneratedExecutionContext): void;
+    getExecution(id: string, index: number): ExecutionInfo | undefined;
     /**
-     * Merge a scoped execution context back into the parent context
-     *
-     * Copies all variables and execution info from the scoped context to this context.
-     * Updates the execution counter to maintain unique execution indices.
-     *
-     * @param scopedContext - The scoped context to merge
+     * Create the execution context for one invocation of a scope (a loop body,
+     * a per-port function). Each call is the next invocation of that scope key.
+     * A clean scope (a per-port scope) starts with no variables and cannot read
+     * its ancestors' durable variables; any other (a node-level scope) inherits
+     * the parent's variables. `isAsyncOverride` is the scope's own async mode,
+     * when it differs from the parent's.
      */
+    createScope(_parentNodeName: string, _parentIndex: number, _scopeName: string, cleanScope?: boolean, isAsyncOverride?: boolean): GeneratedExecutionContext;
+    /** Merge a scope's variables, executions and counters back into this context. */
     mergeScope(scopedContext: GeneratedExecutionContext): void;
     private getVariableKey;
     private getExecutionKey;
     getExecutionCount(): number;
     reset(): void;
-    /**
-     * Check if the workflow has been aborted
-     */
     isAborted(): boolean;
-    /**
-     * Throw CancellationError if the workflow has been aborted
-     * @param nodeId - Optional node ID to include in the error
-     */
+    /** Return the parent-owned signal without transferring ownership. */
+    getAbortSignal(): AbortSignal | undefined;
+    /** Throw a CancellationError, naming `nodeId` when given, if the run was aborted. */
     checkAborted(nodeId?: string): void;
+    /** Awaited by generated code, so a debugger can hold a node at a breakpoint. */
     sendStatusChangedEvent(args: {
         nodeTypeName: string;
         id: string;
@@ -125,11 +132,7 @@ export declare class GeneratedExecutionContext {
         side?: 'start' | 'exit';
         executionIndex: number;
         status: TStatusType;
-    }): void;
-    sendVariableSetEvent(args: {
-        identifier: TVariableIdentification;
-        value: unknown;
-    }): void;
+    }): Promise<void>;
     sendLogErrorEvent(args: {
         nodeTypeName: string;
         id: string;
@@ -137,31 +140,16 @@ export declare class GeneratedExecutionContext {
         side?: 'start' | 'exit';
         executionIndex: number;
         error: string;
-    }): void;
+        code?: string;
+    }): Promise<void>;
     sendWorkflowCompletedEvent(args: {
         executionIndex: number;
         status: 'SUCCEEDED' | 'FAILED' | 'CANCELLED';
         result?: unknown;
-    }): void;
-    /**
-     * Serialize the execution context state for checkpointing.
-     * Function values are resolved to concrete values before serialization.
-     */
-    serialize(): {
-        variables: Record<string, unknown>;
-        executions: Record<string, ExecutionInfo>;
-        executionCounter: number;
-        nodeExecutionCounts: Record<string, number>;
-    };
-    /**
-     * Restore execution context state from a checkpoint.
-     */
-    restore(data: {
-        variables: Record<string, unknown>;
-        executions: Record<string, ExecutionInfo>;
-        executionCounter: number;
-        nodeExecutionCounts: Record<string, number>;
-    }): void;
+    }): Promise<void>;
+    private sendVariableSetEvent;
+    /** Return live debugger-visible variables without invoking lazy values. */
+    inspectVariables(): Record<string, unknown>;
 }
 export {};
 //# sourceMappingURL=ExecutionContext.d.ts.map

package/dist/runtime/continuation-core.d.ts

@@ -0,0 +1,147 @@
+/** The version of the engine that wrote a continuation: the package's own. */
+export declare const ENGINE_VERSION: string;
+export declare const CONTINUATION_FORMAT_VERSION: 1;
+export declare const GENERATOR_ABI: "flow-weaver-generated-v2";
+export declare const MAX_CONTINUATION_BYTES: number;
+export declare const MAX_CONTINUATION_DEPTH = 32;
+export declare const MAX_CONTINUATION_ENTRIES = 10000;
+export declare const MAX_CONTINUATION_STRING_BYTES: number;
+/**
+ * Who answers a gate: a person deciding, a system supplying data, an agent
+ * doing a task, or the clock (`timer`: a `sleep` node, woken by whoever
+ * keeps the run when its time has come).
+ */
+export type DurableGateKind = "approval" | "input" | "agent" | "timer";
+export type WireValue = null | boolean | number | string | readonly WireValue[] | {
+    readonly [key: string]: WireValue;
+};
+export interface WorkflowFrameAddress {
+    readonly workflowId: string;
+    readonly invocation: number;
+    readonly callerNodeId?: string;
+    readonly callerExecutionIndex?: number;
+}
+export interface ScopeAddress {
+    readonly parentNodeId: string;
+    readonly parentExecutionIndex: number;
+    readonly scopeName: string;
+    readonly invocation: number;
+    readonly loopIteration?: number;
+    readonly branchArm?: string;
+}
+export interface BranchAddress {
+    readonly workflowId: string;
+    readonly frameDepth: number;
+    readonly nodeId: string;
+    readonly executionIndex: number;
+    readonly arm: string;
+}
+export interface ExecutionAddress {
+    readonly frames: readonly WorkflowFrameAddress[];
+    readonly scopes: readonly ScopeAddress[];
+    readonly branches: readonly BranchAddress[];
+    readonly nodeId: string;
+    readonly nodeType: string;
+    readonly executionIndex: number;
+}
+export interface ContinuationVariable {
+    readonly address: ExecutionAddress;
+    readonly portName: string;
+    readonly value: WireValue;
+}
+export interface EffectReceipt {
+    readonly address: ExecutionAddress;
+    readonly operationKey: string;
+    readonly receipt: WireValue;
+}
+export interface ContinuationState {
+    readonly completed: readonly ExecutionAddress[];
+    readonly variables: readonly ContinuationVariable[];
+    readonly nextBoundary: ExecutionAddress;
+}
+export interface DurableGate {
+    readonly id: string;
+    readonly kind: DurableGateKind;
+    readonly address: ExecutionAddress;
+    readonly payload: WireValue;
+}
+/** The branch arms a node sits under, as the compiled graph describes them. */
+export type ContinuationGraphNodeBranchPath = readonly {
+    readonly nodeId: string;
+    readonly arm: string;
+}[];
+export interface ContinuationEnvelope {
+    readonly formatVersion: typeof CONTINUATION_FORMAT_VERSION;
+    readonly runId: string;
+    readonly gateId: string;
+    readonly gateKind: DurableGateKind;
+    readonly workflowId: string;
+    readonly bundleDigest: string;
+    readonly graphFingerprint: string;
+    readonly engineVersion: string;
+    readonly generatorAbi: string;
+    readonly location: ExecutionAddress;
+    readonly state: ContinuationState;
+    readonly receipts: readonly EffectReceipt[];
+    readonly createdAt: string;
+    readonly checksum: string;
+}
+declare const acceptedContinuationBrand: unique symbol;
+export type AcceptedContinuationEnvelope = ContinuationEnvelope & {
+    readonly [acceptedContinuationBrand]: true;
+};
+export type ContinuationRefusalReason = "malformed" | "oversized" | "unsupported-format" | "incompatible-engine" | "incompatible-generator" | "wrong-workflow" | "wrong-bundle" | "wrong-graph" | "checksum-mismatch" | "stale-gate" | "wrong-run" | "ambiguous-effect";
+export interface ContinuationRefusal {
+    readonly accepted: false;
+    readonly reason: ContinuationRefusalReason;
+    readonly message: string;
+}
+export interface AcceptedContinuation {
+    readonly accepted: true;
+    readonly envelope: AcceptedContinuationEnvelope;
+}
+export type DecodedContinuation = AcceptedContinuation | ContinuationRefusal;
+/** What a resume must match before an envelope is trusted. */
+export interface ContinuationIdentity {
+    readonly runId: string;
+    readonly workflowId: string;
+    /** When given, the envelope must be the one this gate answer belongs to. */
+    readonly gateId?: string;
+}
+export declare const ENVELOPE_KEYS: readonly ["formatVersion", "runId", "gateId", "gateKind", "workflowId", "bundleDigest", "graphFingerprint", "engineVersion", "generatorAbi", "location", "state", "receipts", "createdAt", "checksum"];
+export declare function utf8ByteLength(text: string): number;
+/** The SHA-256 of a string's UTF-8 bytes, as lowercase hex. */
+export declare function sha256Hex(text: string): string;
+export declare class WireValidationError extends Error {
+    readonly reason: "malformed" | "oversized";
+    constructor(reason: "malformed" | "oversized", message: string);
+}
+export declare function validateWireValue(value: unknown): asserts value is WireValue;
+export declare function canonicalWireValue(value: unknown): string;
+export declare function cloneAndFreezeWireValue<T extends WireValue>(value: T): T;
+export declare function executionAddressKey(address: ExecutionAddress): string;
+export declare function durableGateId(runId: string, kind: DurableGateKind, address: ExecutionAddress): string;
+export declare function operationKey(runId: string, address: ExecutionAddress): string;
+export declare function continuationChecksum(envelope: ContinuationEnvelope): string;
+export declare function createContinuationEnvelope(fields: Omit<ContinuationEnvelope, "formatVersion" | "engineVersion" | "generatorAbi" | "createdAt" | "checksum"> & {
+    readonly engineVersion?: string;
+    readonly generatorAbi?: string;
+    readonly createdAt?: string;
+}): ContinuationEnvelope;
+export declare function isPlainObjectRecord(value: unknown): value is Record<string, unknown>;
+export declare function hasExactlyTheKeys(value: Record<string, unknown>, keys: readonly string[]): boolean;
+export declare function isExecutionAddress(value: unknown): value is ExecutionAddress;
+export declare function structurallyValidEnvelope(value: unknown): value is ContinuationEnvelope;
+/**
+ * Take an envelope back from wherever a host kept it. It is parsed when given
+ * as text, checked for shape, checksum, gate identity, engine and generator
+ * versions, and bound to the run and workflow it is about to resume. What is
+ * accepted is a frozen copy; the input is never trusted afterwards.
+ *
+ * This is what the compiled file offers a host of its own. The coordinator's
+ * `decodeContinuation` does this and, having the compiled graph, more.
+ */
+export declare function acceptContinuation(input: unknown, identity: ContinuationIdentity): DecodedContinuation;
+export declare function assertAcceptedContinuation(value: ContinuationEnvelope): asserts value is AcceptedContinuationEnvelope;
+export {};
+//# sourceMappingURL=continuation-core.d.ts.map

package/dist/runtime/continuation.d.ts

@@ -0,0 +1,48 @@
+import { type ContinuationGraphNodeBranchPath, type DecodedContinuation, type DurableGateKind } from "./continuation-core.js";
+export * from "./continuation-core.js";
+export interface ContinuationCompatibility {
+    readonly runId: string;
+    readonly workflowId: string;
+    readonly bundleDigest: string;
+    readonly graphFingerprint: string;
+    readonly engineVersion?: string;
+    readonly generatorAbi?: string;
+    readonly gateId?: string;
+    readonly graph: ContinuationGraphCompatibility;
+}
+export interface ContinuationGraphNode {
+    readonly workflowId: string;
+    readonly nodeId: string;
+    readonly nodeType: string;
+    readonly executionOrder: number;
+    readonly inputPorts: readonly string[];
+    readonly outputPorts: readonly string[];
+    readonly scopeNames: readonly string[];
+    readonly invokedWorkflows: readonly string[];
+    readonly parentScope?: {
+        readonly parentNodeId: string;
+        readonly scopeName: string;
+    };
+    readonly branchArms: readonly string[];
+    readonly branchPath: ContinuationGraphNodeBranchPath;
+    readonly predecessors: readonly ContinuationGraphPredecessor[];
+    readonly durableGate?: DurableGateKind;
+    readonly durableEffect?: true;
+}
+export interface ContinuationGraphPredecessor {
+    readonly nodeId: string;
+    readonly branchPath: ContinuationGraphNodeBranchPath;
+}
+export interface ContinuationGraphCompatibility {
+    readonly nodes: readonly ContinuationGraphNode[];
+}
+/**
+ * The coordinator's decoder: a strict, bounded parse of untrusted text, then
+ * every check `acceptContinuation` makes, then the ones that need the
+ * compiled graph: the boundary and every completed address belong to it, the
+ * completed set is a valid prefix before the boundary, variables are outputs
+ * of completed nodes, receipts match their effects, and the bundle and graph
+ * identities are the ones the coordinator vouches for.
+ */
+export declare function decodeContinuation(input: string | unknown, compatibility: ContinuationCompatibility): DecodedContinuation;
+//# sourceMappingURL=continuation.d.ts.map

package/dist/runtime/debug-controller.d.ts

@@ -1,14 +1,9 @@
 /**
  * DebugController intercepts workflow execution at node boundaries,
- * enabling step-through debugging and checkpoint/resume.
- *
- * Injected via globalThis.__fw_debug_controller__ (same pattern as
- * __fw_debugger__ and __fw_agent_channel__). The generated code calls
- * beforeNode/afterNode at each node boundary; the controller decides
- * whether to skip, pause, checkpoint, or continue.
+ * enabling live step-through debugging. It is execution-scoped and is not a
+ * durable continuation or crash-recovery mechanism.
  */
-import type { GeneratedExecutionContext } from './ExecutionContext.js';
-import type { CheckpointWriter } from './checkpoint.js';
+import type { GeneratedExecutionContext } from './ExecutionContext';
 export type DebugMode = 'step' | 'continue' | 'continueToBreakpoint' | 'run';
 export interface DebugPauseState {
     /** Node we're paused at */
@@ -40,25 +35,19 @@ export type DebugResumeAction = {
 /**
  * Minimal interface for the debug controller as referenced by generated code.
  * The full DebugController class implements this, but generated code only
- * needs beforeNode/afterNode — so this type is what gets imported.
+ * needs beforeNode/afterNode, so this type is what gets imported.
  */
 export type TDebugController = {
-    beforeNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<boolean> | boolean;
+    beforeNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<void> | void;
     afterNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<void> | void;
 };
 export interface DebugControllerConfig {
     /** Enable step-through debugging (pauses before first node) */
     debug?: boolean;
-    /** Enable checkpointing to disk after each node */
-    checkpoint?: boolean;
-    /** Checkpoint writer instance (required when checkpoint=true) */
-    checkpointWriter?: CheckpointWriter;
     /** Initial breakpoint node IDs */
     breakpoints?: string[];
     /** Execution order (set by executor after compilation) */
     executionOrder?: string[];
-    /** Nodes to skip on resume (loaded from checkpoint) */
-    skipNodes?: Map<string, Record<string, unknown>>;
 }
 export declare class DebugController {
     private mode;
@@ -68,9 +57,6 @@ export declare class DebugController {
     private executionOrder;
     private position;
     private lastCompletedNodeId;
-    private checkpointEnabled;
-    private checkpointWriter;
-    private skipNodes;
     private _gateResolve;
     private _pauseResolve;
     private _pausePromise;
@@ -80,9 +66,8 @@ export declare class DebugController {
     setExecutionOrder(order: string[]): void;
     /**
      * Called before a node executes.
-     * Returns true if the node should execute, false to skip.
      */
-    beforeNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<boolean>;
+    beforeNode(nodeId: string, ctx: GeneratedExecutionContext): Promise<void>;
     /**
      * Called after a node completes successfully.
      */
@@ -109,9 +94,9 @@ export declare class DebugController {
     /** Get completed nodes list */
     getCompletedNodes(): string[];
     private pause;
+    /** Set the mode for the next nodes. An abort never gets here: each caller throws or skips it first. */
     private applyAction;
     private applyPendingModifications;
-    private restoreNodeOutputs;
     private extractVariables;
     private extractNodeOutputs;
     private _createPausePromise;