@openlup/outbox 0.0.0 → 0.13.1

package/dist/factory.js

@@ -0,0 +1,99 @@
+import metadata from "../package.json" with { type: "json" };
+import { validateScheduledConfig } from "./config.js";
+import { runOutboxDispatchWorker } from "./worker.js";
+/** @beta Lease-bound dispatch and terminal compaction, with no host entrypoint. */
+export function createOutbox(ports, options) {
+    options = { ...options, config: { ...options.config }, knownEventTypes: [...options.knownEventTypes],
+        requiredSchema: { ...options.requiredSchema, objects: options.requiredSchema.objects.map((o) => ({ ...o })) },
+        ...(options.prune ? { prune: { ...options.prune } } : {}) };
+    ports = { ...ports };
+    const descriptors = ports.descriptors.map((d) => Object.freeze({ eventType: d.eventType, timeoutMs: d.timeoutMs }));
+    validateScheduledConfig(options.config, options.hostLimitSeconds, descriptors.map((d) => d.timeoutMs));
+    const positive = (key, value, maximum) => {
+        if (!Number.isInteger(value) || value <= 0 || value > maximum)
+            throw new Error(`@openlup/outbox: ${key}: use a positive integer at most ${maximum}`);
+    };
+    positive("leaseSeconds", options.leaseSeconds, 3600);
+    if (options.leaseSeconds < options.hostLimitSeconds)
+        throw new Error("@openlup/outbox: leaseSeconds: cover the full host execution window, including finish time");
+    positive("cadenceSeconds", options.cadenceSeconds, 86400);
+    if (new Set(descriptors.map((d) => d.eventType)).size !== descriptors.length || descriptors.some((d) => !d.eventType.trim()))
+        throw new Error("@openlup/outbox: descriptors: supply one descriptor for each composed event handler");
+    if (!ports.store || !ports.lease || typeof ports.buildHandlers !== "function")
+        throw new Error("@openlup/outbox: ports: supply store, lease and handler builder");
+    const suppliedLogger = ports.logger ?? console;
+    const log = (method, args) => { try {
+        suppliedLogger[method](...args);
+    }
+    catch { /* Diagnostics cannot skip finish or cleanup. */ } };
+    const logger = { warn: (...args) => log("warn", args), error: (...args) => log("error", args) };
+    const config = { ...options.config }, knownEventTypes = [...options.knownEventTypes];
+    const pruning = options.prune?.enabled === true;
+    const retention = { processedDays: options.prune?.processedDays ?? 30, discardedDays: options.prune?.discardedDays ?? 90, limit: options.prune?.limit ?? 500 };
+    if (pruning) {
+        if (!ports.compactor)
+            throw new Error("@openlup/outbox: compactor: bind terminal compaction when prune is selected");
+        positive("prune.cadenceSeconds", options.prune.cadenceSeconds, 604800);
+        positive("processedDays", retention.processedDays, 3650);
+        positive("discardedDays", retention.discardedDays, 3650);
+        positive("limit", retention.limit, 10000);
+    }
+    const summary = (reason) => ({ ok: false, checked: 0, updated: 0, failures: 1, skipped: false, reason });
+    const run = async (jobName, invocation, dispatch) => {
+        const claim = await ports.lease.claimJobRun(jobName, invocation, options.leaseSeconds);
+        if (!claim.acquired)
+            return { outcome: claim.reason === "job_disabled" ? "disabled" : "skipped", detail: { ok: true, checked: 0, updated: 0, failures: 0, skipped: true, reason: claim.reason } };
+        if (!claim.runId)
+            throw new Error("@openlup/outbox: acquired lease has no run id");
+        let scope;
+        let hookMetadata = {};
+        let detail = summary("outbox_dispatch_failed");
+        let failure = false;
+        try {
+            try {
+                if (dispatch) {
+                    const context = { runId: claim.runId, invocation };
+                    hookMetadata = await ports.beforeDispatch?.(context) ?? {};
+                    const built = await ports.buildHandlers(context);
+                    scope = "handlers" in built ? built : { handlers: built };
+                    const actual = scope.handlers;
+                    if (actual.size !== descriptors.length || descriptors.some((d) => actual.get(d.eventType)?.eventType !== d.eventType || actual.get(d.eventType)?.timeoutMs !== d.timeoutMs))
+                        throw new Error("outbox_registry_descriptor_mismatch");
+                    detail = await runOutboxDispatchWorker({ store: ports.store, registry: actual, config, knownEventTypes, diagnostics: ports.diagnostics, clock: ports.clock, logger });
+                }
+                else {
+                    const count = await ports.compactor.compact(retention);
+                    detail = { ok: true, checked: count, updated: count, failures: 0, skipped: false };
+                }
+            }
+            catch (error) {
+                failure = true;
+                detail = summary(message(error));
+                logger.error("[outbox-dispatch] schedule_failed", message(error));
+            }
+            // Reserved run identity and worker counters override hook metadata.
+            const extra = { ...hookMetadata, ...detail, runId: claim.runId };
+            const finishApplied = await ports.lease.finishJobRun(jobName, claim.runId, invocation, failure ? "failed" : "success", detail, extra);
+            return { outcome: failure || !finishApplied ? "failed" : detail.skipped ? "skipped" : "success", detail, finishApplied };
+        }
+        catch (error) {
+            logger.error("[outbox-dispatch] finish_job_run_failed", message(error));
+            throw error;
+        }
+        finally {
+            try {
+                await scope?.close?.();
+            }
+            catch (error) {
+                logger.error("[outbox-dispatch] handler_scope_close_failed", message(error));
+            }
+        }
+    };
+    const schedules = [{ id: "outbox-dispatch", cadenceSeconds: options.cadenceSeconds, run: (invocation) => run("outbox-dispatch", invocation, true) },
+        ...(pruning ? [{ id: "outbox-prune", cadenceSeconds: options.prune.cadenceSeconds, run: (invocation) => run("outbox-prune", invocation, false) }] : [])];
+    return { handlers: descriptors, schedules, routes: [], manifest: {
+            name: metadata.name, version: metadata.version, kind: "rail", emits: [], handles: descriptors.map((d) => d.eventType),
+            schedules: schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), routes: [], requiredPorts: ["store", "lease", ...(pruning ? ["compactor"] : [])], env: [], requiredSchema: options.requiredSchema,
+        } };
+}
+function message(error) { return (error instanceof Error ? error.message : String(error)).slice(0, 180); }

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./contracts.js";
+export { runOutboxDispatchWorker } from "./worker.js";
+export { OutboxHandlerExecutionTrace } from "./trace.js";
+export { uniqueRegistry, composeHandlers, claimAllowlist } from "./registry.js";
+export { readOutboxDispatchConfig, validateScheduledConfig } from "./config.js";
+export { buildOutboxEnqueue } from "./enqueue.js";
+export type { EnqueueEvent } from "./enqueue.js";
+export { withPayloadSchema } from "./typedEvents.js";
+export { createOutbox } from "./factory.js";
+export type { OutboxFactoryPorts, OutboxFactoryOptions, OutboxScheduleResult, HandlerScope, CompactionPort } from "./factory.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./contracts.js";
+export { runOutboxDispatchWorker } from "./worker.js";
+export { OutboxHandlerExecutionTrace } from "./trace.js";
+export { uniqueRegistry, composeHandlers, claimAllowlist } from "./registry.js";
+export { readOutboxDispatchConfig, validateScheduledConfig } from "./config.js";
+export { buildOutboxEnqueue } from "./enqueue.js";
+export { withPayloadSchema } from "./typedEvents.js";
+export { createOutbox } from "./factory.js";

package/dist/postgres.d.ts

@@ -0,0 +1,10 @@
+import type { SqlExecutor, RequiredSchema } from "@openlup/core/readiness";
+import type { OutboxStore } from "./contracts.js";
+import type { CompactionPort } from "./factory.js";
+/** @beta These identities describe the shipped default adapter only. */
+export declare const POSTGRES_OUTBOX_SCHEMA: RequiredSchema;
+/** @beta Supply an autocommit executor or a per-operation transaction that commits before resolve.
+ * Never pass a producer transaction or retain an operation transaction across handler I/O. */
+export declare function createPostgresOutboxStore(executor: SqlExecutor): OutboxStore;
+/** @beta Compacts terminal payload/error, retaining the event and its unique key. */
+export declare function createPostgresOutboxCompactor(executor: SqlExecutor): CompactionPort;

package/dist/postgres.js

@@ -0,0 +1,79 @@
+/** @beta These identities describe the shipped default adapter only. */
+export const POSTGRES_OUTBOX_SCHEMA = {
+    version: "outbox-1", migration: "sql/0001_outbox.sql", objects: [
+        { kind: "table", name: "public.outbox_events" }, { kind: "table", name: "public.outbox_dormant_event_types" },
+        ...["id", "created_at", "available_at", "processed_at", "aggregate_type", "aggregate_id", "event_type", "idempotency_key", "status", "attempts", "payload", "error", "metadata"].map((name) => ({ kind: "column", name: `public.outbox_events.${name}` })),
+        { kind: "function", name: "public.outbox_claim_batch", signature: "text[],text[],integer,integer,integer" },
+        { kind: "function", name: "public.outbox_mark_processed", signature: "uuid,text,jsonb" },
+        { kind: "function", name: "public.outbox_mark_failed", signature: "uuid,text,text,text,integer,integer,integer,integer" },
+        { kind: "function", name: "public.outbox_release_unprocessed", signature: "uuid[],text[],integer" },
+        { kind: "function", name: "pg_catalog.pg_input_is_valid", signature: "text,text" },
+    ],
+};
+/** @beta Supply an autocommit executor or a per-operation transaction that commits before resolve.
+ * Never pass a producer transaction or retain an operation transaction across handler I/O. */
+export function createPostgresOutboxStore(executor) {
+    const scalar = async (text, values) => {
+        const { rows } = await executor.query(text, values);
+        if (rows.length !== 1 || !Object.hasOwn(rows[0], "value"))
+            throw new Error("outbox_store_invalid_scalar");
+        return rows[0].value;
+    };
+    return {
+        async claimBatch(input) {
+            const { rows } = await executor.query(`select id::text, to_char(created_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') as created_at,
+to_char(available_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') as available_at,
+to_char(processed_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') as processed_at,
+aggregate_type, aggregate_id::text, event_type, idempotency_key, status, attempts, payload, error, metadata
+from public.outbox_claim_batch($1::text[], $2::text[], $3::integer, $4::integer, $5::integer)`, [input.eventTypes, input.knownEventTypes ?? [], input.batchSize, input.visibilitySeconds, input.maxAttempts]);
+            return rows;
+        },
+        async markProcessed(input) {
+            const value = await scalar("select public.outbox_mark_processed($1::uuid, $2::text, $3::jsonb) as value", [input.eventId, input.claimToken, JSON.stringify(input.metadata ?? {})]);
+            if (typeof value !== "boolean")
+                throw new Error("outbox_mark_processed_invalid_response");
+            return { applied: value };
+        },
+        async markFailed(input) {
+            const value = await scalar("select public.outbox_mark_failed($1::uuid,$2::text,$3::text,$4::text,$5::integer,$6::integer,$7::integer,$8::integer) as value", [input.eventId, input.claimToken, input.error, input.outcome, input.baseDelaySeconds, input.maxDelaySeconds, input.maxAttempts, input.snoozeSeconds]);
+            if (!["failed", "discarded", "snoozed", "missed"].includes(String(value)))
+                throw new Error("outbox_mark_failed_unexpected_status");
+            return { status: value };
+        },
+        async releaseUnprocessed(items, delaySeconds) {
+            if (!items.length)
+                return 0;
+            const value = await scalar("select public.outbox_release_unprocessed($1::uuid[],$2::text[],$3::integer) as value", [items.map((i) => i.eventId), items.map((i) => i.claimToken), delaySeconds]);
+            if (typeof value !== "number" || !Number.isInteger(value) || value < 0)
+                throw new Error("outbox_release_invalid_response");
+            return value;
+        },
+        async hasPendingEventType(eventType) {
+            const value = await scalar("select exists (select 1 from public.outbox_events where event_type=$1 and status in ('pending','failed','processing')) as value", [eventType]);
+            if (typeof value !== "boolean")
+                throw new Error("outbox_pending_invalid_response");
+            return value;
+        },
+    };
+}
+/** @beta Compacts terminal payload/error, retaining the event and its unique key. */
+export function createPostgresOutboxCompactor(executor) {
+    return { async compact(input) {
+            const { rows } = await executor.query(`with targets as (
+  select id from public.outbox_events
+  where metadata->>'retentionCompactedAt' is null and (
+    (status = 'processed' and coalesce(processed_at, created_at) < now() - make_interval(days => $1::integer))
+    or (status = 'discarded' and case when pg_catalog.pg_input_is_valid(metadata->>'discardedAt', 'timestamp with time zone')
+      then (metadata->>'discardedAt')::timestamptz else null end < now() - make_interval(days => $2::integer)))
+  order by created_at, id limit $3::integer for update skip locked
+), compacted as (
+  update public.outbox_events e set payload = '{}'::jsonb, error = null,
+    metadata = e.metadata || jsonb_build_object('retentionCompactedAt', now(), 'retentionCompactedBy', 'outbox_compact_terminal', 'retentionCompactedStatus', e.status)
+  from targets t where e.id = t.id returning e.id
+) select count(*)::integer as value from compacted`, [input.processedDays, input.discardedDays, input.limit]);
+            const value = rows[0]?.value;
+            if (rows.length !== 1 || typeof value !== "number" || !Number.isInteger(value) || value < 0)
+                throw new Error("outbox_compaction_invalid_response");
+            return value;
+        } };
+}

package/dist/registry.d.ts

@@ -0,0 +1,4 @@
+import type { OutboxHandler, OutboxHandlerRegistry } from "./contracts.js";
+export declare function claimAllowlist(registry: OutboxHandlerRegistry): string[];
+export declare function uniqueRegistry(handlers: readonly OutboxHandler[]): OutboxHandlerRegistry;
+export declare function composeHandlers(first: OutboxHandler, second: OutboxHandler): OutboxHandler;

package/dist/registry.js

@@ -0,0 +1,48 @@
+export function claimAllowlist(registry) {
+    return [...registry.keys()];
+}
+export function uniqueRegistry(handlers) {
+    const registry = new Map();
+    for (const handler of handlers) {
+        const existing = registry.get(handler.eventType);
+        registry.set(handler.eventType, existing ? composeHandlers(existing, handler) : handler);
+    }
+    return registry;
+}
+// Preserve top-level delivery observations, with first-component precedence.
+const DELIVERY_LIFECYCLE_METADATA_KEYS = ["resendId", "providerMessageId", "skipped", "dedupe"];
+function hoistDeliveryLifecycleKeys(detail) {
+    if (!detail)
+        return {};
+    const hoisted = {};
+    for (const key of DELIVERY_LIFECYCLE_METADATA_KEYS) {
+        if (detail[key] !== undefined)
+            hoisted[key] = detail[key];
+    }
+    return hoisted;
+}
+export function composeHandlers(first, second) {
+    return {
+        eventType: first.eventType,
+        timeoutMs: first.timeoutMs + second.timeoutMs,
+        async handle(row, signal) {
+            const firstOutcome = await first.handle(row, signal);
+            if (firstOutcome.kind !== "processed")
+                return firstOutcome;
+            const secondOutcome = await second.handle(row, signal);
+            if (secondOutcome.kind !== "processed")
+                return secondOutcome;
+            return {
+                kind: "processed",
+                detail: {
+                    // Hoist second first, then first, so the primary (email) handler wins on
+                    // the rare chance both emit a lifecycle key.
+                    ...hoistDeliveryLifecycleKeys(secondOutcome.detail),
+                    ...hoistDeliveryLifecycleKeys(firstOutcome.detail),
+                    first: firstOutcome.detail ?? {},
+                    second: secondOutcome.detail ?? {},
+                },
+            };
+        },
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,5 @@
+import type { OutboxStore, OutboxEventRow } from "./contracts.js";
+/** @beta Framework-free refusal suite. The caller supplies a real processing row. */
+export declare function assertOutboxStoreFences(store: OutboxStore, processing: OutboxEventRow): Promise<void>;
+/** @beta Synthetic envelope; never use for deployed queue observations. */
+export declare function syntheticOutboxRow(overrides?: Partial<OutboxEventRow>): OutboxEventRow;

package/dist/testing.js

@@ -0,0 +1,16 @@
+/** @beta Framework-free refusal suite. The caller supplies a real processing row. */
+export async function assertOutboxStoreFences(store, processing) {
+    const token = processing.metadata.claimToken;
+    if (processing.status !== "processing" || typeof token !== "string" || !token)
+        throw new Error("conformance_requires_processing_row");
+    if ((await store.markProcessed({ eventId: processing.id, claimToken: `stale-${token}` })).applied)
+        throw new Error("conformance_stale_processed_applied");
+    if ((await store.markFailed({ eventId: processing.id, claimToken: `stale-${token}`, error: "synthetic", outcome: "retry", baseDelaySeconds: 5, maxDelaySeconds: 10, maxAttempts: 3, snoozeSeconds: 60 })).status !== "missed")
+        throw new Error("conformance_stale_failure_applied");
+    if (await store.releaseUnprocessed([{ eventId: processing.id, claimToken: `stale-${token}` }], 0) !== 0)
+        throw new Error("conformance_stale_release_applied");
+}
+/** @beta Synthetic envelope; never use for deployed queue observations. */
+export function syntheticOutboxRow(overrides = {}) {
+    return { id: "00000000-0000-4000-8000-000000000001", created_at: "2026-01-01T00:00:00.000001Z", available_at: "2026-01-01T00:00:00.000001Z", processed_at: null, aggregate_type: "example", aggregate_id: "00000000-0000-4000-8000-000000000002", event_type: "example.created", idempotency_key: "synthetic-1", status: "processing", attempts: 1, payload: {}, error: null, metadata: { claimToken: "synthetic-token" }, ...overrides };
+}

package/dist/trace.d.ts

@@ -0,0 +1,8 @@
+import type { OutboxHandler, OutboxEventRow, OutboxHandlerOutcome, OutboxHandlerExecutionContext } from "./contracts.js";
+export declare class OutboxHandlerExecutionTrace implements OutboxHandlerExecutionContext {
+    private lastPhase;
+    setPhase(phase: string): void;
+    timeoutReason(): string;
+    qualifyTimeout(outcome: OutboxHandlerOutcome): OutboxHandlerOutcome;
+}
+export declare function executeHandler(handler: OutboxHandler, row: OutboxEventRow): Promise<OutboxHandlerOutcome>;

package/dist/trace.js

@@ -0,0 +1,44 @@
+const SAFE_MESSAGE_MAX_CHARS = 300;
+export class OutboxHandlerExecutionTrace {
+    lastPhase;
+    setPhase(phase) {
+        const sanitized = phase.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, 48);
+        if (sanitized)
+            this.lastPhase = sanitized;
+    }
+    timeoutReason() {
+        return this.lastPhase ? `outbox_handler_timeout:${this.lastPhase}` : "outbox_handler_timeout";
+    }
+    qualifyTimeout(outcome) {
+        return this.lastPhase && outcome.kind === "retry" && outcome.reason === "outbox_handler_timeout"
+            ? { ...outcome, reason: this.timeoutReason() }
+            : outcome;
+    }
+}
+export async function executeHandler(handler, row) {
+    const controller = new AbortController();
+    const execution = new OutboxHandlerExecutionTrace();
+    let abortTimer;
+    let backstopTimer;
+    try {
+        // Abort is the primary timeout mechanism (handlers must honor the
+        // signal); the race is only a backstop for non-abortable code, firing
+        // 500ms later so abort-aware handlers get to settle first.
+        const backstop = new Promise((resolve) => {
+            backstopTimer = setTimeout(() => resolve({ kind: "retry", reason: execution.timeoutReason() }), handler.timeoutMs + 500);
+        });
+        abortTimer = setTimeout(() => controller.abort(), handler.timeoutMs);
+        const outcome = await Promise.race([handler.handle(row, controller.signal, execution), backstop]);
+        return execution.qualifyTimeout(outcome);
+    }
+    catch (error) {
+        return { kind: "retry", reason: safeMessage(error) };
+    }
+    finally {
+        if (abortTimer !== undefined)
+            clearTimeout(abortTimer);
+        if (backstopTimer !== undefined)
+            clearTimeout(backstopTimer);
+    }
+}
+function safeMessage(error) { return (error instanceof Error ? error.message : String(error)).slice(0, SAFE_MESSAGE_MAX_CHARS); }

package/dist/typedEvents.d.ts

@@ -0,0 +1,4 @@
+import type { StandardSchemaV1 } from "@openlup/core/standard-schema";
+import type { OutboxHandler } from "./contracts.js";
+/** @beta Opt-in validation retries invalid payloads; it never changes untyped handlers. */
+export declare function withPayloadSchema<Payload extends Record<string, unknown>>(handler: OutboxHandler, schema: StandardSchemaV1<unknown, Payload>): OutboxHandler;

package/dist/typedEvents.js

@@ -0,0 +1,9 @@
+/** @beta Opt-in validation retries invalid payloads; it never changes untyped handlers. */
+export function withPayloadSchema(handler, schema) {
+    return { eventType: handler.eventType, timeoutMs: handler.timeoutMs, async handle(row, signal, execution) {
+            const result = await schema["~standard"].validate(row.payload);
+            if (result.issues)
+                return { kind: "retry", reason: "outbox_payload_invalid" };
+            return handler.handle({ ...row, payload: result.value }, signal, execution);
+        } };
+}

package/dist/worker.d.ts

@@ -0,0 +1,11 @@
+import type { Clock, OutboxDispatchConfig, OutboxDispatchRunResult, OutboxHandlerRegistry, OutboxQueueDiagnostics, OutboxStore, OutboxLogger, OutboxObservation } from "./contracts.js";
+export declare function runOutboxDispatchWorker(deps: {
+    store: OutboxStore;
+    registry: OutboxHandlerRegistry;
+    config: OutboxDispatchConfig;
+    knownEventTypes?: readonly string[];
+    diagnostics?: OutboxQueueDiagnostics;
+    clock?: Clock;
+    logger?: OutboxLogger;
+    observe?: (observation: OutboxObservation) => void;
+}): Promise<OutboxDispatchRunResult>;

package/dist/worker.js

@@ -0,0 +1,232 @@
+import { executeHandler } from "./trace.js";
+// Tail reserved per row: worst-case handler.timeoutMs + this mark-RPC margin.
+const MARK_MARGIN_MS = 2000;
+// R-8: a hung queueStats RPC must never starve finishJobRun past Vercel's
+// kill — best-effort stats race a hard deadline (try/catch only covers throws).
+const QUEUE_STATS_DEADLINE_MS = 3000;
+const DISCARDED_EVENT_IDS_CAP = 25;
+const SAFE_MESSAGE_MAX_CHARS = 300;
+export async function runOutboxDispatchWorker(deps) {
+    const { store, registry, config } = deps;
+    const suppliedLogger = deps.logger ?? console;
+    const log = (method, args) => {
+        try {
+            suppliedLogger[method](...args);
+        }
+        catch { /* Diagnostic failures cannot interrupt dispatch. */ }
+    };
+    const logger = { warn: (...args) => log("warn", args), error: (...args) => log("error", args) };
+    const observe = (event, count) => {
+        try {
+            deps.observe?.({ event, count });
+        }
+        catch { /* Diagnostics cannot rewrite an outcome. */ }
+    };
+    const clock = deps.clock ?? { now: () => Date.now() };
+    const startedAt = clock.now();
+    const counters = {
+        claimed: 0,
+        processed: 0,
+        retried: 0,
+        snoozed: 0,
+        discarded: 0,
+        released: 0,
+        duplicateInRun: 0,
+        leaseLost: 0,
+        batches: 0,
+    };
+    const byEventType = {};
+    const discardedEventIds = [];
+    const bump = (eventType, key) => {
+        const bucket = (byEventType[eventType] ??= {});
+        bucket[key] = (bucket[key] ?? 0) + 1;
+    };
+    const finish = async (input) => {
+        let queue;
+        if (!input.skipped && deps.diagnostics) {
+            let deadlineTimer;
+            try {
+                queue = await Promise.race([
+                    deps.diagnostics.queueStats(),
+                    new Promise((resolve) => {
+                        deadlineTimer = setTimeout(() => resolve(undefined), QUEUE_STATS_DEADLINE_MS);
+                    }),
+                ]);
+                if (queue === undefined)
+                    logger.warn("[outbox-dispatch] queue_stats_failed", "deadline_exceeded");
+            }
+            catch (error) {
+                logger.warn("[outbox-dispatch] queue_stats_failed", safeMessage(error));
+            }
+            finally {
+                if (deadlineTimer !== undefined)
+                    clearTimeout(deadlineTimer);
+            }
+        }
+        observe("finished", counters.processed);
+        return {
+            ok: true,
+            checked: counters.claimed,
+            updated: counters.processed,
+            failures: counters.retried + counters.discarded,
+            skipped: input.skipped,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+            ...counters,
+            runMs: clock.now() - startedAt,
+            byEventType,
+            discardedEventIds,
+            ...(queue !== undefined ? { queue } : {}),
+        };
+    };
+    const applyMarkFailed = async (row, claimToken, outcome, reason, benign = false) => {
+        const { status } = await store.markFailed({
+            eventId: row.id,
+            claimToken,
+            error: reason,
+            outcome,
+            baseDelaySeconds: config.backoffBaseSeconds,
+            maxDelaySeconds: config.backoffCapSeconds,
+            maxAttempts: config.maxAttempts,
+            snoozeSeconds: config.snoozeSeconds,
+        });
+        if (status === "failed") {
+            counters.retried += 1;
+            bump(row.event_type, "retried");
+        }
+        else if (status === "discarded") {
+            counters.discarded += 1;
+            bump(row.event_type, "discarded");
+            if (discardedEventIds.length < DISCARDED_EVENT_IDS_CAP)
+                discardedEventIds.push(row.id);
+            // Benign discard = expected terminal drop (deleted aggregate): same tag, logged at warn not error so it does not read as a failure.
+            const payload = { eventId: row.id, eventType: row.event_type, aggregateId: row.aggregate_id, attempts: row.attempts, reason, ...(benign ? { benign: true } : {}) };
+            (benign ? logger.warn : logger.error)("[outbox-dispatch] event_discarded", JSON.stringify(payload));
+        }
+        else if (status === "missed") {
+            counters.leaseLost += 1;
+            bump(row.event_type, "leaseLost");
+            logger.warn("[outbox-dispatch] outbox_lease_lost", row.id);
+        }
+        else {
+            counters.snoozed += 1;
+            bump(row.event_type, "snoozed");
+        }
+        return status;
+    };
+    const allowlist = [...registry.keys()];
+    if (allowlist.length === 0) {
+        return finish({ skipped: true, reason: "outbox_registry_empty" });
+    }
+    const seen = new Set();
+    let circuitBroken = false;
+    drain: while (clock.now() - startedAt < config.softBudgetMs) {
+        const claimed = await store.claimBatch({
+            eventTypes: allowlist,
+            knownEventTypes: deps.knownEventTypes,
+            batchSize: config.batchSize,
+            visibilitySeconds: config.visibilitySeconds,
+            maxAttempts: config.maxAttempts,
+        });
+        if (claimed.length === 0)
+            break;
+        counters.batches += 1;
+        counters.claimed += claimed.length;
+        observe("claimed", claimed.length);
+        // RETURNING order is unspecified — re-establish (created_at, id) order.
+        const batch = [...claimed].sort(compareByCreatedAtThenId);
+        const unstarted = [];
+        for (let index = 0; index < batch.length; index += 1) {
+            const row = batch[index];
+            const claimToken = row.metadata?.claimToken;
+            if (typeof claimToken !== "string" || claimToken.length === 0) {
+                counters.leaseLost += 1;
+                bump(row.event_type, "leaseLost");
+                logger.error("[outbox-dispatch] missing_claim_token", row.id);
+                continue;
+            }
+            if (seen.has(row.id)) {
+                // An in-process aborted orphan may still race — never re-execute in-run.
+                counters.released += await store.releaseUnprocessed([{ eventId: row.id, claimToken }], config.backoffBaseSeconds);
+                counters.duplicateInRun += 1;
+                bump(row.event_type, "duplicateInRun");
+                continue;
+            }
+            seen.add(row.id);
+            const handler = registry.get(row.event_type);
+            if (!handler) {
+                await applyMarkFailed(row, claimToken, "retry", "outbox_handler_missing");
+                continue;
+            }
+            const elapsed = clock.now() - startedAt;
+            if (elapsed + handler.timeoutMs + MARK_MARGIN_MS > config.softBudgetMs) {
+                unstarted.push({ eventId: row.id, claimToken });
+                continue;
+            }
+            const outcome = await executeHandler(handler, row);
+            if (outcome.kind === "processed") {
+                const { applied } = await store.markProcessed({
+                    eventId: row.id,
+                    claimToken,
+                    metadata: outcome.detail,
+                });
+                if (applied) {
+                    counters.processed += 1;
+                    bump(row.event_type, "processed");
+                }
+                else {
+                    counters.leaseLost += 1;
+                    bump(row.event_type, "leaseLost");
+                    logger.warn("[outbox-dispatch] outbox_lease_lost", row.id);
+                }
+                continue;
+            }
+            if (outcome.kind === "snooze") {
+                const snoozeCount = Number(row.metadata?.snoozeCount) || 0;
+                if (snoozeCount >= config.maxSnoozes) {
+                    // Liveness bound: a misclassified permanent error must not snooze
+                    // forever — consume an attempt instead. No circuit-break.
+                    await applyMarkFailed(row, claimToken, "retry", `snooze_budget_exhausted:${outcome.reason}`);
+                    continue;
+                }
+                await applyMarkFailed(row, claimToken, "snooze", outcome.reason);
+                // Circuit-break: the provider is down — refund everything still
+                // claimed (tail-gated rows included) and stop hammering it.
+                const remainder = [...unstarted];
+                for (let rest = index + 1; rest < batch.length; rest += 1) {
+                    const restToken = batch[rest].metadata?.claimToken;
+                    if (typeof restToken === "string" && restToken.length > 0) {
+                        remainder.push({ eventId: batch[rest].id, claimToken: restToken });
+                    }
+                }
+                if (remainder.length > 0) {
+                    counters.released += await store.releaseUnprocessed(remainder, config.snoozeSeconds);
+                }
+                circuitBroken = true;
+                break drain;
+            }
+            await applyMarkFailed(row, claimToken, outcome.kind, outcome.reason, outcome.kind === "discard" && outcome.benign === true);
+        }
+        if (unstarted.length > 0) {
+            counters.released += await store.releaseUnprocessed(unstarted, 0);
+            break;
+        }
+        if (claimed.length < config.batchSize)
+            break;
+    }
+    return finish({
+        skipped: false,
+        ...(circuitBroken ? { reason: "provider_outage" } : {}),
+    });
+}
+function compareByCreatedAtThenId(a, b) {
+    if (a.created_at < b.created_at)
+        return -1;
+    if (a.created_at > b.created_at)
+        return 1;
+    if (a.id < b.id)
+        return -1;
+    if (a.id > b.id)
+        return 1;
+    return 0;
+}
+function safeMessage(error) { return (error instanceof Error ? error.message : String(error)).slice(0, SAFE_MESSAGE_MAX_CHARS); }