@temelj/workflow 0.0.0-alpha.1

package/dist/store/cleanup.mjs

@@ -0,0 +1,338 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import { makeWorkflowStepAttemptKey } from "../history/attempt-key.mjs";
+import { isTerminalWorkflowRunStatus } from "../utility.mjs";
+import { omitUndefined } from "../collection.mjs";
+import "../errors/mod.mjs";
+import { compareOptionalTimestamps } from "../temporal.mjs";
+import "../history/mod.mjs";
+import { supportsWorkflowConditionalWrite } from "./capabilities.mjs";
+import { makeCleanupMarkerKey, makeCleanupMarkerKeyPrefix, makeEventsKey, makeIdempotencyKey, makeMessageIdempotencyKey, makeRunKey, makeStepAttemptKeyPrefix } from "../store-keys.mjs";
+import { isSameWorkflowStorageValue } from "./revision.mjs";
+import { toStorageValue } from "./storage-value.mjs";
+import { isReadableMessageIdempotencyIndex, isSameMessageIdempotencyIndex, readableCleanupMarkerRecord } from "./validation.mjs";
+import { getStoredCleanupEventHistory } from "./event-history.mjs";
+import { getReadableStoredWorkflowRun } from "./run.mjs";
+import { messageIdempotencyIndexValuesFromEvents } from "./message-index.mjs";
+//#region src/store/cleanup.ts
+async function stepAttemptKeysForCleanup(storage, namespace, runId) {
+	const prefix = makeStepAttemptKeyPrefix(namespace, runId);
+	return [...new Set((await storage.keys({ prefix })).filter((key) => isStepAttemptKey(key, prefix)))];
+}
+function isStepAttemptKey(key, prefix) {
+	if (!key.startsWith(prefix)) return false;
+	const attemptKey = decodeStepAttemptKey(key, prefix);
+	if (attemptKey === void 0) return false;
+	const separator = attemptKey.lastIndexOf(":");
+	if (!attemptKey.startsWith("run:") || separator <= 4) return false;
+	const stepId = attemptKey.slice(4, separator);
+	const attempt = Number(attemptKey.slice(separator + 1));
+	try {
+		return makeWorkflowStepAttemptKey(stepId, attempt) === attemptKey;
+	} catch {
+		return false;
+	}
+}
+function decodeStepAttemptKey(key, prefix) {
+	try {
+		return decodeURIComponent(key.slice(prefix.length));
+	} catch {
+		return;
+	}
+}
+async function messageIdempotencyIndexesForCleanup(storage, namespace, runId, events) {
+	const candidatesByKey = /* @__PURE__ */ new Map();
+	for (const candidate of messageIdempotencyIndexesFromEvents(namespace, runId, events)) candidatesByKey.set(candidate.key, [...candidatesByKey.get(candidate.key) ?? [], candidate]);
+	return (await Promise.all([...candidatesByKey.keys()].map(async (key) => ({
+		key,
+		value: await storage.get(key)
+	})))).filter((entry) => isCurrentMessageIdempotencyIndex(candidatesByKey.get(entry.key) ?? [], entry.value)).map(toCleanupIndex);
+}
+async function idempotencyIndexesForCleanup(storage, namespace, run) {
+	if (run.idempotencyKey === void 0) return [];
+	const key = idempotencyKeyFromRun(namespace, run);
+	const value = await storage.get(key);
+	return value === run.id ? [{
+		key,
+		value
+	}] : [];
+}
+async function deleteCleanupIndexes(storage, indexes) {
+	const uniqueIndexes = indexes.filter(uniqueCleanupIndexKey);
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		const currentIndexes = await Promise.all(uniqueIndexes.map(async (index) => ({
+			...index,
+			current: await storage.get(index.key)
+		})));
+		return await storage.deleteMany(currentIndexes.flatMap((index) => workflowCleanupIndexMatchesCurrentValue(index.current, index.value) ? [index.key] : []));
+	}
+	return (await Promise.all(uniqueIndexes.map(async (index) => await storage.compareAndSet(index.key, index.value, void 0)))).filter((value) => value).length;
+}
+function workflowCleanupIndexMatchesCurrentValue(current, expected) {
+	if (isReadableMessageIdempotencyIndex(expected)) return isSameMessageIdempotencyIndex(current, expected);
+	return isSameWorkflowStorageValue(current, expected);
+}
+function messageIdempotencyIndexesFromEvents(namespace, runId, events) {
+	return messageIdempotencyIndexValuesFromEvents(events, runId).map(({ idempotencyKey, value }) => ({
+		key: makeMessageIdempotencyKey(namespace, runId, idempotencyKey),
+		value
+	}));
+}
+function idempotencyKeyFromRun(namespace, run) {
+	if (run.idempotencyKey === void 0) WorkflowStateError.runMissingIdempotencyKey(run.id);
+	return makeIdempotencyKey(namespace, {
+		workflowName: run.workflowName,
+		...run.workflowVersion === void 0 ? {} : { workflowVersion: run.workflowVersion },
+		idempotencyKey: run.idempotencyKey
+	});
+}
+function toCleanupIndex(entry) {
+	return {
+		key: entry.key,
+		value: toStorageValue(entry.value)
+	};
+}
+function isCurrentMessageIdempotencyIndex(eventIndexes, value) {
+	if (!isReadableMessageIdempotencyIndex(value)) return false;
+	return eventIndexes.some((eventIndex) => isSameMessageIdempotencyIndex(value, eventIndex.value));
+}
+function uniqueCleanupIndexKey(index, position, indexes) {
+	return indexes.findIndex((current) => current.key === index.key) === position;
+}
+async function cleanupRuns(storage, namespace, runs, options) {
+	const cleanupOptions = options;
+	const limit = cleanupOptions.limit;
+	const statusFilter = cleanupOptions.status ?? [
+		"completed",
+		"failed",
+		"canceled"
+	];
+	const selectedRuns = (await runs.listRuns({
+		status: Array.isArray(statusFilter) ? [...statusFilter] : statusFilter,
+		workflowName: cleanupOptions.workflowName,
+		workflowVersion: cleanupOptions.workflowVersion,
+		idempotencyKey: cleanupOptions.idempotencyKey,
+		parentRunId: cleanupOptions.parentRunId,
+		parentStepId: cleanupOptions.parentStepId,
+		parentStepName: cleanupOptions.parentStepName,
+		parentStepAttempt: cleanupOptions.parentStepAttempt
+	})).filter((run) => isWorkflowRunEligibleForCleanup(run, cleanupOptions)).sort(compareCleanupRuns).filter(isFirstCleanupRunForId).slice(0, limit);
+	const stepAttemptKeysByRun = await Promise.all(selectedRuns.map(async (run) => await stepAttemptKeysForCleanup(storage, namespace, run.id)));
+	const stepAttemptKeys = stepAttemptKeysByRun.flat();
+	const eventKeysByRun = selectedRuns.map((run) => makeEventsKey(namespace, run.id));
+	const storedEventsByRun = await Promise.all(eventKeysByRun.map(async (key) => {
+		const eventHistory = await getStoredCleanupEventHistory(storage, key);
+		return {
+			exists: eventHistory.raw !== void 0,
+			events: eventHistory.events
+		};
+	}));
+	const runEvents = storedEventsByRun.map((entry) => entry.events);
+	const eventKeysForCleanup = eventKeysByRun.map((key, index) => storedEventsByRun[index]?.exists === true ? key : void 0);
+	const eventKeys = eventKeysForCleanup.filter((key) => key !== void 0);
+	const runKeys = selectedRuns.map((run) => ({
+		key: makeRunKey(namespace, run.id),
+		run
+	}));
+	const idempotencyIndexesByRun = await Promise.all(selectedRuns.map(async (run) => await idempotencyIndexesForCleanup(storage, namespace, run)));
+	const idempotencyKeysByRun = idempotencyIndexesByRun.map((indexes) => indexes.map((index) => index.key));
+	const idempotencyKeys = idempotencyKeysByRun.flat();
+	const messageIdempotencyIndexesByRun = await Promise.all(selectedRuns.map(async (run, index) => await messageIdempotencyIndexesForCleanup(storage, namespace, run.id, runEvents[index] ?? [])));
+	const messageIdempotencyKeysByRun = messageIdempotencyIndexesByRun.map((indexes) => indexes.map((index) => index.key));
+	const messageIdempotencyKeys = messageIdempotencyKeysByRun.flat();
+	const deletionResults = cleanupOptions.dryRun === true ? selectedRuns.map(() => ({
+		cleanupMarkerCreated: false,
+		cleanupMarkerDeleted: false,
+		runDeleted: false,
+		deletedEvents: 0,
+		deletedStepAttempts: 0,
+		deletedIdempotencyKeys: 0,
+		deletedMessageIdempotencyKeys: 0
+	})) : await deleteCleanupRunsAndArtifacts(storage, {
+		namespace,
+		runs: runKeys,
+		eventKeysByRun: eventKeysForCleanup,
+		stepAttemptKeysByRun,
+		idempotencyIndexesByRun,
+		messageIdempotencyIndexesByRun
+	});
+	const deletedRuns = countCleanupDeletionResult(deletionResults, "runDeleted");
+	const createdCleanupMarkers = countCleanupDeletionResult(deletionResults, "cleanupMarkerCreated");
+	const deletedCleanupMarkers = countCleanupDeletionResult(deletionResults, "cleanupMarkerDeleted");
+	const deletedEvents = sumCleanupDeletionResult(deletionResults, "deletedEvents");
+	const deletedStepAttempts = sumCleanupDeletionResult(deletionResults, "deletedStepAttempts");
+	const deletedIdempotencyKeys = sumCleanupDeletionResult(deletionResults, "deletedIdempotencyKeys");
+	const deletedMessageIdempotencyKeys = sumCleanupDeletionResult(deletionResults, "deletedMessageIdempotencyKeys");
+	return {
+		mode: "best_effort",
+		runIds: selectedRuns.map((run) => run.id),
+		runs: selectedRuns.map((run, index) => ({
+			mode: "best_effort",
+			runId: run.id,
+			workflowName: run.workflowName,
+			...run.workflowVersion === void 0 ? {} : { workflowVersion: run.workflowVersion },
+			status: isTerminalWorkflowRunStatus(run.status) ? run.status : (() => {
+				WorkflowStateError.cleanupSelectedNonTerminalRun(run.id);
+			})(),
+			createdAt: run.createdAt,
+			updatedAt: run.updatedAt,
+			finishedAt: cleanupFinishedAt(run),
+			...run.idempotencyKey === void 0 ? {} : { idempotencyKey: run.idempotencyKey },
+			...run.parentRunId === void 0 ? {} : { parentRunId: run.parentRunId },
+			...run.parentStepId === void 0 ? {} : { parentStepId: run.parentStepId },
+			...run.parentStepName === void 0 ? {} : { parentStepName: run.parentStepName },
+			...run.parentStepAttempt === void 0 ? {} : { parentStepAttempt: run.parentStepAttempt },
+			events: runEvents[index]?.length ?? 0,
+			stepAttempts: stepAttemptKeysByRun[index]?.length ?? 0,
+			idempotencyKeys: idempotencyKeysByRun[index]?.length ?? 0,
+			messageIdempotencyKeys: messageIdempotencyKeysByRun[index]?.length ?? 0,
+			cleanupMarkerCreated: deletionResults[index]?.cleanupMarkerCreated ?? false,
+			cleanupMarkerDeleted: deletionResults[index]?.cleanupMarkerDeleted ?? false,
+			runDeleted: deletionResults[index]?.runDeleted ?? false,
+			deletedEvents: deletionResults[index]?.deletedEvents ?? 0,
+			deletedStepAttempts: deletionResults[index]?.deletedStepAttempts ?? 0,
+			deletedIdempotencyKeys: deletionResults[index]?.deletedIdempotencyKeys ?? 0,
+			deletedMessageIdempotencyKeys: deletionResults[index]?.deletedMessageIdempotencyKeys ?? 0
+		})),
+		...cleanupOptions.dryRun === true ? {
+			dryRun: true,
+			matchedRuns: selectedRuns.length,
+			matchedEvents: eventKeys.length,
+			matchedStepAttempts: stepAttemptKeys.length,
+			matchedIdempotencyKeys: idempotencyKeys.length,
+			matchedMessageIdempotencyKeys: messageIdempotencyKeys.length
+		} : {},
+		deletedRuns,
+		createdCleanupMarkers,
+		deletedCleanupMarkers,
+		deletedEvents,
+		deletedStepAttempts,
+		deletedIdempotencyKeys,
+		deletedMessageIdempotencyKeys
+	};
+}
+async function listCleanupMarkers(storage, namespace) {
+	const prefix = makeCleanupMarkerKeyPrefix(namespace);
+	return (await Promise.all((await storage.keys({ prefix })).filter((key) => isCleanupMarkerKey(key, prefix)).map(async (key) => await storage.get(key)))).flatMap((marker) => {
+		const parsed = readableCleanupMarkerRecord(marker);
+		return parsed === void 0 ? [] : [parsed];
+	}).sort(compareCleanupMarkers);
+}
+function isCleanupMarkerKey(key, prefix) {
+	return key.startsWith(prefix);
+}
+function compareCleanupMarkers(left, right) {
+	return Temporal.Instant.compare(left.cleanupStartedAt, right.cleanupStartedAt) || left.runId.localeCompare(right.runId);
+}
+function sumCleanupDeletionResult(results, key) {
+	return results.reduce((total, result) => total + result[key], 0);
+}
+function countCleanupDeletionResult(results, key) {
+	return results.filter((result) => result[key]).length;
+}
+function cleanupFinishedAt(run) {
+	if (run.finishedAt === void 0) WorkflowStateError.cleanupRunMissingFinishedAt(run.id);
+	return run.finishedAt;
+}
+function isWorkflowRunEligibleForCleanup(run, options) {
+	if (!isTerminalWorkflowRunStatus(run.status) || run.finishedAt === void 0) return false;
+	if (Temporal.Instant.compare(run.finishedAt, options.finishedAtBefore) >= 0) return false;
+	return options.status === void 0 || matchesCleanupStatus(run.status, options.status);
+}
+function matchesCleanupStatus(status, filter) {
+	return Array.isArray(filter) ? filter.includes(status) : status === filter;
+}
+function compareCleanupRuns(left, right) {
+	const finishedOrder = compareOptionalTimestamps(left.finishedAt, right.finishedAt);
+	if (finishedOrder !== 0) return finishedOrder;
+	const createdOrder = compareOptionalTimestamps(left.createdAt, right.createdAt);
+	if (createdOrder !== 0) return createdOrder;
+	return left.id.localeCompare(right.id);
+}
+function isFirstCleanupRunForId(run, index, runs) {
+	return runs.findIndex((entry) => entry.id === run.id) === index;
+}
+async function deleteCleanupRunsAndArtifacts(storage, options) {
+	const markers = await createCleanupMarkers(storage, options);
+	const deletedRuns = await deleteCleanupRunRecords(storage, options.runs);
+	return await Promise.all(deletedRuns.map(async (runDeleted, index) => {
+		const marker = markers[index];
+		if (!runDeleted) return {
+			cleanupMarkerCreated: marker?.created ?? false,
+			cleanupMarkerDeleted: false,
+			runDeleted: false,
+			deletedEvents: 0,
+			deletedStepAttempts: 0,
+			deletedIdempotencyKeys: 0,
+			deletedMessageIdempotencyKeys: 0
+		};
+		const eventKeys = options.eventKeysByRun[index] === void 0 ? [] : [options.eventKeysByRun[index]];
+		const [deletedEvents, deletedStepAttempts, deletedIdempotencyKeys, deletedMessageIdempotencyKeys] = await Promise.all([
+			storage.deleteMany(eventKeys),
+			storage.deleteMany(options.stepAttemptKeysByRun[index] ?? []),
+			deleteCleanupIndexes(storage, options.idempotencyIndexesByRun[index] ?? []),
+			deleteCleanupIndexes(storage, options.messageIdempotencyIndexesByRun[index] ?? [])
+		]);
+		const cleanupMarkerDeleted = marker?.key !== void 0 && deletionCompleted({
+			deletedEvents,
+			expectedEvents: eventKeys.length,
+			deletedStepAttempts,
+			expectedStepAttempts: options.stepAttemptKeysByRun[index]?.length ?? 0,
+			deletedIdempotencyKeys,
+			expectedIdempotencyKeys: options.idempotencyIndexesByRun[index]?.length ?? 0,
+			deletedMessageIdempotencyKeys,
+			expectedMessageIdempotencyKeys: options.messageIdempotencyIndexesByRun[index]?.length ?? 0
+		});
+		if (cleanupMarkerDeleted) await storage.delete(marker.key);
+		return {
+			cleanupMarkerCreated: marker?.created ?? false,
+			cleanupMarkerDeleted,
+			runDeleted: true,
+			deletedEvents,
+			deletedStepAttempts,
+			deletedIdempotencyKeys,
+			deletedMessageIdempotencyKeys
+		};
+	}));
+}
+async function createCleanupMarkers(storage, options) {
+	const cleanupStartedAt = Temporal.Now.instant();
+	return await Promise.all(options.runs.map(async ({ run }, index) => {
+		const key = makeCleanupMarkerKey(options.namespace, run.id);
+		const marker = {
+			mode: "best_effort",
+			runId: run.id,
+			workflowName: run.workflowName,
+			...run.workflowVersion === void 0 ? {} : { workflowVersion: run.workflowVersion },
+			status: isTerminalWorkflowRunStatus(run.status) ? run.status : (() => {
+				WorkflowStateError.cleanupSelectedNonTerminalRun(run.id);
+			})(),
+			createdAt: run.createdAt,
+			finishedAt: cleanupFinishedAt(run),
+			cleanupStartedAt,
+			events: options.eventKeysByRun[index] === void 0 ? 0 : 1,
+			stepAttempts: options.stepAttemptKeysByRun[index]?.length ?? 0,
+			idempotencyKeys: options.idempotencyIndexesByRun[index]?.length ?? 0,
+			messageIdempotencyKeys: options.messageIdempotencyIndexesByRun[index]?.length ?? 0
+		};
+		await storage.set(key, toStorageValue(marker));
+		return {
+			key,
+			created: true
+		};
+	}));
+}
+function deletionCompleted(options) {
+	return options.deletedEvents === options.expectedEvents && options.deletedStepAttempts === options.expectedStepAttempts && options.deletedIdempotencyKeys === options.expectedIdempotencyKeys && options.deletedMessageIdempotencyKeys === options.expectedMessageIdempotencyKeys;
+}
+async function deleteCleanupRunRecords(storage, runs) {
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		const deletedRuns = (await Promise.all(runs.map(async (run) => {
+			return await getReadableStoredWorkflowRun(storage, run.run.namespace, run.run.id);
+		}))).map((latest, index) => latest !== void 0 && isSameWorkflowStorageValue(omitUndefined(latest), omitUndefined(runs[index].run)));
+		await storage.deleteMany(runs.flatMap((run, index) => deletedRuns[index] === true ? [run.key] : []));
+		return deletedRuns;
+	}
+	return await Promise.all(runs.map(async (run) => await storage.compareAndSet(run.key, toStorageValue(run.run), void 0)));
+}
+//#endregion
+export { cleanupRuns, deleteCleanupIndexes, idempotencyIndexesForCleanup, listCleanupMarkers, messageIdempotencyIndexesForCleanup, stepAttemptKeysForCleanup };

package/dist/store/compaction.d.mts

@@ -0,0 +1,5 @@
+//#region src/store/compaction.d.ts
+/** Removes undefined optional fields before persisting a workflow store record. */
+declare function compactWorkflowStoreRecord<TRecord extends object>(record: TRecord): TRecord;
+//#endregion
+export { compactWorkflowStoreRecord };

package/dist/store/compaction.mjs

@@ -0,0 +1,8 @@
+import { omitUndefined } from "../collection.mjs";
+//#region src/store/compaction.ts
+/** Removes undefined optional fields before persisting a workflow store record. */
+function compactWorkflowStoreRecord(record) {
+	return omitUndefined(record);
+}
+//#endregion
+export { compactWorkflowStoreRecord };

package/dist/store/create.d.mts

@@ -0,0 +1,52 @@
+import { RunId } from "../types/run-id.mjs";
+import { CleanupMarkerRecord, CleanupRunsOptions, CleanupRunsResult } from "../types/cleanup.mjs";
+import { WorkflowPage } from "../types/pagination.mjs";
+import { ListSchedulesOptions, ListSchedulesPageOptions, ScheduleRecord } from "../types/schedule.mjs";
+import { LockRecord } from "../types/lock.mjs";
+import { WorkflowListRunsOptions, WorkflowListRunsPageOptions, WorkflowListStepAttemptsPageOptions } from "../types/run-list.mjs";
+import { WorkflowListStepAttemptsOptions, WorkflowStepAttemptRecord } from "../types/step-attempts.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { EventRecord } from "../types/events.mjs";
+import { CreateWorkflowStoreOptions, WorkflowClaimRunOptions, WorkflowEventHistoryChangeWaitOptions, WorkflowExtendRunLeaseOptions, WorkflowIdempotencyKeyOptions, WorkflowMessageIdempotencyIndex, WorkflowReleaseRunLeaseOptions, WorkflowStorage, WorkflowStore as WorkflowStore$1, WorkflowStoreCapabilities } from "../types/store.mjs";
+//#region src/store/create.d.ts
+declare function createWorkflowStore(options?: CreateWorkflowStoreOptions): WorkflowStore$1;
+/** Storage-backed workflow store implementation. */
+declare class WorkflowStore implements WorkflowStore$1 {
+  readonly storage: WorkflowStorage;
+  readonly namespace: string;
+  readonly capabilities: WorkflowStoreCapabilities;
+  constructor(options?: CreateWorkflowStoreOptions);
+  createRun(run: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+  getRun(runId: RunId): Promise<WorkflowRunRecord | undefined>;
+  getRunByIdempotencyKey(options: WorkflowIdempotencyKeyOptions): Promise<WorkflowRunRecord | undefined>;
+  updateRun(run: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+  updateRunIfCurrent(current: WorkflowRunRecord, next: WorkflowRunRecord): Promise<WorkflowRunRecord | undefined>;
+  listRuns(options?: WorkflowListRunsOptions): Promise<readonly WorkflowRunRecord[]>;
+  listRunsPage(options?: WorkflowListRunsPageOptions): Promise<WorkflowPage<WorkflowRunRecord>>;
+  countRuns(options?: WorkflowListRunsOptions): Promise<number>;
+  claimRun(options: WorkflowClaimRunOptions): Promise<WorkflowRunRecord | undefined>;
+  extendRunLease(options: WorkflowExtendRunLeaseOptions): Promise<WorkflowRunRecord | undefined>;
+  releaseRunLease(options: WorkflowReleaseRunLeaseOptions): Promise<WorkflowRunRecord | undefined>;
+  appendEvent(runId: RunId, event: EventRecord): Promise<readonly EventRecord[]>;
+  appendEventIfRunCurrent(current: WorkflowRunRecord, event: EventRecord): Promise<readonly EventRecord[] | undefined>;
+  getEvents(runId: RunId): Promise<readonly EventRecord[]>;
+  waitForEventHistoryChange(runId: RunId, options?: WorkflowEventHistoryChangeWaitOptions): Promise<void>;
+  listStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<readonly WorkflowStepAttemptRecord[]>;
+  listStepAttemptsPage(runId: RunId, options?: WorkflowListStepAttemptsPageOptions): Promise<WorkflowPage<WorkflowStepAttemptRecord>>;
+  countStepAttempts(runId: RunId, options?: WorkflowListStepAttemptsOptions): Promise<number>;
+  repairStepAttempts(runId: RunId): Promise<readonly WorkflowStepAttemptRecord[]>;
+  repairMessageIdempotencyIndexes(runId: RunId): Promise<readonly WorkflowMessageIdempotencyIndex[]>;
+  hasMessageIdempotencyKey(runId: RunId, idempotencyKey: string): Promise<boolean>;
+  cleanupRuns(options: CleanupRunsOptions): Promise<CleanupRunsResult>;
+  listCleanupMarkers(): Promise<readonly CleanupMarkerRecord[]>;
+  createSchedule<TInput>(schedule: ScheduleRecord<TInput>): Promise<ScheduleRecord<TInput>>;
+  getSchedule(scheduleId: string): Promise<ScheduleRecord | undefined>;
+  updateScheduleIfCurrent<TInput>(current: ScheduleRecord, next: ScheduleRecord<TInput>): Promise<ScheduleRecord<TInput> | undefined>;
+  listSchedules(options?: ListSchedulesOptions): Promise<readonly ScheduleRecord[]>;
+  listSchedulesPage(options?: ListSchedulesPageOptions): Promise<WorkflowPage<ScheduleRecord>>;
+  getLock(key: string): Promise<LockRecord | undefined>;
+  listLocks(): Promise<readonly LockRecord[]>;
+  updateLockIfCurrent(current: LockRecord | undefined, next: LockRecord): Promise<LockRecord | undefined>;
+}
+//#endregion
+export { WorkflowStore, createWorkflowStore };

package/dist/store/create.mjs

@@ -0,0 +1,159 @@
+import { getWorkflowStoreCapabilities } from "./capabilities.mjs";
+import { makeEventsKey } from "../store-keys.mjs";
+import { claimWorkflowRun, countWorkflowRuns, extendWorkflowRunLease, getWorkflowRun, listWorkflowRuns, listWorkflowRunsPage, releaseWorkflowRunLease, updateRunIfCurrent, updateWorkflowRun } from "./run.mjs";
+import { hasMessageIdempotencyKey, repairMessageIdempotencyIndexes } from "./message-index.mjs";
+import { cleanupRuns, listCleanupMarkers } from "./cleanup.mjs";
+import { appendWorkflowEvent, appendWorkflowEventIfRunCurrent, getWorkflowEvents } from "./event.mjs";
+import { createRunWithIdempotency, getRunByIdempotencyKey } from "./idempotency.mjs";
+import { getReadableLock, listReadableLocks, updateLockIfCurrent } from "./lock.mjs";
+import { createSchedule, getReadableSchedule, listSchedules, listSchedulesPage, updateScheduleIfCurrent } from "./schedule.mjs";
+import { countWorkflowStepAttempts, listWorkflowStepAttempts, listWorkflowStepAttemptsPage, repairWorkflowStepAttempts } from "./step-attempt.mjs";
+import { createStorage } from "@temelj/storage";
+//#region src/store/create.ts
+function createWorkflowStore(options = {}) {
+	return new WorkflowStore(options);
+}
+/** Storage-backed workflow store implementation. */
+var WorkflowStore = class {
+	storage;
+	namespace;
+	capabilities;
+	constructor(options = {}) {
+		this.storage = options.storage ?? createStorage();
+		this.namespace = options.namespace ?? "default";
+		this.capabilities = getWorkflowStoreCapabilities(this.storage);
+	}
+	async createRun(run) {
+		return createRunWithIdempotency(this.storage, this.namespace, this, run);
+	}
+	async getRun(runId) {
+		return getWorkflowRun(this.storage, this.namespace, runId);
+	}
+	async getRunByIdempotencyKey(options) {
+		return getRunByIdempotencyKey(this.storage, this.namespace, this, options);
+	}
+	async updateRun(run) {
+		return updateWorkflowRun(this.storage, this.namespace, this, run);
+	}
+	async updateRunIfCurrent(current, next) {
+		return updateRunIfCurrent(this.storage, this.namespace, this, current, next);
+	}
+	async listRuns(options) {
+		return listWorkflowRuns(this.storage, this.namespace, options);
+	}
+	async listRunsPage(options) {
+		return listWorkflowRunsPage(this.storage, this.namespace, options);
+	}
+	async countRuns(options) {
+		return countWorkflowRuns(this.storage, this.namespace, options);
+	}
+	async claimRun(options) {
+		return claimWorkflowRun(this.storage, this.namespace, this, options);
+	}
+	async extendRunLease(options) {
+		return extendWorkflowRunLease(this.storage, this.namespace, this, options);
+	}
+	async releaseRunLease(options) {
+		return releaseWorkflowRunLease(this.storage, this.namespace, this, options);
+	}
+	async appendEvent(runId, event) {
+		return appendWorkflowEvent(this.storage, this.namespace, runId, event);
+	}
+	async appendEventIfRunCurrent(current, event) {
+		return appendWorkflowEventIfRunCurrent(this.storage, this.namespace, current, event);
+	}
+	async getEvents(runId) {
+		return getWorkflowEvents(this.storage, this.namespace, runId);
+	}
+	async waitForEventHistoryChange(runId, options = {}) {
+		if (options.signal?.aborted === true) return;
+		const key = makeEventsKey(this.namespace, runId);
+		await new Promise((resolve) => {
+			let settled = false;
+			let unwatch;
+			const finish = () => {
+				if (settled) return;
+				settled = true;
+				options.signal?.removeEventListener("abort", finish);
+				disposeWorkflowStoreWatcher(unwatch);
+				resolve();
+			};
+			options.signal?.addEventListener("abort", finish, { once: true });
+			this.storage.watch((event) => {
+				if (isWorkflowStorageChangeForKey(event, key)) finish();
+			}).then((unsubscribe) => {
+				unwatch = unsubscribe;
+				if (settled) disposeWorkflowStoreWatcher(unwatch);
+			}).catch(() => {
+				finish();
+			});
+		});
+	}
+	async listStepAttempts(runId, options) {
+		return listWorkflowStepAttempts(this.storage, this.namespace, this, runId, options);
+	}
+	async listStepAttemptsPage(runId, options) {
+		return listWorkflowStepAttemptsPage(this.storage, this.namespace, this, runId, options);
+	}
+	async countStepAttempts(runId, options) {
+		return countWorkflowStepAttempts(this.storage, this.namespace, this, runId, options);
+	}
+	async repairStepAttempts(runId) {
+		return repairWorkflowStepAttempts(this.storage, this.namespace, this, runId);
+	}
+	async repairMessageIdempotencyIndexes(runId) {
+		return repairMessageIdempotencyIndexes(this.storage, this.namespace, runId);
+	}
+	async hasMessageIdempotencyKey(runId, idempotencyKey) {
+		return hasMessageIdempotencyKey(this.storage, this.namespace, runId, idempotencyKey);
+	}
+	async cleanupRuns(options) {
+		return cleanupRuns(this.storage, this.namespace, this, options);
+	}
+	async listCleanupMarkers() {
+		return listCleanupMarkers(this.storage, this.namespace);
+	}
+	async createSchedule(schedule) {
+		return createSchedule(this.storage, this.namespace, schedule);
+	}
+	async getSchedule(scheduleId) {
+		return getReadableSchedule(this.storage, this.namespace, scheduleId);
+	}
+	async updateScheduleIfCurrent(current, next) {
+		return updateScheduleIfCurrent(this.storage, this.namespace, current, next);
+	}
+	async listSchedules(options) {
+		return listSchedules(this.storage, this.namespace, options);
+	}
+	async listSchedulesPage(options) {
+		return listSchedulesPage(this.storage, this.namespace, options);
+	}
+	async getLock(key) {
+		return getReadableLock(this.storage, this.namespace, key);
+	}
+	async listLocks() {
+		return listReadableLocks(this.storage, this.namespace);
+	}
+	async updateLockIfCurrent(current, next) {
+		return updateLockIfCurrent(this.storage, this.namespace, current, next);
+	}
+};
+function disposeWorkflowStoreWatcher(unwatch) {
+	if (unwatch === void 0) return;
+	ignoreWorkflowStoreWatcherDisposal(unwatch());
+}
+function ignoreWorkflowStoreWatcherDisposal(result) {
+	if (result === void 0) return;
+	result.catch(() => {});
+}
+function isWorkflowStorageChangeForKey(event, key) {
+	switch (event.type) {
+		case "set":
+		case "delete": return event.key === key;
+		case "setMany":
+		case "deleteMany": return event.keys.includes(key);
+		case "clear": return event.prefix === void 0 || key.startsWith(event.prefix);
+	}
+}
+//#endregion
+export { WorkflowStore, createWorkflowStore };

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

@@ -0,0 +1,15 @@
+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 { WorkflowEventAppendOutcome, WorkflowEventAppendSuccessOutcome } from "./event-append.mjs";
+import { WorkflowAppendProjectionPipeline } from "./append-projection.mjs";
+//#region src/store/event-append-project.d.ts
+interface WorkflowEventAppendProjectionOutcome {
+  readonly outcome: WorkflowEventAppendOutcome;
+  readonly projectionPipeline?: WorkflowAppendProjectionPipeline;
+}
+declare function appendEventWithProjections(storage: WorkflowStorage, namespace: string, runId: RunId, event: EventRecord, projectionPipeline?: WorkflowAppendProjectionPipeline): Promise<WorkflowEventAppendSuccessOutcome>;
+declare function appendEventWithProjectionPipelineIfRunCurrent(storage: WorkflowStorage, namespace: string, currentRun: WorkflowRunRecord, event: EventRecord): Promise<WorkflowEventAppendProjectionOutcome>;
+//#endregion
+export { WorkflowEventAppendProjectionOutcome, appendEventWithProjectionPipelineIfRunCurrent, appendEventWithProjections };

package/dist/store/event-append-project.mjs

@@ -0,0 +1,77 @@
+import { supportsWorkflowAtomicBatchWrite, supportsWorkflowConditionalWrite } from "./capabilities.mjs";
+import { isStoredWorkflowRunRevisionCurrent, isWorkflowRunStaleForAppend, rollbackAppendedEventIfRunStale } from "./run.mjs";
+import { duplicateMessageAppendOutcome } from "./message-index.mjs";
+import { createWorkflowAppendProjectionPipeline } from "./append-projection.mjs";
+import { appendEventIfCurrent, appendEventIfRunRevisionCurrentAtomically, appendEventWithAtomicProjectionPlan, makeStaleRunAppendOutcome } from "./event-append.mjs";
+//#region src/store/event-append-project.ts
+async function appendEventWithProjections(storage, namespace, runId, event, projectionPipeline) {
+	const appendProjectionPipeline = projectionPipeline ?? await createWorkflowAppendProjectionPipeline(storage, namespace, runId, event);
+	const outcome = await appendEventWithAtomicProjectionPlan(storage, namespace, runId, event, appendProjectionPipeline.planAtomicProjections, duplicateMessageAppendOutcome);
+	await appendProjectionPipeline.finalizePostCommit(outcome);
+	return outcome;
+}
+async function appendEventWithProjectionPipelineIfRunCurrent(storage, namespace, currentRun, event) {
+	const runId = currentRun.id;
+	if (isWorkflowRunStaleForAppend(currentRun, event)) return { outcome: makeStaleRunAppendOutcome() };
+	const projectionPipeline = await createWorkflowAppendProjectionPipeline(storage, namespace, runId, event);
+	if (event.kind === "message_sent" && !supportsWorkflowAtomicBatchWrite(storage)) return await appendMessageEventIfRunCurrent(storage, namespace, currentRun, event, projectionPipeline);
+	if (!supportsWorkflowAtomicBatchWrite(storage) || projectionPipeline.materializesAtomically) return workflowEventAppendProjectionOutcome(await appendEventIfRunRevisionCurrentWithPostAppendGuard(storage, namespace, currentRun, event, projectionPipeline), projectionPipeline);
+	return workflowEventAppendProjectionOutcome(await appendEventIfRunRevisionCurrentAtomically(storage, namespace, currentRun, event, duplicateMessageAppendOutcome), projectionPipeline);
+}
+function workflowEventAppendProjectionOutcome(outcome, projectionPipeline) {
+	if (projectionPipeline === void 0) return { outcome };
+	return {
+		outcome,
+		projectionPipeline
+	};
+}
+async function appendEventIfRunRevisionCurrentWithPostAppendGuard(storage, namespace, currentRun, event, projectionPipeline) {
+	const runId = currentRun.id;
+	if (!await isStoredWorkflowRunRevisionCurrent(storage, namespace, currentRun)) return makeStaleRunAppendOutcome();
+	const outcome = await appendEventWithProjections(storage, namespace, runId, event, projectionPipeline);
+	if (outcome.status !== "appended") return outcome;
+	return await guardAppendedEventAgainstStaleRun(storage, namespace, runId, event, outcome);
+}
+async function appendMessageEventIfRunCurrent(storage, namespace, currentRun, event, projectionPipeline) {
+	const runId = currentRun.id;
+	if (!await isStoredWorkflowRunRevisionCurrent(storage, namespace, currentRun)) return { outcome: makeStaleRunAppendOutcome() };
+	if (!supportsWorkflowConditionalWrite(storage)) {
+		const outcome = await appendEventWithProjections(storage, namespace, runId, event, projectionPipeline);
+		if (outcome.status !== "appended") return {
+			outcome,
+			projectionPipeline
+		};
+		return {
+			outcome: await guardAppendedEventAgainstStaleRun(storage, namespace, runId, event, outcome),
+			projectionPipeline
+		};
+	}
+	const outcome = await appendEventIfCurrent(storage, namespace, runId, event, { detectDuplicate: duplicateMessageAppendOutcome });
+	if (outcome.status !== "appended") {
+		if (!await isStoredWorkflowRunRevisionCurrent(storage, namespace, currentRun)) return {
+			outcome: makeStaleRunAppendOutcome(),
+			projectionPipeline
+		};
+		return {
+			outcome,
+			projectionPipeline
+		};
+	}
+	if (!await isStoredWorkflowRunRevisionCurrent(storage, namespace, currentRun)) {
+		await guardAppendedEventAgainstStaleRun(storage, namespace, runId, event, outcome);
+		return {
+			outcome: makeStaleRunAppendOutcome(),
+			projectionPipeline
+		};
+	}
+	return {
+		outcome: await guardAppendedEventAgainstStaleRun(storage, namespace, runId, event, outcome),
+		projectionPipeline
+	};
+}
+async function guardAppendedEventAgainstStaleRun(storage, namespace, runId, event, outcome) {
+	if (await rollbackAppendedEventIfRunStale(storage, namespace, runId, event, outcome.events)) return makeStaleRunAppendOutcome();
+	return outcome;
+}
+//#endregion
+export { appendEventWithProjectionPipelineIfRunCurrent, appendEventWithProjections };