@openlup/platform 0.26.0 → 0.27.0

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

@@ -0,0 +1,133 @@
+import type { z } from "zod";
+import type { FinalizedCheckoutOrder } from "../contracts/index.js";
+type ProviderAttemptDispatchState = "not_dispatched" | "refused" | "unknown";
+export interface CheckoutAttemptFailureFacts extends Error {
+    paymentAttemptId: string | null;
+    phase: string;
+    dispatchState: ProviderAttemptDispatchState;
+}
+export interface CheckoutPreDispatchFailure extends CheckoutAttemptFailureFacts {
+    code: string;
+    retryCount: number;
+}
+export interface CheckoutInFlightFailure extends CheckoutAttemptFailureFacts {
+    code: string;
+}
+export interface CheckoutUncertainFailure<Diagnostic> extends CheckoutAttemptFailureFacts {
+    errorCode: string;
+    failureDiagnostic: Diagnostic | null;
+}
+interface ReopenPaymentPort<Evidence> {
+    reopenInteractivePreparedAttempt?(input: {
+        idempotencyKey: string;
+        paymentIntentId: string;
+        paymentAttemptId: string;
+        expectedOrderId: string;
+        expectedSubscriptionId: string | null;
+        expectedSubscriptionCycleId: string | null;
+        evidence: Evidence;
+    }): Promise<{
+        paymentAttemptId: string;
+        paymentIntentId: string;
+    }>;
+}
+export declare function createCheckoutProviderAttemptFailure<Order extends FinalizedCheckoutOrder<string>, Reservation, Response, Diagnostic, PreDispatch extends CheckoutPreDispatchFailure, InFlight extends CheckoutInFlightFailure, Uncertain extends CheckoutUncertainFailure<Diagnostic>, Evidence>(bindings: {
+    trustedPreDispatchEvidence(error: PreDispatch): Evidence | null;
+    isPreDispatch(error: unknown): error is PreDispatch;
+    isInFlight(error: unknown): error is InFlight;
+    isUncertain(error: unknown): error is Uncertain;
+    providerAttemptFailureLogFields(error: {
+        paymentAttemptId: string | null;
+        phase: string;
+        code: string;
+        dispatchState: ProviderAttemptDispatchState;
+        retryCount: number;
+        failureDiagnostic: Diagnostic | null;
+    }): unknown;
+    responseSchema: z.ZodType<Response>;
+    runtimeResponseExtension(order: Order): object;
+    contractVersion: string;
+}): {
+    CheckoutProviderAttemptFailure: {
+        new (error: PreDispatch | InFlight | Uncertain): {
+            readonly paymentAttemptId: string | null;
+            readonly phase: string;
+            readonly code: string;
+            readonly dispatchState: ProviderAttemptDispatchState;
+            readonly retryCount: number;
+            readonly failureDiagnostic: Diagnostic | null;
+            readonly orderIdForCompensation: string | null;
+            readonly reason: string | null;
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+        prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+        stackTraceLimit: number;
+    };
+    checkoutProviderAttemptFailure: (error: unknown) => {
+        readonly paymentAttemptId: string | null;
+        readonly phase: string;
+        readonly code: string;
+        readonly dispatchState: ProviderAttemptDispatchState;
+        readonly retryCount: number;
+        readonly failureDiagnostic: Diagnostic | null;
+        readonly orderIdForCompensation: string | null;
+        readonly reason: string | null;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    } | null;
+    logCheckoutProviderAttemptFailure: (error: {
+        readonly paymentAttemptId: string | null;
+        readonly phase: string;
+        readonly code: string;
+        readonly dispatchState: ProviderAttemptDispatchState;
+        readonly retryCount: number;
+        readonly failureDiagnostic: Diagnostic | null;
+        readonly orderIdForCompensation: string | null;
+        readonly reason: string | null;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    }) => void;
+    trustedPreDispatchEvidence: (error: PreDispatch) => Evidence | null;
+    buildReopenedPreparedAttemptResponse: (input: {
+        order: Order;
+        reservations: Reservation[];
+        intent: {
+            paymentIntentId: string;
+            paymentId: string;
+        };
+        paymentAttemptId: string;
+        provider: string;
+    }) => Response;
+    reopenExhaustedPreDispatchAttempt: (input: {
+        error: PreDispatch;
+        paymentPort: ReopenPaymentPort<Evidence>;
+        paymentExecutionIdempotencyKey: string;
+        order: Order;
+        reservations: Reservation[];
+        intent: {
+            paymentIntentId: string;
+            paymentId: string;
+        };
+        provider: string;
+    }) => Promise<Response>;
+    reopenExhaustedPreDispatchRecoveryAttempt: (input: {
+        error: PreDispatch;
+        paymentPort: ReopenPaymentPort<Evidence>;
+        paymentExecutionIdempotencyKey: string;
+        paymentIntentId: string;
+        order: {
+            orderId: string;
+            subscriptionId: string | null;
+            subscriptionCycleId: string | null;
+        };
+    }) => Promise<boolean>;
+};
+export {};

package/dist/commerce/server/commerceProviderAttemptFailure.js

@@ -0,0 +1,175 @@
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+export function createCheckoutProviderAttemptFailure(bindings) {
+    class CheckoutProviderAttemptFailure extends CheckoutOrchestrationError {
+        paymentAttemptId;
+        phase;
+        code;
+        dispatchState;
+        retryCount;
+        failureDiagnostic;
+        constructor(error) {
+            const notDispatched = bindings.isPreDispatch(error);
+            super(notDispatched
+                ? "start_runtime: provider transaction was not dispatched"
+                : "start_runtime: provider attempt remains in flight", null, notDispatched ? "provider_attempt_not_dispatched" : "provider_attempt_in_flight");
+            this.name = "CheckoutProviderAttemptFailure";
+            this.paymentAttemptId = error.paymentAttemptId;
+            this.phase = error.phase;
+            this.code = bindings.isUncertain(error) ? error.errorCode : error.code;
+            this.dispatchState = error.dispatchState;
+            this.retryCount = bindings.isPreDispatch(error) ? error.retryCount : 0;
+            this.failureDiagnostic = bindings.isUncertain(error)
+                ? error.failureDiagnostic
+                : null;
+        }
+    }
+    function checkoutProviderAttemptFailure(error) {
+        if (bindings.isInFlight(error) ||
+            bindings.isPreDispatch(error) ||
+            bindings.isUncertain(error)) {
+            return new CheckoutProviderAttemptFailure(error);
+        }
+        return null;
+    }
+    function logCheckoutProviderAttemptFailure(error) {
+        console.error("checkout_provider_attempt_failure", JSON.stringify(bindings.providerAttemptFailureLogFields(error)));
+    }
+    const trustedPreDispatchEvidence = bindings.trustedPreDispatchEvidence;
+    function buildReopenedPreparedAttemptResponse(input) {
+        return bindings.responseSchema.parse({
+            contractVersion: bindings.contractVersion,
+            runtime: {
+                orderId: input.order.orderId,
+                orderRef: input.order.orderRef,
+                mode: input.order.mode,
+                clientId: input.order.clientId,
+                ...bindings.runtimeResponseExtension(input.order),
+                shippingAddressId: input.order.shippingAddressId,
+                total: input.order.total,
+                finalizedReplayed: input.order.replayed,
+                reservations: input.reservations,
+                payment: {
+                    paymentIntentId: input.intent.paymentIntentId,
+                    paymentId: input.intent.paymentId,
+                    paymentAttemptId: input.paymentAttemptId,
+                    status: "failed",
+                    attemptStatus: "failed",
+                    provider: input.provider,
+                    providerAttemptId: null,
+                    providerClientSecret: null,
+                    providerRedirectUrl: null,
+                    providerNextActionKind: null,
+                    continuationActionOrigin: null,
+                },
+                readiness: {
+                    omsEligibility: { allowed: false, reason: "order_not_paid" },
+                    fulfillmentCreate: { allowed: false, reason: "order_not_paid", omsReason: "order_not_paid" },
+                },
+                nextAction: { kind: "await_hidden_payment_result", provider: input.provider },
+            },
+        });
+    }
+    function preDispatchReopenGate(error, paymentPort) {
+        const evidence = trustedPreDispatchEvidence(error);
+        const paymentAttemptId = error.paymentAttemptId;
+        const reopen = paymentPort.reopenInteractivePreparedAttempt;
+        if (!evidence || !paymentAttemptId || typeof reopen !== "function") {
+            logPreDispatchReopenFailure(error, "capability_unavailable");
+            return null;
+        }
+        return { paymentAttemptId, evidence, reopen };
+    }
+    async function writePreDispatchReopen(input) {
+        const { gate, identity } = input;
+        const request = {
+            idempotencyKey: `${input.paymentExecutionIdempotencyKey}:reopen-not-dispatched`,
+            paymentIntentId: identity.paymentIntentId,
+            paymentAttemptId: gate.paymentAttemptId,
+            expectedOrderId: identity.orderId,
+            expectedSubscriptionId: identity.subscriptionId,
+            expectedSubscriptionCycleId: identity.subscriptionCycleId,
+            evidence: gate.evidence,
+        };
+        const call = async () => {
+            const result = await gate.reopen.call(input.paymentPort, request);
+            if (result.paymentAttemptId !== gate.paymentAttemptId || result.paymentIntentId !== identity.paymentIntentId) {
+                throw new Error("interactive_prepared_attempt_reopen_identity_mismatch");
+            }
+        };
+        try {
+            await call();
+            return true;
+        }
+        catch {
+            console.error("provider_attempt_predispatch_reopen_retry", JSON.stringify({
+                paymentAttemptId: gate.paymentAttemptId,
+                retryOrdinal: 1,
+            }));
+            try {
+                await call();
+                return true;
+            }
+            catch {
+                logPreDispatchReopenFailure(input.error, "rpc_unavailable");
+                return false;
+            }
+        }
+    }
+    async function reopenExhaustedPreDispatchAttempt(input) {
+        const gate = preDispatchReopenGate(input.error, input.paymentPort);
+        if (!gate)
+            throw input.error;
+        // Build and validate the response before the mutation. No fallible work may
+        // follow a successful reopen, or a schema/readiness error could compensate a
+        // now-payable order whose old provider attempt is already terminal.
+        const response = buildReopenedPreparedAttemptResponse({
+            order: input.order,
+            reservations: input.reservations,
+            intent: input.intent,
+            paymentAttemptId: gate.paymentAttemptId,
+            provider: input.provider,
+        });
+        const reopened = await writePreDispatchReopen({
+            gate,
+            error: input.error,
+            paymentPort: input.paymentPort,
+            paymentExecutionIdempotencyKey: input.paymentExecutionIdempotencyKey,
+            identity: {
+                paymentIntentId: input.intent.paymentIntentId,
+                orderId: input.order.orderId,
+                subscriptionId: input.order.subscriptionId,
+                subscriptionCycleId: input.order.subscriptionCycleId,
+            },
+        });
+        if (!reopened)
+            throw input.error;
+        return response;
+    }
+    async function reopenExhaustedPreDispatchRecoveryAttempt(input) {
+        const gate = preDispatchReopenGate(input.error, input.paymentPort);
+        if (!gate)
+            return false;
+        return writePreDispatchReopen({
+            gate,
+            error: input.error,
+            paymentPort: input.paymentPort,
+            paymentExecutionIdempotencyKey: input.paymentExecutionIdempotencyKey,
+            identity: {
+                paymentIntentId: input.paymentIntentId,
+                orderId: input.order.orderId,
+                subscriptionId: input.order.subscriptionId,
+                subscriptionCycleId: input.order.subscriptionCycleId,
+            },
+        });
+    }
+    function logPreDispatchReopenFailure(error, reason) {
+        console.error("provider_attempt_predispatch_reopen_failed", JSON.stringify({
+            paymentAttemptId: error.paymentAttemptId,
+            phase: error.phase,
+            code: error.code,
+            dispatchState: error.dispatchState,
+            reason,
+        }));
+    }
+    return { CheckoutProviderAttemptFailure, checkoutProviderAttemptFailure, logCheckoutProviderAttemptFailure, trustedPreDispatchEvidence, buildReopenedPreparedAttemptResponse, reopenExhaustedPreDispatchAttempt, reopenExhaustedPreDispatchRecoveryAttempt };
+}

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

@@ -0,0 +1,41 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { z } from "zod";
+import { type CommerceReturnsPort, type ReturnRequestCreateInput } from "../commerceReturnsPort.js";
+type AdminAuthResult = {
+    ok: true;
+    userId: string;
+} | {
+    ok: false;
+    code: "UNAUTHORIZED" | "FORBIDDEN" | "INTERNAL";
+    message: string;
+};
+type CustomerAuthResult = {
+    ok: true;
+    userId: string;
+} | {
+    ok: false;
+    code: "UNAUTHORIZED";
+    message: string;
+};
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare function createCustomerReturnRequestHandler(deps: {
+    responder: BffResponder;
+    port: Pick<CommerceReturnsPort<string>, "createRequest">;
+    requestSchema?: z.ZodType<ReturnRequestCreateInput<string>>;
+    authenticateUser: () => Promise<CustomerAuthResult>;
+    enabled: () => boolean;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare function createAdminReturnApproveHandler(deps: {
+    responder: BffResponder;
+    authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>;
+    port: Pick<CommerceReturnsPort, "approve">;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare function createAdminReturnRejectHandler(deps: {
+    responder: BffResponder;
+    authorizeAdmin: (req: HttpRequest) => Promise<AdminAuthResult>;
+    port: Pick<CommerceReturnsPort, "reject">;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export {};

package/dist/commerce/server/commerceReturnsHandlers.js

@@ -0,0 +1,100 @@
+// BFF handlers for the Commerce Returns R0 control plane:
+//   - customer: POST /api/bff/commerce/returns/request  (bearer-authenticated)
+//   - admin:    POST /api/bff/admin/returns/approve|reject
+// Each validates with the returns port schemas and calls the service-role port,
+// mapping RPC input/state errors (ERRCODE 22023) to 400s.
+import { returnApproveSchema, returnRejectSchema, returnRequestCreateSchema, } from "../commerceReturnsPort.js";
+// RPC validation/state errors that map to a 400 (vs an unexpected 500).
+const CLIENT_ERROR = /_invalid_input|_invalid_state|_not_found|_not_returnable|_quantity_exceeds_ordered|_line_not_in_order/;
+function methodGuard(req, res, responder) {
+    const { sendBffError } = responder;
+    if (req.method !== "POST") {
+        sendBffError(res, "METHOD_NOT_ALLOWED", "Method not allowed", { status: 405 });
+        return false;
+    }
+    return true;
+}
+function mapExecuteError(res, error, responder) {
+    const { sendBffError } = responder;
+    const message = error instanceof Error ? error.message : "return_operation_failed";
+    if (CLIENT_ERROR.test(message)) {
+        sendBffError(res, "BAD_REQUEST", "Return request rejected", { details: { reason: message } });
+        return;
+    }
+    sendBffError(res, "INTERNAL", "Return operation failed");
+}
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createCustomerReturnRequestHandler(deps) {
+    const { sendBffError, sendBffSuccess } = deps.responder;
+    return async function handler(req, res) {
+        if (!methodGuard(req, res, deps.responder))
+            return;
+        if (!deps.enabled()) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Returns are not enabled", {
+                details: { feature: "commerce_returns", featureFlag: "COMMERCE_RETURNS_ENABLED", reason: "feature_flag_disabled" },
+            });
+            return;
+        }
+        const auth = await deps.authenticateUser();
+        if (!auth.ok) {
+            sendBffError(res, "UNAUTHORIZED", "Sign in required to request a return");
+            return;
+        }
+        const parsed = (deps.requestSchema ?? returnRequestCreateSchema).safeParse(req.body ?? {});
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid return request", { details: parsed.error.flatten() });
+            return;
+        }
+        try {
+            const result = await deps.port.createRequest({ ...parsed.data, requestedBy: auth.userId });
+            sendBffSuccess(res, result);
+        }
+        catch (error) {
+            mapExecuteError(res, error, deps.responder);
+        }
+    };
+}
+function createAdminReturnHandler(deps) {
+    const { sendBffError, sendBffSuccess } = deps.responder;
+    return async function handler(req, res) {
+        if (!methodGuard(req, res, deps.responder))
+            return;
+        const auth = await deps.authorizeAdmin(req);
+        if (auth.ok === false) {
+            sendBffError(res, auth.code, auth.message);
+            return;
+        }
+        const parsed = deps.requestSchema.safeParse(req.body ?? {});
+        if (parsed.success === false) {
+            sendBffError(res, "BAD_REQUEST", deps.invalidMessage, { details: parsed.error.flatten() });
+            return;
+        }
+        try {
+            const result = await deps.execute(parsed.data, auth.userId);
+            sendBffSuccess(res, result);
+        }
+        catch (error) {
+            mapExecuteError(res, error, deps.responder);
+        }
+    };
+}
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createAdminReturnApproveHandler(deps) {
+    return createAdminReturnHandler({
+        responder: deps.responder,
+        authorizeAdmin: deps.authorizeAdmin,
+        requestSchema: returnApproveSchema,
+        invalidMessage: "Invalid return approve request",
+        execute: (request, actorUserId) => deps.port.approve({ ...request, actorUserId }),
+    });
+}
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createAdminReturnRejectHandler(deps) {
+    return createAdminReturnHandler({
+        responder: deps.responder,
+        authorizeAdmin: deps.authorizeAdmin,
+        requestSchema: returnRejectSchema,
+        invalidMessage: "Invalid return reject request",
+        execute: (request, actorUserId) => deps.port.reject({ ...request, actorUserId }),
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { z } from "zod";
+import type { CommerceCheckoutRuntimeOrderPort } from "../contracts/runtimePorts.js";
+import type { RpcError } from "../contracts/omsTypes.js";
+export interface ManagedCommerceRuntimeClient {
+    rpc(functionName: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: RpcError | null;
+    }>;
+}
+export declare function createManagedCommerceRuntimeOrderPort<Request, Order extends {
+    items: unknown[];
+}>(client: ManagedCommerceRuntimeClient, bindings: {
+    finalizeArgs(request: Request): Record<string, unknown>;
+    responseEnvelopeSchema: z.ZodType;
+}): CommerceCheckoutRuntimeOrderPort<Request, Order>;
+export declare function mapRpcError(error: RpcError): Error;

package/dist/commerce/server/commerceRuntimePort.js

@@ -0,0 +1,57 @@
+import { CommerceRuntimeConflictError, CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+const FINALIZE_RPC_NAME = "commerce_finalize_order_for_checkout";
+export function createManagedCommerceRuntimeOrderPort(client, bindings) {
+    return {
+        async finalizeOrderForCheckout(request) {
+            const { data, error } = await client.rpc(FINALIZE_RPC_NAME, bindings.finalizeArgs(request));
+            if (error)
+                throw mapRpcError(error);
+            return parseFinalizeResponse(data);
+        },
+    };
+    function parseFinalizeResponse(data) {
+        const parsed = bindings.responseEnvelopeSchema.safeParse(data);
+        if (!parsed.success || typeof data !== "object" || data === null) {
+            throw new CommerceRuntimePersistenceError("Commerce finalize response invalid");
+        }
+        const finalizedOrder = data.finalizedOrder;
+        if (!finalizedOrder || typeof finalizedOrder !== "object") {
+            throw new CommerceRuntimePersistenceError("Commerce finalize response invalid");
+        }
+        const order = finalizedOrder;
+        if (!Array.isArray(order.items) || order.items.length === 0) {
+            throw new CommerceRuntimePersistenceError("Commerce finalize response missing order items");
+        }
+        return order;
+    }
+}
+export function mapRpcError(error) {
+    // Diagnostic only: preserve constraint/cause signal without raw payload values.
+    console.error("commerce_runtime_finalize_rpc_error", JSON.stringify({
+        code: error.code,
+        message: safeCommerceDiagnosticValue(error.message),
+        details: safeCommerceDiagnosticValue(error.details),
+        hint: safeCommerceDiagnosticValue(error.hint),
+    }));
+    const text = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+    if (text.includes("acquisition_terms_changed")) {
+        return new CommerceRuntimeConflictError("Acquisition terms changed", {
+            code: error.code, reason: "acquisition_terms_changed",
+        });
+    }
+    if (text.includes("commerce_runtime_finalize_journey_consumed")) {
+        // The journey key already finalized a different request (order completed,
+        // possibly out-of-band via checkout recovery). The client must rotate its
+        // journey key — a retry under the same key can never succeed.
+        return new CommerceRuntimeConflictError("Commerce checkout journey already completed", {
+            code: error.code,
+            reason: "journey_consumed",
+        });
+    }
+    if (error.code === "23505" ||
+        /commerce_runtime_finalize_.*(?:conflict|not_found|not_owned|mismatch|missing|requires|unknown|invalid|not_draft)/.test(text)) {
+        return new CommerceRuntimeConflictError("Commerce order finalize conflict", { code: error.code });
+    }
+    return new CommerceRuntimePersistenceError("Commerce order finalize RPC failed", { code: error.code });
+}

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

@@ -0,0 +1,98 @@
+import type { z } from "zod";
+import type { FinalizedCheckoutOrder, CommerceCheckoutRuntimeOrderPort, InventoryCheckoutReservationPort, CommerceRuntimeReadinessPort } from "../contracts/index.js";
+import type { CheckoutRuntimeRequest, CheckoutRuntimeExecutionInput, CheckoutRuntimeExecutionResult, CheckoutRuntimeExecutionPort, CheckoutRuntimePaymentPort, CheckoutRuntimeResultRequest, CheckoutRuntimeResponse } from "./checkoutRuntimeTypes.js";
+export declare function createCommerceRuntimeService<Request extends CheckoutRuntimeRequest, Order extends FinalizedCheckoutOrder<string>, Reservation, PaymentPort extends CheckoutRuntimePaymentPort, Execution extends CheckoutRuntimeExecutionResult, Transient, ExecutionPort extends CheckoutRuntimeExecutionPort<Execution, Transient, Request["providerFlow"], NonNullable<Request["paymentMethodAliasType"]>, NonNullable<Request["paymentMethodRecurringModel"]>>, PreparedPort, PreDispatch, Readiness, Response extends CheckoutRuntimeResponse, ResultRequest extends CheckoutRuntimeResultRequest, ResultResponse, PreparedProvider extends Request["paymentProvider"]>(bindings: {
+    defaultPaymentProvider: Request["paymentProvider"];
+    defaultProviderFlow: Request["providerFlow"];
+    preparedRecurringModel(request: Request): string | undefined;
+    contractVersion: string;
+    resultResponseSchema: z.ZodType<ResultResponse>;
+    defaultExecutionPort: ExecutionPort;
+    executionSubject(order: Order): object;
+    paymentMetadataExtension(order: Order): object;
+    buildProviderAttemptIdentity(input: {
+        provider: Request["paymentProvider"];
+        localExecutionIdempotencyKey: string;
+        paymentIntentId: string;
+        amountMinor: number;
+        currency: string;
+        mode: "one_time" | "subscription_cycle";
+        orderRef: string;
+    }): {
+        providerIdempotencyKey: string;
+        providerRequestFingerprint: string;
+    };
+    transientProviderInput(execution: Request["paymentExecution"]): Transient | null;
+    requiresPreparedProviderAttempt(provider: Request["paymentProvider"]): provider is PreparedProvider;
+    preparedProviderAttemptPort(port: PaymentPort, provider: Request["paymentProvider"]): PreparedPort;
+    executePreparedProviderAttempt(input: {
+        paymentPort: PreparedPort;
+        executionPort: ExecutionPort;
+        provider: PreparedProvider;
+        paymentIntentId: string;
+        executionInput: CheckoutRuntimeExecutionInput<Transient, Request["providerFlow"], NonNullable<Request["paymentMethodAliasType"]>, NonNullable<Request["paymentMethodRecurringModel"]>>;
+        prepareIdempotencyKey: string;
+        finalizeIdempotencyKey: string;
+        providerIdempotencyKey: string;
+        providerRequestFingerprint: string;
+        providerFlow: string;
+        paymentMethodRef?: string | null;
+        prepareRequestPayload: Record<string, unknown>;
+    }): Promise<{
+        execution: Execution;
+        attempt: {
+            paymentAttemptId: string;
+            status: string;
+        };
+    }>;
+    isPreDispatch(error: unknown): error is PreDispatch;
+    reopenExhaustedPreDispatchAttempt(input: {
+        error: PreDispatch;
+        paymentPort: PaymentPort;
+        paymentExecutionIdempotencyKey: string;
+        order: Order;
+        reservations: Reservation[];
+        intent: {
+            paymentIntentId: string;
+            paymentId: string;
+        };
+        provider: Request["paymentProvider"];
+    }): Promise<Response>;
+    preserveProviderDispatchUncertainty<T>(operation: () => Promise<T>, paymentAttemptId: string): Promise<T>;
+    recordPaymentAttempt(port: PaymentPort, input: {
+        idempotencyKey: string;
+        paymentIntentId: string;
+        execution: Execution;
+    }): Promise<{
+        paymentAttemptId: string;
+        status: string;
+    }>;
+    buildStartedRuntimeResponse(input: {
+        paymentExecutionIdempotencyKey: string;
+        order: Order;
+        reservations: Reservation[];
+        intent: {
+            paymentIntentId: string;
+            paymentId: string;
+            status: string;
+        };
+        execution: Execution;
+        attempt: {
+            paymentAttemptId: string;
+            status: string;
+        };
+        continuationActionOrigin: "fresh_execution" | null;
+        paymentPort: PaymentPort;
+        readinessPort: CommerceRuntimeReadinessPort<Readiness>;
+    }): Promise<Response>;
+}): ({ orderPort, inventoryPort, paymentPort, readinessPort, executionPort, resolveExecutionPort, }: {
+    orderPort: CommerceCheckoutRuntimeOrderPort<Request, Order>;
+    inventoryPort: InventoryCheckoutReservationPort<Order, "created", Reservation>;
+    paymentPort: PaymentPort;
+    readinessPort: CommerceRuntimeReadinessPort<Readiness>;
+    executionPort?: ExecutionPort;
+    resolveExecutionPort?: (provider: string) => ExecutionPort;
+}) => {
+    startRuntime: (request: Request, resolvedExecutionPort?: ExecutionPort) => Promise<Response>;
+    applyPaymentResult: (request: ResultRequest) => Promise<ResultResponse>;
+};