@open-mercato/core 0.6.6-develop.6205.1.109e4b6a84 → 0.6.6-develop.6228.1.cf483c68b5

package/src/modules/data_sync/api/schedules/route.ts

@@ -7,6 +7,10 @@ import type { SyncScheduleService } from '../../lib/sync-schedule-service'
 import { serializeSchedule } from './serialize'
 import { readOptimisticLockExpected } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['data_sync.configure'] },
@@ -65,15 +69,43 @@ export async function POST(req: Request) {
 
   const container = await createRequestContainer()
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
+  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+
+  const guardResult = await validateCrudMutationGuard(container, {
+    tenantId: auth.tenantId,
+    organizationId: scope.organizationId,
+    userId: auth.sub,
+    resourceKind: 'data_sync.schedule',
+    resourceId: scope.organizationId,
+    operation: 'create',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+    mutationPayload: parsed.data,
+  })
+  if (guardResult && !guardResult.ok) {
+    return NextResponse.json(guardResult.body, { status: guardResult.status })
+  }
 
   try {
     const schedule = await scheduleService.saveSchedule({
       ...parsed.data,
       expectedUpdatedAt: readOptimisticLockExpected(req),
-    }, {
-      organizationId: auth.orgId as string,
-      tenantId: auth.tenantId,
-    })
+    }, scope)
+
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: auth.tenantId,
+        organizationId: scope.organizationId,
+        userId: auth.sub,
+        resourceKind: 'data_sync.schedule',
+        resourceId: schedule.id,
+        operation: 'create',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     return NextResponse.json(serializeSchedule(schedule), { status: 201 })
   } catch (error) {
     if (isCrudHttpError(error)) {

package/src/modules/dictionaries/fields/dictionary.tsx

@@ -19,6 +19,7 @@ import { useDictionaryEntries } from '../components/hooks/useDictionaryEntries'
 type DictionaryFieldDefinition = {
   dictionaryId?: string
   dictionaryInlineCreate?: boolean
+  multi?: boolean
   defaultValue?: string
 }
 
@@ -84,9 +85,12 @@ function DictionaryFieldDefEditor({ def, onChange }: { def: { configJson?: Dicti
   const [items, setItems] = React.useState<DictionarySummary[]>([])
   const [loading, setLoading] = React.useState(false)
   const [error, setError] = React.useState<string | null>(null)
+  const multiId = React.useId()
   const inlineCreateId = React.useId()
   const selectedId = typeof def?.configJson?.dictionaryId === 'string' ? def?.configJson?.dictionaryId : ''
   const inlineCreate = def?.configJson?.dictionaryInlineCreate !== false
+  const isMulti = def?.configJson?.multi === true
+  const errorLoadLabel = t('dictionaries.customFields.errorLoad', 'Failed to load dictionaries.')
 
   React.useEffect(() => {
     let cancelled = false
@@ -116,7 +120,7 @@ function DictionaryFieldDefEditor({ def, onChange }: { def: { configJson?: Dicti
       } catch (err) {
         if (!cancelled) {
           console.error('Failed to load dictionaries list', err)
-          setError(t('dictionaries.customFields.errorLoad', 'Failed to load dictionaries.'))
+          setError(errorLoadLabel)
         }
       } finally {
         if (!cancelled) {
@@ -128,7 +132,7 @@ function DictionaryFieldDefEditor({ def, onChange }: { def: { configJson?: Dicti
     return () => {
       cancelled = true
     }
-  }, [t])
+  }, [errorLoadLabel])
 
   const manageHref = '/backend/config/dictionaries'
 
@@ -176,19 +180,38 @@ function DictionaryFieldDefEditor({ def, onChange }: { def: { configJson?: Dicti
       ) : null}
       <div className="inline-flex items-center gap-2 text-xs">
         <Checkbox
-          id={inlineCreateId}
-          checked={inlineCreate}
-          onCheckedChange={(checked) => onChange({ dictionaryInlineCreate: checked === true })}
+          id={multiId}
+          checked={isMulti}
+          onCheckedChange={(checked) => {
+            const enabled = checked === true
+            onChange({ multi: enabled, defaultValue: enabled ? undefined : def?.configJson?.defaultValue })
+          }}
           disabled={!selectedId}
         />
         <label
-          htmlFor={inlineCreateId}
+          htmlFor={multiId}
           className={selectedId ? 'cursor-pointer select-none' : 'cursor-not-allowed opacity-60'}
         >
-          {t('dictionaries.customFields.allowInlineCreate', 'Allow inline creation inside forms')}
+          {t('dictionaries.customFields.allowMultiple', 'Allow selecting multiple entries')}
         </label>
       </div>
-      {selectedId ? (
+      {!isMulti ? (
+        <div className="inline-flex items-center gap-2 text-xs">
+          <Checkbox
+            id={inlineCreateId}
+            checked={inlineCreate}
+            onCheckedChange={(checked) => onChange({ dictionaryInlineCreate: checked === true })}
+            disabled={!selectedId}
+          />
+          <label
+            htmlFor={inlineCreateId}
+            className={selectedId ? 'cursor-pointer select-none' : 'cursor-not-allowed opacity-60'}
+          >
+            {t('dictionaries.customFields.allowInlineCreate', 'Allow inline creation inside forms')}
+          </label>
+        </div>
+      ) : null}
+      {selectedId && !isMulti ? (
         <DictionaryDefaultSelector
           dictionaryId={selectedId}
           defaultValue={typeof def?.configJson?.defaultValue === 'string' ? def.configJson.defaultValue : ''}

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

@@ -80,6 +80,7 @@
   "dictionaries.config.success.delete": "Wörterbuch gelöscht.",
   "dictionaries.config.success.update": "Wörterbuch aktualisiert.",
   "dictionaries.customFields.allowInlineCreate": "Inline-Erstellung in Formularen erlauben",
+  "dictionaries.customFields.allowMultiple": "Mehrere Einträge auswählen erlauben",
   "dictionaries.customFields.defaultValue": "Standardwert",
   "dictionaries.customFields.defaultValueNone": "Kein Standardwert",
   "dictionaries.customFields.defaultValueStale": "Standardeintrag nicht gefunden — er wurde möglicherweise gelöscht oder umbenannt.",

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

@@ -80,6 +80,7 @@
   "dictionaries.config.success.delete": "Dictionary deleted.",
   "dictionaries.config.success.update": "Dictionary updated.",
   "dictionaries.customFields.allowInlineCreate": "Allow inline creation inside forms",
+  "dictionaries.customFields.allowMultiple": "Allow selecting multiple entries",
   "dictionaries.customFields.defaultValue": "Default value",
   "dictionaries.customFields.defaultValueNone": "No default",
   "dictionaries.customFields.defaultValueStale": "Default entry not found — it may have been deleted or renamed.",

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

@@ -80,6 +80,7 @@
   "dictionaries.config.success.delete": "Diccionario eliminado.",
   "dictionaries.config.success.update": "Diccionario actualizado.",
   "dictionaries.customFields.allowInlineCreate": "Permitir creación en línea dentro de los formularios",
+  "dictionaries.customFields.allowMultiple": "Permitir seleccionar varias entradas",
   "dictionaries.customFields.defaultValue": "Valor predeterminado",
   "dictionaries.customFields.defaultValueNone": "Sin valor predeterminado",
   "dictionaries.customFields.defaultValueStale": "No se encontró la entrada predeterminada; puede haber sido eliminada o renombrada.",

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

@@ -80,6 +80,7 @@
   "dictionaries.config.success.delete": "Słownik został usunięty.",
   "dictionaries.config.success.update": "Słownik został zaktualizowany.",
   "dictionaries.customFields.allowInlineCreate": "Zezwól na tworzenie w formularzach",
+  "dictionaries.customFields.allowMultiple": "Zezwól na wybór wielu wpisów",
   "dictionaries.customFields.defaultValue": "Wartość domyślna",
   "dictionaries.customFields.defaultValueNone": "Brak wartości domyślnej",
   "dictionaries.customFields.defaultValueStale": "Nie znaleziono domyślnego wpisu — mógł zostać usunięty albo przemianowany.",

package/src/modules/directory/api/organization-branding/route.ts

@@ -7,6 +7,11 @@ 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 {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { Organization } from '@open-mercato/core/modules/directory/data/entities'
@@ -24,6 +29,7 @@ const brandingResponseSchema = z.object({
   organizationName: z.string(),
   tenantId: z.string().uuid(),
   logoUrl: z.string().nullable(),
+  updatedAt: z.string().nullable(),
 })
 
 const brandingUpdateSchema = z.object({
@@ -105,12 +111,25 @@ async function resolveCurrentOrganization(req: Request) {
   return { auth, container, organization, organizationId, tenantId, translate }
 }
 
+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()
+  if (!trimmed) return null
+  const parsed = new Date(trimmed)
+  return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : null
+}
+
 function toResponsePayload(organization: Organization, tenantId: string) {
   return {
     organizationId: String(organization.id),
     organizationName: organization.name,
     tenantId,
     logoUrl: organization.logoUrl ?? null,
+    updatedAt: toIsoOrNull(organization.updatedAt),
   }
 }
 
@@ -169,6 +188,32 @@ export async function PUT(req: Request) {
   }
 
   try {
+    // Refuse a stale overwrite when two tabs edit the same organization branding.
+    // Strictly additive — a no-op when the client omits the expected-version header.
+    enforceCommandOptimisticLock({
+      resourceKind: 'directory.organization',
+      resourceId: resolved.organizationId,
+      current: resolved.organization.updatedAt ?? null,
+      request: req,
+    })
+
+    // Mutation-guard contract for custom write routes: validate before the write,
+    // then run the after-success hook once the command persists.
+    const guardResult = await validateCrudMutationGuard(resolved.container, {
+      tenantId: resolved.tenantId,
+      organizationId: resolved.organizationId,
+      userId: resolved.auth.sub,
+      resourceKind: 'directory.organization',
+      resourceId: resolved.organizationId,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: { logoUrl: parsed.data.logoUrl ?? null },
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     const commandBus = resolved.container.resolve('commandBus') as CommandBus
     const ctx = buildCommandContext(
       resolved.container,
@@ -188,6 +233,21 @@ export async function PUT(req: Request) {
         ctx,
       },
     )
+
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(resolved.container, {
+        tenantId: resolved.tenantId,
+        organizationId: resolved.organizationId,
+        userId: resolved.auth.sub,
+        resourceKind: 'directory.organization',
+        resourceId: resolved.organizationId,
+        operation: 'update',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     await invalidateSidebarBrandingCache(resolved.container, resolved.organizationId, resolved.tenantId)
     return NextResponse.json(toResponsePayload(result, resolved.tenantId))
   } catch (err) {
@@ -231,6 +291,7 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Save failed', schema: errorSchema },
         { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 409, description: 'Organization branding changed since it was loaded', schema: errorSchema },
         { status: 422, description: 'Invalid logo URL', schema: errorSchema },
       ],
     },

package/src/modules/directory/backend/directory/branding/page.tsx

@@ -7,7 +7,9 @@ import { Page, PageBody, PageHeader } from '@open-mercato/ui/backend/Page'
 import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
-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 { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Input } from '@open-mercato/ui/primitives/input'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -17,6 +19,7 @@ type BrandingPayload = {
   organizationName: string
   tenantId: string
   logoUrl: string | null
+  updatedAt: string | null
 }
 
 type UploadPayload = {
@@ -98,15 +101,17 @@ export default function OrganizationBrandingPage() {
         operation: async () => {
           const uploadedLogoUrl = shouldUpload ? await uploadLogo(data.organizationId) : null
           const resolvedLogoUrl = uploadedLogoUrl ?? nextLogoUrl ?? logoUrl.trim()
-          // optimistic-lock-exempt: selected organization branding uses a scoped command endpoint without an exposed updatedAt token.
-          const response = await apiCallOrThrow<BrandingPayload>(
-            BRANDING_API,
-            {
-              method: 'PUT',
-              headers: { 'content-type': 'application/json' },
-              body: JSON.stringify({ logoUrl: resolvedLogoUrl || null }),
-            },
-            { errorMessage: t('directory.branding.errors.save', 'Failed to update organization branding') },
+          const response = await withScopedApiRequestHeaders(
+            buildOptimisticLockHeader(data.updatedAt),
+            () => apiCallOrThrow<BrandingPayload>(
+              BRANDING_API,
+              {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ logoUrl: resolvedLogoUrl || null }),
+              },
+              { errorMessage: t('directory.branding.errors.save', 'Failed to update organization branding') },
+            ),
           )
           return response.result
         },
@@ -127,6 +132,7 @@ export default function OrganizationBrandingPage() {
       if (fileInputRef.current) fileInputRef.current.value = ''
       flash(t('directory.branding.flash.saved', 'Organization branding updated'), 'success')
     } catch (err: unknown) {
+      if (surfaceRecordConflict(err, t)) return
       const fallback = t('directory.branding.errors.save', 'Failed to update organization branding')
       const message = err instanceof Error ? err.message : fallback
       flash(message, 'error')

package/src/modules/directory/backend/directory/organizations/page.tsx

@@ -13,6 +13,8 @@ import { Button } from '@open-mercato/ui/primitives/button'
 import { apiCall, apiCallOrThrow, 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 { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -177,6 +179,17 @@ export default function DirectoryOrganizationsPage() {
   const total = data?.total ?? 0
   const totalPages = data?.totalPages ?? 0
 
+  const deleteMutationContextId = 'directory-organizations-list:single-delete'
+  const { runMutation: runDeleteMutation, retryLastMutation: retryDeleteMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({
+    contextId: deleteMutationContextId,
+    blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
+  })
+
   const handleDelete = React.useCallback(async (org: OrganizationRow) => {
     const confirmLabel = t('directory.organizations.list.confirmDelete', 'Archive organization "{{name}}"?', { name: org.name })
     const confirmed = await confirm({
@@ -187,22 +200,36 @@ export default function DirectoryOrganizationsPage() {
     if (!confirmed) return
 
     try {
-      await withScopedApiRequestHeaders(
-        buildOptimisticLockHeader(org.updatedAt),
-        () => apiCallOrThrow(
-          `/api/directory/organizations?id=${encodeURIComponent(org.id)}`,
-          { method: 'DELETE' },
-          { errorMessage: t('directory.organizations.list.error.delete', 'Failed to delete organization') },
+      await runDeleteMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(org.updatedAt),
+          () => apiCallOrThrow(
+            `/api/directory/organizations?id=${encodeURIComponent(org.id)}`,
+            { method: 'DELETE' },
+            { errorMessage: t('directory.organizations.list.error.delete', 'Failed to delete organization') },
+          ),
         ),
-      )
+        context: {
+          formId: deleteMutationContextId,
+          resourceKind: 'directory.organization',
+          resourceId: org.id,
+          retryLastMutation: retryDeleteMutation,
+        },
+      })
       await queryClient.invalidateQueries({ queryKey: ['directory-organizations'] })
       flash(t('directory.organizations.flash.deleted', 'Organization deleted'), 'success')
     } catch (err: unknown) {
+      // A stale delete surfaces the unified conflict bar (via the guarded
+      // mutation) — skip the generic error flash to avoid a double message.
+      if (surfaceRecordConflict(err, t)) {
+        await queryClient.invalidateQueries({ queryKey: ['directory-organizations'] })
+        return
+      }
       const fallback = t('directory.organizations.list.error.delete', 'Failed to delete organization')
       const message = err instanceof Error ? err.message : fallback
       flash(message, 'error')
     }
-  }, [confirm, queryClient, t])
+  }, [confirm, deleteMutationContextId, queryClient, retryDeleteMutation, runDeleteMutation, t])
 
   return (
     <Page>

package/src/modules/directory/backend/directory/tenants/page.tsx

@@ -10,10 +10,11 @@ import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { BooleanIcon } from '@open-mercato/ui/backend/ValueIcons'
 import type { FilterValues } from '@open-mercato/ui/backend/FilterBar'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, apiCallOrThrow, 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 { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -117,6 +118,17 @@ export default function DirectoryTenantsPage() {
   const total = data?.total ?? 0
   const totalPages = data?.totalPages ?? 0
 
+  const deleteMutationContextId = 'directory-tenants-list:single-delete'
+  const { runMutation: runDeleteMutation, retryLastMutation: retryDeleteMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({
+    contextId: deleteMutationContextId,
+    blockedMessage: t('ui.forms.flash.saveBlocked', 'Save blocked by validation'),
+  })
+
   const handleDelete = React.useCallback(async (tenant: TenantRow) => {
     const confirmMessage = t('directory.tenants.list.confirmDelete', 'Delete tenant "{{name}}"? This will archive it.').replace('{{name}}', tenant.name)
     const confirmed = await confirm({
@@ -127,23 +139,35 @@ export default function DirectoryTenantsPage() {
     if (!confirmed) return
 
     try {
-      const call = await withScopedApiRequestHeaders(
-        buildOptimisticLockHeader(tenant.updatedAt),
-        () => apiCall(
-          `/api/directory/tenants?id=${encodeURIComponent(tenant.id)}`,
-          { method: 'DELETE' },
+      await runDeleteMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(tenant.updatedAt),
+          () => apiCallOrThrow(
+            `/api/directory/tenants?id=${encodeURIComponent(tenant.id)}`,
+            { method: 'DELETE' },
+            { errorMessage: t('directory.tenants.list.error.delete', 'Failed to delete tenant') },
+          ),
         ),
-      )
-      if (!call.ok) {
-        await raiseCrudError(call.response, t('directory.tenants.list.error.delete', 'Failed to delete tenant'))
-      }
+        context: {
+          formId: deleteMutationContextId,
+          resourceKind: 'directory.tenant',
+          resourceId: tenant.id,
+          retryLastMutation: retryDeleteMutation,
+        },
+      })
       await queryClient.invalidateQueries({ queryKey: ['directory-tenants'] })
       flash(t('directory.tenants.list.success.delete', 'Tenant deleted'), 'success')
-    } catch (err: any) {
+    } catch (err: unknown) {
+      // A stale delete surfaces the unified conflict bar (via the guarded
+      // mutation) — skip the generic error flash to avoid a double message.
+      if (surfaceRecordConflict(err, t)) {
+        await queryClient.invalidateQueries({ queryKey: ['directory-tenants'] })
+        return
+      }
       const message = err instanceof Error ? err.message : t('directory.tenants.list.error.delete', 'Failed to delete tenant')
       flash(message, 'error')
     }
-  }, [confirm, queryClient, t])
+  }, [confirm, deleteMutationContextId, queryClient, retryDeleteMutation, runDeleteMutation, t])
 
   return (
     <Page>

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

@@ -8,6 +8,10 @@ import { z } from 'zod'
 import { invalidateDefinitionsCache } from './definitions.cache'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { mergeEntityFieldsetConfig, normalizeEntityFieldsetConfig } from '../lib/fieldsets'
+import {
+  beginEntitiesMutationGuard,
+  FIELD_DEFINITION_RESOURCE_KIND,
+} from './definitions.mutation-guard'
 
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
@@ -67,6 +71,17 @@ export async function POST(req: Request) {
     cache = resolve('cache') as CacheStrategy
   } catch {}
 
+  const guard = await beginEntitiesMutationGuard({
+    container,
+    auth,
+    req,
+    resourceKind: FIELD_DEFINITION_RESOURCE_KIND,
+    resourceId: entityId,
+    operation: 'custom',
+    mutationPayload: { entityId, definitionCount: definitions.length },
+  })
+  if (guard.blockedResponse) return guard.blockedResponse
+
   await em.begin()
   try {
     // Prefetch every existing definition for this entity in a single query, then index
@@ -134,6 +149,8 @@ export async function POST(req: Request) {
     return NextResponse.json({ error: 'Failed to save definitions batch' }, { status: 500 })
   }
 
+  await guard.runAfterSuccess()
+
   await invalidateDefinitionsCache(cache, {
     tenantId: auth.tenantId ?? null,
     organizationId: auth.orgId ?? null,

package/src/modules/entities/api/definitions.mutation-guard.ts

@@ -0,0 +1,80 @@
+import { NextResponse } from 'next/server'
+import type { AwilixContainer } from 'awilix'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+
+export const ENTITY_DEFINITION_RESOURCE_KIND = 'entities.entity'
+export const FIELD_DEFINITION_RESOURCE_KIND = 'entities.field_definition'
+
+type AuthenticatedContext = NonNullable<AuthContext>
+
+type GuardOperation = 'create' | 'update' | 'delete' | 'custom'
+
+type EntitiesMutationGuardContext = {
+  container: AwilixContainer
+  auth: AuthenticatedContext
+  req: Request
+  resourceKind: string
+  resourceId: string
+  operation: GuardOperation
+  mutationPayload?: Record<string, unknown> | null
+}
+
+type EntitiesMutationGuardHandle = {
+  blockedResponse: NextResponse | null
+  runAfterSuccess: () => Promise<void>
+}
+
+function resolveActorUserId(auth: AuthenticatedContext): string {
+  return auth.userId ?? auth.sub
+}
+
+export async function beginEntitiesMutationGuard(
+  ctx: EntitiesMutationGuardContext,
+): Promise<EntitiesMutationGuardHandle> {
+  const tenantId = ctx.auth.tenantId
+  const userId = resolveActorUserId(ctx.auth)
+  if (!tenantId) {
+    return { blockedResponse: null, runAfterSuccess: async () => undefined }
+  }
+
+  const guardResult = await validateCrudMutationGuard(ctx.container, {
+    tenantId,
+    organizationId: ctx.auth.orgId ?? null,
+    userId,
+    resourceKind: ctx.resourceKind,
+    resourceId: ctx.resourceId,
+    operation: ctx.operation,
+    requestMethod: ctx.req.method,
+    requestHeaders: ctx.req.headers,
+    mutationPayload: ctx.mutationPayload ?? null,
+  })
+
+  if (guardResult && !guardResult.ok) {
+    return {
+      blockedResponse: NextResponse.json(guardResult.body, { status: guardResult.status }),
+      runAfterSuccess: async () => undefined,
+    }
+  }
+
+  return {
+    blockedResponse: null,
+    runAfterSuccess: async () => {
+      if (!guardResult?.ok || !guardResult.shouldRunAfterSuccess) return
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId,
+        organizationId: ctx.auth.orgId ?? null,
+        userId,
+        resourceKind: ctx.resourceKind,
+        resourceId: ctx.resourceId,
+        operation: ctx.operation,
+        requestMethod: ctx.req.method,
+        requestHeaders: ctx.req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    },
+  }
+}

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

@@ -6,6 +6,10 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { CustomFieldDef } from '@open-mercato/core/modules/entities/data/entities'
 import { invalidateDefinitionsCache } from './definitions.cache'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  beginEntitiesMutationGuard,
+  FIELD_DEFINITION_RESOURCE_KIND,
+} from './definitions.mutation-guard'
 
 export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
@@ -30,11 +34,24 @@ export async function POST(req: Request) {
   const where: any = { entityId, key, organizationId: auth.orgId ?? null, tenantId: auth.tenantId ?? null }
   const def = await em.findOne(CustomFieldDef, where)
   if (!def) return NextResponse.json({ error: 'Not found' }, { status: 404 })
+
+  const guard = await beginEntitiesMutationGuard({
+    container,
+    auth,
+    req,
+    resourceKind: FIELD_DEFINITION_RESOURCE_KIND,
+    resourceId: def.id,
+    operation: 'custom',
+    mutationPayload: { entityId, key },
+  })
+  if (guard.blockedResponse) return guard.blockedResponse
+
   ;(def as any).deletedAt = null
   ;(def as any).isActive = true
   ;(def as any).updatedAt = new Date()
   em.persist(def)
   await em.flush()
+  await guard.runAfterSuccess()
   await invalidateDefinitionsCache(cache, {
     tenantId: auth.tenantId ?? null,
     organizationId: auth.orgId ?? null,