@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/server/commercePaidOrderOrchestration.ts

@@ -0,0 +1,275 @@
+import type { PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutJourney, CheckoutKind, CommerceOrderDraftWritePort, CommerceCheckoutRuntimePort } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import { CommerceOrderDraftPriceChangedError } from "../orderDraftErrors.js";
+import { uuidFromOrderRef, messageOf } from "../checkoutHelpers.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+import type { CheckoutPaymentExecution } from "./commerceCheckoutProviderPayment.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import type { CheckoutExecutionProvider, CheckoutProviderFlow } from "./checkoutRuntimeTypes.js";
+export interface CheckoutJourneyRuntimeRequest<Snapshot, PaymentExecution extends CheckoutPaymentExecution, Provider extends string = string, Flow extends string = string, MethodKind extends string = string, RecurringModel extends string = string> {
+  idempotencyKey: string; paymentAttemptSequence?: number;
+  orderDraft: { orderId: string; status: "draft"; paymentStatus: "not_started"; idempotencyKey: string; quoteSnapshot: Snapshot; replayed: boolean };
+  mode: "one_time" | "subscription_cycle"; saveForFutureUse: boolean;
+  clientId: string; shippingAddressId: string; paymentProvider: Provider;
+  returnContext: "public" | "account"; providerFlow: Flow;
+  paymentMethodRef?: string; paymentMethodAliasType?: MethodKind; paymentMethodRecurringModel?: RecurringModel;
+  paymentExecution?: PaymentExecution; declaredBankId?: string;
+  providerPayer?: { email: string; name: string; ip?: string | null; userAgent?: string | null };
+  metadata: Record<string, unknown>;
+}
+export interface CheckoutJourneyRuntimeResponse<Provider extends string = string> {
+  runtime: { orderId: string; payment: { paymentIntentId: string; paymentAttemptId: string | null; status: string; attemptStatus: string | null; provider: Provider; continuationActionOrigin?: "fresh_execution" | null; providerClientSecret?: string | null; providerAttemptId?: string | null; providerRedirectUrl?: string | null; providerNextActionKind?: string | null } };
+}
+export interface CheckoutJourneyResultRequest { idempotencyKey: string; orderId: string; paymentIntentId: string; resultStatus: "succeeded"; occurredAt: string }
+export interface CheckoutPaymentStartedEvent {
+  email: string;
+  clientId: string;
+  orderId: string;
+  paymentIntentId: string;
+}
+
+export type CheckoutStage =
+  | "quote"
+  | "order_draft"
+  | "start_runtime"
+  | "account_link"
+  | "apply_payment_result";
+
+export type CheckoutStageRecorder = <T>(
+  stage: CheckoutStage,
+  operation: () => Promise<T>,
+) => Promise<T>;
+
+export interface OrchestratedCheckoutResult<Snapshot, Provider extends string = string> {
+  orderId: string;
+  paymentIntentId: string;
+  paymentAttemptId: string | null;
+  paymentAttemptStatus?: string | null;
+  runtimePaymentStatus?: string;
+  executionRail: Provider;
+  continuationActionOrigin: "fresh_execution" | null;
+  providerClientSecret: string | null;
+  providerPaymentId: string | null;
+  providerRedirectUrl: string | null;
+  providerNextActionKind: string | null;
+  quoteSnapshot: Snapshot;
+  status: "paid" | "processing" | "failed";
+}
+
+export type PaidOrderOrchestrationDeps<Provisioned, Request, Snapshot, Draft, Extension, Runtime, Settlement, PaymentExecution extends CheckoutPaymentExecution, Provider extends string = string, Flow extends string = string, MethodKind extends string = string, RecurringModel extends string = string> = {
+  provisioned: Provisioned;
+  checkoutKind: CheckoutKind;
+  quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+  orderDraftPort: CommerceOrderDraftWritePort<{ idempotencyKey: string; quoteSnapshot: Snapshot }, Draft>;
+  runtimePort: CommerceCheckoutRuntimePort<CheckoutJourneyRuntimeRequest<Snapshot, PaymentExecution, Provider, Flow, MethodKind, RecurringModel> & Extension, Runtime, CheckoutJourneyResultRequest, Settlement>;
+  paymentProvider?: Provider;
+    saveForFutureUse?: boolean;
+    paymentAttemptSequence?: number;
+  returnContext?: "public" | "account"; // Host redirect return; defaults to "public"
+  paymentExecution?: PaymentExecution;
+  declaredBankId?: string;
+  paymentMethodRef?: string;
+  paymentMethodAliasType?: MethodKind;
+  paymentMethodRecurringModel?: RecurringModel;
+  quoteSnapshot?: Snapshot;
+  providerPayer?: {
+    email: string;
+    name: string;
+    ip?: string | null;
+    userAgent?: string | null;
+  };
+  onPaymentStarted?: (event: CheckoutPaymentStartedEvent) => Promise<void>;
+  recordStage?: CheckoutStageRecorder;
+  now: () => Date;
+}
+
+export function createPaidOrderOrchestration<Provisioned extends { clientId: string; addressId: string }, Request, Snapshot extends CheckoutQuoteSnapshot, Draft extends { orderDraft: { orderId: string } }, Extension extends object, Runtime extends CheckoutJourneyRuntimeResponse<Provider>, Settlement, PaymentExecution extends CheckoutPaymentExecution, Provider extends string, Flow extends string, MethodKind extends string = string, RecurringModel extends string = string>(bindings: {
+  defaultPaymentProvider: Provider; rehearsalPaymentProvider: Provider; confirmationProvider: Provider; missingConfirmationMessage: string;
+  providerFlowFor(provider: Provider, execution: PaymentExecution | undefined): Flow;
+  runtimeRequestExtension(provisioned: Provisioned): Extension;
+  mapStartRuntimeFailure(error: unknown, draftOrderId: string): CheckoutOrchestrationError;
+}) {
+
+async function orchestrateCheckoutJourney(
+  deps: PaidOrderOrchestrationDeps<Provisioned, Request, Snapshot, Draft, Extension, Runtime, Settlement, PaymentExecution, Provider, Flow, MethodKind, RecurringModel>,
+  journey: CheckoutJourney<Request, PricingPolicySnapshot>,
+): Promise<OrchestratedCheckoutResult<Snapshot, Provider>> {
+  const {
+    provisioned,
+    checkoutKind,
+    quotePort,
+    orderDraftPort,
+    runtimePort,
+    paymentProvider = bindings.defaultPaymentProvider,
+    paymentAttemptSequence,
+    paymentExecution,
+    declaredBankId,
+    paymentMethodRef,
+    paymentMethodAliasType,
+    paymentMethodRecurringModel,
+    quoteSnapshot: providedQuoteSnapshot,
+    providerPayer,
+    onPaymentStarted,
+    recordStage,
+    now,
+  } = deps;
+  const stage: CheckoutStageRecorder = recordStage ?? ((_stage, operation) => operation());
+
+  // (b) quote(one_time) -> snapshot. No order persisted yet -> no compensation.
+  let quoteSnapshot: Snapshot | undefined = providedQuoteSnapshot;
+  if (!quoteSnapshot) {
+    try {
+      quoteSnapshot = await stage("quote", () =>
+        quotePort.createQuote(journey.createQuoteRequest(), { clientId: provisioned.clientId }),
+      );
+    } catch (error) {
+      throw new CheckoutOrchestrationError(messageOf(error, "quote"), null);
+    }
+  }
+
+  // (c) order-draft(idempotencyKey, snapshot). If the canonical writer throws,
+  // its transaction (including any promotion claim) rolls back, so there is no
+  // persisted order id to compensate.
+  let draftOrderId: string;
+  try {
+    const draft = await stage("order_draft", () =>
+      orderDraftPort.createOrderDraft(
+        { idempotencyKey: journey.idempotencyKey, quoteSnapshot },
+        { clientId: provisioned.clientId }, // out-of-band -> commerce_orders.client_id -> outbox recipient
+      ),
+    );
+    draftOrderId = uuidFromOrderRef(draft.orderDraft.orderId);
+  } catch (error) {
+    if (error instanceof CommerceOrderDraftPriceChangedError) {
+      throw new CheckoutOrchestrationError(
+        messageOf(error, "order_draft"),
+        null,
+        "promotion_code_price_changed",
+      );
+    }
+    throw new CheckoutOrchestrationError(messageOf(error, "order_draft"), null);
+  }
+
+  // (d) startRuntime -> finalizes order, reserves inventory, opens payment intent.
+  // From here on a throw leaves a live reservation, so compensation targets the order.
+  let orderId: string;
+  let paymentIntentId: string;
+  let paymentContinuation: Pick<OrchestratedCheckoutResult<Snapshot, Provider>, "paymentAttemptId" | "paymentAttemptStatus" | "runtimePaymentStatus" | "executionRail" | "continuationActionOrigin">;
+  let providerClientSecret: string | null;
+  let providerPaymentId: string | null;
+  let providerRedirectUrl: string | null;
+  let providerNextActionKind: string | null;
+  let runtimeRefused: boolean;
+  try {
+    const started = await stage("start_runtime", () =>
+      runtimePort.startRuntime({
+        idempotencyKey: journey.idempotencyKey,
+        paymentAttemptSequence,
+        orderDraft: {
+          orderId: `order_${draftOrderId}`,
+          status: "draft",
+          paymentStatus: "not_started",
+          idempotencyKey: journey.idempotencyKey,
+          quoteSnapshot,
+          replayed: false,
+        },
+        // subscription_initial finalizes as subscription_cycle: finalize creates+links
+        // the provisional subscription; one_time would violate the mode contract.
+        mode: checkoutKind === "subscription_initial" ? "subscription_cycle" : "one_time",
+        saveForFutureUse: deps.saveForFutureUse ?? checkoutKind === "subscription_initial",
+        clientId: provisioned.clientId, shippingAddressId: provisioned.addressId, ...bindings.runtimeRequestExtension(provisioned),
+        paymentProvider,
+        returnContext: deps.returnContext ?? "public",
+        providerFlow: bindings.providerFlowFor(paymentProvider, paymentExecution),
+        paymentMethodRef, paymentMethodAliasType, paymentMethodRecurringModel,
+        paymentExecution,
+        declaredBankId,
+        providerPayer,
+        metadata: journey.createRuntimeMetadata(quoteSnapshot.quote.context?.pricingPolicy),
+      }),
+    );
+    orderId = started.runtime.orderId;
+    paymentIntentId = started.runtime.payment.paymentIntentId;
+    paymentContinuation = { paymentAttemptStatus: started.runtime.payment.attemptStatus, runtimePaymentStatus: started.runtime.payment.status, paymentAttemptId: started.runtime.payment.paymentAttemptId, executionRail: started.runtime.payment.provider, continuationActionOrigin: started.runtime.payment.continuationActionOrigin ?? null };
+    providerClientSecret = started.runtime.payment.providerClientSecret ?? null;
+    providerPaymentId = started.runtime.payment.providerAttemptId ?? null;
+    providerRedirectUrl = started.runtime.payment.providerRedirectUrl ?? null;
+    providerNextActionKind = started.runtime.payment.providerNextActionKind ?? null;
+    runtimeRefused = started.runtime.payment.status === "failed" || started.runtime.payment.attemptStatus === "failed";
+  } catch (error) {
+    // startRuntime is itself a multi-step saga; reservations may already exist.
+    throw bindings.mapStartRuntimeFailure(error, draftOrderId);
+  }
+
+  // A confirmation-bearing runtime that returned without its confirmation capability has
+  // already crossed the PSP boundary. Preserve the aggregate for payment-control
+  // reconciliation rather than treating this post-dispatch contract failure as
+  // permission to release stock or mint another attempt.
+  const settledFreshRefusal = paymentContinuation.continuationActionOrigin === "fresh_execution"
+    && paymentContinuation.runtimePaymentStatus === "failed" && paymentContinuation.paymentAttemptStatus === "failed"
+    && Boolean(orderId && paymentIntentId && paymentContinuation.paymentAttemptId) && paymentContinuation.executionRail === paymentProvider;
+  if (paymentProvider === bindings.confirmationProvider && !providerClientSecret && !settledFreshRefusal) {
+    throw new CheckoutOrchestrationError(
+      bindings.missingConfirmationMessage,
+      null,
+      "provider_attempt_in_flight",
+    );
+  }
+
+  if (onPaymentStarted && !runtimeRefused) {
+    try {
+      await stage("account_link", () =>
+        onPaymentStarted({
+          email: journey.contactEmail,
+          clientId: provisioned.clientId,
+          orderId,
+          paymentIntentId,
+        }),
+      );
+    } catch {
+      console.warn("checkout_payment_started_hook_failed", JSON.stringify({ orderId }));
+    }
+  }
+
+  // (e) For the rehearsal no-op provider only: applyPaymentResult(succeeded).
+  // For real PSPs, the saga returns `"processing"`; payment-control is flipped
+  // by the webhook (Wave B) once the provider confirms the charge. Auto-marking
+  // a real-provider intent as `succeeded` here would bypass the webhook proof
+  // and risk a "local paid / provider unpaid" mismatch. A rehearsal adapter that
+  // already declined (the reference profile's refusal simulator) must never be
+  // auto-settled as succeeded either — the runtime's own terminal answer wins.
+  if (paymentProvider === bindings.rehearsalPaymentProvider && !runtimeRefused) {
+    try {
+      await stage("apply_payment_result", () =>
+        runtimePort.applyPaymentResult({
+          idempotencyKey: journey.idempotencyKey,
+          orderId,
+          paymentIntentId,
+          resultStatus: "succeeded",
+          occurredAt: now().toISOString(),
+        }),
+      );
+    } catch (error) {
+      throw new CheckoutOrchestrationError(messageOf(error, "apply_payment_result"), orderId);
+    }
+
+  }
+
+  return {
+    orderId,
+    paymentIntentId,
+    ...paymentContinuation,
+    providerClientSecret,
+    providerPaymentId,
+    providerRedirectUrl,
+    providerNextActionKind,
+    quoteSnapshot,
+    // A refusal the saga already knows about must not be reported as a wait.
+    status: paymentProvider === bindings.rehearsalPaymentProvider && !runtimeRefused ? "paid"
+      : runtimeRefused ? "failed" : "processing",
+  };
+}
+
+return { orchestrateCheckoutJourney };
+}

package/src/commerce/server/commerceProviderAttemptFailure.ts

@@ -0,0 +1,257 @@
+import type { z } from "zod";
+import type { FinalizedCheckoutOrder } from "../contracts/index.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+type ProviderAttemptDispatchState = "not_dispatched" | "refused" | "unknown";
+export interface CheckoutAttemptFailureFacts extends Error { paymentAttemptId: string | null; phase: string; dispatchState: ProviderAttemptDispatchState }
+export interface CheckoutPreDispatchFailure extends CheckoutAttemptFailureFacts { code: string; retryCount: number }
+export interface CheckoutInFlightFailure extends CheckoutAttemptFailureFacts { code: string }
+export interface CheckoutUncertainFailure<Diagnostic> extends CheckoutAttemptFailureFacts { errorCode: string; failureDiagnostic: Diagnostic | null }
+interface ReopenPaymentPort<Evidence> {
+  reopenInteractivePreparedAttempt?(input: { idempotencyKey: string; paymentIntentId: string; paymentAttemptId: string; expectedOrderId: string; expectedSubscriptionId: string | null; expectedSubscriptionCycleId: string | null; evidence: Evidence }): Promise<{ paymentAttemptId: string; paymentIntentId: string }>;
+}
+export function createCheckoutProviderAttemptFailure<Order extends FinalizedCheckoutOrder<string>, Reservation, Response, Diagnostic, PreDispatch extends CheckoutPreDispatchFailure, InFlight extends CheckoutInFlightFailure, Uncertain extends CheckoutUncertainFailure<Diagnostic>, Evidence>(bindings: {
+  trustedPreDispatchEvidence(error: PreDispatch): Evidence | null;
+  isPreDispatch(error: unknown): error is PreDispatch;
+  isInFlight(error: unknown): error is InFlight;
+  isUncertain(error: unknown): error is Uncertain;
+  providerAttemptFailureLogFields(error: { paymentAttemptId: string | null; phase: string; code: string; dispatchState: ProviderAttemptDispatchState; retryCount: number; failureDiagnostic: Diagnostic | null }): unknown;
+  responseSchema: z.ZodType<Response>;
+  runtimeResponseExtension(order: Order): object;
+  contractVersion: string;
+}) {
+
+type ProviderAttemptFailure =
+  | InFlight
+  | PreDispatch
+  | Uncertain;
+
+class CheckoutProviderAttemptFailure extends CheckoutOrchestrationError {
+  readonly paymentAttemptId: string | null;
+  readonly phase: string;
+  readonly code: string;
+  readonly dispatchState: ProviderAttemptDispatchState;
+  readonly retryCount: number;
+  readonly failureDiagnostic: Diagnostic | null;
+
+  constructor(error: ProviderAttemptFailure) {
+    const notDispatched = bindings.isPreDispatch(error);
+    super(
+      notDispatched
+        ? "start_runtime: provider transaction was not dispatched"
+        : "start_runtime: provider attempt remains in flight",
+      null,
+      notDispatched ? "provider_attempt_not_dispatched" : "provider_attempt_in_flight",
+    );
+    this.name = "CheckoutProviderAttemptFailure";
+    this.paymentAttemptId = error.paymentAttemptId;
+    this.phase = error.phase;
+    this.code = bindings.isUncertain(error) ? error.errorCode : error.code;
+    this.dispatchState = error.dispatchState;
+    this.retryCount = bindings.isPreDispatch(error) ? error.retryCount : 0;
+    this.failureDiagnostic = bindings.isUncertain(error)
+      ? error.failureDiagnostic
+      : null;
+  }
+}
+
+function checkoutProviderAttemptFailure(error: unknown): CheckoutProviderAttemptFailure | null {
+  if (
+    bindings.isInFlight(error) ||
+    bindings.isPreDispatch(error) ||
+    bindings.isUncertain(error)
+  ) {
+    return new CheckoutProviderAttemptFailure(error);
+  }
+  return null;
+}
+
+function logCheckoutProviderAttemptFailure(error: CheckoutProviderAttemptFailure): void {
+  console.error("checkout_provider_attempt_failure", JSON.stringify(bindings.providerAttemptFailureLogFields(error)));
+}
+
+const trustedPreDispatchEvidence = bindings.trustedPreDispatchEvidence;
+
+function buildReopenedPreparedAttemptResponse(input: {
+  order: Order;
+  reservations: Reservation[];
+  intent: { paymentIntentId: string; paymentId: string };
+  paymentAttemptId: string;
+  provider: string;
+}): Response {
+  return bindings.responseSchema.parse({
+    contractVersion: bindings.contractVersion,
+    runtime: {
+      orderId: input.order.orderId,
+      orderRef: input.order.orderRef,
+      mode: input.order.mode,
+      clientId: input.order.clientId,
+      ...bindings.runtimeResponseExtension(input.order),
+      shippingAddressId: input.order.shippingAddressId,
+      total: input.order.total,
+      finalizedReplayed: input.order.replayed,
+      reservations: input.reservations,
+      payment: {
+        paymentIntentId: input.intent.paymentIntentId,
+        paymentId: input.intent.paymentId,
+        paymentAttemptId: input.paymentAttemptId,
+        status: "failed",
+        attemptStatus: "failed",
+        provider: input.provider,
+        providerAttemptId: null,
+        providerClientSecret: null,
+        providerRedirectUrl: null,
+        providerNextActionKind: null,
+        continuationActionOrigin: null,
+      },
+      readiness: {
+        omsEligibility: { allowed: false, reason: "order_not_paid" },
+        fulfillmentCreate: { allowed: false, reason: "order_not_paid", omsReason: "order_not_paid" },
+      },
+      nextAction: { kind: "await_hidden_payment_result", provider: input.provider },
+    },
+  });
+}
+
+type PreDispatchReopenGate = {
+  paymentAttemptId: string;
+  evidence: Evidence;
+  reopen: NonNullable<ReopenPaymentPort<Evidence>["reopenInteractivePreparedAttempt"]>;
+};
+
+interface PreDispatchReopenIdentity {
+  paymentIntentId: string;
+  orderId: string;
+  subscriptionId: string | null;
+  subscriptionCycleId: string | null;
+}
+
+function preDispatchReopenGate(
+  error: PreDispatch,
+  paymentPort: ReopenPaymentPort<Evidence>,
+): PreDispatchReopenGate | null {
+  const evidence = trustedPreDispatchEvidence(error);
+  const paymentAttemptId = error.paymentAttemptId;
+  const reopen = paymentPort.reopenInteractivePreparedAttempt;
+  if (!evidence || !paymentAttemptId || typeof reopen !== "function") {
+    logPreDispatchReopenFailure(error, "capability_unavailable");
+    return null;
+  }
+  return { paymentAttemptId, evidence, reopen };
+}
+
+async function writePreDispatchReopen(input: {
+  gate: PreDispatchReopenGate;
+  error: PreDispatch;
+  paymentPort: ReopenPaymentPort<Evidence>;
+  paymentExecutionIdempotencyKey: string;
+  identity: PreDispatchReopenIdentity;
+}): Promise<boolean> {
+  const { gate, identity } = input;
+  const request = {
+    idempotencyKey: `${input.paymentExecutionIdempotencyKey}:reopen-not-dispatched`,
+    paymentIntentId: identity.paymentIntentId,
+    paymentAttemptId: gate.paymentAttemptId,
+    expectedOrderId: identity.orderId,
+    expectedSubscriptionId: identity.subscriptionId,
+    expectedSubscriptionCycleId: identity.subscriptionCycleId,
+    evidence: gate.evidence,
+  };
+  const call = async () => {
+    const result = await gate.reopen.call(input.paymentPort, request);
+    if (result.paymentAttemptId !== gate.paymentAttemptId || result.paymentIntentId !== identity.paymentIntentId) {
+      throw new Error("interactive_prepared_attempt_reopen_identity_mismatch");
+    }
+  };
+  try {
+    await call();
+    return true;
+  } catch {
+    console.error("provider_attempt_predispatch_reopen_retry", JSON.stringify({
+      paymentAttemptId: gate.paymentAttemptId,
+      retryOrdinal: 1,
+    }));
+    try {
+      await call();
+      return true;
+    } catch {
+      logPreDispatchReopenFailure(input.error, "rpc_unavailable");
+      return false;
+    }
+  }
+}
+
+async function reopenExhaustedPreDispatchAttempt(input: {
+  error: PreDispatch;
+  paymentPort: ReopenPaymentPort<Evidence>;
+  paymentExecutionIdempotencyKey: string;
+  order: Order;
+  reservations: Reservation[];
+  intent: { paymentIntentId: string; paymentId: string };
+  provider: string;
+}): Promise<Response> {
+  const gate = preDispatchReopenGate(input.error, input.paymentPort);
+  if (!gate) throw input.error;
+  // Build and validate the response before the mutation. No fallible work may
+  // follow a successful reopen, or a schema/readiness error could compensate a
+  // now-payable order whose old provider attempt is already terminal.
+  const response = buildReopenedPreparedAttemptResponse({
+    order: input.order,
+    reservations: input.reservations,
+    intent: input.intent,
+    paymentAttemptId: gate.paymentAttemptId,
+    provider: input.provider,
+  });
+  const reopened = await writePreDispatchReopen({
+    gate,
+    error: input.error,
+    paymentPort: input.paymentPort,
+    paymentExecutionIdempotencyKey: input.paymentExecutionIdempotencyKey,
+    identity: {
+      paymentIntentId: input.intent.paymentIntentId,
+      orderId: input.order.orderId,
+      subscriptionId: input.order.subscriptionId,
+      subscriptionCycleId: input.order.subscriptionCycleId,
+    },
+  });
+  if (!reopened) throw input.error;
+  return response;
+}
+
+async function reopenExhaustedPreDispatchRecoveryAttempt(input: {
+  error: PreDispatch;
+  paymentPort: ReopenPaymentPort<Evidence>;
+  paymentExecutionIdempotencyKey: string;
+  paymentIntentId: string;
+  order: { orderId: string; subscriptionId: string | null; subscriptionCycleId: string | null };
+}): Promise<boolean> {
+  const gate = preDispatchReopenGate(input.error, input.paymentPort);
+  if (!gate) return false;
+  return writePreDispatchReopen({
+    gate,
+    error: input.error,
+    paymentPort: input.paymentPort,
+    paymentExecutionIdempotencyKey: input.paymentExecutionIdempotencyKey,
+    identity: {
+      paymentIntentId: input.paymentIntentId,
+      orderId: input.order.orderId,
+      subscriptionId: input.order.subscriptionId,
+      subscriptionCycleId: input.order.subscriptionCycleId,
+    },
+  });
+}
+
+function logPreDispatchReopenFailure(
+  error: PreDispatch,
+  reason: "capability_unavailable" | "rpc_unavailable",
+): void {
+  console.error("provider_attempt_predispatch_reopen_failed", JSON.stringify({
+    paymentAttemptId: error.paymentAttemptId,
+    phase: error.phase,
+    code: error.code,
+    dispatchState: error.dispatchState,
+    reason,
+  }));
+}
+
+return { CheckoutProviderAttemptFailure, checkoutProviderAttemptFailure, logCheckoutProviderAttemptFailure, trustedPreDispatchEvidence, buildReopenedPreparedAttemptResponse, reopenExhaustedPreDispatchAttempt, reopenExhaustedPreDispatchRecoveryAttempt };
+}

package/src/commerce/server/commerceReturnsHandlers.ts

@@ -0,0 +1,143 @@
+// BFF handlers for the Commerce Returns R0 control plane:
+//   - customer: POST /api/bff/commerce/returns/request  (bearer-authenticated)
+//   - admin:    POST /api/bff/admin/returns/approve|reject
+// Each validates with the returns port schemas and calls the service-role port,
+// mapping RPC input/state errors (ERRCODE 22023) to 400s.
+
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { z } from "zod";
+import {
+  returnApproveSchema,
+  returnRejectSchema,
+  returnRequestCreateSchema,
+  type CommerceReturnsPort,
+  type ReturnRequestCreateInput,
+} from "../commerceReturnsPort.js";
+
+type AdminAuthResult =
+  | { ok: true; userId: string }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL"; message: string };
+
+// Local auth-result shape (structural match for the customers auth result) so the
+// commerce domain stays free of a cross-domain import of customers internals.
+type CustomerAuthResult =
+  | { ok: true; userId: string }
+  | { ok: false; code: "UNAUTHORIZED"; message: string };
+
+// RPC validation/state errors that map to a 400 (vs an unexpected 500).
+const CLIENT_ERROR = /_invalid_input|_invalid_state|_not_found|_not_returnable|_quantity_exceeds_ordered|_line_not_in_order/;
+
+function methodGuard(req: HttpRequest, res: HttpResponse, responder: BffResponder): boolean {
+  const { sendBffError } = responder;
+  if (req.method !== "POST") {
+    sendBffError(res, "METHOD_NOT_ALLOWED", "Method not allowed", { status: 405 });
+    return false;
+  }
+  return true;
+}
+
+function mapExecuteError(res: HttpResponse, error: unknown, responder: BffResponder): void {
+  const { sendBffError } = responder;
+  const message = error instanceof Error ? error.message : "return_operation_failed";
+  if (CLIENT_ERROR.test(message)) {
+    sendBffError(res, "BAD_REQUEST", "Return request rejected", { details: { reason: message } });
+    return;
+  }
+  sendBffError(res, "INTERNAL", "Return operation failed");
+}
+
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createCustomerReturnRequestHandler(deps: {
+  responder: BffResponder;
+  port: Pick<CommerceReturnsPort<string>, "createRequest">;
+  requestSchema?: z.ZodType<ReturnRequestCreateInput<string>>;
+  authenticateUser: () => Promise<CustomerAuthResult>;
+  enabled: () => boolean;
+}) {
+  const { sendBffError, sendBffSuccess } = deps.responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (!methodGuard(req, res, deps.responder)) return;
+    if (!deps.enabled()) {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Returns are not enabled", {
+        details: { feature: "commerce_returns", featureFlag: "COMMERCE_RETURNS_ENABLED", reason: "feature_flag_disabled" },
+      });
+      return;
+    }
+    const auth = await deps.authenticateUser();
+    if (!auth.ok) {
+      sendBffError(res, "UNAUTHORIZED", "Sign in required to request a return");
+      return;
+    }
+    const parsed = (deps.requestSchema ?? returnRequestCreateSchema).safeParse(req.body ?? {});
+    if (!parsed.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid return request", { details: parsed.error.flatten() });
+      return;
+    }
+    try {
+      const result = await deps.port.createRequest({ ...parsed.data, requestedBy: auth.userId });
+      sendBffSuccess(res, result);
+    } catch (error) {
+      mapExecuteError(res, error, deps.responder);
+    }
+  };
+}
+
+function createAdminReturnHandler<T>(deps: {
+  responder: BffResponder;
+  authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>;
+  requestSchema: { safeParse: (input: unknown) => { success: true; data: T } | { success: false; error: { flatten: () => unknown } } };
+  invalidMessage: string;
+  execute: (request: T, actorUserId: string) => Promise<unknown>;
+}) {
+  const { sendBffError, sendBffSuccess } = deps.responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (!methodGuard(req, res, deps.responder)) return;
+    const auth = await deps.authorizeAdmin(req);
+    if (auth.ok === false) {
+      sendBffError(res, auth.code, auth.message);
+      return;
+    }
+    const parsed = deps.requestSchema.safeParse(req.body ?? {});
+    if (parsed.success === false) {
+      sendBffError(res, "BAD_REQUEST", deps.invalidMessage, { details: parsed.error.flatten() });
+      return;
+    }
+    try {
+      const result = await deps.execute(parsed.data, auth.userId);
+      sendBffSuccess(res, result);
+    } catch (error) {
+      mapExecuteError(res, error, deps.responder);
+    }
+  };
+}
+
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createAdminReturnApproveHandler(deps: {
+  responder: BffResponder;
+  authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>;
+  port: Pick<CommerceReturnsPort, "approve">;
+}) {
+  return createAdminReturnHandler({
+    responder: deps.responder,
+    authorizeAdmin: deps.authorizeAdmin,
+    requestSchema: returnApproveSchema,
+    invalidMessage: "Invalid return approve request",
+    execute: (request, actorUserId) => deps.port.approve({ ...request, actorUserId }),
+  });
+}
+
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createAdminReturnRejectHandler(deps: {
+  responder: BffResponder;
+  authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>;
+  port: Pick<CommerceReturnsPort, "reject">;
+}) {
+  return createAdminReturnHandler({
+    responder: deps.responder,
+    authorizeAdmin: deps.authorizeAdmin,
+    requestSchema: returnRejectSchema,
+    invalidMessage: "Invalid return reject request",
+    execute: (request, actorUserId) => deps.port.reject({ ...request, actorUserId }),
+  });
+}