@open-mercato/core 0.6.5-develop.4534.1.b459babe6d → 0.6.5-develop.4544.1.71c003c861

package/src/modules/auth/api/users/acl/route.ts

@@ -5,8 +5,9 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { logCrudAccess } from '@open-mercato/shared/lib/crud/factory'
 import { forbidden, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
-import { UserAcl } from '@open-mercato/core/modules/auth/data/entities'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { UserAcl } from '@open-mercato/core/modules/auth/data/entities'
 import { assertActorCanModifySuperAdminUserTarget } from '@open-mercato/core/modules/auth/lib/grantChecks'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import type { EntityManager } from '@mikro-orm/postgresql'
@@ -29,6 +30,7 @@ const userAclResponseSchema = z.object({
   isSuperAdmin: z.boolean(),
   features: z.array(z.string()),
   organizations: z.array(z.string()).nullable(),
+  updatedAt: z.string().nullable(),
 })
 
 const userAclUpdateResponseSchema = z.object({
@@ -73,8 +75,9 @@ export async function GET(req: Request) {
         isSuperAdmin: !!acl.isSuperAdmin,
         features: Array.isArray(acl.featuresJson) ? acl.featuresJson : [],
         organizations: Array.isArray(acl.organizationsJson) ? acl.organizationsJson : null,
+        updatedAt: acl.updatedAt instanceof Date ? acl.updatedAt.toISOString() : null,
       }
-    : { hasCustomAcl: false, isSuperAdmin: false, features: [], organizations: null }
+    : { hasCustomAcl: false, isSuperAdmin: false, features: [], organizations: null, updatedAt: null }
 
   await logCrudAccess({
     container,
@@ -128,6 +131,22 @@ export async function PUT(req: Request) {
   const organizations = Array.isArray(parsed.data.organizations) ? parsed.data.organizations : null
 
   let acl = await em.findOne(UserAcl, { user: parsed.data.userId as any, tenantId: auth.tenantId as any })
+  // Optimistic lock: refuse a stale per-user ACL overwrite so concurrent edits
+  // cannot silently clobber each other (#2055). Strictly additive — a no-op when
+  // the client sends no expected-version header; skipped when no ACL row exists.
+  if (acl) {
+    try {
+      enforceCommandOptimisticLock({
+        resourceKind: 'auth.user_acl',
+        resourceId: acl.id,
+        current: acl.updatedAt ?? null,
+        request: req,
+      })
+    } catch (err) {
+      if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+      throw err
+    }
+  }
   const existingIsSuperAdmin = acl ? !!acl.isSuperAdmin : false
   const existingFeatures = acl && Array.isArray(acl.featuresJson) ? normalizeFeatureList(acl.featuresJson) : []
 
@@ -151,22 +170,31 @@ export async function PUT(req: Request) {
 
   const hasCustomAcl = effectiveIsSuperAdmin || effectiveFeatures.length > 0
 
-  await withAtomicFlush(em, [
-    () => {
-      if (!hasCustomAcl) {
-        if (acl) em.remove(acl)
-      } else {
-        if (!acl) {
-          acl = em.create(UserAcl, { user: parsed.data.userId as any, tenantId: auth.tenantId as any })
-        }
-        const aclRecord = acl as any
-        aclRecord.isSuperAdmin = effectiveIsSuperAdmin
-        aclRecord.featuresJson = effectiveFeatures
-        aclRecord.organizationsJson = organizations
-        em.persist(acl)
-      }
-    },
-  ], { transaction: true })
+  // Persist the ACL mutation inside a transaction so the per-user permission
+  // write (or removal) commits atomically (proper ACL-edit transaction handling).
+  if (!hasCustomAcl) {
+    if (acl) {
+      const aclToRemove = acl
+      await withAtomicFlush(em, [() => em.remove(aclToRemove)], { transaction: true })
+    }
+  } else {
+    if (!acl) {
+      acl = em.create(UserAcl, { user: parsed.data.userId as any, tenantId: auth.tenantId as any })
+    }
+    const aclRecord = acl as any
+    await withAtomicFlush(
+      em,
+      [
+        () => {
+          aclRecord.isSuperAdmin = effectiveIsSuperAdmin
+          aclRecord.featuresJson = effectiveFeatures
+          aclRecord.organizationsJson = organizations
+          em.persist(aclRecord)
+        },
+      ],
+      { transaction: true },
+    )
+  }
 
   // Invalidate cache for this user
   await rbacService.invalidateUserCache(parsed.data.userId)

package/src/modules/auth/api/users/route.ts

@@ -80,6 +80,7 @@ const userListItemSchema = z.object({
   tenantName: z.string().nullable(),
   roles: z.array(z.string()),
   roleIds: z.array(z.string().uuid()).optional(),
+  updatedAt: z.string().nullable().optional(),
 })
 
 const userListResponseSchema = z.object({
@@ -429,6 +430,7 @@ export async function GET(req: Request) {
       roles: roleMap[uid] || [],
       roleIds: roleIdMap[uid] || [],
       hasPassword: !!u.passwordHash,
+      updatedAt: u.updatedAt instanceof Date ? u.updatedAt.toISOString() : null,
       ...(cfByUser[uid] || {}),
     }
   })

package/src/modules/auth/backend/roles/[id]/edit/page.tsx

@@ -2,7 +2,8 @@
 import * as React from 'react'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { deleteCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { AclEditor, type AclData } from '@open-mercato/core/modules/auth/components/AclEditor'
@@ -16,6 +17,7 @@ import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-
 type EditRoleFormValues = {
   name?: string
   tenantId?: string | null
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 type RoleRecord = {
@@ -24,6 +26,7 @@ type RoleRecord = {
   tenantId: string | null
   tenantName?: string | null
   usersCount?: number | null
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 type RoleListResponse = {
@@ -37,6 +40,7 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
   const [initial, setInitial] = React.useState<RoleRecord | null>(null)
   const [loading, setLoading] = React.useState(true)
   const [aclData, setAclData] = React.useState<AclData>({ isSuperAdmin: false, features: [], organizations: null })
+  const [aclUpdatedAt, setAclUpdatedAt] = React.useState<string | null>(null)
   const [actorIsSuperAdmin, setActorIsSuperAdmin] = React.useState(false)
   const [selectedTenantId, setSelectedTenantId] = React.useState<string | null>(null)
   const widgetEditorRef = React.useRef<WidgetVisibilityEditorHandle | null>(null)
@@ -158,6 +162,7 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
               canEditOrganizations
               value={aclData}
               onChange={setAclData}
+              onVersionChange={setAclUpdatedAt}
               currentUserIsSuperAdmin={actorIsSuperAdmin}
               tenantId={selectedTenantId ?? null}
               preserveOnTenantChange
@@ -213,17 +218,37 @@ export default function EditRolePage({ params }: { params?: { id?: string } }) {
             if (Object.keys(customFields).length) {
               payload.customFields = customFields
             }
-            await updateCrud('auth/roles', payload)
-            await updateCrud('auth/roles/acl', { roleId: id, tenantId: effectiveTenantId, ...aclData }, {
+            const roleOptimisticLockHeader = buildOptimisticLockHeader(initial?.updatedAt)
+            if (Object.keys(roleOptimisticLockHeader).length > 0) {
+              await withScopedApiRequestHeaders(roleOptimisticLockHeader, () => updateCrud('auth/roles', payload))
+            } else {
+              await updateCrud('auth/roles', payload)
+            }
+            // Optimistic lock the ACL save against the loaded RoleAcl version so a
+            // concurrent permission edit cannot silently overwrite (#2055). CrudForm
+            // surfaces the 409 as the unified conflict bar.
+            const aclLockHeader = buildOptimisticLockHeader(aclUpdatedAt)
+            const saveRoleAcl = () => updateCrud('auth/roles/acl', { roleId: id, tenantId: effectiveTenantId, ...aclData }, {
               errorMessage: t('auth.roles.form.errors.aclUpdate', 'Failed to update role access control'),
             })
+            if (Object.keys(aclLockHeader).length > 0) {
+              await withScopedApiRequestHeaders(aclLockHeader, saveRoleAcl)
+            } else {
+              await saveRoleAcl()
+            }
             await widgetEditorRef.current?.save()
             try { window.dispatchEvent(new Event('om:refresh-sidebar')) } catch {}
           }}
           onDelete={async () => {
-            await deleteCrud('auth/roles', String(id), {
+            const roleOptimisticLockHeader = buildOptimisticLockHeader(initial?.updatedAt)
+            const deleteRole = () => deleteCrud('auth/roles', String(id), {
               errorMessage: t('auth.roles.form.errors.delete', 'Failed to delete role'),
             })
+            if (Object.keys(roleOptimisticLockHeader).length > 0) {
+              await withScopedApiRequestHeaders(roleOptimisticLockHeader, deleteRole)
+            } else {
+              await deleteRole()
+            }
           }}
           deleteRedirect={`/backend/roles?flash=${encodeURIComponent(t('auth.roles.flash.deleted', 'Role deleted'))}&type=success`}
         />

package/src/modules/auth/backend/roles/page.tsx

@@ -6,7 +6,8 @@ import { DataTable } from '@open-mercato/ui/backend/DataTable'
 import type { ColumnDef, SortingState } from '@tanstack/react-table'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -20,6 +21,7 @@ type Row = {
   tenantId?: string | null
   tenantIds?: string[]
   tenantName?: string | null
+  updatedAt?: string | null
 }
 
 export default function RolesListPage() {
@@ -77,9 +79,12 @@ export default function RolesListPage() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall(
-        `/api/auth/roles?id=${encodeURIComponent(row.id)}`,
-        { method: 'DELETE' },
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(row.updatedAt),
+        () => apiCall(
+          `/api/auth/roles?id=${encodeURIComponent(row.id)}`,
+          { method: 'DELETE' },
+        ),
       )
       if (!call.ok) {
         await raiseCrudError(call.response, t('auth.roles.list.error.delete', 'Failed to delete role'))

package/src/modules/auth/backend/users/[id]/edit/page.tsx

@@ -3,7 +3,8 @@ import * as React from 'react'
 import { E } from '#generated/entities.ids.generated'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm, type CrudField, type CrudFormGroup, type CrudFieldOption } from '@open-mercato/ui/backend/CrudForm'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { deleteCrud, updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
 import { AclEditor, type AclData } from '@open-mercato/core/modules/auth/components/AclEditor'
@@ -27,6 +28,7 @@ type EditUserFormValues = {
   tenantId: string | null
   organizationId: string | null
   roles: string[]
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 type LoadedUser = {
@@ -40,6 +42,7 @@ type LoadedUser = {
   roles: string[]
   roleIds: string[]
   hasPassword: boolean
+  updatedAt: string | null
 }
 
 type UserApiItem = {
@@ -53,6 +56,8 @@ type UserApiItem = {
   roles?: unknown
   roleIds?: unknown
   hasPassword?: boolean
+  updatedAt?: string | null
+  updated_at?: string | null
 }
 
 type UserListResponse = {
@@ -123,6 +128,7 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
   const [isNotFound, setIsNotFound] = React.useState(false)
   const [canEditOrgs, setCanEditOrgs] = React.useState(false)
   const [aclData, setAclData] = React.useState<AclData>({ isSuperAdmin: false, features: [], organizations: null })
+  const [aclUpdatedAt, setAclUpdatedAt] = React.useState<string | null>(null)
   const [customFieldValues, setCustomFieldValues] = React.useState<Record<string, unknown>>({})
   const [actorIsSuperAdmin, setActorIsSuperAdmin] = React.useState(false)
   const [actorResolved, setActorResolved] = React.useState(false)
@@ -209,6 +215,11 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
               roles: roleNames,
               roleIds: roleIds.length > 0 ? roleIds : roleNames,
               hasPassword: item.hasPassword !== false,
+              updatedAt: typeof item.updatedAt === 'string'
+                ? item.updatedAt
+                : typeof item.updated_at === 'string'
+                  ? item.updated_at
+                  : null,
             })
             setSelectedTenantId(item.tenantId ? String(item.tenantId) : null)
             const custom = extractCustomFieldEntries(item as Record<string, unknown>)
@@ -353,6 +364,7 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
             canEditOrganizations={canEditOrgs}
             value={aclData}
             onChange={setAclData}
+            onVersionChange={setAclUpdatedAt}
             userRoles={initialUser?.roles || []}
             currentUserIsSuperAdmin={actorIsSuperAdmin}
             tenantId={selectedTenantId ?? null}
@@ -393,6 +405,7 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
         tenantId: initialUser.tenantId,
         organizationId: initialUser.organizationId,
         roles: initialUser.roleIds,
+        updatedAt: initialUser.updatedAt,
         ...customFieldValues,
       }
     }
@@ -471,17 +484,37 @@ export default function EditUserPage({ params }: { params?: { id?: string } }) {
               roles: Array.isArray(values.roles) ? values.roles : [],
               ...(Object.keys(customFields).length ? { customFields } : {}),
             }
-            await updateCrud('auth/users', payload)
-            await updateCrud('auth/users/acl', { userId: id, ...aclData }, {
+            const userOptimisticLockHeader = buildOptimisticLockHeader(initialUser?.updatedAt)
+            if (Object.keys(userOptimisticLockHeader).length > 0) {
+              await withScopedApiRequestHeaders(userOptimisticLockHeader, () => updateCrud('auth/users', payload))
+            } else {
+              await updateCrud('auth/users', payload)
+            }
+            // Optimistic lock the ACL save against the loaded UserAcl version so a
+            // concurrent permission edit cannot silently overwrite (#2055). CrudForm
+            // surfaces the 409 as the unified conflict bar.
+            const aclLockHeader = buildOptimisticLockHeader(aclUpdatedAt)
+            const saveUserAcl = () => updateCrud('auth/users/acl', { userId: id, ...aclData }, {
               errorMessage: t('auth.users.form.errors.aclUpdate', 'Failed to update user access control'),
             })
+            if (Object.keys(aclLockHeader).length > 0) {
+              await withScopedApiRequestHeaders(aclLockHeader, saveUserAcl)
+            } else {
+              await saveUserAcl()
+            }
             await widgetEditorRef.current?.save()
             try { window.dispatchEvent(new Event('om:refresh-sidebar')) } catch {}
           }}
           onDelete={async () => {
-            await deleteCrud('auth/users', String(id), {
+            const userOptimisticLockHeader = buildOptimisticLockHeader(initialUser?.updatedAt)
+            const deleteUser = () => deleteCrud('auth/users', String(id), {
               errorMessage: t('auth.users.form.errors.delete', 'Failed to delete user'),
             })
+            if (Object.keys(userOptimisticLockHeader).length > 0) {
+              await withScopedApiRequestHeaders(userOptimisticLockHeader, deleteUser)
+            } else {
+              await deleteUser()
+            }
           }}
           deleteRedirect={`/backend/users?flash=${encodeURIComponent(t('auth.users.flash.deleted', 'User deleted'))}&type=success`}
         />

package/src/modules/auth/backend/users/page.tsx

@@ -8,7 +8,8 @@ import type { ColumnDef, SortingState } from '@tanstack/react-table'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
@@ -26,6 +27,7 @@ type Row = {
   tenantId: string | null
   tenantName?: string | null
   roles: string[]
+  updatedAt?: string | null
 }
 
 type FilterOption = { value: string; label: string }
@@ -388,7 +390,10 @@ export default function UsersListPage() {
     if (!confirmed) return
     const deleteErrorMessage = t('auth.users.list.error.delete', 'Failed to delete user')
     try {
-      const call = await apiCall(`/api/auth/users?id=${encodeURIComponent(row.id)}`, { method: 'DELETE' })
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(row.updatedAt),
+        () => apiCall(`/api/auth/users?id=${encodeURIComponent(row.id)}`, { method: 'DELETE' }),
+      )
       if (!call.ok) {
         await raiseCrudError(call.response, deleteErrorMessage)
       }

package/src/modules/auth/components/AclEditor.tsx

@@ -68,6 +68,7 @@ type AclPayload = {
   isSuperAdmin?: boolean
   features?: unknown
   organizations?: unknown
+  updatedAt?: string | null
 }
 type OrganizationListResponse = { items?: Array<{ id?: string; name?: string }> }
 
@@ -99,6 +100,7 @@ export function AclEditor({
   canEditOrganizations,
   value,
   onChange,
+  onVersionChange,
   userRoles,
   currentUserIsSuperAdmin,
   tenantId,
@@ -109,6 +111,12 @@ export function AclEditor({
   canEditOrganizations: boolean
   value?: AclData
   onChange?: (data: AclData) => void
+  /**
+   * Reports the loaded ACL row's `updatedAt` (or null when none exists) so the
+   * parent can send the optimistic-lock header on save and reject stale ACL
+   * overwrites (#2055).
+   */
+  onVersionChange?: (updatedAt: string | null) => void
   userRoles?: string[]
   currentUserIsSuperAdmin?: boolean
   tenantId?: string | null
@@ -168,8 +176,9 @@ export function AclEditor({
       setIsSuperAdmin(!!aclJson.isSuperAdmin)
       setGranted(actorSanitizeFeatures(aclJson.features))
       setOrganizations(aclJson.organizations == null ? null : Array.isArray(aclJson.organizations) ? aclJson.organizations : [])
+      onVersionChange?.(typeof aclJson.updatedAt === 'string' ? aclJson.updatedAt : null)
     } catch {}
-  }, [kind, targetId, actorSanitizeFeatures])
+  }, [kind, targetId, actorSanitizeFeatures, onVersionChange])
 
   React.useEffect(() => {
     const cancelled = { current: false }

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

@@ -33,7 +33,10 @@ export class User {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
-@Property({ name: 'deleted_at', type: Date, nullable: true })
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date(), nullable: true })
+  updatedAt?: Date | null
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
   deletedAt?: Date | null
 }
 
@@ -52,6 +55,9 @@ export class Role {
   @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
   createdAt: Date = new Date()
 
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date(), nullable: true })
+  updatedAt?: Date | null
+
   @Property({ name: 'deleted_at', type: Date, nullable: true })
   deletedAt?: Date | null
 }

package/src/modules/auth/services/sidebarPreferencesService.ts

@@ -54,6 +54,38 @@ export async function loadSidebarPreference(
   return normalizeSidebarSettings(existing?.settingsJson as SidebarPreferencesSettings | undefined)
 }
 
+export async function loadSidebarPreferenceUpdatedAt(
+  em: EntityManager,
+  scope: SidebarPreferenceScope,
+): Promise<{ id: string; updatedAt: Date | null } | null> {
+  const { userId, tenantId, organizationId } = normalizeScope(scope)
+  const existing = await findOneWithDecryption(
+    em,
+    UserSidebarPreference,
+    { user: userId, tenantId, organizationId },
+    undefined,
+    { tenantId, organizationId },
+  )
+  if (!existing) return null
+  return { id: existing.id, updatedAt: existing.updatedAt ?? null }
+}
+
+export async function loadRoleSidebarPreferenceUpdatedAt(
+  em: EntityManager,
+  scope: RoleSidebarPreferenceScope,
+): Promise<{ id: string; updatedAt: Date | null } | null> {
+  const { roleId, tenantId } = normalizeRoleScope(scope)
+  const existing = await findOneWithDecryption(
+    em,
+    RoleSidebarPreference,
+    { role: roleId, tenantId },
+    undefined,
+    { tenantId, organizationId: null },
+  )
+  if (!existing) return null
+  return { id: existing.id, updatedAt: existing.updatedAt ?? null }
+}
+
 export async function saveSidebarPreference(
   em: EntityManager,
   scope: SidebarPreferenceScope,
@@ -389,7 +421,7 @@ export async function updateSidebarVariant(
   if (!variant) return null
   const target = variant
   await withAtomicFlush(em, [
-    async () => {
+    () => {
       if (typeof input.name === 'string' && input.name.trim().length > 0) {
         target.name = input.name.trim()
       }
@@ -400,12 +432,14 @@ export async function updateSidebarVariant(
         })
       }
       if (typeof input.isActive === 'boolean') {
-        if (input.isActive) {
-          await deactivateAllVariants(em, scope, variantId)
-        }
         target.isActive = input.isActive
       }
     },
+    async () => {
+      if (input.isActive === true) {
+        await deactivateAllVariants(em, scope, variantId)
+      }
+    },
   ], { transaction: true })
   return toVariantRecord(target)
 }

package/src/modules/business_rules/api/rules/route.ts

@@ -4,6 +4,8 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { BusinessRule } from '../../data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
@@ -277,6 +279,20 @@ export async function PUT(req: Request) {
     return NextResponse.json({ error: 'Rule not found' }, { status: 404 })
   }
 
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'business_rules.rule',
+      resourceId: rule.id,
+      current: rule.updatedAt ?? null,
+      request: req,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    throw err
+  }
+
   em.assign(rule, parsed.data)
 
   try {
@@ -321,6 +337,20 @@ export async function DELETE(req: Request) {
     return NextResponse.json({ error: 'Rule not found' }, { status: 404 })
   }
 
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'business_rules.rule',
+      resourceId: rule.id,
+      current: rule.updatedAt ?? null,
+      request: req,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    throw err
+  }
+
   rule.deletedAt = new Date()
   await em.persist(rule).flush()
   await invalidateBusinessRuleDiscoveryCache(cache, rule.tenantId, rule.organizationId)

package/src/modules/business_rules/api/sets/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { RuleSet } from '../../data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
@@ -221,6 +223,20 @@ export async function PUT(req: Request) {
     return NextResponse.json({ error: 'Rule set not found' }, { status: 404 })
   }
 
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'business_rules.ruleSet',
+      resourceId: ruleSet.id,
+      current: ruleSet.updatedAt ?? null,
+      request: req,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    throw err
+  }
+
   em.assign(ruleSet, parsed.data)
   await em.persist(ruleSet).flush()
 
@@ -254,6 +270,20 @@ export async function DELETE(req: Request) {
     return NextResponse.json({ error: 'Rule set not found' }, { status: 404 })
   }
 
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'business_rules.ruleSet',
+      resourceId: ruleSet.id,
+      current: ruleSet.updatedAt ?? null,
+      request: req,
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    throw err
+  }
+
   ruleSet.deletedAt = new Date()
   await em.persist(ruleSet).flush()
 

package/src/modules/business_rules/backend/rules/[id]/page.tsx

@@ -8,7 +8,10 @@ import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { apiFetch } from '@open-mercato/ui/backend/utils/api'
+import { apiFetch, withScopedApiHeaders } from '@open-mercato/ui/backend/utils/api'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { readJsonSafe } from '@open-mercato/ui/backend/utils/serverErrors'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useOrganizationScopeDetail } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import {
@@ -67,7 +70,7 @@ export default function EditBusinessRulePage() {
 
     const payload = buildRulePayload(values, effectiveTenantId, effectiveOrgId, undefined)
 
-    const response = await apiFetch('/api/business_rules/rules', {
+    const updateRule = () => apiFetch('/api/business_rules/rules', {
       method: 'PUT',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
@@ -75,10 +78,18 @@ export default function EditBusinessRulePage() {
         id: ruleId,
       }),
     })
+    const headers = buildOptimisticLockHeader(rule?.updatedAt ?? rule?.updated_at ?? null)
+    const response = Object.keys(headers).length
+      ? await withScopedApiHeaders(headers, updateRule)
+      : await updateRule()
 
     if (!response.ok) {
-      const error = await response.json()
-      throw new Error(error.error || error.message || t('business_rules.errors.updateFailed'))
+      const body = (await readJsonSafe<Record<string, unknown>>(response)) ?? {}
+      const message =
+        (typeof body.error === 'string' && body.error) ||
+        (typeof body.message === 'string' && body.message) ||
+        t('business_rules.errors.updateFailed')
+      throw new CrudHttpError(response.status, { ...body, error: message })
     }
 
     router.push('/backend/rules')
@@ -134,6 +145,7 @@ export default function EditBusinessRulePage() {
           schema={businessRuleFormSchema}
           fields={fields}
           initialValues={initialValues}
+          optimisticLockUpdatedAt={rule?.updatedAt ?? rule?.updated_at ?? null}
           onSubmit={handleSubmit}
           cancelHref="/backend/rules"
           groups={formGroups}