@openlup/platform 0.18.0 → 0.20.0

package/src/catalog/effectiveBundleCatalogStore.ts

@@ -0,0 +1,208 @@
+import type { PgQueryExecutor } from "../data/index.js";
+import { assertPrimaryUnitGtinAuthority, type CatalogSkuIdentifier } from "./contracts/foundation.js";
+import { BundleCatalogReadError, type BundleCatalogReadPort, type BundleComponentRow, type BundleSummary, type GetBundleInput } from "./bundleCatalogReadPort.js";
+import { uniqueBundlePrice, selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";
+import { COUNT_SQL } from "./bundleCatalogQueries.js";
+import { LIST_SQL, DETAIL_SQL, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL } from "./effectiveBundleCatalogQueries.js";
+
+interface BundleRow {
+  id: string;
+  code: string;
+  title: string;
+  status: string;
+  fulfillment_mode: string;
+  updated_at: string;
+  component_count: string | number;
+  has_active_target_price: boolean;
+  composition_constraint: Record<string, unknown> | null;
+  metadata: Record<string, unknown> | null;
+}
+
+interface ComponentRow {
+  bundle_id: string;
+  sku: string;
+  title: string | null;
+  product_slug: string;
+  variant_id: string;
+  quantity: number;
+  is_addon: boolean;
+  sort_order: number;
+  reference_unit_price_minor: number | null;
+  reference_price_count: number | string;
+  sku_status: string;
+  product_status: string;
+  net_weight_g: number;
+  sellable_standalone: boolean;
+  sellable_in_subscription: boolean;
+  document_ready: boolean;
+  identifiers: CatalogSkuIdentifier[];
+}
+
+interface PriceRow {
+  price_list_id: string;
+  mode: string;
+  target_price_minor: number;
+  currency: string;
+  amount_kind: string;
+  active: boolean;
+  valid_from: string;
+  valid_to: string | null;
+}
+
+interface ActiveBundleRow {
+  id: string;
+  code: string;
+  title: string;
+  fulfillment_mode: string;
+  mode: string;
+  target_price_minor: number;
+  price_list_id: string;
+  currency: string;
+  region_code: string;
+}
+
+
+/** Selected only by the explicit effective-authority option. */
+export function createEffectiveBundleCatalogStore(executor: PgQueryExecutor, incumbent: BundleCatalogReadPort): BundleCatalogReadPort {
+  async function rows<T>(sql: string, values: unknown[]): Promise<T[]> {
+    const result = await executor.query(sql, values).catch((error: unknown) => {
+      throw new BundleCatalogReadError(error instanceof Error ? error.message : String(error));
+    });
+    return (result.rows ?? []) as unknown as T[];
+  }
+  async function selectPriceList(bundleId: string, input: GetBundleInput): Promise<{ id: string; currency: string } | null> {
+    const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+    const own = input.currency ? [] : await rows<{ id: string; currency: string; region_code: string; mode: string }>(OWN_LIST_SQL, [bundleId, mode, atTime]);
+    const chosenPrice = uniqueBundlePrice(own, mode), chosen = chosenPrice ? [chosenPrice] : [];
+    const currency = input.currency ?? chosen[0]?.currency;
+    if (!currency) return null;
+    const candidates = await rows<{ id: string; currency: string }>(CURRENCY_LIST_SQL, [currency, input.regionCode ?? chosen[0]?.region_code ?? null, atTime]);
+    if (candidates.length > 1) throw new BundleCatalogReadError("bundle_price_list_ambiguous");
+    if (chosen[0] && candidates[0] && chosen[0].id !== candidates[0].id) throw new BundleCatalogReadError("bundle_price_list_changed");
+    return candidates[0] ?? null;
+  }
+  return {
+    ...incumbent,
+    async listBundles(input) {
+      const filter = [input.status, input.query ?? null];
+      const [page, counted] = await Promise.all([
+        rows<BundleRow>(LIST_SQL, [...filter, input.limit, input.offset]),
+        rows<{ total: string | number }>(COUNT_SQL, filter),
+      ]);
+      return { bundles: page.map(toSummary), total: Number(counted[0]?.total ?? page.length) };
+    },
+    async getBundle(input) {
+      const bundle = (await rows<BundleRow>(DETAIL_SQL, [input.code]))[0];
+      if (!bundle) return null;
+      const atTime = input.atTime ?? new Date().toISOString();
+      const list = await selectPriceList(bundle.id, { ...input, atTime });
+      const [componentRows, priceRows] = await Promise.all([
+        rows<ComponentRow>(COMPONENT_SQL, [bundle.id, list?.id ?? null, atTime, input.mode ?? "one_time"]).then(rows => rows.map(toComponent)),
+        rows<PriceRow>(PRICE_SQL, [bundle.id]),
+      ]);
+      return {
+        ...toSummary(bundle), compositionConstraint: toConstraint(bundle.composition_constraint), metadata: bundle.metadata ?? {},
+        components: componentRows, prices: priceRows.map(toPrice),
+        resolvedTargetPrice: selectEffectiveBundleTargetPrice(priceRows.map(row => ({ price: toPrice(row), priceListId: row.price_list_id })),
+          { priceListId: list?.id ?? null, currency: list?.currency ?? null, mode: input.mode ?? "one_time", atTime }),
+        resolvedCurrency: list?.currency ?? null, resolvedPriceListId: list?.id ?? null,
+      };
+    },
+    async listActiveBundleCompositions(input = {}) {
+      const atTime = input.atTime ?? new Date().toISOString(), mode = input.mode ?? "one_time";
+      const feed = await rows<ActiveBundleRow>(FEED_SQL, [input.currency ?? null, input.regionCode ?? null, atTime, mode]);
+      const selected = new Map<string, ActiveBundleRow>();
+      const listReads = new Map<string, Promise<{ id: string }[]>>();
+      for (const row of feed) {
+        const same = feed.filter(candidate => candidate.id === row.id);
+        const candidate = uniqueBundlePrice(same, mode)!;
+        const key = `${row.currency}:${row.region_code}`;
+        if (!listReads.has(key)) listReads.set(key, rows<{ id: string }>(CURRENCY_LIST_SQL, [row.currency, row.region_code ?? null, atTime]));
+        const lists = await listReads.get(key)!;
+        if (lists.length > 1) throw new BundleCatalogReadError("bundle_price_list_ambiguous");
+        if (lists[0]?.id !== row.price_list_id) throw new BundleCatalogReadError("bundle_price_list_changed");
+        selected.set(row.id, candidate);
+      }
+      if (!selected.size) return [];
+      const chosen = [...selected.values()];
+      const source = await rows<ComponentRow>(FEED_COMPONENT_SQL, [chosen.map(row => row.id), chosen.map(row => row.price_list_id), atTime, mode]);
+      const byBundle = groupComponents(source);
+      const sellable = chosen.filter(row => {
+        const components = source.filter(component => component.bundle_id === row.id);
+        return components.length > 0 && components.every(component => componentReady(component, mode));
+      });
+      return sellable.map(row => ({ code: row.code, title: row.title, fulfillmentMode: row.fulfillment_mode,
+        currency: row.currency, targetPriceMinor: row.target_price_minor, mode: row.mode, components: byBundle.get(row.id) ?? [] }));
+    },
+  };
+}
+
+function groupComponents(rows: readonly ComponentRow[]): Map<string, BundleComponentRow[]> {
+  const grouped = new Map<string, BundleComponentRow[]>();
+  for (const row of rows) {
+    const bucket = grouped.get(row.bundle_id) ?? [];
+    bucket.push(toComponent(row));
+    grouped.set(row.bundle_id, bucket);
+  }
+  return grouped;
+}
+
+function toComponent(row: ComponentRow): BundleComponentRow {
+  if (Number(row.reference_price_count) > 1) throw new BundleCatalogReadError("bundle_price_ambiguous");
+  return {
+    sku: row.sku,
+    title: row.title ?? null,
+    productSlug: row.product_slug,
+    variantId: row.variant_id,
+    quantity: Number(row.quantity),
+    isAddon: row.is_addon === true,
+    sortOrder: Number(row.sort_order),
+    referenceUnitPriceMinor:
+      row.reference_unit_price_minor === null || row.reference_unit_price_minor === undefined
+        ? null
+        : Number(row.reference_unit_price_minor),
+  };
+}
+
+function toSummary(row: BundleRow): BundleSummary {
+  return {
+    code: row.code,
+    title: row.title,
+    status: row.status,
+    fulfillmentMode: row.fulfillment_mode,
+    componentCount: Number(row.component_count ?? 0),
+    hasActiveTargetPrice: row.has_active_target_price === true,
+    updatedAt: row.updated_at,
+  };
+}
+
+function toPrice(row: PriceRow) {
+  return {
+    mode: row.mode,
+    targetPriceMinor: Number(row.target_price_minor),
+    currency: row.currency,
+    amountKind: row.amount_kind,
+    active: row.active === true,
+    validFrom: row.valid_from,
+    validTo: row.valid_to ?? null,
+  };
+}
+
+/** An empty envelope is stored as `{}`; that is "unconstrained", not a constraint. */
+function toConstraint(value: Record<string, unknown> | null) {
+  if (!value || typeof value.kind !== "string" || value.kind.trim() === "") return null;
+  return {
+    kind: value.kind,
+    version: typeof value.version === "number" ? value.version : 0,
+    data: (value.data ?? {}) as Record<string, unknown>,
+  };
+}
+
+function componentReady(row: ComponentRow, mode: string): boolean {
+  try { assertPrimaryUnitGtinAuthority(row.identifiers); } catch { return false; }
+  return row.sku_status === "active" && row.product_status === "active" && row.document_ready === true
+    && Number.isSafeInteger(row.net_weight_g) && row.net_weight_g > 0
+    && (mode === "subscription" ? row.sellable_in_subscription : row.sellable_standalone)
+    && row.reference_unit_price_minor !== null && Number.isSafeInteger(Number(row.reference_unit_price_minor))
+    && Number(row.reference_unit_price_minor) > 0;
+}

package/src/catalog/index.ts

@@ -41,3 +41,4 @@ export { BUNDLE_MIGRATIONS, CATALOG_MIGRATIONS } from "./sql.js";
 export { SUMMARY_COLUMNS, LIST_FILTER, LIST_SQL, COUNT_SQL, DETAIL_SQL, REFERENCE_PRICE, COMPONENT_SQL, FEED_COMPONENT_SQL, PRICE_SQL, OWN_LIST_SQL, CURRENCY_LIST_SQL, FEED_SQL, HISTORY_SQL, HISTORY_COUNT_SQL } from "./bundleCatalogQueries.js";
 export { createPostgresCatalogSkuEnvelopeReadPort } from "./catalogSkuEnvelope.js";
 export { createPostgresCatalogDraftStore } from "./catalogDraftStore.js";
+export { selectEffectiveBundleTargetPrice } from "./bundlePriceSelection.js";

package/src/composition/index.ts

@@ -16,3 +16,5 @@ export {
   type ServeNodeResult,
 } from "./nodeHost.js";
 export { createCatalogContribution, type CatalogContributionInput } from "./catalogContribution.js";
+export { createInventoryContribution } from "./inventoryContribution.js";
+export { createShippingContribution } from "./shippingContribution.js";

package/src/composition/inventoryContribution.ts

@@ -0,0 +1,24 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Structural selected callables keep inventory and catalog declarations independent. */
+export function createInventoryContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  inventory: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+  routes: Contribution["routes"];
+}) {
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "inventory", kind: "capability", provides: ["./inventory"], dependsOn: [] },
+      emits: [], handles: [], schedules: [], env: [], requiredPorts: Object.keys(input.inventory),
+      routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+    },
+    handlers: [], schedules: [], routes: input.routes,
+  };
+  return {
+    contributions: [contribution],
+    ports: Object.fromEntries(Object.entries(input.inventory).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/inventory:${name}`, fn])),
+    routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/inventory:${route.id}`, route.handle])),
+  };
+}

package/src/composition/shippingContribution.ts

@@ -0,0 +1,24 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Structural selected callables keep shipping declarations independent. */
+export function createShippingContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  shipping: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+  routes: Contribution["routes"];
+}) {
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "shipping", kind: "capability", provides: ["./shipping"], dependsOn: [] },
+      emits: [], handles: [], schedules: [], env: [], requiredPorts: Object.keys(input.shipping),
+      routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+    },
+    handlers: [], schedules: [], routes: input.routes,
+  };
+  return {
+    contributions: [contribution],
+    ports: Object.fromEntries(Object.entries(input.shipping).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/shipping:${name}`, fn])),
+    routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/shipping:${route.id}`, route.handle])),
+  };
+}

package/src/inventory/bindings.ts

@@ -0,0 +1,61 @@
+import type { z } from "zod";
+import { createPostgresAdminInventoryPort } from "./adminInventory.js";
+import type { InventoryMutationPort, InventoryReadPort } from "./ports.js";
+import type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
+import { createInventorySubscriptionForecastResponseSchema } from "./schemas.js";
+
+export interface InventoryBindingDependencies {
+  dataKind: string;
+  provider: { stockMasterProvider: string; providerSchema: z.ZodType<string> };
+  executor?: { query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> } | null;
+  createManagedStore?: (provider: InventoryBindingDependencies["provider"]) => {
+    readPort: InventoryReadPort; mutationPort: InventoryMutationPort;
+  } | null;
+  newPurchaseStockReadPort?: NewPurchaseStockReadPort | null;
+  now?: () => string;
+}
+
+export interface InventoryBindings {
+  readPort: InventoryReadPort | null;
+  mutationPort: InventoryMutationPort | null;
+  newPurchaseStockReadPort: NewPurchaseStockReadPort | null;
+  readiness: { ready: boolean; reason: string | null };
+  unsupported: { newPurchaseStockRead: string | null };
+}
+
+/** Select one store only. Factories declare bindings, never discover or activate a host. */
+export function createInventoryBindings(deps: InventoryBindingDependencies): InventoryBindings {
+  const refused = (reason: string): InventoryBindings => ({
+    readPort: null, mutationPort: null, newPurchaseStockReadPort: null,
+    readiness: { ready: false, reason }, unsupported: { newPurchaseStockRead: reason },
+  });
+  if (!deps.provider?.providerSchema?.safeParse(deps.provider.stockMasterProvider).success) return refused("inventory_provider_mismatch");
+  let readPort: InventoryReadPort, mutationPort: InventoryMutationPort;
+  if (deps.dataKind === "postgres") {
+    if (!deps.executor || typeof deps.executor.query !== "function") return refused("inventory_executor_required");
+    readPort = mutationPort = createPostgresAdminInventoryPort(deps.executor, deps.provider, deps.now);
+  } else if (deps.dataKind === "supabase") {
+    const store = deps.createManagedStore?.(deps.provider);
+    if (!store) return refused("inventory_managed_store_required");
+    ({ readPort, mutationPort } = store);
+  } else return refused("inventory_store_incompatible");
+  if (![readPort?.listStock, readPort?.listReservations, readPort?.checkAtp, readPort?.forecastSubscriptions, mutationPort?.adjustStock].every(fn => typeof fn === "function")) return refused("inventory_store_incompatible");
+  const responseSchema = createInventorySubscriptionForecastResponseSchema(deps.provider.providerSchema);
+  const native = deps.dataKind === "postgres";
+  const stockRead = native ? null : deps.newPurchaseStockReadPort;
+  const newPurchaseStockReadPort = typeof stockRead?.read === "function" ? stockRead : null;
+  return {
+    readPort: {
+      listStock: request => readPort.listStock(request),
+      listReservations: request => readPort.listReservations(request),
+      checkAtp: request => readPort.checkAtp(request),
+      forecastSubscriptions: async request => responseSchema.parse(await readPort.forecastSubscriptions(request)),
+    },
+    mutationPort, newPurchaseStockReadPort,
+    readiness: { ready: true, reason: null },
+    unsupported: {
+      newPurchaseStockRead: native ? "inventory_native_new_purchase_stock_read_unsupported"
+        : newPurchaseStockReadPort ? null : "inventory_new_purchase_stock_reader_required",
+    },
+  };
+}

package/src/inventory/index.ts

@@ -19,3 +19,4 @@ export { createPostgresRenewalReservationPort, type AutomaticRenewalInventoryPor
 export { forecastSubscriptionInventoryShortages, buildSubscriptionInventoryForecast } from "./forecast.js";
 export { calculateSubscriptionForecastSkus, calculateSubscriptionForecastTotals } from "./subscriptionForecastCalculation.js";
 export { INVENTORY_MIGRATIONS } from "./sql.js";
+export { createInventoryBindings, type InventoryBindingDependencies, type InventoryBindings } from "./bindings.js";

package/src/pricing/commercePriceAuthority.ts

@@ -84,6 +84,71 @@ export function createCommercePriceAuthorityPort(
   };
 }
 
+/** Opt-in scheduling using the selected list for concurrent history reads. */
+export function createConcurrentCommercePriceAuthorityPort(
+  reads: CommercePriceAuthorityReadPort,
+): CommercePriceAuthorityPort {
+  return {
+    async resolvePrice(query): Promise<CommercePriceAuthorityResult> {
+      const atTime = query.atTime ?? new Date().toISOString();
+      const priceListId = selectUniqueEffectivePriceList(await reads.listPriceLists(query), atTime);
+
+      // Schedule history alongside base reads, retaining base-refusal precedence.
+      const policyHistoryRead = query.mode === "subscription" ? Promise.resolve().then(() =>
+        reads.listSubscriptionPolicyHistory({ priceListId, regionCode: query.regionCode,
+          currency: query.currency, channel: query.channel })).then(
+        (value) => ({ value }), (error: unknown) => ({ error }),
+      ) : null;
+
+      const baseCandidates = effective(await reads.listExactBaseEntries({
+        variantId: query.variantId,
+        priceListId,
+      }), atTime);
+      if (baseCandidates.length === 0) throw new CommercePriceAuthorityError("base_price_not_found");
+      if (baseCandidates.length !== 1) throw new CommercePriceAuthorityError("base_price_ambiguous");
+      if (baseCandidates[0]!.value.amountKind !== "gross") {
+        throw new CommercePriceAuthorityError("base_price_amount_kind_invalid");
+      }
+
+      const base = { ...baseCandidates[0]!.value, resolvedAt: atTime };
+      if (query.mode === "one_time") return { kind: "one_time", base, unitPriceMinor: base.unitPriceMinor };
+
+      const policyRead = await policyHistoryRead!;
+      if ("error" in policyRead) throw policyRead.error;
+      const policyHistory = policyRead.value;
+      if (policyHistory.length === 0) {
+        const legacyCandidates = effective(await reads.listExactLegacySubscriptionEntries({
+          variantId: query.variantId,
+          priceListId: base.priceListId,
+        }), atTime);
+        if (legacyCandidates.length === 0) throw new CommercePriceAuthorityError("legacy_subscription_price_not_found");
+        if (legacyCandidates.length !== 1) throw new CommercePriceAuthorityError("legacy_subscription_price_ambiguous");
+        const legacyResolved = { ...legacyCandidates[0]!.value, resolvedAt: atTime };
+        return { kind: "subscription_legacy", base, unitPriceMinor: legacyResolved.unitPriceMinor, legacyResolved };
+      }
+
+      const effectivePolicies = effective(policyHistory, atTime);
+      if (effectivePolicies.length === 0) throw new CommercePriceAuthorityError("subscription_price_policy_not_effective");
+      if (effectivePolicies.length !== 1) throw new CommercePriceAuthorityError("subscription_price_policy_ambiguous");
+      try {
+        const policy = await assertSubscriptionPricePolicyDigest(effectivePolicies[0]!.value);
+        return {
+          kind: "subscription_policy",
+          base,
+          unitPriceMinor: deriveSubscriptionUnitPrice(base.unitPriceMinor, policy),
+          policy,
+        };
+      } catch (error) {
+        throw new CommercePriceAuthorityError(
+          error instanceof SubscriptionPricePolicyDigestError
+            ? "subscription_price_policy_digest_mismatch"
+            : "subscription_price_policy_invalid",
+        );
+      }
+    },
+  };
+}
+
 /** The current money context requires one list; creation order cannot resolve overlap. */
 export function selectUniqueEffectivePriceList(
   priceLists: readonly TimedAuthorityValue<string>[], atTime: string,

package/src/pricing/commerceQuoteHandler.ts

@@ -1,3 +1,4 @@
+import type { ShippingTerms } from "../shipping/index.js";
 import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
 import { mapAcquisitionTermsFailure } from "./acquisitionQuoteBinding.js";
 import type { HttpRequest, HttpResponse } from "../http/index.js";
@@ -28,6 +29,7 @@ function commerceQuoteFailureDetails(stage: CommerceQuoteFailureStage) {
 
 export interface CommerceQuoteHandlerDeps<Request extends CreateQuoteRequest = CreateQuoteRequest, Response extends CreateQuoteResponse = CreateQuoteResponse> {
   responder: BffResponder;
+  shipping?: { terms(quote: Response["quote"]): ShippingTerms | undefined };
   acquisition?: { terms(quote: Response["quote"]): ResolvedAcquisitionTerms | undefined };
   createQuoteRequestSchema: z.ZodType<Request>;
   createQuoteResponseSchema: z.ZodType<Response>;
@@ -46,12 +48,14 @@ export interface CommerceQuoteHandlerDeps<Request extends CreateQuoteRequest = C
     request: Request,
     quote: Awaited<ReturnType<CommerceQuotePort<Request, Response>["createQuote"]>>["quote"],
     acquisitionTerms?: ResolvedAcquisitionTerms,
+    shippingTerms?: ShippingTerms,
   ) => string | null;
   honorPromotionAcceptance?: (
     token: string,
     request: Request,
     quote: Awaited<ReturnType<CommerceQuotePort<Request, Response>["createQuote"]>>["quote"],
     acquisitionTerms?: ResolvedAcquisitionTerms,
+    shippingTerms?: ShippingTerms,
   ) => boolean;
 }
 
@@ -59,6 +63,7 @@ export function createCommerceQuoteHandler<Request extends CreateQuoteRequest, R
   responder, createQuoteRequestSchema, createQuoteResponseSchema, publicCreateQuoteRequestSchema, publicCreateQuoteResponseSchema,
   quotePort,
   acquisition,
+  shipping,
   fallbackQuotePort,
   resolveCustomerEligibility,
   resolvePricingPolicy,
@@ -110,12 +115,22 @@ export function createCommerceQuoteHandler<Request extends CreateQuoteRequest, R
       let quote = canonicalQuote.data;
       stage = "promotion_acceptance";
       const acquisitionTerms = acquisition?.terms(quote.quote);
-      const honoredToken = promotionAcceptanceToken && honorPromotionAcceptance?.(
-        promotionAcceptanceToken, request.data, quote.quote, acquisitionTerms,
-      ) ? promotionAcceptanceToken : undefined;
-      const issuedToken = honoredToken ?? createPromotionAcceptance?.(request.data, quote.quote, acquisitionTerms) ?? undefined;
+      const shippingTerms = shipping?.terms(quote.quote);
+      const honoredToken = promotionAcceptanceToken && (shipping
+        ? honorPromotionAcceptance?.(promotionAcceptanceToken, request.data, quote.quote, acquisitionTerms, shippingTerms)
+        : honorPromotionAcceptance?.(promotionAcceptanceToken, request.data, quote.quote, acquisitionTerms))
+        ? promotionAcceptanceToken : undefined;
+      const issuedToken = honoredToken ?? (shipping
+        ? createPromotionAcceptance?.(request.data, quote.quote, acquisitionTerms, shippingTerms)
+        : createPromotionAcceptance?.(request.data, quote.quote, acquisitionTerms)) ?? undefined;
       const containsV2Promotion = quote.quote.discounts.some((discount) =>
         discount.promotionEngineVersion === "promotion-engine.v2");
+      if (shippingTerms && !issuedToken) {
+        sendBffError(res, "CONFLICT", "Shipping quote must be refreshed", {
+          details: { feature: "quote", reason: "promotion_acceptance_refresh_required" },
+        });
+        return;
+      }
       if ((containsV2Promotion || acquisitionTerms) && !issuedToken) {
         stage = "promotion_fallback";
         const fallback = fallbackQuotePort
@@ -124,7 +139,7 @@ export function createCommerceQuoteHandler<Request extends CreateQuoteRequest, R
               ...(pricingPolicy ? { pricingPolicy } : {}),
             }))
           : null;
-        if (!fallback?.success || acquisition?.terms(fallback.data.quote) || fallback.data.quote.discounts.some((discount) =>
+        if (!fallback?.success || shipping?.terms(fallback.data.quote) || acquisition?.terms(fallback.data.quote) || fallback.data.quote.discounts.some((discount) =>
           discount.promotionEngineVersion === "promotion-engine.v2")) {
           sendBffError(res, "CONFLICT", "Promotion quote must be refreshed", {
             details: { feature: "quote", reason: "promotion_acceptance_refresh_required" },

package/src/pricing/dbBackedCommerceQuotePort.ts

@@ -1,3 +1,6 @@
+import type { ShippingTerms } from "../shipping/index.js";
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { QuoteShippingPromotionInput, QuoteShippingPromotionResult } from "./quoteShippingPromotions.js";
 import type { PricingResolverPort } from "@openlup/core/pricing";
 import { buildLineBreakdown } from "@openlup/core/pricing";
 import type { CreateQuoteResponse, PricingPolicySnapshot, CreateQuoteRequest, CommerceQuoteContext, CommerceQuoteLine, CommerceQuotePricingComponent, CommerceTaxProfile, CommerceQuoteDiscount, CommerceCodeRejection, CommerceCodeRejectionDetail, CartLineInput } from "./contracts/index.js";
@@ -27,6 +30,7 @@ export interface DbBackedCommerceQuotePortDeps<Request extends CreateQuoteReques
   currency: string;
   now?: () => string;
   shippingFlatMinor?: () => Promise<number>;
+  resolveQuoteShippingPromotions?: (input: QuoteShippingPromotionInput<Request>) => Promise<QuoteShippingPromotionResult>;
   hasPromotionCodePort: boolean;
   lineContext(line: CartLineInput, item: Item): LineContext;
   quoteContext(request: Request, lines: Array<LineContext & { line: CommerceQuoteLine }>): () => Context;
@@ -52,14 +56,14 @@ export function createDbBackedCommerceQuotePort<
     now = () => new Date().toISOString(),
     quoteCatalogReadPort, isStrictD1Quote, pricingResolverPort,
     commercePriceAuthorityPort, shippingFlatMinor, resolveAutomaticQuotePromotions,
-    applyPromotionCodesV2, hasPromotionCodePort, lineContext, quoteContext,
+    applyPromotionCodesV2, hasPromotionCodePort, lineContext, quoteContext, resolveQuoteShippingPromotions,
   } = deps;
   assertSupportedCommerceTaxProfile(taxProfile, supportedTaxProfiles);
   const money = moneyIn(currency);
   async function createServerAuthoritativeQuote(
       request: Request,
       options?: CreateQuoteOptions,
-    ): Promise<Omit<CreateQuoteResponse, "quote"> & { quote: Omit<CreateQuoteResponse["quote"], "context"> & { context: Context & { pricingPolicy?: PricingPolicySnapshot } } }> {
+    ): Promise<Omit<CreateQuoteResponse, "quote"> & { quote: Omit<CreateQuoteResponse["quote"], "context"> & { context: Context & { pricingPolicy?: PricingPolicySnapshot; shippingTerms?: ShippingTerms; acquisitionTerms?: ResolvedAcquisitionTerms } } }> {
       const atTime = now();
       const skuIndex = await buildSkuIndex(quoteCatalogReadPort);
       const pricedLines = await Promise.all(request.lines.map(async (requestLine) => {
@@ -178,33 +182,48 @@ export function createDbBackedCommerceQuotePort<
       const referenceProductMinor = sum(pricedLines.map((entry) => entry.referenceGrossMinor));
       const netTotalMinor = sum(lines.map((line) => line.tax.netAmount.amountMinor));
       const taxTotalMinor = sum(lines.map((line) => line.tax.vatAmount.amountMinor));
-      // Shipping is a flat per-order gross from settings; absent settings port ⇒ no
-      // shipping (byte-identical to pre-shipping quotes). Resolved before promo eval so
-      // the free-shipping lane has a real amount to zero.
-      const shippingGrossMinor = shippingFlatMinor
-        ? await shippingFlatMinor()
-        : 0;
-      const automaticPromotionResult = await resolveAutomaticQuotePromotions({
-        request,
-        options,
-        regionCode,
-        referenceProductMinor,
-        subtotalGrossMinor,
-        shippingGrossMinor,
-        atTime,
-      });
-      const promotionResult = await applyPromotionCodesV2({
-        preserveLegacyDiscountsWhenNoCandidates: options?.pricingPolicy?.promotionEngineVersion !== PROMOTION_ENGINE_V2,
-        clientId: options?.clientId ?? null,
-        mode: request.mode,
-        promoCodes: request.promoCodes,
-        referenceProductMinor: sum(pricedLines.map((entry) => entry.referenceGrossMinor)),
-        subtotalGrossMinor,
-        shippingGrossMinor,
-        discounts: automaticPromotionResult.discounts,
-        codeRejections: automaticPromotionResult.codeRejections,
-        atTime,
-      });
+      let shippingGrossMinor: number;
+      let promotionResult: QuotePromotionResult;
+      let hasShipping: boolean;
+      let shippingTerms: ShippingTerms | undefined;
+      let acquisitionTerms: ResolvedAcquisitionTerms | undefined;
+      if (resolveQuoteShippingPromotions) {
+        const resolved = await resolveQuoteShippingPromotions({ request, options, regionCode, currency, referenceProductMinor, subtotalGrossMinor, atTime });
+        shippingGrossMinor = resolved.shippingGrossMinor;
+        promotionResult = resolved;
+        hasShipping = resolved.hasShipping;
+        shippingTerms = resolved.shippingTerms;
+        acquisitionTerms = resolved.acquisitionTerms;
+      } else {
+        // Shipping is a flat per-order gross from settings; absent settings port ⇒ no
+        // shipping (byte-identical to pre-shipping quotes). Resolved before promo eval so
+        // the free-shipping lane has a real amount to zero.
+        shippingGrossMinor = shippingFlatMinor
+          ? await shippingFlatMinor()
+          : 0;
+        const automaticPromotionResult = await resolveAutomaticQuotePromotions({
+          request,
+          options,
+          regionCode,
+          referenceProductMinor,
+          subtotalGrossMinor,
+          shippingGrossMinor,
+          atTime,
+        });
+        promotionResult = await applyPromotionCodesV2({
+          preserveLegacyDiscountsWhenNoCandidates: options?.pricingPolicy?.promotionEngineVersion !== PROMOTION_ENGINE_V2,
+          clientId: options?.clientId ?? null,
+          mode: request.mode,
+          promoCodes: request.promoCodes,
+          referenceProductMinor: sum(pricedLines.map((entry) => entry.referenceGrossMinor)),
+          subtotalGrossMinor,
+          shippingGrossMinor,
+          discounts: automaticPromotionResult.discounts,
+          codeRejections: automaticPromotionResult.codeRejections,
+          atTime,
+        });
+        hasShipping = shippingFlatMinor != null;
+      }
       const { discounts, codeRejections, codeRejectionDetails } = promotionResult;
       // Two lanes: order_total/line discounts reduce the subtotal; a shipping discount
       // (free-shipping promo) reduces the shipping gross. They are summed and validated
@@ -222,7 +241,6 @@ export function createDbBackedCommerceQuotePort<
       );
       const ship = splitIncludedVat(shippingGrossMinor, taxProfile.vatRateBps);
       const shipDiscount = splitIncludedVat(shippingDiscountMinor, taxProfile.vatRateBps);
-      const hasShipping = shippingFlatMinor != null;
       const shippingFields = hasShipping
         ? {
             shippingGross: money(shippingGrossMinor),
@@ -241,6 +259,8 @@ export function createDbBackedCommerceQuotePort<
           pricingComponents: quoteComponents,
           context: {
             ...context(),
+            ...(resolveQuoteShippingPromotions && acquisitionTerms ? { acquisitionTerms } : {}),
+            ...(resolveQuoteShippingPromotions && shippingTerms ? { shippingTerms } : {}),
             ...(options?.pricingPolicy ? { pricingPolicy: options.pricingPolicy } : {}),
           },
           subtotalGross: money(subtotalGrossMinor),

package/src/pricing/index.ts

@@ -1,7 +1,7 @@
 export * from "./contracts/index.js";
 export { CommercePriceAuthorityError } from "./ports.js";
 export type { CommercePriceAuthorityPort } from "./ports.js";
-export { createCommercePriceAuthorityPort, selectUniqueEffectivePriceList } from "./commercePriceAuthority.js";
+export { createCommercePriceAuthorityPort, createConcurrentCommercePriceAuthorityPort, 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";
@@ -50,3 +50,4 @@ export * from "./acquisitionOfferPricingSchemas.js";
 export * from "./acquisitionOfferPricing.js";
 export * from "./acquisitionOfferPricingHandler.js";
 export * from "./acquisitionReadiness.js";
+export type { QuoteShippingPromotionInput, QuoteShippingPromotionResult } from "./quoteShippingPromotions.js";

package/src/pricing/quoteShippingPromotions.ts

@@ -0,0 +1,21 @@
+import type { ShippingTerms } from "../shipping/index.js";
+import type { ResolvedAcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { CreateQuoteRequest } from "./contracts/quote.js";
+import type { CreateQuoteOptions } from "./quotePorts.js";
+import type { QuotePromotionResult } from "./dbBackedCommerceQuotePort.js";
+
+export interface QuoteShippingPromotionInput<Request extends CreateQuoteRequest> {
+  request: Request;
+  options?: CreateQuoteOptions;
+  regionCode: string;
+  currency: string;
+  referenceProductMinor: number;
+  subtotalGrossMinor: number;
+  atTime: string;
+}
+export interface QuoteShippingPromotionResult extends QuotePromotionResult {
+  shippingGrossMinor: number;
+  hasShipping: boolean;
+  shippingTerms?: ShippingTerms;
+  acquisitionTerms?: ResolvedAcquisitionTerms;
+}