@swirls/looms 0.0.1 → 0.1.0

package/dist/workflow/definitions.js

@@ -1,4 +1,6 @@
 import { Schema } from 'effect';
+import { DEFAULT_DEFINITION_VERSION } from '@swirls/looms/core';
+import { DEFAULT_GRAPH_CONCURRENCY, getReadyNodeIds, resolveGraphConcurrency, topologicalSort, workflowEdges, } from './graph.js';
 export const NodeStatusSchema = Schema.Union([
     Schema.Literal('pending'),
     Schema.Literal('running'),
@@ -10,23 +12,87 @@ export const NodeStateSchema = Schema.Struct({
     status: NodeStatusSchema,
     result: Schema.NullOr(Schema.Json),
     error: Schema.NullOr(Schema.String),
+    attempts: Schema.optional(Schema.Finite),
+    branch: Schema.optional(Schema.String),
+    /** Policy skips (skip/fallback) still satisfy dependents; inactive skips propagate. */
+    skipCause: Schema.optional(Schema.Union([Schema.Literal('inactive'), Schema.Literal('policy')])),
+    iteration: Schema.optional(Schema.Struct({ index: Schema.Finite, previous: Schema.Json })),
 });
+function compatibleNodeStatus(status) {
+    switch (status) {
+        case 'pending':
+        case 'running':
+        case 'completed':
+        case 'failed':
+        case 'skipped':
+            return status;
+        default:
+            return 'pending';
+    }
+}
 export function defineWorkflow(def) {
-    // SAFETY: factory fields match WorkflowDefinition.
-    return { kind: 'workflow', ...def, input: def.input };
+    const definition = {
+        kind: 'workflow',
+        ...def,
+        version: def.version ?? DEFAULT_DEFINITION_VERSION,
+        concurrency: resolveGraphConcurrency(def.concurrency),
+    };
+    topologicalSort(definition.nodes, workflowEdges(definition));
+    for (const node of definition.nodes) {
+        const failure = node.failure;
+        if (failure?.type === 'retry' &&
+            (!Number.isInteger(failure.maxAttempts) ||
+                failure.maxAttempts < 1 ||
+                failure.maxAttempts > 64)) {
+            throw new Error(`Node "${node.id}" retry maxAttempts must be between 1 and 64`);
+        }
+        if (failure?.type === 'fallback' &&
+            !definition.nodes.some((candidate) => candidate.id === failure.nodeId)) {
+            throw new Error(`Node "${node.id}" references unknown fallback "${failure.nodeId}"`);
+        }
+    }
+    return definition;
 }
 export function readyNodes(workflow, nodeStates) {
-    return workflow.nodes
-        .filter((node) => {
+    const states = {};
+    for (const node of workflow.nodes) {
         const state = nodeStates[node.id];
-        if (state && state.status !== 'pending') {
-            return false;
-        }
-        const deps = node.deps ?? [];
-        return deps.every((depId) => {
-            const dep = nodeStates[depId];
-            return dep?.status === 'completed' || dep?.status === 'skipped';
-        });
-    })
-        .map((node) => node.id);
+        states[node.id] = {
+            status: compatibleNodeStatus(state?.status),
+            result: null,
+            error: null,
+        };
+    }
+    return getReadyNodeIds(workflow, states);
+}
+function childRef(child) {
+    return {
+        kind: child.kind,
+        name: child.name,
+        version: child.version ?? DEFAULT_DEFINITION_VERSION,
+    };
+}
+function iterations(child, items, concurrency) {
+    return {
+        type: 'map',
+        ...childRef(child),
+        items,
+        concurrency: resolveGraphConcurrency(concurrency),
+    };
+}
+/** Builds the helpers a node's `run` uses to describe durable work. */
+export function nodeResultBuilders() {
+    return {
+        spawn: (child, input) => ({ type: 'spawn', ...childRef(child), input }),
+        sleep: (ms) => ({ type: 'sleep', ms }),
+        effects: (effects) => ({ type: 'effects', effects }),
+        map: (child, items) => iterations(child, items, 1),
+        fanout: (child, items, concurrency = DEFAULT_GRAPH_CONCURRENCY) => iterations(child, items, concurrency),
+        loop: (child, input, { maxIterations }) => {
+            if (!Number.isInteger(maxIterations) || maxIterations < 0) {
+                throw new Error('loop maxIterations must be a non-negative integer');
+            }
+            return { type: 'loop', ...childRef(child), input, maxIterations };
+        },
+    };
 }

package/dist/workflow/effects.d.ts

@@ -1,24 +1,114 @@
-import { Schema } from 'effect';
+import { Effect, Schema } from 'effect';
 import { type EventInputOf, type JsonValue } from '@swirls/looms/core';
-import { type WorkflowDefinition } from './definitions';
+import { type NodeState, type WorkflowDefinition } from './definitions';
 import { WorkflowDefinitionsTag } from './definitions-store';
 import { type WorkflowEvent } from './scope';
+type WorkflowEvents = EventInputOf<WorkflowEvent>[];
 export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").EffectDefinition<{
     readonly definitionName?: string | undefined;
+    readonly definitionVersion: string;
     readonly nodes?: {
         readonly [x: string]: {
             readonly status: "completed" | "failed" | "pending" | "running" | "skipped";
             readonly result: Schema.Json;
             readonly error: string | null;
+            readonly attempts?: number | undefined;
+            readonly branch?: string | undefined;
+            readonly skipCause?: "inactive" | "policy" | undefined;
+            readonly iteration?: {
+                readonly index: number;
+                readonly previous: Schema.Json;
+            } | undefined;
         };
     } | undefined;
     readonly input?: Schema.Json | undefined;
 }, WorkflowDefinitionsTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.ambiguous";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly error: string;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.attempt.started";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.cancel.requested";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.cancelled";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.completed";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.dispatched";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.failed";
     readonly payload: {
         readonly effectId: string;
         readonly error: string;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.heartbeat";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly heartbeatAt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.queued";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.retry.scheduled";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly nextAttemptAt: number;
+        readonly error: string;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.timed_out";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly timeout: string;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.worker.started";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.run.cancelled";
+    readonly payload: {
+        readonly reason?: string | undefined;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.run.completed";
     readonly payload: {
@@ -31,7 +121,9 @@ export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").Effect
         readonly rootThreadId?: string | undefined;
         readonly kind: string;
         readonly definitionName: string;
+        readonly definitionVersion: string;
         readonly input: Schema.Json;
+        readonly requestedThreadId?: string | null | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.signal.received";
@@ -45,6 +137,11 @@ export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").Effect
         readonly stateHash: string;
         readonly state?: Schema.Json | undefined;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.thread.cancel.requested";
+    readonly payload: {
+        readonly threadId: string;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.thread.cancelled";
     readonly payload: {
@@ -69,6 +166,7 @@ export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").Effect
         readonly threadId: string;
         readonly kind: string;
         readonly definitionName: string;
+        readonly definitionVersion: string;
         readonly input: Schema.Json;
         readonly parentThreadId: string | null;
     };
@@ -113,7 +211,75 @@ export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").Effect
     readonly type: "workflow.effects.requested";
     readonly payload: {
         readonly nodeId: string;
-        readonly effects: readonly import("@swirls/looms/core").RuntimeEffect[];
+        readonly effects: readonly ({
+            readonly type: "runtime.spawn";
+            readonly childThreadId: string;
+            readonly kind: string;
+            readonly definitionName: string;
+            readonly definitionVersion: string;
+            readonly input: Schema.Json;
+        } | {
+            readonly type: "runtime.wait";
+            readonly waitId: string;
+            readonly on: {
+                readonly type: string | readonly string[];
+                readonly match?: Schema.Json | undefined;
+            } | {
+                readonly timerAt: number;
+            };
+            readonly tag?: Schema.Json | undefined;
+        } | {
+            readonly type: "runtime.emit";
+            readonly event: {
+                readonly type: string;
+                readonly payload: Schema.Json;
+                readonly threadId?: string | null | undefined;
+                readonly parentThreadId?: string | null | undefined;
+                readonly causationId?: string | null | undefined;
+                readonly correlationId?: string | null | undefined;
+                readonly effectId?: string | null | undefined;
+                readonly origin?: {
+                    readonly type: "thread";
+                    readonly threadId: string;
+                } | {
+                    readonly type: "external";
+                    readonly actorId?: string | undefined;
+                } | {
+                    readonly type: "system";
+                } | undefined;
+                readonly ephemeral?: boolean | undefined;
+                readonly id?: string | undefined;
+                readonly ts?: number | undefined;
+                readonly idempotencyKey?: string | null | undefined;
+            };
+            readonly tag?: string | undefined;
+        } | {
+            readonly type: "runtime.complete";
+            readonly output: Schema.Json;
+        } | {
+            readonly type: "runtime.fail";
+            readonly error: string;
+        } | {
+            readonly type: "runtime.cancel";
+            readonly threadId: string;
+            readonly tag?: string | undefined;
+        } | {
+            readonly type: string;
+            readonly input: Schema.Json;
+            readonly tag?: string | undefined;
+        })[];
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "workflow.map.requested";
+    readonly payload: {
+        readonly nodeId: string;
+        readonly attempt: number;
+        readonly kind: string;
+        readonly definitionName: string;
+        readonly definitionVersion: string;
+        readonly items: readonly Schema.Json[];
+        readonly concurrency: number;
+        readonly limitBytes: number;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "workflow.node.finished";
@@ -121,12 +287,14 @@ export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").Effect
         readonly nodeId: string;
         readonly result: Schema.Json;
         readonly error: string | null;
+        readonly branch?: string | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "workflow.node.skipped";
     readonly payload: {
         readonly nodeId: string;
         readonly reason: string;
+        readonly cause: "inactive" | "policy";
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "workflow.node.started";
@@ -144,34 +312,130 @@ export declare const scheduleEffect: NoInfer<import("@swirls/looms/core").Effect
     readonly type: "workflow.spawn.requested";
     readonly payload: {
         readonly nodeId: string;
+        readonly attempt: number;
         readonly childThreadId: string;
         readonly kind: string;
         readonly definitionName: string;
+        readonly definitionVersion: string;
         readonly input: Schema.Json;
+        readonly loopIndex: number | null;
     };
 })>>;
 export declare function scheduleEvents(definition: WorkflowDefinition, binding: {
-    nodes: {
-        [id: string]: {
-            status: string;
-            result: JsonValue | null;
-        };
-    };
+    nodes: Record<string, NodeState>;
     input: JsonValue;
-}, threadId: string): EventInputOf<WorkflowEvent>[];
+}, threadId: string): Effect.Effect<WorkflowEvents>;
 export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectDefinition<{
     readonly definitionName?: string | undefined;
+    readonly definitionVersion: string;
     readonly nodeId: string;
+    readonly attempt: number;
+    readonly iteration?: {
+        readonly index: number;
+        readonly previous: Schema.Json;
+    } | undefined;
     readonly input?: Schema.Json | undefined;
-    readonly results?: {
-        readonly [x: string]: Schema.Json;
+    readonly nodes?: {
+        readonly [x: string]: {
+            readonly status: "completed" | "failed" | "pending" | "running" | "skipped";
+            readonly result: Schema.Json;
+            readonly error: string | null;
+            readonly attempts?: number | undefined;
+            readonly branch?: string | undefined;
+            readonly skipCause?: "inactive" | "policy" | undefined;
+            readonly iteration?: {
+                readonly index: number;
+                readonly previous: Schema.Json;
+            } | undefined;
+        };
     } | undefined;
 }, WorkflowDefinitionsTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.ambiguous";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly error: string;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.attempt.started";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.cancel.requested";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.cancelled";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.completed";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.dispatched";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.failed";
     readonly payload: {
         readonly effectId: string;
         readonly error: string;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.heartbeat";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly heartbeatAt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.queued";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.retry.scheduled";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly nextAttemptAt: number;
+        readonly error: string;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.timed_out";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly timeout: string;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.effect.worker.started";
+    readonly payload: {
+        readonly effectId: string;
+        readonly attempt: number;
+        readonly deadlineAt: number | null;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.run.cancelled";
+    readonly payload: {
+        readonly reason?: string | undefined;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.run.completed";
     readonly payload: {
@@ -184,7 +448,9 @@ export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly rootThreadId?: string | undefined;
         readonly kind: string;
         readonly definitionName: string;
+        readonly definitionVersion: string;
         readonly input: Schema.Json;
+        readonly requestedThreadId?: string | null | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.signal.received";
@@ -198,6 +464,11 @@ export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly stateHash: string;
         readonly state?: Schema.Json | undefined;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.thread.cancel.requested";
+    readonly payload: {
+        readonly threadId: string;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.thread.cancelled";
     readonly payload: {
@@ -222,6 +493,7 @@ export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly threadId: string;
         readonly kind: string;
         readonly definitionName: string;
+        readonly definitionVersion: string;
         readonly input: Schema.Json;
         readonly parentThreadId: string | null;
     };
@@ -266,7 +538,75 @@ export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectD
     readonly type: "workflow.effects.requested";
     readonly payload: {
         readonly nodeId: string;
-        readonly effects: readonly import("@swirls/looms/core").RuntimeEffect[];
+        readonly effects: readonly ({
+            readonly type: "runtime.spawn";
+            readonly childThreadId: string;
+            readonly kind: string;
+            readonly definitionName: string;
+            readonly definitionVersion: string;
+            readonly input: Schema.Json;
+        } | {
+            readonly type: "runtime.wait";
+            readonly waitId: string;
+            readonly on: {
+                readonly type: string | readonly string[];
+                readonly match?: Schema.Json | undefined;
+            } | {
+                readonly timerAt: number;
+            };
+            readonly tag?: Schema.Json | undefined;
+        } | {
+            readonly type: "runtime.emit";
+            readonly event: {
+                readonly type: string;
+                readonly payload: Schema.Json;
+                readonly threadId?: string | null | undefined;
+                readonly parentThreadId?: string | null | undefined;
+                readonly causationId?: string | null | undefined;
+                readonly correlationId?: string | null | undefined;
+                readonly effectId?: string | null | undefined;
+                readonly origin?: {
+                    readonly type: "thread";
+                    readonly threadId: string;
+                } | {
+                    readonly type: "external";
+                    readonly actorId?: string | undefined;
+                } | {
+                    readonly type: "system";
+                } | undefined;
+                readonly ephemeral?: boolean | undefined;
+                readonly id?: string | undefined;
+                readonly ts?: number | undefined;
+                readonly idempotencyKey?: string | null | undefined;
+            };
+            readonly tag?: string | undefined;
+        } | {
+            readonly type: "runtime.complete";
+            readonly output: Schema.Json;
+        } | {
+            readonly type: "runtime.fail";
+            readonly error: string;
+        } | {
+            readonly type: "runtime.cancel";
+            readonly threadId: string;
+            readonly tag?: string | undefined;
+        } | {
+            readonly type: string;
+            readonly input: Schema.Json;
+            readonly tag?: string | undefined;
+        })[];
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "workflow.map.requested";
+    readonly payload: {
+        readonly nodeId: string;
+        readonly attempt: number;
+        readonly kind: string;
+        readonly definitionName: string;
+        readonly definitionVersion: string;
+        readonly items: readonly Schema.Json[];
+        readonly concurrency: number;
+        readonly limitBytes: number;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "workflow.node.finished";
@@ -274,12 +614,14 @@ export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly nodeId: string;
         readonly result: Schema.Json;
         readonly error: string | null;
+        readonly branch?: string | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "workflow.node.skipped";
     readonly payload: {
         readonly nodeId: string;
         readonly reason: string;
+        readonly cause: "inactive" | "policy";
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "workflow.node.started";
@@ -297,9 +639,13 @@ export declare const runNodeEffect: NoInfer<import("@swirls/looms/core").EffectD
     readonly type: "workflow.spawn.requested";
     readonly payload: {
         readonly nodeId: string;
+        readonly attempt: number;
         readonly childThreadId: string;
         readonly kind: string;
         readonly definitionName: string;
+        readonly definitionVersion: string;
         readonly input: Schema.Json;
+        readonly loopIndex: number | null;
     };
 })>>;
+export {};