@openlup/platform 0.16.0 → 0.18.0

package/dist/inventory/ports.js

@@ -0,0 +1,16 @@
+export class InventoryPersistenceError extends Error {
+    details;
+    constructor(message = "Inventory persistence failed", details = {}) {
+        super(message);
+        this.name = "InventoryPersistenceError";
+        this.details = details;
+    }
+}
+export class InventoryConflictError extends Error {
+    details;
+    constructor(message = "Inventory conflict", details = {}) {
+        super(message);
+        this.name = "InventoryConflictError";
+        this.details = details;
+    }
+}

package/dist/inventory/renewalReservation.d.ts

@@ -0,0 +1,27 @@
+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>;
+}
+/** ATP/reservation adapter; it can reserve only through the fenced public renewal function. */
+export declare function createPostgresRenewalReservationPort(executor: PgQueryExecutor): AutomaticRenewalInventoryPort;
+export {};

package/dist/inventory/renewalReservation.js

@@ -0,0 +1,61 @@
+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) {
+    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);
+            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) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function requiredRecord(value, field) {
+    const result = record(value);
+    if (!result)
+        throw new Error(`subscription_renewal_${field}_invalid`);
+    return result;
+}
+function text(value) { return typeof value === "string" ? value.trim() : ""; }
+function nullableText(value) { return text(value) || null; }

package/dist/inventory/reservationPolicy.d.ts

@@ -0,0 +1,6 @@
+import type { ReservationPolicyInput, ReservationPolicy } from "./contracts/reservation.js";
+export declare const MIN_CHECKOUT_RESERVATION_TTL_MINUTES: number;
+export declare const MAX_CHECKOUT_RESERVATION_TTL_MINUTES: number;
+export declare const DEFAULT_CHECKOUT_RESERVATION_TTL_MINUTES: number;
+export declare function reservationPolicyFor(input: ReservationPolicyInput): ReservationPolicy;
+export declare function normalizedTtlMinutes(value: number | null | undefined): number;

package/dist/inventory/reservationPolicy.js

@@ -0,0 +1,19 @@
+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) {
+    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) {
+    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/dist/inventory/schemas.d.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+export declare const adminInventoryStockRequestSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    skuId: z.ZodOptional<z.ZodGUID>;
+    locationId: z.ZodOptional<z.ZodGUID>;
+    includeZero: z.ZodDefault<z.ZodCoercedBoolean<unknown>>;
+}, z.core.$strict>;
+export declare const adminInventoryReservationsRequestSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        expired: "expired";
+        reserved: "reserved";
+        released: "released";
+        consumed: "consumed";
+    }>>;
+    orderId: z.ZodOptional<z.ZodGUID>;
+}, z.core.$strict>;
+export declare const adminInventoryStockAdjustmentRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    skuId: z.ZodGUID;
+    locationId: z.ZodGUID;
+    lotId: z.ZodOptional<z.ZodNullable<z.ZodGUID>>;
+    quantityDelta: z.ZodNumber;
+    reason: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const adminInventorySubscriptionForecastRequestSchema: z.ZodObject<{
+    horizonDays: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    protectionDays: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export declare const inventoryStockListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"inventory.v0">;
+    stock: z.ZodArray<z.ZodObject<{
+        skuId: z.ZodGUID;
+        sku: z.ZodString;
+        locationId: z.ZodGUID;
+        locationCode: z.ZodString;
+        locationKind: z.ZodEnum<{
+            internal_warehouse: "internal_warehouse";
+            third_party_logistics: "third_party_logistics";
+            supplier: "supplier";
+            quarantine: "quarantine";
+            virtual: "virtual";
+        }>;
+        locationStatus: z.ZodEnum<{
+            active: "active";
+            inactive: "inactive";
+        }>;
+        fulfillable: z.ZodBoolean;
+        lotId: z.ZodNullable<z.ZodGUID>;
+        lotCode: z.ZodNullable<z.ZodString>;
+        lotStatus: z.ZodNullable<z.ZodEnum<{
+            expired: "expired";
+            available: "available";
+            quarantined: "quarantined";
+            recalled: "recalled";
+        }>>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        onHand: z.ZodNumber;
+        reserved: z.ZodNumber;
+        unavailable: z.ZodNumber;
+        incoming: z.ZodNumber;
+        safetyStock: z.ZodNumber;
+        availableNow: z.ZodNumber;
+    }, z.core.$strict>>;
+    totalCount: z.ZodNumber;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+}, z.core.$strict>;
+export declare const inventoryReservationsListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"inventory.v0">;
+    reservations: z.ZodArray<z.ZodObject<{
+        id: z.ZodGUID;
+        orderId: z.ZodGUID;
+        subscriptionCycleId: z.ZodNullable<z.ZodGUID>;
+        status: z.ZodEnum<{
+            expired: "expired";
+            reserved: "reserved";
+            released: "released";
+            consumed: "consumed";
+        }>;
+        kind: z.ZodEnum<{
+            checkout_payment_window: "checkout_payment_window";
+            subscription_retry_window: "subscription_retry_window";
+            manual_ops: "manual_ops";
+        }>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+    totalCount: z.ZodNumber;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+}, z.core.$strict>;
+export declare function createInventorySubscriptionForecastResponseSchema(providerSchema: z.ZodType<string>): z.ZodObject<{
+    contractVersion: z.ZodLiteral<"inventory.v0">;
+    generatedAt: z.ZodString;
+    stockMasterProvider: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    horizonDays: z.ZodNumber;
+    protectionDays: z.ZodNumber;
+    skus: z.ZodArray<z.ZodObject<{
+        skuId: z.ZodGUID;
+        sku: z.ZodString;
+        providerCurrentForSale: z.ZodNullable<z.ZodNumber>;
+        providerStockLastSyncedAt: z.ZodNullable<z.ZodString>;
+        providerStockStaleAfter: z.ZodNullable<z.ZodString>;
+        stockStatus: z.ZodEnum<{
+            stale: "stale";
+            missing: "missing";
+            fresh: "fresh";
+        }>;
+        openHardReservations: z.ZodNumber;
+        safetyStock: z.ZodNumber;
+        sellableNow: z.ZodNumber;
+        activeSubscriptionDemand30: z.ZodNumber;
+        activeSubscriptionDemand45: z.ZodNumber;
+        activeSubscriptionDemand60: z.ZodNumber;
+        plannedSupply: z.ZodNumber;
+        coverageDays: z.ZodNullable<z.ZodNumber>;
+        shortageDate: z.ZodNullable<z.ZodString>;
+        horizonMissingQty: z.ZodNumber;
+        protectionMissingQty: z.ZodNumber;
+        missingQty: z.ZodNumber;
+        recommendedProductionQty: z.ZodNumber;
+    }, z.core.$strict>>;
+    totals: z.ZodObject<{
+        activeSubscriptionCount: z.ZodNumber;
+        excludedSubscriptionCount: z.ZodNumber;
+        missingProviderStockSkuCount: z.ZodNumber;
+        staleProviderStockSkuCount: z.ZodNumber;
+        horizonShortageSkuCount: z.ZodNumber;
+        protectionShortageSkuCount: z.ZodNumber;
+        shortageSkuCount: z.ZodNumber;
+        recommendedProductionQty: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;

package/dist/inventory/schemas.js

@@ -0,0 +1,112 @@
+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) {
+    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/dist/inventory/sql.d.ts

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

package/dist/inventory/sql.js

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

package/dist/inventory/subscriptionForecastCalculation.d.ts

@@ -0,0 +1,4 @@
+import type { SubscriptionForecastCalculationInput, SubscriptionForecastCounts, SubscriptionForecastSku, SubscriptionForecastTotals } from "./contracts/forecast.js";
+export declare function calculateSubscriptionForecastSkus(input: SubscriptionForecastCalculationInput): SubscriptionForecastSku[];
+/** Kept separate so native envelopes can read their metadata before count getters. */
+export declare function calculateSubscriptionForecastTotals(input: SubscriptionForecastCounts, skus: SubscriptionForecastSku[]): SubscriptionForecastTotals;

package/dist/inventory/subscriptionForecastCalculation.js

@@ -0,0 +1,133 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function calculateSubscriptionForecastSkus(input) {
+    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([
+        ...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((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, skus) {
+    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) {
+    let available = input.sellableNow;
+    let shortageDate = null;
+    let horizonMissingQty = 0;
+    let protectionMissingQty = 0;
+    const events = [
+        ...input.supply.map((line) => ({
+            type: "supply",
+            at: line.expectedAt,
+            quantity: line.quantity,
+        })),
+        ...input.demand.map((line) => ({
+            type: "demand",
+            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, dueAtOrBeforeMs) {
+    return sum(lines
+        .filter((line) => Date.parse(line.dueAt) <= dueAtOrBeforeMs)
+        .map((line) => line.quantity));
+}
+function sum(values) {
+    return values.reduce((total, value) => total + value, 0);
+}

package/dist/pricing/acquisitionFinancialPolicy.d.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/dist/pricing/acquisitionFinancialPolicy.js

@@ -0,0 +1 @@
+export {};

package/dist/pricing/acquisitionOfferPricing.d.ts

@@ -0,0 +1,27 @@
+import { type CommerceOfferPricingDeps } from "./commerceOfferPricing.js";
+import { 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";
+export declare function acquisitionProjectionFreshness(acquisitionTerms: AcquisitionTerms, observedAt: string, nextBoundaryAt?: string | null): {
+    acquisitionTerms: {
+        initialDiscountBps: number;
+        effectiveFrom: string;
+        effectiveTo: string | null;
+        schemaVersion: "subscription-acquisition.v1";
+        revision: string;
+        delivery2DiscountBps: number;
+    };
+    observedAt: string;
+    validUntil: string;
+};
+/** Explicit opt-in projection; the incumbent projector receives no new defaults. */
+export declare 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>>;

package/dist/pricing/acquisitionOfferPricing.js

@@ -0,0 +1,25 @@
+import { projectCommerceOfferPricing } from "./commerceOfferPricing.js";
+import { COMMERCE_OFFER_PRICING_V2_CONTRACT_VERSION, COMMERCE_OFFER_PRICING_V3_CONTRACT_VERSION } from "./contracts/offer.js";
+import { ACQUISITION_TERMS_CAPABILITY } from "./contracts/acquisitionTerms.js";
+import { ACQUISITION_PROJECTION_MAX_AGE_MS, acquisitionProjectionFreshnessSchema } from "./acquisitionOfferPricingSchemas.js";
+export function acquisitionProjectionFreshness(acquisitionTerms, observedAt, nextBoundaryAt) {
+    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(input) {
+    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 };
+}

package/dist/pricing/acquisitionOfferPricingHandler.d.ts

@@ -0,0 +1,20 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { z } from "zod";
+import { type AcquisitionOfferPricingResponse, type CommerceOfferPricingResponse } from "./contracts/offer.js";
+import type { AcquisitionCapability } from "./contracts/acquisitionTerms.js";
+import type { PricingPolicyRequest, PricingPolicySnapshot } from "./contracts/offerPolicy.js";
+export declare const ACQUISITION_CAPABILITY_HEADER = "x-commerce-acquisition-capability";
+export interface AcquisitionOfferPricingHandlerDeps {
+    responder: BffResponder;
+    commerceOfferPricingResponseSchema: z.ZodType<AcquisitionOfferPricingResponse | CommerceOfferPricingResponse>;
+    incumbentHandler(req: HttpRequest, res: HttpResponse): Promise<void>;
+    readOfferPricing(pricingPolicy?: PricingPolicySnapshot, acquisitionCapability?: AcquisitionCapability): Promise<AcquisitionOfferPricingResponse | CommerceOfferPricingResponse>;
+    requirePricingPolicy?: boolean;
+    resolvePricingPolicy?(request: {
+        visitorId: string;
+        pricingPolicy: PricingPolicyRequest;
+    }): PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+}
+export declare function createAcquisitionOfferPricingHandler({ responder, commerceOfferPricingResponseSchema, incumbentHandler, readOfferPricing, resolvePricingPolicy, requirePricingPolicy, }: AcquisitionOfferPricingHandlerDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function readAcquisitionCapability(req: HttpRequest): AcquisitionCapability | undefined | null;