@openlup/platform 0.17.0 → 0.18.0

package/src/pricing/acquisitionOfferPricingHandler.ts

@@ -0,0 +1,157 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import { COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, type AcquisitionOfferPricingResponse, type CommerceOfferPricingResponse } from "./contracts/offer.js";
+import type { AcquisitionCapability } from "./contracts/acquisitionTerms.js";
+import { acquisitionCapabilitySchema } from "./acquisitionTermsSchemas.js";
+import { pricingPolicyRequestSchema } from "./offerPolicySchemas.js";
+import type { PricingPolicyRequest, PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+import { mapPricingPolicyFailure } from "./commercePricingPolicyErrors.js";
+import { COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL, COMMERCE_OFFER_PRICING_CACHE_CONTROL,
+  OFFER_POLICY_CAPABILITY_HEADER, OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER } from "./commerceOfferPricingHandler.js";
+export const ACQUISITION_CAPABILITY_HEADER = "x-commerce-acquisition-capability";
+const ROUTER_QUERY_KEYS = new Set(["path", "__bffPath"]);
+
+export interface AcquisitionOfferPricingHandlerDeps {
+  responder: BffResponder;
+  commerceOfferPricingResponseSchema: z.ZodType<AcquisitionOfferPricingResponse | CommerceOfferPricingResponse>;
+  incumbentHandler(req: HttpRequest, res: HttpResponse): Promise<void>;
+  readOfferPricing(pricingPolicy?: PricingPolicySnapshot, acquisitionCapability?: AcquisitionCapability): Promise<AcquisitionOfferPricingResponse | CommerceOfferPricingResponse>;
+  requirePricingPolicy?: boolean;
+  resolvePricingPolicy?(request: {
+    visitorId: string;
+    pricingPolicy: PricingPolicyRequest;
+  }): PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+}
+
+export function createAcquisitionOfferPricingHandler({
+  responder, commerceOfferPricingResponseSchema, incumbentHandler,
+  readOfferPricing,
+  resolvePricingPolicy,
+  requirePricingPolicy = false,
+}: AcquisitionOfferPricingHandlerDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(
+    req: HttpRequest,
+    res: HttpResponse,
+  ): Promise<void> {
+    if (req.headers?.[ACQUISITION_CAPABILITY_HEADER] === undefined) return incumbentHandler(req, res);
+    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;
+    }
+
+    let failureReason = "offer_pricing_policy_unavailable";
+    try {
+      const acquisitionCapability = readAcquisitionCapability(req);
+      if (acquisitionCapability === null) {
+        sendBffError(res, "BAD_REQUEST", "Commerce acquisition capability is invalid");
+        return;
+      }
+      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;
+      if (acquisitionCapability && pricingPolicy?.offerPolicyVersion !== "commerce.offer-policy.v2") {
+        sendBffError(res, "BAD_REQUEST", "Commerce acquisition pricing requires offer policy v2");
+        return;
+      }
+      failureReason = "offer_pricing_projection_unavailable";
+      const parsed = commerceOfferPricingResponseSchema.safeParse(
+        await (acquisitionCapability ? readOfferPricing(pricingPolicy, acquisitionCapability) : readOfferPricing(pricingPolicy)),
+      );
+      if (!parsed.success || Boolean(acquisitionCapability) !==
+          (parsed.data.contractVersion === COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION)) {
+        sendBffError(
+          res,
+          "INVALID_RESPONSE",
+          "Commerce offer pricing returned invalid response",
+        );
+        return;
+      }
+      res.setHeader("Vary", [ACQUISITION_CAPABILITY_HEADER, OFFER_POLICY_CAPABILITY_HEADER,
+        OFFER_POLICY_TOKEN_HEADER, OFFER_POLICY_VISITOR_HEADER].join(", "));
+      sendBffSuccess(
+        res,
+        parsed.data,
+        { contractVersion: parsed.data.contractVersion },
+        {
+          cacheControl: policyRequest
+            ? COMMERCE_OFFER_PRICING_ASSIGNED_CACHE_CONTROL
+            : COMMERCE_OFFER_PRICING_CACHE_CONTROL,
+        },
+      );
+    } catch (error) {
+      const policyFailure = failureReason === "offer_pricing_policy_unavailable"
+        ? mapPricingPolicyFailure(error) : null;
+      sendBffError(
+        res,
+        "UPSTREAM_UNAVAILABLE",
+        "Commerce offer pricing is unavailable",
+        {
+          details: {
+            reason: failureReason,
+            ...(policyFailure ? { policyReason: policyFailure.details.policyReason } : {}),
+          },
+        },
+      );
+    }
+  };
+}
+
+export function readAcquisitionCapability(req: HttpRequest): AcquisitionCapability | undefined | null {
+  const raw = req.headers?.[ACQUISITION_CAPABILITY_HEADER];
+  if (raw === undefined) return undefined;
+  const parsed = acquisitionCapabilitySchema.safeParse(typeof raw === "string" ? raw.trim() : raw);
+  return parsed.success ? parsed.data : null;
+}
+
+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/acquisitionOfferPricingSchemas.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { acquisitionTermsSchema } from "./acquisitionTermsSchemas.js";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, type AcquisitionOfferPricingResponse, type CommerceOfferPricingResponse } from "./contracts/offer.js";
+export const ACQUISITION_PROJECTION_MAX_AGE_MS = 60_000;
+export const acquisitionProjectionFreshnessShape = {
+  acquisitionTerms: acquisitionTermsSchema,
+  observedAt: z.string().datetime({ offset: true }),
+  validUntil: z.string().datetime({ offset: true }),
+};
+export const acquisitionProjectionFreshnessSchema = z.object(acquisitionProjectionFreshnessShape).strict().refine((value) => {
+  const observed = Date.parse(value.observedAt);
+  const until = Date.parse(value.validUntil);
+  return until > observed && until <= observed + ACQUISITION_PROJECTION_MAX_AGE_MS
+    && (value.acquisitionTerms.effectiveFrom == null || Date.parse(value.acquisitionTerms.effectiveFrom) <= observed)
+    && (value.acquisitionTerms.effectiveTo == null || until <= Date.parse(value.acquisitionTerms.effectiveTo));
+}, "acquisition projection must be current and expire by its next boundary or 60 seconds");
+
+
+/** Validate against the host's existing v2 scope, product and settlement schemas. */
+export function createAcquisitionOfferPricingSchema<ScopeV2 extends string>(
+  v2Schema: z.ZodType<Extract<CommerceOfferPricingResponse<string, ScopeV2>, { contractVersion: typeof COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION }>>,
+): z.ZodType<AcquisitionOfferPricingResponse<ScopeV2>> {
+  return z.unknown().transform((value, ctx) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      ctx.addIssue({ code: "custom", message: "Invalid acquisition offer" }); return z.NEVER;
+    }
+    const { contractVersion, acquisitionTerms, observedAt, validUntil, ...base } = value as Record<string, unknown>;
+    const pricing = v2Schema.safeParse({ ...base, contractVersion: COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION });
+    const freshness = acquisitionProjectionFreshnessSchema.safeParse({ acquisitionTerms, observedAt, validUntil });
+    if (contractVersion !== COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION || !pricing.success || !freshness.success) {
+      ctx.addIssue({ code: "custom", message: "Invalid acquisition offer" }); return z.NEVER;
+    }
+    return { ...pricing.data, contractVersion: COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, ...freshness.data };
+  });
+}

package/src/pricing/acquisitionQuoteBinding.ts

@@ -0,0 +1,12 @@
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import { AcquisitionTermsError } from "./acquisitionTerms.js";
+/** Server-selected terms only. Absence contributes no property or token bytes. */
+export function acquisitionQuoteBinding(acquisitionTerms?: ResolvedAcquisitionTerms): { acquisitionTerms?: ResolvedAcquisitionTerms } {
+  return acquisitionTerms ? { acquisitionTerms } : {};
+}
+export function mapAcquisitionTermsFailure(error: unknown) {
+  if (!(error instanceof AcquisitionTermsError)) return null;
+  const refreshRequired = error.reason === "acquisition_terms_capability_required" || error.reason === "acquisition_terms_v2_required";
+  return { code: refreshRequired ? "CONFLICT" as const : "UPSTREAM_UNAVAILABLE" as const,
+    details: { reason: error.reason, refreshRequired } };
+}

package/src/pricing/acquisitionReadiness.ts

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { ACQUISITION_TERMS_CAPABILITY, type AcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import { acquisitionTermsSchema } from "./acquisitionTermsSchemas.js";
+import type { AcquisitionFinancialPolicy } from "./acquisitionFinancialPolicy.js";
+import { AcquisitionTermsError } from "./acquisitionTerms.js";
+import { OFFER_POLICY_V2_READINESS_CONTRACT } from "./offerPolicyReadiness.js";
+export const ACQUISITION_READINESS_CONTRACT = "commerce-acquisition-readiness.v1";
+
+export interface AcquisitionReadinessEvidence extends Omit<AcquisitionTerms, "schemaVersion"> {
+  contractVersion: typeof ACQUISITION_READINESS_CONTRACT;
+  kind: "legacy_pair" | "v2_standalone";
+  legacyPairCount: number;
+  standaloneCount: number;
+  nextBoundaryAt: string | null;
+}
+
+export interface AcquisitionOfferPolicyReadiness {
+  contractVersion: typeof OFFER_POLICY_V2_READINESS_CONTRACT;
+  ready: boolean;
+  checkedAt: string;
+  reasons: string[];
+  evidence?: { acquisition: AcquisitionReadinessEvidence | null };
+}
+
+import type { OfferPolicyReadinessPort } from "./offerPolicyReadiness.js";
+
+interface CacheEntry {
+  expiresAtMs: number;
+  readiness: AcquisitionOfferPolicyReadiness;
+}
+
+export interface AcquisitionReadinessCache {
+  read(port: OfferPolicyReadinessPort): Promise<AcquisitionOfferPolicyReadiness>;
+  clear(): void;
+}
+
+export function createAcquisitionReadinessCache<Row>(input: {
+  policy: AcquisitionFinancialPolicy<Row>;
+  now?: () => number;
+  positiveTtlMs?: number;
+  negativeTtlMs?: number;
+}): AcquisitionReadinessCache {
+  if (!input?.policy) throw new AcquisitionTermsError("acquisition_terms_policy_unconfigured");
+  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<AcquisitionOfferPolicyReadiness> | 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(async (readiness) => {
+          // An RPC started before the boundary can finish after it. Re-read once;
+          // never lend the old green result a fresh positive cache window.
+          if (readiness.ready && boundaryMs(readiness) <= now()) readiness = await loadFailClosed(port);
+          if (readiness.ready && boundaryMs(readiness) <= now()) readiness = unavailable("readiness_acquisition_boundary_elapsed");
+          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: readiness.ready ? Math.min(startedAtMs + positiveTtlMs, boundaryMs(readiness))
+              : startedAtMs + negativeTtlMs,
+          };
+          return readiness;
+        })
+        .finally(() => {
+          inFlight = null;
+        });
+      return inFlight;
+    },
+    clear() {
+      cached = null;
+      inFlight = null;
+    },
+  };
+}
+
+async function loadFailClosed(port: OfferPolicyReadinessPort): Promise<AcquisitionOfferPolicyReadiness> {
+  try {
+    const parsed = parseReadiness(await port.readOfferPolicyV2Readiness());
+    return parsed ?? unavailable("readiness_contract_invalid");
+  } catch {
+    return unavailable("readiness_rpc_unavailable");
+  }
+}
+
+function parseReadiness(value: unknown): AcquisitionOfferPolicyReadiness | 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;
+  const evidence = record.evidence;
+  let acquisition: AcquisitionReadinessEvidence | null | undefined;
+  if (evidence && typeof evidence === "object" && !Array.isArray(evidence) && "acquisition" in evidence) {
+    const raw = (evidence as Record<string, unknown>).acquisition;
+    acquisition = raw === null && !record.ready ? null : parseAcquisitionEvidence(raw);
+    if (acquisition === undefined) return null;
+    if (record.ready && acquisition && (Date.parse(acquisition.effectiveFrom) > Date.parse(record.checkedAt)
+      || acquisition.effectiveTo !== null && Date.parse(acquisition.effectiveTo) <= Date.parse(record.checkedAt)
+      || acquisition.nextBoundaryAt !== null && Date.parse(acquisition.nextBoundaryAt) <= Date.parse(record.checkedAt))) return null;
+  }
+  return {
+    contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+    ready: record.ready,
+    checkedAt: record.checkedAt,
+    reasons: record.reasons,
+    ...(acquisition !== undefined ? { evidence: { acquisition } } : {}),
+  };
+}
+
+function parseAcquisitionEvidence(value: unknown): AcquisitionReadinessEvidence | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const { contractVersion, kind, legacyPairCount, standaloneCount, nextBoundaryAt, ...terms } = value as Record<string, unknown>;
+  const parsed = acquisitionTermsSchema.safeParse({ ...terms, schemaVersion: ACQUISITION_TERMS_CAPABILITY });
+  if (!parsed.success || contractVersion !== ACQUISITION_READINESS_CONTRACT
+    || !(kind === "legacy_pair" && legacyPairCount === 1 && standaloneCount === 0
+      || kind === "v2_standalone" && legacyPairCount === 0 && standaloneCount === 1)
+    || !(nextBoundaryAt === null || z.string().datetime({ offset: true }).safeParse(nextBoundaryAt).success)
+    || parsed.data.effectiveTo !== null && (nextBoundaryAt === null
+      || Date.parse(nextBoundaryAt as string) > Date.parse(parsed.data.effectiveTo))) return undefined;
+  const { schemaVersion: _schema, ...publicTerms } = parsed.data;
+  return { ...publicTerms, contractVersion, kind, legacyPairCount, standaloneCount, nextBoundaryAt } as AcquisitionReadinessEvidence;
+}
+
+function boundaryMs(readiness: AcquisitionOfferPolicyReadiness): number {
+  const boundary = readiness.evidence?.acquisition?.nextBoundaryAt;
+  return boundary ? Date.parse(boundary) : Infinity;
+}
+
+function unavailable(reason: string): AcquisitionOfferPolicyReadiness {
+  return {
+    contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+    ready: false,
+    checkedAt: new Date(0).toISOString(),
+    reasons: [reason],
+  };
+}

package/src/pricing/acquisitionTerms.ts

@@ -0,0 +1,125 @@
+import { ACQUISITION_TERMS_CAPABILITY, type AcquisitionTermsMetadata, type ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { AcquisitionFinancialPolicy } from "./acquisitionFinancialPolicy.js";
+import { acquisitionTermsMetadataSchema, resolvedAcquisitionTermsSchema } from "./acquisitionTermsSchemas.js";
+export type AcquisitionTermsRefusal = "acquisition_terms_policy_unconfigured" | "acquisition_terms_invalid" | "acquisition_terms_ambiguous"
+  | "acquisition_terms_not_effective" | "acquisition_terms_capability_required" | "acquisition_terms_v2_required";
+export class AcquisitionTermsError extends Error {
+  constructor(readonly reason: AcquisitionTermsRefusal) { super(reason); this.name = "AcquisitionTermsError"; }
+}
+export interface AcquisitionTermsSelection {
+  kind: "legacy_pair" | "v2_standalone" | "legacy_unconfigured";
+  terms: ResolvedAcquisitionTerms;
+  sourcePromotionId: string;
+  legacyPromotionId?: string;
+  nextBoundaryAt: string | null;
+}
+
+function requirePolicy<Row>(policy: AcquisitionFinancialPolicy<Row>): void {
+  if (!policy) throw new AcquisitionTermsError("acquisition_terms_policy_unconfigured");
+}
+function effective<Row>(row: Row, at: number, policy: AcquisitionFinancialPolicy<Row>): boolean {
+  const facts = policy.facts(row);
+  return Date.parse(facts.validFrom) <= at && (facts.validTo === null || Date.parse(facts.validTo) > at);
+}
+function metadata<Row>(row: Row, policy: AcquisitionFinancialPolicy<Row>): AcquisitionTermsMetadata {
+  const parsed = acquisitionTermsMetadataSchema.safeParse(policy.facts(row).metadata);
+  if (!parsed.success) throw new AcquisitionTermsError("acquisition_terms_invalid");
+  policy.validateMetadata(row, parsed.data);
+  return parsed.data;
+}
+function resolved<Row>(row: Row, terms: AcquisitionTermsMetadata, policy: AcquisitionFinancialPolicy<Row>,
+  purpose: "resolved_target" | "filter_validation" = "resolved_target"): ResolvedAcquisitionTerms {
+  const facts = policy.facts(row);
+  const parsed = resolvedAcquisitionTermsSchema.safeParse({ ...terms,
+    initialDiscountBps: policy.initialDiscountBps(row, purpose), effectiveFrom: facts.validFrom,
+    effectiveTo: facts.validTo, sourcePromotionId: facts.id });
+  if (!parsed.success) throw new AcquisitionTermsError("acquisition_terms_invalid");
+  return { ...parsed.data, effectiveFrom: new Date(parsed.data.effectiveFrom).toISOString(),
+    effectiveTo: parsed.data.effectiveTo === null ? null : new Date(parsed.data.effectiveTo).toISOString() };
+}
+/** Selection never falls back from a configured but malformed or incomplete schedule. */
+export function selectAcquisitionTerms<Row>(
+  rows: readonly Row[], atTime: string, regionCode: string, policy: AcquisitionFinancialPolicy<Row>,
+): AcquisitionTermsSelection | null {
+  requirePolicy(policy);
+  const at = Date.parse(atTime);
+  if (!Number.isFinite(at)) throw new AcquisitionTermsError("acquisition_terms_invalid");
+  const scoped = rows.filter((row) => policy.facts(row).active && policy.facts(row).regionCodes.includes(regionCode));
+  const tagged = scoped.filter((row) => policy.facts(row).metadataPresent);
+  if (tagged.length === 0) {
+    const legacyRows = scoped.filter((row) => policy.classify(row).unconfiguredLegacyEligible);
+    const knownPairs = legacyRows.flatMap((legacy) => scoped.filter((mirror) => policy.classify(mirror).target
+      && policy.pairMatches(legacy, mirror)).map((mirror) => ({ legacy, mirror })));
+    const pairs = knownPairs.filter(({ mirror }) => effective(mirror, at, policy));
+    if (pairs.length > 1) throw new AcquisitionTermsError("acquisition_terms_ambiguous");
+    if (pairs.length === 0) {
+      if (knownPairs.length) throw new AcquisitionTermsError("acquisition_terms_not_effective");
+      return null;
+    }
+    const { legacy, mirror } = pairs[0]!;
+    const terms = resolved(mirror, policy.unconfiguredTerms(legacy, mirror), policy);
+    return { kind: "legacy_unconfigured", terms, sourcePromotionId: policy.facts(mirror).id,
+      legacyPromotionId: policy.facts(legacy).id, nextBoundaryAt: terms.effectiveTo };
+  }
+  const grouped = new Map<string, Row[]>();
+  for (const row of tagged) {
+    const parsed = metadata(row, policy);
+    const group = grouped.get(parsed.revision) ?? [];
+    group.push(row); grouped.set(parsed.revision, group);
+  }
+  const selections: AcquisitionTermsSelection[] = [];
+  for (const group of grouped.values()) {
+    const mirrors = group.filter((row) => policy.classify(row).target);
+    const legacy = group.filter((row) => policy.classify(row).baselineLegacy);
+    if (mirrors.length !== 1 || legacy.length > 1 || group.length !== mirrors.length + legacy.length) {
+      throw new AcquisitionTermsError("acquisition_terms_ambiguous");
+    }
+    const mirror = mirrors[0]!;
+    if (legacy.length === 1 ? !policy.pairMatches(legacy[0]!, mirror) : policy.facts(mirror).mirrorOf != null) {
+      throw new AcquisitionTermsError("acquisition_terms_invalid");
+    }
+    const terms = resolved(mirror, metadata(mirror, policy), policy);
+    selections.push({ kind: legacy.length ? "legacy_pair" : "v2_standalone", terms,
+      sourcePromotionId: policy.facts(mirror).id, ...(legacy.length ? { legacyPromotionId: policy.facts(legacy[0]!).id } : {}), nextBoundaryAt: null });
+  }
+  selections.sort((a, b) => Date.parse(a.terms.effectiveFrom) - Date.parse(b.terms.effectiveFrom));
+  for (let i = 1; i < selections.length; i++) {
+    const previousEnd = selections[i - 1]!.terms.effectiveTo;
+    const start = Date.parse(selections[i]!.terms.effectiveFrom);
+    if (previousEnd === null || Date.parse(previousEnd) > start) throw new AcquisitionTermsError("acquisition_terms_ambiguous");
+    if (Date.parse(previousEnd) < start) throw new AcquisitionTermsError("acquisition_terms_not_effective");
+  }
+  const current = selections.filter(({ terms }) => Date.parse(terms.effectiveFrom) <= at
+    && (terms.effectiveTo === null || Date.parse(terms.effectiveTo) > at));
+  if (current.length !== 1) throw new AcquisitionTermsError("acquisition_terms_not_effective");
+  if (scoped.some((row) => !policy.facts(row).metadataPresent && policy.classify(row).canonicalRow && effective(row, at, policy))) {
+    throw new AcquisitionTermsError("acquisition_terms_invalid");
+  }
+  const boundaries = selections.flatMap(({ terms }) => [terms.effectiveFrom, terms.effectiveTo])
+    .filter((instant): instant is string => instant !== null && Date.parse(instant) > at).sort();
+  return { ...current[0]!, nextBoundaryAt: boundaries[0] ?? null };
+}
+
+/** Ordinary coupon validity and inactive rows remain owned by their evaluator. */
+export function filterAcquisitionPromotions<Row>(rows: readonly Row[], atTime: string, regionCode: string,
+  policy: AcquisitionFinancialPolicy<Row>): Row[] {
+  requirePolicy(policy);
+  const at = Date.parse(atTime);
+  if (!Number.isFinite(at)) throw new AcquisitionTermsError("acquisition_terms_invalid");
+  return rows.filter((row) => {
+    if (!policy.facts(row).regionCodes.includes(regionCode) || !policy.classify(row).canonicalRow) return true;
+    if (policy.facts(row).metadataPresent) {
+      const parsed = metadata(row, policy);
+      resolved(row, parsed, policy, "filter_validation");
+    }
+    return effective(row, at, policy);
+  });
+}
+
+export function assertAcquisitionTermsCapability(
+  selection: AcquisitionTermsSelection | null, capability: unknown, promotionEngineVersion: unknown,
+): void {
+  if (!selection || selection.kind !== "v2_standalone") return;
+  if (capability !== ACQUISITION_TERMS_CAPABILITY) throw new AcquisitionTermsError("acquisition_terms_capability_required");
+  if (promotionEngineVersion !== "promotion-engine.v2") throw new AcquisitionTermsError("acquisition_terms_v2_required");
+}

package/src/pricing/acquisitionTermsSchemas.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { ACQUISITION_TERMS_CAPABILITY, type AcquisitionTerms, type ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+export const acquisitionCapabilitySchema = z.literal(ACQUISITION_TERMS_CAPABILITY);
+const revisionSchema = z.string().min(1).max(80).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const bpsSchema = z.number().int().min(0).max(10_000);
+const instantSchema = z.string().datetime({ offset: true });
+
+/** Only these extra terms are stored; promotion benefit and validity remain authoritative. */
+export const acquisitionTermsMetadataSchema = z.object({
+  schemaVersion: acquisitionCapabilitySchema,
+  revision: revisionSchema,
+  delivery2DiscountBps: bpsSchema,
+}).strict();
+
+const termsShape = {
+  ...acquisitionTermsMetadataSchema.shape,
+  initialDiscountBps: bpsSchema,
+  effectiveFrom: instantSchema,
+  effectiveTo: instantSchema.nullable(),
+};
+const validWindow = (terms: { effectiveFrom?: string; effectiveTo?: string | null }) =>
+  typeof terms.effectiveFrom === "string" && (terms.effectiveTo === null
+    || typeof terms.effectiveTo === "string" && Date.parse(terms.effectiveTo) > Date.parse(terms.effectiveFrom));
+
+export const acquisitionTermsSchema = z.object(termsShape).strict()
+  .refine(validWindow, { message: "Acquisition terms require a nonempty effective interval" });
+export const resolvedAcquisitionTermsSchema = z.object({
+  ...termsShape,
+  sourcePromotionId: z.string().min(1).max(120),
+}).strict().refine(validWindow, { message: "Acquisition terms require a nonempty effective interval" });
+
+export const acquisitionTermsExpectationSchema = z.object({
+  revision: revisionSchema,
+  delivery2DiscountBps: bpsSchema,
+}).strict();
+
+export function projectAcquisitionTerms(terms: ResolvedAcquisitionTerms): AcquisitionTerms {
+  const { sourcePromotionId: _source, ...publicTerms } = resolvedAcquisitionTermsSchema.parse(terms);
+  return publicTerms;
+}
+
+
+/** Compose only at an opted-in host boundary; preserve its existing refinements. */
+export function createAcquisitionQuoteSchemas<Request extends z.ZodObject, Context extends z.ZodObject, Quote extends z.ZodObject>(input: {
+  request: Request; context: Context; quote: Quote;
+}) {
+  return {
+    request: input.request.safeExtend({ acquisitionCapability: acquisitionCapabilitySchema.optional() }),
+    context: input.context.safeExtend({ acquisitionCapability: acquisitionCapabilitySchema.optional(), atTime: instantSchema.optional() }),
+    quote: input.quote.safeExtend({ acquisitionTerms: resolvedAcquisitionTermsSchema.optional() }),
+  };
+}

package/src/pricing/catalogFactsProvenance.ts

@@ -0,0 +1,102 @@
+import { CATALOG_FACTS_POLICY_PROVENANCE_VERSION, CATALOG_FACTS_PROVENANCE_VERSION } from "./contracts/provenance.js";
+import type { CatalogFactsProvenance } from "./contracts/provenance.js";
+import {
+  catalogFactsProvenanceSchema,
+} from "./catalogFactsSchemas.js";
+import type { CreateQuoteResponse } from "./contracts/quote.js";
+import { CommerceQuoteError } from "./quotePorts.js";
+import type { CommerceQuoteCatalogItem } from "./commerceQuoteCatalogReadPort.js";
+
+type ResolvedPriceObservation = {
+  priceEntryId: string;
+  unitPriceMinor: number;
+};
+
+type StrictCatalogFactsItem = CommerceQuoteCatalogItem & {
+  documentRevision: { id: string; digest: string };
+};
+
+type PolicyDerivedSubscriptionFacts = {
+  policyRevisionId: string;
+  policyDigest: string;
+};
+
+export function createCatalogFactsProvenance(input: {
+  item: StrictCatalogFactsItem;
+  resolved: ResolvedPriceObservation;
+  base: ResolvedPriceObservation;
+  mode: "one_time" | "subscription";
+  atTime: string;
+  currency: string;
+  resolvedUnitAmountMinor: number;
+  resolvedLineAmountMinor: number;
+  baseUnitAmountMinor: number;
+  policy?: PolicyDerivedSubscriptionFacts;
+}): CatalogFactsProvenance {
+  if (input.policy) {
+    if (input.mode !== "subscription") {
+      throw new CommerceQuoteError("PRICING_INVARIANT_VIOLATION", "One-time quote facts cannot carry a subscription policy");
+    }
+    return catalogFactsProvenanceSchema.parse({
+      version: CATALOG_FACTS_POLICY_PROVENANCE_VERSION,
+      skuId: input.item.skuId,
+      documentRevisionId: input.item.documentRevision.id,
+      documentDigest: input.item.documentRevision.digest,
+      basePriceEntryId: input.base.priceEntryId,
+      policyRevisionId: input.policy.policyRevisionId,
+      policyDigest: input.policy.policyDigest,
+      mode: input.mode,
+      atTime: input.atTime,
+      currency: input.currency,
+      resolvedUnitAmountMinor: input.resolvedUnitAmountMinor,
+      resolvedLineAmountMinor: input.resolvedLineAmountMinor,
+      baseUnitAmountMinor: input.baseUnitAmountMinor,
+    });
+  }
+  return catalogFactsProvenanceSchema.parse({
+    version: CATALOG_FACTS_PROVENANCE_VERSION,
+    skuId: input.item.skuId,
+    documentRevisionId: input.item.documentRevision.id,
+    documentDigest: input.item.documentRevision.digest,
+    resolvedPriceEntryId: input.resolved.priceEntryId,
+    basePriceEntryId: input.base.priceEntryId,
+    mode: input.mode,
+    atTime: input.atTime,
+    currency: input.currency,
+    resolvedUnitAmountMinor: input.resolvedUnitAmountMinor,
+    resolvedLineAmountMinor: input.resolvedLineAmountMinor,
+    baseUnitAmountMinor: input.baseUnitAmountMinor,
+  });
+}
+
+export function catalogFactsForQuoteLine(
+  enabled: boolean, item: CommerceQuoteCatalogItem, resolved: ResolvedPriceObservation,
+  base: ResolvedPriceObservation, mode: "one_time" | "subscription",
+  atTime: string, currency: string, resolvedUnitAmountMinor: number,
+  resolvedLineAmountMinor: number, baseUnitAmountMinor: number,
+  policy?: PolicyDerivedSubscriptionFacts,
+): CatalogFactsProvenance | undefined {
+  if (!enabled) return undefined;
+  const { id, digest } = item.documentRevision;
+  if (id === null || digest === null) {
+    throw new CommerceQuoteError("PRICE_NOT_CONFIGURED", "Strict catalog facts are unavailable", {
+      sku: item.skuCode,
+      variantId: item.variantId,
+    });
+  }
+  return createCatalogFactsProvenance({
+    item: { ...item, documentRevision: { id, digest } },
+    resolved, base, mode, atTime, currency, resolvedUnitAmountMinor, resolvedLineAmountMinor, baseUnitAmountMinor, policy,
+  });
+}
+
+/** Public responses retain every money field but never server-only catalog identifiers. */
+export function projectPublicQuoteSnapshot<Snapshot extends CreateQuoteResponse>(snapshot: Snapshot): Snapshot {
+  return {
+    ...snapshot,
+    quote: {
+      ...snapshot.quote,
+      lines: snapshot.quote.lines.map(({ catalogFacts: _catalogFacts, ...line }) => line),
+    },
+  };
+}