@openlup/platform 0.25.0 → 0.27.0

package/src/commerce/server/commerceCheckoutQuoteGuard.ts

@@ -0,0 +1,172 @@
+import type { z } from "zod";
+import { acquisitionExpectationChanged, projectPublicQuoteSnapshot, type PricingPolicySnapshot, type ResolvedAcquisitionTerms } from "../../pricing/index.js";
+import { hasShippingTerms } from "../../shipping/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 { resolveCheckoutOffer, withCheckoutOfferContext, type CheckoutOfferPolicyPort } from "./checkoutOfferPolicyPort.js";
+import type { CheckoutQuoteSnapshot, ExpectedCheckoutQuote } from "./checkoutQuoteTypes.js";
+import type { StarterOfferGuardResult } from "./commerceStarterOfferGuard.js";
+export type CheckoutQuoteGuardResult<Snapshot, Response> = { kind: "accepted"; quoteSnapshot: Snapshot } | { kind: "price_changed"; response: Response; starterOfferRejection?: string };
+export function createCheckoutQuoteGuard<Intent extends NeutralIntent, Provisioned extends { clientId: string }, Request, Snapshot extends CheckoutQuoteSnapshot, Response, Terms, Plan>(bindings: {
+  buildQuoteRequest(intent: Intent, provisioned: Provisioned, policy?: PricingPolicySnapshot): Request;
+  responseSchema: z.ZodType<Response>;
+  resolveStarterOfferGuard(input: { flagEnabled: boolean; intent: Intent; provisioned: Provisioned; authoritativeQuote: Snapshot; quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>; isFirstOrderEligible?: () => Promise<boolean>; termsPort?: Terms; offerVersion?: string }): Promise<StarterOfferGuardResult<Plan>>;
+  withStarterPackContext(snapshot: Snapshot, plan: Plan | null): Snapshot;
+}) {
+  type ConfiguratorIntent = Intent;
+  type ConfiguratorIntentPersistenceResponse = Provisioned;
+  type CreateQuoteResponse = Snapshot;
+  type ExpectedQuoteTotal = ExpectedCheckoutQuote;
+async function resolveCheckoutQuoteGuard(input: {
+  quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+  intent: ConfiguratorIntent;
+  provisioned: ConfiguratorIntentPersistenceResponse;
+  checkoutKind: CheckoutKind;
+  expectedQuote?: ExpectedQuoteTotal;
+  recordQuoteStage: <T>(operation: () => Promise<T>) => Promise<T>;
+  resolvePricingPolicy?: (
+    request: Request,
+  ) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+    pricingEligibilityClientId?: string | null;
+  verifyPromotionAcceptance?: (input: {
+    token: string;
+    request: Request;
+    quote: CreateQuoteResponse["quote"];
+    expectedTotal: ExpectedQuoteTotal["totalGross"];
+  }) => boolean;
+  promotionAcceptanceToken?: string;
+    offerPolicy?: CheckoutOfferPolicyPort<Intent, Snapshot["quote"]>;
+    starterPackEnabled?: () => boolean;
+  isFirstOrderEligible?: () => Promise<boolean>;
+    starterTermsPort?: Terms;
+}): Promise<CheckoutQuoteGuardResult<Snapshot, Response>> {
+  const { quotePort, intent, provisioned, checkoutKind, expectedQuote, recordQuoteStage } = input;
+  const offer = await resolveCheckoutOffer(input.offerPolicy, intent, checkoutKind);
+  const quoteRequest = bindings.buildQuoteRequest(intent, provisioned, expectedQuote?.pricingPolicy);
+  const pricingPolicy = await input.resolvePricingPolicy?.(quoteRequest);
+  const pricingClientId = input.pricingEligibilityClientId ?? provisioned.clientId;
+  const authoritativeQuote = await recordQuoteStage(() =>
+    quotePort.createServerAuthoritativeQuote
+      ? quotePort.createServerAuthoritativeQuote(quoteRequest, {
+        clientId: pricingClientId,
+        ...(pricingPolicy ? { pricingPolicy } : {}),
+        ...(offer ? { offerVersion: offer.offerVersion } : {}),
+      })
+      : quotePort.createQuote(quoteRequest, {
+        clientId: pricingClientId,
+        ...(pricingPolicy ? { pricingPolicy } : {}),
+        ...(offer ? { offerVersion: offer.offerVersion } : {}),
+      }),
+  );
+  console.info(
+    "checkout_promo_eligibility_context",
+    JSON.stringify({ promoEligibilityContext: "resolved_client" }),
+  );
+  const hasCurrentV2Promotion = authoritativeQuote.quote.discounts.some((discount) =>
+    discount.promotionEngineVersion === "promotion-engine.v2");
+  const requiresPromotionAcceptance = Boolean(input.promotionAcceptanceToken) || hasCurrentV2Promotion
+    || hasShippingTerms(authoritativeQuote.quote)
+    || authoritativeQuote.quote.context?.acquisitionTerms !== undefined;
+  const promotionAcceptanceValid = !requiresPromotionAcceptance || Boolean(
+    expectedQuote && input.promotionAcceptanceToken && input.verifyPromotionAcceptance?.({
+      token: input.promotionAcceptanceToken,
+      request: quoteRequest,
+      quote: authoritativeQuote.quote,
+      expectedTotal: expectedQuote.totalGross,
+    }),
+  );
+  const priceAccepted = promotionAcceptanceValid
+    && (!expectedQuote || !quoteTotalChanged(expectedQuote, authoritativeQuote));
+  // The starter guard runs only once the price itself is accepted: a moved total
+  // is already a rejection, and re-quoting a steady package for a basket that is
+  // about to be refused would be pure waste.
+  const starter: StarterOfferGuardResult<Plan> = priceAccepted
+    ? await bindings.resolveStarterOfferGuard({
+      flagEnabled: input.starterPackEnabled?.() ?? false,
+      intent,
+      provisioned,
+      authoritativeQuote,
+      quotePort,
+      isFirstOrderEligible: input.isFirstOrderEligible,
+      termsPort: input.starterTermsPort,
+      offerVersion: offer?.offerVersion,
+    })
+    : { kind: "absent" };
+  if (priceAccepted && starter.kind !== "rejected") {
+    const persisted = withoutPricingPolicyToken(authoritativeQuote);
+    return {
+      kind: "accepted",
+      quoteSnapshot: await withCheckoutOfferContext(offer, intent, bindings.withStarterPackContext(
+        persisted,
+        starter.kind === "minted" ? starter.plan : null,
+      )),
+    };
+  }
+  return {
+    kind: "price_changed",
+    ...(starter.kind === "rejected" ? { starterOfferRejection: starter.reason } : {}),
+    response: buildCheckoutPriceChangedResponse({
+      checkoutKind,
+      expectedQuote: expectedQuote ?? { totalGross: authoritativeQuote.quote.totalGross },
+      authoritativeQuote,
+    }),
+  };
+}
+
+function withoutPricingPolicyToken(snapshot: CreateQuoteResponse): CreateQuoteResponse {
+  const policy = snapshot.quote.context?.pricingPolicy;
+  if (!policy?.pricingPolicyToken) return snapshot;
+  const { pricingPolicyToken: _token, ...persistedPolicy } = policy;
+  return {
+    ...snapshot,
+    quote: {
+      ...snapshot.quote,
+      context: { ...snapshot.quote.context!, pricingPolicy: persistedPolicy },
+    },
+  };
+}
+
+function buildCheckoutPriceChangedResponse(input: {
+  checkoutKind: CheckoutKind;
+  expectedQuote: ExpectedQuoteTotal;
+  authoritativeQuote: CreateQuoteResponse;
+}): Response {
+  return bindings.responseSchema.parse({
+    contractVersion: CHECKOUT_CONTRACT_VERSION,
+    checkoutKind: input.checkoutKind,
+    status: "price_changed",
+    priceChanged: true,
+    expectedQuote: { totalGross: input.expectedQuote.totalGross },
+    authoritativeQuote: projectPublicQuoteSnapshot(input.authoritativeQuote),
+  });
+}
+
+function quoteTotalChanged(
+  expectedQuote: ExpectedQuoteTotal | undefined,
+  authoritativeQuote: {
+    quote: {
+      totalGross: { amountMinor: number; currency: string };
+      context?: { pricingPolicy?: PricingPolicySnapshot; acquisitionTerms?: ResolvedAcquisitionTerms };
+    };
+  },
+): boolean {
+  if (!expectedQuote) return false;
+  const actualPolicy = authoritativeQuote.quote.context?.pricingPolicy;
+  const expectedPolicy = expectedQuote.pricingPolicy;
+  const historicalUnboundV1 = expectedPolicy?.offerPolicyVersion === "commerce.offer-policy.v1"
+    && expectedPolicy.promotionEngineVersion === "promotion-engine.v1"
+    && !expectedPolicy.pricingPolicyToken;
+  return (
+    acquisitionExpectationChanged(expectedQuote.acquisitionTerms, authoritativeQuote.quote.context?.acquisitionTerms) ||
+    expectedQuote.totalGross.amountMinor !== authoritativeQuote.quote.totalGross.amountMinor ||
+    expectedQuote.totalGross.currency !== authoritativeQuote.quote.totalGross.currency ||
+    (expectedPolicy != null && !historicalUnboundV1 && (
+      expectedPolicy.offerPolicyVersion !== actualPolicy?.offerPolicyVersion ||
+      expectedPolicy.promotionEngineVersion !== actualPolicy?.promotionEngineVersion
+    ))
+  );
+}
+
+return { resolveCheckoutQuoteGuard, buildCheckoutPriceChangedResponse };
+}

package/src/commerce/server/commerceCheckoutResume.ts

@@ -0,0 +1,132 @@
+import type { z } from "zod";
+import { CHECKOUT_RESUME_CONTRACT_VERSION } from "../checkoutResumeSchemas.js";
+import { CommerceCheckoutResumePersistenceError } from "../errors.js";
+import type { CommerceCheckoutResumeDraftPort, CommerceCheckoutResumeDraftUpsertInput, CommerceCheckoutResumeDraftReadInput } from "../contracts/ports.js";
+interface ResumeResult { data: unknown; error: { code?: string; message?: string; details?: string } | null }
+interface ResumeQuery {
+  select(columns: string): ResumeQuery;
+  eq(column: string, value: unknown): ResumeQuery;
+  is(column: string, value: null): ResumeQuery;
+  gt(column: string, value: string): ResumeQuery;
+  single(): PromiseLike<ResumeResult>;
+  maybeSingle(): PromiseLike<ResumeResult>;
+}
+export interface CommerceCheckoutResumeClient {
+  from(table: "commerce_checkout_resume_drafts"): {
+    select(columns: string): ResumeQuery;
+    update(payload: Record<string, unknown>): ResumeQuery;
+    insert(payload: Record<string, unknown>): ResumeQuery;
+  };
+}
+
+interface CheckoutResumeRow<Section, State> {
+  id: string;
+  last_section_id: Section;
+  draft_state: State;
+  expires_at: string;
+  created_at: string;
+  updated_at: string;
+}
+
+const SELECT_COLUMNS =
+  "id, last_section_id, draft_state, expires_at, created_at, updated_at";
+
+export function createCommerceCheckoutResumeQueryPort<Section, State extends { redactedFields: unknown }, Draft>(
+  client: CommerceCheckoutResumeClient,
+  draftSchema: z.ZodType<Draft>,
+): CommerceCheckoutResumeDraftPort<Section, State, Draft> {
+  return {
+    async upsertDraft(input: CommerceCheckoutResumeDraftUpsertInput<Section, State>) {
+      const payload = {
+        token_hash: input.tokenHash,
+        idempotency_key_hash: input.idempotencyKeyHash,
+        last_section_id: input.lastSectionId,
+        draft_state: input.draftState,
+        redacted_fields: input.draftState.redactedFields,
+        expires_at: input.expiresAt,
+        revoked_at: null,
+        updated_at: input.now,
+      };
+
+      const { data: existing, error: existingError } = await client
+        .from("commerce_checkout_resume_drafts")
+        .select("id, expires_at, revoked_at")
+        .eq("token_hash", input.tokenHash)
+        .maybeSingle();
+      if (existingError) throw mapError(existingError);
+
+      if (existing && !isActiveResumeRow(existing as { expires_at?: string | null; revoked_at?: string | null }, input.now)) {
+        throw new CommerceCheckoutResumePersistenceError(
+          "Checkout resume draft token is expired or revoked",
+          { boundary: "commerce_checkout_resume_drafts", reason: "expired_or_revoked" },
+        );
+      }
+
+      const query = existing
+        ? client
+            .from("commerce_checkout_resume_drafts")
+            .update(payload)
+            .eq("token_hash", input.tokenHash)
+            .is("revoked_at", null)
+            .gt("expires_at", input.now)
+        : client.from("commerce_checkout_resume_drafts").insert(payload);
+
+      const { data, error } = await query.select(SELECT_COLUMNS).single();
+      if (error) throw mapError(error);
+
+      return parseRow(data, false);
+    },
+
+    async readDraftByTokenHash(input: CommerceCheckoutResumeDraftReadInput) {
+      const { data, error } = await client
+        .from("commerce_checkout_resume_drafts")
+        .select(SELECT_COLUMNS)
+        .eq("token_hash", input.tokenHash)
+        .is("revoked_at", null)
+        .gt("expires_at", input.now)
+        .maybeSingle();
+      if (error) throw mapError(error);
+      if (!data) return null;
+
+      return parseRow(data, true);
+    },
+  };
+
+  function isActiveResumeRow(
+    row: { expires_at?: string | null; revoked_at?: string | null },
+    now: string,
+  ): boolean {
+    return !row.revoked_at && !!row.expires_at && row.expires_at > now;
+  }
+
+  function parseRow(row: unknown, replayed: boolean): Draft {
+    const data = row as CheckoutResumeRow<Section, State>;
+    const parsed = draftSchema.safeParse({
+      id: data.id,
+      contractVersion: CHECKOUT_RESUME_CONTRACT_VERSION,
+      lastSectionId: data.last_section_id,
+      draftState: data.draft_state,
+      expiresAt: data.expires_at,
+      createdAt: data.created_at,
+      updatedAt: data.updated_at,
+      replayed,
+    });
+
+    if (!parsed.success) {
+      throw new CommerceCheckoutResumePersistenceError(
+        "Checkout resume draft response invalid",
+        { boundary: "commerce_checkout_resume_drafts" },
+      );
+    }
+
+    return parsed.data;
+  }
+
+}
+
+function mapError(error: { code?: string; message?: string; details?: string }): Error {
+  return new CommerceCheckoutResumePersistenceError("Checkout resume draft persistence failed", {
+    code: error.code,
+    boundary: "commerce_checkout_resume_drafts",
+  });
+}

package/src/commerce/server/commerceCheckoutResumeGuard.ts

@@ -0,0 +1,195 @@
+import type { z } from "zod";
+import type { CheckoutKind, CommerceResumableOrderReadPort, ResumableOrderSnapshot } from "../contracts/index.js";
+import { resolveDeliverySelectionEvidence } from "../../shipping/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+export function subscriptionResponse(intent: { cadenceDays: number | null }, checkoutKind: CheckoutKind) {
+  return checkoutKind === "one_time" ? { requested: false, cadenceDays: null, activationStatus: "not_applicable" as const }
+    : { requested: true, cadenceDays: intent.cadenceDays, activationStatus: "pending_payment_success" as const };
+}
+
+const DEFAULT_RESUME_WINDOW_MINUTES = 60;
+
+export interface CheckoutResumeGuardDeps {
+  resumableOrderPort?: CommerceResumableOrderReadPort;
+    resumeWindowMinutes?: number;
+}
+
+export function selectedDeliveryMatches(
+  orderMetadata: Record<string, unknown> | null | undefined,
+  intent: { selectedDelivery?: unknown },
+): boolean {
+  const existing = resolveDeliverySelectionEvidence({ orderMetadata }).selection;
+  const fresh = resolveDeliverySelectionEvidence({
+    orderMetadata: { selectedDelivery: intent.selectedDelivery },
+  }).selection;
+  if (!existing || !fresh) return false;
+  return deliveryKey(existing) === deliveryKey(fresh);
+}
+
+function deliveryKey(selection: Record<string, unknown>): string {
+  const pickupPoint = selection.pickupPoint && typeof selection.pickupPoint === "object"
+    ? selection.pickupPoint as Record<string, unknown>
+    : {};
+  return [
+    text(selection.providerKind),
+    text(selection.carrierKind),
+    text(selection.carrierCode),
+    text(selection.serviceCode ?? selection.service),
+    text(selection.deliveryKind ?? selection.kind),
+    text(pickupPoint.id ?? pickupPoint.pointId),
+  ].join("|");
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+
+export interface QuoteLikeSnapshot {
+  currency: string;
+  totalGross: { amountMinor: number; currency: string };
+  lines: ReadonlyArray<{ sku: string; quantity: number }>;
+}
+
+function quoteMatches(
+  orderMetadata: Record<string, unknown> | null | undefined,
+  accepted: QuoteLikeSnapshot,
+): boolean {
+  const stored = readStoredQuote(orderMetadata);
+  if (!stored) return false;
+  return stored.currency === accepted.currency
+    && stored.totalGross.currency === accepted.totalGross.currency
+    && stored.totalGross.amountMinor === accepted.totalGross.amountMinor
+    && lineKey(stored.lines) === lineKey(accepted.lines);
+}
+
+function readStoredQuote(
+  orderMetadata: Record<string, unknown> | null | undefined,
+): QuoteLikeSnapshot | null {
+  // The producer stores the whole envelope, so the quote sits one level down.
+  const snapshot = orderMetadata?.quoteSnapshot;
+  const quote = isRecord(snapshot) ? snapshot.quote : undefined;
+  if (!isRecord(quote)) return null;
+  const total = quote.totalGross;
+  const lines = quote.lines;
+  if (typeof quote.currency !== "string" || !isRecord(total) || !Array.isArray(lines)) return null;
+  if (typeof total.amountMinor !== "number" || typeof total.currency !== "string") return null;
+  const parsed: { sku: string; quantity: number }[] = [];
+  for (const line of lines) {
+    if (!isRecord(line) || typeof line.sku !== "string" || typeof line.quantity !== "number") {
+      return null;
+    }
+    parsed.push({ sku: line.sku, quantity: line.quantity });
+  }
+  return {
+    currency: quote.currency,
+    totalGross: { amountMinor: total.amountMinor, currency: total.currency },
+    lines: parsed,
+  };
+}
+
+function lineKey(lines: ReadonlyArray<{ sku: string; quantity: number }>): string {
+  return lines.map((line) => `${line.sku}x${line.quantity}`).sort().join("|");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function createCheckoutResumeGuard<Intent extends { idempotencyKey: string; cadenceDays: number | null; selectedDelivery?: unknown }, Response>(bindings: {
+  responseSchema: z.ZodType<Response>;
+  statusUrl(orderId: string, paymentIntentId: string, clientId: string): string;
+}) {
+function buildSavedOrderResumeResponse(input: {
+  resumable: ResumableOrderSnapshot;
+  clientId: string;
+  checkoutKind: CheckoutKind;
+  intent: Intent;
+}): Response {
+  const { resumable, clientId, checkoutKind, intent } = input;
+  return bindings.responseSchema.parse({
+      contractVersion: CHECKOUT_CONTRACT_VERSION,
+      checkoutKind,
+      orderRef: `order_${resumable.orderId}`,
+      orderId: resumable.orderId,
+      status: resumable.status,
+      paymentIntentId: resumable.paymentIntentId,
+      clientId,
+      clientAction: { kind: "none" },
+      statusUrl: bindings.statusUrl(resumable.orderId, resumable.paymentIntentId, clientId),
+      subscription: subscriptionResponse(intent, checkoutKind),
+      payment: { requiresReusablePaymentMethod: checkoutKind === "subscription_initial" },
+    });
+}
+
+async function resolveResumeOpenOrderResponse(input: {
+  deps: CheckoutResumeGuardDeps;
+  clientId: string;
+  checkoutKind: CheckoutKind;
+  intent: Intent;
+    acceptedQuote?: QuoteLikeSnapshot;
+  now: () => Date;
+}): Promise<Response | null> {
+  const { deps, clientId, checkoutKind, intent, acceptedQuote, now } = input;
+  if (!deps.resumableOrderPort) return null;
+
+  try {
+    const resumable = await deps.resumableOrderPort.findResumableOrderForClient({
+      clientId,
+      withinMinutes: deps.resumeWindowMinutes ?? DEFAULT_RESUME_WINDOW_MINUTES,
+      now: now(),
+      journeyKey: intent.idempotencyKey,
+    });
+    if (!resumable) return null;
+    if (acceptedQuote && resumable.sameJourney) {
+      // The buyer edited their cart; they did not come back on another device.
+      // Answering with this order would re-offer the OLD total. Falling through
+      // hands the case to `commerce_supersede_pre_payment_order_draft`, which
+      // cancels the unpaid order plus its intent, attempt and PROVISIONAL
+      // subscription and re-drafts at the new price — and which refuses outright
+      // once money has moved, at which point this guard legitimately owns it.
+      console.info(
+        "checkout_resume_skipped_same_journey",
+        JSON.stringify({ orderId: resumable.orderId, status: resumable.status }),
+      );
+      return null;
+    }
+    if (!selectedDeliveryMatches(resumable.metadata, intent)) {
+      console.info(
+        "checkout_resume_skipped_delivery_mismatch",
+        JSON.stringify({ orderId: resumable.orderId, status: resumable.status }),
+      );
+      return null;
+    }
+    if (acceptedQuote && !quoteMatches(resumable.metadata, acceptedQuote)) {
+      // Second, independent barrier. A different journey can still hold a
+      // different basket — same buyer, two tabs, two configurations — and money
+      // is what the buyer is about to authorize, so it must be the money they
+      // were just shown.
+      console.info(
+        "checkout_resume_skipped_quote_mismatch",
+        JSON.stringify({ orderId: resumable.orderId, status: resumable.status }),
+      );
+      return null;
+    }
+
+    const response = buildSavedOrderResumeResponse({ resumable, clientId, checkoutKind, intent });
+    console.info(
+      "checkout_resumed_open_order",
+      JSON.stringify({ orderId: resumable.orderId, status: resumable.status }),
+    );
+    return response;
+  } catch (error) {
+    console.warn(
+      "checkout_resume_lookup_failed",
+      JSON.stringify({
+        message: safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error)),
+      }),
+    );
+    return null;
+  }
+}
+
+
+return { resolveResumeOpenOrderResponse, buildSavedOrderResumeResponse };
+}

package/src/commerce/server/commerceCheckoutSavedPaymentMethod.ts

@@ -0,0 +1,85 @@
+import type { HttpRequest } from "../../http/index.js";
+interface CheckoutSavedPaymentMethodResolverPort<Flow extends string, MethodKind extends string = string, RecurringModel extends string = string> {
+  resolveSavedPaymentMethod(input: { accessToken: string; clientId: string; savedMethodId: string; requestedFlow: Flow; now: Date }): Promise<{ providerMethodRef: string; providerAliasType: MethodKind; recurringModel?: RecurringModel } | null>;
+}
+export type ResolveSavedMethodResult<MethodKind extends string = string, RecurringModel extends string = string> =
+  | { kind: "none" }
+  | {
+      kind: "resolved";
+      paymentMethodRef: string;
+      paymentMethodAliasType: MethodKind;
+      paymentMethodRecurringModel?: RecurringModel;
+    }
+  | {
+      kind: "rejected";
+      reason:
+        | "saved_payment_method_resolver_unavailable"
+        | "saved_payment_method_session_required"
+        | "saved_payment_method_unavailable"
+        | "saved_payment_method_read_failed";
+    };
+
+export function createCheckoutSavedPaymentMethodResolver<Execution, Flow extends string, MethodKind extends string = string, RecurringModel extends string = string>(requestForExecution: (execution: Execution | undefined) => { flow: Flow; savedMethodId: string } | null) {
+type ResolveSavedMethodInput = {
+  req: HttpRequest;
+  paymentExecution: Execution | undefined;
+  clientId: string;
+  savedPaymentMethodResolverPort?: CheckoutSavedPaymentMethodResolverPort<Flow, MethodKind, RecurringModel>;
+  now: () => Date;
+  recordStage: <T>(stage: "payment_method_ref", operation: () => Promise<T>) => Promise<T>;
+}
+
+async function resolveSavedPaymentMethodForCheckout({
+  req,
+  paymentExecution,
+  clientId,
+  savedPaymentMethodResolverPort,
+  now,
+  recordStage,
+}: ResolveSavedMethodInput): Promise<ResolveSavedMethodResult<MethodKind, RecurringModel>> {
+  const savedPaymentMethodRequest = requestForExecution(paymentExecution);
+  if (!savedPaymentMethodRequest) return { kind: "none" };
+  if (!savedPaymentMethodResolverPort) {
+    return { kind: "rejected", reason: "saved_payment_method_resolver_unavailable" };
+  }
+
+  const accessToken = readBearerToken(req);
+  if (!accessToken) {
+    return { kind: "rejected", reason: "saved_payment_method_session_required" };
+  }
+
+  try {
+    const resolved = await recordStage("payment_method_ref", () =>
+      savedPaymentMethodResolverPort.resolveSavedPaymentMethod({
+        accessToken,
+        clientId,
+        savedMethodId: savedPaymentMethodRequest.savedMethodId,
+        requestedFlow: savedPaymentMethodRequest.flow,
+        now: now(),
+      }),
+    );
+    if (!resolved) {
+      return { kind: "rejected", reason: "saved_payment_method_unavailable" };
+    }
+    return {
+      kind: "resolved",
+      paymentMethodRef: resolved.providerMethodRef,
+      paymentMethodAliasType: resolved.providerAliasType,
+      ...(resolved.recurringModel
+        ? { paymentMethodRecurringModel: resolved.recurringModel }
+        : {}),
+    };
+  } catch {
+    return { kind: "rejected", reason: "saved_payment_method_read_failed" };
+  }
+}
+
+function readBearerToken(req: HttpRequest): string | null {
+  const raw = req.headers.authorization;
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  const match = value?.match(/^Bearer\s+(.+)$/i);
+  return match?.[1]?.trim() || null;
+}
+
+return { resolveSavedPaymentMethodForCheckout };
+}

package/src/commerce/server/commerceCheckoutStartRuntimeFailure.ts

@@ -0,0 +1,59 @@
+import { CommerceRuntimeConflictError } from "../runtimeErrors.js";
+import { isInventoryAdmissionBusy } from "./checkoutConflictClassifiers.js";
+import { messageOf } from "../checkoutHelpers.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+export function createCheckoutStartRuntimeFailure(bindings: {
+  checkoutProviderAttemptFailure(error: unknown): CheckoutOrchestrationError | null;
+  prepareConflictReason: string;
+}) {
+
+function mapStartRuntimeFailure(
+  error: unknown,
+  draftOrderId: string,
+): CheckoutOrchestrationError {
+  const providerAttemptFailure = bindings.checkoutProviderAttemptFailure(error);
+  if (providerAttemptFailure) {
+    // `executePreparedProviderAttempt` writes the payment-control attempt
+    // before it calls the PSP. Once that dispatch throws, the PSP may still
+    // have accepted the charge. Keep the finalized order, reservation and
+    // provisional subscription intact until reconciliation establishes the
+    // terminal result; a compensating release here could both oversell stock
+    // and permit a second charge for the same journey.
+    return providerAttemptFailure;
+  }
+  if (
+    error instanceof CommerceRuntimeConflictError &&
+    error.details.reason === bindings.prepareConflictReason
+  ) {
+    // D8 refused a changed request before a second PSP call. Keep the existing
+    // prepared attempt and aggregate fenced until reconciliation resolves it.
+    return new CheckoutOrchestrationError(
+      "start_runtime: provider attempt remains in flight",
+      null,
+      "provider_attempt_in_flight",
+    );
+  }
+  if (error instanceof CommerceRuntimeConflictError && error.details.reason === "acquisition_terms_changed") {
+    return new CheckoutOrchestrationError("Acquisition terms changed", draftOrderId, "acquisition_terms_changed");
+  }
+  if (isInventoryAdmissionBusy(error)) {
+    return new CheckoutOrchestrationError("Inventory admission temporarily unavailable", null, "inventory_admission_busy");
+  }
+  if (
+    error instanceof CommerceRuntimeConflictError &&
+    error.details.reason === "journey_consumed"
+  ) {
+    // The journey key already finalized an order; the fresh draft minted for
+    // this submit is abandoned and needs compensation, and the client must
+    // rotate its key before retrying.
+    return new CheckoutOrchestrationError(
+      messageOf(error, "start_runtime"),
+      draftOrderId,
+      "journey_consumed",
+    );
+  }
+  return new CheckoutOrchestrationError(messageOf(error, "start_runtime"), draftOrderId);
+}
+
+return { mapStartRuntimeFailure };
+}