@open-mercato/core 0.8.1-develop.7263.1.bbc6db3437 → 0.8.1-develop.7267.1.2e95af80a6

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

@@ -1,136 +0,0 @@
-/**
- * Read-through cache for `wms`'s `AvailabilityProvider` — §6 staleness
- * budget (60s TTL for a browse-time `check`, never cached for
- * `query.bypassCache`), tag-based invalidation on `wms` balance changes.
- *
- * Tag granularity is a deliberate deviation from §6's literal
- * `availability:{tenantId}:{variantId}` naming: this module already has a
- * coarse, tenant-scoped tag for the same purpose
- * (`enricherCacheTags.ts`'s `WMS_INVENTORY_CACHE_TAG`), justified there as
- * "collection tags over-invalidate slightly; a per-warehouse scheme the
- * write side could miss would under-invalidate, which is the failure that
- * actually shows wrong stock to a user." The same reasoning applies here, so
- * `WMS_AVAILABILITY_CACHE_TAG` follows that established precedent rather
- * than a literal per-variant tag. `runWithCacheTenant` already scopes both
- * keys and tags to the current tenant (`packages/cache/src/service.ts`), so
- * neither needs `tenantId` embedded manually.
- */
-
-import { runWithCacheTenant } from '@open-mercato/cache'
-import { createLogger } from '@open-mercato/shared/lib/logger'
-import { availabilityItemKey } from '@open-mercato/shared/lib/availability'
-import type { AvailabilityItemResult, AvailabilityQuery, AvailabilityResult } from '@open-mercato/shared/lib/availability'
-import type { EntityManager } from '@mikro-orm/postgresql'
-import { computeAvailability } from './availabilityCalculation'
-
-export const WMS_AVAILABILITY_CACHE_TAG = 'wms:availability'
-/** §6 staleness budget: a browse-time `check` may be up to 60s stale. */
-export const WMS_AVAILABILITY_CACHE_TTL_MS = 60_000
-
-const logger = createLogger('wms').child({ component: 'availability-cache' })
-
-type CacheService = {
-  get(key: string, options?: { returnExpired?: boolean }): Promise<unknown>
-  set(key: string, value: unknown, options?: { ttl?: number; tags?: string[] }): Promise<void>
-  deleteByTags(tags: string[]): Promise<number>
-}
-
-type Resolver = { resolve: <T = unknown>(name: string) => T }
-
-function resolveCache(container: Resolver | null | undefined): CacheService | null {
-  if (!container?.resolve) return null
-  for (const name of ['cache', 'cacheService']) {
-    try {
-      const candidate = container.resolve<CacheService>(name)
-      if (candidate && typeof candidate.deleteByTags === 'function') return candidate
-    } catch {
-      // try the next registration name
-    }
-  }
-  return null
-}
-
-function cacheKeyForItem(query: AvailabilityQuery, item: AvailabilityQuery['items'][number]): string {
-  return [
-    'wms:availability',
-    query.organizationId,
-    query.storeId ?? '',
-    item.catalogProductId,
-    item.catalogVariantId ?? '',
-    item.quantity,
-  ].join(':')
-}
-
-/**
- * Wraps `computeAvailability` with the read-through cache. Falls back to a
- * live computation when no cache service is registered or `bypassCache` is
- * set — the same code path either way, just without the read/write.
- */
-export async function computeAvailabilityCached(
-  em: EntityManager,
-  container: Resolver,
-  query: AvailabilityQuery,
-): Promise<AvailabilityResult> {
-  const cache = resolveCache(container)
-  if (!cache || query.bypassCache) {
-    return computeAvailability(em, container, query)
-  }
-
-  return runWithCacheTenant(query.tenantId, async () => {
-    const byItem: AvailabilityResult['byItem'] = {}
-    const missed: AvailabilityQuery['items'] = []
-
-    for (const item of query.items) {
-      const key = availabilityItemKey(item)
-      try {
-        const cached = await cache.get(cacheKeyForItem(query, item))
-        if (cached) {
-          byItem[key] = { ...(cached as AvailabilityItemResult), isAuthoritative: false }
-          continue
-        }
-      } catch (err) {
-        logger.warn('Availability cache read failed; computing live', { key, err })
-      }
-      missed.push(item)
-    }
-
-    if (missed.length > 0) {
-      const live = await computeAvailability(em, container, { ...query, items: missed })
-      for (const item of missed) {
-        const key = availabilityItemKey(item)
-        const result = live.byItem[key]
-        byItem[key] = result
-        try {
-          await cache.set(cacheKeyForItem(query, item), result, {
-            ttl: WMS_AVAILABILITY_CACHE_TTL_MS,
-            tags: [WMS_AVAILABILITY_CACHE_TAG],
-          })
-        } catch (err) {
-          logger.warn('Availability cache write failed', { key, err })
-        }
-      }
-    }
-
-    return { byItem }
-  })
-}
-
-/**
- * Best-effort tag invalidation — mirrors
- * `invalidateInventoryEnricherCache.ts`. A failure is logged and swallowed:
- * invalidation must never fail the write that triggered it, and the TTL
- * bounds how long a missed drop can serve stale data.
- */
-export async function invalidateWmsAvailabilityCache(
-  container: Resolver | null | undefined,
-  tenantId: string | null | undefined,
-): Promise<void> {
-  if (!tenantId) return
-  const cache = resolveCache(container)
-  if (!cache) return
-  try {
-    await runWithCacheTenant(tenantId, () => cache.deleteByTags([WMS_AVAILABILITY_CACHE_TAG]))
-  } catch (err) {
-    logger.warn('Failed to invalidate wms availability cache', { tenantId, err })
-  }
-}

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

@@ -1,289 +0,0 @@
-/**
- * `wms`'s `AvailabilityProvider` computation — batched sellable-quantity
- * aggregation, safety-stock handling, low-stock thresholds, and product
- * rollup.
- *
- * @see .ai/specs/2026-08-14-availability-contract.md §4.2
- *
- * Batching contract (R4): exactly one balance aggregation, one profile
- * lookup, one policy lookup, and (only when the batch has product-level
- * items) one variant-rollup lookup — never per item.
- *
- * Safety-stock contract (R1): `sellable = max(0, aggregate_available -
- * safety_stock)`, with `safety_stock` subtracted ONCE per variant, after
- * aggregating every in-scope location — never once per balance row.
- */
-
-import type { EntityManager } from '@mikro-orm/postgresql'
-import { availabilityItemKey } from '@open-mercato/shared/lib/availability'
-import type { AvailabilityItemResult, AvailabilityQuery, AvailabilityResult, AvailabilityState } from '@open-mercato/shared/lib/availability'
-import { tryResolve } from './tryResolve'
-import { buildSqlInClause } from './sqlInClause'
-
-type Resolver = { resolve: <T = unknown>(name: string) => T }
-
-/**
- * Narrow, locally-declared duck type for `availability`'s `PolicyResolutionService`
- * (soft-resolved, never statically imported — `wms` never hard-requires `availability`,
- * §3.1). Structurally identical to the real service's relevant surface.
- */
-type PolicyField<T> = { value: T; policySourceId: string | null }
-type ResolvedPolicyOverlay = {
-  isStockManaged: PolicyField<boolean>
-  allowBackorder: PolicyField<boolean>
-  backorderLeadTimeDays: PolicyField<number | null>
-  preorderReleaseAt: PolicyField<Date | null>
-  lowStockThreshold: PolicyField<number | null>
-  isActive: PolicyField<boolean>
-}
-type PolicyResolutionScopeLike = {
-  tenantId: string
-  organizationId: string
-  storeId?: string | null
-  productId: string
-  variantId?: string | null
-}
-type PolicyResolutionServiceLike = {
-  resolveMany(em: EntityManager, scopes: PolicyResolutionScopeLike[]): Promise<ResolvedPolicyOverlay[]>
-}
-
-const OPEN_POLICY_DEFAULT: ResolvedPolicyOverlay = {
-  isStockManaged: { value: true, policySourceId: null },
-  allowBackorder: { value: false, policySourceId: null },
-  backorderLeadTimeDays: { value: null, policySourceId: null },
-  preorderReleaseAt: { value: null, policySourceId: null },
-  lowStockThreshold: { value: null, policySourceId: null },
-  isActive: { value: true, policySourceId: null },
-}
-
-type BalanceAggregateRow = { catalog_variant_id: string; aggregate_available: string | number | null }
-type ProfileRow = {
-  catalog_product_id: string
-  catalog_variant_id: string | null
-  safety_stock: string | number | null
-  reorder_point: string | number | null
-}
-type VariantRow = { id: string; product_id: string }
-
-async function loadBalanceAggregates(
-  em: EntityManager,
-  tenantId: string,
-  organizationId: string,
-  variantIds: string[],
-  locationIds?: string[] | null,
-): Promise<Map<string, number>> {
-  const result = new Map<string, number>()
-  if (variantIds.length === 0) return result
-
-  const variantClause = buildSqlInClause('b.catalog_variant_id', variantIds)
-  const params: unknown[] = [organizationId, tenantId, ...variantClause.params]
-  let locationClause = ''
-  if (locationIds && locationIds.length > 0) {
-    const locationIn = buildSqlInClause('b.location_id', locationIds)
-    locationClause = ` and ${locationIn.sql}`
-    params.push(...locationIn.params)
-  }
-
-  const sql = `
-    select b.catalog_variant_id,
-           sum(coalesce(b.quantity_on_hand, 0) - coalesce(b.quantity_reserved, 0) - coalesce(b.quantity_allocated, 0)) as aggregate_available
-    from wms_inventory_balances b
-    where b.organization_id = ? and b.tenant_id = ? and ${variantClause.sql} and b.deleted_at is null
-      ${locationClause}
-    group by b.catalog_variant_id
-  `
-  const rows = await em.getConnection().execute<BalanceAggregateRow[]>(sql, params)
-  for (const row of rows) {
-    result.set(row.catalog_variant_id, Number(row.aggregate_available ?? 0))
-  }
-  return result
-}
-
-async function loadProfiles(
-  em: EntityManager,
-  tenantId: string,
-  organizationId: string,
-  variantIds: string[],
-  productIds: string[],
-): Promise<ProfileRow[]> {
-  if (variantIds.length === 0 && productIds.length === 0) return []
-  const variantClause = buildSqlInClause('catalog_variant_id', variantIds)
-  const productClause = buildSqlInClause('catalog_product_id', productIds)
-  const sql = `
-    select catalog_product_id, catalog_variant_id, safety_stock, reorder_point
-    from wms_product_inventory_profiles
-    where organization_id = ? and tenant_id = ? and deleted_at is null
-      and (${variantClause.sql} or (${productClause.sql} and catalog_variant_id is null))
-  `
-  return em.getConnection().execute<ProfileRow[]>(sql, [
-    organizationId,
-    tenantId,
-    ...variantClause.params,
-    ...productClause.params,
-  ])
-}
-
-async function loadActiveVariantsForProducts(
-  em: EntityManager,
-  tenantId: string,
-  organizationId: string,
-  productIds: string[],
-): Promise<VariantRow[]> {
-  if (productIds.length === 0) return []
-  const productClause = buildSqlInClause('product_id', productIds)
-  const sql = `
-    select id, product_id
-    from catalog_product_variants
-    where organization_id = ? and tenant_id = ? and ${productClause.sql} and is_active = true and deleted_at is null
-  `
-  return em.getConnection().execute<VariantRow[]>(sql, [organizationId, tenantId, ...productClause.params])
-}
-
-function findProfile(profiles: ProfileRow[], productId: string, variantId: string | null): ProfileRow | null {
-  if (variantId) {
-    const variantRow = profiles.find((p) => p.catalog_variant_id === variantId)
-    if (variantRow) return variantRow
-  }
-  return profiles.find((p) => p.catalog_product_id === productId && !p.catalog_variant_id) ?? null
-}
-
-function computeState(params: {
-  sellable: number
-  requested: number
-  lowStockThreshold: number | null
-  allowBackorder: boolean
-  backorderLeadTimeDays: number | null
-  preorderReleaseAt: Date | null
-  isActive: boolean
-}): { state: AvailabilityState; canFulfil: boolean; leadTimeDays: number | null; releaseAt: string | null } {
-  if (!params.isActive) {
-    return { state: 'out_of_stock', canFulfil: false, leadTimeDays: null, releaseAt: null }
-  }
-  if (params.preorderReleaseAt && params.preorderReleaseAt.getTime() > Date.now()) {
-    return { state: 'preorder', canFulfil: true, leadTimeDays: null, releaseAt: params.preorderReleaseAt.toISOString() }
-  }
-  if (params.sellable >= params.requested) {
-    const state: AvailabilityState =
-      params.lowStockThreshold != null && params.sellable <= params.lowStockThreshold ? 'low_stock' : 'in_stock'
-    return { state, canFulfil: true, leadTimeDays: null, releaseAt: null }
-  }
-  if (params.allowBackorder) {
-    return { state: 'backorder', canFulfil: true, leadTimeDays: params.backorderLeadTimeDays, releaseAt: null }
-  }
-  return { state: 'out_of_stock', canFulfil: false, leadTimeDays: null, releaseAt: null }
-}
-
-/**
- * Computes availability for a batch of items — always live, never cached
- * (the cache wrapper lives in `availabilityCache.ts`, Phase 2 Step 3.2).
- */
-export async function computeAvailability(
-  em: EntityManager,
-  container: Resolver,
-  query: AvailabilityQuery,
-): Promise<AvailabilityResult> {
-  const byItem: AvailabilityResult['byItem'] = {}
-  if (query.items.length === 0) return { byItem }
-
-  const variantItems = query.items.filter((item) => !!item.catalogVariantId)
-  const productItems = query.items.filter((item) => !item.catalogVariantId)
-  const productItemIds = Array.from(new Set(productItems.map((item) => item.catalogProductId)))
-
-  // One batched lookup of active variants for every product-level item (R4).
-  const rollupVariantRows = await loadActiveVariantsForProducts(em, query.tenantId, query.organizationId, productItemIds)
-  const variantsByProduct = new Map<string, string[]>()
-  for (const row of rollupVariantRows) {
-    const list = variantsByProduct.get(row.product_id) ?? []
-    list.push(row.id)
-    variantsByProduct.set(row.product_id, list)
-  }
-
-  const allVariantIds = Array.from(
-    new Set([
-      ...variantItems.map((item) => item.catalogVariantId as string),
-      ...rollupVariantRows.map((row) => row.id),
-    ]),
-  )
-  const allProductIds = Array.from(new Set(query.items.map((item) => item.catalogProductId)))
-
-  // One balance aggregation and one profile lookup for the whole batch (R4).
-  const [balances, profiles] = await Promise.all([
-    loadBalanceAggregates(em, query.tenantId, query.organizationId, allVariantIds, query.locationIds),
-    loadProfiles(em, query.tenantId, query.organizationId, allVariantIds, allProductIds),
-  ])
-
-  // One batched policy resolution for the whole batch (R4).
-  const policyService = tryResolve<PolicyResolutionServiceLike>(container, 'policyResolutionService')
-  const policyScopes: PolicyResolutionScopeLike[] = query.items.map((item) => ({
-    tenantId: query.tenantId,
-    organizationId: query.organizationId,
-    storeId: query.storeId ?? null,
-    productId: item.catalogProductId,
-    variantId: item.catalogVariantId ?? null,
-  }))
-  const resolvedPolicies = policyService
-    ? await policyService.resolveMany(em, policyScopes)
-    : policyScopes.map(() => OPEN_POLICY_DEFAULT)
-
-  function sellableFor(variantId: string, productId: string): number {
-    const aggregate = balances.get(variantId) ?? 0
-    const profile = findProfile(profiles, productId, variantId)
-    const safetyStock = profile ? Number(profile.safety_stock ?? 0) : 0
-    return Math.max(0, aggregate - safetyStock)
-  }
-
-  query.items.forEach((item, index) => {
-    const policy = resolvedPolicies[index] ?? OPEN_POLICY_DEFAULT
-    const key = availabilityItemKey(item)
-
-    if (!policy.isStockManaged.value) {
-      byItem[key] = {
-        state: 'not_tracked',
-        availableQuantity: null,
-        canFulfil: true,
-        leadTimeDays: null,
-        releaseAt: null,
-        isAuthoritative: true,
-        policySourceId: policy.isStockManaged.policySourceId,
-      }
-      return
-    }
-
-    let sellable: number
-    let reorderPoint: number | null = null
-    if (item.catalogVariantId) {
-      sellable = sellableFor(item.catalogVariantId, item.catalogProductId)
-      const profile = findProfile(profiles, item.catalogProductId, item.catalogVariantId)
-      reorderPoint = profile && profile.reorder_point != null ? Number(profile.reorder_point) : null
-    } else {
-      const variantIds = variantsByProduct.get(item.catalogProductId) ?? []
-      sellable = variantIds.reduce((sum, variantId) => sum + sellableFor(variantId, item.catalogProductId), 0)
-      const profile = findProfile(profiles, item.catalogProductId, null)
-      reorderPoint = profile && profile.reorder_point != null ? Number(profile.reorder_point) : null
-    }
-
-    const effectiveLowStockThreshold = policy.lowStockThreshold.value ?? reorderPoint
-
-    const computed = computeState({
-      sellable,
-      requested: item.quantity,
-      lowStockThreshold: effectiveLowStockThreshold,
-      allowBackorder: policy.allowBackorder.value,
-      backorderLeadTimeDays: policy.backorderLeadTimeDays.value,
-      preorderReleaseAt: policy.preorderReleaseAt.value,
-      isActive: policy.isActive.value,
-    })
-
-    byItem[key] = {
-      state: computed.state,
-      availableQuantity: sellable,
-      canFulfil: computed.canFulfil,
-      leadTimeDays: computed.leadTimeDays,
-      releaseAt: computed.releaseAt,
-      isAuthoritative: true,
-      policySourceId: policy.isStockManaged.policySourceId,
-    }
-  })
-
-  return { byItem }
-}

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

@@ -1,29 +0,0 @@
-/**
- * `wms`'s `AvailabilityProvider` registration (`id: 'wms'`).
- *
- * @see .ai/specs/2026-08-14-availability-contract.md §3.1, §4.2
- *
- * Registered from `wms/di.ts`'s `register(container)`, which — like every
- * module DI registrar — runs once per `createRequestContainer()` call
- * (`packages/shared/src/lib/di/container.ts`), not once at process boot.
- * `availabilityProviderRegistry.register()` is idempotent replace-by-id, so
- * each request's registration simply re-points the shared registry entry at
- * a closure over that request's own container — the same pattern this
- * module already uses for its plain entity-class registrations in `di.ts`.
- */
-
-import type { EntityManager } from '@mikro-orm/postgresql'
-import type { AvailabilityProvider, AvailabilityQuery, AvailabilityResult } from '@open-mercato/shared/lib/availability'
-import { computeAvailabilityCached } from './availabilityCache'
-
-type Resolver = { resolve: <T = unknown>(name: string) => T }
-
-export function createWmsAvailabilityProvider(container: Resolver): AvailabilityProvider {
-  return {
-    id: 'wms',
-    async getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult> {
-      const em = (container.resolve('em') as EntityManager).fork()
-      return computeAvailabilityCached(em, container, query)
-    },
-  }
-}

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

@@ -1,21 +0,0 @@
-/**
- * Renders an id list into a raw-SQL `IN` clause with one placeholder per member.
- *
- * MikroORM does not bind parameters at the driver level: `AbstractSqlConnection.execute`
- * calls `platform.formatQuery`, which interpolates each value through
- * `BasePostgreSqlPlatform.escape`, and that renders a JavaScript array as a bare
- * comma-separated list. `column = ANY(?)` therefore reaches PostgreSQL as
- * `= ANY('a', 'b')` — or, for a single-element array, as the bare scalar, which fails
- * with `malformed array literal`. Same fix as the dashboards aggregation builder (#4669)
- * and the staff time-tracking raw queries: one placeholder per member.
- *
- * An empty list yields `IN (NULL)` rather than a dropped clause: a caller that narrowed
- * to nothing must select nothing, never silently widen to every row.
- */
-export type SqlInClause = { sql: string; params: unknown[] }
-
-export function buildSqlInClause(column: string, values: readonly string[]): SqlInClause {
-  if (values.length === 0) return { sql: `${column} IN (NULL)`, params: [] }
-  const placeholders = values.map(() => '?').join(', ')
-  return { sql: `${column} IN (${placeholders})`, params: [...values] }
-}

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

@@ -1,8 +0,0 @@
-/** Per-module local soft-resolve helper — see `packages/core/AGENTS.md` § Cross-Module Coupling. */
-export function tryResolve<T>(resolver: { resolve: <R = unknown>(name: string) => R }, name: string): T | undefined {
-  try {
-    return resolver.resolve<T>(name)
-  } catch {
-    return undefined
-  }
-}

package/src/modules/wms/subscribers/invalidate-availability-cache.ts

@@ -1,30 +0,0 @@
-// Invalidates the wms AvailabilityProvider's read-through cache
-// (`availabilityCache.ts`) whenever a balance changes. Ephemeral
-// (`persistent: false`) — cache invalidation is a real-time housekeeping
-// concern, not something that needs retry/audit semantics; the cache's own
-// 60s TTL is the backstop if an event is ever lost.
-//
-// `wms.*` does NOT match `wms.inventory_balance.created` (single-segment
-// matcher) — `wms.inventory_balance.*` matches all three CRUD actions
-// (created/updated/deleted) in one subscriber, mirroring
-// `invalidate-enricher-cache-balance.ts`.
-
-import { invalidateWmsAvailabilityCache } from '../lib/availabilityCache'
-
-export const metadata = {
-  event: 'wms.inventory_balance.*',
-  persistent: false,
-  id: 'wms:invalidate-availability-cache',
-}
-
-type SubscriberContext = {
-  resolve: <T = unknown>(name: string) => T
-  tenantId?: string | null
-}
-
-export default async function handle(payload: unknown, ctx: SubscriberContext): Promise<void> {
-  const data = (payload ?? {}) as Record<string, unknown>
-  const tenantId =
-    typeof data.tenantId === 'string' && data.tenantId.length > 0 ? data.tenantId : ctx.tenantId ?? null
-  await invalidateWmsAvailabilityCache(ctx, tenantId)
-}