@temelj/workflow 0.0.0-alpha.1

package/dist/collection.d.mts

@@ -0,0 +1,15 @@
+//#region src/collection.d.ts
+/** Returns whether a value matches one expected value or any value in an expected list. */
+declare function matchesOptionalValue<T>(value: T, expected: T | readonly T[]): boolean;
+/** Returns the first item for each key while preserving input order. */
+declare function uniqueBy<T>(items: readonly T[], key: (item: T) => string): readonly T[];
+/** Returns a copy of an object without properties whose value is undefined. */
+declare function omitUndefined(value: object): Record<string, unknown>;
+/** Returns an object containing one property only when the value is defined. */
+declare function optionalProperty<TKey extends string, TValue>(key: TKey, value: TValue | undefined): Partial<Record<TKey, TValue>>;
+/** Returns sorted string values from a set. */
+declare function sortedStringSet(values: ReadonlySet<string>): readonly string[];
+/** Returns an object containing a sorted string set only when the set is not empty. */
+declare function optionalSortedStringSetProperty<TKey extends string>(key: TKey, values: ReadonlySet<string>): Partial<Record<TKey, readonly string[]>>;
+//#endregion
+export { matchesOptionalValue, omitUndefined, optionalProperty, optionalSortedStringSetProperty, sortedStringSet, uniqueBy };

package/dist/collection.mjs

@@ -0,0 +1,33 @@
+//#region src/collection.ts
+/** Returns whether a value matches one expected value or any value in an expected list. */
+function matchesOptionalValue(value, expected) {
+	return Array.isArray(expected) ? expected.includes(value) : Object.is(value, expected);
+}
+/** Returns the first item for each key while preserving input order. */
+function uniqueBy(items, key) {
+	const seen = /* @__PURE__ */ new Set();
+	return items.filter((item) => {
+		const itemKey = key(item);
+		if (seen.has(itemKey)) return false;
+		seen.add(itemKey);
+		return true;
+	});
+}
+/** Returns a copy of an object without properties whose value is undefined. */
+function omitUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+/** Returns an object containing one property only when the value is defined. */
+function optionalProperty(key, value) {
+	return value === void 0 ? {} : { [key]: value };
+}
+/** Returns sorted string values from a set. */
+function sortedStringSet(values) {
+	return [...values].sort();
+}
+/** Returns an object containing a sorted string set only when the set is not empty. */
+function optionalSortedStringSetProperty(key, values) {
+	return values.size === 0 ? {} : { [key]: sortedStringSet(values) };
+}
+//#endregion
+export { matchesOptionalValue, omitUndefined, optionalProperty, optionalSortedStringSetProperty, sortedStringSet, uniqueBy };

package/dist/compiled-function.d.mts

@@ -0,0 +1,27 @@
+import { RegistryLike, WorkflowImplementation } from "./types/definition.mjs";
+import { WorkflowStepApi, WorkflowStepDefinition } from "./types/step.mjs";
+import { CompiledWorkflowFunction, WorkflowClient, WorkflowRunHandle } from "./types/client.mjs";
+//#region src/compiled-function.d.ts
+type AnyCompiledWorkflowFunction = (...args: never[]) => unknown;
+type AnyCompiledWorkflowImplementation = WorkflowImplementation<readonly unknown[], unknown, readonly unknown[]>;
+type AnyCompiledWorkflowStepDefinition = WorkflowStepDefinition<readonly unknown[], unknown>;
+/** Attaches compiled workflow metadata to a directive-authored function. */
+declare function attachWorkflowDefinition<TArgs extends readonly unknown[], TOutput>(fn: CompiledWorkflowFunction<TArgs, TOutput>, definition: WorkflowImplementation<TArgs, Awaited<TOutput>, TArgs>): CompiledWorkflowFunction<TArgs, TOutput>;
+/** Attaches compiled step metadata to a directive-authored function. */
+declare function attachWorkflowStepDefinition<TArgs extends readonly unknown[], TOutput>(fn: CompiledWorkflowFunction<TArgs, TOutput>, definition: WorkflowStepDefinition<TArgs, Awaited<TOutput>>): CompiledWorkflowFunction<TArgs, TOutput>;
+/** Reads workflow metadata previously attached to a compiled workflow function. */
+declare function getWorkflowFunctionDefinition<TArgs extends readonly unknown[], TOutput>(fn: CompiledWorkflowFunction<TArgs, TOutput>): WorkflowImplementation<TArgs, Awaited<TOutput>, TArgs> | undefined;
+/** Reads step metadata previously attached to a compiled step function. */
+declare function getWorkflowStepFunctionDefinition<TArgs extends readonly unknown[], TOutput>(fn: CompiledWorkflowFunction<TArgs, TOutput>): WorkflowStepDefinition<TArgs, Awaited<TOutput>> | undefined;
+/** Reads erased workflow metadata from a function after runtime validation. */
+declare function getCompiledWorkflowDefinition(fn: AnyCompiledWorkflowFunction): AnyCompiledWorkflowImplementation | undefined;
+/** Reads erased step metadata from a function after runtime validation. */
+declare function getCompiledWorkflowStepDefinition(fn: AnyCompiledWorkflowFunction): AnyCompiledWorkflowStepDefinition | undefined;
+/** Registers compiled workflow functions with a workflow registry. */
+declare function registerWorkflowFunctions(registry: RegistryLike, workflows: readonly AnyCompiledWorkflowFunction[]): void;
+/** Starts a compiled workflow function through a workflow client. */
+declare function runWorkflowFunction<TArgs extends readonly unknown[], TOutput>(client: WorkflowClient, workflow: CompiledWorkflowFunction<TArgs, TOutput>, ...args: TArgs): Promise<WorkflowRunHandle<Awaited<TOutput>>>;
+/** Calls a compiled step function through the durable step API when metadata is present. */
+declare function callWorkflowStepFunction<TArgs extends readonly unknown[], TOutput>(step: WorkflowStepApi, fn: CompiledWorkflowFunction<TArgs, TOutput>, ...args: TArgs): Promise<Awaited<TOutput>>;
+//#endregion
+export { attachWorkflowDefinition, attachWorkflowStepDefinition, callWorkflowStepFunction, getCompiledWorkflowDefinition, getCompiledWorkflowStepDefinition, getWorkflowFunctionDefinition, getWorkflowStepFunctionDefinition, registerWorkflowFunctions, runWorkflowFunction };

package/dist/compiled-function.mjs

@@ -0,0 +1,54 @@
+import { WorkflowDefinitionError } from "./errors/definition.mjs";
+import "./errors/mod.mjs";
+//#region src/compiled-function.ts
+const workflowDefinitions = /* @__PURE__ */ new WeakMap();
+const stepDefinitions = /* @__PURE__ */ new WeakMap();
+/** Attaches compiled workflow metadata to a directive-authored function. */
+function attachWorkflowDefinition(fn, definition) {
+	workflowDefinitions.set(fn, definition);
+	return fn;
+}
+/** Attaches compiled step metadata to a directive-authored function. */
+function attachWorkflowStepDefinition(fn, definition) {
+	stepDefinitions.set(fn, definition);
+	return fn;
+}
+/** Reads workflow metadata previously attached to a compiled workflow function. */
+function getWorkflowFunctionDefinition(fn) {
+	return getCompiledWorkflowDefinition(fn);
+}
+/** Reads step metadata previously attached to a compiled step function. */
+function getWorkflowStepFunctionDefinition(fn) {
+	return getCompiledWorkflowStepDefinition(fn);
+}
+/** Reads erased workflow metadata from a function after runtime validation. */
+function getCompiledWorkflowDefinition(fn) {
+	return workflowDefinitions.get(fn);
+}
+/** Reads erased step metadata from a function after runtime validation. */
+function getCompiledWorkflowStepDefinition(fn) {
+	return stepDefinitions.get(fn);
+}
+/** Registers compiled workflow functions with a workflow registry. */
+function registerWorkflowFunctions(registry, workflows) {
+	for (const workflow of workflows) {
+		const definition = getCompiledWorkflowDefinition(workflow);
+		if (definition === void 0) WorkflowDefinitionError.compiledMetadataMissing();
+		registry.register(definition);
+	}
+}
+/** Starts a compiled workflow function through a workflow client. */
+async function runWorkflowFunction(client, workflow, ...args) {
+	const definition = getWorkflowFunctionDefinition(workflow);
+	if (definition === void 0) WorkflowDefinitionError.compiledMetadataMissing();
+	client.register(definition);
+	return await client.runs.start(definition.definition, args);
+}
+/** Calls a compiled step function through the durable step API when metadata is present. */
+async function callWorkflowStepFunction(step, fn, ...args) {
+	const definition = getWorkflowStepFunctionDefinition(fn);
+	if (definition === void 0) return await fn(...args);
+	return await step.task.call(definition, ...args);
+}
+//#endregion
+export { attachWorkflowDefinition, attachWorkflowStepDefinition, callWorkflowStepFunction, getCompiledWorkflowDefinition, getCompiledWorkflowStepDefinition, getWorkflowFunctionDefinition, getWorkflowStepFunctionDefinition, registerWorkflowFunctions, runWorkflowFunction };

package/dist/definition.d.mts

@@ -0,0 +1,37 @@
+import { MessageId } from "./types/message-id.mjs";
+import { WorkflowDefinition, WorkflowDefinitionConfig, WorkflowHandler, WorkflowImplementation, WorkflowInputFromSchema, WorkflowRawInputFromSchema, WorkflowStartTarget } from "./types/definition.mjs";
+import { MessageChannel, MessageChannelConfig, SendMessageChannelOptions, WaitForMessageChannelOptions } from "./types/message.mjs";
+import { Schema, SchemaOutput } from "@temelj/standard-schema";
+//#region src/definition.d.ts
+/** Defines a durable workflow definition. */
+declare function defineWorkflow<TInput = unknown, TOutput = unknown, TRawInput = TInput>(config: WorkflowDefinitionConfig): WorkflowDefinition<TInput, TOutput, TRawInput>;
+/** Defines a durable workflow definition. */
+declare function defineWorkflow<const TSchema extends Schema, TOutput = unknown>(config: WorkflowDefinitionConfig<TSchema>): WorkflowDefinition<SchemaOutput<TSchema>, TOutput, WorkflowRawInputFromSchema<TSchema, never>>;
+/** Creates a workflow definition from a resolved name and optional version. */
+declare function defineWorkflowFromName<TInput = unknown, TOutput = unknown, TRawInput = TInput>(name: string, version?: string): WorkflowDefinition<TInput, TOutput, TRawInput>;
+/** Returns the durable definition for a workflow definition or implementation. */
+declare function defineWorkflowFromTarget<TInput, TOutput, TRawInput>(target: WorkflowStartTarget<TInput, TOutput, TRawInput>): WorkflowDefinition<TInput, TOutput, TRawInput>;
+/** Defines an executable workflow implementation from durable workflow config. */
+declare function implementWorkflow<TInput = unknown, TOutput = unknown, TRawInput = TInput>(config: WorkflowDefinitionConfig, handler: WorkflowHandler<TInput, TOutput>): WorkflowImplementation<TInput, TOutput, TRawInput>;
+/** Defines an executable workflow implementation from durable workflow config. */
+declare function implementWorkflow<const TSchema extends Schema, TOutput = unknown>(config: WorkflowDefinitionConfig<TSchema>, handler: WorkflowHandler<SchemaOutput<TSchema>, TOutput>): WorkflowImplementation<SchemaOutput<TSchema>, TOutput, WorkflowRawInputFromSchema<TSchema, never>>;
+/** Defines workflow message channel for durable workflow use. */
+declare function defineMessageChannel<TPayload = unknown, TKey = void, const TSchema extends Schema | undefined = undefined>(config: MessageChannelConfig<TKey, TSchema>): MessageChannel<WorkflowInputFromSchema<TSchema, TPayload>, TKey>;
+/** Normalizes and parses workflow message channel send. */
+declare function resolveMessageChannelSend<TPayload, TKey>(channel: MessageChannel<TPayload, TKey>, options?: SendMessageChannelOptions<TPayload, TKey>): Promise<{
+  readonly messageId: MessageId;
+  readonly payload?: TPayload;
+  readonly idempotencyKey?: string;
+}>;
+/** Normalizes and parses workflow message channel wait. */
+declare function resolveMessageChannelWait<TKey>(channel: MessageChannel<unknown, TKey>, options?: WaitForMessageChannelOptions<TKey>): {
+  commandId: string;
+  name: string;
+  messageId: string;
+  timeout?: Temporal.Duration | undefined;
+  schema?: Schema | undefined;
+};
+/** Parses raw workflow input against the definition schema when one is configured. */
+declare function parseWorkflowInput<TInput>(definition: WorkflowDefinition<TInput, unknown, unknown>, input: unknown): Promise<TInput>;
+//#endregion
+export { defineMessageChannel, defineWorkflow, defineWorkflowFromName, defineWorkflowFromTarget, implementWorkflow, parseWorkflowInput, resolveMessageChannelSend, resolveMessageChannelWait };

package/dist/definition.mjs

@@ -0,0 +1,83 @@
+import { validateStandardSchema } from "@temelj/standard-schema";
+//#region src/definition.ts
+/** Defines a durable workflow definition. */
+function defineWorkflow(config) {
+	return {
+		kind: "definition",
+		config,
+		name: config.name,
+		...config.version === void 0 ? {} : { version: config.version }
+	};
+}
+/** Creates a workflow definition from a resolved name and optional version. */
+function defineWorkflowFromName(name, version) {
+	return defineWorkflow({
+		name,
+		...version === void 0 ? {} : { version }
+	});
+}
+/** Returns the durable definition for a workflow definition or implementation. */
+function defineWorkflowFromTarget(target) {
+	return target.kind === "implementation" ? target.definition : target;
+}
+/** Defines an executable workflow implementation from durable workflow config. */
+function implementWorkflow(config, handler) {
+	const definition = {
+		kind: "definition",
+		config,
+		name: config.name,
+		...config.version === void 0 ? {} : { version: config.version }
+	};
+	return {
+		kind: "implementation",
+		definition,
+		config: definition.config,
+		name: definition.name,
+		...definition.version === void 0 ? {} : { version: definition.version },
+		handler
+	};
+}
+/** Defines workflow message channel for durable workflow use. */
+function defineMessageChannel(config) {
+	const name = config.name;
+	return {
+		name,
+		...config.schema === void 0 ? {} : { schema: config.schema },
+		resolveMessageId: (...args) => {
+			return config.resolveMessageId?.(...args) ?? name;
+		}
+	};
+}
+/** Normalizes and parses workflow message channel send. */
+async function resolveMessageChannelSend(channel, options = {}) {
+	const payload = channel.schema === void 0 ? options.payload : await validateStandardSchema(channel.schema, options.payload, "Workflow message validation failed");
+	return {
+		messageId: resolveMessageChannelMessageId(channel, options.key),
+		...payload === void 0 ? {} : { payload },
+		...options.idempotencyKey === void 0 ? {} : { idempotencyKey: options.idempotencyKey }
+	};
+}
+/** Normalizes and parses workflow message channel wait. */
+function resolveMessageChannelWait(channel, options = {}) {
+	return {
+		commandId: options.commandId ?? options.name ?? channel.name,
+		name: options.name ?? channel.name,
+		messageId: resolveMessageChannelMessageId(channel, options.key),
+		...options.timeout === void 0 ? {} : { timeout: options.timeout },
+		...channel.schema === void 0 ? {} : { schema: channel.schema }
+	};
+}
+function resolveMessageChannelMessageId(channel, key) {
+	return channel.resolveMessageId(...workflowMessageChannelKeyArgs(key));
+}
+function workflowMessageChannelKeyArgs(key) {
+	return key === void 0 ? [] : [key];
+}
+/** Parses raw workflow input against the definition schema when one is configured. */
+async function parseWorkflowInput(definition, input) {
+	const schema = definition.config.schema;
+	if (schema === void 0) return input;
+	return await validateStandardSchema(schema, input, "Workflow input validation failed");
+}
+//#endregion
+export { defineMessageChannel, defineWorkflow, defineWorkflowFromName, defineWorkflowFromTarget, implementWorkflow, parseWorkflowInput, resolveMessageChannelSend, resolveMessageChannelWait };

package/dist/engine/child-workflow.d.mts

@@ -0,0 +1,10 @@
+import { WorkflowDefinition } from "../types/definition.mjs";
+import { WorkflowStepRunWorkflowOptions, WorkflowStepStartWorkflowOptions, WorkflowStepWorkflowApi } from "../types/step.mjs";
+import { WorkflowExecutionEnvironment, WorkflowRunCanceler, WorkflowRunStarter } from "../types/engine.mjs";
+//#region src/engine/child-workflow.d.ts
+interface WorkflowChildWorkflowEngine extends WorkflowRunStarter, WorkflowRunCanceler {}
+declare function createWorkflowStepWorkflowApi(environment: WorkflowExecutionEnvironment, engine: WorkflowChildWorkflowEngine): WorkflowStepWorkflowApi;
+declare function runChildWorkflow<TInput, TOutput, TRawInput = TInput>(environment: WorkflowExecutionEnvironment, engine: WorkflowChildWorkflowEngine, definition: WorkflowDefinition<TInput, TOutput, TRawInput>, input: TRawInput, options: WorkflowStepRunWorkflowOptions | undefined): Promise<TOutput>;
+declare function startBackgroundChildWorkflow<TInput, TOutput, TRawInput = TInput>(environment: WorkflowExecutionEnvironment, engine: WorkflowChildWorkflowEngine, definition: WorkflowDefinition<TInput, TOutput, TRawInput>, input: TRawInput, options: WorkflowStepStartWorkflowOptions | undefined): Promise<string>;
+//#endregion
+export { WorkflowChildWorkflowEngine, createWorkflowStepWorkflowApi, runChildWorkflow, startBackgroundChildWorkflow };

package/dist/engine/child-workflow.mjs

@@ -0,0 +1,333 @@
+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 { 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 { deepEquals } from "@temelj/value";
+//#region src/engine/child-workflow.ts
+function createWorkflowStepWorkflowApi(environment, engine) {
+	return {
+		async run(workflow, input, options) {
+			return await runChildWorkflow(environment, engine, defineWorkflowFromTarget(workflow), input, options);
+		},
+		async start(workflow, input, options) {
+			return await startBackgroundChildWorkflow(environment, engine, defineWorkflowFromTarget(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", [
+		options?.commandId,
+		options?.name,
+		definition.name
+	], "Workflow child commandId, name, or definition name");
+	const started = history.startedChildWorkflow(identity.id);
+	const completed = history.completedChildWorkflow(identity.id);
+	if (completed !== void 0) {
+		requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(completed));
+		if (started === void 0 || isChildWorkflowTerminalForStartedAttempt(completed, started)) {
+			requireChildWorkflowReplayMatches(runId, identity, started, definition, input, options, limits);
+			recordedChildWorkflowCompletionTimestamp(identity, completed.timestamp);
+			return completed.result;
+		}
+	}
+	const retry = resolveChildWorkflowRetryConfig(options);
+	const failed = history.failedChildWorkflow(identity.id);
+	if (failed !== void 0) requireRecordedDurableTerminalStarted(identity, history.hasStartedEventBeforeTerminalEvent(failed));
+	if (started !== void 0) {
+		requireRecordedChildWorkflowStartedAttempt(identity, started);
+		requireChildWorkflowReplayMatches(runId, identity, started, definition, input, options, limits);
+	}
+	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 nextAttempt = nextChildWorkflowRetryAttempt(runId, latestFailedAttempt.attempt, maximumStepAttemptsPerRun);
+		if (retry.maximumAttempts !== 0 && nextAttempt > retry.maximumAttempts) WorkflowStepExecutionError.failed({
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt: latestFailedAttempt.attempt,
+			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);
+	}
+	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));
+	if (timeoutAt !== void 0 && Temporal.Instant.compare(timeoutAt, now()) <= 0 && childRun.status !== "completed" && childRun.status !== "failed" && childRun.status !== "canceled") {
+		const error = childWorkflowTimeoutErrorRecord({
+			runId,
+			childRunId,
+			stepId: identity.id,
+			timeoutAt
+		});
+		await appendDurableStepTerminalEvent(environment, {
+			kind: "child_workflow_failed",
+			timestamp: now(),
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			childRunId,
+			error
+		});
+		await requireCurrentExecutionOwner(store, runId, executionOwner);
+		await engine.cancelRun(childRunId);
+		if (retry.maximumAttempts === 0 || attempt < retry.maximumAttempts) suspendChildWorkflowRetry(runId, timeoutAt, retry, identity, attempt, maximumStepAttemptsPerRun);
+		WorkflowStepExecutionError.failed({
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			cause: workflowErrorFromRecord(error)
+		});
+	}
+	if (childRun.status === "completed") {
+		await appendDurableStepTerminalEvent(environment, {
+			kind: "child_workflow_completed",
+			timestamp: now(),
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			childRunId,
+			result: childRun.output
+		});
+		return childRun.output;
+	}
+	if (childRun.status === "failed" || childRun.status === "canceled") {
+		const error = childRun.error ?? (childRun.status === "canceled" ? serializeError(WorkflowRunCanceledError.create(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");
+		})();
+		await appendDurableStepTerminalEvent(environment, {
+			kind: "child_workflow_failed",
+			timestamp: failedAt,
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			childRunId,
+			error
+		});
+		if (childRun.status === "canceled") WorkflowStepExecutionError.failed({
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			cause: workflowErrorFromRecord(error)
+		});
+		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);
+		}
+		WorkflowStepExecutionError.failed({
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			cause: workflowErrorFromRecord(error)
+		});
+	}
+	WorkflowSuspended.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", [
+		options?.commandId,
+		options?.name,
+		definition.name
+	], "Workflow child commandId, name, or definition name");
+	const started = history.startedChildWorkflow(identity.id);
+	if (started !== void 0) {
+		requireRecordedChildWorkflowStartedAttempt(identity, started);
+		requireChildWorkflowReplayMatches(runId, identity, started, definition, input, options, limits);
+		return started.childRunId;
+	}
+	return await startChildWorkflow(store, engine, runId, history, now, maximumStepAttemptsPerRun, identity, definition, input, options, 1, limits, executionOwner, environment.createRecordedId, environment.createDeterministicRandom, environment.createDeterministicUuid, environment.createDeterministicBytes, environment.telemetry, environment.logger, environment.replaying, environment.observeChildWorkflowStarted);
+}
+function childRunMatchesParentStepAttempt(childRun, parentRunId, identity, attempt) {
+	return childRun.parentRunId === parentRunId && childRun.parentStepId === identity.id && childRun.parentStepName === identity.name && childRun.parentStepAttempt === attempt;
+}
+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}`;
+	const replayIdempotencyKey = childWorkflowIdempotencyKey(runId, identity, options, started.attempt);
+	const replayCancellation = resolveChildWorkflowCancellationPolicy(options);
+	if (started.workflowName === definition.name && started.workflowVersion === definition.version && (replayChildRunId === void 0 || started.childRunId === replayChildRunId) && started.idempotencyKey === replayIdempotencyKey && (started.cancellation ?? "cascade") === replayCancellation && deepEquals(started.input, toOptionalPersistedValue(input, "child workflow input", limits)) && started.timeoutAt === void 0 === (options?.timeout === void 0)) return;
+	const recordedWorkflow = started.workflowVersion === void 0 ? started.workflowName : `${started.workflowName}@${started.workflowVersion}`;
+	const replayWorkflow = definition.version === void 0 ? definition.name : `${definition.name}@${definition.version}`;
+	let message;
+	if (recordedWorkflow !== replayWorkflow) message = `recorded workflow step ${identity.id} targeted ${recordedWorkflow}, but replay targeted ${replayWorkflow}`;
+	else if (replayChildRunId !== void 0 && started.childRunId !== replayChildRunId) message = `recorded workflow step ${identity.id} started child run ${started.childRunId}, but replay requested child run ${replayChildRunId}`;
+	else if (started.idempotencyKey !== replayIdempotencyKey) {
+		const recordedIdempotencyKey = started.idempotencyKey ?? "no idempotency key";
+		message = `recorded workflow step ${identity.id} used child idempotency key ${recordedIdempotencyKey}, but replay used ${replayIdempotencyKey}`;
+	} else if ((started.cancellation ?? "cascade") !== replayCancellation) message = `recorded workflow step ${identity.id} used child cancellation policy ${started.cancellation ?? "cascade"}, but replay used ${replayCancellation}`;
+	else if (!deepEquals(started.input, toOptionalPersistedValue(input, "child workflow input", limits))) message = `recorded workflow step ${identity.id} targeted ${recordedWorkflow} with different input`;
+	else {
+		const recordedTimeout = started.timeoutAt === void 0 ? "no timeout" : started.timeoutAt;
+		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
+	});
+}
+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
+	});
+}
+function suspendChildWorkflowRetry(runId, failedAt, retry, identity, attempt, maximumStepAttemptsPerRun) {
+	WorkflowSuspended.forStepRetry(nextRetryAt(failedAt, retry, attempt, "Workflow step retry delay") ?? failedAt, identity, nextChildWorkflowRetryAttempt(runId, attempt, maximumStepAttemptsPerRun));
+}
+function nextChildWorkflowRetryAttempt(runId, failedAttempt, maximumStepAttemptsPerRun) {
+	const nextAttempt = nextPositiveSafeInteger(failedAttempt);
+	if (nextAttempt === void 0) WorkflowStepAttemptLimitError.exceeded(runId, maximumStepAttemptsPerRun);
+	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);
+	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}` },
+		idempotencyKey,
+		...deadlineAt === void 0 ? {} : { deadlineAt },
+		parent: {
+			runId,
+			stepId: identity.id,
+			stepName: identity.name,
+			stepAttempt: attempt
+		}
+	});
+	const startedEvent = {
+		kind: "child_workflow_started",
+		timestamp: now(),
+		stepId: identity.id,
+		stepName: identity.name,
+		count: identity.count,
+		attempt,
+		childRunId: handle.runId,
+		workflowName: definition.name,
+		...definition.version === void 0 ? {} : { workflowVersion: definition.version },
+		cancellation,
+		input: persistedInput,
+		idempotencyKey,
+		...timeoutAt === void 0 ? {} : { timeoutAt }
+	};
+	await appendDurableStepStartedEvent({
+		store,
+		runId,
+		history,
+		now,
+		createRecordedId,
+		createDeterministicRandom,
+		createDeterministicUuid,
+		createDeterministicBytes,
+		maximumStepAttemptsPerRun,
+		limits,
+		executionOwner,
+		telemetry,
+		logger,
+		replaying
+	}, startedEvent);
+	observeChildWorkflowStarted?.(runId, startedEvent);
+	return handle.runId;
+}
+function childWorkflowPollAt(now, childRun, pollInterval) {
+	if (hasDueChildSchedule(now, childRun)) return now.add(Temporal.Duration.from({ milliseconds: Math.min(pollInterval, 100) }));
+	return [
+		childRun.availableAt,
+		childRun.retryAt,
+		childRun.deadlineAt,
+		childRun.leaseExpiresAt,
+		now.add(Temporal.Duration.from({ milliseconds: pollInterval }))
+	].filter((value) => value !== void 0).filter((value) => Temporal.Instant.compare(value, now) > 0).sort((left, right) => Temporal.Instant.compare(left, right))[0] ?? now;
+}
+function resolveChildWorkflowPollInterval(options) {
+	const pollInterval = options?.pollInterval === void 0 ? 100 : options.pollInterval.total({ unit: "millisecond" });
+	if (!isPositiveSafeInteger(pollInterval)) WorkflowDurationError.childPollIntervalTimerSafe();
+	return pollInterval;
+}
+function hasDueChildSchedule(now, childRun) {
+	return childRun.availableAt !== void 0 && Temporal.Instant.compare(childRun.availableAt, now) <= 0 || childRun.retryAt !== void 0 && Temporal.Instant.compare(childRun.retryAt, now) <= 0 || childRun.deadlineAt !== void 0 && Temporal.Instant.compare(childRun.deadlineAt, now) <= 0 || childRun.leaseExpiresAt !== void 0 && Temporal.Instant.compare(childRun.leaseExpiresAt, now) <= 0;
+}
+function childWorkflowTimeoutAt(now, options) {
+	if (options?.timeout === void 0) return;
+	if (safeDuration(options.timeout.total({ unit: "millisecond" }), "Workflow child timeout") <= 0) WorkflowDurationError.childTimeoutPositive();
+	return now.add(options.timeout);
+}
+function resolveChildWorkflowCancellationPolicy(options) {
+	const policy = options?.cancellation ?? "cascade";
+	if (policy !== "cascade" && policy !== "detach") WorkflowOptionsError.childCancellationPolicy();
+	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({
+		runId: options.runId,
+		childRunId: options.childRunId,
+		stepId: options.stepId,
+		timeoutAt: options.timeoutAt
+	});
+	return {
+		name: error.name,
+		message: error.message,
+		details: {
+			runId: error.runId,
+			childRunId: error.childRunId,
+			stepId: error.stepId,
+			timeoutAt: error.timeoutAt.toString()
+		}
+	};
+}
+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 };

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

@@ -0,0 +1,9 @@
+import { WorkflowStepIdentity, WorkflowStepType } from "../types/run.mjs";
+import { WorkflowHistory } from "../history/mod.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>;
+/** 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 };

package/dist/engine/command-identity.mjs

@@ -0,0 +1,14 @@
+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) {
+	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);
+}
+//#endregion
+export { resolveWorkflowCommandIdentity, resolveWorkflowCommandIdentityFromCandidates };