@openlup/platform 0.26.0 → 0.27.0

package/dist/commerce/server/commerceOmsHandlers.js

@@ -0,0 +1,176 @@
+import { adminCommerceOrderDetailRequestSchema, adminCommerceOrderDetailResponseSchema, adminCommerceOrderHoldRequestSchema, adminCommerceOrderHoldResponseSchema, adminCommerceOrderNoteRequestSchema, adminCommerceOrderNoteResponseSchema, adminCommerceOrderReleaseHoldRequestSchema, adminCommerceOrderUpdateShippingAddressRequestSchema, adminCommerceOrderUpdateShippingAddressResponseSchema, adminCommerceOrdersListRequestSchema, adminCommerceOrdersListResponseSchema, } from "../oms/omsContracts.js";
+import { CommerceOmsConflictError } from "../oms/omsPorts.js";
+import { unprojectedOmsReadGate } from "./handlerSupport.js";
+export function createAdminCommerceOrdersListHandler({ authorizeAdmin, omsPort, readGate, listRequestSchema = adminCommerceOrdersListRequestSchema, listResponseSchema = adminCommerceOrdersListResponseSchema, detailResponseSchema = adminCommerceOrderDetailResponseSchema, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "GET" && req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["GET", "POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const rawRequest = req.method === "GET" ? req.query ?? {} : req.body ?? {};
+        const request = parseOmsRequest(res, respond, listRequestSchema, rawRequest, "Invalid admin commerce orders request");
+        if (request === undefined)
+            return;
+        // Wave 7a: gate the machine actor; the human admin OMS UI is unaffected.
+        const gate = readGate?.({
+            authorization: auth,
+            view: "list",
+            query: auditSafeListQuery(request),
+        }) ?? unprojectedOmsReadGate;
+        if (gate.blocked)
+            return;
+        try {
+            const result = await omsPort.listOrders(request);
+            const response = listResponseSchema.safeParse(result);
+            if (!response.success) {
+                respond.sendBffError(res, "INVALID_RESPONSE", "Admin commerce orders returned invalid response");
+                return;
+            }
+            await gate.audit(response.data.orders.flatMap((o) => (o.clientId ? [o.clientId] : [])));
+            respond.sendBffSuccess(res, gate.maskOrders(response.data));
+        }
+        catch {
+            respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce orders read failed");
+        }
+    };
+}
+function auditSafeListQuery(request) {
+    const { search, ...safe } = request;
+    return search ? { ...safe, search: "[redacted]" } : safe;
+}
+export function createAdminCommerceOrderDetailHandler({ authorizeAdmin, omsPort, readGate, listRequestSchema = adminCommerceOrdersListRequestSchema, listResponseSchema = adminCommerceOrdersListResponseSchema, detailResponseSchema = adminCommerceOrderDetailResponseSchema, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "GET")
+            return respond.sendMethodNotAllowed(res, ["GET"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderDetailRequestSchema, req.query, "Invalid admin commerce order detail request");
+        if (request === undefined)
+            return;
+        // Wave 7a: gate the machine actor. Detail returns FULL PII (gated + audited).
+        const gate = readGate?.({
+            authorization: auth,
+            view: "detail",
+            query: { ...request },
+        }) ?? unprojectedOmsReadGate;
+        if (gate.blocked)
+            return;
+        try {
+            const result = await omsPort.getOrderDetail(request);
+            if (!result) {
+                respond.sendBffError(res, "NOT_FOUND", "Commerce order not found");
+                return;
+            }
+            const response = detailResponseSchema.safeParse(result);
+            if (!response.success) {
+                respond.sendBffError(res, "INVALID_RESPONSE", "Admin commerce order detail returned invalid response");
+                return;
+            }
+            await gate.audit(response.data.order.clientId ? [response.data.order.clientId] : []);
+            const masked = gate.maskOrders({ orders: [response.data.order] });
+            respond.sendBffSuccess(res, { ...response.data, order: masked.orders[0] });
+        }
+        catch {
+            respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin commerce order detail failed");
+        }
+    };
+}
+export function createAdminCommerceOrderHoldHandler({ authorizeAdmin, omsPort, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderHoldRequestSchema, req.body ?? {}, "Invalid admin commerce order hold request");
+        if (request === undefined)
+            return;
+        await sendHoldResponse(res, respond, () => omsPort.createHold({ ...request, actorUserId: auth.userId }));
+    };
+}
+export function createAdminCommerceOrderReleaseHoldHandler({ authorizeAdmin, omsPort, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderReleaseHoldRequestSchema, req.body ?? {}, "Invalid admin commerce order release request");
+        if (request === undefined)
+            return;
+        await sendHoldResponse(res, respond, () => omsPort.releaseHold({ ...request, actorUserId: auth.userId }));
+    };
+}
+export function createAdminCommerceOrderNoteHandler({ authorizeAdmin, omsPort, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderNoteRequestSchema, req.body ?? {}, "Invalid admin commerce order note request");
+        if (request === undefined)
+            return;
+        await sendOmsMutationResponse(res, respond, () => omsPort.addNote({ ...request, actorUserId: auth.userId }), adminCommerceOrderNoteResponseSchema, "Admin commerce note mutation returned invalid response", "Admin commerce note mutation failed");
+    };
+}
+export function createAdminCommerceOrderUpdateShippingAddressHandler({ authorizeAdmin, omsPort, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        const request = parseOmsRequest(res, respond, adminCommerceOrderUpdateShippingAddressRequestSchema, req.body ?? {}, "Invalid admin commerce order shipping address request");
+        if (request === undefined)
+            return;
+        await sendOmsMutationResponse(res, respond, () => omsPort.updateShippingAddress({ ...request, actorUserId: auth.userId }), adminCommerceOrderUpdateShippingAddressResponseSchema, "Admin commerce shipping address mutation returned invalid response", "Admin commerce shipping address mutation failed");
+    };
+}
+export async function authorize(req, res, authorizeAdmin, respond) {
+    try {
+        const authorization = await authorizeAdmin(req);
+        if (authorization.ok === false) {
+            respond.sendBffError(res, authorization.code, authorization.message);
+            return null;
+        }
+        return { ok: true, userId: authorization.userId, isMachineActor: authorization.isMachineActor };
+    }
+    catch {
+        respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+        return null;
+    }
+}
+function sendHoldResponse(res, respond, action) {
+    return sendOmsMutationResponse(res, respond, action, adminCommerceOrderHoldResponseSchema, "Admin commerce hold mutation returned invalid response", "Admin commerce hold mutation failed");
+}
+// Returns the parsed request, or answers the 400 with the flattened details and returns undefined.
+export function parseOmsRequest(res, respond, schema, input, message) {
+    const request = schema.safeParse(input);
+    if (request.success === false) {
+        respond.sendBffError(res, "BAD_REQUEST", message, { details: request.error.flatten() });
+        return undefined;
+    }
+    return request.data;
+}
+// One OMS mutation answer: 502 on a refused or unaccepted result, 409 on a conflict, 503 on any other throw.
+export async function sendOmsMutationResponse(res, respond, action, schema, invalidMessage, failedMessage, accept = () => true) {
+    try {
+        const result = await action();
+        const response = schema.safeParse(result);
+        if (response.success === false || !accept(response.data)) {
+            respond.sendBffError(res, "INVALID_RESPONSE", invalidMessage);
+            return;
+        }
+        respond.sendBffSuccess(res, response.data);
+    }
+    catch (error) {
+        if (error instanceof CommerceOmsConflictError) {
+            respond.sendBffError(res, "CONFLICT", error.message, { details: error.details });
+            return;
+        }
+        respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", failedMessage);
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { CommerceOmsHoldPort } from "../oms/omsPorts.js";
+import { type BaseDeps } from "./commerceOmsHandlers.js";
+import type { OmsHandlerRequest } from "./handlerSupport.js";
+export declare function createAdminCommerceOrderMarkRefundedHandler<Response>({ authorizeAdmin, omsPort, mutationsEnabled, respond, }: BaseDeps<Response> & {
+    omsPort: Pick<CommerceOmsHoldPort, "markRefunded">;
+    mutationsEnabled: () => boolean;
+}): (req: OmsHandlerRequest, res: Response) => Promise<void>;

package/dist/commerce/server/commerceOmsMarkRefundedHandler.js

@@ -0,0 +1,19 @@
+import { adminCommerceOrderMarkRefundedRequestSchema, adminCommerceOrderMarkRefundedResponseSchema, } from "../oms/omsContracts.js";
+import { authorize, parseOmsRequest, sendOmsMutationResponse } from "./commerceOmsHandlers.js";
+export function createAdminCommerceOrderMarkRefundedHandler({ authorizeAdmin, omsPort, mutationsEnabled, respond, }) {
+    return async function handler(req, res) {
+        if (req.method !== "POST")
+            return respond.sendMethodNotAllowed(res, ["POST"]);
+        const auth = await authorize(req, res, authorizeAdmin, respond);
+        if (!auth)
+            return;
+        if (!mutationsEnabled()) {
+            respond.sendBffError(res, "FORBIDDEN", "Commerce OMS refund mutations are not enabled");
+            return;
+        }
+        const request = parseOmsRequest(res, respond, adminCommerceOrderMarkRefundedRequestSchema, req.body ?? {}, "Invalid admin commerce order mark-refunded request");
+        if (request === undefined)
+            return;
+        await sendOmsMutationResponse(res, respond, () => omsPort.markRefunded({ ...request, actorUserId: auth.userId }), adminCommerceOrderMarkRefundedResponseSchema, "Admin commerce mark-refunded mutation returned invalid response", "Admin commerce mark-refunded mutation failed");
+    };
+}

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

@@ -0,0 +1,24 @@
+import type { z } from "zod";
+import type { CommerceOrderDraftWritePort } from "../contracts/ports.js";
+import type { RpcError as CommerceOrderDraftRpcError } from "../contracts/omsTypes.js";
+import { ORDER_DRAFT_RPC_NAME } from "./orderDraftRpcPayload.js";
+/** Companion RPC that supersedes a stale pre-payment draft for a stable journey key. */
+export declare const ORDER_DRAFT_SUPERSEDE_RPC_NAME: "commerce_supersede_pre_payment_order_draft";
+export interface CommerceOrderDraftRpcClient<Args extends Record<string, unknown>> {
+    rpc(functionName: typeof ORDER_DRAFT_RPC_NAME, args: Args): PromiseLike<{
+        data: unknown;
+        error: CommerceOrderDraftRpcError | null;
+    }>;
+    rpc(functionName: typeof ORDER_DRAFT_SUPERSEDE_RPC_NAME, args: {
+        p_idempotency_key: string;
+    }): PromiseLike<{
+        data: unknown;
+        error: CommerceOrderDraftRpcError | null;
+    }>;
+}
+export declare function createCommerceOrderDraftRpcPort<Request extends {
+    idempotencyKey: string;
+}, Response, Args extends Record<string, unknown>>(client: CommerceOrderDraftRpcClient<Args>, bindings: {
+    createOrderDraftRpcArgs(request: Request, clientId: string | null): Args;
+    responseSchema: z.ZodType<Response>;
+}): CommerceOrderDraftWritePort<Request, Response>;

package/dist/commerce/server/commerceOrderDraft.js

@@ -0,0 +1,92 @@
+import { CommerceOrderDraftConflictError, CommerceOrderDraftInvalidResponseError, CommerceOrderDraftPersistenceError } from "../errors.js";
+import { CommerceOrderDraftPriceChangedError } from "../orderDraftErrors.js";
+import { ORDER_DRAFT_RPC_NAME } from "./orderDraftRpcPayload.js";
+/** Companion RPC that supersedes a stale pre-payment draft for a stable journey key. */
+export const ORDER_DRAFT_SUPERSEDE_RPC_NAME = "commerce_supersede_pre_payment_order_draft";
+export function createCommerceOrderDraftRpcPort(client, bindings) {
+    return {
+        async createOrderDraft(request, options) {
+            const args = bindings.createOrderDraftRpcArgs(request, options?.clientId ?? null);
+            let response = await client.rpc(ORDER_DRAFT_RPC_NAME, args);
+            // Stable journey key + edited cart: the producer keys the draft by
+            // idempotencyKey and 23505s when the same key arrives with a different
+            // (frozen-money) snapshot. Canonical order money freezes an order's amounts
+            // once written, so the stale draft cannot be mutated in place — supersede it
+            // (cancel the unpaid draft, drop the key) and retry create ONCE via the
+            // order-draft supersede RPC. If nothing was superseded (funds already moved),
+            // the conflict stands and the caller's resume path owns the in-flight order.
+            if (response.error && isIdempotencyConflict(response.error)) {
+                const superseded = await supersedeStalePrePaymentDraft(client, request.idempotencyKey);
+                if (superseded) {
+                    response = await client.rpc(ORDER_DRAFT_RPC_NAME, args);
+                }
+            }
+            if (response.error)
+                throw mapRpcError(response.error);
+            const parsed = bindings.responseSchema.safeParse(response.data);
+            if (!parsed.success) {
+                throw new CommerceOrderDraftInvalidResponseError();
+            }
+            return parsed.data;
+        },
+    };
+}
+/**
+ * Best-effort supersede of a stale pre-payment draft for this idempotency key.
+ * Any failure returns false so the original conflict is preserved (fail-closed to
+ * the existing conflict path — never masks a real error as a fresh draft).
+ */
+async function supersedeStalePrePaymentDraft(client, idempotencyKey) {
+    try {
+        const { data, error } = await client.rpc(ORDER_DRAFT_SUPERSEDE_RPC_NAME, {
+            p_idempotency_key: idempotencyKey,
+        });
+        if (error)
+            return false;
+        return data === true;
+    }
+    catch {
+        return false;
+    }
+}
+function mapRpcError(error) {
+    const catalogReason = ["commerce_order_draft_catalog_head_moved", "commerce_order_draft_catalog_anchor_missing", "commerce_order_draft_offer_membership_refused"]
+        .find((reason) => [error.message, error.details, error.hint].some((value) => value?.includes(reason)));
+    if (catalogReason)
+        return new CommerceOrderDraftConflictError("Commerce catalog admission changed", {
+            reason: catalogReason, code: error.code, boundary: ORDER_DRAFT_RPC_NAME,
+        });
+    if (isPromotionPriceChanged(error)) {
+        return new CommerceOrderDraftPriceChangedError("Commerce order draft promotion changed", {
+            code: error.code,
+            boundary: ORDER_DRAFT_RPC_NAME,
+            reason: "promotion_code_unavailable",
+        });
+    }
+    if (isIdempotencyConflict(error)) {
+        return new CommerceOrderDraftConflictError("Commerce order draft idempotency conflict", {
+            code: error.code,
+            boundary: ORDER_DRAFT_RPC_NAME,
+        });
+    }
+    return new CommerceOrderDraftPersistenceError("Commerce order draft RPC failed", {
+        code: error.code,
+        boundary: ORDER_DRAFT_RPC_NAME,
+    });
+}
+function isPromotionPriceChanged(error) {
+    const searchable = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+    return [
+        "promotion_code_global_limit_reached",
+        "promotion_code_customer_limit_reached",
+        "promotion_code_not_active",
+        "promotion_code_not_found",
+        "promotion_code_definition_changed",
+        "promotion_code_snapshot_revision_mismatch",
+    ].some((reason) => searchable.includes(reason));
+}
+function isIdempotencyConflict(error) {
+    const searchable = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+    return (error.code === "23505" ||
+        searchable.includes("commerce_order_draft_idempotency_conflict"));
+}

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

@@ -0,0 +1,131 @@
+import type { PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutJourney, CheckoutKind, CommerceOrderDraftWritePort, CommerceCheckoutRuntimePort } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+import type { CheckoutPaymentExecution } from "./commerceCheckoutProviderPayment.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+export interface CheckoutJourneyRuntimeRequest<Snapshot, PaymentExecution extends CheckoutPaymentExecution, Provider extends string = string, Flow extends string = string, MethodKind extends string = string, RecurringModel extends string = string> {
+    idempotencyKey: string;
+    paymentAttemptSequence?: number;
+    orderDraft: {
+        orderId: string;
+        status: "draft";
+        paymentStatus: "not_started";
+        idempotencyKey: string;
+        quoteSnapshot: Snapshot;
+        replayed: boolean;
+    };
+    mode: "one_time" | "subscription_cycle";
+    saveForFutureUse: boolean;
+    clientId: string;
+    shippingAddressId: string;
+    paymentProvider: Provider;
+    returnContext: "public" | "account";
+    providerFlow: Flow;
+    paymentMethodRef?: string;
+    paymentMethodAliasType?: MethodKind;
+    paymentMethodRecurringModel?: RecurringModel;
+    paymentExecution?: PaymentExecution;
+    declaredBankId?: string;
+    providerPayer?: {
+        email: string;
+        name: string;
+        ip?: string | null;
+        userAgent?: string | null;
+    };
+    metadata: Record<string, unknown>;
+}
+export interface CheckoutJourneyRuntimeResponse<Provider extends string = string> {
+    runtime: {
+        orderId: string;
+        payment: {
+            paymentIntentId: string;
+            paymentAttemptId: string | null;
+            status: string;
+            attemptStatus: string | null;
+            provider: Provider;
+            continuationActionOrigin?: "fresh_execution" | null;
+            providerClientSecret?: string | null;
+            providerAttemptId?: string | null;
+            providerRedirectUrl?: string | null;
+            providerNextActionKind?: string | null;
+        };
+    };
+}
+export interface CheckoutJourneyResultRequest {
+    idempotencyKey: string;
+    orderId: string;
+    paymentIntentId: string;
+    resultStatus: "succeeded";
+    occurredAt: string;
+}
+export interface CheckoutPaymentStartedEvent {
+    email: string;
+    clientId: string;
+    orderId: string;
+    paymentIntentId: string;
+}
+export type CheckoutStage = "quote" | "order_draft" | "start_runtime" | "account_link" | "apply_payment_result";
+export type CheckoutStageRecorder = <T>(stage: CheckoutStage, operation: () => Promise<T>) => Promise<T>;
+export interface OrchestratedCheckoutResult<Snapshot, Provider extends string = string> {
+    orderId: string;
+    paymentIntentId: string;
+    paymentAttemptId: string | null;
+    paymentAttemptStatus?: string | null;
+    runtimePaymentStatus?: string;
+    executionRail: Provider;
+    continuationActionOrigin: "fresh_execution" | null;
+    providerClientSecret: string | null;
+    providerPaymentId: string | null;
+    providerRedirectUrl: string | null;
+    providerNextActionKind: string | null;
+    quoteSnapshot: Snapshot;
+    status: "paid" | "processing" | "failed";
+}
+export type PaidOrderOrchestrationDeps<Provisioned, Request, Snapshot, Draft, Extension, Runtime, Settlement, PaymentExecution extends CheckoutPaymentExecution, Provider extends string = string, Flow extends string = string, MethodKind extends string = string, RecurringModel extends string = string> = {
+    provisioned: Provisioned;
+    checkoutKind: CheckoutKind;
+    quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+    orderDraftPort: CommerceOrderDraftWritePort<{
+        idempotencyKey: string;
+        quoteSnapshot: Snapshot;
+    }, Draft>;
+    runtimePort: CommerceCheckoutRuntimePort<CheckoutJourneyRuntimeRequest<Snapshot, PaymentExecution, Provider, Flow, MethodKind, RecurringModel> & Extension, Runtime, CheckoutJourneyResultRequest, Settlement>;
+    paymentProvider?: Provider;
+    saveForFutureUse?: boolean;
+    paymentAttemptSequence?: number;
+    returnContext?: "public" | "account";
+    paymentExecution?: PaymentExecution;
+    declaredBankId?: string;
+    paymentMethodRef?: string;
+    paymentMethodAliasType?: MethodKind;
+    paymentMethodRecurringModel?: RecurringModel;
+    quoteSnapshot?: Snapshot;
+    providerPayer?: {
+        email: string;
+        name: string;
+        ip?: string | null;
+        userAgent?: string | null;
+    };
+    onPaymentStarted?: (event: CheckoutPaymentStartedEvent) => Promise<void>;
+    recordStage?: CheckoutStageRecorder;
+    now: () => Date;
+};
+export declare function createPaidOrderOrchestration<Provisioned extends {
+    clientId: string;
+    addressId: string;
+}, Request, Snapshot extends CheckoutQuoteSnapshot, Draft extends {
+    orderDraft: {
+        orderId: string;
+    };
+}, Extension extends object, Runtime extends CheckoutJourneyRuntimeResponse<Provider>, Settlement, PaymentExecution extends CheckoutPaymentExecution, Provider extends string, Flow extends string, MethodKind extends string = string, RecurringModel extends string = string>(bindings: {
+    defaultPaymentProvider: Provider;
+    rehearsalPaymentProvider: Provider;
+    confirmationProvider: Provider;
+    missingConfirmationMessage: string;
+    providerFlowFor(provider: Provider, execution: PaymentExecution | undefined): Flow;
+    runtimeRequestExtension(provisioned: Provisioned): Extension;
+    mapStartRuntimeFailure(error: unknown, draftOrderId: string): CheckoutOrchestrationError;
+}): {
+    orchestrateCheckoutJourney: (deps: PaidOrderOrchestrationDeps<Provisioned, Request, Snapshot, Draft, Extension, Runtime, Settlement, PaymentExecution, Provider, Flow, MethodKind, RecurringModel>, journey: CheckoutJourney<Request, PricingPolicySnapshot>) => Promise<OrchestratedCheckoutResult<Snapshot, Provider>>;
+};

package/dist/commerce/server/commercePaidOrderOrchestration.js

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