@beignet/core 0.0.1 → 0.0.3

package/src/outbox/index.ts

@@ -0,0 +1,1104 @@
+/**
+ * @beignet/core/outbox
+ *
+ * Durable outbox primitives for transactionally recording events and jobs that
+ * should be delivered after the owning database transaction commits.
+ */
+
+import {
+  type EventPayloadDef,
+  type InferEventPayload,
+  parseEventPayload,
+} from "../events";
+import {
+  getJobRetryDelayMs,
+  getJobRetryMaxAttempts,
+  type InferJobPayload,
+  type JobDef,
+  parseJobPayload,
+  shouldRetryJob,
+} from "../jobs";
+import type { JobDispatcherPort } from "../ports/events";
+import type {
+  BufferedDomainEventRecorder,
+  DomainEventRecorderPort,
+} from "../ports/unit-of-work";
+import {
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "../providers";
+
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Default lease duration for claimed outbox messages.
+ */
+export const DEFAULT_OUTBOX_LEASE_MS = 30_000;
+/**
+ * Default maximum delivery attempts before a message is dead-lettered.
+ */
+export const DEFAULT_OUTBOX_MAX_ATTEMPTS = 3;
+
+/**
+ * Message kinds supported by the Beignet outbox.
+ */
+export type OutboxMessageKind = "event" | "job";
+
+/**
+ * Delivery status for an outbox message.
+ */
+export type OutboxMessageStatus =
+  | "pending"
+  | "claimed"
+  | "delivered"
+  | "deadLettered";
+
+/**
+ * JSON-serializable value accepted by the outbox.
+ */
+export type OutboxJsonValue =
+  | null
+  | string
+  | number
+  | boolean
+  | readonly OutboxJsonValue[]
+  | { readonly [key: string]: OutboxJsonValue };
+
+/**
+ * JSON object accepted by outbox payload helpers.
+ */
+export type OutboxJsonObject = { readonly [key: string]: OutboxJsonValue };
+
+/**
+ * Serialized delivery error stored on failed messages.
+ */
+export interface OutboxErrorInfo {
+  /**
+   * Error name when available.
+   */
+  name?: string;
+  /**
+   * Error message.
+   */
+  message: string;
+  /**
+   * Error stack when available.
+   */
+  stack?: string;
+}
+
+/**
+ * Input for enqueueing a raw outbox message.
+ */
+export interface OutboxEnqueueInput {
+  /**
+   * Optional caller-provided message ID.
+   */
+  id?: string;
+  /**
+   * Message kind.
+   */
+  kind: OutboxMessageKind;
+  /**
+   * Event or job name.
+   */
+  name: string;
+  /**
+   * JSON-serializable payload.
+   */
+  payload: OutboxJsonValue;
+  /**
+   * Earliest time the message may be claimed.
+   */
+  availableAt?: Date;
+  /**
+   * Maximum delivery attempts before dead-lettering.
+   */
+  maxAttempts?: number;
+}
+
+/**
+ * Durable outbox message record.
+ */
+export interface OutboxMessage {
+  /**
+   * Stable message ID.
+   */
+  id: string;
+  /**
+   * Message kind.
+   */
+  kind: OutboxMessageKind;
+  /**
+   * Event or job name.
+   */
+  name: string;
+  /**
+   * JSON-serializable payload.
+   */
+  payload: OutboxJsonValue;
+  /**
+   * Current delivery status.
+   */
+  status: OutboxMessageStatus;
+  /**
+   * Number of claim attempts.
+   */
+  attempts: number;
+  /**
+   * Maximum delivery attempts before dead-lettering.
+   */
+  maxAttempts: number;
+  /**
+   * Earliest time the message may be claimed.
+   */
+  availableAt: Date;
+  /**
+   * Last claim timestamp.
+   */
+  claimedAt: Date | null;
+  /**
+   * Lease expiration timestamp for claimed messages.
+   */
+  lockedUntil: Date | null;
+  /**
+   * Token required to mark a claimed message delivered or failed.
+   */
+  claimToken: string | null;
+  /**
+   * Delivery timestamp.
+   */
+  deliveredAt: Date | null;
+  /**
+   * Last delivery error.
+   */
+  lastError: OutboxErrorInfo | null;
+  /**
+   * Creation timestamp.
+   */
+  createdAt: Date;
+  /**
+   * Last update timestamp.
+   */
+  updatedAt: Date;
+}
+
+/**
+ * Message returned from a successful outbox claim.
+ */
+export interface ClaimedOutboxMessage
+  extends Omit<
+    OutboxMessage,
+    "claimToken" | "claimedAt" | "lockedUntil" | "status"
+  > {
+  status: "claimed";
+  claimToken: string;
+  claimedAt: Date;
+  lockedUntil: Date;
+}
+
+/**
+ * Options for leasing a batch of pending outbox messages for delivery.
+ */
+export interface OutboxClaimBatchOptions {
+  /**
+   * Maximum messages to claim in one batch.
+   */
+  limit: number;
+  /**
+   * Claim timestamp.
+   */
+  now?: Date;
+  /**
+   * Lease duration in milliseconds.
+   */
+  leaseMs?: number;
+}
+
+/**
+ * Input for marking a claimed message delivered.
+ */
+export interface OutboxMarkDeliveredInput {
+  /**
+   * Claimed message ID.
+   */
+  id: string;
+  /**
+   * Claim token returned by `claimBatch(...)`.
+   */
+  claimToken: string;
+  /**
+   * Delivery timestamp.
+   */
+  now?: Date;
+}
+
+/**
+ * Input for marking a claimed message failed.
+ */
+export interface OutboxMarkFailedInput {
+  /**
+   * Claimed message ID.
+   */
+  id: string;
+  /**
+   * Claim token returned by `claimBatch(...)`.
+   */
+  claimToken: string;
+  /**
+   * Delivery error.
+   */
+  error?: unknown;
+  /**
+   * Next time the message may be claimed.
+   */
+  retryAt?: Date;
+  /**
+   * Whether this failure should dead-letter the message.
+   */
+  deadLetter?: boolean;
+  /**
+   * Failure timestamp.
+   */
+  now?: Date;
+}
+
+/**
+ * App-facing outbox storage port.
+ *
+ * Durable adapters should claim messages atomically and require `claimToken`
+ * for delivery/failure updates.
+ */
+export interface OutboxPort {
+  /**
+   * Enqueue a new pending message.
+   */
+  enqueue(input: OutboxEnqueueInput): Promise<OutboxMessage>;
+  /**
+   * Atomically claim eligible messages for one worker.
+   */
+  claimBatch(options: OutboxClaimBatchOptions): Promise<ClaimedOutboxMessage[]>;
+  /**
+   * Mark a claimed message delivered.
+   */
+  markDelivered(input: OutboxMarkDeliveredInput): Promise<void>;
+  /**
+   * Mark a claimed message failed, retryable, or dead-lettered.
+   */
+  markFailed(input: OutboxMarkFailedInput): Promise<void>;
+}
+
+/**
+ * In-memory outbox for tests and local examples.
+ */
+export interface MemoryOutboxPort extends OutboxPort {
+  /**
+   * Current message snapshots.
+   */
+  readonly messages: readonly OutboxMessage[];
+  /**
+   * Remove all messages.
+   */
+  clear(): void;
+}
+
+/**
+ * Options for `createOutboxMessage(...)`.
+ */
+export interface CreateOutboxMessageOptions {
+  /**
+   * Generated message ID override.
+   */
+  id?: string;
+  /**
+   * Timestamp used for created/updated/available dates.
+   */
+  now?: Date;
+}
+
+/**
+ * Options for typed event/job enqueue helpers.
+ */
+export interface EnqueueTypedOutboxOptions {
+  /**
+   * Optional caller-provided message ID.
+   */
+  id?: string;
+  /**
+   * Earliest time the message may be claimed.
+   */
+  availableAt?: Date;
+  /**
+   * Maximum delivery attempts before dead-lettering.
+   */
+  maxAttempts?: number;
+}
+
+/**
+ * Registry of definitions that `drainOutbox(...)` can deliver.
+ */
+export interface OutboxRegistry {
+  /**
+   * Event definitions keyed by event name.
+   */
+  readonly events: ReadonlyMap<string, EventPayloadDef>;
+  /**
+   * Job definitions keyed by job name.
+   */
+  readonly jobs: ReadonlyMap<string, JobDef>;
+}
+
+/**
+ * Input for defining an outbox registry.
+ */
+export interface DefineOutboxRegistryInput {
+  /**
+   * Events that may be delivered from the outbox.
+   */
+  events?: readonly EventPayloadDef[];
+  /**
+   * Jobs that may be delivered from the outbox.
+   */
+  jobs?: readonly JobDef[];
+}
+
+/**
+ * Options for draining one outbox batch.
+ */
+export interface DrainOutboxOptions {
+  /**
+   * Outbox storage port.
+   */
+  outbox: OutboxPort;
+  /**
+   * Registry used to resolve message names to event/job definitions.
+   */
+  registry: OutboxRegistry;
+  /**
+   * Event bus used for event messages.
+   */
+  eventBus?: {
+    publish<E extends EventPayloadDef>(
+      event: E,
+      payload: InferEventPayload<E>,
+    ): MaybePromise<void>;
+  };
+  /**
+   * Job dispatcher used for job messages.
+   */
+  jobs?: JobDispatcherPort;
+  /**
+   * Maximum messages to claim in one drain pass.
+   */
+  batchSize?: number;
+  /**
+   * Timestamp used for claiming and state updates.
+   */
+  now?: Date;
+  /**
+   * Claim lease duration in milliseconds.
+   */
+  leaseMs?: number;
+  /**
+   * Retry delay in milliseconds or function for per-message delay.
+   */
+  retryDelayMs?:
+    | number
+    | ((args: {
+        message: ClaimedOutboxMessage;
+        error: unknown;
+        now: Date;
+      }) => number);
+  /**
+   * Optional instrumentation target for retry and dead-letter visibility.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+  /**
+   * Observer called when delivery fails. Observer failures are ignored so the
+   * original delivery failure still controls retry/dead-letter behavior.
+   */
+  onError?: (
+    error: unknown,
+    message: ClaimedOutboxMessage,
+  ) => MaybePromise<void>;
+}
+
+/**
+ * Summary returned from one `drainOutbox(...)` pass.
+ */
+export interface DrainOutboxResult {
+  /**
+   * Messages claimed in this batch.
+   */
+  claimed: number;
+  /**
+   * Messages delivered successfully.
+   */
+  delivered: number;
+  /**
+   * Messages scheduled for retry.
+   */
+  retried: number;
+  /**
+   * Messages moved to dead letter state.
+   */
+  deadLettered: number;
+}
+
+/**
+ * Error thrown when an outbox payload is not JSON serializable.
+ */
+export class OutboxSerializationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OutboxSerializationError";
+  }
+}
+
+/**
+ * Error thrown when an outbox message cannot be resolved through the registry.
+ */
+export class OutboxRegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OutboxRegistryError";
+  }
+}
+
+/**
+ * Error thrown when a claimed message cannot be updated with the supplied token.
+ */
+export class OutboxClaimError extends Error {
+  /**
+   * Message ID involved in the claim error.
+   */
+  readonly id: string;
+
+  constructor(args: { id: string; message: string }) {
+    super(args.message);
+    this.name = "OutboxClaimError";
+    this.id = args.id;
+  }
+}
+
+function assertNonEmptyString(name: string, value: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function cloneDate(value: Date): Date {
+  return new Date(value.getTime());
+}
+
+function createId(): string {
+  if (!globalThis.crypto?.randomUUID) {
+    throw new Error("crypto.randomUUID is required to create outbox IDs.");
+  }
+
+  return globalThis.crypto.randomUUID();
+}
+
+function assertJsonValue(
+  value: unknown,
+  path: readonly string[] = [],
+  seen: WeakSet<object> = new WeakSet(),
+): OutboxJsonValue {
+  const label = path.length > 0 ? path.join(".") : "payload";
+
+  if (value === null) return null;
+
+  if (
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    typeof value === "number"
+  ) {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new OutboxSerializationError(
+        `Outbox ${label} must be a finite number.`,
+      );
+    }
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      throw new OutboxSerializationError(
+        `Outbox ${label} must be JSON serializable. Circular references are not supported.`,
+      );
+    }
+    seen.add(value);
+    try {
+      return value.map((item, index) =>
+        assertJsonValue(item, [...path, String(index)], seen),
+      );
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  if (typeof value === "object") {
+    if (value instanceof Date) {
+      throw new OutboxSerializationError(
+        `Outbox ${label} must be JSON serializable. Convert Date values to strings before enqueueing.`,
+      );
+    }
+    if (seen.has(value)) {
+      throw new OutboxSerializationError(
+        `Outbox ${label} must be JSON serializable. Circular references are not supported.`,
+      );
+    }
+
+    seen.add(value);
+    try {
+      const record = value as Record<string, unknown>;
+      const output: Record<string, OutboxJsonValue> = {};
+      for (const key of Object.keys(record)) {
+        const child = record[key];
+        if (child === undefined) {
+          throw new OutboxSerializationError(
+            `Outbox ${[...path, key].join(".")} cannot be undefined.`,
+          );
+        }
+        output[key] = assertJsonValue(child, [...path, key], seen);
+      }
+      return output;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  throw new OutboxSerializationError(
+    `Outbox ${label} must be JSON serializable. Received ${typeof value}.`,
+  );
+}
+
+/**
+ * Convert an unknown value to an outbox-safe JSON value.
+ *
+ * Dates, undefined values, functions, non-finite numbers, symbols, and circular
+ * references are rejected so durable adapters can store the payload safely.
+ */
+export function toOutboxJsonValue(value: unknown): OutboxJsonValue {
+  const jsonValue = assertJsonValue(value);
+  return JSON.parse(JSON.stringify(jsonValue)) as OutboxJsonValue;
+}
+
+/**
+ * Serialize an unknown delivery error into outbox error metadata.
+ */
+export function serializeOutboxError(error: unknown): OutboxErrorInfo {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    };
+  }
+
+  if (typeof error === "string") {
+    return { message: error };
+  }
+
+  return { message: "Unknown outbox delivery error" };
+}
+
+function copyMessage(message: OutboxMessage): OutboxMessage {
+  return {
+    ...message,
+    availableAt: cloneDate(message.availableAt),
+    claimedAt: message.claimedAt ? cloneDate(message.claimedAt) : null,
+    lockedUntil: message.lockedUntil ? cloneDate(message.lockedUntil) : null,
+    deliveredAt: message.deliveredAt ? cloneDate(message.deliveredAt) : null,
+    createdAt: cloneDate(message.createdAt),
+    updatedAt: cloneDate(message.updatedAt),
+    lastError: message.lastError ? { ...message.lastError } : null,
+  };
+}
+
+function toClaimedMessage(message: OutboxMessage): ClaimedOutboxMessage {
+  if (
+    message.status !== "claimed" ||
+    !message.claimToken ||
+    !message.claimedAt ||
+    !message.lockedUntil
+  ) {
+    throw new OutboxClaimError({
+      id: message.id,
+      message: `Outbox message "${message.id}" is not claimed.`,
+    });
+  }
+
+  return {
+    ...copyMessage(message),
+    status: "claimed",
+    claimToken: message.claimToken,
+    claimedAt: cloneDate(message.claimedAt),
+    lockedUntil: cloneDate(message.lockedUntil),
+  };
+}
+
+/**
+ * Create a validated pending outbox message.
+ */
+export function createOutboxMessage(
+  input: OutboxEnqueueInput,
+  options: CreateOutboxMessageOptions = {},
+): OutboxMessage {
+  assertNonEmptyString("kind", input.kind);
+  assertNonEmptyString("name", input.name);
+  if (input.id !== undefined) assertNonEmptyString("id", input.id);
+  if (input.maxAttempts !== undefined) {
+    assertPositiveInteger("maxAttempts", input.maxAttempts);
+  }
+
+  const now = options.now ?? new Date();
+  return {
+    id: options.id ?? input.id ?? createId(),
+    kind: input.kind,
+    name: input.name,
+    payload: toOutboxJsonValue(input.payload),
+    status: "pending",
+    attempts: 0,
+    maxAttempts: input.maxAttempts ?? DEFAULT_OUTBOX_MAX_ATTEMPTS,
+    availableAt: input.availableAt
+      ? cloneDate(input.availableAt)
+      : cloneDate(now),
+    claimedAt: null,
+    lockedUntil: null,
+    claimToken: null,
+    deliveredAt: null,
+    lastError: null,
+    createdAt: cloneDate(now),
+    updatedAt: cloneDate(now),
+  };
+}
+
+function isEligible(message: OutboxMessage, now: Date): boolean {
+  if (message.status === "pending") {
+    return message.availableAt.getTime() <= now.getTime();
+  }
+
+  return (
+    message.status === "claimed" &&
+    message.lockedUntil !== null &&
+    message.lockedUntil.getTime() <= now.getTime()
+  );
+}
+
+/**
+ * Create an in-memory outbox for tests and local examples.
+ *
+ * The memory outbox is process-local and not durable.
+ */
+export function createMemoryOutbox(): MemoryOutboxPort {
+  const messages = new Map<string, OutboxMessage>();
+
+  function getClaimedOrThrow(id: string, claimToken: string): OutboxMessage {
+    const message = messages.get(id);
+    if (!message) {
+      throw new OutboxClaimError({
+        id,
+        message: `Outbox message "${id}" does not exist.`,
+      });
+    }
+    if (message.status !== "claimed" || message.claimToken !== claimToken) {
+      throw new OutboxClaimError({
+        id,
+        message: `Outbox message "${id}" is not claimed by this worker.`,
+      });
+    }
+    return message;
+  }
+
+  return {
+    get messages() {
+      return [...messages.values()].map(copyMessage);
+    },
+
+    async enqueue(input) {
+      const message = createOutboxMessage(input);
+      if (messages.has(message.id)) {
+        throw new Error(`Outbox message "${message.id}" already exists.`);
+      }
+      messages.set(message.id, message);
+      return copyMessage(message);
+    },
+
+    async claimBatch(options) {
+      assertPositiveInteger("limit", options.limit);
+      const now = options.now ?? new Date();
+      const leaseMs = options.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
+      assertPositiveInteger("leaseMs", leaseMs);
+      const lockedUntil = new Date(now.getTime() + leaseMs);
+      const claimed: ClaimedOutboxMessage[] = [];
+
+      const eligible = [...messages.values()]
+        .filter((message) => isEligible(message, now))
+        .sort((a, b) => {
+          const available = a.availableAt.getTime() - b.availableAt.getTime();
+          if (available !== 0) return available;
+          return a.createdAt.getTime() - b.createdAt.getTime();
+        })
+        .slice(0, options.limit);
+
+      for (const message of eligible) {
+        message.status = "claimed";
+        message.attempts += 1;
+        message.claimToken = createId();
+        message.claimedAt = cloneDate(now);
+        message.lockedUntil = cloneDate(lockedUntil);
+        message.updatedAt = cloneDate(now);
+        claimed.push(toClaimedMessage(message));
+      }
+
+      return claimed;
+    },
+
+    async markDelivered(input) {
+      assertNonEmptyString("id", input.id);
+      assertNonEmptyString("claimToken", input.claimToken);
+      const message = getClaimedOrThrow(input.id, input.claimToken);
+      const now = input.now ?? new Date();
+
+      message.status = "delivered";
+      message.deliveredAt = cloneDate(now);
+      message.claimToken = null;
+      message.claimedAt = null;
+      message.lockedUntil = null;
+      message.updatedAt = cloneDate(now);
+    },
+
+    async markFailed(input) {
+      assertNonEmptyString("id", input.id);
+      assertNonEmptyString("claimToken", input.claimToken);
+      const message = getClaimedOrThrow(input.id, input.claimToken);
+      const now = input.now ?? new Date();
+
+      message.status = input.deadLetter ? "deadLettered" : "pending";
+      message.lastError = serializeOutboxError(input.error);
+      message.availableAt = input.retryAt
+        ? cloneDate(input.retryAt)
+        : cloneDate(now);
+      message.claimToken = null;
+      message.claimedAt = null;
+      message.lockedUntil = null;
+      message.updatedAt = cloneDate(now);
+    },
+
+    clear() {
+      messages.clear();
+    },
+  };
+}
+
+function mapDefinitions<T extends { name: string }>(
+  kind: string,
+  defs: readonly T[],
+): ReadonlyMap<string, T> {
+  const map = new Map<string, T>();
+  for (const def of defs) {
+    if (map.has(def.name)) {
+      throw new OutboxRegistryError(
+        `Duplicate ${kind} definition "${def.name}" in outbox registry.`,
+      );
+    }
+    map.set(def.name, def);
+  }
+  return map;
+}
+
+/**
+ * Define the events and jobs that an outbox drain worker can deliver.
+ *
+ * Duplicate names throw because message delivery resolves by name.
+ */
+export function defineOutboxRegistry(
+  input: DefineOutboxRegistryInput,
+): OutboxRegistry {
+  return {
+    events: mapDefinitions("event", input.events ?? []),
+    jobs: mapDefinitions("job", input.jobs ?? []),
+  };
+}
+
+/**
+ * Validate an event payload and enqueue it as an outbox message.
+ */
+export async function enqueueEvent<E extends EventPayloadDef>(
+  outbox: OutboxPort,
+  event: E,
+  payload: InferEventPayload<E>,
+  options: EnqueueTypedOutboxOptions = {},
+): Promise<OutboxMessage> {
+  const parsed = await parseEventPayload(event, payload);
+  return outbox.enqueue({
+    id: options.id,
+    kind: "event",
+    name: event.name,
+    payload: toOutboxJsonValue(parsed),
+    availableAt: options.availableAt,
+    maxAttempts: options.maxAttempts,
+  });
+}
+
+/**
+ * Validate a job payload and enqueue it as an outbox message.
+ */
+export async function enqueueJob<J extends JobDef>(
+  outbox: OutboxPort,
+  job: J,
+  payload: InferJobPayload<J>,
+  options: EnqueueTypedOutboxOptions = {},
+): Promise<OutboxMessage> {
+  const parsed = await parseJobPayload(job, payload);
+  return outbox.enqueue({
+    id: options.id,
+    kind: "job",
+    name: job.name,
+    payload: toOutboxJsonValue(parsed),
+    availableAt: options.availableAt,
+    maxAttempts: options.maxAttempts ?? getJobRetryMaxAttempts(job.retry),
+  });
+}
+
+/**
+ * Create a domain event recorder that writes events to the outbox.
+ */
+export function createOutboxEventRecorder(
+  outbox: OutboxPort,
+  options: EnqueueTypedOutboxOptions = {},
+): BufferedDomainEventRecorder {
+  return {
+    async record(event, payload) {
+      await enqueueEvent(outbox, event, payload, options);
+    },
+    entries() {
+      return [];
+    },
+    clear() {},
+    async flush() {},
+  };
+}
+
+/**
+ * Create a job dispatcher that writes jobs to the outbox.
+ */
+export function createOutboxJobDispatcher(
+  outbox: OutboxPort,
+  options: EnqueueTypedOutboxOptions = {},
+): JobDispatcherPort {
+  return {
+    async dispatch(job, payload) {
+      await enqueueJob(outbox, job, payload, options);
+    },
+  };
+}
+
+function resolveRetryDelayMs(
+  options: DrainOutboxOptions,
+  message: ClaimedOutboxMessage,
+  error: unknown,
+  now: Date,
+): number {
+  if (typeof options.retryDelayMs === "function") {
+    const delay = options.retryDelayMs({ message, error, now });
+    assertPositiveInteger("retryDelayMs", delay);
+    return delay;
+  }
+
+  if (options.retryDelayMs !== undefined) {
+    assertPositiveInteger("retryDelayMs", options.retryDelayMs);
+    return options.retryDelayMs;
+  }
+
+  if (message.kind === "job") {
+    const job = options.registry.jobs.get(message.name);
+    if (job?.retry) {
+      return getJobRetryDelayMs(job.retry, {
+        attempt: message.attempts,
+        error,
+        jobName: message.name,
+      });
+    }
+  }
+
+  return Math.min(60_000, 1000 * 2 ** Math.max(0, message.attempts - 1));
+}
+
+function shouldRetryOutboxMessage(
+  options: DrainOutboxOptions,
+  message: ClaimedOutboxMessage,
+  error: unknown,
+): boolean {
+  if (message.kind !== "job") {
+    return message.attempts < message.maxAttempts;
+  }
+
+  const job = options.registry.jobs.get(message.name);
+  return shouldRetryJob(job?.retry, {
+    attempt: message.attempts,
+    error,
+    jobName: message.name,
+    maxAttempts: message.maxAttempts,
+  });
+}
+
+async function deliverOutboxMessage(
+  options: DrainOutboxOptions,
+  message: ClaimedOutboxMessage,
+): Promise<void> {
+  if (message.kind === "event") {
+    if (!options.eventBus) {
+      throw new OutboxRegistryError(
+        `Cannot deliver event "${message.name}" without an event bus.`,
+      );
+    }
+
+    const event = options.registry.events.get(message.name);
+    if (!event) {
+      throw new OutboxRegistryError(
+        `Outbox registry does not include event "${message.name}".`,
+      );
+    }
+
+    const payload = await parseEventPayload(event, message.payload);
+    await options.eventBus.publish(event, payload);
+    return;
+  }
+
+  if (!options.jobs) {
+    throw new OutboxRegistryError(
+      `Cannot deliver job "${message.name}" without a job dispatcher.`,
+    );
+  }
+
+  const job = options.registry.jobs.get(message.name);
+  if (!job) {
+    throw new OutboxRegistryError(
+      `Outbox registry does not include job "${message.name}".`,
+    );
+  }
+
+  const payload = await parseJobPayload(job, message.payload);
+  await options.jobs.dispatch(job, payload);
+}
+
+/**
+ * Claim and deliver one batch of outbox messages.
+ *
+ * This does not loop forever; production workers should call it on their own
+ * polling cadence. Event and job messages require matching registry entries.
+ * Failed messages are retried with backoff until `maxAttempts`, then
+ * dead-lettered.
+ */
+export async function drainOutbox(
+  options: DrainOutboxOptions,
+): Promise<DrainOutboxResult> {
+  const batchSize = options.batchSize ?? 100;
+  assertPositiveInteger("batchSize", batchSize);
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "outbox",
+      watcher: "jobs",
+    },
+  );
+
+  const now = options.now ?? new Date();
+  const messages = await options.outbox.claimBatch({
+    limit: batchSize,
+    now,
+    leaseMs: options.leaseMs,
+  });
+  const result: DrainOutboxResult = {
+    claimed: messages.length,
+    delivered: 0,
+    retried: 0,
+    deadLettered: 0,
+  };
+
+  for (const message of messages) {
+    try {
+      await deliverOutboxMessage(options, message);
+      await options.outbox.markDelivered({
+        id: message.id,
+        claimToken: message.claimToken,
+        now,
+      });
+      result.delivered += 1;
+    } catch (error) {
+      try {
+        await options.onError?.(error, message);
+      } catch {
+        // Preserve the delivery failure path so the message is retried or
+        // dead-lettered even if the observer fails.
+      }
+      const shouldRetry = shouldRetryOutboxMessage(options, message, error);
+      const deadLetter = !shouldRetry;
+      const retryDelayMs = deadLetter
+        ? 0
+        : resolveRetryDelayMs(options, message, error, now);
+      await options.outbox.markFailed({
+        id: message.id,
+        claimToken: message.claimToken,
+        error,
+        deadLetter,
+        now,
+        retryAt: deadLetter
+          ? undefined
+          : new Date(now.getTime() + retryDelayMs),
+      });
+
+      if (deadLetter) {
+        if (message.kind === "job") {
+          instrumentation.record({
+            type: "job",
+            jobName: message.name,
+            status: "deadLettered",
+            details: {
+              attempt: message.attempts,
+              maxAttempts: message.maxAttempts,
+              messageId: message.id,
+              error: serializeOutboxError(error),
+            },
+          });
+        }
+        result.deadLettered += 1;
+      } else {
+        if (message.kind === "job") {
+          instrumentation.record({
+            type: "job",
+            jobName: message.name,
+            status: "retryScheduled",
+            details: {
+              attempt: message.attempts,
+              maxAttempts: message.maxAttempts,
+              messageId: message.id,
+              retryDelayMs,
+              retryAt: new Date(now.getTime() + retryDelayMs).toISOString(),
+              error: serializeOutboxError(error),
+            },
+          });
+        }
+        result.retried += 1;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Domain event recorder port re-exported for outbox integrations.
+ */
+export type { DomainEventRecorderPort };