@open-mercato/core 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4544.1.71c003c861

package/src/modules/sales/commands/documentAddresses.ts

@@ -1,6 +1,8 @@
 // @ts-nocheck
 
 import { registerCommand, type CommandHandler } from '@open-mercato/shared/lib/commands'
+import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import {
@@ -8,12 +10,123 @@ import {
   documentAddressDeleteSchema,
   documentAddressUpdateSchema,
   type DocumentAddressCreateInput,
+  type DocumentAddressDeleteInput,
   type DocumentAddressUpdateInput,
 } from '../data/validators'
 import { SalesDocumentAddress, SalesOrder, SalesQuote } from '../data/entities'
-import { ensureOrganizationScope, ensureSameScope, ensureTenantScope, assertFound } from './shared'
+import { ensureOrganizationScope, ensureSameScope, ensureTenantScope, assertFound, extractUndoPayload } from './shared'
 import { loadSalesSettings } from './settings'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { E } from '#generated/entities.ids.generated'
+
+const DOCUMENT_ADDRESS_ENTITY_TYPE = E.sales.sales_document_address
+
+type DocumentAddressSnapshot = {
+  id: string
+  organizationId: string
+  tenantId: string
+  documentId: string
+  documentKind: 'order' | 'quote'
+  customerAddressId: string | null
+  name: string | null
+  purpose: string | null
+  companyName: string | null
+  addressLine1: string
+  addressLine2: string | null
+  buildingNumber: string | null
+  flatNumber: string | null
+  city: string | null
+  region: string | null
+  postalCode: string | null
+  country: string | null
+  latitude: number | null
+  longitude: number | null
+}
+
+type DocumentAddressUndoPayload = {
+  before?: DocumentAddressSnapshot | null
+  after?: DocumentAddressSnapshot | null
+}
+
+function snapshotDocumentAddress(entity: SalesDocumentAddress): DocumentAddressSnapshot {
+  return {
+    id: entity.id,
+    organizationId: entity.organizationId,
+    tenantId: entity.tenantId,
+    documentId: entity.documentId,
+    documentKind: entity.documentKind as 'order' | 'quote',
+    customerAddressId: entity.customerAddressId ?? null,
+    name: entity.name ?? null,
+    purpose: entity.purpose ?? null,
+    companyName: entity.companyName ?? null,
+    addressLine1: entity.addressLine1,
+    addressLine2: entity.addressLine2 ?? null,
+    buildingNumber: entity.buildingNumber ?? null,
+    flatNumber: entity.flatNumber ?? null,
+    city: entity.city ?? null,
+    region: entity.region ?? null,
+    postalCode: entity.postalCode ?? null,
+    country: entity.country ?? null,
+    latitude: entity.latitude ?? null,
+    longitude: entity.longitude ?? null,
+  }
+}
+
+async function loadDocumentAddressSnapshot(
+  em: EntityManager,
+  id: string
+): Promise<DocumentAddressSnapshot | null> {
+  const entity = await em.findOne(SalesDocumentAddress, { id })
+  return entity ? snapshotDocumentAddress(entity) : null
+}
+
+function applyDocumentAddressSnapshot(em: EntityManager, entity: SalesDocumentAddress, snapshot: DocumentAddressSnapshot): void {
+  entity.organizationId = snapshot.organizationId
+  entity.tenantId = snapshot.tenantId
+  entity.documentId = snapshot.documentId
+  entity.documentKind = snapshot.documentKind
+  entity.customerAddressId = snapshot.customerAddressId
+  entity.name = snapshot.name
+  entity.purpose = snapshot.purpose
+  entity.companyName = snapshot.companyName
+  entity.addressLine1 = snapshot.addressLine1
+  entity.addressLine2 = snapshot.addressLine2
+  entity.buildingNumber = snapshot.buildingNumber
+  entity.flatNumber = snapshot.flatNumber
+  entity.city = snapshot.city
+  entity.region = snapshot.region
+  entity.postalCode = snapshot.postalCode
+  entity.country = snapshot.country
+  entity.latitude = snapshot.latitude
+  entity.longitude = snapshot.longitude
+  entity.order = snapshot.documentKind === 'order' ? em.getReference(SalesOrder, snapshot.documentId) : null
+  entity.quote = snapshot.documentKind === 'quote' ? em.getReference(SalesQuote, snapshot.documentId) : null
+}
+
+async function emitDocumentAddressIndexSideEffects(
+  ctx: { container: { resolve: (name: string) => unknown } },
+  action: 'created' | 'updated' | 'deleted',
+  snapshot: DocumentAddressSnapshot
+): Promise<void> {
+  let dataEngine: DataEngine | null = null
+  try {
+    dataEngine = ctx.container.resolve('dataEngine') as DataEngine
+  } catch {
+    dataEngine = null
+  }
+  if (!dataEngine) return
+  await emitCrudSideEffects({
+    dataEngine,
+    action,
+    entity: snapshot,
+    identifiers: {
+      id: snapshot.id,
+      organizationId: snapshot.organizationId,
+      tenantId: snapshot.tenantId,
+    },
+    indexer: { entityType: DOCUMENT_ADDRESS_ENTITY_TYPE },
+  })
+}
 
 async function requireDocument(
   em: EntityManager,
@@ -90,10 +203,48 @@ const createDocumentAddress: CommandHandler<DocumentAddressCreateInput, { id: st
     await em.persist(entity).flush()
     return { id: entity.id }
   },
+  captureAfter: async (_input, result, ctx) => {
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    return result?.id ? loadDocumentAddressSnapshot(em, result.id) : null
+  },
+  buildLog: async ({ result, snapshots }) => {
+    const after = snapshots.after as DocumentAddressSnapshot | undefined
+    if (!after) return null
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('sales.audit.document_addresses.create', 'Add document address'),
+      resourceKind: 'sales.document_address',
+      resourceId: result.id,
+      parentResourceKind: after.documentKind === 'order' ? 'sales.order' : 'sales.quote',
+      parentResourceId: after.documentId,
+      tenantId: after.tenantId,
+      organizationId: after.organizationId,
+      snapshotAfter: after,
+      payload: { undo: { after } satisfies DocumentAddressUndoPayload },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<DocumentAddressUndoPayload>(logEntry)
+    const after = payload?.after
+    if (!after) return
+    ensureTenantScope(ctx, after.tenantId)
+    ensureOrganizationScope(ctx, after.organizationId)
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const entity = await em.findOne(SalesDocumentAddress, { id: after.id })
+    if (!entity) return
+    await em.remove(entity).flush()
+    await emitDocumentAddressIndexSideEffects(ctx, 'deleted', after)
+  },
 }
 
 const updateDocumentAddress: CommandHandler<DocumentAddressUpdateInput, { id: string }> = {
   id: 'sales.document-addresses.update',
+  async prepare(rawInput, ctx) {
+    const parsed = documentAddressUpdateSchema.parse(rawInput)
+    const em = ctx.container.resolve('em') as EntityManager
+    const snapshot = await loadDocumentAddressSnapshot(em, parsed.id)
+    return snapshot ? { before: snapshot } : {}
+  },
   async execute(rawInput, ctx) {
     const input = documentAddressUpdateSchema.parse(rawInput)
     ensureTenantScope(ctx, input.tenantId)
@@ -133,13 +284,55 @@ const updateDocumentAddress: CommandHandler<DocumentAddressUpdateInput, { id: st
     await em.flush()
     return { id: entity.id }
   },
+  captureAfter: async (_input, result, ctx) => {
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    return result?.id ? loadDocumentAddressSnapshot(em, result.id) : null
+  },
+  buildLog: async ({ result, snapshots }) => {
+    const before = snapshots.before as DocumentAddressSnapshot | undefined
+    const after = snapshots.after as DocumentAddressSnapshot | undefined
+    if (!after) return null
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('sales.audit.document_addresses.update', 'Update document address'),
+      resourceKind: 'sales.document_address',
+      resourceId: result.id,
+      parentResourceKind: after.documentKind === 'order' ? 'sales.order' : 'sales.quote',
+      parentResourceId: after.documentId,
+      tenantId: after.tenantId,
+      organizationId: after.organizationId,
+      snapshotBefore: before ?? null,
+      snapshotAfter: after,
+      payload: { undo: { before: before ?? null, after } satisfies DocumentAddressUndoPayload },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<DocumentAddressUndoPayload>(logEntry)
+    const before = payload?.before
+    if (!before) return
+    ensureTenantScope(ctx, before.tenantId)
+    ensureOrganizationScope(ctx, before.organizationId)
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const entity =
+      (await em.findOne(SalesDocumentAddress, { id: before.id })) ??
+      em.create(SalesDocumentAddress, { id: before.id } as Partial<SalesDocumentAddress>)
+    applyDocumentAddressSnapshot(em, entity, before)
+    await em.persist(entity).flush()
+    await emitDocumentAddressIndexSideEffects(ctx, 'updated', before)
+  },
 }
 
 const deleteDocumentAddress: CommandHandler<
-  { id: string; documentId: string; documentKind: 'order' | 'quote'; organizationId: string; tenantId: string },
-  { ok: true }
+  DocumentAddressDeleteInput,
+  { ok: true; id: string }
 > = {
   id: 'sales.document-addresses.delete',
+  async prepare(rawInput, ctx) {
+    const parsed = documentAddressDeleteSchema.parse(rawInput)
+    const em = ctx.container.resolve('em') as EntityManager
+    const snapshot = await loadDocumentAddressSnapshot(em, parsed.id)
+    return snapshot ? { before: snapshot } : {}
+  },
   async execute(rawInput, ctx) {
     const input = documentAddressDeleteSchema.parse(rawInput)
     ensureTenantScope(ctx, input.tenantId)
@@ -159,7 +352,36 @@ const deleteDocumentAddress: CommandHandler<
       })
     }
     await em.remove(entity).flush()
-    return { ok: true }
+    return { ok: true, id: input.id }
+  },
+  buildLog: async ({ result, snapshots }) => {
+    const before = snapshots.before as DocumentAddressSnapshot | undefined
+    if (!before) return null
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('sales.audit.document_addresses.delete', 'Remove document address'),
+      resourceKind: 'sales.document_address',
+      resourceId: result.id,
+      parentResourceKind: before.documentKind === 'order' ? 'sales.order' : 'sales.quote',
+      parentResourceId: before.documentId,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      payload: { undo: { before } satisfies DocumentAddressUndoPayload },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<DocumentAddressUndoPayload>(logEntry)
+    const before = payload?.before
+    if (!before) return
+    ensureTenantScope(ctx, before.tenantId)
+    ensureOrganizationScope(ctx, before.organizationId)
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const existing = await em.findOne(SalesDocumentAddress, { id: before.id })
+    const entity = existing ?? em.create(SalesDocumentAddress, { id: before.id } as Partial<SalesDocumentAddress>)
+    applyDocumentAddressSnapshot(em, entity, before)
+    await em.persist(entity).flush()
+    await emitDocumentAddressIndexSideEffects(ctx, 'created', before)
   },
 }
 

package/src/modules/sales/commands/documents.ts

@@ -96,6 +96,9 @@ import {
   ensureTenantScope,
   extractUndoPayload,
   toNumericString,
+  enforceSalesDocumentOptimisticLock,
+  SALES_RESOURCE_KIND_ORDER,
+  SALES_RESOURCE_KIND_QUOTE,
 } from "./shared";
 import {
   loadShipmentSnapshot,
@@ -4935,6 +4938,7 @@ const updateQuoteCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const shouldInvalidateSentToken = (quote.status ?? null) === "sent";
     if (shouldInvalidateSentToken) {
       quote.acceptanceToken = null;
@@ -4970,6 +4974,13 @@ const updateQuoteCommand: CommandHandler<
               value: "draft",
             });
           }
+        },
+        // Scalar mutations above are persisted by withAtomicFlush's per-phase
+        // flush boundary before the recalc reads below run any query on the same
+        // EntityManager. MikroORM v7 would otherwise silently discard pending
+        // scalar changes on `quote` when the `em.find` line/adjustment lookups
+        // reset the changeset (see SPEC-018).
+        async () => {
           if (shouldRecalculateTotals) {
             const [existingLines, adjustments] = await Promise.all([
               em.find(
@@ -5183,6 +5194,14 @@ const updateOrderCommand: CommandHandler<
             input: parsed,
             em,
           });
+        },
+        // Scalar mutations above are persisted by withAtomicFlush's per-phase
+        // flush boundary before the recalc reads and the status-change-note
+        // lookup below run any query on the same EntityManager. MikroORM v7 would
+        // otherwise silently discard pending scalar changes on `order` when the
+        // `em.find` lines/adjustments or appendOrderStatusChangeNote queries
+        // reset the changeset (see SPEC-018).
+        async () => {
           if (shouldRecalculateTotals) {
             const [existingLines, adjustments] = await Promise.all([
               em.find(
@@ -5984,6 +6003,7 @@ const convertQuoteToOrderCommand: CommandHandler<
           ),
         });
       ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
+      enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
       const snapshot = await loadQuoteSnapshot(em, payload.quoteId);
       if (!snapshot)
         throw new CrudHttpError(404, {
@@ -6453,6 +6473,7 @@ const orderLineUpsertCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
@@ -6773,6 +6794,7 @@ const orderLineDeleteCommand: CommandHandler<
         ),
       });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     const shipmentCount = await em.count(SalesShipmentItem, {
       orderLine: parsed.id,
       shipment: { deletedAt: null },
@@ -6943,6 +6965,7 @@ const quoteLineUpsertCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesQuoteLine, { quote }, { orderBy: { lineNumber: "asc" } }),
       em.find(
@@ -7254,6 +7277,7 @@ const quoteLineDeleteCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const existingLines = await em.find(
       SalesQuoteLine,
       { quote },
@@ -7407,6 +7431,7 @@ const orderAdjustmentUpsertCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -7700,6 +7725,7 @@ const orderAdjustmentDeleteCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
@@ -7864,6 +7890,7 @@ const quoteAdjustmentUpsertCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -8155,6 +8182,7 @@ const quoteAdjustmentDeleteCommand: CommandHandler<
     if (!quote)
       throw new CrudHttpError(404, { error: "Sales quote not found" });
     ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
+    enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesQuoteLine, { quote }, { orderBy: { lineNumber: "asc" } }),

package/src/modules/sales/commands/returns.ts

@@ -12,7 +12,7 @@ import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/
 import { SalesDocumentNumberGenerator } from '../services/salesDocumentNumberGenerator'
 import type { SalesCalculationService } from '../services/salesCalculationService'
 import type { SalesAdjustmentDraft, SalesLineSnapshot, SalesDocumentCalculationResult } from '../lib/types'
-import { cloneJson, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString } from './shared'
+import { cloneJson, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString, enforceSalesDocumentOptimisticLock, SALES_RESOURCE_KIND_ORDER } from './shared'
 import { SalesOrder, SalesOrderAdjustment, SalesOrderLine, SalesReturn, SalesReturnLine } from '../data/entities'
 import { returnCreateSchema, type ReturnCreateInput } from '../data/validators'
 import { E } from '#generated/entities.ids.generated'
@@ -286,6 +286,7 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
         throw new CrudHttpError(404, { error: translate('sales.returns.orderMissing', 'Order not found.') })
       }
       ensureSameScope(order, input.organizationId, input.tenantId)
+      enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
 
       const orderLines = await findWithDecryption(
         tx,
@@ -476,11 +477,12 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
     // Line reversals, adjustment/return removals, and the order-total recompute
     // interleave queries on the same EntityManager with scalar mutations, so they
     // must run inside an atomic flush to avoid lost updates and partial commits.
+    let lines: SalesOrderLine[] = []
     await withAtomicFlush(
       em,
       [
         async () => {
-          const lines = await findWithDecryption(
+          lines = await findWithDecryption(
             em,
             SalesOrderLine,
             { order: order.id, deletedAt: null },
@@ -496,7 +498,14 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
             line.updatedAt = new Date()
             em.persist(line)
           })
-
+        },
+        // The line returnedQuantity reversals above are persisted by
+        // withAtomicFlush's per-phase flush boundary before the adjustment /
+        // header / return-line lookups below run any query on this
+        // EntityManager. MikroORM v7 would otherwise silently discard the pending
+        // scalar changes on the managed `lines` when the next read resets the
+        // changeset (see SPEC-018).
+        async () => {
           if (after.adjustmentIds.length) {
             const adjustments = await findWithDecryption(
               em,

package/src/modules/sales/commands/shared.ts

@@ -2,10 +2,46 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 export { assertFound } from '@open-mercato/shared/lib/crud/errors'
 export { ensureOrganizationScope, ensureSameScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
 export { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
 
+/** Resource kinds used by the document-aggregate optimistic-lock check. */
+export const SALES_RESOURCE_KIND_ORDER = 'sales.order'
+export const SALES_RESOURCE_KIND_QUOTE = 'sales.quote'
+
+/**
+ * Enforce the document-aggregate OSS optimistic lock for a sales sub-resource
+ * command (lines, adjustments, shipments, payments, returns, quote
+ * conversion). The client sends the parent order/quote's expected `updated_at`
+ * via the optimistic-lock extension header; this compares it against the
+ * already-loaded document and throws the structured 409 on mismatch.
+ *
+ * The parent document is the consistency boundary: sub-resource mutations
+ * recalculate document totals (or transition the document), which dirties the
+ * parent so its `updated_at` advances on flush — meaning concurrent sub-edits
+ * observe each other and conflict. Call this AFTER loading + scope-checking the
+ * document and BEFORE mutating, so `document.updatedAt` is the pre-mutation
+ * version.
+ *
+ * Strictly additive: when the client sends no header the check is a no-op, so
+ * existing API consumers are unaffected. Respects `OM_OPTIMISTIC_LOCK`.
+ */
+export function enforceSalesDocumentOptimisticLock(
+  ctx: CommandRuntimeContext,
+  document: { id: string; updatedAt?: Date | string | null } | null | undefined,
+  resourceKind: string,
+): void {
+  if (!document) return
+  enforceCommandOptimisticLock({
+    resourceKind,
+    resourceId: document.id,
+    current: document.updatedAt ?? null,
+    request: ctx.request ?? null,
+  })
+}
+
 export function cloneJson<T>(value: T): T {
   if (value === null || value === undefined) return value
   return JSON.parse(JSON.stringify(value)) as T

package/src/modules/sales/commands/shipments.ts

@@ -657,11 +657,17 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
         : null
       const normalizedItems = validatedItems?.items ?? null
       const lineMap = validatedItems?.lineMap ?? new Map<string, SalesOrderLine>()
+      // Resolve the status label BEFORE mutating shipment scalars so this
+      // dictionary read does not interleave with (and drop) the pending
+      // shipment changeset under MikroORM v7 (SPEC-018 / #2453 class).
+      const resolvedShipmentStatus = input.statusEntryId !== undefined
+        ? await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null)
+        : undefined
       if (input.shipmentNumber !== undefined) shipmentEntity.shipmentNumber = input.shipmentNumber ?? null
       if (input.shippingMethodId !== undefined) shipmentEntity.shippingMethodId = input.shippingMethodId ?? null
       if (input.statusEntryId !== undefined) {
         shipmentEntity.statusEntryId = input.statusEntryId ?? null
-        shipmentEntity.status = await resolveDictionaryEntryValue(tx, input.statusEntryId ?? null)
+        shipmentEntity.status = resolvedShipmentStatus ?? null
       }
       if (input.carrierName !== undefined) shipmentEntity.carrierName = input.carrierName ?? null
       if (input.trackingNumbers !== undefined) shipmentEntity.trackingNumbers = parseTrackingNumbers(input.trackingNumbers)
@@ -685,6 +691,13 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
       }
       shipmentEntity.updatedAt = new Date()
 
+      // Persist the shipment scalar mutations before the item reads below run on
+      // the same EntityManager. Under MikroORM v7 an interleaved query (the
+      // findWithDecryption on SalesShipmentItem here and in the snapshot step)
+      // resets the identity-map changeset, so shippingMethodId/status/carrier/etc.
+      // would silently not persist even though the write returns 200 (#2453).
+      await tx.flush()
+
       const shouldLoadItems = Boolean(normalizedItems || input.lineStatusEntryId !== undefined)
       const existingItems = shouldLoadItems ? await findWithDecryption(tx, SalesShipmentItem, { shipment: shipmentEntity }, {}, { tenantId: shipmentEntity.tenantId, organizationId: shipmentEntity.organizationId }) : []
       const newItems: SalesShipmentItem[] = []
@@ -758,6 +771,9 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
         }
       }
 
+      // Flush any order/line status mutations applied above before the snapshot
+      // read below queries the same EntityManager (same interleaved-read hazard).
+      await tx.flush()
       const itemsForSnapshot =
         normalizedItems || shouldLoadItems
           ? (normalizedItems ? newItems : existingItems)

package/src/modules/sales/components/AdjustmentKindSettings.tsx

@@ -16,7 +16,8 @@ import {
 import { Input } from '@open-mercato/ui/primitives/input'
 import { Label } from '@open-mercato/ui/primitives/label'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { AppearanceSelector } from '@open-mercato/core/modules/dictionaries/components/AppearanceSelector'
@@ -219,11 +220,15 @@ export function AdjustmentKindSettings() {
           ? JSON.stringify(payload)
           : JSON.stringify({ id: dialog.entry.id, ...payload })
 
-      const call = await apiCall('/api/sales/adjustment-kinds', {
-        method,
-        headers: { 'content-type': 'application/json' },
-        body,
-      })
+      const lockHeader =
+        dialog.mode === 'edit' ? buildOptimisticLockHeader(dialog.entry.updatedAt) : {}
+      const call = await withScopedApiRequestHeaders(lockHeader, () =>
+        apiCall('/api/sales/adjustment-kinds', {
+          method,
+          headers: { 'content-type': 'application/json' },
+          body,
+        })
+      )
       if (!call.ok) {
         await raiseCrudError(call.response, labels.saveError)
       }
@@ -248,11 +253,15 @@ export function AdjustmentKindSettings() {
       })
       if (!confirmed) return
       try {
-        const call = await apiCall('/api/sales/adjustment-kinds', {
-          method: 'DELETE',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ id: entry.id }),
-        })
+        const call = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(entry.updatedAt),
+          () =>
+            apiCall('/api/sales/adjustment-kinds', {
+              method: 'DELETE',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ id: entry.id }),
+            })
+        )
         if (!call.ok) {
           await raiseCrudError(call.response, labels.deleteError)
         }

package/src/modules/sales/components/DocumentNumberSettings.tsx

@@ -128,6 +128,7 @@ export function DocumentNumberSettings() {
         orderNextNumber: Number.parseInt(formState.orderNextNumber, 10) || undefined,
         quoteNextNumber: Number.parseInt(formState.quoteNextNumber, 10) || undefined,
       }
+      // optimistic-lock-exempt: single-row tenant numbering settings blob — no per-record version / concurrent record edit
       const call = await apiCall<SettingsResponse>('/api/sales/settings/document-numbers', {
         method: 'PUT',
         headers: { 'content-type': 'application/json' },

package/src/modules/sales/components/OrderEditingSettings.tsx

@@ -121,6 +121,7 @@ export function OrderEditingSettings() {
         orderCustomerEditableStatuses: customerStatuses,
         orderAddressEditableStatuses: addressStatuses,
       }
+      // optimistic-lock-exempt: single-row tenant order-editing settings blob — no per-record version / concurrent record edit
       const call = await apiCall<SettingsResponse>('/api/sales/settings/order-editing', {
         method: 'PUT',
         headers: { 'content-type': 'application/json' },

package/src/modules/sales/components/PaymentMethodsSettings.tsx

@@ -15,7 +15,9 @@ import {
 import { Label } from '@open-mercato/ui/primitives/label'
 import { CrudForm, type CrudField, type CrudCustomFieldRenderProps } from '@open-mercato/ui/backend/CrudForm'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -291,12 +293,14 @@ export function PaymentMethodsSettings() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall('/api/sales/payment-methods', {
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      const call = await withScopedApiRequestHeaders(headers, () => apiCall('/api/sales/payment-methods', {
         method: 'DELETE',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ id: entry.id }),
-      })
+      }))
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.delete)
       }
       flash(translations.messages.deleted, 'success')
@@ -325,12 +329,15 @@ export function PaymentMethodsSettings() {
     const method = dialog.mode === 'create' ? 'POST' : 'PUT'
     if (dialog.mode === 'edit') payload.id = dialog.entry.id
     try {
-      const call = await apiCall(path, {
+      const savePaymentMethod = () => apiCall(path, {
         method,
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(payload),
       })
+      const headers = buildOptimisticLockHeader(dialog.mode === 'edit' ? dialog.entry.updatedAt : null)
+      const call = await withScopedApiRequestHeaders(headers, savePaymentMethod)
       if (!call.ok) {
+        if (surfaceRecordConflict({ status: call.status, body: call.result }, t)) return
         await raiseCrudError(call.response, translations.errors.save)
       }
       flash(translations.messages.saved, 'success')
@@ -466,6 +473,7 @@ export function PaymentMethodsSettings() {
             schema={paymentFormSchema}
             fields={fields}
             initialValues={formValues}
+            optimisticLockUpdatedAt={dialog?.mode === 'edit' ? dialog.entry.updatedAt : null}
             submitLabel={translations.form.save}
             onSubmit={handleSubmit}
             cancelHref={undefined}