@swirls/looms 0.0.2 → 0.1.0

package/dist/s2/store.js

@@ -1,7 +1,8 @@
 import { AppendInput, AppendRecord, S2, S2Endpoints, S2Error } from '@s2-dev/streamstore';
-import { Effect, Layer, Option, Predicate, Queue, Schema, Stream } from 'effect';
-import { createKeyedSerializer, EventStoreConflictError, EventStoreError, EventStoreFencedError, EventStoreTag, EventEnvelopeSchema, fromWireEvent, withSnapshotStore, } from '@swirls/looms/core';
+import { DateTime, Effect, Layer, Predicate, Schema, Stream } from 'effect';
+import { createKeyedSerializer, assertEventByteLimits, EventStoreConflictError, EventStoreError, EventStoreFencedError, EventPayloadTooLargeError, EventStoreTag, EventEnvelopeSchema, fromWireEvent, withSnapshotStore, } from '@swirls/looms/core';
 import { S2ConfigSchema, streamNameForRun } from './config.js';
+import { paginateS2Stream } from './pagination.js';
 import { s2SnapshotStore } from './snapshot-store.js';
 function toStoreError(cause, message) {
     if (cause instanceof EventStoreError) {
@@ -20,50 +21,8 @@ function isUnsatisfiableCause(cause) {
     const text = cause instanceof Error ? cause.message : String(cause);
     return text.includes('out of range') || text.includes('Range not satisfiable');
 }
-/**
- * Paginate an S2 stream lazily using Effect Streams.
- *
- * Pulls pages on demand until the stream tail is reached, an empty page is returned,
- * or the caller's optional limit is satisfied.
- */
-export function paginateS2Stream(fetchPage, options) {
-    const fromSeq = options?.fromSeq ?? 0;
-    const userLimit = options?.limit;
-    const maxPageSize = options?.maxPageSize ?? 1000;
-    if (userLimit !== undefined && userLimit <= 0) {
-        return Stream.empty;
-    }
-    const baseStream = Stream.paginate({ cursor: fromSeq, remaining: userLimit }, (state) => Effect.gen(function* () {
-        if (state.remaining !== undefined && state.remaining <= 0) {
-            return [[], Option.none()];
-        }
-        const count = state.remaining !== undefined ? Math.min(maxPageSize, state.remaining) : maxPageSize;
-        const page = yield* fetchPage(state.cursor, count);
-        if (!page || page.records.length === 0) {
-            return [[], Option.none()];
-        }
-        const records = page.records.filter((r) => r.seqNum >= fromSeq);
-        const nextRemaining = state.remaining !== undefined ? state.remaining - records.length : undefined;
-        const lastRecord = page.records[page.records.length - 1];
-        if (!lastRecord || (nextRemaining !== undefined && nextRemaining <= 0)) {
-            return [records, Option.none()];
-        }
-        const nextCursor = Math.max(state.cursor + 1, lastRecord.seqNum + 1);
-        if (nextCursor <= state.cursor) {
-            return [records, Option.none()];
-        }
-        // A byte-capped page is shorter than `count`. Do not trust `page.tail`
-        // there — S2 may report the batch end, not the stream tail.
-        const shortPage = page.records.length < count;
-        const reachedTail = !shortPage && page.tail?.seqNum !== undefined && nextCursor >= page.tail.seqNum;
-        if (reachedTail) {
-            return [records, Option.none()];
-        }
-        return [records, Option.some({ cursor: nextCursor, remaining: nextRemaining })];
-    }));
-    return userLimit !== undefined ? baseStream.pipe(Stream.take(userLimit)) : baseStream;
-}
-export async function readAllPages(fetchPage, options) {
+export { paginateS2Stream };
+export function readAllPages(fetchPage, options) {
     const fetchPageEffect = (cursor, count) => Effect.tryPromise({
         try: () => fetchPage(cursor, count),
         catch: (cause) => toStoreError(cause, 'S2 page fetch failed'),
@@ -101,61 +60,49 @@ function createClient(config) {
  * Expected tail mismatches during `append` map to `EventStoreConflictError`.
  */
 export function s2(config) {
-    const parsed = Schema.decodeUnknownSync(S2ConfigSchema)(config);
+    const parsed = Schema.decodeSync(S2ConfigSchema)(config);
     const client = createClient(parsed);
     const basin = client.basin(parsed.basin);
     const ensured = new Set();
     const appends = createKeyedSerializer();
     let basinEnsured = false;
-    const ensureBasin = Effect.tryPromise({
-        try: async () => {
-            if (basinEnsured) {
-                return;
-            }
-            try {
-                await client.basins.create({ basin: parsed.basin });
-            }
-            catch (err) {
-                // 409 = already exists
-                if (!(err instanceof S2Error && err.status === 409)) {
-                    throw err;
-                }
-            }
+    const ensureBasin = Effect.suspend(() => {
+        if (basinEnsured) {
+            return Effect.void;
+        }
+        return Effect.tryPromise({
+            try: () => client.basins.create({ basin: parsed.basin }),
+            catch: (cause) => toStoreError(cause, `Failed to ensure basin ${parsed.basin}`),
+        }).pipe(Effect.catchIf((error) => error.cause instanceof S2Error && error.cause.status === 409, () => Effect.void), Effect.tap(() => Effect.sync(() => {
             basinEnsured = true;
-        },
-        catch: (cause) => toStoreError(cause, `Failed to ensure basin ${parsed.basin}`),
+        })), Effect.asVoid);
     });
     const ensureStream = (runId) => Effect.gen(function* () {
         yield* ensureBasin;
-        return yield* Effect.tryPromise({
-            try: async () => {
-                const name = streamNameForRun(runId);
-                if (ensured.has(name)) {
-                    return basin.stream(name);
-                }
-                try {
-                    await basin.streams.create({
-                        stream: name,
-                        config: parsed.streamConfig,
-                    });
-                }
-                catch (err) {
-                    // 409 = already exists
-                    if (!(err instanceof S2Error && err.status === 409)) {
-                        // Some local servers may not support create; try using the stream anyway.
-                        if (!(err instanceof S2Error && (err.status === 404 || err.status === 405))) {
-                            throw err;
-                        }
-                    }
-                }
-                ensured.add(name);
-                return basin.stream(name);
-            },
-            catch: (cause) => toStoreError(cause, `Failed to open stream for ${runId}`),
-        });
+        const name = streamNameForRun(runId);
+        if (!ensured.has(name)) {
+            yield* Effect.tryPromise({
+                try: () => basin.streams.create({
+                    stream: name,
+                    config: parsed.streamConfig,
+                }),
+                catch: (cause) => toStoreError(cause, `Failed to open stream for ${runId}`),
+            }).pipe(Effect.catchIf((error) => error.cause instanceof S2Error &&
+                (error.cause.status === 409 ||
+                    error.cause.status === 404 ||
+                    error.cause.status === 405), () => Effect.void));
+            ensured.add(name);
+        }
+        return basin.stream(name);
     });
     const service = {
         append: (runId, events, options) => Effect.gen(function* () {
+            yield* Effect.try({
+                try: () => assertEventByteLimits(runId, events),
+                catch: (cause) => cause instanceof EventPayloadTooLargeError
+                    ? cause
+                    : new EventStoreError('event size validation failed', cause),
+            });
             if (events.length === 0 && options?.fence === undefined) {
                 const tail = yield* service.tail(runId);
                 return { sequences: [], tail };
@@ -186,7 +133,7 @@ export function s2(config) {
                     cause.status === 412 &&
                     (message.includes('fenc') || message.includes('token'));
                 if (isFence) {
-                    return yield* Effect.fail(new EventStoreFencedError(runId, options?.fencingToken ?? options?.fence ?? ''));
+                    return yield* new EventStoreFencedError(runId, options?.fencingToken ?? options?.fence ?? '');
                 }
                 if (cause instanceof S2Error &&
                     (cause.status === 409 ||
@@ -195,9 +142,9 @@ export function s2(config) {
                         message.includes('match'))) {
                     const tailCheck = yield* Effect.promise(() => stream.checkTail().catch(() => null));
                     const actualTail = tailCheck?.tail?.seqNum ?? 0;
-                    return yield* Effect.fail(new EventStoreConflictError(runId, options?.expectedTail ?? 0, actualTail));
+                    return yield* new EventStoreConflictError(runId, options?.expectedTail ?? 0, actualTail);
                 }
-                return yield* Effect.fail(toStoreError(cause, `Append failed for ${runId}`));
+                return yield* toStoreError(cause, `Append failed for ${runId}`);
             }
             const ack = appendResult.ack;
             const sequences = [];
@@ -213,23 +160,13 @@ export function s2(config) {
             return Stream.unwrap(Effect.gen(function* () {
                 const stream = yield* ensureStream(runId);
                 const fetchPage = (cursor, count) => Effect.tryPromise({
-                    try: async () => {
-                        try {
-                            return await stream.read({
-                                start: { from: { seqNum: cursor }, clamp: true },
-                                stop: { limits: { count } },
-                                ignoreCommandRecords: true,
-                            });
-                        }
-                        catch (cause) {
-                            if (isUnsatisfiableCause(cause)) {
-                                return null;
-                            }
-                            throw cause;
-                        }
-                    },
+                    try: () => stream.read({
+                        start: { from: { seqNum: cursor }, clamp: true },
+                        stop: { limits: { count } },
+                        ignoreCommandRecords: true,
+                    }),
                     catch: (cause) => toStoreError(cause, `Read failed for ${runId}`),
-                });
+                }).pipe(Effect.catchIf((error) => isUnsatisfiableCause(error.cause), () => Effect.succeed(null)));
                 const recordStream = paginateS2Stream(fetchPage, {
                     fromSeq: s2From,
                     limit: options?.limit,
@@ -246,31 +183,21 @@ export function s2(config) {
             const res = yield* Effect.tryPromise({
                 try: () => stream.checkTail(),
                 catch: (cause) => toStoreError(cause, `Tail failed for ${runId}`),
-            }).pipe(Effect.catch((err) => err.cause instanceof S2Error && err.cause.status === 404
-                ? Effect.succeed({ tail: { seqNum: 0, timestamp: new Date(0) } })
-                : Effect.fail(err)));
+            }).pipe(Effect.catchIf((err) => err.cause instanceof S2Error && err.cause.status === 404, () => Effect.succeed({
+                tail: { seqNum: 0, timestamp: DateTime.toDateUtc(DateTime.makeUnsafe(0)) },
+            })));
             return res.tail.seqNum;
         }),
         bounds: (runId) => Effect.gen(function* () {
             const stream = yield* ensureStream(runId);
             const page = yield* Effect.tryPromise({
-                try: async () => {
-                    try {
-                        return await stream.read({
-                            start: { from: { seqNum: 0 }, clamp: true },
-                            stop: { limits: { count: 1 } },
-                            ignoreCommandRecords: false,
-                        });
-                    }
-                    catch (cause) {
-                        if (isUnsatisfiableCause(cause)) {
-                            return null;
-                        }
-                        throw cause;
-                    }
-                },
+                try: () => stream.read({
+                    start: { from: { seqNum: 0 }, clamp: true },
+                    stop: { limits: { count: 1 } },
+                    ignoreCommandRecords: false,
+                }),
                 catch: (cause) => toStoreError(cause, `Bounds failed for ${runId}`),
-            });
+            }).pipe(Effect.catchIf((error) => isUnsatisfiableCause(error.cause), () => Effect.succeed(null)));
             const tail = page?.tail?.seqNum ?? 0;
             const first = page?.records[0];
             const head = first ? first.seqNum + 1 : tail + 1;
@@ -284,49 +211,28 @@ export function s2(config) {
                 catch: (cause) => toStoreError(cause, `Trim failed for ${runId}`),
             });
         }),
-        subscribe: (runId, options) => Stream.callback((queue) => Effect.callback((resume) => {
+        subscribe: (runId, options) => {
             const fromSeq = options?.fromSeq ?? 1;
             const s2From = Math.max(0, fromSeq - 1);
-            let stopped = false;
-            const run = async () => {
-                try {
-                    const stream = await Effect.runPromise(ensureStream(runId));
-                    const session = await stream.readSession({
+            return Stream.unwrap(Effect.gen(function* () {
+                const stream = yield* ensureStream(runId);
+                const session = yield* Effect.tryPromise({
+                    try: () => stream.readSession({
                         start: { from: { seqNum: s2From }, clamp: true },
                         ignoreCommandRecords: true,
-                    });
-                    for await (const record of session) {
-                        if (stopped) {
-                            break;
-                        }
-                        if (record.seqNum < s2From) {
-                            continue;
-                        }
-                        Queue.offerUnsafe(queue, parseEvent(record.body, record.seqNum));
-                    }
-                    Queue.endUnsafe(queue);
-                    resume(Effect.void);
-                }
-                catch (cause) {
-                    await Effect.runPromise(Queue.fail(queue, toStoreError(cause, `Subscribe failed for ${runId}`)));
-                    resume(Effect.void);
-                }
-            };
-            void run();
-            return Effect.sync(() => {
-                stopped = true;
-            });
-        })),
-        listRuns: () => Effect.tryPromise({
-            try: async () => {
-                const listed = await basin.streams.list({ prefix: 'runs/' });
-                return listed.streams
-                    .map((s) => s.name)
-                    .filter((name) => name.startsWith('runs/'))
-                    .map((name) => name.slice('runs/'.length));
-            },
+                    }),
+                    catch: (cause) => toStoreError(cause, `Subscribe failed for ${runId}`),
+                });
+                return Stream.fromAsyncIterable(session, (cause) => toStoreError(cause, `Subscribe failed for ${runId}`)).pipe(Stream.filter((record) => record.seqNum >= s2From), Stream.map((record) => parseEvent(record.body, record.seqNum)));
+            }));
+        },
+        listRuns: Effect.tryPromise({
+            try: () => basin.streams.list({ prefix: 'runs/' }),
             catch: (cause) => toStoreError(cause, 'listRuns failed'),
-        }),
+        }).pipe(Effect.map((listed) => listed.streams
+            .map((stream) => stream.name)
+            .filter((name) => name.startsWith('runs/'))
+            .map((name) => name.slice('runs/'.length)))),
     };
     return withSnapshotStore(service, s2SnapshotStore(parsed));
 }

package/dist/testing/index.d.ts

@@ -9,3 +9,18 @@ export interface TestRuntime {
 export declare function createTestRuntime(modules: readonly AnyRuntimeModule[]): Promise<TestRuntime>;
 export declare function assertReplayDeterministic(test: TestRuntime, runId: string): Promise<void>;
 export declare function moduleConformance(module: AnyRuntimeModule): string[];
+export type EventStoreFaultOperation = 'append' | 'read' | 'tail' | 'bounds' | 'trim' | 'listRuns';
+export interface EventStoreFaultContext {
+    readonly operation: EventStoreFaultOperation;
+    readonly runId: string | null;
+    readonly call: number;
+}
+export interface FaultInjectingEventStore {
+    readonly store: EventStore;
+    readonly calls: ReadonlyMap<EventStoreFaultOperation, number>;
+}
+/**
+ * Wraps an EventStore with deterministic delay/failure injection. Throw from
+ * `before` to fail a call, or await inside it to pause a race at an exact store boundary.
+ */
+export declare function createFaultInjectingEventStore(source: EventStore, before: (context: EventStoreFaultContext) => void | Promise<void>): FaultInjectingEventStore;

package/dist/testing/index.js

@@ -1,5 +1,5 @@
 import { Effect, Predicate } from 'effect';
-import { composeModules, EventStoreTag, foldRun, makeMemoryEventStore, ModuleCompositionError, } from '@swirls/looms/core';
+import { composeModules, EventStoreTag, foldRun, makeMemoryEventStore, ModuleCompositionError, EventStoreError, snapshotStoreOf, stringifyJson, withSnapshotStore, } from '@swirls/looms/core';
 import { createRuntime } from '@swirls/looms/runtime';
 function namedEffects(effects) {
     const listed = [];
@@ -15,22 +15,24 @@ function namedEffects(effects) {
     }
     return listed;
 }
-export async function createTestRuntime(modules) {
-    const store = await Effect.runPromise(makeMemoryEventStore);
-    const runtime = createRuntime({ modules, store });
-    return {
-        runtime,
-        store,
-        run: (effect) => Effect.runPromise(Effect.provideService(effect, EventStoreTag, store)),
-    };
+export function createTestRuntime(modules) {
+    return Effect.runPromise(makeMemoryEventStore.pipe(Effect.map((store) => {
+        const runtime = createRuntime({ modules, store });
+        return {
+            runtime,
+            store,
+            run: (effect) => Effect.runPromise(Effect.provideService(effect, EventStoreTag, store)),
+        };
+    })));
 }
-export async function assertReplayDeterministic(test, runId) {
-    const events = await test.run(test.runtime.getEvents(runId));
-    const first = foldRun(events, test.runtime.registry, { runId });
-    const second = foldRun(events, test.runtime.registry, { runId });
-    if (JSON.stringify(first) !== JSON.stringify(second)) {
-        throw new Error(`Replay is not deterministic for run ${runId}`);
-    }
+export function assertReplayDeterministic(test, runId) {
+    return test.run(test.runtime.getEvents(runId)).then((events) => {
+        const first = foldRun(events, test.runtime.registry, { runId });
+        const second = foldRun(events, test.runtime.registry, { runId });
+        if (stringifyJson(first) !== stringifyJson(second)) {
+            throw new Error(`Replay is not deterministic for run ${runId}`);
+        }
+    });
 }
 export function moduleConformance(module) {
     const errors = [];
@@ -61,3 +63,38 @@ export function moduleConformance(module) {
     }
     return errors;
 }
+/**
+ * Wraps an EventStore with deterministic delay/failure injection. Throw from
+ * `before` to fail a call, or await inside it to pause a race at an exact store boundary.
+ */
+export function createFaultInjectingEventStore(source, before) {
+    const calls = new Map();
+    const inject = (operation, runId) => Effect.tryPromise({
+        try: () => {
+            const call = (calls.get(operation) ?? 0) + 1;
+            calls.set(operation, call);
+            return Promise.resolve(before({ operation, runId, call }));
+        },
+        catch: (cause) => cause instanceof EventStoreError
+            ? cause
+            : new EventStoreError(`Injected ${operation} fault`, cause),
+    });
+    const store = {
+        append: (runId, events, options) => inject('append', runId).pipe(Effect.andThen(source.append(runId, events, options))),
+        read: (runId, options) => inject('read', runId).pipe(Effect.andThen(source.read(runId, options))),
+        tail: (runId) => inject('tail', runId).pipe(Effect.andThen(source.tail(runId))),
+        subscribe: source.subscribe,
+        listRuns: inject('listRuns', null).pipe(Effect.andThen(source.listRuns)),
+    };
+    if (source.bounds) {
+        store.bounds = (runId) => inject('bounds', runId).pipe(Effect.andThen(source.bounds(runId)));
+    }
+    if (source.trim) {
+        store.trim = (runId, beforeSeq) => inject('trim', runId).pipe(Effect.andThen(source.trim(runId, beforeSeq)));
+    }
+    const snapshots = snapshotStoreOf(source);
+    if (snapshots) {
+        withSnapshotStore(store, snapshots);
+    }
+    return { store, calls };
+}

package/dist/workflow/definitions-store.d.ts

@@ -1,8 +1,7 @@
 import { Context, Layer } from 'effect';
+import { type DefinitionStore } from '@swirls/looms/core';
 import type { WorkflowDefinition } from './definitions';
-export interface WorkflowDefinitionStore {
-    get(name: string): WorkflowDefinition | undefined;
-}
+export type WorkflowDefinitionStore = DefinitionStore<WorkflowDefinition>;
 declare const WorkflowDefinitionsTag_base: Context.ServiceClass<WorkflowDefinitionsTag, "looms/WorkflowDefinitions", WorkflowDefinitionStore>;
 export declare class WorkflowDefinitionsTag extends WorkflowDefinitionsTag_base {
 }

package/dist/workflow/definitions-store.js

@@ -1,8 +1,8 @@
 import { Context, Layer } from 'effect';
+import { makeDefinitionStore } from '@swirls/looms/core';
 export class WorkflowDefinitionsTag extends Context.Service()('looms/WorkflowDefinitions') {
 }
 export function makeWorkflowDefinitionStore(definitions) {
-    const map = new Map(definitions.map((def) => [def.name, def]));
-    return { get: (name) => map.get(name) };
+    return makeDefinitionStore('workflow', definitions);
 }
 export const WorkflowDefinitionsLive = (definitions) => Layer.succeed(WorkflowDefinitionsTag, makeWorkflowDefinitionStore(definitions));

package/dist/workflow/definitions.d.ts

@@ -1,14 +1,34 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { Schema } from 'effect';
-import type { InferDefinedSchema, JsonValue, RuntimeEffect } from '@swirls/looms/core';
+import { type JsonValue, type RuntimeEffect } from '@swirls/looms/core';
+import { type WorkflowEdge } from './graph';
 export declare const NodeStatusSchema: Schema.Union<readonly [Schema.Literal<"pending">, Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"skipped">]>;
 export type NodeStatus = Schema.Schema.Type<typeof NodeStatusSchema>;
 export declare const NodeStateSchema: Schema.Struct<{
     readonly status: Schema.Union<readonly [Schema.Literal<"pending">, Schema.Literal<"running">, Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"skipped">]>;
     readonly result: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     readonly error: Schema.NullOr<Schema.String>;
+    readonly attempts: Schema.optional<Schema.Finite>;
+    readonly branch: Schema.optional<Schema.String>;
+    /** Policy skips (skip/fallback) still satisfy dependents; inactive skips propagate. */
+    readonly skipCause: Schema.optional<Schema.Union<readonly [Schema.Literal<"inactive">, Schema.Literal<"policy">]>>;
+    readonly iteration: Schema.optional<Schema.Struct<{
+        readonly index: Schema.Finite;
+        readonly previous: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>;
 }>;
 export type NodeState = Schema.Schema.Type<typeof NodeStateSchema>;
+export interface WorkflowChild {
+    readonly kind: string;
+    readonly name: string;
+    readonly version?: string;
+}
+export interface WorkflowIteration {
+    /** Zero-based index of the loop iteration about to run. */
+    readonly index: number;
+    /** Output of the previous iteration's child. */
+    readonly previous: JsonValue;
+}
 export interface WorkflowNodeContext<TInput = JsonValue> {
     readonly threadId: string;
     readonly nodeId: string;
@@ -16,12 +36,22 @@ export interface WorkflowNodeContext<TInput = JsonValue> {
     readonly results: {
         [nodeId: string]: JsonValue | null;
     };
-    spawn(child: {
-        kind: string;
-        name: string;
-    }, input: JsonValue): NodeResult;
+    /** Set when a `loop` node is re-run after one of its iterations completed. */
+    readonly iteration: WorkflowIteration | undefined;
+    spawn(child: WorkflowChild, input: JsonValue): NodeResult;
     sleep(ms: number): NodeResult;
     effects(effects: RuntimeEffect[]): NodeResult;
+    /** Run one child per item, one at a time, and finish with the ordered outputs. */
+    map(child: WorkflowChild, items: readonly JsonValue[]): NodeResult;
+    /** Run one child per item with bounded concurrency and finish with the ordered outputs. */
+    fanout(child: WorkflowChild, items: readonly JsonValue[], concurrency?: number): NodeResult;
+    /**
+     * Run one child iteration, then re-run this node with `ctx.iteration`. Returning a value
+     * instead ends the loop; reaching `maxIterations` ends it with the last iteration's output.
+     */
+    loop(child: WorkflowChild, input: JsonValue, options: {
+        maxIterations: number;
+    }): NodeResult;
 }
 export type NodeResult = {
     type: 'value';
@@ -30,26 +60,64 @@ export type NodeResult = {
     type: 'spawn';
     kind: string;
     name: string;
+    version: string;
     input: JsonValue;
+    childThreadId?: string;
 } | {
     type: 'sleep';
     ms: number;
 } | {
     type: 'effects';
     effects: RuntimeEffect[];
+} | {
+    type: 'switch';
+    branch: string;
+    value?: JsonValue;
+} | {
+    type: 'map';
+    kind: string;
+    name: string;
+    version: string;
+    items: readonly JsonValue[];
+    concurrency: number;
+} | {
+    type: 'loop';
+    kind: string;
+    name: string;
+    version: string;
+    input: JsonValue;
+    maxIterations: number;
+};
+export type WorkflowFailurePolicy = {
+    readonly type: 'fail';
+} | {
+    readonly type: 'skip';
+} | {
+    readonly type: 'retry';
+    readonly maxAttempts: number;
+} | {
+    readonly type: 'fallback';
+    readonly nodeId: string;
 };
 export interface WorkflowNodeDefinition<TInput = JsonValue> {
     id: string;
     deps?: string[];
+    type?: 'task' | 'switch' | 'workflow';
+    failure?: WorkflowFailurePolicy;
     run(ctx: WorkflowNodeContext<TInput>): Promise<JsonValue | NodeResult> | JsonValue | NodeResult;
 }
 export interface WorkflowDefinition<TName extends string = string, TInput = JsonValue, TOutput extends JsonValue = JsonValue> {
     readonly kind: 'workflow';
     readonly name: TName;
+    readonly version: string;
     readonly description?: string;
-    readonly input?: StandardSchemaV1<any, TInput> | Schema.Schema<TInput>;
+    readonly input?: StandardSchemaV1<any, TInput> | Schema.ConstraintDecoder<TInput>;
     readonly nodes: WorkflowNodeDefinition<TInput>[];
+    readonly edges?: readonly WorkflowEdge[];
     readonly concurrency?: number;
+    readonly inputLimitBytes?: number;
+    readonly outputLimitBytes?: number;
+    readonly checkpointLimitBytes?: number;
     output?(ctx: {
         input: TInput;
         results: {
@@ -58,25 +126,13 @@ export interface WorkflowDefinition<TName extends string = string, TInput = Json
     }): TOutput;
 }
 export type AnyWorkflowDefinition = WorkflowDefinition;
-export declare function defineWorkflow<TName extends string, TSchema = undefined, TInput = InferDefinedSchema<TSchema>, TOutput extends JsonValue = JsonValue>(def: {
-    name: TName;
-    description?: string;
-    input?: TSchema;
-    nodes: Array<{
-        id: string;
-        deps?: string[];
-        run: (ctx: WorkflowNodeContext<TInput>) => Promise<JsonValue | NodeResult> | JsonValue | NodeResult;
-    }>;
-    concurrency?: number;
-    output?: (ctx: {
-        input: TInput;
-        results: {
-            [nodeId: string]: JsonValue | null;
-        };
-    }) => TOutput;
+export declare function defineWorkflow<TName extends string, TInput = JsonValue, TOutput extends JsonValue = JsonValue>(def: Omit<WorkflowDefinition<TName, TInput, TOutput>, 'kind' | 'version'> & {
+    readonly version?: string;
 }): WorkflowDefinition<TName, TInput, TOutput>;
 export declare function readyNodes(workflow: WorkflowDefinition, nodeStates: {
     [nodeId: string]: {
         status: string;
     };
 }): string[];
+/** Builds the helpers a node's `run` uses to describe durable work. */
+export declare function nodeResultBuilders(): Pick<WorkflowNodeContext, 'spawn' | 'sleep' | 'effects' | 'map' | 'fanout' | 'loop'>;