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

package/src/modules/currencies/backend/currencies/[id]/page.tsx

@@ -1,14 +1,16 @@
 'use client'
 
 import * as React from 'react'
-import { useRouter, useParams } from 'next/navigation'
+import { useRouter, useParams, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
-import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { SendObjectMessageDialog } from '@open-mercato/ui/backend/messages'
@@ -35,6 +37,7 @@ type CurrencyData = {
 export default function EditCurrencyPage({ params }: { params?: { id?: string } }) {
   const t = useT()
   const router = useRouter()
+  const pathname = usePathname()
   const { confirm: confirmDialog, ConfirmDialogElement } = useConfirmDialog()
   const mutationContextId = 'currencies-edit:delete'
   const { runMutation, retryLastMutation } = useGuardedMutation<{
@@ -185,11 +188,25 @@ export default function EditCurrencyPage({ params }: { params?: { id?: string }
       flash(t('currencies.flash.deleted'), 'success')
       router.push('/backend/currencies')
     } catch (error) {
-      if (extractOptimisticLockConflict(error)) return
+      if (surfaceRecordConflict(error, t)) return
       flash(t('currencies.flash.deleteError'), 'error')
     }
   }, [currency, t, router, confirmDialog, mutationContextId, retryLastMutation, runMutation])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `currencies.currency` + id
+  // explicitly. The resourceKind mirrors the CrudForm `versionHistory` so the held
+  // lock matches the save-time conflict surface for the same currency.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'currencies.currency',
+      resourceId: currency?.id ?? null,
+      updatedAt: currency?.updatedAt ?? currency?.updated_at ?? null,
+      data: currency as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (loading) {
     return (
       <Page>

package/src/modules/currencies/backend/currencies/page.tsx

@@ -14,6 +14,7 @@ import { Plus, Star } from 'lucide-react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -188,7 +189,7 @@ export default function CurrenciesPage() {
         flash(t('currencies.flash.deleted'), 'success')
         setReloadToken((token) => token + 1)
       } catch (error) {
-        if (extractOptimisticLockConflict(error)) return
+        if (surfaceRecordConflict(error, t, { onRefresh: () => setReloadToken((token) => token + 1) })) return
         flash(t('currencies.flash.deleteError'), 'error')
       }
     },

package/src/modules/currencies/backend/exchange-rates/[id]/page.tsx

@@ -1,13 +1,14 @@
 'use client'
 
 import * as React from 'react'
-import { useRouter } from 'next/navigation'
+import { useRouter, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { LoadingMessage, ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
 import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import {
   loadCurrencyOptions,
@@ -47,6 +48,7 @@ type ExchangeRateData = {
 export default function EditExchangeRatePage({ params }: { params?: { id?: string } }) {
   const t = useT()
   const router = useRouter()
+  const pathname = usePathname()
 
   const [exchangeRate, setExchangeRate] = React.useState<ExchangeRateData | null>(null)
   const [loading, setLoading] = React.useState(true)
@@ -84,6 +86,20 @@ export default function EditExchangeRatePage({ params }: { params?: { id?: strin
     [t, loadOptions]
   )
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `currencies.exchange_rate`
+  // + id explicitly. The resourceKind mirrors the CrudForm `versionHistory` so the
+  // held lock matches the save-time conflict surface for the same exchange rate.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'currencies.exchange_rate',
+      resourceId: exchangeRate?.id ?? null,
+      updatedAt: exchangeRate?.updatedAt ?? exchangeRate?.updated_at ?? null,
+      data: exchangeRate as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (loading) {
     return (
       <Page>

package/src/modules/currencies/backend/exchange-rates/page.tsx

@@ -13,7 +13,8 @@ import { BooleanIcon } from '@open-mercato/ui/backend/ValueIcons'
 import { Plus } from 'lucide-react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
-import { buildOptimisticLockHeader, extractOptimisticLockConflict } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -152,7 +153,7 @@ export default function ExchangeRatesPage() {
         flash(t('exchangeRates.flash.deleted'), 'success')
         setReloadToken((token) => token + 1)
       } catch (error) {
-        if (extractOptimisticLockConflict(error)) return
+        if (surfaceRecordConflict(error, t, { onRefresh: () => setReloadToken((token) => token + 1) })) return
         flash(t('exchangeRates.flash.deleteError'), 'error')
       }
     },

package/src/modules/customer_accounts/api/admin/roles/[id].ts

@@ -7,7 +7,7 @@ import { RbacService } from '@open-mercato/core/modules/auth/services/rbacServic
 import { CustomerRole, CustomerRoleAcl, CustomerUserRole } from '@open-mercato/core/modules/customer_accounts/data/entities'
 import { updateRoleSchema } from '@open-mercato/core/modules/customer_accounts/data/validators'
 import { emitCustomerAccountsEvent } from '@open-mercato/core/modules/customer_accounts/events'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 
 export const metadata = {}
@@ -107,7 +107,7 @@ export async function PUT(req: Request, { params }: { params: { id: string } })
   // Optimistic lock: refuse a stale overwrite so two admins editing the same role
   // in parallel cannot silently clobber each other (#2055). Strictly additive.
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'customer_accounts.role',
       resourceId: role.id,
       current: role.updatedAt ?? null,
@@ -169,7 +169,7 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
 
   // Optimistic lock: refuse a stale delete. Strictly additive.
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'customer_accounts.role',
       resourceId: role.id,
       current: role.updatedAt ?? null,

package/src/modules/customer_accounts/api/admin/users/[id].ts

@@ -12,7 +12,7 @@ import { adminUpdateUserSchema } from '@open-mercato/core/modules/customer_accou
 import { emitCustomerAccountsEvent } from '@open-mercato/core/modules/customer_accounts/events'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { isOwnedCompanyEntity } from '@open-mercato/core/modules/customer_accounts/lib/customerEntityOwnership'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 
 export const metadata = {}
@@ -143,7 +143,7 @@ export async function PUT(req: Request, { params }: { params: { id: string } })
   // customer user in parallel cannot silently clobber each other (#2055). The
   // check is strictly additive — a no-op when the client sends no expected-version header.
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'customer_accounts.user',
       resourceId: user.id,
       current: user.updatedAt ?? null,
@@ -267,7 +267,7 @@ export async function DELETE(req: Request, { params }: { params: { id: string }
   // Optimistic lock: refuse a stale delete (e.g. deleting a record another admin
   // already modified). Strictly additive — a no-op without the expected-version header.
   try {
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(container, {
       resourceKind: 'customer_accounts.user',
       resourceId: user.id,
       current: user.updatedAt ?? null,

package/src/modules/customers/api/addresses/route.ts

@@ -68,6 +68,7 @@ const crud = makeCrudRoute({
       'is_primary',
       'organization_id',
       'tenant_id',
+      'updated_at',
     ],
     sortFieldMap: {
       createdAt: 'created_at',
@@ -142,6 +143,7 @@ const addressListItemSchema = z.object({
   is_primary: z.boolean().nullable().optional(),
   organization_id: z.string().uuid().nullable().optional(),
   tenant_id: z.string().uuid().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
 })
 
 const addressCreateResponseSchema = z.object({

package/src/modules/customers/api/tags/route.ts

@@ -42,12 +42,16 @@ const crud = makeCrudRoute({
     idField: 'id',
     orgField: 'organizationId',
     tenantField: 'tenantId',
+    // CustomerTag has no `deleted_at` column. Without this, the auto-registered
+    // generic optimistic-lock reader would filter on `deletedAt: null` against a
+    // non-existent column, throw, and fail open — silently disabling the lock.
+    softDeleteField: null,
   },
   indexer: { entityType: E.customers.customer_tag },
   list: {
     schema: listSchema,
     entityId: E.customers.customer_tag,
-    fields: ['id', 'slug', 'label', 'color', 'description', 'organization_id', 'tenant_id'],
+    fields: ['id', 'slug', 'label', 'color', 'description', 'organization_id', 'tenant_id', 'updated_at'],
     buildFilters: async (query: any) => {
       const filters: Record<string, any> = {}
       if (query.search) {
@@ -107,6 +111,7 @@ const tagListItemSchema = z.object({
   description: z.string().nullable().optional(),
   organization_id: z.string().uuid().nullable().optional(),
   tenant_id: z.string().uuid().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
 })
 
 const tagCreateResponseSchema = z.object({

package/src/modules/customers/backend/customers/companies-v2/[id]/page.tsx

@@ -2,7 +2,7 @@
 
 import * as React from 'react'
 import Link from 'next/link'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { useRouter, useSearchParams, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Building2, Hash, Users, BarChart3, StickyNote } from 'lucide-react'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
@@ -16,6 +16,7 @@ import { AttachmentsSection, ErrorMessage, LoadingMessage, RecordNotFoundState,
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { InjectionSpot, useInjectionWidgets } from '@open-mercato/ui/backend/injection/InjectionSpot'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { createTranslatorWithFallback } from '@open-mercato/shared/lib/i18n/translate'
 import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { CollapsibleZoneLayout, type ZoneSectionDescriptor } from '@open-mercato/ui/backend/crud/CollapsibleZoneLayout'
@@ -49,6 +50,7 @@ export default function CompanyDetailV2Page({ params }: { params?: { id?: string
   const t = useT()
   const router = useRouter()
   const searchParams = useSearchParams()
+  const pathname = usePathname()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
 
   const detailTranslator = React.useMemo(() => createTranslatorWithFallback(t), [t])
@@ -193,6 +195,21 @@ export default function CompanyDetailV2Page({ params }: { params?: { id?: string
     logContext: 'customers.companies-v2',
   })
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `customers.company` + id
+  // explicitly (the hardcoded path allowlist misses the `companies-v2` route).
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'customers.company',
+      resourceId: currentCompanyId,
+      updatedAt: (data?.company as { updatedAt?: string | null; updated_at?: string | null } | undefined)?.updatedAt
+        ?? (data?.company as { updated_at?: string | null } | undefined)?.updated_at
+        ?? null,
+      data: data as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   const handleEditActivity = React.useCallback((activity: { id: string; interactionType?: string; title?: string | null; body?: string | null; scheduledAt?: string | null; occurredAt?: string | null; [key: string]: unknown }) => {
     const raw = activity as Record<string, unknown>
     const durationValue = typeof raw.duration === 'number'
@@ -470,7 +487,7 @@ export default function CompanyDetailV2Page({ params }: { params?: { id?: string
                 <CrudForm<CompanyEditFormValues>
                   embedded
                   trackDirtyWhenEmbedded
-                  injectionSpotId="customers.company"
+                  injectionSpotId="crud-form:customers.company"
                   entityIds={[E.customers.customer_entity, E.customers.customer_company_profile]}
                   schema={formSchema}
                   fields={formFields}

package/src/modules/customers/backend/customers/deals/[id]/hooks/useDealAssociations.ts

@@ -1,7 +1,9 @@
 import * as React from 'react'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type {
   CompanyAssociationApiRecord,
@@ -95,6 +97,8 @@ type UseDealAssociationsOptions = {
   data: DealDetailPayload | null
   setData: React.Dispatch<React.SetStateAction<DealDetailPayload | null>>
   runMutationWithContext: GuardedMutationRunner
+  /** Re-fetch the deal detail; wired into the conflict bar's refresh action on a 409. */
+  onRefresh?: (() => void) | null
 }
 
 type UseDealAssociationsResult = {
@@ -113,6 +117,7 @@ export function useDealAssociations({
   data,
   setData,
   runMutationWithContext,
+  onRefresh,
 }: UseDealAssociationsOptions): UseDealAssociationsResult {
   const t = useT()
   const [peopleEditorIds, setPeopleEditorIds] = React.useState<string[]>([])
@@ -263,7 +268,10 @@ export function useDealAssociations({
       setPeopleSaving(true)
       try {
         await runMutationWithContext(
-          () => updateCrud('customers/deals', { id: currentDealId, personIds: nextIds }),
+          () => withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(data?.deal.updatedAt),
+            () => updateCrud('customers/deals', { id: currentDealId, personIds: nextIds }),
+          ),
           { id: currentDealId, personIds: nextIds, operation: 'updateDealPeople' },
         )
         const nextPeople = await loadPeopleAssociations(nextIds.slice(0, 3))
@@ -277,7 +285,7 @@ export function useDealAssociations({
               }
             : prev,
         )
-      } catch {
+      } catch (error) {
         setPeopleEditorIds(previousIds)
         setData((prev) =>
           prev
@@ -289,12 +297,16 @@ export function useDealAssociations({
               }
             : prev,
         )
-        flash(t('customers.deals.detail.peopleUpdateError', 'Failed to update linked people.'), 'error')
+        // runMutationWithContext already surfaces the conflict bar on a 409; only
+        // fall back to the generic flash when this is not a record conflict.
+        if (!surfaceRecordConflict(error, t, { onRefresh: onRefresh ?? null })) {
+          flash(t('customers.deals.detail.peopleUpdateError', 'Failed to update linked people.'), 'error')
+        }
       } finally {
         setPeopleSaving(false)
       }
     },
-    [currentDealId, data?.people, loadPeopleAssociations, peopleEditorIds, runMutationWithContext, setData, t],
+    [currentDealId, data?.deal.updatedAt, data?.people, loadPeopleAssociations, onRefresh, peopleEditorIds, runMutationWithContext, setData, t],
   )
 
   const handleCompaniesAssociationsChange = React.useCallback(
@@ -307,7 +319,10 @@ export function useDealAssociations({
       setCompaniesSaving(true)
       try {
         await runMutationWithContext(
-          () => updateCrud('customers/deals', { id: currentDealId, companyIds: nextIds }),
+          () => withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(data?.deal.updatedAt),
+            () => updateCrud('customers/deals', { id: currentDealId, companyIds: nextIds }),
+          ),
           { id: currentDealId, companyIds: nextIds, operation: 'updateDealCompanies' },
         )
         const nextCompanies = await loadCompanyAssociations(nextIds.slice(0, 3))
@@ -321,7 +336,7 @@ export function useDealAssociations({
               }
             : prev,
         )
-      } catch {
+      } catch (error) {
         setCompaniesEditorIds(previousIds)
         setData((prev) =>
           prev
@@ -333,7 +348,11 @@ export function useDealAssociations({
               }
             : prev,
         )
-        flash(t('customers.deals.detail.companiesUpdateError', 'Failed to update linked companies.'), 'error')
+        // runMutationWithContext already surfaces the conflict bar on a 409; only
+        // fall back to the generic flash when this is not a record conflict.
+        if (!surfaceRecordConflict(error, t, { onRefresh: onRefresh ?? null })) {
+          flash(t('customers.deals.detail.companiesUpdateError', 'Failed to update linked companies.'), 'error')
+        }
       } finally {
         setCompaniesSaving(false)
       }
@@ -342,7 +361,9 @@ export function useDealAssociations({
       companiesEditorIds,
       currentDealId,
       data?.companies,
+      data?.deal.updatedAt,
       loadCompanyAssociations,
+      onRefresh,
       runMutationWithContext,
       setData,
       t,

package/src/modules/customers/backend/customers/deals/[id]/hooks/useDealClosure.ts

@@ -1,10 +1,15 @@
 import * as React from 'react'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { 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 { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { DealStatsPayload, GuardedMutationRunner } from './types'
 
 type UseDealClosureOptions = {
   currentDealId: string | null
+  dealUpdatedAt: string | null
   runMutationWithContext: GuardedMutationRunner
   confirmDiscardIfDirty: () => Promise<boolean>
   onClosed: () => Promise<void>
@@ -26,10 +31,12 @@ type UseDealClosureResult = {
 
 export function useDealClosure({
   currentDealId,
+  dealUpdatedAt,
   runMutationWithContext,
   confirmDiscardIfDirty,
   onClosed,
 }: UseDealClosureOptions): UseDealClosureResult {
+  const t = useT()
   const [lostDialogOpen, setLostDialogOpen] = React.useState(false)
   const [wonPopupOpen, setWonPopupOpen] = React.useState(false)
   const [lostPopupOpen, setLostPopupOpen] = React.useState(false)
@@ -51,45 +58,65 @@ export function useDealClosure({
   const handleWon = React.useCallback(async () => {
     if (!currentDealId) return
     if (!(await confirmDiscardIfDirty())) return
-    await runMutationWithContext(
-      () => updateCrud('customers/deals', { id: currentDealId, closureOutcome: 'won', status: 'win' }),
-      { id: currentDealId, closureOutcome: 'won', status: 'win', operation: 'closeWon' },
-    )
+    try {
+      await runMutationWithContext(
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(dealUpdatedAt),
+          () => updateCrud('customers/deals', { id: currentDealId, closureOutcome: 'won', status: 'win' }),
+        ),
+        { id: currentDealId, closureOutcome: 'won', status: 'win', operation: 'closeWon' },
+      )
+    } catch (err) {
+      if (!surfaceRecordConflict(err, t, { onRefresh: () => { void onClosed() } })) {
+        flash(t('customers.deals.detail.closeWonError', 'Failed to mark deal as won.'), 'error')
+      }
+      return
+    }
     const stats = await fetchDealStats()
     setWonStats(stats)
     setWonPopupOpen(true)
     await onClosed()
-  }, [confirmDiscardIfDirty, currentDealId, fetchDealStats, onClosed, runMutationWithContext])
+  }, [confirmDiscardIfDirty, currentDealId, dealUpdatedAt, fetchDealStats, onClosed, runMutationWithContext, t])
 
   const handleLostConfirm = React.useCallback(
     async (input: { lossReasonId: string; lossNotes?: string }) => {
       if (!currentDealId) return
       if (!(await confirmDiscardIfDirty())) return
-      await runMutationWithContext(
-        () =>
-          updateCrud('customers/deals', {
+      try {
+        await runMutationWithContext(
+          () => withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(dealUpdatedAt),
+            () =>
+              updateCrud('customers/deals', {
+                id: currentDealId,
+                closureOutcome: 'lost',
+                status: 'loose',
+                lossReasonId: input.lossReasonId,
+                lossNotes: input.lossNotes ?? null,
+              }),
+          ),
+          {
             id: currentDealId,
             closureOutcome: 'lost',
             status: 'loose',
             lossReasonId: input.lossReasonId,
             lossNotes: input.lossNotes ?? null,
-          }),
-        {
-          id: currentDealId,
-          closureOutcome: 'lost',
-          status: 'loose',
-          lossReasonId: input.lossReasonId,
-          lossNotes: input.lossNotes ?? null,
-          operation: 'closeLost',
-        },
-      )
+            operation: 'closeLost',
+          },
+        )
+      } catch (err) {
+        if (!surfaceRecordConflict(err, t, { onRefresh: () => { void onClosed() } })) {
+          flash(t('customers.deals.detail.closeLostError', 'Failed to mark deal as lost.'), 'error')
+        }
+        return
+      }
       setLostDialogOpen(false)
       const stats = await fetchDealStats()
       setLostStats(stats)
       setLostPopupOpen(true)
       await onClosed()
     },
-    [confirmDiscardIfDirty, currentDealId, fetchDealStats, onClosed, runMutationWithContext],
+    [confirmDiscardIfDirty, currentDealId, dealUpdatedAt, fetchDealStats, onClosed, runMutationWithContext, t],
   )
 
   const openLostDialog = React.useCallback(() => setLostDialogOpen(true), [])

package/src/modules/customers/backend/customers/deals/[id]/hooks/useDealPipeline.ts

@@ -1,6 +1,9 @@
 import * as React from 'react'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
+import { 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 { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { DealDetailPayload, GuardedMutationRunner } from './types'
 
@@ -35,13 +38,20 @@ export function useDealPipeline({
       setIsStageSaving(true)
       try {
         await runMutationWithContext(
-          () => updateCrud('customers/deals', { id: currentDealId, pipelineStageId: nextStageId }),
+          () => withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(data.deal.updatedAt),
+            () => updateCrud('customers/deals', { id: currentDealId, pipelineStageId: nextStageId }),
+          ),
           { id: currentDealId, pipelineStageId: nextStageId, operation: 'updateDealStage' },
         )
         flash(t('customers.deals.detail.stageUpdateSuccess', 'Deal stage updated.'), 'success')
         await onStageChanged()
-      } catch {
-        flash(t('customers.deals.detail.stageUpdateError', 'Failed to update deal stage.'), 'error')
+      } catch (err) {
+        // A concurrent edit / pessimistic lock 409 routes to the unified conflict
+        // bar or merge dialog (S3); surface any other error as a flash.
+        if (!surfaceRecordConflict(err, t, { onRefresh: () => { void onStageChanged() } })) {
+          flash(t('customers.deals.detail.stageUpdateError', 'Failed to update deal stage.'), 'error')
+        }
       } finally {
         setIsStageSaving(false)
       }

package/src/modules/customers/backend/customers/deals/[id]/page.tsx

@@ -4,11 +4,12 @@ import * as React from 'react'
 import Link from 'next/link'
 import { Building2, UserSearch, Users } from 'lucide-react'
 import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { useRouter, useSearchParams, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { AttachmentsSection, ErrorMessage, LoadingMessage, NotesSection, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
 import { InjectionSpot } from '@open-mercato/ui/backend/injection/InjectionSpot'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { CollapsibleZoneLayout } from '@open-mercato/ui/backend/crud/CollapsibleZoneLayout'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -52,6 +53,7 @@ export default function DealDetailPage({ params }: { params?: { id?: string } })
   const t = useT()
   const router = useRouter()
   const searchParams = useSearchParams()
+  const pathname = usePathname()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
   const detailTranslator = React.useMemo(() => createTranslatorWithFallback(t), [t])
 
@@ -80,6 +82,20 @@ export default function DealDetailPage({ params }: { params?: { id?: string } })
     data,
   })
 
+  // Publish page-load record context with explicit `updatedAt`/`data` to the
+  // AppShell-owned `backend:record:current` mount. The deal path is already in the
+  // widget's allowlist (presence works) but supplied no version/record payload —
+  // this gives the merge dialog its action-log base and field-diff source.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'customers.deal',
+      resourceId: data?.deal.id ?? null,
+      updatedAt: data?.deal.updatedAt ?? null,
+      data: data as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   const notesAdapter = React.useMemo(
     () => createCustomerNotesAdapter(detailTranslator, { runMutation: runMutationWithContext }),
     [detailTranslator, runMutationWithContext],
@@ -171,6 +187,7 @@ export default function DealDetailPage({ params }: { params?: { id?: string } })
     data,
     setData,
     runMutationWithContext,
+    onRefresh: () => { void loadData() },
   })
 
   const { isStageSaving, handleStageChange } = useDealPipeline({
@@ -195,6 +212,7 @@ export default function DealDetailPage({ params }: { params?: { id?: string } })
     handleLostConfirm,
   } = useDealClosure({
     currentDealId,
+    dealUpdatedAt: data?.deal.updatedAt ?? null,
     runMutationWithContext,
     confirmDiscardIfDirty,
     onClosed: loadData,
@@ -365,6 +383,8 @@ export default function DealDetailPage({ params }: { params?: { id?: string } })
         showAssociationsGroup={false}
         showVersionHistory={false}
         showCancelAction={false}
+        injectionSpotId="crud-form:customers.deal"
+        optimisticLockUpdatedAt={data.deal.updatedAt}
         onDirtyChange={setIsDirty}
         initialPipelineOptions={formPipelineOptions}
         initialPipelineStageOptions={data.pipelineStages}