@openlup/platform 0.25.0 → 0.27.0

package/src/commerce/server/commerceCheckoutCompensation.ts

@@ -0,0 +1,66 @@
+export interface CheckoutCompensationPort {
+  releaseOrderReservations(input: {
+    idempotencyKey: string;
+    orderId: string;
+    reason: string;
+  }): Promise<{ releasedCount: number }>;
+  cancelUnstartedPromotionOrder(input: {
+    idempotencyKey: string;
+    orderId: string;
+    reason: string;
+  }): Promise<{ cancelled: boolean }>;
+  cancelAbandonedOrder(input: {
+    idempotencyKey: string;
+    orderId: string;
+    reason: string;
+  }): Promise<{ cancelled: boolean }>;
+}
+
+export async function tryCompensate(
+  port: CheckoutCompensationPort,
+  idempotencyKey: string,
+  orderId: string,
+  options?: { cancellationReason?: string },
+): Promise<void> {
+  const promotionCancellationReason = options?.cancellationReason
+    ?? "checkout_orchestration_failed_before_runtime";
+  const abandonedCancellationReason = options?.cancellationReason
+    ?? "checkout_orchestration_failed_before_provider_dispatch";
+  try {
+    await port.releaseOrderReservations({
+      idempotencyKey: `${idempotencyKey}:checkout-compensation`,
+      orderId,
+      reason: "checkout_orchestration_failed",
+    });
+  } catch {
+    console.warn("checkout_compensation_release_failed", JSON.stringify({ orderId }));
+  }
+  let promotionOrderCancelled = false;
+  try {
+    const result = await port.cancelUnstartedPromotionOrder({
+      idempotencyKey,
+      orderId,
+      reason: promotionCancellationReason,
+    });
+    promotionOrderCancelled = result.cancelled;
+  } catch {
+    console.warn("checkout_promotion_draft_compensation_failed", JSON.stringify({ orderId }));
+  }
+  if (promotionOrderCancelled) return;
+
+  // The promotion-specific cleanup deliberately refuses an order once a local
+  // payment intent exists. A deterministic pre-dispatch runtime failure is still
+  // safe to cancel: the caller withholds the order id for every uncertain or
+  // in-flight provider attempt, so reaching this fallback proves no PSP dispatch
+  // may have taken money. Use the canonical aggregate cleanup to close the order,
+  // payment intent and provisional subscription instead of leaving pending ghosts.
+  try {
+    await port.cancelAbandonedOrder({
+      idempotencyKey,
+      orderId,
+      reason: abandonedCancellationReason,
+    });
+  } catch {
+    console.warn("checkout_abandoned_order_compensation_failed", JSON.stringify({ orderId }));
+  }
+}

package/src/commerce/server/commerceCheckoutContinuationTerms.ts

@@ -0,0 +1,87 @@
+import type { z } from "zod";
+import { acquisitionExpectationChanged, type AcquisitionTermsExpectation, type CreateQuoteRequest } from "../../pricing/index.js";
+import { stableJson } from "../../promotions/index.js";
+import type { CheckoutKind, ConfiguratorIntent } from "../contracts/index.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import type { StarterDeclaration } from "./commerceStarterOfferGuard.js";
+import { selectedDeliveryMatches, type CheckoutResumeGuardDeps } from "./commerceCheckoutResumeGuard.js";
+export function createSavedAcquisitionContinuation<Intent extends ConfiguratorIntent & { selectedDelivery?: unknown }, Provisioned, Request extends CreateQuoteRequest, Snapshot extends CheckoutQuoteSnapshot, InvoicePreference, Response>(bindings: {
+  quoteSchema: z.ZodType<Snapshot>;
+  buildQuoteRequest(intent: Intent, provisioned: Provisioned): Request;
+  sameSubjectContext(context: NonNullable<Snapshot["quote"]["context"]>, fresh: Request, provisioned: Provisioned): boolean;
+  runtimeMetadata(intent: Intent, kind: CheckoutKind, preference?: InvoicePreference): Record<string, unknown>;
+  starterDeclaration(intent: Intent): StarterDeclaration | undefined;
+  starterPlan(snapshot: Snapshot): { starterIntervalDays: number; delivery2: { discountBps: number }; graduation: { cadenceDays: number; lines: Array<{ qty: number }> } } | undefined;
+  buildSavedOrderResumeResponse(input: { resumable: Awaited<ReturnType<NonNullable<CheckoutResumeGuardDeps["resumableOrderPort"]>["findResumableOrderForClient"]>> & {}; clientId: string; checkoutKind: CheckoutKind; intent: Intent }): Response;
+}) {
+
+async function resolveSavedAcquisitionContinuation(input: {
+  deps: CheckoutResumeGuardDeps;
+  clientId: string;
+  provisioned: Provisioned;
+  checkoutKind: CheckoutKind;
+  intent: Intent;
+  invoicePreference?: InvoicePreference;
+  expectedQuote?: {
+    totalGross: { amountMinor: number; currency: string };
+    acquisitionTerms?: AcquisitionTermsExpectation;
+  };
+  now: () => Date;
+}): Promise<Response | null> {
+  const { deps, clientId, checkoutKind, intent, expectedQuote } = input;
+  if (!deps.resumableOrderPort || !expectedQuote || checkoutKind !== "subscription_initial") return null;
+  try {
+    const resumable = await deps.resumableOrderPort.findResumableOrderForClient({
+      clientId, withinMinutes: deps.resumeWindowMinutes ?? 60,
+      now: input.now(), journeyKey: intent.idempotencyKey,
+    });
+    if (!resumable || !resumable.paymentIntentId || !selectedDeliveryMatches(resumable.metadata, intent)) return null;
+    const saved = bindings.quoteSchema.safeParse(resumable.metadata?.quoteSnapshot);
+    if (!saved.success) return null;
+    const { quote } = saved.data;
+    const context = quote.context;
+    const fresh = bindings.buildQuoteRequest(intent, input.provisioned);
+    if (!context || context.mode !== "subscription" || context.cadenceDays !== fresh.cadenceDays
+      || !bindings.sameSubjectContext(context, fresh, input.provisioned) || (context as typeof context & { offerVersion?: string }).offerVersion !== intent.offerVersion
+
+      || stableJson(context.promoCodes) !== stableJson(fresh.promoCodes)
+      || lineKey(quote.lines) !== lineKey(fresh.lines)
+      || stableJson(quote.totalGross) !== stableJson(expectedQuote.totalGross)
+      || acquisitionExpectationChanged(expectedQuote.acquisitionTerms, context.acquisitionTerms)
+      || acquisitionExpectationChanged(bindings.starterDeclaration(intent)?.acquisitionTerms, context.acquisitionTerms)) return null;
+    const metadata = resumable.metadata ?? {};
+    const finalized = record(metadata.runtimeFinalize);
+    const savedContact = metadata.deliveryContact ?? finalized?.deliveryContact;
+    const freshMetadata = bindings.runtimeMetadata(intent, checkoutKind, input.invoicePreference);
+    if (!savedContact || stableJson(savedContact) !== stableJson(freshMetadata.deliveryContact)) return null;
+    const savedInvoice = metadata.invoiceBuyerSnapshot ?? finalized?.invoiceBuyerSnapshot;
+    if (!savedInvoice || stableJson(savedInvoice) !== stableJson(freshMetadata.invoiceBuyerSnapshot)) return null;
+    const starter = bindings.starterPlan(saved.data);
+    const declared = bindings.starterDeclaration(intent);
+    if (Boolean(starter) !== Boolean(declared)) return null;
+    if (starter && declared && (
+      starter.starterIntervalDays !== declared.intervalDays
+      || starter.delivery2.discountBps !== declared.delivery2DiscountBps
+      || starter.graduation.cadenceDays !== declared.steady.cadenceDays
+      || starter.graduation.lines.reduce((n, line) => n + line.qty, 0) !== declared.steady.units
+    )) return null;
+    return bindings.buildSavedOrderResumeResponse({ resumable, clientId, checkoutKind, intent });
+  } catch {
+    // Lookup is an optimization; regular quote/admission remains authoritative.
+    return null;
+  }
+}
+
+function lineKey(lines: ReadonlyArray<{ sku: string; quantity: number }>): string {
+  const totals = new Map<string, number>();
+  for (const line of lines) totals.set(line.sku, (totals.get(line.sku) ?? 0) + line.quantity);
+  return stableJson([...totals].sort(([a], [b]) => a.localeCompare(b)));
+}
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : null;
+}
+
+
+return { resolveSavedAcquisitionContinuation };
+}

package/src/commerce/server/commerceCheckoutCustomerDefaults.ts

@@ -0,0 +1,24 @@
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { z } from "zod";
+import type { CheckoutKind, CommerceCustomerDefaultsReadPort } from "../contracts/index.js";
+export async function readCheckoutCustomerDefaults<Snapshot>(input: {
+  port: CommerceCustomerDefaultsReadPort<Snapshot> | undefined;
+  clientId: string;
+  checkoutKind: CheckoutKind;
+  recordStage: <T>(operation: () => Promise<T>) => Promise<T>;
+}, schema: z.ZodType<Snapshot>): Promise<Snapshot | null> {
+  const { port, clientId, checkoutKind, recordStage } = input;
+  if (!port) return null;
+  const snapshot = await recordStage(() =>
+    port.getCustomerDefaultsSnapshot({ clientId, checkoutKind }),
+  );
+  return snapshot ? schema.parse(snapshot) : null;
+}
+
+
+export async function readCheckoutCustomerDefaultsOrRespond<Snapshot>(input: Parameters<typeof readCheckoutCustomerDefaults<Snapshot>>[0] & { res: HttpResponse }, schema: z.ZodType<Snapshot>, responder: BffResponder): Promise<{ kind: "read"; snapshot: Snapshot | null } | { kind: "responded" }> {
+  const { res, ...read } = input;
+  try { return { kind: "read", snapshot: await readCheckoutCustomerDefaults(read, schema) }; }
+  catch { responder.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout customer defaults read failed", { details: { feature: "checkout", stage: "customer_defaults" } }); return { kind: "responded" }; }
+}

package/src/commerce/server/commerceCheckoutFailureHandler.ts

@@ -0,0 +1,144 @@
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import type { CheckoutKind, ConfiguratorIntent as NeutralIntent } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import type { PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+import { AcquisitionTermsError } from "../../pricing/index.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+import { tryCompensate, type CheckoutCompensationPort } from "./commerceCheckoutCompensation.js";
+import { checkoutOrchestrationFailureDetails } from "./commerceDiagnostics.js";
+import type { CheckoutTimingOutcome } from "./commerceCheckoutTiming.js";
+import { CheckoutOfferRefusedError } from "./checkoutOfferPolicyPort.js";
+import { isJourneyConsumedCheckoutConflict, isStockUnavailableCheckoutConflict, START_RUNTIME_SIMPLE_CONFLICTS } from "./checkoutConflictClassifiers.js";
+export function createCheckoutFailureHandler<Intent extends NeutralIntent, Provisioned, Request, Snapshot extends CheckoutQuoteSnapshot>(bindings: {
+  responder: BffResponder; logProviderFailure(error: unknown): void;
+  respondQuoteFailure(res: HttpResponse, error: unknown): boolean;
+  previewDiagnosticsEnabled(): boolean;
+  respondToPromotionCodePriceChange(input: { res: HttpResponse; quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>; intent: Intent; provisioned: Provisioned; checkoutKind: CheckoutKind; acceptedQuoteSnapshot: Snapshot | null; expectedQuote?: { totalGross: { amountMinor: number; currency: string }; pricingPolicy?: PricingPolicySnapshot }; resolvePricingPolicy?: (request: Request) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>; recordQuote: <T>(operation: () => Promise<T>) => Promise<T> }): Promise<boolean>;
+}) {
+  const { sendBffError } = bindings.responder;
+
+type CheckoutFailureInput = {
+  error: unknown;
+  compensationPort: CheckoutCompensationPort;
+  intent: Intent;
+  res: HttpResponse;
+  quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+  provisioned: Provisioned;
+  checkoutKind: CheckoutKind;
+  acceptedQuoteSnapshot: Snapshot | null;
+  expectedQuote?: {
+    totalGross: { amountMinor: number; currency: string };
+    pricingPolicy?: PricingPolicySnapshot;
+  };
+  resolvePricingPolicy?: (
+    request: Request,
+  ) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+  recordQuote: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+
+async function respondToCheckoutFailure(
+  input: CheckoutFailureInput,
+): Promise<CheckoutTimingOutcome> {
+  const { error, compensationPort, intent } = input;
+  bindings.logProviderFailure(error);
+
+  // A prepared provider attempt is money-in-flight, even when the PSP request
+  // threw. Its order can carry a reservation and provisional subscription, so
+  // classify the existing client conflict before generic compensation. Payment
+  // control reconciliation, never a browser retry, determines its outcome.
+  for (const conflict of START_RUNTIME_SIMPLE_CONFLICTS) {
+    if (conflict.match(error)) {
+      sendBffError(input.res, "CONFLICT", conflict.message, {
+        details: { feature: "checkout", stage: "start_runtime", reason: conflict.reason },
+      });
+      return "rejected";
+    }
+  }
+
+  if (error instanceof AcquisitionTermsError && bindings.respondQuoteFailure(input.res, error)) return "rejected";
+
+  // Raised by the quote guard before any order draft exists, so there is nothing
+  // to compensate.
+  if (error instanceof CheckoutOfferRefusedError) {
+    sendBffError(input.res, "CONFLICT", "Checkout offer refused", {
+      details: { feature: "checkout", stage: "quote", reason: error.reason },
+    });
+    return "rejected";
+  }
+
+  if (isStockUnavailableCheckoutConflict(error)) {
+    if (error instanceof CheckoutOrchestrationError && error.orderIdForCompensation) {
+      await tryCompensate(
+        compensationPort,
+        intent.idempotencyKey,
+        error.orderIdForCompensation,
+        { cancellationReason: "checkout_stock_unavailable" },
+      );
+    }
+    sendBffError(input.res, "CONFLICT", "Stock unavailable", {
+      details: { feature: "checkout", stage: "start_runtime", reason: "stock_unavailable" },
+    });
+    return "rejected";
+  }
+  if (isJourneyConsumedCheckoutConflict(error)) {
+    // The journey key already finalized an order (completed out-of-band, e.g.
+    // via a recovery link); this submit minted a fresh draft that can never
+    // finalize under that key. Cancel the abandoned draft and tell the client
+    // to rotate its journey key — retrying unrotated can never succeed.
+    if (error instanceof CheckoutOrchestrationError && error.orderIdForCompensation) {
+      await tryCompensate(
+        compensationPort,
+        intent.idempotencyKey,
+        error.orderIdForCompensation,
+        { cancellationReason: "checkout_journey_consumed" },
+      );
+    }
+    sendBffError(input.res, "CONFLICT", "Checkout journey already completed", {
+      details: { feature: "checkout", stage: "start_runtime", reason: "journey_consumed" },
+    });
+    return "rejected";
+  }
+  if (error instanceof CheckoutOrchestrationError && error.reason === "inventory_admission_busy") {
+    sendBffError(input.res, "UPSTREAM_UNAVAILABLE", "Inventory admission temporarily unavailable", {
+      details: { feature: "checkout", stage: "start_runtime", reason: "inventory_admission_busy" },
+    });
+    return "error";
+  }
+  if (error instanceof CheckoutOrchestrationError && error.orderIdForCompensation) {
+    await tryCompensate(compensationPort, intent.idempotencyKey, error.orderIdForCompensation);
+  }
+  if (
+    error instanceof CheckoutOrchestrationError &&
+    (error.reason === "promotion_code_price_changed" || error.reason === "acquisition_terms_changed")
+  ) {
+    const responded = await bindings.respondToPromotionCodePriceChange({
+      res: input.res,
+      quotePort: input.quotePort,
+      intent,
+      provisioned: input.provisioned,
+      checkoutKind: input.checkoutKind,
+      acceptedQuoteSnapshot: input.acceptedQuoteSnapshot,
+      expectedQuote: input.expectedQuote,
+      resolvePricingPolicy: input.resolvePricingPolicy,
+      recordQuote: input.recordQuote,
+    });
+    return responded ? "rejected" : "error";
+  }
+  const cause = safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error));
+  const orderId = error instanceof CheckoutOrchestrationError ? error.orderIdForCompensation : null;
+  console.error(
+    "checkout_orchestration_failed",
+    JSON.stringify({ message: cause, orderIdForCompensation: orderId }),
+  );
+  sendBffError(input.res, "UPSTREAM_UNAVAILABLE", "Checkout failed", {
+    details: checkoutOrchestrationFailureDetails(cause, bindings.previewDiagnosticsEnabled()),
+  });
+  return "error";
+}
+
+return { respondToCheckoutFailure };
+}

package/src/commerce/server/commerceCheckoutHandler.ts

@@ -0,0 +1,269 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { ConfiguratorIntent, CheckoutKind, CommerceResumableOrderReadPort } from "../contracts/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import type { CheckoutContinuationAction } from "./checkoutPaymentContinuationCredential.js";
+import { providerPayerFromRequest } from "./commerceCheckoutProviderPayment.js";
+import { runBestEffortAccountLink } from "./commerceCheckoutHandlerHelpers.js";
+import type { ResolveSavedMethodResult } from "./commerceCheckoutSavedPaymentMethod.js";
+import type { CheckoutTimingOutcome, CheckoutTimingStage } from "./commerceCheckoutTiming.js";
+import type { CheckoutQuoteSnapshot, ExpectedCheckoutQuote } from "./checkoutQuoteTypes.js";
+import type { OrchestratedCheckoutResult, CheckoutStageRecorder } from "./commercePaidOrderOrchestration.js";
+import type { CheckoutExecutionProvider } from "./checkoutRuntimeTypes.js";
+import type { CheckoutResumeGuardDeps } from "./commerceCheckoutResumeGuard.js";
+interface CheckoutHandlerDependencies {
+  persistencePort: unknown; quotePort: unknown; orderDraftPort: unknown; runtimePort: unknown; compensationPort: unknown;
+  savedPaymentMethodResolverPort?: unknown; customerDefaultsPort?: unknown;
+  resumableOrderPort?: CommerceResumableOrderReadPort; resumeWindowMinutes?: number;
+  linkCustomerAccount?: (email: string) => Promise<void>;
+  verifyPromotionAcceptance?: unknown; promotionAcceptanceEnforced?: boolean;
+  now?: () => Date; resolvePricingPolicy?: unknown; resolvePricingEligibilityClientId?: (email: string) => Promise<string | null>;
+  starterPackEnabled?: () => boolean; isFirstOrderEligible?: (clientId: string | null) => Promise<boolean>;
+  offerPolicy?: unknown; starterTermsPort?: unknown;
+  mintPaymentContinuationCookie?: unknown;
+}
+type RecordOperation = <T>(operation: () => Promise<T>) => Promise<T>;
+interface CheckoutHandlerData<Intent> {
+  intent: Intent; paymentProvider: CheckoutExecutionProvider; paymentAttemptSequence?: number;
+  returnContext: "public" | "account"; paymentExecution?: unknown; declaredBankId?: string;
+  invoicePreference: unknown; expectedQuote?: ExpectedCheckoutQuote & { promotionAcceptanceToken?: string };
+}
+export function createCommerceCheckoutHandler<Deps extends CheckoutHandlerDependencies, Intent extends ConfiguratorIntent, Provisioned extends { clientId: string }, Data extends CheckoutHandlerData<Intent>, Snapshot extends CheckoutQuoteSnapshot, Defaults, Result extends OrchestratedCheckoutResult<Snapshot>, Response extends { status: string; clientAction?: CheckoutContinuationAction }, MethodKind extends string = string, RecurringModel extends string = string>(bindings: {
+  responder: BffResponder;
+  mintPaymentContinuationOnFreshAction(input: { mint?: Deps["mintPaymentContinuationCookie"]; res: HttpResponse; journeyId: string; clientId: string; requestRail: string; response: Response; result: Result }): void;
+  mintCheckoutRefusalContinuation(input: { mint?: Deps["mintPaymentContinuationCookie"]; res: HttpResponse; journeyId: string; clientId: string; requestRail: string; response: Response; result: Result }): void;
+  createCheckoutTimingLogger(req: HttpRequest): { record: <T>(stage: CheckoutTimingStage, operation: () => Promise<T>) => Promise<T>; log(stage: CheckoutTimingStage, outcome: CheckoutTimingOutcome): void };
+  previewCheckoutDiagnosticsEnabled(): boolean;
+  admitCheckoutRequest(input: { req: HttpRequest; res: HttpResponse; deps: Deps; record: <T>(stage: "rate_limit" | "risk_blocklist", operation: () => Promise<T>) => Promise<T> }): Promise<{ kind: "accepted"; data: Data; intent: Intent; checkoutKind: CheckoutKind } | { kind: "responded"; outcome: "rejected" | "error" }>;
+  persistCheckoutIdentityOrRespond(input: { res: HttpResponse; persistencePort: Deps["persistencePort"]; resumeGuardDeps: CheckoutResumeGuardDeps; intent: Intent; checkoutKind: CheckoutKind; now: () => Date; previewDiagnosticsEnabled: boolean; recordPersistStage: RecordOperation }): Promise<{ kind: "provisioned"; provisioned: Provisioned } | { kind: "responded"; outcome: "error" | "rejected" }>;
+  resolveSavedPaymentMethodForCheckout(input: { req: HttpRequest; paymentExecution: Data["paymentExecution"]; clientId: string; savedPaymentMethodResolverPort: Deps["savedPaymentMethodResolverPort"]; now: () => Date; recordStage: <T>(stage: "payment_method_ref", operation: () => Promise<T>) => Promise<T> }): Promise<ResolveSavedMethodResult<MethodKind, RecurringModel>>;
+  respondToSavedPaymentMethodRejection(res: HttpResponse, reason: Extract<ResolveSavedMethodResult, { kind: "rejected" }>["reason"]): void;
+  readCheckoutCustomerDefaultsOrRespond(input: { res: HttpResponse; port: Deps["customerDefaultsPort"]; clientId: string; checkoutKind: CheckoutKind; recordStage: RecordOperation }): Promise<{ kind: "read"; snapshot: Defaults | null } | { kind: "responded" }>;
+  resolveCheckoutQuoteOrContinuation(input: { quotePort: Deps["quotePort"]; intent: Intent; provisioned: Provisioned; deps: CheckoutResumeGuardDeps; invoicePreference: Data["invoicePreference"]; now: () => Date; offerPolicy: Deps["offerPolicy"]; starterTermsPort: Deps["starterTermsPort"]; checkoutKind: CheckoutKind; expectedQuote: Data["expectedQuote"]; promotionAcceptanceToken?: string; verifyPromotionAcceptance: Deps["verifyPromotionAcceptance"]; recordQuoteStage: RecordOperation; resolvePricingPolicy: Deps["resolvePricingPolicy"]; pricingEligibilityClientId?: string | null; starterPackEnabled?: () => boolean; isFirstOrderEligible?: () => Promise<boolean> }): Promise<{ kind: "accepted"; quoteSnapshot: Snapshot } | { kind: "price_changed"; response: Response; starterOfferRejection?: string } | { kind: "resumed"; response: Response }>;
+  resolveResumeOpenOrderResponse(input: { deps: CheckoutResumeGuardDeps; clientId: string; checkoutKind: CheckoutKind; intent: Intent; acceptedQuote: Snapshot["quote"]; now: () => Date }): Promise<Response | null>;
+  orchestratePaidOrder(input: { intent: Intent; provisioned: Provisioned; checkoutKind: CheckoutKind; quotePort: Deps["quotePort"]; orderDraftPort: Deps["orderDraftPort"]; runtimePort: Deps["runtimePort"]; customerDefaultsSnapshot: Defaults | null; paymentProvider: Data["paymentProvider"]; paymentAttemptSequence: Data["paymentAttemptSequence"]; returnContext: Data["returnContext"]; paymentExecution: Data["paymentExecution"]; declaredBankId: Data["declaredBankId"]; paymentMethodRef?: string; paymentMethodAliasType?: MethodKind; paymentMethodRecurringModel?: RecurringModel; invoicePreference: Data["invoicePreference"]; quoteSnapshot: Snapshot; providerPayer: ReturnType<typeof providerPayerFromRequest>; onPaymentStarted?: (event: { email: string }) => Promise<void>; recordStage: CheckoutStageRecorder; now: () => Date }): Promise<Result>;
+  buildCheckoutSuccessResponse(input: { orchestrated: Result; paymentProvider: Data["paymentProvider"]; checkoutKind: CheckoutKind; intent: Intent; clientId: string }): Response;
+  respondToCheckoutFailure(input: { error: unknown; compensationPort: Deps["compensationPort"]; intent: Intent; res: HttpResponse; quotePort: Deps["quotePort"]; provisioned: Provisioned; checkoutKind: CheckoutKind; acceptedQuoteSnapshot: Snapshot | null; expectedQuote: Data["expectedQuote"]; resolvePricingPolicy: Deps["resolvePricingPolicy"]; recordQuote: RecordOperation }): Promise<CheckoutTimingOutcome>;
+}) {
+  const { sendBffError, sendBffSuccess } = bindings.responder;
+function createHandler(deps: Deps) {
+const {
+  persistencePort,
+  quotePort,
+  orderDraftPort,
+  runtimePort,
+  compensationPort,
+  savedPaymentMethodResolverPort,
+  customerDefaultsPort,
+  resumableOrderPort,
+  resumeWindowMinutes,
+  linkCustomerAccount,
+  verifyPromotionAcceptance,
+  promotionAcceptanceEnforced = false,
+  now = () => new Date(),
+  resolvePricingPolicy,
+  resolvePricingEligibilityClientId,
+  starterPackEnabled,
+  offerPolicy,
+  starterTermsPort,
+  isFirstOrderEligible,
+  mintPaymentContinuationCookie,
+} = deps;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    const timing = bindings.createCheckoutTimingLogger(req);
+    let totalOutcome: CheckoutTimingOutcome = "error";
+    try {
+      const admission = await bindings.admitCheckoutRequest({
+        req,
+        res,
+        deps,
+        record: timing.record,
+      });
+      if (admission.kind === "responded") {
+        totalOutcome = admission.outcome;
+        return;
+      }
+      const { data, intent, checkoutKind } = admission;
+
+      let pricingEligibilityClientId: string | null | undefined;
+      if (resolvePricingEligibilityClientId) {
+        try {
+          pricingEligibilityClientId = await resolvePricingEligibilityClientId(intent.contact.email);
+        } catch {
+          sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout customer eligibility read failed", {
+            details: { feature: "checkout", stage: "customer_eligibility" },
+          });
+          return;
+        }
+      }
+
+      const identity = await bindings.persistCheckoutIdentityOrRespond({
+        res,
+        persistencePort,
+        resumeGuardDeps: { resumableOrderPort, resumeWindowMinutes },
+        intent,
+        checkoutKind,
+        now,
+        previewDiagnosticsEnabled: bindings.previewCheckoutDiagnosticsEnabled(),
+        recordPersistStage: (operation) => timing.record("persist_intent", operation),
+      });
+      if (identity.kind === "responded") {
+        totalOutcome = identity.outcome;
+        return;
+      }
+      const provisioned = identity.provisioned;
+
+      let paymentMethodRef: string | undefined;
+      let paymentMethodAliasType: MethodKind | undefined;
+      let paymentMethodRecurringModel: RecurringModel | undefined;
+      const savedMethodResult = await bindings.resolveSavedPaymentMethodForCheckout({
+        req,
+        paymentExecution: data.paymentExecution,
+        clientId: provisioned.clientId,
+        savedPaymentMethodResolverPort,
+        now,
+        recordStage: timing.record,
+      });
+      if (savedMethodResult.kind === "rejected") {
+        bindings.respondToSavedPaymentMethodRejection(res, savedMethodResult.reason);
+        totalOutcome = "rejected";
+        return;
+      }
+      if (savedMethodResult.kind === "resolved") {
+        paymentMethodRef = savedMethodResult.paymentMethodRef;
+        paymentMethodAliasType = savedMethodResult.paymentMethodAliasType;
+        paymentMethodRecurringModel = savedMethodResult.paymentMethodRecurringModel;
+      }
+
+      const defaults = await bindings.readCheckoutCustomerDefaultsOrRespond({ res, port: customerDefaultsPort, clientId: provisioned.clientId, checkoutKind, recordStage: (operation) => timing.record("customer_defaults", operation) });
+      if (defaults.kind === "responded") return;
+      const customerDefaultsSnapshot = defaults.snapshot;
+
+      let acceptedQuoteSnapshot: Snapshot | null = null;
+      try {
+        const quoteGuard = await bindings.resolveCheckoutQuoteOrContinuation({
+          quotePort,
+          intent,
+          provisioned,
+          deps: { resumableOrderPort, resumeWindowMinutes },
+          invoicePreference: data.invoicePreference,
+          now,
+          offerPolicy,
+          starterTermsPort,
+          checkoutKind,
+          expectedQuote: data.expectedQuote,
+          promotionAcceptanceToken: data.expectedQuote?.promotionAcceptanceToken,
+          verifyPromotionAcceptance,
+          recordQuoteStage: (operation) => timing.record("quote", operation),
+          resolvePricingPolicy,
+          pricingEligibilityClientId,
+          starterPackEnabled,
+          ...(isFirstOrderEligible
+            ? {
+                isFirstOrderEligible: () => isFirstOrderEligible(
+                  pricingEligibilityClientId ?? provisioned.clientId,
+                ),
+              }
+            : {}),
+        });
+        if (quoteGuard.kind === "resumed") {
+          sendBffSuccess(res, quoteGuard.response, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+          totalOutcome = "success";
+          return;
+        }
+        if (quoteGuard.kind === "price_changed") {
+          if (quoteGuard.starterOfferRejection) {
+            console.info(
+              "checkout_starter_offer_rejected",
+              JSON.stringify({ reason: quoteGuard.starterOfferRejection }),
+            );
+          }
+          sendBffSuccess(res, quoteGuard.response, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+          totalOutcome = "rejected";
+          return;
+        }
+        acceptedQuoteSnapshot = quoteGuard.quoteSnapshot;
+
+        // Deliberately AFTER the quote. The duplicate-charge guard has to answer
+        // "may I re-offer this order" against the money the buyer was just
+        // shown, and before this it could only answer against the order alone —
+        // which is how a changed cart got re-offered at its old total.
+        const resumeResponse = await bindings.resolveResumeOpenOrderResponse({
+          deps: { resumableOrderPort, resumeWindowMinutes },
+          clientId: provisioned.clientId,
+          checkoutKind,
+          intent,
+          acceptedQuote: quoteGuard.quoteSnapshot.quote,
+          now,
+        });
+        if (resumeResponse) {
+          sendBffSuccess(res, resumeResponse, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+          totalOutcome = "success";
+          return;
+        }
+
+        const orchestrated = await bindings.orchestratePaidOrder({
+          intent,
+          provisioned,
+          checkoutKind,
+          quotePort,
+          orderDraftPort,
+          runtimePort,
+          customerDefaultsSnapshot,
+          paymentProvider: data.paymentProvider,
+          paymentAttemptSequence: data.paymentAttemptSequence,
+          returnContext: data.returnContext,
+          paymentExecution: data.paymentExecution,
+          declaredBankId: data.declaredBankId,
+          paymentMethodRef, paymentMethodAliasType, paymentMethodRecurringModel,
+          invoicePreference: data.invoicePreference,
+          quoteSnapshot: quoteGuard.quoteSnapshot,
+          providerPayer: providerPayerFromRequest(req, intent),
+          onPaymentStarted: linkCustomerAccount
+            ? async ({ email }) => {
+                await runBestEffortAccountLink(linkCustomerAccount, email);
+              }
+            : undefined,
+          recordStage: timing.record,
+          now,
+        });
+        const response = bindings.buildCheckoutSuccessResponse({
+          orchestrated,
+          paymentProvider: data.paymentProvider,
+          checkoutKind,
+          intent,
+          clientId: provisioned.clientId,
+        });
+        const continuationInput = {
+          mint: mintPaymentContinuationCookie,
+          res, journeyId: intent.idempotencyKey, clientId: provisioned.clientId,
+          requestRail: data.paymentProvider, response, result: orchestrated,
+        };
+        bindings.mintPaymentContinuationOnFreshAction(continuationInput);
+        bindings.mintCheckoutRefusalContinuation(continuationInput);
+        sendBffSuccess(res, response, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+        totalOutcome = "success";
+      } catch (error) {
+        totalOutcome = await bindings.respondToCheckoutFailure({
+          error,
+          compensationPort,
+          intent,
+          res,
+          quotePort,
+          provisioned,
+          checkoutKind,
+          acceptedQuoteSnapshot,
+          expectedQuote: data.expectedQuote,
+          resolvePricingPolicy,
+          recordQuote: (operation) => timing.record("quote", operation),
+        });
+        return;
+      }
+    } finally {
+      timing.log("total", totalOutcome);
+    }
+  };
+}
+
+return createHandler;
+}