@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/server/commerceCheckoutTiming.ts

@@ -0,0 +1,53 @@
+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 type CheckoutTimingStage =
+  | CheckoutStage
+  | "rate_limit"
+  | "risk_blocklist"
+  | "persist_intent"
+  | "payment_method_ref"
+  | "customer_defaults"
+  | "total";
+
+export type CheckoutTimingOutcome = "success" | "error" | "rejected";
+
+export function createCheckoutTimingLogger(requestId: string, route: string): {
+  record: CheckoutStageRecorder & (<T>(stage: CheckoutTimingStage, operation: () => Promise<T>) => Promise<T>);
+  log: (stage: CheckoutTimingStage, outcome: CheckoutTimingOutcome) => void;
+} {
+  const totalStartedAt = Date.now();
+
+  const write = (
+    stage: CheckoutTimingStage,
+    startedAt: number,
+    outcome: CheckoutTimingOutcome,
+  ): void => {
+    console.log(JSON.stringify({
+      level: "info",
+      event: "checkout_stage",
+      request_id: requestId,
+      route,
+      stage,
+      duration_ms: Math.max(0, Date.now() - startedAt),
+      outcome,
+    }));
+  };
+
+  return {
+    async record<T>(stage: CheckoutTimingStage, operation: () => Promise<T>): Promise<T> {
+      const startedAt = Date.now();
+      try {
+        const result = await operation();
+        write(stage, startedAt, "success");
+        return result;
+      } catch (error) {
+        write(stage, startedAt, "error");
+        throw error;
+      }
+    },
+    log(stage: CheckoutTimingStage, outcome: CheckoutTimingOutcome): void {
+      write(stage, totalStartedAt, outcome);
+    },
+  };
+}

package/src/commerce/server/commerceDiagnostics.ts

@@ -0,0 +1,37 @@
+const MAX_DIAGNOSTIC_LENGTH = 240;
+
+const REDACTION_PATTERNS: Array<[RegExp, string]> = [
+  [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, "[redacted-email]"],
+  [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9_]+\b/g, "[redacted-key]"],
+  [
+    /\b(client_secret|payment_secret|secret|token|authorization|password|pass|apikey|api_key)\s*[:=]\s*["']?[^"',\s}]+/gi,
+    "$1=[redacted]",
+  ],
+  [/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [redacted]"],
+  [/\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi, "[redacted-uuid]"],
+  [/\b(?:intent|checkout|order|payment|subscription|idempotency)[-_a-z0-9]*[:=][A-Za-z0-9._:-]{12,}/gi, "[redacted-id]"],
+  [/\+?\d[\d\s().-]{7,}\d/g, "[redacted-number]"],
+];
+
+export function safeCommerceDiagnosticValue(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  let text = String(value);
+  for (const [pattern, replacement] of REDACTION_PATTERNS) {
+    text = text.replace(pattern, replacement);
+  }
+  return text.length > MAX_DIAGNOSTIC_LENGTH
+    ? `${text.slice(0, MAX_DIAGNOSTIC_LENGTH - 3)}...`
+    : text;
+}
+
+export function checkoutOrchestrationFailureDetails(reason: string | null, previewDiagnosticsEnabled = false): {
+  feature: "checkout";
+  stage: "orchestrate_order";
+  diagnosticReason?: string;
+} {
+  return {
+    feature: "checkout",
+    stage: "orchestrate_order",
+    ...(previewDiagnosticsEnabled && reason ? { diagnosticReason: reason } : {}),
+  };
+}

package/src/commerce/server/commerceOmsCancelOrderHandler.ts

@@ -0,0 +1,43 @@
+import {
+adminCommerceOrderCancelRequestSchema,
+adminCommerceOrderMarkRefundedResponseSchema,
+} from "../oms/omsContracts.js";
+import type { CommerceOmsHoldPort } from "../oms/omsPorts.js";
+import { authorize,parseOmsRequest,sendOmsMutationResponse,type BaseDeps } from "./commerceOmsHandlers.js";
+import type { OmsHandlerRequest } from "./handlerSupport.js";
+
+// This is deliberately not the fulfillment cancellation boundary. It only
+// terminalizes an unpaid commerce order; the SQL RPC owns the state-machine and
+// reservation-release side effect.
+export function createAdminCommerceOrderCancelHandler<Response>({
+  authorizeAdmin,
+  omsPort,
+  mutationsEnabled,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsHoldPort, "cancelOrder">;
+  mutationsEnabled: () => boolean;
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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 order cancellation is not enabled");
+      return;
+    }
+
+    const request = parseOmsRequest(res, respond, adminCommerceOrderCancelRequestSchema, req.body ?? {}, "Invalid admin commerce order cancellation request");
+    if (request === undefined) return;
+
+    await sendOmsMutationResponse(
+      res,
+      respond,
+      () => omsPort.cancelOrder({ ...request, actorUserId: auth.userId }),
+      adminCommerceOrderMarkRefundedResponseSchema,
+      "Admin commerce order cancellation returned invalid response",
+      "Admin commerce order cancellation failed",
+      (data) => data.status === "cancelled",
+    );
+  };
+}

package/src/commerce/server/commerceOmsControlPlaneHandlers.ts

@@ -0,0 +1,71 @@
+import type { OmsHandlerDeps,OmsHandlerRequest,OmsHandlerResponder } from "./handlerSupport.js";
+/**
+ * The `?view=control_plane_v1` read handlers. Unlike the V0 handlers in
+ * `commerceOmsHandlers.ts`, these deliberately take NO `governance` dependency and
+ * do not run `applyOmsAgentCustomerReadGate`: `commerce.oms_control_plane.v1`
+ * carries no customer identity, so the gate would audit a `customer_read` of zero
+ * customers and mask a field the strict contract forbids — and the portable
+ * `node-postgres` branch of this same contract has neither an actor kind nor an
+ * audit client to run it with. The exemption holds only while the projection stays
+ * customer-free, a precondition pinned in `omsControlPlaneReadGovernance.test.ts`.
+ */
+import {
+omsControlPlaneDetailRequestSchema,
+omsControlPlaneDetailResponseSchema,
+omsControlPlaneListRequestSchema,
+omsControlPlaneListResponseSchema,
+type CommerceOmsControlPlanePort,
+} from "../oms/omsControlPlane.js";
+
+type Deps<Response> = OmsHandlerDeps<Response> & {
+  port: CommerceOmsControlPlanePort;
+};
+
+export function createCommerceOmsControlPlaneListHandler<Response>({ authorizeAdmin, port, respond }: Deps<Response>) {
+  return async (req: OmsHandlerRequest, res: Response): Promise<void> => {
+    if (req.method !== "GET") return respond.sendMethodNotAllowed(res, ["GET"]);
+    if (!await authorize(req, res, authorizeAdmin, respond)) return;
+    const request = omsControlPlaneListRequestSchema.safeParse(req.query ?? {});
+    if (!request.success) {
+      respond.sendBffError(res, "BAD_REQUEST", "Invalid OMS control-plane list request", { details: request.error.flatten() });
+      return;
+    }
+    try {
+      const result = omsControlPlaneListResponseSchema.parse(await port.listOrders(request.data));
+      respond.sendBffSuccess(res, result);
+    } catch {
+      respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "OMS control-plane list is unavailable");
+    }
+  };
+}
+
+export function createCommerceOmsControlPlaneDetailHandler<Response>({ authorizeAdmin, port, respond }: Deps<Response>) {
+  return async (req: OmsHandlerRequest, res: Response): Promise<void> => {
+    if (req.method !== "GET") return respond.sendMethodNotAllowed(res, ["GET"]);
+    if (!await authorize(req, res, authorizeAdmin, respond)) return;
+    const request = omsControlPlaneDetailRequestSchema.safeParse(req.query ?? {});
+    if (!request.success) {
+      respond.sendBffError(res, "BAD_REQUEST", "Invalid OMS control-plane detail request", { details: request.error.flatten() });
+      return;
+    }
+    try {
+      const result = await port.getOrderDetail(request.data);
+      if (!result) return respond.sendBffError(res, "NOT_FOUND", "Commerce order not found");
+      respond.sendBffSuccess(res, omsControlPlaneDetailResponseSchema.parse(result));
+    } catch {
+      respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "OMS control-plane detail is unavailable");
+    }
+  };
+}
+
+async function authorize<Response>(
+  req: OmsHandlerRequest,
+  res: Response,
+  authorizeAdmin: Deps<Response>["authorizeAdmin"],
+  respond: OmsHandlerResponder<Response>,
+): Promise<boolean> {
+  const result = await authorizeAdmin(req);
+  if (result.ok === true) return true;
+  respond.sendBffError(res, result.code, result.message);
+  return false;
+}

package/src/commerce/server/commerceOmsHandlers.ts

@@ -0,0 +1,275 @@
+import {
+adminCommerceOrderDetailRequestSchema,
+adminCommerceOrderDetailResponseSchema,
+adminCommerceOrderHoldRequestSchema,
+adminCommerceOrderHoldResponseSchema,
+adminCommerceOrderNoteRequestSchema,
+adminCommerceOrderNoteResponseSchema,
+adminCommerceOrderReleaseHoldRequestSchema,
+adminCommerceOrderUpdateShippingAddressRequestSchema,
+adminCommerceOrderUpdateShippingAddressResponseSchema,
+adminCommerceOrdersListRequestSchema,
+adminCommerceOrdersListResponseSchema,
+} from "../oms/omsContracts.js";
+import { CommerceOmsConflictError,type CommerceOmsHoldPort,type CommerceOmsReadPort } from "../oms/omsPorts.js";
+import type { OmsHandlerDeps,OmsHandlerRequest,OmsHandlerResponder } from "./handlerSupport.js";
+import { unprojectedOmsReadGate,type OmsAdminAuthResult as AdminAuthResult } from "./handlerSupport.js";
+
+export type { OmsAdminAuthResult as AdminAuthResult } from "./handlerSupport.js";
+export type BaseDeps<Response> = OmsHandlerDeps<Response>;
+
+export function createAdminCommerceOrdersListHandler<Response>({
+  authorizeAdmin,
+  omsPort,
+  readGate,
+  listRequestSchema = adminCommerceOrdersListRequestSchema,
+  listResponseSchema = adminCommerceOrdersListResponseSchema,
+  detailResponseSchema = adminCommerceOrderDetailResponseSchema,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsReadPort, "listOrders">;
+
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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: Record<string, unknown>): Record<string, unknown> {
+  const { search, ...safe } = request;
+  return search ? { ...safe, search: "[redacted]" } : safe;
+}
+
+export function createAdminCommerceOrderDetailHandler<Response>({
+  authorizeAdmin,
+  omsPort,
+  readGate,
+  listRequestSchema = adminCommerceOrdersListRequestSchema,
+  listResponseSchema = adminCommerceOrdersListResponseSchema,
+  detailResponseSchema = adminCommerceOrderDetailResponseSchema,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsReadPort, "getOrderDetail">;
+
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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<Response>({
+  authorizeAdmin,
+  omsPort,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsHoldPort, "createHold">;
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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<Response>({
+  authorizeAdmin,
+  omsPort,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsHoldPort, "releaseHold">;
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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<Response>({
+  authorizeAdmin,
+  omsPort,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsHoldPort, "addNote">;
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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<Response>({
+  authorizeAdmin,
+  omsPort,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsHoldPort, "updateShippingAddress">;
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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<Response>(
+  req: OmsHandlerRequest,
+  res: Response,
+  authorizeAdmin: (req: OmsHandlerRequest) => Promise<AdminAuthResult>,
+  respond: OmsHandlerResponder<Response>,
+): Promise<{ ok: true; userId: string; isMachineActor?: boolean } | null> {
+  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<Response>(res: Response, respond: OmsHandlerResponder<Response>, action: () => Promise<unknown>): Promise<void> {
+  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<Response, T>(
+  res: Response,
+  respond: OmsHandlerResponder<Response>,
+  schema: { safeParse: (input: unknown) => { success: true; data: T } | { success: false; error: { flatten: () => unknown } } },
+  input: unknown,
+  message: string,
+): T | undefined {
+  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<Response, T>(
+  res: Response,
+  respond: OmsHandlerResponder<Response>,
+  action: () => Promise<unknown>,
+  schema: { safeParse: (input: unknown) => { success: true; data: T } | { success: false } },
+  invalidMessage: string,
+  failedMessage: string,
+  accept: (data: T) => boolean = () => true,
+): Promise<void> {
+  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/src/commerce/server/commerceOmsMarkRefundedHandler.ts

@@ -0,0 +1,39 @@
+import {
+adminCommerceOrderMarkRefundedRequestSchema,
+adminCommerceOrderMarkRefundedResponseSchema,
+} from "../oms/omsContracts.js";
+import type { CommerceOmsHoldPort } from "../oms/omsPorts.js";
+import { authorize,parseOmsRequest,sendOmsMutationResponse,type BaseDeps } from "./commerceOmsHandlers.js";
+import type { OmsHandlerRequest } from "./handlerSupport.js";
+
+export function createAdminCommerceOrderMarkRefundedHandler<Response>({
+  authorizeAdmin,
+  omsPort,
+  mutationsEnabled,
+  respond,
+}: BaseDeps<Response> & {
+  omsPort: Pick<CommerceOmsHoldPort, "markRefunded">;
+  mutationsEnabled: () => boolean;
+}) {
+  return async function handler(req: OmsHandlerRequest, res: Response): Promise<void> {
+    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/src/commerce/server/commerceOrderDraft.ts

@@ -0,0 +1,131 @@
+import type { z } from "zod";
+import { CommerceOrderDraftConflictError, CommerceOrderDraftInvalidResponseError, CommerceOrderDraftPersistenceError } from "../errors.js";
+import { CommerceOrderDraftPriceChangedError } from "../orderDraftErrors.js";
+import type { CommerceOrderDraftWritePort, CreateOrderDraftOptions } 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 const ORDER_DRAFT_SUPERSEDE_RPC_NAME =
+  "commerce_supersede_pre_payment_order_draft" as const;
+
+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 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> {
+  return {
+    async createOrderDraft(
+      request: Request,
+      options?: CreateOrderDraftOptions,
+    ): Promise<Response> {
+      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<Args extends Record<string, unknown>>(
+  client: CommerceOrderDraftRpcClient<Args>,
+  idempotencyKey: string,
+): Promise<boolean> {
+  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: CommerceOrderDraftRpcError): 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: CommerceOrderDraftRpcError): boolean {
+  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: CommerceOrderDraftRpcError): boolean {
+  const searchable = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+  return (
+    error.code === "23505" ||
+    searchable.includes("commerce_order_draft_idempotency_conflict")
+  );
+}