@openlup/platform 0.17.0 → 0.19.0

package/dist/pricing/acquisitionOfferPricingHandler.js

@@ -0,0 +1,105 @@
+import { COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION } from "./contracts/offer.js";
+import { acquisitionCapabilitySchema } from "./acquisitionTermsSchemas.js";
+import { pricingPolicyRequestSchema } from "./offerPolicySchemas.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 function createAcquisitionOfferPricingHandler({ responder, commerceOfferPricingResponseSchema, incumbentHandler, readOfferPricing, resolvePricingPolicy, requirePricingPolicy = false, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        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) {
+    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) {
+    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, name) {
+    const value = req.headers?.[name];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/pricing/acquisitionOfferPricingSchemas.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, type AcquisitionOfferPricingResponse, type CommerceOfferPricingResponse } from "./contracts/offer.js";
+export declare const ACQUISITION_PROJECTION_MAX_AGE_MS = 60000;
+export declare const acquisitionProjectionFreshnessShape: {
+    acquisitionTerms: z.ZodObject<{
+        initialDiscountBps: z.ZodNumber;
+        effectiveFrom: z.ZodString;
+        effectiveTo: z.ZodNullable<z.ZodString>;
+        schemaVersion: z.ZodLiteral<"subscription-acquisition.v1">;
+        revision: z.ZodString;
+        delivery2DiscountBps: z.ZodNumber;
+    }, z.core.$strict>;
+    observedAt: z.ZodString;
+    validUntil: z.ZodString;
+};
+export declare const acquisitionProjectionFreshnessSchema: z.ZodObject<{
+    acquisitionTerms: z.ZodObject<{
+        initialDiscountBps: z.ZodNumber;
+        effectiveFrom: z.ZodString;
+        effectiveTo: z.ZodNullable<z.ZodString>;
+        schemaVersion: z.ZodLiteral<"subscription-acquisition.v1">;
+        revision: z.ZodString;
+        delivery2DiscountBps: z.ZodNumber;
+    }, z.core.$strict>;
+    observedAt: z.ZodString;
+    validUntil: z.ZodString;
+}, z.core.$strict>;
+/** Validate against the host's existing v2 scope, product and settlement schemas. */
+export declare function createAcquisitionOfferPricingSchema<ScopeV2 extends string>(v2Schema: z.ZodType<Extract<CommerceOfferPricingResponse<string, ScopeV2>, {
+    contractVersion: typeof COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION;
+}>>): z.ZodType<AcquisitionOfferPricingResponse<ScopeV2>>;

package/dist/pricing/acquisitionOfferPricingSchemas.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { acquisitionTermsSchema } from "./acquisitionTermsSchemas.js";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION } 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(v2Schema) {
+    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;
+        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/dist/pricing/acquisitionQuoteBinding.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+/** Server-selected terms only. Absence contributes no property or token bytes. */
+export declare function acquisitionQuoteBinding(acquisitionTerms?: ResolvedAcquisitionTerms): {
+    acquisitionTerms?: ResolvedAcquisitionTerms;
+};
+export declare function mapAcquisitionTermsFailure(error: unknown): {
+    code: "CONFLICT" | "UPSTREAM_UNAVAILABLE";
+    details: {
+        reason: import("./acquisitionTerms.js").AcquisitionTermsRefusal;
+        refreshRequired: boolean;
+    };
+} | null;

package/dist/pricing/acquisitionQuoteBinding.js

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

package/dist/pricing/acquisitionReadiness.d.ts

@@ -0,0 +1,31 @@
+import { type AcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { AcquisitionFinancialPolicy } from "./acquisitionFinancialPolicy.js";
+import { OFFER_POLICY_V2_READINESS_CONTRACT } from "./offerPolicyReadiness.js";
+export declare 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";
+export interface AcquisitionReadinessCache {
+    read(port: OfferPolicyReadinessPort): Promise<AcquisitionOfferPolicyReadiness>;
+    clear(): void;
+}
+export declare function createAcquisitionReadinessCache<Row>(input: {
+    policy: AcquisitionFinancialPolicy<Row>;
+    now?: () => number;
+    positiveTtlMs?: number;
+    negativeTtlMs?: number;
+}): AcquisitionReadinessCache;

package/dist/pricing/acquisitionReadiness.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { ACQUISITION_TERMS_CAPABILITY } from "./contracts/acquisitionTerms.js";
+import { acquisitionTermsSchema } from "./acquisitionTermsSchemas.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 function createAcquisitionReadinessCache(input) {
+    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 = null;
+    let inFlight = 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) {
+    try {
+        const parsed = parseReadiness(await port.readOfferPolicyV2Readiness());
+        return parsed ?? unavailable("readiness_contract_invalid");
+    }
+    catch {
+        return unavailable("readiness_rpc_unavailable");
+    }
+}
+function parseReadiness(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    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;
+    if (evidence && typeof evidence === "object" && !Array.isArray(evidence) && "acquisition" in evidence) {
+        const raw = evidence.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) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const { contractVersion, kind, legacyPairCount, standaloneCount, nextBoundaryAt, ...terms } = value;
+    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) > Date.parse(parsed.data.effectiveTo)))
+        return undefined;
+    const { schemaVersion: _schema, ...publicTerms } = parsed.data;
+    return { ...publicTerms, contractVersion, kind, legacyPairCount, standaloneCount, nextBoundaryAt };
+}
+function boundaryMs(readiness) {
+    const boundary = readiness.evidence?.acquisition?.nextBoundaryAt;
+    return boundary ? Date.parse(boundary) : Infinity;
+}
+function unavailable(reason) {
+    return {
+        contractVersion: OFFER_POLICY_V2_READINESS_CONTRACT,
+        ready: false,
+        checkedAt: new Date(0).toISOString(),
+        reasons: [reason],
+    };
+}

package/dist/pricing/acquisitionTerms.d.ts

@@ -0,0 +1,19 @@
+import { type ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { AcquisitionFinancialPolicy } from "./acquisitionFinancialPolicy.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 declare class AcquisitionTermsError extends Error {
+    readonly reason: AcquisitionTermsRefusal;
+    constructor(reason: AcquisitionTermsRefusal);
+}
+export interface AcquisitionTermsSelection {
+    kind: "legacy_pair" | "v2_standalone" | "legacy_unconfigured";
+    terms: ResolvedAcquisitionTerms;
+    sourcePromotionId: string;
+    legacyPromotionId?: string;
+    nextBoundaryAt: string | null;
+}
+/** Selection never falls back from a configured but malformed or incomplete schedule. */
+export declare function selectAcquisitionTerms<Row>(rows: readonly Row[], atTime: string, regionCode: string, policy: AcquisitionFinancialPolicy<Row>): AcquisitionTermsSelection | null;
+/** Ordinary coupon validity and inactive rows remain owned by their evaluator. */
+export declare function filterAcquisitionPromotions<Row>(rows: readonly Row[], atTime: string, regionCode: string, policy: AcquisitionFinancialPolicy<Row>): Row[];
+export declare function assertAcquisitionTermsCapability(selection: AcquisitionTermsSelection | null, capability: unknown, promotionEngineVersion: unknown): void;

package/dist/pricing/acquisitionTerms.js

@@ -0,0 +1,126 @@
+import { ACQUISITION_TERMS_CAPABILITY } from "./contracts/acquisitionTerms.js";
+import { acquisitionTermsMetadataSchema, resolvedAcquisitionTermsSchema } from "./acquisitionTermsSchemas.js";
+export class AcquisitionTermsError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = "AcquisitionTermsError";
+    }
+}
+function requirePolicy(policy) {
+    if (!policy)
+        throw new AcquisitionTermsError("acquisition_terms_policy_unconfigured");
+}
+function effective(row, at, policy) {
+    const facts = policy.facts(row);
+    return Date.parse(facts.validFrom) <= at && (facts.validTo === null || Date.parse(facts.validTo) > at);
+}
+function metadata(row, policy) {
+    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, terms, policy, purpose = "resolved_target") {
+    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(rows, atTime, regionCode, policy) {
+    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();
+    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 = [];
+    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 !== 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(rows, atTime, regionCode, policy) {
+    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, capability, promotionEngineVersion) {
+    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/dist/pricing/acquisitionTermsSchemas.d.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { type AcquisitionTerms, type ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+export declare const acquisitionCapabilitySchema: z.ZodLiteral<"subscription-acquisition.v1">;
+/** Only these extra terms are stored; promotion benefit and validity remain authoritative. */
+export declare const acquisitionTermsMetadataSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"subscription-acquisition.v1">;
+    revision: z.ZodString;
+    delivery2DiscountBps: z.ZodNumber;
+}, z.core.$strict>;
+export declare const acquisitionTermsSchema: z.ZodObject<{
+    initialDiscountBps: z.ZodNumber;
+    effectiveFrom: z.ZodString;
+    effectiveTo: z.ZodNullable<z.ZodString>;
+    schemaVersion: z.ZodLiteral<"subscription-acquisition.v1">;
+    revision: z.ZodString;
+    delivery2DiscountBps: z.ZodNumber;
+}, z.core.$strict>;
+export declare const resolvedAcquisitionTermsSchema: z.ZodObject<{
+    sourcePromotionId: z.ZodString;
+    initialDiscountBps: z.ZodNumber;
+    effectiveFrom: z.ZodString;
+    effectiveTo: z.ZodNullable<z.ZodString>;
+    schemaVersion: z.ZodLiteral<"subscription-acquisition.v1">;
+    revision: z.ZodString;
+    delivery2DiscountBps: z.ZodNumber;
+}, z.core.$strict>;
+export declare const acquisitionTermsExpectationSchema: z.ZodObject<{
+    revision: z.ZodString;
+    delivery2DiscountBps: z.ZodNumber;
+}, z.core.$strict>;
+export declare function projectAcquisitionTerms(terms: ResolvedAcquisitionTerms): AcquisitionTerms;
+/** Compose only at an opted-in host boundary; preserve its existing refinements. */
+export declare function createAcquisitionQuoteSchemas<Request extends z.ZodObject, Context extends z.ZodObject, Quote extends z.ZodObject>(input: {
+    request: Request;
+    context: Context;
+    quote: Quote;
+}): {
+    request: z.ZodObject<{
+        [x: string]: any;
+        acquisitionCapability: z.ZodOptional<z.ZodLiteral<"subscription-acquisition.v1">>;
+    }, z.core.$strip>;
+    context: z.ZodObject<{
+        [x: string]: any;
+        acquisitionCapability: z.ZodOptional<z.ZodLiteral<"subscription-acquisition.v1">>;
+        atTime: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    quote: z.ZodObject<{
+        [x: string]: any;
+        acquisitionTerms: z.ZodOptional<z.ZodObject<{
+            sourcePromotionId: z.ZodString;
+            initialDiscountBps: z.ZodNumber;
+            effectiveFrom: z.ZodString;
+            effectiveTo: z.ZodNullable<z.ZodString>;
+            schemaVersion: z.ZodLiteral<"subscription-acquisition.v1">;
+            revision: z.ZodString;
+            delivery2DiscountBps: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strip>;
+};

package/dist/pricing/acquisitionTermsSchemas.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { ACQUISITION_TERMS_CAPABILITY } 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) => 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) {
+    const { sourcePromotionId: _source, ...publicTerms } = resolvedAcquisitionTermsSchema.parse(terms);
+    return publicTerms;
+}
+/** Compose only at an opted-in host boundary; preserve its existing refinements. */
+export function createAcquisitionQuoteSchemas(input) {
+    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/dist/pricing/catalogFactsProvenance.d.ts

@@ -0,0 +1,33 @@
+import type { CatalogFactsProvenance } from "./contracts/provenance.js";
+import type { CreateQuoteResponse } from "./contracts/quote.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 declare 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;
+export declare 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;
+/** Public responses retain every money field but never server-only catalog identifiers. */
+export declare function projectPublicQuoteSnapshot<Snapshot extends CreateQuoteResponse>(snapshot: Snapshot): Snapshot;
+export {};