@temelj/workflow 0.0.0-alpha.1

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

@@ -0,0 +1,37 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+import { StorageCompareAndSetManyItem, StorageValue } from "@temelj/storage";
+//#region src/store/event-append.d.ts
+type WorkflowEventAppendSuccessOutcome = {
+  readonly status: "appended";
+  readonly events: readonly EventRecord[];
+  readonly previousEventHistory?: StorageValue;
+} | {
+  readonly status: "duplicate";
+  readonly events: readonly EventRecord[];
+};
+type WorkflowEventAppendOutcome = WorkflowEventAppendSuccessOutcome | {
+  readonly status: "staleRun";
+};
+type WorkflowEventAppendedOutcome = Extract<WorkflowEventAppendSuccessOutcome, {
+  readonly status: "appended";
+}>;
+interface WorkflowEventAppendAtomicProjectionPlan {
+  readonly item?: StorageCompareAndSetManyItem<StorageValue>;
+}
+type WorkflowEventAppendAtomicProjectionPlanner = (attempt: number) => Promise<WorkflowEventAppendAtomicProjectionPlan | undefined>;
+type WorkflowEventAppendDuplicateDetector = (runId: RunId, events: readonly EventRecord[], event: EventRecord) => Extract<WorkflowEventAppendSuccessOutcome, {
+  readonly status: "duplicate";
+}> | undefined;
+interface EventAppendOptions {
+  readonly detectDuplicate?: WorkflowEventAppendDuplicateDetector;
+  readonly previousEventHistory?: StorageValue;
+}
+declare function makeStaleRunAppendOutcome(): WorkflowEventAppendOutcome;
+declare function appendEventWithAtomicProjectionPlan(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord, planProjection?: WorkflowEventAppendAtomicProjectionPlanner, detectDuplicate?: WorkflowEventAppendDuplicateDetector): Promise<WorkflowEventAppendSuccessOutcome>;
+declare function appendEventIfRunRevisionCurrentAtomically(storage: WorkflowStorage, namespace: string, currentRun: WorkflowRunRecord, event: EventRecord, detectDuplicate?: WorkflowEventAppendDuplicateDetector): Promise<WorkflowEventAppendOutcome>;
+declare function appendEventIfCurrent(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord, options?: EventAppendOptions): Promise<WorkflowEventAppendSuccessOutcome>;
+//#endregion
+export { WorkflowEventAppendAtomicProjectionPlanner, WorkflowEventAppendDuplicateDetector, WorkflowEventAppendOutcome, WorkflowEventAppendSuccessOutcome, WorkflowEventAppendedOutcome, appendEventIfCurrent, appendEventIfRunRevisionCurrentAtomically, appendEventWithAtomicProjectionPlan, makeStaleRunAppendOutcome };

package/dist/store/event-append.mjs

@@ -0,0 +1,80 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import "../errors/mod.mjs";
+import { supportsWorkflowAtomicBatchWrite, supportsWorkflowConditionalWrite } from "./capabilities.mjs";
+import { makeEventsKey, makeRunKey } from "../store-keys.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { createRunRevisionGuardedEventHistoryCompareAndSetItems, createWorkflowEventHistoryCompareAndSetItem, getStoredEventHistory } from "./event-history.mjs";
+//#region src/store/event-append.ts
+const MAX_APPEND_EVENT_ATTEMPTS = 16;
+function makeAppendedEventOutcome(events, previousEventHistory) {
+	return {
+		status: "appended",
+		events,
+		...previousEventHistory === void 0 ? {} : { previousEventHistory }
+	};
+}
+function makeStaleRunAppendOutcome() {
+	return { status: "staleRun" };
+}
+async function appendEventWithAtomicProjectionPlan(storage, namespace, runId, event, planProjection, detectDuplicate) {
+	if (!supportsWorkflowAtomicBatchWrite(storage)) return await appendEventIfCurrent(storage, namespace, runId, event, {
+		detectDuplicate,
+		previousEventHistory: await storage.get(makeEventsKey(namespace, runId))
+	});
+	const eventsStorageKey = makeEventsKey(namespace, runId);
+	for (let attempt = 0; attempt < MAX_APPEND_EVENT_ATTEMPTS; attempt++) {
+		const appendState = await readWorkflowEventAppendState(storage, eventsStorageKey, runId, event, detectDuplicate);
+		const duplicate = appendState.duplicate;
+		if (duplicate !== void 0) return duplicate;
+		const projectionPlan = await planProjection?.(attempt);
+		const items = [createWorkflowEventHistoryCompareAndSetItem(eventsStorageKey, appendState.raw, appendState.nextEvents), ...projectionPlan?.item === void 0 ? [] : [projectionPlan.item]];
+		if (await storage.compareAndSetMany(items)) return makeAppendedEventOutcome(appendState.nextEvents, appendState.raw);
+	}
+	WorkflowStateError.failedWorkflowEventAppend(runId, MAX_APPEND_EVENT_ATTEMPTS);
+}
+async function appendEventIfRunRevisionCurrentAtomically(storage, namespace, currentRun, event, detectDuplicate) {
+	const runId = currentRun.id;
+	const runStorageKey = makeRunKey(namespace, runId);
+	const eventsStorageKey = makeEventsKey(namespace, runId);
+	for (let attempt = 0; attempt < MAX_APPEND_EVENT_ATTEMPTS; attempt++) {
+		const appendState = await readWorkflowEventAppendState(storage, eventsStorageKey, runId, event, detectDuplicate);
+		const duplicate = appendState.duplicate;
+		if (duplicate !== void 0) {
+			if (await storage.compareAndSetMany(createRunRevisionGuardedEventHistoryCompareAndSetItems(runStorageKey, currentRun, eventsStorageKey, appendState.raw, appendState.currentEvents))) return duplicate;
+			continue;
+		}
+		if (await storage.compareAndSetMany(createRunRevisionGuardedEventHistoryCompareAndSetItems(runStorageKey, currentRun, eventsStorageKey, appendState.raw, appendState.nextEvents))) return makeAppendedEventOutcome(appendState.nextEvents, appendState.raw);
+		if (event.kind === "message_sent") return makeStaleRunAppendOutcome();
+	}
+	return makeStaleRunAppendOutcome();
+}
+async function appendEventIfCurrent(storage, namespace, runId, event, options = {}) {
+	const key = makeEventsKey(namespace, runId);
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		const current = (await getStoredEventHistory(storage, key)).events;
+		const duplicate = options.detectDuplicate?.(runId, current, event);
+		if (duplicate !== void 0) return duplicate;
+		const events = [...current, event];
+		await storage.set(key, toStorageValue(events));
+		return makeAppendedEventOutcome(events, options.previousEventHistory);
+	}
+	for (let attempt = 0; attempt < MAX_APPEND_EVENT_ATTEMPTS; attempt++) {
+		const appendState = await readWorkflowEventAppendState(storage, key, runId, event, options.detectDuplicate);
+		const duplicate = appendState.duplicate;
+		if (duplicate !== void 0) return duplicate;
+		if (await storage.compareAndSet(key, appendState.raw, toStorageValue(appendState.nextEvents))) return makeAppendedEventOutcome(appendState.nextEvents, appendState.raw);
+	}
+	WorkflowStateError.failedWorkflowEventAppend(runId, MAX_APPEND_EVENT_ATTEMPTS);
+}
+async function readWorkflowEventAppendState(storage, eventsStorageKey, runId, event, detectDuplicate) {
+	const { raw, events: currentEvents } = await getStoredEventHistory(storage, eventsStorageKey);
+	const duplicate = detectDuplicate?.(runId, currentEvents, event);
+	return {
+		raw,
+		currentEvents,
+		...duplicate === void 0 ? {} : { duplicate },
+		nextEvents: duplicate === void 0 ? [...currentEvents, event] : currentEvents
+	};
+}
+//#endregion
+export { appendEventIfCurrent, appendEventIfRunRevisionCurrentAtomically, appendEventWithAtomicProjectionPlan, makeStaleRunAppendOutcome };

package/dist/store/event-history.d.mts

@@ -0,0 +1,22 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+import { StorageCompareAndSetManyItem, StorageValue } from "@temelj/storage";
+//#region src/store/event-history.d.ts
+type WorkflowEventHistoryCompareAndSetItem = StorageCompareAndSetManyItem<StorageValue>;
+type WorkflowRunRevisionCompareAndSetItem = StorageCompareAndSetManyItem<StorageValue>;
+declare function getStoredEventHistory(storage: WorkflowStorage, key: string): Promise<{
+  readonly raw: StorageValue | undefined;
+  readonly events: readonly EventRecord[];
+}>;
+declare function getStoredCleanupEventHistory(storage: WorkflowStorage, key: string): Promise<{
+  readonly raw: StorageValue | undefined;
+  readonly events: readonly EventRecord[];
+}>;
+declare function isSameWorkflowEventIdentity(left: EventRecord, right: EventRecord): boolean;
+declare function rollbackAppendedEventIfCurrent(storage: WorkflowStorage, namespace: string, runId: RunId, expectedEvents: readonly EventRecord[], previousEventHistory?: StorageValue): Promise<boolean>;
+declare function createWorkflowEventHistoryCompareAndSetItem(eventsStorageKey: string, expected: StorageValue | undefined, events: readonly EventRecord[]): WorkflowEventHistoryCompareAndSetItem;
+declare function createRunRevisionGuardedEventHistoryCompareAndSetItems(runStorageKey: string, currentRun: WorkflowRunRecord, eventsStorageKey: string, expectedEvents: StorageValue | undefined, events: readonly EventRecord[]): readonly [WorkflowRunRevisionCompareAndSetItem, WorkflowEventHistoryCompareAndSetItem];
+//#endregion
+export { createRunRevisionGuardedEventHistoryCompareAndSetItems, createWorkflowEventHistoryCompareAndSetItem, getStoredCleanupEventHistory, getStoredEventHistory, isSameWorkflowEventIdentity, rollbackAppendedEventIfCurrent };

package/dist/store/event-history.mjs

@@ -0,0 +1,75 @@
+import { getEventDescriptor, isCleanupEventRecord } from "../events/descriptors.mjs";
+import { supportsWorkflowConditionalWrite } from "./capabilities.mjs";
+import { makeEventsKey } from "../store-keys.mjs";
+import { isSameWorkflowStorageValue } from "./revision.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { isReadableEventRecord } from "./validation.mjs";
+//#region src/store/event-history.ts
+async function getStoredEventHistory(storage, key) {
+	const raw = await storage.get(key);
+	return {
+		raw,
+		events: Array.isArray(raw) ? raw.filter(isReadableEventRecord) : []
+	};
+}
+async function getStoredCleanupEventHistory(storage, key) {
+	const history = await getStoredEventHistory(storage, key);
+	return {
+		raw: history.raw,
+		events: history.events.filter(isCleanupEventRecord)
+	};
+}
+function isSameWorkflowEventIdentity(left, right) {
+	if (left.kind !== right.kind || Temporal.Instant.compare(left.timestamp, right.timestamp) !== 0) return false;
+	const descriptor = getEventDescriptor(left.kind);
+	return isSameWorkflowEventFields(left, right, descriptor.identityFields) && isSameWorkflowEventValueFields(left, right, descriptor.valueIdentityFields) && isSameWorkflowEventStringListFields(left, right, descriptor.stringListIdentityFields);
+}
+function isSameWorkflowEventFields(left, right, fields = []) {
+	return fields.every((field) => Reflect.get(left, field) === Reflect.get(right, field));
+}
+function isSameWorkflowEventValueFields(left, right, fields = []) {
+	return fields.every((field) => isSameWorkflowStorageValue(Reflect.get(left, field), Reflect.get(right, field)));
+}
+function isSameWorkflowEventStringListFields(left, right, fields = []) {
+	return fields.every((field) => {
+		const leftValue = Reflect.get(left, field);
+		const rightValue = Reflect.get(right, field);
+		const leftValues = Array.isArray(leftValue) && leftValue.every((item) => typeof item === "string" && item.trim() !== "") ? leftValue : void 0;
+		const rightValues = Array.isArray(rightValue) && rightValue.every((item) => typeof item === "string" && item.trim() !== "") ? rightValue : void 0;
+		if (leftValues === void 0 || rightValues === void 0) return leftValues === rightValues;
+		if (leftValues.length !== rightValues.length) return false;
+		return leftValues.every((value, index) => value === rightValues[index]);
+	});
+}
+async function rollbackAppendedEventIfCurrent(storage, namespace, runId, expectedEvents, previousEventHistory) {
+	if (expectedEvents.length === 0) return false;
+	const key = makeEventsKey(namespace, runId);
+	const rolledBackEvents = expectedEvents.slice(0, -1);
+	if (supportsWorkflowConditionalWrite(storage)) return await storage.compareAndSet(key, toStorageValue(expectedEvents), previousEventHistory ?? toStorageValue(rolledBackEvents));
+	const current = (await getStoredEventHistory(storage, key)).events;
+	const expectedLast = expectedEvents.at(-1);
+	const currentLast = current.at(-1);
+	if (current.length !== expectedEvents.length || expectedLast === void 0 || currentLast === void 0 || !isSameWorkflowEventIdentity(currentLast, expectedLast)) return false;
+	await storage.set(key, previousEventHistory ?? toStorageValue(rolledBackEvents));
+	return true;
+}
+function createWorkflowEventHistoryCompareAndSetItem(eventsStorageKey, expected, events) {
+	return {
+		key: eventsStorageKey,
+		expected,
+		value: toStorageValue(events)
+	};
+}
+function createWorkflowRunRevisionCompareAndSetItem(runStorageKey, currentRun) {
+	const value = toStorageValue(currentRun);
+	return {
+		key: runStorageKey,
+		expected: value,
+		value
+	};
+}
+function createRunRevisionGuardedEventHistoryCompareAndSetItems(runStorageKey, currentRun, eventsStorageKey, expectedEvents, events) {
+	return [createWorkflowRunRevisionCompareAndSetItem(runStorageKey, currentRun), createWorkflowEventHistoryCompareAndSetItem(eventsStorageKey, expectedEvents, events)];
+}
+//#endregion
+export { createRunRevisionGuardedEventHistoryCompareAndSetItems, createWorkflowEventHistoryCompareAndSetItem, getStoredCleanupEventHistory, getStoredEventHistory, isSameWorkflowEventIdentity, rollbackAppendedEventIfCurrent };

package/dist/store/event.d.mts

@@ -0,0 +1,10 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+//#region src/store/event.d.ts
+declare function appendWorkflowEvent(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord): Promise<readonly EventRecord[]>;
+declare function appendWorkflowEventIfRunCurrent(storage: WorkflowStorage, namespace: string, current: WorkflowRunRecord, event: EventRecord): Promise<readonly EventRecord[] | undefined>;
+declare function getWorkflowEvents(storage: WorkflowStorage, namespace: string, runId: RunId): Promise<readonly EventRecord[]>;
+//#endregion
+export { appendWorkflowEvent, appendWorkflowEventIfRunCurrent, getWorkflowEvents };

package/dist/store/event.mjs

@@ -0,0 +1,28 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import { makeEventsKey } from "../store-keys.mjs";
+import { requireReadableStoreRun } from "./validation.mjs";
+import { getStoredEventHistory } from "./event-history.mjs";
+import { requireReadableStoredWorkflowRun } from "./run.mjs";
+import { createWorkflowAppendProjectionPipeline } from "./append-projection.mjs";
+import { appendEventWithProjectionPipelineIfRunCurrent, appendEventWithProjections } from "./event-append-project.mjs";
+//#region src/store/event.ts
+async function finalizeWorkflowAppendOutcome(outcome, projectionPipeline) {
+	if (outcome.status === "staleRun") return;
+	if (projectionPipeline === void 0) WorkflowStateError.appendProjectionPipelineMissing();
+	return await projectionPipeline.finalize(outcome);
+}
+async function appendWorkflowEvent(storage, namespace, runId, event) {
+	await requireReadableStoredWorkflowRun(storage, namespace, runId);
+	const projectionPipeline = await createWorkflowAppendProjectionPipeline(storage, namespace, runId, event);
+	return await finalizeWorkflowAppendOutcome(await appendEventWithProjections(storage, namespace, runId, event, projectionPipeline), projectionPipeline);
+}
+async function appendWorkflowEventIfRunCurrent(storage, namespace, current, event) {
+	requireReadableStoreRun(current, namespace);
+	const appendOutcome = await appendEventWithProjectionPipelineIfRunCurrent(storage, namespace, current, event);
+	return await finalizeWorkflowAppendOutcome(appendOutcome.outcome, appendOutcome.projectionPipeline);
+}
+async function getWorkflowEvents(storage, namespace, runId) {
+	return (await getStoredEventHistory(storage, makeEventsKey(namespace, runId))).events;
+}
+//#endregion
+export { appendWorkflowEvent, appendWorkflowEventIfRunCurrent, getWorkflowEvents };

package/dist/store/idempotency.d.mts

@@ -0,0 +1,10 @@
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { WorkflowIdempotencyKeyOptions, WorkflowStorage } from "../types/store.mjs";
+//#region src/store/idempotency.d.ts
+interface WorkflowIdempotencyRunReader {
+  getRun(runId: string): Promise<WorkflowRunRecord | undefined>;
+}
+declare function createRunWithIdempotency(storage: WorkflowStorage, namespace: string, store: WorkflowIdempotencyRunReader, run: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+declare function getRunByIdempotencyKey(storage: WorkflowStorage, namespace: string, store: WorkflowIdempotencyRunReader, options: WorkflowIdempotencyKeyOptions): Promise<WorkflowRunRecord | undefined>;
+//#endregion
+export { createRunWithIdempotency, getRunByIdempotencyKey };

package/dist/store/idempotency.mjs

@@ -0,0 +1,167 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import "../errors/mod.mjs";
+import { supportsWorkflowAtomicBatchWrite, supportsWorkflowConditionalWrite } from "./capabilities.mjs";
+import { makeEventsKey, makeIdempotencyKey, makeRunKey } from "../store-keys.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { isReadableWorkflowRunRecord } from "./validation.mjs";
+//#region src/store/idempotency.ts
+const MAX_IDEMPOTENT_CREATE_WAIT_ATTEMPTS = 16;
+async function createRunWithIdempotency(storage, namespace, store, run) {
+	if (run.namespace !== namespace) throw WorkflowStateError.runNamespaceMismatch(String(run.namespace), namespace);
+	const keyOptions = idempotencyKeyOptionsForRun(run);
+	if (supportsWorkflowAtomicBatchWrite(storage)) return await createRunAtomicallyWithIdempotency(storage, namespace, store, run, keyOptions);
+	const idempotencyClaim = keyOptions === void 0 ? void 0 : await claimWorkflowIdempotencyIndex(storage, namespace, store, run, keyOptions);
+	if (idempotencyClaim?.status === "existing") return idempotencyClaim.run;
+	if (keyOptions !== void 0) assertWorkflowIdempotencyClaimed(run.id, idempotencyClaim);
+	try {
+		await createRunRecordAndEventHistory(storage, namespace, run);
+		return run;
+	} catch (error) {
+		await rollbackWorkflowIdempotencyClaim(storage, idempotencyClaim);
+		throw error;
+	}
+}
+async function createRunRecordAndEventHistory(storage, namespace, run) {
+	const runKey = makeRunKey(namespace, run.id);
+	const eventsKey = makeEventsKey(namespace, run.id);
+	let claim = {};
+	try {
+		if (!supportsWorkflowConditionalWrite(storage)) {
+			if (await storage.get(runKey) !== void 0) WorkflowStateError.runIdAlreadyExists(run.id);
+			if (await storage.get(eventsKey) !== void 0) WorkflowStateError.eventHistoryAlreadyExists(run.id);
+			await storage.set(runKey, toStorageValue(run));
+			claim = { runKey };
+			await storage.set(eventsKey, toStorageValue([]));
+			return {
+				...claim,
+				eventsKey
+			};
+		}
+		if (!await storage.compareAndSet(runKey, void 0, toStorageValue(run))) WorkflowStateError.runIdAlreadyExists(run.id);
+		claim = { runKey };
+		if (!await storage.compareAndSet(eventsKey, void 0, toStorageValue([]))) WorkflowStateError.eventHistoryAlreadyExists(run.id);
+		return {
+			...claim,
+			eventsKey
+		};
+	} catch (error) {
+		await rollbackRunCreationClaim(storage, claim);
+		throw error;
+	}
+}
+async function rollbackRunCreationClaim(storage, claim) {
+	await storage.deleteMany([...claim.runKey === void 0 ? [] : [claim.runKey], ...claim.eventsKey === void 0 ? [] : [claim.eventsKey]]);
+}
+async function rollbackWorkflowIdempotencyClaim(storage, claim) {
+	if (claim?.status !== "claimed") return;
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		await storage.delete(claim.key);
+		return;
+	}
+	await storage.compareAndSet(claim.key, claim.value, void 0);
+}
+async function claimWorkflowIdempotencyIndex(storage, namespace, store, run, keyOptions) {
+	const key = makeIdempotencyKey(namespace, keyOptions);
+	const value = toStorageValue(run.id);
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		const existingRun = await getRunByIdempotencyKey(storage, namespace, store, keyOptions);
+		if (existingRun !== void 0) return {
+			status: "existing",
+			run: existingRun
+		};
+		await storage.set(key, value);
+		return {
+			status: "claimed",
+			key,
+			value
+		};
+	}
+	if (await storage.compareAndSet(key, void 0, value)) return {
+		status: "claimed",
+		key,
+		value
+	};
+	const existingRun = await waitForRunByIdempotencyKey(storage, namespace, store, keyOptions);
+	if (existingRun !== void 0) return {
+		status: "existing",
+		run: existingRun
+	};
+	if (!await releaseStaleWorkflowIdempotencyIndex(storage, namespace, store, keyOptions)) WorkflowStateError.idempotencyKeyClaimedWithoutRun(run.id);
+	if (await storage.compareAndSet(key, void 0, value)) return {
+		status: "claimed",
+		key,
+		value
+	};
+	const reclaimedExistingRun = await waitForRunByIdempotencyKey(storage, namespace, store, keyOptions);
+	if (reclaimedExistingRun !== void 0) return {
+		status: "existing",
+		run: reclaimedExistingRun
+	};
+	WorkflowStateError.idempotencyKeyClaimedWithoutRun(run.id);
+}
+function assertWorkflowIdempotencyClaimed(runId, claim) {
+	if (claim?.status !== "claimed") WorkflowStateError.idempotencyKeyClaimedWithoutRun(runId);
+}
+async function createRunAtomicallyWithIdempotency(storage, namespace, store, run, keyOptions) {
+	for (let attempt = 0; attempt < 2; attempt++) {
+		if (await storage.compareAndSetMany([
+			...atomicIdempotencyClaimItems(namespace, run, keyOptions),
+			{
+				key: makeRunKey(namespace, run.id),
+				expected: void 0,
+				value: toStorageValue(run)
+			},
+			{
+				key: makeEventsKey(namespace, run.id),
+				expected: void 0,
+				value: toStorageValue([])
+			}
+		])) return run;
+		if (keyOptions === void 0) WorkflowStateError.runIdAlreadyExists(run.id);
+		const existingRun = await waitForRunByIdempotencyKey(storage, namespace, store, keyOptions);
+		if (existingRun !== void 0) return existingRun;
+		if (attempt === 0 && await releaseStaleWorkflowIdempotencyIndex(storage, namespace, store, keyOptions)) continue;
+		WorkflowStateError.idempotencyKeyClaimedWithoutRun(run.id);
+	}
+	throw WorkflowStateError.runIdAlreadyExists(run.id);
+}
+function atomicIdempotencyClaimItems(namespace, run, keyOptions) {
+	return keyOptions === void 0 ? [] : [{
+		key: makeIdempotencyKey(namespace, keyOptions),
+		expected: void 0,
+		value: toStorageValue(run.id)
+	}];
+}
+async function getRunByIdempotencyKey(storage, namespace, store, options) {
+	const runId = await storage.get(makeIdempotencyKey(namespace, options));
+	if (!(typeof runId === "string" && runId.trim() !== "")) return;
+	const run = await store.getRun(runId);
+	return run !== void 0 && isReadableWorkflowRunRecord(run, run.namespace) && run.workflowName === options.workflowName && run.workflowVersion === options.workflowVersion && run.idempotencyKey === options.idempotencyKey ? run : void 0;
+}
+function idempotencyKeyOptionsForRun(run) {
+	return run.idempotencyKey === void 0 ? void 0 : {
+		workflowName: run.workflowName,
+		...run.workflowVersion === void 0 ? {} : { workflowVersion: run.workflowVersion },
+		idempotencyKey: run.idempotencyKey
+	};
+}
+async function waitForRunByIdempotencyKey(storage, namespace, store, options) {
+	for (let attempt = 0; attempt < MAX_IDEMPOTENT_CREATE_WAIT_ATTEMPTS; attempt++) {
+		const run = await getRunByIdempotencyKey(storage, namespace, store, options);
+		if (run !== void 0) return run;
+		await Promise.resolve();
+	}
+}
+async function releaseStaleWorkflowIdempotencyIndex(storage, namespace, store, options) {
+	if (!supportsWorkflowConditionalWrite(storage)) return false;
+	const key = makeIdempotencyKey(namespace, options);
+	const value = await storage.get(key);
+	if (value === void 0) return false;
+	if (typeof value === "string" && value.trim() !== "") {
+		const run = await store.getRun(value);
+		if (run !== void 0 && isReadableWorkflowRunRecord(run, run.namespace) && run.workflowName === options.workflowName && run.workflowVersion === options.workflowVersion && run.idempotencyKey === options.idempotencyKey) return false;
+	}
+	return await storage.compareAndSet(key, value, void 0);
+}
+//#endregion
+export { createRunWithIdempotency, getRunByIdempotencyKey };

package/dist/store/instrumentation.d.mts

@@ -0,0 +1,7 @@
+import { Telemetry } from "../types/telemetry.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+//#region src/store/instrumentation.d.ts
+/** Wraps workflow storage operations with telemetry. */
+declare function instrumentWorkflowStorage(storage: WorkflowStorage, telemetry: Telemetry | undefined): WorkflowStorage;
+//#endregion
+export { instrumentWorkflowStorage };

package/dist/store/instrumentation.mjs

@@ -0,0 +1,123 @@
+import { withStorageTelemetry } from "../telemetry.mjs";
+//#region src/store/instrumentation.ts
+/** Wraps workflow storage operations with telemetry. */
+function instrumentWorkflowStorage(storage, telemetry) {
+	if (telemetry?.withStorageOperation === void 0) return storage;
+	const backend = storage.engine.name;
+	const run = async (operation, callback) => await withStorageTelemetry(telemetry, {
+		operation,
+		backend
+	}, callback);
+	const instrumented = {
+		engine: storage.engine,
+		capabilities: storage.capabilities,
+		on(pattern, handler) {
+			return storage.on(pattern, handler);
+		},
+		once(pattern, handler) {
+			return storage.once(pattern, handler);
+		},
+		off(pattern, handler) {
+			storage.off(pattern, handler);
+		},
+		listeners(pattern) {
+			return pattern === void 0 ? storage.listeners() : storage.listeners(pattern);
+		},
+		clearListeners(pattern) {
+			storage.clearListeners(pattern);
+		},
+		listenerCount(pattern) {
+			return storage.listenerCount(pattern);
+		},
+		async watch(callback) {
+			return await run("watch", async () => await storage.watch(callback));
+		},
+		async unwatch() {
+			await run("unwatch", async () => await storage.unwatch());
+		},
+		async get(key) {
+			return await run("get", async () => await storage.get(key));
+		},
+		async tryGet(key) {
+			return await run("tryGet", async () => await storage.tryGet(key));
+		},
+		async set(key, value, options) {
+			await run("set", async () => await storage.set(key, value, options));
+		},
+		async trySet(key, value, options) {
+			return await run("trySet", async () => await storage.trySet(key, value, options));
+		},
+		async compareAndSet(key, expected, value, options) {
+			return await run("compareAndSet", async () => await storage.compareAndSet(key, expected, value, options));
+		},
+		async tryCompareAndSet(key, expected, value, options) {
+			return await run("tryCompareAndSet", async () => await storage.tryCompareAndSet(key, expected, value, options));
+		},
+		async compareAndSetMany(items) {
+			return await run("compareAndSetMany", async () => await storage.compareAndSetMany(items));
+		},
+		async tryCompareAndSetMany(items) {
+			return await run("tryCompareAndSetMany", async () => await storage.tryCompareAndSetMany(items));
+		},
+		async has(key) {
+			return await run("has", async () => await storage.has(key));
+		},
+		async tryHas(key) {
+			return await run("tryHas", async () => await storage.tryHas(key));
+		},
+		async delete(key) {
+			return await run("delete", async () => await storage.delete(key));
+		},
+		async tryDelete(key) {
+			return await run("tryDelete", async () => await storage.tryDelete(key));
+		},
+		async getMany(keys) {
+			return await run("getMany", async () => await storage.getMany(keys));
+		},
+		async tryGetMany(keys) {
+			return await run("tryGetMany", async () => await storage.tryGetMany(keys));
+		},
+		async setMany(items) {
+			await run("setMany", async () => await storage.setMany(items));
+		},
+		async trySetMany(items) {
+			return await run("trySetMany", async () => await storage.trySetMany(items));
+		},
+		async deleteMany(keys) {
+			return await run("deleteMany", async () => await storage.deleteMany(keys));
+		},
+		async tryDeleteMany(keys) {
+			return await run("tryDeleteMany", async () => await storage.tryDeleteMany(keys));
+		},
+		async keys(options) {
+			return await run("keys", async () => await storage.keys(options));
+		},
+		async tryKeys(options) {
+			return await run("tryKeys", async () => await storage.tryKeys(options));
+		},
+		async entries(options) {
+			return await run("entries", async () => await storage.entries(options));
+		},
+		async tryEntries(options) {
+			return await run("tryEntries", async () => await storage.tryEntries(options));
+		},
+		async clear(options) {
+			await run("clear", async () => await storage.clear(options));
+		},
+		async tryClear(options) {
+			return await run("tryClear", async () => await storage.tryClear(options));
+		},
+		async dispose() {
+			await run("dispose", async () => await storage.dispose());
+		},
+		async [Symbol.asyncDispose]() {
+			await instrumented.dispose();
+		},
+		async tryDispose() {
+			return await run("tryDispose", async () => await storage.tryDispose());
+		}
+	};
+	return instrumented;
+}
+//#endregion
+export { instrumentWorkflowStorage };

package/dist/store/lock.d.mts

@@ -0,0 +1,8 @@
+import { LockRecord } from "../types/lock.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+//#region src/store/lock.d.ts
+declare function getReadableLock(storage: WorkflowStorage, namespace: string, key: string): Promise<LockRecord | undefined>;
+declare function listReadableLocks(storage: WorkflowStorage, namespace: string): Promise<readonly LockRecord[]>;
+declare function updateLockIfCurrent(storage: WorkflowStorage, namespace: string, current: LockRecord | undefined, next: LockRecord): Promise<LockRecord | undefined>;
+//#endregion
+export { getReadableLock, listReadableLocks, updateLockIfCurrent };

package/dist/store/lock.mjs

@@ -0,0 +1,28 @@
+import { WorkflowLockStateError } from "../errors/lock.mjs";
+import "../errors/mod.mjs";
+import { makeLockKey, makeLockKeyPrefix } from "../store-keys.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { isReadableLockRecord } from "./validation.mjs";
+import { compactWorkflowStoreRecord } from "./compaction.mjs";
+//#region src/store/lock.ts
+async function getReadableLock(storage, namespace, key) {
+	const lock = await storage.get(makeLockKey(namespace, key));
+	return isReadableLockRecord(lock, namespace) ? lock : void 0;
+}
+async function listReadableLocks(storage, namespace) {
+	return (await storage.entries({ prefix: makeLockKeyPrefix(namespace) })).map((entry) => entry.value).filter((lock) => isReadableLockRecord(lock, namespace)).sort((a, b) => a.key.localeCompare(b.key)).filter(isFirstLockRecordForKey);
+}
+async function updateLockIfCurrent(storage, namespace, current, next) {
+	if (next.namespace !== namespace) WorkflowLockStateError.namespaceMismatch(String(next.namespace), namespace);
+	if (current !== void 0) {
+		if (current.namespace !== namespace) WorkflowLockStateError.namespaceMismatch(String(current.namespace), namespace);
+		if (current.key !== next.key) WorkflowLockStateError.keyChangeRejected();
+	}
+	const compact = compactWorkflowStoreRecord(next);
+	return await storage.compareAndSet(makeLockKey(namespace, next.key), current === void 0 ? void 0 : toStorageValue(current), toStorageValue(compact)) ? compact : void 0;
+}
+function isFirstLockRecordForKey(lock, index, locks) {
+	return locks.findIndex((entry) => entry.key === lock.key) === index;
+}
+//#endregion
+export { getReadableLock, listReadableLocks, updateLockIfCurrent };

package/dist/store/materialization.d.mts

@@ -0,0 +1,30 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowStepAttemptRecord } from "../types/step-attempts.mjs";
+import "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { WorkflowStorage } from "../types/store.mjs";
+import { StorageCompareAndSetManyItem, StorageValue } from "@temelj/storage";
+//#region src/store/materialization.d.ts
+interface WorkflowStepAttemptMaterializationStoragePlan {
+  readonly materializes: boolean;
+  readonly storageKey?: string;
+  readonly current?: WorkflowStepAttemptRecord;
+  readonly item?: StorageCompareAndSetManyItem<StorageValue>;
+}
+interface WorkflowStepAttemptAppendMaterializationOutcome {
+  readonly status: "appended" | "duplicate";
+  readonly events: readonly EventRecord[];
+  readonly previousEventHistory?: StorageValue;
+}
+declare function materializeStepAttemptForAppendOutcome(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord, outcome: WorkflowStepAttemptAppendMaterializationOutcome): Promise<void>;
+declare function createWorkflowStepAttemptMaterializationStoragePlan(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord): Promise<WorkflowStepAttemptMaterializationStoragePlan>;
+declare function reconcileStepAttempts(storage: WorkflowStorage, namespace: string, runId: RunId, events: readonly EventRecord[]): Promise<readonly WorkflowStepAttemptRecord[]>;
+declare function materializeStepAttemptIfCurrent(storage: WorkflowStorage, runId: RunId, storageKey: string, createNext: (current: WorkflowStepAttemptRecord | undefined) => WorkflowStepAttemptRecord | undefined, options?: {
+  readonly repairStatusMismatch?: boolean;
+}): Promise<void>;
+declare function shouldStoreStepAttempt(current: WorkflowStepAttemptRecord | undefined, next: WorkflowStepAttemptRecord, options?: {
+  readonly repairStatusMismatch?: boolean;
+}): boolean;
+declare function isSameStepAttemptIdentity(current: WorkflowStepAttemptRecord, next: WorkflowStepAttemptRecord): boolean;
+//#endregion
+export { WorkflowStepAttemptAppendMaterializationOutcome, WorkflowStepAttemptMaterializationStoragePlan, createWorkflowStepAttemptMaterializationStoragePlan, isSameStepAttemptIdentity, materializeStepAttemptForAppendOutcome, materializeStepAttemptIfCurrent, reconcileStepAttempts, shouldStoreStepAttempt };