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

package/src/modules/availability/commands/policies.ts

@@ -0,0 +1,358 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { requireId } from '@open-mercato/shared/lib/commands/helpers'
+import { extractUndoPayload, type UndoPayload } from '@open-mercato/shared/lib/commands/undo'
+import { runCrudCommandWrite } from '@open-mercato/shared/lib/commands/runCrudCommandWrite'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError, conflict, isUniqueViolation } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { CrudEventsConfig } from '@open-mercato/shared/lib/crud/types'
+import { E } from '#generated/entities.ids.generated'
+import { AvailabilityPolicy } from '../data/entities'
+import {
+  availabilityPolicyCreateSchema,
+  availabilityPolicyUpdateSchema,
+  availabilityPolicyDeleteSchema,
+  availabilityPolicyMergedConstraintsSchema,
+  type AvailabilityPolicyCreateInput,
+  type AvailabilityPolicyUpdateInput,
+} from '../data/validators'
+import { buildAvailabilityPolicyCommandWhere, ensureAvailabilityPolicyCommandScope } from './scope'
+
+const AVAILABILITY_POLICY_ENTITY_ID = E.availability.availability_policy
+
+const policyCrudEvents: CrudEventsConfig<AvailabilityPolicy> = {
+  module: 'availability',
+  entity: 'policy',
+  persistent: true,
+  buildPayload: (ctx) => ({
+    id: ctx.identifiers.id,
+    organizationId: ctx.identifiers.organizationId,
+    tenantId: ctx.identifiers.tenantId,
+  }),
+}
+
+type AvailabilityPolicySnapshot = {
+  id: string
+  organizationId: string
+  tenantId: string
+  storeId: string | null
+  productId: string | null
+  variantId: string | null
+  isStockManaged: boolean
+  allowBackorder: boolean
+  backorderLeadTimeDays: number | null
+  preorderReleaseAt: string | null
+  lowStockThreshold: number | null
+  minOrderQuantity: number | null
+  maxOrderQuantity: number | null
+  quantityIncrement: number | null
+  hideWhenOutOfStock: boolean
+  isActive: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+type AvailabilityPolicyUndoPayload = UndoPayload<AvailabilityPolicySnapshot>
+
+function toSnapshot(record: AvailabilityPolicy): AvailabilityPolicySnapshot {
+  return {
+    id: record.id,
+    organizationId: record.organizationId,
+    tenantId: record.tenantId,
+    storeId: record.storeId ?? null,
+    productId: record.productId ?? null,
+    variantId: record.variantId ?? null,
+    isStockManaged: !!record.isStockManaged,
+    allowBackorder: !!record.allowBackorder,
+    backorderLeadTimeDays: record.backorderLeadTimeDays ?? null,
+    preorderReleaseAt: record.preorderReleaseAt ? record.preorderReleaseAt.toISOString() : null,
+    lowStockThreshold: record.lowStockThreshold ?? null,
+    minOrderQuantity: record.minOrderQuantity ?? null,
+    maxOrderQuantity: record.maxOrderQuantity ?? null,
+    quantityIncrement: record.quantityIncrement ?? null,
+    hideWhenOutOfStock: !!record.hideWhenOutOfStock,
+    isActive: !!record.isActive,
+    createdAt: record.createdAt.toISOString(),
+    updatedAt: record.updatedAt.toISOString(),
+  }
+}
+
+async function loadSnapshot(
+  em: EntityManager,
+  id: string,
+  ctx: CommandRuntimeContext,
+): Promise<AvailabilityPolicySnapshot | null> {
+  const record = await em.findOne(AvailabilityPolicy, buildAvailabilityPolicyCommandWhere<AvailabilityPolicy>(ctx, { id }))
+  if (!record) return null
+  ensureAvailabilityPolicyCommandScope(ctx, record)
+  return toSnapshot(record)
+}
+
+function applyUndoSnapshot(record: AvailabilityPolicy, snapshot: AvailabilityPolicySnapshot): void {
+  record.storeId = snapshot.storeId
+  record.productId = snapshot.productId
+  record.variantId = snapshot.variantId
+  record.isStockManaged = snapshot.isStockManaged
+  record.allowBackorder = snapshot.allowBackorder
+  record.backorderLeadTimeDays = snapshot.backorderLeadTimeDays
+  record.preorderReleaseAt = snapshot.preorderReleaseAt ? new Date(snapshot.preorderReleaseAt) : null
+  record.lowStockThreshold = snapshot.lowStockThreshold
+  record.minOrderQuantity = snapshot.minOrderQuantity
+  record.maxOrderQuantity = snapshot.maxOrderQuantity
+  record.quantityIncrement = snapshot.quantityIncrement
+  record.hideWhenOutOfStock = snapshot.hideWhenOutOfStock
+  record.isActive = snapshot.isActive
+  record.updatedAt = new Date()
+}
+
+const createPolicyCommand: CommandHandler<AvailabilityPolicyCreateInput, { policyId: string }> = {
+  id: 'availability.policies.create',
+  async execute(input, ctx) {
+    const parsed = availabilityPolicyCreateSchema.parse(input)
+    ensureAvailabilityPolicyCommandScope(ctx, parsed)
+
+    const record = new AvailabilityPolicy()
+    record.organizationId = parsed.organizationId
+    record.tenantId = parsed.tenantId
+    record.storeId = parsed.storeId ?? null
+    record.productId = parsed.productId ?? null
+    record.variantId = parsed.variantId ?? null
+    record.isStockManaged = parsed.isStockManaged ?? false
+    record.allowBackorder = parsed.allowBackorder ?? false
+    record.backorderLeadTimeDays = parsed.backorderLeadTimeDays ?? null
+    record.preorderReleaseAt = parsed.preorderReleaseAt ?? null
+    record.lowStockThreshold = parsed.lowStockThreshold ?? null
+    record.minOrderQuantity = parsed.minOrderQuantity ?? null
+    record.maxOrderQuantity = parsed.maxOrderQuantity ?? null
+    record.quantityIncrement = parsed.quantityIncrement ?? null
+    record.hideWhenOutOfStock = parsed.hideWhenOutOfStock ?? false
+    record.isActive = parsed.isActive ?? true
+
+    try {
+      await runCrudCommandWrite({
+        ctx,
+        entityId: AVAILABILITY_POLICY_ENTITY_ID,
+        action: 'created',
+        scope: { tenantId: record.tenantId, organizationId: record.organizationId },
+        events: policyCrudEvents,
+        sideEffect: () => ({
+          entity: record,
+          identifiers: { id: record.id, organizationId: record.organizationId, tenantId: record.tenantId },
+        }),
+        phases: [({ em }) => { em.persist(record) }],
+      })
+    } catch (err) {
+      if (isUniqueViolation(err, 'availability_policies_scope_target_unique')) {
+        const { translate } = await resolveTranslations()
+        throw conflict(translate('availability.policies.errors.duplicateTarget', 'A policy already exists for this store/product/variant combination.'))
+      }
+      throw err
+    }
+
+    return { policyId: record.id }
+  },
+  captureAfter: async (_input, result, ctx) => {
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    return loadSnapshot(em, result.policyId, ctx)
+  },
+  buildLog: async ({ snapshots }) => {
+    const after = snapshots.after as AvailabilityPolicySnapshot | undefined
+    if (!after) return null
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('availability.audit.create', 'Create availability policy'),
+      resourceKind: 'availability.policy',
+      resourceId: after.id,
+      tenantId: after.tenantId,
+      organizationId: after.organizationId,
+      snapshotAfter: after,
+      payload: { undo: { after } },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<AvailabilityPolicyUndoPayload>(logEntry)
+    const after = payload?.after ?? null
+    if (!after) return
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const record = await em.findOne(AvailabilityPolicy, { id: after.id })
+    if (!record) return
+    record.deletedAt = new Date()
+    await em.flush()
+  },
+}
+
+const updatePolicyCommand: CommandHandler<AvailabilityPolicyUpdateInput, { policyId: string }> = {
+  id: 'availability.policies.update',
+  async prepare(input, ctx) {
+    requireId(input.id, 'Availability policy ID is required')
+    const em = ctx.container.resolve('em') as EntityManager
+    const before = await loadSnapshot(em, input.id, ctx)
+    return { before }
+  },
+  async execute(input, ctx) {
+    const parsed = availabilityPolicyUpdateSchema.parse(input)
+    requireId(parsed.id, 'Availability policy ID is required')
+
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const record = await em.findOne(AvailabilityPolicy, buildAvailabilityPolicyCommandWhere<AvailabilityPolicy>(ctx, { id: parsed.id }))
+    if (!record) throw new CrudHttpError(404, { error: 'Availability policy not found' })
+    ensureAvailabilityPolicyCommandScope(ctx, record)
+
+    const merged = {
+      storeId: parsed.storeId !== undefined ? parsed.storeId : record.storeId,
+      productId: parsed.productId !== undefined ? parsed.productId : record.productId,
+      variantId: parsed.variantId !== undefined ? parsed.variantId : record.variantId,
+      isStockManaged: parsed.isStockManaged !== undefined ? parsed.isStockManaged : record.isStockManaged,
+      allowBackorder: parsed.allowBackorder !== undefined ? parsed.allowBackorder : record.allowBackorder,
+      backorderLeadTimeDays:
+        parsed.backorderLeadTimeDays !== undefined ? parsed.backorderLeadTimeDays : record.backorderLeadTimeDays,
+      minOrderQuantity: parsed.minOrderQuantity !== undefined ? parsed.minOrderQuantity : record.minOrderQuantity,
+      maxOrderQuantity: parsed.maxOrderQuantity !== undefined ? parsed.maxOrderQuantity : record.maxOrderQuantity,
+    }
+    availabilityPolicyMergedConstraintsSchema.parse(merged)
+
+    try {
+      await runCrudCommandWrite({
+        ctx,
+        em,
+        entityId: AVAILABILITY_POLICY_ENTITY_ID,
+        action: 'updated',
+        scope: { tenantId: record.tenantId, organizationId: record.organizationId },
+        events: policyCrudEvents,
+        sideEffect: () => ({
+          entity: record,
+          identifiers: { id: record.id, organizationId: record.organizationId, tenantId: record.tenantId },
+        }),
+        phases: [
+          ({ em: forkedEm }) => {
+            const target = forkedEm.getReference(AvailabilityPolicy, record.id)
+            if (parsed.storeId !== undefined) target.storeId = parsed.storeId
+            if (parsed.productId !== undefined) target.productId = parsed.productId
+            if (parsed.variantId !== undefined) target.variantId = parsed.variantId
+            if (parsed.isStockManaged !== undefined) target.isStockManaged = parsed.isStockManaged
+            if (parsed.allowBackorder !== undefined) target.allowBackorder = parsed.allowBackorder
+            if (parsed.backorderLeadTimeDays !== undefined) target.backorderLeadTimeDays = parsed.backorderLeadTimeDays
+            if (parsed.preorderReleaseAt !== undefined) target.preorderReleaseAt = parsed.preorderReleaseAt
+            if (parsed.lowStockThreshold !== undefined) target.lowStockThreshold = parsed.lowStockThreshold
+            if (parsed.minOrderQuantity !== undefined) target.minOrderQuantity = parsed.minOrderQuantity
+            if (parsed.maxOrderQuantity !== undefined) target.maxOrderQuantity = parsed.maxOrderQuantity
+            if (parsed.quantityIncrement !== undefined) target.quantityIncrement = parsed.quantityIncrement
+            if (parsed.hideWhenOutOfStock !== undefined) target.hideWhenOutOfStock = parsed.hideWhenOutOfStock
+            if (parsed.isActive !== undefined) target.isActive = parsed.isActive
+            target.updatedAt = new Date()
+          },
+        ],
+      })
+    } catch (err) {
+      if (isUniqueViolation(err, 'availability_policies_scope_target_unique')) {
+        const { translate } = await resolveTranslations()
+        throw conflict(translate('availability.policies.errors.duplicateTarget', 'A policy already exists for this store/product/variant combination.'))
+      }
+      throw err
+    }
+
+    return { policyId: record.id }
+  },
+  captureAfter: async (_input, result, ctx) => {
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    return loadSnapshot(em, result.policyId, ctx)
+  },
+  buildLog: async ({ snapshots }) => {
+    const before = snapshots.before as AvailabilityPolicySnapshot | undefined
+    const after = snapshots.after as AvailabilityPolicySnapshot | undefined
+    if (!after) return null
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('availability.audit.update', 'Update availability policy'),
+      resourceKind: 'availability.policy',
+      resourceId: after.id,
+      tenantId: after.tenantId,
+      organizationId: after.organizationId,
+      snapshotBefore: before ?? undefined,
+      snapshotAfter: after,
+      payload: { undo: { before, after } },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<AvailabilityPolicyUndoPayload>(logEntry)
+    const before = payload?.before ?? null
+    if (!before) return
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const record = await em.findOne(AvailabilityPolicy, { id: before.id })
+    if (!record) return
+    applyUndoSnapshot(record, before)
+    await em.flush()
+  },
+}
+
+const deletePolicyCommand: CommandHandler<{ id: string; organizationId: string; tenantId: string }, { policyId: string }> = {
+  id: 'availability.policies.delete',
+  async prepare(input, ctx) {
+    requireId(input.id, 'Availability policy ID is required')
+    const em = ctx.container.resolve('em') as EntityManager
+    const before = await loadSnapshot(em, input.id, ctx)
+    return { before }
+  },
+  async execute(input, ctx) {
+    const parsed = availabilityPolicyDeleteSchema.parse(input)
+    requireId(parsed.id, 'Availability policy ID is required')
+
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const record = await em.findOne(AvailabilityPolicy, buildAvailabilityPolicyCommandWhere<AvailabilityPolicy>(ctx, { id: parsed.id }))
+    if (!record) throw new CrudHttpError(404, { error: 'Availability policy not found' })
+    ensureAvailabilityPolicyCommandScope(ctx, record)
+
+    await runCrudCommandWrite({
+      ctx,
+      em,
+      entityId: AVAILABILITY_POLICY_ENTITY_ID,
+      action: 'deleted',
+      scope: { tenantId: record.tenantId, organizationId: record.organizationId },
+      events: policyCrudEvents,
+      sideEffect: () => ({
+        entity: record,
+        identifiers: { id: record.id, organizationId: record.organizationId, tenantId: record.tenantId },
+      }),
+      phases: [
+        ({ em: forkedEm }) => {
+          const target = forkedEm.getReference(AvailabilityPolicy, record.id)
+          target.deletedAt = new Date()
+        },
+      ],
+    })
+
+    return { policyId: record.id }
+  },
+  buildLog: async ({ snapshots }) => {
+    const before = snapshots.before as AvailabilityPolicySnapshot | undefined
+    if (!before) return null
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('availability.audit.delete', 'Delete availability policy'),
+      resourceKind: 'availability.policy',
+      resourceId: before.id,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      payload: { undo: { before } },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<AvailabilityPolicyUndoPayload>(logEntry)
+    const before = payload?.before ?? null
+    if (!before) return
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const record = await em.findOne(AvailabilityPolicy, { id: before.id })
+    if (!record) return
+    record.deletedAt = null
+    record.updatedAt = new Date()
+    await em.flush()
+  },
+}
+
+registerCommand(createPolicyCommand)
+registerCommand(updatePolicyCommand)
+registerCommand(deletePolicyCommand)
+
+export { createPolicyCommand, updatePolicyCommand, deletePolicyCommand }

package/src/modules/availability/commands/scope.ts

@@ -0,0 +1,26 @@
+import type { FilterQuery } from '@mikro-orm/core'
+import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { buildScopedWhere } from '@open-mercato/shared/lib/api/crud'
+import { ensureOrganizationScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
+
+type AvailabilityPolicyScopedRecord = { organizationId: string; tenantId: string }
+
+export function buildAvailabilityPolicyCommandWhere<T extends object>(
+  ctx: CommandRuntimeContext,
+  base: FilterQuery<T>,
+): FilterQuery<T> {
+  const organizationId = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? undefined
+  return buildScopedWhere(base as Record<string, unknown>, {
+    organizationId,
+    organizationIds: ctx.organizationIds ?? undefined,
+    tenantId: ctx.auth?.tenantId ?? undefined,
+  }) as FilterQuery<T>
+}
+
+export function ensureAvailabilityPolicyCommandScope(
+  ctx: CommandRuntimeContext,
+  record: AvailabilityPolicyScopedRecord,
+): void {
+  ensureTenantScope(ctx, record.tenantId)
+  ensureOrganizationScope(ctx, record.organizationId)
+}

package/src/modules/availability/data/entities.ts

@@ -0,0 +1,92 @@
+import { OptionalProps } from '@mikro-orm/core'
+import { Entity, Index, PrimaryKey, Property } from '@mikro-orm/decorators/legacy'
+
+@Entity({ tableName: 'availability_policies' })
+@Index({ name: 'availability_policies_scope_idx', properties: ['tenantId', 'organizationId'] })
+@Index({
+  // Exactly one policy row per (store, product, variant) combination — nullable columns mean
+  // "applies to all stores" / "product-level" / "store-level default". Postgres treats NULLs as
+  // distinct by default, so the index is declared NULLS NOT DISTINCT (mirrors user_devices).
+  name: 'availability_policies_scope_target_unique',
+  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',
+})
+export class AvailabilityPolicy {
+  [OptionalProps]?:
+    | 'storeId'
+    | 'productId'
+    | 'variantId'
+    | 'isStockManaged'
+    | 'allowBackorder'
+    | 'backorderLeadTimeDays'
+    | 'preorderReleaseAt'
+    | 'lowStockThreshold'
+    | 'minOrderQuantity'
+    | 'maxOrderQuantity'
+    | 'quantityIncrement'
+    | 'hideWhenOutOfStock'
+    | 'isActive'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  /** `catalog.EcommerceStore`-shaped id (not yet a real entity in this repo) — null = all stores. */
+  @Property({ name: 'store_id', type: 'uuid', nullable: true })
+  storeId?: string | null
+
+  /** `catalog.CatalogProduct.id`. */
+  @Property({ name: 'product_id', type: 'uuid', nullable: true })
+  productId?: string | null
+
+  /** `catalog.CatalogProductVariant.id`. Non-null requires `productId` non-null (validated). */
+  @Property({ name: 'variant_id', type: 'uuid', nullable: true })
+  variantId?: string | null
+
+  @Property({ name: 'is_stock_managed', type: 'boolean', default: false })
+  isStockManaged: boolean = false
+
+  @Property({ name: 'allow_backorder', type: 'boolean', default: false })
+  allowBackorder: boolean = false
+
+  @Property({ name: 'backorder_lead_time_days', type: 'integer', nullable: true })
+  backorderLeadTimeDays?: number | null
+
+  @Property({ name: 'preorder_release_at', type: Date, nullable: true })
+  preorderReleaseAt?: Date | null
+
+  @Property({ name: 'low_stock_threshold', type: 'integer', nullable: true })
+  lowStockThreshold?: number | null
+
+  @Property({ name: 'min_order_quantity', type: 'integer', nullable: true })
+  minOrderQuantity?: number | null
+
+  @Property({ name: 'max_order_quantity', type: 'integer', nullable: true })
+  maxOrderQuantity?: number | null
+
+  @Property({ name: 'quantity_increment', type: 'integer', nullable: true })
+  quantityIncrement?: number | null
+
+  @Property({ name: 'hide_when_out_of_stock', type: 'boolean', default: false })
+  hideWhenOutOfStock: boolean = false
+
+  @Property({ name: 'is_active', type: 'boolean', default: true })
+  isActive: boolean = true
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}

package/src/modules/availability/data/validators.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod'
+
+const uuid = () => z.string().uuid()
+
+const scopedSchema = z.object({
+  organizationId: uuid(),
+  tenantId: uuid(),
+})
+
+const nonNegativeInt = () => z.number().int().min(0)
+
+const policyFieldsSchema = z.object({
+  storeId: uuid().nullable().optional(),
+  productId: uuid().nullable().optional(),
+  variantId: uuid().nullable().optional(),
+  isStockManaged: z.boolean().optional(),
+  allowBackorder: z.boolean().optional(),
+  backorderLeadTimeDays: nonNegativeInt().nullable().optional(),
+  preorderReleaseAt: z.coerce.date().nullable().optional(),
+  lowStockThreshold: nonNegativeInt().nullable().optional(),
+  minOrderQuantity: nonNegativeInt().nullable().optional(),
+  maxOrderQuantity: nonNegativeInt().nullable().optional(),
+  quantityIncrement: nonNegativeInt().nullable().optional(),
+  hideWhenOutOfStock: z.boolean().optional(),
+  isActive: z.boolean().optional(),
+})
+
+export const AVAILABILITY_POLICY_VARIANT_REQUIRES_PRODUCT_MESSAGE_KEY =
+  'availability.policies.errors.variantRequiresProduct'
+export const AVAILABILITY_POLICY_BACKORDER_REQUIRES_LEAD_TIME_MESSAGE_KEY =
+  'availability.policies.errors.backorderRequiresLeadTime'
+export const AVAILABILITY_POLICY_MAX_BELOW_MIN_MESSAGE_KEY = 'availability.policies.errors.maxBelowMin'
+
+function refinePolicyConstraints<T extends z.ZodTypeAny>(schema: T) {
+  return schema
+    .refine((val: any) => !(val.variantId && !val.productId), {
+      message: AVAILABILITY_POLICY_VARIANT_REQUIRES_PRODUCT_MESSAGE_KEY,
+      path: ['variantId'],
+    })
+    .refine((val: any) => !(val.allowBackorder && val.backorderLeadTimeDays == null), {
+      message: AVAILABILITY_POLICY_BACKORDER_REQUIRES_LEAD_TIME_MESSAGE_KEY,
+      path: ['backorderLeadTimeDays'],
+    })
+    .refine(
+      (val: any) =>
+        !(val.minOrderQuantity != null && val.maxOrderQuantity != null && val.maxOrderQuantity < val.minOrderQuantity),
+      { message: AVAILABILITY_POLICY_MAX_BELOW_MIN_MESSAGE_KEY, path: ['maxOrderQuantity'] },
+    )
+}
+
+export const availabilityPolicyCreateSchema = refinePolicyConstraints(
+  scopedSchema.extend(policyFieldsSchema.shape),
+)
+
+// Cross-field constraints (variant requires product, backorder requires lead time, max >= min)
+// are NOT re-checked here at the zod layer: a partial update payload may touch only one side of
+// a constraint while the other side's value already satisfies it in the stored row. The update
+// command (commands/policies.ts) re-validates the same constraints against the merged
+// (existing-row + patch) record, where the full picture is available.
+export const availabilityPolicyUpdateSchema = z
+  .object({ id: uuid() })
+  .merge(scopedSchema.extend(policyFieldsSchema.shape).partial())
+
+export const availabilityPolicyDeleteSchema = scopedSchema.extend({ id: uuid() })
+
+/** Re-applies the create-time cross-field constraints to a merged (existing + patch) record. Used by the update command. */
+export const availabilityPolicyMergedConstraintsSchema = refinePolicyConstraints(policyFieldsSchema)
+
+export type AvailabilityPolicyCreateInput = z.infer<typeof availabilityPolicyCreateSchema>
+export type AvailabilityPolicyUpdateInput = z.infer<typeof availabilityPolicyUpdateSchema>

package/src/modules/availability/di.ts

@@ -0,0 +1,54 @@
+import { asValue } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { setCatalogOnlyPolicyLookup, availabilityItemKey } from '@open-mercato/shared/lib/availability'
+import type { CatalogOnlyPolicyOverride } from '@open-mercato/shared/lib/availability'
+import { AvailabilityPolicy } from './data/entities'
+import { createPolicyResolutionService } from './lib/policyResolution'
+
+export function register(container: AppContainer) {
+  container.register({
+    AvailabilityPolicy: asValue(AvailabilityPolicy),
+    policyResolutionService: {
+      resolve: (c) => createPolicyResolutionService(c),
+    },
+  })
+
+  // Wires the shared catalog-only fallback's optional policy hook (decision 2,
+  // PLAN.md § Key design decisions) — closure captures the boot container, the
+  // same technique `wms/di.ts` uses for its own provider registration.
+  setCatalogOnlyPolicyLookup(async (query) => {
+    const em = (container.resolve('em') as EntityManager).fork()
+    const service = createPolicyResolutionService(container)
+    const overrides: Record<string, CatalogOnlyPolicyOverride | null> = {}
+
+    // Batched (R4): one resolveMany() call for the whole item set, not one
+    // resolve() per item — the same discipline wms's provider follows.
+    const resolved = await service.resolveMany(
+      em,
+      query.items.map((item) => ({
+        tenantId: query.tenantId,
+        organizationId: query.organizationId,
+        storeId: query.storeId ?? null,
+        productId: item.catalogProductId,
+        variantId: item.catalogVariantId ?? null,
+      })),
+    )
+
+    query.items.forEach((item, index) => {
+      const policy = resolved[index]
+      overrides[availabilityItemKey(item)] = {
+        isStockManaged: policy.isStockManaged.value,
+        isActive: policy.isActive.value,
+        preorderReleaseAt: policy.preorderReleaseAt.value ? policy.preorderReleaseAt.value.toISOString() : null,
+        policySourceId:
+          policy.preorderReleaseAt.policySourceId
+          ?? policy.isActive.policySourceId
+          ?? policy.isStockManaged.policySourceId
+          ?? null,
+      }
+    })
+
+    return overrides
+  })
+}

package/src/modules/availability/events.ts

@@ -0,0 +1,17 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+const events = [
+  { id: 'availability.policy.created', label: 'Availability Policy Created', entity: 'policy', category: 'crud' },
+  { id: 'availability.policy.updated', label: 'Availability Policy Updated', entity: 'policy', category: 'crud' },
+  { id: 'availability.policy.deleted', label: 'Availability Policy Deleted', entity: 'policy', category: 'crud' },
+] as const
+
+export const eventsConfig = createModuleEvents({
+  moduleId: 'availability',
+  events,
+})
+
+export const emitAvailabilityEvent = eventsConfig.emit
+export type AvailabilityEventId = typeof events[number]['id']
+
+export default eventsConfig