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

package/dist/cloudflare/runtime.mjs

@@ -0,0 +1,226 @@
+import { WorkflowResultTimeoutError, WorkflowRunCanceledError } from "../errors/run.mjs";
+import { durationTotal } from "../utility.mjs";
+import { WorkflowCapabilityError } from "../errors/capability.mjs";
+import { WorkflowDefinitionError } from "../errors/definition.mjs";
+import "../errors/mod.mjs";
+import { getCompiledWorkflowDefinition } from "../compiled-function.mjs";
+import { Registry } from "../registry.mjs";
+import { parseWorkflowInput } from "../definition.mjs";
+import { resolveSendMessageInput } from "../message-options.mjs";
+import { decodeCloudflareWorkflowValue, encodeCloudflareWorkflowValue } from "./codec.mjs";
+import { resolveCloudflareWorkflowImplementation } from "./registry.mjs";
+import { makeCloudflareWorkflowEventType } from "./name.mjs";
+//#region src/cloudflare/runtime.ts
+const DEFAULT_RESULT_POLL_INTERVAL = 100;
+const CLOUDFLARE_INSTANCE_ID_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9-_]*$/;
+/** Creates a runtime facade over a generic Cloudflare Workflow binding. */
+function createCloudflareWorkflowRuntime(options) {
+	return new CloudflareWorkflowRuntimeImpl(options);
+}
+var CloudflareWorkflowRuntimeImpl = class {
+	runs;
+	messages;
+	schedules = unsupportedApi("Cloudflare workflow schedules");
+	locks = unsupportedApi("Cloudflare workflow locks");
+	workers = unsupportedApi("Cloudflare workflow workers");
+	#binding;
+	#registry;
+	#registration;
+	#resultPollInterval;
+	constructor(options) {
+		this.#binding = options.binding;
+		this.#registry = options.registry ?? new Registry();
+		this.#registration = options.registration ?? "dynamic";
+		this.#resultPollInterval = options.resultPollInterval === void 0 ? DEFAULT_RESULT_POLL_INTERVAL : durationMilliseconds(options.resultPollInterval, "Cloudflare result poll interval");
+		this.runs = {
+			getHandle: async () => WorkflowCapabilityError.unsupported("Cloudflare run lookup without a workflow target; use runtime.runs.get(workflow, runId)"),
+			list: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow run listing"),
+			get: async (workflow, runId) => this.#createHandle(workflow, runId)
+		};
+		this.messages = { send: async (runId, input, channelOptions) => {
+			const message = await resolveSendMessageInput(input, channelOptions);
+			await (await this.#binding.get(runId)).sendEvent({
+				type: makeCloudflareWorkflowEventType(message.messageId),
+				payload: encodeCloudflareWorkflowValue(message.payload)
+			});
+		} };
+	}
+	async close() {}
+	implementWorkflow(definition, handler) {
+		if (this.#registration === "static") {
+			const implementation = this.#registry.get(definition);
+			if (implementation === void 0 || implementation.handler !== handler) WorkflowDefinitionError.implementationNotBundled(workflowImplementationKey(definition.name, definition.version));
+			return implementation;
+		}
+		return this.#registry.implementWorkflow(definition, handler);
+	}
+	register(implementation) {
+		if (this.#registry.get(implementation.definition) !== implementation) {
+			if (this.#registration === "static") WorkflowDefinitionError.implementationNotBundled(workflowImplementationKey(implementation.name, implementation.version));
+			this.#registry.register(implementation);
+		}
+	}
+	async start(workflow, ...args) {
+		if (typeof workflow === "function") {
+			const implementation = getCompiledWorkflowDefinition(workflow);
+			if (implementation === void 0) WorkflowDefinitionError.compiledMetadataMissing();
+			this.register(implementation);
+			return await this.#startTarget(implementation, args, void 0);
+		}
+		const target = workflow;
+		if (target.kind === "implementation") this.register(target);
+		return await this.#startTarget(target, args[0], args[1]);
+	}
+	async #startTarget(target, rawInput, startOptions) {
+		rejectUnsupportedStartOptions(startOptions);
+		const requestedVersion = startOptions?.workflowVersion ?? target.version;
+		const implementation = resolveCloudflareWorkflowImplementation(this.#registry, target.name, requestedVersion);
+		if (implementation.config.retry !== void 0) WorkflowCapabilityError.unsupported("Cloudflare workflow-level retry configuration");
+		const input = await parseWorkflowInput(implementation.definition, rawInput);
+		const envelope = {
+			kind: "temelj-workflow",
+			version: 1,
+			workflowName: implementation.name,
+			...implementation.version === void 0 ? {} : { workflowVersion: implementation.version },
+			input: encodeCloudflareWorkflowValue(input)
+		};
+		const id = await resolveInstanceId(implementation.name, implementation.version, startOptions);
+		const createdAt = Temporal.Now.instant();
+		let instance;
+		if (startOptions?.idempotencyKey === void 0) instance = await this.#binding.create({
+			...id === void 0 ? {} : { id },
+			params: envelope
+		});
+		else {
+			if (id === void 0) throw new TypeError("Cloudflare idempotent workflow start requires a resolved instance id");
+			instance = (await this.#binding.createBatch([{
+				id,
+				params: envelope
+			}]))[0] ?? await this.#binding.get(id);
+		}
+		return this.#handle(implementation.definition, instance, createdAt);
+	}
+	async #createHandle(workflow, runId) {
+		const implementation = resolveCloudflareWorkflowImplementation(this.#registry, workflow.name, workflow.version);
+		const instance = await this.#binding.get(runId);
+		return this.#handle(implementation.definition, instance, Temporal.Now.instant());
+	}
+	#handle(definition, instance, createdAt) {
+		const status = async () => await instance.status();
+		const record = async () => workflowRunRecord(definition, instance.id, createdAt, await status());
+		return {
+			runId: instance.id,
+			workflowName: definition.name,
+			...definition.version === void 0 ? {} : { workflowVersion: definition.version },
+			getRun: record,
+			status: async () => cloudflareRunStatus((await status()).status),
+			events: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow event history"),
+			timeline: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow timeline"),
+			result: async (options) => await cloudflareWorkflowResult(instance, options, this.#resultPollInterval),
+			getStreamInfo: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			followStream: () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			waitForStream: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			waitForStreamChunk: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			waitForStreamTerminal: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			readStream: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			readStreamPage: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow streams"),
+			reschedule: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow rescheduling"),
+			releaseStaleLease: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow worker leases"),
+			retryFailed: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow manual retries"),
+			markPermanentlyFailed: async () => WorkflowCapabilityError.unsupported("Cloudflare permanent workflow failure"),
+			setMetadata: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow metadata"),
+			setAttributes: async () => WorkflowCapabilityError.unsupported("Cloudflare workflow attributes"),
+			async cancel() {
+				if (!isTerminalCloudflareStatus((await instance.status()).status)) await instance.terminate();
+				return await record();
+			}
+		};
+	}
+};
+function workflowImplementationKey(name, version) {
+	return version === void 0 ? name : `${name}@${version}`;
+}
+function isTerminalCloudflareStatus(status) {
+	return status === "complete" || status === "errored" || status === "terminated";
+}
+async function cloudflareWorkflowResult(instance, options, defaultPollInterval) {
+	const pollInterval = options?.pollInterval === void 0 ? defaultPollInterval : durationMilliseconds(options.pollInterval, "Cloudflare result poll interval");
+	const timeout = options?.timeout === void 0 ? void 0 : durationMilliseconds(options.timeout, "Cloudflare result timeout");
+	const startedAt = Date.now();
+	while (true) {
+		const state = await instance.status();
+		if (state.status === "complete") return decodeCloudflareWorkflowValue(state.output, `Cloudflare Workflow ${instance.id} output`);
+		if (state.status === "errored") {
+			const error = new Error(state.error?.message ?? "Cloudflare Workflow failed");
+			error.name = state.error?.name ?? "Error";
+			throw error;
+		}
+		if (state.status === "terminated") WorkflowRunCanceledError.canceled(instance.id);
+		if (state.status === "unknown") throw new TypeError("Cloudflare Workflow returned an unknown instance status");
+		if (timeout !== void 0 && Date.now() - startedAt >= timeout) WorkflowResultTimeoutError.timedOut(instance.id, Temporal.Duration.from({ milliseconds: timeout }));
+		await new Promise((resolve) => setTimeout(resolve, pollInterval));
+	}
+}
+function workflowRunRecord(definition, runId, createdAt, state) {
+	const now = Temporal.Now.instant();
+	const status = cloudflareRunStatus(state.status);
+	return {
+		id: runId,
+		namespace: "cloudflare",
+		workflowName: definition.name,
+		...definition.version === void 0 ? {} : { workflowVersion: definition.version },
+		status,
+		...state.status === "complete" ? { output: decodeCloudflareWorkflowValue(state.output, `Cloudflare Workflow ${runId} output`) } : {},
+		...state.error === void 0 ? {} : { error: {
+			name: state.error.name,
+			message: state.error.message
+		} },
+		createdAt,
+		updatedAt: now,
+		lastTransitionAt: now,
+		lastTransitionReason: status === "completed" ? "completed" : status === "failed" ? "failed" : status === "canceled" ? "canceled" : status === "waiting" ? "waiting" : status === "running" ? "started" : "created",
+		...status === "completed" || status === "failed" || status === "canceled" ? { finishedAt: now } : {}
+	};
+}
+function cloudflareRunStatus(status) {
+	switch (status) {
+		case "queued": return "pending";
+		case "running": return "running";
+		case "waiting":
+		case "paused":
+		case "waitingForPause": return "waiting";
+		case "complete": return "completed";
+		case "errored": return "failed";
+		case "terminated": return "canceled";
+		case "unknown": throw new TypeError("Cloudflare Workflow returned an unknown instance status");
+	}
+}
+async function resolveInstanceId(workflowName, workflowVersion, options) {
+	if (options?.id !== void 0) {
+		validateInstanceId(options.id);
+		return options.id;
+	}
+	if (options?.idempotencyKey === void 0) return;
+	const input = new TextEncoder().encode(`${workflowName}\0${workflowVersion ?? ""}\0${options.idempotencyKey}`);
+	const id = `temelj-${[...new Uint8Array(await crypto.subtle.digest("SHA-256", input))].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+	validateInstanceId(id);
+	return id;
+}
+function validateInstanceId(id) {
+	if (id.length > 100 || !CLOUDFLARE_INSTANCE_ID_PATTERN.test(id)) throw new TypeError("Cloudflare Workflow instance id must be at most 100 characters and contain only letters, digits, underscores, and hyphens");
+}
+function rejectUnsupportedStartOptions(options) {
+	if (options?.availableAt !== void 0 || options?.deadlineAt !== void 0 || options?.context !== void 0 || options?.parent !== void 0 || options?.workflowVersionResolver !== void 0) WorkflowCapabilityError.unsupported("Cloudflare start context, parent, delayed availability, deadline, or version resolver");
+}
+function durationMilliseconds(duration, label) {
+	const milliseconds = durationTotal(duration);
+	if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) throw new RangeError(`${label} must resolve to non-negative whole milliseconds`);
+	return milliseconds;
+}
+function unsupportedApi(capability) {
+	return new Proxy({}, { get() {
+		return () => WorkflowCapabilityError.unsupported(capability);
+	} });
+}
+//#endregion
+export { createCloudflareWorkflowRuntime };

package/dist/cloudflare/step.d.mts

@@ -0,0 +1,22 @@
+import { WorkflowContext } from "../types/definition.mjs";
+import { WorkflowStepApi } from "../types/step.mjs";
+import { CloudflareNonRetryableErrorConstructor, CloudflareWorkflowStep } from "./types.mjs";
+import { Logger } from "@temelj/log";
+//#region src/cloudflare/step.d.ts
+interface CreateCloudflareWorkflowStepApiOptions {
+  readonly step: CloudflareWorkflowStep;
+  readonly logger?: Logger;
+  readonly nonRetryableError?: CloudflareNonRetryableErrorConstructor;
+}
+/** Creates the Temelj durable command API backed by one Cloudflare Workflow step object. */
+declare function createCloudflareWorkflowStepApi(options: CreateCloudflareWorkflowStepApiOptions): WorkflowStepApi;
+interface CreateCloudflareWorkflowContextOptions<TInput> extends CreateCloudflareWorkflowStepApiOptions {
+  readonly input: TInput;
+  readonly runId: string;
+  readonly workflowName: string;
+  readonly workflowVersion?: string;
+  readonly createdAt: Temporal.Instant;
+}
+declare function createCloudflareWorkflowContext<TInput>(options: CreateCloudflareWorkflowContextOptions<TInput>): WorkflowContext<TInput>;
+//#endregion
+export { CreateCloudflareWorkflowContextOptions, CreateCloudflareWorkflowStepApiOptions, createCloudflareWorkflowContext, createCloudflareWorkflowStepApi };

package/dist/cloudflare/step.mjs

@@ -0,0 +1,160 @@
+import { WorkflowNonRetryableError } from "../errors/failures.mjs";
+import { durationTotal } from "../utility.mjs";
+import { WorkflowCapabilityError } from "../errors/capability.mjs";
+import "../errors/mod.mjs";
+import { resolveWaitForMessageInput } from "../message-options.mjs";
+import { resolveWorkflowRetryConfig } from "../engine/retry.mjs";
+import { decodeCloudflareWorkflowValue, encodeCloudflareWorkflowValue } from "./codec.mjs";
+import { makeCloudflareWorkflowEventType, makeCloudflareWorkflowStepName } from "./name.mjs";
+import { validateStandardSchema } from "@temelj/standard-schema";
+import { createNoopLogger } from "@temelj/log";
+//#region src/cloudflare/step.ts
+const DEFAULT_STEP_RETRY = {
+	maximumAttempts: 10,
+	backoffCoefficient: 2
+};
+const MAXIMUM_CLOUDFLARE_ATTEMPTS = 1e4;
+const MAXIMUM_CLOUDFLARE_DELAY_MILLISECONDS = 31536e6;
+const MAXIMUM_CLOUDFLARE_STEP_TIMEOUT_MILLISECONDS = 18e5;
+const MAXIMUM_EVENT_WAIT_MILLISECONDS = 31536e6;
+/** Creates the Temelj durable command API backed by one Cloudflare Workflow step object. */
+function createCloudflareWorkflowStepApi(options) {
+	const logger = options.logger ?? createNoopLogger();
+	const runTask = async (config, callback) => {
+		const commandName = config.commandId ?? config.name;
+		if (commandName === void 0) throw new TypeError("Cloudflare durable task requires a name or commandId");
+		const retry = resolveWorkflowRetryConfig(config.retry, DEFAULT_STEP_RETRY, "Cloudflare Workflow step retry");
+		const stepName = makeCloudflareWorkflowStepName(commandName);
+		const encoded = await options.step.do(stepName, cloudflareStepConfig(config, retry), async (cloudflareContext) => {
+			const context = workflowStepContext(commandName, retry, cloudflareContext, logger);
+			try {
+				return encodeCloudflareWorkflowValue(await callback(context));
+			} catch (error) {
+				if (error instanceof WorkflowNonRetryableError && options.nonRetryableError !== void 0) throw new options.nonRetryableError(error.message, error.name);
+				throw error;
+			}
+		});
+		return decodeCloudflareWorkflowValue(encoded, `Cloudflare step ${commandName} result`);
+	};
+	const deterministic = {
+		now: async (commandId = "now") => await runTask({ commandId: `deterministic:${commandId}` }, () => Temporal.Now.instant()),
+		random: async (commandId = "random") => await runTask({ commandId: `deterministic:${commandId}` }, () => Math.random()),
+		recordedId: async (commandId = "id") => await runTask({ commandId: `deterministic:${commandId}` }, () => crypto.randomUUID()),
+		id: async (commandId = "id") => await runTask({ commandId: `deterministic:${commandId}` }, () => crypto.randomUUID()),
+		uuid: async (commandId = "uuid") => await runTask({ commandId: `deterministic:${commandId}` }, () => crypto.randomUUID()),
+		bytes: async (commandId, length) => await runTask({ commandId: `deterministic:${commandId}` }, () => {
+			const bytes = new Uint8Array(length);
+			for (let offset = 0; offset < bytes.byteLength; offset += 65536) crypto.getRandomValues(bytes.subarray(offset, offset + 65536));
+			return bytes;
+		})
+	};
+	const waitMessage = (async (messageInput, channelOptions) => {
+		const wait = resolveWaitForMessageInput(messageInput, channelOptions);
+		const timeout = wait.timeout === void 0 ? MAXIMUM_EVENT_WAIT_MILLISECONDS : durationMilliseconds(wait.timeout, "Cloudflare Workflow message timeout");
+		if (timeout < 1e3 || timeout > MAXIMUM_EVENT_WAIT_MILLISECONDS) throw new RangeError("Cloudflare Workflow message timeout must be between 1 second and 365 days");
+		const event = await options.step.waitForEvent(makeCloudflareWorkflowStepName(wait.commandId ?? wait.name ?? wait.messageId), {
+			type: makeCloudflareWorkflowEventType(wait.messageId),
+			timeout
+		});
+		const decoded = decodeCloudflareWorkflowValue(event.payload, `Cloudflare message ${wait.messageId} payload`);
+		if (wait.schema === void 0) return decoded;
+		return await validateStandardSchema(wait.schema, decoded, "Workflow message validation failed");
+	});
+	return {
+		log: logger,
+		task: {
+			run: runTask,
+			async call(definition, ...args) {
+				return await runTask(definition.config, async (context) => {
+					return await definition.handler(...args, context);
+				});
+			},
+			async sleep(commandId, duration) {
+				await options.step.sleep(makeCloudflareWorkflowStepName(commandId), durationMilliseconds(duration, "Cloudflare Workflow sleep"));
+			},
+			async sleepUntil(commandId, timestamp) {
+				await options.step.sleepUntil(makeCloudflareWorkflowStepName(commandId), timestamp.epochMilliseconds);
+			}
+		},
+		workflow: unsupportedFacet("child workflows"),
+		message: {
+			send: async () => WorkflowCapabilityError.unsupported("Cloudflare in-workflow message send"),
+			wait: waitMessage
+		},
+		lock: unsupportedFacet("Cloudflare workflow locks"),
+		runData: unsupportedFacet("Cloudflare workflow run data"),
+		deterministic,
+		stream: unsupportedFacet("Cloudflare workflow streams"),
+		hook: unsupportedFacet("Cloudflare workflow hooks")
+	};
+}
+function createCloudflareWorkflowContext(options) {
+	const logger = options.logger ?? createNoopLogger();
+	const step = createCloudflareWorkflowStepApi({
+		...options,
+		logger
+	});
+	return {
+		input: options.input,
+		step,
+		deterministic: step.deterministic,
+		log: logger,
+		run: {
+			id: options.runId,
+			workflowName: options.workflowName,
+			...options.workflowVersion === void 0 ? {} : { workflowVersion: options.workflowVersion },
+			createdAt: options.createdAt
+		},
+		signal: new AbortController().signal,
+		version: options.workflowVersion
+	};
+}
+function cloudflareStepConfig(config, retry) {
+	if (retry.maximumAttempts === 0 || retry.maximumAttempts > MAXIMUM_CLOUDFLARE_ATTEMPTS) throw new RangeError(`Cloudflare Workflow steps support at most ${MAXIMUM_CLOUDFLARE_ATTEMPTS} attempts`);
+	const initialDelay = retry.initialInterval === void 0 ? 0 : durationMilliseconds(retry.initialInterval, "Cloudflare Workflow retry interval");
+	const maximumDelay = retry.maximumInterval === void 0 ? void 0 : durationMilliseconds(retry.maximumInterval, "Cloudflare Workflow maximum retry interval");
+	assertMaximumDuration(initialDelay, MAXIMUM_CLOUDFLARE_DELAY_MILLISECONDS, "Cloudflare Workflow retry interval");
+	if (maximumDelay !== void 0) assertMaximumDuration(maximumDelay, MAXIMUM_CLOUDFLARE_DELAY_MILLISECONDS, "Cloudflare Workflow maximum retry interval");
+	const timeout = config.timeout === void 0 ? void 0 : durationMilliseconds(config.timeout, "Cloudflare Workflow step timeout");
+	if (timeout !== void 0) assertMaximumDuration(timeout, MAXIMUM_CLOUDFLARE_STEP_TIMEOUT_MILLISECONDS, "Cloudflare Workflow step timeout");
+	return {
+		retries: {
+			limit: retry.maximumAttempts,
+			delay: ({ ctx }) => retryDelay(initialDelay, retry, ctx.attempt, maximumDelay)
+		},
+		...timeout === void 0 ? {} : { timeout }
+	};
+}
+function retryDelay(initialDelay, retry, attempt, maximumDelay) {
+	const delay = initialDelay * retry.backoffCoefficient ** Math.max(0, attempt - 1);
+	return Math.min(delay, maximumDelay ?? MAXIMUM_CLOUDFLARE_DELAY_MILLISECONDS);
+}
+function workflowStepContext(commandName, retry, context, logger) {
+	return {
+		step: {
+			id: `${commandName}:${context.step.count}`,
+			name: commandName,
+			count: context.step.count,
+			kind: "run"
+		},
+		attempt: context.attempt,
+		config: retry,
+		signal: new AbortController().signal,
+		log: logger
+	};
+}
+function durationMilliseconds(duration, label) {
+	const milliseconds = durationTotal(duration);
+	if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) throw new RangeError(`${label} must resolve to non-negative whole milliseconds`);
+	return milliseconds;
+}
+function assertMaximumDuration(value, maximum, label) {
+	if (value > maximum) throw new RangeError(`${label} must not exceed ${maximum} milliseconds`);
+}
+function unsupportedFacet(capability) {
+	return new Proxy({}, { get() {
+		return () => WorkflowCapabilityError.unsupported(capability);
+	} });
+}
+//#endregion
+export { createCloudflareWorkflowContext, createCloudflareWorkflowStepApi };

package/dist/cloudflare/types.d.mts

@@ -0,0 +1,87 @@
+//#region src/cloudflare/types.d.ts
+/** Minimal Cloudflare Workflow binding used by the Temelj adapter. */
+interface CloudflareWorkflowBinding {
+  create(options?: CloudflareWorkflowInstanceCreateOptions): Promise<CloudflareWorkflowInstance>;
+  createBatch(items: readonly CloudflareWorkflowInstanceCreateOptions[]): Promise<readonly CloudflareWorkflowInstance[]>;
+  get(id: string): Promise<CloudflareWorkflowInstance>;
+}
+/** Parameters accepted when creating a Cloudflare Workflow instance. */
+interface CloudflareWorkflowInstanceCreateOptions {
+  readonly id?: string;
+  readonly params?: unknown;
+}
+/** Minimal Cloudflare Workflow instance used by the Temelj adapter. */
+interface CloudflareWorkflowInstance {
+  readonly id: string;
+  status(): Promise<CloudflareWorkflowInstanceStatus>;
+  terminate(options?: {
+    readonly rollback?: boolean;
+  }): Promise<void>;
+  sendEvent(options: {
+    readonly type: string;
+    readonly payload?: unknown;
+  }): Promise<void>;
+}
+/** Status returned by a Cloudflare Workflow instance binding. */
+interface CloudflareWorkflowInstanceStatus {
+  readonly status: "queued" | "running" | "paused" | "errored" | "terminated" | "complete" | "waiting" | "waitingForPause" | "unknown";
+  readonly error?: {
+    readonly name: string;
+    readonly message: string;
+  };
+  readonly output?: unknown;
+}
+/** Minimal Cloudflare durable step context. */
+interface CloudflareWorkflowStepContext {
+  readonly step: {
+    readonly name: string;
+    readonly count: number;
+  };
+  readonly attempt: number;
+  readonly config: CloudflareWorkflowStepConfig;
+}
+/** Cloudflare retry and timeout configuration used by a durable step. */
+interface CloudflareWorkflowStepConfig {
+  readonly retries?: {
+    readonly limit: number;
+    readonly delay: number | ((input: {
+      readonly ctx: CloudflareWorkflowStepContext;
+      readonly error: Error;
+    }) => number | Promise<number>);
+    readonly backoff?: "constant" | "linear" | "exponential";
+  };
+  readonly timeout?: number;
+}
+/** Event returned by Cloudflare after a matching `waitForEvent` call. */
+interface CloudflareWorkflowStepEvent<TPayload = unknown> {
+  readonly payload: TPayload;
+  readonly timestamp: Date;
+  readonly type: string;
+}
+/** Minimal Cloudflare durable step API used by the Temelj adapter. */
+interface CloudflareWorkflowStep {
+  do<T>(name: string, config: CloudflareWorkflowStepConfig, callback: (context: CloudflareWorkflowStepContext) => T | Promise<T>): Promise<T>;
+  sleep(name: string, duration: number): Promise<void>;
+  sleepUntil(name: string, timestamp: number): Promise<void>;
+  waitForEvent<T>(name: string, options: {
+    readonly type: string;
+    readonly timeout: string | number;
+  }): Promise<CloudflareWorkflowStepEvent<T>>;
+}
+/** Event delivered to the generic Temelj Cloudflare entrypoint. */
+interface CloudflareWorkflowEvent<TPayload = unknown> {
+  readonly payload: TPayload;
+  readonly timestamp: Date;
+  readonly instanceId: string;
+  readonly workflowName: string;
+  readonly schedule?: {
+    readonly cron: string;
+    readonly scheduledTime: number;
+  };
+}
+/** Constructor used to convert Temelj non-retryable errors for Cloudflare. */
+interface CloudflareNonRetryableErrorConstructor {
+  new (message: string, name?: string): Error;
+}
+//#endregion
+export { CloudflareNonRetryableErrorConstructor, CloudflareWorkflowBinding, CloudflareWorkflowEvent, CloudflareWorkflowInstance, CloudflareWorkflowInstanceCreateOptions, CloudflareWorkflowInstanceStatus, CloudflareWorkflowStep, CloudflareWorkflowStepConfig, CloudflareWorkflowStepContext, CloudflareWorkflowStepEvent };

package/dist/cloudflare/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/engine/inspection-api.mjs

@@ -42,7 +42,8 @@ function createWorkflowEngineInspectionApi(store, now) {
 			});
 		},
 		async getTimeline(runId) {
-			return createTimeline(await getRequiredRun(store, runId), await store.getEvents(runId));
+			const run = await getRequiredRun(store, runId);
+			return createTimeline(run, await store.getEvents(runId));
 		},
 		async listStepAttempts(runId, options) {
 			await getRequiredRun(store, runId);

package/dist/engine/inspection.mjs

@@ -81,22 +81,24 @@ async function getWorkflowRunSummary(options) {
 	const { store, now, filters } = options;
 	const cleanupCutoff = workflowSummaryCleanupCutoff(filters);
 	const runs = await store.listRuns(filters);
-	return summarizeWorkflowRuns({
+	const summaryInputs = {
 		runs,
 		now,
 		cleanupCutoff,
 		...await getWorkflowRunSummaryActivityInputs(store, runs)
-	});
+	};
+	return summarizeWorkflowRuns(summaryInputs);
 }
 async function getWorkflowRecoverySummary(options) {
 	const { store, now, filters } = options;
 	const runs = await store.listRuns(filters);
+	const activeRuns = runs.filter((run) => {
+		return workflowRunCanHaveActiveWork(run);
+	});
 	return summarizeWorkflowRecovery({
 		runs,
 		now,
-		inputs: await getWorkflowRecoverySummaryInputs(store, runs.filter((run) => {
-			return workflowRunCanHaveActiveWork(run);
-		}))
+		inputs: await getWorkflowRecoverySummaryInputs(store, activeRuns)
 	});
 }
 async function getWorkflowRecoverySummaryInputs(store, activeRuns) {

package/dist/engine/message.mjs

@@ -60,18 +60,20 @@ function createWorkflowStepMessageApi(environment) {
 				payload: toOptionalPersistedValue(options.payload, "message payload", limits),
 				idempotencyKey
 			};
-			if (started === void 0) await appendDurableStepStartedEvent(environment, {
-				kind: "message_send_started",
-				timestamp: now(),
-				stepId: identity.id,
-				stepName: identity.name,
-				count: identity.count,
-				targetRunId: nextMessageSend.targetRunId,
-				messageId: nextMessageSend.messageId,
-				payload: nextMessageSend.payload,
-				...nextMessageSend.idempotencyKey === void 0 ? {} : { idempotencyKey: nextMessageSend.idempotencyKey }
-			});
-			else requireMessageSendReplayMatches(identity, started, started, nextMessageSend);
+			if (started === void 0) {
+				const timestamp = now();
+				await appendDurableStepStartedEvent(environment, {
+					kind: "message_send_started",
+					timestamp,
+					stepId: identity.id,
+					stepName: identity.name,
+					count: identity.count,
+					targetRunId: nextMessageSend.targetRunId,
+					messageId: nextMessageSend.messageId,
+					payload: nextMessageSend.payload,
+					...nextMessageSend.idempotencyKey === void 0 ? {} : { idempotencyKey: nextMessageSend.idempotencyKey }
+				});
+			} else requireMessageSendReplayMatches(identity, started, started, nextMessageSend);
 			try {
 				await sendWorkflowMessage(store, targetRunId, {
 					...options,
@@ -338,7 +340,8 @@ function messageWaitAvailableAt(now, timeoutAt, deadlineAt) {
 async function wakeRunForMessageEvent(store, runId, messageEvent) {
 	const run = await store.getRun(runId);
 	if (run === void 0 || run.status !== "waiting") return;
-	const activeWaits = new WorkflowHistory(await store.getEvents(runId)).activeMessageWaitStepIds(messageEvent.messageId);
+	const events = await store.getEvents(runId);
+	const activeWaits = new WorkflowHistory(events).activeMessageWaitStepIds(messageEvent.messageId);
 	if (!(messageEvent.waiterStepIds === void 0 ? activeWaits.length > 0 : activeWaits.some((stepId) => messageEvent.waiterStepIds?.includes(stepId)))) return;
 	await store.updateRunIfCurrent(run, {
 		...run,

package/dist/engine/observation.mjs

@@ -181,9 +181,7 @@ function emitRunEvent(emit, run, previousRun) {
 		case "deadline":
 			emit("workflow:run-failed", payload);
 			break;
-		case "canceled":
-			emit("workflow:run-canceled", payload);
-			break;
+		case "canceled": emit("workflow:run-canceled", payload);
 	}
 }
 function makeRunObservationEvent(run, previousRun) {

package/dist/engine/run-data.mjs

@@ -52,7 +52,8 @@ async function setWorkflowRunAttributes(environment, commandId, attributes) {
 	const recorded = history.attributesSet(identity.id);
 	if (recorded !== void 0) {
 		requireAttributesReplayMatches(identity, recorded, normalized);
-		const updated = await patchCurrentExecutionRunAttributes(store, executionOwner, workflowAttributePatchFromEvent(recorded), recorded.timestamp);
+		const recordedPatch = workflowAttributePatchFromEvent(recorded);
+		const updated = await patchCurrentExecutionRunAttributes(store, executionOwner, recordedPatch, recorded.timestamp);
 		if (updated === void 0) WorkflowStaleExecutionError.stale(executionOwner.id);
 		Object.assign(executionOwner, updated);
 		return;

package/dist/engine/run-service.mjs

@@ -20,7 +20,8 @@ async function rerunWorkflowRun(service, startWorkflow, runId, rerunOptions) {
 }
 async function resolveRerunWorkflowDefinition(sourceRun, options) {
 	const workflowName = options?.workflowName ?? sourceRun.workflowName;
-	return defineWorkflowFromName(workflowName, await resolveWorkflowVersion(workflowName, options !== void 0 && "workflowVersion" in options ? options.workflowVersion : sourceRun.workflowVersion, options?.workflowVersionResolver));
+	const resolvedWorkflowVersion = await resolveWorkflowVersion(workflowName, options !== void 0 && "workflowVersion" in options ? options.workflowVersion : sourceRun.workflowVersion, options?.workflowVersionResolver);
+	return defineWorkflowFromName(workflowName, resolvedWorkflowVersion);
 }
 async function rescheduleWorkflowRun(service, lifecycle, runId, rescheduleOptions) {
 	const options = rescheduleOptions;

package/dist/engine/start-api.mjs

@@ -28,7 +28,8 @@ function resolveScheduleNextOptions(options, now) {
 function createWorkflowEngineStartApi(service) {
 	return {
 		async startWorkflow(workflow, input, startOptions) {
-			const resolvedDefinition = await resolveWorkflowStartSpec(defineWorkflowFromTarget(workflow), startOptions);
+			const definition = defineWorkflowFromTarget(workflow);
+			const resolvedDefinition = await resolveWorkflowStartSpec(definition, startOptions);
 			const parsedInput = await parseWorkflowInput(resolvedDefinition, input);
 			const idempotencyKey = startOptions?.idempotencyKey;
 			const explicitRunId = startOptions?.id;

package/dist/engine/state.mjs

@@ -376,7 +376,8 @@ async function parentHasActiveChildWorkflowAttemptForRun(store, parentRunId, chi
 }
 async function parentHasActiveChildWorkflowEventForAttempt(store, parentRunId, attempt) {
 	if (attempt.childRunId === void 0) return false;
-	const lifecycle = new WorkflowHistory(await store.getEvents(parentRunId)).childWorkflowLifecycleForAttempt(attempt);
+	const events = await store.getEvents(parentRunId);
+	const lifecycle = new WorkflowHistory(events).childWorkflowLifecycleForAttempt(attempt);
 	if (lifecycle.started === void 0) return false;
 	if (!isPositiveSafeInteger(lifecycle.started.attempt)) return false;
 	return !lifecycle.hasTerminalAfterStarted;

package/dist/engine/stream.d.mts

@@ -6,6 +6,7 @@ import { WorkflowStepIdentity } from "../types/run.mjs";
 import { EventRecord } from "../types/events.mjs";
 import { WorkflowEventHistoryWatcher, WorkflowEventReader, WorkflowRunReaderRepository } from "../types/store.mjs";
 import { WorkflowExecutionEnvironment } from "../types/engine.mjs";
+import "temporal-polyfill/global";
 //#region src/engine/stream.d.ts
 interface WorkflowStreamReader<TChunk> {
   (options?: ReadStreamOptions): Promise<StreamState<TChunk>>;