@open-mercato/core 0.6.6-develop.6229.1.ebe6706732 → 0.6.6-develop.6241.1.47c01ad4ed

package/src/modules/customers/api/tags/unassign/route.ts

@@ -9,8 +9,14 @@ import { tagAssignmentSchema, type TagAssignmentInput } from '../../../data/vali
 import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { withScopedPayload } from '../../utils'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 
+const TAG_ASSIGNMENT_RESOURCE_KIND = 'customers.tagAssignment'
+
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['customers.activities.manage'] },
 }
@@ -37,15 +43,48 @@ async function buildContext(
 export async function POST(req: Request) {
   try {
     const { ctx, auth, translate } = await buildContext(req)
+    const tenantId = auth!.tenantId
+    const organizationId = ctx.selectedOrganizationId
+    if (!tenantId || !organizationId) {
+      return NextResponse.json({ error: translate('customers.errors.context_required', 'Organization and tenant context required') }, { status: 400 })
+    }
     const body = await req.json().catch(() => ({}))
     const scoped = withScopedPayload(body, ctx, translate)
     const input = tagAssignmentSchema.parse(scoped)
 
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId,
+      organizationId,
+      userId: auth!.sub,
+      resourceKind: TAG_ASSIGNMENT_RESOURCE_KIND,
+      resourceId: input.entityId,
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: input,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     const commandBus = (ctx.container.resolve('commandBus') as CommandBus)
     const { result, logEntry } = await commandBus.execute<TagAssignmentInput, { assignmentId: string | null }>(
     'customers.tags.unassign',
     { input, ctx },
   )
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId,
+        organizationId,
+        userId: auth!.sub,
+        resourceKind: TAG_ASSIGNMENT_RESOURCE_KIND,
+        resourceId: input.entityId,
+        operation: 'custom',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
     const response = NextResponse.json({ id: result?.assignmentId ?? null })
     if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
       response.headers.set(

package/src/modules/customers/i18n/de.json

@@ -1505,6 +1505,7 @@
   "customers.errors.company_not_found": "Unternehmen nicht gefunden",
   "customers.errors.company_people_load_failed": "Verknüpfte Personen konnten nicht geladen werden",
   "customers.errors.company_required": "Unternehmens-ID ist erforderlich",
+  "customers.errors.context_required": "Organisations- und Mandantenkontext erforderlich",
   "customers.errors.customer_label_tables_missing": "Kundenlabel-Tabellen fehlen. Führen Sie yarn db:migrate aus.",
   "customers.errors.customer_not_found": "Kunde nicht gefunden",
   "customers.errors.deal_companies_load_failed": "Verknüpfte Unternehmen konnten nicht geladen werden",

package/src/modules/customers/i18n/en.json

@@ -1505,6 +1505,7 @@
   "customers.errors.company_not_found": "Company not found",
   "customers.errors.company_people_load_failed": "Failed to load linked people",
   "customers.errors.company_required": "Company id is required",
+  "customers.errors.context_required": "Organization and tenant context required",
   "customers.errors.customer_label_tables_missing": "Customer label tables are missing. Run yarn db:migrate.",
   "customers.errors.customer_not_found": "Customer not found",
   "customers.errors.deal_companies_load_failed": "Failed to load linked companies",

package/src/modules/customers/i18n/es.json

@@ -1505,6 +1505,7 @@
   "customers.errors.company_not_found": "Empresa no encontrada",
   "customers.errors.company_people_load_failed": "No se pudieron cargar las personas vinculadas",
   "customers.errors.company_required": "Se requiere el ID de la empresa",
+  "customers.errors.context_required": "Se requiere contexto de organización e inquilino",
   "customers.errors.customer_label_tables_missing": "Faltan las tablas de etiquetas de cliente. Ejecute yarn db:migrate.",
   "customers.errors.customer_not_found": "Cliente no encontrado",
   "customers.errors.deal_companies_load_failed": "No se pudieron cargar las empresas vinculadas",

package/src/modules/customers/i18n/pl.json

@@ -1505,6 +1505,7 @@
   "customers.errors.company_not_found": "Nie znaleziono firmy",
   "customers.errors.company_people_load_failed": "Nie udało się załadować powiązanych osób",
   "customers.errors.company_required": "Wymagany identyfikator firmy",
+  "customers.errors.context_required": "Wymagany jest kontekst organizacji i najemcy",
   "customers.errors.customer_label_tables_missing": "Brakuje tabel etykiet klientów. Uruchom yarn db:migrate.",
   "customers.errors.customer_not_found": "Nie znaleziono klienta",
   "customers.errors.deal_companies_load_failed": "Nie udało się załadować powiązanych firm",

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

@@ -4,8 +4,16 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { EncryptionMap } from '@open-mercato/core/modules/entities/data/entities'
 import { upsertEncryptionMapSchema } from '@open-mercato/core/modules/entities/data/validators'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 
+const ENCRYPTION_MAP_RESOURCE_KIND = 'entities.encryption_map'
+
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
   POST: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
@@ -18,6 +26,16 @@ function resolveScope(auth: { tenantId?: string | null; orgId?: string | null })
   }
 }
 
+function toIsoOrNull(value: Date | string | null | undefined): string | null {
+  if (value == null) return null
+  if (value instanceof Date) {
+    const ms = value.getTime()
+    return Number.isFinite(ms) ? new Date(ms).toISOString() : null
+  }
+  const trimmed = String(value).trim()
+  return trimmed.length ? trimmed : null
+}
+
 export async function GET(req: Request) {
   const url = new URL(req.url)
   const entityId = url.searchParams.get('entityId') || ''
@@ -26,8 +44,8 @@ export async function GET(req: Request) {
   if (!auth?.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   const { tenantId, organizationId } = resolveScope(auth)
 
-  const { resolve } = await createRequestContainer()
-  const em = resolve('em') as any
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as any
   const repo = em.getRepository(EncryptionMap)
   // Prefer tenant+org, then tenant-global, then global
   const candidates = [
@@ -51,52 +69,114 @@ export async function GET(req: Request) {
     organizationId,
     fields: record?.fieldsJson ?? [],
     isActive: record?.isActive ?? true,
+    updatedAt: toIsoOrNull(record?.updatedAt),
   })
 }
 
 export async function POST(req: Request) {
-  const body = await req.json().catch(() => ({}))
-  const parsed = upsertEncryptionMapSchema.safeParse(body)
-  if (!parsed.success) {
-    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
-  }
-  const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  const scope = resolveScope(auth)
-  const payload = parsed.data
-  const tenantId = scope.tenantId
-  const organizationId = scope.organizationId
+  try {
+    const body = await req.json().catch(() => ({}))
+    const parsed = upsertEncryptionMapSchema.safeParse(body)
+    if (!parsed.success) {
+      return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
+    }
+    const auth = await getAuthFromRequest(req)
+    if (!auth?.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    const scope = resolveScope(auth)
+    const payload = parsed.data
+    const tenantId: string = auth.tenantId
+    const organizationId = scope.organizationId
 
-  const { resolve } = await createRequestContainer()
-  const em = resolve('em') as any
-  const repo = em.getRepository(EncryptionMap)
-  const existing = await repo.findOne({ entityId: payload.entityId, tenantId, organizationId, deletedAt: null })
-  if (existing) {
-    existing.fieldsJson = payload.fields
-    existing.isActive = payload.isActive ?? true
-    existing.updatedAt = new Date()
-    await em.persist(existing).flush()
-  } else {
-    const map = repo.create({
-      entityId: payload.entityId,
+    const container = await createRequestContainer()
+    const em = container.resolve('em') as any
+    const repo = em.getRepository(EncryptionMap)
+    const existing = await repo.findOne({ entityId: payload.entityId, tenantId, organizationId, deletedAt: null })
+
+    // Reject stale writes: a save started from an older tab must not silently
+    // overwrite a newer encryption configuration. No-op when the client did not
+    // send the expected-version header (strictly additive).
+    if (existing) {
+      enforceCommandOptimisticLock({
+        resourceKind: ENCRYPTION_MAP_RESOURCE_KIND,
+        resourceId: existing.id,
+        current: existing.updatedAt,
+        request: req,
+      })
+    }
+
+    // Mutation-guard contract for custom write routes. The resource is the
+    // encryption map for this entity scoped to the tenant/organization.
+    const guardResult = await validateCrudMutationGuard(container, {
       tenantId,
       organizationId,
-      fieldsJson: payload.fields,
-      isActive: payload.isActive ?? true,
+      userId: auth.sub,
+      resourceKind: ENCRYPTION_MAP_RESOURCE_KIND,
+      resourceId: existing?.id ?? payload.entityId,
+      operation: existing ? 'update' : 'create',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: payload,
     })
-    await em.persist(map).flush()
-  }
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
 
-  try {
-    const svc = resolve('tenantEncryptionService') as { invalidateMap?: (e: string, t: string | null, o: string | null) => Promise<void> }
-    await svc?.invalidateMap?.(payload.entityId, tenantId, organizationId)
-  } catch {
-    // best-effort cache bust
-  }
+    let saved: any
+    if (existing) {
+      existing.fieldsJson = payload.fields
+      existing.isActive = payload.isActive ?? true
+      existing.updatedAt = new Date()
+      await em.persist(existing).flush()
+      saved = existing
+    } else {
+      const map = repo.create({
+        entityId: payload.entityId,
+        tenantId,
+        organizationId,
+        fieldsJson: payload.fields,
+        isActive: payload.isActive ?? true,
+      })
+      await em.persist(map).flush()
+      saved = map
+    }
+
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId,
+        organizationId,
+        userId: auth.sub,
+        resourceKind: ENCRYPTION_MAP_RESOURCE_KIND,
+        resourceId: saved?.id ?? payload.entityId,
+        operation: existing ? 'update' : 'create',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
+    try {
+      const svc = container.resolve('tenantEncryptionService') as { invalidateMap?: (e: string, t: string | null, o: string | null) => Promise<void> }
+      await svc?.invalidateMap?.(payload.entityId, tenantId, organizationId)
+    } catch {
+      // best-effort cache bust
+    }
 
-  return NextResponse.json({ ok: true })
+    return NextResponse.json({ ok: true, updatedAt: toIsoOrNull(saved?.updatedAt) })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    throw err
+  }
 }
 
+const conflictResponseSchema = z.object({
+  error: z.string(),
+  code: z.string(),
+  currentUpdatedAt: z.string(),
+  expectedUpdatedAt: z.string(),
+})
+
 export const openApi: OpenApiRouteDoc = {
   tag: 'Entities',
   summary: 'Manage encryption maps',
@@ -105,13 +185,16 @@ export const openApi: OpenApiRouteDoc = {
       summary: 'Fetch encryption map',
       description: 'Returns the encrypted field map for the current tenant/organization scope.',
       query: z.object({ entityId: z.string() }),
-      responses: [{ status: 200, description: 'Map', schema: z.object({ entityId: z.string(), fields: z.array(z.object({ field: z.string(), hashField: z.string().nullable().optional() })), isActive: z.boolean().optional() }) }],
+      responses: [{ status: 200, description: 'Map', schema: z.object({ entityId: z.string(), fields: z.array(z.object({ field: z.string(), hashField: z.string().nullable().optional() })), isActive: z.boolean().optional(), updatedAt: z.string().nullable().optional() }) }],
     },
     POST: {
       summary: 'Upsert encryption map',
-      description: 'Creates or updates the encryption map for the current tenant/organization scope.',
+      description: 'Creates or updates the encryption map for the current tenant/organization scope. Enforces optimistic locking when the caller sends the expected version header.',
       requestBody: { contentType: 'application/json', schema: upsertEncryptionMapSchema },
-      responses: [{ status: 200, description: 'Saved', schema: z.object({ ok: z.boolean() }) }],
+      responses: [
+        { status: 200, description: 'Saved', schema: z.object({ ok: z.boolean(), updatedAt: z.string().nullable().optional() }) },
+        { status: 409, description: 'Optimistic-lock conflict (stale write)', schema: conflictResponseSchema },
+      ],
     },
   },
 }

package/src/modules/entities/components/EncryptionManager.tsx

@@ -13,8 +13,10 @@ import {
 } from '@open-mercato/ui/primitives/select'
 import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useCustomFieldDefs, type CustomFieldDefDto } from '@open-mercato/ui/backend/utils/customFieldDefs'
 import { Plus, Save, Trash2 } from 'lucide-react'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -34,6 +36,7 @@ type EncryptionMapResponse = {
   entityId: string
   fields?: Array<{ field: string; hashField?: string | null }>
   isActive?: boolean
+  updatedAt?: string | null
 }
 
 type CanonicalOption = { value: string; label?: string }
@@ -225,6 +228,8 @@ export function EncryptionManager() {
     lastMapSignatureRef.current = signature
   }, [mapSignature, map, canonicalOptions, hasUserEdited])
 
+  const { runMutation } = useGuardedMutation({ contextId: 'entities.encryption-map' })
+
   const mutation = useMutation({
     mutationFn: async () => {
       const trimmed = fields
@@ -243,15 +248,29 @@ export function EncryptionManager() {
       if (!trimmed.length) {
         throw new Error(t('entities.encryption.errors.noFields', 'Add at least one field to encrypt'))
       }
-      const res = await apiCall('/api/entities/encryption', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ entityId: selectedEntityId, fields: trimmed, isActive }),
+      const payload = { entityId: selectedEntityId, fields: trimmed, isActive }
+      // Route the write through the guarded mutation helper so global injection
+      // modules (mutation guard, record-lock conflict handling) can run, and send
+      // the loaded map's version so a stale tab cannot silently overwrite a newer
+      // encryption configuration (the server rejects mismatches with a 409).
+      return runMutation({
+        operation: async () => {
+          const res = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(map?.updatedAt ?? null),
+            () => apiCall('/api/entities/encryption', {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(payload),
+            }),
+          )
+          if (!res.ok) {
+            await raiseCrudError(res.response, t('entities.encryption.errors.save', 'Failed to save encryption map'))
+          }
+          return true
+        },
+        context: {},
+        mutationPayload: payload,
       })
-      if (!res.ok) {
-        await raiseCrudError(res.response, t('entities.encryption.errors.save', 'Failed to save encryption map'))
-      }
-      return true
     },
     onSuccess: () => {
       flash(t('entities.encryption.flash.saved', 'Encryption map saved'), 'success')

package/src/modules/integrations/api/[id]/credentials/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { emitIntegrationsEvent } from '../../../events'
 import { saveCredentialsSchema } from '../../../data/validators'
 import {
@@ -58,8 +60,10 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
   let values: Record<string, unknown> | null
+  let updatedAt: Date | null
   try {
     values = await credentialsService.resolve(integration.id, scope)
+    updatedAt = await credentialsService.resolveUpdatedAt(integration.id, scope)
   } catch (error) {
     if (isCredentialsEncryptionUnavailableError(error)) {
       return NextResponse.json({ error: 'Integration credentials encryption is unavailable' }, { status: 503 })
@@ -71,6 +75,7 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
     integrationId: integration.id,
     schema: credentialsService.getSchema(integration.id),
     credentials: values ?? {},
+    updatedAt: updatedAt?.toISOString() ?? null,
   })
 }
 
@@ -130,6 +135,24 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
   const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
+  try {
+    const currentUpdatedAt = await credentialsService.resolveUpdatedAt(integration.id, scope)
+    enforceCommandOptimisticLock({
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      current: currentUpdatedAt,
+      request: req,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    if (isCredentialsEncryptionUnavailableError(error)) {
+      return NextResponse.json({ error: 'Integration credentials encryption is unavailable' }, { status: 503 })
+    }
+    throw error
+  }
+
   const credentialFieldErrors = collectCredentialUrlValidationErrors(
     credentialsService.getSchema(integration.id),
     payloadData.credentials,

package/src/modules/integrations/api/[id]/route.ts

@@ -59,11 +59,15 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
   const logService = container.resolve('integrationLogService') as IntegrationLogService
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
-  const [credentials, state, analyticsMap] = await Promise.all([
+  const [credentials, credentialsUpdatedAt, state, analyticsMap] = await Promise.all([
     credentialsService.resolve(integration.id, scope).catch((err) => {
       if (err instanceof CredentialsEncryptionUnavailableError) return null
       throw err
     }),
+    credentialsService.resolveUpdatedAt(integration.id, scope).catch((err) => {
+      if (err instanceof CredentialsEncryptionUnavailableError) return null
+      throw err
+    }),
     stateService.resolveState(integration.id, scope),
     logService.aggregateAnalytics([integration.id], scope, 30),
   ])
@@ -102,6 +106,7 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
             lastHealthCheckedAt: resolvedState.lastHealthCheckedAt?.toISOString() ?? null,
             lastHealthLatencyMs: resolvedState.lastHealthLatencyMs,
             enabledAt: resolvedState.enabledAt?.toISOString() ?? null,
+            updatedAt: resolvedState.updatedAt?.toISOString() ?? null,
           },
         }
       }),
@@ -132,8 +137,10 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
         lastHealthCheckedAt: state.lastHealthCheckedAt?.toISOString() ?? null,
         lastHealthLatencyMs: state.lastHealthLatencyMs,
         enabledAt: state.enabledAt?.toISOString() ?? null,
+        updatedAt: state.updatedAt?.toISOString() ?? null,
       },
       hasCredentials,
+      credentialsUpdatedAt: credentialsUpdatedAt?.toISOString() ?? null,
       healthStatus,
       analytics,
     },

package/src/modules/integrations/api/[id]/state/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { emitIntegrationsEvent } from '../../../events'
 import { updateStateSchema } from '../../../data/validators'
 import type { IntegrationStateService } from '../../../lib/state-service'
@@ -80,6 +82,22 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
   }
 
   const stateService = container.resolve('integrationStateService') as IntegrationStateService
+  const stateScope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  try {
+    const current = await stateService.resolveState(integration.id, stateScope)
+    enforceCommandOptimisticLock({
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      current: current.updatedAt,
+      request: req,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    throw error
+  }
 
   const state = await stateService.upsert(
     integration.id,
@@ -87,10 +105,7 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
       isEnabled: payloadData.isEnabled,
       reauthRequired: payloadData.reauthRequired,
     },
-    {
-      organizationId: auth.orgId as string,
-      tenantId: auth.tenantId,
-    },
+    stateScope,
   )
 
   await emitIntegrationsEvent('integrations.state.updated', {
@@ -117,5 +132,6 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
     isEnabled: state.isEnabled,
     reauthRequired: state.reauthRequired,
     apiVersion: state.apiVersion ?? null,
+    updatedAt: state.updatedAt?.toISOString() ?? null,
   })
 }

package/src/modules/integrations/api/[id]/version/route.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { emitIntegrationsEvent } from '../../../events'
 import { updateVersionSchema } from '../../../data/validators'
 import type { IntegrationStateService } from '../../../lib/state-service'
@@ -102,7 +104,22 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
   const stateService = container.resolve('integrationStateService') as IntegrationStateService
   const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
 
-  const before = await stateService.resolveApiVersion(integration.id, scope)
+  const currentState = await stateService.resolveState(integration.id, scope)
+  try {
+    enforceCommandOptimisticLock({
+      resourceKind: 'integrations.integration',
+      resourceId: integration.id,
+      current: currentState.updatedAt,
+      request: req,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+    throw error
+  }
+
+  const before = currentState.apiVersion
   await stateService.upsert(integration.id, { apiVersion: payloadData.apiVersion }, scope)
 
   await emitIntegrationsEvent('integrations.version.changed', {

package/src/modules/integrations/api/route.ts

@@ -93,6 +93,7 @@ export async function GET(req: Request) {
     lastHealthCheckedAt: string | null
     lastHealthLatencyMs: number | null
     enabledAt: string | null
+    stateUpdatedAt: string | null
     sortEnabledAtMs: number
     sortTitle: string
     sortCategory: string
@@ -140,6 +141,7 @@ export async function GET(req: Request) {
         lastHealthCheckedAt: state.lastHealthCheckedAt?.toISOString() ?? null,
         lastHealthLatencyMs: state.lastHealthLatencyMs,
         enabledAt: state.enabledAt?.toISOString() ?? null,
+        stateUpdatedAt: state.updatedAt?.toISOString() ?? null,
         sortEnabledAtMs: enabledAtMs,
         sortTitle: integration.title.toLowerCase(),
         sortCategory: (integration.category ?? '').toLowerCase(),
@@ -220,6 +222,7 @@ export async function GET(req: Request) {
       lastHealthCheckedAt: row.lastHealthCheckedAt,
       lastHealthLatencyMs: row.lastHealthLatencyMs,
       enabledAt: row.enabledAt,
+      stateUpdatedAt: row.stateUpdatedAt,
       analytics: analytics ?? {
         lastActivityAt: null,
         totalCount: 0,