@open-mercato/core 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4559.1.839e136509

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

@@ -7,7 +7,8 @@ import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { mapCrudServerErrorToFormErrors } from '@open-mercato/ui/backend/utils/serverErrors'
 import { E } from '#generated/entities.ids.generated'
@@ -68,6 +69,7 @@ type PersonOverview = {
     nextInteractionIcon?: string | null
     nextInteractionColor?: string | null
     organizationId?: string | null
+    updatedAt?: string | null
   }
   profile: {
     id: string
@@ -317,19 +319,31 @@ export default function CustomerPersonDetailPage({ params }: { params?: { id?: s
     async (patch: Record<string, unknown>, apply: (prev: PersonOverview) => PersonOverview) => {
       if (!data) return
       const payload = { id: data.person.id, ...patch }
-      await runMutationWithContext(
-        () => apiCallOrThrow(
-          '/api/customers/people',
-          {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(payload),
-          },
-          { errorMessage: t('customers.people.detail.inline.error') },
+      const result = await runMutationWithContext(
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader((data?.person as { updatedAt?: string } | undefined)?.updatedAt),
+          () => apiCallOrThrow<{ ok?: boolean; updatedAt?: string | null }>(
+            '/api/customers/people',
+            {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(payload),
+            },
+            { errorMessage: t('customers.people.detail.inline.error') },
+          ),
         ),
         payload,
       )
-      setData((prev) => (prev ? apply(prev) : prev))
+      // Refresh the optimistic-lock token so the next sequential inline edit does not
+      // send a stale updatedAt and falsely 409 (#2055, default-ON locking).
+      const nextUpdatedAt = result?.result?.updatedAt ?? null
+      setData((prev) => {
+        if (!prev) return prev
+        const applied = apply(prev)
+        return nextUpdatedAt
+          ? { ...applied, person: { ...applied.person, updatedAt: nextUpdatedAt } }
+          : applied
+      })
     },
     [data, runMutationWithContext, t]
   )
@@ -382,13 +396,16 @@ export default function CustomerPersonDetailPage({ params }: { params?: { id?: s
     setIsDeleting(true)
     try {
       await runMutationWithContext(
-        () => apiCallOrThrow(
-          `/api/customers/people?id=${encodeURIComponent(personId)}`,
-          {
-            method: 'DELETE',
-            headers: { 'content-type': 'application/json' },
-          },
-          { errorMessage: t('customers.people.list.deleteError') },
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader((data?.person as { updatedAt?: string } | undefined)?.updatedAt),
+          () => apiCallOrThrow(
+            `/api/customers/people?id=${encodeURIComponent(personId)}`,
+            {
+              method: 'DELETE',
+              headers: { 'content-type': 'application/json' },
+            },
+            { errorMessage: t('customers.people.list.deleteError') },
+          ),
         ),
         { id: personId },
       )
@@ -428,14 +445,17 @@ export default function CustomerPersonDetailPage({ params }: { params?: { id?: s
           customFields: customPayload,
         }
         await runMutationWithContext(
-          () => apiCallOrThrow(
-            '/api/customers/people',
-            {
-              method: 'PUT',
-              headers: { 'content-type': 'application/json' },
-              body: JSON.stringify(payload),
-            },
-            { errorMessage: t('customers.people.detail.inline.error') },
+          () => withScopedApiRequestHeaders(
+            buildOptimisticLockHeader((data?.person as { updatedAt?: string } | undefined)?.updatedAt),
+            () => apiCallOrThrow(
+              '/api/customers/people',
+              {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+              },
+              { errorMessage: t('customers.people.detail.inline.error') },
+            ),
           ),
           payload,
         )

package/src/modules/customers/backend/customers/people/page.tsx

@@ -461,6 +461,7 @@ export default function CustomersPeoplePage() {
     try {
       await runSingleMutation({
         operation: async () => {
+          // optimistic-lock-exempt: delete-only mutation — no field-level lost-update
           await apiCallOrThrow(
             `/api/customers/people?id=${encodeURIComponent(person.id)}`,
             {
@@ -500,6 +501,7 @@ export default function CustomersPeoplePage() {
         runBulkDelete(
           selectedRows,
           async (row) => {
+            // optimistic-lock-exempt: bulk delete-only mutation — no field-level lost-update
             await apiCallOrThrow(`/api/customers/people?id=${encodeURIComponent(row.id)}`, {
               method: 'DELETE',
               headers: { 'content-type': 'application/json' },

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

@@ -7,12 +7,16 @@ import { User, Hash, Users, Building2 } from 'lucide-react'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { CollapsibleZoneLayout, type ZoneSectionDescriptor } from '@open-mercato/ui/backend/crud/CollapsibleZoneLayout'
+import { useIsMobile } from '@open-mercato/ui/hooks/useIsMobile'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { E } from '#generated/entities.ids.generated'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useOrganizationScopeDetail } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -53,6 +57,7 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
   const router = useRouter()
   const searchParams = useSearchParams()
   const { organizationId } = useOrganizationScopeDetail()
+  const isMobile = useIsMobile()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
 
   const detailTranslator = React.useMemo(() => createTranslatorWithFallback(t), [t])
@@ -62,6 +67,15 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
   const fields = React.useMemo(() => createPersonEditFields(t), [t])
 
   const [data, setData] = React.useState<PersonOverview | null>(null)
+  // Mirror the latest `data` into a ref so save handlers always read the current
+  // optimistic-lock token (`person.updatedAt`) instead of the value captured in
+  // their `useCallback` closure. Without this, a header-field save issued after a
+  // prior in-page reload would send a stale token (or none), letting a concurrent
+  // two-tab overwrite slip through without the 409 + conflict bar (#2055, Alina A7).
+  const dataRef = React.useRef<PersonOverview | null>(null)
+  React.useEffect(() => {
+    dataRef.current = data
+  }, [data])
   const [isLoading, setIsLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -124,7 +138,7 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
 
   // Data loading
   const initialLoadDoneRef = React.useRef(false)
-  const loadData = React.useCallback(async () => {
+  const loadData = React.useCallback(async (lockTokenOverride?: string | null) => {
     if (!id) {
       setIsNotFound(true)
       setIsLoading(false)
@@ -141,7 +155,15 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
         undefined,
         { errorMessage: t('customers.people.detail.error.load', 'Failed to load person.') },
       )
-      setData(payload as PersonOverview)
+      // When the caller is the save handler, pin the optimistic-lock token to the
+      // value the write itself returned rather than the one this GET observed — a
+      // concurrent third-party bump between save and reload must stay stale so the
+      // next in-page save 409s (#2055, Alina A7). Applied in the same state update
+      // as the refresh to avoid a redundant second re-render.
+      const next = lockTokenOverride && payload?.person
+        ? { ...payload, person: { ...payload.person, updatedAt: lockTokenOverride, updated_at: lockTokenOverride } }
+        : payload
+      setData(next as PersonOverview)
     } catch (err) {
       if ((err as { status?: number }).status === 404) {
         setIsNotFound(true)
@@ -230,6 +252,7 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
     // moment instead of "today" (#1807 prefill).
     const editPayload = {
       id: activity.id,
+      updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt as string : typeof raw.updated_at === 'string' ? raw.updated_at as string : null,
       interactionType: typeof activity.interactionType === 'string' ? activity.interactionType : undefined,
       title: typeof activity.title === 'string' ? activity.title : null,
       body: typeof activity.body === 'string' ? activity.body : null,
@@ -329,9 +352,27 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
           throw err
         }
 
-        await updateCrud('customers/people', payload)
+        // Attach the current optimistic-lock token directly on this write path so
+        // every header-field edit (displayName/status/…) carries `updatedAt`, not
+        // just the fields the embedded CrudForm intercepts. Read from `dataRef` so
+        // the token reflects the latest in-page reload rather than a stale closure
+        // capture, and let the 409 propagate to CrudForm's surfaceRecordConflict so
+        // the unified conflict bar renders (#2055, Alina A7).
+        const lockedUpdatedAt = dataRef.current?.person?.updatedAt
+          ?? dataRef.current?.person?.updated_at
+          ?? null
+        const updateResponse = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(lockedUpdatedAt),
+          () => updateCrud<{ updatedAt?: string | null }>('customers/people', payload),
+        )
         flash(t('customers.people.form.updateSuccess', 'Person updated.'), 'success')
-        await loadData()
+        // Refresh the view and pin the optimistic-lock token to the write's OWN
+        // authoritative `updatedAt` in a single reload (see loadData) so a
+        // concurrent third-party bump stays stale on the next save (#2055, Alina A7).
+        const savedUpdatedAt = typeof updateResponse.result?.updatedAt === 'string'
+          ? updateResponse.result.updatedAt
+          : null
+        await loadData(savedUpdatedAt)
       } finally {
         setIsSaving(false)
       }
@@ -351,10 +392,28 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
         variant: 'destructive',
       })
       if (!approved) return
-      await runMutationWithContext(
-        () => deleteCrud('customers/people', { id: personId }),
-        { id: personId, operation: 'deletePerson' },
-      )
+      try {
+        await runMutationWithContext(
+          () => withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(data?.person?.updatedAt ?? data?.person?.updated_at ?? null),
+            () => deleteCrud('customers/people', { id: personId }),
+          ),
+          { id: personId, operation: 'deletePerson' },
+        )
+      } catch (err) {
+        // The guarded mutation routes a 409 to the unified conflict bar; surface
+        // any other server error (e.g. a linked-records delete guard) as a flash
+        // instead of letting it crash the page.
+        if (!surfaceRecordConflict(err, t)) {
+          flash(
+            err instanceof Error && err.message.trim().length > 0
+              ? err.message
+              : t('customers.people.detail.deleteError', 'Failed to delete person.'),
+            'error',
+          )
+        }
+        return
+      }
       flash(t('customers.people.list.deleteSuccess', 'Person deleted.'), 'success')
       router.push('/backend/customers/people')
     },
@@ -464,6 +523,7 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
                   fields={fields}
                   groups={groups}
                   initialValues={initialValues}
+                  optimisticLockUpdatedAt={data.person.updatedAt ?? data.person.updated_at ?? null}
                   onSubmit={handleFormSubmit}
                   onDelete={handleFormDelete}
                   hideFooterActions
@@ -602,22 +662,22 @@ export default function PersonDetailV2Page({ params }: { params?: { id?: string
                 </div>
               </PersonDetailTabs>
             )
-            return (
-              <>
-                <div className="md:hidden">
-                  <MobilePersonDetail zone1={zone1Content} zone2={zone2Content} />
-                </div>
-                <div className="hidden md:block">
-                  <CollapsibleZoneLayout
-                    pageType="person-v2"
-                    entityName={personName}
-                    isDirty={isDirty}
-                    sections={zoneSections}
-                    zone1={zone1Content}
-                    zone2={zone2Content}
-                  />
-                </div>
-              </>
+            // Render only the layout variant that matches the viewport. Mounting
+            // both the mobile and desktop layouts at once would create two
+            // CrudForm instances bound to one `formWrapperRef`, so header Save
+            // could submit the hidden instance's stale values and silently
+            // discard the edit (#2453). `useIsMobile` is SSR-safe.
+            return isMobile ? (
+              <MobilePersonDetail zone1={zone1Content} zone2={zone2Content} />
+            ) : (
+              <CollapsibleZoneLayout
+                pageType="person-v2"
+                entityName={personName}
+                isDirty={isDirty}
+                sections={zoneSections}
+                zone1={zone1Content}
+                zone2={zone2Content}
+              />
             )
           })()}
 

package/src/modules/customers/commands/addresses.ts

@@ -213,22 +213,24 @@ const updateAddressCommand: CommandHandler<AddressUpdateInput, { addressId: stri
       ensureSameScope(entity, address.organizationId, address.tenantId)
       address.entity = entity
     }
-    if (parsed.name !== undefined) address.name = parsed.name ?? null
-    if (parsed.purpose !== undefined) address.purpose = parsed.purpose ?? null
-    if (parsed.companyName !== undefined) address.companyName = parsed.companyName ?? null
-    if (parsed.addressLine1 !== undefined) address.addressLine1 = parsed.addressLine1
-    if (parsed.addressLine2 !== undefined) address.addressLine2 = parsed.addressLine2 ?? null
-    if (parsed.buildingNumber !== undefined) address.buildingNumber = parsed.buildingNumber ?? null
-    if (parsed.flatNumber !== undefined) address.flatNumber = parsed.flatNumber ?? null
-    if (parsed.city !== undefined) address.city = parsed.city ?? null
-    if (parsed.region !== undefined) address.region = parsed.region ?? null
-    if (parsed.postalCode !== undefined) address.postalCode = parsed.postalCode ?? null
-    if (parsed.country !== undefined) address.country = parsed.country ?? null
-    if (parsed.latitude !== undefined) address.latitude = parsed.latitude ?? null
-    if (parsed.longitude !== undefined) address.longitude = parsed.longitude ?? null
-    if (parsed.isPrimary !== undefined) address.isPrimary = parsed.isPrimary
 
     await withAtomicFlush(em, [
+      () => {
+        if (parsed.name !== undefined) address.name = parsed.name ?? null
+        if (parsed.purpose !== undefined) address.purpose = parsed.purpose ?? null
+        if (parsed.companyName !== undefined) address.companyName = parsed.companyName ?? null
+        if (parsed.addressLine1 !== undefined) address.addressLine1 = parsed.addressLine1
+        if (parsed.addressLine2 !== undefined) address.addressLine2 = parsed.addressLine2 ?? null
+        if (parsed.buildingNumber !== undefined) address.buildingNumber = parsed.buildingNumber ?? null
+        if (parsed.flatNumber !== undefined) address.flatNumber = parsed.flatNumber ?? null
+        if (parsed.city !== undefined) address.city = parsed.city ?? null
+        if (parsed.region !== undefined) address.region = parsed.region ?? null
+        if (parsed.postalCode !== undefined) address.postalCode = parsed.postalCode ?? null
+        if (parsed.country !== undefined) address.country = parsed.country ?? null
+        if (parsed.latitude !== undefined) address.latitude = parsed.latitude ?? null
+        if (parsed.longitude !== undefined) address.longitude = parsed.longitude ?? null
+        if (parsed.isPrimary !== undefined) address.isPrimary = parsed.isPrimary
+      },
       async () => {
         if (address.isPrimary) {
           await enforcePrimaryAddress(em, typeof address.entity === 'string' ? address.entity : address.entity.id, address.id)

package/src/modules/customers/commands/companies.ts

@@ -677,7 +677,9 @@ const updateCompanyCommand: CommandHandler<CompanyUpdateInput, { entityId: strin
     })
     await emitQueryIndexUpsertEvents(ctx, [companyEntityIndexEntry(record)])
 
-    return { entityId: record.id }
+    // Expose the freshly-bumped updatedAt so the CRUD update response can hand it to
+    // inline-edit detail pages for sequential-save lock-token refresh (#2055).
+    return { entityId: record.id, updatedAt: record.updatedAt }
   },
   captureAfter: async (_input, result, ctx) => {
     const em = (ctx.container.resolve('em') as EntityManager).fork()

package/src/modules/customers/commands/interactions.ts

@@ -38,6 +38,7 @@ import {
   buildCustomFieldResetMap,
 } from '@open-mercato/shared/lib/commands/customFieldSnapshots'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceRecordGoneIsConflict, enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import type { CrudIndexerConfig, CrudEventsConfig } from '@open-mercato/shared/lib/crud/types'
 import { recomputeNextInteraction } from '../lib/interactionProjection'
@@ -451,10 +452,25 @@ const updateInteractionCommand: CommandHandler<InteractionUpdateInput, { interac
     const em = (ctx.container.resolve('em') as EntityManager).fork()
     const { interaction, entityId, nextInteractionId } = await runInTransaction(em, async (trx) => {
       const interaction = await findOneWithDecryption(trx, CustomerInteraction, { id: parsed.id, deletedAt: null })
-      if (!interaction) throw new CrudHttpError(404, { error: 'Interaction not found' })
+      if (!interaction) {
+        enforceRecordGoneIsConflict({ resourceKind: 'customers.interaction', resourceId: parsed.id, request: ctx.request ?? null })
+        throw new CrudHttpError(404, { error: 'Interaction not found' })
+      }
       ensureTenantScope(ctx, interaction.tenantId)
       ensureOrganizationScope(ctx, interaction.organizationId)
 
+      // Concurrent-edit guard for command-driven callers (e.g. the legacy
+      // /api/customers/todos route, which bypasses the makeCrudRoute lock guard):
+      // when the client opted into optimistic locking, a stale edit fails with the
+      // unified 409 instead of silently overwriting (#2055). Strictly additive —
+      // no-op when no expected-version header is present.
+      enforceCommandOptimisticLock({
+        resourceKind: 'customers.interaction',
+        resourceId: interaction.id,
+        current: interaction.updatedAt,
+        request: ctx.request ?? null,
+      })
+
       // Email visibility is an access-controlled field: only the interaction's
       // author may change a
       // private email's visibility (mirrors the dedicated PATCH .../visibility
@@ -709,10 +725,20 @@ const completeInteractionCommand: CommandHandler<InteractionCompleteInput, { int
     const em = (ctx.container.resolve('em') as EntityManager).fork()
     const { interaction, entityId, nextInteractionId } = await runInTransaction(em, async (trx) => {
       const interaction = await findOneWithDecryption(trx, CustomerInteraction, { id: parsed.id, deletedAt: null })
-      if (!interaction) throw new CrudHttpError(404, { error: 'Interaction not found' })
+      if (!interaction) {
+        enforceRecordGoneIsConflict({ resourceKind: 'customers.interaction', resourceId: parsed.id, request: ctx.request ?? null })
+        throw new CrudHttpError(404, { error: 'Interaction not found' })
+      }
       ensureTenantScope(ctx, interaction.tenantId)
       ensureOrganizationScope(ctx, interaction.organizationId)
 
+      enforceCommandOptimisticLock({
+        resourceKind: 'customers.interaction',
+        resourceId: interaction.id,
+        current: interaction.updatedAt,
+        request: ctx.request ?? null,
+      })
+
       interaction.status = 'done'
       interaction.occurredAt = parsed.occurredAt ?? new Date()
       await trx.flush()
@@ -839,10 +865,20 @@ const cancelInteractionCommand: CommandHandler<InteractionCancelInput, { interac
     const em = (ctx.container.resolve('em') as EntityManager).fork()
     const { interaction, entityId, nextInteractionId } = await runInTransaction(em, async (trx) => {
       const interaction = await findOneWithDecryption(trx, CustomerInteraction, { id: parsed.id, deletedAt: null })
-      if (!interaction) throw new CrudHttpError(404, { error: 'Interaction not found' })
+      if (!interaction) {
+        enforceRecordGoneIsConflict({ resourceKind: 'customers.interaction', resourceId: parsed.id, request: ctx.request ?? null })
+        throw new CrudHttpError(404, { error: 'Interaction not found' })
+      }
       ensureTenantScope(ctx, interaction.tenantId)
       ensureOrganizationScope(ctx, interaction.organizationId)
 
+      enforceCommandOptimisticLock({
+        resourceKind: 'customers.interaction',
+        resourceId: interaction.id,
+        current: interaction.updatedAt,
+        request: ctx.request ?? null,
+      })
+
       interaction.status = 'canceled'
       await trx.flush()
 
@@ -967,10 +1003,20 @@ const deleteInteractionCommand: CommandHandler<{ body?: Record<string, unknown>;
       const em = (ctx.container.resolve('em') as EntityManager).fork()
       const { interaction, entityId, nextInteractionId } = await runInTransaction(em, async (trx) => {
         const interaction = await findOneWithDecryption(trx, CustomerInteraction, { id, deletedAt: null })
-        if (!interaction) throw new CrudHttpError(404, { error: 'Interaction not found' })
+        if (!interaction) {
+          enforceRecordGoneIsConflict({ resourceKind: 'customers.interaction', resourceId: id, request: ctx.request ?? null })
+          throw new CrudHttpError(404, { error: 'Interaction not found' })
+        }
         ensureTenantScope(ctx, interaction.tenantId)
         ensureOrganizationScope(ctx, interaction.organizationId)
 
+        enforceCommandOptimisticLock({
+          resourceKind: 'customers.interaction',
+          resourceId: interaction.id,
+          current: interaction.updatedAt,
+          request: ctx.request ?? null,
+        })
+
         const entityId = typeof interaction.entity === 'string' ? interaction.entity : interaction.entity.id
         interaction.deletedAt = new Date()
         await trx.flush()

package/src/modules/customers/commands/people.ts

@@ -866,7 +866,8 @@ const updatePersonCommand: CommandHandler<PersonUpdateInput, { entityId: string
     })
     await emitQueryIndexUpsertEvents(ctx, [personEntityIndexEntry(record)])
 
-    return { entityId: record.id }
+    // Expose the freshly-bumped updatedAt for inline-edit sequential-save lock refresh (#2055).
+    return { entityId: record.id, updatedAt: record.updatedAt }
   },
   captureAfter: async (_input, result, ctx) => {
     const em = (ctx.container.resolve('em') as EntityManager).fork()

package/src/modules/customers/commands/personCompanyLinks.ts

@@ -382,6 +382,7 @@ const updatePersonCompanyLinkCommand: CommandHandler<PersonCompanyLinkUpdateInpu
     const profile = await requirePersonProfile(em, person)
     const linkedCompany = await requireCompanyEntity(em, companyId, parsed.tenantId, parsed.organizationId)
 
+    const linkWasPrimary = link.isPrimary
     await withAtomicFlush(em, [
       async () => {
         if (parsed.isPrimary) {
@@ -389,16 +390,18 @@ const updatePersonCompanyLinkCommand: CommandHandler<PersonCompanyLinkUpdateInpu
           link.isPrimary = true
           profile.company = linkedCompany
         } else if (!parsed.isPrimary) {
-          const linkWasPrimary = link.isPrimary
           link.isPrimary = false
-          if (linkWasPrimary) {
-            const remainingLinks = (await loadPersonCompanyLinks(em, person)).filter((entry) => entry.id !== link.id)
-            await promoteFallbackPrimaryLink(em, person, profile, remainingLinks, companyId)
-          } else if (profile.company && typeof profile.company !== 'string' && profile.company.id === companyId) {
+          if (!linkWasPrimary && profile.company && typeof profile.company !== 'string' && profile.company.id === companyId) {
             profile.company = null
           }
         }
       },
+      async () => {
+        if (!parsed.isPrimary && linkWasPrimary) {
+          const remainingLinks = (await loadPersonCompanyLinks(em, person)).filter((entry) => entry.id !== link.id)
+          await promoteFallbackPrimaryLink(em, person, profile, remainingLinks, companyId)
+        }
+      },
     ], { transaction: true })
 
     const dataEngine = ctx.container.resolve('dataEngine') as DataEngine

package/src/modules/customers/commands/pipeline-stages.ts

@@ -49,18 +49,6 @@ const createPipelineStageCommand: CommandHandler<PipelineStageCreateInput, { sta
         ? existingStages.length
         : Math.max(0, Math.min(requestedOrder, existingStages.length))
 
-    // Shift the order of every stage at or after the insert position. Skipping
-    // this step would either duplicate `order` values (silently corrupting kanban
-    // ordering) or push the new stage to the wrong spot when re-sorting.
-    if (requestedOrder !== undefined) {
-      for (const stage of existingStages) {
-        if (stage.order >= insertOrder) {
-          stage.order += 1
-          stage.updatedAt = new Date()
-        }
-      }
-    }
-
     const stage = em.create(CustomerPipelineStage, {
       organizationId: parsed.organizationId,
       tenantId: parsed.tenantId,
@@ -73,6 +61,17 @@ const createPipelineStageCommand: CommandHandler<PipelineStageCreateInput, { sta
 
     await withAtomicFlush(em, [
       () => {
+        // Shift the order of every stage at or after the insert position. Skipping
+        // this step would either duplicate `order` values (silently corrupting kanban
+        // ordering) or push the new stage to the wrong spot when re-sorting.
+        if (requestedOrder !== undefined) {
+          for (const existing of existingStages) {
+            if (existing.order >= insertOrder) {
+              existing.order += 1
+              existing.updatedAt = new Date()
+            }
+          }
+        }
         em.persist(stage)
       },
       async () => {
@@ -112,11 +111,12 @@ const updatePipelineStageCommand: CommandHandler<PipelineStageUpdateInput, void>
     ensureTenantScope(ctx, stage.tenantId)
     ensureOrganizationScope(ctx, stage.organizationId)
 
-    if (parsed.label !== undefined) stage.label = parsed.label
-    if (parsed.order !== undefined) stage.order = parsed.order
-    stage.updatedAt = new Date()
-
     await withAtomicFlush(em, [
+      () => {
+        if (parsed.label !== undefined) stage.label = parsed.label
+        if (parsed.order !== undefined) stage.order = parsed.order
+        stage.updatedAt = new Date()
+      },
       async () => {
         if (parsed.label !== undefined || parsed.color !== undefined || parsed.icon !== undefined) {
           await ensureDictionaryEntry(em, {

package/src/modules/customers/components/AddressFormatSettings.tsx

@@ -87,6 +87,7 @@ export function AddressFormatSettings() {
       setPending(next)
       setError(null)
       try {
+        // optimistic-lock-exempt: single-row tenant address-format preference toggle — no per-record version / concurrent record edit
         const call = await apiCall<Record<string, unknown>>(
           '/api/customers/settings/address-format',
           {

package/src/modules/customers/components/DictionarySettings.tsx

@@ -8,7 +8,8 @@ import {
   DialogTitle,
 } from '@open-mercato/ui/primitives/dialog'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
@@ -220,10 +221,12 @@ function CustomerDictionarySection({ kind, title, description }: CustomerDiction
     })
     if (!confirmed) return
     try {
-      await apiCallOrThrow(
-        `/api/customers/dictionaries/${kind}/${encodeURIComponent(entry.id)}`,
-        { method: 'DELETE' },
-        { errorMessage: errorDelete },
+      await withScopedApiRequestHeaders(buildOptimisticLockHeader(entry.updatedAt), () =>
+        apiCallOrThrow(
+          `/api/customers/dictionaries/${kind}/${encodeURIComponent(entry.id)}`,
+          { method: 'DELETE' },
+          { errorMessage: errorDelete },
+        ),
       )
       flash(successDelete, 'success')
       await loadEntries()
@@ -281,14 +284,16 @@ function CustomerDictionarySection({ kind, title, description }: CustomerDiction
           closeDialog()
           return
         }
-        await apiCallOrThrow(
-          `/api/customers/dictionaries/${kind}/${encodeURIComponent(target.id)}`,
-          {
-            method: 'PATCH',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(body),
-          },
-          { errorMessage: errorSave },
+        await withScopedApiRequestHeaders(buildOptimisticLockHeader(target.updatedAt), () =>
+          apiCallOrThrow(
+            `/api/customers/dictionaries/${kind}/${encodeURIComponent(target.id)}`,
+            {
+              method: 'PATCH',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(body),
+            },
+            { errorMessage: errorSave },
+          ),
         )
         flash(successSave, 'success')
       }

package/src/modules/customers/components/DictionarySortSettings.tsx

@@ -170,6 +170,10 @@ export function DictionarySortSettings() {
     setError(null)
     try {
       await runMutation({
+        // optimistic-lock-exempt: tenant-scoped settings blob (dictionary sort
+        // modes), not a versioned per-record entity — there is no `updatedAt`
+        // round-trip to lock against, and concurrent writes converge on the
+        // last-selected preference. Mirrors other singleton settings PATCHes.
         operation: async () => {
           await apiCallOrThrow(
             '/api/customers/settings/dictionary-sort-modes',