@openlup/platform 0.17.0 → 0.18.0

package/src/pricing/contracts/quote.ts

@@ -0,0 +1,106 @@
+import type { CommerceCurrency, CommerceMoney, CommerceTaxBreakdown } from "./money.js";
+import type { CommerceCodeRejectionDetail } from "./evidence.js";
+
+export const COMMERCE_CONTRACT_VERSION = "commerce.v0";
+
+export interface CommerceQuotePricingComponent {
+  scope: "line" | "order";
+  componentType: "base_unit" | "mode_discount" | "qty_tier" | "promo" | "loyalty" | "shipping" | "bundle";
+  amountMinor: number;
+  reasonCode: string;
+  reasonPayload: Record<string, unknown>;
+}
+
+/** Hosts may extend this context with their own validated policy. */
+export interface CommerceQuoteContext {
+  mode: "one_time" | "subscription";
+  cadenceDays?: number | null;
+  promoCodes: string[];
+}
+
+export interface CommerceQuoteLine {
+  sku: string;
+  productSlug: string;
+  quantity: number;
+  unitPriceGross: CommerceMoney;
+  lineSubtotalGross: CommerceMoney;
+  tax: CommerceTaxBreakdown;
+  pricingComponents?: CommerceQuotePricingComponent[];
+}
+
+export type CommercePromotionCustomerSemantic =
+  | "first_purchase_10"
+  | "first_subscription_50"
+  | "bundle_5";
+
+export interface CommerceQuoteDiscount {
+  promotionId: string;
+  code?: string | null;
+  label?: string;
+  appliesTo: "order_total" | "line" | "shipping";
+  amountOffMinor: number;
+  reasonCode: string;
+  /** Stable presentation identity for canonical offers; never inferred from an editable name. */
+  customerSemantic?: CommercePromotionCustomerSemantic;
+  promotionEngineVersion?: "promotion-engine.v2";
+  promotionCodeId?: string;
+  promotionCodeRevision?: number;
+  promotionDefinitionFingerprint?: string;
+  promotionCodeScopes?: Array<"one_time" | "subscription_initial">;
+  promotionMinimumReferenceMinor?: number;
+  promotionCodeValidTo?: string | null;
+  promotionBenefitKind?: "target_percentage" | "percentage" | "fixed_amount" | "free_shipping";
+  promotionBenefitValueBps?: number;
+  promotionBenefitValueMinor?: number;
+  floorApplied?: boolean;
+}
+
+/**
+ * Why a customer-submitted promo code did not produce a discount, surfaced so the FE
+ * can show a specific message instead of a generic "invalid". `better_price_exists` is
+ * the one non-error reason (eligible but unused because an automatic offer is equally
+ * good or better; the FE renders it neutrally); `scope_not_applicable` means the code
+ * is real but does not apply to this order type. The last two are v2-engine-only reasons.
+ */
+export type CommerceCodeRejectionReason =
+  | "not_recognized" | "already_used" | "not_eligible" | "expired"
+  | "better_price_exists" | "scope_not_applicable";
+
+export interface CommerceCodeRejection {
+  code: string;
+  reason: CommerceCodeRejectionReason;
+}
+
+export interface CommerceQuote {
+  currency: CommerceCurrency;
+  taxIncluded: true;
+  lines: CommerceQuoteLine[];
+  discounts: CommerceQuoteDiscount[];
+  pricingComponents?: CommerceQuotePricingComponent[];
+  context?: CommerceQuoteContext;
+  /** Submitted coupon codes that produced no discount, with the reason. Omitted when empty. */
+  codeRejections?: CommerceCodeRejection[];
+  /** UI-safe specifics for selected rejected codes. Omitted when no detail is available. */
+  codeRejectionDetails?: CommerceCodeRejectionDetail[];
+  subtotalGross: CommerceMoney;
+  discountTotalGross: CommerceMoney;
+  /** Gross shipping before any free-shipping promo. Optional; absent ⇒ shipping not priced (legacy/0). */
+  shippingGross?: CommerceMoney;
+  /** Gross shipping discount from a free-shipping promo (≤ shippingGross). Optional; absent ⇒ 0. */
+  shippingDiscountGross?: CommerceMoney;
+  totalGross: CommerceMoney;
+  netTotal: CommerceMoney;
+  taxTotal: CommerceMoney;
+}
+
+export interface CreateQuoteRequest {
+  mode: "one_time" | "subscription";
+  lines: import("./money.js").CartLineInput[];
+  cadenceDays?: number | null;
+  promoCodes: string[];
+}
+
+export interface CreateQuoteResponse {
+  contractVersion: typeof COMMERCE_CONTRACT_VERSION;
+  quote: Omit<CommerceQuote, "lines"> & { lines: Array<CommerceQuoteLine & { catalogFacts?: import("./provenance.js").CatalogFactsProvenance }> };
+}

package/src/pricing/dbBackedCommerceQuoteHelpers.ts

@@ -0,0 +1,256 @@
+import type { CommercePriceAuthorityResult } from "./contracts/authority.js";
+import type { CreateQuoteRequest } from "./contracts/quote.js";
+import type {
+  CommerceMoney,
+  CommerceQuotePricingComponent,
+} from "./contracts/index.js";
+import type { PricingComponent } from "@openlup/core/pricing";
+import { CommerceQuoteError } from "./quotePorts.js";
+import { splitIncludedVat } from "./quoteSchemas.js";
+import {
+  CommercePriceAuthorityError,
+  type CommercePriceAuthorityPort,
+} from "./ports.js";
+import type { PricingResolverPort, PricingMode, ResolvedPrice } from "@openlup/core/pricing";
+import type {
+  CommerceQuoteCatalogItem,
+} from "./commerceQuoteCatalogReadPort.js";
+
+/** Pure helpers for the DB-backed commerce quote port (extracted to keep the port under the LOC cap). */
+
+export interface SkuIndexEntry<Item = CommerceQuoteCatalogItem> {
+  item: Item;
+}
+
+export async function buildSkuIndex<Item extends CommerceQuoteCatalogItem>(
+  quoteCatalogReadPort: { listQuoteCatalogItems(): Promise<Item[]> },
+): Promise<Map<string, SkuIndexEntry<Item>>> {
+  const items = await quoteCatalogReadPort.listQuoteCatalogItems();
+  return new Map(
+    items.map((item) => [item.skuCode, { item }] as const),
+  );
+}
+
+export function eligibleQtyForMode(request: CreateQuoteRequest, mode: Exclude<PricingMode, "any">): number {
+  return request.lines
+    .filter((line) => !line.isAddon)
+    .filter((line) => (line.modeAtLine ?? request.mode) === mode)
+    .reduce((sum, line) => sum + line.quantity, 0);
+}
+
+export async function resolveOneTimeComparison(input: {
+  pricingResolverPort: PricingResolverPort;
+  variantId: string;
+  lineQty: number;
+  eligibleCartQty: number;
+  regionCode: string;
+  currency: string;
+  atTime: string;
+}): Promise<ResolvedPrice | null> {
+  return input.pricingResolverPort.resolvePrice({
+    variantId: input.variantId,
+    mode: "one_time",
+    lineQty: input.lineQty,
+    eligibleCartQty: input.eligibleCartQty,
+    regionCode: input.regionCode,
+    currency: input.currency,
+    atTime: input.atTime,
+  });
+}
+
+export interface StrictQuotePriceResolution {
+  base: ResolvedPrice;
+  resolved: ResolvedPrice;
+  policy?: {
+    policyRevisionId: string;
+    policyDigest: string;
+  };
+}
+
+/**
+ * Strict authority quotes require one exact one-time base anchor. Subscription money is either
+ * derived by a validated policy or taken from the authority's explicit legacy
+ * subscription observation; this layer never calls the generic resolver.
+ */
+export async function resolveStrictQuotePrice(input: {
+  commercePriceAuthorityPort: CommercePriceAuthorityPort;
+  variantId: string;
+  mode: Exclude<PricingMode, "any">;
+  regionCode: string;
+  currency: string;
+  channel: string;
+  atTime: string;
+}): Promise<StrictQuotePriceResolution> {
+  try {
+    const authority = await input.commercePriceAuthorityPort.resolvePrice({
+      variantId: input.variantId,
+      mode: input.mode,
+      regionCode: input.regionCode,
+      currency: input.currency,
+      channel: input.channel,
+      atTime: input.atTime,
+    });
+    return strictQuotePriceResolution(authority, input.mode);
+  } catch (error) {
+    if (error instanceof CommercePriceAuthorityError) {
+      throw new CommerceQuoteError(
+        "PRICE_NOT_CONFIGURED",
+        "Commerce price is not configured",
+        { reason: error.code },
+      );
+    }
+    throw error;
+  }
+}
+
+function strictQuotePriceResolution(
+  authority: CommercePriceAuthorityResult,
+  requestedMode: Exclude<PricingMode, "any">,
+): StrictQuotePriceResolution {
+  const base = authority.base;
+  if (base.mode !== "one_time" || base.matchedMinQty !== 1) {
+    throw new CommerceQuoteError(
+      "PRICING_INVARIANT_VIOLATION",
+      "Strict money authority did not return an exact one-time base anchor",
+      { basePriceEntryId: base.priceEntryId, mode: base.mode, matchedMinQty: base.matchedMinQty },
+    );
+  }
+
+  if (requestedMode === "one_time") {
+    if (authority.kind !== "one_time" || authority.unitPriceMinor !== base.unitPriceMinor) {
+      throw new CommerceQuoteError(
+        "PRICING_INVARIANT_VIOLATION",
+        "Strict money authority returned an invalid one-time result",
+        { authorityKind: authority.kind, basePriceEntryId: base.priceEntryId },
+      );
+    }
+    return { base, resolved: base };
+  }
+
+  if (authority.kind === "subscription_policy") {
+    return {
+      base,
+      resolved: { ...base, mode: "subscription", unitPriceMinor: authority.unitPriceMinor },
+      policy: {
+        policyRevisionId: authority.policy.id,
+        policyDigest: authority.policy.digest,
+      },
+    };
+  }
+  if (authority.kind === "subscription_legacy") {
+    if (authority.legacyResolved.mode !== "subscription" || authority.legacyResolved.unitPriceMinor !== authority.unitPriceMinor) {
+      throw new CommerceQuoteError(
+        "PRICING_INVARIANT_VIOLATION",
+        "Strict money authority returned an invalid legacy subscription result",
+        { legacyPriceEntryId: authority.legacyResolved.priceEntryId, mode: authority.legacyResolved.mode },
+      );
+    }
+    return { base, resolved: authority.legacyResolved };
+  }
+  throw new CommerceQuoteError(
+    "PRICING_INVARIANT_VIOLATION",
+    "Strict money authority returned a one-time result for a subscription quote",
+    { authorityKind: authority.kind, basePriceEntryId: base.priceEntryId },
+  );
+}
+
+export function assertSubscriptionCheapest(input: {
+  requestSku: string;
+  modeAtLine: Exclude<PricingMode, "any">;
+  resolved: ResolvedPrice;
+  oneTime: ResolvedPrice | null;
+  vatRateBps: number;
+}): void {
+  if (
+    input.modeAtLine === "subscription" &&
+    input.oneTime &&
+    toGrossMinor(input.resolved, input.vatRateBps) > toGrossMinor(input.oneTime, input.vatRateBps)
+  ) {
+    throw new CommerceQuoteError(
+      "PRICING_INVARIANT_VIOLATION",
+      "Subscription price must not exceed active one-time price",
+      {
+        sku: input.requestSku,
+        subscriptionPriceEntryId: input.resolved.priceEntryId,
+        oneTimePriceEntryId: input.oneTime.priceEntryId,
+      },
+    );
+  }
+}
+
+export function toGrossMinor(price: ResolvedPrice, vatRateBps: number): number {
+  if (price.amountKind === "gross") return price.unitPriceMinor;
+  return Math.round((price.unitPriceMinor * (10_000 + vatRateBps)) / 10_000);
+}
+
+export function calculateIncludedVat(
+  grossMinor: number,
+  vatRateBps: number,
+): { netMinor: number; vatMinor: number } {
+  return splitIncludedVat(grossMinor, vatRateBps);
+}
+
+/** Exhaustive transport vocabulary; widening requires the matching durable contract. */
+const TRANSPORT_COMPONENT_TYPES: Record<CommerceQuotePricingComponent["componentType"], true> = {
+  base_unit: true,
+  mode_discount: true,
+  qty_tier: true,
+  promo: true,
+  loyalty: true,
+  shipping: true,
+  bundle: true,
+};
+
+function isTransportComponentType(
+  componentType: PricingComponent["component_type"],
+): componentType is CommerceQuotePricingComponent["componentType"] {
+  return Object.prototype.hasOwnProperty.call(TRANSPORT_COMPONENT_TYPES, componentType);
+}
+
+/**
+ * Map one kernel pricing component onto the quote transport shape.
+ *
+ * A component type outside the transport union stops the quote loudly. It is never
+ * cast through and never silently dropped: a dropped component breaks the breakdown
+ * invariant (components must sum to the line total), so a quote would go out priced
+ * from an incomplete explanation of its own total.
+ */
+export function mapPricingComponent(
+  component: PricingComponent,
+  scope: "line" | "order",
+): CommerceQuotePricingComponent {
+  const componentType = component.component_type;
+  if (!isTransportComponentType(componentType)) {
+    throw new CommerceQuoteError(
+      "PRICING_INVARIANT_VIOLATION",
+      "Pricing component type is not carried by the quote transport",
+      { componentType, carriedTypes: Object.keys(TRANSPORT_COMPONENT_TYPES) },
+    );
+  }
+  return {
+    scope,
+    componentType,
+    amountMinor: component.amount_minor,
+    reasonCode: component.reason_code,
+    reasonPayload: component.reason_payload,
+  };
+}
+
+/**
+ * A money builder bound to one currency.
+ *
+ * This used to be a plain `money(amountMinor)` that stamped the settlement
+ * currency as a literal, which meant the quote's declared `currency` and the
+ * currency on every amount inside it came from two different places. They
+ * agreed only because the port's `currency` option was typed as that same
+ * literal. Binding the builder once per port makes the agreement structural:
+ * there is no second place left for the two to disagree.
+ */
+export function moneyIn(currency: string): (amountMinor: number) => CommerceMoney {
+  return (amountMinor) => ({ amountMinor, currency });
+}
+
+export function sum(values: number[]): number {
+  return values.reduce((total, value) => total + value, 0);
+}
+

package/src/pricing/dbBackedCommerceQuotePort.ts

@@ -0,0 +1,260 @@
+import type { PricingResolverPort } from "@openlup/core/pricing";
+import { buildLineBreakdown } from "@openlup/core/pricing";
+import type { CreateQuoteResponse, PricingPolicySnapshot, CreateQuoteRequest, CommerceQuoteContext, CommerceQuoteLine, CommerceQuotePricingComponent, CommerceTaxProfile, CommerceQuoteDiscount, CommerceCodeRejection, CommerceCodeRejectionDetail, CartLineInput } from "./contracts/index.js";
+import { COMMERCE_CONTRACT_VERSION, PROMOTION_ENGINE_V2 } from "./contracts/index.js";
+import { CommerceQuoteError, type CreateQuoteOptions } from "./quotePorts.js";
+import { splitIncludedVat } from "./quoteSchemas.js";
+import type { CommercePriceAuthorityPort } from "./ports.js";
+import { assertSubscriptionCheapest, buildSkuIndex, calculateIncludedVat, eligibleQtyForMode, mapPricingComponent, moneyIn, resolveOneTimeComparison, resolveStrictQuotePrice, sum, toGrossMinor } from "./dbBackedCommerceQuoteHelpers.js";
+import { assertSupportedCommerceTaxProfile } from "./taxProfileGuard.js";
+import type { CommerceQuoteCatalogItem } from "./commerceQuoteCatalogReadPort.js";
+import { catalogFactsForQuoteLine, projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+
+export interface QuotePromotionResult {
+  discounts: CommerceQuoteDiscount[];
+  codeRejections: CommerceCodeRejection[];
+  codeRejectionDetails: CommerceCodeRejectionDetail[];
+}
+
+export interface DbBackedCommerceQuotePortDeps<Request extends CreateQuoteRequest, Item extends CommerceQuoteCatalogItem, LineContext extends object, Context extends CommerceQuoteContext> {
+  quoteCatalogReadPort: { listQuoteCatalogItems(): Promise<Item[]> };
+  isStrictD1Quote: boolean;
+  commercePriceAuthorityPort?: CommercePriceAuthorityPort;
+  pricingResolverPort?: PricingResolverPort;
+  taxProfile: CommerceTaxProfile;
+  supportedTaxProfiles: readonly CommerceTaxProfile[];
+  regionCode: string;
+  currency: string;
+  now?: () => string;
+  shippingFlatMinor?: () => Promise<number>;
+  hasPromotionCodePort: boolean;
+  lineContext(line: CartLineInput, item: Item): LineContext;
+  quoteContext(request: Request, lines: Array<LineContext & { line: CommerceQuoteLine }>): () => Context;
+  resolveAutomaticQuotePromotions(input: {
+    request: Request; options?: CreateQuoteOptions; regionCode: string;
+    referenceProductMinor: number; subtotalGrossMinor: number; shippingGrossMinor: number; atTime: string;
+  }): Promise<Pick<QuotePromotionResult, "discounts" | "codeRejections">>;
+  applyPromotionCodesV2(input: {
+    preserveLegacyDiscountsWhenNoCandidates: boolean; clientId: string | null;
+    mode: Request["mode"]; promoCodes: string[]; referenceProductMinor: number;
+    subtotalGrossMinor: number; shippingGrossMinor: number;
+    discounts: CommerceQuoteDiscount[]; codeRejections: CommerceCodeRejection[]; atTime: string;
+  }): Promise<QuotePromotionResult>;
+}
+
+const STRICT_D1_COMMERCE_CHANNEL = "D2C";
+export function createDbBackedCommerceQuotePort<
+  Request extends CreateQuoteRequest, Item extends CommerceQuoteCatalogItem,
+  LineContext extends object, Context extends CommerceQuoteContext,
+>(deps: DbBackedCommerceQuotePortDeps<Request, Item, LineContext, Context>) {
+  const {
+    taxProfile, supportedTaxProfiles, regionCode, currency,
+    now = () => new Date().toISOString(),
+    quoteCatalogReadPort, isStrictD1Quote, pricingResolverPort,
+    commercePriceAuthorityPort, shippingFlatMinor, resolveAutomaticQuotePromotions,
+    applyPromotionCodesV2, hasPromotionCodePort, lineContext, quoteContext,
+  } = deps;
+  assertSupportedCommerceTaxProfile(taxProfile, supportedTaxProfiles);
+  const money = moneyIn(currency);
+  async function createServerAuthoritativeQuote(
+      request: Request,
+      options?: CreateQuoteOptions,
+    ): Promise<Omit<CreateQuoteResponse, "quote"> & { quote: Omit<CreateQuoteResponse["quote"], "context"> & { context: Context & { pricingPolicy?: PricingPolicySnapshot } } }> {
+      const atTime = now();
+      const skuIndex = await buildSkuIndex(quoteCatalogReadPort);
+      const pricedLines = await Promise.all(request.lines.map(async (requestLine) => {
+        const entry = skuIndex.get(requestLine.sku);
+        if (!entry || (requestLine.variantId && requestLine.variantId !== entry.item.variantId)) {
+          throw new CommerceQuoteError("UNKNOWN_SKU", "Unknown commerce SKU", {
+            sku: requestLine.sku,
+            variantId: requestLine.variantId ?? null,
+          });
+        }
+        const modeAtLine = requestLine.modeAtLine ?? request.mode;
+        if (!entry.item.sellability[modeAtLine === "one_time" ? "oneTime" : "subscription"]) {
+          throw new CommerceQuoteError("UNKNOWN_SKU", "Commerce SKU is not sellable in this purchase mode", {
+            sku: requestLine.sku,
+            variantId: entry.item.variantId,
+            mode: modeAtLine,
+          });
+        }
+        const eligibleCartQty = eligibleQtyForMode(request, modeAtLine);
+        const strictResolution = isStrictD1Quote
+          ? await resolveStrictQuotePrice({
+              commercePriceAuthorityPort: commercePriceAuthorityPort!,
+              variantId: entry.item.variantId,
+              mode: modeAtLine,
+              regionCode,
+              currency,
+              channel: STRICT_D1_COMMERCE_CHANNEL,
+              atTime,
+            })
+          : undefined;
+        const resolved = strictResolution?.resolved ?? await pricingResolverPort!.resolvePrice({
+          variantId: entry.item.variantId,
+          mode: modeAtLine,
+          lineQty: requestLine.quantity,
+          eligibleCartQty,
+          regionCode,
+          currency,
+          atTime,
+        });
+        if (!resolved) {
+          throw new CommerceQuoteError("PRICE_NOT_CONFIGURED", "Commerce price is not configured", {
+            sku: requestLine.sku,
+            variantId: entry.item.variantId,
+            mode: modeAtLine,
+          });
+        }
+        const oneTime = strictResolution?.base ?? await resolveOneTimeComparison({
+          pricingResolverPort: pricingResolverPort!,
+          variantId: entry.item.variantId,
+          lineQty: requestLine.quantity,
+          eligibleCartQty,
+          regionCode,
+          currency,
+          atTime,
+        });
+        const promotionReference = hasPromotionCodePort && request.promoCodes.length > 0
+          ? strictResolution?.base ?? await resolveOneTimeComparison({
+              pricingResolverPort: pricingResolverPort!,
+              variantId: entry.item.variantId,
+              lineQty: requestLine.quantity,
+              eligibleCartQty: 1,
+              regionCode,
+              currency,
+              atTime,
+            })
+          : oneTime;
+        assertSubscriptionCheapest({
+          requestSku: requestLine.sku,
+          modeAtLine,
+          resolved,
+          oneTime,
+          vatRateBps: taxProfile.vatRateBps,
+        });
+        const unitPriceGrossMinor = toGrossMinor(resolved, taxProfile.vatRateBps);
+        const baseUnitGrossMinor = oneTime ? toGrossMinor(oneTime, taxProfile.vatRateBps) : unitPriceGrossMinor;
+        const grossMinor = unitPriceGrossMinor * requestLine.quantity;
+        const tax = calculateIncludedVat(grossMinor, taxProfile.vatRateBps);
+        const pricingComponents = buildLineBreakdown({
+          variant_id: entry.item.variantId,
+          line_qty: requestLine.quantity,
+          base_unit_price_minor: baseUnitGrossMinor,
+          resolved_unit_price_minor: unitPriceGrossMinor,
+          matched_tier_min_qty: resolved.matchedMinQty,
+          mode_at_line: modeAtLine,
+          mode_resolved_via_fallback: resolved.mode === "any",
+        }).map((component) => mapPricingComponent(component, "line"));
+        const catalogFacts = isStrictD1Quote
+          ? catalogFactsForQuoteLine(true, entry.item, resolved, oneTime!, modeAtLine, atTime, currency, unitPriceGrossMinor, grossMinor, toGrossMinor(oneTime!, taxProfile.vatRateBps), strictResolution?.policy)
+          : undefined;
+        return {
+          line: {
+            sku: entry.item.skuCode,
+            productSlug: entry.item.productSlug,
+            quantity: requestLine.quantity,
+            unitPriceGross: money(unitPriceGrossMinor),
+            lineSubtotalGross: money(grossMinor),
+            tax: {
+              ...taxProfile,
+              netAmount: money(tax.netMinor),
+              vatAmount: money(tax.vatMinor),
+              grossAmount: money(grossMinor),
+            },
+            pricingComponents,
+            ...(catalogFacts ? { catalogFacts } : {}),
+          },
+          pricingComponents,
+          ...lineContext(requestLine, entry.item),
+          referenceGrossMinor: toGrossMinor(promotionReference ?? oneTime ?? resolved, taxProfile.vatRateBps)
+            * requestLine.quantity,
+        };
+      }));
+      const lines: CommerceQuoteLine[] = pricedLines.map((entry) => entry.line);
+      const quoteComponents: CommerceQuotePricingComponent[] = pricedLines.flatMap((entry) => entry.pricingComponents);
+      const context = quoteContext(request, pricedLines);
+      const subtotalGrossMinor = sum(lines.map((line) => line.lineSubtotalGross.amountMinor));
+      const referenceProductMinor = sum(pricedLines.map((entry) => entry.referenceGrossMinor));
+      const netTotalMinor = sum(lines.map((line) => line.tax.netAmount.amountMinor));
+      const taxTotalMinor = sum(lines.map((line) => line.tax.vatAmount.amountMinor));
+      // Shipping is a flat per-order gross from settings; absent settings port ⇒ no
+      // shipping (byte-identical to pre-shipping quotes). Resolved before promo eval so
+      // the free-shipping lane has a real amount to zero.
+      const shippingGrossMinor = shippingFlatMinor
+        ? await shippingFlatMinor()
+        : 0;
+      const automaticPromotionResult = await resolveAutomaticQuotePromotions({
+        request,
+        options,
+        regionCode,
+        referenceProductMinor,
+        subtotalGrossMinor,
+        shippingGrossMinor,
+        atTime,
+      });
+      const promotionResult = await applyPromotionCodesV2({
+        preserveLegacyDiscountsWhenNoCandidates: options?.pricingPolicy?.promotionEngineVersion !== PROMOTION_ENGINE_V2,
+        clientId: options?.clientId ?? null,
+        mode: request.mode,
+        promoCodes: request.promoCodes,
+        referenceProductMinor: sum(pricedLines.map((entry) => entry.referenceGrossMinor)),
+        subtotalGrossMinor,
+        shippingGrossMinor,
+        discounts: automaticPromotionResult.discounts,
+        codeRejections: automaticPromotionResult.codeRejections,
+        atTime,
+      });
+      const { discounts, codeRejections, codeRejectionDetails } = promotionResult;
+      // Two lanes: order_total/line discounts reduce the subtotal; a shipping discount
+      // (free-shipping promo) reduces the shipping gross. They are summed and validated
+      // independently by the quote schema.
+      const orderDiscountMinor = discounts
+        .filter((d) => d.appliesTo !== "shipping")
+        .reduce((total, d) => total + d.amountOffMinor, 0);
+      const shippingDiscountMinor = discounts
+        .filter((d) => d.appliesTo === "shipping")
+        .reduce((total, d) => total + d.amountOffMinor, 0);
+
+      const { netMinor: discountNetMinor, vatMinor: discountVatMinor } = splitIncludedVat(
+        orderDiscountMinor,
+        taxProfile.vatRateBps,
+      );
+      const ship = splitIncludedVat(shippingGrossMinor, taxProfile.vatRateBps);
+      const shipDiscount = splitIncludedVat(shippingDiscountMinor, taxProfile.vatRateBps);
+      const hasShipping = shippingFlatMinor != null;
+      const shippingFields = hasShipping
+        ? {
+            shippingGross: money(shippingGrossMinor),
+            shippingDiscountGross: money(shippingDiscountMinor),
+          }
+        : {};
+      return {
+        contractVersion: COMMERCE_CONTRACT_VERSION,
+        quote: {
+          currency,
+          taxIncluded: true,
+          lines,
+          discounts,
+          ...(codeRejections.length ? { codeRejections } : {}),
+          ...(codeRejectionDetails.length ? { codeRejectionDetails } : {}),
+          pricingComponents: quoteComponents,
+          context: {
+            ...context(),
+            ...(options?.pricingPolicy ? { pricingPolicy: options.pricingPolicy } : {}),
+          },
+          subtotalGross: money(subtotalGrossMinor),
+          discountTotalGross: money(orderDiscountMinor),
+          ...shippingFields,
+          totalGross: money(subtotalGrossMinor - orderDiscountMinor + shippingGrossMinor - shippingDiscountMinor),
+          netTotal: money(netTotalMinor - discountNetMinor + ship.netMinor - shipDiscount.netMinor),
+          taxTotal: money(taxTotalMinor - discountVatMinor + ship.vatMinor - shipDiscount.vatMinor),
+        },
+      };
+    }
+
+  return {
+    createQuote: async (request: Request, options?: CreateQuoteOptions) => projectPublicQuoteSnapshot(await createServerAuthoritativeQuote(request, options)),
+    createServerAuthoritativeQuote,
+  };
+}

package/src/pricing/dbBackedCommerceQuoteSnapshotVerifier.ts

@@ -0,0 +1,49 @@
+import type { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+import {
+  type CreateQuoteResponse,
+} from "./contracts/quote.js";
+import {
+  CommerceQuoteSnapshotError,
+  type CommerceQuotePort,
+  type CommerceQuoteSnapshotVerifierPort,
+} from "./quotePorts.js";
+import { projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+import { createExpectedQuote } from "./commerceQuoteSnapshotExpect.js";
+
+export function createDbBackedCommerceQuoteSnapshotVerifier<Request, Response extends CreateQuoteResponse>(
+  quotePort: CommerceQuotePort<Request, Response>,
+  quoteRequestFromSnapshot: (snapshot: Response) => Request,
+  createQuoteResponseSchema: z.ZodType<Response>,
+): CommerceQuoteSnapshotVerifierPort<Response> {
+  async function verifyAndEnrich(snapshot: Response): Promise<Response> {
+    const publicSnapshot = projectPublicQuoteSnapshot(snapshot);
+    const expected = await createExpectedQuote(
+      quotePort.createServerAuthoritativeQuote
+        ? { createQuote: quotePort.createServerAuthoritativeQuote.bind(quotePort) }
+        : quotePort,
+      quoteRequestFromSnapshot(publicSnapshot),
+      {
+        invalidResponseMessage: "Commerce DB-backed quote verifier returned invalid response",
+        catalogMismatchMessage:
+          "Commerce quote snapshot does not match current DB-backed catalog pricing",
+      },
+      createQuoteResponseSchema,
+    );
+    if (!isDeepStrictEqual(publicSnapshot, projectPublicQuoteSnapshot(expected))) {
+      throw new CommerceQuoteSnapshotError(
+        "QUOTE_SNAPSHOT_MISMATCH",
+        "Commerce quote snapshot does not match current DB-backed catalog pricing",
+        {
+          reason: "snapshot_does_not_match_db_backed_quote",
+          skus: publicSnapshot.quote.lines.map((line) => line.sku),
+        },
+      );
+    }
+    return expected;
+  }
+
+  return {
+    verifyQuoteSnapshot: verifyAndEnrich,
+  };
+}