@openlup/platform 0.16.0 → 0.18.0

package/src/promotions/promotionCodePreview.ts

@@ -0,0 +1,183 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type {
+  PromotionCodeBenefit,
+  PromotionCodePreviewRequest,
+  PromotionCodePreviewResponse,
+} from "./contracts/index.js";
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+import {
+  evaluatePromotionAdjustmentsV2,
+  type PromotionAdjustmentCandidate,
+} from "@openlup/core/promo";
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const PROMOTION_ENGINE_VERSION = "promotion-engine.v2" as const;
+
+export function createPromotionCodePreview({ minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR }: { minimumProductPayableMinor: number }) {
+  function generatePromotionCode(): string {
+    const bytes = randomBytes(10);
+    let bits = 0;
+    let buffer = 0;
+    let code = "";
+    for (const byte of bytes) {
+      buffer = (buffer << 8) | byte;
+      bits += 8;
+      while (bits >= 5) {
+        bits -= 5;
+        code += CROCKFORD_BASE32[(buffer >>> bits) & 31];
+        buffer &= (1 << bits) - 1;
+      }
+    }
+    return code;
+  }
+
+  function normalizePromotionCode(code: string): string {
+    return code.trim().toUpperCase();
+  }
+
+  function promotionPreviewProof(input: PromotionCodePreviewRequest, secret: string): string {
+    assertPreviewSecret(secret);
+    assertSupportedPreviewBenefits(input);
+    return createHmac("sha256", secret).update(previewProofPayload(input)).digest("base64url");
+  }
+
+  function verifyPromotionPreviewProof(
+    input: PromotionCodePreviewRequest,
+    proof: string,
+    secret: string,
+  ): boolean {
+    const expected = promotionPreviewProof(input, secret);
+    const expectedBytes = Buffer.from(expected);
+    const actualBytes = Buffer.from(proof);
+    return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+  }
+
+  function previewPromotionCode(
+    input: PromotionCodePreviewRequest,
+    secret: string,
+  ): PromotionCodePreviewResponse {
+    assertSupportedPreviewBenefits(input);
+    const eligible = input.context.referenceProductMinor >= input.minimumReferenceMinor;
+    const results = (["one_time", "subscription_initial"] as const).map((scope) => {
+      const currentProductMinor =
+        scope === "one_time"
+          ? input.context.oneTimeProductMinor
+          : input.context.subscriptionProductMinor;
+      const candidates = eligible
+        ? input.benefits
+          .map((benefit) => toCandidate(benefit, input.scopes, currentProductMinor))
+          .filter((candidate): candidate is PromotionAdjustmentCandidate => candidate !== null)
+        : [];
+      const result = evaluatePromotionAdjustmentsV2(
+        {
+          purchaseScope: scope,
+          referenceProductMinor: input.context.referenceProductMinor,
+          currentProductMinor,
+          shippingMinor: input.context.shippingMinor,
+          minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+        },
+        candidates,
+      );
+      return {
+        scope,
+        productPayableMinor: result.productPayableMinor,
+        shippingPayableMinor: result.shippingPayableMinor,
+        effectiveProductDiscountBps: result.effectiveProductDiscountBps,
+        winner: result.adjustments.some((adjustment) => adjustment.source === "code")
+          ? ("code" as const)
+          : ("automatic" as const),
+        floorApplied: result.adjustments.some((adjustment) => adjustment.floorApplied),
+        adjustments: result.adjustments.map((adjustment) => ({
+          lane: adjustment.lane,
+          kind: input.promotionEngineVersion === "promotion-engine.v1"
+            && adjustment.promotionId === "preview-product"
+            && input.benefits.some((benefit) => benefit.lane === "product" && benefit.kind === "percentage")
+            ? ("percentage" as const)
+            : adjustment.kind,
+          amountOffMinor: adjustment.amountOffMinor,
+          beforeMinor: adjustment.beforeMinor,
+          afterMinor: adjustment.afterMinor,
+        })),
+      };
+    });
+    return {
+      contractVersion: COMMERCE_CONTRACT_VERSION,
+      promotionEngineVersion: input.promotionEngineVersion,
+      previewProof: promotionPreviewProof(input, secret),
+      results,
+    };
+  }
+
+  function previewProofPayload(input: PromotionCodePreviewRequest): string {
+    return stableJson({
+      promotionEngineVersion: input.promotionEngineVersion,
+      minimumProductPayableMinor: MINIMUM_PRODUCT_PAYABLE_MINOR,
+      minimumReferenceMinor: input.minimumReferenceMinor,
+      benefits: input.benefits,
+      scopes: input.scopes,
+      context: input.context,
+    });
+  }
+
+  function assertPreviewSecret(secret: string): void {
+    if (Buffer.byteLength(secret, "utf8") < 32) {
+      throw new RangeError("promotion_preview_secret_too_short");
+    }
+  }
+
+  function assertSupportedPreviewBenefits(input: PromotionCodePreviewRequest): void {
+    if (input.benefits.some((benefit) => "validationState" in benefit)) {
+      throw new RangeError("promotion_preview_unsupported_legacy_value");
+    }
+  }
+
+  function toCandidate(
+    benefit: PromotionCodeBenefit,
+    scopes: PromotionCodePreviewRequest["scopes"],
+    currentProductMinor: number,
+  ): PromotionAdjustmentCandidate | null {
+    const base = {
+      promotionId: `preview-${benefit.lane}`,
+      codeId: "preview-code",
+      source: "code" as const,
+      name: "Promotion code preview",
+      scopes,
+    };
+    if ("validationState" in benefit) {
+      throw new RangeError("promotion_preview_unsupported_legacy_value");
+    }
+    if (("valueBps" in benefit && benefit.valueBps === 0)
+        || ("valueMinor" in benefit && benefit.valueMinor === 0)) return null;
+    if (benefit.kind === "target_percentage") return { ...base, ...benefit };
+    if (benefit.kind === "percentage" && benefit.lane === "product") {
+      const valueMinor = benefit.valueBps >= 10_000
+        ? currentProductMinor
+        : Number((BigInt(currentProductMinor) * BigInt(benefit.valueBps)) / 10_000n);
+      return {
+        ...base,
+        lane: "product",
+        kind: "fixed_amount",
+        valueMinor,
+      };
+    }
+    if (benefit.kind === "percentage" && benefit.lane === "shipping" && benefit.valueBps >= 10_000) {
+      return { ...base, lane: "shipping", kind: "free_shipping" };
+    }
+    if (benefit.kind === "percentage") return { ...base, ...benefit };
+    if (benefit.kind === "fixed_amount") return { ...base, ...benefit };
+    return { ...base, ...benefit };
+  }
+
+  function stableJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+      const record = value as Record<string, unknown>;
+      return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+        .join(",")}}`;
+    }
+    return JSON.stringify(value);
+  }
+
+  return { generatePromotionCode, normalizePromotionCode, promotionPreviewProof, verifyPromotionPreviewProof, previewPromotionCode };
+}

package/src/promotions/promotionCodeQuotePort.ts

@@ -0,0 +1,35 @@
+import type {
+  PromotionAdjustmentCandidate,
+  PromotionPurchaseScope,
+} from "@openlup/core/promo";
+import type {
+  CommerceCodeRejection,
+  CommerceCodeRejectionDetail,
+} from "../pricing/index.js";
+
+export type ResolvedPromotionCodeCandidate = PromotionAdjustmentCandidate & {
+  codeRevision: number;
+  definitionFingerprint: string;
+  minimumReferenceMinor: number;
+  validTo: string | null;
+};
+
+export interface ResolvePromotionCodeQuoteInput {
+  codes: readonly string[];
+  clientId: string | null;
+  purchaseScope: PromotionPurchaseScope;
+  referenceProductMinor: number;
+  atTime: string;
+}
+
+export interface PromotionCodeQuoteResolution {
+  candidates: ResolvedPromotionCodeCandidate[];
+  codeRejections: CommerceCodeRejection[];
+  /** Additive v2 RPC detail; old RPC fallback returns an empty array. */
+  codeRejectionDetails: CommerceCodeRejectionDetail[];
+}
+
+/** Advisory quote read only. Capacity is authoritatively claimed by the order transaction. */
+export interface PromotionCodeQuotePort {
+  resolve(input: ResolvePromotionCodeQuoteInput): Promise<PromotionCodeQuoteResolution>;
+}

package/src/promotions/promotionQuoteAcceptance.ts

@@ -0,0 +1,284 @@
+import type { ResolvedAcquisitionTerms } from "../pricing/index.js";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import type { CommerceQuote, CommerceQuoteDiscount } from "../pricing/index.js";
+import type { PromotionAcceptanceTelemetry } from "./promotionAcceptanceTelemetry.js";
+import {
+  projectPromotionQuoteMoney,
+  promotionQuoteMoneySections,
+  PROMOTION_QUOTE_MONEY_SECTIONS,
+  stableJson,
+  type PromotionQuoteMismatchField,
+} from "./promotionQuoteBinding.js";
+export const PROMOTION_ACCEPTANCE_MAX_TTL_MS = 72 * 60 * 60 * 1_000;
+export const PROMOTION_ACCEPTANCE_CLOCK_SKEW_MS = 60_000;
+const payloadSchema = z.object({
+  v: z.literal(1),
+  kid: z.string().regex(/^[0-9a-f]{16}$/),
+  iat: z.number().int().nonnegative(),
+  exp: z.number().int().positive(),
+  engine: z.literal("promotion-engine.v2"),
+  requestBinding: z.string().regex(/^[0-9a-f]{64}$/),
+  codeBinding: z.string().regex(/^[0-9a-f]{64}$/),
+  quoteBinding: z.string().regex(/^[0-9a-f]{64}$/),
+  // Legacy payloads still parse, but their whole-quote binding is rejected.
+  // Quote refresh issues a new money-bound token; missing sections report other.
+  sectionBindings: z.object(Object.fromEntries(PROMOTION_QUOTE_MONEY_SECTIONS
+    .map((section) => [section, z.string().regex(/^[0-9a-f]{64}$/)])) as Record<
+      PromotionQuoteMoneySectionKey, z.ZodString>).strict().optional(),
+  totalMinor: z.number().int().nonnegative(),
+  currency: z.string().length(3),
+}).strict();
+type PromotionQuoteMoneySectionKey = (typeof PROMOTION_QUOTE_MONEY_SECTIONS)[number];
+export interface PromotionAcceptanceKeyring {
+  current: string;
+  previous?: string | null;
+}
+export type PromotionAcceptanceDiagnostic = {
+  accepted: boolean;
+  reason: PromotionAcceptanceTelemetry["reason"];
+  keySlot: PromotionAcceptanceTelemetry["keySlot"];
+  expiryBucket: PromotionAcceptanceTelemetry["expiryBucket"];
+  /** Present only on `quote_mismatch`: which money section diverged. */
+  mismatchField?: PromotionQuoteMismatchField;
+};
+
+export function createPromotionQuoteAcceptance<Request extends { promoCodes: string[] }>({ projectRequest }: { projectRequest(request: Request): unknown }) {
+  function issuePromotionQuoteAcceptance(input: {
+    request: Request;
+    quote: CommerceQuote;
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+    keyring: PromotionAcceptanceKeyring;
+    now?: Date;
+  }): string | null {
+    return issuePromotionQuoteAcceptanceWithOutcome(input).token;
+  }
+
+  function issuePromotionQuoteAcceptanceWithOutcome(input: {
+    request: Request;
+    quote: CommerceQuote;
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+    keyring: PromotionAcceptanceKeyring;
+    now?: Date;
+  }): { token: string | null; diagnostic: PromotionAcceptanceDiagnostic } {
+    const evidence = v2Discounts(input.quote);
+    if (evidence.length === 0 && !input.acquisitionTerms) return {
+      token: null,
+      diagnostic: rejected("no_v2_adjustment"),
+    };
+    assertSecret(input.keyring.current);
+    const nowMs = (input.now ?? new Date()).getTime();
+    const codeExpiry = Math.min(...evidence.map((discount) =>
+      discount.promotionCodeValidTo ? Date.parse(discount.promotionCodeValidTo) : Number.POSITIVE_INFINITY));
+    const exp = Math.min(nowMs + PROMOTION_ACCEPTANCE_MAX_TTL_MS, codeExpiry);
+    if (!Number.isFinite(exp) || exp <= nowMs) return {
+      token: null,
+      diagnostic: rejected("ttl_invalid"),
+    };
+    const payload = payloadSchema.parse({
+      v: 1,
+      kid: keyId(input.keyring.current),
+      iat: nowMs,
+      exp,
+      engine: "promotion-engine.v2",
+      requestBinding: requestBinding(input.request, input.keyring.current),
+      codeBinding: codeBinding(input.request.promoCodes, input.keyring.current),
+      quoteBinding: quoteBinding(input.quote, input.keyring.current, input.acquisitionTerms),
+      sectionBindings: sectionBindings(input.quote, input.keyring.current, input.acquisitionTerms),
+      totalMinor: input.quote.totalGross.amountMinor,
+      currency: input.quote.totalGross.currency,
+    });
+    const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    return {
+      token: `${encoded}.${sign(encoded, input.keyring.current)}`,
+      diagnostic: {
+        accepted: true,
+        reason: "issued",
+        keySlot: "current",
+        expiryBucket: expiryBucket(exp, nowMs),
+      },
+    };
+  }
+
+  function verifyPromotionQuoteAcceptance(input: {
+    token: string;
+    request: Request;
+    quote: CommerceQuote;
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+    expectedTotal: { amountMinor: number; currency: string };
+    keyring: PromotionAcceptanceKeyring;
+    now?: Date;
+  }): boolean {
+    return verifyPromotionQuoteAcceptanceWithOutcome(input).accepted;
+  }
+
+  function verifyPromotionQuoteAcceptanceWithOutcome(input: {
+    token: string;
+    request: Request;
+    quote: CommerceQuote;
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+    expectedTotal: { amountMinor: number; currency: string };
+    keyring: PromotionAcceptanceKeyring;
+    now?: Date;
+  }): PromotionAcceptanceDiagnostic {
+    const verified = verifyEnvelopeWithOutcome(input.token, input.keyring, input.now ?? new Date());
+    if (verified.verified === false) return verified.diagnostic;
+    const { payload, secret } = verified;
+    const base = { keySlot: verified.keySlot, expiryBucket: verified.expiryBucket };
+    if (payload.requestBinding !== requestBinding(input.request, secret)) {
+      return { accepted: false, reason: "request_mismatch", ...base };
+    }
+    if (payload.codeBinding !== codeBinding(input.request.promoCodes, secret)) {
+      return { accepted: false, reason: "code_mismatch", ...base };
+    }
+    if (payload.quoteBinding !== quoteBinding(input.quote, secret, input.acquisitionTerms)) {
+      const mismatchField = namedMismatchField(payload.sectionBindings, input.quote, secret, input.acquisitionTerms);
+      return { accepted: false, reason: "quote_mismatch", mismatchField, ...base };
+    }
+    if (payload.totalMinor !== input.expectedTotal.amountMinor) {
+      return { accepted: false, reason: "total_mismatch", ...base };
+    }
+    if (payload.currency !== input.expectedTotal.currency) {
+      return { accepted: false, reason: "currency_mismatch", ...base };
+    }
+    if (v2Discounts(input.quote).length === 0 && !input.acquisitionTerms) {
+      return { accepted: false, reason: "no_v2_adjustment_in_quote", ...base };
+    }
+    return { accepted: true, reason: "accepted", ...base };
+  }
+
+  function verifyEnvelopeWithOutcome(
+    token: string,
+    keyring: PromotionAcceptanceKeyring,
+    now: Date,
+  ): ({
+    verified: true;
+    payload: z.infer<typeof payloadSchema>;
+    secret: string;
+    keySlot: "current" | "previous";
+    expiryBucket: PromotionAcceptanceTelemetry["expiryBucket"];
+  } | { verified: false; diagnostic: PromotionAcceptanceDiagnostic }) {
+    const [encoded, signature, extra] = token.split(".");
+    if (!encoded || !signature || extra || encoded.length > 8_192 || signature.length !== 43) {
+      return { verified: false, diagnostic: rejected("malformed") };
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    } catch {
+      return { verified: false, diagnostic: rejected("malformed") };
+    }
+    const payload = payloadSchema.safeParse(parsed);
+    if (!payload.success) return { verified: false, diagnostic: rejected("malformed") };
+    const candidates = [
+      { slot: "current" as const, secret: keyring.current },
+      { slot: "previous" as const, secret: keyring.previous },
+    ].filter((candidate): candidate is { slot: "current" | "previous"; secret: string } =>
+      typeof candidate.secret === "string" && candidate.secret.length >= 32);
+    const candidate = candidates.find((value) => keyId(value.secret) === payload.data.kid);
+    if (!candidate) return { verified: false, diagnostic: rejected("unknown_key") };
+    if (!safeEqual(signature, sign(encoded, candidate.secret))) {
+      return { verified: false, diagnostic: rejected("signature_invalid") };
+    }
+    const nowMs = now.getTime();
+    const safeBase = { keySlot: candidate.slot, expiryBucket: expiryBucket(payload.data.exp, nowMs) };
+    if (payload.data.exp <= payload.data.iat ||
+      payload.data.exp - payload.data.iat > PROMOTION_ACCEPTANCE_MAX_TTL_MS) {
+      return { verified: false, diagnostic: { accepted: false, reason: "ttl_invalid", ...safeBase } };
+    }
+    if (payload.data.iat > nowMs + PROMOTION_ACCEPTANCE_CLOCK_SKEW_MS) {
+      return { verified: false, diagnostic: { accepted: false, reason: "not_yet_valid", ...safeBase } };
+    }
+    if (nowMs >= payload.data.exp) {
+      return { verified: false, diagnostic: { accepted: false, reason: "expired", ...safeBase } };
+    }
+    return {
+      verified: true,
+      payload: payload.data,
+      secret: candidate.secret,
+      keySlot: candidate.slot,
+      expiryBucket: expiryBucket(payload.data.exp, nowMs),
+    };
+  }
+
+  function rejected(reason: PromotionAcceptanceTelemetry["reason"]): PromotionAcceptanceDiagnostic {
+    return { accepted: false, reason, keySlot: "none", expiryBucket: "none" };
+  }
+
+  function expiryBucket(exp: number, now: number): PromotionAcceptanceTelemetry["expiryBucket"] {
+    const remaining = exp - now;
+    if (remaining <= 0) return "expired";
+    if (remaining < 60 * 60 * 1_000) return "lt_1h";
+    if (remaining < 24 * 60 * 60 * 1_000) return "1_24h";
+    return "24_72h";
+  }
+
+  function v2Discounts(quote: CommerceQuote): CommerceQuoteDiscount[] {
+    return quote.discounts.filter((discount) =>
+      discount.promotionEngineVersion === "promotion-engine.v2" &&
+      discount.reasonCode === "promotion_code_v2");
+  }
+
+  function requestBinding(request: Request, secret: string): string {
+    return hmac(secret, stableJson(projectRequest(request)));
+  }
+
+  function codeBinding(codes: readonly string[], secret: string): string {
+    return hmac(secret, stableJson([...new Set(codes.map((code) => code.trim().toUpperCase()))].sort()));
+  }
+
+  function quoteBinding(quote: CommerceQuote, secret: string, acquisitionTerms?: ResolvedAcquisitionTerms): string {
+    return hmac(secret, stableJson(projectPromotionQuoteMoney(quote, acquisitionTerms)));
+  }
+
+  function sectionBindings(
+    quote: CommerceQuote,
+    secret: string,
+    acquisitionTerms?: ResolvedAcquisitionTerms,
+  ): Record<PromotionQuoteMoneySectionKey, string> {
+    const sections = promotionQuoteMoneySections(quote, acquisitionTerms);
+    return Object.fromEntries(PROMOTION_QUOTE_MONEY_SECTIONS
+      .map((section) => [section, hmac(secret, stableJson(sections[section]))])) as Record<
+        PromotionQuoteMoneySectionKey, string>;
+  }
+
+  /**
+   * The verifier holds only the issuer's HMACs, never the issued quote, so the
+   * differing section is found by comparing per-section hashes in a fixed order.
+   */
+  function namedMismatchField(
+    issued: Record<PromotionQuoteMoneySectionKey, string> | undefined,
+    quote: CommerceQuote,
+    secret: string,
+    acquisitionTerms?: ResolvedAcquisitionTerms,
+  ): PromotionQuoteMismatchField {
+    if (!issued) return "other";
+    const verified = sectionBindings(quote, secret, acquisitionTerms);
+    return PROMOTION_QUOTE_MONEY_SECTIONS
+      .find((section) => issued[section] !== verified[section]) ?? "other";
+  }
+
+  function keyId(secret: string): string {
+    return createHash("sha256").update(secret).digest("hex").slice(0, 16);
+  }
+
+  function hmac(secret: string, value: string): string {
+    return createHmac("sha256", secret).update(value).digest("hex");
+  }
+
+  function sign(encoded: string, secret: string): string {
+    return createHmac("sha256", secret).update(encoded).digest("base64url");
+  }
+
+  function safeEqual(left: string, right: string): boolean {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+  }
+
+  function assertSecret(secret: string): void {
+    if (secret.length < 32) throw new Error("promotion_acceptance_secret_invalid");
+  }
+
+  return { issuePromotionQuoteAcceptance, issuePromotionQuoteAcceptanceWithOutcome, verifyPromotionQuoteAcceptance, verifyPromotionQuoteAcceptanceWithOutcome };
+}

package/src/promotions/promotionQuoteBinding.ts

@@ -0,0 +1,158 @@
+import { acquisitionQuoteBinding, type ResolvedAcquisitionTerms } from "../pricing/index.js";
+import type {
+  CommerceMoney,
+  CommerceQuote,
+  CommerceQuoteDiscount,
+} from "../pricing/index.js";
+
+/**
+ * The canonical money projection an acceptance token binds.
+ *
+ * ⛔ The token protects **what the customer pays**, never how it was presented
+ * or which server-only evidence produced it. Everything outside this projection
+ * is deliberately unbound: `label`, `reasonCode`, `customerSemantic`, `code`,
+ * `promotionCodeRevision`, `promotionCodeScopes`, `promotionMinimumReferenceMinor`,
+ * `promotionCodeValidTo`, `floorApplied`, `context`, `codeRejections`,
+ * `codeRejectionDetails`, `pricingComponents` and `catalogFacts`. Those differ
+ * legitimately between the two surfaces that share one token — the public quote
+ * route signs the contract-parsed public projection while the checkout guard
+ * verifies the raw server-authoritative quote, which carries `catalogFacts`
+ * (with a per-request `atTime`) that the public projection strips — so binding
+ * them turned every strict-path v2 code checkout into a permanent rejection.
+ *
+ * What stays bound is every amount and every discount identity: change a price,
+ * a quantity, a tax split, shipping, a discount amount, which promotion granted
+ * it, or what it applies to, and the token stops verifying.
+ */
+export interface PromotionQuoteMoneyLine {
+  sku: string;
+  quantity: number;
+  unitPriceGross: CommerceMoney;
+  lineSubtotalGross: CommerceMoney;
+  tax: {
+    vatRateBps: number;
+    netAmount: CommerceMoney;
+    vatAmount: CommerceMoney;
+    grossAmount: CommerceMoney;
+  };
+}
+
+export interface PromotionQuoteMoneyDiscount {
+  promotionId: string;
+  appliesTo: CommerceQuoteDiscount["appliesTo"];
+  amountOffMinor: number;
+  promotionCodeId: string | null;
+  promotionDefinitionFingerprint: string | null;
+  promotionBenefitKind: NonNullable<CommerceQuoteDiscount["promotionBenefitKind"]> | null;
+  promotionBenefitValueBps: number | null;
+  promotionBenefitValueMinor: number | null;
+}
+
+export interface PromotionQuoteMoneyProjection {
+  acquisitionTerms?: ResolvedAcquisitionTerms;
+  currency: string;
+  totalGross: CommerceMoney;
+  netTotal: CommerceMoney;
+  taxTotal: CommerceMoney;
+  subtotalGross: CommerceMoney;
+  discountTotalGross: CommerceMoney;
+  shippingGross: CommerceMoney | null;
+  shippingDiscountGross: CommerceMoney | null;
+  lines: PromotionQuoteMoneyLine[];
+  discounts: PromotionQuoteMoneyDiscount[];
+}
+
+/** The five sections the token hashes separately so a mismatch can name itself. */
+export const PROMOTION_QUOTE_MONEY_SECTIONS = [
+  "lines",
+  "discounts",
+  "shipping",
+  "totals",
+  "currency",
+] as const;
+
+export type PromotionQuoteMoneySection = (typeof PROMOTION_QUOTE_MONEY_SECTIONS)[number];
+
+/** `other` is the honest answer for a token minted before section bindings existed. */
+export const PROMOTION_QUOTE_MISMATCH_FIELDS = [
+  ...PROMOTION_QUOTE_MONEY_SECTIONS,
+  "other",
+] as const;
+
+export type PromotionQuoteMismatchField = (typeof PROMOTION_QUOTE_MISMATCH_FIELDS)[number];
+
+/**
+ * Discount order is preserved: the promotion engine emits its lanes
+ * deterministically, so a reordering is a real evaluation difference.
+ */
+export function projectPromotionQuoteMoney(quote: CommerceQuote, acquisitionTerms?: ResolvedAcquisitionTerms): PromotionQuoteMoneyProjection {
+  return {
+    ...acquisitionQuoteBinding(acquisitionTerms),
+    currency: quote.currency,
+    totalGross: quote.totalGross,
+    netTotal: quote.netTotal,
+    taxTotal: quote.taxTotal,
+    subtotalGross: quote.subtotalGross,
+    discountTotalGross: quote.discountTotalGross,
+    shippingGross: quote.shippingGross ?? null,
+    shippingDiscountGross: quote.shippingDiscountGross ?? null,
+    lines: quote.lines.map((line) => ({
+      sku: line.sku,
+      quantity: line.quantity,
+      unitPriceGross: line.unitPriceGross,
+      lineSubtotalGross: line.lineSubtotalGross,
+      tax: {
+        vatRateBps: line.tax.vatRateBps,
+        netAmount: line.tax.netAmount,
+        vatAmount: line.tax.vatAmount,
+        grossAmount: line.tax.grossAmount,
+      },
+    })),
+    discounts: quote.discounts.map((discount) => ({
+      promotionId: discount.promotionId,
+      appliesTo: discount.appliesTo,
+      amountOffMinor: discount.amountOffMinor,
+      promotionCodeId: discount.promotionCodeId ?? null,
+      promotionDefinitionFingerprint: discount.promotionDefinitionFingerprint ?? null,
+      promotionBenefitKind: discount.promotionBenefitKind ?? null,
+      promotionBenefitValueBps: discount.promotionBenefitValueBps ?? null,
+      promotionBenefitValueMinor: discount.promotionBenefitValueMinor ?? null,
+    })),
+  };
+}
+
+/** Same projection, partitioned. The union of these five sections is the whole projection. */
+export function promotionQuoteMoneySections(
+  quote: CommerceQuote,
+  acquisitionTerms?: ResolvedAcquisitionTerms,
+): Record<PromotionQuoteMoneySection, unknown> {
+  const money = projectPromotionQuoteMoney(quote, acquisitionTerms);
+  return {
+    lines: money.lines,
+    discounts: money.discounts,
+    shipping: {
+      shippingGross: money.shippingGross,
+      shippingDiscountGross: money.shippingDiscountGross,
+    },
+    totals: {
+      ...acquisitionQuoteBinding(money.acquisitionTerms),
+      totalGross: money.totalGross,
+      netTotal: money.netTotal,
+      taxTotal: money.taxTotal,
+      subtotalGross: money.subtotalGross,
+      discountTotalGross: money.discountTotalGross,
+    },
+    currency: money.currency,
+  };
+}
+
+/** Key-sorted, `undefined`-dropping JSON. Every acceptance binding hashes this shape. */
+export function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}