@open-mercato/core 0.6.6-develop.6330.1.a261878aa8 → 0.6.6-develop.6332.1.6e73f0f55b

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

@@ -4981,7 +4981,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);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const shouldInvalidateSentToken = (quote.status ?? null) === "sent";
     if (shouldInvalidateSentToken) {
       quote.acceptanceToken = null;
@@ -5213,6 +5213,7 @@ const updateOrderCommand: CommandHandler<
     if (!order)
       throw new CrudHttpError(404, { error: "Sales order not found" });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     const previousStatus = normalizeStatusValue(order.status);
     let statusChangeNote: SalesNote | null = null;
     const shouldRecalculateTotals =
@@ -6055,7 +6056,7 @@ const convertQuoteToOrderCommand: CommandHandler<
           ),
         });
       ensureQuoteScope(ctx, quote.organizationId, quote.tenantId);
-      enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
+      await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
       const snapshot = await loadQuoteSnapshot(em, payload.quoteId);
       if (!snapshot)
         throw new CrudHttpError(404, {
@@ -6545,7 +6546,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);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
@@ -6866,7 +6867,7 @@ const orderLineDeleteCommand: CommandHandler<
         ),
       });
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
-    enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     const shipmentCount = await em.count(SalesShipmentItem, {
       orderLine: parsed.id,
       shipment: { deletedAt: null },
@@ -7037,7 +7038,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);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesQuoteLine, { quote }, { orderBy: { lineNumber: "asc" } }),
       em.find(
@@ -7349,7 +7350,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);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     const existingLines = await em.find(
       SalesQuoteLine,
       { quote },
@@ -7503,7 +7504,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);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -7797,7 +7798,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);
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
@@ -7962,7 +7963,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);
+    await enforceSalesDocumentOptimisticLock(ctx, quote, SALES_RESOURCE_KIND_QUOTE);
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -8254,7 +8255,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);
+    await 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/payments.ts

@@ -30,6 +30,8 @@ import {
   ensureTenantScope,
   extractUndoPayload,
   toNumericString,
+  enforceSalesDocumentOptimisticLock,
+  SALES_RESOURCE_KIND_ORDER,
 } from './shared'
 import { resolveDictionaryEntryValue } from '../lib/dictionaries'
 import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
@@ -343,6 +345,9 @@ const createPaymentCommand: CommandHandler<
       if (order.deletedAt) {
         throw new CrudHttpError(404, { error: 'sales.payments.order_not_found' })
       }
+      // Guard the parent order's aggregate version (Gap A): a payment mutation
+      // recalculates the order totals, so a stale parent must 409 before we touch it.
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
       if (
         order.currencyCode &&
         input.currencyCode &&
@@ -730,6 +735,9 @@ const updatePaymentCommand: CommandHandler<
     )
     ensureSameScope(payment, resolvedOrganizationId, resolvedTenantId)
     const previousOrder = payment.order as SalesOrder | null
+    // Guard the parent order's aggregate version (Gap A): updating a payment
+    // recalculates the order totals, so a stale parent must 409 before mutating.
+    await enforceSalesDocumentOptimisticLock(ctx, previousOrder, SALES_RESOURCE_KIND_ORDER)
     // Apply payment scalar fields, order/line status changes and the
     // allocations rebuild in one transaction so a mid-write failure cannot
     // leave the payment and its allocations partially committed (#2336).
@@ -1064,6 +1072,9 @@ const deletePaymentCommand: CommandHandler<
     )
     ensureSameScope(payment, input.organizationId, input.tenantId)
     const order = payment.order as SalesOrder | null
+    // Guard the parent order's aggregate version (Gap A): deleting a payment
+    // recalculates the order totals, so a stale parent must 409 before mutating.
+    await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
     const allocations = await findWithDecryption(em, SalesPaymentAllocation, { payment }, {}, { tenantId: payment.tenantId, organizationId: payment.organizationId })
     const allocationOrders = allocations
       .map((allocation) =>

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

@@ -615,7 +615,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)
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
 
       const orderLines = await findWithDecryption(
         tx,
@@ -890,7 +890,7 @@ const updateReturnCommand: CommandHandler<ReturnUpdateInput, { returnId: string
       }
       // Lock on the return's own version — editing header fields (reason / notes /
       // returnedAt) only touches the return, not the order totals.
-      enforceSalesDocumentOptimisticLock(ctx, entity, SALES_RESOURCE_KIND_RETURN)
+      await enforceSalesDocumentOptimisticLock(ctx, entity, SALES_RESOURCE_KIND_RETURN)
 
       if (input.reason !== undefined) entity.reason = input.reason.length ? input.reason : null
       if (input.notes !== undefined) entity.notes = input.notes.length ? input.notes : null
@@ -1020,7 +1020,7 @@ const deleteReturnCommand: CommandHandler<ReturnDeleteInput, { returnId: string
     }
     ensureSameScope(header, input.organizationId, input.tenantId)
     // Lock on the return's own version, captured before any mutation.
-    enforceSalesDocumentOptimisticLock(ctx, header, SALES_RESOURCE_KIND_RETURN)
+    await enforceSalesDocumentOptimisticLock(ctx, header, SALES_RESOURCE_KIND_RETURN)
 
     await reverseReturnEffects(em, salesCalculationService, snapshot)
 

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

@@ -2,7 +2,7 @@ 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'
+import { enforceCommandOptimisticLockWithGuards } 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'
@@ -28,14 +28,20 @@ export const SALES_RESOURCE_KIND_RETURN = 'sales.return'
  *
  * Strictly additive: when the client sends no header the check is a no-op, so
  * existing API consumers are unaffected. Respects `OM_OPTIMISTIC_LOCK`.
+ *
+ * Routes through the async DI-aware seam `enforceCommandOptimisticLockWithGuards`
+ * (Phase 0 / S1): the OSS `updated_at` floor runs first (identical behavior when
+ * `record_locks` is disabled — floor only), then the optional enterprise
+ * `record_locks` enrichment is awaited so the aggregate check observes the
+ * action-log diff when the resource is enabled. Callers MUST `await` it.
  */
-export function enforceSalesDocumentOptimisticLock(
+export async function enforceSalesDocumentOptimisticLock(
   ctx: CommandRuntimeContext,
   document: { id: string; updatedAt?: Date | string | null } | null | undefined,
   resourceKind: string,
-): void {
+): Promise<void> {
   if (!document) return
-  enforceCommandOptimisticLock({
+  await enforceCommandOptimisticLockWithGuards(ctx.container, {
     resourceKind,
     resourceId: document.id,
     current: document.updatedAt ?? null,

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

@@ -29,6 +29,8 @@ import {
   ensureSameScope,
   ensureTenantScope,
   extractUndoPayload,
+  enforceSalesDocumentOptimisticLock,
+  SALES_RESOURCE_KIND_ORDER,
 } from './shared'
 import { resolveDictionaryEntryValue } from '../lib/dictionaries'
 import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
@@ -442,6 +444,10 @@ const createShipmentCommand: CommandHandler<ShipmentCreateInput, { shipmentId: s
     const shipment = await em.transactional(async (tx) => {
       const order = await loadOrder(tx, input.orderId, { tenantId: input.tenantId, organizationId: input.organizationId })
       ensureSameScope(order, input.organizationId, input.tenantId)
+      // Guard the parent order's aggregate version (Gap B): a shipment mutation
+      // recalculates the order's fulfilled quantities, so a stale parent must 409
+      // before we touch it.
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
       const { items: normalizedItems, lineMap } = await validateShipmentItems({
         em: tx,
         order,
@@ -674,6 +680,10 @@ const updateShipmentCommand: CommandHandler<ShipmentUpdateInput, { shipmentId: s
       if (input.orderId && input.orderId !== order.id) {
         throw new CrudHttpError(400, { error: 'sales.shipments.invalid_order' })
       }
+      // Guard the parent order's aggregate version (Gap B): updating a shipment
+      // recalculates the order's fulfilled quantities, so a stale parent must 409
+      // before we touch it.
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
 
       // Check if order is financially closed - prevent modifications to shipments
       const paidAmount = parseFloat(order.paidTotalAmount || '0')
@@ -976,6 +986,10 @@ const deleteShipmentCommand: CommandHandler<
       if (order.id !== payload.orderId) {
         throw new CrudHttpError(400, { error: translate('sales.shipments.invalid_order', 'Shipment does not belong to this order') })
       }
+      // Guard the parent order's aggregate version (Gap B): deleting a shipment
+      // recalculates the order's fulfilled quantities, so a stale parent must 409
+      // before we touch it.
+      await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER)
       const scope = { tenantId: shipmentEntity.tenantId, organizationId: shipmentEntity.organizationId }
       const items = await findWithDecryption(tx, SalesShipmentItem, { shipment: shipmentEntity }, {}, scope)
       items.forEach((item) => tx.remove(item))

package/src/modules/sales/components/documents/PaymentDialog.tsx

@@ -9,7 +9,7 @@ import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimi
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { createCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
-import { handleSectionMutationError, rowOptimisticVersion } from './optimisticLock'
+import { handleSectionMutationError } from './optimisticLock'
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
 import { useDialogKeyHandler } from '@open-mercato/ui/hooks/useDialogKeyHandler'
 import { Input } from '@open-mercato/ui/primitives/input'
@@ -58,6 +58,7 @@ type PaymentDialogProps = {
   orderId: string
   organizationId: string | null
   tenantId: string | null
+  documentUpdatedAt?: string | null
   onOpenChange: (open: boolean) => void
   onSaved?: (totals?: PaymentTotals | null) => void | Promise<void>
 }
@@ -79,6 +80,7 @@ export function PaymentDialog({
   orderId,
   organizationId,
   tenantId,
+  documentUpdatedAt,
   onOpenChange,
   onSaved,
 }: PaymentDialogProps) {
@@ -539,7 +541,9 @@ export function PaymentDialog({
       const action = payment?.id ? updateCrud : createCrud
       try {
         const result = await withScopedApiRequestHeaders(
-          buildOptimisticLockHeader(payment?.id ? rowOptimisticVersion(payment) : undefined),
+          // The server guards the PARENT order's aggregate version (Gap A) for
+          // both create and update, so send the order's `updated_at`.
+          buildOptimisticLockHeader(documentUpdatedAt ?? undefined),
           () =>
             action(
               'sales/payments',
@@ -569,7 +573,7 @@ export function PaymentDialog({
         throw err
       }
     },
-    [currencyCode, mode, onOpenChange, onSaved, orderId, organizationId, payment?.id, payment?.updatedAt, t, tenantId]
+    [currencyCode, documentUpdatedAt, mode, onOpenChange, onSaved, orderId, organizationId, payment?.id, t, tenantId]
   )
 
   const handleSubmitForm = React.useCallback(

package/src/modules/sales/components/documents/PaymentsSection.tsx

@@ -7,7 +7,7 @@ import { LoadingMessage, ErrorMessage, TabEmptyState } from '@open-mercato/ui/ba
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
-import { handleSectionMutationError, readRowUpdatedAt, rowOptimisticVersion } from './optimisticLock'
+import { handleSectionMutationError, readRowUpdatedAt } from './optimisticLock'
 import type { SectionAction } from '@open-mercato/ui/backend/detail'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -41,6 +41,7 @@ type SalesDocumentPaymentsSectionProps = {
   currencyCode: string | null | undefined
   organizationId?: string | null
   tenantId?: string | null
+  documentUpdatedAt?: string | null
   onActionChange?: (action: SectionAction | null) => void
   onTotalsChange?: () => void
   onPaymentsChange?: (payments: PaymentRow[]) => void
@@ -69,6 +70,7 @@ export function SalesDocumentPaymentsSection({
   currencyCode,
   organizationId: orgFromProps,
   tenantId: tenantFromProps,
+  documentUpdatedAt,
   onActionChange,
   onTotalsChange,
   onPaymentsChange,
@@ -216,7 +218,9 @@ export function SalesDocumentPaymentsSection({
     async (row: PaymentRow) => {
       try {
         const result = await withScopedApiRequestHeaders(
-          buildOptimisticLockHeader(rowOptimisticVersion(row)),
+          // The server guards the PARENT order's aggregate version (Gap A), so
+          // send the order's `updated_at`, not the payment row's.
+          buildOptimisticLockHeader(documentUpdatedAt ?? undefined),
           () =>
             deleteCrud<{ orderTotals?: PaymentTotals | null }>('sales/payments', {
               body: {
@@ -242,7 +246,7 @@ export function SalesDocumentPaymentsSection({
         flash(t('sales.documents.payments.errorDelete', 'Failed to delete payment.'), 'error')
       }
     },
-    [loadPayments, onTotalsChange, orderId, resolvedOrganizationId, resolvedTenantId, t]
+    [documentUpdatedAt, loadPayments, onTotalsChange, orderId, resolvedOrganizationId, resolvedTenantId, t]
   )
 
   React.useEffect(() => {
@@ -369,6 +373,7 @@ export function SalesDocumentPaymentsSection({
         orderId={orderId}
         organizationId={resolvedOrganizationId}
         tenantId={resolvedTenantId}
+        documentUpdatedAt={documentUpdatedAt ?? null}
         onSaved={handlePaymentSaved}
       />
     </div>

package/src/modules/sales/components/documents/ShipmentDialog.tsx

@@ -15,7 +15,7 @@ import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimi
 import { createCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
-import { handleSectionMutationError, rowOptimisticVersion } from './optimisticLock'
+import { handleSectionMutationError } from './optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { cn } from '@open-mercato/shared/lib/utils'
 import { E } from '#generated/entities.ids.generated'
@@ -46,6 +46,7 @@ type ShipmentDialogProps = {
   currencyCode?: string | null
   organizationId: string | null
   tenantId: string | null
+  documentUpdatedAt?: string | null
   computeAvailable: (lineId: string, excludeShipmentId?: string | null) => number
   shippingAddressSnapshot?: NormalizedAddressSnapshot | Record<string, unknown> | null
   onClose: () => void
@@ -278,6 +279,7 @@ export function ShipmentDialog({
   currencyCode,
   organizationId,
   tenantId,
+  documentUpdatedAt,
   computeAvailable,
   shippingAddressSnapshot,
   onClose,
@@ -1089,7 +1091,9 @@ export function ShipmentDialog({
       let result
       try {
         result = await withScopedApiRequestHeaders(
-          buildOptimisticLockHeader(shipment?.id ? rowOptimisticVersion(shipment) : undefined),
+          // The server guards the PARENT order's aggregate version (Gap B) for
+          // both create and update, so send the order's `updated_at`.
+          buildOptimisticLockHeader(documentUpdatedAt ?? undefined),
           () =>
             action(
               'sales/shipments',
@@ -1219,6 +1223,7 @@ export function ShipmentDialog({
     },
     [
       currencyCode,
+      documentUpdatedAt,
       lines,
       mode,
       onAddComment,
@@ -1226,7 +1231,6 @@ export function ShipmentDialog({
       orderId,
       organizationId,
       shipment?.id,
-      shipment?.updatedAt,
       addressOptions,
       addressOptionsMap,
       shippingMethods,

package/src/modules/sales/components/documents/ShipmentsSection.tsx

@@ -20,7 +20,7 @@ import type { SectionAction } from '@open-mercato/core/modules/customers/compone
 import { generateTempId } from '@open-mercato/core/modules/customers/lib/detailHelpers'
 import { formatAddressString, type AddressValue } from '@open-mercato/core/modules/customers/utils/addressFormat'
 import { ShipmentDialog } from './ShipmentDialog'
-import { handleSectionMutationError, readRowUpdatedAt, rowOptimisticVersion } from './optimisticLock'
+import { handleSectionMutationError, readRowUpdatedAt } from './optimisticLock'
 import { extractCustomFieldValues } from './customFieldHelpers'
 import type { OrderLine, ShipmentRow, ShipmentItem } from './shipmentTypes'
 
@@ -33,6 +33,7 @@ type SalesShipmentsSectionProps = {
   shippingAddressSnapshot?: Record<string, unknown> | null
   organizationId?: string | null
   tenantId?: string | null
+  documentUpdatedAt?: string | null
   onActionChange?: (action: SectionAction | null) => void
   onAddComment?: (body: string) => Promise<void>
 }
@@ -114,6 +115,7 @@ export function SalesShipmentsSection({
   shippingAddressSnapshot,
   organizationId: organizationIdProp,
   tenantId: tenantIdProp,
+  documentUpdatedAt,
   onActionChange,
   onAddComment,
 }: SalesShipmentsSectionProps) {
@@ -401,7 +403,9 @@ export function SalesShipmentsSection({
       if (!confirmed) return
       try {
         const result = await withScopedApiRequestHeaders(
-          buildOptimisticLockHeader(rowOptimisticVersion(shipment)),
+          // The server guards the PARENT order's aggregate version (Gap B), so
+          // send the order's `updated_at`, not the shipment row's.
+          buildOptimisticLockHeader(documentUpdatedAt ?? undefined),
           () =>
             deleteCrud('sales/shipments', {
               body: {
@@ -425,7 +429,7 @@ export function SalesShipmentsSection({
         flash(t('sales.documents.shipments.errorDelete', 'Failed to delete shipment.'), 'error')
       }
     },
-    [confirm, loadShipments, orderId, resolvedOrganizationId, resolvedTenantId, t]
+    [confirm, documentUpdatedAt, loadShipments, orderId, resolvedOrganizationId, resolvedTenantId, t]
   )
 
   const renderItemList = (items: ShipmentItem[]) => (
@@ -573,6 +577,7 @@ export function SalesShipmentsSection({
         currencyCode={currencyCode}
         organizationId={resolvedOrganizationId}
         tenantId={resolvedTenantId}
+        documentUpdatedAt={documentUpdatedAt ?? null}
         computeAvailable={computeAvailable}
         shippingAddressSnapshot={shippingAddressSnapshot}
         onClose={() => setDialogState(null)}

package/src/modules/sales/di.ts

@@ -42,15 +42,20 @@ type AppCradle = AppContainer['cradle'] & {
 }
 
 const RESOURCE_KIND_ORDER = 'sales.order'
+const RESOURCE_KIND_PAYMENT = 'sales.payment'
+const RESOURCE_KIND_SHIPMENT = 'sales.shipment'
 
-const readSalesOrderUpdatedAt: OptimisticLockCurrentReader = async (
+async function readOrderUpdatedAtById(
   em: EntityManager,
-  { resourceId, tenantId, organizationId },
-) => {
+  orderId: string | null | undefined,
+  tenantId: string,
+  organizationId: string | null | undefined,
+): Promise<string | null> {
+  if (!orderId) return null
   const row = await em.findOne(
     SalesOrder,
     {
-      id: resourceId,
+      id: orderId,
       tenantId,
       ...(organizationId ? { organizationId } : {}),
       deletedAt: null,
@@ -60,13 +65,67 @@ const readSalesOrderUpdatedAt: OptimisticLockCurrentReader = async (
   return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
 }
 
-// Hand-wired sales.order reader registered at module-load time so the
-// `customer_entities`-style polymorphic-table override pattern stays
-// observable for downstream modules. Functionally identical to the
-// auto-registered generic reader; kept here as a reference example. The
-// guard's mode check short-circuits when `OM_OPTIMISTIC_LOCK=off`.
+const readSalesOrderUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => readOrderUpdatedAtById(em, resourceId, tenantId, organizationId)
+
+// Payments and shipments are guarded against the PARENT ORDER's aggregate
+// version (their mutations recalc order totals / fulfilled quantities, so the
+// order is the consistency boundary — same model as lines/adjustments/returns).
+// The CRUD-layer guard therefore must compare against the order, not the
+// payment/shipment row: resolve the parent order from the sub-resource id and
+// return its `updated_at`. This keeps the single optimistic-lock header
+// consistent across the makeCrudRoute guard and the command-level
+// `enforceSalesDocumentOptimisticLock` guard (both read the order version).
+const readPaymentParentOrderUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const payment = await em.findOne(
+    SalesPayment,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      deletedAt: null,
+    },
+    { fields: ['order'] as const },
+  )
+  const orderId = (payment as { order?: { id?: string } | string | null } | null)?.order
+  const resolvedOrderId = typeof orderId === 'string' ? orderId : orderId?.id ?? null
+  return readOrderUpdatedAtById(em, resolvedOrderId, tenantId, organizationId)
+}
+
+const readShipmentParentOrderUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const shipment = await em.findOne(
+    SalesShipment,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      deletedAt: null,
+    },
+    { fields: ['order'] as const },
+  )
+  const orderId = (shipment as { order?: { id?: string } | string | null } | null)?.order
+  const resolvedOrderId = typeof orderId === 'string' ? orderId : orderId?.id ?? null
+  return readOrderUpdatedAtById(em, resolvedOrderId, tenantId, organizationId)
+}
+
+// Hand-wired sales readers registered at module-load time. `sales.order` mirrors
+// the auto-registered generic reader (kept as the polymorphic-table override
+// reference). `sales.payment`/`sales.shipment` redirect the CRUD-layer guard to
+// the parent order so payments/shipments guard the aggregate (Phase 3 Gap A/B)
+// instead of their own row. The guard's mode check short-circuits when
+// `OM_OPTIMISTIC_LOCK=off`.
 registerOptimisticLockReaders({
   [RESOURCE_KIND_ORDER]: readSalesOrderUpdatedAt,
+  [RESOURCE_KIND_PAYMENT]: readPaymentParentOrderUpdatedAt,
+  [RESOURCE_KIND_SHIPMENT]: readShipmentParentOrderUpdatedAt,
 })
 
 export function register(container: AppContainer) {

package/src/modules/sales/setup.ts

@@ -51,7 +51,9 @@ export const setup: ModuleSetupConfig = {
     admin: ['sales.*', 'sales.documents.number.edit'],
     employee: [
       'sales.channels.view',
+      'sales.channels.manage',
       'sales.settings.view',
+      'sales.settings.manage',
       'sales.orders.view',
       'sales.orders.manage',
       'sales.orders.approve',

package/src/modules/staff/backend/staff/leave-requests/[id]/page.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from 'react'
-import { useRouter } from 'next/navigation'
+import { usePathname, useRouter } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Badge } from '@open-mercato/ui/primitives/badge'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -14,12 +14,14 @@ import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { LeaveRequestForm, buildLeaveRequestPayload, type LeaveRequestFormValues } from '@open-mercato/core/modules/staff/components/LeaveRequestForm'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { type LeaveRequestRecord, type LeaveRequestsResponse, type NormalizedLeaveRequest, normalizeLeaveRequest, resolveStatusVariant, formatDateLabel, formatDateRange } from '../../../../lib/leaveRequestHelpers'
 
 export default function StaffLeaveRequestDetailPage({ params }: { params?: { id?: string } }) {
   const id = params?.id
   const t = useT()
   const router = useRouter()
+  const pathname = usePathname()
   const [isLoading, setIsLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -123,6 +125,20 @@ const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) =>
     router.refresh()
   }, [decisionComment, record?.id, record?.updatedAt, router, t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `staff.leaveRequest` + id
+  // explicitly. The resourceKind follows the module's camelCase version-history
+  // convention so the held lock matches the leave request's save-time conflict surface.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'staff.leaveRequest',
+      resourceId: id || null,
+      updatedAt: record?.updatedAt ?? null,
+      data: record as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isLoading) {
     return (
       <Page>

package/src/modules/staff/backend/staff/team-members/[id]/page.tsx

@@ -2,7 +2,7 @@
 
 import * as React from 'react'
 import Link from 'next/link'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
@@ -15,6 +15,7 @@ import { createTranslatorWithFallback } from '@open-mercato/shared/lib/i18n/tran
 import { AvailabilityRulesEditor } from '@open-mercato/core/modules/planner/components/AvailabilityRulesEditor'
 import { buildMemberScheduleItems } from '@open-mercato/core/modules/staff/lib/memberSchedule'
 import { TeamMemberForm, buildTeamMemberPayload, type TeamMemberFormValues } from '@open-mercato/core/modules/staff/components/TeamMemberForm'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { NotesSection } from '@open-mercato/ui/backend/detail'
 import { ActivitiesSection, type SectionAction } from '@open-mercato/ui/backend/detail'
 import { AddressesSection as SharedAddressesSection } from '@open-mercato/ui/backend/detail'
@@ -71,6 +72,7 @@ export default function StaffTeamMemberDetailPage({ params }: { params?: { id?:
   const t = useT()
   const detailTranslator = React.useMemo(() => createTranslatorWithFallback(t), [t])
   const router = useRouter()
+  const pathname = usePathname()
   const searchParams = useSearchParams()
   const [initialValues, setInitialValues] = React.useState<TeamMemberFormValues | null>(null)
   const [memberRecord, setMemberRecord] = React.useState<TeamMemberRecord | null>(null)
@@ -341,6 +343,20 @@ export default function StaffTeamMemberDetailPage({ params }: { params?: { id?:
     : [t('staff.teamMembers.detail.roles.unassigned', 'No roles assigned')]
   const userEmail = memberRecord?.user?.email ?? null
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `staff.teamMember` + id
+  // explicitly. The resourceKind mirrors the TeamMemberForm `versionHistory` so the held
+  // lock matches the save-time conflict surface for the same team member.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'staff.teamMember',
+      resourceId: memberId || null,
+      updatedAt: initialValues?.updatedAt ?? null,
+      data: initialValues as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isNotFound) {
     return (
       <Page>