@temelj/workflow 0.0.0-alpha.1

package/dist/engine/lock.mjs

@@ -0,0 +1,197 @@
+import { WorkflowOptionsError } from "../errors/base.mjs";
+import { WorkflowNonRetryableError, WorkflowRetryableError } from "../errors/failures.mjs";
+import { isPositiveSafeInteger, positiveSafeInteger } from "../utility.mjs";
+import { WorkflowLockError, WorkflowLockStateError } from "../errors/lock.mjs";
+import "../errors/mod.mjs";
+import { WorkflowSuspended, patchRun } from "./state.mjs";
+import { recordWorkflowDeterministicValue } from "./deterministic.mjs";
+import { requireLockReleaseReplayMatches, requireLockReplayMatches, requireLockWaitDeadlineReplayMatches, requireLockWaitReplayMatches } from "./lock-replay.mjs";
+//#region src/engine/lock.ts
+function createWorkflowStepLockApi(environment, engine, run) {
+	const { runId, history } = environment;
+	const acquire = async (commandId, key, options) => {
+		const requestedLeaseDuration = positiveSafeInteger(options.leaseDuration.total({ unit: "millisecond" }), "Workflow lock lease duration");
+		const waitDeadlineAt = options.waitTimeout === void 0 ? void 0 : await recordLockWaitDeadline(environment, commandId, options.waitTimeout);
+		const { waitTimeout: _waitTimeout, ...engineLockOptions } = options;
+		const lock = await run({
+			commandId,
+			retry: { maximumAttempts: options.wait === true ? 0 : 1 }
+		}, async (context) => {
+			return await engine.acquireLock(key, {
+				...engineLockOptions,
+				holderId: options.holderId ?? runId,
+				holderRunId: runId,
+				holderStepId: context.step.id,
+				...waitDeadlineAt === void 0 ? {} : { waitDeadlineAt }
+			});
+		});
+		requireLockReplayMatches(lock, {
+			key,
+			holderId: options.holderId ?? runId,
+			holderRunId: runId,
+			leaseDuration: requestedLeaseDuration
+		});
+		requireLockWaitReplayMatches(history.failedSteps(`run:${commandId}`), {
+			key,
+			wait: options.wait === true
+		});
+		return lock;
+	};
+	const release = async (commandId, key, options) => {
+		const holderId = options?.holderId ?? runId;
+		const lock = await run({
+			commandId,
+			retry: { maximumAttempts: 1 }
+		}, async () => {
+			return await engine.releaseLock(key, {
+				holderId,
+				...options?.now === void 0 ? {} : { now: options.now }
+			});
+		});
+		requireLockReleaseReplayMatches(lock, {
+			key,
+			holderId
+		});
+		return lock;
+	};
+	return {
+		acquire,
+		release,
+		async with(commandId, key, options, callback) {
+			const lock = await acquire(`${commandId}:acquire`, key, options);
+			try {
+				const output = await callback(lock);
+				await release(`${commandId}:release`, key, {
+					...options.holderId === void 0 ? {} : { holderId: options.holderId },
+					...options.now === void 0 ? {} : { now: options.now }
+				});
+				return output;
+			} catch (error) {
+				if (error instanceof WorkflowSuspended) throw error;
+				await release(`${commandId}:release`, key, {
+					...options.holderId === void 0 ? {} : { holderId: options.holderId },
+					...options.now === void 0 ? {} : { now: options.now }
+				});
+				throw error;
+			}
+		}
+	};
+}
+async function acquireLock(store, key, lockOptions, acquiredAt) {
+	const holderId = lockOptions.holderId;
+	const leaseDuration = positiveDurationMilliseconds(lockOptions.leaseDuration, "Workflow lock lease duration");
+	const waitDeadlineAt = resolveLockWaitDeadline(lockOptions, acquiredAt);
+	const existing = await store.getLock(key);
+	if (existing !== void 0 && !(existing.holderId === holderId || existing.releasedAt !== void 0) && Temporal.Instant.compare(existing.leaseExpiresAt, acquiredAt) > 0) {
+		if (lockOptions.wait === true) {
+			if (waitDeadlineAt !== void 0 && Temporal.Instant.compare(waitDeadlineAt, acquiredAt) <= 0) WorkflowNonRetryableError.failed(`Workflow lock wait timed out: ${key}`, { details: {
+				key,
+				holderId,
+				currentHolderId: existing.holderId,
+				waitDeadlineAt: waitDeadlineAt.toString()
+			} });
+			const retryAt = workflowLockRetryAt(existing, acquiredAt, waitDeadlineAt);
+			throw WorkflowRetryableError.lockAlreadyHeld(key, {
+				retryAt,
+				details: {
+					key,
+					holderId,
+					currentHolderId: existing.holderId,
+					...waitDeadlineAt === void 0 ? {} : { waitDeadlineAt: waitDeadlineAt.toString() }
+				}
+			});
+		}
+		WorkflowLockError.alreadyHeld(key);
+	}
+	const lock = {
+		key,
+		namespace: store.namespace,
+		holderId,
+		...lockOptions.holderRunId === void 0 ? {} : { holderRunId: lockOptions.holderRunId },
+		...lockOptions.holderStepId === void 0 ? {} : { holderStepId: lockOptions.holderStepId },
+		fencingToken: (existing?.fencingToken ?? 0) + 1,
+		acquiredAt,
+		leaseExpiresAt: acquiredAt.add(Temporal.Duration.from({ milliseconds: leaseDuration }))
+	};
+	const acquired = await store.updateLockIfCurrent(existing, lock);
+	if (acquired === void 0) WorkflowLockStateError.acquireConflictExhausted(key);
+	return acquired;
+}
+async function releaseLock(store, key, lockOptions, releasedAt) {
+	const holderId = lockOptions.holderId;
+	const current = await store.getLock(key);
+	if (current === void 0) WorkflowLockStateError.notFound(key);
+	if (current.holderId !== holderId) WorkflowLockError.holderMismatch(key);
+	const released = {
+		...current,
+		releasedAt
+	};
+	const updated = await store.updateLockIfCurrent(current, released);
+	if (updated === void 0) WorkflowLockStateError.releaseConflictExhausted(key);
+	await wakeWorkflowRunsWaitingForLock(store, key, releasedAt);
+	return updated;
+}
+async function releaseStaleLock(store, key, releasedAt) {
+	const current = await store.getLock(key);
+	if (current === void 0) WorkflowLockStateError.notFound(key);
+	if (current.releasedAt !== void 0) WorkflowLockError.alreadyReleased(key);
+	if (Temporal.Instant.compare(current.leaseExpiresAt, releasedAt) > 0) WorkflowLockError.notStale(key);
+	const released = {
+		...current,
+		releasedAt
+	};
+	const updated = await store.updateLockIfCurrent(current, released);
+	if (updated === void 0) WorkflowLockStateError.staleReleaseConflictExhausted(key);
+	await wakeWorkflowRunsWaitingForLock(store, key, releasedAt);
+	return updated;
+}
+function resolveLockWaitDeadline(options, now) {
+	if (options.waitTimeout !== void 0 && options.waitDeadlineAt !== void 0) WorkflowLockError.waitDeadlineConflict();
+	if ((options.waitTimeout !== void 0 || options.waitDeadlineAt !== void 0) && options.wait !== true) WorkflowLockError.timeoutRequiresWait();
+	if (options.waitDeadlineAt !== void 0) return options.waitDeadlineAt;
+	if (options.waitTimeout === void 0) return;
+	positiveDurationMilliseconds(options.waitTimeout, "Workflow lock waitTimeout");
+	return now.add(options.waitTimeout);
+}
+function positiveDurationMilliseconds(duration, label) {
+	const milliseconds = duration.total({ unit: "millisecond" });
+	if (!isPositiveSafeInteger(milliseconds)) WorkflowOptionsError.positiveSafeIntegerDuration(label);
+	return milliseconds;
+}
+async function recordLockWaitDeadline(environment, name, timeout) {
+	const resolvedTimeout = positiveSafeInteger(timeout.total({ unit: "millisecond" }), "Workflow lock waitTimeout");
+	return await recordWorkflowDeterministicValue(environment, `${name}:wait-deadline`, () => environment.now().add(Temporal.Duration.from({ milliseconds: resolvedTimeout })), (recorded) => requireLockWaitDeadlineReplayMatches(recorded, resolvedTimeout));
+}
+function workflowLockRetryAt(lock, now, waitDeadlineAt) {
+	const retryAt = Temporal.Instant.compare(lock.leaseExpiresAt, now) <= 0 ? now : lock.leaseExpiresAt;
+	if (waitDeadlineAt !== void 0 && Temporal.Instant.compare(waitDeadlineAt, retryAt) < 0) return waitDeadlineAt;
+	return retryAt;
+}
+async function wakeWorkflowRunsWaitingForLock(store, key, timestamp) {
+	const wakeAt = timestamp;
+	const waitingRuns = await store.listRuns({
+		status: "waiting",
+		retryReason: "step"
+	});
+	await Promise.all(waitingRuns.map(async (run) => {
+		if (run.availableAt !== void 0 && Temporal.Instant.compare(run.availableAt, wakeAt) <= 0) return;
+		if (!(await store.listStepAttempts(run.id, {
+			kind: "run",
+			status: "failed"
+		})).some((attempt) => WorkflowRetryableError.isLockAlreadyHeld(attempt.error, key))) return;
+		await patchRun(store, run, {
+			availableAt: wakeAt,
+			retryAt: wakeAt,
+			updatedAt: wakeAt,
+			lastTransitionAt: wakeAt,
+			lastTransitionReason: "retry",
+			deadlineAt: run.deadlineAt,
+			startedAt: run.startedAt ?? wakeAt,
+			error: run.error,
+			output: void 0,
+			finishedAt: void 0
+		});
+	}));
+}
+//#endregion
+export { acquireLock, createWorkflowStepLockApi, releaseLock, releaseStaleLock };

package/dist/engine/message.d.mts

@@ -0,0 +1,47 @@
+import { RunId } from "../types/run-id.mjs";
+import { BroadcastMessageChannelOptions, BroadcastMessageInput, BroadcastMessageResult, MessageChannel, SendMessageChannelOptions, SendMessageInput, SendMessageOptions, WaitForMessageOptions } from "../types/message.mjs";
+import { WorkflowStepMessageApi } from "../types/step.mjs";
+import { Telemetry, TelemetryContext } from "../types/telemetry.mjs";
+import { WorkflowStepIdentity } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import "../history/mod.mjs";
+import { WorkflowConditionalEventAppender, WorkflowEventReader, WorkflowMessageIdempotencyIndexLookup, WorkflowRunConditionalWriterRepository, WorkflowRunListerRepository, WorkflowRunReaderRepository } from "../types/store.mjs";
+import { WorkflowExecutionLimits } from "../types/engine-options.mjs";
+import { WorkflowExecutionEnvironment } from "../types/engine.mjs";
+import { Schema } from "@temelj/standard-schema";
+//#region src/engine/message.d.ts
+type MessageWaitSource = Extract<EventRecord, {
+  readonly kind: "message_wait_started";
+}>["source"];
+type WorkflowMessageWaitOptions = WaitForMessageOptions<Schema | undefined> & {
+  readonly source?: MessageWaitSource;
+};
+type WorkflowMessageDeliveryStore = WorkflowMessageIdempotencyIndexLookup & WorkflowRunReaderRepository & WorkflowEventReader & WorkflowConditionalEventAppender & WorkflowRunConditionalWriterRepository;
+type WorkflowMessageStore = WorkflowMessageDeliveryStore & WorkflowRunListerRepository;
+interface WorkflowMessageServiceOptions {
+  readonly store: WorkflowMessageStore;
+  readonly now: () => Temporal.Instant;
+  readonly limits: WorkflowExecutionLimits;
+  readonly observeMessageSent?: (runId: RunId, event: Extract<EventRecord, {
+    readonly kind: "message_sent";
+  }>) => void;
+  readonly telemetry?: Telemetry;
+}
+declare function createWorkflowStepMessageApi(environment: WorkflowExecutionEnvironment): WorkflowStepMessageApi;
+declare function sendWorkflowMessageInput<TPayload, TKey = void>(service: WorkflowMessageServiceOptions, runId: RunId, messageInput: SendMessageInput | MessageChannel<TPayload, TKey>, channelOptions: SendMessageChannelOptions<TPayload, TKey> | undefined): Promise<void>;
+declare function broadcastWorkflowMessageInput<TPayload, TKey = void>(service: WorkflowMessageServiceOptions, messageInput: BroadcastMessageInput | MessageChannel<TPayload, TKey>, channelOptions: BroadcastMessageChannelOptions<TPayload, TKey> | undefined): Promise<BroadcastMessageResult>;
+declare function sendWorkflowMessage(store: WorkflowMessageDeliveryStore, runId: RunId, options: SendMessageOptions, now: () => Temporal.Instant, limits: WorkflowExecutionLimits, observeMessageSent?: (runId: RunId, event: Extract<EventRecord, {
+  readonly kind: "message_sent";
+}>) => void, telemetry?: Telemetry, traceContext?: TelemetryContext): Promise<void>;
+declare function waitForWorkflowMessage(environment: WorkflowExecutionEnvironment, options: WorkflowMessageWaitOptions): Promise<unknown>;
+declare function requireMessageWaitReplayMatches(identity: WorkflowStepIdentity, started: Extract<EventRecord, {
+  readonly kind: "message_wait_started";
+}> | undefined, event: Extract<EventRecord, {
+  readonly kind: "message_wait_started" | "message_wait_completed" | "message_wait_failed";
+}>, options: WorkflowMessageWaitOptions): void;
+declare function messageWaitAvailableAt(now: () => Temporal.Instant, timeoutAt: Temporal.Instant | undefined, deadlineAt: Temporal.Instant | undefined): Temporal.Instant;
+declare function wakeRunForMessageEvent(store: WorkflowRunReaderRepository & WorkflowEventReader & WorkflowRunConditionalWriterRepository, runId: RunId, messageEvent: Extract<EventRecord, {
+  readonly kind: "message_sent";
+}>): Promise<void>;
+//#endregion
+export { broadcastWorkflowMessageInput, createWorkflowStepMessageApi, messageWaitAvailableAt, requireMessageWaitReplayMatches, sendWorkflowMessage, sendWorkflowMessageInput, waitForWorkflowMessage, wakeRunForMessageEvent };

package/dist/engine/message.mjs

@@ -0,0 +1,357 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import { WorkflowDurationError, WorkflowReplayDivergenceError } from "../errors/failures.mjs";
+import { getRequiredRun, safeDuration } from "../utility.mjs";
+import { WorkflowMessageDeliveryError, WorkflowMessageIdempotencyConflictError, WorkflowMessageWaitTimeoutError } from "../errors/message.mjs";
+import { resolveBroadcastMessageInput, resolveSendMessageInput, resolveWaitForMessageInput } from "../message-options.mjs";
+import { workflowErrorFromRecord } from "../errors/records.mjs";
+import { captureTelemetryContext } from "../telemetry.mjs";
+import { serializeError, toOptionalPersistedValue } from "./serialization.mjs";
+import { WorkflowHistory } from "../history/mod.mjs";
+import { enforceWorkflowEventHistoryNextLimit } from "./retry.mjs";
+import { WorkflowSuspended } from "./state.mjs";
+import { resolveWorkflowCommandIdentity, resolveWorkflowCommandIdentityFromCandidates } from "./command-identity.mjs";
+import { appendDurableStepStartedEvent, appendDurableStepTerminalEvent } from "./durable-command.mjs";
+import { requireMessageSendReplayMatches, requireRecordedDurableTerminalStarted } from "./replay.mjs";
+import { validateStandardSchema } from "@temelj/standard-schema";
+import { deepEquals } from "@temelj/value";
+//#region src/engine/message.ts
+const MAX_MESSAGE_DELIVERY_APPEND_ATTEMPTS = 16;
+function createWorkflowStepMessageApi(environment) {
+	const { store, history, now, limits } = environment;
+	return {
+		async send(targetRunId, messageInput, channelOptions) {
+			const options = await resolveSendMessageInput(messageInput, channelOptions);
+			const idempotencyKey = options.idempotencyKey;
+			const identity = resolveWorkflowCommandIdentity(history, "message-send", options.messageId);
+			const started = history.startedMessageSend(identity.id);
+			const completed = history.completedMessageSend(identity.id);
+			if (completed !== void 0) {
+				requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(completed));
+				requireMessageSendReplayMatches(identity, started, completed, {
+					targetRunId,
+					messageId: options.messageId,
+					payload: toOptionalPersistedValue(options.payload, "message payload", limits),
+					idempotencyKey
+				});
+				if (!(completed.timestamp instanceof Temporal.Instant)) WorkflowReplayDivergenceError.diverged(`recorded message-send step ${identity.id} has invalid completion timestamp: ` + String(completed.timestamp), {
+					expectedStepId: identity.id,
+					actualStepId: identity.id
+				});
+				return;
+			}
+			const failed = history.failedMessageSend(identity.id);
+			if (failed !== void 0) {
+				requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(failed));
+				requireMessageSendReplayMatches(identity, started, failed, {
+					targetRunId,
+					messageId: options.messageId,
+					payload: toOptionalPersistedValue(options.payload, "message payload", limits),
+					idempotencyKey
+				});
+				if (!(failed.timestamp instanceof Temporal.Instant)) WorkflowReplayDivergenceError.diverged(`recorded message-send step ${identity.id} has invalid failure timestamp: ` + String(failed.timestamp), {
+					expectedStepId: identity.id,
+					actualStepId: identity.id
+				});
+				throw workflowErrorFromRecord(failed.error);
+			}
+			const nextMessageSend = {
+				targetRunId,
+				messageId: options.messageId,
+				payload: toOptionalPersistedValue(options.payload, "message payload", limits),
+				idempotencyKey
+			};
+			if (started === void 0) await appendDurableStepStartedEvent(environment, {
+				kind: "message_send_started",
+				timestamp: now(),
+				stepId: identity.id,
+				stepName: identity.name,
+				count: identity.count,
+				targetRunId: nextMessageSend.targetRunId,
+				messageId: nextMessageSend.messageId,
+				payload: nextMessageSend.payload,
+				...nextMessageSend.idempotencyKey === void 0 ? {} : { idempotencyKey: nextMessageSend.idempotencyKey }
+			});
+			else requireMessageSendReplayMatches(identity, started, started, nextMessageSend);
+			try {
+				await sendWorkflowMessage(store, targetRunId, {
+					...options,
+					idempotencyKey
+				}, now, limits, environment.observeMessageSent, environment.telemetry);
+			} catch (error) {
+				await appendDurableStepTerminalEvent(environment, {
+					kind: "message_send_failed",
+					timestamp: now(),
+					stepId: identity.id,
+					stepName: identity.name,
+					targetRunId,
+					messageId: options.messageId,
+					error: serializeError(error)
+				});
+				throw error;
+			}
+			await appendDurableStepTerminalEvent(environment, {
+				kind: "message_send_completed",
+				timestamp: now(),
+				stepId: identity.id,
+				stepName: identity.name,
+				targetRunId,
+				messageId: options.messageId
+			});
+		},
+		async wait(messageInput, channelOptions) {
+			return await waitForWorkflowMessage(environment, resolveWaitForMessageInput(messageInput, channelOptions));
+		}
+	};
+}
+async function sendWorkflowMessageInput(service, runId, messageInput, channelOptions) {
+	const telemetryContext = captureTelemetryContext(service.telemetry);
+	const messageOptions = await resolveSendMessageInput(messageInput, channelOptions);
+	await sendWorkflowMessage(service.store, runId, messageOptions, service.now, service.limits, service.observeMessageSent, service.telemetry, telemetryContext);
+}
+async function broadcastWorkflowMessageInput(service, messageInput, channelOptions) {
+	const telemetryContext = captureTelemetryContext(service.telemetry);
+	const messageOptions = await resolveBroadcastMessageInput(messageInput, channelOptions);
+	toOptionalPersistedValue(messageOptions.payload, "message payload", service.limits);
+	const targets = await broadcastMessageTargets(service.store, messageOptions.target);
+	for (const target of targets) await sendWorkflowMessage(service.store, target.id, messageOptions, service.now, service.limits, service.observeMessageSent, service.telemetry, telemetryContext);
+	return {
+		messageId: messageOptions.messageId,
+		runIds: targets.map((target) => target.id),
+		deliveredMessages: targets.length
+	};
+}
+async function sendWorkflowMessage(store, runId, options, now, limits, observeMessageSent, telemetry, traceContext) {
+	const targetRunId = runId;
+	const idempotencyKey = options.idempotencyKey;
+	const telemetryContext = traceContext ?? captureTelemetryContext(telemetry);
+	const run = await getRequiredRun(store, targetRunId);
+	const payload = toOptionalPersistedValue(options.payload, "message payload", limits);
+	let timestamp;
+	let appendedEvents;
+	for (let attempt = 0; attempt < MAX_MESSAGE_DELIVERY_APPEND_ATTEMPTS && appendedEvents === void 0; attempt++) {
+		const currentRun = attempt === 0 ? run : await getRequiredRun(store, targetRunId);
+		const currentEvents = await store.getEvents(targetRunId);
+		const currentHistory = new WorkflowHistory(currentEvents);
+		if (idempotencyKey !== void 0) {
+			const existingMessage = currentHistory.messageByIdempotencyKey(idempotencyKey);
+			if (existingMessage !== void 0) {
+				if (existingMessage.messageId === options.messageId && deepEquals(existingMessage.payload, payload)) {
+					await wakeRunForMessageEvent(store, targetRunId, existingMessage);
+					return;
+				}
+				WorkflowMessageIdempotencyConflictError.conflict({
+					runId: targetRunId,
+					messageId: options.messageId,
+					idempotencyKey
+				});
+			}
+			await requireMessageIdempotencyIndexUnclaimed(store, targetRunId, options.messageId, idempotencyKey);
+		}
+		if (currentRun.status === "completed" || currentRun.status === "failed" || currentRun.status === "canceled") WorkflowMessageDeliveryError.cannotSend({
+			runId: targetRunId,
+			status: currentRun.status,
+			messageId: options.messageId
+		});
+		const waiterStepIds = currentHistory.activeMessageWaitStepIds(options.messageId);
+		timestamp ??= now();
+		enforceWorkflowEventHistoryNextLimit(currentEvents, limits);
+		appendedEvents = await store.appendEventIfRunCurrent(currentRun, {
+			kind: "message_sent",
+			timestamp,
+			messageId: options.messageId,
+			payload,
+			...waiterStepIds.length === 0 ? {} : { waiterStepIds },
+			...idempotencyKey === void 0 ? {} : { idempotencyKey },
+			...telemetryContext === void 0 ? {} : { telemetryContext }
+		});
+	}
+	if (appendedEvents === void 0) {
+		const currentRun = await getRequiredRun(store, targetRunId);
+		if (currentRun.status === "completed" || currentRun.status === "failed" || currentRun.status === "canceled") WorkflowMessageDeliveryError.cannotSend({
+			runId: targetRunId,
+			status: currentRun.status,
+			messageId: options.messageId
+		});
+		WorkflowStateError.failedMessageAppend(targetRunId);
+	}
+	const appendedHistory = new WorkflowHistory(appendedEvents);
+	if (idempotencyKey !== void 0) {
+		const existingMessage = appendedHistory.messageByIdempotencyKey(idempotencyKey);
+		if (existingMessage !== void 0 && !workflowMessageSendMatches(existingMessage, options, payload)) WorkflowMessageIdempotencyConflictError.conflict({
+			runId: targetRunId,
+			messageId: options.messageId,
+			idempotencyKey
+		});
+	}
+	const messageEvent = appendedHistory.messageForSend(options.messageId, idempotencyKey) ?? {
+		kind: "message_sent",
+		timestamp: timestamp ?? now(),
+		messageId: options.messageId,
+		payload,
+		...telemetryContext === void 0 ? {} : { telemetryContext }
+	};
+	observeMessageSent?.(targetRunId, messageEvent);
+	await wakeRunForMessageEvent(store, targetRunId, messageEvent);
+}
+async function broadcastMessageTargets(store, target) {
+	return (await store.listRuns(target)).filter((run) => !(run.status === "completed" || run.status === "failed" || run.status === "canceled"));
+}
+async function requireMessageIdempotencyIndexUnclaimed(store, runId, messageId, idempotencyKey) {
+	if (await store.hasMessageIdempotencyKey(runId, idempotencyKey)) WorkflowMessageIdempotencyConflictError.conflict({
+		runId,
+		messageId,
+		idempotencyKey
+	});
+}
+function workflowMessageSendMatches(event, options, payload) {
+	return event.messageId === options.messageId && deepEquals(event.payload, payload);
+}
+async function waitForWorkflowMessage(environment, options) {
+	const { runId, history, now, limits, executionOwner } = environment;
+	const identity = resolveWorkflowCommandIdentityFromCandidates(history, "message-wait", [
+		options.commandId,
+		options.name,
+		options.messageId
+	], "Workflow message commandId, name, or messageId");
+	const started = history.startedMessageWait(identity.id);
+	const completed = history.completedMessageWait(identity.id);
+	if (completed !== void 0) {
+		requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(completed));
+		requireMessageWaitReplayMatches(identity, started, completed, options);
+		return options.schema === void 0 ? completed.payload : await validateStandardSchema(options.schema, completed.payload, "Workflow message validation failed");
+	}
+	const failed = history.failedMessageWait(identity.id);
+	if (failed !== void 0) {
+		requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(failed));
+		requireMessageWaitReplayMatches(identity, started, failed, options);
+		throw workflowErrorFromRecord(failed.error);
+	}
+	if (started !== void 0) requireMessageWaitReplayMatches(identity, started, started, options);
+	const timeoutAt = started?.timeoutAt === void 0 ? options.timeout === void 0 ? void 0 : (() => {
+		const timeout = safeDuration(options.timeout.total({ unit: "millisecond" }), "Workflow messageId timeout");
+		if (timeout <= 0) WorkflowDurationError.signalTimeoutPositive();
+		return now().add(Temporal.Duration.from({ milliseconds: timeout }));
+	})() : (() => {
+		if (!(started.timeoutAt instanceof Temporal.Instant)) WorkflowReplayDivergenceError.diverged(`recorded message-wait step ${identity.id} has invalid timeout timestamp: ` + String(started.timeoutAt), {
+			expectedStepId: identity.id,
+			actualStepId: identity.id
+		});
+		return started.timeoutAt;
+	})();
+	let waitStartedAt;
+	if (started === void 0) {
+		waitStartedAt = now();
+		await appendDurableStepStartedEvent(environment, {
+			kind: "message_wait_started",
+			timestamp: waitStartedAt,
+			stepId: identity.id,
+			stepName: identity.name,
+			count: identity.count,
+			messageId: options.messageId,
+			...options.source === void 0 ? {} : { source: options.source },
+			...timeoutAt === void 0 ? {} : { timeoutAt }
+		});
+	}
+	const messageId = history.messageForWait(options.messageId, identity.id, timeoutAt);
+	if (messageId !== void 0) {
+		let payload;
+		try {
+			payload = options.schema === void 0 ? messageId.payload : await validateStandardSchema(options.schema, messageId.payload, "Workflow message validation failed");
+		} catch (error) {
+			await appendDurableStepTerminalEvent(environment, {
+				kind: "message_wait_failed",
+				timestamp: now(),
+				stepId: identity.id,
+				stepName: identity.name,
+				messageId: options.messageId,
+				error: serializeError(error)
+			});
+			throw error;
+		}
+		const persistedPayload = toOptionalPersistedValue(payload, "messageId payload", limits);
+		await appendDurableStepTerminalEvent(environment, {
+			kind: "message_wait_completed",
+			timestamp: now(),
+			stepId: identity.id,
+			stepName: identity.name,
+			messageId: options.messageId,
+			...persistedPayload === void 0 ? {} : { payload: persistedPayload },
+			messageTimestamp: messageId.timestamp,
+			...messageId.telemetryContext === void 0 ? {} : { telemetryContext: messageId.telemetryContext }
+		});
+		return payload;
+	}
+	if (timeoutAt !== void 0 && Temporal.Instant.compare(timeoutAt, now()) <= 0) {
+		const error = WorkflowMessageWaitTimeoutError.create({
+			runId,
+			stepId: identity.id,
+			stepName: identity.name,
+			messageId: options.messageId,
+			timeoutAt
+		});
+		await appendDurableStepTerminalEvent(environment, {
+			kind: "message_wait_failed",
+			timestamp: now(),
+			stepId: identity.id,
+			stepName: identity.name,
+			messageId: options.messageId,
+			error: serializeError(error)
+		});
+		throw error;
+	}
+	WorkflowSuspended.until(messageWaitAvailableAt(now, timeoutAt, executionOwner.deadlineAt));
+}
+function requireMessageWaitReplayMatches(identity, started, event, options) {
+	const recordedMessage = started?.messageId ?? event.messageId;
+	if (started !== void 0 && !(started.timestamp instanceof Temporal.Instant)) WorkflowReplayDivergenceError.diverged(`recorded message-wait step ${identity.id} has invalid start timestamp: ` + String(started.timestamp), {
+		expectedStepId: identity.id,
+		actualStepId: identity.id
+	});
+	if (recordedMessage !== options.messageId) WorkflowReplayDivergenceError.diverged(`recorded message-wait step ${identity.id} waited for ${recordedMessage}, but replay waited for ${options.messageId}`, {
+		expectedStepId: identity.id,
+		actualStepId: identity.id
+	});
+	if (started !== void 0 && started.source !== options.source) {
+		const recordedSource = started.source ?? "message";
+		const replaySource = options.source ?? "message";
+		WorkflowReplayDivergenceError.diverged(`recorded message-wait step ${identity.id} was created by ${recordedSource}, but replay used ${replaySource}`, {
+			expectedStepId: identity.id,
+			actualStepId: identity.id
+		});
+	}
+	if (started !== void 0 && started.timeoutAt === void 0 !== (options.timeout === void 0)) {
+		const recordedTimeout = started.timeoutAt === void 0 ? "no timeout" : started.timeoutAt;
+		const replayTimeout = options.timeout === void 0 ? "no timeout" : "a timeout";
+		WorkflowReplayDivergenceError.diverged(`recorded message-wait step ${identity.id} had ${String(recordedTimeout)}, but replay used ${replayTimeout}`, {
+			expectedStepId: identity.id,
+			actualStepId: identity.id
+		});
+	}
+	if (event.kind === "message_wait_completed" && !(event.messageTimestamp instanceof Temporal.Instant)) WorkflowReplayDivergenceError.diverged(`recorded message-wait step ${identity.id} has invalid messageId timestamp: ` + String(event.messageTimestamp), {
+		expectedStepId: identity.id,
+		actualStepId: identity.id
+	});
+}
+function messageWaitAvailableAt(now, timeoutAt, deadlineAt) {
+	return [timeoutAt, deadlineAt].filter((value) => value !== void 0).sort((left, right) => Temporal.Instant.compare(left, right))[0] ?? now().add(Temporal.Duration.from({ milliseconds: 2 ** 31 - 1 }));
+}
+async function wakeRunForMessageEvent(store, runId, messageEvent) {
+	const run = await store.getRun(runId);
+	if (run === void 0 || run.status !== "waiting") return;
+	const activeWaits = new WorkflowHistory(await store.getEvents(runId)).activeMessageWaitStepIds(messageEvent.messageId);
+	if (!(messageEvent.waiterStepIds === void 0 ? activeWaits.length > 0 : activeWaits.some((stepId) => messageEvent.waiterStepIds?.includes(stepId)))) return;
+	await store.updateRunIfCurrent(run, {
+		...run,
+		availableAt: run.availableAt !== void 0 && Temporal.Instant.compare(run.availableAt, messageEvent.timestamp) <= 0 ? run.availableAt : messageEvent.timestamp,
+		updatedAt: messageEvent.timestamp,
+		lastTransitionAt: messageEvent.timestamp,
+		lastTransitionReason: "waiting",
+		deadlineAt: run.deadlineAt,
+		retryAt: run.retryAt,
+		error: void 0,
+		output: void 0,
+		finishedAt: void 0
+	});
+}
+//#endregion
+export { broadcastWorkflowMessageInput, createWorkflowStepMessageApi, messageWaitAvailableAt, requireMessageWaitReplayMatches, sendWorkflowMessage, sendWorkflowMessageInput, waitForWorkflowMessage, wakeRunForMessageEvent };

package/dist/engine/mod.d.mts

@@ -0,0 +1,4 @@
+import { CreateWorkflowEngineOptions, WorkflowDeterministicBytesContext, WorkflowDeterministicValueContext, WorkflowEngineSerializationLimits, WorkflowExecutionLimits, WorkflowRecordedIdContext } from "../types/engine-options.mjs";
+import { LockManager, WorkflowAdmin, WorkflowCleanupAdmin, WorkflowClientEngine, WorkflowEngineLike, WorkflowExecutionEnvironment, WorkflowExecutionEnvironmentStore, WorkflowExecutor, WorkflowHookManager, WorkflowMessageIdempotencyMaintenance, WorkflowMessageSender, WorkflowRunCanceler, WorkflowRunHandleReader, WorkflowRunMaintenance, WorkflowRunReader, WorkflowRunRerunner, WorkflowRunStarter, WorkflowScheduleRunObserver, WorkflowScheduler, WorkflowStarter, WorkflowStepAttemptLookupReader, WorkflowStepAttemptMaintenance, WorkflowStepAttemptReader, WorkflowStreamReader, WorkflowWorkerEngine, WorkflowWorkerEngineStore, WorkflowWorkerOperationObserver } from "../types/engine.mjs";
+import { WorkflowEngine, createWorkflowEngine } from "./create.mjs";
+export { type CreateWorkflowEngineOptions, type LockManager, type WorkflowAdmin, type WorkflowCleanupAdmin, type WorkflowClientEngine, type WorkflowDeterministicBytesContext, type WorkflowDeterministicValueContext, WorkflowEngine, type WorkflowEngineLike, type WorkflowEngineSerializationLimits, type WorkflowExecutionEnvironment, type WorkflowExecutionEnvironmentStore, type WorkflowExecutionLimits, type WorkflowExecutor, type WorkflowHookManager, type WorkflowMessageIdempotencyMaintenance, type WorkflowMessageSender, type WorkflowRecordedIdContext, type WorkflowRunCanceler, type WorkflowRunHandleReader, type WorkflowRunMaintenance, type WorkflowRunReader, type WorkflowRunRerunner, type WorkflowRunStarter, type WorkflowScheduleRunObserver, type WorkflowScheduler, type WorkflowStarter, type WorkflowStepAttemptLookupReader, type WorkflowStepAttemptMaintenance, type WorkflowStepAttemptReader, type WorkflowStreamReader, type WorkflowWorkerEngine, type WorkflowWorkerEngineStore, type WorkflowWorkerOperationObserver, createWorkflowEngine };

package/dist/engine/mod.mjs

@@ -0,0 +1,2 @@
+import { WorkflowEngine, createWorkflowEngine } from "./create.mjs";
+export { WorkflowEngine, createWorkflowEngine };

package/dist/engine/observation.d.mts

@@ -0,0 +1,35 @@
+import { MessageId } from "../types/message-id.mjs";
+import { RunId } from "../types/run-id.mjs";
+import { CleanupRunsResult } from "../types/cleanup.mjs";
+import { ChildWorkflowStartedObservationEvent, ObservationEmitter as ObservationEmitter$1, ObservationEventHandler, ObservationEventPattern, ScheduleRunCreatedObservationEvent, ScheduleTickObservationEvent, WorkerOperationObservationEvent } from "../types/observation.mjs";
+import { Telemetry, TelemetryContext } from "../types/telemetry.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord, MessageSentEvent } from "../types/events.mjs";
+import { StorageValue } from "@temelj/storage";
+//#region src/engine/observation.d.ts
+declare function createObservationEmitter(telemetry?: Telemetry): ObservationEmitter$1;
+declare class ObservationEmitter implements ObservationEmitter$1 {
+  #private;
+  constructor(telemetry?: Telemetry);
+  on<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): () => void;
+  once<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): () => void;
+  off<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): void;
+  clearListeners(pattern?: ObservationEventPattern): void;
+  listenerCount(pattern?: ObservationEventPattern): number;
+  listeners(): readonly ObservationEventHandler[];
+  listeners<Pattern extends ObservationEventPattern>(pattern: Pattern): readonly ObservationEventHandler<Pattern>[];
+  emitRunEvent(run: WorkflowRunRecord, previousRun?: WorkflowRunRecord): void;
+  emitRunMetadataUpdated(run: WorkflowRunRecord, previousRun?: WorkflowRunRecord): void;
+  emitDurableEventAppended(runId: RunId, event: EventRecord, appendedEvents: readonly EventRecord[]): void;
+  emitMessageSent(runId: RunId, event: MessageSentEvent): void;
+  emitHookResumed(runId: RunId, messageId: MessageId, payload: StorageValue | undefined, traceContext: TelemetryContext | undefined): void;
+  emitWebhookResumed(runId: RunId, messageId: MessageId, payload: StorageValue | undefined, traceContext: TelemetryContext | undefined): void;
+  emitChildWorkflowStarted(event: ChildWorkflowStartedObservationEvent): void;
+  emitCleanupCompleted(result: CleanupRunsResult): void;
+  emitRetentionApplied(result: CleanupRunsResult): void;
+  emitWorkerOperation(event: WorkerOperationObservationEvent): void;
+  emitScheduleTicked(event: ScheduleTickObservationEvent): void;
+  emitScheduleRunCreated(event: ScheduleRunCreatedObservationEvent): void;
+}
+//#endregion
+export { ObservationEmitter, createObservationEmitter };