@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/server/checkoutRefusalContinuation.d.ts

@@ -0,0 +1,24 @@
+import type { CheckoutContinuationAction } from "./checkoutPaymentContinuationCredential.js";
+import type { CheckoutCookieResponse, CheckoutPaymentContinuationMinter } from "./checkoutPaymentContinuationCredential.js";
+/** A separate guard: refusal diagnostics must not widen existing action authority. */
+export declare 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;

package/dist/commerce/server/checkoutRefusalContinuation.js

@@ -0,0 +1,18 @@
+import { isCheckoutContinuationRail } from "./checkoutPaymentContinuationCredential.js";
+/** A separate guard: refusal diagnostics must not widen existing action authority. */
+export function mintCheckoutRefusalContinuation(input, executionRails) {
+    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/dist/commerce/server/checkoutRuntimeTypes.d.ts

@@ -0,0 +1,81 @@
+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/dist/commerce/server/checkoutRuntimeTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/commerce/server/commerceCheckoutCommandExecution.d.ts

@@ -0,0 +1,60 @@
+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 { type CheckoutCompensationPort } from "./commerceCheckoutCompensation.js";
+import type { PaidOrderOrchestrationDeps, CheckoutJourneyRuntimeRequest, CheckoutJourneyRuntimeResponse, CheckoutJourneyResultRequest, OrchestratedCheckoutResult } from "./commercePaidOrderOrchestration.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 declare function checkoutCommandJourney(command: CheckoutCommandV1, metadata: Record<string, unknown> | undefined): CheckoutJourney<CheckoutCommandQuoteRequest, PricingPolicySnapshot>;
+export declare 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>>;
+}): {
+    executeCheckoutCommand: (request: CheckoutCommandExecutionRequest<Provider, MethodKind, RecurringModel>, deps: {
+        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>;
+    }) => Promise<CheckoutCommandRuntimeResult<Snapshot, CheckoutCommandPersistenceResult, Draft, Runtime, Settlement>>;
+};

package/dist/commerce/server/commerceCheckoutCommandExecution.js

@@ -0,0 +1,136 @@
+import { buildOrderDeliveryContact } from "../checkoutHelpers.js";
+import { CommerceRuntimeConflictError, CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+import { tryCompensate } from "./commerceCheckoutCompensation.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+export function checkoutCommandJourney(command, metadata) {
+    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(bindings) {
+    const COMMAND_CONFLICT_REASONS = new Set([
+        "journey_consumed",
+        "promotion_code_price_changed",
+        "provider_attempt_in_flight",
+    ]);
+    async function executeCheckoutCommand(request, deps) {
+        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);
+        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;
+        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: null, runtime: null, settlement: null };
+        try {
+            const orchestrationDeps = {
+                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, idempotencyKey, compensationPort) {
+        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 };
+}

package/dist/commerce/server/commerceCheckoutCompensation.d.ts

@@ -0,0 +1,26 @@
+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 declare function tryCompensate(port: CheckoutCompensationPort, idempotencyKey: string, orderId: string, options?: {
+    cancellationReason?: string;
+}): Promise<void>;

package/dist/commerce/server/commerceCheckoutCompensation.js

@@ -0,0 +1,46 @@
+export async function tryCompensate(port, idempotencyKey, orderId, options) {
+    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/dist/commerce/server/commerceCheckoutContinuationTerms.d.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+import { type AcquisitionTermsExpectation, type CreateQuoteRequest } from "../../pricing/index.js";
+import type { CheckoutKind, ConfiguratorIntent } from "../contracts/index.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import type { StarterDeclaration } from "./commerceStarterOfferGuard.js";
+import { type CheckoutResumeGuardDeps } from "./commerceCheckoutResumeGuard.js";
+export declare 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;
+}): {
+    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>;
+};

package/dist/commerce/server/commerceCheckoutContinuationTerms.js

@@ -0,0 +1,66 @@
+import { acquisitionExpectationChanged } from "../../pricing/index.js";
+import { stableJson } from "../../promotions/index.js";
+import { selectedDeliveryMatches } from "./commerceCheckoutResumeGuard.js";
+export function createSavedAcquisitionContinuation(bindings) {
+    async function resolveSavedAcquisitionContinuation(input) {
+        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.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) {
+        const totals = new Map();
+        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) {
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value : null;
+    }
+    return { resolveSavedAcquisitionContinuation };
+}

package/dist/commerce/server/commerceCheckoutCustomerDefaults.d.ts

@@ -0,0 +1,18 @@
+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 declare 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>;
+export declare 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";
+}>;

package/dist/commerce/server/commerceCheckoutCustomerDefaults.js

@@ -0,0 +1,17 @@
+export async function readCheckoutCustomerDefaults(input, schema) {
+    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(input, schema, responder) {
+    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/dist/commerce/server/commerceCheckoutFailureHandler.d.ts

@@ -0,0 +1,51 @@
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.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 { type CheckoutCompensationPort } from "./commerceCheckoutCompensation.js";
+import type { CheckoutTimingOutcome } from "./commerceCheckoutTiming.js";
+export declare 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>;
+}): {
+    respondToCheckoutFailure: (input: {
+        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>;
+    }) => Promise<CheckoutTimingOutcome>;
+};