@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/runtime/durable-execution.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The durable engine: what a generated body talks to through its execution
+ * context, and what a coordinator or a host of its own constructs around a
+ * run. Node completion, variables, gates and effects are recorded by exact
+ * execution address, so a run can stop at a gate and be replayed later by
+ * any process from a continuation.
+ *
+ * This module is written to be inlined: `fw compile` copies its text into
+ * every compiled file after `continuation-core.ts` (see
+ * `src/api/inline-runtime.ts`). It imports values only from that module,
+ * and its type imports are aliased by the inliner. No Node API, nothing
+ * past ES2020. Every comment below this header is copied too, and the
+ * generator goldens pin the copied text; this header is the one comment the
+ * inliner drops.
+ *
+ * One execution context talks to this engine, `src/runtime/ExecutionContext.ts`,
+ * inlined into compiled files the same way. Its 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 again (`tests/continuation/durable-loops.test.ts`).
+ */
+import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
+import type { DebugController } from './debug-controller.js';
+import type { TDebugger } from './events.js';
+import { type AcceptedContinuationEnvelope, type ContinuationEnvelope, type ContinuationState, type BranchAddress, type DurableGate, type DurableGateKind, type EffectReceipt, type ExecutionAddress, type ScopeAddress, type WireValue, type WorkflowFrameAddress } from './continuation-core.js';
+export interface GateResolution {
+    readonly gateId: string;
+    readonly value: WireValue;
+}
+export declare function acceptGateResolution(resolution: GateResolution | undefined): GateResolution | undefined;
+export type EffectRecovery = {
+    readonly kind: 'not-committed';
+} | {
+    readonly kind: 'committed';
+    readonly receipt: WireValue;
+    readonly result: WireValue;
+} | {
+    readonly kind: 'repeatable';
+} | {
+    readonly kind: 'ambiguous';
+};
+export interface EffectAdapter {
+    recover(operationKey: string, address: ExecutionAddress): Promise<EffectRecovery>;
+    /** Persist the exact successful effect result before it enters a continuation. */
+    commit?(operationKey: string, address: ExecutionAddress, execution: EffectExecution<WireValue>): Promise<void>;
+}
+export interface WorkflowRuntimeServices {
+    readonly debugger?: TDebugger;
+    readonly debugController?: DebugController;
+    readonly mocks?: FwMockConfig;
+    readonly workflowRegistry?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
+    readonly effectAdapter?: EffectAdapter;
+}
+/**
+ * The engine as a generated body sees it. It is an interface, not the class,
+ * so a runtime built by the package and one built by a compiled file's own
+ * copy of the engine are interchangeable to the type checker: two classes
+ * with private members never are.
+ */
+export interface DurableEngine {
+    address(runtime: Pick<WorkflowRuntime, 'frames' | 'scopes' | 'branches'>, nodeId: string, nodeType: string, executionIndex: number): ExecutionAddress;
+    /** Called once at the top of a root body: the workflow's name and graph identity. */
+    bind(runtime: Pick<WorkflowRuntime, 'frames'>, workflowId: string, graphFingerprint: string): void;
+    shouldExecute(address: ExecutionAddress): boolean;
+    commitNode(address: ExecutionAddress): void;
+    setVariable(address: ExecutionAddress, portName: string, value: unknown): void;
+    getVariable(address: ExecutionAddress, portName: string, allowAncestorLookup?: boolean): unknown;
+    resolveGate(runtime: WorkflowRuntime, boundary: GateBoundary): WireValue;
+    executeEffect<T extends WireValue>(runtime: WorkflowRuntime, boundary: EffectBoundary, execute: (operationKey: string) => Promise<EffectExecution<T>>): Promise<T>;
+    assertResumeResolutionConsumed(): void;
+}
+export interface WorkflowRuntime {
+    readonly runId: string;
+    readonly abortSignal?: AbortSignal;
+    readonly services: WorkflowRuntimeServices;
+    readonly durable: DurableEngine;
+    readonly frames: readonly WorkflowFrameAddress[];
+    readonly scopes: readonly ScopeAddress[];
+    readonly branches: readonly BranchAddress[];
+}
+export interface NodeExecutionRuntime {
+    readonly nodeId: string;
+    readonly runtime: WorkflowRuntime;
+    readonly recursionDepth: number;
+    createNestedRuntime(workflowId: string): WorkflowRuntime;
+}
+export interface CreateWorkflowRuntimeOptions {
+    readonly runId: string;
+    readonly workflowId: string;
+    readonly abortSignal?: AbortSignal;
+    readonly services?: WorkflowRuntimeServices;
+    readonly continuation?: AcceptedContinuationEnvelope;
+    readonly resolution?: GateResolution;
+    /**
+     * The identity of the compiled artifact this run executes, `sha256:<hex>`.
+     * A coordinator that hashes the artifact passes it, and a continuation is
+     * refused on resume when it names another. Left out, the engine derives one
+     * from the workflow's own graph identity, so a host that keeps a
+     * continuation and brings it back to the same compiled file needs nothing
+     * more.
+     */
+    readonly bundleDigest?: string;
+}
+export interface GateBoundary {
+    readonly kind: DurableGateKind;
+    readonly nodeId: string;
+    readonly nodeType: string;
+    readonly executionIndex: number;
+    readonly payload: WireValue;
+}
+export interface EffectBoundary {
+    readonly nodeId: string;
+    readonly nodeType: string;
+    readonly executionIndex: number;
+}
+export interface EffectExecution<T extends WireValue> {
+    readonly result: T;
+    readonly receipt: WireValue;
+}
+/**
+ * Thrown out of a generated body when a gate has to wait for the outside.
+ * It carries everything a host needs to keep: the gate to answer, and the
+ * continuation to bring back with the answer. `continuation` is present when
+ * the body declared its identity (every body compiled by this version does);
+ * a coordinator may also build its own from `state` and `receipts`.
+ */
+export declare class DurableGateYield extends Error {
+    readonly gate: DurableGate;
+    readonly state: ContinuationState;
+    readonly receipts: readonly EffectReceipt[];
+    readonly continuation?: ContinuationEnvelope | undefined;
+    readonly code = "FLOW_WEAVER_DURABLE_GATE_YIELD";
+    constructor(gate: DurableGate, state: ContinuationState, receipts: readonly EffectReceipt[], continuation?: ContinuationEnvelope | undefined);
+}
+export declare class AmbiguousEffectError extends Error {
+    readonly operationKey: string;
+    readonly address: ExecutionAddress;
+    readonly code = "FLOW_WEAVER_AMBIGUOUS_EFFECT";
+    constructor(operationKey: string, address: ExecutionAddress);
+}
+export declare function requireEffectRecovery(value: unknown, key: string, address: ExecutionAddress): EffectRecovery;
+export declare class DurableExecution implements DurableEngine {
+    readonly runId: string;
+    readonly workflowId: string;
+    private readonly completed;
+    private readonly variables;
+    private readonly receipts;
+    private readonly resumeEnvelope?;
+    private readonly resolution?;
+    private readonly givenBundleDigest?;
+    private graphFingerprint?;
+    private resolutionConsumed;
+    constructor(runId: string, workflowId: string, continuation?: AcceptedContinuationEnvelope, resolution?: GateResolution, bundleDigest?: string);
+    address(runtime: Pick<WorkflowRuntime, 'frames' | 'scopes' | 'branches'>, nodeId: string, nodeType: string, executionIndex: number): ExecutionAddress;
+    /**
+     * The artifact identity this run executes under: the one the coordinator
+     * gave, or one derived from the graph identity the body declared. Known
+     * only after `bind`.
+     */
+    bundleDigest(): string | undefined;
+    bind(runtime: Pick<WorkflowRuntime, 'frames'>, workflowId: string, graphFingerprint: string): void;
+    shouldExecute(address: ExecutionAddress): boolean;
+    commitNode(address: ExecutionAddress): void;
+    setVariable(address: ExecutionAddress, portName: string, value: unknown): void;
+    getVariable(address: ExecutionAddress, portName: string, allowAncestorLookup?: boolean): unknown;
+    resolveGate(runtime: WorkflowRuntime, boundary: GateBoundary): WireValue;
+    executeEffect<T extends WireValue>(runtime: WorkflowRuntime, boundary: EffectBoundary, execute: (operationKey: string) => Promise<EffectExecution<T>>): Promise<T>;
+    snapshot(nextBoundary: ExecutionAddress): ContinuationState;
+    assertResumeResolutionConsumed(): void;
+}
+export declare function createWorkflowRuntime(options: CreateWorkflowRuntimeOptions): WorkflowRuntime;
+export declare function createNestedWorkflowRuntime(runtime: WorkflowRuntime, workflowId: string, callerNodeId: string, callerExecutionIndex: number, invocation: number): WorkflowRuntime;
+export declare function createScopedWorkflowRuntime(runtime: WorkflowRuntime, scope: ScopeAddress): WorkflowRuntime;
+export declare function isDurableGateYield(error: unknown): error is DurableGateYield;
+export declare function isAmbiguousEffectError(error: unknown): error is AmbiguousEffectError;
+//# sourceMappingURL=durable-execution.d.ts.map

package/dist/runtime/events.d.ts

@@ -32,6 +32,14 @@ export type TErrorLogEvent = {
     side?: "start" | "exit";
     executionIndex: number;
     error: string;
+    /**
+     * Structured error code copied from a thrown `Error.code`, when the
+     * node threw one. Optional: most throws carry only a message. Consumers
+     * use it to route to a localized message catalog instead of rendering
+     * the (single-language) `error` string. Undefined when the thrown value
+     * had no `code`.
+     */
+    code?: string;
     innerFlowInvocation?: boolean;
 };
 export type TWorkflowCompletedEvent = {
@@ -43,7 +51,14 @@ export type TWorkflowCompletedEvent = {
 };
 export type TEvent = TStatusChangedEvent | TVariableSetEvent | TErrorLogEvent | TWorkflowCompletedEvent;
 export type TDebugger = {
-    sendEvent: (event: TEvent) => void;
+    /**
+     * The execution context awaits what this returns for a status event, so a
+     * debugger can hold a node at a breakpoint by returning a promise it has
+     * not settled yet. Typed `unknown` rather than `void | Promise<void>` so a
+     * handler that returns something else, such as `(e) => events.push(e)`,
+     * still fits.
+     */
+    sendEvent: (event: TEvent) => unknown;
     innerFlowInvocation: boolean;
     sessionId?: string;
 };

package/dist/runtime/executable-module-contract.d.ts

@@ -0,0 +1,16 @@
+import { GENERATOR_ABI, type ContinuationGraphCompatibility } from './continuation.js';
+export declare const EXECUTABLE_WORKFLOW_MODULE_FORMAT: 1;
+export declare const EXECUTABLE_WORKFLOW_METADATA_EXPORT: "__flowWeaverExecutableArtifact";
+export interface ExecutableWorkflowModuleMetadata {
+    readonly formatVersion: typeof EXECUTABLE_WORKFLOW_MODULE_FORMAT;
+    readonly generatorAbi: typeof GENERATOR_ABI;
+    readonly workflowName: string;
+    readonly workflowNames: readonly string[];
+    readonly graphFingerprint: string;
+    readonly continuationGraph: ContinuationGraphCompatibility;
+    readonly capabilities: {
+        readonly gate: boolean;
+        readonly effect: boolean;
+    };
+}
+//# sourceMappingURL=executable-module-contract.d.ts.map

package/dist/runtime/index.d.ts

@@ -1,11 +1,14 @@
-export { GeneratedExecutionContext } from "./ExecutionContext.js";
-export { CancellationError } from "./CancellationError.js";
-export { DebugController } from "./debug-controller.js";
-export type { TDebugController, DebugMode, DebugPauseState, DebugResumeAction, DebugControllerConfig } from "./debug-controller.js";
-export { CheckpointWriter, loadCheckpoint, findLatestCheckpoint } from "./checkpoint.js";
-export type { CheckpointData } from "./checkpoint.js";
-export * from "./events.js";
-export * from "./function-registry.js";
-export * from "./parameter-resolver.js";
-export * from "./builtin-functions.js";
+export { GeneratedExecutionContext } from "./ExecutionContext";
+export { CancellationError } from "./CancellationError";
+export { DebugController } from "./debug-controller";
+export type { TDebugController, DebugMode, DebugPauseState, DebugResumeAction, DebugControllerConfig } from "./debug-controller";
+export { createWorkflowRuntime, DurableExecution, DurableGateYield, AmbiguousEffectError, acceptGateResolution, } from "./durable-execution";
+export type { WorkflowRuntime, WorkflowRuntimeServices, CreateWorkflowRuntimeOptions, DurableEngine, GateResolution, EffectAdapter, EffectRecovery, } from "./durable-execution";
+export * from "./continuation";
+export * from "./strict-json";
+export * from "./events";
+export * from "./function-registry";
+export * from "./parameter-resolver";
+export * from "./builtin-functions";
+export * from "./executable-module-contract";
 //# sourceMappingURL=index.d.ts.map