@temelj/workflow 0.0.0-alpha.1

package/dist/engine/hooks.mjs

@@ -0,0 +1,237 @@
+import { WorkflowHookError } from "../errors/hook.mjs";
+import { WorkflowHookDisposedError } from "../errors/message.mjs";
+import "../errors/mod.mjs";
+import { captureTelemetryContext } from "../telemetry.mjs";
+import { serializeError, toOptionalPersistedValue, toPersistedValue } from "./serialization.mjs";
+import { WorkflowHistory } from "../history/mod.mjs";
+import { enforceWorkflowEventHistoryNextLimit } from "./retry.mjs";
+import { WORKFLOW_HOOK_TOKEN_PREFIX, parseHookToken, parseWebhookToken } from "../types/hook.mjs";
+import { sendWorkflowMessage, waitForWorkflowMessage } from "./message.mjs";
+import { encodeBase64UrlString } from "@temelj/string";
+//#region src/engine/hooks.ts
+const MAX_HOOK_DISPOSAL_APPEND_ATTEMPTS = 16;
+function createHook(runId, options, wait) {
+	return new Hook(runId, options, wait);
+}
+function createWebhook(runId, options, wait) {
+	return new Webhook(runId, options, wait);
+}
+function createWorkflowStepHookApi(environment) {
+	const { runId } = environment;
+	const tokens = /* @__PURE__ */ new Set();
+	return {
+		create(options) {
+			const hook = createHook(runId, options, async () => {
+				return await waitForWorkflowMessage(environment, {
+					commandId: options.commandId ?? options.name,
+					messageId: options.messageId ?? options.name,
+					source: "hook",
+					...options.timeout === void 0 ? {} : { timeout: options.timeout },
+					...options.schema === void 0 ? {} : { schema: options.schema }
+				});
+			});
+			requireUniqueWorkflowStepHookToken(tokens, "hook", hook.name, hook.token);
+			return hook;
+		},
+		createWebhook(options) {
+			const webhook = createWebhook(runId, options, async () => {
+				return await waitForWorkflowMessage(environment, {
+					commandId: options.commandId ?? options.name,
+					messageId: options.messageId ?? options.name,
+					source: "webhook",
+					...options.timeout === void 0 ? {} : { timeout: options.timeout },
+					...options.schema === void 0 ? {} : { schema: options.schema }
+				});
+			});
+			requireUniqueWorkflowStepHookToken(tokens, "webhook", webhook.name, webhook.token);
+			return webhook;
+		}
+	};
+}
+var Hook = class {
+	token;
+	runId;
+	name;
+	messageId;
+	#wait;
+	constructor(runId, options, wait) {
+		const messageId = options.messageId ?? options.name;
+		this.token = formatHookToken({
+			runId,
+			name: options.name,
+			messageId
+		});
+		this.runId = runId;
+		this.name = options.name;
+		this.messageId = messageId;
+		this.#wait = wait;
+	}
+	async wait() {
+		return await this.#wait();
+	}
+	then(onfulfilled, onrejected) {
+		return this.wait().then(onfulfilled, onrejected);
+	}
+};
+function requireUniqueWorkflowStepHookToken(tokens, kind, name, token) {
+	if (tokens.has(token)) WorkflowHookError.tokenNotUnique(kind, name);
+	tokens.add(token);
+}
+var Webhook = class {
+	token;
+	runId;
+	name;
+	messageId;
+	metadata;
+	#wait;
+	constructor(runId, options, wait) {
+		const messageId = options.messageId ?? options.name;
+		const metadata = options.metadata === void 0 ? void 0 : toPersistedValue(options.metadata, "workflow webhook metadata", {});
+		this.token = formatHookToken({
+			runId,
+			name: options.name,
+			messageId,
+			kind: "webhook",
+			...metadata === void 0 ? {} : { metadata }
+		});
+		this.runId = runId;
+		this.name = options.name;
+		this.messageId = messageId;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+		this.#wait = wait;
+	}
+	async wait() {
+		return await this.#wait();
+	}
+	then(onfulfilled, onrejected) {
+		return this.wait().then(onfulfilled, onrejected);
+	}
+};
+async function resumeHook(token, options, service) {
+	const hook = parseHookToken(token);
+	const payload = toOptionalPersistedValue(options?.payload, "hook payload", service.limits);
+	const telemetryContext = captureTelemetryContext(service.telemetry);
+	await sendWorkflowMessage(service.store, hook.runId, {
+		messageId: hook.messageId,
+		payload,
+		idempotencyKey: options?.idempotencyKey
+	}, service.now, service.limits, service.emitMessageSent, service.telemetry, telemetryContext);
+	service.emitHookResumed(hook.runId, hook.messageId, payload, telemetryContext);
+}
+async function resumeWebhook(token, options, service) {
+	const webhook = parseWebhookToken(token);
+	const payload = toOptionalPersistedValue(options?.payload, "webhook payload", service.limits);
+	const telemetryContext = captureTelemetryContext(service.telemetry);
+	await sendWorkflowMessage(service.store, webhook.runId, {
+		messageId: webhook.messageId,
+		payload,
+		idempotencyKey: options?.idempotencyKey
+	}, service.now, service.limits, service.emitMessageSent, service.telemetry, telemetryContext);
+	service.emitWebhookResumed(webhook.runId, webhook.messageId, payload, telemetryContext);
+}
+async function disposeHook(token, service) {
+	return await disposeHookToken(token, parseHookToken(token), service);
+}
+async function disposeWebhook(token, service) {
+	return await disposeHookToken(token, parseWebhookToken(token), service);
+}
+async function getHookByToken(token, store, now) {
+	const hook = parseHookToken(token);
+	return inspectHookToken(token, await store.getRun(hook.runId), await store.getEvents(hook.runId), now);
+}
+async function disposeHookToken(token, hook, service) {
+	let timestamp;
+	for (let attempt = 0; attempt < MAX_HOOK_DISPOSAL_APPEND_ATTEMPTS; attempt++) {
+		const run = await service.store.getRun(hook.runId);
+		const events = run === void 0 ? [] : await service.store.getEvents(hook.runId);
+		const inspection = inspectHookToken(token, run, events, service.now());
+		if (inspection.status !== "waiting") return inspection;
+		if (run === void 0) return inspection;
+		if (inspection.stepId === void 0) WorkflowHookError.waitingStepMissing();
+		timestamp ??= service.now();
+		enforceWorkflowEventHistoryNextLimit(events, service.limits);
+		const appendedEvents = await service.store.appendEventIfRunCurrent(run, {
+			kind: "message_wait_failed",
+			timestamp,
+			stepId: inspection.stepId,
+			stepName: hook.name,
+			messageId: hook.messageId,
+			error: serializeError(WorkflowHookDisposedError.create({
+				runId: hook.runId,
+				stepId: inspection.stepId,
+				stepName: hook.name,
+				messageId: hook.messageId
+			}))
+		});
+		if (appendedEvents === void 0) continue;
+		if (run.status === "waiting") await service.store.updateRunIfCurrent(run, {
+			...run,
+			availableAt: run.availableAt !== void 0 && Temporal.Instant.compare(run.availableAt, timestamp) <= 0 ? run.availableAt : timestamp,
+			updatedAt: timestamp,
+			lastTransitionAt: timestamp,
+			lastTransitionReason: "waiting",
+			deadlineAt: run.deadlineAt,
+			retryAt: run.retryAt,
+			error: void 0,
+			output: void 0,
+			finishedAt: void 0
+		});
+		return inspectHookToken(token, run, appendedEvents, service.now());
+	}
+	const run = await service.store.getRun(hook.runId);
+	return inspectHookToken(token, run, run === void 0 ? [] : await service.store.getEvents(hook.runId), service.now());
+}
+function inspectHookToken(token, run, events, now) {
+	const hook = parseHookToken(token);
+	if (run === void 0) return hookInspection(token, hook, "not-found");
+	const history = new WorkflowHistory(events);
+	const started = history.latestMessageWaitStartedByNameAndMessageId(hook.name, hook.messageId);
+	if (started === void 0) return hookInspection(token, hook, "not-found");
+	const terminal = history.latestMessageWaitTerminalAfterStarted(started);
+	if (terminal?.kind === "message_wait_completed") return hookInspection(token, hook, "completed", {
+		stepId: started.stepId,
+		timeoutAt: started.timeoutAt,
+		payload: terminal.payload
+	});
+	if (terminal?.kind === "message_wait_failed") return hookInspection(token, hook, WorkflowHookDisposedError.isDisposed(terminal.error) ? "disposed" : "failed", {
+		stepId: started.stepId,
+		timeoutAt: started.timeoutAt,
+		error: terminal.error
+	});
+	if (run.status === "completed" || run.status === "failed" || run.status === "canceled") return hookInspection(token, hook, "run-terminal", {
+		stepId: started.stepId,
+		timeoutAt: started.timeoutAt
+	});
+	if (started.timeoutAt !== void 0 && Temporal.Instant.compare(started.timeoutAt, now) <= 0) return hookInspection(token, hook, "expired", {
+		stepId: started.stepId,
+		timeoutAt: started.timeoutAt
+	});
+	return hookInspection(token, hook, "waiting", {
+		stepId: started.stepId,
+		timeoutAt: started.timeoutAt
+	});
+}
+function hookInspection(token, hook, status, state = {}) {
+	return {
+		token,
+		runId: hook.runId,
+		name: hook.name,
+		messageId: hook.messageId,
+		kind: hook.kind,
+		status,
+		...hook.metadata === void 0 ? {} : { metadata: hook.metadata },
+		...state.stepId === void 0 ? {} : { stepId: state.stepId },
+		...state.timeoutAt === void 0 ? {} : { timeoutAt: state.timeoutAt },
+		...state.payload === void 0 ? {} : { payload: state.payload },
+		...state.error === void 0 ? {} : { error: state.error }
+	};
+}
+function formatHookToken(hook) {
+	const payload = {
+		v: 1,
+		...hook
+	};
+	return `${WORKFLOW_HOOK_TOKEN_PREFIX}v1:${encodeBase64UrlString(JSON.stringify(payload))}`;
+}
+//#endregion
+export { Hook, Webhook, createHook, createWebhook, createWorkflowStepHookApi, disposeHook, disposeWebhook, getHookByToken, inspectHookToken, resumeHook, resumeWebhook };

package/dist/engine/inspection-api.d.mts

@@ -0,0 +1,34 @@
+import { RunId } from "../types/run-id.mjs";
+import { PageOptions, WorkflowPage } from "../types/pagination.mjs";
+import { WorkflowListRunsOptions, WorkflowListRunsPageOptions, WorkflowListStepAttemptsPageOptions } from "../types/run-list.mjs";
+import { WorkflowRecoverySummary, WorkflowRecoverySummaryOptions, WorkflowRunSummary, WorkflowRunSummaryOptions } from "../types/summary.mjs";
+import { WorkflowListStepAttemptsOptions, WorkflowStepAttemptRecord, WorkflowStepAttemptSummary } from "../types/step-attempts.mjs";
+import { Timeline } from "../types/timeline.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowEventReader, WorkflowLockListerRepository, WorkflowMessageIdempotencyIndex, WorkflowRunQueryRepository, WorkflowScheduleListerRepository, WorkflowStepAttemptReadModel } from "../types/store.mjs";
+//#region src/engine/inspection-api.d.ts
+interface WorkflowEngineInspectionApi {
+  getRun(runId: RunId): Promise<WorkflowRunRecord | undefined>;
+  getEvents(runId: RunId): Promise<readonly EventRecord[]>;
+  listEventsPage(runId: RunId, options?: PageOptions): Promise<WorkflowPage<EventRecord>>;
+  listRuns(options?: WorkflowListRunsOptions): Promise<readonly WorkflowRunRecord[]>;
+  listRunsPage(options?: WorkflowListRunsPageOptions): Promise<WorkflowPage<WorkflowRunRecord>>;
+  countRuns(options?: WorkflowListRunsOptions): Promise<number>;
+  getRunSummary(options?: WorkflowRunSummaryOptions): Promise<WorkflowRunSummary>;
+  getRecoverySummary(options?: WorkflowRecoverySummaryOptions): Promise<WorkflowRecoverySummary>;
+  getTimeline(runId: RunId): Promise<Timeline>;
+  listStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<readonly WorkflowStepAttemptRecord[]>;
+  listStepAttemptsPage(runId: RunId, options?: WorkflowListStepAttemptsPageOptions): Promise<WorkflowPage<WorkflowStepAttemptRecord>>;
+  countStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<number>;
+  repairStepAttempts(runId: RunId): Promise<readonly WorkflowStepAttemptRecord[]>;
+  repairMessageIdempotencyIndexes(runId: RunId): Promise<readonly WorkflowMessageIdempotencyIndex[]>;
+  getStepAttemptSummary(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<WorkflowStepAttemptSummary>;
+}
+interface WorkflowInspectionRepairStore {
+  repairMessageIdempotencyIndexes(runId: RunId): Promise<readonly WorkflowMessageIdempotencyIndex[]>;
+}
+type WorkflowEngineInspectionStore = WorkflowRunQueryRepository & WorkflowEventReader & WorkflowInspectionRepairStore & WorkflowStepAttemptReadModel & WorkflowLockListerRepository & WorkflowScheduleListerRepository;
+declare function createWorkflowEngineInspectionApi(store: WorkflowEngineInspectionStore, now: () => Temporal.Instant): WorkflowEngineInspectionApi;
+//#endregion
+export { WorkflowEngineInspectionApi, createWorkflowEngineInspectionApi };

package/dist/engine/inspection-api.mjs

@@ -0,0 +1,77 @@
+import { getRequiredRun } from "../utility.mjs";
+import { createTimeline } from "../history/timeline.mjs";
+import "../history/mod.mjs";
+import "./state.mjs";
+import { makeWorkflowEventCursorKey, pageItems } from "../pagination.mjs";
+import { getChildRunsForAttempts } from "./summary/child-workflow-runs.mjs";
+import { getWorkflowRecoverySummary, getWorkflowRunSummary } from "./inspection.mjs";
+import { createWorkflowStepAttemptSummaryReducer } from "./summary/step-attempts.mjs";
+//#region src/engine/inspection-api.ts
+function createWorkflowEngineInspectionApi(store, now) {
+	return {
+		async getRun(runId) {
+			return await store.getRun(runId);
+		},
+		async getEvents(runId) {
+			return await store.getEvents(runId);
+		},
+		async listEventsPage(runId, options) {
+			return pageItems(await store.getEvents(runId), options, "Workflow event page", makeWorkflowEventCursorKey);
+		},
+		async listRuns(options) {
+			return await store.listRuns(options);
+		},
+		async listRunsPage(options) {
+			return await store.listRunsPage(options);
+		},
+		async countRuns(options) {
+			return await store.countRuns(options);
+		},
+		async getRunSummary(options) {
+			return await getWorkflowRunSummary({
+				store,
+				now: now(),
+				filters: options
+			});
+		},
+		async getRecoverySummary(options) {
+			return await getWorkflowRecoverySummary({
+				store,
+				now: now(),
+				filters: options
+			});
+		},
+		async getTimeline(runId) {
+			return createTimeline(await getRequiredRun(store, runId), await store.getEvents(runId));
+		},
+		async listStepAttempts(runId, options) {
+			await getRequiredRun(store, runId);
+			return await store.listStepAttempts(runId, options);
+		},
+		async listStepAttemptsPage(runId, options) {
+			await getRequiredRun(store, runId);
+			return await store.listStepAttemptsPage(runId, options);
+		},
+		async countStepAttempts(runId, options) {
+			await getRequiredRun(store, runId);
+			return await store.countStepAttempts(runId, options);
+		},
+		async repairStepAttempts(runId) {
+			await getRequiredRun(store, runId);
+			return await store.repairStepAttempts(runId);
+		},
+		async repairMessageIdempotencyIndexes(runId) {
+			await getRequiredRun(store, runId);
+			return await store.repairMessageIdempotencyIndexes(runId);
+		},
+		async getStepAttemptSummary(runId, options) {
+			await getRequiredRun(store, runId);
+			const attempts = await store.listStepAttempts(runId, options);
+			const reducer = createWorkflowStepAttemptSummaryReducer(await getChildRunsForAttempts(store, runId, attempts));
+			for (const attempt of attempts) reducer.addAttempt(attempt);
+			return reducer.finish();
+		}
+	};
+}
+//#endregion
+export { createWorkflowEngineInspectionApi };

package/dist/engine/inspection.d.mts

@@ -0,0 +1,18 @@
+import { WorkflowRecoverySummary, WorkflowRecoverySummaryOptions, WorkflowRunSummary, WorkflowRunSummaryOptions } from "../types/summary.mjs";
+import { WorkflowEventReader, WorkflowLockListerRepository, WorkflowRunListerRepository, WorkflowRunReaderRepository, WorkflowScheduleListerRepository, WorkflowStepAttemptLookup } from "../types/store.mjs";
+//#region src/engine/inspection.d.ts
+type WorkflowSummaryRunStore = WorkflowRunReaderRepository & WorkflowRunListerRepository;
+type WorkflowRunSummaryStore = WorkflowSummaryRunStore & WorkflowEventReader & WorkflowStepAttemptLookup;
+type WorkflowRecoverySummaryStore = WorkflowRunSummaryStore & WorkflowLockListerRepository & WorkflowScheduleListerRepository;
+declare function getWorkflowRunSummary(options: {
+  readonly store: WorkflowRunSummaryStore;
+  readonly now: Temporal.Instant;
+  readonly filters?: WorkflowRunSummaryOptions;
+}): Promise<WorkflowRunSummary>;
+declare function getWorkflowRecoverySummary(options: {
+  readonly store: WorkflowRecoverySummaryStore;
+  readonly now: Temporal.Instant;
+  readonly filters?: WorkflowRecoverySummaryOptions;
+}): Promise<WorkflowRecoverySummary>;
+//#endregion
+export { getWorkflowRecoverySummary, getWorkflowRunSummary };

package/dist/engine/inspection.mjs

@@ -0,0 +1,149 @@
+import { WorkflowOptionsError } from "../errors/base.mjs";
+import { isActiveWorkflowRunStatus, isWorkflowRunStatus } from "../utility.mjs";
+import "../errors/mod.mjs";
+import { summarizeWorkflowRecovery } from "./recovery.mjs";
+import { getChildRunsForAttempts } from "./summary/child-workflow-runs.mjs";
+import { summarizeWorkflowRuns } from "./summary.mjs";
+//#region src/engine/inspection.ts
+function isKnownWorkflowRunStatus(run) {
+	return isWorkflowRunStatus(run.status);
+}
+function workflowRunCanHaveActiveWork(run) {
+	return isActiveWorkflowRunStatus(run.status);
+}
+function workflowSummaryCleanupCutoff(filters) {
+	if (filters?.cleanupFinishedAtBefore === void 0) return;
+	const value = filters.cleanupFinishedAtBefore;
+	if (!(value instanceof Temporal.Instant)) WorkflowOptionsError.temporalInstant("Workflow cleanup finishedAtBefore");
+	return value;
+}
+async function listWorkflowRunStepAttempts(store, runId, options) {
+	return await store.listStepAttempts(runId, options);
+}
+async function listActiveWorkflowRunStepAttempts(store, run, kind) {
+	return workflowRunCanHaveActiveWork(run) ? await listWorkflowRunStepAttempts(store, run.id, {
+		status: "running",
+		kind
+	}) : [];
+}
+async function getWorkflowRunSummaryActivityInputs(store, runs) {
+	const [runningChildWorkflows, runningSleeps, runningMessageWaits, runningEvents] = await Promise.all([
+		listRunningChildWorkflowWaits(store, runs),
+		listRunningStepWaits(store, runs, "sleep"),
+		listRunningStepWaits(store, runs, "message-wait"),
+		listRunningEventActivity(store, runs)
+	]);
+	return {
+		runningChildWorkflows,
+		runningSleeps,
+		runningMessageWaits,
+		runningEvents
+	};
+}
+async function listRunningChildWorkflowWaits(store, runs) {
+	return await Promise.all(runs.map(async (run) => {
+		if (!isKnownWorkflowRunStatus(run)) return {
+			runId: run.id,
+			attempts: [],
+			childRuns: []
+		};
+		const attempts = await listWorkflowRunStepAttempts(store, run.id, {
+			status: "running",
+			kind: "workflow"
+		});
+		return {
+			runId: run.id,
+			attempts,
+			childRuns: await getChildRunsForAttempts(store, run.id, attempts)
+		};
+	}));
+}
+async function listRunningStepWaits(store, runs, kind) {
+	return await Promise.all(runs.map(async (run) => {
+		return {
+			runId: run.id,
+			attempts: await listActiveWorkflowRunStepAttempts(store, run, kind)
+		};
+	}));
+}
+async function listRunningEventActivity(store, runs) {
+	return await Promise.all(runs.map(async (run) => {
+		return {
+			runId: run.id,
+			events: workflowRunCanHaveActiveWork(run) ? await store.getEvents(run.id) : []
+		};
+	}));
+}
+async function listWorkflowRunAttemptGroups(store, runs, options) {
+	return await Promise.all(runs.map(async (run) => await listWorkflowRunStepAttempts(store, run.id, options)));
+}
+async function getWorkflowRunSummary(options) {
+	const { store, now, filters } = options;
+	const cleanupCutoff = workflowSummaryCleanupCutoff(filters);
+	const runs = await store.listRuns(filters);
+	return summarizeWorkflowRuns({
+		runs,
+		now,
+		cleanupCutoff,
+		...await getWorkflowRunSummaryActivityInputs(store, runs)
+	});
+}
+async function getWorkflowRecoverySummary(options) {
+	const { store, now, filters } = options;
+	const runs = await store.listRuns(filters);
+	return summarizeWorkflowRecovery({
+		runs,
+		now,
+		inputs: await getWorkflowRecoverySummaryInputs(store, runs.filter((run) => {
+			return workflowRunCanHaveActiveWork(run);
+		}))
+	});
+}
+async function getWorkflowRecoverySummaryInputs(store, activeRuns) {
+	const [sleepAttemptGroups, messageWaitAttemptGroups, childWorkflowAttemptGroups, lockWaitAttemptGroups, eventsByRunId, locks, schedules] = await Promise.all([
+		listWorkflowRunAttemptGroups(store, activeRuns, {
+			status: "running",
+			kind: "sleep"
+		}),
+		listWorkflowRunAttemptGroups(store, activeRuns, {
+			status: "running",
+			kind: "message-wait"
+		}),
+		listChildWorkflowAttemptGroups(store, activeRuns),
+		listWorkflowRunAttemptGroups(store, activeRuns, {
+			status: "failed",
+			kind: "run"
+		}),
+		getWorkflowRecoveryEventsByRunId(store, activeRuns),
+		store.listLocks(),
+		store.listSchedules()
+	]);
+	return {
+		sleepAttempts: sleepAttemptGroups.flat(),
+		messageWaitAttempts: messageWaitAttemptGroups.flat(),
+		childWorkflowAttempts: childWorkflowAttemptGroups.flatMap((group) => group.attempts),
+		lockWaitAttempts: lockWaitAttemptGroups.flat(),
+		childRuns: childWorkflowAttemptGroups.flatMap((group) => group.childRuns),
+		eventsByRunId,
+		locks,
+		schedules
+	};
+}
+async function listChildWorkflowAttemptGroups(store, activeRuns) {
+	return await Promise.all(activeRuns.map(async (run) => {
+		const attempts = await listWorkflowRunStepAttempts(store, run.id, {
+			status: "running",
+			kind: "workflow"
+		});
+		return {
+			runId: run.id,
+			attempts,
+			childRuns: await getChildRunsForAttempts(store, run.id, attempts)
+		};
+	}));
+}
+async function getWorkflowRecoveryEventsByRunId(store, activeRuns) {
+	return new Map(await Promise.all(activeRuns.map(async (run) => [run.id, await store.getEvents(run.id)])));
+}
+//#endregion
+export { getWorkflowRecoverySummary, getWorkflowRunSummary };

package/dist/engine/lifecycle.d.mts

@@ -0,0 +1,18 @@
+import { ObservationEmitter } from "../types/observation.mjs";
+import { ExecutionResult } from "../types/result.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { CreateWorkflowEngineOptions } from "../types/engine-options.mjs";
+//#region src/engine/lifecycle.d.ts
+declare function createWorkflowLifecycleEmitter(options: CreateWorkflowEngineOptions, observation?: ObservationEmitter): WorkflowLifecycleEmitterContract;
+interface WorkflowLifecycleEmitterContract {
+  readonly emitLifecycleEvent: (run: WorkflowRunRecord, previousRun?: WorkflowRunRecord) => Promise<void>;
+  readonly emitResultLifecycleEvent: <TOutput>(result: ExecutionResult<TOutput>, previousRun?: WorkflowRunRecord) => Promise<ExecutionResult<TOutput>>;
+}
+declare class WorkflowLifecycleEmitter implements WorkflowLifecycleEmitterContract {
+  #private;
+  constructor(options: CreateWorkflowEngineOptions, observation?: ObservationEmitter);
+  emitLifecycleEvent: (run: WorkflowRunRecord, previousRun?: WorkflowRunRecord) => Promise<void>;
+  emitResultLifecycleEvent: <TOutput>(result: ExecutionResult<TOutput>, previousRun?: WorkflowRunRecord) => Promise<ExecutionResult<TOutput>>;
+}
+//#endregion
+export { WorkflowLifecycleEmitter, createWorkflowLifecycleEmitter };

package/dist/engine/lifecycle.mjs

@@ -0,0 +1,38 @@
+//#region src/engine/lifecycle.ts
+function createWorkflowLifecycleEmitter(options, observation) {
+	return new WorkflowLifecycleEmitter(options, observation);
+}
+var WorkflowLifecycleEmitter = class {
+	#options;
+	#observation;
+	constructor(options, observation) {
+		this.#options = options;
+		this.#observation = observation;
+	}
+	emitLifecycleEvent = async (run, previousRun) => {
+		const event = {
+			run,
+			previousRun,
+			status: run.status,
+			reason: run.lastTransitionReason,
+			timestamp: run.lastTransitionAt,
+			workflowName: run.workflowName,
+			...run.workflowVersion === void 0 ? {} : { workflowVersion: run.workflowVersion }
+		};
+		this.#observation?.emitRunEvent(run, previousRun);
+		const callbacks = [];
+		if (this.#options.onLifecycleEvent !== void 0) callbacks.push(this.#options.onLifecycleEvent);
+		if (run.status === "completed" && this.#options.onRunCompleted !== void 0) callbacks.push(this.#options.onRunCompleted);
+		else if (run.status === "failed" && this.#options.onRunFailed !== void 0) callbacks.push(this.#options.onRunFailed);
+		else if (run.status === "canceled" && this.#options.onRunCanceled !== void 0) callbacks.push(this.#options.onRunCanceled);
+		else if (run.status === "waiting" && run.lastTransitionReason === "retry" && this.#options.onRunRetry !== void 0) callbacks.push(this.#options.onRunRetry);
+		else if (run.status === "waiting" && this.#options.onRunWaiting !== void 0) callbacks.push(this.#options.onRunWaiting);
+		for (const callback of callbacks) await callback(event);
+	};
+	emitResultLifecycleEvent = async (result, previousRun) => {
+		if (result.run.lastTransitionReason === "completed" || result.run.lastTransitionReason === "failed" || result.run.lastTransitionReason === "deadline" || result.run.lastTransitionReason === "waiting" || result.run.lastTransitionReason === "retry" || result.run.lastTransitionReason === "canceled") await this.emitLifecycleEvent(result.run, previousRun);
+		return result;
+	};
+};
+//#endregion
+export { WorkflowLifecycleEmitter, createWorkflowLifecycleEmitter };

package/dist/engine/lock-replay.d.mts

@@ -0,0 +1,30 @@
+import { RunId } from "../types/run-id.mjs";
+import { StepId } from "../types/step-id.mjs";
+import { LockRecord } from "../types/lock.mjs";
+import "../types/step.mjs";
+import "../types/run.mjs";
+import { WorkflowErrorRecord } from "../types/error.mjs";
+//#region src/engine/lock-replay.d.ts
+declare function requireLockWaitDeadlineReplayMatches(recorded: {
+  readonly stepId: StepId;
+  readonly timestamp: Temporal.Instant;
+  readonly value: unknown;
+}, timeout: number): void;
+declare function requireLockReplayMatches(recorded: LockRecord, expected: {
+  readonly key: string;
+  readonly holderId: string;
+  readonly holderRunId: RunId;
+  readonly leaseDuration: number;
+}): void;
+declare function requireLockReleaseReplayMatches(recorded: LockRecord, expected: {
+  readonly key: string;
+  readonly holderId: string;
+}): void;
+declare function requireLockWaitReplayMatches(failedSteps: readonly {
+  readonly error: WorkflowErrorRecord;
+}[], expected: {
+  readonly key: string;
+  readonly wait: boolean;
+}): void;
+//#endregion
+export { requireLockReleaseReplayMatches, requireLockReplayMatches, requireLockWaitDeadlineReplayMatches, requireLockWaitReplayMatches };

package/dist/engine/lock-replay.mjs

@@ -0,0 +1,38 @@
+import { WorkflowReplayDivergenceError, WorkflowRetryableError } from "../errors/failures.mjs";
+import "../errors/mod.mjs";
+//#region src/engine/lock-replay.ts
+function requireLockWaitDeadlineReplayMatches(recorded, timeout) {
+	if (!(recorded.value instanceof Temporal.Instant)) WorkflowReplayDivergenceError.diverged(`recorded lock wait deadline ${recorded.stepId} is invalid`, {
+		expectedStepId: recorded.stepId,
+		actualStepId: recorded.stepId
+	});
+	if (recorded.value.since(recorded.timestamp).total({ unit: "millisecond" }) === timeout) return;
+	WorkflowReplayDivergenceError.diverged(`recorded lock wait deadline ${recorded.stepId} does not match replayed waitTimeout`, {
+		expectedStepId: recorded.stepId,
+		actualStepId: recorded.stepId
+	});
+}
+function requireLockReplayMatches(recorded, expected) {
+	const recordedLeaseDuration = recorded.leaseExpiresAt.since(recorded.acquiredAt).total({ unit: "millisecond" });
+	if (recorded.key === expected.key && recorded.holderId === expected.holderId && recorded.holderRunId === expected.holderRunId && recordedLeaseDuration === expected.leaseDuration) return;
+	WorkflowReplayDivergenceError.diverged(`recorded lock step ${recorded.holderStepId ?? recorded.key} does not match replayed lock acquisition`, {
+		expectedStepId: recorded.holderStepId,
+		actualStepId: recorded.holderStepId
+	});
+}
+function requireLockReleaseReplayMatches(recorded, expected) {
+	if (recorded.key === expected.key && recorded.holderId === expected.holderId && recorded.releasedAt !== void 0) return;
+	WorkflowReplayDivergenceError.diverged(`recorded lock step ${recorded.holderStepId ?? recorded.key} does not match replayed lock release`, {
+		expectedStepId: recorded.holderStepId,
+		actualStepId: recorded.holderStepId
+	});
+}
+function requireLockWaitReplayMatches(failedSteps, expected) {
+	if (!failedSteps.some((failed) => WorkflowRetryableError.isLockAlreadyHeld(failed.error, expected.key)) || expected.wait) return;
+	WorkflowReplayDivergenceError.diverged(`recorded lock ${expected.key} waited but replayed lock acquisition does not allow waiting`, {
+		expectedStepId: `run:${expected.key}`,
+		actualStepId: `run:${expected.key}`
+	});
+}
+//#endregion
+export { requireLockReleaseReplayMatches, requireLockReplayMatches, requireLockWaitDeadlineReplayMatches, requireLockWaitReplayMatches };

package/dist/engine/lock.d.mts

@@ -0,0 +1,21 @@
+import { AcquireLockOptions, LockRecord, ReleaseLockOptions } from "../types/lock.mjs";
+import { WorkflowStepContext, WorkflowStepLockApi, WorkflowStepRunConfig } from "../types/step.mjs";
+import { WorkflowLockConditionalWriterRepository, WorkflowLockReaderRepository, WorkflowRunListerRepository, WorkflowRunUnconditionalWriterRepository, WorkflowStepAttemptLookup, WorkflowStoreNamespace } from "../types/store.mjs";
+import { WorkflowExecutionEnvironment } from "../types/engine.mjs";
+//#region src/engine/lock.d.ts
+type WorkflowLockCommandStore = WorkflowStoreNamespace & WorkflowLockReaderRepository & WorkflowLockConditionalWriterRepository;
+type WorkflowLockRunWakeStore = WorkflowRunListerRepository & WorkflowRunUnconditionalWriterRepository;
+type WorkflowLockStepAttemptWakeStore = WorkflowStepAttemptLookup;
+type WorkflowLockWakeStore = WorkflowLockRunWakeStore & WorkflowLockStepAttemptWakeStore;
+type WorkflowLockReleaseStore = WorkflowLockCommandStore & WorkflowLockWakeStore;
+interface WorkflowStepLockEngine {
+  acquireLock(key: string, options: AcquireLockOptions): Promise<LockRecord>;
+  releaseLock(key: string, options: ReleaseLockOptions): Promise<LockRecord>;
+}
+type WorkflowStepLockRunner = <TOutput>(config: WorkflowStepRunConfig, callback: (context: WorkflowStepContext) => Promise<TOutput> | TOutput) => Promise<TOutput>;
+declare function createWorkflowStepLockApi(environment: WorkflowExecutionEnvironment, engine: WorkflowStepLockEngine, run: WorkflowStepLockRunner): WorkflowStepLockApi;
+declare function acquireLock(store: WorkflowLockCommandStore, key: string, lockOptions: AcquireLockOptions, acquiredAt: Temporal.Instant): Promise<LockRecord>;
+declare function releaseLock(store: WorkflowLockReleaseStore, key: string, lockOptions: ReleaseLockOptions, releasedAt: Temporal.Instant): Promise<LockRecord>;
+declare function releaseStaleLock(store: WorkflowLockReleaseStore, key: string, releasedAt: Temporal.Instant): Promise<LockRecord>;
+//#endregion
+export { WorkflowStepLockEngine, acquireLock, createWorkflowStepLockApi, releaseLock, releaseStaleLock };