@beignet/core 0.0.50 → 0.0.52

package/dist/outbox/index.js

@@ -4,7 +4,7 @@
  * Durable outbox primitives for transactionally recording events and jobs that
  * should be delivered after the owning database transaction commits.
  */
-import { parseEventPayload, } from "../events/index.js";
+import { prepareEventPayloadForTransport, } from "../events/index.js";
 import { getJobRetryDelayMs, getJobRetryMaxAttempts, parseJobPayload, SINGLE_ATTEMPT_DISPATCH, shouldRetryJob, } from "../jobs/index.js";
 import { createProviderInstrumentation, } from "../providers/index.js";
 import { captureTraceCarrier, parseTraceCarrier, resolveTracingPort, runWithTracing, } from "../tracing/index.js";
@@ -12,6 +12,18 @@ import { captureTraceCarrier, parseTraceCarrier, resolveTracingPort, runWithTrac
  * 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.
  */
@@ -52,6 +64,49 @@ export class OutboxClaimError extends Error {
         this.id = args.id;
     }
 }
+/**
+ * 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. */
+    id;
+    /** Number of claims already made. */
+    attempts;
+    /** Maximum permitted claim attempts. */
+    maxAttempts;
+    constructor(args) {
+        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. */
+    id;
+    constructor(args) {
+        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. */
+    id;
+    /** Configured maximum active duration. */
+    maxActiveMs;
+    constructor(args) {
+        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.
  */
@@ -425,9 +480,11 @@ export function createMemoryOutbox(storeOptions = {}) {
             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 = [];
+            const deadLettered = [];
             const eligible = [...messages.values()]
                 .filter((message) => isEligible(message, now))
                 .sort((a, b) => {
@@ -438,6 +495,20 @@ export function createMemoryOutbox(storeOptions = {}) {
             })
                 .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();
@@ -446,13 +517,41 @@ export function createMemoryOutbox(storeOptions = {}) {
                 message.updatedAt = cloneDate(now);
                 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) {
             assertNonEmptyString("id", input.id);
             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);
             message.claimToken = null;
@@ -465,6 +564,16 @@ export function createMemoryOutbox(storeOptions = {}) {
             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);
             message.availableAt = input.retryAt
@@ -505,13 +614,16 @@ export function defineOutboxRegistry(input) {
  * Validate an event payload and enqueue it as an outbox message.
  */
 export async function enqueueEvent(outbox, event, payload, options = {}) {
-    await parseEventPayload(event, payload);
+    const prepared = await prepareEventPayloadForTransport(event, payload);
+    return await enqueueTransportEvent(outbox, event, prepared.transportValue, options);
+}
+async function enqueueTransportEvent(outbox, event, payload, options) {
     const trace = parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
     return outbox.enqueue({
         id: options.id,
         kind: "event",
         name: event.name,
-        payload: toOutboxJsonValue(payload),
+        payload,
         trace,
         availableAt: options.availableAt,
         maxAttempts: options.maxAttempts,
@@ -539,9 +651,10 @@ export async function enqueueJob(outbox, job, payload, options = {}) {
 export function createOutboxEventRecorder(outbox, options = {}) {
     return {
         async record(event, payload, publishOptions) {
-            await enqueueEvent(outbox, event, payload, {
+            const prepared = await prepareEventPayloadForTransport(event, payload, publishOptions);
+            await enqueueTransportEvent(outbox, event, prepared.transportValue, {
                 ...options,
-                trace: publishOptions?.trace ?? options.trace,
+                trace: prepared.publishOptions.trace ?? options.trace,
             });
         },
     };
@@ -612,8 +725,8 @@ async function deliverOutboxMessage(options, message, trace) {
         if (!event) {
             throw new OutboxRegistryError(`Outbox registry does not include event "${message.name}".`);
         }
-        await parseEventPayload(event, message.payload);
-        await options.eventBus.publish(event, message.payload, trace ? { trace } : undefined);
+        const prepared = await prepareEventPayloadForTransport(event, message.payload, trace ? { trace } : undefined);
+        await options.eventBus.publish(event, prepared.payload, prepared.publishOptions);
         return;
     }
     if (!options.jobs) {
@@ -640,18 +753,835 @@ async function deliverOutboxMessage(options, message, trace) {
     }
     await options.jobs.dispatch(job, message.payload, trace ? { trace } : undefined);
 }
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const OUTBOX_SETTLEMENT_ATTEMPTS = 3;
+const OUTBOX_SETTLEMENT_RETRY_DELAY_MS = 100;
+function defaultOutboxWait(delayMs, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        let timer;
+        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) {
+    const value = now();
+    assertValidDate("now", value);
+    return value;
+}
+function assertTimerDuration(name, value) {
+    assertPositiveInteger(name, value);
+    if (value > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${name} must be at most ${MAX_TIMER_DELAY_MS}`);
+    }
+}
+function resolveDrainRuntime(options) {
+    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, failure) {
+    try {
+        await options.onLeaseError?.(failure);
+    }
+    catch {
+        // Lease observers cannot change delivery ownership or recovery behavior.
+    }
+}
+async function notifySettlementFailure(options, failure) {
+    try {
+        await options.onSettlementError?.(failure);
+    }
+    catch {
+        // Settlement observers cannot replace the unknown storage outcome.
+    }
+}
+async function runBoundedClaimRenewal(options) {
+    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", result }), (error) => ({ kind: "failed", error }));
+    const deadline = Promise.resolve()
+        .then(() => options.runtime.wait(remainingMs, waitController.signal))
+        .then(() => options.signal.aborted
+        ? { kind: "stopped" }
+        : { kind: "deadline" }, (error) => options.signal.aborted
+        ? { kind: "stopped" }
+        : { kind: "waitFailed", 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, runtime, message, activeUntil) {
+    const controller = new AbortController();
+    let stopped = false;
+    let lockedUntil = cloneDate(message.lockedUntil);
+    let renewing = false;
+    let firstRenewalError;
+    let terminalFailure;
+    let resolveLost = () => { };
+    const lost = new Promise((resolve) => {
+        resolveLost = resolve;
+    });
+    const fail = (failure) => {
+        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;
+                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) {
+    let lastError;
+    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) {
+    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" }), (error) => ({ kind: "failed", error }));
+    const deadline = Promise.resolve()
+        .then(() => options.runtime.wait(remainingMs, waitController.signal))
+        .then(() => ({ kind: "deadline" }), (error) => ({ kind: "waitFailed", error }));
+    const result = await Promise.race([settlement, deadline]);
+    waitController.abort();
+    return result;
+}
+async function recordDeadLetter(options, instrumentation, jobInstrumentation, message, error, details = {}) {
+    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, runtime, instrumentation, jobInstrumentation, tracing, message) {
+    const emptyOutcome = () => ({
+        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,
+    };
+    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" }), (error) => ({ kind: "failed", error }));
+    const maximumActive = Promise.resolve()
+        .then(() => runtime.wait(runtime.maxActiveMs, lifetimeController.signal))
+        .then(() => ({ kind: "maxActive" }), (error) => ({ kind: "waitFailed", error }));
+    const leaseLost = heartbeat.lost.then((failure) => ({
+        kind: "leaseLost",
+        failure,
+    }));
+    const deliveryOutcome = await Promise.race([
+        delivery,
+        maximumActive,
+        leaseLost,
+    ]);
+    lifetimeController.abort();
+    if (deliveryOutcome.kind === "maxActive") {
+        await heartbeat.stop();
+        const failure = {
+            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 = {
+            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 = {
+            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 = {
+                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 = {
+            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) {
-    const batchSize = options.batchSize ?? 100;
-    assertPositiveInteger("batchSize", batchSize);
+    const runtime = resolveDrainRuntime(options);
+    assertOutboxDrainPort(options.outbox);
     assertOutboxDeliveryCapabilities(options);
     const instrumentation = createProviderInstrumentation(options.instrumentation, {
         providerName: "outbox",
@@ -662,157 +1592,81 @@ export async function drainOutbox(options) {
         watcher: "jobs",
     });
     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 = {
-        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,
-            };
-            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 = [];
+        const abandoned = [];
+        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);
+            const selectedCount = selected.claimed.length + selected.deadLettered.length;
+            if (selectedCount === 0) {
+                sourceExhausted = true;
+                break;
             }
-            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);
-            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 (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;
+            if (selectedCount > limit) {
+                throw new Error(`Outbox claimBatch returned ${selectedCount} messages for a limit of ${limit}.`);
             }
+            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) {
+    const candidate = outbox;
+    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) {
     const missing = [];
     if (options.registry.events.size > 0 && !options.eventBus) {