@openlup/platform 0.17.0 → 0.18.0

package/src/pricing/index.ts

@@ -0,0 +1,52 @@
+export * from "./contracts/index.js";
+export { CommercePriceAuthorityError } from "./ports.js";
+export type { CommercePriceAuthorityPort } from "./ports.js";
+export { createCommercePriceAuthorityPort, selectUniqueEffectivePriceList } from "./commercePriceAuthority.js";
+export type { CommercePriceAuthorityReadPort, TimedAuthorityValue } from "./commercePriceAuthority.js";
+export { subscriptionPricePolicySemanticsSchema, subscriptionPricePolicyCanonicalInputSchema, subscriptionPricePolicyRevisionSchema, SubscriptionPricePolicyDigestError, canonicalSubscriptionPricePolicyTuple, digestSubscriptionPricePolicy, assertSubscriptionPricePolicyDigest, deriveSubscriptionUnitPrice } from "./subscriptionPricePolicy.js";
+export { offerPolicyVersionSchema, promotionEngineVersionSchema, pricingPolicyRequestSchema, pricingPolicySnapshotSchema } from "./offerPolicySchemas.js";
+export { createPricingPolicyToken, verifyPricingPolicyToken, resolvePricingPolicy } from "./pricingPolicyToken.js";
+export type { PricingPolicyTokenPayload } from "./pricingPolicyToken.js";
+export { CommercePricingPolicyUnavailableError, PRICING_POLICY_REQUEST_REASONS, CommercePricingPolicyRequestError, mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+export type { PricingPolicyRequestReason, SafePricingPolicyReason, PricingPolicyFailureMapping } from "./commercePricingPolicyErrors.js";
+export { CommerceQuoteError, CommerceQuoteSnapshotError } from "./quotePorts.js";
+export type { CreateQuoteOptions, CommerceQuotePort, CommerceQuoteSnapshotVerifierPort, CommerceQuoteErrorCode, CommerceQuoteSnapshotErrorCode } from "./quotePorts.js";
+export { createCommerceQuotePrimitives } from "./quotePrimitives.js";
+export { createCommerceQuoteSchemas, splitIncludedVat, quoteMoneyCurrenciesMatch } from "./quoteSchemas.js";
+export { quoteDiscountSchema, hasValidV2PromotionEvidence } from "./quotePromotionEvidence.js";
+export { quoteCodeRejectionDetailSchema } from "./quoteCodeRejectionDetails.js";
+export { catalogFactsProvenanceSchema, rejectCatalogFactsFromPublicQuote } from "./catalogFactsSchemas.js";
+export { createCatalogFactsProvenance, catalogFactsForQuoteLine, projectPublicQuoteSnapshot } from "./catalogFactsProvenance.js";
+export { CommerceQuoteCatalogReadError } from "./commerceQuoteCatalogReadPort.js";
+export type { CommerceQuoteCatalogItem, CommerceQuoteCatalogReadPort, CommerceQuoteCatalogReadRefusalCode } from "./commerceQuoteCatalogReadPort.js";
+export { assertSupportedCommerceTaxProfile } from "./taxProfileGuard.js";
+
+export { buildSkuIndex, eligibleQtyForMode, resolveOneTimeComparison, resolveStrictQuotePrice, assertSubscriptionCheapest, toGrossMinor, calculateIncludedVat, mapPricingComponent, moneyIn, sum } from "./dbBackedCommerceQuoteHelpers.js";
+export type { SkuIndexEntry, StrictQuotePriceResolution } from "./dbBackedCommerceQuoteHelpers.js";
+export { createDbBackedCommerceQuotePort } from "./dbBackedCommerceQuotePort.js";
+export type { DbBackedCommerceQuotePortDeps, QuotePromotionResult } from "./dbBackedCommerceQuotePort.js";
+export { createExpectedQuote } from "./commerceQuoteSnapshotExpect.js";
+export type { QuoteSnapshotExpectMessages } from "./commerceQuoteSnapshotExpect.js";
+export { createDbBackedCommerceQuoteSnapshotVerifier } from "./dbBackedCommerceQuoteSnapshotVerifier.js";
+export { createCommerceQuoteHandler } from "./commerceQuoteHandler.js";
+export type { CommerceQuoteHandlerDeps } from "./commerceQuoteHandler.js";
+export { createCommerceQuoteBatchHandler } from "./commerceQuoteBatchHandler.js";
+export type { CommerceQuoteBatchHandlerDeps } from "./commerceQuoteBatchHandler.js";
+export { createCommerceOfferPricingSchemas } from "./offerPricingSchemas.js";
+export { projectCommerceOfferPricing } from "./commerceOfferPricing.js";
+export type { CommerceOfferPricingDeps } from "./commerceOfferPricing.js";
+export { createCommerceOfferPricingHandler, COMMERCE_OFFER_PRICING_CACHE_CONTROL, COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL, OFFER_POLICY_CAPABILITY_HEADER, OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER } from "./commerceOfferPricingHandler.js";
+export type { CommerceOfferPricingHandlerDeps } from "./commerceOfferPricingHandler.js";
+export { createCommerceOfferPricingCache } from "./commerceOfferPricingCache.js";
+export type { CommerceOfferPricingCache } from "./commerceOfferPricingCache.js";
+export { OFFER_POLICY_V2_READINESS_CONTRACT, createOfferPolicyReadinessCache, readOfferPolicyV2Readiness, resetOfferPolicyReadinessCacheForTests } from "./offerPolicyReadiness.js";
+export type { OfferPolicyV2Readiness, OfferPolicyReadinessPort, OfferPolicyReadinessCache } from "./offerPolicyReadiness.js";
+export * from "./acquisitionFinancialPolicy.js";
+export * from "./acquisitionTermsSchemas.js";
+export * from "./acquisitionTerms.js";
+export * from "./quoteAcquisitionTerms.js";
+export * from "./acquisitionQuoteBinding.js";
+export * from "./acquisitionOfferPricingSchemas.js";
+export * from "./acquisitionOfferPricing.js";
+export * from "./acquisitionOfferPricingHandler.js";
+export * from "./acquisitionReadiness.js";

package/src/pricing/offerPolicyReadiness.ts

@@ -0,0 +1,110 @@
+export const OFFER_POLICY_V2_READINESS_CONTRACT = "commerce-offer-policy-v2-readiness.v1";
+
+export interface OfferPolicyV2Readiness {
+  contractVersion: typeof OFFER_POLICY_V2_READINESS_CONTRACT;
+  ready: boolean;
+  checkedAt: string;
+  reasons: string[];
+}
+
+export interface OfferPolicyReadinessPort {
+  readOfferPolicyV2Readiness(): Promise<unknown>;
+}
+
+interface CacheEntry {
+  expiresAtMs: number;
+  readiness: OfferPolicyV2Readiness;
+}
+
+export interface OfferPolicyReadinessCache {
+  read(port: OfferPolicyReadinessPort): Promise<OfferPolicyV2Readiness>;
+  clear(): void;
+}
+
+export function createOfferPolicyReadinessCache(input: {
+  now?: () => number;
+  positiveTtlMs?: number;
+  negativeTtlMs?: number;
+} = {}): OfferPolicyReadinessCache {
+  const now = input.now ?? Date.now;
+  const positiveTtlMs = Math.min(60_000, Math.max(0, input.positiveTtlMs ?? 60_000));
+  const negativeTtlMs = Math.min(5_000, Math.max(0, input.negativeTtlMs ?? 5_000));
+  let cached: CacheEntry | null = null;
+  let inFlight: Promise<OfferPolicyV2Readiness> | null = null;
+
+  return {
+    read(port) {
+      const current = now();
+      if (cached && cached.expiresAtMs > current) return Promise.resolve(cached.readiness);
+      if (inFlight) return inFlight;
+      const startedAtMs = current;
+      inFlight = loadFailClosed(port)
+        .then((readiness) => {
+          cached = {
+            readiness,
+            // Bound staleness from the start of the database read. A slow RPC
+            // must consume the TTL, not extend a green decision past 60s.
+            expiresAtMs: startedAtMs + (readiness.ready ? positiveTtlMs : negativeTtlMs),
+          };
+          return readiness;
+        })
+        .finally(() => {
+          inFlight = null;
+        });
+      return inFlight;
+    },
+    clear() {
+      cached = null;
+      inFlight = null;
+    },
+  };
+}
+
+const sharedCache = createOfferPolicyReadinessCache();
+
+export function readOfferPolicyV2Readiness(
+  port: OfferPolicyReadinessPort,
+): Promise<OfferPolicyV2Readiness> {
+  return sharedCache.read(port);
+}
+
+export function resetOfferPolicyReadinessCacheForTests(isTest: boolean): void {
+  if (isTest) sharedCache.clear();
+}
+
+async function loadFailClosed(port: OfferPolicyReadinessPort): Promise<OfferPolicyV2Readiness> {
+  try {
+    const parsed = parseReadiness(await port.readOfferPolicyV2Readiness());
+    return parsed ?? unavailable("readiness_contract_invalid");
+  } catch {
+    return unavailable("readiness_rpc_unavailable");
+  }
+}
+
+function parseReadiness(value: unknown): OfferPolicyV2Readiness | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (
+    record.contractVersion !== OFFER_POLICY_V2_READINESS_CONTRACT ||
+    typeof record.ready !== "boolean" ||
+    typeof record.checkedAt !== "string" ||
+    !Number.isFinite(Date.parse(record.checkedAt)) ||
+    !Array.isArray(record.reasons) ||
+    !record.reasons.every((reason) => typeof reason === "string")
+  ) return null;
+  return {
+    contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+    ready: record.ready,
+    checkedAt: record.checkedAt,
+    reasons: record.reasons,
+  };
+}
+
+function unavailable(reason: string): OfferPolicyV2Readiness {
+  return {
+    contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+    ready: false,
+    checkedAt: new Date(0).toISOString(),
+    reasons: [reason],
+  };
+}

package/src/pricing/offerPolicySchemas.ts

@@ -0,0 +1,23 @@
+import { z } from "./validation.js";
+import { OFFER_POLICY_V1, OFFER_POLICY_V2, PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2, OFFER_POLICY_V2_CAPABILITY } from "./contracts/index.js";
+
+export const offerPolicyVersionSchema = z.enum([OFFER_POLICY_V1, OFFER_POLICY_V2]);
+export const promotionEngineVersionSchema = z.enum([PROMOTION_ENGINE_V1, PROMOTION_ENGINE_V2]);
+
+/** Client capability plus an opaque server-signed assignment. Never a version selector. */
+export const pricingPolicyRequestSchema = z.object({
+  capability: z.literal(OFFER_POLICY_V2_CAPABILITY).optional(),
+  token: z.string().trim().min(32).max(2048).optional(),
+}).strict();
+
+export const pricingPolicySnapshotSchema = z.object({
+  offerPolicyVersion: offerPolicyVersionSchema,
+  promotionEngineVersion: promotionEngineVersionSchema,
+  pricingPolicyToken: z.string().trim().min(32).max(2048).optional(),
+}).strict().refine(
+  (value) =>
+    (value.offerPolicyVersion === OFFER_POLICY_V1 && value.promotionEngineVersion === PROMOTION_ENGINE_V1) ||
+    (value.offerPolicyVersion === OFFER_POLICY_V2 && value.promotionEngineVersion === PROMOTION_ENGINE_V2),
+  { message: "offer policy and promotion engine versions must be paired" },
+);
+

package/src/pricing/offerPricingSchemas.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import type { CommerceMoney } from "./contracts/money.js";
+import { COMMERCE_OFFER_PRICING_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION } from "./contracts/offer.js";
+import { pricingPolicySnapshotSchema } from "./offerPolicySchemas.js";
+export function createCommerceOfferPricingSchemas<ScopeV1 extends string, ScopeV2 extends string>({
+  commerceMoneySchema, catalogProductSlugSchema, scopeV1Schema, scopeV2Schema,
+  minimumProductPayableMinor, minimumProductPayableMessage,
+}: {
+  commerceMoneySchema: z.ZodType<CommerceMoney>;
+  catalogProductSlugSchema: z.ZodType<string>;
+  scopeV1Schema: z.ZodType<ScopeV1>;
+  scopeV2Schema: z.ZodType<ScopeV2>;
+  minimumProductPayableMinor: number;
+  minimumProductPayableMessage: string;
+}) {
+const offerPriceSchema = z
+  .object({
+    packageGross: commerceMoneySchema,
+    unitGross: commerceMoneySchema,
+  })
+  .strict();
+
+const commerceProductOfferPricingSchema = z
+  .object({
+    productSlug: catalogProductSlugSchema,
+    unitCount: z.number().int().positive(),
+    oneTime: offerPriceSchema,
+    subscriptionInitial: offerPriceSchema,
+    subscriptionRecurring: offerPriceSchema,
+    catalogAnchorUnitGross: commerceMoneySchema,
+    initialDiscountPercent: z.number().int().min(0).max(100),
+    recurringDiscountPercent: z.number().int().min(0).max(100),
+  })
+  .strict();
+
+const commerceOfferPricingV1ResponseSchema = z
+  .object({
+    contractVersion: z.literal(COMMERCE_OFFER_PRICING_CONTRACT_VERSION),
+    scope: scopeV1Schema,
+    products: z.array(commerceProductOfferPricingSchema).min(1),
+    minimum: z
+      .object({
+        oneTime: commerceProductOfferPricingSchema,
+        subscription: commerceProductOfferPricingSchema,
+      })
+      .strict(),
+  })
+  .strict();
+
+const commerceOfferPricingV2ResponseSchema = z
+  .object({
+    contractVersion: z.literal(COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION),
+    scope: scopeV2Schema,
+    pricingPolicy: pricingPolicySnapshotSchema,
+    products: z.array(commerceProductOfferPricingSchema).min(1),
+    minimum: z.object({
+      oneTime: commerceProductOfferPricingSchema,
+      subscription: commerceProductOfferPricingSchema,
+    }).strict(),
+    shipping: z.object({
+      gross: commerceMoneySchema,
+      discountGross: commerceMoneySchema,
+      payable: commerceMoneySchema,
+    }).strict(),
+    minimumProductPayable: commerceMoneySchema,
+  })
+  .strict()
+  .refine(
+    (value) =>
+      value.pricingPolicy.offerPolicyVersion === "commerce.offer-policy.v2" &&
+      value.pricingPolicy.promotionEngineVersion === "promotion-engine.v2",
+    { message: "offer-pricing v2 requires the paired v2 policy", path: ["pricingPolicy"] },
+  )
+  .refine(
+    (value) => value.minimumProductPayable.amountMinor === minimumProductPayableMinor,
+    { message: minimumProductPayableMessage, path: ["minimumProductPayable"] },
+  )
+  .refine(
+    (value) =>
+      value.shipping.payable.amountMinor ===
+      value.shipping.gross.amountMinor - value.shipping.discountGross.amountMinor,
+    { message: "offer-pricing v2 shipping arithmetic is inconsistent", path: ["shipping"] },
+  );
+
+const commerceOfferPricingResponseSchema = z.union([
+  commerceOfferPricingV1ResponseSchema,
+  commerceOfferPricingV2ResponseSchema,
+]);
+
+return { commerceProductOfferPricingSchema, commerceOfferPricingV1ResponseSchema,
+  commerceOfferPricingV2ResponseSchema, commerceOfferPricingResponseSchema };
+}

package/src/pricing/ports.ts

@@ -0,0 +1,17 @@
+import type { CommercePriceAuthorityQuery, CommercePriceAuthorityResult, CommercePriceAuthorityRefusal } from "./contracts/index.js";
+
+/** Named refusal from the strict current-money authority. */
+export class CommercePriceAuthorityError extends Error {
+  constructor(readonly code: CommercePriceAuthorityRefusal) {
+    super(code);
+    this.name = "CommercePriceAuthorityError";
+  }
+}
+
+/**
+ * Resolves one current, exact base anchor and either a validated policy-derived
+ * subscription amount or the narrowly permitted pre-cutover legacy observation.
+ */
+export interface CommercePriceAuthorityPort {
+  resolvePrice(query: CommercePriceAuthorityQuery): Promise<CommercePriceAuthorityResult>;
+}

package/src/pricing/pricingPolicyToken.ts

@@ -0,0 +1,119 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import {
+  OFFER_POLICY_V1,
+  OFFER_POLICY_V2,
+  OFFER_POLICY_V2_CAPABILITY,
+  PROMOTION_ENGINE_V1,
+  PROMOTION_ENGINE_V2,
+  type OfferPolicyVersion,
+  type PromotionEngineVersion,
+} from "./contracts/index.js";
+
+const TOKEN_PREFIX = "pp1";
+// Rollout contract: an already-started checkout keeps its assigned policy for
+// at least the 72-hour compatibility window, including during a rollback.
+const DEFAULT_TTL_MS = 72 * 60 * 60 * 1_000;
+
+export interface PricingPolicyTokenPayload {
+  assignmentKeyHash: string;
+  issuedAtMs: number;
+  expiresAtMs: number;
+  offerPolicyVersion: OfferPolicyVersion;
+  promotionEngineVersion: PromotionEngineVersion;
+}
+
+interface CreateTokenInput extends Omit<PricingPolicyTokenPayload, "assignmentKeyHash"> {
+  assignmentKey: string;
+}
+
+export function createPricingPolicyToken(input: CreateTokenInput, secret: string): string {
+  assertSecret(secret);
+  const payload: PricingPolicyTokenPayload = {
+    assignmentKeyHash: assignmentHash(input.assignmentKey, secret),
+    issuedAtMs: input.issuedAtMs,
+    expiresAtMs: input.expiresAtMs,
+    offerPolicyVersion: input.offerPolicyVersion,
+    promotionEngineVersion: input.promotionEngineVersion,
+  };
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `${TOKEN_PREFIX}.${encoded}.${sign(encoded, secret)}`;
+}
+
+export function verifyPricingPolicyToken(
+  token: string,
+  secret: string,
+  nowMs = Date.now(),
+): PricingPolicyTokenPayload | null {
+  if (secret.trim().length < 32) return null;
+  const [prefix, encoded, signature, extra] = token.split(".");
+  if (prefix !== TOKEN_PREFIX || !encoded || !signature || extra) return null;
+  if (!safeEqual(signature, sign(encoded, secret))) return null;
+  try {
+    const value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")) as Record<string, unknown>;
+    const pairIsValid =
+      (value.offerPolicyVersion === OFFER_POLICY_V1 && value.promotionEngineVersion === PROMOTION_ENGINE_V1) ||
+      (value.offerPolicyVersion === OFFER_POLICY_V2 && value.promotionEngineVersion === PROMOTION_ENGINE_V2);
+    if (
+      !pairIsValid || typeof value.assignmentKeyHash !== "string" ||
+      typeof value.issuedAtMs !== "number" || typeof value.expiresAtMs !== "number" ||
+      value.issuedAtMs > nowMs || value.expiresAtMs < nowMs
+    ) return null;
+    return value as unknown as PricingPolicyTokenPayload;
+  } catch {
+    return null;
+  }
+}
+
+export function resolvePricingPolicy(input: {
+  assignmentKey?: string;
+  capability?: string;
+  token?: string;
+  secret: string;
+  v2Enabled: boolean;
+  rolloutBps: number;
+  nowMs?: number;
+  ttlMs?: number;
+}) {
+  const nowMs = input.nowMs ?? Date.now();
+  const existing = input.token ? verifyPricingPolicyToken(input.token, input.secret, nowMs) : null;
+  const boundExisting = existing && input.assignmentKey &&
+    existing.assignmentKeyHash === assignmentHash(input.assignmentKey, input.secret)
+      ? existing : null;
+  if (boundExisting) return { ...boundExisting, pricingPolicyToken: input.token };
+
+  const eligible = input.v2Enabled && input.capability === OFFER_POLICY_V2_CAPABILITY &&
+    Boolean(input.assignmentKey) && input.secret.trim().length >= 32;
+  const rolloutBps = Math.max(0, Math.min(10_000, Math.trunc(input.rolloutBps)));
+  const v2 = eligible && cohort(input.assignmentKey!, input.secret) < rolloutBps;
+  const offerPolicyVersion = v2 ? OFFER_POLICY_V2 : OFFER_POLICY_V1;
+  const promotionEngineVersion = v2 ? PROMOTION_ENGINE_V2 : PROMOTION_ENGINE_V1;
+  if (!eligible) return { offerPolicyVersion, promotionEngineVersion };
+
+  return {
+    offerPolicyVersion,
+    promotionEngineVersion,
+    pricingPolicyToken: createPricingPolicyToken({
+      assignmentKey: input.assignmentKey!, issuedAtMs: nowMs,
+      expiresAtMs: nowMs + (input.ttlMs ?? DEFAULT_TTL_MS),
+      offerPolicyVersion, promotionEngineVersion,
+    }, input.secret),
+  };
+}
+
+function assignmentHash(value: string, secret: string): string {
+  return createHmac("sha256", secret).update(`pricing-policy-identity:${value}`).digest("hex");
+}
+function cohort(value: string, secret: string): number {
+  return Number.parseInt(createHmac("sha256", secret).update(`pricing-policy-cohort:${value}`).digest("hex").slice(0, 8), 16) % 10_000;
+}
+function sign(value: string, secret: string): string {
+  return createHmac("sha256", secret).update(`${TOKEN_PREFIX}.${value}`).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.trim().length < 32) throw new Error("pricing_policy_token_secret_too_short");
+}

package/src/pricing/quoteAcquisitionTerms.ts

@@ -0,0 +1,10 @@
+import type { AcquisitionTermsExpectation, ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+export function acquisitionExpectationChanged(
+  expected: AcquisitionTermsExpectation | undefined,
+  actual: ResolvedAcquisitionTerms | undefined,
+): boolean {
+  return expected !== undefined && (
+    expected.revision !== actual?.revision ||
+    expected.delivery2DiscountBps !== actual?.delivery2DiscountBps
+  );
+}

package/src/pricing/quoteCodeRejectionDetails.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export const quoteCodeRejectionDetailSchema = z.discriminatedUnion("reason", [
+  z.object({
+    code: z.string().trim().min(1).max(80),
+    reason: z.literal("scope_not_applicable"),
+    allowedScopes: z.array(z.enum(["one_time", "subscription_initial"])).min(1).max(2),
+  }).strict(),
+  z.object({
+    code: z.string().trim().min(1).max(80),
+    reason: z.literal("minimum_not_met"),
+    minimumReferenceMinor: z.number().int().nonnegative(),
+  }).strict(),
+  z.object({
+    code: z.string().trim().min(1).max(80),
+    reason: z.literal("not_yet_active"),
+    validFrom: z.string().datetime({ offset: true }),
+  }).strict(),
+  z.object({
+    code: z.string().trim().min(1).max(80),
+    reason: z.literal("global_limit_reached"),
+  }).strict(),
+]);

package/src/pricing/quotePorts.ts

@@ -0,0 +1,58 @@
+import type { CreateQuoteRequest, CreateQuoteResponse } from "./contracts/quote.js";
+import type { PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+
+/**
+ * Server-resolved options for promo evaluation. Passed OUT-OF-BAND by the caller
+ * (orchestration -> provisioned.clientId; preview -> session/null) — NEVER sourced
+ * from the client request body — so `first_purchase` eligibility cannot be forged.
+ */
+export interface CreateQuoteOptions {
+  clientId?: string | null;
+  pricingPolicy?: PricingPolicySnapshot;
+}
+
+export interface CommerceQuotePort<Request = CreateQuoteRequest, Response = CreateQuoteResponse> {
+  createQuote(request: Request, options?: CreateQuoteOptions): Promise<Response>;
+  createServerAuthoritativeQuote?(request: Request, options?: CreateQuoteOptions): Promise<Response>;
+}
+
+export interface CommerceQuoteSnapshotVerifierPort<Response = CreateQuoteResponse> {
+  verifyQuoteSnapshot(snapshot: Response): Promise<Response | void>;
+}
+
+export type CommerceQuoteSnapshotErrorCode = "QUOTE_SNAPSHOT_MISMATCH";
+
+export class CommerceQuoteSnapshotError extends Error {
+  readonly code: CommerceQuoteSnapshotErrorCode;
+  readonly details: Record<string, unknown>;
+
+  constructor(
+    code: CommerceQuoteSnapshotErrorCode,
+    message: string,
+    details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "CommerceQuoteSnapshotError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export type CommerceQuoteErrorCode =
+  | "UNKNOWN_SKU"
+  | "PRICE_NOT_CONFIGURED"
+  | "UNSUPPORTED_TAX_PROFILE"
+  | "PRICING_INVARIANT_VIOLATION";
+
+export class CommerceQuoteError extends Error {
+  readonly code: CommerceQuoteErrorCode;
+  readonly details: Record<string, unknown>;
+
+  constructor(code: CommerceQuoteErrorCode, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "CommerceQuoteError";
+    this.code = code;
+    this.details = details;
+  }
+}
+

package/src/pricing/quotePrimitives.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+/** Currency acceptance belongs to the host's settlement profile. */
+export function createCommerceQuotePrimitives(commerceCurrencySchema: z.ZodType<string>) {
+  const commerceTaxCountrySchema = z.string().trim().regex(/^[A-Z]{2}$/);
+  const commerceTaxCategorySchema = z.string().trim().regex(/^[a-z][a-z0-9_]*$/);
+  const commerceTaxLegalBasisSchema = z.string().trim().min(1).max(200);
+  const commerceSkuSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[a-zA-Z0-9._:-]+$/);
+
+  const commerceMoneySchema = z.object({
+    amountMinor: z.number().int().nonnegative(),
+    currency: commerceCurrencySchema,
+  });
+
+  return { commerceCurrencySchema, commerceTaxCountrySchema, commerceTaxCategorySchema, commerceTaxLegalBasisSchema, commerceSkuSchema, commerceMoneySchema };
+}

package/src/pricing/quotePromotionEvidence.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+
+import type { QuotePromotionEvidence } from "./contracts/evidence.js";
+
+const uuidSchema = z.string().uuid();
+
+export const quoteDiscountSchema = z
+  .object({
+    promotionId: z.string().trim().min(1).max(120),
+    code: z.string().trim().min(1).max(80).nullable().optional(),
+    label: z.string().trim().min(1).max(200).optional(),
+    appliesTo: z.enum(["order_total", "line", "shipping"]),
+    amountOffMinor: z.number().int().positive(),
+    reasonCode: z.string().trim().min(1).max(120),
+    customerSemantic: z.enum([
+      "first_purchase_10", "first_subscription_50", "bundle_5",
+    ]).optional(),
+    promotionEngineVersion: z.literal("promotion-engine.v2").optional(),
+    promotionCodeId: z.string().uuid().optional(),
+    promotionCodeRevision: z.number().int().positive().optional(),
+    promotionDefinitionFingerprint: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    promotionCodeScopes: z.array(z.enum(["one_time", "subscription_initial"])).min(1).max(2).optional(),
+    promotionMinimumReferenceMinor: z.number().int().nonnegative().optional(),
+    promotionCodeValidTo: z.string().datetime({ offset: true }).nullable().optional(),
+    promotionBenefitKind: z.enum([
+      "target_percentage", "percentage", "fixed_amount", "free_shipping",
+    ]).optional(),
+    promotionBenefitValueBps: z.number().int().min(1).max(9_999).optional(),
+    promotionBenefitValueMinor: z.number().int().positive().optional(),
+    floorApplied: z.boolean().optional(),
+  })
+  .strict()
+  .superRefine((discount, context) => {
+    if (!hasValidV2PromotionEvidence(discount)) {
+      context.addIssue({ code: "custom", message: "v2 promotion discount evidence is incomplete" });
+    }
+  });
+
+export function hasValidV2PromotionEvidence(discount: QuotePromotionEvidence): boolean {
+  const carriesEvidence = discount.promotionEngineVersion !== undefined ||
+    discount.promotionCodeId !== undefined ||
+    discount.promotionCodeRevision !== undefined ||
+    discount.promotionDefinitionFingerprint !== undefined ||
+    discount.promotionCodeScopes !== undefined ||
+    discount.promotionMinimumReferenceMinor !== undefined ||
+    discount.promotionCodeValidTo !== undefined ||
+    discount.promotionBenefitKind !== undefined ||
+    discount.promotionBenefitValueBps !== undefined ||
+    discount.promotionBenefitValueMinor !== undefined || discount.floorApplied !== undefined;
+  return !carriesEvidence || (
+    discount.promotionEngineVersion === "promotion-engine.v2" &&
+    discount.reasonCode === "promotion_code_v2" &&
+    Boolean(discount.code) &&
+    uuidSchema.safeParse(discount.promotionCodeId).success &&
+    discount.promotionCodeRevision !== undefined &&
+    /^[0-9a-f]{64}$/.test(discount.promotionDefinitionFingerprint ?? "") &&
+    validScopes(discount.promotionCodeScopes) &&
+    (discount.promotionMinimumReferenceMinor ?? -1) >= 0 &&
+    discount.promotionCodeValidTo !== undefined &&
+    discount.promotionBenefitKind !== undefined &&
+    benefitValueMatchesKind(discount) &&
+    discount.floorApplied !== undefined &&
+    uuidSchema.safeParse(discount.promotionId).success
+  );
+}
+
+function validScopes(scopes: QuotePromotionEvidence["promotionCodeScopes"]): boolean {
+  return Boolean(scopes?.length && scopes.length <= 2 &&
+    new Set(scopes).size === scopes.length &&
+    scopes.every((scope) => scope === "one_time" || scope === "subscription_initial"));
+}
+
+function benefitValueMatchesKind(discount: QuotePromotionEvidence): boolean {
+  const percentage = discount.promotionBenefitKind === "target_percentage" ||
+    discount.promotionBenefitKind === "percentage";
+  return percentage === (discount.promotionBenefitValueBps !== undefined) &&
+    (discount.promotionBenefitKind === "fixed_amount") ===
+      (discount.promotionBenefitValueMinor !== undefined) &&
+    (discount.promotionBenefitKind !== "free_shipping" ||
+      (discount.promotionBenefitValueBps === undefined &&
+       discount.promotionBenefitValueMinor === undefined));
+}