@open-mercato/core 0.6.7-develop.6669.1.40b669666b → 0.6.7-develop.6670.1.4efa7961c6

package/src/modules/wms/lib/lowStockBalanceFilter.ts

@@ -0,0 +1,74 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+export type LowStockBalanceFilterMode = 'belowReorder' | 'belowSafety'
+
+type LowStockScope = {
+  organizationId: string
+  tenantId: string
+  warehouseId?: string | null
+}
+
+export async function resolveLowStockVariantIds(
+  em: EntityManager,
+  scope: LowStockScope,
+  mode: LowStockBalanceFilterMode,
+): Promise<string[]> {
+  const params: unknown[] = [scope.organizationId, scope.tenantId]
+  let warehouseJoin = ''
+  if (scope.warehouseId) {
+    warehouseJoin = ' and b.warehouse_id = ?'
+    params.push(scope.warehouseId)
+  }
+
+  const thresholdExpr =
+    mode === 'belowSafety'
+      ? 'coalesce(p.safety_stock, 0)'
+      : 'coalesce(p.reorder_point, 0)'
+
+  const thresholdGuard =
+    mode === 'belowSafety'
+      ? 'coalesce(p.safety_stock, 0) > 0'
+      : '(coalesce(p.reorder_point, 0) > 0 or coalesce(p.safety_stock, 0) > 0)'
+
+  params.push(scope.organizationId, scope.tenantId)
+
+  const sql = `
+    select distinct p.catalog_variant_id as catalog_variant_id
+    from wms_product_inventory_profiles p
+    join (
+      select
+        b.catalog_variant_id,
+        b.warehouse_id,
+        sum(
+          coalesce(b.quantity_on_hand, 0)
+          - coalesce(b.quantity_reserved, 0)
+          - coalesce(b.quantity_allocated, 0)
+        ) as available
+      from wms_inventory_balances b
+      where b.organization_id = ?
+        and b.tenant_id = ?
+        and b.deleted_at is null
+        ${warehouseJoin}
+      group by b.catalog_variant_id, b.warehouse_id
+    ) availability
+      on availability.catalog_variant_id = p.catalog_variant_id
+    where p.organization_id = ?
+      and p.tenant_id = ?
+      and p.deleted_at is null
+      and p.catalog_variant_id is not null
+      and ${thresholdGuard}
+      and availability.available <= ${thresholdExpr}
+  `
+
+  const rows = await em.getConnection().execute<Array<{ catalog_variant_id: string }>>(sql, params)
+  return rows
+    .map((row) => row.catalog_variant_id?.trim())
+    .filter((value): value is string => Boolean(value))
+}
+
+/** Sentinel UUID that never matches a real entity — forces zero results when a low-stock filter returns an empty variant set. */
+const NO_MATCH_UUID = '00000000-0000-4000-8000-000000000000'
+
+export function formatLowStockVariantIdsForFilter(variantIds: string[]): string[] {
+  return variantIds.length > 0 ? variantIds : [NO_MATCH_UUID]
+}

package/src/modules/wms/lib/primaryWarehousePolicy.ts

@@ -0,0 +1,46 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Warehouse } from '../data/entities'
+
+type Scope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type WarehouseAvailability = {
+  warehouseId: string
+  available: number
+}
+
+export async function resolvePrimaryWarehouseId(
+  em: EntityManager,
+  scope: Scope,
+): Promise<string | null> {
+  const warehouse = await findOneWithDecryption(
+    em,
+    Warehouse,
+    {
+      organizationId: scope.organizationId,
+      isPrimary: true,
+      isActive: true,
+      deletedAt: null,
+    },
+    undefined,
+    scope,
+  )
+  return warehouse?.id ?? null
+}
+
+export function sortWarehouseAvailabilityForReservation(
+  warehouses: WarehouseAvailability[],
+  primaryWarehouseId: string | null,
+): WarehouseAvailability[] {
+  return [...warehouses].sort((left, right) => {
+    if (primaryWarehouseId) {
+      const leftPrimary = left.warehouseId === primaryWarehouseId ? 1 : 0
+      const rightPrimary = right.warehouseId === primaryWarehouseId ? 1 : 0
+      if (leftPrimary !== rightPrimary) return rightPrimary - leftPrimary
+    }
+    return right.available - left.available
+  })
+}

package/src/modules/wms/lib/roleFeatures.ts

@@ -0,0 +1,32 @@
+/**
+ * Reserved tenant role names seeded by WMS `setup.ts` via `ensureRoles`.
+ * Other modules MUST NOT reuse `operator` or `supervisor` without coordinating ACL grants and i18n labels.
+ */
+export const WMS_OPERATOR_ROLE = 'operator' as const
+export const WMS_SUPERVISOR_ROLE = 'supervisor' as const
+
+export const WMS_CUSTOM_ROLE_NAMES = [WMS_OPERATOR_ROLE, WMS_SUPERVISOR_ROLE] as const
+
+export const WMS_OPERATOR_FEATURES = [
+  'wms.view',
+  'wms.adjust_inventory',
+  'wms.receive_inventory',
+  'wms.cycle_count',
+] as const
+
+export const WMS_MANAGE_FEATURES = [
+  'wms.manage_warehouses',
+  'wms.manage_zones',
+  'wms.manage_locations',
+  'wms.manage_inventory',
+  'wms.manage_reservations',
+] as const
+
+export const WMS_SUPERVISOR_FEATURES = [
+  ...WMS_OPERATOR_FEATURES,
+  'wms.import',
+  ...WMS_MANAGE_FEATURES,
+] as const
+
+export type WmsOperatorFeature = (typeof WMS_OPERATOR_FEATURES)[number]
+export type WmsSupervisorFeature = (typeof WMS_SUPERVISOR_FEATURES)[number]

package/src/modules/wms/lib/salesOrderInventoryAutomation.ts

@@ -0,0 +1,390 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { FeatureTogglesService } from '@open-mercato/core/modules/feature_toggles/lib/feature-flag-check'
+import type { QueryEngine } from '@open-mercato/shared/lib/query/types'
+import { E } from '#generated/entities.ids.generated'
+import { InventoryBalance, InventoryReservation } from '../data/entities'
+import { emitWmsEvent } from '../events'
+import { loadExplicitWarehouseIdForOrder } from './salesOrderWarehouseAssignment'
+import {
+  resolvePrimaryWarehouseId,
+  sortWarehouseAvailabilityForReservation,
+  type WarehouseAvailability,
+} from './primaryWarehousePolicy'
+import { resolveWmsIntegrationToggleEnabled } from './wmsIntegrationToggles'
+
+type EventContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+type SalesOrderLifecyclePayload = {
+  orderId?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+}
+
+type Scope = {
+  tenantId: string
+  organizationId: string
+}
+
+type ReservationShortfallLine = {
+  catalogVariantId: string
+  requiredQuantity: number
+  reservedQuantity: number
+  shortfallQuantity: number
+}
+
+function isInsufficientStockError(error: unknown): boolean {
+  return error instanceof CrudHttpError && error.status === 409 && error.body?.error === 'insufficient_stock'
+}
+
+function isBalanceIntegrityViolationError(error: unknown): boolean {
+  return error instanceof CrudHttpError && error.status === 409 && error.body?.error === 'balance_integrity_violation'
+}
+
+type SalesOrderRow = {
+  id?: string
+  order_number?: string | null
+  tenant_id?: string | null
+  organization_id?: string | null
+}
+
+type SalesOrderLineRow = {
+  id?: string
+  kind?: string | null
+  product_variant_id?: string | null
+  quantity?: string | number | null
+  line_number?: number | null
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim().length > 0) {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return 0
+}
+
+function getWarehouseId(balance: InventoryBalance): string | null {
+  const relation = balance.warehouse as { id?: string } | string | undefined
+  if (typeof relation === 'string') return relation
+  return typeof relation?.id === 'string' ? relation.id : null
+}
+
+function buildCommandContext(ctx: EventContext, scope: Scope): CommandRuntimeContext {
+  return {
+    container: {
+      resolve: ctx.resolve,
+    } as CommandRuntimeContext['container'],
+    auth: null,
+    organizationScope: null,
+    selectedOrganizationId: scope.organizationId,
+    organizationIds: [scope.organizationId],
+  }
+}
+
+async function isInventoryAutomationEnabled(ctx: EventContext, tenantId: string): Promise<boolean> {
+  try {
+    const featureTogglesService = ctx.resolve<FeatureTogglesService>('featureTogglesService')
+    const em = ctx.resolve<EntityManager>('em')
+    return resolveWmsIntegrationToggleEnabled(
+      featureTogglesService,
+      em,
+      'wms_integration_sales_order_inventory',
+      tenantId,
+    )
+  } catch {
+    return true
+  }
+}
+
+async function loadOrderViaQueryEngine(
+  ctx: EventContext,
+  orderId: string,
+  scope: Scope,
+): Promise<SalesOrderRow | null> {
+  // Read sales orders/lines via QueryEngine instead of importing the sales ORM
+  // entity classes — keeps the WMS module decoupled from sales internals.
+  // Sales mutations also flush their CRUD side effects synchronously through
+  // the command bus before this subscriber fires, so the query_index/base
+  // table is consistent at this point.
+  const queryEngine = ctx.resolve<QueryEngine>('queryEngine')
+  const result = await queryEngine.query<SalesOrderRow>(E.sales.sales_order, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    filters: { id: { $eq: orderId } },
+    fields: ['id', 'order_number', 'tenant_id', 'organization_id'],
+    page: { page: 1, pageSize: 1 },
+  })
+  return result.items[0] ?? null
+}
+
+async function loadOrderLinesViaQueryEngine(
+  ctx: EventContext,
+  orderId: string,
+  scope: Scope,
+): Promise<SalesOrderLineRow[]> {
+  const queryEngine = ctx.resolve<QueryEngine>('queryEngine')
+  const result = await queryEngine.query<SalesOrderLineRow>(E.sales.sales_order_line, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    filters: { order_id: { $eq: orderId } },
+    fields: ['id', 'kind', 'product_variant_id', 'quantity', 'line_number'],
+    sort: [{ field: 'line_number', dir: 'asc' as never }],
+    page: { page: 1, pageSize: 1000 },
+  })
+  return result.items
+}
+
+async function loadActiveReservations(
+  em: EntityManager,
+  orderId: string,
+  scope: Scope,
+): Promise<InventoryReservation[]> {
+  return findWithDecryption(
+    em,
+    InventoryReservation,
+    {
+      sourceType: 'order',
+      sourceId: orderId,
+      status: 'active',
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      deletedAt: null,
+    },
+    { orderBy: { createdAt: 'asc' } },
+    scope,
+  )
+}
+
+async function loadBalances(
+  em: EntityManager,
+  variantIds: string[],
+  scope: Scope,
+): Promise<InventoryBalance[]> {
+  if (variantIds.length === 0) return []
+  return findWithDecryption(
+    em,
+    InventoryBalance,
+    {
+      catalogVariantId: { $in: variantIds },
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    scope,
+  )
+}
+
+function buildRequiredQuantityByVariant(lines: SalesOrderLineRow[]): Map<string, number> {
+  const quantities = new Map<string, number>()
+  for (const line of lines) {
+    if (line.kind !== 'product' || !line.product_variant_id) continue
+    const quantity = toNumber(line.quantity)
+    if (quantity <= 0) continue
+    quantities.set(
+      line.product_variant_id,
+      (quantities.get(line.product_variant_id) ?? 0) + quantity,
+    )
+  }
+  return quantities
+}
+
+function buildReservedQuantityByVariant(reservations: InventoryReservation[]): Map<string, number> {
+  const quantities = new Map<string, number>()
+  for (const reservation of reservations) {
+    quantities.set(
+      reservation.catalogVariantId,
+      (quantities.get(reservation.catalogVariantId) ?? 0) + toNumber(reservation.quantity),
+    )
+  }
+  return quantities
+}
+
+function buildWarehouseAvailability(
+  balances: InventoryBalance[],
+): Map<string, WarehouseAvailability[]> {
+  const byVariant = new Map<string, Map<string, number>>()
+  for (const balance of balances) {
+    const warehouseId = getWarehouseId(balance)
+    if (!warehouseId) continue
+    const available =
+      toNumber(balance.quantityOnHand) -
+      toNumber(balance.quantityReserved) -
+      toNumber(balance.quantityAllocated)
+    if (available <= 0) continue
+
+    const warehouseMap = byVariant.get(balance.catalogVariantId) ?? new Map<string, number>()
+    warehouseMap.set(warehouseId, (warehouseMap.get(warehouseId) ?? 0) + available)
+    byVariant.set(balance.catalogVariantId, warehouseMap)
+  }
+
+  const result = new Map<string, WarehouseAvailability[]>()
+  for (const [variantId, warehouseMap] of byVariant.entries()) {
+    result.set(
+      variantId,
+      Array.from(warehouseMap.entries()).map(([warehouseId, available]) => ({ warehouseId, available })),
+    )
+  }
+  return result
+}
+
+export async function reserveInventoryForConfirmedOrder(
+  payload: SalesOrderLifecyclePayload,
+  ctx: EventContext,
+): Promise<void> {
+  if (!payload.orderId || !payload.tenantId || !payload.organizationId) return
+  if (!(await isInventoryAutomationEnabled(ctx, payload.tenantId))) return
+
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+  const em = ctx.resolve<EntityManager>('em').fork()
+  const commandBus = ctx.resolve<CommandBus>('commandBus')
+  const commandCtx = buildCommandContext(ctx, scope)
+  const order = await loadOrderViaQueryEngine(ctx, payload.orderId, scope)
+  if (!order || typeof order.id !== 'string') return
+
+  const orderId = order.id
+  const orderNumber = typeof order.order_number === 'string' ? order.order_number : null
+
+  const [lines, activeReservations] = await Promise.all([
+    loadOrderLinesViaQueryEngine(ctx, orderId, scope),
+    loadActiveReservations(em, orderId, scope),
+  ])
+  const requiredByVariant = buildRequiredQuantityByVariant(lines)
+  if (requiredByVariant.size === 0) return
+
+  const reservedByVariant = buildReservedQuantityByVariant(activeReservations)
+  const balances = await loadBalances(em, Array.from(requiredByVariant.keys()), scope)
+  const availabilityByVariant = buildWarehouseAvailability(balances)
+  const [primaryWarehouseId, assignedWarehouseId] = await Promise.all([
+    resolvePrimaryWarehouseId(em, scope),
+    loadExplicitWarehouseIdForOrder(em, orderId, scope),
+  ])
+  const preferredWarehouseId = assignedWarehouseId ?? primaryWarehouseId
+  const shortfalls: ReservationShortfallLine[] = []
+
+  for (const [variantId, requiredQuantity] of requiredByVariant.entries()) {
+    let remainingQuantity = requiredQuantity - (reservedByVariant.get(variantId) ?? 0)
+    if (remainingQuantity <= 0) continue
+
+    let variantBuckets = availabilityByVariant.get(variantId) ?? []
+    if (assignedWarehouseId) {
+      variantBuckets = variantBuckets.filter(
+        (bucket) => bucket.warehouseId === assignedWarehouseId,
+      )
+    }
+
+    const warehouseAvailability = sortWarehouseAvailabilityForReservation(
+      variantBuckets,
+      preferredWarehouseId,
+    )
+    let reservedForVariant = 0
+    try {
+      for (const bucket of warehouseAvailability) {
+        if (remainingQuantity <= 0) break
+        const reserveQuantity = Math.min(remainingQuantity, bucket.available)
+        if (reserveQuantity <= 0) continue
+
+        await commandBus.execute('wms.inventory.reserve', {
+          input: {
+            tenantId: scope.tenantId,
+            organizationId: scope.organizationId,
+            warehouseId: bucket.warehouseId,
+            catalogVariantId: variantId,
+            quantity: reserveQuantity,
+            sourceType: 'order',
+            sourceId: orderId,
+            metadata: {
+              automation: 'sales.order.confirmed',
+              orderId,
+              orderNumber,
+              catalogVariantId: variantId,
+            },
+          },
+          ctx: commandCtx,
+        })
+
+        remainingQuantity -= reserveQuantity
+        reservedForVariant += reserveQuantity
+        bucket.available -= reserveQuantity
+      }
+    } catch (error) {
+      if (!isInsufficientStockError(error)) throw error
+    }
+
+    if (remainingQuantity > 0.000001) {
+      shortfalls.push({
+        catalogVariantId: variantId,
+        requiredQuantity,
+        reservedQuantity: reservedForVariant + (reservedByVariant.get(variantId) ?? 0),
+        shortfallQuantity: remainingQuantity,
+      })
+    }
+  }
+
+  if (shortfalls.length > 0) {
+    await emitWmsEvent('wms.inventory.reservation_shortfall', {
+      id: orderId,
+      orderId,
+      orderNumber,
+      shortfalls,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+    })
+  }
+}
+
+export async function releaseInventoryForCancelledOrder(
+  payload: SalesOrderLifecyclePayload,
+  ctx: EventContext,
+): Promise<void> {
+  if (!payload.orderId || !payload.tenantId || !payload.organizationId) return
+  if (!(await isInventoryAutomationEnabled(ctx, payload.tenantId))) return
+
+  const scope: Scope = {
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  }
+  const em = ctx.resolve<EntityManager>('em').fork()
+  const commandBus = ctx.resolve<CommandBus>('commandBus')
+  const commandCtx = buildCommandContext(ctx, scope)
+  const activeReservations = await loadActiveReservations(em, payload.orderId, scope)
+
+  for (const reservation of activeReservations) {
+    try {
+      await commandBus.execute('wms.inventory.release', {
+        input: {
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          reservationId: reservation.id,
+          reason: 'sales.order.cancelled',
+          metadata: {
+            automation: 'sales.order.cancelled',
+            orderId: payload.orderId,
+          },
+        },
+        ctx: commandCtx,
+      })
+    } catch (error) {
+      if (!isBalanceIntegrityViolationError(error)) throw error
+      void emitWmsEvent('wms.inventory.balance_drift', {
+        id: reservation.id,
+        balanceId: reservation.id,
+        reservationId: reservation.id,
+        field: 'quantityReserved',
+        attemptedValue: null,
+        clampedValue: null,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+      }).catch(() => undefined)
+    }
+  }
+}

package/src/modules/wms/lib/salesOrderWarehouseAssignment.ts

@@ -0,0 +1,78 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { SalesOrderWarehouseAssignment, Warehouse } from '../data/entities'
+
+type Scope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type SalesOrderWarehouseAssignmentView = {
+  id: string
+  salesOrderId: string
+  warehouseId: string
+  warehouseName: string | null
+  warehouseCode: string | null
+  notes: string | null
+  assignedBy: string | null
+}
+
+function resolveWarehouseId(assignment: SalesOrderWarehouseAssignment): string | null {
+  const warehouseRel = assignment.warehouse as { id?: string } | undefined
+  return typeof warehouseRel?.id === 'string' ? warehouseRel.id : null
+}
+
+export async function loadExplicitWarehouseIdForOrder(
+  em: EntityManager,
+  salesOrderId: string,
+  scope: Scope,
+): Promise<string | null> {
+  const assignment = await findOneWithDecryption(
+    em,
+    SalesOrderWarehouseAssignment,
+    {
+      salesOrderId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    },
+    { populate: ['warehouse'] },
+    scope,
+  )
+  if (!assignment) return null
+  return resolveWarehouseId(assignment)
+}
+
+export async function loadSalesOrderWarehouseAssignmentView(
+  em: EntityManager,
+  salesOrderId: string,
+  scope: Scope,
+): Promise<SalesOrderWarehouseAssignmentView | null> {
+  const assignment = await findOneWithDecryption(
+    em,
+    SalesOrderWarehouseAssignment,
+    {
+      salesOrderId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+      deletedAt: null,
+    },
+    { populate: ['warehouse'] },
+    scope,
+  )
+  if (!assignment) return null
+
+  const warehouseId = resolveWarehouseId(assignment)
+  if (!warehouseId) return null
+
+  const warehouse = assignment.warehouse as Warehouse | undefined
+  return {
+    id: assignment.id,
+    salesOrderId: assignment.salesOrderId,
+    warehouseId,
+    warehouseName: warehouse?.name ?? null,
+    warehouseCode: warehouse?.code ?? null,
+    notes: assignment.notes ?? null,
+    assignedBy: assignment.assignedBy ?? null,
+  }
+}

package/src/modules/wms/lib/wmsIntegrationToggles.ts

@@ -0,0 +1,81 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { FeatureToggle } from '@open-mercato/core/modules/feature_toggles/data/entities'
+import type { FeatureTogglesService } from '@open-mercato/core/modules/feature_toggles/lib/feature-flag-check'
+
+export const WMS_INTEGRATION_TOGGLES = [
+  {
+    identifier: 'wms_integration_sales_order_inventory',
+    name: 'Sales Order Inventory Reservation',
+    description: 'Allows WMS to reserve and release inventory from sales order lifecycle events.',
+    category: 'wms',
+    type: 'boolean' as const,
+    defaultValue: true,
+  },
+  {
+    identifier: 'wms_integration_shipping_shipments',
+    name: 'Shipping Shipment Coordination',
+    description: 'Allows WMS to react to shipping shipment lifecycle events when shipment orchestration is enabled.',
+    category: 'wms',
+    type: 'boolean' as const,
+    defaultValue: true,
+  },
+  {
+    identifier: 'wms_integration_procurement_goods_receipt',
+    name: 'Procurement Goods Receipt Bridge',
+    description: 'Reserved toggle for future procurement-driven receiving integration.',
+    category: 'wms',
+    type: 'boolean' as const,
+    defaultValue: false,
+  },
+] as const
+
+export type WmsIntegrationToggleIdentifier = (typeof WMS_INTEGRATION_TOGGLES)[number]['identifier']
+
+export function findWmsIntegrationToggleDefinition(identifier: string) {
+  return WMS_INTEGRATION_TOGGLES.find((toggle) => toggle.identifier === identifier) ?? null
+}
+
+export async function seedWmsIntegrationToggles(em: EntityManager): Promise<void> {
+  for (const toggle of WMS_INTEGRATION_TOGGLES) {
+    const existing = await findOneWithDecryption(em, FeatureToggle, {
+      identifier: toggle.identifier,
+      deletedAt: null,
+    })
+    if (existing) continue
+    em.persist(
+      em.create(FeatureToggle, {
+        identifier: toggle.identifier,
+        name: toggle.name,
+        description: toggle.description,
+        category: toggle.category,
+        type: toggle.type,
+        defaultValue: toggle.defaultValue,
+      }),
+    )
+  }
+  await em.flush()
+}
+
+export async function resolveWmsIntegrationToggleEnabled(
+  featureTogglesService: FeatureTogglesService,
+  em: EntityManager,
+  identifier: WmsIntegrationToggleIdentifier,
+  tenantId: string,
+): Promise<boolean> {
+  const definition = findWmsIntegrationToggleDefinition(identifier)
+  const fallback = definition?.defaultValue ?? true
+
+  const result = await featureTogglesService.getBoolConfig(identifier, tenantId)
+  if (result.ok) return result.value
+
+  if (result.error?.code !== 'MISSING_TOGGLE' || !definition) {
+    return fallback
+  }
+
+  await seedWmsIntegrationToggles(em)
+  await featureTogglesService.invalidateIsEnabledCacheByKey(identifier, tenantId)
+
+  const retried = await featureTogglesService.getBoolConfig(identifier, tenantId)
+  return retried.ok ? retried.value : fallback
+}