@open-mercato/core 0.6.7-develop.6661.1.0043ed1d03 → 0.6.7-develop.6670.1.4efa7961c6

package/dist/modules/wms/commands/inventory-actions.js

@@ -0,0 +1,1539 @@
+import { LockMode } from "@mikro-orm/core";
+import { randomUUID } from "crypto";
+import { registerCommand } from "@open-mercato/shared/lib/commands";
+import { emitCrudSideEffects } from "@open-mercato/shared/lib/commands/helpers";
+import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
+import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
+import { findOneWithDecryption, findWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { emitWmsEvent } from "../events.js";
+import { E } from "../../../generated/entities.ids.generated.js";
+import {
+  InventoryBalance,
+  InventoryLot,
+  InventoryMovement,
+  InventoryReservation,
+  ProductInventoryProfile,
+  Warehouse,
+  WarehouseLocation
+} from "../data/entities.js";
+import {
+  inventoryAdjustSchema,
+  inventoryCycleCountSchema,
+  inventoryMoveSchema,
+  inventoryReceiveSchema,
+  inventoryReservationAllocateSchema,
+  inventoryReservationCreateSchema,
+  inventoryReservationReleaseSchema
+} from "../data/validators.js";
+import {
+  evaluateLowStock,
+  isLotEligible,
+  resolveReservationStrategyFromProfile,
+  sortBucketsForStrategy
+} from "../lib/inventoryPolicy.js";
+import { enforceInventoryTrackingRequirements } from "../lib/inventoryTrackingValidation.js";
+import {
+  buildMovementIdempotencyKey,
+  buildReservationIdempotencyKey
+} from "../lib/inventoryIdempotency.js";
+import {
+  ensureOrganizationScope,
+  ensureTenantScope,
+  inventoryBalanceCrudEvents,
+  inventoryBalanceCrudIndexer,
+  inventoryMovementCrudEvents,
+  inventoryMovementCrudIndexer,
+  inventoryReservationCrudEvents,
+  inventoryReservationCrudIndexer,
+  toNumericString,
+  WMS_INVENTORY_BALANCE_RESOURCE,
+  WMS_INVENTORY_MOVEMENT_RESOURCE,
+  WMS_INVENTORY_RESERVATION_RESOURCE
+} from "./shared.js";
+async function emitInventorySideEffects(ctx, affected) {
+  let de = null;
+  try {
+    de = ctx.container.resolve("dataEngine");
+  } catch {
+    de = null;
+  }
+  if (!de) return;
+  for (const { entity, action } of affected.reservations ?? []) {
+    await emitCrudSideEffects({
+      dataEngine: de,
+      action,
+      entity,
+      identifiers: {
+        id: entity.id,
+        organizationId: entity.organizationId,
+        tenantId: entity.tenantId
+      },
+      indexer: inventoryReservationCrudIndexer,
+      events: inventoryReservationCrudEvents
+    });
+  }
+  for (const { entity, action } of affected.movements ?? []) {
+    await emitCrudSideEffects({
+      dataEngine: de,
+      action,
+      entity,
+      identifiers: {
+        id: entity.id,
+        organizationId: entity.organizationId,
+        tenantId: entity.tenantId
+      },
+      indexer: inventoryMovementCrudIndexer,
+      events: inventoryMovementCrudEvents
+    });
+  }
+  for (const { entity, action } of affected.balances ?? []) {
+    await emitCrudSideEffects({
+      dataEngine: de,
+      action,
+      entity,
+      identifiers: {
+        id: entity.id,
+        organizationId: entity.organizationId,
+        tenantId: entity.tenantId
+      },
+      indexer: inventoryBalanceCrudIndexer,
+      events: inventoryBalanceCrudEvents
+    });
+  }
+}
+function resolveScope(ctx, fallback) {
+  const tenantId = fallback?.tenantId ?? ctx.auth?.tenantId ?? null;
+  const organizationId = fallback?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null;
+  if (!tenantId || !organizationId) {
+    throw new CrudHttpError(400, { error: "Tenant and organization scope are required." });
+  }
+  return { tenantId, organizationId };
+}
+function resolveEm(ctx) {
+  return ctx.container.resolve("em").fork();
+}
+async function runInTransaction(em, operation) {
+  const transactionalEm = em;
+  if (typeof transactionalEm.transactional === "function") {
+    return transactionalEm.transactional((trx) => operation(trx));
+  }
+  return operation(em);
+}
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 0;
+}
+function isUniqueConstraintError(error) {
+  if (!error || typeof error !== "object") return false;
+  const code = error.code;
+  if (code === "23505") return true;
+  const name = error.name;
+  return name === "UniqueConstraintViolationException";
+}
+async function findExistingMovementByIdempotencyKey(em, scope, idempotencyKey) {
+  return findOneWithDecryption(
+    em,
+    InventoryMovement,
+    {
+      organizationId: scope.organizationId,
+      idempotencyKey,
+      deletedAt: null
+    },
+    void 0,
+    scope
+  );
+}
+async function findExistingActiveReservationByIdempotencyKey(em, scope, idempotencyKey) {
+  return findOneWithDecryption(
+    em,
+    InventoryReservation,
+    {
+      organizationId: scope.organizationId,
+      idempotencyKey,
+      status: "active",
+      deletedAt: null
+    },
+    void 0,
+    scope
+  );
+}
+function resolveLotFromBalance(balance) {
+  const lotRaw = balance.lot ?? null;
+  if (!lotRaw || typeof lotRaw === "string") return null;
+  return lotRaw;
+}
+function balanceHasEligibleLot(balance, now) {
+  const lot = resolveLotFromBalance(balance);
+  return isLotEligible(lot, now);
+}
+function setNumeric(target, key, value) {
+  target[key] = toNumericString(value);
+}
+function getAvailableQuantity(balance) {
+  return toNumber(balance.quantityOnHand) - toNumber(balance.quantityReserved) - toNumber(balance.quantityAllocated);
+}
+function extractReservationMetadata(reservation) {
+  if (!reservation.metadata || typeof reservation.metadata !== "object" || Array.isArray(reservation.metadata)) {
+    return {};
+  }
+  return { ...reservation.metadata };
+}
+function buildBucketKey(input) {
+  return [
+    input.warehouseId,
+    input.locationId,
+    input.catalogVariantId,
+    input.lotId ?? "",
+    input.serialNumber ?? ""
+  ].join("::");
+}
+function serializeAllocationBuckets(buckets) {
+  return buckets.map((bucket) => ({
+    locationId: bucket.locationId,
+    lotId: bucket.lotId,
+    quantity: toNumericString(bucket.quantity)
+  }));
+}
+async function buildMutationLog(input) {
+  const { translate } = await resolveTranslations();
+  const aliases = Array.from(
+    new Set((input.cacheAliases ?? []).filter((alias) => typeof alias === "string" && alias.length > 0))
+  );
+  return {
+    actionLabel: translate(input.actionKey, input.fallbackLabel),
+    resourceKind: input.resourceKind,
+    resourceId: input.resourceId,
+    parentResourceKind: input.parentResourceId ? "wms.inventory" : null,
+    parentResourceId: input.parentResourceId ?? null,
+    tenantId: input.tenantId,
+    organizationId: input.organizationId,
+    ...aliases.length ? { context: { cacheAliases: aliases } } : {}
+  };
+}
+async function requireWarehouse(em, ctx, warehouseId, scope) {
+  const resolvedScope = scope ?? resolveScope(ctx);
+  const warehouse = await findOneWithDecryption(
+    em,
+    Warehouse,
+    { id: warehouseId, deletedAt: null },
+    void 0,
+    resolvedScope
+  );
+  if (!warehouse) throw new CrudHttpError(404, { error: "Warehouse not found." });
+  ensureTenantScope(ctx, warehouse.tenantId);
+  ensureOrganizationScope(ctx, warehouse.organizationId);
+  return warehouse;
+}
+async function requireLocation(em, ctx, locationId, scope) {
+  const resolvedScope = scope ?? resolveScope(ctx);
+  const location = await findOneWithDecryption(
+    em,
+    WarehouseLocation,
+    { id: locationId, deletedAt: null },
+    void 0,
+    resolvedScope
+  );
+  if (!location) throw new CrudHttpError(404, { error: "Warehouse location not found." });
+  ensureTenantScope(ctx, location.tenantId);
+  ensureOrganizationScope(ctx, location.organizationId);
+  return location;
+}
+async function requireReservation(em, ctx, reservationId, scope, lock = false) {
+  const resolvedScope = scope ?? resolveScope(ctx);
+  const reservation = await findOneWithDecryption(
+    em,
+    InventoryReservation,
+    { id: reservationId, deletedAt: null },
+    lock ? { lockMode: LockMode.PESSIMISTIC_WRITE } : void 0,
+    resolvedScope
+  );
+  if (!reservation) throw new CrudHttpError(404, { error: "Inventory reservation not found." });
+  ensureTenantScope(ctx, reservation.tenantId);
+  ensureOrganizationScope(ctx, reservation.organizationId);
+  return reservation;
+}
+async function loadProfileForVariant(em, ctx, catalogVariantId, scope) {
+  const resolvedScope = scope ?? resolveScope(ctx);
+  const profile = await findOneWithDecryption(
+    em,
+    ProductInventoryProfile,
+    { catalogVariantId, deletedAt: null },
+    void 0,
+    resolvedScope
+  );
+  if (!profile) return null;
+  ensureTenantScope(ctx, profile.tenantId);
+  ensureOrganizationScope(ctx, profile.organizationId);
+  return profile;
+}
+async function resolveReceiveLotId(em, ctx, scope, input) {
+  if (input.lotId?.trim()) return input.lotId.trim();
+  const lotNumber = input.lotNumber?.trim();
+  if (!lotNumber) return void 0;
+  const existing = await findOneWithDecryption(
+    em,
+    InventoryLot,
+    {
+      catalogVariantId: input.catalogVariantId,
+      lotNumber,
+      deletedAt: null
+    },
+    void 0,
+    scope
+  );
+  if (existing) return existing.id;
+  const queryEngine = ctx.container.resolve("queryEngine");
+  const variantResult = await queryEngine.query(E.catalog.catalog_product_variant, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    filters: { id: { $eq: input.catalogVariantId } },
+    fields: ["id", "sku"],
+    page: { page: 1, pageSize: 1 }
+  });
+  const firstItem = variantResult.items?.[0];
+  const sku = typeof firstItem === "object" && firstItem !== null ? String(firstItem.sku ?? "").trim() : "";
+  if (!sku) {
+    throw new CrudHttpError(422, { error: "variant_sku_missing" });
+  }
+  const lot = em.create(InventoryLot, {
+    id: randomUUID(),
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    catalogVariantId: input.catalogVariantId,
+    sku,
+    lotNumber,
+    status: "available"
+  });
+  em.persist(lot);
+  return lot.id;
+}
+async function listCandidateBalances(em, ctx, input, scope) {
+  const where = {
+    warehouse: input.warehouseId,
+    catalogVariantId: input.catalogVariantId,
+    deletedAt: null
+  };
+  if (input.lotId) where.lot = input.lotId;
+  if (input.serialNumber) where.serialNumber = input.serialNumber;
+  const balances = await findWithDecryption(
+    em,
+    InventoryBalance,
+    where,
+    {
+      populate: ["lot", "location"],
+      lockMode: LockMode.PESSIMISTIC_WRITE,
+      orderBy: { createdAt: "asc", id: "asc" }
+    },
+    scope
+  );
+  for (const balance of balances) {
+    ensureTenantScope(ctx, balance.tenantId);
+    ensureOrganizationScope(ctx, balance.organizationId);
+  }
+  return balances;
+}
+async function listBalancesForVariant(em, ctx, catalogVariantId, scope) {
+  const balances = await findWithDecryption(
+    em,
+    InventoryBalance,
+    {
+      catalogVariantId,
+      deletedAt: null
+    },
+    void 0,
+    scope
+  );
+  for (const balance of balances) {
+    ensureTenantScope(ctx, balance.tenantId);
+    ensureOrganizationScope(ctx, balance.organizationId);
+  }
+  return balances;
+}
+async function emitLowStockEventIfNeeded(em, ctx, scope, catalogVariantId) {
+  const profile = await loadProfileForVariant(em, ctx, catalogVariantId, scope);
+  if (!profile) return;
+  const balances = await listBalancesForVariant(em, ctx, catalogVariantId, scope);
+  const availableQuantity = balances.reduce((total, balance) => total + getAvailableQuantity(balance), 0);
+  const lowStock = evaluateLowStock(profile, availableQuantity);
+  if (!lowStock) return;
+  await emitWmsEvent("wms.inventory.low_stock", {
+    id: catalogVariantId,
+    catalogVariantId,
+    availableQuantity: lowStock.availableQuantity,
+    reorderPoint: lowStock.reorderPoint,
+    safetyStock: lowStock.safetyStock,
+    state: lowStock.state,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId
+  });
+}
+async function loadReceivedAtByBucket(em, balances, scope) {
+  if (balances.length === 0) return /* @__PURE__ */ new Map();
+  const locationIds = Array.from(
+    new Set(
+      balances.map((balance) => typeof balance.location === "string" ? balance.location : balance.location.id)
+    )
+  );
+  const warehouseId = typeof balances[0].warehouse === "string" ? balances[0].warehouse : balances[0].warehouse.id;
+  const catalogVariantId = balances[0].catalogVariantId;
+  const movements = await findWithDecryption(
+    em,
+    InventoryMovement,
+    {
+      warehouse: warehouseId,
+      catalogVariantId,
+      deletedAt: null,
+      $or: [
+        { locationFrom: { $in: locationIds } },
+        { locationTo: { $in: locationIds } }
+      ]
+    },
+    {
+      orderBy: { receivedAt: "asc" }
+    },
+    scope
+  );
+  const map = /* @__PURE__ */ new Map();
+  for (const movement of movements) {
+    const locationIdRaw = movement.locationTo ?? movement.locationFrom ?? null;
+    const locationId = typeof locationIdRaw === "string" ? locationIdRaw : locationIdRaw?.id ?? null;
+    if (!locationId) continue;
+    const lotIdRaw = movement.lot ?? null;
+    const lotId = typeof lotIdRaw === "string" ? lotIdRaw : lotIdRaw?.id ?? null;
+    const key = buildBucketKey({
+      warehouseId,
+      locationId,
+      catalogVariantId: movement.catalogVariantId,
+      lotId,
+      serialNumber: movement.serialNumber ?? null
+    });
+    if (!map.has(key)) {
+      map.set(key, movement.receivedAt);
+    }
+  }
+  return map;
+}
+function sortBalancesForStrategy(balances, strategy, receiptMap) {
+  const rows = balances.map((balance) => {
+    const warehouseId = typeof balance.warehouse === "string" ? balance.warehouse : balance.warehouse.id;
+    const locationId = typeof balance.location === "string" ? balance.location : balance.location.id;
+    const lotIdRaw = balance.lot ?? null;
+    const lotId = typeof lotIdRaw === "string" ? lotIdRaw : lotIdRaw?.id ?? null;
+    const lot = typeof balance.lot === "string" ? null : balance.lot;
+    return {
+      balance,
+      warehouseId,
+      locationId,
+      catalogVariantId: balance.catalogVariantId,
+      createdAt: balance.createdAt,
+      lotId,
+      lotExpiresAt: lot?.expiresAt ?? null,
+      serialNumber: balance.serialNumber ?? null
+    };
+  });
+  const sorted = sortBucketsForStrategy(rows, strategy, receiptMap);
+  return sorted.map((row) => row.balance);
+}
+async function resolveReservationStrategy(em, ctx, input, scope) {
+  const profile = await loadProfileForVariant(em, ctx, input.catalogVariantId, scope);
+  return resolveReservationStrategyFromProfile(profile, input.strategy);
+}
+function requireSufficientAvailability(remaining) {
+  if (remaining > 1e-6) {
+    throw new CrudHttpError(409, { error: "insufficient_stock" });
+  }
+}
+async function findExactBalanceForUpdate(em, scope, input) {
+  return findOneWithDecryption(
+    em,
+    InventoryBalance,
+    {
+      warehouse: input.warehouseId,
+      location: input.locationId,
+      catalogVariantId: input.catalogVariantId,
+      lot: input.lotId ?? null,
+      serialNumber: input.serialNumber ?? null,
+      deletedAt: null
+    },
+    { lockMode: LockMode.PESSIMISTIC_WRITE },
+    scope
+  );
+}
+async function findReservationBucketBalance(em, scope, reservation, bucket) {
+  const warehouseId = typeof reservation.warehouse === "string" ? reservation.warehouse : reservation.warehouse.id;
+  if (typeof bucket.balanceId === "string" && bucket.balanceId.length > 0) {
+    const balance = await findOneWithDecryption(
+      em,
+      InventoryBalance,
+      { id: bucket.balanceId, deletedAt: null },
+      { lockMode: LockMode.PESSIMISTIC_WRITE },
+      scope
+    );
+    if (balance) return balance;
+  }
+  return findExactBalanceForUpdate(em, scope, {
+    warehouseId,
+    locationId: bucket.locationId,
+    catalogVariantId: reservation.catalogVariantId,
+    lotId: bucket.lotId ?? void 0,
+    serialNumber: bucket.serialNumber ?? void 0
+  });
+}
+async function upsertBalanceBucket(em, scope, input) {
+  const existing = await findExactBalanceForUpdate(em, scope, input);
+  if (existing) return { balance: existing, created: false };
+  const balance = em.create(InventoryBalance, {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    warehouse: em.getReference(Warehouse, input.warehouseId),
+    location: em.getReference(WarehouseLocation, input.locationId),
+    catalogVariantId: input.catalogVariantId,
+    lot: input.lotId ? em.getReference(InventoryLot, input.lotId) : null,
+    serialNumber: input.serialNumber ?? null,
+    quantityOnHand: "0",
+    quantityReserved: "0",
+    quantityAllocated: "0",
+    metadata: null
+  });
+  em.persist(balance);
+  await em.flush();
+  return { balance, created: true };
+}
+async function resolveReceivedAtForBalance(em, balance, scope, fallback) {
+  if (!balance) return fallback;
+  const warehouseId = typeof balance.warehouse === "string" ? balance.warehouse : balance.warehouse.id;
+  const locationId = typeof balance.location === "string" ? balance.location : balance.location.id;
+  const lotIdRaw = balance.lot ?? null;
+  const lotId = typeof lotIdRaw === "string" ? lotIdRaw : lotIdRaw?.id ?? null;
+  const movement = await findOneWithDecryption(
+    em,
+    InventoryMovement,
+    {
+      warehouse: warehouseId,
+      catalogVariantId: balance.catalogVariantId,
+      lot: lotId,
+      serialNumber: balance.serialNumber ?? null,
+      deletedAt: null,
+      $or: [
+        { locationFrom: locationId },
+        { locationTo: locationId }
+      ]
+    },
+    { orderBy: { receivedAt: "asc" } },
+    scope
+  );
+  return movement?.receivedAt ?? fallback;
+}
+async function createMovement(em, scope, input) {
+  const movement = em.create(InventoryMovement, {
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    warehouse: em.getReference(Warehouse, input.warehouseId),
+    locationFrom: input.locationFromId ? em.getReference(WarehouseLocation, input.locationFromId) : null,
+    locationTo: input.locationToId ? em.getReference(WarehouseLocation, input.locationToId) : null,
+    catalogVariantId: input.catalogVariantId,
+    lot: input.lotId ? em.getReference(InventoryLot, input.lotId) : null,
+    serialNumber: input.serialNumber ?? null,
+    quantity: toNumericString(input.quantity),
+    type: input.type,
+    referenceType: input.referenceType,
+    referenceId: input.referenceId,
+    performedBy: input.performedBy,
+    performedAt: input.performedAt,
+    receivedAt: input.receivedAt,
+    reason: input.reason ?? null,
+    reasonCode: input.reasonCode ?? null,
+    metadata: input.metadata ?? null,
+    idempotencyKey: input.idempotencyKey
+  });
+  em.persist(movement);
+  return movement;
+}
+async function persistMovementWithIdempotency(em, scope, input) {
+  const idempotencyKey = buildMovementIdempotencyKey({
+    referenceType: input.referenceType,
+    referenceId: input.referenceId,
+    type: input.type,
+    warehouseId: input.warehouseId,
+    locationFromId: input.locationFromId,
+    locationToId: input.locationToId,
+    catalogVariantId: input.catalogVariantId,
+    lotId: input.lotId,
+    serialNumber: input.serialNumber,
+    quantity: input.quantity
+  });
+  const existing = await findExistingMovementByIdempotencyKey(em, scope, idempotencyKey);
+  if (existing) {
+    return { movement: existing, idempotentReplay: true };
+  }
+  try {
+    const movement = await createMovement(em, scope, {
+      ...input,
+      idempotencyKey
+    });
+    return { movement, idempotentReplay: false };
+  } catch (error) {
+    if (!isUniqueConstraintError(error)) throw error;
+    const raced = await findExistingMovementByIdempotencyKey(em, scope, idempotencyKey);
+    if (!raced) throw error;
+    return { movement: raced, idempotentReplay: true };
+  }
+}
+async function emitBalanceDriftIfNeeded(balance, field, attemptedValue, scope, reservationId) {
+  if (attemptedValue >= -1e-6) return;
+  await emitWmsEvent("wms.inventory.balance_drift", {
+    id: balance.id,
+    balanceId: balance.id,
+    reservationId,
+    field,
+    attemptedValue: toNumericString(attemptedValue),
+    clampedValue: "0",
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId
+  }).catch(() => void 0);
+}
+function enforceNonNegativeBalance(balance, field, nextValue, reservationId, scope) {
+  if (nextValue < -1e-6) {
+    void emitBalanceDriftIfNeeded(balance, field, nextValue, scope, reservationId);
+    throw new CrudHttpError(409, { error: "balance_integrity_violation" });
+  }
+  setNumeric(balance, field, nextValue);
+}
+const reserveInventoryCommand = {
+  id: "wms.inventory.reserve",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryReservationCreateSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      await requireWarehouse(trx, ctx, input.warehouseId, scope);
+      const reservationIdempotencyKey = buildReservationIdempotencyKey({
+        sourceType: input.sourceType,
+        sourceId: input.sourceId,
+        catalogVariantId: input.catalogVariantId,
+        warehouseId: input.warehouseId,
+        quantity: input.quantity
+      });
+      const existingReservation = await findExistingActiveReservationByIdempotencyKey(
+        trx,
+        scope,
+        reservationIdempotencyKey
+      );
+      if (existingReservation) {
+        const metadata = extractReservationMetadata(existingReservation);
+        const buckets2 = Array.isArray(metadata.allocatedBuckets) ? metadata.allocatedBuckets : [];
+        return {
+          reservationId: existingReservation.id,
+          allocatedBuckets: serializeAllocationBuckets(buckets2),
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          warehouseId: input.warehouseId,
+          catalogVariantId: input.catalogVariantId,
+          quantity: input.quantity,
+          reservationEntity: existingReservation,
+          touchedBalances: [],
+          idempotentReplay: true
+        };
+      }
+      const strategy = await resolveReservationStrategy(trx, ctx, input, scope);
+      const balances = await listCandidateBalances(trx, ctx, input, scope);
+      const receiptMap = await loadReceivedAtByBucket(trx, balances, scope);
+      const now = /* @__PURE__ */ new Date();
+      const ordered = sortBalancesForStrategy(
+        balances.filter(
+          (balance) => balanceHasEligibleLot(balance, now) && getAvailableQuantity(balance) > 0
+        ),
+        strategy,
+        receiptMap
+      );
+      let remaining = input.quantity;
+      const buckets = [];
+      const touchedBalances = [];
+      for (const balance of ordered) {
+        if (remaining <= 0) break;
+        const available = getAvailableQuantity(balance);
+        if (available <= 0) continue;
+        const quantity = Math.min(available, remaining);
+        const locationId = typeof balance.location === "string" ? balance.location : balance.location.id;
+        const lotIdRaw = balance.lot ?? null;
+        const lotId = typeof lotIdRaw === "string" ? lotIdRaw : lotIdRaw?.id ?? null;
+        const persistedBalance = await findExactBalanceForUpdate(trx, scope, {
+          warehouseId: input.warehouseId,
+          locationId,
+          catalogVariantId: input.catalogVariantId,
+          lotId: lotId ?? void 0,
+          serialNumber: balance.serialNumber ?? void 0
+        });
+        if (!persistedBalance) {
+          throw new CrudHttpError(409, { error: "invalid_tracking_state" });
+        }
+        setNumeric(
+          persistedBalance,
+          "quantityReserved",
+          toNumber(persistedBalance.quantityReserved) + quantity
+        );
+        touchedBalances.push(persistedBalance);
+        buckets.push({
+          balanceId: persistedBalance.id,
+          locationId,
+          lotId,
+          serialNumber: balance.serialNumber ?? null,
+          quantity
+        });
+        remaining -= quantity;
+      }
+      requireSufficientAvailability(remaining);
+      let reservation;
+      try {
+        reservation = trx.create(InventoryReservation, {
+          organizationId: scope.organizationId,
+          tenantId: scope.tenantId,
+          warehouse: trx.getReference(Warehouse, input.warehouseId),
+          catalogVariantId: input.catalogVariantId,
+          lot: buckets.length === 1 && buckets[0].lotId ? trx.getReference(InventoryLot, buckets[0].lotId) : null,
+          serialNumber: buckets.length === 1 ? buckets[0].serialNumber : null,
+          quantity: toNumericString(input.quantity),
+          sourceType: input.sourceType,
+          sourceId: input.sourceId,
+          expiresAt: input.expiresAt ?? null,
+          status: "active",
+          idempotencyKey: reservationIdempotencyKey,
+          metadata: {
+            ...input.metadata ?? {},
+            allocatedBuckets: buckets,
+            allocationState: "reserved",
+            strategy
+          }
+        });
+        trx.persist(reservation);
+        await trx.flush();
+      } catch (error) {
+        if (!isUniqueConstraintError(error)) throw error;
+        const raced = await findExistingActiveReservationByIdempotencyKey(
+          trx,
+          scope,
+          reservationIdempotencyKey
+        );
+        if (!raced) throw error;
+        const metadata = extractReservationMetadata(raced);
+        const racedBuckets = Array.isArray(metadata.allocatedBuckets) ? metadata.allocatedBuckets : [];
+        return {
+          reservationId: raced.id,
+          allocatedBuckets: serializeAllocationBuckets(racedBuckets),
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          warehouseId: input.warehouseId,
+          catalogVariantId: input.catalogVariantId,
+          quantity: input.quantity,
+          reservationEntity: raced,
+          touchedBalances: [],
+          idempotentReplay: true
+        };
+      }
+      return {
+        reservationId: reservation.id,
+        allocatedBuckets: serializeAllocationBuckets(buckets),
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        warehouseId: input.warehouseId,
+        catalogVariantId: input.catalogVariantId,
+        quantity: input.quantity,
+        reservationEntity: reservation,
+        touchedBalances,
+        idempotentReplay: false
+      };
+    });
+    if (!result.idempotentReplay) {
+      await emitInventorySideEffects(ctx, {
+        reservations: [{ entity: result.reservationEntity, action: "created" }],
+        balances: result.touchedBalances.map((entity) => ({ entity, action: "updated" }))
+      });
+      void emitWmsEvent("wms.inventory.reserved", {
+        id: result.reservationId,
+        reservationId: result.reservationId,
+        warehouseId: result.warehouseId,
+        catalogVariantId: result.catalogVariantId,
+        quantity: toNumericString(result.quantity),
+        tenantId: result.tenantId,
+        organizationId: result.organizationId
+      }).catch(() => void 0);
+      void emitLowStockEventIfNeeded(
+        resolveEm(ctx),
+        ctx,
+        { tenantId: result.tenantId, organizationId: result.organizationId },
+        result.catalogVariantId
+      ).catch(() => void 0);
+    }
+    return {
+      reservationId: result.reservationId,
+      allocatedBuckets: result.allocatedBuckets
+    };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.reserve",
+    fallbackLabel: "Reserve inventory",
+    resourceKind: WMS_INVENTORY_RESERVATION_RESOURCE,
+    resourceId: result?.reservationId ?? null,
+    parentResourceId: input?.warehouseId && input?.catalogVariantId ? `${input.warehouseId}:${input.catalogVariantId}` : null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+const releaseInventoryReservationCommand = {
+  id: "wms.inventory.release",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryReservationReleaseSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      const reservation = await requireReservation(trx, ctx, input.reservationId, scope, true);
+      const metadata = extractReservationMetadata(reservation);
+      const buckets = Array.isArray(metadata.allocatedBuckets) ? metadata.allocatedBuckets : [];
+      const allocationState = metadata.allocationState ?? "reserved";
+      const touchedBalances = [];
+      for (const bucket of buckets) {
+        const balance = await findReservationBucketBalance(
+          trx,
+          scope,
+          reservation,
+          bucket
+        );
+        if (!balance) continue;
+        if (allocationState === "allocated") {
+          enforceNonNegativeBalance(
+            balance,
+            "quantityAllocated",
+            toNumber(balance.quantityAllocated) - bucket.quantity,
+            reservation.id,
+            scope
+          );
+        } else {
+          enforceNonNegativeBalance(
+            balance,
+            "quantityReserved",
+            toNumber(balance.quantityReserved) - bucket.quantity,
+            reservation.id,
+            scope
+          );
+        }
+        touchedBalances.push(balance);
+      }
+      reservation.status = "released";
+      reservation.metadata = {
+        ...metadata,
+        releasedReason: input.reason,
+        releasedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await trx.flush();
+      return {
+        reservationId: reservation.id,
+        warehouseId: typeof reservation.warehouse === "string" ? reservation.warehouse : reservation.warehouse.id,
+        catalogVariantId: reservation.catalogVariantId,
+        quantity: reservation.quantity,
+        tenantId: reservation.tenantId,
+        organizationId: reservation.organizationId,
+        reservationEntity: reservation,
+        touchedBalances
+      };
+    });
+    await emitInventorySideEffects(ctx, {
+      reservations: [{ entity: result.reservationEntity, action: "updated" }],
+      balances: result.touchedBalances.map((entity) => ({ entity, action: "updated" }))
+    });
+    void emitWmsEvent("wms.inventory.released", {
+      id: result.reservationId,
+      reservationId: result.reservationId,
+      warehouseId: result.warehouseId,
+      catalogVariantId: result.catalogVariantId,
+      quantity: result.quantity,
+      tenantId: result.tenantId,
+      organizationId: result.organizationId
+    }).catch(() => void 0);
+    void emitLowStockEventIfNeeded(
+      resolveEm(ctx),
+      ctx,
+      { tenantId: result.tenantId, organizationId: result.organizationId },
+      result.catalogVariantId
+    ).catch(() => void 0);
+    return { reservationId: result.reservationId };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.release",
+    fallbackLabel: "Release inventory reservation",
+    resourceKind: WMS_INVENTORY_RESERVATION_RESOURCE,
+    resourceId: result?.reservationId ?? input?.reservationId ?? null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+const allocateInventoryReservationCommand = {
+  id: "wms.inventory.allocate",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryReservationAllocateSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      const reservation = await requireReservation(trx, ctx, input.reservationId, scope, true);
+      const metadata = extractReservationMetadata(reservation);
+      if (metadata.allocationState === "allocated") {
+        return {
+          reservationId: reservation.id,
+          allocationState: "allocated",
+          warehouseId: typeof reservation.warehouse === "string" ? reservation.warehouse : reservation.warehouse.id,
+          catalogVariantId: reservation.catalogVariantId,
+          quantity: reservation.quantity,
+          tenantId: reservation.tenantId,
+          organizationId: reservation.organizationId,
+          reservationEntity: reservation,
+          touchedBalances: []
+        };
+      }
+      const buckets = Array.isArray(metadata.allocatedBuckets) ? metadata.allocatedBuckets : [];
+      const touchedBalances = [];
+      for (const bucket of buckets) {
+        const balance = await findReservationBucketBalance(
+          trx,
+          scope,
+          reservation,
+          bucket
+        );
+        if (!balance) throw new CrudHttpError(409, { error: "invalid_tracking_state" });
+        if (toNumber(balance.quantityReserved) < bucket.quantity - 1e-6) {
+          throw new CrudHttpError(409, { error: "invalid_tracking_state" });
+        }
+        setNumeric(
+          balance,
+          "quantityReserved",
+          toNumber(balance.quantityReserved) - bucket.quantity
+        );
+        setNumeric(
+          balance,
+          "quantityAllocated",
+          toNumber(balance.quantityAllocated) + bucket.quantity
+        );
+        touchedBalances.push(balance);
+      }
+      reservation.metadata = {
+        ...metadata,
+        allocationState: "allocated",
+        allocatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await trx.flush();
+      return {
+        reservationId: reservation.id,
+        allocationState: "allocated",
+        warehouseId: typeof reservation.warehouse === "string" ? reservation.warehouse : reservation.warehouse.id,
+        catalogVariantId: reservation.catalogVariantId,
+        quantity: reservation.quantity,
+        tenantId: reservation.tenantId,
+        organizationId: reservation.organizationId,
+        reservationEntity: reservation,
+        touchedBalances
+      };
+    });
+    await emitInventorySideEffects(ctx, {
+      reservations: [{ entity: result.reservationEntity, action: "updated" }],
+      balances: result.touchedBalances.map((entity) => ({ entity, action: "updated" }))
+    });
+    void emitWmsEvent("wms.inventory.allocated", {
+      id: result.reservationId,
+      reservationId: result.reservationId,
+      warehouseId: result.warehouseId,
+      catalogVariantId: result.catalogVariantId,
+      quantity: result.quantity,
+      tenantId: result.tenantId,
+      organizationId: result.organizationId
+    }).catch(() => void 0);
+    return { reservationId: result.reservationId, allocationState: result.allocationState };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.allocate",
+    fallbackLabel: "Allocate inventory reservation",
+    resourceKind: WMS_INVENTORY_RESERVATION_RESOURCE,
+    resourceId: result?.reservationId ?? input?.reservationId ?? null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+const adjustInventoryCommand = {
+  id: "wms.inventory.adjust",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryAdjustSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      await requireWarehouse(trx, ctx, input.warehouseId, scope);
+      const location = await requireLocation(trx, ctx, input.locationId, scope);
+      const locationWarehouseId = typeof location.warehouse === "string" ? location.warehouse : location.warehouse.id;
+      if (locationWarehouseId !== input.warehouseId) {
+        throw new CrudHttpError(422, { error: "invalid_location" });
+      }
+      const { balance, created: balanceWasNew } = await upsertBalanceBucket(trx, scope, {
+        warehouseId: input.warehouseId,
+        locationId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId,
+        serialNumber: input.serialNumber
+      });
+      const delta = input.delta;
+      const performedAt = input.performedAt ?? /* @__PURE__ */ new Date();
+      const movementInput = {
+        warehouseId: input.warehouseId,
+        locationToId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId ?? null,
+        serialNumber: input.serialNumber ?? null,
+        quantity: delta,
+        type: "adjust",
+        referenceType: input.referenceType,
+        referenceId: input.referenceId,
+        performedBy: input.performedBy,
+        performedAt,
+        receivedAt: performedAt,
+        reason: input.reason,
+        reasonCode: input.reasonCode ?? null,
+        metadata: input.metadata ?? null
+      };
+      const idempotencyKey = buildMovementIdempotencyKey({
+        referenceType: movementInput.referenceType,
+        referenceId: movementInput.referenceId,
+        type: movementInput.type,
+        warehouseId: movementInput.warehouseId,
+        locationFromId: movementInput.locationFromId,
+        locationToId: movementInput.locationToId,
+        catalogVariantId: movementInput.catalogVariantId,
+        lotId: movementInput.lotId,
+        serialNumber: movementInput.serialNumber,
+        quantity: movementInput.quantity
+      });
+      const existingMovement = await findExistingMovementByIdempotencyKey(trx, scope, idempotencyKey);
+      if (existingMovement) {
+        return {
+          movementId: existingMovement.id,
+          warehouseId: input.warehouseId,
+          catalogVariantId: input.catalogVariantId,
+          quantity: delta,
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          movementEntity: existingMovement,
+          balanceEntity: balance,
+          balanceAction: "updated",
+          idempotentReplay: true
+        };
+      }
+      if (delta < 0 && getAvailableQuantity(balance) < Math.abs(delta) - 1e-6) {
+        throw new CrudHttpError(409, { error: "insufficient_stock" });
+      }
+      setNumeric(
+        balance,
+        "quantityOnHand",
+        toNumber(balance.quantityOnHand) + delta
+      );
+      const { movement } = await persistMovementWithIdempotency(trx, scope, movementInput);
+      await trx.flush();
+      return {
+        movementId: movement.id,
+        warehouseId: input.warehouseId,
+        catalogVariantId: input.catalogVariantId,
+        quantity: delta,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        movementEntity: movement,
+        balanceEntity: balance,
+        balanceAction: balanceWasNew ? "created" : "updated",
+        idempotentReplay: false
+      };
+    });
+    if (!result.idempotentReplay) {
+      await emitInventorySideEffects(ctx, {
+        movements: [{ entity: result.movementEntity, action: "created" }],
+        balances: [{ entity: result.balanceEntity, action: result.balanceAction }]
+      });
+      void emitWmsEvent("wms.inventory.adjusted", {
+        id: result.movementId,
+        movementId: result.movementId,
+        warehouseId: result.warehouseId,
+        catalogVariantId: result.catalogVariantId,
+        quantity: toNumericString(result.quantity),
+        tenantId: result.tenantId,
+        organizationId: result.organizationId
+      }).catch(() => void 0);
+      void emitLowStockEventIfNeeded(
+        resolveEm(ctx),
+        ctx,
+        { tenantId: result.tenantId, organizationId: result.organizationId },
+        result.catalogVariantId
+      ).catch(() => void 0);
+    }
+    return { movementId: result.movementId };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.adjust",
+    fallbackLabel: "Adjust inventory",
+    resourceKind: WMS_INVENTORY_MOVEMENT_RESOURCE,
+    resourceId: result?.movementId ?? null,
+    parentResourceId: input?.warehouseId && input?.catalogVariantId ? `${input.warehouseId}:${input.catalogVariantId}` : null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+const receiveInventoryCommand = {
+  id: "wms.inventory.receive",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryReceiveSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      await requireWarehouse(trx, ctx, input.warehouseId, scope);
+      const location = await requireLocation(trx, ctx, input.locationId, scope);
+      const locationWarehouseId = typeof location.warehouse === "string" ? location.warehouse : location.warehouse.id;
+      if (locationWarehouseId !== input.warehouseId) {
+        throw new CrudHttpError(422, { error: "invalid_location" });
+      }
+      const profile = await loadProfileForVariant(trx, ctx, input.catalogVariantId, scope);
+      const resolvedLotId = await resolveReceiveLotId(trx, ctx, scope, input);
+      enforceInventoryTrackingRequirements(profile, {
+        lotId: resolvedLotId ?? null,
+        serialNumber: input.serialNumber ?? null
+      });
+      const { balance, created: balanceWasNew } = await upsertBalanceBucket(trx, scope, {
+        warehouseId: input.warehouseId,
+        locationId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: resolvedLotId,
+        serialNumber: input.serialNumber
+      });
+      const receivedAt = input.receivedAt ?? input.performedAt ?? /* @__PURE__ */ new Date();
+      const performedAt = input.performedAt ?? receivedAt;
+      const movementInput = {
+        warehouseId: input.warehouseId,
+        locationToId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: resolvedLotId ?? null,
+        serialNumber: input.serialNumber ?? null,
+        quantity: input.quantity,
+        type: "receipt",
+        referenceType: input.referenceType,
+        referenceId: input.referenceId,
+        performedBy: input.performedBy,
+        performedAt,
+        receivedAt,
+        reason: input.reason,
+        metadata: input.metadata ?? null
+      };
+      const idempotencyKey = buildMovementIdempotencyKey({
+        referenceType: movementInput.referenceType,
+        referenceId: movementInput.referenceId,
+        type: movementInput.type,
+        warehouseId: movementInput.warehouseId,
+        locationFromId: movementInput.locationFromId,
+        locationToId: movementInput.locationToId,
+        catalogVariantId: movementInput.catalogVariantId,
+        lotId: movementInput.lotId,
+        serialNumber: movementInput.serialNumber,
+        quantity: movementInput.quantity
+      });
+      const existingMovement = await findExistingMovementByIdempotencyKey(trx, scope, idempotencyKey);
+      if (existingMovement) {
+        return {
+          movementId: existingMovement.id,
+          warehouseId: input.warehouseId,
+          locationId: input.locationId,
+          catalogVariantId: input.catalogVariantId,
+          quantity: input.quantity,
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          movementEntity: existingMovement,
+          balanceEntity: balance,
+          balanceAction: "updated",
+          idempotentReplay: true
+        };
+      }
+      setNumeric(
+        balance,
+        "quantityOnHand",
+        toNumber(balance.quantityOnHand) + input.quantity
+      );
+      const { movement } = await persistMovementWithIdempotency(trx, scope, movementInput);
+      await trx.flush();
+      return {
+        movementId: movement.id,
+        warehouseId: input.warehouseId,
+        locationId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        quantity: input.quantity,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        movementEntity: movement,
+        balanceEntity: balance,
+        balanceAction: balanceWasNew ? "created" : "updated",
+        idempotentReplay: false
+      };
+    });
+    if (!result.idempotentReplay) {
+      await emitInventorySideEffects(ctx, {
+        movements: [{ entity: result.movementEntity, action: "created" }],
+        balances: [{ entity: result.balanceEntity, action: result.balanceAction }]
+      });
+      void emitWmsEvent("wms.inventory.received", {
+        id: result.movementId,
+        movementId: result.movementId,
+        warehouseId: result.warehouseId,
+        locationId: result.locationId,
+        catalogVariantId: result.catalogVariantId,
+        quantity: toNumericString(result.quantity),
+        tenantId: result.tenantId,
+        organizationId: result.organizationId
+      }).catch(() => void 0);
+      void emitLowStockEventIfNeeded(
+        resolveEm(ctx),
+        ctx,
+        { tenantId: result.tenantId, organizationId: result.organizationId },
+        result.catalogVariantId
+      ).catch(() => void 0);
+    }
+    return { movementId: result.movementId };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.receive",
+    fallbackLabel: "Receive inventory",
+    resourceKind: WMS_INVENTORY_MOVEMENT_RESOURCE,
+    resourceId: result?.movementId ?? null,
+    parentResourceId: input?.warehouseId && input?.catalogVariantId ? `${input.warehouseId}:${input.catalogVariantId}` : null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+const moveInventoryCommand = {
+  id: "wms.inventory.move",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryMoveSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      await requireWarehouse(trx, ctx, input.warehouseId, scope);
+      const sourceLocation = await requireLocation(trx, ctx, input.fromLocationId, scope);
+      const targetLocation = await requireLocation(trx, ctx, input.toLocationId, scope);
+      const sourceWarehouseId = typeof sourceLocation.warehouse === "string" ? sourceLocation.warehouse : sourceLocation.warehouse.id;
+      const targetWarehouseId = typeof targetLocation.warehouse === "string" ? targetLocation.warehouse : targetLocation.warehouse.id;
+      if (sourceWarehouseId !== input.warehouseId || targetWarehouseId !== input.warehouseId) {
+        throw new CrudHttpError(422, { error: "invalid_location" });
+      }
+      const sourceResult = await upsertBalanceBucket(trx, scope, {
+        warehouseId: input.warehouseId,
+        locationId: input.fromLocationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId,
+        serialNumber: input.serialNumber
+      });
+      const sourceBalance = sourceResult.balance;
+      const sourceBalanceAction = sourceResult.created ? "created" : "updated";
+      const targetResult = await upsertBalanceBucket(trx, scope, {
+        warehouseId: input.warehouseId,
+        locationId: input.toLocationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId,
+        serialNumber: input.serialNumber
+      });
+      const targetBalance = targetResult.balance;
+      const targetBalanceAction = targetResult.created ? "created" : "updated";
+      const performedAt = input.performedAt ?? /* @__PURE__ */ new Date();
+      const receivedAt = await resolveReceivedAtForBalance(trx, sourceBalance, scope, performedAt);
+      const movementInput = {
+        warehouseId: input.warehouseId,
+        locationFromId: input.fromLocationId,
+        locationToId: input.toLocationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId ?? null,
+        serialNumber: input.serialNumber ?? null,
+        quantity: input.quantity,
+        type: input.type ?? "transfer",
+        referenceType: input.referenceType,
+        referenceId: input.referenceId,
+        performedBy: input.performedBy,
+        performedAt,
+        receivedAt,
+        reason: input.reason,
+        reasonCode: input.reasonCode ?? null,
+        metadata: input.metadata ?? null
+      };
+      const idempotencyKey = buildMovementIdempotencyKey({
+        referenceType: movementInput.referenceType,
+        referenceId: movementInput.referenceId,
+        type: movementInput.type,
+        warehouseId: movementInput.warehouseId,
+        locationFromId: movementInput.locationFromId,
+        locationToId: movementInput.locationToId,
+        catalogVariantId: movementInput.catalogVariantId,
+        lotId: movementInput.lotId,
+        serialNumber: movementInput.serialNumber,
+        quantity: movementInput.quantity
+      });
+      const existingMovement = await findExistingMovementByIdempotencyKey(trx, scope, idempotencyKey);
+      if (existingMovement) {
+        return {
+          movementId: existingMovement.id,
+          warehouseId: input.warehouseId,
+          catalogVariantId: input.catalogVariantId,
+          quantity: input.quantity,
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          movementEntity: existingMovement,
+          balances: [
+            { entity: sourceBalance, action: sourceBalanceAction },
+            { entity: targetBalance, action: targetBalanceAction }
+          ],
+          idempotentReplay: true
+        };
+      }
+      if (getAvailableQuantity(sourceBalance) < input.quantity - 1e-6) {
+        throw new CrudHttpError(409, { error: "insufficient_stock" });
+      }
+      setNumeric(
+        sourceBalance,
+        "quantityOnHand",
+        toNumber(sourceBalance.quantityOnHand) - input.quantity
+      );
+      setNumeric(
+        targetBalance,
+        "quantityOnHand",
+        toNumber(targetBalance.quantityOnHand) + input.quantity
+      );
+      const { movement } = await persistMovementWithIdempotency(trx, scope, movementInput);
+      await trx.flush();
+      return {
+        movementId: movement.id,
+        warehouseId: input.warehouseId,
+        catalogVariantId: input.catalogVariantId,
+        quantity: input.quantity,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        movementEntity: movement,
+        balances: [
+          { entity: sourceBalance, action: sourceBalanceAction },
+          { entity: targetBalance, action: targetBalanceAction }
+        ],
+        idempotentReplay: false
+      };
+    });
+    if (!result.idempotentReplay) {
+      await emitInventorySideEffects(ctx, {
+        movements: [{ entity: result.movementEntity, action: "created" }],
+        balances: result.balances
+      });
+      void emitWmsEvent("wms.inventory.moved", {
+        id: result.movementId,
+        movementId: result.movementId,
+        warehouseId: result.warehouseId,
+        catalogVariantId: result.catalogVariantId,
+        quantity: toNumericString(result.quantity),
+        tenantId: result.tenantId,
+        organizationId: result.organizationId
+      }).catch(() => void 0);
+      void emitLowStockEventIfNeeded(
+        resolveEm(ctx),
+        ctx,
+        { tenantId: result.tenantId, organizationId: result.organizationId },
+        result.catalogVariantId
+      ).catch(() => void 0);
+    }
+    return { movementId: result.movementId };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.move",
+    fallbackLabel: "Move inventory",
+    resourceKind: WMS_INVENTORY_MOVEMENT_RESOURCE,
+    resourceId: result?.movementId ?? null,
+    parentResourceId: input?.warehouseId && input?.catalogVariantId ? `${input.warehouseId}:${input.catalogVariantId}` : null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+const cycleCountInventoryCommand = {
+  id: "wms.inventory.cycleCount",
+  // See "WMS Inventory Mutation Commands — Undo Policy" at top of file.
+  isUndoable: false,
+  async execute(rawInput, ctx) {
+    const input = inventoryCycleCountSchema.parse(rawInput ?? {});
+    ensureTenantScope(ctx, input.tenantId);
+    ensureOrganizationScope(ctx, input.organizationId);
+    const em = resolveEm(ctx);
+    const result = await runInTransaction(em, async (trx) => {
+      const scope = resolveScope(ctx, input);
+      await requireWarehouse(trx, ctx, input.warehouseId, scope);
+      const location = await requireLocation(trx, ctx, input.locationId, scope);
+      const locationWarehouseId = typeof location.warehouse === "string" ? location.warehouse : location.warehouse.id;
+      if (locationWarehouseId !== input.warehouseId) {
+        throw new CrudHttpError(422, { error: "invalid_location" });
+      }
+      const { balance, created: balanceWasNew } = await upsertBalanceBucket(trx, scope, {
+        warehouseId: input.warehouseId,
+        locationId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId,
+        serialNumber: input.serialNumber
+      });
+      const currentOnHand = toNumber(balance.quantityOnHand);
+      const delta = input.countedQuantity - currentOnHand;
+      if (delta === 0) {
+        return {
+          adjustmentDelta: "0",
+          movementId: null,
+          warehouseId: input.warehouseId,
+          catalogVariantId: input.catalogVariantId,
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          movementEntity: null,
+          balanceEntity: balance,
+          balanceAction: "updated"
+        };
+      }
+      if (!input.autoAdjust) {
+        throw new CrudHttpError(422, { error: "auto_adjust_required" });
+      }
+      const performedAt = input.performedAt ?? /* @__PURE__ */ new Date();
+      const receivedAt = await resolveReceivedAtForBalance(trx, balance, scope, performedAt);
+      const movementInput = {
+        warehouseId: input.warehouseId,
+        locationToId: input.locationId,
+        catalogVariantId: input.catalogVariantId,
+        lotId: input.lotId ?? null,
+        serialNumber: input.serialNumber ?? null,
+        quantity: delta,
+        type: "cycle_count",
+        referenceType: "manual",
+        referenceId: input.referenceId,
+        performedBy: input.performedBy,
+        performedAt,
+        receivedAt,
+        reason: input.reason,
+        metadata: input.metadata ?? null
+      };
+      const idempotencyKey = buildMovementIdempotencyKey({
+        referenceType: movementInput.referenceType,
+        referenceId: movementInput.referenceId,
+        type: movementInput.type,
+        warehouseId: movementInput.warehouseId,
+        locationFromId: movementInput.locationFromId,
+        locationToId: movementInput.locationToId,
+        catalogVariantId: movementInput.catalogVariantId,
+        lotId: movementInput.lotId,
+        serialNumber: movementInput.serialNumber,
+        quantity: movementInput.quantity
+      });
+      const existingMovement = await findExistingMovementByIdempotencyKey(trx, scope, idempotencyKey);
+      if (existingMovement) {
+        return {
+          adjustmentDelta: toNumericString(delta),
+          movementId: existingMovement.id,
+          warehouseId: input.warehouseId,
+          catalogVariantId: input.catalogVariantId,
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+          movementEntity: existingMovement,
+          balanceEntity: balance,
+          balanceAction: "updated",
+          idempotentReplay: true
+        };
+      }
+      setNumeric(
+        balance,
+        "quantityOnHand",
+        input.countedQuantity
+      );
+      const { movement } = await persistMovementWithIdempotency(trx, scope, movementInput);
+      await trx.flush();
+      return {
+        adjustmentDelta: toNumericString(delta),
+        movementId: movement.id,
+        warehouseId: input.warehouseId,
+        catalogVariantId: input.catalogVariantId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+        movementEntity: movement,
+        balanceEntity: balance,
+        balanceAction: balanceWasNew ? "created" : "updated",
+        idempotentReplay: false
+      };
+    });
+    if (!result.idempotentReplay) {
+      await emitInventorySideEffects(ctx, {
+        movements: result.movementEntity ? [{ entity: result.movementEntity, action: "created" }] : [],
+        balances: [{ entity: result.balanceEntity, action: result.balanceAction }]
+      });
+      if (result.movementId) {
+        void emitWmsEvent("wms.inventory.reconciled", {
+          id: result.movementId,
+          movementId: result.movementId,
+          warehouseId: result.warehouseId,
+          catalogVariantId: result.catalogVariantId,
+          adjustmentDelta: result.adjustmentDelta,
+          tenantId: result.tenantId,
+          organizationId: result.organizationId
+        }).catch(() => void 0);
+        void emitLowStockEventIfNeeded(
+          resolveEm(ctx),
+          ctx,
+          { tenantId: result.tenantId, organizationId: result.organizationId },
+          result.catalogVariantId
+        ).catch(() => void 0);
+      }
+    }
+    return {
+      adjustmentDelta: result.adjustmentDelta,
+      movementId: result.movementId ?? null
+    };
+  },
+  buildLog: async ({ input, result, ctx }) => buildMutationLog({
+    actionKey: "wms.audit.inventory.cycleCount",
+    fallbackLabel: "Run cycle count reconciliation",
+    resourceKind: WMS_INVENTORY_MOVEMENT_RESOURCE,
+    resourceId: result?.movementId ?? null,
+    parentResourceId: input?.warehouseId && input?.catalogVariantId ? `${input.warehouseId}:${input.catalogVariantId}` : null,
+    tenantId: input?.tenantId ?? ctx.auth?.tenantId ?? null,
+    organizationId: input?.organizationId ?? ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+    cacheAliases: [WMS_INVENTORY_BALANCE_RESOURCE]
+  })
+};
+registerCommand(reserveInventoryCommand);
+registerCommand(releaseInventoryReservationCommand);
+registerCommand(allocateInventoryReservationCommand);
+registerCommand(adjustInventoryCommand);
+registerCommand(receiveInventoryCommand);
+registerCommand(moveInventoryCommand);
+registerCommand(cycleCountInventoryCommand);
+//# sourceMappingURL=inventory-actions.js.map