@openlup/platform 0.17.0 → 0.19.0

package/src/pricing/commerceOfferPricing.ts

@@ -0,0 +1,224 @@
+import {
+  COMMERCE_OFFER_PRICING_CONTRACT_VERSION,
+  COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION,
+  type CommerceOfferPricingResponse,
+  type CommerceProductOfferPricing,
+} from "./contracts/offer.js";
+import {
+  OFFER_POLICY_V2,
+  PROMOTION_ENGINE_V2,
+  type PricingPolicySnapshot,
+} from "./contracts/offerPolicy.js";
+import type { CreateQuoteRequest } from "./contracts/quote.js";
+import type { CommerceCurrency, CommerceQuote } from "./contracts/index.js";
+import {
+  CommerceQuoteError,
+  type CommerceQuotePort,
+} from "./quotePorts.js";
+import type {
+  CommerceQuoteCatalogItem,
+} from "./commerceQuoteCatalogReadPort.js";
+
+/**
+ * Why one product was left out of the offer projection.
+ *
+ * The projection's `minimumBy` produces the customer-facing "from" figure, so a
+ * silently shrunken product set would advertise a price that is not the real
+ * minimum. A dropped product cannot pull that minimum DOWN - the reachable error
+ * is always a HIGHER advertised price, never an undersell - but it must still be
+ * legible, so every exclusion is recorded. The response contract deliberately
+ * does not move: this is the whole signal.
+ *
+ * Private, bounded operational fact; no request or customer data.
+ */
+interface OfferPricingExclusionDiagnostic {
+  event: "commerce_offer_pricing_product_excluded";
+  product_slug: string;
+  refusal_code: string;
+}
+
+function recordOfferPricingExclusion(diagnostic: OfferPricingExclusionDiagnostic): void {
+  try {
+    console.info(JSON.stringify(diagnostic));
+  } catch {
+    // A private diagnostic sink must never alter the projection it observes.
+  }
+}
+
+export interface CommerceOfferPricingDeps<Item extends CommerceQuoteCatalogItem, ScopeV1 extends string, ScopeV2 extends string> {
+  quoteCatalogReadPort: { listQuoteCatalogItems(): Promise<Item[]> };
+  quoteWithPromotions: CommerceQuotePort;
+  quoteWithoutPromotions: CommerceQuotePort;
+  pricingPolicy?: PricingPolicySnapshot;
+  isOfferProduct(product: Item): boolean;
+  requestFor(product: Item, mode: "one_time" | "subscription"): CreateQuoteRequest;
+  unitCount: number;
+  minimumProductPayableMinor: number;
+  scopeV1: ScopeV1;
+  scopeV2: ScopeV2;
+}
+
+/**
+ * Product-only acquisition projection over the same quote ports used by
+ * configurator checkout. It never prices delivery and is never accepted as a
+ * checkout expectation; its only consumer is non-transactional "from" copy.
+ */
+export async function projectCommerceOfferPricing<Item extends CommerceQuoteCatalogItem, ScopeV1 extends string, ScopeV2 extends string>({
+  quoteCatalogReadPort,
+  quoteWithPromotions,
+  quoteWithoutPromotions,
+  pricingPolicy, isOfferProduct, requestFor, unitCount: COMMERCE_MIN_AUTO_ORDER_UNITS,
+  minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR, scopeV1, scopeV2,
+}: CommerceOfferPricingDeps<Item, ScopeV1, ScopeV2>): Promise<CommerceOfferPricingResponse<ScopeV1, ScopeV2>> {
+  const products = (await quoteCatalogReadPort.listQuoteCatalogItems()).filter(isOfferProduct);
+  if (products.length === 0) throw new Error("commerce_offer_pricing_unavailable");
+
+  const settled = await Promise.all(
+    products.map(async (product) => {
+      try {
+        return {
+          product,
+          entry: await projectProduct(
+            product, quoteWithPromotions, quoteWithoutPromotions, requestFor, COMMERCE_MIN_AUTO_ORDER_UNITS, pricingPolicy,
+          ),
+        };
+      } catch (error) {
+        // One SKU the strict money authority cannot price must not remove every
+        // PDP price block. Only that refusal degrades; an infrastructure failure
+        // or a violated pricing invariant still refuses the whole projection.
+        if (error instanceof CommerceQuoteError && error.code === "PRICE_NOT_CONFIGURED") {
+          recordOfferPricingExclusion({
+            event: "commerce_offer_pricing_product_excluded",
+            product_slug: product.productSlug,
+            refusal_code: typeof error.details.reason === "string" ? error.details.reason : "unknown",
+          });
+          return null;
+        }
+        throw error;
+      }
+    }),
+  );
+  const priced = settled.flatMap((outcome) => (outcome ? [outcome] : []));
+  const projected = priced.map((outcome) => outcome.entry);
+  // The minimum below is the customer-facing "from" figure. Over an EMPTY set it
+  // would be meaningless, so a projection that priced nothing refuses exactly as
+  // an empty catalogue does rather than answering with an invented floor.
+  if (projected.length === 0) throw new Error("commerce_offer_pricing_unavailable");
+  const oneTime = minimumBy(projected, (entry) => entry.oneTime.unitGross.amountMinor);
+  const subscription = minimumBy(
+    projected,
+    (entry) => entry.subscriptionInitial.unitGross.amountMinor,
+  );
+
+  const legacy = {
+    contractVersion: COMMERCE_OFFER_PRICING_CONTRACT_VERSION,
+    scope: scopeV1,
+    products: projected,
+    minimum: { oneTime, subscription },
+  } as const;
+  if (pricingPolicy?.offerPolicyVersion !== OFFER_POLICY_V2 ||
+      pricingPolicy.promotionEngineVersion !== PROMOTION_ENGINE_V2) return legacy;
+
+  // The representative quote must come from a product that actually PRICED. Using
+  // the catalogue's first product would re-raise the very refusal just excluded
+  // and refuse the whole response despite another product having priced.
+  const representative = await quoteWithPromotions.createQuote(
+    requestFor(priced[0]!.product, "one_time"),
+    pricingPolicy ? { pricingPolicy } : undefined,
+  );
+  // An absent shipping figure is zero in the currency the quote came back in.
+  // It used to be zero in a named currency, which is a coercion rather than a
+  // default: a quote in one currency would have carried a shipping line in
+  // another, and the two would have been summed.
+  const quoteCurrency = representative.quote.currency;
+  const gross = representative.quote.shippingGross ?? { amountMinor: 0, currency: quoteCurrency };
+  const discountGross = representative.quote.shippingDiscountGross
+    ?? { amountMinor: 0, currency: quoteCurrency };
+  return {
+    contractVersion: COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION,
+    scope: scopeV2,
+    pricingPolicy,
+    products: projected,
+    minimum: { oneTime, subscription },
+    shipping: {
+      gross,
+      discountGross,
+      payable: { amountMinor: gross.amountMinor - discountGross.amountMinor, currency: gross.currency },
+    },
+    // Both halves come from the injected settlement policy, which supplies the
+    // denomination and left the amount, which was one major unit written out as
+    // a hundredths-assuming literal.
+    minimumProductPayable: {
+      amountMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+      currency: quoteCurrency,
+    },
+  };
+}
+
+async function projectProduct<Item extends CommerceQuoteCatalogItem>(
+  product: Item,
+  quoteWithPromotions: CommerceQuotePort,
+  quoteWithoutPromotions: CommerceQuotePort,
+  requestFor: (product: Item, mode: "one_time" | "subscription") => CreateQuoteRequest,
+  COMMERCE_MIN_AUTO_ORDER_UNITS: number,
+  pricingPolicy?: PricingPolicySnapshot,
+): Promise<CommerceProductOfferPricing> {
+  const options = pricingPolicy ? { pricingPolicy } : undefined;
+  const [oneTime, subscriptionInitial, subscriptionRecurring] = await Promise.all([
+    quoteWithPromotions.createQuote(requestFor(product, "one_time"), options),
+    quoteWithPromotions.createQuote(requestFor(product, "subscription"), options),
+    quoteWithoutPromotions.createQuote(requestFor(product, "subscription"), options),
+  ]);
+  const oneTimeProductGross = productGross(oneTime.quote);
+  const initialProductGross = productGross(subscriptionInitial.quote);
+  const recurringProductGross = productGross(subscriptionRecurring.quote);
+  const anchorUnitGross = oneTime.quote.lines[0]?.unitPriceGross;
+  if (!anchorUnitGross) throw new Error("commerce_offer_pricing_line_missing");
+  const anchorPackageGross =
+    anchorUnitGross.amountMinor * COMMERCE_MIN_AUTO_ORDER_UNITS;
+
+  return {
+    productSlug: product.productSlug,
+    unitCount: COMMERCE_MIN_AUTO_ORDER_UNITS,
+    oneTime: price(oneTimeProductGross, oneTime.quote.currency, COMMERCE_MIN_AUTO_ORDER_UNITS),
+    subscriptionInitial: price(initialProductGross, subscriptionInitial.quote.currency, COMMERCE_MIN_AUTO_ORDER_UNITS),
+    subscriptionRecurring: price(
+      recurringProductGross,
+      subscriptionRecurring.quote.currency,
+      COMMERCE_MIN_AUTO_ORDER_UNITS,
+    ),
+    catalogAnchorUnitGross: anchorUnitGross,
+    initialDiscountPercent: discountPercent(anchorPackageGross, initialProductGross),
+    recurringDiscountPercent: discountPercent(anchorPackageGross, recurringProductGross),
+  };
+}
+
+function productGross(quote: CommerceQuote): number {
+  return quote.subtotalGross.amountMinor - quote.discountTotalGross.amountMinor;
+}
+
+// Carries whatever currency the quote came back in; it is not this helper's job
+// to name one (src/lib/currency/platformCurrency.ts owns that question).
+function price(amountMinor: number, currency: CommerceCurrency, COMMERCE_MIN_AUTO_ORDER_UNITS: number) {
+  return {
+    packageGross: { amountMinor, currency },
+    unitGross: {
+      amountMinor: Math.round(amountMinor / COMMERCE_MIN_AUTO_ORDER_UNITS),
+      currency,
+    },
+  };
+}
+
+function discountPercent(anchorMinor: number, effectiveMinor: number): number {
+  if (anchorMinor <= 0 || effectiveMinor >= anchorMinor) return 0;
+  return Math.round(((anchorMinor - effectiveMinor) / anchorMinor) * 100);
+}
+
+function minimumBy(
+  entries: CommerceProductOfferPricing[],
+  amount: (entry: CommerceProductOfferPricing) => number,
+): CommerceProductOfferPricing {
+  return entries.reduce((minimum, entry) =>
+    amount(entry) < amount(minimum) ? entry : minimum,
+  );
+}

package/src/pricing/commerceOfferPricingCache.ts

@@ -0,0 +1,53 @@
+import type { CommerceOfferPricingResponse } from "./contracts/offer.js";
+
+/** One bounded value and one in-flight load per runtime instance. */
+export interface CommerceOfferPricingCache<Response extends CommerceOfferPricingResponse = CommerceOfferPricingResponse> {
+  read(key: string, load: () => Promise<Response>): Promise<Response>;
+}
+
+export function createCommerceOfferPricingCache<Response extends CommerceOfferPricingResponse = CommerceOfferPricingResponse>(input: {
+  ttlMs: number;
+  failureTtlMs?: number;
+  now?: () => number;
+}): CommerceOfferPricingCache<Response> {
+  const now = input.now ?? Date.now;
+  const failureTtlMs = input.failureTtlMs ?? 0;
+  const cached = new Map<string, { value: Response; expiresAt: number }>();
+  const failed = new Map<string, { error: unknown; expiresAt: number }>();
+  const pending = new Map<string, Promise<Response>>();
+
+  return {
+    read(key, load) {
+      const cachedEntry = cached.get(key);
+      const failedEntry = failed.get(key);
+      if (cachedEntry && cachedEntry.expiresAt > now()) return Promise.resolve(cachedEntry.value);
+      if (failedEntry && failedEntry.expiresAt > now()) return Promise.reject(failedEntry.error);
+      const pendingEntry = pending.get(key);
+      if (pendingEntry) return pendingEntry;
+
+      const startedAt = now();
+      const current = load()
+        .then((value) => {
+          // Bound freshness from the pricing instant, not from completion of a
+          // potentially slow DB read.
+          cached.set(key, { value, expiresAt: startedAt + input.ttlMs });
+          failed.delete(key);
+          return value;
+        })
+        .catch((error: unknown) => {
+          // A public cold endpoint must not hammer a degraded database once per
+          // request. Keep only the failure object, briefly, and never turn it
+          // into stale pricing data; callers still receive the same rejection.
+          if (failureTtlMs > 0) {
+            failed.set(key, { error, expiresAt: now() + failureTtlMs });
+          }
+          throw error;
+        })
+        .finally(() => {
+          if (pending.get(key) === current) pending.delete(key);
+        });
+      pending.set(key, current);
+      return current;
+    },
+  };
+}

package/src/pricing/commerceOfferPricingHandler.ts

@@ -0,0 +1,137 @@
+import type { PricingPolicyRequest, PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import {
+  type CommerceOfferPricingResponse,
+} from "./contracts/offer.js";
+import {
+  pricingPolicyRequestSchema,
+} from "./offerPolicySchemas.js";
+
+// Price/promotion validity can end at any instant. Keep the public cache very
+// short and omit stale-while-revalidate; a future contract may expose the next
+// validity boundary and clamp this exactly to it.
+export const COMMERCE_OFFER_PRICING_CACHE_CONTROL =
+  "public, max-age=0, s-maxage=5, must-revalidate";
+export const COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL = "private, no-store";
+
+export const OFFER_POLICY_CAPABILITY_HEADER = "x-commerce-offer-policy-capability";
+export const OFFER_POLICY_TOKEN_HEADER = "x-commerce-pricing-policy-token";
+export const OFFER_POLICY_VISITOR_HEADER = "x-commerce-visitor-id";
+
+const ROUTER_QUERY_KEYS = new Set(["path", "__bffPath"]);
+
+export interface CommerceOfferPricingHandlerDeps<Response extends CommerceOfferPricingResponse = CommerceOfferPricingResponse> {
+  responder: BffResponder;
+  commerceOfferPricingResponseSchema: z.ZodType<Response>;
+  readOfferPricing(pricingPolicy?: PricingPolicySnapshot): Promise<Response>;
+  requirePricingPolicy?: boolean;
+  resolvePricingPolicy?(request: {
+    visitorId: string;
+    pricingPolicy: PricingPolicyRequest;
+  }): PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+}
+
+export function createCommerceOfferPricingHandler<Response extends CommerceOfferPricingResponse>({
+  responder, commerceOfferPricingResponseSchema,
+  readOfferPricing,
+  resolvePricingPolicy,
+  requirePricingPolicy = false,
+}: CommerceOfferPricingHandlerDeps<Response>) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(
+    req: HttpRequest,
+    res: HttpResponse,
+  ): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+    const userQueryKeys = Object.keys(req.query ?? {}).filter(
+      (key) => !ROUTER_QUERY_KEYS.has(key),
+    );
+    if (userQueryKeys.length > 0) {
+      sendBffError(res, "BAD_REQUEST", "Commerce offer pricing does not accept query parameters");
+      return;
+    }
+
+    try {
+      const policyRequest = readPolicyRequest(req);
+      if (policyRequest === null) {
+        sendBffError(res, "BAD_REQUEST", "Commerce offer pricing policy capability is invalid");
+        return;
+      }
+      if (!policyRequest && requirePricingPolicy) {
+        // A caller that sent no capability headers is an incomplete request,
+        // not an unavailable origin — the same attribution the missing-visitor
+        // branch above already applies.
+        sendBffError(
+          res,
+          "BAD_REQUEST",
+          "Commerce offer pricing requires offer policy v2",
+          {
+            details: {
+              reason: "pricing_policy_request_invalid",
+              stage: "pricing_policy",
+              policyReason: "v2_capability_required",
+            },
+          },
+        );
+        return;
+      }
+      const pricingPolicy = policyRequest && resolvePricingPolicy
+        ? await resolvePricingPolicy(policyRequest)
+        : undefined;
+      const parsed = commerceOfferPricingResponseSchema.safeParse(
+        await readOfferPricing(pricingPolicy),
+      );
+      if (!parsed.success) {
+        sendBffError(
+          res,
+          "INVALID_RESPONSE",
+          "Commerce offer pricing returned invalid response",
+        );
+        return;
+      }
+      sendBffSuccess(
+        res,
+        parsed.data,
+        { contractVersion: parsed.data.contractVersion },
+        {
+          cacheControl: policyRequest
+            ? COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL
+            : COMMERCE_OFFER_PRICING_CACHE_CONTROL,
+        },
+      );
+    } catch {
+      sendBffError(
+        res,
+        "UPSTREAM_UNAVAILABLE",
+        "Commerce offer pricing is unavailable",
+      );
+    }
+  };
+}
+
+function readPolicyRequest(req: HttpRequest): {
+  visitorId: string;
+  pricingPolicy: PricingPolicyRequest;
+} | undefined | null {
+  const capability = singleHeader(req, OFFER_POLICY_CAPABILITY_HEADER);
+  const token = singleHeader(req, OFFER_POLICY_TOKEN_HEADER);
+  if (!capability && !token) return undefined;
+  const visitorId = singleHeader(req, OFFER_POLICY_VISITOR_HEADER);
+  if (!visitorId || visitorId.length > 120) return null;
+  const parsed = pricingPolicyRequestSchema.safeParse({
+    ...(capability ? { capability } : {}),
+    ...(token ? { token } : {}),
+  });
+  return parsed.success ? { visitorId, pricingPolicy: parsed.data } : null;
+}
+
+function singleHeader(req: HttpRequest, name: string): string | undefined {
+  const value = req.headers?.[name];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+

package/src/pricing/commercePriceAuthority.ts

@@ -0,0 +1,169 @@
+import type { CommercePriceAuthorityQuery, CommercePriceAuthorityResult } from "./contracts/index.js";
+import {
+  CommercePriceAuthorityError,
+  type CommercePriceAuthorityPort,
+} from "./ports.js";
+import {
+  SubscriptionPricePolicyDigestError,
+  assertSubscriptionPricePolicyDigest,
+  deriveSubscriptionUnitPrice,
+} from "./subscriptionPricePolicy.js";
+import type { ResolvedPrice } from "@openlup/core/pricing";
+
+export interface TimedAuthorityValue<T> {
+  value: T;
+  validFrom: string;
+  validTo: string | null;
+}
+
+export interface CommercePriceAuthorityReadPort {
+  listPriceLists(context: Pick<CommercePriceAuthorityQuery, "regionCode" | "currency">): Promise<ReadonlyArray<TimedAuthorityValue<string>>>;
+  listExactBaseEntries(input: { variantId: string; priceListId: string }): Promise<ReadonlyArray<TimedAuthorityValue<ResolvedPrice>>>;
+  listExactLegacySubscriptionEntries(input: { variantId: string; priceListId: string }): Promise<ReadonlyArray<TimedAuthorityValue<ResolvedPrice>>>;
+  listSubscriptionPolicyHistory(context: Pick<CommercePriceAuthorityQuery, "regionCode" | "currency" | "channel"> & { priceListId: string }): Promise<ReadonlyArray<TimedAuthorityValue<unknown>>>;
+}
+
+/** Provider-neutral strict money algorithm; adapters own only persistence reads and row mapping. */
+export function createCommercePriceAuthorityPort(
+  reads: CommercePriceAuthorityReadPort,
+): CommercePriceAuthorityPort {
+  return {
+    async resolvePrice(query): Promise<CommercePriceAuthorityResult> {
+      const atTime = query.atTime ?? new Date().toISOString();
+      const priceListId = selectUniqueEffectivePriceList(await reads.listPriceLists(query), atTime);
+
+      const baseCandidates = effective(await reads.listExactBaseEntries({
+        variantId: query.variantId,
+        priceListId,
+      }), atTime);
+      if (baseCandidates.length === 0) throw new CommercePriceAuthorityError("base_price_not_found");
+      if (baseCandidates.length !== 1) throw new CommercePriceAuthorityError("base_price_ambiguous");
+      if (baseCandidates[0]!.value.amountKind !== "gross") {
+        throw new CommercePriceAuthorityError("base_price_amount_kind_invalid");
+      }
+
+      const base = { ...baseCandidates[0]!.value, resolvedAt: atTime };
+      if (query.mode === "one_time") return { kind: "one_time", base, unitPriceMinor: base.unitPriceMinor };
+
+      const policyHistory = await reads.listSubscriptionPolicyHistory({
+        priceListId: base.priceListId,
+        regionCode: query.regionCode,
+        currency: query.currency,
+        channel: query.channel,
+      });
+      if (policyHistory.length === 0) {
+        const legacyCandidates = effective(await reads.listExactLegacySubscriptionEntries({
+          variantId: query.variantId,
+          priceListId: base.priceListId,
+        }), atTime);
+        if (legacyCandidates.length === 0) throw new CommercePriceAuthorityError("legacy_subscription_price_not_found");
+        if (legacyCandidates.length !== 1) throw new CommercePriceAuthorityError("legacy_subscription_price_ambiguous");
+        const legacyResolved = { ...legacyCandidates[0]!.value, resolvedAt: atTime };
+        return { kind: "subscription_legacy", base, unitPriceMinor: legacyResolved.unitPriceMinor, legacyResolved };
+      }
+
+      const effectivePolicies = effective(policyHistory, atTime);
+      if (effectivePolicies.length === 0) throw new CommercePriceAuthorityError("subscription_price_policy_not_effective");
+      if (effectivePolicies.length !== 1) throw new CommercePriceAuthorityError("subscription_price_policy_ambiguous");
+      try {
+        const policy = await assertSubscriptionPricePolicyDigest(effectivePolicies[0]!.value);
+        return {
+          kind: "subscription_policy",
+          base,
+          unitPriceMinor: deriveSubscriptionUnitPrice(base.unitPriceMinor, policy),
+          policy,
+        };
+      } catch (error) {
+        throw new CommercePriceAuthorityError(
+          error instanceof SubscriptionPricePolicyDigestError
+            ? "subscription_price_policy_digest_mismatch"
+            : "subscription_price_policy_invalid",
+        );
+      }
+    },
+  };
+}
+
+/** Opt-in scheduling using the selected list for concurrent history reads. */
+export function createConcurrentCommercePriceAuthorityPort(
+  reads: CommercePriceAuthorityReadPort,
+): CommercePriceAuthorityPort {
+  return {
+    async resolvePrice(query): Promise<CommercePriceAuthorityResult> {
+      const atTime = query.atTime ?? new Date().toISOString();
+      const priceListId = selectUniqueEffectivePriceList(await reads.listPriceLists(query), atTime);
+
+      // Schedule history alongside base reads, retaining base-refusal precedence.
+      const policyHistoryRead = query.mode === "subscription" ? Promise.resolve().then(() =>
+        reads.listSubscriptionPolicyHistory({ priceListId, regionCode: query.regionCode,
+          currency: query.currency, channel: query.channel })).then(
+        (value) => ({ value }), (error: unknown) => ({ error }),
+      ) : null;
+
+      const baseCandidates = effective(await reads.listExactBaseEntries({
+        variantId: query.variantId,
+        priceListId,
+      }), atTime);
+      if (baseCandidates.length === 0) throw new CommercePriceAuthorityError("base_price_not_found");
+      if (baseCandidates.length !== 1) throw new CommercePriceAuthorityError("base_price_ambiguous");
+      if (baseCandidates[0]!.value.amountKind !== "gross") {
+        throw new CommercePriceAuthorityError("base_price_amount_kind_invalid");
+      }
+
+      const base = { ...baseCandidates[0]!.value, resolvedAt: atTime };
+      if (query.mode === "one_time") return { kind: "one_time", base, unitPriceMinor: base.unitPriceMinor };
+
+      const policyRead = await policyHistoryRead!;
+      if ("error" in policyRead) throw policyRead.error;
+      const policyHistory = policyRead.value;
+      if (policyHistory.length === 0) {
+        const legacyCandidates = effective(await reads.listExactLegacySubscriptionEntries({
+          variantId: query.variantId,
+          priceListId: base.priceListId,
+        }), atTime);
+        if (legacyCandidates.length === 0) throw new CommercePriceAuthorityError("legacy_subscription_price_not_found");
+        if (legacyCandidates.length !== 1) throw new CommercePriceAuthorityError("legacy_subscription_price_ambiguous");
+        const legacyResolved = { ...legacyCandidates[0]!.value, resolvedAt: atTime };
+        return { kind: "subscription_legacy", base, unitPriceMinor: legacyResolved.unitPriceMinor, legacyResolved };
+      }
+
+      const effectivePolicies = effective(policyHistory, atTime);
+      if (effectivePolicies.length === 0) throw new CommercePriceAuthorityError("subscription_price_policy_not_effective");
+      if (effectivePolicies.length !== 1) throw new CommercePriceAuthorityError("subscription_price_policy_ambiguous");
+      try {
+        const policy = await assertSubscriptionPricePolicyDigest(effectivePolicies[0]!.value);
+        return {
+          kind: "subscription_policy",
+          base,
+          unitPriceMinor: deriveSubscriptionUnitPrice(base.unitPriceMinor, policy),
+          policy,
+        };
+      } catch (error) {
+        throw new CommercePriceAuthorityError(
+          error instanceof SubscriptionPricePolicyDigestError
+            ? "subscription_price_policy_digest_mismatch"
+            : "subscription_price_policy_invalid",
+        );
+      }
+    },
+  };
+}
+
+/** The current money context requires one list; creation order cannot resolve overlap. */
+export function selectUniqueEffectivePriceList(
+  priceLists: readonly TimedAuthorityValue<string>[], atTime: string,
+): string {
+  const candidates = effective(priceLists, atTime);
+  if (candidates.length === 0) throw new CommercePriceAuthorityError("active_price_list_not_found");
+  if (candidates.length !== 1) throw new CommercePriceAuthorityError("active_price_list_ambiguous");
+  return candidates[0]!.value;
+}
+
+function effective<T>(values: readonly TimedAuthorityValue<T>[], atTime: string): TimedAuthorityValue<T>[] {
+  const atMs = Date.parse(atTime);
+  return values.filter(({ validFrom, validTo }) => {
+    const fromMs = Date.parse(validFrom);
+    const toMs = validTo === null ? null : Date.parse(validTo);
+    return Number.isFinite(atMs) && Number.isFinite(fromMs) && fromMs <= atMs && (toMs === null || toMs > atMs);
+  });
+}

package/src/pricing/commercePricingPolicyErrors.ts

@@ -0,0 +1,88 @@
+/** The server cannot assign a policy right now. Caller-independent: retrying an
+ * identical request only succeeds once production configuration changes. */
+export class CommercePricingPolicyUnavailableError extends Error {
+  constructor(public readonly reason: string) {
+    super("commerce_pricing_policy_v2_unavailable");
+    this.name = "CommercePricingPolicyUnavailableError";
+  }
+}
+
+/**
+ * Every reason a caller-side refusal can carry. ⛔ Each one answers `400`, which
+ * puts it outside every 5xx monitor, so each one owes a dedicated monitor of its
+ * own; a host's observability check can read this tuple and fail when a reason
+ * has none. Adding a member here without adding a monitor is the regression this
+ * tuple exists to prevent: reclassifying `v2_capability_required` from `503` to
+ * `400` once silently removed the only alert on a site-wide unpriceable-quote
+ * outage.
+ */
+export const PRICING_POLICY_REQUEST_REASONS = [
+  "v2_capability_required",
+  "v2_visitor_id_required",
+] as const;
+
+export type PricingPolicyRequestReason = (typeof PRICING_POLICY_REQUEST_REASONS)[number];
+
+/** The request itself lacks the context a v2 assignment needs. Caller-fixable,
+ * and never evidence that pricing is down. The reason is typed off
+ * PRICING_POLICY_REQUEST_REASONS so a new one cannot skip its monitor. */
+export class CommercePricingPolicyRequestError extends Error {
+  constructor(public readonly reason: PricingPolicyRequestReason) {
+    super("commerce_pricing_policy_v2_request_invalid");
+    this.name = "CommercePricingPolicyRequestError";
+  }
+}
+
+export type SafePricingPolicyReason =
+  | "v2_capability_required"
+  | "v2_visitor_id_required"
+  | "signing_secret_unavailable"
+  | "v1_assignment_rejected"
+  | "v2_assignment_config_invalid"
+  | "v2_readiness_not_ready"
+  | "other";
+
+const SAFE_PRICING_POLICY_REASONS = new Set<SafePricingPolicyReason>([
+  "v2_capability_required",
+  "v2_visitor_id_required",
+  "signing_secret_unavailable", // gitleaks:allow — closed-set diagnostic code, never a credential
+  "v1_assignment_rejected",
+  "v2_assignment_config_invalid",
+  "v2_readiness_not_ready",
+  "other",
+]);
+
+export interface PricingPolicyFailureMapping {
+  code: "BAD_REQUEST" | "UPSTREAM_UNAVAILABLE";
+  details: {
+    reason: "pricing_policy_request_invalid" | "pricing_policy_unavailable";
+    stage: "pricing_policy";
+    policyReason: SafePricingPolicyReason;
+  };
+}
+
+/**
+ * Single owner of the status a pricing-policy refusal earns, shared by every
+ * route that resolves one. A caller-attributable gap answers `400`; only a
+ * server that genuinely cannot price answers `503`, so a `503` on these routes
+ * stays a truthful outage signal.
+ */
+export function mapPricingPolicyFailure(error: unknown): PricingPolicyFailureMapping | null {
+  const caller = error instanceof CommercePricingPolicyRequestError;
+  if (!caller && !(error instanceof CommercePricingPolicyUnavailableError)) return null;
+  return {
+    code: caller ? "BAD_REQUEST" : "UPSTREAM_UNAVAILABLE",
+    details: {
+      reason: caller ? "pricing_policy_request_invalid" : "pricing_policy_unavailable",
+      stage: "pricing_policy",
+      policyReason: safePricingPolicyReason((error as { reason: unknown }).reason),
+    },
+  };
+}
+
+function safePricingPolicyReason(value: unknown): SafePricingPolicyReason {
+  return SAFE_PRICING_POLICY_REASONS.has(value as SafePricingPolicyReason)
+    ? value as SafePricingPolicyReason
+    : "other";
+}
+