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

package/src/backend/__tests__/NotesSection.test.tsx

@@ -4,9 +4,12 @@ import * as React from 'react'
 import { fireEvent, screen, waitFor } from '@testing-library/react'
 import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
 import { NotesSection, type NotesDataAdapter } from '../detail/NotesSection'
+import { dismissRecordConflict, getRecordConflictForTest } from '../conflicts'
+import { OPTIMISTIC_LOCK_CONFLICT_CODE } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
 
 describe('NotesSection', () => {
   beforeEach(() => {
+    dismissRecordConflict()
     Object.defineProperty(Element.prototype, 'scrollIntoView', {
       configurable: true,
       writable: true,
@@ -22,6 +25,10 @@ describe('NotesSection', () => {
     })
   })
 
+  afterEach(() => {
+    dismissRecordConflict()
+  })
+
   it('keeps an add-note action visible after notes already exist', async () => {
     const dataAdapter: NotesDataAdapter = {
       list: jest.fn(async () => [
@@ -60,4 +67,68 @@ describe('NotesSection', () => {
       expect(container.querySelector('textarea')).not.toBeNull()
     })
   })
+
+  it('surfaces the unified conflict bar when a write fails with a 409', async () => {
+    const conflict = {
+      status: 409,
+      body: {
+        error: 'optimistic_lock_conflict',
+        code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+        currentUpdatedAt: '2026-06-02T00:00:00.000Z',
+        expectedUpdatedAt: '2026-06-01T00:00:00.000Z',
+      },
+    }
+    const dataAdapter: NotesDataAdapter = {
+      list: jest.fn(async () => [
+        {
+          id: 'note-1',
+          body: 'Existing note',
+          createdAt: '2026-04-10T08:00:00.000Z',
+          authorName: 'Ada Lovelace',
+        },
+      ]),
+      create: jest.fn(async () => {
+        throw conflict
+      }),
+      update: jest.fn(async () => undefined),
+      delete: jest.fn(async () => undefined),
+    }
+
+    const { container } = renderWithProviders(
+      <NotesSection
+        entityId="person-1"
+        emptyLabel="—"
+        viewerUserId="user-1"
+        viewerName="Ada Lovelace"
+        addActionLabel="Add note"
+        emptyState={{
+          title: 'No notes yet',
+          actionLabel: 'Add note',
+        }}
+        dataAdapter={dataAdapter}
+        disableMarkdown
+      />,
+    )
+
+    await screen.findByText('Existing note')
+    fireEvent.click(screen.getByRole('button', { name: 'Add note' }))
+
+    const textarea = await waitFor(() => {
+      const el = container.querySelector('textarea')
+      if (!el) throw new Error('composer not open')
+      return el as HTMLTextAreaElement
+    })
+    fireEvent.change(textarea, { target: { value: 'Conflicting note' } })
+
+    const form = container.querySelector('form')
+    expect(form).not.toBeNull()
+    fireEvent.submit(form as HTMLFormElement)
+
+    await waitFor(() => {
+      expect(dataAdapter.create).toHaveBeenCalledTimes(1)
+      const entry = getRecordConflictForTest()
+      expect(entry).not.toBeNull()
+      expect(entry?.currentUpdatedAt).toBe('2026-06-02T00:00:00.000Z')
+    })
+  })
 })

package/src/backend/conflicts/__tests__/recordLockDeferral.test.ts

@@ -0,0 +1,99 @@
+/** @jest-environment jsdom */
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { OPTIMISTIC_LOCK_CONFLICT_CODE } from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+import {
+  dismissRecordConflict,
+  getRecordConflictForTest,
+  registerRecordLockConflictHandler,
+  resetRecordLockConflictHandlerForTest,
+  surfaceRecordConflict,
+} from '..'
+
+const t = (key: string, fallback?: string) => fallback ?? key
+
+function recordLockConflict() {
+  return new CrudHttpError(409, {
+    error: 'Record conflict detected',
+    code: 'record_lock_conflict',
+    lock: null,
+    conflict: { id: 'c1' },
+  })
+}
+
+function ossConflict() {
+  return new CrudHttpError(409, {
+    error: 'record_modified',
+    code: OPTIMISTIC_LOCK_CONFLICT_CODE,
+    currentUpdatedAt: '2026-06-01T00:00:01.000Z',
+    expectedUpdatedAt: '2026-06-01T00:00:00.000Z',
+  })
+}
+
+describe('surfaceRecordConflict — single surface (S3)', () => {
+  beforeEach(() => {
+    dismissRecordConflict()
+    resetRecordLockConflictHandlerForTest()
+  })
+  afterEach(() => {
+    dismissRecordConflict()
+    resetRecordLockConflictHandlerForTest()
+  })
+
+  it('defers a record_lock_conflict to the registered merge-dialog handler that owns the record (returns true → no OSS bar)', () => {
+    const handler = jest.fn(() => true)
+    registerRecordLockConflictHandler(handler)
+
+    const handled = surfaceRecordConflict(recordLockConflict(), t)
+
+    expect(handled).toBe(true)
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(handler.mock.calls[0][0]).toMatchObject({ code: 'record_lock_conflict' })
+    // The OSS conflict bar must NOT render when the dialog handles it.
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+
+  it('SAFETY: handler registered but DECLINES the record (returns false) → OSS bar still renders (never swallowed)', () => {
+    const handler = jest.fn(() => false)
+    registerRecordLockConflictHandler(handler)
+
+    const handled = surfaceRecordConflict(recordLockConflict(), t)
+
+    expect(handled).toBe(true)
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(getRecordConflictForTest()).not.toBeNull()
+  })
+
+  it('SAFETY: with NO handler registered, a record_lock_conflict still renders the OSS bar (never swallowed)', () => {
+    const handled = surfaceRecordConflict(recordLockConflict(), t)
+    expect(handled).toBe(true)
+    expect(getRecordConflictForTest()).not.toBeNull()
+  })
+
+  it('renders the OSS conflict bar for an optimistic_lock_conflict regardless of handler registration', () => {
+    const handler = jest.fn(() => true)
+    registerRecordLockConflictHandler(handler)
+    const handled = surfaceRecordConflict(ossConflict(), t)
+    expect(handled).toBe(true)
+    // The record-lock handler must NOT be consulted for an OSS optimistic-lock conflict.
+    expect(handler).not.toHaveBeenCalled()
+    const entry = getRecordConflictForTest()
+    expect(entry).not.toBeNull()
+    expect(entry?.currentUpdatedAt).toBe('2026-06-01T00:00:01.000Z')
+  })
+
+  it('unregister restores the no-handler behavior', () => {
+    const handler = jest.fn(() => true)
+    const unregister = registerRecordLockConflictHandler(handler)
+    unregister()
+
+    surfaceRecordConflict(recordLockConflict(), t)
+    expect(handler).not.toHaveBeenCalled()
+    expect(getRecordConflictForTest()).not.toBeNull()
+  })
+
+  it('returns false for a non-conflict error', () => {
+    expect(surfaceRecordConflict(new CrudHttpError(422, { error: 'validation_failed' }), t)).toBe(false)
+    expect(surfaceRecordConflict(new Error('boom'), t)).toBe(false)
+    expect(getRecordConflictForTest()).toBeNull()
+  })
+})

package/src/backend/conflicts/index.ts

@@ -1,4 +1,8 @@
-import { extractOptimisticLockConflict } from '../utils/optimisticLock'
+import {
+  extractOptimisticLockConflict,
+  extractRecordLockConflict,
+  type RecordLockConflictBody,
+} from '../utils/optimisticLock'
 import { showRecordConflict } from './store'
 
 export {
@@ -21,29 +25,102 @@ export type SurfaceRecordConflictOptions = {
 }
 
 /**
- * If `error` is an OSS optimistic-lock conflict (HTTP 409 with
- * `code: 'optimistic_lock_conflict'`), push the localized "record modified"
- * message onto the shared conflict bar and return `true`. Otherwise return
- * `false` so callers can fall back to their normal error handling.
+ * Handler the enterprise `record_locks` merge-dialog widget registers (on mount)
+ * so `surfaceRecordConflict` can defer the OSS conflict bar in favor of the
+ * field-level merge dialog. Core/UI stays enterprise-free: enterprise calls
+ * {@link registerRecordLockConflictHandler}; this module never imports it.
  *
- * This is the single entry point every form uses, so the conflict surfaces the
- * same persistent, error-styled bar everywhere.
+ * MUST return `true` only when it actually owns/renders the surface for THIS
+ * conflict (its widget is mounted for the conflicting record). Returning `false`
+ * (different record / cannot render) makes `surfaceRecordConflict` fall through
+ * to the OSS conflict bar, so a conflict is never swallowed and we never render
+ * BOTH the merge dialog and the bar (single surface, S3).
+ */
+export type RecordLockConflictHandler = (conflict: RecordLockConflictBody, error: unknown) => boolean
+
+let recordLockConflictHandler: RecordLockConflictHandler | null = null
+
+/**
+ * Register the record-lock conflict handler (enterprise merge-dialog widget).
+ * Returns an unregister function. When a handler is registered,
+ * `surfaceRecordConflict` defers `record_lock_conflict` 409s to it instead of
+ * rendering the OSS conflict bar (single surface, S3).
+ *
+ * SAFETY: when NO handler is registered (widget absent/removed),
+ * `surfaceRecordConflict` still renders the OSS conflict bar for ANY 409 — a
+ * conflict is never silently swallowed.
+ */
+export function registerRecordLockConflictHandler(handler: RecordLockConflictHandler): () => void {
+  recordLockConflictHandler = handler
+  return () => {
+    if (recordLockConflictHandler === handler) recordLockConflictHandler = null
+  }
+}
+
+/** Test-only: inspect whether a record-lock conflict handler is registered. */
+export function hasRecordLockConflictHandlerForTest(): boolean {
+  return recordLockConflictHandler !== null
+}
+
+/** Test-only: clear any registered record-lock conflict handler. */
+export function resetRecordLockConflictHandlerForTest(): void {
+  recordLockConflictHandler = null
+}
+
+/**
+ * Single conflict surface (S3). Resolves a 409 to exactly one UI:
+ *
+ *   - `record_lock_conflict` payload AND a merge-dialog handler registered →
+ *     defer to the handler (no conflict bar) and return `true`.
+ *   - otherwise (OSS `optimistic_lock_conflict`, OR a `record_lock_conflict`
+ *     with NO handler registered) → render the OSS conflict bar and return
+ *     `true`. A conflict is ALWAYS surfaced; the worst case is plainer UX, never
+ *     a silently-swallowed conflict.
+ *   - not a recognized conflict → return `false` so callers fall back to their
+ *     normal error handling.
  */
 export function surfaceRecordConflict(
   error: unknown,
   t: Translate,
   options: SurfaceRecordConflictOptions = {},
 ): boolean {
-  const conflict = extractOptimisticLockConflict(error)
-  if (!conflict) return false
-  showRecordConflict({
-    message: t(
-      'ui.forms.flash.recordModified',
-      'This record was modified by someone else. Refresh and try again.',
-    ),
-    title: options.title ?? null,
-    currentUpdatedAt: conflict.currentUpdatedAt,
-    onRefresh: options.onRefresh ?? null,
-  })
-  return true
+  const recordLockConflict = extractRecordLockConflict(error)
+  if (recordLockConflict && recordLockConflictHandler) {
+    // The widget owns the surface ONLY when it handles this record's conflict
+    // (returns true). If it declines (different record / not mounted for it),
+    // fall through to the OSS bar so the conflict is never swallowed and we
+    // never render both the merge dialog AND the bar.
+    if (recordLockConflictHandler(recordLockConflict, error)) return true
+  }
+
+  const ossConflict = extractOptimisticLockConflict(error)
+  if (ossConflict) {
+    showRecordConflict({
+      message: t(
+        'ui.forms.flash.recordModified',
+        'This record was modified by someone else. Refresh and try again.',
+      ),
+      title: options.title ?? null,
+      currentUpdatedAt: ossConflict.currentUpdatedAt,
+      onRefresh: options.onRefresh ?? null,
+    })
+    return true
+  }
+
+  // No handler is registered but the server returned a record-lock 409: still
+  // render the OSS bar so the conflict is never swallowed.
+  if (recordLockConflict) {
+    showRecordConflict({
+      message: t(
+        'ui.forms.flash.recordModified',
+        'This record was modified by someone else. Refresh and try again.',
+      ),
+      title: options.title ?? null,
+      currentUpdatedAt: null,
+      onRefresh: options.onRefresh ?? null,
+    })
+    return true
+  }
+
+  return false
 }

package/src/backend/detail/AddressesSection.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { surfaceRecordConflict } from '../conflicts'
 import { LoadingMessage } from '@open-mercato/ui/backend/detail'
 import { createTranslatorWithFallback } from '@open-mercato/shared/lib/i18n/translate'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -40,13 +41,14 @@ export type AddressSummary = {
   postalCode?: string | null
   country?: string | null
   isPrimary?: boolean
+  updatedAt?: string | null
 }
 
 export type AddressDataAdapter<C = unknown> = {
   list: (params: { entityId: string | null; context?: C }) => Promise<AddressSummary[]>
   create: (params: { entityId: string; payload: AddressInput; context?: C }) => Promise<{ id?: string } | void>
-  update: (params: { id: string; payload: AddressInput; context?: C }) => Promise<void>
-  delete: (params: { id: string; context?: C }) => Promise<void>
+  update: (params: { id: string; payload: AddressInput; updatedAt?: string | null; context?: C }) => Promise<void>
+  delete: (params: { id: string; updatedAt?: string | null; context?: C }) => Promise<void>
 }
 
 export type AddressesSectionProps<C = unknown> = {
@@ -205,7 +207,8 @@ function AddressesSectionImpl<C = unknown>({
       pushLoading()
       setIsSubmitting(true)
       try {
-        await dataAdapter.update({ id, payload, context: dataContext })
+        const addressUpdatedAt = addresses.find((address) => address.id === id)?.updatedAt ?? null
+        await dataAdapter.update({ id, payload, updatedAt: addressUpdatedAt, context: dataContext })
         setAddresses((prev) => {
           return prev.map((address) => {
             if (address.id !== id) {
@@ -230,6 +233,7 @@ function AddressesSectionImpl<C = unknown>({
         })
         flash(label('success', 'Address saved.'), 'success')
       } catch (err) {
+        surfaceRecordConflict(err, t)
         const message =
           err instanceof Error && err.message ? err.message : label('error', 'Failed to save address.')
         const error = new Error(message) as Error & { details?: unknown }
@@ -242,7 +246,7 @@ function AddressesSectionImpl<C = unknown>({
         popLoading()
       }
     },
-    [dataAdapter, dataContext, label, normalizedEntityId, popLoading, pushLoading],
+    [addresses, dataAdapter, dataContext, label, normalizedEntityId, popLoading, pushLoading, t],
   )
 
   const handleDelete = React.useCallback(
@@ -253,20 +257,21 @@ function AddressesSectionImpl<C = unknown>({
       pushLoading()
       setIsSubmitting(true)
       try {
-        await dataAdapter.delete({ id, context: dataContext })
+        const addressUpdatedAt = addresses.find((address) => address.id === id)?.updatedAt ?? null
+        await dataAdapter.delete({ id, updatedAt: addressUpdatedAt, context: dataContext })
         setAddresses((prev) => prev.filter((address) => address.id !== id))
         flash(label('deleted', 'Address deleted.'), 'success')
       } catch (err) {
         const message =
           err instanceof Error && err.message ? err.message : label('error', 'Failed to delete address.')
-        flash(message, 'error')
+        if (!surfaceRecordConflict(err, t)) flash(message, 'error')
         throw err
       } finally {
         setIsSubmitting(false)
         popLoading()
       }
     },
-    [dataAdapter, dataContext, label, normalizedEntityId, popLoading, pushLoading],
+    [addresses, dataAdapter, dataContext, label, normalizedEntityId, popLoading, pushLoading, t],
   )
 
   const displayAddresses = React.useMemo<AddressValue[]>(() => {

package/src/backend/detail/NotesSection.tsx

@@ -16,6 +16,7 @@ import {
   SelectValue,
 } from '@open-mercato/ui/primitives/select'
 import { flash } from '../FlashMessages'
+import { surfaceRecordConflict } from '../conflicts'
 import { SwitchableMarkdownInput } from '../inputs/SwitchableMarkdownInput'
 import { ErrorMessage } from './ErrorMessage'
 import { LoadingMessage } from './LoadingMessage'
@@ -48,6 +49,7 @@ export type CommentSummary = {
   id: string
   body: string
   createdAt: string
+  updatedAt?: string | null
   authorUserId?: string | null
   authorName?: string | null
   authorEmail?: string | null
@@ -87,8 +89,8 @@ export type NotesDataAdapter<C = unknown> = {
     totalPages: number
   }>
   create: (params: NotesCreatePayload & { context?: C }) => Promise<Partial<CommentSummary> | void>
-  update: (params: { id: string; patch: NotesUpdatePayload; context?: C }) => Promise<void>
-  delete: (params: { id: string; context?: C }) => Promise<void>
+  update: (params: { id: string; patch: NotesUpdatePayload; updatedAt?: string | null; context?: C }) => Promise<void>
+  delete: (params: { id: string; updatedAt?: string | null; context?: C }) => Promise<void>
 }
 
 type RenderIconFn = (icon: string, className?: string) => React.ReactNode
@@ -221,6 +223,12 @@ export function mapCommentSummary(input: unknown): CommentSummary {
       : typeof data.created_at === 'string'
         ? data.created_at
         : new Date().toISOString()
+  const updatedAt =
+    typeof data.updatedAt === 'string'
+      ? data.updatedAt
+      : typeof data.updated_at === 'string'
+        ? data.updated_at
+        : null
   const authorUserId =
     typeof data.authorUserId === 'string'
       ? data.authorUserId
@@ -267,6 +275,7 @@ export function mapCommentSummary(input: unknown): CommentSummary {
     id,
     body,
     createdAt,
+    updatedAt,
     authorUserId,
     authorName,
     authorEmail,
@@ -678,7 +687,7 @@ function NotesSectionImpl<C = unknown>({
         return true
       } catch (err) {
         const message = err instanceof Error ? err.message : label('error')
-        flash(message, 'error')
+        if (!surfaceRecordConflict(err, t)) flash(message, 'error')
         return false
       } finally {
         setIsSubmitting(false)
@@ -699,6 +708,7 @@ function NotesSectionImpl<C = unknown>({
             : undefined
       const sanitizedColor =
         patch.appearanceColor !== undefined ? sanitizeHexColor(patch.appearanceColor ?? null) : undefined
+      const noteUpdatedAt = notes.find((comment) => comment.id === noteId)?.updatedAt ?? null
       try {
         await dataAdapter.update({
           id: noteId,
@@ -707,6 +717,7 @@ function NotesSectionImpl<C = unknown>({
             appearanceIcon: sanitizedIcon,
             appearanceColor: sanitizedColor,
           },
+          updatedAt: noteUpdatedAt,
           context: dataContext,
         })
         setNotes((prev) => {
@@ -723,11 +734,11 @@ function NotesSectionImpl<C = unknown>({
         flash(label('updateSuccess'), 'success')
       } catch (error) {
         const message = error instanceof Error ? error.message : label('updateError')
-        flash(message, 'error')
+        if (!surfaceRecordConflict(error, t)) flash(message, 'error')
         throw error instanceof Error ? error : new Error(message)
       }
     },
-    [dataAdapter, dataContext, t],
+    [dataAdapter, dataContext, notes, t],
   )
 
   const handleDeleteNote = React.useCallback(
@@ -740,7 +751,7 @@ function NotesSectionImpl<C = unknown>({
       setDeletingNoteId(note.id)
       pushLoading()
       try {
-        await dataAdapter.delete({ id: note.id, context: dataContext })
+        await dataAdapter.delete({ id: note.id, updatedAt: note.updatedAt ?? null, context: dataContext })
         setNotes((prev) => prev.filter((existing) => existing.id !== note.id))
         if (pagedMode) {
           setVisibleCount((prev) => Math.max(0, prev - 1))
@@ -748,13 +759,13 @@ function NotesSectionImpl<C = unknown>({
         flash(label('deleteSuccess', 'Note deleted'), 'success')
       } catch (err) {
         const message = err instanceof Error ? err.message : label('deleteError', 'Failed to delete note')
-        flash(message, 'error')
+        if (!surfaceRecordConflict(err, t)) flash(message, 'error')
       } finally {
         setDeletingNoteId(null)
         popLoading()
       }
     },
-    [confirm, dataAdapter, dataContext, label, popLoading, pushLoading],
+    [confirm, dataAdapter, dataContext, label, popLoading, pushLoading, t],
   )
 
   const handleSubmit = React.useCallback(

package/src/backend/injection/recordContext.tsx

@@ -0,0 +1,101 @@
+'use client'
+import * as React from 'react'
+
+/**
+ * AppShell-owned transport for the current detail record's injection context
+ * (Phase 0 / S2). The `backend:record:current` injection spot is mounted once,
+ * globally, by `AppShell` — before page `children` — so a page cannot pass props
+ * "up" to it. Instead, a detail page publishes its record context through this
+ * provider; `AppShell` merges it into the spot's base `{ path, query }` context.
+ *
+ * Keeps `packages/ui`/core enterprise-free: this is a plain context object, no
+ * record_locks dependency, no second `<InjectionSpot>`.
+ */
+export type RecordInjectionContext = {
+  /** record_locks resource key, e.g. `customers.person`, `sales.order`. */
+  resourceKind: string
+  /** The record's id. */
+  resourceId: string
+  /** Server `updated_at` (ISO) for the optimistic-lock floor + action-log base. */
+  updatedAt?: string | null
+  /** Optional record payload for field-level merge UX. */
+  data?: Record<string, unknown> | null
+  /** The detail screen path this context belongs to (used for stale-context guarding). */
+  path?: string | null
+}
+
+/**
+ * Build a normalized record injection context. Returns `null` when the required
+ * keys are missing so callers can publish unconditionally.
+ */
+export function buildRecordInjectionContext(input: {
+  resourceKind: string | null | undefined
+  resourceId: string | null | undefined
+  updatedAt?: string | Date | null
+  data?: Record<string, unknown> | null
+  path?: string | null
+}): RecordInjectionContext | null {
+  const resourceKind = typeof input.resourceKind === 'string' ? input.resourceKind.trim() : ''
+  const resourceId = typeof input.resourceId === 'string' ? input.resourceId.trim() : ''
+  if (!resourceKind || !resourceId) return null
+  const updatedAt = input.updatedAt instanceof Date
+    ? input.updatedAt.toISOString()
+    : (typeof input.updatedAt === 'string' && input.updatedAt.trim().length ? input.updatedAt.trim() : null)
+  return {
+    resourceKind,
+    resourceId,
+    updatedAt,
+    data: input.data ?? null,
+    path: typeof input.path === 'string' && input.path.length ? input.path : null,
+  }
+}
+
+type RecordInjectionContextSetter = (context: RecordInjectionContext | null) => void
+
+const BackendRecordInjectionContextSetterContext = React.createContext<RecordInjectionContextSetter | null>(null)
+
+/**
+ * AppShell renders this provider around page `children`, supplying the setter
+ * that publishes record context into AppShell-owned state. Detail pages call
+ * `useSetCurrentRecordInjectionContext()` to publish/clear.
+ */
+export function BackendRecordInjectionContextProvider({
+  setCurrentRecordInjectionContext,
+  children,
+}: {
+  setCurrentRecordInjectionContext: RecordInjectionContextSetter
+  children: React.ReactNode
+}) {
+  return (
+    <BackendRecordInjectionContextSetterContext.Provider value={setCurrentRecordInjectionContext}>
+      {children}
+    </BackendRecordInjectionContextSetterContext.Provider>
+  )
+}
+
+/**
+ * Publish the current detail record's injection context to the AppShell-owned
+ * `backend:record:current` mount, and clear it automatically on unmount /
+ * dependency change. Pass `null` to clear (e.g. while the record is loading).
+ *
+ * ```tsx
+ * useSetCurrentRecordInjectionContext(
+ *   buildRecordInjectionContext({ resourceKind: 'customers.person', resourceId: id, updatedAt, data, path }),
+ * )
+ * ```
+ */
+export function useSetCurrentRecordInjectionContext(context: RecordInjectionContext | null): void {
+  const setter = React.useContext(BackendRecordInjectionContextSetterContext)
+  // Serialize so we only re-publish when the meaningful fields change.
+  const serialized = context
+    ? JSON.stringify({ k: context.resourceKind, i: context.resourceId, u: context.updatedAt ?? null, p: context.path ?? null })
+    : null
+  React.useEffect(() => {
+    if (!setter) return
+    setter(context)
+    return () => {
+      setter(null)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [setter, serialized])
+}

package/src/backend/utils/optimisticLock.ts

@@ -68,3 +68,39 @@ export function extractOptimisticLockConflict(
     expectedUpdatedAt,
   }
 }
+
+/**
+ * The enterprise `record_locks` 409 conflict code. Kept as a literal here so
+ * core/UI stays enterprise-free (no import from `@open-mercato/enterprise`).
+ */
+export const RECORD_LOCK_CONFLICT_CODE = 'record_lock_conflict' as const
+
+export type RecordLockConflictBody = {
+  code: typeof RECORD_LOCK_CONFLICT_CODE
+  error?: string
+  lock?: unknown
+  conflict?: unknown
+}
+
+/**
+ * Detect whether an error is an enterprise `record_locks` conflict (HTTP 409
+ * with `code: 'record_lock_conflict'`). Returns the conflict body when matched
+ * so `surfaceRecordConflict` can defer to the merge-dialog widget, or `null`.
+ */
+export function extractRecordLockConflict(err: unknown): RecordLockConflictBody | null {
+  if (!err || typeof err !== 'object') return null
+  const candidate = err as Record<string, unknown>
+  if (candidate.status !== 409) return null
+  const body = candidate.body && typeof candidate.body === 'object'
+    ? candidate.body
+    : candidate
+  if (!body || typeof body !== 'object') return null
+  const bodyRecord = body as Record<string, unknown>
+  if (bodyRecord.code !== RECORD_LOCK_CONFLICT_CODE) return null
+  return {
+    code: RECORD_LOCK_CONFLICT_CODE,
+    error: typeof bodyRecord.error === 'string' ? bodyRecord.error : undefined,
+    lock: bodyRecord.lock ?? null,
+    conflict: bodyRecord.conflict ?? null,
+  }
+}