@openlup/platform 0.17.0 → 0.19.0

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),
+    },
+  };
+}

package/src/pricing/catalogFactsSchemas.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+import { CATALOG_FACTS_PROVENANCE_VERSION, CATALOG_FACTS_POLICY_PROVENANCE_VERSION } from "./contracts/provenance.js";
+const catalogFactsFields = {
+  skuId: z.string().uuid(),
+  documentRevisionId: z.string().uuid(),
+  documentDigest: z.string().regex(/^[a-f0-9]{64}$/iu),
+  basePriceEntryId: z.string().trim().min(1).max(120),
+  atTime: z.string().datetime({ offset: true }),
+  currency: z.string().regex(/^[A-Z]{3}$/u),
+  resolvedUnitAmountMinor: z.number().int().min(0),
+  resolvedLineAmountMinor: z.number().int().min(0),
+  baseUnitAmountMinor: z.number().int().min(0),
+};
+
+/**
+ * Server-only evidence for a quote line resolved from the strict current
+ * catalog facts port. V1 records authored price-entry observations; v2
+ * records policy-derived subscription money without inventing such an entry.
+ */
+const catalogFactsV1ProvenanceSchema = z
+  .object({
+    version: z.literal(CATALOG_FACTS_PROVENANCE_VERSION),
+    resolvedPriceEntryId: z.string().trim().min(1).max(120),
+    mode: z.enum(["one_time", "subscription"]),
+    ...catalogFactsFields,
+  })
+  .strict();
+
+const catalogFactsV2ProvenanceSchema = z
+  .object({
+    version: z.literal(CATALOG_FACTS_POLICY_PROVENANCE_VERSION),
+    // A policy-derived subscription price has no authored subscription price
+    // entry. Its immutable evidence is the exact base anchor plus this policy.
+    policyRevisionId: z.string().uuid(),
+    policyDigest: z.string().regex(/^[a-f0-9]{64}$/iu),
+    mode: z.literal("subscription"),
+    ...catalogFactsFields,
+  })
+  .strict();
+
+/**
+ * Server-only evidence for a strict quote line. V1 remains readable for
+ * historical and explicitly pre-cutover legacy subscription observations; v2
+ * records the policy which derived a current subscription amount.
+ */
+export const catalogFactsProvenanceSchema = z.union([
+  catalogFactsV1ProvenanceSchema,
+  catalogFactsV2ProvenanceSchema,
+]);
+
+
+
+/** Reject server-only provenance at every HTTP response schema boundary. */
+export function rejectCatalogFactsFromPublicQuote(
+  response: { quote: { lines: readonly { catalogFacts?: unknown }[] } },
+  ctx: z.RefinementCtx,
+  pathPrefix: Array<string | number> = ["quote"],
+): void {
+  response.quote.lines.forEach((line, index) => {
+    if (line.catalogFacts !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "catalog facts are server-only",
+        path: [...pathPrefix, "lines", index, "catalogFacts"],
+      });
+    }
+  });
+}