@temelj/workflow 0.0.0-alpha.1

package/dist/engine/run-data.mjs

@@ -0,0 +1,74 @@
+import { normalizeWorkflowAttributePatch, workflowAttributeEventPatch, workflowAttributePatchFromEvent } from "../attributes.mjs";
+import { toPersistedValue } from "./serialization.mjs";
+import { WorkflowStaleExecutionError, appendEventIfCurrentExecution, patchCurrentExecutionRun, patchCurrentExecutionRunAttributes } from "./state.mjs";
+import { resolveWorkflowCommandIdentity } from "./command-identity.mjs";
+import { requireAttributesReplayMatches, requireMetadataReplayMatches } from "./replay.mjs";
+//#region src/engine/run-data.ts
+function createWorkflowRunDataApi(environment) {
+	return {
+		async setMetadata(commandId, metadata) {
+			await setWorkflowRunMetadata(environment, commandId, metadata);
+		},
+		async setAttributes(commandId, attributes) {
+			await setWorkflowRunAttributes(environment, commandId, attributes);
+		}
+	};
+}
+async function setWorkflowRunMetadata(environment, commandId, metadata) {
+	const { store, runId, history, now, limits, executionOwner } = environment;
+	const identity = resolveWorkflowCommandIdentity(history, "metadata", commandId);
+	const persistedMetadata = toPersistedValue(metadata, "workflow run metadata", limits);
+	const recorded = history.metadataSet(identity.id);
+	if (recorded !== void 0) {
+		requireMetadataReplayMatches(identity, recorded, persistedMetadata);
+		const updated = await patchCurrentExecutionRun(store, executionOwner, {
+			metadata: recorded.metadata,
+			updatedAt: recorded.timestamp
+		});
+		if (updated === void 0) WorkflowStaleExecutionError.stale(executionOwner.id);
+		Object.assign(executionOwner, updated);
+		return;
+	}
+	const timestamp = now();
+	await appendEventIfCurrentExecution(store, history, {
+		kind: "metadata_set",
+		timestamp,
+		stepId: identity.id,
+		stepName: identity.name,
+		count: identity.count,
+		metadata: persistedMetadata
+	}, executionOwner, limits, void 0, (event, events) => environment.observeDurableEventAppended?.(runId, event, events));
+	const updated = await patchCurrentExecutionRun(store, executionOwner, {
+		metadata: persistedMetadata,
+		updatedAt: timestamp
+	});
+	if (updated === void 0) WorkflowStaleExecutionError.stale(executionOwner.id);
+	Object.assign(executionOwner, updated);
+}
+async function setWorkflowRunAttributes(environment, commandId, attributes) {
+	const { store, runId, history, now, limits, executionOwner } = environment;
+	const identity = resolveWorkflowCommandIdentity(history, "attributes", commandId);
+	const normalized = normalizeWorkflowAttributePatch(attributes);
+	const recorded = history.attributesSet(identity.id);
+	if (recorded !== void 0) {
+		requireAttributesReplayMatches(identity, recorded, normalized);
+		const updated = await patchCurrentExecutionRunAttributes(store, executionOwner, workflowAttributePatchFromEvent(recorded), recorded.timestamp);
+		if (updated === void 0) WorkflowStaleExecutionError.stale(executionOwner.id);
+		Object.assign(executionOwner, updated);
+		return;
+	}
+	const timestamp = now();
+	await appendEventIfCurrentExecution(store, history, {
+		kind: "attributes_set",
+		timestamp,
+		stepId: identity.id,
+		stepName: identity.name,
+		count: identity.count,
+		...workflowAttributeEventPatch(normalized)
+	}, executionOwner, limits, void 0, (event, events) => environment.observeDurableEventAppended?.(runId, event, events));
+	const updated = await patchCurrentExecutionRunAttributes(store, executionOwner, normalized, timestamp);
+	if (updated === void 0) WorkflowStaleExecutionError.stale(executionOwner.id);
+	Object.assign(executionOwner, updated);
+}
+//#endregion
+export { createWorkflowRunDataApi, setWorkflowRunAttributes, setWorkflowRunMetadata };

package/dist/engine/run-service.d.mts

@@ -0,0 +1,38 @@
+import { RunId } from "../types/run-id.mjs";
+import { WorkflowDefinition } from "../types/definition.mjs";
+import { WorkflowHandle } from "../types/result.mjs";
+import { WorkflowAttributePatch, WorkflowRunRecord, WorkflowRunWorkflowName, WorkflowRunWorkflowVersion } from "../types/run.mjs";
+import { WorkflowMarkRunPermanentlyFailedOptions, WorkflowReleaseStaleLeaseOptions, WorkflowRerunOptions, WorkflowRescheduleRunOptions, WorkflowRetryFailedRunOptions, WorkflowStartOptions } from "../types/run-options.mjs";
+import { WorkflowEventReader, WorkflowLockConditionalWriterRepository, WorkflowLockListerRepository, WorkflowRunReaderRepository, WorkflowRunWriterRepository, WorkflowStepAttemptLookup } from "../types/store.mjs";
+//#region src/engine/run-service.d.ts
+type WorkflowRunServiceStore = WorkflowRunReaderRepository & WorkflowRunWriterRepository & WorkflowEventReader & WorkflowStepAttemptLookup & WorkflowLockListerRepository & WorkflowLockConditionalWriterRepository;
+interface WorkflowRunServiceOptions {
+  readonly store: WorkflowRunServiceStore;
+  readonly now: () => Temporal.Instant;
+  readonly limits: {
+    readonly maximumPersistedValueBytes?: number;
+  };
+}
+interface WorkflowRunLifecycleEmitter {
+  readonly emitLifecycleEvent: (next: WorkflowRunRecord, previous: WorkflowRunRecord) => void | Promise<void>;
+}
+interface WorkflowRunMetadataUpdateEmitter {
+  readonly emitRunMetadataUpdated: (next: WorkflowRunRecord, previous: WorkflowRunRecord) => void;
+}
+declare function rerunWorkflowRun(service: WorkflowRunServiceOptions, startWorkflow: <TOutput = unknown>(definition: WorkflowDefinition<unknown, TOutput, unknown>, input: unknown, options?: WorkflowStartOptions) => Promise<WorkflowHandle<TOutput>>, runId: RunId, rerunOptions: WorkflowRerunOptions | undefined): Promise<WorkflowHandle<unknown>>;
+declare function resolveRerunWorkflowDefinition(sourceRun: WorkflowRerunSourceRun, options: WorkflowRerunOptions | undefined): Promise<WorkflowDefinition<unknown, unknown, unknown>>;
+interface WorkflowRerunSourceRun {
+  readonly workflowName: WorkflowRunWorkflowName;
+  readonly workflowVersion?: WorkflowRunWorkflowVersion;
+}
+declare function rescheduleWorkflowRun(service: WorkflowRunServiceOptions, lifecycle: WorkflowRunLifecycleEmitter, runId: RunId, rescheduleOptions: WorkflowRescheduleRunOptions | undefined): Promise<WorkflowRunRecord>;
+declare function releaseStaleWorkflowRunLease(service: WorkflowRunServiceOptions, lifecycle: WorkflowRunLifecycleEmitter, runId: RunId, releaseOptions: WorkflowReleaseStaleLeaseOptions | undefined): Promise<WorkflowRunRecord>;
+declare function retryFailedWorkflowRun(service: WorkflowRunServiceOptions, lifecycle: WorkflowRunLifecycleEmitter, runId: RunId, retryOptions: WorkflowRetryFailedRunOptions | undefined): Promise<WorkflowRunRecord>;
+declare function markWorkflowRunPermanentlyFailed(service: WorkflowRunServiceOptions, lifecycle: WorkflowRunLifecycleEmitter, runId: RunId, permanentFailureOptions: WorkflowMarkRunPermanentlyFailedOptions): Promise<WorkflowRunRecord>;
+declare function updateWorkflowRunMetadata(service: WorkflowRunServiceOptions, lifecycle: WorkflowRunMetadataUpdateEmitter, runId: RunId, metadata: unknown): Promise<WorkflowRunRecord>;
+declare function setWorkflowRunAttributes(service: WorkflowRunServiceOptions, runId: RunId, attributes: WorkflowAttributePatch): Promise<WorkflowRunRecord>;
+declare function cancelWorkflowRun(service: WorkflowRunServiceOptions, lifecycle: WorkflowRunLifecycleEmitter, runId: RunId): Promise<WorkflowRunRecord>;
+declare function resolveWorkflowVersion(workflowName: string, fallbackVersion: string | undefined, resolver: ((workflowName: string, definition: WorkflowDefinition<unknown, unknown, unknown>) => string | undefined | Promise<string | undefined>) | undefined): Promise<string | undefined>;
+declare function resolveWorkflowStartSpec<TInput, TOutput, TRawInput>(definition: WorkflowDefinition<TInput, TOutput, TRawInput>, options: WorkflowStartOptions | undefined): Promise<WorkflowDefinition<TInput, TOutput, TRawInput>>;
+//#endregion
+export { cancelWorkflowRun, markWorkflowRunPermanentlyFailed, releaseStaleWorkflowRunLease, rerunWorkflowRun, rescheduleWorkflowRun, resolveRerunWorkflowDefinition, resolveWorkflowStartSpec, resolveWorkflowVersion, retryFailedWorkflowRun, setWorkflowRunAttributes, updateWorkflowRunMetadata };

package/dist/engine/run-service.mjs

@@ -0,0 +1,133 @@
+import { WorkflowStateError } from "../errors/base.mjs";
+import { WorkflowPermanentFailureError } from "../errors/failures.mjs";
+import { getRequiredRun, isScheduledWorkflowRunStatus, nextRunAttempt } from "../utility.mjs";
+import { normalizeWorkflowAttributePatch } from "../attributes.mjs";
+import "../errors/mod.mjs";
+import { defineWorkflowFromName } from "../definition.mjs";
+import "./retry-policy.mjs";
+import { serializeError, toPersistedValue } from "./serialization.mjs";
+import { cancelRunWithChildren, releaseLocksForRun, setRunAttributesIfCurrent, transitionRunAfterStaleLeaseRelease, transitionRunToManualRetry, transitionRunToPermanentFailure, transitionRunToRescheduled, updateRunMetadataIfCurrent } from "./state.mjs";
+//#region src/engine/run-service.ts
+async function rerunWorkflowRun(service, startWorkflow, runId, rerunOptions) {
+	const sourceRun = await getRequiredRun(service.store, runId);
+	const options = rerunOptions;
+	const definition = await resolveRerunWorkflowDefinition(sourceRun, options);
+	const start = options?.start;
+	return await startWorkflow(definition, sourceRun.input, {
+		...sourceRun.context === void 0 ? {} : { context: sourceRun.context },
+		...start
+	});
+}
+async function resolveRerunWorkflowDefinition(sourceRun, options) {
+	const workflowName = options?.workflowName ?? sourceRun.workflowName;
+	return defineWorkflowFromName(workflowName, await resolveWorkflowVersion(workflowName, options !== void 0 && "workflowVersion" in options ? options.workflowVersion : sourceRun.workflowVersion, options?.workflowVersionResolver));
+}
+async function rescheduleWorkflowRun(service, lifecycle, runId, rescheduleOptions) {
+	const options = rescheduleOptions;
+	const now = service.now();
+	const availableAt = options?.availableAt ?? now;
+	for (let attempt = 0; attempt < 16; attempt++) {
+		const current = await getRequiredRun(service.store, runId);
+		if (!isScheduledWorkflowRunStatus(current.status)) WorkflowStateError.runCannotBeRescheduled(runId);
+		if (current.availableAt !== void 0 && Temporal.Instant.compare(current.availableAt, availableAt) === 0 && current.lastTransitionReason === "rescheduled") return current;
+		const updated = await service.store.updateRunIfCurrent(current, transitionRunToRescheduled(current, now, availableAt));
+		if (updated !== void 0) {
+			await releaseLocksForRun(service.store, updated.id, now);
+			await lifecycle.emitLifecycleEvent(updated, current);
+			return updated;
+		}
+	}
+	WorkflowStateError.failedRunReschedule(runId);
+}
+async function releaseStaleWorkflowRunLease(service, lifecycle, runId, releaseOptions) {
+	const options = releaseOptions;
+	const now = service.now();
+	const availableAt = options?.availableAt ?? now;
+	for (let attempt = 0; attempt < 16; attempt++) {
+		const current = await getRequiredRun(service.store, runId);
+		if (isScheduledWorkflowRunStatus(current.status)) return current;
+		if (current.status !== "running") WorkflowStateError.staleLeaseReleaseRequiresRunning(runId);
+		if (current.workerId !== void 0 && typeof current.workerId === "string" && current.workerId.trim() !== "" && current.leaseExpiresAt !== void 0 && Temporal.Instant.compare(current.leaseExpiresAt, now) > 0) WorkflowStateError.runLeaseStillActive(runId);
+		const updated = await service.store.updateRunIfCurrent(current, transitionRunAfterStaleLeaseRelease(current, now, availableAt));
+		if (updated !== void 0) {
+			await lifecycle.emitLifecycleEvent(updated, current);
+			return updated;
+		}
+	}
+	WorkflowStateError.failedStaleRunLeaseRelease(runId);
+}
+async function retryFailedWorkflowRun(service, lifecycle, runId, retryOptions) {
+	const options = retryOptions;
+	const now = service.now();
+	const availableAt = options?.availableAt ?? now;
+	for (let attempt = 0; attempt < 16; attempt++) {
+		const current = await getRequiredRun(service.store, runId);
+		if (isScheduledWorkflowRunStatus(current.status)) return current;
+		if (current.status !== "failed") WorkflowStateError.runRetryRequiresFailed(runId);
+		if (current.lastTransitionReason === "permanent_failure" && options?.force !== true) WorkflowStateError.runRetryRequiresForceAfterPermanentFailure(runId);
+		if (options?.force !== true && current.retryReason === void 0 && current.retryAt === void 0) WorkflowStateError.failedRunRetryRequiresForce(runId);
+		const retryAttempt = nextRunAttempt(current.retryAttempt);
+		const updated = await service.store.updateRunIfCurrent(current, transitionRunToManualRetry(current, now, availableAt, retryAttempt));
+		if (updated !== void 0) {
+			await lifecycle.emitLifecycleEvent(updated, current);
+			return updated;
+		}
+	}
+	WorkflowStateError.failedRunRetry(runId);
+}
+async function markWorkflowRunPermanentlyFailed(service, lifecycle, runId, permanentFailureOptions) {
+	const now = service.now();
+	const reason = permanentFailureOptions.reason;
+	for (let attempt = 0; attempt < 16; attempt++) {
+		const current = await getRequiredRun(service.store, runId);
+		if (current.status === "completed" || current.status === "canceled") WorkflowStateError.permanentFailureInvalidStatus(runId, current.status);
+		if (current.status === "failed" && current.lastTransitionReason === "permanent_failure" && current.error?.details?.reason === reason) return current;
+		const updated = await service.store.updateRunIfCurrent(current, transitionRunToPermanentFailure(current, serializeError(WorkflowPermanentFailureError.create({
+			runId,
+			reason
+		})), now));
+		if (updated !== void 0) {
+			await lifecycle.emitLifecycleEvent(updated, current);
+			return updated;
+		}
+	}
+	WorkflowStateError.failedPermanentRunFailure(runId);
+}
+async function updateWorkflowRunMetadata(service, lifecycle, runId, metadata) {
+	const persistedMetadata = toPersistedValue(metadata, "workflow run metadata", service.limits);
+	const timestamp = service.now();
+	const previousRun = await getRequiredRun(service.store, runId);
+	const updatedRun = await updateRunMetadataIfCurrent(service.store, runId, persistedMetadata, timestamp);
+	lifecycle.emitRunMetadataUpdated(updatedRun, previousRun);
+	return updatedRun;
+}
+async function setWorkflowRunAttributes(service, runId, attributes) {
+	const normalized = normalizeWorkflowAttributePatch(attributes);
+	const timestamp = service.now();
+	return await setRunAttributesIfCurrent(service.store, runId, normalized, timestamp);
+}
+async function cancelWorkflowRun(service, lifecycle, runId) {
+	const previousRun = await getRequiredRun(service.store, runId);
+	const canceledRun = await cancelRunWithChildren(service.store, runId, service.now());
+	if (previousRun.status !== "canceled") await lifecycle.emitLifecycleEvent(canceledRun, previousRun);
+	return canceledRun;
+}
+async function resolveWorkflowVersion(workflowName, fallbackVersion, resolver) {
+	if (resolver === void 0) return fallbackVersion;
+	const resolved = await resolver(workflowName, defineWorkflowFromName(workflowName, fallbackVersion));
+	return typeof resolved === "string" && resolved.trim() !== "" ? resolved : fallbackVersion;
+}
+async function resolveWorkflowStartSpec(definition, options) {
+	const version = await resolveWorkflowVersion(definition.name, options?.workflowVersion ?? definition.version, options?.workflowVersionResolver);
+	if (version === definition.version) return definition;
+	return {
+		...definition,
+		version,
+		config: {
+			...definition.config,
+			...version === void 0 ? { version: void 0 } : { version }
+		}
+	};
+}
+//#endregion
+export { cancelWorkflowRun, markWorkflowRunPermanentlyFailed, releaseStaleWorkflowRunLease, rerunWorkflowRun, rescheduleWorkflowRun, resolveRerunWorkflowDefinition, resolveWorkflowStartSpec, resolveWorkflowVersion, retryFailedWorkflowRun, setWorkflowRunAttributes, updateWorkflowRunMetadata };

package/dist/engine/run-utils.d.mts

@@ -0,0 +1,16 @@
+import { RunId } from "../types/run-id.mjs";
+import { CleanupRunsOptions, RetentionPolicyOptions } from "../types/cleanup.mjs";
+import { WorkflowDefinition } from "../types/definition.mjs";
+import { CompletedResult, ExecutionResult, HandleOperations, WorkflowHandle } from "../types/result.mjs";
+import { WorkflowRunRecord } from "../types/run.mjs";
+import { WorkflowEventReader, WorkflowRunReaderRepository } from "../types/store.mjs";
+//#region src/engine/run-utils.d.ts
+type WorkflowRunLookup = WorkflowRunReaderRepository;
+type WorkflowHandleStore = WorkflowRunLookup & WorkflowEventReader;
+declare function retentionCleanupOptions(options: RetentionPolicyOptions, engineNow: () => Temporal.Instant): CleanupRunsOptions;
+declare function workflowHandle<TOutput>(store: WorkflowHandleStore, definition: WorkflowDefinition<unknown, TOutput>, runId: RunId, now: () => Temporal.Instant, operations: HandleOperations): WorkflowHandle<TOutput>;
+declare function readRunResult<TOutput>(store: WorkflowRunLookup, runId: RunId, fallbackAvailableAt: Temporal.Instant): Promise<ExecutionResult<TOutput>>;
+declare function makeCompletedRunResult<TOutput>(run: WorkflowRunRecord): CompletedResult<TOutput>;
+declare function makeCanceledRunResult<TOutput>(run: WorkflowRunRecord): ExecutionResult<TOutput>;
+//#endregion
+export { makeCanceledRunResult, makeCompletedRunResult, readRunResult, retentionCleanupOptions, workflowHandle };

package/dist/engine/run-utils.mjs

@@ -0,0 +1,83 @@
+import { WorkflowRunCanceledError } from "../errors/run.mjs";
+import { getRequiredRun } from "../utility.mjs";
+import "../errors/mod.mjs";
+import { serializeError } from "./serialization.mjs";
+//#region src/engine/run-utils.ts
+function retentionCleanupOptions(options, engineNow) {
+	return {
+		finishedAtBefore: (options.now === void 0 ? engineNow() : options.now).toZonedDateTimeISO("UTC").subtract(options.olderThan).toInstant(),
+		...options.status === void 0 ? {} : { status: options.status },
+		...options.workflowName === void 0 ? {} : { workflowName: options.workflowName },
+		...options.workflowVersion === void 0 ? {} : { workflowVersion: options.workflowVersion },
+		...options.idempotencyKey === void 0 ? {} : { idempotencyKey: options.idempotencyKey },
+		...options.parentRunId === void 0 ? {} : { parentRunId: options.parentRunId },
+		...options.parentStepId === void 0 ? {} : { parentStepId: options.parentStepId },
+		...options.parentStepName === void 0 ? {} : { parentStepName: options.parentStepName },
+		...options.parentStepAttempt === void 0 ? {} : { parentStepAttempt: options.parentStepAttempt },
+		...options.dryRun === void 0 ? {} : { dryRun: options.dryRun },
+		...options.limit === void 0 ? {} : { limit: options.limit }
+	};
+}
+function workflowHandle(store, definition, runId, now, operations) {
+	return {
+		runId,
+		workflowName: definition.name,
+		...definition.version === void 0 ? {} : { workflowVersion: definition.version },
+		async getRun() {
+			return await getRequiredRun(store, runId);
+		},
+		async status() {
+			return (await getRequiredRun(store, runId)).status;
+		},
+		async events() {
+			return await store.getEvents(runId);
+		},
+		async timeline() {
+			return await operations.getTimeline(runId);
+		},
+		result: async () => await readRunResult(store, runId, now()),
+		async setMetadata(metadata) {
+			return await operations.setMetadata(runId, metadata);
+		},
+		async setAttributes(attributes) {
+			return await operations.setAttributes(runId, attributes);
+		},
+		async cancel() {
+			return await operations.cancel(runId);
+		}
+	};
+}
+async function readRunResult(store, runId, fallbackAvailableAt) {
+	const run = await getRequiredRun(store, runId);
+	if (run.status === "completed") return makeCompletedRunResult(run);
+	if (run.status === "failed") return {
+		kind: "failed",
+		run,
+		error: run.error ?? {
+			name: "WorkflowError",
+			message: `Workflow run failed: ${runId}`
+		}
+	};
+	if (run.status === "canceled") return makeCanceledRunResult(run);
+	return {
+		kind: "waiting",
+		run,
+		availableAt: run.availableAt ?? fallbackAvailableAt
+	};
+}
+function makeCompletedRunResult(run) {
+	return {
+		kind: "completed",
+		run,
+		output: run.output
+	};
+}
+function makeCanceledRunResult(run) {
+	return {
+		kind: "failed",
+		run,
+		error: run.error ?? serializeError(WorkflowRunCanceledError.create(run.id))
+	};
+}
+//#endregion
+export { makeCanceledRunResult, makeCompletedRunResult, readRunResult, retentionCleanupOptions, workflowHandle };

package/dist/engine/schedule.d.mts

@@ -0,0 +1,25 @@
+import { RunId } from "../types/run-id.mjs";
+import { ScheduleConfig, ScheduleId, ScheduleRecord, ScheduleStatus, TickSchedulesOptions, TickSchedulesResult } from "../types/schedule.mjs";
+import { WorkflowDefinition } from "../types/definition.mjs";
+import "../types/run.mjs";
+import { WorkflowRunReaderRepository, WorkflowScheduleConditionalWriterRepository, WorkflowScheduleCreationRepository, WorkflowScheduleListerRepository, WorkflowScheduleReaderRepository, WorkflowStoreNamespace } from "../types/store.mjs";
+import { WorkflowExecutionLimits } from "../types/engine-options.mjs";
+import { WorkflowRunCanceler, WorkflowRunStarter, WorkflowScheduleRunObserver } from "../types/engine.mjs";
+//#region src/engine/schedule.d.ts
+type WorkflowScheduleCommandStore = WorkflowStoreNamespace & WorkflowScheduleCreationRepository & WorkflowScheduleReaderRepository & WorkflowScheduleConditionalWriterRepository;
+type WorkflowScheduleTickStore = WorkflowScheduleListerRepository & WorkflowScheduleConditionalWriterRepository & WorkflowRunReaderRepository;
+type WorkflowScheduleTickEngine = WorkflowRunStarter & WorkflowRunCanceler & Partial<WorkflowScheduleRunObserver>;
+declare function resolveScheduleRecord<TInput, TOutput, TRawInput>(namespace: string, definition: WorkflowDefinition<TInput, TOutput, TRawInput>, options: ScheduleConfig<TInput, TRawInput>, createdAt: Temporal.Instant, limits: WorkflowExecutionLimits): ScheduleRecord<TInput>;
+declare function upsertSchedule<TInput, TOutput, TRawInput>(store: WorkflowScheduleCommandStore, definition: WorkflowDefinition<TInput, TOutput, TRawInput>, options: ScheduleConfig<TInput, TRawInput>, timestamp: Temporal.Instant, limits: WorkflowExecutionLimits): Promise<ScheduleRecord<TInput>>;
+declare function updateScheduleStatus(store: WorkflowScheduleReaderRepository & WorkflowScheduleConditionalWriterRepository, scheduleId: ScheduleId, status: ScheduleStatus, now: Temporal.Instant): Promise<ScheduleRecord>;
+declare function workflowScheduleFireTimes(schedule: ScheduleRecord, now: Temporal.Instant): readonly Temporal.Instant[];
+declare function advanceSchedule(store: WorkflowScheduleConditionalWriterRepository, schedule: ScheduleRecord, now: Temporal.Instant, updatedAt: Temporal.Instant, fired?: {
+  readonly fireAt: Temporal.Instant;
+  readonly runId: RunId;
+}): Promise<ScheduleRecord | undefined>;
+declare function bufferSchedule(store: WorkflowScheduleConditionalWriterRepository, schedule: ScheduleRecord, fireTimes: readonly Temporal.Instant[], now: Temporal.Instant, updatedAt: Temporal.Instant): Promise<ScheduleRecord | undefined>;
+declare function hasActiveScheduledRun(store: WorkflowRunReaderRepository, schedule: ScheduleRecord): Promise<boolean>;
+declare function cancelActiveScheduledRun(store: WorkflowRunReaderRepository, engine: WorkflowRunCanceler, schedule: ScheduleRecord): Promise<void>;
+declare function tickSchedules(store: WorkflowScheduleTickStore, engine: WorkflowScheduleTickEngine, now: () => Temporal.Instant, tickOptions: TickSchedulesOptions | undefined): Promise<TickSchedulesResult>;
+//#endregion
+export { advanceSchedule, bufferSchedule, cancelActiveScheduledRun, hasActiveScheduledRun, resolveScheduleRecord, tickSchedules, updateScheduleStatus, upsertSchedule, workflowScheduleFireTimes };

package/dist/engine/schedule.mjs

@@ -0,0 +1,207 @@
+import { isActiveWorkflowRunStatus } from "../utility.mjs";
+import { WorkflowScheduleAlreadyExistsError, WorkflowScheduleError } from "../errors/schedule.mjs";
+import "../errors/mod.mjs";
+import { defineWorkflowFromName } from "../definition.mjs";
+import { toOptionalPersistedValue, toPersistedValue } from "./serialization.mjs";
+//#region src/engine/schedule.ts
+const MAX_SCHEDULE_UPSERT_ATTEMPTS = 3;
+function resolveScheduleRecord(namespace, definition, options, createdAt, limits) {
+	const nextFireAt = (options.from ?? createdAt).toZonedDateTimeISO("UTC").add(options.every).toInstant();
+	const endAt = options.endAt;
+	const catchUp = options.catchUp ?? "one";
+	const maxCatchUpRuns = options.maxCatchUpRuns;
+	const overlap = options.overlap ?? "allow";
+	const persistedInput = toOptionalPersistedValue(options.input, "workflow schedule input", limits);
+	return {
+		id: options.id,
+		namespace,
+		workflowName: definition.name,
+		...definition.version === void 0 ? {} : { workflowVersion: definition.version },
+		...persistedInput === void 0 ? {} : { input: persistedInput },
+		...options.context === void 0 ? {} : { context: toPersistedValue(options.context, "workflow schedule context", limits) },
+		status: endAt !== void 0 && Temporal.Instant.compare(nextFireAt, endAt) > 0 ? "deleted" : "active",
+		every: options.every,
+		catchUp,
+		...maxCatchUpRuns === void 0 ? {} : { maxCatchUpRuns },
+		...options.maxLateness === void 0 ? {} : { maxLateness: options.maxLateness },
+		overlap,
+		createdAt,
+		updatedAt: createdAt,
+		nextFireAt,
+		...endAt === void 0 ? {} : { endAt },
+		tickCount: 0
+	};
+}
+async function upsertSchedule(store, definition, options, timestamp, limits) {
+	const schedule = resolveScheduleRecord(store.namespace, definition, options, timestamp, limits);
+	for (let attempt = 0; attempt < MAX_SCHEDULE_UPSERT_ATTEMPTS; attempt += 1) {
+		const existing = await store.getSchedule(schedule.id);
+		if (existing === void 0) try {
+			return await store.createSchedule(schedule);
+		} catch (error) {
+			if (!WorkflowScheduleAlreadyExistsError.isAlreadyExists(error, schedule.id)) throw error;
+			continue;
+		}
+		const next = {
+			...schedule,
+			createdAt: existing.createdAt,
+			updatedAt: timestamp,
+			tickCount: existing.tickCount,
+			...existing.bufferedFireAt === void 0 ? {} : { bufferedFireAt: existing.bufferedFireAt },
+			...existing.lastFireAt === void 0 ? {} : { lastFireAt: existing.lastFireAt },
+			...existing.lastRunId === void 0 ? {} : { lastRunId: existing.lastRunId }
+		};
+		const updated = await store.updateScheduleIfCurrent(existing, next);
+		if (updated !== void 0) return updated;
+	}
+	WorkflowScheduleError.upsertConflictExhausted(schedule.id);
+}
+async function updateScheduleStatus(store, scheduleId, status, now) {
+	const current = await store.getSchedule(scheduleId);
+	if (current === void 0) WorkflowScheduleError.notFound(scheduleId);
+	const next = {
+		...current,
+		status,
+		updatedAt: now
+	};
+	const updated = await store.updateScheduleIfCurrent(current, next);
+	if (updated === void 0) WorkflowScheduleError.updateConflictExhausted(scheduleId);
+	return updated;
+}
+function workflowScheduleFireTimes(schedule, now) {
+	if (schedule.bufferedFireAt !== void 0) return [schedule.bufferedFireAt];
+	if (schedule.catchUp !== "all") {
+		const fireAt = schedule.catchUp === "skip" && Temporal.Instant.compare(schedule.nextFireAt, now) < 0 ? now : schedule.nextFireAt;
+		return schedule.endAt !== void 0 && Temporal.Instant.compare(fireAt, schedule.endAt) > 0 || schedule.maxLateness !== void 0 && now.since(fireAt).total({ unit: "millisecond" }) > schedule.maxLateness.total({ unit: "millisecond" }) ? [] : [fireAt];
+	}
+	const maxCatchUpRuns = schedule.maxCatchUpRuns ?? 10;
+	const fireTimes = [];
+	let fireAt = schedule.nextFireAt;
+	while (Temporal.Instant.compare(fireAt, now) <= 0) {
+		if (schedule.endAt !== void 0 && Temporal.Instant.compare(fireAt, schedule.endAt) > 0) break;
+		if (!(schedule.maxLateness !== void 0 && now.since(fireAt).total({ unit: "millisecond" }) > schedule.maxLateness.total({ unit: "millisecond" }))) {
+			fireTimes.push(fireAt);
+			if (fireTimes.length >= maxCatchUpRuns) break;
+		}
+		fireAt = fireAt.add(schedule.every);
+	}
+	return fireTimes;
+}
+async function advanceSchedule(store, schedule, now, updatedAt, fired) {
+	const nextFireAt = (fired?.fireAt ?? now).add(schedule.every);
+	const next = {
+		...schedule,
+		nextFireAt,
+		status: schedule.endAt !== void 0 && Temporal.Instant.compare(nextFireAt, schedule.endAt) > 0 ? "deleted" : schedule.status,
+		updatedAt,
+		tickCount: schedule.tickCount + (fired === void 0 ? 0 : 1),
+		...fired === void 0 || schedule.bufferedFireAt === void 0 ? {} : { bufferedFireAt: void 0 },
+		...fired === void 0 ? {} : {
+			lastFireAt: fired.fireAt,
+			lastRunId: fired.runId
+		}
+	};
+	return await store.updateScheduleIfCurrent(schedule, next);
+}
+async function bufferSchedule(store, schedule, fireTimes, now, updatedAt) {
+	const bufferAt = schedule.bufferedFireAt ?? fireTimes.at(-1);
+	const nextFireAt = (fireTimes.at(-1) ?? now).add(schedule.every);
+	const next = {
+		...schedule,
+		nextFireAt,
+		status: schedule.endAt !== void 0 && Temporal.Instant.compare(nextFireAt, schedule.endAt) > 0 ? "deleted" : schedule.status,
+		updatedAt,
+		...bufferAt === void 0 ? {} : { bufferedFireAt: bufferAt }
+	};
+	return await store.updateScheduleIfCurrent(schedule, next);
+}
+async function hasActiveScheduledRun(store, schedule) {
+	if (schedule.lastRunId === void 0) return false;
+	const run = await store.getRun(schedule.lastRunId);
+	return run !== void 0 && isActiveWorkflowRunStatus(run.status);
+}
+async function cancelActiveScheduledRun(store, engine, schedule) {
+	if (schedule.lastRunId === void 0) return;
+	const run = await store.getRun(schedule.lastRunId);
+	if (run !== void 0 && isActiveWorkflowRunStatus(run.status)) await engine.cancelRun(schedule.lastRunId);
+}
+async function tickSchedules(store, engine, now, tickOptions) {
+	const tickNow = tickOptions?.now === void 0 ? now() : tickOptions.now;
+	const limit = tickOptions?.limit;
+	const schedules = (await store.listSchedules({ status: "active" })).filter((schedule) => schedule.bufferedFireAt !== void 0 || Temporal.Instant.compare(schedule.nextFireAt, tickNow) <= 0).slice(0, limit);
+	const runIds = [];
+	const scheduleIds = [];
+	for (const schedule of schedules) {
+		const hasActiveRun = await hasActiveScheduledRun(store, schedule);
+		if (schedule.overlap === "skip" && hasActiveRun) {
+			const skipped = await advanceSchedule(store, schedule, tickNow, tickNow);
+			if (skipped !== void 0) scheduleIds.push(skipped.id);
+			continue;
+		}
+		if (schedule.overlap === "cancel" && hasActiveRun) await cancelActiveScheduledRun(store, engine, schedule);
+		let currentSchedule = schedule;
+		let advancedSchedule = false;
+		const fireTimes = workflowScheduleFireTimes(schedule, tickNow);
+		if (schedule.overlap === "buffer" && hasActiveRun) {
+			const buffered = await bufferSchedule(store, schedule, fireTimes, tickNow, tickNow);
+			if (buffered !== void 0) scheduleIds.push(buffered.id);
+			continue;
+		}
+		if (fireTimes.length === 0) {
+			const skipped = await advanceSchedule(store, schedule, tickNow, tickNow);
+			if (skipped !== void 0) scheduleIds.push(skipped.id);
+			continue;
+		}
+		for (const fireAt of fireTimes) {
+			const run = await engine.startWorkflow(defineWorkflowFromName(schedule.workflowName, schedule.workflowVersion), schedule.input, {
+				idempotencyKey: `schedule:${schedule.id}:${fireAt.toString()}`,
+				availableAt: fireAt,
+				context: scheduleRunContext(schedule, fireAt)
+			});
+			const advanced = await advanceSchedule(store, currentSchedule, tickNow, tickNow, {
+				fireAt,
+				runId: run.runId
+			});
+			if (advanced === void 0) break;
+			currentSchedule = advanced;
+			advancedSchedule = true;
+			runIds.push(run.runId);
+			engine.observeScheduleRunCreated?.({
+				scheduleId: schedule.id,
+				runId: run.runId,
+				workflowName: schedule.workflowName,
+				...schedule.workflowVersion === void 0 ? {} : { workflowVersion: schedule.workflowVersion },
+				fireAt,
+				timestamp: tickNow
+			});
+		}
+		if (advancedSchedule) scheduleIds.push(schedule.id);
+	}
+	const nextScheduleAt = (await store.listSchedules({
+		status: "active",
+		limit: 1
+	}))[0]?.nextFireAt;
+	return {
+		ticked: runIds.length,
+		runIds,
+		scheduleIds,
+		...nextScheduleAt === void 0 ? {} : { nextScheduleAt }
+	};
+}
+function scheduleRunContext(schedule, fireAt) {
+	if (schedule.context === void 0) return {
+		scheduleId: schedule.id,
+		scheduleFireAt: fireAt.toString()
+	};
+	if (typeof schedule.context === "object" && schedule.context !== null && !Array.isArray(schedule.context) && (Object.getPrototypeOf(schedule.context) === Object.prototype || Object.getPrototypeOf(schedule.context) === null)) return Object.assign({}, schedule.context, {
+		scheduleId: schedule.id,
+		scheduleFireAt: fireAt.toString()
+	});
+	return {
+		value: schedule.context,
+		scheduleId: schedule.id,
+		scheduleFireAt: fireAt.toString()
+	};
+}
+//#endregion
+export { advanceSchedule, bufferSchedule, cancelActiveScheduledRun, hasActiveScheduledRun, resolveScheduleRecord, tickSchedules, updateScheduleStatus, upsertSchedule, workflowScheduleFireTimes };

package/dist/engine/serialization.d.mts

@@ -0,0 +1,9 @@
+import { WorkflowErrorRecord } from "../types/error.mjs";
+import { WorkflowEngineSerializationLimits } from "../types/engine-options.mjs";
+import { StorageValue } from "@temelj/storage";
+//#region src/engine/serialization.d.ts
+declare function serializeError(error: unknown): WorkflowErrorRecord;
+declare function toPersistedValue(value: unknown, path: string, limits?: WorkflowEngineSerializationLimits): StorageValue;
+declare function toOptionalPersistedValue(value: unknown, path: string, limits?: WorkflowEngineSerializationLimits): StorageValue | undefined;
+//#endregion
+export { serializeError, toOptionalPersistedValue, toPersistedValue };