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

package/dist/engine/child-workflow.mjs

@@ -1,31 +1,35 @@
+import { WorkflowErrorCode } from "../errors/codes.mjs";
 import { WorkflowOptionsError } from "../errors/base.mjs";
 import { WorkflowDurationError, WorkflowReplayDivergenceError } from "../errors/failures.mjs";
 import { WorkflowChildWorkflowTimeoutError, WorkflowRunCanceledError, WorkflowRunInvalidError } from "../errors/run.mjs";
-import { getRequiredRun, isPositiveSafeInteger, nextPositiveSafeInteger, safeDuration } from "../utility.mjs";
 import { WorkflowStepAttemptLimitError, WorkflowStepExecutionError } from "../errors/step.mjs";
-import { defineWorkflowFromTarget } from "../definition.mjs";
 import { workflowErrorFromRecord } from "../errors/records.mjs";
+import { defineFromTarget } from "../definition.mjs";
+import { isPositiveSafeInteger, nextPositiveSafeInteger, safeDuration } from "../values.mjs";
+import { getRequiredRun } from "../store/query.mjs";
 import { serializeError, toOptionalPersistedValue } from "./serialization.mjs";
 import { enforceStepAttemptBudget, nextRetryAt, resolveChildWorkflowRetryConfig } from "./retry.mjs";
-import { WorkflowSuspended, requireCurrentExecutionOwner } from "./state.mjs";
-import { resolveWorkflowCommandIdentityFromCandidates } from "./command-identity.mjs";
-import { appendDurableStepStartedEvent, appendDurableStepTerminalEvent } from "./durable-command.mjs";
-import { requireRecordedDurableTerminalStarted } from "./replay.mjs";
+import { Suspended } from "./signals.mjs";
+import { requireCurrentExecutionOwner, requireDefinitionMatchesRun } from "./state.mjs";
+import { cancelWorkflowRun } from "./run-service.mjs";
+import { resolveCommandIdentityFromCandidates } from "./command-identity.mjs";
+import { appendDurableEvent, appendDurableStepStartedEvent } from "./durable-command.mjs";
+import { recordedInstant, requireRecordedDurableTerminalStarted } from "./replay.mjs";
 import { deepEquals } from "@temelj/value";
 //#region src/engine/child-workflow.ts
-function createWorkflowStepWorkflowApi(environment, engine) {
+function createStepWorkflowApi(environment, engine) {
 	return {
 		async run(workflow, input, options) {
-			return await runChildWorkflow(environment, engine, defineWorkflowFromTarget(workflow), input, options);
+			return await runChildWorkflow(environment, engine, defineFromTarget(workflow), input, options);
 		},
 		async start(workflow, input, options) {
-			return await startBackgroundChildWorkflow(environment, engine, defineWorkflowFromTarget(workflow), input, options);
+			return await startBackgroundChildWorkflow(environment, engine, defineFromTarget(workflow), input, options);
 		}
 	};
 }
 async function runChildWorkflow(environment, engine, definition, input, options) {
 	const { store, runId, history, now, maximumStepAttemptsPerRun, limits, executionOwner } = environment;
-	const identity = resolveWorkflowCommandIdentityFromCandidates(history, "workflow", [
+	const identity = resolveCommandIdentityFromCandidates(history, "workflow", [
 		options?.commandId,
 		options?.name,
 		definition.name
@@ -36,7 +40,7 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 		requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(completed));
 		if (started === void 0 || isChildWorkflowTerminalForStartedAttempt(completed, started)) {
 			requireChildWorkflowReplayMatches(runId, identity, started, definition, input, options, limits);
-			recordedChildWorkflowCompletionTimestamp(identity, completed.timestamp);
+			recordedInstant("workflow", identity, "completion", completed.timestamp);
 			return completed.result;
 		}
 	}
@@ -50,7 +54,7 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 	const pollInterval = resolveChildWorkflowPollInterval(options);
 	const latestFailedAttempt = failed !== void 0 && (started === void 0 || isChildWorkflowTerminalForStartedAttempt(failed, started)) ? failed : void 0;
 	if (latestFailedAttempt !== void 0) {
-		const failedAt = recordedChildWorkflowFailureTimestamp(identity, latestFailedAttempt.timestamp);
+		const failedAt = recordedInstant("workflow", identity, "failure", latestFailedAttempt.timestamp);
 		const nextAttempt = nextChildWorkflowRetryAttempt(runId, latestFailedAttempt.attempt, maximumStepAttemptsPerRun);
 		if (retry.maximumAttempts !== 0 && nextAttempt > retry.maximumAttempts) WorkflowStepExecutionError.failed({
 			stepId: identity.id,
@@ -59,14 +63,15 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 			cause: workflowErrorFromRecord(latestFailedAttempt.error)
 		});
 		const retryAt = nextRetryAt(failedAt, retry, latestFailedAttempt.attempt, "Workflow step retry delay");
-		if (retryAt !== void 0 && Temporal.Instant.compare(retryAt, now()) > 0) WorkflowSuspended.forStepRetry(retryAt, identity, nextAttempt);
+		if (retryAt !== void 0 && Temporal.Instant.compare(retryAt, now()) > 0) Suspended.forStepRetry(retryAt, identity, nextAttempt);
 	}
 	const attempt = latestFailedAttempt === void 0 ? started?.attempt ?? 1 : latestFailedAttempt.attempt + 1;
 	const childRunId = started === void 0 || latestFailedAttempt !== void 0 ? await startChildWorkflow(store, engine, runId, history, now, maximumStepAttemptsPerRun, identity, definition, input, options, attempt, limits, executionOwner, environment.createRecordedId, environment.createDeterministicRandom, environment.createDeterministicUuid, environment.createDeterministicBytes, environment.telemetry, environment.logger, environment.replaying, environment.observeChildWorkflowStarted) : started.childRunId;
 	const childRun = await getRequiredRun(store, childRunId);
 	const activeStarted = history.startedChildWorkflow(identity.id);
-	const timeoutAt = activeStarted?.timeoutAt === void 0 ? void 0 : recordedChildWorkflowTimeoutAt(identity, activeStarted.timeoutAt);
-	if (!childRunMatchesParentStepAttempt(childRun, runId, identity, attempt)) WorkflowSuspended.until(childWorkflowPollAt(now(), childRun, pollInterval));
+	const timeoutAt = activeStarted?.timeoutAt === void 0 ? void 0 : recordedInstant("workflow", identity, "timeout", activeStarted.timeoutAt);
+	if (!childRunMatchesParentStepAttempt(childRun, runId, identity, attempt)) Suspended.until(childWorkflowPollAt(now(), childRun, pollInterval));
+	requireDefinitionMatchesRun(definition, childRun);
 	if (timeoutAt !== void 0 && Temporal.Instant.compare(timeoutAt, now()) <= 0 && childRun.status !== "completed" && childRun.status !== "failed" && childRun.status !== "canceled") {
 		const error = childWorkflowTimeoutErrorRecord({
 			runId,
@@ -74,7 +79,7 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 			stepId: identity.id,
 			timeoutAt
 		});
-		await appendDurableStepTerminalEvent(environment, {
+		await appendDurableEvent(environment, {
 			kind: "child_workflow_failed",
 			timestamp: now(),
 			stepId: identity.id,
@@ -83,8 +88,8 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 			childRunId,
 			error
 		});
-		await requireCurrentExecutionOwner(store, runId, executionOwner);
-		await engine.cancelRun(childRunId);
+		await requireCurrentExecutionOwner(store, executionOwner);
+		await cancelWorkflowRun(engine.context, engine.lifecycle, childRunId);
 		if (retry.maximumAttempts === 0 || attempt < retry.maximumAttempts) suspendChildWorkflowRetry(runId, timeoutAt, retry, identity, attempt, maximumStepAttemptsPerRun);
 		WorkflowStepExecutionError.failed({
 			stepId: identity.id,
@@ -94,7 +99,7 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 		});
 	}
 	if (childRun.status === "completed") {
-		await appendDurableStepTerminalEvent(environment, {
+		await appendDurableEvent(environment, {
 			kind: "child_workflow_completed",
 			timestamp: now(),
 			stepId: identity.id,
@@ -106,14 +111,14 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 		return childRun.output;
 	}
 	if (childRun.status === "failed" || childRun.status === "canceled") {
-		const error = childRun.error ?? (childRun.status === "canceled" ? serializeError(WorkflowRunCanceledError.create(childRun.id)) : {
+		const error = childRun.error ?? (childRun.status === "canceled" ? serializeError(new WorkflowRunCanceledError(childRun.id)) : {
 			name: "WorkflowError",
 			message: `Child workflow failed: ${childRun.id}`
 		});
 		const failedAt = childRun.finishedAt === void 0 ? now() : childRun.finishedAt instanceof Temporal.Instant ? childRun.finishedAt : (() => {
-			WorkflowRunInvalidError.invalid(childRun.id, "Workflow child failure timestamp must be valid");
+			throw new WorkflowRunInvalidError(childRun.id, "Workflow child failure timestamp must be valid");
 		})();
-		await appendDurableStepTerminalEvent(environment, {
+		await appendDurableEvent(environment, {
 			kind: "child_workflow_failed",
 			timestamp: failedAt,
 			stepId: identity.id,
@@ -130,7 +135,7 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 		});
 		if (retry.maximumAttempts === 0 || attempt < retry.maximumAttempts) {
 			const nextAttempt = nextChildWorkflowRetryAttempt(runId, attempt, maximumStepAttemptsPerRun);
-			WorkflowSuspended.forStepRetry(nextRetryAt(failedAt, retry, attempt, "Workflow step retry delay") ?? failedAt, identity, nextAttempt);
+			Suspended.forStepRetry(nextRetryAt(failedAt, retry, attempt, "Workflow step retry delay") ?? failedAt, identity, nextAttempt);
 		}
 		WorkflowStepExecutionError.failed({
 			stepId: identity.id,
@@ -139,11 +144,11 @@ async function runChildWorkflow(environment, engine, definition, input, options)
 			cause: workflowErrorFromRecord(error)
 		});
 	}
-	WorkflowSuspended.until(childWorkflowPollAt(now(), childRun, pollInterval));
+	Suspended.until(childWorkflowPollAt(now(), childRun, pollInterval));
 }
 async function startBackgroundChildWorkflow(environment, engine, definition, input, options) {
 	const { store, runId, history, now, maximumStepAttemptsPerRun, limits, executionOwner } = environment;
-	const identity = resolveWorkflowCommandIdentityFromCandidates(history, "workflow", [
+	const identity = resolveCommandIdentityFromCandidates(history, "workflow", [
 		options?.commandId,
 		options?.name,
 		definition.name
@@ -162,27 +167,6 @@ function childRunMatchesParentStepAttempt(childRun, parentRunId, identity, attem
 function isChildWorkflowTerminalForStartedAttempt(terminal, started) {
 	return terminal.attempt === started.attempt && terminal.childRunId === started.childRunId;
 }
-function recordedChildWorkflowTimeoutAt(identity, value) {
-	if (value instanceof Temporal.Instant) return value;
-	WorkflowReplayDivergenceError.diverged(`recorded workflow step ${identity.id} has invalid timeout timestamp: ` + String(value), {
-		expectedStepId: identity.id,
-		actualStepId: identity.id
-	});
-}
-function recordedChildWorkflowCompletionTimestamp(identity, value) {
-	if (value instanceof Temporal.Instant) return value;
-	WorkflowReplayDivergenceError.diverged(`recorded workflow step ${identity.id} has invalid completion timestamp: ` + String(value), {
-		expectedStepId: identity.id,
-		actualStepId: identity.id
-	});
-}
-function recordedChildWorkflowFailureTimestamp(identity, value) {
-	if (value instanceof Temporal.Instant) return value;
-	WorkflowReplayDivergenceError.diverged(`recorded workflow step ${identity.id} has invalid failure timestamp: ` + String(value), {
-		expectedStepId: identity.id,
-		actualStepId: identity.id
-	});
-}
 function requireChildWorkflowReplayMatches(runId, identity, started, definition, input, options, limits) {
 	if (started === void 0) return;
 	const replayChildRunId = options?.id === void 0 ? void 0 : started.attempt === 1 ? options.id : `${options.id}:attempt:${started.attempt}`;
@@ -204,20 +188,14 @@ function requireChildWorkflowReplayMatches(runId, identity, started, definition,
 		const replayTimeout = options?.timeout === void 0 ? "no timeout" : "a timeout";
 		message = `recorded workflow step ${identity.id} had ${String(recordedTimeout)}, but replay used ${replayTimeout}`;
 	}
-	WorkflowReplayDivergenceError.diverged(message, {
-		expectedStepId: identity.id,
-		actualStepId: identity.id
-	});
+	WorkflowReplayDivergenceError.atStep(identity.id, message);
 }
 function requireRecordedChildWorkflowStartedAttempt(identity, started) {
 	if (isPositiveSafeInteger(started.attempt)) return;
-	WorkflowReplayDivergenceError.diverged(`recorded workflow step ${identity.id} has an invalid attempt number`, {
-		expectedStepId: identity.id,
-		actualStepId: identity.id
-	});
+	WorkflowReplayDivergenceError.atStep(identity.id, `recorded workflow step ${identity.id} has an invalid attempt number`);
 }
 function suspendChildWorkflowRetry(runId, failedAt, retry, identity, attempt, maximumStepAttemptsPerRun) {
-	WorkflowSuspended.forStepRetry(nextRetryAt(failedAt, retry, attempt, "Workflow step retry delay") ?? failedAt, identity, nextChildWorkflowRetryAttempt(runId, attempt, maximumStepAttemptsPerRun));
+	Suspended.forStepRetry(nextRetryAt(failedAt, retry, attempt, "Workflow step retry delay") ?? failedAt, identity, nextChildWorkflowRetryAttempt(runId, attempt, maximumStepAttemptsPerRun));
 }
 function nextChildWorkflowRetryAttempt(runId, failedAttempt, maximumStepAttemptsPerRun) {
 	const nextAttempt = nextPositiveSafeInteger(failedAttempt);
@@ -225,24 +203,25 @@ function nextChildWorkflowRetryAttempt(runId, failedAttempt, maximumStepAttempts
 	return nextAttempt;
 }
 async function startChildWorkflow(store, engine, runId, history, now, maximumStepAttemptsPerRun, identity, definition, input, options, attempt, limits, executionOwner, createRecordedId, createDeterministicRandom, createDeterministicUuid, createDeterministicBytes, telemetry, logger, replaying, observeChildWorkflowStarted) {
-	await requireCurrentExecutionOwner(store, runId, executionOwner);
+	await requireCurrentExecutionOwner(store, executionOwner);
 	enforceStepAttemptBudget(runId, history, maximumStepAttemptsPerRun);
 	const timeoutAt = childWorkflowTimeoutAt(now(), options);
 	const deadlineAt = childWorkflowDeadlineAt(timeoutAt, executionOwner.deadlineAt);
 	const idempotencyKey = childWorkflowIdempotencyKey(runId, identity, options, attempt);
 	const cancellation = resolveChildWorkflowCancellationPolicy(options);
 	const persistedInput = toOptionalPersistedValue(input, "child workflow input", limits);
-	const handle = await engine.startWorkflow(definition, input, {
-		...options?.id === void 0 ? {} : { id: attempt === 1 ? options.id : `${options.id}:attempt:${attempt}` },
+	const startOptions = {
+		id: options?.id !== void 0 ? attempt === 1 ? options.id : `${options.id}:attempt:${attempt}` : void 0,
 		idempotencyKey,
-		...deadlineAt === void 0 ? {} : { deadlineAt },
+		deadlineAt,
 		parent: {
 			runId,
 			stepId: identity.id,
 			stepName: identity.name,
 			stepAttempt: attempt
 		}
-	});
+	};
+	const handle = await engine.startWorkflow(definition, input, startOptions);
 	const startedEvent = {
 		kind: "child_workflow_started",
 		timestamp: now(),
@@ -252,11 +231,11 @@ async function startChildWorkflow(store, engine, runId, history, now, maximumSte
 		attempt,
 		childRunId: handle.runId,
 		workflowName: definition.name,
-		...definition.version === void 0 ? {} : { workflowVersion: definition.version },
+		workflowVersion: definition.version,
 		cancellation,
 		input: persistedInput,
 		idempotencyKey,
-		...timeoutAt === void 0 ? {} : { timeoutAt }
+		timeoutAt
 	};
 	await appendDurableStepStartedEvent({
 		store,
@@ -289,7 +268,7 @@ function childWorkflowPollAt(now, childRun, pollInterval) {
 }
 function resolveChildWorkflowPollInterval(options) {
 	const pollInterval = options?.pollInterval === void 0 ? 100 : options.pollInterval.total({ unit: "millisecond" });
-	if (!isPositiveSafeInteger(pollInterval)) WorkflowDurationError.childPollIntervalTimerSafe();
+	if (!isPositiveSafeInteger(pollInterval)) throw new WorkflowDurationError("Workflow child pollInterval must be a timer-safe duration");
 	return pollInterval;
 }
 function hasDueChildSchedule(now, childRun) {
@@ -297,19 +276,19 @@ function hasDueChildSchedule(now, childRun) {
 }
 function childWorkflowTimeoutAt(now, options) {
 	if (options?.timeout === void 0) return;
-	if (safeDuration(options.timeout.total({ unit: "millisecond" }), "Workflow child timeout") <= 0) WorkflowDurationError.childTimeoutPositive();
+	if (safeDuration(options.timeout.total({ unit: "millisecond" }), "Workflow child timeout") <= 0) throw new WorkflowDurationError("Workflow child timeout must be greater than zero");
 	return now.add(options.timeout);
 }
 function resolveChildWorkflowCancellationPolicy(options) {
 	const policy = options?.cancellation ?? "cascade";
-	if (policy !== "cascade" && policy !== "detach") WorkflowOptionsError.childCancellationPolicy();
+	if (policy !== "cascade" && policy !== "detach") throw new WorkflowOptionsError("Workflow child cancellation policy must be cascade or detach", { code: WorkflowErrorCode.OPTIONS_CHILD_CANCELLATION_POLICY_INVALID });
 	return policy;
 }
 function childWorkflowDeadlineAt(timeoutAt, parentDeadlineAt) {
 	return [timeoutAt, parentDeadlineAt].filter((value) => value !== void 0).sort((left, right) => Temporal.Instant.compare(left, right))[0];
 }
 function childWorkflowTimeoutErrorRecord(options) {
-	const error = WorkflowChildWorkflowTimeoutError.create({
+	const error = new WorkflowChildWorkflowTimeoutError({
 		runId: options.runId,
 		childRunId: options.childRunId,
 		stepId: options.stepId,
@@ -330,4 +309,4 @@ function childWorkflowIdempotencyKey(runId, identity, options, attempt) {
 	return `${options?.idempotencyKey === void 0 ? `parent:${runId}:step:${identity.id}` : options.idempotencyKey}:attempt:${attempt}`;
 }
 //#endregion
-export { createWorkflowStepWorkflowApi, runChildWorkflow, startBackgroundChildWorkflow };
+export { createStepWorkflowApi };

package/dist/engine/command-identity.d.mts

@@ -1,9 +1,8 @@
-import { WorkflowStepIdentity, WorkflowStepType } from "../types/run.mjs";
-import { WorkflowHistory } from "../history/mod.mjs";
+import { StepIdentity, StepType } from "../types/run.mjs";
+import { History } from "../history/replay.mjs";
 //#region src/engine/command-identity.d.ts
 /** Resolves the durable identity for a workflow command occurrence. */
-declare function resolveWorkflowCommandIdentity<TType extends WorkflowStepType>(history: WorkflowHistory, kind: TType, commandId: string): WorkflowStepIdentity<TType>;
+export declare function resolveCommandIdentity<TType extends StepType>(history: History, kind: TType, commandId: string): StepIdentity<TType>;
 /** Resolves a durable command identity from ordered command-name candidates. */
-declare function resolveWorkflowCommandIdentityFromCandidates<TType extends WorkflowStepType>(history: WorkflowHistory, kind: TType, candidates: readonly (string | undefined)[], label: string): WorkflowStepIdentity<TType>;
-//#endregion
-export { resolveWorkflowCommandIdentity, resolveWorkflowCommandIdentityFromCandidates };
+export declare function resolveCommandIdentityFromCandidates<TType extends StepType>(history: History, kind: TType, candidates: readonly (string | undefined)[], label: string): StepIdentity<TType>;
+//#endregion

package/dist/engine/command-identity.mjs

@@ -1,14 +1,18 @@
+import { WorkflowErrorCode } from "../errors/codes.mjs";
 import { WorkflowOptionsError } from "../errors/base.mjs";
 import "../errors/mod.mjs";
 //#region src/engine/command-identity.ts
 /** Resolves the durable identity for a workflow command occurrence. */
-function resolveWorkflowCommandIdentity(history, kind, commandId) {
+function resolveCommandIdentity(history, kind, commandId) {
 	return history.nextStep(kind, commandId);
 }
 /** Resolves a durable command identity from ordered command-name candidates. */
-function resolveWorkflowCommandIdentityFromCandidates(history, kind, candidates, label) {
-	for (const candidate of candidates) if (candidate !== void 0) return resolveWorkflowCommandIdentity(history, kind, candidate);
-	throw WorkflowOptionsError.required(label);
+function resolveCommandIdentityFromCandidates(history, kind, candidates, label) {
+	for (const candidate of candidates) if (candidate !== void 0) return resolveCommandIdentity(history, kind, candidate);
+	throw new WorkflowOptionsError(`${label} is required`, {
+		code: WorkflowErrorCode.OPTIONS_REQUIRED,
+		details: { label }
+	});
 }
 //#endregion
-export { resolveWorkflowCommandIdentity, resolveWorkflowCommandIdentityFromCandidates };
+export { resolveCommandIdentity, resolveCommandIdentityFromCandidates };

package/dist/engine/context.d.mts

@@ -0,0 +1,17 @@
+import { ObservationEmitter } from "../types/observation.mjs";
+import { Telemetry } from "../types/telemetry.mjs";
+import { WorkflowStore } from "../types/store.mjs";
+import { ExecutionLimits } from "../types/engine-options.mjs";
+import { Logger } from "@temelj/log";
+//#region src/engine/context.d.ts
+/** What engine operations share: the store, the clock, limits, IDs, logging, and observation. */
+export interface EngineContext {
+  readonly store: WorkflowStore;
+  readonly now: () => Temporal.Instant;
+  readonly limits: ExecutionLimits;
+  readonly observation: ObservationEmitter;
+  readonly telemetry?: Telemetry;
+  readonly logger: Logger;
+  readonly createRunId: () => string;
+}
+//#endregion

package/dist/engine/create.d.mts

@@ -1,106 +1,48 @@
-import { RunId } from "../types/run-id.mjs";
-import { CleanupMarkerRecord, CleanupRunsOptions, CleanupRunsResult, RetentionPolicyOptions } from "../types/cleanup.mjs";
-import { PageOptions, WorkflowPage } from "../types/pagination.mjs";
-import { ListSchedulesOptions, ListSchedulesPageOptions, ScheduleConfig, ScheduleId, ScheduleRecord, TickSchedulesOptions, TickSchedulesResult } from "../types/schedule.mjs";
-import { WorkflowImplementation, WorkflowStartTarget } from "../types/definition.mjs";
-import { HookInspection, ResumeHookOptions, ResumeWebhookOptions } from "../types/hook.mjs";
-import { AcquireLockOptions, LockRecord, ReleaseLockOptions, ReleaseStaleLockOptions } from "../types/lock.mjs";
-import { WorkflowListRunsOptions, WorkflowListRunsPageOptions, WorkflowListStepAttemptsPageOptions } from "../types/run-list.mjs";
-import { BroadcastMessageChannelOptions, BroadcastMessageInput, BroadcastMessageResult, MessageChannel, SendMessageChannelOptions, SendMessageInput } from "../types/message.mjs";
-import { StreamIdOrName } from "../types/stream-id.mjs";
-import { FollowStreamOptions, ReadStreamOptions, ReadStreamPageOptions, StreamChunk, StreamInfo, StreamPage, StreamState, StreamUpdate, WaitStreamOptions } from "../types/stream.mjs";
-import { WorkflowRecoverySummary, WorkflowRecoverySummaryOptions, WorkflowRunSummary, WorkflowRunSummaryOptions } from "../types/summary.mjs";
-import { WorkflowListStepAttemptsOptions, WorkflowStepAttemptRecord, WorkflowStepAttemptSummary } from "../types/step-attempts.mjs";
-import { ObservationEventHandler, ObservationEventPattern, ObservationUnsubscribe, ScheduleRunCreatedObservationEvent, WorkerOperationObservationEvent } from "../types/observation.mjs";
-import { Timeline } from "../types/timeline.mjs";
-import { ExecutionResult, WorkflowHandle } from "../types/result.mjs";
-import { WorkflowAttributePatch, WorkflowRunRecord } from "../types/run.mjs";
-import { EventRecord } from "../types/events.mjs";
-import { ScheduleNextOptions, WorkflowBatchStartItem, WorkflowExecutionOptions, WorkflowMarkRunPermanentlyFailedOptions, WorkflowReleaseStaleLeaseOptions, WorkflowRerunOptions, WorkflowRescheduleRunOptions, WorkflowResumeOptions, WorkflowRetryFailedRunOptions, WorkflowStartOptions } from "../types/run-options.mjs";
-import { WorkflowMessageIdempotencyIndex, WorkflowStorage, WorkflowStore } from "../types/store.mjs";
+import { RunId } from "../types/ids.mjs";
+import { ScheduleConfig, ScheduleRecord, TickSchedulesOptions, TickSchedulesResult } from "../types/schedule.mjs";
+import { StartTarget, WorkflowImplementation } from "../types/definition.mjs";
+import { AcquireLockOptions, LockRecord, ReleaseLockOptions } from "../types/lock.mjs";
+import { ListRunsOptions } from "../types/run-list.mjs";
+import { RunSummary } from "../types/summary.mjs";
+import { ObservationEmitter } from "../types/observation.mjs";
+import { ExecutionResult } from "../types/result.mjs";
+import { RunRecord } from "../types/run.mjs";
+import { WorkflowStorage, WorkflowStore } from "../types/store.mjs";
 import { CreateWorkflowEngineOptions } from "../types/engine-options.mjs";
-import { WorkflowEngine as WorkflowEngine$1 } from "../types/engine.mjs";
-import "../mod.mjs";
+import { BatchStartItem, ExecutionOptions, RerunOptions, ResumeOptions, ScheduleNextOptions, StartOptions } from "../types/run-options.mjs";
+import { EngineContext } from "./context.mjs";
+import { RunRef } from "./start.mjs";
+import { StorageValue } from "@temelj/storage";
 //#region src/engine/create.d.ts
-/** Creates workflow engine. */
-declare function createWorkflowEngine(options?: CreateWorkflowEngineOptions): WorkflowEngine$1;
-/** Storage-backed workflow engine implementation used by the default client and runtime. */
-declare class WorkflowEngine implements WorkflowEngine$1 {
+interface EngineRunLifecycle {
+  readonly emitLifecycleEvent: (next: RunRecord, previous: RunRecord) => void | Promise<void>;
+  readonly emitRunMetadataUpdated: (next: RunRecord, previous: RunRecord) => void;
+}
+export declare function createWorkflowEngine(options?: CreateWorkflowEngineOptions): WorkflowEngine;
+/** Executes workflows against a store; the client and workers build on it. */
+export declare class WorkflowEngine {
   #private;
   readonly storage: WorkflowStorage;
   readonly store: WorkflowStore;
+  readonly observation: ObservationEmitter;
+  /** Shared by the engine's services and the client facades. */
+  readonly context: EngineContext;
+  readonly lifecycle: EngineRunLifecycle;
   constructor(options?: CreateWorkflowEngineOptions);
-  on<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): ObservationUnsubscribe;
-  once<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): ObservationUnsubscribe;
-  off<Pattern extends ObservationEventPattern>(pattern: Pattern, handler: ObservationEventHandler<Pattern>): void;
-  listeners(): readonly ObservationEventHandler[];
-  listeners<Pattern extends ObservationEventPattern>(pattern: Pattern): readonly ObservationEventHandler<Pattern>[];
-  clearListeners(pattern?: ObservationEventPattern): void;
-  listenerCount(pattern?: ObservationEventPattern): number;
   close(): Promise<void>;
-  observeWorkerOperation(event: WorkerOperationObservationEvent): void;
-  observeScheduleRunCreated(event: ScheduleRunCreatedObservationEvent): void;
-  startWorkflow<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options?: WorkflowStartOptions): Promise<WorkflowHandle<TOutput>>;
-  startWorkflows<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, items: readonly WorkflowBatchStartItem<TRawInput>[]): Promise<readonly WorkflowHandle<TOutput>[]>;
-  scheduleNextWorkflow<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options: ScheduleNextOptions): Promise<WorkflowHandle<TOutput>>;
-  createSchedule<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, scheduleOptions: ScheduleConfig<TInput, TRawInput>): Promise<ScheduleRecord<TInput>>;
-  upsertSchedule<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowStartTarget<TInput, TOutput, TRawInput>, scheduleOptions: ScheduleConfig<TInput, TRawInput>): Promise<ScheduleRecord<TInput>>;
-  getSchedule(scheduleId: ScheduleId): Promise<ScheduleRecord | undefined>;
-  listSchedules(options?: ListSchedulesOptions): Promise<readonly ScheduleRecord[]>;
-  listSchedulesPage(options?: ListSchedulesPageOptions): Promise<WorkflowPage<ScheduleRecord>>;
-  pauseSchedule(scheduleId: ScheduleId): Promise<ScheduleRecord>;
-  resumeSchedule(scheduleId: ScheduleId): Promise<ScheduleRecord>;
-  archiveSchedule(scheduleId: ScheduleId): Promise<ScheduleRecord>;
-  deleteSchedule(scheduleId: ScheduleId): Promise<ScheduleRecord>;
+  startWorkflow<TInput, TOutput, TRawInput = TInput>(workflow: StartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options?: StartOptions): Promise<RunRef<TOutput>>;
+  startWorkflows<TInput, TOutput, TRawInput = TInput>(workflow: StartTarget<TInput, TOutput, TRawInput>, items: readonly BatchStartItem<TRawInput>[]): Promise<readonly RunRef<TOutput>[]>;
+  getRunRef(runId: RunId): Promise<RunRef<StorageValue | undefined>>;
+  scheduleNextWorkflow<TInput, TOutput, TRawInput = TInput>(workflow: StartTarget<TInput, TOutput, TRawInput>, input: TRawInput, options: ScheduleNextOptions): Promise<RunRef<TOutput>>;
+  createSchedule<TInput, TOutput, TRawInput = TInput>(workflow: StartTarget<TInput, TOutput, TRawInput>, scheduleOptions: ScheduleConfig<TInput, TRawInput>): Promise<ScheduleRecord>;
   tickSchedules(options?: TickSchedulesOptions): Promise<TickSchedulesResult>;
   acquireLock(key: string, options: AcquireLockOptions): Promise<LockRecord>;
-  getLock(key: string): Promise<LockRecord | undefined>;
-  listLocks(): Promise<readonly LockRecord[]>;
   releaseLock(key: string, options: ReleaseLockOptions): Promise<LockRecord>;
-  releaseStaleLock(key: string, options?: ReleaseStaleLockOptions): Promise<LockRecord>;
-  runWorkflow<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>, input: TRawInput, options?: WorkflowExecutionOptions): Promise<WorkflowHandle<TOutput>>;
-  runWorkflowNow<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>, input: TRawInput, options?: WorkflowExecutionOptions): Promise<ExecutionResult<TOutput>>;
-  resumeWorkflow<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>, runId: RunId, options?: WorkflowResumeOptions): Promise<ExecutionResult<TOutput>>;
-  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>;
-  cleanupRuns(options: CleanupRunsOptions): Promise<CleanupRunsResult>;
-  listCleanupMarkers(): Promise<readonly CleanupMarkerRecord[]>;
-  applyRetentionPolicy(retentionOptions: RetentionPolicyOptions): Promise<CleanupRunsResult>;
-  rerunWorkflow(runId: RunId, options?: WorkflowRerunOptions): Promise<WorkflowHandle<unknown>>;
-  rescheduleRun(runId: RunId, options?: WorkflowRescheduleRunOptions): Promise<WorkflowRunRecord>;
-  releaseStaleRunLease(runId: RunId, options?: WorkflowReleaseStaleLeaseOptions): Promise<WorkflowRunRecord>;
-  retryFailedRun(runId: RunId, options?: WorkflowRetryFailedRunOptions): Promise<WorkflowRunRecord>;
-  markRunPermanentlyFailed(runId: RunId, options: WorkflowMarkRunPermanentlyFailedOptions): Promise<WorkflowRunRecord>;
-  updateRunMetadata(runId: RunId, metadata: unknown): Promise<WorkflowRunRecord>;
-  setRunAttributes(runId: RunId, attributes: WorkflowAttributePatch): Promise<WorkflowRunRecord>;
-  cancelRun(runId: RunId): Promise<WorkflowRunRecord>;
-  resumeHook(token: string, options?: ResumeHookOptions): Promise<void>;
-  resumeWebhook(token: string, options?: ResumeWebhookOptions): Promise<void>;
-  disposeHook(token: string): Promise<HookInspection>;
-  disposeWebhook(token: string): Promise<HookInspection>;
-  getHookByToken(token: string): Promise<HookInspection>;
-  getStreamInfo(runId: RunId, streamIdOrName: StreamIdOrName): Promise<StreamInfo>;
-  followStream<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, followOptions?: FollowStreamOptions): AsyncIterable<StreamUpdate<TChunk>>;
-  waitForStream(runId: RunId, streamIdOrName: StreamIdOrName, waitOptions?: WaitStreamOptions): Promise<StreamInfo | undefined>;
-  waitForStreamChunk<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, afterIndex: number, waitOptions?: WaitStreamOptions): Promise<StreamChunk<TChunk> | undefined>;
-  waitForStreamTerminal(runId: RunId, streamIdOrName: StreamIdOrName, waitOptions?: WaitStreamOptions): Promise<StreamInfo | undefined>;
-  readStream<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, readOptions?: ReadStreamOptions): Promise<StreamState<TChunk>>;
-  readStreamPage<TChunk = unknown>(runId: RunId, streamIdOrName: StreamIdOrName, readOptions?: ReadStreamPageOptions): Promise<StreamPage<TChunk>>;
-  sendMessage<TPayload, TKey = void>(runId: RunId, messageInput: SendMessageInput | MessageChannel<TPayload, TKey>, channelOptions?: SendMessageChannelOptions<TPayload, TKey>): Promise<void>;
-  broadcastMessage<TPayload, TKey = void>(messageInput: BroadcastMessageInput | MessageChannel<TPayload, TKey>, channelOptions?: BroadcastMessageChannelOptions<TPayload, TKey>): Promise<BroadcastMessageResult>;
+  runWorkflow<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>, input: TRawInput, options?: ExecutionOptions): Promise<RunRef<TOutput>>;
+  runWorkflowNow<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>, input: TRawInput, options?: ExecutionOptions): Promise<ExecutionResult<TOutput>>;
+  resumeWorkflow<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>, runId: RunId, options?: ResumeOptions): Promise<ExecutionResult<TOutput>>;
+  getRunSummary(options?: ListRunsOptions): Promise<RunSummary>;
+  rerunWorkflow(runId: RunId, options?: RerunOptions): Promise<RunRef<unknown>>;
 }
 //#endregion
-export { WorkflowEngine, createWorkflowEngine };
+export {};