@openlup/platform 0.25.0 → 0.27.0

package/src/commerce/server/outboxCheckoutRecoveryEmailHandler.ts

@@ -0,0 +1,188 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+// Checkout-recovery email handler (W3, transactional). Consumes the
+// commerce.checkout_recovery outbox events produced by the W2 enqueue cron and
+// sends a "finish your payment" email with a signed deep-link to complete payment
+// for the SAME unpaid order. Transactional: NO marketing-consent gate. Promotes
+// the W2 producer from dormant to runtime-gated.
+//
+// Three producers feed this one handler: the W2 cron, the operator payment-link
+// command (`operatorIssued: true`), and the buyer's own escape hatch off a payment
+// step that will not finish (`buyerRequested: true`). They differ in one place
+// only — which eligibility question is asked below — and share the template, the
+// dedupe ledger and the deep-link build.
+//
+// handle() flow: parse the minimal payload -> resolve recipient by order ->
+// dedupe on the email_sends ledger -> build the localized deep-link from the raw
+// recovery token -> send -> map the provider outcome to a worker outcome.
+
+import { z } from "zod";
+import { COMMERCE_CHECKOUT_RECOVERY_EVENT_TYPE } from "../outboxEventSchemas.js";
+import {
+  OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG,
+  type OrderPaymentLifecyclePort,
+  type TransactionalEmailPort,
+  type OrderRecipientPort,
+} from "../outboxOrderDraftEmailPorts.js";
+import {
+  PAYMENT_SESSION_ACTIVE,
+  shouldSkipCheckoutRecovery,
+  shouldSkipOperatorCheckoutRecovery,
+} from "../orderEmailEligibility.js";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerOutcome,
+} from "../outboxDispatchContracts.js";
+
+const HANDLER_TIMEOUT_MS = 10_000;
+
+export const outboxCheckoutRecoveryEmailDescriptor = Object.freeze({
+  eventType: COMMERCE_CHECKOUT_RECOVERY_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+
+// Deferrals allowed before a nudge blocked by a live payment session retires.
+// The dispatcher's default backoff is 60 s doubling to a 3600 s cap, so five
+// attempts span ~31 min — past the 15 min activity window that produced the
+// skip, and well inside the 120 min subscription sweep that would cancel the
+// order anyway. It also sits under the default `maxAttempts` of 8: exhausting
+// retries routes a row to the terminal DLQ as `discarded`, which records a
+// dispatch failure for a reminder that was merely untimely. Retiring as
+// `processed` keeps it an honest deliberate skip. A deployment that configures
+// `maxAttempts` below this ceiling has chosen fewer retries globally, and gets
+// that choice here too.
+const PAYMENT_SESSION_RETRY_CEILING = 5;
+
+// Frozen minimal parse: orderId (recipient + linkage) and recoveryToken (the
+// deep-link) are load-bearing; mode/reminderHours degrade to safe defaults so a
+// producer tweak never retro-DLQs an in-flight reminder.
+//
+// `operatorIssued` says a human minted this link on the operator surface rather
+// than the cron finding an abandoned order. `buyerRequested` says the BUYER asked
+// for it, from inside the payment step they are stuck on. Both optional, and
+// absent means the cron: every row already in flight when either shipped keeps
+// its exact behaviour.
+const payloadSubsetSchema = z
+  .object({
+    orderId: z.guid(),
+    recoveryToken: z.string().min(1),
+    mode: z.string().optional(),
+    reminderHours: z.number().int().positive().optional(),
+    operatorIssued: z.boolean().optional(),
+    buyerRequested: z.boolean().optional(),
+  })
+  .passthrough();
+
+export function createOutboxCheckoutRecoveryEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+  lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler {
+  return {
+    ...outboxCheckoutRecoveryEmailDescriptor,
+    async handle(row: OutboxEventRow, signal: AbortSignal): Promise<OutboxHandlerOutcome> {
+      const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+      if (parsed.ok === false) {
+        return parsed.outcome;
+      }
+
+      const lifecycle = await deps.lifecyclePort.read(parsed.data.orderId, signal);
+      // Three producers, three questions. The cron asks "is this order still
+      // sitting unpaid", and going quiet once it is not is right. An
+      // operator-issued link is a decision a human already made about an order
+      // that has usually left `pending_payment` — expired is the ordinary case —
+      // and the redeem rail recreates it when the customer opens the link.
+      // Judging that by the cron's rule would skip it as
+      // `order_not_pending_payment` and no-send in silence.
+      const skipReason = parsed.data.buyerRequested
+        ? skipReasonForBuyerRequestedRecovery(lifecycle)
+        : parsed.data.operatorIssued
+          ? shouldSkipOperatorCheckoutRecovery(lifecycle)
+          : shouldSkipCheckoutRecovery(lifecycle);
+      if (skipReason === PAYMENT_SESSION_ACTIVE) {
+        // A live payment session is temporary. The producer key is unique per
+        // event, so settling it as processed would consume the only reminder
+        // without sending. Defer until the session settles, subject to the
+        // retry ceiling below.
+        //
+        // Read `attempts` defensively: `undefined < n` is false, which would
+        // retire the nudge on its FIRST deferral — the precise opposite of the
+        // intent here, and silent.
+        const attempts = Number.isFinite(row.attempts) ? row.attempts : 0;
+        if (attempts < PAYMENT_SESSION_RETRY_CEILING) {
+          return { kind: "retry", reason: PAYMENT_SESSION_ACTIVE };
+        }
+        // Past the ceiling, retire deliberately. Letting retries run out routes
+        // the row to the terminal DLQ as `discarded`, which reads as a dispatch
+        // failure for a reminder that was only untimely.
+        return { kind: "processed", detail: { skipped: "payment_session_exhausted" } };
+      }
+      if (skipReason) {
+        return { kind: "processed", detail: { skipped: skipReason } };
+      }
+
+      const recipient = await deps.recipientPort.resolve(parsed.data.orderId, signal);
+      if (recipient === null) {
+        // No client on the order (or unreadable) — nothing to send, never retry.
+        return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+      }
+
+      const alreadySent = await deps.emailPort.findExistingSend(
+        OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG,
+        row.id,
+      );
+      if (alreadySent) {
+        return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+      }
+
+      const locale = deps.runtime.resolveLocale(recipient.country ?? null);
+
+      const outcome = await deps.emailPort.sendCheckoutRecovery({
+        to: recipient.email,
+        firstName: recipient.firstName,
+        contextName: recipient.contextName ?? null,
+        orderId: parsed.data.orderId,
+        recoveryToken: parsed.data.recoveryToken,
+        mode: parsed.data.mode ?? "one_time",
+        reminderHours: parsed.data.reminderHours ?? 1,
+        outboxEventId: row.id,
+        // Marks the deep-link as the one the buyer mailed themselves off a stuck
+        // payment step, so the landing page can tell that arrival apart from a
+        // cron nudge. Absent for every other producer, which keeps their URLs
+        // byte-identical to what they were.
+        linkSource: parsed.data.buyerRequested ? "buyer_hatch" : undefined,
+        locale,
+        signal,
+      });
+
+      return deps.runtime.mapSendOutcome(outcome);
+    },
+  };
+}
+
+/**
+ * Eligibility for a link the BUYER asked for, from inside the payment step.
+ *
+ * Everything the operator rule suppresses is suppressed here too — the order is
+ * gone, or the money is already in — because those make the email actively wrong
+ * rather than merely late. Exactly ONE rule is lifted:
+ * `payment_session_active`.
+ *
+ * That rule is a politeness rule: do not remind someone to pay while they are
+ * paying. For this producer it is not merely unhelpful, it is inverted. A buyer
+ * who taps this control is BY CONSTRUCTION inside a live payment session — that
+ * session is the thing that will not finish, and asking for a way out of it is
+ * the whole request. Deferring on it would defer every buyer row through the
+ * retry ceiling and then retire it as `payment_session_exhausted`, so the hatch
+ * would send nothing, ever, and nothing would report a failure.
+ *
+ * Written here rather than as a fourth predicate in `orderEmailEligibility`: it
+ * is not a different question from the operator's, it is the operator's question
+ * with its one transient answer already decided by who is asking.
+ */
+function skipReasonForBuyerRequestedRecovery(
+  lifecycle: Parameters<typeof shouldSkipOperatorCheckoutRecovery>[0],
+): string | null {
+  const reason = shouldSkipOperatorCheckoutRecovery(lifecycle);
+  return reason === PAYMENT_SESSION_ACTIVE ? null : reason;
+}

package/src/commerce/server/outboxDispatchRegistry.ts

@@ -0,0 +1,269 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+// Registry = the single source of truth for which event types this wave
+// claims. The claim allowlist is derived from its keys, so the PSP-blocked
+// event types stay structurally unclaimable until their handlers register.
+import type { OutboxHandlerDescriptor } from "@openlup/core/outbox";
+import { composeOutboxHandlerDescriptors, assertOutboxRegistryDescriptors } from "./outboxDispatchRegistryComposition.js";
+import type { OutboxHandler, OutboxHandlerRegistry } from "../outboxDispatchContracts.js";
+import type {
+  OrderPaymentLifecyclePort,
+  OrderPaidLinesPort,
+  OrderRecipientPort,
+  TransactionalEmailPort,
+} from "../outboxOrderDraftEmailPorts.js";
+import { createOutboxOrderDraftEmailHandler, outboxOrderDraftEmailDescriptor } from "./outboxOrderDraftEmailHandler.js";
+import { createOutboxCheckoutRecoveryEmailHandler, outboxCheckoutRecoveryEmailDescriptor } from "./outboxCheckoutRecoveryEmailHandler.js";
+import {
+  createOutboxOrderPaidEmailHandler, outboxOrderPaidEmailDescriptor,
+  type OrderPaidParcelNoteReader,
+} from "./outboxOrderPaidEmailHandler.js";
+import { createOutboxPaymentFailedEmailHandler, outboxPaymentFailedEmailDescriptor } from "./outboxPaymentFailedEmailHandler.js";
+import { createOutboxCheckoutExpiredEmailHandler, outboxCheckoutExpiredEmailDescriptor } from "./outboxCheckoutExpiredEmailHandler.js";
+import { createOutboxOrderRefundedEmailHandler, outboxOrderRefundedEmailDescriptor } from "./outboxOrderRefundedEmailHandler.js";
+import { createOutboxShipmentDispatchedEmailHandler, outboxShipmentDispatchedEmailDescriptor } from "./outboxShipmentDispatchedEmailHandler.js";
+import {
+  createOutboxShipmentDeliveredEmailHandler, outboxShipmentDeliveredEmailDescriptor,
+  type DeliveredEmailProviderKindReader,
+} from "./outboxShipmentDeliveredEmailHandler.js";
+import { createOutboxShipmentExceptionEmailHandler, outboxShipmentExceptionEmailDescriptor } from "./outboxShipmentExceptionEmailHandler.js";
+import {
+  createOutboxReturnApprovedEmailHandler, outboxReturnApprovedEmailDescriptor,
+  createOutboxReturnRejectedEmailHandler, outboxReturnRejectedEmailDescriptor,
+} from "./outboxReturnEmailHandlers.js";
+import type { OrderPaidFulfillmentPort } from "./outboxOrderPaidFulfillmentPorts.js";
+import {
+  createOutboxOrderPaidFulfillmentHandler, outboxOrderPaidFulfillmentDescriptor,
+  type OrderPaidRiskAssessmentPort,
+} from "./outboxOrderPaidFulfillmentHandler.js";
+import {
+  platformOwnsBuyerEmail,
+  type OrderBuyerCommsPolicy,
+} from "../salesChannelEnvelope.js";
+
+/**
+ * Reads the sales-source buyer-comms policy for one order. `null` is
+ * the answer for an order that names no channel — a storefront order, or one
+ * that predates the source axis.
+ *
+ * Read on every event so changes to `sales_channels.buyer_comms_owner` take
+ * effect on the next dispatch. A cached policy could keep sending after
+ * ownership has changed.
+ */
+export interface OrderBuyerCommsPolicyReader {
+  readOrderBuyerCommsPolicy(orderUuid: string): Promise<OrderBuyerCommsPolicy | null>;
+}
+
+export type TransactionalEmailRegistryDeps<Locale extends string = string> = {
+  runtime: CommerceEmailRuntime<Locale>;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+  lifecyclePort: OrderPaymentLifecyclePort;
+  orderPaidLinesPort: OrderPaidLinesPort;
+  // Optional adopter note for the paid receipt; absent keeps today's receipt.
+  orderPaidParcelNote?: OrderPaidParcelNoteReader<Locale>;
+  // The delivered-email handler suppresses OUR delivered email for providers whose
+  // capability profile owns the notice (none today). Absent only in
+  // tests/non-transactional composition.
+  deliveredProviderKindReader?: DeliveredEmailProviderKindReader;
+  // Suppresses OUR buyer-facing email for channel-owned orders. Absent only in
+  // tests/non-transactional composition, where it degrades to today's behaviour.
+  buyerCommsPolicyReader?: OrderBuyerCommsPolicyReader;
+};
+
+function readOrderUuid(payload: Record<string, unknown>): string | null {
+  const value = payload.orderUuid;
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Wraps ONE buyer-facing email handler so a channel that owns buyer
+ * communication does not also get ours.
+ *
+ * WHY THE WRAPPER IS AT THE HANDLER AND NOT AT THE TRIGGER. The checkout email
+ * reconciler (`commerce_reconcile_checkout_email_outbox`) back-fills a `commerce.order.paid.email`
+ * row for EVERY order that reads `paid` and has none, keyed only on the order
+ * id — it does not look at `source_kind`, and outboxDispatchRuntime runs it
+ * inline immediately before the dispatch worker in the same invocation. A
+ * trigger-level or emitter-level suppression would therefore be undone on the
+ * very next reconcile pass, silently, and the buyer would get the email anyway.
+ * The dispatcher is the last place that can still decide.
+ *
+ * Recorded as `processed` rather than `discard` so the event settles once and
+ * never retries. `skipped` is one of the DELIVERY_LIFECYCLE_METADATA_KEYS below,
+ * so the email-delivery lifecycle trigger reads the suppression as a skip with a
+ * reason instead of leaving a delivery hanging — the same shape the
+ * carrier-owned delivered notice already uses.
+ */
+function suppressForChannel(
+  handler: OutboxHandler,
+  reader: OrderBuyerCommsPolicyReader | undefined,
+): OutboxHandler {
+  if (!reader) return handler;
+  return {
+    eventType: handler.eventType,
+    timeoutMs: handler.timeoutMs,
+    async handle(row, signal, execution) {
+      const orderUuid = readOrderUuid(row.payload);
+      // A payload with no usable order id is not a policy question. Hand it to
+      // the handler, whose own contract parse produces the right discard rather
+      // than this wrapper inventing a second failure mode for the same row.
+      if (orderUuid !== null) {
+        const policy = await reader.readOrderBuyerCommsPolicy(orderUuid);
+        if (!platformOwnsBuyerEmail(policy)) {
+          return { kind: "processed", detail: { skipped: "channel_owns_buyer_comms" } };
+        }
+      }
+      return handler.handle(row, signal, execution);
+    },
+  };
+}
+
+export function describeCoreOutboxHandlers(selection: {
+  transactionalEmail: boolean; fulfillmentEnabled: boolean;
+}): OutboxHandlerDescriptor[] {
+  return [
+    ...(selection.transactionalEmail ? [
+      outboxOrderDraftEmailDescriptor, outboxCheckoutRecoveryEmailDescriptor,
+      outboxOrderPaidEmailDescriptor, outboxPaymentFailedEmailDescriptor,
+      outboxCheckoutExpiredEmailDescriptor, outboxOrderRefundedEmailDescriptor,
+      outboxShipmentDispatchedEmailDescriptor, outboxShipmentDeliveredEmailDescriptor,
+      outboxShipmentExceptionEmailDescriptor, outboxReturnApprovedEmailDescriptor,
+      outboxReturnRejectedEmailDescriptor,
+    ] : []),
+    ...(selection.fulfillmentEnabled ? [outboxOrderPaidFulfillmentDescriptor] : []),
+  ];
+}
+
+export function createOutboxDispatchRegistry<Locale extends string>(deps: {
+  /** Bind the existing outbox rail's composition; commerce owns no second rail. */
+  uniqueRegistry(handlers: readonly OutboxHandler[]): OutboxHandlerRegistry;
+  transactionalEmail?: TransactionalEmailRegistryDeps<Locale>;
+  fulfillmentPort?: OrderPaidFulfillmentPort;
+  // Optional risk seam, evaluated per-handle via the thunk so the flag-OFF
+  // posture can ack without side effects. When absent/disabled, fulfillment runs
+  // exactly as before.
+  riskPort?: OrderPaidRiskAssessmentPort;
+  riskEnabled?: boolean;
+  // Read once at job construction. When false, the fulfillment event type is not
+  // registered, so commerce.order.paid rows stay unclaimed for later activation.
+  fulfillmentEnabled: boolean;
+  // Handlers from OTHER domains (subscription, accounting, …), composed by the
+  // job so this commerce file never imports cross-domain code. Each must claim a
+  // distinct event type. Appended after the commerce handlers.
+  extraHandlers?: readonly OutboxHandler[];
+  expectedDescriptors?: () => readonly OutboxHandlerDescriptor[];
+}): OutboxHandlerRegistry {
+  // Applied to the buyer-facing set below. The four email handlers it is NOT
+  // applied to are structurally unreachable for a channel order on the ingest
+  // path this repository ships, and each is asserted rather than assumed:
+  //   - order-draft-created: emitted INSIDE `commerce_create_order_draft`.
+  //     `commerce_create_channel_order` writes the order header directly and
+  //     emits `channel.order.ingested`, so no draft event ever exists.
+  //   - checkout-recovery: minted from an expired-checkout recovery token, which
+  //     only the checkout-expiry path can create.
+  //   - checkout-expired and payment-failed: both key off a one-time order
+  //     reaching status `expired`/`failed`, and the ONLY writer of those statuses
+  //     for a one-time order is `commerce_payment_apply_result`. The ingest saga
+  //     calls `applySucceeded` and nothing else — the marketplace collected the
+  //     money before the order existed here, so there is no decline or session to
+  //     expire. Nothing sweeps a stale `draft` order to `expired` either.
+  // This is an argument about the CURRENT ingest path. A later wave that gives a
+  // channel order a decline or expiry rail must revisit this list, not assume it.
+  //
+  // `commerce.order.canceled` is absent from this enumeration because its email
+  // handler (outboxOrderCanceledEmailHandler.ts) is registered by NOTHING — the
+  // only claimant of that event type is the accounting reversal handler, which
+  // arrives through `extraHandlers` and must keep running for a channel order.
+  // Wrapping a handler this registry does not compose would be theatre; if that
+  // email is ever wired up, it belongs in the wrapped set.
+  const suppress = (handler: OutboxHandler): OutboxHandler =>
+    suppressForChannel(handler, deps.transactionalEmail?.buyerCommsPolicyReader);
+  const handlers: OutboxHandler[] = [
+    ...(deps.transactionalEmail
+      ? [
+          createOutboxOrderDraftEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+            lifecyclePort: deps.transactionalEmail.lifecyclePort,
+          }),
+          createOutboxCheckoutRecoveryEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+            lifecyclePort: deps.transactionalEmail.lifecyclePort,
+          }),
+          suppress(createOutboxOrderPaidEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+            linesPort: deps.transactionalEmail.orderPaidLinesPort,
+            describeParcel: deps.transactionalEmail.orderPaidParcelNote,
+          })),
+          createOutboxPaymentFailedEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+            lifecyclePort: deps.transactionalEmail.lifecyclePort,
+          }),
+          createOutboxCheckoutExpiredEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+            lifecyclePort: deps.transactionalEmail.lifecyclePort,
+          }),
+          suppress(createOutboxOrderRefundedEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+          })),
+          suppress(createOutboxShipmentDispatchedEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+          })),
+          suppress(createOutboxShipmentDeliveredEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+            providerKindReader: deps.transactionalEmail.deliveredProviderKindReader,
+          })),
+          suppress(createOutboxShipmentExceptionEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+          })),
+          suppress(createOutboxReturnApprovedEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+          })),
+          suppress(createOutboxReturnRejectedEmailHandler({
+            runtime: deps.transactionalEmail.runtime,
+            emailPort: deps.transactionalEmail.emailPort,
+            recipientPort: deps.transactionalEmail.recipientPort,
+          })),
+        ]
+      : []),
+    ...(deps.fulfillmentEnabled && deps.fulfillmentPort
+      ? [
+          createOutboxOrderPaidFulfillmentHandler({
+            fulfillmentPort: deps.fulfillmentPort,
+            riskPort: deps.riskPort,
+            isRiskEnabled: () => deps.riskEnabled === true,
+          }),
+        ]
+      : []),
+    ...(deps.extraHandlers ?? []),
+  ];
+  const registry = deps.uniqueRegistry(handlers);
+  const expected = deps.expectedDescriptors?.() ?? composeOutboxHandlerDescriptors([
+    ...describeCoreOutboxHandlers({
+      transactionalEmail: Boolean(deps.transactionalEmail),
+      fulfillmentEnabled: deps.fulfillmentEnabled && Boolean(deps.fulfillmentPort),
+    }),
+    ...(deps.extraHandlers ?? []).map(({ eventType, timeoutMs }) => ({ eventType, timeoutMs })),
+  ]);
+  assertOutboxRegistryDescriptors(registry, expected);
+  return registry;
+}

package/src/commerce/server/outboxDispatchRegistryComposition.ts

@@ -0,0 +1,31 @@
+import type { OutboxHandlerDescriptor } from "@openlup/core/outbox";
+import type { OutboxHandlerRegistry } from "../outboxDispatchContracts.js";
+
+/** Preserve native registration order and the timeout sum of same-event handlers. */
+export function composeOutboxHandlerDescriptors(
+  handlers: readonly OutboxHandlerDescriptor[],
+): OutboxHandlerDescriptor[] {
+  const descriptors = new Map<string, OutboxHandlerDescriptor>();
+  for (const handler of handlers) {
+    const existing = descriptors.get(handler.eventType);
+    descriptors.set(handler.eventType, {
+      eventType: handler.eventType,
+      timeoutMs: (existing?.timeoutMs ?? 0) + handler.timeoutMs,
+    });
+  }
+  return [...descriptors.values()];
+}
+
+/** Refuse a different claim surface before a worker can call claimBatch. */
+export function assertOutboxRegistryDescriptors(
+  registry: OutboxHandlerRegistry,
+  expected: readonly OutboxHandlerDescriptor[],
+): void {
+  const actual = [...registry.entries()];
+  if (actual.length !== expected.length || actual.some(([key, handler], index) => {
+    const descriptor = expected[index];
+    return key !== descriptor.eventType || handler.eventType !== key
+      || handler.timeoutMs !== descriptor.timeoutMs
+      || !Number.isFinite(handler.timeoutMs) || handler.timeoutMs <= 0;
+  })) throw new Error("outbox_registry_descriptor_mismatch");
+}

package/src/commerce/server/outboxOrderDraftEmailHandler.ts

@@ -0,0 +1,162 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_ORDER_DRAFT_CREATED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerOutcome,
+} from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG,
+  type OrderEmailTotals,
+  type OrderPaymentLifecyclePort,
+  type OrderRecipientPort,
+  type TransactionalEmailPort,
+} from "../outboxOrderDraftEmailPorts.js";
+import { buildItems, type RawLine } from "../orderEmailLines.js";
+import { shouldSkipOrderDraftConfirmation } from "../orderEmailEligibility.js";
+
+export { OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG };
+
+const HANDLER_TIMEOUT_MS = 10_000;
+
+export const outboxOrderDraftEmailDescriptor = Object.freeze({
+  eventType: COMMERCE_ORDER_DRAFT_CREATED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+
+// Frozen minimal parse (challenge R-m5): validate ONLY the fields this handler
+// consumes, with schemas owned HERE — never the live quote/order-draft zod
+// schemas. A producer-side schema deploy must not retro-DLQ in-flight events.
+// Everything except orderUuid/orderId is optional-tolerant: malformed lines or
+// totals degrade the email content, they never fail the event.
+const payloadSubsetSchema = z
+  .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    orderDraftSnapshot: z.unknown().optional(),
+  })
+  .passthrough();
+
+const moneySubsetSchema = z
+  .object({
+    amountMinor: z.number().int().nonnegative(),
+    currency: z.string().trim().min(1),
+  })
+  .passthrough();
+
+const lineSubsetSchema = z
+  .object({
+    quantity: z.number().int().positive(),
+    productSlug: z.string().trim().min(1).optional(),
+    sku: z.string().trim().min(1).optional(),
+    lineSubtotalGross: moneySubsetSchema.optional(),
+  })
+  .passthrough();
+
+const snapshotSubsetSchema = z
+  .object({
+    lines: z.array(z.unknown()).optional(),
+    totals: z
+      .object({
+        subtotalGross: z.unknown().optional(),
+        discountTotalGross: z.unknown().optional(),
+        totalGross: z.unknown().optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+function extractLines(snapshot: unknown): RawLine[] {
+  const parsed = snapshotSubsetSchema.safeParse(snapshot);
+  if (!parsed.success || parsed.data.lines === undefined) return [];
+  const lines: RawLine[] = [];
+  for (const candidate of parsed.data.lines) {
+    const line = lineSubsetSchema.safeParse(candidate);
+    if (!line.success) continue;
+    if (line.data.productSlug === undefined && line.data.sku === undefined) continue;
+    lines.push({
+      label: null,
+      quantity: line.data.quantity,
+      lineSubtotalMinor: line.data.lineSubtotalGross?.amountMinor ?? null,
+      currency: line.data.lineSubtotalGross?.currency ?? null,
+    });
+  }
+  return lines;
+}
+
+function buildTotals<Locale extends string>(snapshot: unknown, runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "genericItemLabel" | "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">): OrderEmailTotals | null {
+  const parsed = snapshotSubsetSchema.safeParse(snapshot);
+  if (!parsed.success || parsed.data.totals === undefined) return null;
+  const total = moneySubsetSchema.safeParse(parsed.data.totals.totalGross);
+  if (!total.success) return null;
+  const subtotal = moneySubsetSchema.safeParse(parsed.data.totals.subtotalGross);
+  const discount = moneySubsetSchema.safeParse(parsed.data.totals.discountTotalGross);
+  const currency = total.data.currency;
+  return {
+    // Omit the subtotal row when it cannot be parsed — do NOT fall back to the
+    // grand total, which would render "Subtotal = Total" alongside a separate
+    // discount line that no longer reconciles.
+    subtotalLabel: subtotal.success
+      ? runtime.formatMoney(subtotal.data.amountMinor, subtotal.data.currency)
+      : null,
+    discountLabel:
+      discount.success && discount.data.amountMinor > 0
+        ? `-${runtime.formatMoney(discount.data.amountMinor, discount.data.currency)}`
+        : null,
+    totalLabel: runtime.formatMoney(total.data.amountMinor, currency),
+  };
+}
+
+export function createOutboxOrderDraftEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "genericItemLabel" | "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+  lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler {
+  return {
+    ...outboxOrderDraftEmailDescriptor,
+    async handle(row: OutboxEventRow, signal: AbortSignal): Promise<OutboxHandlerOutcome> {
+      const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+      if (parsed.ok === false) {
+        return parsed.outcome;
+      }
+
+      const lifecycle = await deps.lifecyclePort.read(parsed.data.orderUuid, signal);
+      const skipReason = shouldSkipOrderDraftConfirmation(lifecycle);
+      if (skipReason) {
+        return { kind: "processed", detail: { skipped: skipReason } };
+      }
+
+      const recipient = await deps.recipientPort.resolve(parsed.data.orderUuid, signal);
+      if (recipient === null) {
+        return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+      }
+
+      const alreadySent = await deps.emailPort.findExistingSend(
+        OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG,
+        row.id,
+      );
+      if (alreadySent) {
+        return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+      }
+
+      const lines = extractLines(parsed.data.orderDraftSnapshot);
+      const locale = deps.runtime.resolveLocale(recipient.country ?? null);
+
+      const outcome = await deps.emailPort.sendOrderConfirmation({
+        to: recipient.email,
+        firstName: recipient.firstName,
+        contextName: recipient.contextName ?? null,
+        orderId: parsed.data.orderId,
+        outboxEventId: row.id,
+        items: buildItems(lines, locale, deps.runtime),
+        totals: buildTotals(parsed.data.orderDraftSnapshot, deps.runtime),
+        locale,
+        signal,
+      });
+
+      return deps.runtime.mapSendOutcome(outcome);
+    },
+  };
+}