@swirls/looms 0.0.2 → 0.2.0

package/dist/workflow/events.js

@@ -1,5 +1,5 @@
-import { Schema } from 'effect';
-import { defineEventCatalog } from '@swirls/looms/core';
+import { Effect, Schema } from 'effect';
+import { DEFAULT_DEFINITION_VERSION, defineEventCatalog, RuntimeEffectSchema } from '@swirls/looms/core';
 export const WorkflowNodeStartedPayloadSchema = Schema.Struct({
     nodeId: Schema.String,
 });
@@ -7,33 +7,55 @@ export const WorkflowNodeFinishedPayloadSchema = Schema.Struct({
     nodeId: Schema.String,
     result: Schema.NullOr(Schema.Json),
     error: Schema.NullOr(Schema.String),
+    branch: Schema.optional(Schema.String),
 });
+export const WorkflowSkipCauseSchema = Schema.Union([
+    Schema.Literal('inactive'),
+    Schema.Literal('policy'),
+]);
 export const WorkflowNodeSkippedPayloadSchema = Schema.Struct({
     nodeId: Schema.String,
     reason: Schema.String,
+    cause: WorkflowSkipCauseSchema.pipe(Schema.withDecodingDefaultKey(Effect.succeed('inactive'))),
 });
+const attempt = Schema.Finite.pipe(Schema.withDecodingDefaultKey(Effect.succeed(1)));
+const definitionVersion = Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION)));
 export const WorkflowSpawnRequestedPayloadSchema = Schema.Struct({
     nodeId: Schema.String,
+    attempt,
     childThreadId: Schema.String,
     kind: Schema.String,
     definitionName: Schema.String,
+    definitionVersion,
     input: Schema.Json,
+    /** Set for `loop` iterations: the node re-runs after this child instead of finishing. */
+    loopIndex: Schema.NullOr(Schema.Finite).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null))),
+});
+export const WorkflowMapRequestedPayloadSchema = Schema.Struct({
+    nodeId: Schema.String,
+    attempt,
+    kind: Schema.String,
+    definitionName: Schema.String,
+    definitionVersion,
+    items: Schema.Array(Schema.Json),
+    concurrency: Schema.Finite,
+    limitBytes: Schema.Finite,
 });
 export const WorkflowSleepRequestedPayloadSchema = Schema.Struct({
     nodeId: Schema.String,
     waitId: Schema.String,
-    wakeAt: Schema.Number,
+    wakeAt: Schema.Finite,
 });
 export const WorkflowEffectsRequestedPayloadSchema = Schema.Struct({
     nodeId: Schema.String,
-    // SAFETY: RuntimeEffect represents serializable requested effect instructions.
-    effects: Schema.Array(Schema.Unknown),
+    effects: Schema.Array(RuntimeEffectSchema),
 });
 export const workflowCatalog = defineEventCatalog('workflow', {
     'node.started': WorkflowNodeStartedPayloadSchema,
     'node.finished': WorkflowNodeFinishedPayloadSchema,
     'node.skipped': WorkflowNodeSkippedPayloadSchema,
     'spawn.requested': WorkflowSpawnRequestedPayloadSchema,
+    'map.requested': WorkflowMapRequestedPayloadSchema,
     'sleep.requested': WorkflowSleepRequestedPayloadSchema,
     'effects.requested': WorkflowEffectsRequestedPayloadSchema,
 });

package/dist/workflow/graph.d.ts

@@ -0,0 +1,56 @@
+import { Effect } from 'effect';
+import { type JsonValue } from '@swirls/looms/core';
+import type { NodeState, WorkflowDefinition, WorkflowNodeDefinition } from './definitions';
+export declare const MIN_GRAPH_CONCURRENCY = 1;
+export declare const MAX_GRAPH_CONCURRENCY = 64;
+export declare const DEFAULT_GRAPH_CONCURRENCY = 8;
+export declare const DEFAULT_VALUE_SIZE_LIMIT_BYTES = 2000000;
+export declare const DEFAULT_CHECKPOINT_SIZE_LIMIT_BYTES = 4000000;
+declare const WorkflowValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WorkflowValidationError";
+} & Readonly<A>;
+export declare class WorkflowValidationError extends WorkflowValidationError_base<{
+    readonly message: string;
+}> {
+    constructor(message: string);
+}
+declare const WorkflowValueTooLargeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WorkflowValueTooLargeError";
+} & Readonly<A>;
+export declare class WorkflowValueTooLargeError extends WorkflowValueTooLargeError_base<{
+    readonly label: string;
+    readonly actualBytes: number;
+    readonly limitBytes: number;
+    readonly message: string;
+}> {
+    constructor(label: string, actualBytes: number, limitBytes: number);
+}
+export interface WorkflowEdge {
+    readonly sourceNodeId: string;
+    readonly targetNodeId: string;
+    /** For switch nodes, only the edge matching the returned branch is active. */
+    readonly label?: string;
+}
+export type GraphNodeStatuses = Record<string, NodeState['status']>;
+/** Distinguishes each attempt, and each loop iteration within it, of one node. */
+export declare function nodeRunKey(nodeId: string, attempt: number, iteration?: number): string;
+export declare function iterationChildWorkflowId(parentThreadId: string, nodeId: string, kind: 'map' | 'loop', attempt: number, index: number): string;
+export declare function nodeChildWorkflowId(parentThreadId: string, nodeId: string, attempt: number): string;
+export declare function assertJsonWithinLimit(value: JsonValue | Readonly<object>, label: string, limitBytes?: number): Effect.Effect<void, WorkflowValueTooLargeError>;
+export declare function resolveGraphConcurrency(value?: number): number;
+export declare function workflowEdges<TInput>(definition: WorkflowDefinition<string, TInput>): WorkflowEdge[];
+export declare function topologicalSort(nodes: readonly Pick<WorkflowNodeDefinition, 'id'>[], edges: readonly WorkflowEdge[]): string[];
+export declare function isEdgeActive(edge: WorkflowEdge, nodes: readonly Pick<WorkflowNodeDefinition, 'id' | 'type'>[], states: Readonly<Record<string, NodeState>>): boolean;
+export declare function getReadyNodeIds<TInput>(definition: WorkflowDefinition<string, TInput>, states: Readonly<Record<string, NodeState>>): string[];
+/**
+ * Nodes whose predecessors are settled but whose incoming paths are all inactive can be durably
+ * skipped. Repeating this function propagates skips.
+ */
+export declare function getSkippableNodeIds<TInput>(definition: WorkflowDefinition<string, TInput>, states: Readonly<Record<string, NodeState>>): string[];
+/** Fallback nodes whose primaries all settled without falling back will never run. */
+export declare function getUnusedFallbackIds<TInput>(definition: WorkflowDefinition<string, TInput>, states: Readonly<Record<string, NodeState>>): string[];
+/** Node results as dependents see them: a node that fell back reports its fallback's result. */
+export declare function nodeResults<TInput>(definition: WorkflowDefinition<string, TInput>, states: Readonly<Record<string, NodeState>>): {
+    [k: string]: import("effect/Schema").Json;
+};
+export {};

package/dist/workflow/graph.js

@@ -0,0 +1,207 @@
+import { Data, Effect } from 'effect';
+import { deterministicThreadId, isJsonString, utf8JsonBytes } from '@swirls/looms/core';
+export const MIN_GRAPH_CONCURRENCY = 1;
+export const MAX_GRAPH_CONCURRENCY = 64;
+export const DEFAULT_GRAPH_CONCURRENCY = 8;
+export const DEFAULT_VALUE_SIZE_LIMIT_BYTES = 2_000_000;
+export const DEFAULT_CHECKPOINT_SIZE_LIMIT_BYTES = 4_000_000;
+export class WorkflowValidationError extends Data.TaggedError('WorkflowValidationError') {
+    constructor(message) {
+        super({ message });
+    }
+}
+export class WorkflowValueTooLargeError extends Data.TaggedError('WorkflowValueTooLargeError') {
+    constructor(label, actualBytes, limitBytes) {
+        super({
+            label,
+            actualBytes,
+            limitBytes,
+            message: `${label} is ${actualBytes} UTF-8 bytes; limit is ${limitBytes} bytes`,
+        });
+    }
+}
+/** Distinguishes each attempt, and each loop iteration within it, of one node. */
+export function nodeRunKey(nodeId, attempt, iteration) {
+    return iteration === undefined ? `${nodeId}_${attempt}` : `${nodeId}_${attempt}_${iteration}`;
+}
+export function iterationChildWorkflowId(parentThreadId, nodeId, kind, attempt, index) {
+    return deterministicThreadId(parentThreadId, nodeId, kind, attempt, index);
+}
+export function nodeChildWorkflowId(parentThreadId, nodeId, attempt) {
+    return deterministicThreadId(parentThreadId, nodeId, 'workflow', attempt);
+}
+export function assertJsonWithinLimit(value, label, limitBytes = DEFAULT_VALUE_SIZE_LIMIT_BYTES) {
+    const actualBytes = utf8JsonBytes(value);
+    return actualBytes > limitBytes
+        ? Effect.fail(new WorkflowValueTooLargeError(label, actualBytes, limitBytes))
+        : Effect.void;
+}
+export function resolveGraphConcurrency(value) {
+    const concurrency = value ?? DEFAULT_GRAPH_CONCURRENCY;
+    if (!Number.isInteger(concurrency) ||
+        concurrency < MIN_GRAPH_CONCURRENCY ||
+        concurrency > MAX_GRAPH_CONCURRENCY) {
+        throw new WorkflowValidationError('Workflow concurrency must be an integer between 1 and 64');
+    }
+    return concurrency;
+}
+export function workflowEdges(definition) {
+    if (definition.edges) {
+        return [...definition.edges];
+    }
+    return definition.nodes.flatMap((node) => (node.deps ?? []).map((sourceNodeId) => ({ sourceNodeId, targetNodeId: node.id })));
+}
+export function topologicalSort(nodes, edges) {
+    const ids = new Set();
+    const inputOrder = new Map();
+    const indegree = new Map();
+    const outgoing = new Map();
+    nodes.forEach((node, index) => {
+        if (ids.has(node.id)) {
+            throw new WorkflowValidationError(`Duplicate workflow node: ${node.id}`);
+        }
+        ids.add(node.id);
+        inputOrder.set(node.id, index);
+        indegree.set(node.id, 0);
+        outgoing.set(node.id, []);
+    });
+    for (const edge of edges) {
+        if (!ids.has(edge.sourceNodeId)) {
+            throw new WorkflowValidationError(`Edge references non-existent source node: ${edge.sourceNodeId}`);
+        }
+        if (!ids.has(edge.targetNodeId)) {
+            throw new WorkflowValidationError(`Edge references non-existent target node: ${edge.targetNodeId}`);
+        }
+        outgoing.get(edge.sourceNodeId)?.push(edge.targetNodeId);
+        indegree.set(edge.targetNodeId, (indegree.get(edge.targetNodeId) ?? 0) + 1);
+    }
+    const ready = nodes.filter((node) => indegree.get(node.id) === 0).map((node) => node.id);
+    const sorted = [];
+    while (ready.length > 0) {
+        const nodeId = ready.shift();
+        if (nodeId === undefined) {
+            break;
+        }
+        sorted.push(nodeId);
+        for (const target of outgoing.get(nodeId) ?? []) {
+            const next = (indegree.get(target) ?? 0) - 1;
+            indegree.set(target, next);
+            if (next === 0) {
+                ready.push(target);
+                ready.sort((a, b) => (inputOrder.get(a) ?? 0) - (inputOrder.get(b) ?? 0));
+            }
+        }
+    }
+    if (sorted.length !== nodes.length) {
+        throw new WorkflowValidationError('Workflow contains a cycle');
+    }
+    return sorted;
+}
+function selectedBranch(state) {
+    if (state?.status !== 'completed') {
+        return undefined;
+    }
+    if (state.branch !== undefined) {
+        return state.branch;
+    }
+    return isJsonString(state.result) ? state.result : undefined;
+}
+export function isEdgeActive(edge, nodes, states) {
+    const state = states[edge.sourceNodeId];
+    if (state?.status === 'skipped') {
+        return state.skipCause === 'policy';
+    }
+    const source = nodes.find((node) => node.id === edge.sourceNodeId);
+    if (source?.type !== 'switch') {
+        return true;
+    }
+    const branch = selectedBranch(state);
+    return edge.label !== undefined && branch === edge.label;
+}
+/** The fallback node standing in for `node`, if its failure policy handed off to one. */
+function activeFallback(node, state) {
+    return node.failure?.type === 'fallback' &&
+        state?.status === 'skipped' &&
+        state.skipCause === 'policy'
+        ? node.failure.nodeId
+        : undefined;
+}
+/**
+ * A node is settled once dependents may observe it: completed, or skipped. A node that fell back
+ * stays unsettled until its fallback node completes, so dependents see the fallback's result.
+ */
+function isSettled(definition, states, nodeId) {
+    const state = states[nodeId];
+    if (state?.status === 'completed') {
+        return true;
+    }
+    if (state?.status !== 'skipped') {
+        return false;
+    }
+    const node = definition.nodes.find((candidate) => candidate.id === nodeId);
+    const fallback = node && activeFallback(node, state);
+    return fallback === undefined || isSettled(definition, states, fallback);
+}
+function fallbackTargets(definition) {
+    return new Set(definition.nodes.flatMap((node) => node.failure?.type === 'fallback' ? [node.failure.nodeId] : []));
+}
+export function getReadyNodeIds(definition, states) {
+    const edges = workflowEdges(definition);
+    const order = topologicalSort(definition.nodes, edges);
+    const fallbacks = fallbackTargets(definition);
+    return order.filter((nodeId) => {
+        if ((states[nodeId]?.status ?? 'pending') !== 'pending' || fallbacks.has(nodeId)) {
+            return false;
+        }
+        const incoming = edges.filter((edge) => edge.targetNodeId === nodeId);
+        if (incoming.length === 0) {
+            return true;
+        }
+        return (incoming.every((edge) => isSettled(definition, states, edge.sourceNodeId)) &&
+            incoming.some((edge) => isEdgeActive(edge, definition.nodes, states)));
+    });
+}
+/**
+ * Nodes whose predecessors are settled but whose incoming paths are all inactive can be durably
+ * skipped. Repeating this function propagates skips.
+ */
+export function getSkippableNodeIds(definition, states) {
+    const edges = workflowEdges(definition);
+    const order = topologicalSort(definition.nodes, edges);
+    return order.filter((nodeId) => {
+        if ((states[nodeId]?.status ?? 'pending') !== 'pending') {
+            return false;
+        }
+        const incoming = edges.filter((edge) => edge.targetNodeId === nodeId);
+        if (incoming.length === 0) {
+            return false;
+        }
+        return (incoming.every((edge) => isSettled(definition, states, edge.sourceNodeId)) &&
+            !incoming.some((edge) => isEdgeActive(edge, definition.nodes, states)));
+    });
+}
+/** Fallback nodes whose primaries all settled without falling back will never run. */
+export function getUnusedFallbackIds(definition, states) {
+    return [...fallbackTargets(definition)].filter((target) => {
+        if ((states[target]?.status ?? 'pending') !== 'pending') {
+            return false;
+        }
+        const primaries = definition.nodes.filter((node) => node.failure?.type === 'fallback' && node.failure.nodeId === target);
+        return primaries.every((node) => {
+            const state = states[node.id];
+            const status = state?.status;
+            return (status === 'completed' || status === 'skipped') && !activeFallback(node, state);
+        });
+    });
+}
+/** Node results as dependents see them: a node that fell back reports its fallback's result. */
+export function nodeResults(definition, states) {
+    const results = Object.fromEntries(Object.entries(states).map(([id, state]) => [id, state.result]));
+    for (const node of definition.nodes) {
+        const fallback = activeFallback(node, states[node.id]);
+        if (fallback !== undefined) {
+            results[node.id] = states[fallback]?.result ?? null;
+        }
+    }
+    return results;
+}

package/dist/workflow/index.d.ts

@@ -6,3 +6,4 @@ export * from './threads';
 export * from './effects';
 export * from './projections';
 export * from './module';
+export * from './graph';

package/dist/workflow/index.js

@@ -6,3 +6,4 @@ export * from './threads.js';
 export * from './effects.js';
 export * from './projections.js';
 export * from './module.js';
+export * from './graph.js';