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

package/src/modules/availability/lib/policyResolution.ts

@@ -0,0 +1,264 @@
+/**
+ * `AvailabilityPolicy` resolution chain — six levels, most specific wins.
+ *
+ * @see .ai/specs/2026-08-14-availability-contract.md §5.2
+ *
+ * Resolution design (documented here because §5.2 does not fully spell it
+ * out — see PLAN.md § Key design decisions):
+ *
+ * - Boolean columns (`isStockManaged`, `allowBackorder`, `hideWhenOutOfStock`,
+ *   `isActive`) are NOT NULL, so a matched row's own value is always
+ *   concrete — there is no "unset" to fall through. The single most specific
+ *   EXISTING row decides every boolean field.
+ * - Nullable columns (`backorderLeadTimeDays`, `preorderReleaseAt`,
+ *   `lowStockThreshold`, `minOrderQuantity`, `maxOrderQuantity`,
+ *   `quantityIncrement`) genuinely cascade: a matched row that leaves the
+ *   field `null` defers to the next-less-specific row, per US-A2's "which
+ *   level currently decides each field" requirement.
+ *
+ * `resolveMany()` exists so `wms`'s batched `check()` (§4.2/R4 — one policy
+ * lookup regardless of item count) can soft-resolve this service and still
+ * issue exactly one query for the whole batch, rather than one per item.
+ * `resolve()` is `resolveMany([scope])[0]`, so single-item callers (the admin
+ * check tool, the resolve-preview endpoint) are unaffected.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { AvailabilityPolicy } from '../data/entities'
+import { tryResolve } from './tryResolve'
+
+export type PolicyResolutionScope = {
+  tenantId: string
+  organizationId: string
+  storeId?: string | null
+  productId: string
+  variantId?: string | null
+}
+
+export type ResolvedField<T> = {
+  value: T
+  /** The `AvailabilityPolicy` row id that decided, or `null` for the module default. */
+  policySourceId: string | null
+}
+
+export type ResolvedAvailabilityPolicy = {
+  isStockManaged: ResolvedField<boolean>
+  allowBackorder: ResolvedField<boolean>
+  backorderLeadTimeDays: ResolvedField<number | null>
+  preorderReleaseAt: ResolvedField<Date | null>
+  lowStockThreshold: ResolvedField<number | null>
+  minOrderQuantity: ResolvedField<number | null>
+  maxOrderQuantity: ResolvedField<number | null>
+  quantityIncrement: ResolvedField<number | null>
+  hideWhenOutOfStock: ResolvedField<boolean>
+  isActive: ResolvedField<boolean>
+}
+
+/** The six chain levels, most specific first. `null` = "no row matched this level". */
+export type PolicyChainLevel =
+  | 'variant_store'
+  | 'variant'
+  | 'product_store'
+  | 'product'
+  | 'store_default'
+  | 'module_default'
+
+export const POLICY_CHAIN_LEVELS: PolicyChainLevel[] = [
+  'variant_store',
+  'variant',
+  'product_store',
+  'product',
+  'store_default',
+  'module_default',
+]
+
+const NULLABLE_FIELDS = [
+  'backorderLeadTimeDays',
+  'preorderReleaseAt',
+  'lowStockThreshold',
+  'minOrderQuantity',
+  'maxOrderQuantity',
+  'quantityIncrement',
+] as const
+
+const BOOLEAN_FIELDS = ['isStockManaged', 'allowBackorder', 'hideWhenOutOfStock', 'isActive'] as const
+
+function candidateFilters(scope: PolicyResolutionScope): Array<Record<string, unknown>> {
+  const storeId = scope.storeId ?? null
+  const variantId = scope.variantId ?? null
+  const filters: Array<Record<string, unknown>> = []
+  if (variantId) {
+    filters.push({ variantId, storeId })
+    filters.push({ variantId, storeId: null })
+  }
+  filters.push({ productId: scope.productId, variantId: null, storeId })
+  filters.push({ productId: scope.productId, variantId: null, storeId: null })
+  filters.push({ productId: null, variantId: null, storeId })
+  if (storeId) filters.push({ productId: null, variantId: null, storeId: null })
+  return filters
+}
+
+/** Picks the (up to) five candidate rows for one scope out of a shared, already-loaded candidate pool. */
+function matchChainRows(scope: PolicyResolutionScope, pool: AvailabilityPolicy[]): Array<AvailabilityPolicy | null> {
+  const storeId = scope.storeId ?? null
+  const variantId = scope.variantId ?? null
+  const findMatch = (predicate: (row: AvailabilityPolicy) => boolean) => pool.find(predicate) ?? null
+
+  const rows: Array<AvailabilityPolicy | null> = []
+  if (variantId) {
+    rows.push(findMatch((r) => r.variantId === variantId && (r.storeId ?? null) === storeId))
+    rows.push(findMatch((r) => r.variantId === variantId && (r.storeId ?? null) === null))
+  }
+  rows.push(findMatch((r) => r.productId === scope.productId && !r.variantId && (r.storeId ?? null) === storeId))
+  rows.push(findMatch((r) => r.productId === scope.productId && !r.variantId && (r.storeId ?? null) === null))
+  rows.push(findMatch((r) => !r.productId && !r.variantId && (r.storeId ?? null) === storeId))
+  // The store-default level cascades store-specific → all-stores, same as
+  // the variant/product levels above it ("store_id null = applies to all
+  // stores in the organization", §5.1) — otherwise an org-wide default row
+  // is invisible to any query that names a concrete store.
+  if (storeId) rows.push(findMatch((r) => !r.productId && !r.variantId && (r.storeId ?? null) === null))
+  return rows
+}
+
+function resolveFromRows(
+  rows: Array<AvailabilityPolicy | null>,
+  isStockManagedModuleDefault: boolean,
+): ResolvedAvailabilityPolicy {
+  const firstRow = rows.find((row): row is AvailabilityPolicy => row != null) ?? null
+  const result = {} as ResolvedAvailabilityPolicy
+
+  for (const field of BOOLEAN_FIELDS) {
+    if (firstRow) {
+      ;(result as any)[field] = { value: (firstRow as any)[field], policySourceId: firstRow.id }
+    } else {
+      ;(result as any)[field] = { value: false, policySourceId: null }
+    }
+  }
+
+  // is_stock_managed's module default is dynamic (wms + profile existence), not a flat `false`.
+  if (!firstRow) result.isStockManaged = { value: isStockManagedModuleDefault, policySourceId: null }
+  // is_active's module default is "active" (nothing to deactivate).
+  if (!firstRow) result.isActive = { value: true, policySourceId: null }
+
+  for (const field of NULLABLE_FIELDS) {
+    let resolved: ResolvedField<unknown> = { value: null, policySourceId: null }
+    for (const row of rows) {
+      if (row && (row as any)[field] != null) {
+        resolved = { value: (row as any)[field], policySourceId: row.id }
+        break
+      }
+    }
+    ;(result as any)[field] = resolved
+  }
+
+  return result
+}
+
+/** `is_stock_managed`'s module default: true when `wms` is enabled and a `ProductInventoryProfile` exists for the item. */
+export async function resolveIsStockManagedModuleDefault(
+  em: EntityManager,
+  container: { resolve: <T = unknown>(name: string) => T },
+  scope: { tenantId: string; organizationId: string; productId: string; variantId?: string | null },
+): Promise<boolean> {
+  const ProductInventoryProfile = tryResolve<new () => unknown>(container, 'ProductInventoryProfile')
+  if (!ProductInventoryProfile) return false
+
+  const baseFilter = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    catalogProductId: scope.productId,
+    deletedAt: null,
+  }
+
+  if (scope.variantId) {
+    const variantRow = await em.findOne(ProductInventoryProfile as any, { ...baseFilter, catalogVariantId: scope.variantId })
+    if (variantRow) return true
+  }
+
+  const productRow = await em.findOne(ProductInventoryProfile as any, { ...baseFilter, catalogVariantId: null })
+  return !!productRow
+}
+
+/** Batched module-default check for `resolveMany` — one query for every scope that might need it. */
+async function resolveIsStockManagedModuleDefaultMany(
+  em: EntityManager,
+  container: { resolve: <T = unknown>(name: string) => T },
+  scopes: PolicyResolutionScope[],
+): Promise<Map<string, boolean>> {
+  const ProductInventoryProfile = tryResolve<new () => unknown>(container, 'ProductInventoryProfile')
+  const results = new Map<string, boolean>()
+  if (!ProductInventoryProfile || scopes.length === 0) return results
+
+  const first = scopes[0]
+  const productIds = Array.from(new Set(scopes.map((s) => s.productId)))
+  const rows = (await em.find(ProductInventoryProfile as any, {
+    tenantId: first.tenantId,
+    organizationId: first.organizationId,
+    deletedAt: null,
+    catalogProductId: { $in: productIds },
+  } as any)) as Array<{ catalogProductId: string; catalogVariantId: string | null }>
+
+  const exists = new Set(rows.map((row) => `${row.catalogProductId}:${row.catalogVariantId ?? ''}`))
+  for (const scope of scopes) {
+    const variantHit = scope.variantId ? exists.has(`${scope.productId}:${scope.variantId}`) : false
+    const productHit = exists.has(`${scope.productId}:`)
+    results.set(scopeKey(scope), variantHit || productHit)
+  }
+  return results
+}
+
+function scopeKey(scope: PolicyResolutionScope): string {
+  return `${scope.productId}:${scope.variantId ?? ''}:${scope.storeId ?? ''}`
+}
+
+export interface PolicyResolutionService {
+  resolve(em: EntityManager, scope: PolicyResolutionScope): Promise<ResolvedAvailabilityPolicy>
+  resolveMany(em: EntityManager, scopes: PolicyResolutionScope[]): Promise<ResolvedAvailabilityPolicy[]>
+}
+
+export function createPolicyResolutionService(container: {
+  resolve: <T = unknown>(name: string) => T
+}): PolicyResolutionService {
+  async function resolveMany(em: EntityManager, scopes: PolicyResolutionScope[]): Promise<ResolvedAvailabilityPolicy[]> {
+    if (scopes.length === 0) return []
+
+    const first = scopes[0]
+    const seen = new Set<string>()
+    const orFilters: Array<Record<string, unknown>> = []
+    for (const scope of scopes) {
+      for (const filter of candidateFilters(scope)) {
+        const key = JSON.stringify(filter)
+        if (seen.has(key)) continue
+        seen.add(key)
+        orFilters.push(filter)
+      }
+    }
+
+    const pool = orFilters.length
+      ? await em.find(AvailabilityPolicy, {
+          tenantId: first.tenantId,
+          organizationId: first.organizationId,
+          deletedAt: null,
+          $or: orFilters as any,
+        })
+      : []
+
+    // Only scopes that resolve to no row at all need the dynamic is_stock_managed
+    // module default — batch just those.
+    const rowsByScope = scopes.map((scope) => matchChainRows(scope, pool))
+    const needsModuleDefault = scopes.filter((scope, index) => !rowsByScope[index].some((row) => row != null))
+    const moduleDefaults = await resolveIsStockManagedModuleDefaultMany(em, container, needsModuleDefault)
+
+    return scopes.map((scope, index) =>
+      resolveFromRows(rowsByScope[index], moduleDefaults.get(scopeKey(scope)) ?? false),
+    )
+  }
+
+  return {
+    async resolve(em, scope) {
+      const [result] = await resolveMany(em, [scope])
+      return result
+    },
+    resolveMany,
+  }
+}

package/src/modules/availability/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/availability/migrations/.snapshot-open-mercato.json

@@ -0,0 +1,375 @@
+{
+  "name": "public",
+  "namespaces": [
+    "public"
+  ],
+  "tables": [
+    {
+      "name": "availability_policies",
+      "schema": "public",
+      "columns": {
+        "allow_backorder": {
+          "name": "allow_backorder",
+          "type": "boolean",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "false",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "boolean"
+        },
+        "backorder_lead_time_days": {
+          "name": "backorder_lead_time_days",
+          "type": "int",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "integer"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "deleted_at": {
+          "name": "deleted_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "hide_when_out_of_stock": {
+          "name": "hide_when_out_of_stock",
+          "type": "boolean",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "false",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "boolean"
+        },
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": true,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "gen_random_uuid()",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "is_active": {
+          "name": "is_active",
+          "type": "boolean",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "true",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "boolean"
+        },
+        "is_stock_managed": {
+          "name": "is_stock_managed",
+          "type": "boolean",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "false",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "boolean"
+        },
+        "low_stock_threshold": {
+          "name": "low_stock_threshold",
+          "type": "int",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "integer"
+        },
+        "max_order_quantity": {
+          "name": "max_order_quantity",
+          "type": "int",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "integer"
+        },
+        "min_order_quantity": {
+          "name": "min_order_quantity",
+          "type": "int",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "integer"
+        },
+        "organization_id": {
+          "name": "organization_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "preorder_release_at": {
+          "name": "preorder_release_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "product_id": {
+          "name": "product_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "quantity_increment": {
+          "name": "quantity_increment",
+          "type": "int",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "integer"
+        },
+        "store_id": {
+          "name": "store_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "variant_id": {
+          "name": "variant_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        }
+      },
+      "indexes": [
+        {
+          "columnNames": [
+            "id"
+          ],
+          "composite": false,
+          "constraint": true,
+          "keyName": "availability_policies_pkey",
+          "primary": true,
+          "unique": true
+        },
+        {
+          "columnNames": [
+            "tenant_id",
+            "organization_id"
+          ],
+          "composite": true,
+          "constraint": false,
+          "keyName": "availability_policies_scope_idx",
+          "primary": false,
+          "unique": false
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "availability_policies_scope_target_unique",
+          "primary": false,
+          "unique": false,
+          "expression": "create unique index \"availability_policies_scope_target_unique\" on \"availability_policies\" (\"tenant_id\", \"organization_id\", \"store_id\", \"product_id\", \"variant_id\") nulls not distinct where deleted_at is null"
+        }
+      ],
+      "checks": [],
+      "triggers": [],
+      "foreignKeys": {},
+      "comment": null
+    }
+  ],
+  "views": [],
+  "nativeEnums": {}
+}

package/src/modules/availability/migrations/Migration20260922095844_availability.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260922095844_availability extends Migration {
+
+  override name = 'Migration20260922095844';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "availability_policies" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "store_id" uuid null, "product_id" uuid null, "variant_id" uuid null, "is_stock_managed" boolean not null default false, "allow_backorder" boolean not null default false, "backorder_lead_time_days" int null, "preorder_release_at" timestamptz null, "low_stock_threshold" int null, "min_order_quantity" int null, "max_order_quantity" int null, "quantity_increment" int null, "hide_when_out_of_stock" boolean not null default false, "is_active" boolean not null default true, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "availability_policies_scope_target_unique" on "availability_policies" ("tenant_id", "organization_id", "store_id", "product_id", "variant_id") nulls not distinct where deleted_at is null;`);
+    this.addSql(`create index "availability_policies_scope_idx" on "availability_policies" ("tenant_id", "organization_id");`);
+  }
+
+}

package/src/modules/availability/setup.ts

@@ -0,0 +1,10 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    admin: ['availability.*'],
+    employee: ['availability.policies.view'],
+  },
+}
+
+export default setup