@openlup/outbox 0.0.0 → 0.13.1

package/src/factory.ts

@@ -0,0 +1,107 @@
+import metadata from "../package.json" with { type: "json" };
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+import type { JobLeasePort, PlatformJobInvocation, PlatformJobFinishSummary } from "@openlup/core/platform-runtime";
+import type { OutboxHandlerDescriptor } from "@openlup/core/outbox";
+import type { OutboxDispatchConfig, OutboxDispatchRunResult, OutboxHandlerRegistry, OutboxLogger, OutboxStore, OutboxQueueDiagnostics, Clock } from "./contracts.js";
+import { validateScheduledConfig } from "./config.js";
+import { runOutboxDispatchWorker } from "./worker.js";
+/** @beta */
+export interface CompactionPort { compact(input: { processedDays: number; discardedDays: number; limit: number }): Promise<number> }
+/** @beta The builder owns partially acquired resources until this scope is returned. */
+export interface HandlerScope { handlers: OutboxHandlerRegistry; close?(): Promise<void> | void }
+/** @beta */
+export interface OutboxFactoryPorts {
+  store: OutboxStore; lease: JobLeasePort;
+  descriptors: readonly OutboxHandlerDescriptor[];
+  buildHandlers(run: { runId: string; invocation: PlatformJobInvocation }): Promise<OutboxHandlerRegistry | HandlerScope> | OutboxHandlerRegistry | HandlerScope;
+  beforeDispatch?(run: { runId: string; invocation: PlatformJobInvocation }): Promise<Record<string, unknown>>;
+  diagnostics?: OutboxQueueDiagnostics; clock?: Clock; logger?: OutboxLogger;
+  compactor?: CompactionPort;
+}
+/** @beta Schema requirements describe the selected adapters, not a guessed default. */
+export interface OutboxFactoryOptions {
+  config: OutboxDispatchConfig; knownEventTypes: readonly string[];
+  hostLimitSeconds: number; leaseSeconds: number; cadenceSeconds: number;
+  requiredSchema: RequiredSchema;
+  prune?: { enabled: boolean; cadenceSeconds: number; processedDays?: number; discardedDays?: number; limit?: number };
+}
+/** @beta Finish/cleanup evidence is distinct from the accepted worker result. */
+export interface OutboxScheduleResult {
+  outcome: "success" | "failed" | "skipped" | "disabled";
+  detail: OutboxDispatchRunResult | { ok: boolean; checked: number; updated: number; failures: number; skipped: boolean; reason?: string };
+  finishApplied?: boolean;
+}
+export function createOutbox(ports: OutboxFactoryPorts & { compactor: CompactionPort }, options: OutboxFactoryOptions): Contribution;
+export function createOutbox(ports: OutboxFactoryPorts, options: OutboxFactoryOptions & { prune?: { enabled: false; cadenceSeconds: number } }): Contribution;
+/** @beta Lease-bound dispatch and terminal compaction, with no host entrypoint. */
+export function createOutbox(ports: OutboxFactoryPorts, options: OutboxFactoryOptions): Contribution {
+  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: string, value: number, maximum: number): void => {
+    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: "warn" | "error", args: unknown[]): void => { try { suppliedLogger[method](...args); } catch { /* Diagnostics cannot skip finish or cleanup. */ } };
+  const logger = { warn: (...args: unknown[]) => log("warn", args), error: (...args: unknown[]) => 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: string): PlatformJobFinishSummary & { ok: false } => ({ ok: false, checked: 0, updated: 0, failures: 1, skipped: false, reason });
+  const run = async (jobName: string, invocation: PlatformJobInvocation, dispatch: boolean): Promise<OutboxScheduleResult> => {
+    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: HandlerScope | undefined; let hookMetadata: Record<string, unknown> = {};
+    let detail: OutboxScheduleResult["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: PlatformJobInvocation) => run("outbox-dispatch", invocation, true) },
+    ...(pruning ? [{ id: "outbox-prune", cadenceSeconds: options.prune!.cadenceSeconds, run: (invocation: PlatformJobInvocation) => 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: unknown): string { return (error instanceof Error ? error.message : String(error)).slice(0,180); }

package/src/index.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/src/postgres.ts

@@ -0,0 +1,76 @@
+import type { SqlExecutor, RequiredSchema } from "@openlup/core/readiness";
+import type { OutboxStore, OutboxEventRow, OutboxMarkFailedStatus } from "./contracts.js";
+import type { CompactionPort } from "./factory.js";
+/** @beta These identities describe the shipped default adapter only. */
+export const POSTGRES_OUTBOX_SCHEMA: RequiredSchema = {
+  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" as const, 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: SqlExecutor): OutboxStore {
+  const scalar = async (text: string, values: readonly unknown[]): Promise<unknown> => {
+    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 as unknown as OutboxEventRow[];
+    },
+    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 as OutboxMarkFailedStatus };
+    },
+    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: SqlExecutor): CompactionPort {
+  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/src/registry.ts

@@ -0,0 +1,49 @@
+import type { OutboxHandler, OutboxHandlerRegistry } from "./contracts.js";
+export function claimAllowlist(registry: OutboxHandlerRegistry): string[] {
+  return [...registry.keys()];
+}
+
+export function uniqueRegistry(handlers: readonly OutboxHandler[]): OutboxHandlerRegistry {
+  const registry = new Map<string, OutboxHandler>();
+  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"] as const;
+
+function hoistDeliveryLifecycleKeys(detail: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!detail) return {};
+  const hoisted: Record<string, unknown> = {};
+  for (const key of DELIVERY_LIFECYCLE_METADATA_KEYS) {
+    if (detail[key] !== undefined) hoisted[key] = detail[key];
+  }
+  return hoisted;
+}
+
+export function composeHandlers(first: OutboxHandler, second: OutboxHandler): OutboxHandler {
+  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/src/testing.ts

@@ -0,0 +1,13 @@
+import type { OutboxStore, OutboxEventRow } from "./contracts.js";
+/** @beta Framework-free refusal suite. The caller supplies a real processing row. */
+export async function assertOutboxStoreFences(store: OutboxStore, processing: OutboxEventRow): Promise<void> {
+  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: Partial<OutboxEventRow> = {}): OutboxEventRow {
+  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/src/trace.ts

@@ -0,0 +1,52 @@
+import type { OutboxHandler, OutboxEventRow, OutboxHandlerOutcome, OutboxHandlerExecutionContext } from "./contracts.js";
+const SAFE_MESSAGE_MAX_CHARS = 300;
+export class OutboxHandlerExecutionTrace implements OutboxHandlerExecutionContext {
+  private lastPhase: string | undefined;
+
+  setPhase(phase: string): void {
+    const sanitized = phase.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, 48);
+    if (sanitized) this.lastPhase = sanitized;
+  }
+
+  timeoutReason(): string {
+    return this.lastPhase ? `outbox_handler_timeout:${this.lastPhase}` : "outbox_handler_timeout";
+  }
+
+  qualifyTimeout(outcome: OutboxHandlerOutcome): OutboxHandlerOutcome {
+    return this.lastPhase && outcome.kind === "retry" && outcome.reason === "outbox_handler_timeout"
+      ? { ...outcome, reason: this.timeoutReason() }
+      : outcome;
+  }
+}
+
+export async function executeHandler(
+  handler: OutboxHandler,
+  row: OutboxEventRow,
+): Promise<OutboxHandlerOutcome> {
+  const controller = new AbortController();
+  const execution = new OutboxHandlerExecutionTrace();
+  let abortTimer: ReturnType<typeof setTimeout> | undefined;
+  let backstopTimer: ReturnType<typeof setTimeout> | undefined;
+  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<OutboxHandlerOutcome>((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: unknown): string { return (error instanceof Error ? error.message : String(error)).slice(0, SAFE_MESSAGE_MAX_CHARS); }

package/src/typedEvents.ts

@@ -0,0 +1,10 @@
+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 function withPayloadSchema<Payload extends Record<string, unknown>>(handler: OutboxHandler, schema: StandardSchemaV1<unknown, Payload>): OutboxHandler {
+  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/src/worker.ts

@@ -0,0 +1,281 @@
+import { executeHandler } from "./trace.js";
+import type {
+  Clock,
+  OutboxDispatchConfig,
+  OutboxDispatchRunResult,
+  OutboxEventRow,
+  OutboxHandlerRegistry,
+  OutboxQueueDiagnostics,
+  OutboxStore,
+  OutboxLogger,
+  OutboxObservation,
+} from "./contracts.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;
+
+interface ClaimedItem {
+  eventId: string;
+  claimToken: string;
+}
+
+type PerTypeCounter =
+  | "processed"
+  | "retried"
+  | "snoozed"
+  | "discarded"
+  | "leaseLost"
+  | "duplicateInRun";
+
+export async function runOutboxDispatchWorker(deps: {
+  store: OutboxStore;
+  registry: OutboxHandlerRegistry;
+  config: OutboxDispatchConfig;
+  knownEventTypes?: readonly string[];
+  diagnostics?: OutboxQueueDiagnostics;
+  clock?: Clock;
+  logger?: OutboxLogger;
+  observe?: (observation: OutboxObservation) => void;
+}): Promise<OutboxDispatchRunResult> {
+  const { store, registry, config } = deps;
+  const suppliedLogger = deps.logger ?? console;
+  const log = (method: "warn" | "error", args: unknown[]): void => {
+    try { suppliedLogger[method](...args); } catch { /* Diagnostic failures cannot interrupt dispatch. */ }
+  };
+  const logger = { warn: (...args: unknown[]) => log("warn", args), error: (...args: unknown[]) => log("error", args) };
+  const observe = (event: "claimed" | "finished", count: number): void => {
+    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: Record<string, Record<string, number>> = {};
+  const discardedEventIds: string[] = [];
+
+  const bump = (eventType: string, key: PerTypeCounter): void => {
+    const bucket = (byEventType[eventType] ??= {});
+    bucket[key] = (bucket[key] ?? 0) + 1;
+  };
+
+  const finish = async (input: {
+    skipped: boolean;
+    reason?: string;
+  }): Promise<OutboxDispatchRunResult> => {
+    let queue: Record<string, unknown> | undefined;
+    if (!input.skipped && deps.diagnostics) {
+      let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        queue = await Promise.race([
+          deps.diagnostics.queueStats(),
+          new Promise<undefined>((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: OutboxEventRow,
+    claimToken: string,
+    outcome: "retry" | "discard" | "snooze",
+    reason: string,
+    benign = false,
+  ): Promise<"failed" | "discarded" | "snoozed" | "missed"> => {
+    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<string>();
+  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: ClaimedItem[] = [];
+
+    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: OutboxEventRow, b: OutboxEventRow): number {
+  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: unknown): string { return (error instanceof Error ? error.message : String(error)).slice(0, SAFE_MESSAGE_MAX_CHARS); }