@temelj/workflow 0.0.0-alpha.1

package/dist/pagination.mjs

@@ -0,0 +1,73 @@
+import { WorkflowOptionsError } from "./errors/base.mjs";
+import "./errors/mod.mjs";
+import { workflowCursorPayloadSchema } from "./types/pagination.mjs";
+import { decodeBase64UrlString, encodeBase64UrlString } from "@temelj/string";
+//#region src/pagination.ts
+const CURSOR_PREFIX = "wf-page:";
+const DEFAULT_PAGE_LIMIT = 100;
+function pageItems(items, options, label, cursorKey) {
+	const pageOptions = options ?? {};
+	const limit = pageOptions.limit ?? DEFAULT_PAGE_LIMIT;
+	const cursor = decodeCursor(pageOptions.cursor, label);
+	const offset = cursor === void 0 ? 0 : items.findIndex((item, index) => compareCursorKeys(cursorKey(item, index), cursor) > 0);
+	const start = offset === -1 ? items.length : offset;
+	const pageItems = items.slice(start, start + limit);
+	const nextOffset = start + pageItems.length;
+	const hasMore = nextOffset < items.length;
+	const last = pageItems.at(-1);
+	return {
+		items: pageItems,
+		...hasMore && last !== void 0 ? { nextCursor: encodeCursor({ key: [...cursorKey(last, nextOffset - 1)] }) } : {},
+		hasMore
+	};
+}
+function makeWorkflowRunCursorKey(run) {
+	return [run.createdAt.epochMilliseconds, run.id];
+}
+function makeWorkflowEventCursorKey(_event, index) {
+	return [index];
+}
+function makeWorkflowStepAttemptCursorKey(attempt) {
+	return [
+		attempt.startedAt.epochMilliseconds,
+		attempt.stepId,
+		attempt.attempt
+	];
+}
+function makeScheduleCursorKey(schedule) {
+	return [
+		schedule.nextFireAt.epochMilliseconds,
+		schedule.createdAt.epochMilliseconds,
+		schedule.id
+	];
+}
+function makeStreamChunkCursorKey(chunk) {
+	return [chunk.index];
+}
+function encodeCursor(payload) {
+	return `${CURSOR_PREFIX}${encodeBase64UrlString(JSON.stringify(payload))}`;
+}
+function decodeCursor(value, label) {
+	if (value === void 0) return;
+	if (!value.startsWith(CURSOR_PREFIX)) WorkflowOptionsError.cursorInvalid(label);
+	try {
+		const parsed = workflowCursorPayloadSchema.safeParse(JSON.parse(decodeBase64UrlString(value.slice(8))));
+		if (!parsed.success) WorkflowOptionsError.cursorInvalid(label);
+		return parsed.data.key;
+	} catch (error) {
+		if (!(error instanceof WorkflowOptionsError)) WorkflowOptionsError.cursorInvalid(label);
+		throw error;
+	}
+}
+function compareCursorKeys(left, right) {
+	const length = Math.max(left.length, right.length);
+	for (let index = 0; index < length; index++) {
+		const leftPart = left[index];
+		const rightPart = right[index];
+		const compared = leftPart === rightPart ? 0 : leftPart === void 0 ? -1 : rightPart === void 0 ? 1 : typeof leftPart === "number" && Number.isFinite(leftPart) && typeof rightPart === "number" && Number.isFinite(rightPart) ? leftPart - rightPart : String(leftPart).localeCompare(String(rightPart));
+		if (compared !== 0) return compared;
+	}
+	return 0;
+}
+//#endregion
+export { makeScheduleCursorKey, makeStreamChunkCursorKey, makeWorkflowEventCursorKey, makeWorkflowRunCursorKey, makeWorkflowStepAttemptCursorKey, pageItems };

package/dist/registry.d.mts

@@ -0,0 +1,20 @@
+import { Registry as Registry$1, WorkflowDefinition, WorkflowHandler, WorkflowImplementation } from "./types/definition.mjs";
+//#region src/registry.d.ts
+/** In-memory workflow registry implementation. */
+declare class Registry implements Registry$1 {
+  private readonly implementations;
+  /** Defines and registers a workflow implementation. */
+  readonly implementWorkflow: <TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>) => WorkflowImplementation<TInput, TOutput, TRawInput>;
+  /** Registers a workflow implementation. */
+  readonly register: <TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>) => void;
+  /** Returns the workflow implementation registered for a definition. */
+  readonly get: <TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>) => WorkflowImplementation<TInput, TOutput, TRawInput> | undefined;
+  /** Returns the workflow implementation registered for a name and optional version. */
+  readonly getByName: (name: string, version?: string) => WorkflowImplementation<unknown, unknown> | undefined;
+  /** Returns the last registered workflow implementation for a name. */
+  readonly latest: (name: string) => WorkflowImplementation<unknown, unknown> | undefined;
+  /** Returns all registered workflow implementations in registration order. */
+  readonly entries: () => readonly WorkflowImplementation<unknown, unknown>[];
+}
+//#endregion
+export { Registry };

package/dist/registry.mjs

@@ -0,0 +1,48 @@
+import { WorkflowDefinitionError } from "./errors/definition.mjs";
+import "./errors/mod.mjs";
+//#region src/registry.ts
+/** In-memory workflow registry implementation. */
+var Registry = class {
+	implementations = /* @__PURE__ */ new Map();
+	/** Defines and registers a workflow implementation. */
+	implementWorkflow = (definition, handler) => {
+		const implementation = {
+			kind: "implementation",
+			definition,
+			config: definition.config,
+			name: definition.name,
+			...definition.version === void 0 ? {} : { version: definition.version },
+			handler
+		};
+		this.register(implementation);
+		return implementation;
+	};
+	/** Registers a workflow implementation. */
+	register = (implementation) => {
+		const key = makeWorkflowImplementationKey(implementation.name, implementation.version);
+		if (this.implementations.has(key)) WorkflowDefinitionError.implementationAlreadyRegistered(key);
+		this.implementations.set(key, implementation);
+	};
+	/** Returns the workflow implementation registered for a definition. */
+	get = (definition) => {
+		return this.implementations.get(makeWorkflowImplementationKey(definition.name, definition.version));
+	};
+	/** Returns the workflow implementation registered for a name and optional version. */
+	getByName = (name, version) => this.implementations.get(makeWorkflowImplementationKey(name, version));
+	/** Returns the last registered workflow implementation for a name. */
+	latest = (name) => {
+		const implementations = this.entries();
+		for (let index = implementations.length - 1; index >= 0; index--) {
+			const implementation = implementations[index];
+			if (implementation.name === name) return implementation;
+		}
+	};
+	/** Returns all registered workflow implementations in registration order. */
+	entries = () => [...this.implementations.values()];
+};
+/** Builds the internal registry key for a workflow implementation. */
+function makeWorkflowImplementationKey(name, version) {
+	return version === void 0 ? name : `${name}@${version}`;
+}
+//#endregion
+export { Registry };

package/dist/rolldown.d.mts

@@ -0,0 +1,7 @@
+import { WorkflowPluginOptions } from "./types/vite.mjs";
+import { workflowPlugin } from "./vite/plugin.mjs";
+//#region src/rolldown.d.ts
+/** Creates the Rolldown plugin that compiles workflow and step directives. */
+declare const workflow: (options?: WorkflowPluginOptions | undefined) => import("rolldown").Plugin<any>;
+//#endregion
+export { type WorkflowPluginOptions, workflow, workflowPlugin };

package/dist/rolldown.mjs

@@ -0,0 +1,6 @@
+import { workflowPlugin } from "./vite/plugin.mjs";
+//#region src/rolldown.ts
+/** Creates the Rolldown plugin that compiles workflow and step directives. */
+const workflow = workflowPlugin.rolldown;
+//#endregion
+export { workflow, workflowPlugin };

package/dist/rollup.d.mts

@@ -0,0 +1,7 @@
+import { WorkflowPluginOptions } from "./types/vite.mjs";
+import { workflowPlugin } from "./vite/plugin.mjs";
+//#region src/rollup.d.ts
+/** Creates the Rollup plugin that compiles workflow and step directives. */
+declare const workflow: (options?: WorkflowPluginOptions | undefined) => import("rollup").Plugin<any>;
+//#endregion
+export { type WorkflowPluginOptions, workflow, workflowPlugin };

package/dist/rollup.mjs

@@ -0,0 +1,6 @@
+import { workflowPlugin } from "./vite/plugin.mjs";
+//#region src/rollup.ts
+/** Creates the Rollup plugin that compiles workflow and step directives. */
+const workflow = workflowPlugin.rollup;
+//#endregion
+export { workflow, workflowPlugin };

package/dist/rspack.d.mts

@@ -0,0 +1,7 @@
+import { WorkflowPluginOptions } from "./types/vite.mjs";
+import { workflowPlugin } from "./vite/plugin.mjs";
+//#region src/rspack.d.ts
+/** Creates the Rspack plugin that compiles workflow and step directives. */
+declare const workflow: (options?: WorkflowPluginOptions | undefined) => import("unplugin").RspackPluginInstance;
+//#endregion
+export { type WorkflowPluginOptions, workflow, workflowPlugin };

package/dist/rspack.mjs

@@ -0,0 +1,6 @@
+import { workflowPlugin } from "./vite/plugin.mjs";
+//#region src/rspack.ts
+/** Creates the Rspack plugin that compiles workflow and step directives. */
+const workflow = workflowPlugin.rspack;
+//#endregion
+export { workflow, workflowPlugin };

package/dist/runtime.d.mts

@@ -0,0 +1,34 @@
+import { RunId } from "./types/run-id.mjs";
+import { WorkflowDefinition, WorkflowHandler, WorkflowImplementation } from "./types/definition.mjs";
+import "./types/run.mjs";
+import { WorkflowRunArguments, WorkflowStartOptions } from "./types/run-options.mjs";
+import { CompiledWorkflowFunction, WorkflowClientWorkersApi, WorkflowRunHandle } from "./types/client.mjs";
+import { CreateWorkflowRuntimeOptions, WorkflowRuntime as WorkflowRuntime$1, WorkflowRuntimeLocksApi, WorkflowRuntimeRunsApi, WorkflowRuntimeSchedulesApi } from "./types/runtime.mjs";
+//#region src/runtime.d.ts
+/** Creates a workflow runtime backed by a workflow client. */
+declare function createWorkflowRuntime(options?: CreateWorkflowRuntimeOptions): WorkflowRuntime$1;
+/** Workflow runtime implementation backed by a workflow client. */
+declare class WorkflowRuntime implements WorkflowRuntime$1 {
+  #private;
+  readonly runs: WorkflowRuntimeRunsApi;
+  readonly schedules: WorkflowRuntimeSchedulesApi;
+  readonly locks: WorkflowRuntimeLocksApi;
+  readonly workers: WorkflowClientWorkersApi;
+  constructor(options?: CreateWorkflowRuntimeOptions);
+  close(): Promise<void>;
+  implementWorkflow<TInput, TOutput, TRawInput = TInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, handler: WorkflowHandler<TInput, TOutput>): WorkflowImplementation<TInput, TOutput, TRawInput>;
+  register<TInput, TOutput, TRawInput = TInput>(implementation: WorkflowImplementation<TInput, TOutput, TRawInput>): void;
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowDefinition<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+  start<TInput, TOutput, TRawInput = TInput>(workflow: WorkflowImplementation<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+  start<TArgs extends readonly unknown[], TOutput>(workflow: CompiledWorkflowFunction<TArgs, TOutput>, ...args: TArgs): Promise<WorkflowRunHandle<Awaited<TOutput>>>;
+}
+/** Starts a workflow through an explicit runtime and returns a client run handle. */
+declare function startWorkflowRuntimeRun<TInput, TOutput, TRawInput = TInput>(runtime: WorkflowRuntime, workflow: WorkflowImplementation<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+/** Starts a workflow through an explicit runtime and returns a client run handle. */
+declare function startWorkflowRuntimeRun<TInput, TOutput, TRawInput = TInput>(runtime: WorkflowRuntime, workflow: WorkflowDefinition<TInput, TOutput, TRawInput>, ...args: WorkflowRunArguments<TRawInput, WorkflowStartOptions>): Promise<WorkflowRunHandle<TOutput>>;
+/** Starts a workflow through an explicit runtime and returns a client run handle. */
+declare function startWorkflowRuntimeRun<TArgs extends readonly unknown[], TOutput>(runtime: WorkflowRuntime, workflow: CompiledWorkflowFunction<TArgs, TOutput>, ...args: TArgs): Promise<WorkflowRunHandle<Awaited<TOutput>>>;
+/** Returns a typed handle for an existing run through an explicit runtime. */
+declare function getWorkflowRuntimeRun<TOutput = unknown>(runtime: WorkflowRuntime, runId: RunId): Promise<WorkflowRunHandle<TOutput>>;
+//#endregion
+export { WorkflowRuntime, createWorkflowRuntime, getWorkflowRuntimeRun, startWorkflowRuntimeRun };

package/dist/runtime.mjs

@@ -0,0 +1,194 @@
+import { WorkflowStateError } from "./errors/base.mjs";
+import { WorkflowResultTimeoutError, WorkflowRunCanceledError, WorkflowRunNotFoundError } from "./errors/run.mjs";
+import { durationTotal } from "./utility.mjs";
+import { WorkflowDefinitionError } from "./errors/definition.mjs";
+import { WorkflowRuntimeError } from "./errors/runtime.mjs";
+import "./errors/mod.mjs";
+import { getCompiledWorkflowDefinition } from "./compiled-function.mjs";
+import { workflowErrorFromRecord } from "./errors/records.mjs";
+import { durationBetween } from "./temporal.mjs";
+import { nonNegativeTimerDelay, sleep } from "./timer.mjs";
+import { Registry } from "./registry.mjs";
+import { createWorkflowClient } from "./client/create.mjs";
+import { parseWorkflowRuntime } from "./types/runtime.mjs";
+//#region src/runtime.ts
+const DEFAULT_RESULT_POLL_INTERVAL = Temporal.Duration.from({ milliseconds: 100 });
+const WORKFLOW_RUNTIME_CLOCKS = /* @__PURE__ */ new WeakMap();
+const WORKFLOW_RUNTIME_CLIENTS = /* @__PURE__ */ new WeakMap();
+const WORKFLOW_RUNTIME_REGISTRIES = /* @__PURE__ */ new WeakMap();
+/** Creates a workflow runtime backed by a workflow client. */
+function createWorkflowRuntime(options = {}) {
+	return new WorkflowRuntime(options);
+}
+/** Workflow runtime implementation backed by a workflow client. */
+var WorkflowRuntime = class {
+	runs;
+	schedules;
+	locks;
+	workers;
+	#client;
+	#registry;
+	constructor(options = {}) {
+		const now = options.now ?? Temporal.Now.instant;
+		this.#registry = options.registry ?? new Registry();
+		this.#client = createWorkflowClient({
+			...options,
+			registry: this.#registry,
+			now
+		});
+		this.runs = {
+			getHandle: async (runId) => await getWorkflowRuntimeRun(this, runId),
+			list: async (options) => await this.#client.runs.list(options)
+		};
+		this.schedules = this.#client.schedules;
+		this.locks = this.#client.locks;
+		this.workers = this.#client.workers;
+		WORKFLOW_RUNTIME_CLOCKS.set(this, now);
+		WORKFLOW_RUNTIME_CLIENTS.set(this, this.#client);
+		WORKFLOW_RUNTIME_REGISTRIES.set(this, this.#registry);
+	}
+	async close() {
+		await this.#client.close();
+	}
+	implementWorkflow(definition, handler) {
+		return this.#registry.implementWorkflow(definition, handler);
+	}
+	register(implementation) {
+		this.#registry.register(implementation);
+	}
+	async start(workflow, ...args) {
+		return await startWorkflowRuntimeRunUnknown(this, workflow, ...args);
+	}
+};
+/** Starts a workflow through an explicit runtime and returns a client run handle. */
+async function startWorkflowRuntimeRun(runtime, workflow, ...args) {
+	return await startWorkflowRuntimeRunUnknown(runtime, workflow, ...args);
+}
+async function startWorkflowRuntimeRunUnknown(runtime, workflow, ...args) {
+	parseWorkflowRuntime(runtime);
+	const client = getWorkflowRuntimeClient(runtime);
+	const registry = getWorkflowRuntimeRegistry(runtime);
+	if (typeof workflow === "function") {
+		const definition = getCompiledWorkflowDefinition(workflow);
+		if (definition === void 0) WorkflowDefinitionError.compiledMetadataMissing();
+		ensureWorkflowRegistered(registry, definition);
+		return await client.runs.start(definition.definition, args);
+	}
+	const target = workflow;
+	if (target.kind === "implementation") {
+		ensureWorkflowRegistered(registry, target);
+		return await client.runs.start(target.definition, args[0], args[1]);
+	}
+	return await client.runs.start(target, args[0], args[1]);
+}
+/** Returns a typed handle for an existing run through an explicit runtime. */
+async function getWorkflowRuntimeRun(runtime, runId) {
+	parseWorkflowRuntime(runtime);
+	const run = await getWorkflowRuntimeClient(runtime).runs.get(runId);
+	if (run === void 0) WorkflowRunNotFoundError.notFound(runId);
+	return createStoredRunHandle(runtime, run);
+}
+function createStoredRunHandle(runtime, initialRun) {
+	const runId = initialRun.id;
+	const now = WORKFLOW_RUNTIME_CLOCKS.get(runtime) ?? Temporal.Now.instant;
+	const client = getWorkflowRuntimeClient(runtime);
+	const getRun = async () => {
+		const run = await client.runs.get(runId);
+		if (run === void 0) WorkflowRunNotFoundError.notFound(runId);
+		return run;
+	};
+	return {
+		runId,
+		workflowName: initialRun.workflowName,
+		...initialRun.workflowVersion === void 0 ? {} : { workflowVersion: initialRun.workflowVersion },
+		getRun,
+		async status() {
+			return (await getRun()).status;
+		},
+		async events() {
+			return await client.runs.events(runId);
+		},
+		async timeline() {
+			return await client.runs.timeline(runId);
+		},
+		async result(options) {
+			const pollInterval = nonNegativeTimerDelay(options?.pollInterval ?? DEFAULT_RESULT_POLL_INTERVAL, "Workflow result pollInterval").clampedDelay;
+			const timeout = options?.timeout;
+			const deadlineAt = timeout === void 0 ? void 0 : now().add(timeout);
+			while (true) {
+				const run = await client.runs.get(runId);
+				if (run === void 0) WorkflowRunNotFoundError.notFound(runId);
+				if (run.status === "completed") return run.output;
+				if (run.status === "failed") {
+					if (run.error === void 0) WorkflowStateError.failedRunMissingError(runId);
+					throw workflowErrorFromRecord(run.error);
+				}
+				if (run.status === "canceled") WorkflowRunCanceledError.canceled(runId);
+				let sleepDelay = pollInterval;
+				if (timeout !== void 0 && deadlineAt !== void 0) {
+					const remainingDelay = durationTotal(durationBetween(now(), deadlineAt));
+					if (remainingDelay <= 0) WorkflowResultTimeoutError.timedOut(runId, timeout);
+					sleepDelay = Math.min(sleepDelay, remainingDelay);
+				}
+				await sleep(sleepDelay);
+			}
+		},
+		async getStreamInfo(streamIdOrName) {
+			return await client.streams.getInfo(runId, streamIdOrName);
+		},
+		followStream(streamIdOrName, options) {
+			return client.streams.follow(runId, streamIdOrName, options);
+		},
+		async waitForStream(streamIdOrName, options) {
+			return await client.streams.wait(runId, streamIdOrName, options);
+		},
+		async waitForStreamChunk(streamIdOrName, afterIndex, options) {
+			return await client.streams.waitForChunk(runId, streamIdOrName, afterIndex, options);
+		},
+		async waitForStreamTerminal(streamIdOrName, options) {
+			return await client.streams.waitForTerminal(runId, streamIdOrName, options);
+		},
+		async readStream(streamIdOrName, options) {
+			return await client.streams.read(runId, streamIdOrName, options);
+		},
+		async readStreamPage(streamIdOrName, options) {
+			return await client.streams.readPage(runId, streamIdOrName, options);
+		},
+		async reschedule(options) {
+			return await client.admin.reschedule(runId, options);
+		},
+		async releaseStaleLease(options) {
+			return await client.admin.releaseStaleLease(runId, options);
+		},
+		async retryFailed(options) {
+			return await client.admin.retryFailed(runId, options);
+		},
+		async markPermanentlyFailed(options) {
+			return await client.admin.markPermanentlyFailed(runId, options);
+		},
+		async setMetadata(metadata) {
+			return await client.admin.updateMetadata(runId, metadata);
+		},
+		async setAttributes(attributes) {
+			return await client.admin.setAttributes(runId, attributes);
+		},
+		async cancel() {
+			return await client.admin.cancel(runId);
+		}
+	};
+}
+function getWorkflowRuntimeClient(runtime) {
+	const client = WORKFLOW_RUNTIME_CLIENTS.get(runtime);
+	if (client === void 0) WorkflowRuntimeError.clientMissing();
+	return client;
+}
+function getWorkflowRuntimeRegistry(runtime) {
+	const registry = WORKFLOW_RUNTIME_REGISTRIES.get(runtime);
+	if (registry === void 0) WorkflowRuntimeError.registryMissing();
+	return registry;
+}
+function ensureWorkflowRegistered(registry, implementation) {
+	if (registry.get(implementation.definition) === void 0) registry.register(implementation);
+}
+//#endregion
+export { WorkflowRuntime, createWorkflowRuntime, getWorkflowRuntimeRun, startWorkflowRuntimeRun };

package/dist/step-definition.d.mts

@@ -0,0 +1,10 @@
+import { WorkflowStepContext, WorkflowStepDefinition, WorkflowStepRunConfig } from "./types/step.mjs";
+//#region src/step-definition.d.ts
+type WorkflowStepHandler = (...args: never[]) => unknown;
+type WorkflowStepHandlerInputTuple<THandler extends WorkflowStepHandler> = THandler extends ((...args: infer TArgs) => unknown) ? TArgs : never;
+type WorkflowStepHandlerArgs<THandler extends WorkflowStepHandler> = WorkflowStepHandlerInputTuple<THandler> extends [...infer TArgs, WorkflowStepContext] ? TArgs : WorkflowStepHandlerInputTuple<THandler>;
+type WorkflowStepHandlerOutput<THandler extends WorkflowStepHandler> = THandler extends ((...args: never[]) => infer TOutput) ? Awaited<TOutput> : never;
+/** Defines a workflow step. */
+declare function defineWorkflowStep<THandler extends WorkflowStepHandler>(config: WorkflowStepRunConfig, handler: THandler): WorkflowStepDefinition<WorkflowStepHandlerArgs<THandler>, WorkflowStepHandlerOutput<THandler>>;
+//#endregion
+export { defineWorkflowStep };

package/dist/step-definition.mjs

@@ -0,0 +1,15 @@
+import { WorkflowDefinitionError } from "./errors/definition.mjs";
+import "./errors/mod.mjs";
+//#region src/step-definition.ts
+/** Defines a workflow step. */
+function defineWorkflowStep(config, handler) {
+	const commandId = config.commandId ?? config.name;
+	if (commandId === void 0) WorkflowDefinitionError.stepNameOrCommandIdRequired();
+	return {
+		config,
+		name: commandId,
+		handler
+	};
+}
+//#endregion
+export { defineWorkflowStep };

package/dist/store/append-projection.d.mts

@@ -0,0 +1,15 @@
+import { RunId } from "../types/run-id.mjs";
+import "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+import { WorkflowEventAppendAtomicProjectionPlanner, WorkflowEventAppendSuccessOutcome } from "./event-append.mjs";
+//#region src/store/append-projection.d.ts
+interface WorkflowAppendProjectionPipeline {
+  readonly materializesAtomically: boolean;
+  readonly planAtomicProjections?: WorkflowEventAppendAtomicProjectionPlanner;
+  finalize(outcome: WorkflowEventAppendSuccessOutcome): Promise<readonly EventRecord[]>;
+  finalizePostCommit(outcome: WorkflowEventAppendSuccessOutcome): Promise<void>;
+}
+declare function createWorkflowAppendProjectionPipeline(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord): Promise<WorkflowAppendProjectionPipeline>;
+//#endregion
+export { WorkflowAppendProjectionPipeline, createWorkflowAppendProjectionPipeline };

package/dist/store/append-projection.mjs

@@ -0,0 +1,26 @@
+import { supportsWorkflowAtomicBatchWrite } from "./capabilities.mjs";
+import { createWorkflowStepAttemptMaterializationStoragePlan, materializeStepAttemptForAppendOutcome } from "./materialization.mjs";
+import { projectMessageIdempotencyIndexForAppendOutcome } from "./message-index.mjs";
+//#region src/store/append-projection.ts
+async function createWorkflowAppendProjectionPipeline(storage, namespace, runId, event) {
+	if (!supportsWorkflowAtomicBatchWrite(storage)) return createWorkflowAppendProjectionPipelineFromStepAttemptPlan(storage, namespace, runId, event, void 0);
+	return createWorkflowAppendProjectionPipelineFromStepAttemptPlan(storage, namespace, runId, event, await createWorkflowStepAttemptMaterializationStoragePlan(storage, namespace, runId, event));
+}
+function createWorkflowAppendProjectionPipelineFromStepAttemptPlan(storage, namespace, runId, event, initialStepAttemptPlan) {
+	return {
+		materializesAtomically: initialStepAttemptPlan?.materializes === true,
+		planAtomicProjections: createWorkflowAppendAtomicProjectionPlanner(storage, namespace, runId, event, initialStepAttemptPlan),
+		async finalize(outcome) {
+			return await projectMessageIdempotencyIndexForAppendOutcome(storage, namespace, runId, event, outcome);
+		},
+		async finalizePostCommit(outcome) {
+			if (!supportsWorkflowAtomicBatchWrite(storage)) await materializeStepAttemptForAppendOutcome(storage, namespace, runId, event, outcome);
+		}
+	};
+}
+function createWorkflowAppendAtomicProjectionPlanner(storage, namespace, runId, event, initialStepAttemptPlan) {
+	if (!supportsWorkflowAtomicBatchWrite(storage)) return;
+	return async (attempt) => attempt === 0 && initialStepAttemptPlan !== void 0 ? initialStepAttemptPlan : await createWorkflowStepAttemptMaterializationStoragePlan(storage, namespace, runId, event);
+}
+//#endregion
+export { createWorkflowAppendProjectionPipeline };

package/dist/store/capabilities.d.mts

@@ -0,0 +1,14 @@
+import { WorkflowStorage, WorkflowStoreCapabilities } from "../types/store.mjs";
+//#region src/store/capabilities.d.ts
+/** Detects which coordination capabilities are available on a workflow store backend. */
+declare function getWorkflowStoreCapabilities(storage: WorkflowStorage): WorkflowStoreCapabilities;
+/** Validates workflow store capabilities and throws when the requirement is not met. */
+declare function requireWorkflowStoreCapabilities(store: {
+  readonly capabilities: WorkflowStoreCapabilities;
+}, requirements: Partial<Record<keyof WorkflowStoreCapabilities, string>>): void;
+/** Returns whether a storage backend can reject stale single-key writes. */
+declare function supportsWorkflowConditionalWrite(storage: WorkflowStorage): boolean;
+/** Returns whether a storage backend can atomically reject stale multi-key writes. */
+declare function supportsWorkflowAtomicBatchWrite(storage: WorkflowStorage): boolean;
+//#endregion
+export { getWorkflowStoreCapabilities, requireWorkflowStoreCapabilities, supportsWorkflowAtomicBatchWrite, supportsWorkflowConditionalWrite };

package/dist/store/capabilities.mjs

@@ -0,0 +1,42 @@
+import { WorkflowCapabilityError } from "../errors/capability.mjs";
+import "../errors/mod.mjs";
+//#region src/store/capabilities.ts
+/** Detects which coordination capabilities are available on a workflow store backend. */
+function getWorkflowStoreCapabilities(storage) {
+	const conditionalWrites = supportsWorkflowConditionalWrite(storage);
+	const conditionalBatches = supportsWorkflowAtomicBatchWrite(storage);
+	return {
+		conditionalWrites,
+		conditionalRunClaims: conditionalWrites,
+		conditionalRunUpdates: conditionalWrites,
+		conditionalRunLeaseExtensions: conditionalWrites,
+		conditionalRunLeaseReleases: conditionalWrites,
+		conditionalEventAppends: conditionalWrites,
+		conditionalStepAttemptMaterialization: conditionalWrites,
+		atomicRunCreation: conditionalBatches,
+		atomicEventAndStepAttemptMaterialization: conditionalBatches,
+		messageIdempotencyIndexes: true,
+		indexedRunQueries: false,
+		indexedRunCounts: false,
+		indexedClaimableRunQueries: false,
+		indexedStepAttemptQueries: false,
+		indexedScheduleQueries: false,
+		indexedLockQueries: false,
+		rollsBackEventsOnMaterializationFailure: true,
+		reconcilesStepAttemptsFromEvents: true
+	};
+}
+/** Validates workflow store capabilities and throws when the requirement is not met. */
+function requireWorkflowStoreCapabilities(store, requirements) {
+	for (const [capability, label] of Object.entries(requirements)) if (store.capabilities[capability] !== true) WorkflowCapabilityError.unsupported(label ?? `workflow store ${capability}`);
+}
+/** Returns whether a storage backend can reject stale single-key writes. */
+function supportsWorkflowConditionalWrite(storage) {
+	return storage.capabilities.compareAndSet;
+}
+/** Returns whether a storage backend can atomically reject stale multi-key writes. */
+function supportsWorkflowAtomicBatchWrite(storage) {
+	return storage.capabilities.compareAndSetMany;
+}
+//#endregion
+export { getWorkflowStoreCapabilities, requireWorkflowStoreCapabilities, supportsWorkflowAtomicBatchWrite, supportsWorkflowConditionalWrite };

package/dist/store/cleanup.d.mts

@@ -0,0 +1,18 @@
+import { RunId } from "../types/run-id.mjs";
+import { CleanupMarkerRecord, CleanupRunsOptions, CleanupRunsResult } from "../types/cleanup.mjs";
+import { WorkflowListRunsOptions } from "../types/run-list.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowCleanupIndexKey, WorkflowStorage } from "../types/store.mjs";
+//#region src/store/cleanup.d.ts
+interface WorkflowCleanupRunLister {
+  listRuns(options: WorkflowListRunsOptions): Promise<readonly WorkflowRunRecord[]>;
+}
+declare function stepAttemptKeysForCleanup(storage: WorkflowStorage, namespace: string, runId: RunId): Promise<readonly string[]>;
+declare function messageIdempotencyIndexesForCleanup(storage: WorkflowStorage, namespace: string, runId: RunId, events: readonly EventRecord[]): Promise<readonly WorkflowCleanupIndexKey[]>;
+declare function idempotencyIndexesForCleanup(storage: WorkflowStorage, namespace: string, run: WorkflowRunRecord): Promise<readonly WorkflowCleanupIndexKey[]>;
+declare function deleteCleanupIndexes(storage: WorkflowStorage, indexes: readonly WorkflowCleanupIndexKey[]): Promise<number>;
+declare function cleanupRuns(storage: WorkflowStorage, namespace: string, runs: WorkflowCleanupRunLister, options: CleanupRunsOptions): Promise<CleanupRunsResult>;
+declare function listCleanupMarkers(storage: WorkflowStorage, namespace: string): Promise<readonly CleanupMarkerRecord[]>;
+//#endregion
+export { cleanupRuns, deleteCleanupIndexes, idempotencyIndexesForCleanup, listCleanupMarkers, messageIdempotencyIndexesForCleanup, stepAttemptKeysForCleanup };