@openlup/outbox 0.0.0 → 0.14.0

package/sql/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "version": "outbox-1",
+  "migrations": [
+    {
+      "file": "0001_outbox.sql",
+      "source": "db/platform/migrations/20260807190000_comms_outbox_rail.sql",
+      "sha256": "dfb3e9808714846738222bb74a1bfdb38ceafdde2ca8a0c71ab835739fb333bd"
+    }
+  ]
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+import type { OutboxDispatchConfig } from "./contracts.js";
+const CONFIG_BOUNDS = {
+  batchSize: { env: "COMMERCE_OUTBOX_DISPATCH_BATCH_SIZE", def: 25, min: 1, max: 100 },
+  maxAttempts: { env: "COMMERCE_OUTBOX_DISPATCH_MAX_ATTEMPTS", def: 8, min: 1, max: 20 },
+  visibilitySeconds: {
+    env: "COMMERCE_OUTBOX_DISPATCH_VISIBILITY_SECONDS",
+    def: 300,
+    min: 300,
+    max: 3600,
+  },
+  backoffBaseSeconds: { env: "COMMERCE_OUTBOX_DISPATCH_BACKOFF_BASE_SECONDS", def: 60, min: 5, max: 3600 },
+  backoffCapSeconds: { env: "COMMERCE_OUTBOX_DISPATCH_BACKOFF_CAP_SECONDS", def: 3600, min: 5, max: 86_400 },
+  snoozeSeconds: { env: "COMMERCE_OUTBOX_DISPATCH_SNOOZE_SECONDS", def: 300, min: 60, max: 3600 },
+  maxSnoozes: { env: "COMMERCE_OUTBOX_DISPATCH_MAX_SNOOZES", def: 48, min: 1, max: 1000 },
+  // Max keeps a >= 15s tail under the cron's hard kill: drain stop + in-flight
+  // handler + marks + queue stats + finishJobRun must all fit after the budget.
+  softBudgetMs: {
+    env: "COMMERCE_OUTBOX_DISPATCH_SOFT_BUDGET_MS",
+    def: 40_000,
+    min: 5000,
+    max: 60 * 1000 - 15_000,
+  },
+} as const;
+
+function readBoundedInt(
+  env: Record<string, string | undefined>,
+  bound: { env: string; def: number; min: number; max: number },
+): number {
+  const raw = env[bound.env];
+  if (raw === undefined || raw.trim() === "") return bound.def;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) {
+    console.warn(`[outbox-dispatch] invalid ${bound.env}=${raw}; using default ${bound.def}`);
+    return bound.def;
+  }
+  const clamped = Math.min(Math.max(parsed, bound.min), bound.max);
+  if (clamped !== parsed) {
+    console.warn(`[outbox-dispatch] ${bound.env}=${parsed} clamped to ${clamped}`);
+  }
+  return clamped;
+}
+
+export function readOutboxDispatchConfig(
+  env: Record<string, string | undefined>,
+  prefix = "COMMERCE_OUTBOX_DISPATCH_",
+): OutboxDispatchConfig {
+  const bounds = Object.fromEntries(Object.entries(CONFIG_BOUNDS).map(([key, bound]) => [key, { ...bound, env: prefix + bound.env.slice("COMMERCE_OUTBOX_DISPATCH_".length) }])) as typeof CONFIG_BOUNDS;
+  const config: OutboxDispatchConfig = {
+    batchSize: readBoundedInt(env, bounds.batchSize),
+    maxAttempts: readBoundedInt(env, bounds.maxAttempts),
+    visibilitySeconds: readBoundedInt(env, bounds.visibilitySeconds),
+    backoffBaseSeconds: readBoundedInt(env, bounds.backoffBaseSeconds),
+    backoffCapSeconds: readBoundedInt(env, bounds.backoffCapSeconds),
+    snoozeSeconds: readBoundedInt(env, bounds.snoozeSeconds),
+    maxSnoozes: readBoundedInt(env, bounds.maxSnoozes),
+    softBudgetMs: readBoundedInt(env, bounds.softBudgetMs),
+  };
+  if (config.backoffCapSeconds < config.backoffBaseSeconds) {
+    console.warn(
+      `[outbox-dispatch] backoff cap ${config.backoffCapSeconds}s below base ${config.backoffBaseSeconds}s; raising cap to base`,
+    );
+    config.backoffCapSeconds = config.backoffBaseSeconds;
+  }
+  return config;
+}
+
+/** @beta Scheduled configuration is stricter than the bare immediate worker. */
+export function validateScheduledConfig(config: OutboxDispatchConfig, hostLimitSeconds: number, timeouts: readonly number[]): void {
+  const fail = (key: string, fix: string): never => { throw new Error(`@openlup/outbox: ${key}: ${fix}`); };
+  if (!Number.isFinite(hostLimitSeconds) || hostLimitSeconds < 20 || hostLimitSeconds > 720) fail("hostLimitSeconds", "use 20–720 seconds");
+  for (const [key, bound] of Object.entries(CONFIG_BOUNDS)) {
+    const value = config[key as keyof OutboxDispatchConfig];
+    const min = key === "visibilitySeconds" ? Math.min(5 * hostLimitSeconds, 3600) : bound.min;
+    const max = key === "softBudgetMs" ? hostLimitSeconds * 1000 - 15000 : bound.max;
+    if (!Number.isInteger(value) || value < min || value > max) fail(key, `use an integer in ${min}–${max}`);
+  }
+  if (config.backoffCapSeconds < config.backoffBaseSeconds) fail("backoffCapSeconds", "keep cap at least the base delay");
+  for (const timeout of timeouts) if (!Number.isFinite(timeout) || timeout <= 0 || timeout + 2000 > config.softBudgetMs) fail("handler.timeoutMs", "fit the effective timeout plus 2000 ms mark margin in the budget");
+}

package/src/contracts.ts

@@ -0,0 +1,86 @@
+import type { OutboxHandler as KernelHandler, OutboxEventRow } from "@openlup/core/outbox";
+export type { OutboxEventRow, OutboxHandlerOutcome, OutboxHandlerExecutionContext, OutboxHandlerDescriptor } from "@openlup/core/outbox";
+/** @beta The worker creates the host's standard AbortController. */
+export type OutboxHandler = KernelHandler<AbortSignal>;
+export type OutboxHandlerRegistry = ReadonlyMap<string, OutboxHandler>;
+
+export type OutboxMarkFailedStatus = "failed" | "discarded" | "snoozed" | "missed";
+
+export interface OutboxStore {
+  /** Read-only preflight used to admit a terminal handler when active providers are unavailable. */
+  hasPendingEventType?(eventType: string): Promise<boolean>;
+  claimBatch(input: {
+    eventTypes: readonly string[];
+    knownEventTypes?: readonly string[];
+    batchSize: number;
+    visibilitySeconds: number;
+    maxAttempts: number;
+  }): Promise<OutboxEventRow[]>;
+  markProcessed(input: {
+    eventId: string;
+    claimToken: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<{ applied: boolean }>;
+  markFailed(input: {
+    eventId: string;
+    claimToken: string;
+    error: string;
+    outcome: "retry" | "discard" | "snooze";
+    baseDelaySeconds: number;
+    maxDelaySeconds: number;
+    maxAttempts: number;
+    snoozeSeconds: number;
+  }): Promise<{ status: OutboxMarkFailedStatus }>;
+  releaseUnprocessed(
+    items: ReadonlyArray<{ eventId: string; claimToken: string }>,
+    delaySeconds: number,
+  ): Promise<number>;
+}
+
+/** Managed-only best-effort queue observation, separate from core claim/ack policy. */
+export interface OutboxQueueDiagnostics {
+  queueStats(): Promise<Record<string, unknown>>;
+}
+
+export interface Clock {
+  now(): number;
+}
+
+export interface OutboxDispatchRunResult {
+  ok: boolean;
+  checked: number;
+  updated: number;
+  failures: number;
+  skipped: boolean;
+  reason?: string;
+  claimed: number;
+  processed: number;
+  retried: number;
+  snoozed: number;
+  discarded: number;
+  released: number;
+  duplicateInRun: number;
+  leaseLost: number;
+  batches: number;
+  runMs: number;
+  byEventType: Record<string, Record<string, number>>;
+  discardedEventIds: string[];
+  queue?: Record<string, unknown>;
+}
+
+export interface OutboxDispatchConfig {
+  batchSize: number;
+  maxAttempts: number;
+  visibilitySeconds: number;
+  backoffBaseSeconds: number;
+  backoffCapSeconds: number;
+  snoozeSeconds: number;
+  maxSnoozes: number;
+  softBudgetMs: number;
+}
+
+
+/** @beta Logging defaults retain the dispatch console transcript. */
+export interface OutboxLogger { warn(...args: unknown[]): void; error(...args: unknown[]): void }
+/** @beta Synchronous bounded observations; no payloads or credentials. */
+export interface OutboxObservation { event: "claimed" | "finished"; count: number }

package/src/enqueue.ts

@@ -0,0 +1,15 @@
+/** @beta Caller executes this inside the same transaction as its domain write. */
+export interface EnqueueEvent {
+  aggregateType: string; aggregateId: string; eventType: string; idempotencyKey: string;
+  payload: Record<string, unknown>; metadata?: Record<string, unknown>;
+  availableAt?: string;
+}
+/** @beta Duplicate enqueue keeps the durable event identity; no independent commit. */
+export function buildOutboxEnqueue(event: EnqueueEvent): { text: string; values: readonly unknown[] } {
+  return {
+    text: `insert into public.outbox_events (aggregate_type, aggregate_id, event_type, idempotency_key, payload, metadata, available_at)
+values ($1, $2::uuid, $3, $4, $5::jsonb, $6::jsonb, coalesce($7::timestamptz, now()))
+on conflict (event_type, idempotency_key) do nothing returning id::text`,
+    values: [event.aggregateType, event.aggregateId, event.eventType, event.idempotencyKey, JSON.stringify(event.payload), JSON.stringify(event.metadata ?? {}), event.availableAt ?? null],
+  };
+}

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);
+  } };
+}