@temelj/workflow 0.0.0-alpha.1

package/dist/types/events.mjs

@@ -0,0 +1,283 @@
+import { nonBlankStringListSchema, nonBlankStringSchema, nonNegativeSafeIntegerSchema, positiveSafeIntegerSchema, temporalInstantSchema, temporalNonNegativeDurationSchema } from "./common.mjs";
+import { workflowErrorRecordSchema } from "./error.mjs";
+import { runIdSchema } from "./run-id.mjs";
+import { stepIdSchema } from "./step-id.mjs";
+import { workflowTelemetryContextSchema } from "./telemetry.mjs";
+import { workflowAttributeValueSchema, workflowPersistedValueSchema } from "./run.mjs";
+import { messageIdSchema } from "./message-id.mjs";
+import { workflowChildWorkflowCancellationPolicySchema } from "./step.mjs";
+import { streamIdSchema } from "./stream-id.mjs";
+import { z } from "zod";
+//#region src/types/events.ts
+const workflowMessageWaitSourceSchema = z.enum(["hook", "webhook"]);
+const workflowRunEventKindSchema = z.enum([
+	"workflow_started",
+	"workflow_completed",
+	"workflow_failed"
+]);
+const workflowStepEventKindSchema = z.enum([
+	"step_started",
+	"step_completed",
+	"step_failed"
+]);
+const workflowSleepEventKindSchema = z.enum(["sleep_started", "sleep_completed"]);
+const workflowChildWorkflowEventKindSchema = z.enum([
+	"child_workflow_started",
+	"child_workflow_completed",
+	"child_workflow_failed"
+]);
+const workflowMessageEventKindSchema = z.enum([
+	"message_sent",
+	"message_send_started",
+	"message_send_completed",
+	"message_send_failed",
+	"message_wait_started",
+	"message_wait_completed",
+	"message_wait_failed"
+]);
+const workflowStreamEventKindSchema = z.enum([
+	"stream_started",
+	"stream_chunk",
+	"stream_closed",
+	"stream_failed"
+]);
+const workflowDataEventKindSchema = z.enum(["metadata_set", "attributes_set"]);
+const workflowDeterministicEventKindSchema = z.literal("deterministic_value_recorded");
+const workflowEventKindSchema = z.union([
+	workflowRunEventKindSchema,
+	workflowStepEventKindSchema,
+	workflowSleepEventKindSchema,
+	workflowChildWorkflowEventKindSchema,
+	workflowMessageEventKindSchema,
+	workflowStreamEventKindSchema,
+	workflowDataEventKindSchema,
+	workflowDeterministicEventKindSchema
+]);
+const persistedValueSchema = workflowPersistedValueSchema;
+const runAttributesSchema = z.record(z.string(), workflowAttributeValueSchema);
+const eventBaseShape = { timestamp: temporalInstantSchema };
+const stepIdentityShape = {
+	stepId: stepIdSchema,
+	stepName: nonBlankStringSchema
+};
+const countShape = { count: positiveSafeIntegerSchema };
+const attemptShape = { attempt: positiveSafeIntegerSchema };
+const workflowMessageWaiterStepIdsSchema = nonBlankStringListSchema.refine((items) => new Set(items).size === items.length, { error: "Expected unique step ids" });
+const workflowStartedEventSchema = z.object({
+	...eventBaseShape,
+	kind: z.literal("workflow_started")
+});
+const workflowCompletedEventSchema = z.object({
+	...eventBaseShape,
+	kind: z.literal("workflow_completed")
+});
+const workflowFailedEventSchema = z.object({
+	...eventBaseShape,
+	kind: z.literal("workflow_failed")
+});
+const workflowStepStartedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	...attemptShape,
+	kind: z.literal("step_started"),
+	timeoutAt: temporalInstantSchema.optional()
+});
+const workflowStepCompletedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...attemptShape,
+	kind: z.literal("step_completed"),
+	result: persistedValueSchema.optional()
+});
+const workflowStepFailedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...attemptShape,
+	kind: z.literal("step_failed"),
+	error: workflowErrorRecordSchema
+});
+const workflowSleepStartedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("sleep_started"),
+	until: temporalInstantSchema,
+	duration: temporalNonNegativeDurationSchema.optional()
+});
+const workflowSleepCompletedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("sleep_completed")
+});
+const workflowChildWorkflowStartedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	...attemptShape,
+	kind: z.literal("child_workflow_started"),
+	childRunId: runIdSchema,
+	workflowName: nonBlankStringSchema,
+	workflowVersion: nonBlankStringSchema.optional(),
+	cancellation: workflowChildWorkflowCancellationPolicySchema.optional(),
+	input: persistedValueSchema.optional(),
+	idempotencyKey: nonBlankStringSchema.optional(),
+	timeoutAt: temporalInstantSchema.optional()
+});
+const workflowChildWorkflowCompletedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...attemptShape,
+	kind: z.literal("child_workflow_completed"),
+	childRunId: runIdSchema,
+	result: persistedValueSchema.optional()
+});
+const workflowChildWorkflowFailedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...attemptShape,
+	kind: z.literal("child_workflow_failed"),
+	childRunId: runIdSchema,
+	error: workflowErrorRecordSchema
+});
+const workflowMessageSentEventSchema = z.object({
+	...eventBaseShape,
+	kind: z.literal("message_sent"),
+	messageId: messageIdSchema,
+	payload: persistedValueSchema.optional(),
+	waiterStepIds: workflowMessageWaiterStepIdsSchema.optional(),
+	idempotencyKey: nonBlankStringSchema.optional(),
+	telemetryContext: workflowTelemetryContextSchema.optional()
+});
+const workflowMessageSendStartedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("message_send_started"),
+	targetRunId: runIdSchema,
+	messageId: messageIdSchema,
+	payload: persistedValueSchema.optional(),
+	idempotencyKey: nonBlankStringSchema.optional()
+});
+const workflowMessageSendCompletedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("message_send_completed"),
+	targetRunId: runIdSchema,
+	messageId: messageIdSchema
+});
+const workflowMessageSendFailedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("message_send_failed"),
+	targetRunId: runIdSchema,
+	messageId: messageIdSchema,
+	error: workflowErrorRecordSchema
+});
+const workflowMessageWaitStartedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("message_wait_started"),
+	messageId: messageIdSchema,
+	source: workflowMessageWaitSourceSchema.optional(),
+	timeoutAt: temporalInstantSchema.optional()
+});
+const workflowMessageWaitCompletedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("message_wait_completed"),
+	messageId: messageIdSchema,
+	payload: persistedValueSchema.optional(),
+	messageTimestamp: temporalInstantSchema,
+	telemetryContext: workflowTelemetryContextSchema.optional()
+});
+const workflowMessageWaitFailedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("message_wait_failed"),
+	messageId: messageIdSchema,
+	error: workflowErrorRecordSchema
+});
+const workflowMetadataSetEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("metadata_set"),
+	metadata: persistedValueSchema
+});
+const workflowAttributesSetEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("attributes_set"),
+	attributes: runAttributesSchema.optional(),
+	removeAttributes: z.array(nonBlankStringSchema).readonly().optional()
+});
+const workflowStreamStartedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("stream_started"),
+	streamId: streamIdSchema,
+	contentType: nonBlankStringSchema.optional(),
+	metadata: persistedValueSchema.optional()
+});
+const workflowStreamChunkEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("stream_chunk"),
+	streamId: streamIdSchema,
+	index: nonNegativeSafeIntegerSchema,
+	chunk: persistedValueSchema.optional()
+});
+const workflowStreamClosedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("stream_closed"),
+	streamId: streamIdSchema
+});
+const workflowStreamFailedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	kind: z.literal("stream_failed"),
+	streamId: streamIdSchema,
+	error: workflowErrorRecordSchema
+});
+const workflowDeterministicValueRecordedEventSchema = z.object({
+	...eventBaseShape,
+	...stepIdentityShape,
+	...countShape,
+	kind: z.literal("deterministic_value_recorded"),
+	value: persistedValueSchema
+});
+const workflowEventRecordSchema = z.discriminatedUnion("kind", [
+	workflowStartedEventSchema,
+	workflowCompletedEventSchema,
+	workflowFailedEventSchema,
+	workflowStepStartedEventSchema,
+	workflowStepCompletedEventSchema,
+	workflowStepFailedEventSchema,
+	workflowSleepStartedEventSchema,
+	workflowSleepCompletedEventSchema,
+	workflowChildWorkflowStartedEventSchema,
+	workflowChildWorkflowCompletedEventSchema,
+	workflowChildWorkflowFailedEventSchema,
+	workflowMessageSentEventSchema,
+	workflowMessageSendStartedEventSchema,
+	workflowMessageSendCompletedEventSchema,
+	workflowMessageSendFailedEventSchema,
+	workflowMessageWaitStartedEventSchema,
+	workflowMessageWaitCompletedEventSchema,
+	workflowMessageWaitFailedEventSchema,
+	workflowMetadataSetEventSchema,
+	workflowAttributesSetEventSchema,
+	workflowStreamStartedEventSchema,
+	workflowStreamChunkEventSchema,
+	workflowStreamClosedEventSchema,
+	workflowStreamFailedEventSchema,
+	workflowDeterministicValueRecordedEventSchema
+]);
+const workflowEventRecordListSchema = z.array(workflowEventRecordSchema);
+//#endregion
+export { workflowAttributesSetEventSchema, workflowChildWorkflowCompletedEventSchema, workflowChildWorkflowEventKindSchema, workflowChildWorkflowFailedEventSchema, workflowChildWorkflowStartedEventSchema, workflowCompletedEventSchema, workflowDataEventKindSchema, workflowDeterministicEventKindSchema, workflowDeterministicValueRecordedEventSchema, workflowEventKindSchema, workflowEventRecordListSchema, workflowEventRecordSchema, workflowFailedEventSchema, workflowMessageEventKindSchema, workflowMessageSendCompletedEventSchema, workflowMessageSendFailedEventSchema, workflowMessageSendStartedEventSchema, workflowMessageSentEventSchema, workflowMessageWaitCompletedEventSchema, workflowMessageWaitFailedEventSchema, workflowMessageWaitSourceSchema, workflowMessageWaitStartedEventSchema, workflowMessageWaiterStepIdsSchema, workflowMetadataSetEventSchema, workflowRunEventKindSchema, workflowSleepCompletedEventSchema, workflowSleepEventKindSchema, workflowSleepStartedEventSchema, workflowStartedEventSchema, workflowStepCompletedEventSchema, workflowStepEventKindSchema, workflowStepFailedEventSchema, workflowStepStartedEventSchema, workflowStreamChunkEventSchema, workflowStreamClosedEventSchema, workflowStreamEventKindSchema, workflowStreamFailedEventSchema, workflowStreamStartedEventSchema };

package/dist/types/hook.d.mts

@@ -0,0 +1,149 @@
+import { MessageId } from "./message-id.mjs";
+import { RunId } from "./run-id.mjs";
+import "./run.mjs";
+import { WorkflowErrorRecord } from "./error.mjs";
+import { z } from "zod";
+import { Schema, SchemaOutput } from "@temelj/standard-schema";
+//#region src/types/hook.d.ts
+declare const WORKFLOW_HOOK_TOKEN_PREFIX = "temelj-hook:";
+declare const WORKFLOW_HOOK_TOKEN_VERSION = "v1";
+declare const workflowHookKindSchema: z.ZodEnum<{
+  hook: "hook";
+  webhook: "webhook";
+}>;
+declare const workflowHookTokenPayloadSchema: z.ZodObject<{
+  v: z.ZodOptional<z.ZodLiteral<1>>;
+  runId: z.ZodString;
+  name: z.ZodString;
+  messageId: z.ZodString;
+  kind: z.ZodOptional<z.ZodEnum<{
+    hook: "hook";
+    webhook: "webhook";
+  }>>;
+  metadata: z.ZodOptional<z.ZodType<import("@temelj/storage").StorageValue, unknown, z.core.$ZodTypeInternals<import("@temelj/storage").StorageValue, unknown>>>;
+}, z.core.$strip>;
+declare const workflowHookTokenSchema: z.ZodString;
+/** Decoded fields carried by a workflow webhook resume token. */
+declare const parsedWorkflowWebhookTokenSchema: z.ZodObject<{
+  runId: z.ZodString;
+  name: z.ZodString;
+  messageId: z.ZodString;
+}, z.core.$strip>;
+declare const parsedWorkflowHookTokenSchema: z.ZodObject<{
+  runId: z.ZodString;
+  name: z.ZodString;
+  messageId: z.ZodString;
+  kind: z.ZodEnum<{
+    hook: "hook";
+    webhook: "webhook";
+  }>;
+  metadata: z.ZodOptional<z.ZodType<import("@temelj/storage").StorageValue, unknown, z.core.$ZodTypeInternals<import("@temelj/storage").StorageValue, unknown>>>;
+}, z.core.$strip>;
+/** Parses a workflow hook token and throws WorkflowHookError when it is invalid. */
+declare function parseHookToken(token: string): ParsedWorkflowHookToken;
+/** Parses a workflow webhook token and throws a webhook-specific options error when invalid. */
+declare function parseWebhookToken(token: string): ParsedWorkflowHookToken;
+/** Promise-like handle for a message-backed workflow hook created by workflow code. */
+interface Hook<TPayload = unknown> extends PromiseLike<TPayload> {
+  /** Opaque token used by external code to resume or dispose the hook. */
+  readonly token: string;
+  /** Run ID that owns the waiting hook. */
+  readonly runId: RunId;
+  /** Hook name supplied when the hook was created. */
+  readonly name: string;
+  /** Message ID that will resume the hook. */
+  readonly messageId: MessageId;
+  /** Waits until the hook receives a payload, fails, expires, or is disposed. */
+  wait(): Promise<TPayload>;
+}
+/** Promise-like handle for a webhook-backed workflow hook created by workflow code. */
+interface Webhook<TPayload = unknown> extends PromiseLike<TPayload> {
+  /** Opaque token used by external code to resume or dispose the webhook hook. */
+  readonly token: string;
+  /** Run ID that owns the waiting webhook hook. */
+  readonly runId: RunId;
+  /** Webhook hook name supplied when the hook was created. */
+  readonly name: string;
+  /** Message ID that will resume the webhook hook. */
+  readonly messageId: MessageId;
+  /** Optional persisted metadata encoded into the webhook token. */
+  readonly metadata?: unknown;
+  /** Waits until the webhook hook receives a payload, fails, expires, or is disposed. */
+  wait(): Promise<TPayload>;
+}
+/** Options for creating a message-backed external resume hook. */
+interface CreateHookOptions<TSchema extends Schema | undefined = undefined> {
+  readonly commandId?: string;
+  readonly name: string;
+  readonly messageId?: MessageId;
+  readonly timeout?: Temporal.Duration;
+  readonly schema?: TSchema;
+}
+/** Options for creating a webhook-labeled external resume hook. */
+interface CreateWebhookOptions<TSchema extends Schema | undefined = undefined> extends CreateHookOptions<TSchema> {
+  readonly metadata?: unknown;
+}
+/** Options for completing an external resume hook. */
+interface ResumeHookOptions {
+  readonly payload?: unknown;
+  readonly idempotencyKey?: string;
+}
+/** Options for completing a webhook-labeled external resume hook. */
+type ResumeWebhookOptions = ResumeHookOptions;
+/** Kind of external resume token represented in hook inspection data. */
+type HookKind = "hook" | "webhook";
+/** Payload encoded into a workflow hook token before it is given to external systems. */
+interface HookTokenPayload {
+  readonly v?: 1;
+  readonly runId: RunId;
+  readonly name: string;
+  readonly messageId: MessageId;
+  readonly kind?: HookKind;
+  readonly metadata?: unknown;
+}
+/** Opaque token string used to resume or dispose an external workflow hook. */
+type HookToken = string;
+/** Observed lifecycle status of an external resume token. */
+type HookInspectionStatus = "waiting" | "completed" | "failed" | "disposed" | "expired" | "run-terminal" | "not-found";
+/** Inspection record for an external resume token and its recorded outcome. */
+interface HookInspection {
+  readonly token: string;
+  readonly runId: RunId;
+  readonly name: string;
+  readonly messageId: MessageId;
+  readonly kind: HookKind;
+  readonly status: HookInspectionStatus;
+  readonly stepId?: string;
+  readonly timeoutAt?: Temporal.Instant;
+  readonly metadata?: unknown;
+  readonly payload?: unknown;
+  readonly error?: WorkflowErrorRecord;
+}
+/** Decoded fields carried by a workflow webhook resume token. */
+interface ParsedWorkflowWebhookToken {
+  readonly runId: RunId;
+  readonly name: string;
+  readonly messageId: MessageId;
+}
+/** Decoded fields carried by any workflow hook token, including webhook tokens. */
+interface ParsedWorkflowHookToken extends ParsedWorkflowWebhookToken {
+  readonly kind: HookKind;
+  readonly metadata?: unknown;
+}
+/** Alias for message-backed hook handles. */
+type HookCreator<TPayload = unknown> = Hook<TPayload>;
+/** Alias for webhook-backed hook handles. */
+type WebhookCreator<TPayload = unknown> = Webhook<TPayload>;
+/** Minimal hook creation surface exposed on the workflow step API. */
+interface WorkflowStepHookCreateApi {
+  /** Creates a message-backed external resume hook. */
+  create<TPayload = unknown>(options: CreateHookOptions): Hook<TPayload>;
+  /** Creates a message-backed external resume hook with schema-validated payloads. */
+  create<const TSchema extends Schema>(options: CreateHookOptions<TSchema>): Hook<SchemaOutput<TSchema>>;
+  /** Creates a webhook-labeled external resume hook. */
+  createWebhook<TPayload = unknown>(options: CreateWebhookOptions): Webhook<TPayload>;
+  /** Creates a webhook-labeled external resume hook with schema-validated payloads. */
+  createWebhook<const TSchema extends Schema>(options: CreateWebhookOptions<TSchema>): Webhook<SchemaOutput<TSchema>>;
+}
+//#endregion
+export { CreateHookOptions, CreateWebhookOptions, Hook, HookCreator, HookInspection, HookInspectionStatus, HookKind, HookToken, HookTokenPayload, ParsedWorkflowHookToken, ParsedWorkflowWebhookToken, ResumeHookOptions, ResumeWebhookOptions, WORKFLOW_HOOK_TOKEN_PREFIX, WORKFLOW_HOOK_TOKEN_VERSION, Webhook, WebhookCreator, WorkflowStepHookCreateApi, parseHookToken, parseWebhookToken, parsedWorkflowHookTokenSchema, parsedWorkflowWebhookTokenSchema, workflowHookKindSchema, workflowHookTokenPayloadSchema, workflowHookTokenSchema };

package/dist/types/hook.mjs

@@ -0,0 +1,66 @@
+import { nonBlankStringSchema } from "./common.mjs";
+import { runIdSchema } from "./run-id.mjs";
+import { workflowPersistedValueSchema } from "./run.mjs";
+import { WorkflowHookError } from "../errors/hook.mjs";
+import "../errors/mod.mjs";
+import { messageIdSchema } from "./message-id.mjs";
+import { z } from "zod";
+import { decodeBase64UrlString } from "@temelj/string";
+//#region src/types/hook.ts
+const WORKFLOW_HOOK_TOKEN_PREFIX = "temelj-hook:";
+const WORKFLOW_HOOK_TOKEN_VERSION = "v1";
+const workflowHookKindSchema = z.enum(["hook", "webhook"]);
+const workflowHookTokenPayloadSchema = z.object({
+	v: z.literal(1).optional(),
+	runId: runIdSchema,
+	name: nonBlankStringSchema,
+	messageId: messageIdSchema,
+	kind: workflowHookKindSchema.optional(),
+	metadata: workflowPersistedValueSchema.optional()
+});
+const workflowHookTokenSchema = nonBlankStringSchema.refine((token) => token.startsWith(WORKFLOW_HOOK_TOKEN_PREFIX), { error: "Workflow hook token is invalid" });
+/** Decoded fields carried by a workflow webhook resume token. */
+const parsedWorkflowWebhookTokenSchema = z.object({
+	runId: runIdSchema,
+	name: nonBlankStringSchema,
+	messageId: messageIdSchema
+});
+const parsedWorkflowHookTokenSchema = parsedWorkflowWebhookTokenSchema.extend({
+	kind: workflowHookKindSchema,
+	metadata: workflowPersistedValueSchema.optional()
+});
+/** Parses a workflow hook token and throws WorkflowHookError when it is invalid. */
+function parseHookToken(token) {
+	const parsedToken = workflowHookTokenSchema.safeParse(token);
+	if (!parsedToken.success) WorkflowHookError.tokenInvalid();
+	const body = parsedToken.data.slice(12);
+	if (body.startsWith(`v1:`)) try {
+		const payload = JSON.parse(decodeBase64UrlString(body.slice(3)));
+		const hook = workflowHookTokenPayloadSchema.safeParse(payload);
+		if (!hook.success) WorkflowHookError.tokenInvalid();
+		const parsedHook = parsedWorkflowHookTokenSchema.safeParse({
+			runId: hook.data.runId,
+			name: hook.data.name,
+			messageId: hook.data.messageId,
+			kind: hook.data.kind ?? "hook",
+			...hook.data.metadata === void 0 ? {} : { metadata: hook.data.metadata }
+		});
+		if (!parsedHook.success) WorkflowHookError.tokenInvalid();
+		return parsedHook.data;
+	} catch (error) {
+		if (!(error instanceof WorkflowHookError)) WorkflowHookError.tokenInvalid();
+		WorkflowHookError.tokenInvalid();
+	}
+	WorkflowHookError.tokenInvalid();
+}
+/** Parses a workflow webhook token and throws a webhook-specific options error when invalid. */
+function parseWebhookToken(token) {
+	try {
+		return parseHookToken(token);
+	} catch (error) {
+		if (error instanceof WorkflowHookError) WorkflowHookError.webhookTokenInvalid();
+		throw error;
+	}
+}
+//#endregion
+export { WORKFLOW_HOOK_TOKEN_PREFIX, WORKFLOW_HOOK_TOKEN_VERSION, parseHookToken, parseWebhookToken, parsedWorkflowHookTokenSchema, parsedWorkflowWebhookTokenSchema, workflowHookKindSchema, workflowHookTokenPayloadSchema, workflowHookTokenSchema };

package/dist/types/lock.d.mts

@@ -0,0 +1,63 @@
+import { RunId } from "./run-id.mjs";
+import { StepId } from "./step-id.mjs";
+import "./run.mjs";
+import { z } from "zod";
+//#region src/types/lock.d.ts
+declare const workflowLockRecordSchema: z.ZodObject<{
+  key: z.ZodString;
+  namespace: z.ZodString;
+  holderId: z.ZodString;
+  holderRunId: z.ZodOptional<z.ZodString>;
+  holderStepId: z.ZodOptional<z.ZodString>;
+  fencingToken: z.ZodNumber;
+  acquiredAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  leaseExpiresAt: z.ZodCustom<Temporal.Instant, Temporal.Instant>;
+  releasedAt: z.ZodOptional<z.ZodCustom<Temporal.Instant, Temporal.Instant>>;
+}, z.core.$strip>;
+/** Stored lease-backed workflow lock state. */
+interface LockRecord {
+  readonly key: string;
+  readonly namespace: string;
+  readonly holderId: string;
+  readonly holderRunId?: RunId;
+  readonly holderStepId?: StepId;
+  readonly fencingToken: number;
+  readonly acquiredAt: Temporal.Instant;
+  readonly leaseExpiresAt: Temporal.Instant;
+  readonly releasedAt?: Temporal.Instant;
+}
+/** Options for acquiring a workflow lock. */
+interface AcquireLockOptions {
+  readonly holderId: string;
+  readonly holderRunId?: RunId;
+  readonly holderStepId?: StepId;
+  readonly leaseDuration: Temporal.Duration;
+  readonly wait?: boolean;
+  readonly waitTimeout?: Temporal.Duration;
+  readonly waitDeadlineAt?: Temporal.Instant;
+  readonly now?: Temporal.Instant;
+}
+/** Options for acquiring a workflow lock from a durable step. */
+interface WorkflowStepAcquireLockOptions {
+  readonly holderId?: string;
+  readonly leaseDuration: Temporal.Duration;
+  readonly wait?: boolean;
+  readonly waitTimeout?: Temporal.Duration;
+  readonly now?: Temporal.Instant;
+}
+/** Options for releasing a workflow lock from a durable step. */
+interface WorkflowStepReleaseLockOptions {
+  readonly holderId?: string;
+  readonly now?: Temporal.Instant;
+}
+/** Options for releasing a workflow lock outside workflow step execution. */
+interface ReleaseLockOptions {
+  readonly holderId: string;
+  readonly now?: Temporal.Instant;
+}
+/** Options for releasing a workflow lock whose lease has expired. */
+interface ReleaseStaleLockOptions {
+  readonly now?: Temporal.Instant;
+}
+//#endregion
+export { AcquireLockOptions, LockRecord, ReleaseLockOptions, ReleaseStaleLockOptions, WorkflowStepAcquireLockOptions, WorkflowStepReleaseLockOptions, workflowLockRecordSchema };

package/dist/types/lock.mjs

@@ -0,0 +1,18 @@
+import { nonBlankStringSchema, positiveSafeIntegerSchema, temporalInstantSchema } from "./common.mjs";
+import { runIdSchema } from "./run-id.mjs";
+import { stepIdSchema } from "./step-id.mjs";
+import { z } from "zod";
+//#region src/types/lock.ts
+const workflowLockRecordSchema = z.object({
+	key: nonBlankStringSchema,
+	namespace: nonBlankStringSchema,
+	holderId: nonBlankStringSchema,
+	holderRunId: runIdSchema.optional(),
+	holderStepId: stepIdSchema.optional(),
+	fencingToken: positiveSafeIntegerSchema,
+	acquiredAt: temporalInstantSchema,
+	leaseExpiresAt: temporalInstantSchema,
+	releasedAt: temporalInstantSchema.optional()
+});
+//#endregion
+export { workflowLockRecordSchema };

package/dist/types/message-id.d.mts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+//#region src/types/message-id.d.ts
+declare const messageIdSchema: z.ZodString;
+/** Non-empty identifier used to route durable workflow messages. */
+type MessageId = string;
+//#endregion
+export { MessageId, messageIdSchema };

package/dist/types/message-id.mjs

@@ -0,0 +1,5 @@
+import { z } from "zod";
+//#region src/types/message-id.ts
+const messageIdSchema = z.string().refine((value) => value.trim().length > 0, "Expected an ID");
+//#endregion
+export { messageIdSchema };

package/dist/types/message.d.mts

@@ -0,0 +1,87 @@
+import { MessageId } from "./message-id.mjs";
+import { RunId } from "./run-id.mjs";
+import { WorkflowListRunsOptions } from "./run-list.mjs";
+import { Schema } from "@temelj/standard-schema";
+//#region src/types/message.d.ts
+/** Typed message channel that maps optional keys to durable message ids. */
+interface MessageChannel<TPayload = unknown, TKey = void> {
+  readonly name: string;
+  readonly schema?: Schema;
+  readonly resolveMessageId: (...args: MessageChannelKeyArgs<TKey>) => MessageId;
+  readonly types?: MessageChannelTypes<TPayload, TKey>;
+}
+/** Compile-time payload and key markers carried by a message channel. */
+interface MessageChannelTypes<TPayload, TKey> {
+  readonly payload: TPayload;
+  readonly key: TKey;
+}
+/** Argument tuple required when deriving a message id from a channel key. */
+type MessageChannelKeyArgs<TKey> = [void] extends [TKey] ? [key?: TKey] : [key: TKey];
+/** Configuration for defining a typed message channel. */
+interface MessageChannelConfig<TKey = void, TSchema extends Schema | undefined = undefined> {
+  readonly name: string;
+  readonly schema?: TSchema;
+  readonly resolveMessageId?: (...args: MessageChannelKeyArgs<TKey>) => MessageId;
+}
+/** Options for sending a concrete message id to a workflow run. */
+interface SendMessageOptions {
+  readonly messageId: MessageId;
+  readonly payload?: unknown;
+  readonly idempotencyKey?: string;
+}
+/** Options for sending through a typed message channel. */
+interface SendMessageChannelOptions<TPayload = unknown, TKey = void> {
+  readonly key?: TKey;
+  readonly payload?: TPayload;
+  readonly idempotencyKey?: string;
+}
+/** Object form for sending through a typed message channel. */
+interface SendMessageChannelObject<TPayload = unknown, TKey = void> extends SendMessageChannelOptions<TPayload, TKey> {
+  readonly channel: MessageChannel<TPayload, TKey>;
+}
+/** Accepted input forms for sending a message to one run. */
+type SendMessageInput = SendMessageOptions | SendMessageChannelObject;
+/** Options for broadcasting a concrete message id to matching runs. */
+interface BroadcastMessageOptions extends SendMessageOptions {
+  readonly payload?: unknown;
+  readonly target?: WorkflowListRunsOptions;
+}
+/** Options for broadcasting through a typed message channel to matching runs. */
+interface BroadcastMessageChannelOptions<TPayload = unknown, TKey = void> extends SendMessageChannelOptions<TPayload, TKey> {
+  readonly target?: WorkflowListRunsOptions;
+}
+/** Object form for broadcasting through a typed message channel. */
+interface BroadcastMessageChannelObject<TPayload = unknown, TKey = void> extends BroadcastMessageChannelOptions<TPayload, TKey> {
+  readonly channel: MessageChannel<TPayload, TKey>;
+}
+/** Accepted input forms for broadcasting a message to matching runs. */
+type BroadcastMessageInput = BroadcastMessageOptions | BroadcastMessageChannelObject;
+/** Summary returned after broadcasting a message to matching runs. */
+interface BroadcastMessageResult {
+  readonly messageId: MessageId;
+  readonly runIds: RunId[];
+  readonly deliveredMessages: number;
+}
+/** Options for waiting on a concrete message id from workflow code. */
+interface WaitForMessageOptions<TSchema extends Schema | undefined = undefined> {
+  readonly commandId?: string;
+  readonly name?: string;
+  readonly messageId: MessageId;
+  readonly timeout?: Temporal.Duration;
+  readonly schema?: TSchema;
+}
+/** Options for waiting through a typed message channel from workflow code. */
+interface WaitForMessageChannelOptions<TKey = void> {
+  readonly commandId?: string;
+  readonly name?: string;
+  readonly key?: TKey;
+  readonly timeout?: Temporal.Duration;
+}
+/** Object form for waiting through a typed message channel. */
+interface WaitForMessageChannelObject<TKey = void> extends WaitForMessageChannelOptions<TKey> {
+  readonly channel: MessageChannel<unknown, TKey>;
+}
+/** Accepted input forms for waiting on a workflow message. */
+type WaitForMessageInput<TSchema extends Schema | undefined = undefined> = WaitForMessageOptions<TSchema> | WaitForMessageChannelObject;
+//#endregion
+export { BroadcastMessageChannelObject, BroadcastMessageChannelOptions, BroadcastMessageInput, BroadcastMessageOptions, BroadcastMessageResult, MessageChannel, MessageChannelConfig, MessageChannelKeyArgs, MessageChannelTypes, type MessageId, SendMessageChannelObject, SendMessageChannelOptions, SendMessageInput, SendMessageOptions, WaitForMessageChannelObject, WaitForMessageChannelOptions, WaitForMessageInput, WaitForMessageOptions };