@open-mercato/core 0.8.1-develop.7228.1.b7ea09d2d3 → 0.8.1-develop.7238.1.3abe669ea5

package/src/modules/sales/migrations/Migration20260916120000_sales_payment_allocation_order_idx.ts

@@ -0,0 +1,74 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// sales_payment_allocations carried a single non-PK index — (payment_id,
+// organization_id, tenant_id) — which serves the reads that start from a payment.
+// Every such read in commands/payments.ts is `{ payment }`, so that index has
+// always matched them, and its leading column also serves the payment_id foreign
+// key's referential check. Nothing here replaces it.
+//
+// The table is also read from the ORDER side, and that direction was unindexed.
+// Recomputing an order's payment totals does:
+//
+//   findWithDecryption(em, SalesPaymentAllocation, { ...scope, order: orderId },
+//                      { populate: ['payment'] }, scope)
+//
+// which the ORM emits filtered on (organization_id, tenant_id, order_id), inner
+// joined to sales_payments — `payment` is a required to-one, and the default
+// BALANCED load strategy joins those. That recompute runs on every payment create,
+// update and delete. commands/documents.ts reads the same way in four more places:
+// one em.find in the sales.orders.delete snapshot, and three nativeDelete({ order })
+// calls that take row locks while they scan.
+//
+// Measured on a table of 1.4M rows: a parallel sequential scan removing 478,376 rows
+// per worker, 28.6 ms per read to return one row. The cost is CPU filtering across
+// 23,757 buffer accesses, so a warm cache does not reduce it — the plan that
+// measured this reported every one of those buffers as `shared hit`.
+//
+// order_id and invoice_id are indexed separately rather than folded into the index
+// above, and the scope columns are deliberately omitted, for the reason given in
+// Migration20260821120000: sales_orders.id is gen_random_uuid() from its own table,
+// so an order_id already determines its tenant and organization. Four of the five
+// order-side reads supply no scope at all, so a composite would serve none of them
+// better; the seek returns the rows of one order and any remaining terms are
+// rechecked over those.
+//
+// invoice_id gets the same treatment on the foreign key's account alone. Both
+// columns are the child side of `on delete set null` constraints, which PostgreSQL
+// does not index automatically, and the constraint check probes the referencing
+// column — so without these, every delete of a parent order or invoice scans this
+// table in full. Both parents really are hard-deleted (commands/documents.ts). This
+// is the same pairing Migration20260821120000 made for order_id and quote_id.
+//
+// Built CONCURRENTLY — the table takes a write per payment allocation and is large
+// on any install that has been running a while. CREATE INDEX CONCURRENTLY cannot run
+// inside a transaction, hence isTransactional() => false; the runner applies
+// migrations one-by-one, so the opt-out is safe. Drop first so retrying a failed
+// concurrent build removes PostgreSQL's INVALID index stub instead of letting IF NOT
+// EXISTS report success over a table that stays unindexed. Same shape as
+// Migration20260806120000 and Migration20260821120000.
+//
+// On a database that does not have these indexes yet — every fresh install — the
+// drops are no-ops and there is no window without them. An operator who already
+// created one out of band should expect it to be rebuilt here, and the reads that
+// depend on it to fall back to their pre-index cost until the concurrent build
+// finishes; on a large table, run this while the writers that depend on it are
+// paused.
+export class Migration20260916120000_sales_payment_allocation_order_idx extends Migration {
+
+  override isTransactional(): boolean {
+    return false;
+  }
+
+  override up(): void | Promise<void> {
+    this.addSql(`drop index concurrently if exists "sales_payment_allocations_order_idx";`);
+    this.addSql(`create index concurrently "sales_payment_allocations_order_idx" on "sales_payment_allocations" ("order_id");`);
+    this.addSql(`drop index concurrently if exists "sales_payment_allocations_invoice_idx";`);
+    this.addSql(`create index concurrently "sales_payment_allocations_invoice_idx" on "sales_payment_allocations" ("invoice_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index concurrently if exists "sales_payment_allocations_invoice_idx";`);
+    this.addSql(`drop index concurrently if exists "sales_payment_allocations_order_idx";`);
+  }
+
+}

package/src/modules/wms/di.ts

@@ -1,5 +1,6 @@
 import { asValue } from 'awilix'
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { availabilityProviderRegistry } from '@open-mercato/shared/lib/availability'
 import {
   InventoryBalance,
   InventoryLot,
@@ -10,6 +11,7 @@ import {
   WarehouseLocation,
   WarehouseZone,
 } from './data/entities'
+import { createWmsAvailabilityProvider } from './lib/availabilityProvider'
 
 export function register(container: AppContainer) {
   container.register({
@@ -22,4 +24,8 @@ export function register(container: AppContainer) {
     InventoryReservation: asValue(InventoryReservation),
     InventoryMovement: asValue(InventoryMovement),
   })
+
+  // Explicit, idempotent (replace-by-id) registration into the shared,
+  // dependency-free registry — never "same DI key, load order wins" (§3.1).
+  availabilityProviderRegistry.register(createWmsAvailabilityProvider(container))
 }

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

@@ -0,0 +1,136 @@
+/**
+ * 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

@@ -0,0 +1,289 @@
+/**
+ * `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

@@ -0,0 +1,29 @@
+/**
+ * `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

@@ -0,0 +1,21 @@
+/**
+ * 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

@@ -0,0 +1,8 @@
+/** 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

@@ -0,0 +1,30 @@
+// 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)
+}