@endora-commerce/contracts 0.100.0

package/dist/inventory.d.ts

@@ -0,0 +1,673 @@
+import { z } from 'zod';
+import type { BulkImportReport } from './import-export.js';
+/**
+ * Inventory module contracts — feature 010 multi-warehouse rewrite.
+ * Source of truth per Constitution Principle V; the backend re-uses
+ * these schemas as route validators and the frontends consume the
+ * inferred TS types.
+ *
+ * See specs/010-inventory-module/contracts/ for the HTTP contract docs.
+ *
+ * Foundation 001 schemas (`stockLevelSchema`, `adjustStockRequestSchema`,
+ * `availabilityNotificationRequestSchema`) are preserved at the bottom
+ * of the file for backward compatibility with the existing admin
+ * inventory routes; new code should consume the feature-010 schemas.
+ */
+export declare const warehouseAddressSchema: z.ZodObject<{
+    street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type WarehouseAddress = z.infer<typeof warehouseAddressSchema>;
+export declare const warehouseContactSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type WarehouseContact = z.infer<typeof warehouseContactSchema>;
+export declare const warehouseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    code: z.ZodString;
+    active: z.ZodBoolean;
+    description: z.ZodNullable<z.ZodString>;
+    address: z.ZodNullable<z.ZodObject<{
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    contact: z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    defaultLowStockThreshold: z.ZodNullable<z.ZodNumber>;
+    totals: z.ZodOptional<z.ZodObject<{
+        products: z.ZodNumber;
+        onHand: z.ZodNumber;
+        isDefaultForChannelCount: z.ZodNumber;
+    }, z.core.$strip>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type Warehouse = z.infer<typeof warehouseSchema>;
+export declare const createWarehouseRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    code: z.ZodString;
+    active: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    address: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    contact: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    defaultLowStockThreshold: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export type CreateWarehouseRequest = z.infer<typeof createWarehouseRequestSchema>;
+export declare const updateWarehouseRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    address: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        street: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        postalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        countryCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    contact: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    defaultLowStockThreshold: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strict>;
+export type UpdateWarehouseRequest = z.infer<typeof updateWarehouseRequestSchema>;
+export declare const warehouseChannelAssignmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    warehouseId: z.ZodString;
+    warehouseName: z.ZodString;
+    warehouseCode: z.ZodString;
+    isDefault: z.ZodBoolean;
+    sortOrder: z.ZodNumber;
+    assignedAt: z.ZodString;
+}, z.core.$strip>;
+export type WarehouseChannelAssignment = z.infer<typeof warehouseChannelAssignmentSchema>;
+export declare const assignWarehouseToChannelRequestSchema: z.ZodObject<{
+    warehouseId: z.ZodString;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    sortOrder: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AssignWarehouseToChannelRequest = z.infer<typeof assignWarehouseToChannelRequestSchema>;
+export declare const patchWarehouseChannelAssignmentRequestSchema: z.ZodObject<{
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    sortOrder: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type PatchWarehouseChannelAssignmentRequest = z.infer<typeof patchWarehouseChannelAssignmentRequestSchema>;
+export declare const inventoryLandingKpisSchema: z.ZodObject<{
+    totalProductsTracked: z.ZodNumber;
+    totalOnHand: z.ZodNumber;
+    outOfStockCount: z.ZodNumber;
+    lowStockCount: z.ZodNumber;
+    perWarehouseTotals: z.ZodArray<z.ZodObject<{
+        warehouseId: z.ZodString;
+        warehouseCode: z.ZodString;
+        onHand: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InventoryLandingKpis = z.infer<typeof inventoryLandingKpisSchema>;
+export declare const stockDisplayBandSchema: z.ZodEnum<{
+    available: "available";
+    out_of_stock: "out_of_stock";
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+export type StockDisplayBand = z.infer<typeof stockDisplayBandSchema>;
+export declare const stockLevelRowSchema: z.ZodObject<{
+    productId: z.ZodString;
+    productSku: z.ZodString;
+    productName: z.ZodString;
+    manageStock: z.ZodBoolean;
+    backorderEnabled: z.ZodBoolean;
+    lowStockThreshold: z.ZodNullable<z.ZodNumber>;
+    lowStockThresholdMode: z.ZodEnum<{
+        cumulative: "cumulative";
+        per_warehouse: "per_warehouse";
+    }>;
+    perWarehouse: z.ZodArray<z.ZodObject<{
+        warehouseId: z.ZodString;
+        warehouseCode: z.ZodString;
+        onHand: z.ZodNumber;
+        reserved: z.ZodNumber;
+        lowStockThreshold: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    cumulativeOnHand: z.ZodNumber;
+    displayBand: z.ZodEnum<{
+        available: "available";
+        out_of_stock: "out_of_stock";
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    isLowStock: z.ZodBoolean;
+    isOutOfStock: z.ZodBoolean;
+}, z.core.$strip>;
+export type StockLevelRow = z.infer<typeof stockLevelRowSchema>;
+/**
+ * Bulk replace per-warehouse low-stock thresholds for one product.
+ * The submitted set is the new truth: any (product, warehouse) row not
+ * mentioned here is deleted. Pass `threshold: null` in an entry to
+ * delete that single entry while keeping others.
+ */
+export declare const setProductWarehouseLowStockThresholdsRequestSchema: z.ZodObject<{
+    productId: z.ZodString;
+    thresholds: z.ZodArray<z.ZodObject<{
+        warehouseId: z.ZodString;
+        threshold: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SetProductWarehouseLowStockThresholdsRequest = z.infer<typeof setProductWarehouseLowStockThresholdsRequestSchema>;
+export declare const setStockLevelRequestSchema: z.ZodObject<{
+    productId: z.ZodString;
+    warehouseId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    onHand: z.ZodNumber;
+}, z.core.$strip>;
+export type SetStockLevelRequest = z.infer<typeof setStockLevelRequestSchema>;
+export declare const inventoryDisplayModeSchema: z.ZodEnum<{
+    exact: "exact";
+    band: "band";
+    available_or_not: "available_or_not";
+}>;
+export type InventoryDisplayMode = z.infer<typeof inventoryDisplayModeSchema>;
+export declare const thresholdTripleSchema: z.ZodObject<{
+    high: z.ZodNullable<z.ZodNumber>;
+    medium: z.ZodNullable<z.ZodNumber>;
+    low: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type ThresholdTriple = z.infer<typeof thresholdTripleSchema>;
+export declare const inventoryThresholdsSchema: z.ZodObject<{
+    global: z.ZodObject<{
+        high: z.ZodNullable<z.ZodNumber>;
+        medium: z.ZodNullable<z.ZodNumber>;
+        low: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    perCategory: z.ZodArray<z.ZodObject<{
+        categoryId: z.ZodString;
+        high: z.ZodNullable<z.ZodNumber>;
+        medium: z.ZodNullable<z.ZodNumber>;
+        low: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    perProduct: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        high: z.ZodNullable<z.ZodNumber>;
+        medium: z.ZodNullable<z.ZodNumber>;
+        low: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InventoryThresholds = z.infer<typeof inventoryThresholdsSchema>;
+export declare const patchInventoryThresholdsRequestSchema: z.ZodObject<{
+    global: z.ZodOptional<z.ZodObject<{
+        high: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        medium: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        low: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    perCategory: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        categoryId: z.ZodString;
+        high: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        medium: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        low: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    perProduct: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        high: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        medium: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        low: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+}, z.core.$strict>;
+export type PatchInventoryThresholdsRequest = z.infer<typeof patchInventoryThresholdsRequestSchema>;
+export declare const storefrontProductStockSchema: z.ZodObject<{
+    productId: z.ZodString;
+    manageStock: z.ZodBoolean;
+    backorderEnabled: z.ZodBoolean;
+    displayMode: z.ZodEnum<{
+        exact: "exact";
+        band: "band";
+        available_or_not: "available_or_not";
+    }>;
+    displayBand: z.ZodEnum<{
+        available: "available";
+        out_of_stock: "out_of_stock";
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    exactOnHand: z.ZodNullable<z.ZodNumber>;
+    isOutOfStock: z.ZodBoolean;
+    showNotifyButton: z.ZodBoolean;
+}, z.core.$strip>;
+export type StorefrontProductStock = z.infer<typeof storefrontProductStockSchema>;
+export declare const availabilityNotificationStatusSchema: z.ZodEnum<{
+    cancelled: "cancelled";
+    queued: "queued";
+    notified: "notified";
+}>;
+export type AvailabilityNotificationStatus = z.infer<typeof availabilityNotificationStatusSchema>;
+export declare const availabilityNotificationSchema: z.ZodObject<{
+    id: z.ZodString;
+    productId: z.ZodString;
+    productName: z.ZodOptional<z.ZodString>;
+    productSku: z.ZodOptional<z.ZodString>;
+    customerAccountId: z.ZodNullable<z.ZodString>;
+    email: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        queued: "queued";
+        notified: "notified";
+    }>;
+    queuedAt: z.ZodString;
+    notifiedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AvailabilityNotification = z.infer<typeof availabilityNotificationSchema>;
+export declare const subscribeAvailabilityNotificationRequestSchema: z.ZodObject<{
+    productId: z.ZodString;
+    email: z.ZodString;
+}, z.core.$strip>;
+export type SubscribeAvailabilityNotificationRequest = z.infer<typeof subscribeAvailabilityNotificationRequestSchema>;
+export declare const patchAvailabilityNotificationRequestSchema: z.ZodObject<{
+    status: z.ZodLiteral<"cancelled">;
+}, z.core.$strip>;
+export type PatchAvailabilityNotificationRequest = z.infer<typeof patchAvailabilityNotificationRequestSchema>;
+export declare const fulfilmentStrategySchema: z.ZodEnum<{
+    any: "any";
+    default_first: "default_first";
+    lowest_stock_first: "lowest_stock_first";
+    highest_stock_first: "highest_stock_first";
+    defined_order: "defined_order";
+}>;
+export type FulfilmentStrategy = z.infer<typeof fulfilmentStrategySchema>;
+export declare const stockImportErrorSchema: z.ZodObject<{
+    row: z.ZodNumber;
+    sku: z.ZodString;
+    reason: z.ZodEnum<{
+        product_not_found: "product_not_found";
+        invalid_quantity: "invalid_quantity";
+        malformed_row: "malformed_row";
+    }>;
+}, z.core.$strip>;
+export type StockImportError = z.infer<typeof stockImportErrorSchema>;
+export declare const stockImportResultSchema: z.ZodObject<{
+    rowsRead: z.ZodNumber;
+    rowsApplied: z.ZodNumber;
+    rowsSkipped: z.ZodNumber;
+    errors: z.ZodArray<z.ZodObject<{
+        row: z.ZodNumber;
+        sku: z.ZodString;
+        reason: z.ZodEnum<{
+            product_not_found: "product_not_found";
+            invalid_quantity: "invalid_quantity";
+            malformed_row: "malformed_row";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StockImportResult = z.infer<typeof stockImportResultSchema>;
+export declare const stockLevelSchema: z.ZodObject<{
+    id: z.ZodString;
+    productId: z.ZodString;
+    variantId: z.ZodNullable<z.ZodString>;
+    onHand: z.ZodNumber;
+    reserved: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type StockLevel = z.infer<typeof stockLevelSchema>;
+export declare const adjustStockRequestSchema: z.ZodObject<{
+    productId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    delta: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AdjustStockRequest = z.infer<typeof adjustStockRequestSchema>;
+export declare const availabilityNotificationRequestSchema: z.ZodObject<{
+    variantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AvailabilityNotificationRequest = z.infer<typeof availabilityNotificationRequestSchema>;
+/**
+ * The deterministic id of the warehouse every install seeds.
+ *
+ * Published as a **constant, not a port** (FR-013): switching `inventory` off
+ * does not change what the seeded id is, and `orders` compares against it when
+ * a line names no warehouse.
+ */
+export declare const DEFAULT_WAREHOUSE_ID = "00000000-0000-4000-8000-00000000d017";
+/**
+ * A warehouse as it crosses a module boundary — never the ORM entity.
+ *
+ * `address` reuses {@link WarehouseAddress}, declared above for the HTTP
+ * surface: the column stores exactly that JSONB shape, so a second
+ * declaration would be two names for one blob.
+ */
+export interface WarehouseRecord {
+    id: string;
+    name: string;
+    code: string;
+    active: boolean;
+    description: string | null;
+    address: WarehouseAddress | null;
+    contactName: string | null;
+    contactEmail: string | null;
+    contactPhone: string | null;
+    defaultLowStockThreshold: number | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** One product's stock in one warehouse. `available` is `onHand - reserved`. */
+export interface StockLevelRecord {
+    id: string;
+    productId: string;
+    variantId: string | null;
+    warehouseId: string;
+    onHand: number;
+    reserved: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * One **active** warehouse bound to a sales channel, in the order placement
+ * walks them. See {@link InventoryStockReadPort.listChannelWarehouses}.
+ */
+export interface ChannelWarehouse {
+    warehouseId: string;
+    warehouseCode: string;
+    isDefault: boolean;
+}
+/** Which warehouses serve which sales channel, and in what order. */
+export interface WarehouseChannelAssignmentRecord {
+    id: string;
+    warehouseId: string;
+    salesChannelId: string;
+    isDefault: boolean;
+    sortOrder: number;
+    createdAt: Date;
+}
+/**
+ * Container name: `inventoryStockReadPort`. Owner: `inventory`.
+ *
+ * `orders` reads stock at placement to pick warehouses, and `import_export`
+ * reads it to export a stock sheet. Both reach the `StockLevel` entity today,
+ * and `orders` does so through a **dynamic** import inside a method body —
+ * invisible to a reviewer scanning the import block, which is why the boundary
+ * check was taught to see one.
+ *
+ * `candidatesFor` answers the question `orders` actually asks: which
+ * warehouses can serve this line on this channel, with how much available,
+ * already shaped for {@link resolveAllocations}. Assembling that from three
+ * tables is this module's business, and it was being assembled in `orders`.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `inventory` has an off state at all is its manifest's
+ * `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface InventoryStockReadPort {
+    listStockForProducts(productIds: readonly string[], options?: {
+        warehouseId?: string;
+    }): Promise<StockLevelRecord[]>;
+    listWarehouses(options?: {
+        activeOnly?: boolean;
+    }): Promise<WarehouseRecord[]>;
+    listChannelAssignments(salesChannelId: string): Promise<WarehouseChannelAssignmentRecord[]>;
+    /**
+     * The **active** warehouses bound to a channel, joined with their codes and
+     * ordered the way placement walks them: `isDefault desc, sortOrder asc,
+     * createdAt asc`. When the channel has no active warehouse bound, this
+     * answers the seeded default warehouse — the fallback lives here rather than
+     * in the caller, which is where it used to be spelled out of a UUID constant
+     * copied from `warehouse.entity.ts` (D-94.4).
+     *
+     * Not a widening of {@link listChannelAssignments}: that one has a different
+     * ordering and a different consumer, and both should keep saying what they
+     * mean.
+     *
+     * **`candidatesFor` is not the method for the placement call site**, and the
+     * distinction matters more than it looks. `candidatesFor` computes
+     * availability through this module's own `EntityManager`, so it neither
+     * takes nor holds the `PESSIMISTIC_WRITE` on `stock_levels` that stops two
+     * concurrent placements allocating the same unit
+     * (`test/contract/orders/place-stock-race.test.ts`). Placement therefore
+     * takes the channel → warehouse binding from here and reads and locks the
+     * stock rows itself, on its own transaction.
+     */
+    listChannelWarehouses(salesChannelId: string): Promise<ChannelWarehouse[]>;
+    /**
+     * Candidate warehouses for one product line on one channel, ordered by
+     * warehouse code, with `available = onHand - reserved`. An empty answer
+     * means the line cannot be allocated anywhere, which is not the same as an
+     * error.
+     *
+     * Read outside any caller's transaction — see the warning on
+     * {@link listChannelWarehouses}.
+     */
+    candidatesFor(input: {
+        productId: string;
+        variantId?: string | null;
+        salesChannelId: string | null;
+    }): Promise<CandidateWarehouse[]>;
+}
+/**
+ * One row of a stock-level import.
+ *
+ * `productSku` rather than a product id: a spreadsheet addresses a product the
+ * way an operator does, and resolving it is this module's business because it
+ * is this module that decides a row addressing nothing is a rejected row.
+ * `variantId` absent or `null` addresses the simple-product baseline level.
+ *
+ * The row names no warehouse by default. The import applies to the seeded
+ * default one — the behaviour the CSV path has always had. Integrations that
+ * address a specific warehouse (for example ERP stock sync) may set
+ * `warehouseCode` to the warehouse's unique `code`.
+ */
+export interface StockLevelImportRow {
+    productSku: string;
+    variantId?: string | null;
+    onHand: number;
+    warehouseCode?: string;
+}
+/**
+ * Container name: `inventoryStockImportPort`. Owner: `inventory`.
+ *
+ * All-or-nothing per call, one audit row — the same contract `catalog`'s bulk
+ * import port carries, and for the same reason. With `inventory` off the call answers 503
+ * `MODULE_DISABLED`; the caller is expected to decide presence before offering
+ * the surface at all.
+ */
+export interface InventoryStockImportPort {
+    importStockLevels(rows: readonly StockLevelImportRow[]): Promise<BulkImportReport>;
+}
+/** How many `(product, warehouse)` thresholds the copy wrote. */
+export interface ProductThresholdCopyResult {
+    copied: number;
+}
+/**
+ * Container name: `inventoryProductThresholdWritePort`. Owner: `inventory`.
+ *
+ * Issue #185. `catalog` duplicates a product and carries the source's
+ * per-warehouse low-stock thresholds over to the copy — with an
+ * `insert … select` against `product_warehouse_low_stock_thresholds`, a table
+ * this module owns and this module's migration creates. Four things were absent
+ * from that statement at once: no import specifier, so the boundary check could
+ * not see it; no gate, so the write proceeded with this module switched off; no
+ * declared edge; and no audit row on this side, so rows appeared here with
+ * nothing here having decided they should.
+ *
+ * The copy is therefore published rather than ledgered. It runs as one Command
+ * on **this module's own transaction**, not the caller's: the duplication
+ * commits its product row before it asks, an alerting profile is an indication
+ * on a product rather than part of what makes one, and a duplicate that lost
+ * its thresholds is exactly the duplicate an operator gets when this module was
+ * never installed. Rolling a whole duplication back over it would be the wrong
+ * trade in the other direction.
+ *
+ * **Owner off:** `catalog` declares this name `degrades-without` and decides
+ * presence in front of the gate, so a duplicate made while this module is off
+ * carries no per-warehouse thresholds and the duplication itself succeeds. The
+ * gate `providePort` wraps this in stays real for any caller that forgets.
+ */
+export interface InventoryProductThresholdWritePort {
+    /**
+     * Copy every `(warehouse, threshold)` the source product carries onto the
+     * target, overwriting a row the target already holds for the same warehouse.
+     * A source with no thresholds answers `{ copied: 0 }` and records nothing —
+     * the same rule the channel-membership service applies to an idempotent add.
+     */
+    copyProductWarehouseThresholds(input: {
+        sourceProductId: string;
+        targetProductId: string;
+    }): Promise<ProductThresholdCopyResult>;
+}
+export interface FulfilmentLayer {
+    strategy: FulfilmentStrategy | null | undefined;
+    warehouseOrder: string[] | null | undefined;
+}
+export interface EffectiveFulfilment {
+    strategy: FulfilmentStrategy;
+    warehouseOrder: string[];
+}
+/**
+ * Effective fulfilment-strategy resolver (feature 010).
+ *
+ * The warehouse-picking strategy used to reserve stock at order placement is
+ * configurable at three levels, resolved with precedence:
+ *
+ *   Product > Organization > Sales Channel (setting) > platform default
+ *
+ * Product and organisation each contribute an optional override layer; the
+ * sales-channel layer, and the platform default behind it, are resolved
+ * upstream by the settings module and arrive already collapsed into
+ * `channelDefault`. The first layer with a non-null `strategy` wins and
+ * supplies **both** its `strategy` and its `warehouseOrder` — the warehouse
+ * walk for `defined_order` never mixes across layers.
+ */
+export declare function resolveEffectiveFulfilmentStrategy(product: FulfilmentLayer, organization: FulfilmentLayer, channelDefault: EffectiveFulfilment): EffectiveFulfilment;
+export interface CandidateWarehouse {
+    warehouseId: string;
+    warehouseCode: string;
+    /** `onHand - reserved`. */
+    available: number;
+    isDefault: boolean;
+}
+export interface AllocationDecision {
+    warehouseId: string;
+    quantity: number;
+    /**
+     * True when this allocation is going through with insufficient stock
+     * because the product has `backorderEnabled = true`.
+     */
+    isBackorder: boolean;
+}
+export interface ResolveAllocationsInput {
+    quantity: number;
+    candidateWarehouses: CandidateWarehouse[];
+    strategy: FulfilmentStrategy;
+    /** When `defined_order`, the configured warehouse-id list to walk. */
+    warehouseOrder?: string[];
+    /**
+     * When the product allows backorder, lines that cannot be fully fulfilled
+     * still go through; the unfulfilled remainder is flagged as a backorder
+     * against the first-choice warehouse.
+     */
+    backorderEnabled: boolean;
+}
+export type AllocationOutcome = {
+    ok: true;
+    allocations: AllocationDecision[];
+} | {
+    ok: false;
+    reason: 'insufficient_stock';
+};
+/**
+ * Fulfilment-strategy resolver (feature 010 / FR-029…FR-033, research §R4).
+ *
+ * Picks a list of `(warehouseId, quantity)` allocations for a single order
+ * line given the available candidate warehouses and the resolved strategy.
+ * Tie-break on equal `available` quantities is warehouse-code lexical order —
+ * deterministic and documented.
+ *
+ * Of the five strategies only `default_first` **splits** a line across
+ * warehouses; the others pick a single warehouse per line and refuse the line
+ * if that warehouse cannot fully satisfy the requested quantity.
+ */
+export declare function resolveAllocations(input: ResolveAllocationsInput): AllocationOutcome;
+/**
+ * Container name: `inventoryFulfilmentPlanningPort`. Owner: `inventory`.
+ *
+ * The warehouse-picking **policy** placement runs, published (D-94.4).
+ *
+ * `orders` used to reach both halves through `await import(
+ * '../../inventory/services/…')` inside the placement method body: a dynamic
+ * import, invisible to a reviewer scanning the import block, of the rules that
+ * decide which warehouse serves a line. Publishing them stops the policy being
+ * something `orders` can re-implement by editing an import.
+ *
+ * Two methods and not two more on {@link InventoryStockReadPort}: a *read*
+ * port that also decides policy makes its own name a lie. Both are **pure over
+ * their arguments** — no `EntityManager`, no table, no clock — so the contract
+ * stays FR-034-clean and the caller may run them inside its own transaction
+ * without the owner ever touching it.
+ */
+export interface InventoryFulfilmentPlanningPort {
+    /**
+     * Product > Organization > Sales Channel (already collapsed into
+     * `channelDefault`) > platform default. See
+     * {@link resolveEffectiveFulfilmentStrategy}.
+     */
+    resolveEffectiveStrategy(product: FulfilmentLayer, organization: FulfilmentLayer, channelDefault: EffectiveFulfilment): EffectiveFulfilment;
+    /**
+     * One line's allocation plan over the candidate warehouses the caller has
+     * already read **and locked**. See {@link resolveAllocations}.
+     */
+    planAllocations(input: ResolveAllocationsInput): AllocationOutcome;
+}
+/**
+ * Container name: `inventoryAvailabilityPort`. Owner: `inventory`.
+ *
+ * One product's display band and its channel-public in-stock flag, in batch,
+ * for a caller that is projecting a catalogue outward — `catalog`'s external
+ * product surface and `product_feeds`' generation pipeline.
+ *
+ * Cumulative on-hand across the warehouses the sales channel is served from,
+ * mapped through the product / category / global threshold chain. A product
+ * with no stock rows still gets an entry: `out_of_stock`, or `available` when
+ * stock is not managed for it. That is what makes the result usable as a map —
+ * a caller can tell "no stock" from "not asked about".
+ *
+ * The shape was declared inline in a composition root's local type and in this
+ * module's own cradle, twice, and the `providePort` call carried no type
+ * argument at all — so a consumer resolving it had nothing to name and
+ * `check:port-shape` had nothing to compare the registration to. Published in
+ * `specs/110-instance-repository/` T118c, when the first consumer stopped being
+ * a root.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. `catalog` declares this edge `degrades-without` and decides
+ * presence in front of the gate, which is a consumer's judgement about its own
+ * surface and not a property of this port; `product_feeds` binds it, because a
+ * feed whose availability column is silently absent is worse than a run that
+ * stops and records why.
+ */
+export interface InventoryAvailabilityPort {
+    resolveAvailabilityBands(productIds: string[], salesChannelId: string): Promise<Map<string, {
+        band: StockDisplayBand;
+        inStock: boolean;
+    }>>;
+}
+//# sourceMappingURL=inventory.d.ts.map

package/dist/inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../src/inventory.ts"],"names":[],"mappings":"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"}