@swirls/looms 0.2.0 → 0.3.0

package/dist/client/client.d.ts

@@ -37,6 +37,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -160,6 +164,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -281,6 +289,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -402,6 +414,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -553,6 +569,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -674,6 +694,266 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
+            readonly threads: {
+                readonly [x: string]: {
+                    readonly threadId: string;
+                    readonly kind: string;
+                    readonly definitionName: string;
+                    readonly definitionVersion: string;
+                    readonly parentThreadId: string | null;
+                    readonly status: "cancelled" | "completed" | "failed" | "running" | "waiting";
+                    readonly input: Schema.Json;
+                    readonly output: Schema.Json;
+                    readonly error: string | null;
+                    readonly state: Schema.Json;
+                };
+            };
+            readonly waits: {
+                readonly [x: string]: {
+                    readonly waitId: string;
+                    readonly threadId: string;
+                    readonly on: {
+                        readonly type: string | readonly string[];
+                        readonly match?: Schema.Json | undefined;
+                    } | {
+                        readonly timerAt: number;
+                    };
+                    readonly tag?: Schema.Json | undefined;
+                };
+            };
+            readonly outstandingEffects: readonly {
+                readonly effectId: string;
+                readonly threadId: string;
+                readonly causingSeq: number;
+                readonly causingEventId: string;
+                readonly effect: {
+                    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;
+                };
+            }[];
+            readonly effectExecutions: {
+                readonly [x: string]: {
+                    readonly effectId: string;
+                    readonly attempt: number;
+                    readonly status: "ambiguous" | "cancel_requested" | "dispatched" | "heartbeat" | "queued" | "retry_wait" | "running" | "started" | "timed_out";
+                    readonly nextAttemptAt: number | null;
+                    readonly deadlineAt: number | null;
+                    readonly startedAt: number | null;
+                    readonly lastHeartbeatAt: number | null;
+                    readonly lastError: string | null;
+                };
+            };
+            readonly completedEffectIds: readonly string[];
+            readonly processedIdempotencyKeys: readonly string[];
+        };
+        readonly appended: number;
+    }>;
+    /** Cancel a thread and its descendants; omit `threadId` to cancel the whole run. */
+    cancel: (runId: string, threadId?: string) => Promise<{
+        readonly runId: string;
+        readonly state: {
+            readonly runId: string;
+            readonly status: "cancelled" | "completed" | "failed" | "running";
+            readonly rootThreadId: string | null;
+            readonly startIdentity: {
+                readonly kind: string;
+                readonly definitionName: string;
+                readonly definitionVersion: string;
+                readonly input: Schema.Json;
+                readonly requestedThreadId: string | null;
+                readonly idempotencyKey: string | null;
+                readonly rootThreadId: string;
+            } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
+            readonly threads: {
+                readonly [x: string]: {
+                    readonly threadId: string;
+                    readonly kind: string;
+                    readonly definitionName: string;
+                    readonly definitionVersion: string;
+                    readonly parentThreadId: string | null;
+                    readonly status: "cancelled" | "completed" | "failed" | "running" | "waiting";
+                    readonly input: Schema.Json;
+                    readonly output: Schema.Json;
+                    readonly error: string | null;
+                    readonly state: Schema.Json;
+                };
+            };
+            readonly waits: {
+                readonly [x: string]: {
+                    readonly waitId: string;
+                    readonly threadId: string;
+                    readonly on: {
+                        readonly type: string | readonly string[];
+                        readonly match?: Schema.Json | undefined;
+                    } | {
+                        readonly timerAt: number;
+                    };
+                    readonly tag?: Schema.Json | undefined;
+                };
+            };
+            readonly outstandingEffects: readonly {
+                readonly effectId: string;
+                readonly threadId: string;
+                readonly causingSeq: number;
+                readonly causingEventId: string;
+                readonly effect: {
+                    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;
+                };
+            }[];
+            readonly effectExecutions: {
+                readonly [x: string]: {
+                    readonly effectId: string;
+                    readonly attempt: number;
+                    readonly status: "ambiguous" | "cancel_requested" | "dispatched" | "heartbeat" | "queued" | "retry_wait" | "running" | "started" | "timed_out";
+                    readonly nextAttemptAt: number | null;
+                    readonly deadlineAt: number | null;
+                    readonly startedAt: number | null;
+                    readonly lastHeartbeatAt: number | null;
+                    readonly lastError: string | null;
+                };
+            };
+            readonly completedEffectIds: readonly string[];
+            readonly processedIdempotencyKeys: readonly string[];
+        };
+    }>;
+    /** Start a new run that continues where a finished run ended. */
+    fork: (sourceRunId: string, forkOptions?: {
+        runId?: string;
+    }) => Promise<{
+        readonly runId: string;
+        readonly threadId: string;
+        readonly state: {
+            readonly runId: string;
+            readonly status: "cancelled" | "completed" | "failed" | "running";
+            readonly rootThreadId: string | null;
+            readonly startIdentity: {
+                readonly kind: string;
+                readonly definitionName: string;
+                readonly definitionVersion: string;
+                readonly input: Schema.Json;
+                readonly requestedThreadId: string | null;
+                readonly idempotencyKey: string | null;
+                readonly rootThreadId: string;
+            } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -795,6 +1075,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                 readonly idempotencyKey: string | null;
                 readonly rootThreadId: string;
             } | null;
+            readonly forkedFrom: {
+                readonly runId: string;
+                readonly seq: number;
+            } | null;
             readonly threads: {
                 readonly [x: string]: {
                     readonly threadId: string;
@@ -960,6 +1244,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                     readonly idempotencyKey: string | null;
                     readonly rootThreadId: string;
                 } | null;
+                readonly forkedFrom: {
+                    readonly runId: string;
+                    readonly seq: number;
+                } | null;
                 readonly threads: {
                     readonly [x: string]: {
                         readonly threadId: string;
@@ -1078,6 +1366,10 @@ export declare function createLoomsClient(options?: LoomsClientOptions): {
                     readonly idempotencyKey: string | null;
                     readonly rootThreadId: string;
                 } | null;
+                readonly forkedFrom: {
+                    readonly runId: string;
+                    readonly seq: number;
+                } | null;
                 readonly threads: {
                     readonly [x: string]: {
                         readonly threadId: string;

package/dist/client/client.js

@@ -14,6 +14,12 @@ const StartResultSchema = Schema.Struct({
     state: RunStateSchema,
 });
 const RunResultSchema = Schema.Struct({ runId: Schema.String, state: RunStateSchema });
+/** `appended` counts the events the run gained while the wake ran. */
+const WakeResultSchema = Schema.Struct({
+    runId: Schema.String,
+    state: RunStateSchema,
+    appended: Schema.Finite,
+});
 const EventsResultSchema = Schema.Struct({
     runId: Schema.String,
     events: Schema.Array(EventEnvelopeSchema),
@@ -157,7 +163,17 @@ export function createLoomsClient(options = {}) {
             method: 'POST',
             body: stringifyJson({ events }),
         }),
-        wake: (runId) => request(`/runs/${encodeURIComponent(runId)}/wake`, RunResultSchema, { method: 'POST' }),
+        wake: (runId) => request(`/runs/${encodeURIComponent(runId)}/wake`, WakeResultSchema, { method: 'POST' }),
+        /** Cancel a thread and its descendants; omit `threadId` to cancel the whole run. */
+        cancel: (runId, threadId) => request(`/runs/${encodeURIComponent(runId)}/cancel`, RunResultSchema, {
+            method: 'POST',
+            body: stringifyJson(threadId === undefined ? {} : { threadId }),
+        }),
+        /** Start a new run that continues where a finished run ended. */
+        fork: (sourceRunId, forkOptions) => request(`/runs/${encodeURIComponent(sourceRunId)}/fork`, StartResultSchema, {
+            method: 'POST',
+            body: stringifyJson(forkOptions?.runId === undefined ? {} : { runId: forkOptions.runId }),
+        }),
         workerCallback,
         listRunSummaries: () => request('/runs/summaries', RunSummariesSchema),
         listDefinitions: () => request('/definitions', DefinitionCatalogSchema),

package/dist/cloudflare/router.d.ts

@@ -6,7 +6,7 @@ export interface DurableObjectNamespaceLike<T extends DurableObjectStubLike = Du
 }
 /**
  * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
- * Handles `/health` locally, returns 501 for global run lists, and forwards
+ * Handles `/health` locally, returns 501 for global run lists and forks, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
 export declare function routeToDurableObject(namespace: DurableObjectNamespaceLike, req: Request): Promise<Response | null>;

package/dist/cloudflare/router.js

@@ -1,18 +1,16 @@
-import { resolveRunTarget, RunTargetError } from '@swirls/looms/actor';
+import { crossRunResponse, resolveRunTarget, RunTargetError } from '@swirls/looms/actor';
 /**
  * Routes incoming HTTP requests to the appropriate Durable Object actor cell.
- * Handles `/health` locally, returns 501 for global run lists, and forwards
+ * Handles `/health` locally, returns 501 for global run lists and forks, and forwards
  * all other run and event-stream requests to `namespace.getByName(runId)`.
  */
 export function routeToDurableObject(namespace, req) {
-    const url = new URL(req.url);
-    if (url.pathname === '/health') {
+    if (new URL(req.url).pathname === '/health') {
         return Promise.resolve(Response.json({ ok: true }));
     }
-    if (req.method === 'GET' && (url.pathname === '/runs' || url.pathname === '/runs/summaries')) {
-        return Promise.resolve(Response.json({
-            error: 'Global run listing is not supported in the Durable Object backend without a global index',
-        }, { status: 501 }));
+    const unsupported = crossRunResponse(req, 'the Durable Object backend');
+    if (unsupported) {
+        return Promise.resolve(unsupported);
     }
     return resolveRunTarget(req)
         .then(({ runId, request }) => namespace.getByName(runId).fetch(request))

package/dist/core/effects.d.ts

@@ -166,6 +166,11 @@ export interface EffectDefinition<TInput = JsonValue, R = Context.Service.Any, E
     readonly execution?: EffectExecution;
     /** Whether `execute` runs a user handler. Without one, the effect can only complete through a worker. */
     readonly hasHandler: boolean;
+    /**
+     * The outcome follows from the input alone, like scheduling from state already folded. Forking
+     * a failed run retries the effect that produced the failure, not a deterministic one passing it on.
+     */
+    readonly deterministic?: boolean;
     readonly [effectInputType]?: (input: TInput) => TInput;
     execute(input: JsonValue, ctx: EffectContext): Effect.Effect<ReadonlyArray<E>, InvalidInputError | EffectHandlerError, R>;
 }
@@ -182,6 +187,7 @@ export declare function defineEffect<TSchema extends SchemaInput, R = never, E e
     input: TSchema;
     retry?: RetryPolicy;
     execution?: EffectExecution;
+    deterministic?: boolean;
     execute?: (input: InferDefinedSchema<TSchema>, ctx: EffectContext) => EffectHandlerResult<R, E, HandlerError>;
 }): EffectDefinition<InferDefinedSchema<TSchema>, R, E>;
 export declare function defineEffect<R = never, E extends EventInput = EventInput, HandlerError = never>(def: {
@@ -189,6 +195,7 @@ export declare function defineEffect<R = never, E extends EventInput = EventInpu
     input?: undefined;
     retry?: RetryPolicy;
     execution?: EffectExecution;
+    deterministic?: boolean;
     execute?: (input: JsonValue, ctx: EffectContext) => EffectHandlerResult<R, E, HandlerError>;
 }): EffectDefinition<JsonValue, R, E>;
 export declare function spawn(args: {

package/dist/core/effects.js

@@ -106,6 +106,7 @@ export function defineEffect(def) {
         retry: def.retry,
         execution: def.execution,
         hasHandler: handler !== undefined,
+        deterministic: def.deterministic,
         execute: (raw, ctx) => Effect.gen(function* () {
             const input = schema ? yield* validateInputEffect(schema, raw) : raw;
             return handler ? yield* liftHandlerResult(handler(input, ctx)) : noOutput;

package/dist/core/fold.js

@@ -2,7 +2,7 @@ import { Option, Predicate, Schema, Stream } from 'effect';
 import { isWithdrawnError, WaitConditionSchema } from './effects.js';
 import { createEffectId } from './ids.js';
 import { DEFAULT_DEFINITION_VERSION } from './module.js';
-import { emptyRunState } from './state.js';
+import { completedRunStatus, emptyRunState } from './state.js';
 import { isTerminalStatus } from './thread.js';
 const decodeWaitCondition = Schema.decodeUnknownOption(WaitConditionSchema);
 function payloadObject(event) {
@@ -25,6 +25,7 @@ function cloneState(state) {
         status: state.status,
         rootThreadId: state.rootThreadId,
         startIdentity: state.startIdentity,
+        forkedFrom: state.forkedFrom,
         threads: { ...state.threads },
         waits: { ...state.waits },
         outstandingEffects: [...state.outstandingEffects],
@@ -104,13 +105,18 @@ function applyProtocol(state, event, registry) {
                 status: 'running',
             };
         }
-        case 'runtime.run.completed': {
-            const error = payload.error;
-            const status = Predicate.isString(error) && error.length > 0 ? 'failed' : 'completed';
-            return { ...state, status };
-        }
+        case 'runtime.run.completed':
+            return { ...state, status: completedRunStatus(payload) };
         case 'runtime.run.cancelled':
             return { ...state, status: 'cancelled' };
+        case 'runtime.run.forked': {
+            const sourceRunId = readString(payload, 'sourceRunId');
+            const sourceSeq = payload.sourceSeq;
+            // Attempts recorded in the copied history belong to the source run's processes.
+            return sourceRunId && Predicate.isNumber(sourceSeq)
+                ? { ...state, forkedFrom: { runId: sourceRunId, seq: sourceSeq }, effectExecutions: {} }
+                : state;
+        }
         case 'runtime.thread.started': {
             const threadId = readString(payload, 'threadId') ?? event.threadId;
             const kind = readString(payload, 'kind');

package/dist/core/fork.d.ts

@@ -0,0 +1,35 @@
+import { Effect } from 'effect';
+import { type EffectDefinition } from './effects';
+import { type EventEnvelope } from './envelope';
+import { type FoldRegistry } from './fold';
+declare const ForkSourceError_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: "ForkSourceError";
+} & Readonly<A>;
+export declare class ForkSourceError extends ForkSourceError_base<{
+    readonly runId: string;
+    readonly message: string;
+}> {
+    constructor(runId: string, message: string);
+}
+export interface ForkRegistry extends FoldRegistry {
+    readonly effects: ReadonlyMap<string, Pick<EffectDefinition, 'deterministic'>>;
+}
+export interface ForkPlan {
+    /** The fork's history: the copied prefix, keeping source seqs, then the `runtime.run.forked` marker. */
+    readonly events: readonly EventEnvelope[];
+    /** Last source seq the fork copied. */
+    readonly sourceSeq: number;
+    readonly rootThreadId: string;
+}
+/**
+ * Plan a new run that continues where the source run ended. The fork copies the source's
+ * history up to the point the run finished, keeping sequence numbers so effect ids still
+ * line up, and its next wake re-issues whatever effects were outstanding there.
+ */
+export declare function planFork(input: {
+    readonly sourceRunId: string;
+    readonly runId: string;
+    readonly events: readonly EventEnvelope[];
+    readonly registry: ForkRegistry;
+}): Effect.Effect<ForkPlan, ForkSourceError>;
+export {};

package/dist/core/fork.js

@@ -0,0 +1,129 @@
+import { Data, Effect, Predicate } from 'effect';
+import { isPrimitiveEffect, isWithdrawnError, } from './effects.js';
+import { createEvent } from './envelope.js';
+import { foldEvent, foldRun } from './fold.js';
+import { emptyRunState, isRunTerminal } from './state.js';
+import { isTerminalStatus } from './thread.js';
+export class ForkSourceError extends Data.TaggedError('ForkSourceError') {
+    constructor(runId, message) {
+        super({ runId, message });
+        this.name = 'ForkSourceError';
+    }
+}
+function payloadThreadId(event) {
+    const threadId = Predicate.isObject(event.payload) ? event.payload.threadId : undefined;
+    return Predicate.isString(threadId) ? threadId : event.threadId;
+}
+function rootTerminal(state) {
+    const root = state.rootThreadId ? state.threads[state.rootThreadId] : undefined;
+    return isRunTerminal(state) || (root !== undefined && isTerminalStatus(root.status));
+}
+/** Where the cancellation that wrote `event` began, when it recorded that; a seq is an index + 1. */
+function cancellationStart(event) {
+    const resumeSeq = event.type === 'runtime.thread.cancelled' && Predicate.isObject(event.payload)
+        ? event.payload.resumeSeq
+        : undefined;
+    return Predicate.isNumber(resumeSeq) ? resumeSeq : undefined;
+}
+/**
+ * Fold the source until its root thread ends. Everything from that event on is how the run
+ * finished, so the fork leaves it out; a cancellation that recorded where it began is left
+ * out from there.
+ */
+function scanSource(events, registry) {
+    const effects = new Map();
+    const failedAt = new Map();
+    let state = emptyRunState(events[0]?.runId ?? '');
+    for (const [index, event] of events.entries()) {
+        state = foldEvent(state, event, registry);
+        for (const item of state.outstandingEffects) {
+            effects.set(item.effectId, item.effect);
+        }
+        for (const record of Object.values(state.threads)) {
+            if (record.status === 'failed' && !failedAt.has(record.threadId)) {
+                failedAt.set(record.threadId, index);
+            }
+        }
+        if (rootTerminal(state)) {
+            const root = state.rootThreadId ? state.threads[state.rootThreadId] : undefined;
+            const rootFailed = root?.status === 'failed' || state.status === 'failed';
+            return { cut: cancellationStart(event) ?? index, effects, failedAt, rootFailed };
+        }
+    }
+    return { cut: events.length, effects, failedAt, rootFailed: false };
+}
+/**
+ * Walk back from the root's failure to the effect outcome that started it, so the fork
+ * re-issues that effect instead of replaying a failure the modules already folded in.
+ */
+function failureOrigin(events, scan, registry) {
+    const indexById = new Map(events.map((event, index) => [event.id, index]));
+    /** A failed thread leads back to where the fold failed it, anything else to its cause. */
+    const previous = (index) => {
+        const event = events[index];
+        const threadId = event.type === 'runtime.thread.failed' ? payloadThreadId(event) : null;
+        const failedAt = threadId ? scan.failedAt.get(threadId) : undefined;
+        const cause = event.causationId ? indexById.get(event.causationId) : undefined;
+        const next = failedAt !== undefined && failedAt < index ? failedAt : cause;
+        return next !== undefined && next < index ? next : undefined;
+    };
+    for (let index = scan.cut; index !== undefined; index = previous(index)) {
+        const event = events[index];
+        const effect = event.effectId ? scan.effects.get(event.effectId) : undefined;
+        const error = Predicate.isObject(event.payload) ? event.payload.error : undefined;
+        const withdrawn = Predicate.isString(error) && isWithdrawnError(error);
+        if (effect &&
+            !isPrimitiveEffect(effect) &&
+            !registry.effects.get(effect.type)?.deterministic &&
+            !withdrawn) {
+            return index;
+        }
+    }
+    return scan.cut;
+}
+function copyEvent(event, runId, reissued) {
+    if (event.ephemeral && event.effectId && reissued.has(event.effectId)) {
+        return { ...event, runId, type: 'runtime.fork.elided', payload: { type: event.type } };
+    }
+    if (event.type === 'runtime.snapshot.taken' && Predicate.isObject(event.payload)) {
+        const { state: _state, ...pointer } = event.payload;
+        return { ...event, runId, payload: pointer };
+    }
+    if (event.type === 'runtime.run.started') {
+        return { ...event, runId, idempotencyKey: null };
+    }
+    return { ...event, runId };
+}
+/**
+ * Plan a new run that continues where the source run ended. The fork copies the source's
+ * history up to the point the run finished, keeping sequence numbers so effect ids still
+ * line up, and its next wake re-issues whatever effects were outstanding there.
+ */
+export function planFork(input) {
+    const { sourceRunId, runId, events, registry } = input;
+    if (events.length === 0) {
+        return Effect.fail(new ForkSourceError(sourceRunId, `Run "${sourceRunId}" has no events`));
+    }
+    if (events.some((event, index) => event.seq !== index + 1)) {
+        return Effect.fail(new ForkSourceError(sourceRunId, `Run "${sourceRunId}" does not have its full history from seq 1; it cannot be forked`));
+    }
+    const scan = scanSource(events, registry);
+    const cut = scan.rootFailed ? failureOrigin(events, scan, registry) : scan.cut;
+    const prefix = events.slice(0, cut);
+    const atCut = foldRun(prefix, registry, { runId });
+    if (!atCut.rootThreadId) {
+        return Effect.fail(new ForkSourceError(sourceRunId, `Run "${sourceRunId}" never started a root thread`));
+    }
+    const reissued = new Set(atCut.outstandingEffects.map((item) => item.effectId));
+    const marker = createEvent(runId, {
+        type: 'runtime.run.forked',
+        payload: { sourceRunId, sourceSeq: cut },
+        threadId: null,
+        origin: { type: 'system' },
+    }, { seq: cut + 1 });
+    return Effect.succeed({
+        events: [...prefix.map((event) => copyEvent(event, runId, reissued)), marker],
+        sourceSeq: cut,
+        rootThreadId: atCut.rootThreadId,
+    });
+}

package/dist/core/index.d.ts

@@ -13,6 +13,7 @@ export * from './state';
 export * from './match';
 export * from './fold';
 export * from './replay';
+export * from './fork';
 export * from './projection';
 export * from './module';
 export * from './kind';