@temelj/workflow 0.0.0-alpha.2 → 0.0.0-alpha.4

package/dist/engine/stream-reader.mjs

@@ -0,0 +1,154 @@
+import { WorkflowErrorCode } from "../errors/codes.mjs";
+import { WorkflowOptionsError } from "../errors/base.mjs";
+import { WorkflowStreamError } from "../errors/stream.mjs";
+import { matchesWorkflowError } from "../errors/records.mjs";
+import "../errors/mod.mjs";
+import { History } from "../history/replay.mjs";
+import { isNonNegativeSafeInteger } from "../values.mjs";
+import { getRequiredRun } from "../store/query.mjs";
+import { nonNegativeTimerDelay } from "../timer.mjs";
+import { getStreamInfoFromHistory, readStreamFromHistory } from "./stream.mjs";
+import "temporal-polyfill/global";
+//#region src/engine/stream-reader.ts
+const DEFAULT_STREAM_FOLLOW_POLL_INTERVAL = Temporal.Duration.from({ milliseconds: 100 });
+async function getStreamInfo(context, runId, streamIdOrName) {
+	await getRequiredRun(context.store, runId);
+	return getStreamInfoFromHistory(runId, new History(await context.store.getEvents(runId)), streamIdOrName);
+}
+async function readStream(context, runId, streamIdOrName, readOptions) {
+	await getRequiredRun(context.store, runId);
+	return readStreamFromHistory(runId, new History(await context.store.getEvents(runId)), streamIdOrName, readOptions);
+}
+function followStream(context, runId, streamIdOrName, followOptions) {
+	return followStreamState((readOptions) => readStream(context, runId, streamIdOrName, readOptions), followOptions, { waitForChange: ({ signal }) => waitForStreamStorageChange(context, runId, signal) });
+}
+async function waitForStream(context, runId, streamIdOrName, waitOptions) {
+	return await waitForStreamState(() => getStreamInfo(context, runId, streamIdOrName), waitOptions, { waitForChange: ({ signal }) => waitForStreamStorageChange(context, runId, signal) });
+}
+async function waitForStreamChunk(context, runId, streamIdOrName, afterIndex, waitOptions) {
+	return await waitForStreamStateChunk((readOptions) => readStream(context, runId, streamIdOrName, readOptions), afterIndex, waitOptions, { waitForChange: ({ signal }) => waitForStreamStorageChange(context, runId, signal) });
+}
+async function waitForStreamTerminal(context, runId, streamIdOrName, waitOptions) {
+	return await waitForStreamStateTerminal(() => getStreamInfo(context, runId, streamIdOrName), waitOptions, { waitForChange: ({ signal }) => waitForStreamStorageChange(context, runId, signal) });
+}
+async function waitForStreamStorageChange(context, runId, signal) {
+	await context.store.waitForEventHistoryChange(runId, { signal });
+}
+async function* followStreamState(read, options = {}, waitOptions = {}) {
+	if (options.fromIndex !== void 0 && options.fromTail !== void 0) WorkflowStreamError.readOffsetConflict();
+	const pollInterval = options.pollInterval ?? DEFAULT_STREAM_FOLLOW_POLL_INTERVAL;
+	const maxChunks = options.pageSize ?? options.maxChunks;
+	let nextIndex = options.fromIndex;
+	let initialFromTail = options.fromTail;
+	while (true) {
+		if (options.signal?.aborted) return;
+		const stream = await read({
+			fromIndex: nextIndex,
+			fromTail: nextIndex === void 0 ? initialFromTail : void 0,
+			maxChunks
+		});
+		initialFromTail = void 0;
+		for (const chunk of stream.chunks) {
+			if (options.signal?.aborted) return;
+			nextIndex = chunk.index + 1;
+			yield {
+				kind: "chunk",
+				runId: stream.runId,
+				streamId: stream.id,
+				streamName: stream.name,
+				chunk
+			};
+		}
+		if (nextIndex !== void 0 && nextIndex < stream.chunkCount) continue;
+		if (stream.status !== "open") {
+			if (options.includeTerminal !== false) {
+				const info = {
+					runId: stream.runId,
+					id: stream.id,
+					name: stream.name,
+					status: stream.status,
+					createdAt: stream.createdAt,
+					updatedAt: stream.updatedAt,
+					contentType: stream.contentType,
+					metadata: stream.metadata,
+					chunkCount: stream.chunkCount,
+					lastIndex: stream.lastIndex,
+					error: stream.error
+				};
+				yield {
+					kind: stream.status,
+					runId: stream.runId,
+					streamId: stream.id,
+					streamName: stream.name,
+					info
+				};
+			}
+			return;
+		}
+		await waitForStreamChangeOrPoll(nonNegativeTimerDelay(pollInterval, "Workflow stream follow pollInterval").clampedDelay, options.signal, waitOptions.waitForChange);
+	}
+}
+/** Waits for the next stream change, or for one poll interval when changes cannot be watched. */
+async function pollForStreamChange(options, waitOptions) {
+	await waitForStreamChangeOrPoll(nonNegativeTimerDelay(options.pollInterval ?? DEFAULT_STREAM_FOLLOW_POLL_INTERVAL, "Workflow stream wait pollInterval").clampedDelay, options.signal, waitOptions.waitForChange);
+}
+async function waitForStreamState(readInfo, options = {}, waitOptions = {}) {
+	while (true) {
+		if (options.signal?.aborted) return;
+		try {
+			return await readInfo();
+		} catch (error) {
+			if (!matchesWorkflowError(error, WorkflowErrorCode.STREAM_NOT_FOUND)) throw error;
+		}
+		await pollForStreamChange(options, waitOptions);
+	}
+}
+async function waitForStreamStateChunk(read, afterIndex, options = {}, waitOptions = {}) {
+	if (!isNonNegativeSafeInteger(afterIndex)) WorkflowOptionsError.nonNegativeSafeInteger("Workflow stream chunk wait afterIndex");
+	while (true) {
+		if (options.signal?.aborted) return;
+		const stream = await read({ fromIndex: afterIndex + 1 });
+		const chunk = stream.chunks[0];
+		if (chunk !== void 0) return chunk;
+		if (stream.status !== "open") return;
+		await pollForStreamChange(options, waitOptions);
+	}
+}
+async function waitForStreamStateTerminal(readInfo, options = {}, waitOptions = {}) {
+	while (true) {
+		if (options.signal?.aborted === true) return;
+		const info = await readInfo();
+		if (info.status !== "open") return info;
+		await pollForStreamChange(options, waitOptions);
+	}
+}
+async function sleepForStreamFollow(milliseconds, signal) {
+	if (milliseconds === 0 || signal?.aborted) return;
+	await new Promise((resolve) => {
+		const timer = setTimeout(resolve, milliseconds);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(timer);
+			resolve();
+		}, { once: true });
+	});
+}
+async function waitForStreamChangeOrPoll(milliseconds, signal, waitForChange) {
+	if (waitForChange === void 0) {
+		await sleepForStreamFollow(milliseconds, signal);
+		return;
+	}
+	const controller = new AbortController();
+	const abort = () => {
+		controller.abort();
+	};
+	signal?.addEventListener("abort", abort, { once: true });
+	try {
+		if (signal?.aborted === true) return;
+		await Promise.race([sleepForStreamFollow(milliseconds, controller.signal), waitForChange({ signal: controller.signal })]);
+	} finally {
+		signal?.removeEventListener("abort", abort);
+		controller.abort();
+	}
+}
+//#endregion
+export { followStream, getStreamInfo, readStream, waitForStream, waitForStreamChunk, waitForStreamTerminal };

package/dist/engine/stream.d.mts

@@ -1,56 +1,11 @@
-import { RunId } from "../types/run-id.mjs";
-import { StreamIdOrName } from "../types/stream-id.mjs";
-import { CreateStreamOptions, FollowStreamOptions, ReadStreamOptions, ReadStreamPageOptions, Stream as Stream$1, StreamChunk, StreamInfo, StreamPage, StreamState, StreamUpdate, WaitStreamOptions } from "../types/stream.mjs";
-import { WorkflowStepStreamApi } from "../types/step.mjs";
-import { WorkflowStepIdentity } from "../types/run.mjs";
-import { EventRecord } from "../types/events.mjs";
-import { WorkflowEventHistoryWatcher, WorkflowEventReader, WorkflowRunReaderRepository } from "../types/store.mjs";
-import { WorkflowExecutionEnvironment } from "../types/engine.mjs";
+import { RunId, StreamIdOrName } from "../types/ids.mjs";
+import { ReadStreamOptions, StreamInfo, StreamState } from "../types/stream.mjs";
+import { StepStreamApi } from "../types/step.mjs";
+import { History } from "../history/replay.mjs";
+import { ExecutionEnvironment } from "../types/engine.mjs";
 import "temporal-polyfill/global";
 //#region src/engine/stream.d.ts
-interface WorkflowStreamReader<TChunk> {
-  (options?: ReadStreamOptions): Promise<StreamState<TChunk>>;
-}
-interface WorkflowStreamInfoReader {
-  (): Promise<StreamInfo>;
-}
-interface WorkflowStreamChangeWaiter {
-  (options: {
-    readonly signal?: AbortSignal;
-  }): Promise<void>;
-}
-interface WorkflowStreamWaitOptions {
-  readonly waitForChange?: WorkflowStreamChangeWaiter;
-}
-type WorkflowStreamStore = WorkflowRunReaderRepository & WorkflowEventReader & WorkflowEventHistoryWatcher;
-interface WorkflowStreamServiceOptions {
-  readonly store: WorkflowStreamStore;
-}
-declare function getStreamInfoForRun(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName): Promise<StreamInfo>;
-declare function readStreamForRun<TChunk = unknown>(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName, readOptions?: ReadStreamOptions): Promise<StreamState<TChunk>>;
-declare function readStreamPageForRun<TChunk = unknown>(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName, readOptions?: ReadStreamPageOptions): Promise<StreamPage<TChunk>>;
-declare function followStreamForRun<TChunk = unknown>(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName, followOptions?: FollowStreamOptions): AsyncIterable<StreamUpdate<TChunk>>;
-declare function waitForStreamForRun(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName, waitOptions?: WaitStreamOptions): Promise<StreamInfo | undefined>;
-declare function waitForStreamChunkForRun<TChunk = unknown>(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName, afterIndex: number, waitOptions?: WaitStreamOptions): Promise<StreamChunk<TChunk> | undefined>;
-declare function waitForStreamTerminalForRun(service: WorkflowStreamServiceOptions, runId: RunId, streamIdOrName: StreamIdOrName, waitOptions?: WaitStreamOptions): Promise<StreamInfo | undefined>;
-declare function createWorkflowStepStreamApi(environment: WorkflowExecutionEnvironment): WorkflowStepStreamApi;
-declare function createStream<TChunk>(environment: WorkflowExecutionEnvironment, identity: WorkflowStepIdentity<"stream">, name: string, options?: CreateStreamOptions): Stream<TChunk>;
-declare class Stream<TChunk> implements Stream$1<TChunk> {
-  #private;
-  readonly id: string;
-  readonly name: string;
-  readonly contentType?: string;
-  readonly metadata?: unknown;
-  constructor(environment: WorkflowExecutionEnvironment, identity: WorkflowStepIdentity<"stream">, name: string, options?: CreateStreamOptions);
-  write(chunk: TChunk): Promise<void>;
-  close(): Promise<void>;
-  error(error: unknown): Promise<void>;
-}
-declare function readStream<TChunk = unknown>(runId: RunId, events: readonly EventRecord[], streamIdOrName: StreamIdOrName, options?: ReadStreamOptions): StreamState<TChunk>;
-declare function followStream<TChunk = unknown>(read: WorkflowStreamReader<TChunk>, options?: FollowStreamOptions, waitOptions?: WorkflowStreamWaitOptions): AsyncIterable<StreamUpdate<TChunk>>;
-declare function waitForStream(readInfo: WorkflowStreamInfoReader, options?: WaitStreamOptions, waitOptions?: WorkflowStreamWaitOptions): Promise<StreamInfo | undefined>;
-declare function waitForStreamChunk<TChunk = unknown>(read: WorkflowStreamReader<TChunk>, afterIndex: number, options?: WaitStreamOptions, waitOptions?: WorkflowStreamWaitOptions): Promise<StreamChunk<TChunk> | undefined>;
-declare function waitForStreamTerminal(readInfo: WorkflowStreamInfoReader, options?: WaitStreamOptions, waitOptions?: WorkflowStreamWaitOptions): Promise<StreamInfo | undefined>;
-declare function getStreamInfo(runId: RunId, events: readonly EventRecord[], streamIdOrName: StreamIdOrName): StreamInfo;
-//#endregion
-export { createStream, createWorkflowStepStreamApi, followStream, followStreamForRun, getStreamInfo, getStreamInfoForRun, readStream, readStreamForRun, readStreamPageForRun, waitForStream, waitForStreamChunk, waitForStreamChunkForRun, waitForStreamForRun, waitForStreamTerminal, waitForStreamTerminalForRun };
+export declare function createStepStreamApi(environment: ExecutionEnvironment): StepStreamApi;
+export declare function readStreamFromHistory(runId: RunId, history: History, streamIdOrName: StreamIdOrName, options?: ReadStreamOptions): StreamState;
+export declare function getStreamInfoFromHistory(runId: RunId, history: History, streamIdOrName: StreamIdOrName): StreamInfo;
+//#endregion

package/dist/engine/stream.mjs

@@ -1,59 +1,20 @@
-import { WorkflowOptionsError } from "../errors/base.mjs";
+import { WorkflowErrorCode } from "../errors/codes.mjs";
 import { WorkflowReplayDivergenceError } from "../errors/failures.mjs";
-import { getRequiredRun, isNonNegativeSafeInteger } from "../utility.mjs";
 import { WorkflowStreamError, WorkflowStreamNotFoundError } from "../errors/stream.mjs";
 import "../errors/mod.mjs";
-import { nonNegativeTimerDelay } from "../timer.mjs";
 import { serializeError, toOptionalPersistedValue, toPersistedValue } from "./serialization.mjs";
-import { WorkflowHistory } from "../history/mod.mjs";
-import "./state.mjs";
-import { makeStreamChunkCursorKey, pageItems } from "../pagination.mjs";
-import { resolveWorkflowCommandIdentity } from "./command-identity.mjs";
-import { appendDurableStepStartedEvent, appendDurableStepTerminalEvent } from "./durable-command.mjs";
+import { resolveCommandIdentity } from "./command-identity.mjs";
+import { appendDurableEvent, appendDurableStepStartedEvent } from "./durable-command.mjs";
 import "temporal-polyfill/global";
 import { deepEquals } from "@temelj/value";
 //#region src/engine/stream.ts
 const DEFAULT_MAXIMUM_STREAM_CHUNKS = 1e3;
-const DEFAULT_STREAM_FOLLOW_POLL_INTERVAL = Temporal.Duration.from({ milliseconds: 100 });
-async function getStreamInfoForRun(service, runId, streamIdOrName) {
-	await getRequiredRun(service.store, runId);
-	return getStreamInfoFromHistory(runId, new WorkflowHistory(await service.store.getEvents(runId)), streamIdOrName);
-}
-async function readStreamForRun(service, runId, streamIdOrName, readOptions) {
-	await getRequiredRun(service.store, runId);
-	return readStreamFromHistory(runId, new WorkflowHistory(await service.store.getEvents(runId)), streamIdOrName, readOptions);
-}
-async function readStreamPageForRun(service, runId, streamIdOrName, readOptions) {
-	const stream = await readStreamForRun(service, runId, streamIdOrName, readOptions);
-	return {
-		...stream,
-		chunks: pageItems(stream.chunks, readOptions, "Workflow stream page", makeStreamChunkCursorKey)
-	};
-}
-function followStreamForRun(service, runId, streamIdOrName, followOptions) {
-	return followStream(async (readOptions) => await readStreamForRun(service, runId, streamIdOrName, readOptions), followOptions, { waitForChange: async ({ signal }) => await waitForStreamStorageChange(service, runId, signal) });
-}
-async function waitForStreamForRun(service, runId, streamIdOrName, waitOptions) {
-	return await waitForStream(async () => await getStreamInfoForRun(service, runId, streamIdOrName), waitOptions, { waitForChange: async ({ signal }) => await waitForStreamStorageChange(service, runId, signal) });
-}
-async function waitForStreamChunkForRun(service, runId, streamIdOrName, afterIndex, waitOptions) {
-	return await waitForStreamChunk(async (readOptions) => await readStreamForRun(service, runId, streamIdOrName, readOptions), afterIndex, waitOptions, { waitForChange: async ({ signal }) => await waitForStreamStorageChange(service, runId, signal) });
-}
-async function waitForStreamTerminalForRun(service, runId, streamIdOrName, waitOptions) {
-	return await waitForStreamTerminal(async () => await getStreamInfoForRun(service, runId, streamIdOrName), waitOptions, { waitForChange: async ({ signal }) => await waitForStreamStorageChange(service, runId, signal) });
-}
-async function waitForStreamStorageChange(service, runId, signal) {
-	await service.store.waitForEventHistoryChange(runId, { signal });
-}
-function createWorkflowStepStreamApi(environment) {
+function createStepStreamApi(environment) {
 	const { history } = environment;
 	return { create(commandId, options = {}) {
-		return createStream(environment, resolveWorkflowCommandIdentity(history, "stream", commandId), commandId, options);
+		return new Stream(environment, resolveCommandIdentity(history, "stream", commandId), commandId, options);
 	} };
 }
-function createStream(environment, identity, name, options = {}) {
-	return new Stream(environment, identity, name, options);
-}
 var Stream = class {
 	id;
 	name;
@@ -83,8 +44,20 @@ var Stream = class {
 		this.#maximumChunks = maximumChunks;
 		this.#persistedMetadata = persistedMetadata;
 	}
-	async write(chunk) {
+	async #start() {
 		await ensureStreamStarted(this.#environment, this.#identity, this.id, this.contentType, this.#persistedMetadata);
+	}
+	/** Fields every event of this stream carries. */
+	#eventFields() {
+		return {
+			timestamp: this.#environment.now(),
+			stepId: this.#identity.id,
+			stepName: this.#identity.name,
+			streamId: this.id
+		};
+	}
+	async write(chunk) {
+		await this.#start();
 		const persistedChunk = toPersistedValue(chunk, `workflow stream ${this.id} chunk`, this.#environment.limits);
 		const existing = this.#environment.history.streamChunk(this.#identity.id, this.#nextChunkIndex);
 		const index = this.#nextChunkIndex;
@@ -94,46 +67,37 @@ var Stream = class {
 			return;
 		}
 		requireStreamOpen(this.#environment, this.#identity.id, this.id);
-		if (index >= this.#maximumChunks) WorkflowStreamError.chunkLimitExceeded(this.id, this.#maximumChunks);
-		await appendDurableStepTerminalEvent(this.#environment, {
-			kind: "stream_chunk",
-			timestamp: this.#environment.now(),
-			stepId: this.#identity.id,
-			stepName: this.#identity.name,
+		if (index >= this.#maximumChunks) throw new WorkflowStreamError(`Workflow stream ${this.id} chunk count would exceed maximumStreamChunks ${this.#maximumChunks}`, WorkflowErrorCode.STREAM_CHUNK_LIMIT_EXCEEDED, {
 			streamId: this.id,
+			maximumChunks: this.#maximumChunks
+		});
+		await appendDurableEvent(this.#environment, {
+			kind: "stream_chunk",
+			...this.#eventFields(),
 			index,
 			chunk: persistedChunk
 		});
 	}
 	async close() {
-		await ensureStreamStarted(this.#environment, this.#identity, this.id, this.contentType, this.#persistedMetadata);
+		await this.#start();
 		if (this.#environment.history.closedStream(this.#identity.id) !== void 0) return;
 		requireStreamOpen(this.#environment, this.#identity.id, this.id);
-		await appendDurableStepTerminalEvent(this.#environment, {
+		await appendDurableEvent(this.#environment, {
 			kind: "stream_closed",
-			timestamp: this.#environment.now(),
-			stepId: this.#identity.id,
-			stepName: this.#identity.name,
-			streamId: this.id
+			...this.#eventFields()
 		});
 	}
-	async error(error) {
-		await ensureStreamStarted(this.#environment, this.#identity, this.id, this.contentType, this.#persistedMetadata);
+	async error(cause) {
+		await this.#start();
 		if (this.#environment.history.failedStream(this.#identity.id) !== void 0) return;
 		requireStreamOpen(this.#environment, this.#identity.id, this.id);
-		await appendDurableStepTerminalEvent(this.#environment, {
+		await appendDurableEvent(this.#environment, {
 			kind: "stream_failed",
-			timestamp: this.#environment.now(),
-			stepId: this.#identity.id,
-			stepName: this.#identity.name,
-			streamId: this.id,
-			error: serializeError(error)
+			...this.#eventFields(),
+			error: serializeError(cause)
 		});
 	}
 };
-function readStream(runId, events, streamIdOrName, options = {}) {
-	return readStreamFromHistory(runId, new WorkflowHistory(events), streamIdOrName, options);
-}
 function readStreamFromHistory(runId, history, streamIdOrName, options = {}) {
 	if (options.fromIndex !== void 0 && options.fromTail !== void 0) WorkflowStreamError.readOffsetConflict();
 	const projection = requireStreamProjectionFromHistory(history, streamIdOrName);
@@ -149,96 +113,12 @@ function readStreamFromHistory(runId, history, streamIdOrName, options = {}) {
 		chunks
 	};
 }
-async function* followStream(read, options = {}, waitOptions = {}) {
-	if (options.fromIndex !== void 0 && options.fromTail !== void 0) WorkflowStreamError.readOffsetConflict();
-	const pollInterval = options.pollInterval ?? DEFAULT_STREAM_FOLLOW_POLL_INTERVAL;
-	const maxChunks = options.pageSize ?? options.maxChunks;
-	let nextIndex = options.fromIndex;
-	let initialFromTail = options.fromTail;
-	while (true) {
-		if (options.signal?.aborted) return;
-		const stream = await read({
-			...nextIndex === void 0 ? {} : { fromIndex: nextIndex },
-			...nextIndex === void 0 && initialFromTail !== void 0 ? { fromTail: initialFromTail } : {},
-			...maxChunks === void 0 ? {} : { maxChunks }
-		});
-		initialFromTail = void 0;
-		for (const chunk of stream.chunks) {
-			if (options.signal?.aborted) return;
-			nextIndex = chunk.index + 1;
-			yield {
-				kind: "chunk",
-				runId: stream.runId,
-				streamId: stream.id,
-				streamName: stream.name,
-				chunk
-			};
-		}
-		if (nextIndex !== void 0 && nextIndex < stream.chunkCount) continue;
-		if (stream.status !== "open") {
-			if (options.includeTerminal !== false) yield {
-				kind: stream.status,
-				runId: stream.runId,
-				streamId: stream.id,
-				streamName: stream.name,
-				info: {
-					runId: stream.runId,
-					id: stream.id,
-					name: stream.name,
-					status: stream.status,
-					createdAt: stream.createdAt,
-					updatedAt: stream.updatedAt,
-					...stream.contentType === void 0 ? {} : { contentType: stream.contentType },
-					...stream.metadata === void 0 ? {} : { metadata: stream.metadata },
-					chunkCount: stream.chunkCount,
-					...stream.lastIndex === void 0 ? {} : { lastIndex: stream.lastIndex },
-					...stream.error === void 0 ? {} : { error: stream.error }
-				}
-			};
-			return;
-		}
-		await waitForStreamChangeOrPoll(nonNegativeTimerDelay(pollInterval, "Workflow stream follow pollInterval").clampedDelay, options.signal, waitOptions.waitForChange);
-	}
-}
-async function waitForStream(readInfo, options = {}, waitOptions = {}) {
-	while (true) {
-		if (options.signal?.aborted) return;
-		try {
-			return await readInfo();
-		} catch (error) {
-			if (!WorkflowStreamNotFoundError.isNotFound(error)) throw error;
-		}
-		await waitForStreamChangeOrPoll(nonNegativeTimerDelay(options.pollInterval ?? DEFAULT_STREAM_FOLLOW_POLL_INTERVAL, "Workflow stream wait pollInterval").clampedDelay, options.signal, waitOptions.waitForChange);
-	}
-}
-async function waitForStreamChunk(read, afterIndex, options = {}, waitOptions = {}) {
-	if (!isNonNegativeSafeInteger(afterIndex)) WorkflowOptionsError.nonNegativeSafeInteger("Workflow stream chunk wait afterIndex");
-	while (true) {
-		if (options.signal?.aborted) return;
-		const stream = await read({ fromIndex: afterIndex + 1 });
-		const chunk = stream.chunks[0];
-		if (chunk !== void 0) return chunk;
-		if (stream.status !== "open") return;
-		await waitForStreamChangeOrPoll(nonNegativeTimerDelay(options.pollInterval ?? DEFAULT_STREAM_FOLLOW_POLL_INTERVAL, "Workflow stream wait pollInterval").clampedDelay, options.signal, waitOptions.waitForChange);
-	}
-}
-async function waitForStreamTerminal(readInfo, options = {}, waitOptions = {}) {
-	while (true) {
-		if (options.signal?.aborted === true) return;
-		const info = await readInfo();
-		if (info.status !== "open") return info;
-		await waitForStreamChangeOrPoll(nonNegativeTimerDelay(options.pollInterval ?? DEFAULT_STREAM_FOLLOW_POLL_INTERVAL, "Workflow stream wait pollInterval").clampedDelay, options.signal, waitOptions.waitForChange);
-	}
-}
-function getStreamInfo(runId, events, streamIdOrName) {
-	return getStreamInfoFromHistory(runId, new WorkflowHistory(events), streamIdOrName);
-}
 function getStreamInfoFromHistory(runId, history, streamIdOrName) {
 	return getStreamInfoFromProjection(runId, requireStreamProjectionFromHistory(history, streamIdOrName));
 }
 function requireStreamProjectionFromHistory(history, streamIdOrName) {
 	const projection = history.streamProjection(streamIdOrName);
-	if (projection === void 0) WorkflowStreamNotFoundError.notFound(streamIdOrName);
+	if (projection === void 0) throw new WorkflowStreamNotFoundError(streamIdOrName);
 	return projection;
 }
 function getStreamInfoFromProjection(runId, projection) {
@@ -252,20 +132,28 @@ function getStreamInfoFromProjection(runId, projection) {
 		status: failed === void 0 ? closed === void 0 ? "open" : "closed" : "failed",
 		createdAt: started.timestamp,
 		updatedAt: failed?.event.timestamp ?? closed?.event.timestamp ?? latestChunk?.timestamp ?? started.timestamp,
-		...started.contentType === void 0 ? {} : { contentType: started.contentType },
-		...started.metadata === void 0 ? {} : { metadata: started.metadata },
+		contentType: started.contentType,
+		metadata: started.metadata,
 		chunkCount: chunks.length,
-		...latestChunk === void 0 ? {} : { lastIndex: latestChunk.index },
-		...failed === void 0 ? {} : { error: failed.event.error }
+		lastIndex: latestChunk?.index,
+		error: failed?.event.error
 	};
 }
 function requireStreamEventOrder(projection) {
 	const { started, chunks, closed, failed } = projection;
-	for (const [index, chunk] of chunks.entries()) if (chunk.event.index !== index) WorkflowStreamError.nonContiguousChunkIndex(started.streamId, chunk.event.index, index);
+	for (const [index, chunk] of chunks.entries()) if (chunk.event.index !== index) throw new WorkflowStreamError(`Workflow stream ${started.streamId} has non-contiguous chunk index ${chunk.event.index}; expected ${index}`, WorkflowErrorCode.STREAM_CHUNK_INDEX_NON_CONTIGUOUS, {
+		streamId: started.streamId,
+		actualIndex: chunk.event.index,
+		expectedIndex: index
+	});
 	const terminal = earliestStreamTerminalEvent(closed, failed);
 	if (terminal === void 0) return;
 	const lateChunk = chunks.find((chunk) => chunk.index > terminal.index);
-	if (lateChunk !== void 0) WorkflowStreamError.chunkAfterTerminal(started.streamId, lateChunk.event.index, terminal.event.kind);
+	if (lateChunk !== void 0) throw new WorkflowStreamError(`Workflow stream ${started.streamId} has chunk ${lateChunk.event.index} after terminal event ${terminal.event.kind}`, WorkflowErrorCode.STREAM_CHUNK_AFTER_TERMINAL, {
+		streamId: started.streamId,
+		chunkIndex: lateChunk.event.index,
+		terminalKind: terminal.event.kind
+	});
 }
 function earliestStreamTerminalEvent(closed, failed) {
 	if (closed === void 0) return failed;
@@ -274,47 +162,20 @@ function earliestStreamTerminalEvent(closed, failed) {
 }
 async function ensureStreamStarted(environment, identity, streamId, contentType, metadata) {
 	if (environment.history.startedStream(identity.id) !== void 0) return;
-	await appendDurableStepStartedEvent(environment, {
+	const event = {
 		kind: "stream_started",
 		timestamp: environment.now(),
 		stepId: identity.id,
 		stepName: identity.name,
 		count: identity.count,
 		streamId,
-		...contentType === void 0 ? {} : { contentType },
-		...metadata === void 0 ? {} : { metadata }
-	});
-}
-async function sleepForStreamFollow(milliseconds, signal) {
-	if (milliseconds === 0 || signal?.aborted) return;
-	await new Promise((resolve) => {
-		const timer = setTimeout(resolve, milliseconds);
-		signal?.addEventListener("abort", () => {
-			clearTimeout(timer);
-			resolve();
-		}, { once: true });
-	});
-}
-async function waitForStreamChangeOrPoll(milliseconds, signal, waitForChange) {
-	if (waitForChange === void 0) {
-		await sleepForStreamFollow(milliseconds, signal);
-		return;
-	}
-	const controller = new AbortController();
-	const abort = () => {
-		controller.abort();
+		contentType,
+		metadata
 	};
-	signal?.addEventListener("abort", abort, { once: true });
-	try {
-		if (signal?.aborted === true) return;
-		await Promise.race([sleepForStreamFollow(milliseconds, controller.signal), waitForChange({ signal: controller.signal })]);
-	} finally {
-		signal?.removeEventListener("abort", abort);
-		controller.abort();
-	}
+	await appendDurableStepStartedEvent(environment, event);
 }
 function requireStreamOpen(environment, stepId, streamId) {
-	if (environment.history.closedStream(stepId) !== void 0 || environment.history.failedStream(stepId) !== void 0) WorkflowStreamError.alreadyClosed(streamId);
+	if (environment.history.closedStream(stepId) !== void 0 || environment.history.failedStream(stepId) !== void 0) throw new WorkflowStreamError(`Workflow stream is already closed: ${streamId}`, WorkflowErrorCode.STREAM_ALREADY_CLOSED, { streamId });
 }
 function requireStreamReplayMatches(identity, recorded, next) {
 	if (recorded.stepId === identity.id && recorded.stepName === identity.name && recorded.streamId === next.streamId && recorded.contentType === next.contentType && deepEquals(recorded.metadata, next.metadata)) return;
@@ -325,10 +186,7 @@ function requireStreamReplayMatches(identity, recorded, next) {
 }
 function requireStreamChunkReplayMatches(identity, index, recorded, next) {
 	if (deepEquals(recorded, next)) return;
-	WorkflowReplayDivergenceError.diverged(`recorded stream ${identity.id} chunk ${index} does not match replayed chunk`, {
-		expectedStepId: identity.id,
-		actualStepId: identity.id
-	});
+	WorkflowReplayDivergenceError.atStep(identity.id, `recorded stream ${identity.id} chunk ${index} does not match replayed chunk`);
 }
 //#endregion
-export { createStream, createWorkflowStepStreamApi, followStream, followStreamForRun, getStreamInfo, getStreamInfoForRun, readStream, readStreamForRun, readStreamPageForRun, waitForStream, waitForStreamChunk, waitForStreamChunkForRun, waitForStreamForRun, waitForStreamTerminal, waitForStreamTerminalForRun };
+export { createStepStreamApi, getStreamInfoFromHistory, readStreamFromHistory };

package/dist/engine/summary/recovery.d.mts

@@ -0,0 +1,35 @@
+import { ScheduleRecord } from "../../types/schedule.mjs";
+import { LockRecord } from "../../types/lock.mjs";
+import { RecoverySummary } from "../../types/summary.mjs";
+import { StepAttemptRecord } from "../../types/step-attempts.mjs";
+import { RunRecord } from "../../types/run.mjs";
+import { EventRecord } from "../../types/events.mjs";
+//#region src/engine/summary/recovery.d.ts
+export interface RecoverySummaryInputs {
+  readonly sleepAttempts?: readonly StepAttemptRecord[];
+  readonly messageWaitAttempts?: readonly StepAttemptRecord[];
+  readonly childWorkflowAttempts?: readonly StepAttemptRecord[];
+  readonly childRuns?: readonly RunRecord[];
+  readonly eventsByRunId?: ReadonlyMap<string, readonly EventRecord[]>;
+  readonly lockWaitAttempts?: readonly StepAttemptRecord[];
+  readonly locks?: readonly LockRecord[];
+  readonly schedules?: readonly ScheduleRecord[];
+}
+interface RecoverySummaryOptions {
+  readonly runs: readonly RunRecord[];
+  readonly now: Temporal.Instant;
+  readonly inputs?: RecoverySummaryInputs;
+}
+/**
+ * Every run that can make progress now, and when the next sleep, retry, lease, schedule,
+ * lock wait, or external wait should be checked again.
+ */
+export declare function summarizeRecovery(options: RecoverySummaryOptions): RecoverySummary;
+interface LockWaitDetails {
+  readonly key: string;
+  readonly waitDeadlineAt?: Temporal.Instant;
+}
+/** The lock a failed step attempt was waiting for, when it failed because the lock was held. */
+export declare function lockWaitDetails(attempt: StepAttemptRecord): LockWaitDetails | undefined;
+//#endregion
+export {};