@open-mercato/core 0.6.6-develop.6330.1.a261878aa8 → 0.6.6-develop.6331.1.a33b8e99b7

package/src/modules/dictionaries/api/[dictionaryId]/route.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 import { Dictionary } from '@open-mercato/core/modules/dictionaries/data/entities'
 import { resolveDictionariesRouteContext, resolveDictionaryActorId } from '@open-mercato/core/modules/dictionaries/api/context'
 import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import {
   runCrudMutationGuardAfterSuccess,
   validateCrudMutationGuard,
@@ -115,7 +115,7 @@ export async function PATCH(req: Request, ctx: { params?: { dictionaryId?: strin
     const payload = updateSchema.parse(await req.json().catch(() => ({})))
     const dictionary = await loadDictionary(context, dictionaryId)
 
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(context.container, {
       resourceKind: 'dictionaries.dictionary',
       resourceId: dictionary.id,
       current: dictionary.updatedAt ?? null,
@@ -236,7 +236,7 @@ export async function DELETE(req: Request, ctx: { params?: { dictionaryId?: stri
     const { dictionaryId } = paramsSchema.parse({ dictionaryId: ctx.params?.dictionaryId })
     const dictionary = await loadDictionary(context, dictionaryId)
 
-    enforceCommandOptimisticLock({
+    await enforceCommandOptimisticLockWithGuards(context.container, {
       resourceKind: 'dictionaries.dictionary',
       resourceId: dictionary.id,
       current: dictionary.updatedAt ?? null,

package/src/modules/dictionaries/components/DictionariesManager.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from 'react'
-import { useSearchParams } from 'next/navigation'
+import { useSearchParams, usePathname } from 'next/navigation'
 import { Book, Plus, Pencil, Trash2 } from 'lucide-react'
 import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -18,6 +18,7 @@ import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { apiCall, 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 { 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 { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
@@ -58,6 +59,7 @@ export function DictionariesManager() {
   const t = useT()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
   const searchParams = useSearchParams()
+  const pathname = usePathname()
   const [items, setItems] = React.useState<DictionarySummary[]>([])
   const [selectedId, setSelectedId] = React.useState<string | null>(null)
   const [loading, setLoading] = React.useState(true)
@@ -366,6 +368,24 @@ export function DictionariesManager() {
 
   const selectedDictionary = items.find((item) => item.id === selectedId) ?? null
 
+  // Publish the open dictionary's record context to the AppShell-owned
+  // `backend:record:current` mount so the enterprise record_locks widget resolves
+  // `dictionaries.dictionary` + id while the manager is open. Editing here is
+  // inline/dialog-driven (not a `[id]` detail route or a CrudForm with a stable
+  // `injectionSpotId`), so mounting presence on the manager keyed to the selected
+  // dictionary is the simplest place to hold the lock — it mirrors the
+  // `dictionaries.dictionary` resourceKind the dictionary PATCH route guards on.
+  // Cleared automatically when no dictionary is selected or on unmount.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'dictionaries.dictionary',
+      resourceId: selectedDictionary?.id ?? null,
+      updatedAt: selectedDictionary?.updatedAt ?? null,
+      data: (selectedDictionary ?? null) as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   return (
     <div className="grid gap-6 lg:grid-cols-[320px_1fr]">
       <div className="rounded-lg border bg-card p-4 shadow-sm">

package/src/modules/dictionaries/components/DictionaryEntriesEditor.tsx

@@ -276,6 +276,8 @@ export function DictionaryEntriesEditor({ dictionaryId, dictionaryName, readOnly
         await invalidateDictionaryEntries(queryClient, dictionaryId)
         flash(t('dictionaries.config.entries.success.delete', 'Dictionary entry deleted.'), 'success')
       } catch (err) {
+        // Route a concurrent-edit 409 through the single conflict surface (matching
+        // the entry save path); fall back to a flash for any other delete failure.
         if (surfaceRecordConflict(err, t)) {
           return
         }

package/src/modules/directory/backend/directory/organizations/[id]/edit/page.tsx

@@ -1,5 +1,6 @@
 "use client"
 import * as React from 'react'
+import { usePathname } from 'next/navigation'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-fields-client'
 import { E } from '#generated/entities.ids.generated'
@@ -17,6 +18,7 @@ import { deleteCrud, 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 { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 
 type TreeResponse = {
   items: OrganizationTreeNode[]
@@ -46,6 +48,7 @@ const TREE_PADDING = 12
 export default function EditOrganizationPage({ params }: { params?: { id?: string } }) {
   const orgId = params?.id
   const t = useT()
+  const pathname = usePathname()
   const [initialValues, setInitialValues] = React.useState<Record<string, unknown> | null>(null)
   const [pathLabel, setPathLabel] = React.useState<string>('')
   const [tenantId, setTenantId] = React.useState<string | null>(null)
@@ -270,6 +273,20 @@ export default function EditOrganizationPage({ params }: { params?: { id?: strin
     { id: 'custom', title: t('directory.organizations.form.group.customFields', 'Custom Data'), column: 2, kind: 'customFields' },
   ]), [detailFields, t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `directory.organization` + id
+  // explicitly. The resourceKind mirrors the CrudForm `versionHistory` so the held
+  // lock matches the save-time conflict surface for the same organization.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'directory.organization',
+      resourceId: orgId || null,
+      updatedAt: typeof initialValues?.updatedAt === 'string' ? initialValues.updatedAt : null,
+      data: initialValues,
+      path: pathname,
+    }),
+  )
+
   if (!orgId) {
     return (
       <Page>

package/src/modules/directory/backend/directory/tenants/[id]/edit/page.tsx

@@ -1,5 +1,6 @@
 "use client"
 import * as React from 'react'
+import { usePathname } from 'next/navigation'
 import { E } from '#generated/entities.ids.generated'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
@@ -9,6 +10,7 @@ import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-fields-client'
 
@@ -21,6 +23,7 @@ type TenantFormValues = {
 
 export default function EditTenantPage({ params }: { params?: { id?: string } }) {
   const tenantId = params?.id
+  const pathname = usePathname()
   const [initial, setInitial] = React.useState<TenantFormValues | null>(null)
   const [loading, setLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
@@ -84,6 +87,20 @@ export default function EditTenantPage({ params }: { params?: { id?: string } })
     return () => { cancelled = true }
   }, [tenantId, t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `directory.tenant` + id
+  // explicitly. The resourceKind mirrors the CrudForm `versionHistory` so the held
+  // lock matches the save-time conflict surface for the same tenant.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'directory.tenant',
+      resourceId: tenantId || null,
+      updatedAt: initial?.updatedAt ?? null,
+      data: initial as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (!tenantId) return null
 
   if (isNotFound) {

package/src/modules/entities/api/entities.ts

@@ -8,7 +8,7 @@ import { upsertCustomEntitySchema } from '@open-mercato/core/modules/entities/da
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { isSystemEntitySelectable } from '@open-mercato/shared/lib/entities/system-entities'
 import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
-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'
 import {
   beginEntitiesMutationGuard,
@@ -132,7 +132,7 @@ export async function POST(req: Request) {
   let ent = await em.findOne(CustomEntity, where)
   if (ent) {
     try {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(container, {
         resourceKind: CUSTOM_ENTITY_DEFINITION_RESOURCE_KIND,
         resourceId: ent.id,
         current: ent.updatedAt ?? null,

package/src/modules/entities/api/records.ts

@@ -11,7 +11,7 @@ import { parseBooleanToken, parseBooleanWithDefault } from '@open-mercato/shared
 import { setRecordCustomFields } from '../lib/helpers'
 import { CustomFieldValue } from '../data/entities'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
-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'
 import { getModules } from '@open-mercato/shared/lib/i18n/server'
 import { assertEntityAclForRequest } from '../lib/entityAcl'
@@ -460,7 +460,8 @@ export async function PUT(req: Request) {
   const { entityId, recordId, values } = parsed.data
 
   try {
-    const { resolve } = await createRequestContainer()
+    const container = await createRequestContainer()
+    const { resolve } = container
     const de = resolve('dataEngine') as any
     const em = resolve('em') as any
     const rbac = resolve('rbacService') as RbacService
@@ -510,7 +511,7 @@ export async function PUT(req: Request) {
         entityId: rid,
         organizationId: targetOrgId,
       })
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(container, {
         resourceKind: CUSTOM_ENTITY_RECORD_RESOURCE_KIND,
         resourceId: rid,
         current: currentUpdatedAt,
@@ -558,7 +559,8 @@ export async function DELETE(req: Request) {
   const { entityId, recordId } = parsed.data
 
   try {
-    const { resolve } = await createRequestContainer()
+    const container = await createRequestContainer()
+    const { resolve } = container
     const de = resolve('dataEngine') as any
     const em = resolve('em') as any
     const rbac = resolve('rbacService') as RbacService
@@ -576,7 +578,7 @@ export async function DELETE(req: Request) {
         entityId: recordId,
         organizationId: targetOrgId,
       })
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(container, {
         resourceKind: CUSTOM_ENTITY_RECORD_RESOURCE_KIND,
         resourceId: recordId,
         current: currentUpdatedAt,

package/src/modules/feature_toggles/api/overrides/route.ts

@@ -5,7 +5,7 @@ import type { CommandBus } from '@open-mercato/shared/lib/commands'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
 import { getOverrides } from '../../lib/queries'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
-import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import {
   runCrudMutationGuardAfterSuccess,
   validateCrudMutationGuard,
@@ -100,7 +100,7 @@ export async function PUT(req: Request) {
       toggle: { id: parsed.data.toggleId },
     })
     if (existingOverride) {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(ctx.container, {
         resourceKind: 'feature_toggles.feature_toggle_override',
         resourceId: existingOverride.id,
         current: existingOverride.updatedAt ?? null,

package/src/modules/feature_toggles/backend/feature-toggles/global/[id]/edit/page.tsx

@@ -57,6 +57,18 @@ export default function EditFeatureTogglePage({ params }: { params?: { id?: stri
     )
   }
 
+  // record_locks scope decision (Phase 6): the global feature toggle is a
+  // NON-TENANT, superadmin-only entity. record_locks enrichment (presence,
+  // acquire/heartbeat, conflict upgrade) is tenant-scoped — its decorator skips
+  // enrichment when no tenant/resource resolves — so a global (null-tenant) record
+  // cannot participate in record_locks. This surface therefore stays OSS-floor
+  // guarded ONLY: the CrudForm auto-derives the optimistic-lock header from
+  // `optimisticLockUpdatedAt`, the route enforces it via the OSS floor, and a stale
+  // save surfaces the unified conflict bar. No `backend:record:current` presence is
+  // mounted: it would never resolve a tenant-scoped lock, and this is a
+  // single-superadmin surface with no concurrent-editor expectation. Per-tenant
+  // override values (`api/global/[id]/override`) ARE tenant-scoped and are enabled
+  // in Phase 6b.
   return (
     <Page>
       <PageBody>

package/src/modules/feature_toggles/data/entities.ts

@@ -67,7 +67,7 @@ export class FeatureToggleOverride {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
   updatedAt: Date = new Date()
 
   @Property({ name: 'value', type: 'jsonb' })

package/src/modules/feature_toggles/data/validators.ts

@@ -104,6 +104,7 @@ export const overrideListResponseSchema = z.object({
   name: z.string(),
   category: z.string(),
   isOverride: z.boolean(),
+  updatedAt: z.string().nullable().optional(),
 });
 
 export type OverrideListResponse = z.infer<typeof overrideListResponseSchema>

package/src/modules/feature_toggles/lib/queries.ts

@@ -100,6 +100,7 @@ export async function getOverrides(
             name: toggle.name,
             category: toggle.category ?? '',
             isOverride: Boolean(override),
+            updatedAt: override?.updatedAt instanceof Date ? override.updatedAt.toISOString() : null,
         }
     })
 

package/src/modules/inbox_ops/api/settings/route.ts

@@ -2,7 +2,7 @@ import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { runWithCacheTenant } from '@open-mercato/cache'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
-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'
 import { InboxSettings } from '../../data/entities'
 import { updateSettingsSchema } from '../../data/validators'
@@ -104,7 +104,7 @@ export async function PATCH(req: Request) {
     // Optimistic lock: refuse a stale overwrite when two tabs edit the same inbox
     // settings record. Strictly additive — a no-op without the expected-version header.
     try {
-      enforceCommandOptimisticLock({
+      await enforceCommandOptimisticLockWithGuards(ctx.container, {
         resourceKind: 'inbox_ops.settings',
         resourceId: settings.id,
         current: settings.updatedAt ?? null,

package/src/modules/resources/backend/resources/resource-types/[id]/edit/page.tsx

@@ -1,9 +1,10 @@
 "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 { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
@@ -19,6 +20,7 @@ export default function ResourcesResourceTypeEditPage({ params }: { params?: { i
   const resourceTypeId = params?.id ?? ''
   const t = useT()
   const router = useRouter()
+  const pathname = usePathname()
   const [initialValues, setInitialValues] = React.useState<ResourceTypeFormValues | null>(null)
   const [loading, setLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
@@ -108,6 +110,20 @@ export default function ResourcesResourceTypeEditPage({ params }: { params?: { i
     router.push('/backend/resources/resource-types')
   }, [resourceCount, resourceTypeId, router, t])
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `resources.resourceType` + id
+  // explicitly. The resourceKind mirrors the ResourceTypeCrudForm `versionHistory` so the
+  // held lock matches the save-time conflict surface for the same resource type.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'resources.resourceType',
+      resourceId: resourceTypeId || null,
+      updatedAt: initialValues?.updatedAt ?? null,
+      data: initialValues as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
+
   if (isNotFound) {
     return (
       <Page>

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

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from 'react'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { FormHeader } from '@open-mercato/ui/backend/forms'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -12,6 +12,7 @@ import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { ActivitiesSection, NotesSection, RecordNotFoundState, type SectionAction, type TagOption } from '@open-mercato/ui/backend/detail'
+import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { VersionHistoryAction } from '@open-mercato/ui/backend/version-history'
 import { SendObjectMessageDialog } from '@open-mercato/ui/backend/messages'
@@ -91,6 +92,7 @@ export default function ResourcesResourceDetailPage({ 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<Record<string, unknown> | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -602,6 +604,20 @@ export default function ResourcesResourceDetailPage({ params }: { params?: { id?
       ? initialValues.name.trim()
       : t('resources.resources.detail.untitled', 'Unnamed resource')
 
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so the enterprise record_locks widget resolves `resources.resource` + id
+  // explicitly. The resourceKind mirrors the VersionHistoryAction config / ResourceCrudForm
+  // `versionHistory` so the held lock matches the save-time conflict surface for the resource.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: 'resources.resource',
+      resourceId: resourceId || null,
+      updatedAt: typeof initialValues?.updatedAt === 'string' ? initialValues.updatedAt : null,
+      data: initialValues,
+      path: pathname,
+    }),
+  )
+
   if (isNotFound) {
     return (
       <Page>

package/src/modules/resources/components/detail/notesAdapter.ts

@@ -1,6 +1,7 @@
 "use client"
 
-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 { mapCommentSummary, type NotesDataAdapter } from '@open-mercato/ui/backend/detail/NotesSection'
 
 type Translator = (key: string, fallback?: string, params?: Record<string, string | number>) => string
@@ -61,33 +62,43 @@ export function createResourceNotesAdapter(
       )
       return response.result ?? {}
     },
-    update: async ({ id, patch }) => {
+    update: async ({ id, patch, updatedAt }) => {
       const payload: Record<string, unknown> = { id }
       if (patch.body !== undefined) payload.body = patch.body
       if (patch.appearanceIcon !== undefined) payload.appearanceIcon = patch.appearanceIcon
       if (patch.appearanceColor !== undefined) payload.appearanceColor = patch.appearanceColor
+      // Run through the guarded-mutation runner AND send the optimistic-lock header
+      // (note's loaded updatedAt) so a stale edit fails with a 409; the shared
+      // NotesSection host surfaces it through surfaceRecordConflict instead of
+      // silently overwriting.
       await runWrite(
-        () => apiCallOrThrow(
-          '/api/resources/comments',
-          {
-            method: 'PUT',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(payload),
-          },
-          { errorMessage: translator('resources.resources.detail.notes.updateError', 'Failed to update note.') },
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(updatedAt ?? null),
+          () => apiCallOrThrow(
+            '/api/resources/comments',
+            {
+              method: 'PUT',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(payload),
+            },
+            { errorMessage: translator('resources.resources.detail.notes.updateError', 'Failed to update note.') },
+          ),
         ),
         { operation: 'updateNote', id },
       )
     },
-    delete: async ({ id }) => {
+    delete: async ({ id, updatedAt }) => {
       await runWrite(
-        () => apiCallOrThrow(
-          `/api/resources/comments?id=${encodeURIComponent(id)}`,
-          {
-            method: 'DELETE',
-            headers: { 'content-type': 'application/json' },
-          },
-          { errorMessage: translator('resources.resources.detail.notes.deleteError', 'Failed to delete note') },
+        () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(updatedAt ?? null),
+          () => apiCallOrThrow(
+            `/api/resources/comments?id=${encodeURIComponent(id)}`,
+            {
+              method: 'DELETE',
+              headers: { 'content-type': 'application/json' },
+            },
+            { errorMessage: translator('resources.resources.detail.notes.deleteError', 'Failed to delete note') },
+          ),
         ),
         { operation: 'deleteNote', id },
       )

package/src/modules/sales/backend/sales/documents/[id]/page.tsx

@@ -3,7 +3,7 @@
 "use client"
 
 import * as React from 'react'
-import { useSearchParams, useRouter } from 'next/navigation'
+import { useSearchParams, useRouter, usePathname } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import {
   CustomDataSection,
@@ -68,6 +68,7 @@ import { ICON_SUGGESTIONS } from '@open-mercato/core/modules/customers/lib/dicti
 import { readMarkdownPreferenceCookie, writeMarkdownPreferenceCookie } from '@open-mercato/core/modules/customers/lib/markdownPreference'
 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'
 
 function formatMessageAmount(amount: number | null | undefined, currency: string | null | undefined): string | null {
   if (typeof amount !== 'number' || !Number.isFinite(amount)) return null
@@ -1892,6 +1893,7 @@ export default function SalesDocumentDetailPage({
   const t = useT()
   const router = useRouter()
   const searchParams = useSearchParams()
+  const pathname = usePathname()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
   const [loading, setLoading] = React.useState(true)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -1972,6 +1974,18 @@ export default function SalesDocumentDetailPage({
     },
     [detailInjectionContext, runMutation],
   )
+  // Publish page-load record context to the AppShell-owned `backend:record:current`
+  // mount so record_locks gets presence + the action-log base (updatedAt/data) for
+  // this order/quote. Sub-resource sections inherit this context — no second mount.
+  useSetCurrentRecordInjectionContext(
+    buildRecordInjectionContext({
+      resourceKind: `sales.${kind}`,
+      resourceId: record?.id ?? null,
+      updatedAt: record?.updatedAt ?? null,
+      data: record as Record<string, unknown> | null,
+      path: pathname,
+    }),
+  )
   const clearCustomerError = React.useCallback(() => setCustomerError(null), [])
   const { data: currencyDictionary } = useCurrencyDictionary()
   const scopeVersion = useOrganizationScopeVersion()
@@ -4244,6 +4258,7 @@ export default function SalesDocumentDetailPage({
             currencyCode={record.currencyCode ?? null}
             organizationId={(record as any)?.organizationId ?? (record as any)?.organization_id ?? null}
             tenantId={(record as any)?.tenantId ?? (record as any)?.tenant_id ?? null}
+            documentUpdatedAt={record.updatedAt ?? null}
             shippingAddressSnapshot={shippingSnapshot ?? null}
             onActionChange={handleSectionActionChange}
             onAddComment={appendShipmentComment}
@@ -4300,6 +4315,7 @@ export default function SalesDocumentDetailPage({
           currencyCode={record.currencyCode ?? null}
           organizationId={(record as any)?.organizationId ?? (record as any)?.organization_id ?? null}
           tenantId={(record as any)?.tenantId ?? (record as any)?.tenant_id ?? null}
+          documentUpdatedAt={record.updatedAt ?? null}
           onActionChange={handleSectionActionChange}
           onPaymentsChange={(payments) => setHasPayments(payments.length > 0)}
           onTotalsChange={() => {

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" } }),