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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.6.5-develop.4534.1.b459babe6d",
+  "version": "0.6.5-develop.4559.1.839e136509",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -237,6 +237,7 @@
     "html-to-text": "^10.0.0",
     "mammoth": "^1.9.0",
     "pdfjs-dist": "^6.0.227",
+    "resend": "^6.12.3",
     "sanitize-html": "^2.13.0",
     "semver": "^7.8.1",
     "svix": "^1.95.1",
@@ -244,16 +245,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.6.5-develop.4534.1.b459babe6d",
-    "@open-mercato/shared": "0.6.5-develop.4534.1.b459babe6d",
-    "@open-mercato/ui": "0.6.5-develop.4534.1.b459babe6d",
+    "@open-mercato/ai-assistant": "0.6.5-develop.4559.1.839e136509",
+    "@open-mercato/shared": "0.6.5-develop.4559.1.839e136509",
+    "@open-mercato/ui": "0.6.5-develop.4559.1.839e136509",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.6.5-develop.4534.1.b459babe6d",
-    "@open-mercato/shared": "0.6.5-develop.4534.1.b459babe6d",
-    "@open-mercato/ui": "0.6.5-develop.4534.1.b459babe6d",
+    "@open-mercato/ai-assistant": "0.6.5-develop.4559.1.839e136509",
+    "@open-mercato/shared": "0.6.5-develop.4559.1.839e136509",
+    "@open-mercato/ui": "0.6.5-develop.4559.1.839e136509",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/helpers/integration/communicationChannelsFixtures.ts

@@ -64,6 +64,11 @@ export async function seedConnectedChannel(
  *
  * Returns the created link + message ids (the message id is the platform
  * `messages.message` id, usable as `messageThreadId` to thread a follow-up).
+ *
+ * Pass `createThreadMapping: true` to also seed a `ChannelThreadMapping` for the
+ * thread — required before exercising the reaction (`/messages/[id]/reactions`)
+ * and thread-assign (`/threads/[id]/assign`) routes, which resolve the owning
+ * channel through that mapping.
  */
 export async function seedInboundMessage(
   request: APIRequestContext,
@@ -80,6 +85,7 @@ export async function seedInboundMessage(
     references?: string[];
     messageThreadId?: string;
     providerKey?: string;
+    createThreadMapping?: boolean;
   },
 ): Promise<{ channelLinkId: string; messageId: string; conversationId: string }> {
   const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {

package/src/helpers/integration/dbFixtures.ts

@@ -44,7 +44,7 @@ function resolveDatabaseUrl(): string {
   return url;
 }
 
-async function withClient<T>(run: (client: Client) => Promise<T>): Promise<T> {
+export async function withClient<T>(run: (client: Client) => Promise<T>): Promise<T> {
   const client = new Client({ connectionString: resolveDatabaseUrl() });
   await client.connect();
   try {

package/src/helpers/integration/optimisticLockUi.ts

@@ -0,0 +1,172 @@
+import { expect, type APIRequestContext, type Page } from '@playwright/test'
+import {
+  OPTIMISTIC_LOCK_HEADER_NAME,
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+/**
+ * Shared helpers for the browser-driven optimistic-lock specs
+ * (`TC-LOCK-OSS-014..046`). They make the conflict deterministic without two
+ * real tabs or sleeps: the spec loads an edit page in the browser (the form
+ * captures the record's `updated_at`), then advances `updated_at` out-of-band
+ * via a header-less API PUT (additive path, always succeeds), and finally edits
+ * + saves in the browser so the now-stale header triggers the 409 → conflict bar.
+ *
+ * See `packages/core/src/modules/sales/__integration__/__concurrent_edit_pattern.md`
+ * and the conflict bar component
+ * `packages/ui/src/backend/conflicts/RecordConflictBanner.tsx`
+ * (`data-testid="record-conflict-banner"`).
+ */
+
+const BASE_URL = process.env.BASE_URL?.trim() || ''
+
+export function resolveApiUrl(path: string): string {
+  return BASE_URL ? `${BASE_URL}${path}` : path
+}
+
+export const CONFLICT_BANNER_TESTID = 'record-conflict-banner'
+
+/**
+ * The enterprise `record_locks` module (enabled in CI via
+ * `OM_ENABLE_ENTERPRISE_MODULES=true`) supersedes the OSS banner with a richer
+ * "Conflict detected" resolution dialog. Both are valid surfaces for "the stale
+ * write was refused": on a CrudForm edit page either one can win depending on
+ * whether the record_locks incoming-changes SSE (fired by the out-of-band bump)
+ * is processed before the browser's stale save reaches the server. Asserting one
+ * fixed surface is therefore racy; we wait for whichever conflict surface appears.
+ * (List-delete / non-form flows have no record_locks lock and only ever surface
+ * the OSS banner, so matching either surface is safe there too.)
+ */
+export const CONFLICT_DIALOG_TESTID = 'record-lock-conflict-dialog'
+
+function authHeaders(token: string, lockValue?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  }
+  if (lockValue !== undefined) headers[OPTIMISTIC_LOCK_HEADER_NAME] = lockValue
+  return headers
+}
+
+/**
+ * Read a record's current `updated_at` from a list-shaped CRUD GET
+ * (`GET <basePath>?id=<id>` → `items[0].updated_at`), normalized to ISO.
+ * Works for the `makeCrudRoute` list responses (snake or camel case).
+ */
+export async function readUpdatedAt(
+  request: APIRequestContext,
+  token: string,
+  basePath: string,
+  id: string,
+  idParam = 'id',
+): Promise<string> {
+  const response = await request.fetch(
+    resolveApiUrl(`${basePath}?${idParam}=${encodeURIComponent(id)}`),
+    { method: 'GET', headers: authHeaders(token) },
+  )
+  expect(response.status(), `GET ${basePath}?${idParam}=... should be 200`).toBe(200)
+  const body = (await response.json()) as
+    | { items?: Array<Record<string, unknown>> }
+    | Record<string, unknown>
+  const item = Array.isArray((body as { items?: unknown[] }).items)
+    ? (body as { items: Array<Record<string, unknown>> }).items[0]
+    : (body as Record<string, unknown>)
+  expect(item, `response should include the record for id=${id}`).toBeTruthy()
+  const raw = (item?.updated_at ?? item?.updatedAt) as string | undefined
+  expect(typeof raw, `record should expose updated_at, got ${String(raw)}`).toBe('string')
+  const ms = Date.parse(raw as string)
+  expect(Number.isFinite(ms), `updated_at should parse, got ${String(raw)}`).toBe(true)
+  return new Date(ms).toISOString()
+}
+
+/**
+ * Advance a record's `updated_at` out-of-band so the browser's loaded form now
+ * holds a stale token. Uses a **header-less** PUT (the strictly-additive path
+ * always succeeds and bumps `updated_at`). Returns the new ISO `updated_at`.
+ */
+export async function bumpRecordViaApi(
+  request: APIRequestContext,
+  token: string,
+  basePath: string,
+  putBody: Record<string, unknown>,
+  opts: { idParam?: string; method?: 'PUT' | 'PATCH' } = {},
+): Promise<string | null> {
+  const response = await request.fetch(resolveApiUrl(basePath), {
+    method: opts.method ?? 'PUT',
+    headers: authHeaders(token),
+    data: putBody,
+  })
+  expect(
+    response.status(),
+    `out-of-band ${opts.method ?? 'PUT'} ${basePath} should succeed (additive path), got ${response.status()}`,
+  ).toBeLessThan(300)
+  const id = putBody[opts.idParam ?? 'id']
+  if (typeof id === 'string') {
+    try {
+      return await readUpdatedAt(request, token, basePath, id, opts.idParam)
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/** Direct API helpers to assert the 409 contract body (used by the negative/UX specs). */
+export async function putWithLock(
+  request: APIRequestContext,
+  token: string,
+  basePath: string,
+  body: Record<string, unknown>,
+  lockValue: string,
+) {
+  return request.fetch(resolveApiUrl(basePath), {
+    method: 'PUT',
+    headers: authHeaders(token, lockValue),
+    data: body,
+  })
+}
+
+export async function expectConflictBody(response: { status(): number; json(): Promise<unknown> }) {
+  expect(response.status(), 'stale write should be 409').toBe(409)
+  const body = (await response.json()) as { code?: string; currentUpdatedAt?: string; expectedUpdatedAt?: string }
+  expect(body.code, 'body.code should be the optimistic-lock conflict code').toBe(OPTIMISTIC_LOCK_CONFLICT_CODE)
+  return body
+}
+
+/**
+ * Assert a stale save was refused and surfaced as a conflict. Matches EITHER the
+ * OSS `record-conflict-banner` OR the enterprise record_locks "Conflict detected"
+ * dialog — see `CONFLICT_DIALOG_TESTID` for why both are valid and why pinning one
+ * is racy when enterprise modules are enabled.
+ */
+export async function expectConflictBanner(page: Page): Promise<void> {
+  const conflictSurface = page
+    .getByTestId(CONFLICT_BANNER_TESTID)
+    .or(page.getByTestId(CONFLICT_DIALOG_TESTID))
+  await expect(
+    conflictSurface.first(),
+    'a conflict surface (OSS bar or record_locks dialog) should appear after a stale save',
+  ).toBeVisible({ timeout: 10_000 })
+}
+
+/** Assert no conflict surface is present (a clean single-tab save must not 409). */
+export async function expectNoConflictBanner(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId(CONFLICT_BANNER_TESTID),
+    'a clean save must not surface a false-positive conflict bar',
+  ).toHaveCount(0)
+  await expect(
+    page.getByTestId(CONFLICT_DIALOG_TESTID),
+    'a clean save must not surface a false-positive conflict dialog',
+  ).toHaveCount(0)
+}
+
+/** Click the conflict bar's Refresh button. */
+export async function clickConflictRefresh(page: Page): Promise<void> {
+  await page.getByTestId(CONFLICT_BANNER_TESTID).getByRole('button', { name: /refresh/i }).click()
+}
+
+/** Dismiss the conflict bar via its close (X) button. */
+export async function dismissConflictBanner(page: Page): Promise<void> {
+  await page.getByTestId(CONFLICT_BANNER_TESTID).getByRole('button', { name: /dismiss/i }).click()
+}

package/src/helpers/integration/salesFixtures.ts

@@ -73,6 +73,35 @@ export async function createOrderLineFixture(
   );
 }
 
+/**
+ * Probe whether the authenticated principal can create a sales order on the
+ * current tenant (i.e. holds `sales.orders.manage`). Sales-write integration
+ * specs use this to self-skip on dev databases whose role ACLs were never
+ * synced (`yarn mercato auth sync-role-acls`) rather than fail spuriously —
+ * CI bootstraps a fully-synced tenant so the probe passes there. The probed
+ * order is deleted immediately so the check leaves no residue.
+ */
+export async function canManageSalesOrders(
+  request: APIRequestContext,
+  token: string,
+): Promise<boolean> {
+  const response = await apiRequest(request, 'POST', '/api/sales/orders', {
+    token,
+    data: { currencyCode: 'USD' },
+  });
+  if (response.status() === 403) return false;
+  if (!response.ok()) return false;
+  const id = readId((await response.json()) as unknown, ['id', 'orderId']);
+  if (id) {
+    try {
+      await apiRequest(request, 'DELETE', '/api/sales/orders', { token, data: { id } });
+    } catch {
+      // best-effort cleanup
+    }
+  }
+  return true;
+}
+
 export async function deleteSalesEntityIfExists(
   request: APIRequestContext,
   token: string | null,

package/src/modules/api_keys/backend/api-keys/page.tsx

@@ -6,7 +6,8 @@ import { DataTable } from '@open-mercato/ui/backend/DataTable'
 import type { ColumnDef } from '@tanstack/react-table'
 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 { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -25,6 +26,7 @@ type Row = {
   lastUsedAt: string | null
   expiresAt: string | null
   roles: RoleSummary[]
+  updatedAt?: string | null
 }
 
 type ResponsePayload = {
@@ -104,10 +106,13 @@ export default function ApiKeysListPage() {
     })
     if (!confirmed) return
     try {
-      const call = await apiCall<{ error?: string }>(
-        `/api/api_keys/keys?id=${encodeURIComponent(row.id)}`,
-        { method: 'DELETE' },
-        { fallback: null },
+      const call = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(row.updatedAt),
+        () => apiCall<{ error?: string }>(
+          `/api/api_keys/keys?id=${encodeURIComponent(row.id)}`,
+          { method: 'DELETE' },
+          { fallback: null },
+        ),
       )
       if (!call.ok) {
         const errorPayload = call.result as { error?: string } | undefined

package/src/modules/attachments/components/AttachmentPartitionSettings.tsx

@@ -22,7 +22,8 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@open-mercato/ui/primitives/dialog'
-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 { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -41,6 +42,7 @@ type Partition = {
   configJson: Record<string, unknown> | null
   envKey: string
   createdAt: string | null
+  updatedAt?: string | null
 }
 
 type DialogState =
@@ -230,11 +232,15 @@ export function AttachmentPartitionSettings({ s3Enabled }: AttachmentPartitionSe
         dialog.mode === 'edit'
           ? JSON.stringify({ id: dialog.entry.id, ...payload })
           : JSON.stringify(payload)
-      const call = await apiCall('/api/attachments/partitions', {
-        method,
-        headers: { 'content-type': 'application/json' },
-        body,
-      })
+      const lockHeader =
+        dialog.mode === 'edit' ? buildOptimisticLockHeader(dialog.entry.updatedAt) : {}
+      const call = await withScopedApiRequestHeaders(lockHeader, () =>
+        apiCall('/api/attachments/partitions', {
+          method,
+          headers: { 'content-type': 'application/json' },
+          body,
+        }),
+      )
       if (!call.ok) {
         await raiseCrudError(
           call.response,
@@ -271,9 +277,13 @@ export function AttachmentPartitionSettings({ s3Enabled }: AttachmentPartitionSe
       })
       if (!confirmed) return
       try {
-        const call = await apiCall(`/api/attachments/partitions?id=${encodeURIComponent(entry.id)}`, {
-          method: 'DELETE',
-        })
+        const call = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(entry.updatedAt),
+          () =>
+            apiCall(`/api/attachments/partitions?id=${encodeURIComponent(entry.id)}`, {
+              method: 'DELETE',
+            }),
+        )
         if (!call.ok) {
           await raiseCrudError(
             call.response,

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

@@ -5,11 +5,12 @@ 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 { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import { RoleAcl, Role } from '@open-mercato/core/modules/auth/data/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { resolveIsSuperAdmin } from '@open-mercato/core/modules/auth/lib/tenantAccess'
 import { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
-import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import {
   assertActorCanGrantAcl,
   assertActorCanModifySuperAdminRoleTarget,
@@ -39,6 +40,7 @@ const roleAclResponseSchema = z.object({
   isSuperAdmin: z.boolean(),
   features: z.array(z.string()),
   organizations: z.array(z.string()).nullable(),
+  updatedAt: z.string().nullable(),
 })
 
 const roleAclUpdateResponseSchema = z.object({
@@ -101,8 +103,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,
       }
-    : { isSuperAdmin: false, features: [], organizations: null }
+    : { isSuperAdmin: false, features: [], organizations: null, updatedAt: null }
 
   await logCrudAccess({
     container,
@@ -173,7 +176,24 @@ export async function PUT(req: Request) {
   }
 
   let acl = await em.findOne(RoleAcl, { role, tenantId: targetTenantId })
-  if (!acl) {
+  // Optimistic lock: refuse a stale ACL overwrite so two admins editing the same
+  // role's features in parallel cannot silently clobber each other (#2055). The
+  // check is strictly additive — when the client sends no expected-version header
+  // it is a no-op. Skipped when the ACL row does not exist yet (first grant has
+  // no prior version to conflict with).
+  if (acl) {
+    try {
+      enforceCommandOptimisticLock({
+        resourceKind: 'auth.role_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
+    }
+  } else {
     acl = em.create(RoleAcl, {
       role,
       tenantId: targetTenantId,
@@ -209,15 +229,21 @@ export async function PUT(req: Request) {
     throw err
   }
 
+  // Persist the ACL mutation inside a transaction so the role-permission write
+  // commits atomically (proper ACL-edit transaction handling).
   const aclToPersist = acl
-  await withAtomicFlush(em, [
-    () => {
-      aclToPersist.organizationsJson = requestedOrganizations
-      aclToPersist.isSuperAdmin = requestedIsSuperAdmin
-      aclToPersist.featuresJson = requestedFeatures
-      em.persist(aclToPersist)
-    },
-  ], { transaction: true })
+  await withAtomicFlush(
+    em,
+    [
+      () => {
+        aclToPersist.organizationsJson = requestedOrganizations
+        aclToPersist.isSuperAdmin = requestedIsSuperAdmin
+        aclToPersist.featuresJson = requestedFeatures
+        em.persist(aclToPersist)
+      },
+    ],
+    { transaction: true },
+  )
 
   // Invalidate cache for all users in this tenant since role ACL changed
   if (targetTenantId) {

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

@@ -43,6 +43,7 @@ const roleListItemSchema = z.object({
   tenantId: z.string().uuid().nullable(),
   tenantIds: z.array(z.string().uuid()).optional(),
   tenantName: z.string().nullable(),
+  updatedAt: z.string().nullable().optional(),
 })
 
 const roleListResponseSchema = z.object({
@@ -223,6 +224,7 @@ export async function GET(req: Request) {
       tenantId: tenantId ?? null,
       tenantIds: exposeTenant && tenantId ? [tenantId] : [],
       tenantName: exposeTenant ? tenantName : null,
+      updatedAt: r.updatedAt instanceof Date ? r.updatedAt.toISOString() : null,
       ...(cfByRole[idStr] || {}),
     }
   })

package/src/modules/auth/api/sidebar/preferences/route.ts

@@ -9,13 +9,17 @@ import {
   sidebarPreferencesScopeSchema,
 } from '../../../data/validators'
 import {
+  loadRoleSidebarPreferenceUpdatedAt,
   loadRoleSidebarPreferences,
   loadSidebarPreference,
+  loadSidebarPreferenceUpdatedAt,
   saveRoleSidebarPreference,
   saveSidebarPreference,
 } from '../../../services/sidebarPreferencesService'
 import { SIDEBAR_PREFERENCES_VERSION } from '@open-mercato/shared/modules/navigation/sidebarPreferences'
 import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { Role, RoleSidebarPreference } from '../../../data/entities'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { z } from 'zod'
@@ -47,6 +51,7 @@ const sidebarPreferencesResponseSchema = z.object({
   canApplyToRoles: z.boolean(),
   roles: z.array(sidebarRoleEntrySchema),
   scope: sidebarPreferencesScopeSchema,
+  updatedAt: z.string().datetime().nullable(),
 })
 
 const sidebarPreferencesUpdateResponseSchema = sidebarPreferencesResponseSchema.extend({
@@ -165,6 +170,11 @@ export async function GET(req: Request) {
     })
     const pref = rolePrefs.get(role.id) ?? null
     const rolesPayload = await loadRolesPayload(em, { tenantId: auth.tenantId ?? null, locale })
+    const roleVersion = await loadRoleSidebarPreferenceUpdatedAt(em, {
+      roleId: role.id,
+      tenantId: auth.tenantId ?? null,
+      locale,
+    })
     return NextResponse.json({
       locale,
       settings: pref
@@ -180,6 +190,7 @@ export async function GET(req: Request) {
       canApplyToRoles,
       roles: rolesPayload,
       scope: { type: 'role', roleId: role.id },
+      updatedAt: roleVersion?.updatedAt ? roleVersion.updatedAt.toISOString() : null,
     })
   }
 
@@ -198,6 +209,15 @@ export async function GET(req: Request) {
     ? await loadRolesPayload(em, { tenantId: auth.tenantId ?? null, locale })
     : []
 
+  const userVersion = effectiveUserId
+    ? await loadSidebarPreferenceUpdatedAt(em, {
+        userId: effectiveUserId,
+        tenantId: auth.tenantId ?? null,
+        organizationId: auth.orgId ?? null,
+        locale,
+      })
+    : null
+
   return NextResponse.json({
     locale,
     settings: {
@@ -211,6 +231,7 @@ export async function GET(req: Request) {
     canApplyToRoles,
     roles: rolesPayload,
     scope: { type: 'user' },
+    updatedAt: userVersion?.updatedAt ? userVersion.updatedAt.toISOString() : null,
   })
 }
 
@@ -318,11 +339,34 @@ export async function PUT(req: Request) {
     if (!role) {
       return NextResponse.json({ error: 'Role not found' }, { status: 404 })
     }
+    const existingRolePref = await loadRoleSidebarPreferenceUpdatedAt(em, {
+      roleId: role.id,
+      tenantId: auth.tenantId ?? null,
+      locale,
+    })
+    if (existingRolePref) {
+      try {
+        enforceCommandOptimisticLock({
+          resourceKind: 'auth.role_sidebar_preference',
+          resourceId: existingRolePref.id,
+          current: existingRolePref.updatedAt ?? null,
+          request: req,
+        })
+      } catch (err) {
+        if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+        throw err
+      }
+    }
     const saved = await saveRoleSidebarPreference(em, {
       roleId: role.id,
       tenantId: auth.tenantId ?? null,
       locale,
     }, payload)
+    const savedRoleVersion = await loadRoleSidebarPreferenceUpdatedAt(em, {
+      roleId: role.id,
+      tenantId: auth.tenantId ?? null,
+      locale,
+    })
     if (cache?.deleteByTags) {
       try {
         await cache.deleteByTags([`nav:sidebar:role:${role.id}`])
@@ -342,6 +386,7 @@ export async function PUT(req: Request) {
       canApplyToRoles,
       roles: rolesPayload,
       scope: { type: 'role', roleId: role.id },
+      updatedAt: savedRoleVersion?.updatedAt ? savedRoleVersion.updatedAt.toISOString() : null,
       appliedRoles: [],
       clearedRoles: [],
     })
@@ -356,6 +401,26 @@ export async function PUT(req: Request) {
     return NextResponse.json({ error: 'Forbidden', requiredFeatures: [FEATURE_MANAGE] }, { status: 403 })
   }
 
+  const existingUserPref = await loadSidebarPreferenceUpdatedAt(em, {
+    userId: effectiveUserId,
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    locale,
+  })
+  if (existingUserPref) {
+    try {
+      enforceCommandOptimisticLock({
+        resourceKind: 'auth.sidebar_preference',
+        resourceId: existingUserPref.id,
+        current: existingUserPref.updatedAt ?? null,
+        request: req,
+      })
+    } catch (err) {
+      if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+      throw err
+    }
+  }
+
   const settings = await saveSidebarPreference(em, {
     userId: effectiveUserId,
     tenantId: auth.tenantId ?? null,
@@ -444,12 +509,20 @@ export async function PUT(req: Request) {
     }))
   }
 
+  const savedUserVersion = await loadSidebarPreferenceUpdatedAt(em, {
+    userId: effectiveUserId,
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    locale,
+  })
+
   return NextResponse.json({
     locale,
     settings,
     canApplyToRoles,
     roles: rolesPayload,
     scope: { type: 'user' },
+    updatedAt: savedUserVersion?.updatedAt ? savedUserVersion.updatedAt.toISOString() : null,
     appliedRoles: updatedRoleIds,
     clearedRoles: filteredClearRoleIds,
   })