@beignet/core 0.0.50 → 0.0.51

package/src/outbox/index.ts

@@ -11,6 +11,10 @@ import {
   type InferEventPayload,
   parseEventPayload,
 } from "../events/index.js";
+import {
+  isEventPayloadParsed,
+  markEventPayloadParsed,
+} from "../events/payload-state.js";
 import {
   getJobRetryDelayMs,
   getJobRetryMaxAttempts,
@@ -46,6 +50,18 @@ export type MaybePromise<T> = T | Promise<T>;
  * Default lease duration for claimed outbox messages.
  */
 export const DEFAULT_OUTBOX_LEASE_MS = 30_000;
+/**
+ * Default maximum messages handled by one bounded drain pass.
+ */
+export const DEFAULT_OUTBOX_BATCH_SIZE = 100;
+/**
+ * Default number of outbox messages delivered concurrently.
+ */
+export const DEFAULT_OUTBOX_CONCURRENCY = 1;
+/**
+ * Default maximum time Beignet renews a claim for one delivery.
+ */
+export const DEFAULT_OUTBOX_MAX_ACTIVE_MS = 300_000;
 /**
  * Default maximum delivery attempts before a message is dead-lettered.
  */
@@ -218,7 +234,7 @@ export interface ClaimedOutboxMessage
  */
 export interface OutboxClaimBatchOptions {
   /**
-   * Maximum messages to claim in one batch.
+   * Maximum eligible messages to claim or reconcile in one batch.
    */
   limit: number;
   /**
@@ -231,6 +247,41 @@ export interface OutboxClaimBatchOptions {
   leaseMs?: number;
 }
 
+/**
+ * Result of atomically selecting one bounded set of eligible messages.
+ */
+export interface OutboxClaimBatchResult {
+  /** Messages claimed for delivery by the current worker. */
+  claimed: readonly ClaimedOutboxMessage[];
+  /**
+   * Eligible messages moved directly to dead letter because their claim
+   * attempt budget was already exhausted.
+   */
+  deadLettered: readonly OutboxMessage[];
+}
+
+/**
+ * Input for extending one active outbox claim.
+ */
+export interface OutboxRenewClaimInput {
+  /** Claimed message ID. */
+  id: string;
+  /** Claim token returned by `claimBatch(...)`. */
+  claimToken: string;
+  /** Renewal timestamp. */
+  now?: Date;
+  /** New lease duration measured from `now`. */
+  leaseMs?: number;
+}
+
+/**
+ * Confirmed result of extending one active outbox claim.
+ */
+export interface OutboxRenewClaimResult {
+  /** New confirmed lease expiration timestamp. */
+  lockedUntil: Date;
+}
+
 /**
  * Input for marking a claimed message delivered.
  */
@@ -403,7 +454,11 @@ export interface OutboxPort {
   /**
    * Atomically claim eligible messages for one worker.
    */
-  claimBatch(options: OutboxClaimBatchOptions): Promise<ClaimedOutboxMessage[]>;
+  claimBatch(options: OutboxClaimBatchOptions): Promise<OutboxClaimBatchResult>;
+  /**
+   * Extend an unexpired claim owned by the supplied claim token.
+   */
+  renewClaim(input: OutboxRenewClaimInput): Promise<OutboxRenewClaimResult>;
   /**
    * Mark a claimed message delivered.
    */
@@ -542,6 +597,40 @@ export type OutboxInstrumentationContext = Pick<
   "requestId" | "traceId" | "spanId" | "parentSpanId" | "traceparent"
 >;
 
+/** Wait primitive used by outbox heartbeats and bounded settlement retries. */
+export type OutboxDrainWait = (
+  delayMs: number,
+  signal: AbortSignal,
+) => Promise<void>;
+
+/** Structured failure from a claim heartbeat or active-delivery boundary. */
+export interface OutboxLeaseFailure {
+  /** Underlying renewal, ownership, or duration error. */
+  error: unknown;
+  /** Message whose claim could not be kept active. */
+  message: ClaimedOutboxMessage;
+  /** Lease phase that surfaced the failure. */
+  operation: "renewClaim" | "maxActiveDuration";
+  /** Current lease state after handling the failure. */
+  state: "recovered" | "degraded" | "lost";
+  /** Whether the worker no longer has confirmed ownership. */
+  confirmedLost: boolean;
+}
+
+/** Structured failure from a token-guarded outbox settlement. */
+export interface OutboxSettlementFailure {
+  /** Storage failure returned by the settlement operation. */
+  error: unknown;
+  /** Message whose final storage state is unknown. */
+  message: ClaimedOutboxMessage;
+  /** Settlement operation that failed. */
+  operation: "markDelivered" | "markFailed";
+  /** Whether the external delivery completed successfully. */
+  deliverySucceeded: boolean;
+  /** Original delivery error when `deliverySucceeded` is false. */
+  deliveryError?: unknown;
+}
+
 /**
  * Options for draining one outbox batch.
  */
@@ -571,17 +660,38 @@ export interface DrainOutboxOptions {
    */
   jobs?: JobDispatcherPort;
   /**
-   * Maximum messages to claim in one drain pass.
+   * Maximum eligible messages to handle in one drain pass.
    */
   batchSize?: number;
   /**
-   * Timestamp used for claiming and state updates.
+   * Maximum messages delivered concurrently. Defaults to serial delivery.
+   * Values greater than one do not preserve delivery order.
    */
-  now?: Date;
+  concurrency?: number;
+  /**
+   * Clock used independently for claiming, renewal, settlement, and retry
+   * scheduling. Defaults to the system clock.
+   */
+  now?: () => Date;
   /**
    * Claim lease duration in milliseconds.
    */
   leaseMs?: number;
+  /**
+   * Interval between serialized claim renewals. Defaults to one third of the
+   * lease duration and must remain shorter than the lease.
+   */
+  heartbeatMs?: number;
+  /**
+   * Maximum time Beignet renews a claim for one delivery. When exceeded, the
+   * drain stops renewing and leaves final recovery to the last lease expiry.
+   */
+  maxActiveMs?: number;
+  /**
+   * Abort-aware wait implementation. Inject a deterministic implementation in
+   * tests; production callers normally use the default timer.
+   */
+  wait?: OutboxDrainWait;
   /**
    * Retry delay in milliseconds or function for per-message delay.
    */
@@ -613,19 +723,17 @@ export interface DrainOutboxOptions {
    * Observer called after a failed delivery is successfully moved to the dead
    * letter state. Observer failures are ignored.
    */
-  onDeadLetter?: (
-    error: unknown,
-    message: ClaimedOutboxMessage,
-  ) => MaybePromise<void>;
+  onDeadLetter?: (error: unknown, message: OutboxMessage) => MaybePromise<void>;
   /**
-   * Observer called when a failed delivery cannot be settled as retryable or
-   * dead-lettered. Observer failures are ignored.
+   * Observer called when claim renewal degrades or ownership is lost.
+   * Observer failures are ignored.
    */
-  onSettlementError?: (
-    settlementError: unknown,
-    message: ClaimedOutboxMessage,
-    deliveryError: unknown,
-  ) => MaybePromise<void>;
+  onLeaseError?: (failure: OutboxLeaseFailure) => MaybePromise<void>;
+  /**
+   * Observer called when a delivery outcome cannot be settled durably.
+   * Observer failures are ignored.
+   */
+  onSettlementError?: (failure: OutboxSettlementFailure) => MaybePromise<void>;
 }
 
 /**
@@ -648,6 +756,15 @@ export interface DrainOutboxResult {
    * Messages moved to dead letter state.
    */
   deadLettered: number;
+  /**
+   * Dead-lettered messages whose claim attempt budget was already exhausted.
+   * This is a subset of `deadLettered`.
+   */
+  abandonedDeadLettered: number;
+  /** Messages delivered or failed whose final storage state is unknown. */
+  settlementFailed: number;
+  /** Messages whose active claim could no longer be confirmed. */
+  leaseLost: number;
 }
 
 /**
@@ -686,6 +803,62 @@ export class OutboxClaimError extends Error {
   }
 }
 
+/**
+ * Error persisted when an eligible message has exhausted its claim attempts
+ * without reaching a terminal settlement.
+ */
+export class OutboxAbandonedClaimError extends Error {
+  /** Message ID whose attempt budget was exhausted. */
+  readonly id: string;
+  /** Number of claims already made. */
+  readonly attempts: number;
+  /** Maximum permitted claim attempts. */
+  readonly maxAttempts: number;
+
+  constructor(args: { id: string; attempts: number; maxAttempts: number }) {
+    super(
+      `Outbox message "${args.id}" exhausted ${args.maxAttempts} claim attempts without a terminal settlement.`,
+    );
+    this.name = "OutboxAbandonedClaimError";
+    this.id = args.id;
+    this.attempts = args.attempts;
+    this.maxAttempts = args.maxAttempts;
+  }
+}
+
+/** Error surfaced when an outbox worker no longer has a confirmed claim. */
+export class OutboxLeaseLostError extends Error {
+  /** Message ID whose ownership was lost. */
+  readonly id: string;
+
+  constructor(args: { id: string; message?: string; cause?: unknown }) {
+    super(
+      args.message ??
+        `Outbox claim for message "${args.id}" is no longer active.`,
+      args.cause === undefined ? undefined : { cause: args.cause },
+    );
+    this.name = "OutboxLeaseLostError";
+    this.id = args.id;
+  }
+}
+
+/** Error surfaced when delivery exceeds the configured active-claim window. */
+export class OutboxMaxActiveDurationError extends Error {
+  /** Message ID whose active window elapsed. */
+  readonly id: string;
+  /** Configured maximum active duration. */
+  readonly maxActiveMs: number;
+
+  constructor(args: { id: string; maxActiveMs: number }) {
+    super(
+      `Outbox delivery for message "${args.id}" exceeded the ${args.maxActiveMs}ms active-claim limit.`,
+    );
+    this.name = "OutboxMaxActiveDurationError";
+    this.id = args.id;
+    this.maxActiveMs = args.maxActiveMs;
+  }
+}
+
 /**
  * Error thrown when an outbox admin operation cannot be completed safely.
  */
@@ -1169,9 +1342,11 @@ export function createMemoryOutbox(
       assertPositiveInteger("limit", options.limit);
       const now = options.now ?? storeNow();
       const leaseMs = options.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
+      assertValidDate("now", now);
       assertPositiveInteger("leaseMs", leaseMs);
       const lockedUntil = new Date(now.getTime() + leaseMs);
       const claimed: ClaimedOutboxMessage[] = [];
+      const deadLettered: OutboxMessage[] = [];
 
       const eligible = [...messages.values()]
         .filter((message) => isEligible(message, now))
@@ -1183,6 +1358,23 @@ export function createMemoryOutbox(
         .slice(0, options.limit);
 
       for (const message of eligible) {
+        if (message.attempts >= message.maxAttempts) {
+          message.status = "deadLettered";
+          message.lastError = serializeOutboxError(
+            new OutboxAbandonedClaimError({
+              id: message.id,
+              attempts: message.attempts,
+              maxAttempts: message.maxAttempts,
+            }),
+          );
+          message.claimToken = null;
+          message.claimedAt = null;
+          message.lockedUntil = null;
+          message.updatedAt = cloneDate(now);
+          deadLettered.push(copyMessage(message));
+          continue;
+        }
+
         message.status = "claimed";
         message.attempts += 1;
         message.claimToken = createStoreId();
@@ -1192,7 +1384,31 @@ export function createMemoryOutbox(
         claimed.push(toClaimedMessage(message));
       }
 
-      return claimed;
+      return { claimed, deadLettered };
+    },
+
+    async renewClaim(input) {
+      assertNonEmptyString("id", input.id);
+      assertNonEmptyString("claimToken", input.claimToken);
+      const message = getClaimedOrThrow(input.id, input.claimToken);
+      const now = input.now ?? storeNow();
+      const leaseMs = input.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
+      assertValidDate("now", now);
+      assertPositiveInteger("leaseMs", leaseMs);
+      if (
+        message.lockedUntil === null ||
+        message.lockedUntil.getTime() <= now.getTime()
+      ) {
+        throw new OutboxClaimError({
+          id: input.id,
+          message: `Outbox message "${input.id}" no longer has an active claim to renew.`,
+        });
+      }
+
+      const lockedUntil = new Date(now.getTime() + leaseMs);
+      message.lockedUntil = cloneDate(lockedUntil);
+      message.updatedAt = cloneDate(now);
+      return { lockedUntil: cloneDate(lockedUntil) };
     },
 
     async markDelivered(input) {
@@ -1200,6 +1416,16 @@ export function createMemoryOutbox(
       assertNonEmptyString("claimToken", input.claimToken);
       const message = getClaimedOrThrow(input.id, input.claimToken);
       const now = input.now ?? storeNow();
+      assertValidDate("now", now);
+      if (
+        message.lockedUntil === null ||
+        message.lockedUntil.getTime() <= now.getTime()
+      ) {
+        throw new OutboxClaimError({
+          id: input.id,
+          message: `Outbox message "${input.id}" no longer has an active claim to settle.`,
+        });
+      }
 
       message.status = "delivered";
       message.deliveredAt = cloneDate(now);
@@ -1214,6 +1440,17 @@ export function createMemoryOutbox(
       assertNonEmptyString("claimToken", input.claimToken);
       const message = getClaimedOrThrow(input.id, input.claimToken);
       const now = input.now ?? storeNow();
+      assertValidDate("now", now);
+      if (input.retryAt) assertValidDate("retryAt", input.retryAt);
+      if (
+        message.lockedUntil === null ||
+        message.lockedUntil.getTime() <= now.getTime()
+      ) {
+        throw new OutboxClaimError({
+          id: input.id,
+          message: `Outbox message "${input.id}" no longer has an active claim to settle.`,
+        });
+      }
 
       message.status = input.deadLetter ? "deadLettered" : "pending";
       message.lastError = serializeOutboxError(input.error);
@@ -1271,7 +1508,16 @@ export async function enqueueEvent<E extends EventPayloadDef>(
   payload: InferEventPayload<E>,
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
-  await parseEventPayload(event, payload);
+  const parsed = await parseEventPayload(event, payload);
+  return await enqueueParsedEvent(outbox, event, parsed, options);
+}
+
+async function enqueueParsedEvent<E extends EventPayloadDef>(
+  outbox: OutboxPort,
+  event: E,
+  payload: InferEventPayload<E>,
+  options: EnqueueTypedOutboxOptions,
+): Promise<OutboxMessage> {
   const trace =
     parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
@@ -1317,7 +1563,10 @@ export function createOutboxEventRecorder(
 ): DomainEventRecorderPort {
   return {
     async record(event, payload, publishOptions) {
-      await enqueueEvent(outbox, event, payload, {
+      const parsed = isEventPayloadParsed(publishOptions)
+        ? payload
+        : await parseEventPayload(event, payload);
+      await enqueueParsedEvent(outbox, event, parsed, {
         ...options,
         trace: publishOptions?.trace ?? options.trace,
       });
@@ -1392,7 +1641,7 @@ function shouldRetryOutboxMessage(
 }
 
 function outboxInstrumentationDetails(
-  message: ClaimedOutboxMessage,
+  message: OutboxMessage,
   details?: Record<string, unknown>,
 ): Record<string, unknown> {
   return {
@@ -1424,11 +1673,11 @@ async function deliverOutboxMessage(
       );
     }
 
-    await parseEventPayload(event, message.payload);
+    const payload = await parseEventPayload(event, message.payload);
     await options.eventBus.publish(
       event,
-      message.payload as never,
-      trace ? { trace } : undefined,
+      payload,
+      markEventPayloadParsed(trace ? { trace } : undefined),
     );
     return;
   }
@@ -1474,20 +1723,1033 @@ async function deliverOutboxMessage(
   );
 }
 
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const OUTBOX_SETTLEMENT_ATTEMPTS = 3;
+const OUTBOX_SETTLEMENT_RETRY_DELAY_MS = 100;
+
+type ResolvedDrainRuntime = {
+  batchSize: number;
+  concurrency: number;
+  leaseMs: number;
+  heartbeatMs: number;
+  maxActiveMs: number;
+  now: () => Date;
+  wait: OutboxDrainWait;
+};
+
+type MessageDrainOutcome = {
+  delivered: number;
+  retried: number;
+  deadLettered: number;
+  settlementFailed: number;
+  leaseLost: number;
+};
+
+type ClaimHeartbeat = {
+  lost: Promise<OutboxLeaseFailure>;
+  stopAndExtend(): Promise<{
+    lockedUntil: Date;
+    renewalError?: unknown;
+    renewalRecovered?: boolean;
+    failure?: OutboxLeaseFailure;
+  }>;
+  stop(): Promise<void>;
+};
+
+type BoundedRenewalResult =
+  | { kind: "succeeded"; lockedUntil: Date }
+  | { kind: "failed"; error: unknown }
+  | { kind: "deadline" }
+  | { kind: "stopped" }
+  | { kind: "waitFailed"; error: unknown };
+
+type BoundedSettlementResult =
+  | { kind: "succeeded" }
+  | { kind: "failed"; error: unknown }
+  | { kind: "deadline" }
+  | { kind: "waitFailed"; error: unknown };
+
+function defaultOutboxWait(
+  delayMs: number,
+  signal: AbortSignal,
+): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = () => {
+      if (timer !== undefined) clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    };
+    timer = setTimeout(finish, delayMs);
+    signal.addEventListener("abort", finish, { once: true });
+  });
+}
+
+function readOutboxNow(now: () => Date): Date {
+  const value = now();
+  assertValidDate("now", value);
+  return value;
+}
+
+function assertTimerDuration(name: string, value: number): void {
+  assertPositiveInteger(name, value);
+  if (value > MAX_TIMER_DELAY_MS) {
+    throw new Error(`${name} must be at most ${MAX_TIMER_DELAY_MS}`);
+  }
+}
+
+function resolveDrainRuntime(
+  options: DrainOutboxOptions,
+): ResolvedDrainRuntime {
+  const batchSize = options.batchSize ?? DEFAULT_OUTBOX_BATCH_SIZE;
+  const concurrency = options.concurrency ?? DEFAULT_OUTBOX_CONCURRENCY;
+  const leaseMs = options.leaseMs ?? DEFAULT_OUTBOX_LEASE_MS;
+  const heartbeatMs =
+    options.heartbeatMs ?? Math.max(1, Math.floor(leaseMs / 3));
+  const maxActiveMs = options.maxActiveMs ?? DEFAULT_OUTBOX_MAX_ACTIVE_MS;
+
+  assertPositiveInteger("batchSize", batchSize);
+  assertPositiveInteger("concurrency", concurrency);
+  if (concurrency > batchSize) {
+    throw new Error("concurrency must be less than or equal to batchSize");
+  }
+  assertTimerDuration("leaseMs", leaseMs);
+  if (leaseMs < 2) throw new Error("leaseMs must be at least 2");
+  assertTimerDuration("heartbeatMs", heartbeatMs);
+  if (heartbeatMs >= leaseMs) {
+    throw new Error("heartbeatMs must be shorter than leaseMs");
+  }
+  assertTimerDuration("maxActiveMs", maxActiveMs);
+
+  return {
+    batchSize,
+    concurrency,
+    leaseMs,
+    heartbeatMs,
+    maxActiveMs,
+    now: options.now ?? (() => new Date()),
+    wait: options.wait ?? defaultOutboxWait,
+  };
+}
+
+async function notifyLeaseFailure(
+  options: DrainOutboxOptions,
+  failure: OutboxLeaseFailure,
+): Promise<void> {
+  try {
+    await options.onLeaseError?.(failure);
+  } catch {
+    // Lease observers cannot change delivery ownership or recovery behavior.
+  }
+}
+
+async function notifySettlementFailure(
+  options: DrainOutboxOptions,
+  failure: OutboxSettlementFailure,
+): Promise<void> {
+  try {
+    await options.onSettlementError?.(failure);
+  } catch {
+    // Settlement observers cannot replace the unknown storage outcome.
+  }
+}
+
+async function runBoundedClaimRenewal(options: {
+  outbox: OutboxPort;
+  message: ClaimedOutboxMessage;
+  runtime: ResolvedDrainRuntime;
+  renewalAt: Date;
+  deadline: Date;
+  signal: AbortSignal;
+}): Promise<BoundedRenewalResult> {
+  const remainingMs = options.deadline.getTime() - options.renewalAt.getTime();
+  if (remainingMs <= 0) return { kind: "deadline" };
+  if (options.signal.aborted) return { kind: "stopped" };
+
+  const waitController = new AbortController();
+  const stopWaiting = () => waitController.abort();
+  options.signal.addEventListener("abort", stopWaiting, { once: true });
+
+  const renewal = Promise.resolve()
+    .then(() =>
+      options.outbox.renewClaim({
+        id: options.message.id,
+        claimToken: options.message.claimToken,
+        now: options.renewalAt,
+        leaseMs: options.runtime.leaseMs,
+      }),
+    )
+    .then(
+      (result) => ({ kind: "succeeded" as const, result }),
+      (error: unknown) => ({ kind: "failed" as const, error }),
+    );
+  const deadline = Promise.resolve()
+    .then(() => options.runtime.wait(remainingMs, waitController.signal))
+    .then(
+      () =>
+        options.signal.aborted
+          ? { kind: "stopped" as const }
+          : { kind: "deadline" as const },
+      (error: unknown) =>
+        options.signal.aborted
+          ? { kind: "stopped" as const }
+          : { kind: "waitFailed" as const, error },
+    );
+
+  const result = await Promise.race([renewal, deadline]);
+  options.signal.removeEventListener("abort", stopWaiting);
+  waitController.abort();
+
+  if (result.kind !== "succeeded") return result;
+  try {
+    const completedAt = readOutboxNow(options.runtime.now);
+    if (completedAt.getTime() >= options.deadline.getTime()) {
+      return { kind: "deadline" };
+    }
+    assertValidDate("lockedUntil", result.result.lockedUntil);
+    if (result.result.lockedUntil.getTime() <= completedAt.getTime()) {
+      return {
+        kind: "failed",
+        error: new Error(
+          `Outbox claim renewal for message "${options.message.id}" returned an expired lease.`,
+        ),
+      };
+    }
+    return {
+      kind: "succeeded",
+      lockedUntil: cloneDate(result.result.lockedUntil),
+    };
+  } catch (error) {
+    return { kind: "failed", error };
+  }
+}
+
+function createClaimHeartbeat(
+  options: DrainOutboxOptions,
+  runtime: ResolvedDrainRuntime,
+  message: ClaimedOutboxMessage,
+  activeUntil: Date,
+): ClaimHeartbeat {
+  const controller = new AbortController();
+  let stopped = false;
+  let lockedUntil = cloneDate(message.lockedUntil);
+  let renewing = false;
+  let firstRenewalError: unknown;
+  let terminalFailure: OutboxLeaseFailure | undefined;
+  let resolveLost: (failure: OutboxLeaseFailure) => void = () => {};
+  const lost = new Promise<OutboxLeaseFailure>((resolve) => {
+    resolveLost = resolve;
+  });
+
+  const fail = (failure: OutboxLeaseFailure) => {
+    if (terminalFailure) return;
+    terminalFailure = failure;
+    stopped = true;
+    controller.abort();
+    resolveLost(failure);
+  };
+
+  const run = async () => {
+    try {
+      let delayMs = runtime.heartbeatMs;
+      while (!stopped) {
+        try {
+          await runtime.wait(delayMs, controller.signal);
+        } catch (error) {
+          if (stopped || controller.signal.aborted) return;
+          fail({
+            error: new OutboxLeaseLostError({
+              id: message.id,
+              message: `Outbox heartbeat scheduling failed for message "${message.id}".`,
+              cause: error,
+            }),
+            message,
+            operation: "renewClaim",
+            state: "lost",
+            confirmedLost: false,
+          });
+          return;
+        }
+        if (stopped || controller.signal.aborted) return;
+
+        const renewalAt = readOutboxNow(runtime.now);
+        const renewalDeadline = new Date(
+          Math.min(lockedUntil.getTime(), activeUntil.getTime()),
+        );
+        const activeDeadlineEndsFirst =
+          activeUntil.getTime() <= lockedUntil.getTime();
+        if (renewalAt.getTime() >= renewalDeadline.getTime()) {
+          fail({
+            error: activeDeadlineEndsFirst
+              ? new OutboxMaxActiveDurationError({
+                  id: message.id,
+                  maxActiveMs: runtime.maxActiveMs,
+                })
+              : new OutboxLeaseLostError({ id: message.id }),
+            message,
+            operation: activeDeadlineEndsFirst
+              ? "maxActiveDuration"
+              : "renewClaim",
+            state: "lost",
+            confirmedLost: !activeDeadlineEndsFirst,
+          });
+          return;
+        }
+
+        renewing = true;
+        let renewal: BoundedRenewalResult;
+        try {
+          renewal = await runBoundedClaimRenewal({
+            outbox: options.outbox,
+            message,
+            runtime,
+            renewalAt,
+            deadline: renewalDeadline,
+            signal: controller.signal,
+          });
+        } catch (error) {
+          renewal = { kind: "failed", error };
+        } finally {
+          renewing = false;
+        }
+
+        if (renewal.kind === "stopped") return;
+        if (renewal.kind === "waitFailed") {
+          fail({
+            error: new OutboxLeaseLostError({
+              id: message.id,
+              message: `Could not enforce the renewal deadline for outbox message "${message.id}".`,
+              cause: renewal.error,
+            }),
+            message,
+            operation: "renewClaim",
+            state: "lost",
+            confirmedLost: false,
+          });
+          return;
+        }
+        if (renewal.kind === "deadline") {
+          fail({
+            error: activeDeadlineEndsFirst
+              ? new OutboxMaxActiveDurationError({
+                  id: message.id,
+                  maxActiveMs: runtime.maxActiveMs,
+                })
+              : new OutboxLeaseLostError({
+                  id: message.id,
+                  message: `Outbox claim renewal for message "${message.id}" did not complete before the lease deadline.`,
+                }),
+            message,
+            operation: activeDeadlineEndsFirst
+              ? "maxActiveDuration"
+              : "renewClaim",
+            state: "lost",
+            confirmedLost: false,
+          });
+          return;
+        }
+        if (renewal.kind === "succeeded") {
+          lockedUntil = renewal.lockedUntil;
+          delayMs = runtime.heartbeatMs;
+          continue;
+        }
+
+        const error = renewal.error;
+        if (error instanceof OutboxClaimError) {
+          fail({
+            error,
+            message,
+            operation: "renewClaim",
+            state: "lost",
+            confirmedLost: true,
+          });
+          return;
+        }
+
+        firstRenewalError ??= error;
+        if (stopped) return;
+        const retryAt = readOutboxNow(runtime.now);
+        const remainingMs = renewalDeadline.getTime() - retryAt.getTime();
+        if (remainingMs <= 0) {
+          fail({
+            error: activeDeadlineEndsFirst
+              ? new OutboxMaxActiveDurationError({
+                  id: message.id,
+                  maxActiveMs: runtime.maxActiveMs,
+                })
+              : new OutboxLeaseLostError({
+                  id: message.id,
+                  message: `Outbox claim renewal for message "${message.id}" did not recover before the lease expired.`,
+                  cause: error,
+                }),
+            message,
+            operation: activeDeadlineEndsFirst
+              ? "maxActiveDuration"
+              : "renewClaim",
+            state: "lost",
+            confirmedLost: false,
+          });
+          return;
+        }
+        delayMs = Math.max(
+          1,
+          Math.min(runtime.heartbeatMs, Math.floor(remainingMs / 3)),
+        );
+      }
+    } catch (error) {
+      if (stopped || controller.signal.aborted) return;
+      fail({
+        error: new OutboxLeaseLostError({
+          id: message.id,
+          message: `Outbox claim renewal failed unexpectedly for message "${message.id}".`,
+          cause: error,
+        }),
+        message,
+        operation: "renewClaim",
+        state: "lost",
+        confirmedLost: false,
+      });
+    }
+  };
+
+  const running = run();
+
+  const stop = async (abortRenewal = true) => {
+    stopped = true;
+    if (abortRenewal || !renewing) controller.abort();
+    await running;
+    controller.abort();
+  };
+
+  return {
+    lost,
+    stop: () => stop(true),
+    async stopAndExtend() {
+      await stop(false);
+      if (terminalFailure) {
+        return { lockedUntil, failure: terminalFailure };
+      }
+
+      const renewalAt = readOutboxNow(runtime.now);
+      const activeDeadlineEndsFirst =
+        activeUntil.getTime() <= lockedUntil.getTime();
+      const finalRenewalDeadline = new Date(
+        Math.min(lockedUntil.getTime(), activeUntil.getTime()),
+      );
+      if (renewalAt.getTime() >= finalRenewalDeadline.getTime()) {
+        return {
+          lockedUntil,
+          failure: {
+            error: activeDeadlineEndsFirst
+              ? new OutboxMaxActiveDurationError({
+                  id: message.id,
+                  maxActiveMs: runtime.maxActiveMs,
+                })
+              : new OutboxLeaseLostError({ id: message.id }),
+            message,
+            operation: activeDeadlineEndsFirst
+              ? "maxActiveDuration"
+              : "renewClaim",
+            state: "lost",
+            confirmedLost: !activeDeadlineEndsFirst,
+          },
+        };
+      }
+
+      const finalController = new AbortController();
+      const renewal = await runBoundedClaimRenewal({
+        outbox: options.outbox,
+        message,
+        runtime,
+        renewalAt,
+        deadline: finalRenewalDeadline,
+        signal: finalController.signal,
+      });
+      finalController.abort();
+
+      if (renewal.kind === "succeeded") {
+        return {
+          lockedUntil: renewal.lockedUntil,
+          renewalError: firstRenewalError,
+          renewalRecovered: firstRenewalError === undefined ? undefined : true,
+        };
+      }
+      if (renewal.kind === "failed") {
+        if (!(renewal.error instanceof OutboxClaimError)) {
+          const failedAt = readOutboxNow(runtime.now);
+          if (
+            failedAt.getTime() < lockedUntil.getTime() &&
+            failedAt.getTime() < activeUntil.getTime()
+          ) {
+            return {
+              lockedUntil,
+              renewalError: renewal.error,
+              renewalRecovered: false,
+            };
+          }
+          if (
+            activeDeadlineEndsFirst &&
+            failedAt.getTime() >= activeUntil.getTime()
+          ) {
+            return {
+              lockedUntil,
+              failure: {
+                error: new OutboxMaxActiveDurationError({
+                  id: message.id,
+                  maxActiveMs: runtime.maxActiveMs,
+                }),
+                message,
+                operation: "maxActiveDuration",
+                state: "lost",
+                confirmedLost: false,
+              },
+            };
+          }
+        }
+        return {
+          lockedUntil,
+          failure: {
+            error: renewal.error,
+            message,
+            operation: "renewClaim",
+            state: "lost",
+            confirmedLost: renewal.error instanceof OutboxClaimError,
+          },
+        };
+      }
+
+      return {
+        lockedUntil,
+        failure: {
+          error:
+            renewal.kind === "waitFailed"
+              ? new OutboxLeaseLostError({
+                  id: message.id,
+                  message: activeDeadlineEndsFirst
+                    ? `Could not enforce the maximum active duration for outbox message "${message.id}".`
+                    : `Could not enforce the final renewal deadline for outbox message "${message.id}".`,
+                  cause: renewal.error,
+                })
+              : activeDeadlineEndsFirst
+                ? new OutboxMaxActiveDurationError({
+                    id: message.id,
+                    maxActiveMs: runtime.maxActiveMs,
+                  })
+                : new OutboxLeaseLostError({
+                    id: message.id,
+                    message: `Outbox claim renewal for message "${message.id}" did not complete before settlement.`,
+                  }),
+          message,
+          operation: activeDeadlineEndsFirst
+            ? "maxActiveDuration"
+            : "renewClaim",
+          state: "lost",
+          confirmedLost: false,
+        },
+      };
+    },
+  };
+}
+
+async function settleClaim(options: {
+  operation: OutboxSettlementFailure["operation"];
+  message: ClaimedOutboxMessage;
+  lockedUntil: Date;
+  activeUntil: Date;
+  runtime: ResolvedDrainRuntime;
+  settle(now: Date): Promise<void>;
+}): Promise<{ ok: true } | { ok: false; error: unknown; claimLost: boolean }> {
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= OUTBOX_SETTLEMENT_ATTEMPTS; attempt += 1) {
+    const settlementAt = readOutboxNow(options.runtime.now);
+    const settlementDeadline = new Date(
+      Math.min(options.lockedUntil.getTime(), options.activeUntil.getTime()),
+    );
+    const settlement = await runBoundedSettlement({
+      runtime: options.runtime,
+      settlementAt,
+      deadline: settlementDeadline,
+      settle: options.settle,
+    });
+    if (settlement.kind === "succeeded") {
+      return { ok: true };
+    }
+    if (settlement.kind === "deadline") {
+      return {
+        ok: false,
+        error: new OutboxLeaseLostError({
+          id: options.message.id,
+          message: `Outbox ${options.operation} for message "${options.message.id}" did not complete before its settlement deadline.`,
+        }),
+        claimLost: true,
+      };
+    }
+    if (settlement.kind === "waitFailed") {
+      return { ok: false, error: settlement.error, claimLost: false };
+    }
+
+    const error = settlement.error;
+    lastError = error;
+    if (error instanceof OutboxClaimError) {
+      return { ok: false, error, claimLost: true };
+    }
+
+    const remainingMs =
+      settlementDeadline.getTime() -
+      readOutboxNow(options.runtime.now).getTime();
+    if (attempt >= OUTBOX_SETTLEMENT_ATTEMPTS || remainingMs <= 0) break;
+
+    const waitController = new AbortController();
+    try {
+      await options.runtime.wait(
+        Math.max(
+          1,
+          Math.min(
+            OUTBOX_SETTLEMENT_RETRY_DELAY_MS * 2 ** (attempt - 1),
+            remainingMs,
+          ),
+        ),
+        waitController.signal,
+      );
+    } catch (error) {
+      return { ok: false, error, claimLost: false };
+    }
+  }
+
+  return { ok: false, error: lastError, claimLost: false };
+}
+
+async function runBoundedSettlement(options: {
+  runtime: ResolvedDrainRuntime;
+  settlementAt: Date;
+  deadline: Date;
+  settle(now: Date): Promise<void>;
+}): Promise<BoundedSettlementResult> {
+  const remainingMs =
+    options.deadline.getTime() - options.settlementAt.getTime();
+  if (remainingMs <= 0) return { kind: "deadline" };
+
+  const waitController = new AbortController();
+  const settlement = Promise.resolve()
+    .then(() => options.settle(options.settlementAt))
+    .then(
+      () => ({ kind: "succeeded" as const }),
+      (error: unknown) => ({ kind: "failed" as const, error }),
+    );
+  const deadline = Promise.resolve()
+    .then(() => options.runtime.wait(remainingMs, waitController.signal))
+    .then(
+      () => ({ kind: "deadline" as const }),
+      (error: unknown) => ({ kind: "waitFailed" as const, error }),
+    );
+
+  const result = await Promise.race([settlement, deadline]);
+  waitController.abort();
+  return result;
+}
+
+async function recordDeadLetter(
+  options: DrainOutboxOptions,
+  instrumentation: ReturnType<typeof createProviderInstrumentation>,
+  jobInstrumentation: ReturnType<typeof createProviderInstrumentation>,
+  message: OutboxMessage,
+  error: unknown,
+  details: Record<string, unknown> = {},
+): Promise<void> {
+  try {
+    await options.onDeadLetter?.(error, message);
+  } catch {
+    // Dead-letter observers must not change the settled message state.
+  }
+  instrumentation.record({
+    type: "outbox",
+    ...options.instrumentationContext,
+    messageId: message.id,
+    messageKind: message.kind,
+    messageName: message.name,
+    status: "deadLettered",
+    details: outboxInstrumentationDetails(message, {
+      ...details,
+      error: serializeOutboxError(error),
+    }),
+  });
+  if (message.kind === "job") {
+    jobInstrumentation.record({
+      type: "job",
+      ...options.instrumentationContext,
+      jobName: message.name,
+      status: "deadLettered",
+      details: outboxInstrumentationDetails(message, {
+        ...details,
+        error: serializeOutboxError(error),
+      }),
+    });
+  }
+}
+
+async function processClaimedMessage(
+  options: DrainOutboxOptions,
+  runtime: ResolvedDrainRuntime,
+  instrumentation: ReturnType<typeof createProviderInstrumentation>,
+  jobInstrumentation: ReturnType<typeof createProviderInstrumentation>,
+  tracing: TracingPort | undefined,
+  message: ClaimedOutboxMessage,
+): Promise<MessageDrainOutcome> {
+  const emptyOutcome = (): MessageDrainOutcome => ({
+    delivered: 0,
+    retried: 0,
+    deadLettered: 0,
+    settlementFailed: 0,
+    leaseLost: 0,
+  });
+  const outcome = emptyOutcome();
+  const startedAt = readOutboxNow(runtime.now);
+  const activeUntil = new Date(startedAt.getTime() + runtime.maxActiveMs);
+  const heartbeat = createClaimHeartbeat(
+    options,
+    runtime,
+    message,
+    activeUntil,
+  );
+  const lifetimeController = new AbortController();
+
+  const parentTrace = parseTraceCarrier(message.trace);
+  const traceAttributes = {
+    "beignet.outbox.message_kind": message.kind,
+    "beignet.outbox.message_name": message.name,
+  } as const;
+  const delivery = Promise.resolve()
+    .then(() =>
+      runWithTracing(
+        tracing,
+        {
+          name: `beignet.outbox deliver ${message.name}`,
+          type: "outbox",
+          kind: "consumer",
+          parent: parentTrace,
+          attributes: traceAttributes,
+          metricAttributes: traceAttributes,
+        },
+        (span) =>
+          deliverOutboxMessage(
+            options,
+            message,
+            captureTraceCarrier(span?.context ?? parentTrace),
+          ),
+      ),
+    )
+    .then(
+      () => ({ kind: "succeeded" as const }),
+      (error: unknown) => ({ kind: "failed" as const, error }),
+    );
+  const maximumActive = Promise.resolve()
+    .then(() => runtime.wait(runtime.maxActiveMs, lifetimeController.signal))
+    .then(
+      () => ({ kind: "maxActive" as const }),
+      (error: unknown) => ({ kind: "waitFailed" as const, error }),
+    );
+  const leaseLost = heartbeat.lost.then((failure) => ({
+    kind: "leaseLost" as const,
+    failure,
+  }));
+
+  const deliveryOutcome = await Promise.race([
+    delivery,
+    maximumActive,
+    leaseLost,
+  ]);
+  lifetimeController.abort();
+
+  if (deliveryOutcome.kind === "maxActive") {
+    await heartbeat.stop();
+    const failure: OutboxLeaseFailure = {
+      error: new OutboxMaxActiveDurationError({
+        id: message.id,
+        maxActiveMs: runtime.maxActiveMs,
+      }),
+      message,
+      operation: "maxActiveDuration",
+      state: "lost",
+      confirmedLost: false,
+    };
+    await notifyLeaseFailure(options, failure);
+    instrumentation.custom({
+      name: "outbox.lease.lost",
+      label: "Outbox claim no longer confirmed",
+      summary: `Stopped renewing ${message.kind} "${message.name}" after its active-delivery limit`,
+      details: outboxInstrumentationDetails(message, {
+        operation: failure.operation,
+        state: failure.state,
+        error: serializeOutboxError(failure.error),
+      }),
+    });
+    outcome.leaseLost = 1;
+    return outcome;
+  }
+
+  if (deliveryOutcome.kind === "waitFailed") {
+    await heartbeat.stop();
+    const failure: OutboxLeaseFailure = {
+      error: new OutboxLeaseLostError({
+        id: message.id,
+        message: `Could not enforce the active-delivery limit for outbox message "${message.id}".`,
+        cause: deliveryOutcome.error,
+      }),
+      message,
+      operation: "maxActiveDuration",
+      state: "lost",
+      confirmedLost: false,
+    };
+    await notifyLeaseFailure(options, failure);
+    instrumentation.custom({
+      name: "outbox.lease.lost",
+      label: "Outbox claim no longer confirmed",
+      summary: `Could not enforce the active-delivery limit for ${message.kind} "${message.name}"`,
+      details: outboxInstrumentationDetails(message, {
+        operation: failure.operation,
+        state: failure.state,
+        error: serializeOutboxError(failure.error),
+      }),
+    });
+    outcome.leaseLost = 1;
+    return outcome;
+  }
+
+  if (deliveryOutcome.kind === "leaseLost") {
+    await heartbeat.stop();
+    await notifyLeaseFailure(options, deliveryOutcome.failure);
+    instrumentation.custom({
+      name: "outbox.lease.lost",
+      label: "Outbox claim lost",
+      summary: `Could not keep the claim for ${message.kind} "${message.name}" active`,
+      details: outboxInstrumentationDetails(message, {
+        operation: deliveryOutcome.failure.operation,
+        state: deliveryOutcome.failure.state,
+        confirmedLost: deliveryOutcome.failure.confirmedLost,
+        error: serializeOutboxError(deliveryOutcome.failure.error),
+      }),
+    });
+    outcome.leaseLost = 1;
+    return outcome;
+  }
+
+  const lease = await heartbeat.stopAndExtend();
+  if (lease.failure) {
+    await notifyLeaseFailure(options, lease.failure);
+    instrumentation.custom({
+      name: "outbox.lease.lost",
+      label: "Outbox claim lost",
+      summary: `Could not confirm the claim for ${message.kind} "${message.name}" before settlement`,
+      details: outboxInstrumentationDetails(message, {
+        operation: lease.failure.operation,
+        state: lease.failure.state,
+        confirmedLost: lease.failure.confirmedLost,
+        error: serializeOutboxError(lease.failure.error),
+      }),
+    });
+    outcome.leaseLost = 1;
+    return outcome;
+  }
+
+  const reportRenewalOutcome = async () => {
+    if (lease.renewalError === undefined) return;
+    const failure: OutboxLeaseFailure = {
+      error: lease.renewalError,
+      message,
+      operation: "renewClaim",
+      state: lease.renewalRecovered ? "recovered" : "degraded",
+      confirmedLost: false,
+    };
+    await notifyLeaseFailure(options, failure);
+    instrumentation.custom({
+      name: lease.renewalRecovered
+        ? "outbox.lease.renewal.recovered"
+        : "outbox.lease.renewal.degraded",
+      label: lease.renewalRecovered
+        ? "Outbox claim renewal recovered"
+        : "Outbox claim renewal degraded",
+      summary: lease.renewalRecovered
+        ? `Recovered claim renewal for ${message.kind} "${message.name}"`
+        : `Continued ${message.kind} "${message.name}" settlement under its last confirmed lease`,
+      details: outboxInstrumentationDetails(message, {
+        state: failure.state,
+        error: serializeOutboxError(lease.renewalError),
+      }),
+    });
+  };
+
+  if (deliveryOutcome.kind === "succeeded") {
+    const settlement = await settleClaim({
+      operation: "markDelivered",
+      message,
+      lockedUntil: lease.lockedUntil,
+      activeUntil,
+      runtime,
+      settle: (now) =>
+        options.outbox.markDelivered({
+          id: message.id,
+          claimToken: message.claimToken,
+          now,
+        }),
+    });
+    await reportRenewalOutcome();
+    if (!settlement.ok) {
+      const failure: OutboxSettlementFailure = {
+        error: settlement.error,
+        message,
+        operation: "markDelivered",
+        deliverySucceeded: true,
+      };
+      await notifySettlementFailure(options, failure);
+      instrumentation.custom({
+        name: "outbox.settlement.failed",
+        label: "Outbox settlement failed",
+        summary: `Delivered ${message.kind} "${message.name}", but could not confirm its durable acknowledgement`,
+        details: outboxInstrumentationDetails(message, {
+          operation: failure.operation,
+          deliverySucceeded: true,
+          settlementError: serializeOutboxError(settlement.error),
+        }),
+      });
+      outcome.settlementFailed = 1;
+      if (settlement.claimLost) outcome.leaseLost = 1;
+      return outcome;
+    }
+
+    instrumentation.record({
+      type: "outbox",
+      ...options.instrumentationContext,
+      messageId: message.id,
+      messageKind: message.kind,
+      messageName: message.name,
+      status: "delivered",
+      details: outboxInstrumentationDetails(message),
+    });
+    outcome.delivered = 1;
+    return outcome;
+  }
+
+  const deliveryError = deliveryOutcome.error;
+  const failedAt = readOutboxNow(runtime.now);
+  const shouldRetry = shouldRetryOutboxMessage(options, message, deliveryError);
+  const deadLetter = !shouldRetry;
+  const retryDelayMs = deadLetter
+    ? 0
+    : resolveRetryDelayMs(options, message, deliveryError, failedAt);
+  const retryAt = deadLetter
+    ? undefined
+    : new Date(failedAt.getTime() + retryDelayMs);
+  const settlement = await settleClaim({
+    operation: "markFailed",
+    message,
+    lockedUntil: lease.lockedUntil,
+    activeUntil,
+    runtime,
+    settle: (now) =>
+      options.outbox.markFailed({
+        id: message.id,
+        claimToken: message.claimToken,
+        error: deliveryError,
+        deadLetter,
+        now,
+        retryAt,
+      }),
+  });
+
+  await reportRenewalOutcome();
+
+  try {
+    await options.onError?.(deliveryError, message);
+  } catch {
+    // Delivery observers cannot change retry, dead-letter, or recovery state.
+  }
+
+  if (!settlement.ok) {
+    const failure: OutboxSettlementFailure = {
+      error: settlement.error,
+      message,
+      operation: "markFailed",
+      deliverySucceeded: false,
+      deliveryError,
+    };
+    await notifySettlementFailure(options, failure);
+    instrumentation.custom({
+      name: "outbox.settlement.failed",
+      label: "Outbox settlement failed",
+      summary: `Could not settle failed ${message.kind} "${message.name}"`,
+      details: outboxInstrumentationDetails(message, {
+        operation: failure.operation,
+        deliverySucceeded: false,
+        deliveryError: serializeOutboxError(deliveryError),
+        settlementError: serializeOutboxError(settlement.error),
+      }),
+    });
+    outcome.settlementFailed = 1;
+    if (settlement.claimLost) outcome.leaseLost = 1;
+    return outcome;
+  }
+
+  if (deadLetter) {
+    await recordDeadLetter(
+      options,
+      instrumentation,
+      jobInstrumentation,
+      message,
+      deliveryError,
+    );
+    outcome.deadLettered = 1;
+    return outcome;
+  }
+
+  instrumentation.record({
+    type: "outbox",
+    ...options.instrumentationContext,
+    messageId: message.id,
+    messageKind: message.kind,
+    messageName: message.name,
+    status: "retryScheduled",
+    details: outboxInstrumentationDetails(message, {
+      retryDelayMs,
+      retryAt: retryAt?.toISOString(),
+      error: serializeOutboxError(deliveryError),
+    }),
+  });
+  if (message.kind === "job") {
+    jobInstrumentation.record({
+      type: "job",
+      ...options.instrumentationContext,
+      jobName: message.name,
+      status: "retryScheduled",
+      details: outboxInstrumentationDetails(message, {
+        retryDelayMs,
+        retryAt: retryAt?.toISOString(),
+        error: serializeOutboxError(deliveryError),
+      }),
+    });
+  }
+  outcome.retried = 1;
+  return outcome;
+}
+
 /**
- * Claim and deliver one batch of outbox messages.
+ * Claim and deliver one bounded set 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
- * and delivery transports. Required transports are validated before a batch
- * is claimed. Failed messages are retried with backoff until `maxAttempts`,
- * then dead-lettered.
+ * The drain claims only enough messages to fill active delivery slots and
+ * renews each active claim until delivery settles or reaches its configured
+ * maximum duration. It remains an at-least-once transport: a process can still
+ * terminate after the external effect succeeds but before acknowledgement.
  */
 export async function drainOutbox(
   options: DrainOutboxOptions,
 ): Promise<DrainOutboxResult> {
-  const batchSize = options.batchSize ?? 100;
-  assertPositiveInteger("batchSize", batchSize);
+  const runtime = resolveDrainRuntime(options);
+  assertOutboxDrainPort(options.outbox);
   assertOutboxDeliveryCapabilities(options);
   const instrumentation = createProviderInstrumentation(
     options.instrumentation,
@@ -1504,165 +2766,110 @@ export async function drainOutbox(
     },
   );
   const tracing = resolveTracingPort(options.instrumentation);
-
-  const now = options.now ?? new Date();
-  const messages = await options.outbox.claimBatch({
-    limit: batchSize,
-    now,
-    leaseMs: options.leaseMs,
-  });
   const result: DrainOutboxResult = {
-    claimed: messages.length,
+    claimed: 0,
     delivered: 0,
     retried: 0,
     deadLettered: 0,
+    abandonedDeadLettered: 0,
+    settlementFailed: 0,
+    leaseLost: 0,
   };
-
-  for (const message of messages) {
-    try {
-      const parentTrace = parseTraceCarrier(message.trace);
-      const traceAttributes = {
-        "beignet.outbox.message_kind": message.kind,
-        "beignet.outbox.message_name": message.name,
-      } as const;
-      await runWithTracing(
-        tracing,
-        {
-          name: `beignet.outbox deliver ${message.name}`,
-          type: "outbox",
-          kind: "consumer",
-          parent: parentTrace,
-          attributes: traceAttributes,
-          metricAttributes: traceAttributes,
-        },
-        (span) =>
-          deliverOutboxMessage(
-            options,
-            message,
-            captureTraceCarrier(span?.context ?? parentTrace),
-          ),
-      );
-      await options.outbox.markDelivered({
-        id: message.id,
-        claimToken: message.claimToken,
-        now,
+  let remaining = runtime.batchSize;
+  let sourceExhausted = false;
+
+  while (remaining > 0 && !sourceExhausted) {
+    const active: ClaimedOutboxMessage[] = [];
+    const abandoned: OutboxMessage[] = [];
+
+    while (active.length < runtime.concurrency && remaining > 0) {
+      const limit = Math.min(runtime.concurrency - active.length, remaining);
+      const selected = await options.outbox.claimBatch({
+        limit,
+        now: readOutboxNow(runtime.now),
+        leaseMs: runtime.leaseMs,
       });
-      instrumentation.record({
-        type: "outbox",
-        ...options.instrumentationContext,
-        messageId: message.id,
-        messageKind: message.kind,
-        messageName: message.name,
-        status: "delivered",
-        details: outboxInstrumentationDetails(message),
-      });
-      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 selectedCount =
+        selected.claimed.length + selected.deadLettered.length;
+      if (selectedCount === 0) {
+        sourceExhausted = true;
+        break;
       }
-      const shouldRetry = shouldRetryOutboxMessage(options, message, error);
-      const deadLetter = !shouldRetry;
-      const retryDelayMs = deadLetter
-        ? 0
-        : resolveRetryDelayMs(options, message, error, now);
-      try {
-        await options.outbox.markFailed({
-          id: message.id,
-          claimToken: message.claimToken,
-          error,
-          deadLetter,
-          now,
-          retryAt: deadLetter
-            ? undefined
-            : new Date(now.getTime() + retryDelayMs),
-        });
-      } catch (settlementError) {
-        try {
-          await options.onSettlementError?.(settlementError, message, error);
-        } catch {
-          // Preserve the settlement failure when its observer also fails.
-        }
-        instrumentation.custom({
-          name: "outbox.settlement.failed",
-          label: "Outbox settlement failed",
-          summary: `Could not settle failed ${message.kind} "${message.name}"`,
-          details: outboxInstrumentationDetails(message, {
-            deliveryError: serializeOutboxError(error),
-            settlementError: serializeOutboxError(settlementError),
-          }),
-        });
-        continue;
+      if (selectedCount > limit) {
+        throw new Error(
+          `Outbox claimBatch returned ${selectedCount} messages for a limit of ${limit}.`,
+        );
       }
 
-      if (deadLetter) {
-        try {
-          await options.onDeadLetter?.(error, message);
-        } catch {
-          // Dead-letter observers must not change the settled message state.
-        }
-        instrumentation.record({
-          type: "outbox",
-          ...options.instrumentationContext,
-          messageId: message.id,
-          messageKind: message.kind,
-          messageName: message.name,
-          status: "deadLettered",
-          details: outboxInstrumentationDetails(message, {
-            error: serializeOutboxError(error),
-          }),
-        });
-        if (message.kind === "job") {
-          jobInstrumentation.record({
-            type: "job",
-            ...options.instrumentationContext,
-            jobName: message.name,
-            status: "deadLettered",
-            details: outboxInstrumentationDetails(message, {
-              error: serializeOutboxError(error),
-            }),
-          });
-        }
-        result.deadLettered += 1;
-      } else {
-        const retryAt = new Date(now.getTime() + retryDelayMs).toISOString();
-        instrumentation.record({
-          type: "outbox",
-          ...options.instrumentationContext,
-          messageId: message.id,
-          messageKind: message.kind,
-          messageName: message.name,
-          status: "retryScheduled",
-          details: outboxInstrumentationDetails(message, {
-            retryDelayMs,
-            retryAt,
-            error: serializeOutboxError(error),
-          }),
-        });
-        if (message.kind === "job") {
-          jobInstrumentation.record({
-            type: "job",
-            ...options.instrumentationContext,
-            jobName: message.name,
-            status: "retryScheduled",
-            details: outboxInstrumentationDetails(message, {
-              retryDelayMs,
-              retryAt,
-              error: serializeOutboxError(error),
-            }),
-          });
-        }
-        result.retried += 1;
-      }
+      remaining -= selectedCount;
+      result.claimed += selected.claimed.length;
+      active.push(...selected.claimed);
+      abandoned.push(...selected.deadLettered);
+    }
+
+    // Construct active delivery promises first so their heartbeats protect
+    // freshly claimed rows while abandoned-message observers run.
+    const outcomePromises = active.map((message) =>
+      processClaimedMessage(
+        options,
+        runtime,
+        instrumentation,
+        jobInstrumentation,
+        tracing,
+        message,
+      ),
+    );
+    const abandonedPromises = abandoned.map(async (message) => {
+      const error = new OutboxAbandonedClaimError({
+        id: message.id,
+        attempts: message.attempts,
+        maxAttempts: message.maxAttempts,
+      });
+      await recordDeadLetter(
+        options,
+        instrumentation,
+        jobInstrumentation,
+        message,
+        error,
+        { abandoned: true },
+      );
+    });
+    const [outcomes] = await Promise.all([
+      Promise.all(outcomePromises),
+      Promise.all(abandonedPromises),
+    ]);
+    result.deadLettered += abandoned.length;
+    result.abandonedDeadLettered += abandoned.length;
+
+    for (const outcome of outcomes) {
+      result.delivered += outcome.delivered;
+      result.retried += outcome.retried;
+      result.deadLettered += outcome.deadLettered;
+      result.settlementFailed += outcome.settlementFailed;
+      result.leaseLost += outcome.leaseLost;
     }
   }
 
   return result;
 }
 
+function assertOutboxDrainPort(outbox: OutboxPort): void {
+  const candidate = outbox as unknown as Record<string, unknown>;
+  const missing = [
+    "claimBatch",
+    "renewClaim",
+    "markDelivered",
+    "markFailed",
+  ].filter((method) => typeof candidate[method] !== "function");
+  if (missing.length > 0) {
+    throw new Error(
+      `Cannot drain this outbox: the outbox port is missing ${missing
+        .map((method) => `${method}()`)
+        .join(", ")}.`,
+    );
+  }
+}
+
 function assertOutboxDeliveryCapabilities(options: DrainOutboxOptions): void {
   const missing: string[] = [];