@openlup/platform 0.25.0 → 0.27.0

package/src/commerce/server/checkoutOfferPolicyPort.ts

@@ -0,0 +1,60 @@
+import type { CheckoutKind, CheckoutOfferPolicyPort } from "../contracts/index.js";
+import { commerceOfferEvidenceSchema } from "../offerEvidenceSchemas.js";
+export type { CheckoutOfferPolicyPort } from "../contracts/index.js";
+/** The refusal of an intent that carries an offer field when no adopter port is wired. */
+export const CHECKOUT_OFFER_VERSION_UNSUPPORTED = "offer_version_unsupported";
+
+export class CheckoutOfferRefusedError extends Error {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(`checkout_offer_refused:${reason}`);
+    this.name = "CheckoutOfferRefusedError";
+    this.reason = reason;
+  }
+}
+
+export type CheckoutOfferBinding<Intent, Quote> = { port: CheckoutOfferPolicyPort<Intent, Quote>; offerVersion: string };
+
+/**
+ * Null, without a port call, for an intent that carries neither `offerVersion`
+ * nor `minimumUnits`. Otherwise the adopter's port must bind the offer: without
+ * a port the intent is refused with `offer_version_unsupported`, and a port
+ * refusal keeps its own reason. Both throw `CheckoutOfferRefusedError`.
+ */
+export async function resolveCheckoutOffer<Intent extends { offerVersion?: string; minimumUnits?: number }, Quote>(
+  port: CheckoutOfferPolicyPort<Intent, Quote> | undefined,
+  intent: Intent,
+  checkoutKind: CheckoutKind,
+): Promise<CheckoutOfferBinding<Intent, Quote> | null> {
+  if (intent.offerVersion === undefined && intent.minimumUnits === undefined) return null;
+  if (!port) throw new CheckoutOfferRefusedError(CHECKOUT_OFFER_VERSION_UNSUPPORTED);
+  const resolution = await port.resolve({ intent, checkoutKind });
+  if (resolution.kind === "refused") throw new CheckoutOfferRefusedError(resolution.reason);
+  return { port, offerVersion: resolution.offerVersion };
+}
+
+/**
+ * Writes a bound offer version and the adopter's evidence, checked against
+ * `commerceOfferEvidenceSchema`, into an accepted snapshot's context. Without a
+ * binding the same snapshot is returned; a bound snapshot without a context
+ * fails closed.
+ */
+export async function withCheckoutOfferContext<Intent, Quote extends { context?: object }, Response extends { quote: Quote }>(
+  binding: CheckoutOfferBinding<Intent, Quote> | null,
+  intent: Intent,
+  snapshot: Response,
+): Promise<Response> {
+  if (!binding) return snapshot;
+  const context = snapshot.quote.context;
+  if (!context) throw new Error("checkout_offer_context_missing");
+  const offerEvidence = commerceOfferEvidenceSchema.parse(await binding.port.evidence({
+    intent,
+    offerVersion: binding.offerVersion,
+    quote: snapshot.quote,
+  }));
+  return {
+    ...snapshot,
+    quote: { ...snapshot.quote, context: { ...context, offerVersion: binding.offerVersion, offerEvidence } },
+  };
+}

package/src/commerce/server/checkoutPaymentContinuationCredential.ts

@@ -0,0 +1,222 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS } from "../paymentContinuation.js";
+export type CheckoutContinuationAction = { kind: string; provider?: string; clientSecret?: string; url?: string };
+
+const PURPOSE = "commerce.checkout-payment-continuation.v1" as const;
+const DEFAULT_TTL_SECONDS = CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS;
+const MIN_TTL_SECONDS = 60;
+const MAX_TTL_SECONDS = CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const JOURNEY_PATTERN = /^checkout:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+
+
+export interface CheckoutPaymentContinuationInput<Rail extends string = string> {
+  journeyId: string;
+  orderId: string;
+  clientId: string;
+  paymentIntentId: string;
+  paymentAttemptId: string;
+  executionRail: Rail;
+}
+
+export interface CheckoutPaymentContinuationClaims<Rail extends string = string> extends CheckoutPaymentContinuationInput<Rail> {
+  version: 1;
+  purpose: typeof PURPOSE;
+  expiresAt: number;
+}
+
+export interface CheckoutPaymentContinuationCodec<Rail extends string = string> {
+  issue(input: CheckoutPaymentContinuationInput<Rail>): {
+    claims: CheckoutPaymentContinuationClaims<Rail>;
+    setCookie: string;
+  };
+  verifyCookieHeader(cookieHeader: unknown): CheckoutPaymentContinuationClaims<Rail> | null;
+}
+
+export type CheckoutPaymentContinuationMinter<Rail extends string = string> = (
+  res: CheckoutCookieResponse,
+  input: CheckoutPaymentContinuationInput<Rail>,
+) => void;
+
+export interface CheckoutCookieResponse {
+  getHeader?(name: string): string | number | string[] | undefined;
+  setHeader(name: string, value: number | string | readonly string[]): unknown;
+}
+
+export function mintPaymentContinuationOnFreshAction<Rail extends string>(input: {
+  mint?: CheckoutPaymentContinuationMinter<Rail>;
+  res: CheckoutCookieResponse;
+  journeyId: string;
+  clientId: string;
+  requestRail: string;
+  response: { status: string; clientAction?: CheckoutContinuationAction };
+  result: {
+    continuationActionOrigin: "fresh_execution" | null;
+    executionRail: string;
+    paymentAttemptId: string | null;
+    paymentIntentId: string;
+    orderId: string;
+  };
+}, executionRails: readonly [Rail, Rail]): void {
+  const { result, response } = input;
+  if (
+    result.continuationActionOrigin !== "fresh_execution"
+    || !result.paymentAttemptId
+    || !isCheckoutContinuationRail(result.executionRail, executionRails)
+    || result.executionRail !== input.requestRail
+    || response.status === "price_changed"
+    || !responseWantsContinuation(response, result.executionRail, executionRails)
+  ) return;
+  // Split out from the guard above ON PURPOSE. Every condition there says "this
+  // attempt does not want a continuation"; this one says "it wants one and we
+  // cannot issue it", which is an operator problem and used to be
+  // indistinguishable from the first. That silence is how the capability stayed
+  // dormant in every environment without anyone noticing. Rail and reason only:
+  // no order, client, attempt or intent id is logged.
+  if (!input.mint) {
+    console.warn(
+      "checkout_payment_continuation_unavailable",
+      JSON.stringify({ executionRail: result.executionRail, reason: "no_signing_secret" }),
+    );
+    return;
+  }
+  try {
+    input.mint(input.res, {
+      journeyId: input.journeyId,
+      orderId: result.orderId,
+      clientId: input.clientId,
+      paymentIntentId: result.paymentIntentId,
+      paymentAttemptId: result.paymentAttemptId,
+      executionRail: result.executionRail,
+    });
+  } catch {
+    // Continuation is best-effort; checkout success must never depend on it.
+  }
+}
+
+export function createCheckoutPaymentContinuationCodec<Rail extends string>(
+  rootSecret: string | undefined,
+  options: { cookieName: string; executionRails: readonly [Rail, Rail]; now?: () => Date; ttlSeconds?: number },
+): CheckoutPaymentContinuationCodec<Rail> | null {
+  if (!rootSecret || Buffer.byteLength(rootSecret, "utf8") < 32) return null;
+  const now = options.now ?? (() => new Date());
+  const ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < MIN_TTL_SECONDS || ttlSeconds > MAX_TTL_SECONDS) {
+    throw new Error(
+      `Checkout payment continuation TTL must be between ${MIN_TTL_SECONDS} and ${MAX_TTL_SECONDS} seconds`,
+    );
+  }
+  const signingKey = createHmac("sha256", rootSecret).update(PURPOSE).digest();
+
+  function sign(payload: string): string {
+    return createHmac("sha256", signingKey).update(payload).digest("base64url");
+  }
+
+  return {
+    issue(input) {
+      if (!isValidInput(input, options.executionRails)) throw new Error("Invalid checkout payment continuation input");
+      const claims: CheckoutPaymentContinuationClaims<Rail> = {
+        version: 1,
+        purpose: PURPOSE,
+        expiresAt: Math.floor(now().getTime() / 1000) + ttlSeconds,
+        ...input,
+      };
+      const payload = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");
+      const token = `${payload}.${sign(payload)}`;
+      return {
+        claims,
+        setCookie: `${options.cookieName}=${token}; Path=/; Max-Age=${ttlSeconds}; Secure; HttpOnly; SameSite=Strict`,
+      };
+    },
+    verifyCookieHeader(cookieHeader) {
+      const token = readCookie(cookieHeader, options.cookieName);
+      if (!token) return null;
+      const separator = token.indexOf(".");
+      if (separator <= 0 || separator === token.length - 1 || token.indexOf(".", separator + 1) !== -1) return null;
+      const payload = token.slice(0, separator);
+      const suppliedSignature = token.slice(separator + 1);
+      const expectedSignature = sign(payload);
+      const supplied = Buffer.from(suppliedSignature, "utf8");
+      const expected = Buffer.from(expectedSignature, "utf8");
+      if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) return null;
+      try {
+        const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as unknown;
+        if (!isValidClaims(parsed, options.executionRails)) return null;
+        if (parsed.expiresAt <= Math.floor(now().getTime() / 1000)) return null;
+        return parsed;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+function isValidInput<Rail extends string>(value: unknown, executionRails: readonly Rail[]): value is CheckoutPaymentContinuationInput<Rail> {
+  if (!isRecord(value)) return false;
+  return JOURNEY_PATTERN.test(readString(value, "journeyId"))
+    && UUID_PATTERN.test(readString(value, "orderId"))
+    && UUID_PATTERN.test(readString(value, "clientId"))
+    && UUID_PATTERN.test(readString(value, "paymentIntentId"))
+    && UUID_PATTERN.test(readString(value, "paymentAttemptId"))
+    && isCheckoutContinuationRail(value.executionRail, executionRails);
+}
+
+function isValidClaims<Rail extends string>(value: unknown, executionRails: readonly Rail[]): value is CheckoutPaymentContinuationClaims<Rail> {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value).sort();
+  const expectedKeys = [
+    "clientId", "expiresAt", "journeyId", "orderId", "paymentAttemptId",
+    "executionRail", "paymentIntentId", "purpose", "version",
+  ].sort();
+  return keys.length === expectedKeys.length
+    && keys.every((key, index) => key === expectedKeys[index])
+    && value.version === 1
+    && value.purpose === PURPOSE
+    && Number.isInteger(value.expiresAt)
+    && isValidInput(value, executionRails);
+}
+
+function readCookie(header: unknown, name: string): string | null {
+  const raw = Array.isArray(header) ? header[0] : header;
+  if (typeof raw !== "string") return null;
+  for (const part of raw.split(";")) {
+    const trimmed = part.trim();
+    const separator = trimmed.indexOf("=");
+    if (separator > 0 && trimmed.slice(0, separator) === name) {
+      return trimmed.slice(separator + 1) || null;
+    }
+  }
+  return null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function readString(value: Record<string, unknown>, key: string): string {
+  return typeof value[key] === "string" ? value[key] : "";
+}
+
+function responseWantsContinuation<Rail extends string>(
+  response: { status: string; clientAction?: CheckoutContinuationAction },
+  rail: Rail,
+  executionRails: readonly Rail[],
+): boolean {
+  return actionMatchesExecutionRail(response.clientAction, rail, executionRails)
+    || (response.clientAction?.kind === "none" && response.status === "processing");
+}
+
+function actionMatchesExecutionRail<Rail extends string>(
+  action: CheckoutContinuationAction | undefined,
+  rail: Rail,
+  executionRails: readonly Rail[],
+): boolean {
+  return rail === executionRails[0]
+    ? action?.kind === "provider_embedded" && action.provider === executionRails[0]
+    : action?.kind === "redirect";
+}
+
+export function isCheckoutContinuationRail<Rail extends string>(value: unknown, executionRails: readonly Rail[]): value is Rail {
+  return typeof value === "string" && (executionRails as readonly string[]).includes(value);
+}

package/src/commerce/server/checkoutQuoteTypes.ts

@@ -0,0 +1,9 @@
+import type { AcquisitionTermsExpectation, ResolvedAcquisitionTerms, CreateQuoteResponse, CommerceQuoteContext, PricingPolicySnapshot } from "../../pricing/index.js";
+export interface CheckoutQuoteSnapshot extends CreateQuoteResponse {
+  quote: CreateQuoteResponse["quote"] & { context?: CommerceQuoteContext & { pricingPolicy?: PricingPolicySnapshot; acquisitionTerms?: ResolvedAcquisitionTerms; shippingTerms?: unknown; offerVersion?: string } };
+}
+export interface ExpectedCheckoutQuote {
+  totalGross: { amountMinor: number; currency: string };
+  pricingPolicy?: PricingPolicySnapshot;
+  acquisitionTerms?: AcquisitionTermsExpectation;
+}

package/src/commerce/server/checkoutRecoveryOrderPort.ts

@@ -0,0 +1,40 @@
+export interface CheckoutRecoveryPriorPaymentEvidence {
+  paymentIntentId: string;
+  paymentAttemptId: string;
+  provider: string;
+  providerPaymentId: string | null;
+  idempotencyKey: string;
+  retryRequestId: string | null;
+}
+
+export type CheckoutRecoveryOrderSnapshot<Quote, PaymentStatus, Host extends object = object> = Host & {
+  orderId: string;
+  orderRef: string;
+  orderNumber: string;
+  clientId: string;
+  status: string;
+  mode: "subscription_cycle" | "one_time_order";
+  totalMinor: number;
+  currency: string;
+  cadenceDays: number | null;
+  createdAt: string;
+  customerEmail: string | null;
+  customerName: string | null;
+  paymentIntentId: string | null;
+  paymentIntentStatus: PaymentStatus | null;
+  subscriptionId: string | null;
+  subscriptionCycleId: string | null;
+  shippingAddressId?: string | null;
+  quoteSnapshot?: Quote | null;
+  runtimeMetadata?: Record<string, unknown>;
+  invoiceBuyerSnapshot?: Record<string, unknown>;
+  recoveryRootOrderId?: string;
+  recreatedFromOrderId?: string | null;
+  technicallyExpired?: boolean;
+  priorPaymentEvidence?: CheckoutRecoveryPriorPaymentEvidence | null;
+}
+
+export interface CheckoutRecoveryOrderReadPort<Order> {
+  getRecoveryOrder(input: { orderId: string }): Promise<Order | null>;
+  getLatestRecoveryOrder?(input: { orderId: string }): Promise<Order | null>;
+}

package/src/commerce/server/checkoutRecoveryToken.ts

@@ -0,0 +1,63 @@
+import { createHash, randomBytes } from "node:crypto";
+
+export interface CheckoutRecoveryTokenContext {
+  tokenId: string;
+  orderId: string;
+  clientId: string;
+  /** "subscription_cycle" | "one_time_order" — drives copy + post-pay activation. */
+  mode: string;
+  status: string;
+}
+
+export interface CheckoutRecoveryTokenInspection {
+  tokenId: string;
+  orderId: string;
+  clientId: string;
+  /** Null when the token exists but the order row is already gone. */
+  mode: string | null;
+  status: string | null;
+  subscriptionId: string | null;
+  tokenState: string;
+}
+
+/** Inspection RPC states; only the named continuation states may resume pending orders. */
+export function classifyCheckoutRecoveryTokenState(
+  tokenState: string,
+): "continuation" | "expired_policy" | "refused" {
+  switch (tokenState) {
+    case "active":
+    case "order_not_recoverable":
+      return "continuation";
+    case "expired":
+      return "expired_policy";
+    case "revoked":
+    case "used":
+    case "order_not_found":
+    default:
+      return "refused";
+  }
+}
+
+export interface CheckoutRecoveryTokenPort {
+  /** Issue a token for an unpaid order. Returns the new token row id. */
+  issue(input: { orderId: string; rawToken: string; expiresAt: string }): Promise<string>;
+  /** Validate a raw token; returns the order context, or null if invalid/expired/not recoverable. */
+  validate(rawToken: string, now?: Date): Promise<CheckoutRecoveryTokenContext | null>;
+  /**
+   * Inspect without granting continuation; callers must check state before reconstructing authority.
+   */
+  inspect(rawToken: string, now?: Date): Promise<CheckoutRecoveryTokenInspection | null>;
+}
+
+/** Canonical hash: SHA-256 hex of the raw token (matches the SQL `encode(sha256(...))`). */
+export function hashCheckoutRecoveryToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+/** A non-hex prefix keeps quoted-printable mail transports from consuming the URL separator. */
+export const CHECKOUT_RECOVERY_TOKEN_PREFIX = "rcv_";
+
+/** A 256-bit URL-safe random token for the deep-link, with the QP-safe prefix. */
+export function generateCheckoutRecoveryToken(): string {
+  return CHECKOUT_RECOVERY_TOKEN_PREFIX + randomBytes(32).toString("base64url");
+}

package/src/commerce/server/checkoutRefusalContinuation.ts

@@ -0,0 +1,29 @@
+import type { CheckoutContinuationAction } from "./checkoutPaymentContinuationCredential.js";
+import { isCheckoutContinuationRail } from "./checkoutPaymentContinuationCredential.js";
+import type { CheckoutCookieResponse, CheckoutPaymentContinuationMinter } from "./checkoutPaymentContinuationCredential.js";
+
+/** A separate guard: refusal diagnostics must not widen existing action authority. */
+export function mintCheckoutRefusalContinuation<Rail extends string>(input: {
+  mint?: CheckoutPaymentContinuationMinter<Rail>;
+  res: CheckoutCookieResponse;
+  journeyId: string;
+  clientId: string;
+  requestRail: string;
+  response: { status: string; clientAction?: CheckoutContinuationAction };
+  result: { orderId: string; paymentIntentId: string; paymentAttemptId: string | null;
+    executionRail: string; continuationActionOrigin: "fresh_execution" | null;
+    status: string; runtimePaymentStatus?: string; paymentAttemptStatus?: string | null };
+}, executionRails: readonly [Rail, Rail]): void {
+  const { result, response } = input;
+  if (!input.mint || result.continuationActionOrigin !== "fresh_execution"
+    || result.runtimePaymentStatus !== "failed" || result.paymentAttemptStatus !== "failed" || response.status !== "failed"
+    || (response.clientAction && response.clientAction.kind !== "none")
+    || !result.orderId || !result.paymentIntentId || !result.paymentAttemptId
+    || result.executionRail !== input.requestRail
+    || !isCheckoutContinuationRail(result.executionRail, executionRails)) return;
+  try {
+    input.mint(input.res, { journeyId: input.journeyId, clientId: input.clientId,
+      orderId: result.orderId, paymentIntentId: result.paymentIntentId,
+      paymentAttemptId: result.paymentAttemptId, executionRail: result.executionRail });
+  } catch { /* Optional guidance must never turn a settled refusal into an error. */ }
+}

package/src/commerce/server/checkoutRuntimeTypes.ts

@@ -0,0 +1,26 @@
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+export type CheckoutExecutionProvider = string;
+export type CheckoutProviderFlow = string;
+export interface CheckoutRuntimeRequest<MethodKind extends string = string, RecurringModel extends string = string> {
+  idempotencyKey: string; paymentProvider: CheckoutExecutionProvider; providerFlow: CheckoutProviderFlow;
+  paymentAttemptSequence?: number; paymentMethodRef?: string; paymentMethodAliasType?: MethodKind;
+  paymentMethodRecurringModel?: RecurringModel; providerPayer?: { email: string; name: string; ip?: string | null; userAgent?: string | null };
+  saveForFutureUse?: boolean; returnContext?: "public" | "account"; paymentExecution?: unknown; declaredBankId?: string;
+  metadata: Record<string, unknown>;
+}
+export interface CheckoutRuntimeExecutionInput<Transient, Flow extends string = string, MethodKind extends string = string, RecurringModel extends string = string> extends PaymentExecutionBaseInput {
+  orderRef: string; providerFlow?: Flow; clientId?: string; orderId?: string;
+  paymentMethodRef?: string; paymentMethodAliasType?: MethodKind; paymentMethodRecurringModel?: RecurringModel;
+  payer?: { email: string; name: string; ip?: string | null; userAgent?: string | null };
+  saveForFutureUse?: boolean; returnContext?: "public" | "account"; transientProviderInput?: Transient | null;
+}
+export interface CheckoutRuntimeExecutionResult extends PaymentExecutionBaseResult {
+  provider: CheckoutExecutionProvider; clientSecret?: string | null; redirectUrl?: string | null;
+}
+export interface CheckoutRuntimeExecutionPort<Execution, Transient, Flow extends string = string, MethodKind extends string = string, RecurringModel extends string = string> { execute(input: CheckoutRuntimeExecutionInput<Transient, Flow, MethodKind, RecurringModel>): Promise<Execution> }
+export interface CheckoutRuntimeResultRequest { idempotencyKey: string; orderId: string; paymentIntentId: string; resultStatus: string }
+export interface CheckoutRuntimePaymentPort {
+  createIntent(input: { idempotencyKey: string; targetKind: "one_time_order" | "subscription_cycle"; orderId: string; subscriptionId: string | null; subscriptionCycleId: string | null; amountMinor: number; currency: string; metadata: Record<string, unknown> }): Promise<{ paymentIntentId: string; paymentId: string; status: string; replayed: boolean }>;
+  applyResult(input: CheckoutRuntimeResultRequest): Promise<{ orderId: string; kind: string }>;
+}
+export interface CheckoutRuntimeResponse { runtime: { orderId: string } }

package/src/commerce/server/commerceCheckoutCommandExecution.ts

@@ -0,0 +1,188 @@
+import type { z } from "zod";
+import type { CreateQuoteRequest, PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutJourney, CommerceOrderDraftWritePort, CheckoutCommandRuntimeResult } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import type { CheckoutCommandV1, CheckoutCommandPersistenceResult } from "../checkoutCommandSchemas.js";
+import { buildOrderDeliveryContact } from "../checkoutHelpers.js";
+import { CommerceRuntimeConflictError, CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+import { tryCompensate, type CheckoutCompensationPort } from "./commerceCheckoutCompensation.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+import type { PaidOrderOrchestrationDeps, CheckoutJourneyRuntimeRequest, CheckoutJourneyRuntimeResponse, CheckoutJourneyResultRequest, OrchestratedCheckoutResult } from "./commercePaidOrderOrchestration.js";
+import type { CheckoutExecutionProvider } from "./checkoutRuntimeTypes.js";
+import type { CheckoutPaymentExecution } from "./commerceCheckoutProviderPayment.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+export interface CheckoutCommandQuoteRequest extends CreateQuoteRequest { customerEligibilityContext: { email: string } }
+export interface CheckoutCommandExecutionRequest<Provider extends string = string, MethodKind extends string = string, RecurringModel extends string = string> {
+  command: CheckoutCommandV1; paymentProvider: Provider; paymentAttemptSequence?: number;
+  paymentMethodRef?: string; paymentMethodAliasType?: MethodKind; paymentMethodRecurringModel?: RecurringModel;
+  saveForFutureUse?: boolean; returnContext?: "public" | "account";
+  providerPayer?: { email: string; name: string; ip?: string | null; userAgent?: string | null }; metadata?: Record<string, unknown>;
+}
+export function checkoutCommandJourney(
+  command: CheckoutCommandV1,
+  metadata: Record<string, unknown> | undefined,
+): CheckoutJourney<CheckoutCommandQuoteRequest, PricingPolicySnapshot> {
+  return {
+    idempotencyKey: command.idempotencyKey,
+    contactEmail: command.customer.email,
+    createQuoteRequest: () => ({
+      mode: command.mode,
+      lines: command.lines.map((line) => ({
+        sku: line.sku,
+        quantity: line.quantity,
+        modeAtLine: command.mode,
+      })),
+      cadenceDays: command.cadenceDays ?? null,
+      promoCodes: [],
+      customerEligibilityContext: { email: command.customer.email },
+    }),
+    createRuntimeMetadata: () => ({
+      ...metadata,
+      checkoutCommandVersion: command.version,
+      cadenceDays: command.cadenceDays,
+      deliveryContact: buildOrderDeliveryContact({
+        recipientName: `${command.customer.firstName} ${command.customer.lastName}`,
+        contactEmail: command.customer.email,
+        contactPhone: command.customer.phone,
+        line1: command.shippingAddress.street,
+        city: command.shippingAddress.city,
+        postalCode: command.shippingAddress.postalCode,
+        country: command.shippingAddress.country,
+      }),
+    }),
+  };
+}
+
+export function createCheckoutCommandExecutor<Provisioned extends { clientId: string; addressId: string }, Snapshot extends CheckoutQuoteSnapshot, Draft extends { orderDraft: { orderId: string } }, Extension extends object, Runtime extends CheckoutJourneyRuntimeResponse<Provider>, Settlement, ExecutionPort extends object, PaymentExecution extends CheckoutPaymentExecution, Provider extends string, Flow extends string, MethodKind extends string = string, RecurringModel extends string = string>(bindings: {
+  commandSchema: z.ZodType<CheckoutCommandV1>;
+  commandProvisioned(persistence: CheckoutCommandPersistenceResult): Provisioned;
+  orchestrateCheckoutJourney(deps: PaidOrderOrchestrationDeps<Provisioned, CheckoutCommandQuoteRequest, Snapshot, Draft, Extension, Runtime, Settlement, PaymentExecution, Provider, Flow, MethodKind, RecurringModel>, journey: CheckoutJourney<CheckoutCommandQuoteRequest, PricingPolicySnapshot>): Promise<OrchestratedCheckoutResult<Snapshot, Provider>>;
+}) {
+  type CheckoutCommandExecutionDeps = {
+    quotePort?: CommerceQuotePort<CheckoutCommandQuoteRequest, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+    persistencePort?: { persistCheckoutCommand(command: CheckoutCommandV1): Promise<CheckoutCommandPersistenceResult> };
+    orderDraftPort?: CommerceOrderDraftWritePort<{ idempotencyKey: string; quoteSnapshot: Snapshot }, Draft>;
+    resolveExecutionPort?: (provider: string) => ExecutionPort;
+    compensationPort?: CheckoutCompensationPort; now?: () => Date;
+    startRuntime(request: CheckoutJourneyRuntimeRequest<Snapshot, PaymentExecution, Provider, Flow, MethodKind, RecurringModel> & Extension, executionPort: ExecutionPort): Promise<Runtime>;
+    applyPaymentResult(request: CheckoutJourneyResultRequest): Promise<Settlement>;
+  };
+
+const COMMAND_CONFLICT_REASONS = new Set([
+  "journey_consumed",
+  "promotion_code_price_changed",
+  "provider_attempt_in_flight",
+]);
+
+async function executeCheckoutCommand(
+  request: CheckoutCommandExecutionRequest<Provider, MethodKind, RecurringModel>,
+  deps: CheckoutCommandExecutionDeps,
+): Promise<CheckoutCommandRuntimeResult<Snapshot, CheckoutCommandPersistenceResult, Draft, Runtime, Settlement>> {
+  const command = bindings.commandSchema.safeParse(request.command);
+  if (!command.success) throw new CommerceRuntimeConflictError("Checkout command is invalid");
+  const { quotePort, persistencePort, orderDraftPort, resolveExecutionPort } = deps;
+  if (!quotePort || !persistencePort || !orderDraftPort || !resolveExecutionPort) {
+    throw new CommerceRuntimePersistenceError(
+      "Checkout command runtime composition is incomplete",
+      { missing: [!quotePort && "quote", !persistencePort && "persistence", !orderDraftPort && "order_draft", !resolveExecutionPort && "payment_provider"].filter(Boolean) },
+    );
+  }
+
+  const adapter = resolveExecutionPort(request.paymentProvider) as unknown;
+  if (typeof adapter !== "object" || adapter === null || !("execute" in adapter) || typeof adapter.execute !== "function") {
+    throw new CommerceRuntimePersistenceError("Checkout command payment provider adapter is unavailable");
+  }
+  const executionPort = adapter as ExecutionPort;
+  const journey = checkoutCommandJourney(command.data, request.metadata);
+  // Quote and its currency guard stay ahead of every write: a mismatched
+  // currency must not leave a persisted client, address, or draft behind.
+  const quoteSnapshot = await quotePort.createQuote(journey.createQuoteRequest());
+  if (quoteSnapshot.quote.currency !== command.data.currency) {
+    throw new CommerceRuntimeConflictError("Checkout command currency does not match quote", {
+      commandCurrency: command.data.currency,
+      quoteCurrency: quoteSnapshot.quote.currency,
+    });
+  }
+
+  const persistence = await persistencePort.persistCheckoutCommand(command.data);
+  if (persistence.subjectId !== null) {
+    throw new CommerceRuntimePersistenceError("Checkout command persistence returned an unexpected subject");
+  }
+
+  // From here the neutral command runs the SAME application service as the
+  // legacy configurator checkout: one stage sequence, one start-runtime failure
+  // mapping, one provider invariant set, one settle step, one compensation.
+  const captured: {
+    orderDraft: Draft | null;
+    runtime: Runtime | null;
+    settlement: Settlement | null;
+  } = { orderDraft: null, runtime: null, settlement: null };
+  try {
+    const orchestrationDeps: PaidOrderOrchestrationDeps<Provisioned, CheckoutCommandQuoteRequest, Snapshot, Draft, Extension, Runtime, Settlement, PaymentExecution, Provider, Flow, MethodKind, RecurringModel> & { journey: CheckoutJourney<CheckoutCommandQuoteRequest, PricingPolicySnapshot> } = {
+      journey,
+      provisioned: bindings.commandProvisioned(persistence),
+      checkoutKind: command.data.mode === "subscription" ? "subscription_initial" : "one_time",
+      quotePort,
+      quoteSnapshot,
+      orderDraftPort: {
+        createOrderDraft: async (draftRequest, options) => {
+          captured.orderDraft = await orderDraftPort.createOrderDraft(draftRequest, options);
+          return captured.orderDraft;
+        },
+      },
+      runtimePort: {
+        startRuntime: async (startRequest) => {
+          captured.runtime = await deps.startRuntime(startRequest, executionPort);
+          return captured.runtime;
+        },
+        applyPaymentResult: async (settleRequest) => {
+          captured.settlement = await deps.applyPaymentResult(settleRequest);
+          return captured.settlement;
+        },
+      },
+      paymentProvider: request.paymentProvider,
+      paymentAttemptSequence: request.paymentAttemptSequence,
+      paymentMethodRef: request.paymentMethodRef,
+      paymentMethodAliasType: request.paymentMethodAliasType,
+      paymentMethodRecurringModel: request.paymentMethodRecurringModel,
+      saveForFutureUse: request.saveForFutureUse,
+      returnContext: request.returnContext,
+      providerPayer: request.providerPayer,
+      now: deps.now ?? (() => new Date()),
+    };
+    await bindings.orchestrateCheckoutJourney(orchestrationDeps, journey);
+  } catch (error) {
+    throw await mapOrchestrationFailure(error, journey.idempotencyKey, deps.compensationPort);
+  }
+  if (!captured.orderDraft || !captured.runtime) {
+    throw new CommerceRuntimePersistenceError("Checkout command runtime produced no result");
+  }
+
+  return {
+    quoteSnapshot,
+    persistence,
+    orderDraft: captured.orderDraft,
+    runtime: captured.runtime,
+    settlement: captured.settlement,
+  };
+}
+
+async function mapOrchestrationFailure(
+  error: unknown,
+  idempotencyKey: string,
+  compensationPort: CheckoutCompensationPort | undefined,
+): Promise<unknown> {
+  if (!(error instanceof CheckoutOrchestrationError)) return error;
+  // `orderIdForCompensation` is a compensation capability, not an order id: the
+  // saga deliberately withholds it when a provider attempt may be in flight.
+  if (error.orderIdForCompensation && compensationPort) {
+    await tryCompensate(compensationPort, idempotencyKey, error.orderIdForCompensation);
+  }
+  const details = { stage: error.message.split(":")[0], reason: error.reason };
+  return error.reason && COMMAND_CONFLICT_REASONS.has(error.reason)
+    ? new CommerceRuntimeConflictError("Checkout command could not be completed", details)
+    : new CommerceRuntimePersistenceError("Checkout command runtime failed", details);
+}
+
+return { executeCheckoutCommand };
+}