@openlup/platform 0.16.0 → 0.18.0

package/src/inventory/newPurchaseStockAvailability.ts

@@ -0,0 +1,120 @@
+import type { NewPurchaseStockRow, NewPurchaseStockMode, NewPurchaseStockAvailabilityOptions } from "./contracts/newPurchaseStock.js";
+
+type BundleStockStatus = "available" | "low_stock" | "out_of_stock" | "unknown";
+interface BundleStockRequestItem {
+  sku: string;
+  productSlug: string;
+  variantId: string;
+  requestedQuantity: number;
+  checkoutMode: "one_time" | "subscription";
+}
+interface BundleStockAvailability {
+  sku: string;
+  productSlug: string;
+  variantId: string;
+  status: BundleStockStatus;
+  visibleInConfigurator: boolean;
+  sellableNow: number | null;
+  reasonCode: string;
+  source: string;
+}
+interface BundleStockPort {
+  getAvailability(input: { items: readonly BundleStockRequestItem[] }): Promise<BundleStockAvailability[]>;
+}
+
+/** Normalized host read. Transport, missing-function recognition and fallback stay with the host. */
+export interface NewPurchaseStockReadPort {
+  read(input: { skus: readonly string[]; horizonDays: number; excludeOrderId: string | null }): Promise<Map<string, NewPurchaseStockRow>>;
+}
+interface StockBindings {
+  readPort: NewPurchaseStockReadPort;
+  functionMissingFallback: (() => BundleStockPort) | null;
+  functionMissingError: string;
+  defaultLowStockThreshold: number;
+  defaultHorizonDays: number;
+  deriveOfferAvailability(input: BundleStockRequestItem & { sellableNow: number | null; lowStockThreshold: number; source: string }): BundleStockAvailability;
+  observe: Pick<Console, "warn">;
+}
+
+export function createNewPurchaseStockAvailabilityPort(
+  { readPort, functionMissingFallback, functionMissingError, defaultLowStockThreshold, defaultHorizonDays, deriveOfferAvailability, observe }: StockBindings,
+  options: NewPurchaseStockAvailabilityOptions,
+): BundleStockPort {
+  const lowStockThreshold = options.lowStockThreshold ?? defaultLowStockThreshold;
+  const horizonDays = options.horizonDays ?? defaultHorizonDays;
+
+  return {
+    async getAvailability({ items }) {
+      if (items.length === 0) return [];
+
+      let rows: Map<string, NewPurchaseStockRow>;
+      try {
+        rows = await readPort.read({
+          skus: items.map((item) => item.sku),
+          horizonDays,
+          excludeOrderId: null,
+        });
+      } catch (error) {
+        if (
+          functionMissingFallback
+          && error instanceof Error
+          && error.message === functionMissingError
+        ) {
+          observe.warn("[new-purchase-stock] function missing; falling back to the core availability read");
+          return functionMissingFallback().getAvailability({ items });
+        }
+        observe.warn("[new-purchase-stock] availability read failed", {
+          reason: error instanceof Error ? error.message : String(error),
+        });
+        return items.map((item) => unknownAvailability(item, "inventory_read_failed"));
+      }
+
+      // Same branch rule as the core adapter: once any requested SKU is
+      // provider-backed, every SKU must be, and a SKU without a provider row is
+      // not sellable rather than silently falling back to local stock.
+      const providerBacked = [...rows.values()].some((row) => row.source === "provider");
+      return items.map((item) => {
+        const row = rows.get(item.sku);
+        if (providerBacked) {
+          if (row?.source !== "provider") return unavailable(item, "provider_stock_missing");
+          if (row.stale) return unavailable(item, "provider_stock_stale");
+          return deriveOfferAvailability({
+            ...item,
+            sellableNow: sellableFor(row, options.mode),
+            lowStockThreshold,
+            source: "inventory_provider",
+          });
+        }
+        return deriveOfferAvailability({
+          ...item,
+          sellableNow: row?.source === "local" ? sellableFor(row, options.mode) : null,
+          lowStockThreshold,
+          source: "inventory",
+        });
+      });
+    },
+  };
+}
+
+function sellableFor(row: NewPurchaseStockRow, mode: NewPurchaseStockMode): number | null {
+  const value = mode === "new_purchase" ? row.availableForNewPurchases : row.available;
+  return value == null ? null : Math.max(0, value);
+}
+
+/** The core adapter's provider-missing / provider-stale answer shape. */
+function unavailable(item: BundleStockRequestItem, reasonCode: string): BundleStockAvailability {
+  const { sku, productSlug, variantId } = item;
+  return {
+    sku, productSlug, variantId, status: "out_of_stock", visibleInConfigurator: false, sellableNow: 0,
+    reasonCode, source: "inventory_provider",
+  };
+}
+
+/** The core adapter's read-failure answer shape. */
+function unknownAvailability(item: BundleStockRequestItem, reasonCode: string): BundleStockAvailability {
+  const { sku, productSlug, variantId } = item;
+  return {
+    sku, productSlug, variantId, status: "unknown", visibleInConfigurator: true, sellableNow: null,
+    reasonCode, source: "inventory",
+  };
+}

package/src/inventory/ports.ts

@@ -0,0 +1,46 @@
+import type { InventoryAtpRequest, InventoryAtpResult } from "@openlup/core/inventory";
+import type {
+  AdminInventoryReservationsRequest,
+  AdminInventoryStockAdjustmentRequest,
+  AdminInventoryStockRequest,
+  AdminInventorySubscriptionForecastRequest,
+  InventoryReservationsListResponse,
+  InventoryStockAdjustmentResponse,
+  InventoryStockListResponse,
+  InventorySubscriptionForecastResponse,
+} from "./contracts/index.js";
+
+export interface InventoryReadPort {
+  listStock(request: AdminInventoryStockRequest): Promise<InventoryStockListResponse>;
+  listReservations(request: AdminInventoryReservationsRequest): Promise<InventoryReservationsListResponse>;
+  checkAtp(request: InventoryAtpRequest): Promise<InventoryAtpResult>;
+  forecastSubscriptions(
+    request: AdminInventorySubscriptionForecastRequest,
+  ): Promise<InventorySubscriptionForecastResponse>;
+}
+
+export interface InventoryMutationPort {
+  adjustStock(
+    request: AdminInventoryStockAdjustmentRequest & { actorUserId: string },
+  ): Promise<InventoryStockAdjustmentResponse>;
+}
+
+export class InventoryPersistenceError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(message = "Inventory persistence failed", details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "InventoryPersistenceError";
+    this.details = details;
+  }
+}
+
+export class InventoryConflictError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(message = "Inventory conflict", details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "InventoryConflictError";
+    this.details = details;
+  }
+}

package/src/inventory/renewalReservation.ts

@@ -0,0 +1,88 @@
+import type { AutomaticRenewalReservationResult } from "./contracts/reservation.js";
+
+interface PgQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+export interface AutomaticRenewalInventoryPort {
+  reserve(input: {
+    operationId: string;
+    claimToken: string;
+    holdSeconds?: number;
+    now: string;
+  }): Promise<AutomaticRenewalReservationResult>;
+  releaseReservation(input: {
+    operationId: string;
+    claimToken: string;
+    reason: string;
+    now: string;
+  }): Promise<Record<string, unknown>>;
+  expireReservations(input: { now: string; limit?: number }): Promise<number>;
+}
+
+const RESERVE_SQL = `SELECT public.fulfillment_reserve_subscription_renewal(
+  $1::uuid, $2::uuid, $3::integer, $4::timestamptz) AS response`;
+const RELEASE_SQL = `SELECT public.fulfillment_release_subscription_renewal(
+  $1::uuid, $2::uuid, $3::text, $4::timestamptz) AS response`;
+const EXPIRE_SQL = `SELECT public.fulfillment_expire_subscription_renewals(
+  $1::timestamptz, $2::integer) AS expired`;
+
+/** ATP/reservation adapter; it can reserve only through the fenced public renewal function. */
+export function createPostgresRenewalReservationPort(
+  executor: PgQueryExecutor,
+): AutomaticRenewalInventoryPort {
+  return {
+    async reserve(input) {
+      const result = await executor.query(RESERVE_SQL, [
+        input.operationId,
+        input.claimToken,
+        input.holdSeconds ?? 900,
+        input.now,
+      ]);
+      const row = requiredRecord(record(result.rows[0])?.response, "reserve_response");
+      const status = text(row.status) as AutomaticRenewalReservationResult["status"];
+      if (!["held", "committed", "consumed", "released", "expired", "refused"].includes(status)) {
+        throw new Error("subscription_renewal_reservation_status_invalid");
+      }
+      return {
+        reserved: row.reserved === true,
+        replayed: row.replayed === true,
+        reservationId: nullableText(row.reservationId),
+        status,
+        reason: nullableText(row.reason),
+      };
+    },
+
+    async releaseReservation(input) {
+      const result = await executor.query(RELEASE_SQL, [
+        input.operationId,
+        input.claimToken,
+        input.reason,
+        input.now,
+      ]);
+      return requiredRecord(record(result.rows[0])?.response, "release_response");
+    },
+
+    async expireReservations(input) {
+      const result = await executor.query(EXPIRE_SQL, [input.now, input.limit ?? 100]);
+      const value = Number(record(result.rows[0])?.expired);
+      if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error("subscription_renewal_expiry_response_invalid");
+      }
+      return value;
+    },
+  };
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+function requiredRecord(value: unknown, field: string): Record<string, unknown> {
+  const result = record(value);
+  if (!result) throw new Error(`subscription_renewal_${field}_invalid`);
+  return result;
+}
+function text(value: unknown): string { return typeof value === "string" ? value.trim() : ""; }
+function nullableText(value: unknown): string | null { return text(value) || null; }

package/src/inventory/reservationPolicy.ts

@@ -0,0 +1,27 @@
+import type { ReservationPolicyInput, ReservationPolicy } from "./contracts/reservation.js";
+
+export const MIN_CHECKOUT_RESERVATION_TTL_MINUTES = 24 * 60;
+export const MAX_CHECKOUT_RESERVATION_TTL_MINUTES = 36 * 60;
+export const DEFAULT_CHECKOUT_RESERVATION_TTL_MINUTES = MIN_CHECKOUT_RESERVATION_TTL_MINUTES;
+
+export function reservationPolicyFor(input: ReservationPolicyInput): ReservationPolicy {
+  if (input.reservationKind !== "checkout_payment_window") {
+    return { expiresAt: null, ttlMinutes: null };
+  }
+
+  const ttlMinutes = normalizedTtlMinutes(input.checkoutTtlMinutes);
+  return {
+    expiresAt: new Date(input.now.getTime() + ttlMinutes * 60_000).toISOString(),
+    ttlMinutes,
+  };
+}
+
+export function normalizedTtlMinutes(value: number | null | undefined): number {
+  if (Number.isFinite(value) && value && value > 0) {
+    return Math.min(
+      MAX_CHECKOUT_RESERVATION_TTL_MINUTES,
+      Math.max(MIN_CHECKOUT_RESERVATION_TTL_MINUTES, Math.floor(value)),
+    );
+  }
+  return DEFAULT_CHECKOUT_RESERVATION_TTL_MINUTES;
+}

package/src/inventory/schemas.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { INVENTORY_CONTRACT_VERSION, inventoryStockLineSchema } from "@openlup/core/inventory";
+z.config({ jitless: true });
+
+const inventoryReservationStatusSchema = z.enum([
+  "reserved",
+  "released",
+  "consumed",
+  "expired",
+]);
+
+const inventoryReservationKindSchema = z.enum([
+  "checkout_payment_window",
+  "subscription_retry_window",
+  "manual_ops",
+]);
+
+const uuidSchema = z.guid();
+
+const datetimeSchema = z.string().datetime({ offset: true });
+
+const quantitySchema = z.number().int().nonnegative();
+
+export const adminInventoryStockRequestSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  skuId: uuidSchema.optional(),
+  locationId: uuidSchema.optional(),
+  includeZero: z.coerce.boolean().default(false),
+}).strict();
+
+export const adminInventoryReservationsRequestSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  status: inventoryReservationStatusSchema.optional(),
+  orderId: uuidSchema.optional(),
+}).strict();
+
+export const adminInventoryStockAdjustmentRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  skuId: uuidSchema,
+  locationId: uuidSchema,
+  lotId: uuidSchema.nullable().optional(),
+  quantityDelta: z.number().int(),
+  reason: z.string().trim().min(1).max(120),
+  note: z.string().trim().max(1000).optional(),
+}).strict();
+
+export const adminInventorySubscriptionForecastRequestSchema = z.object({
+  horizonDays: z.coerce.number().int().min(1).max(180).default(60),
+  protectionDays: z.coerce.number().int().min(1).max(180).default(45),
+}).strict().refine((request) => request.protectionDays <= request.horizonDays, {
+  message: "protectionDays must be less than or equal to horizonDays",
+  path: ["protectionDays"],
+});
+
+const inventoryReservationSummarySchema = z.object({
+  id: uuidSchema,
+  orderId: uuidSchema,
+  subscriptionCycleId: uuidSchema.nullable(),
+  status: inventoryReservationStatusSchema,
+  kind: inventoryReservationKindSchema,
+  expiresAt: datetimeSchema.nullable(),
+  createdAt: datetimeSchema,
+}).strict();
+
+export const inventoryStockListResponseSchema = z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  stock: z.array(inventoryStockLineSchema.extend({ availableNow: quantitySchema })),
+  totalCount: z.number().int().min(0),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+}).strict();
+
+export const inventoryReservationsListResponseSchema = z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  reservations: z.array(inventoryReservationSummarySchema),
+  totalCount: z.number().int().min(0),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+}).strict();
+
+const inventorySubscriptionForecastStockStatusSchema = z.enum(["fresh", "stale", "missing"]);
+
+const inventorySubscriptionForecastSkuSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  providerCurrentForSale: quantitySchema.nullable(),
+  providerStockLastSyncedAt: datetimeSchema.nullable(),
+  providerStockStaleAfter: datetimeSchema.nullable(),
+  stockStatus: inventorySubscriptionForecastStockStatusSchema,
+  openHardReservations: quantitySchema,
+  safetyStock: quantitySchema,
+  sellableNow: quantitySchema,
+  activeSubscriptionDemand30: quantitySchema,
+  activeSubscriptionDemand45: quantitySchema,
+  activeSubscriptionDemand60: quantitySchema,
+  plannedSupply: quantitySchema,
+  coverageDays: z.number().int().nonnegative().nullable(),
+  shortageDate: datetimeSchema.nullable(),
+  horizonMissingQty: quantitySchema,
+  protectionMissingQty: quantitySchema,
+  missingQty: quantitySchema,
+  recommendedProductionQty: quantitySchema,
+}).strict();
+
+const inventorySubscriptionForecastTotalsSchema = z.object({
+  activeSubscriptionCount: quantitySchema,
+  excludedSubscriptionCount: quantitySchema,
+  missingProviderStockSkuCount: quantitySchema,
+  staleProviderStockSkuCount: quantitySchema,
+  horizonShortageSkuCount: quantitySchema,
+  protectionShortageSkuCount: quantitySchema,
+  shortageSkuCount: quantitySchema,
+  recommendedProductionQty: quantitySchema,
+}).strict();
+
+export function createInventorySubscriptionForecastResponseSchema(providerSchema: z.ZodType<string>) {
+return z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  generatedAt: datetimeSchema,
+  stockMasterProvider: providerSchema,
+  horizonDays: z.number().int().min(1),
+  protectionDays: z.number().int().min(1),
+  skus: z.array(inventorySubscriptionForecastSkuSchema),
+  totals: inventorySubscriptionForecastTotalsSchema,
+}).strict();
+}

package/src/inventory/sql.ts

@@ -0,0 +1,5 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const INVENTORY_MIGRATIONS = [
+  { id: "20260814000000_fulfillment_stock_evidence", catalogPath: "db/platform/migrations/20260814000000_fulfillment_stock_evidence.sql", position: 27, sha256: "df20c2491cb0196b4e28d19e7578c95bfa5c87b8f89fb0b6284c0e0695a3cc1d", url: new URL("../../sql/20260814000000_fulfillment_stock_evidence.sql", import.meta.url) },
+  { id: "20260815120000_automatic_subscription_renewal", catalogPath: "db/platform/migrations/20260815120000_automatic_subscription_renewal.sql", position: 33, sha256: "edef131f4f483a009e0bb6728a071ab78b6c9ac2aa8047aa7107646a11baec73", url: new URL("../../sql/20260815120000_automatic_subscription_renewal.sql", import.meta.url) },
+] as const;

package/src/inventory/subscriptionForecastCalculation.ts

@@ -0,0 +1,157 @@
+import type { SubscriptionForecastCalculationInput, SubscriptionForecastCounts, SubscriptionForecastSku, SubscriptionForecastTotals, SubscriptionForecastDemandLine, SubscriptionForecastSupplyLine } from "./contracts/forecast.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function calculateSubscriptionForecastSkus(
+  input: SubscriptionForecastCalculationInput,
+): SubscriptionForecastSku[] {
+  const generatedAtMs = Date.parse(input.generatedAt);
+  const horizonAtMs = generatedAtMs + input.horizonDays * DAY_MS;
+  const protectionAtMs = generatedAtMs + input.protectionDays * DAY_MS;
+  const demand = input.demand
+    .filter((line) => !["skipped", "cancelled"].includes(line.status))
+    .filter((line) => Date.parse(line.dueAt) <= horizonAtMs);
+  const plannedSupply = input.supply
+    .filter((line) => line.status === "planned")
+    .filter((line) => Date.parse(line.expectedAt) <= horizonAtMs);
+
+  const providerBySku = new Map(input.providerCurrent.map((line) => [line.skuId, line]));
+  const skuIds = new Set<string>([
+    ...input.providerCurrent.map((line) => line.skuId),
+    ...input.openHardReservations.map((line) => line.skuId),
+    ...input.stock.map((line) => line.skuId),
+    ...demand.map((line) => line.skuId),
+    ...plannedSupply.map((line) => line.skuId),
+  ]);
+
+  const skus = [...skuIds].map<SubscriptionForecastSku>((skuId) => {
+    const provider = providerBySku.get(skuId) ?? null;
+    const stockLines = input.stock.filter((line) => line.skuId === skuId);
+    const demandLines = demand.filter((line) => line.skuId === skuId);
+    const supplyLines = plannedSupply.filter((line) => line.skuId === skuId);
+    const sku = provider?.sku ?? stockLines[0]?.sku ?? demandLines[0]?.sku ?? "unknown";
+    const stockStatus = provider === null
+      ? "missing"
+      : Date.parse(provider.staleAfter) <= generatedAtMs
+        ? "stale"
+        : "fresh";
+    const openHardReservations = sum(input.openHardReservations
+      .filter((line) => line.skuId === skuId)
+      .map((line) => line.quantity));
+    const safetyStock = sum(stockLines
+      .filter((line) => line.fulfillable && line.locationStatus === "active")
+      .map((line) => line.safetyStock));
+    const sellableNow = stockStatus === "fresh" && provider
+      ? Math.max(0, provider.forSaleQuantity - openHardReservations - safetyStock)
+      : 0;
+    const shortage = simulateSubscriptionCoverage({
+      generatedAtMs,
+      protectionAtMs,
+      sellableNow,
+      demand: demandLines,
+      supply: supplyLines,
+    });
+
+    return {
+      skuId,
+      sku,
+      providerCurrentForSale: provider?.forSaleQuantity ?? null,
+      providerStockLastSyncedAt: provider?.lastSyncedAt ?? null,
+      providerStockStaleAfter: provider?.staleAfter ?? null,
+      stockStatus,
+      openHardReservations,
+      safetyStock,
+      sellableNow,
+      activeSubscriptionDemand30: demandQuantityWithin(demandLines, generatedAtMs + 30 * DAY_MS),
+      activeSubscriptionDemand45: demandQuantityWithin(demandLines, generatedAtMs + 45 * DAY_MS),
+      activeSubscriptionDemand60: demandQuantityWithin(demandLines, generatedAtMs + 60 * DAY_MS),
+      plannedSupply: sum(supplyLines.map((line) => line.quantity)),
+      coverageDays: shortage.shortageDate
+        ? Math.max(0, Math.ceil((Date.parse(shortage.shortageDate) - generatedAtMs) / DAY_MS))
+        : null,
+      shortageDate: shortage.shortageDate,
+      horizonMissingQty: shortage.horizonMissingQty,
+      protectionMissingQty: shortage.protectionMissingQty,
+      missingQty: shortage.protectionMissingQty,
+      recommendedProductionQty: shortage.protectionMissingQty,
+    };
+  }).sort((a, b) => a.sku.localeCompare(b.sku));
+
+  return skus;
+}
+
+/** Kept separate so native envelopes can read their metadata before count getters. */
+export function calculateSubscriptionForecastTotals(
+  input: SubscriptionForecastCounts,
+  skus: SubscriptionForecastSku[],
+): SubscriptionForecastTotals {
+  return {
+    activeSubscriptionCount: input.activeSubscriptionCount,
+    excludedSubscriptionCount: input.excludedSubscriptionCount,
+    missingProviderStockSkuCount: skus.filter((line) => line.stockStatus === "missing").length,
+    staleProviderStockSkuCount: skus.filter((line) => line.stockStatus === "stale").length,
+    horizonShortageSkuCount: skus.filter((line) => line.shortageDate !== null).length,
+    protectionShortageSkuCount: skus.filter((line) => line.protectionMissingQty > 0).length,
+    shortageSkuCount: skus.filter((line) => line.shortageDate !== null).length,
+    recommendedProductionQty: sum(skus.map((line) => line.recommendedProductionQty)),
+  };
+}
+
+function simulateSubscriptionCoverage(input: {
+  generatedAtMs: number;
+  protectionAtMs: number;
+  sellableNow: number;
+  demand: SubscriptionForecastDemandLine[];
+  supply: SubscriptionForecastSupplyLine[];
+}): { shortageDate: string | null; horizonMissingQty: number; protectionMissingQty: number } {
+  let available = input.sellableNow;
+  let shortageDate: string | null = null;
+  let horizonMissingQty = 0;
+  let protectionMissingQty = 0;
+  const events = [
+    ...input.supply.map((line) => ({
+      type: "supply" as const,
+      at: line.expectedAt,
+      quantity: line.quantity,
+    })),
+    ...input.demand.map((line) => ({
+      type: "demand" as const,
+      at: line.dueAt,
+      quantity: line.quantity,
+    })),
+  ].sort((a, b) => {
+    const dateDelta = Date.parse(a.at) - Date.parse(b.at);
+    if (dateDelta !== 0) return dateDelta;
+    return a.type === "supply" && b.type === "demand" ? -1 : 1;
+  });
+
+  for (const event of events) {
+    if (event.type === "supply") {
+      available += event.quantity;
+      continue;
+    }
+
+    if (available >= event.quantity) {
+      available -= event.quantity;
+      continue;
+    }
+
+    const missing = event.quantity - available;
+    available = 0;
+    shortageDate ??= event.at;
+    horizonMissingQty += missing;
+    if (Date.parse(event.at) <= input.protectionAtMs) protectionMissingQty += missing;
+  }
+
+  return { shortageDate, horizonMissingQty, protectionMissingQty };
+}
+
+function demandQuantityWithin(lines: SubscriptionForecastDemandLine[], dueAtOrBeforeMs: number): number {
+  return sum(lines
+    .filter((line) => Date.parse(line.dueAt) <= dueAtOrBeforeMs)
+    .map((line) => line.quantity));
+}
+
+function sum(values: number[]): number {
+  return values.reduce((total, value) => total + value, 0);
+}

package/src/pricing/acquisitionFinancialPolicy.ts

@@ -0,0 +1,26 @@
+import type { AcquisitionTermsMetadata } from "./contracts/acquisitionTerms.js";
+export type AcquisitionRowFacts = Readonly<{
+  id: string;
+  active: boolean;
+  regionCodes: readonly string[];
+  validFrom: string;
+  validTo: string | null;
+  mirrorOf: unknown;
+  metadataPresent: boolean;
+  metadata: unknown;
+}>;
+export type AcquisitionClassification = Readonly<{
+  baselineLegacy: boolean;
+  target: boolean;
+  canonicalRow: boolean;
+  unconfiguredLegacyEligible: boolean;
+}>;
+/** Required host policy. No financial predicates or schedules are inferred. */
+export interface AcquisitionFinancialPolicy<Row> {
+  facts(row: Row): AcquisitionRowFacts;
+  classify(row: Row): AcquisitionClassification;
+  validateMetadata(row: Row, terms: AcquisitionTermsMetadata): void;
+  pairMatches(legacy: Row, mirror: Row): boolean;
+  initialDiscountBps(row: Row, purpose: "resolved_target" | "filter_validation"): unknown;
+  unconfiguredTerms(legacy: Row, mirror: Row): AcquisitionTermsMetadata;
+}

package/src/pricing/acquisitionOfferPricing.ts

@@ -0,0 +1,38 @@
+import { projectCommerceOfferPricing, type CommerceOfferPricingDeps } from "./commerceOfferPricing.js";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, type AcquisitionOfferPricingResponse } from "./contracts/offer.js";
+import { ACQUISITION_TERMS_CAPABILITY, type AcquisitionTerms } from "./contracts/acquisitionTerms.js";
+import type { CommerceQuoteCatalogItem } from "./commerceQuoteCatalogReadPort.js";
+import type { CreateQuoteRequest } from "./contracts/quote.js";
+import { ACQUISITION_PROJECTION_MAX_AGE_MS, acquisitionProjectionFreshnessSchema } from "./acquisitionOfferPricingSchemas.js";
+
+export function acquisitionProjectionFreshness(acquisitionTerms: AcquisitionTerms, observedAt: string, nextBoundaryAt?: string | null) {
+  const boundary = nextBoundaryAt ?? acquisitionTerms.effectiveTo;
+  const validUntil = new Date(Math.min(Date.parse(observedAt) + ACQUISITION_PROJECTION_MAX_AGE_MS,
+    boundary == null ? Infinity : Date.parse(boundary))).toISOString();
+  return acquisitionProjectionFreshnessSchema.parse({ acquisitionTerms, observedAt, validUntil });
+}
+
+/** Explicit opt-in projection; the incumbent projector receives no new defaults. */
+export async function projectAcquisitionOfferPricing<Item extends CommerceQuoteCatalogItem, ScopeV1 extends string, ScopeV2 extends string>(
+  input: Omit<CommerceOfferPricingDeps<Item, ScopeV1, ScopeV2>, "requestFor"> & {
+    acquisitionTerms: AcquisitionTerms;
+    observedAt: string;
+    nextBoundaryAt?: string | null;
+    requestFor(product: Item, mode: "one_time" | "subscription", acquisition: {
+      acquisitionCapability: typeof ACQUISITION_TERMS_CAPABILITY; atTime: string;
+    }): CreateQuoteRequest;
+  },
+): Promise<AcquisitionOfferPricingResponse<ScopeV2>> {
+  const freshness = acquisitionProjectionFreshness(input.acquisitionTerms, input.observedAt, input.nextBoundaryAt);
+  if (input.pricingPolicy?.offerPolicyVersion !== "commerce.offer-policy.v2" ||
+    input.pricingPolicy.promotionEngineVersion !== "promotion-engine.v2") {
+    throw new Error("commerce_acquisition_projection_policy_invalid");
+  }
+  const projection = await projectCommerceOfferPricing({ ...input,
+    requestFor: (product, mode) => input.requestFor(product, mode, {
+      acquisitionCapability: ACQUISITION_TERMS_CAPABILITY, atTime: input.observedAt,
+    }),
+  });
+  if (projection.contractVersion !== COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION) throw new Error("commerce_acquisition_projection_policy_invalid");
+  return { ...projection, contractVersion: COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION, ...freshness };
+}