@open-mercato/core 0.6.6-develop.6205.1.109e4b6a84 → 0.6.6-develop.6227.1.2695efff30

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/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,

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

@@ -20,6 +20,10 @@ import { installCustomEntitiesFromModules } from '../lib/install-from-ce'
 import { normalizeCustomFieldOptions } from '@open-mercato/shared/modules/entities/options'
 import { CURRENCY_OPTIONS_URL } from '@open-mercato/shared/modules/entities/kinds'
 import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  beginEntitiesMutationGuard,
+  FIELD_DEFINITION_RESOURCE_KIND,
+} from './definitions.mutation-guard'
 
 /**
  * Validate defaultValue against the field kind. Returns an error message string
@@ -473,6 +477,18 @@ export async function POST(req: Request) {
 
   const where: any = { entityId: input.entityId, key: input.key, organizationId: auth.orgId ?? null, tenantId: auth.tenantId ?? null }
   let def = await em.findOne(CustomFieldDef, where)
+
+  const guard = await beginEntitiesMutationGuard({
+    container,
+    auth,
+    req,
+    resourceKind: FIELD_DEFINITION_RESOURCE_KIND,
+    resourceId: def ? def.id : `${input.entityId}:${input.key}`,
+    operation: def ? 'update' : 'create',
+    mutationPayload: input as unknown as Record<string, unknown>,
+  })
+  if (guard.blockedResponse) return guard.blockedResponse
+
   if (!def) def = em.create(CustomFieldDef, { ...where, createdAt: new Date() })
   def.kind = input.kind
   const inCfg = (input as any).configJson ?? {}
@@ -508,6 +524,7 @@ export async function POST(req: Request) {
   def.updatedAt = new Date()
   em.persist(def)
   await em.flush()
+  await guard.runAfterSuccess()
   await invalidateDefinitionsCache(cache, {
     tenantId: auth.tenantId ?? null,
     organizationId: auth.orgId ?? null,
@@ -535,11 +552,24 @@ export async function DELETE(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: 'delete',
+    mutationPayload: { entityId, key },
+  })
+  if (guard.blockedResponse) return guard.blockedResponse
+
   def.isActive = false
   def.updatedAt = new Date()
   def.deletedAt = def.deletedAt ?? new Date()
   em.persist(def)
   await em.flush()
+  await guard.runAfterSuccess()
   await invalidateDefinitionsCache(cache, {
     tenantId: auth.tenantId ?? null,
     organizationId: auth.orgId ?? null,

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

@@ -10,8 +10,12 @@ import { isSystemEntitySelectable } from '@open-mercato/shared/lib/entities/syst
 import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
 import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  beginEntitiesMutationGuard,
+  ENTITY_DEFINITION_RESOURCE_KIND,
+} from './definitions.mutation-guard'
 
-const CUSTOM_ENTITY_DEFINITION_RESOURCE_KIND = 'entities.entity'
+const CUSTOM_ENTITY_DEFINITION_RESOURCE_KIND = ENTITY_DEFINITION_RESOURCE_KIND
 
 export const metadata = {
   GET: { requireAuth: true },
@@ -110,7 +114,8 @@ export async function POST(req: Request) {
   }
   const input = parsed.data
 
-  const { resolve } = await createRequestContainer()
+  const container = await createRequestContainer()
+  const { resolve } = container
   const em = resolve('em') as any
 
   // A registration for a module-declared, table-backed system entity would flip
@@ -140,6 +145,18 @@ export async function POST(req: Request) {
       throw lockError
     }
   }
+
+  const guard = await beginEntitiesMutationGuard({
+    container,
+    auth,
+    req,
+    resourceKind: ENTITY_DEFINITION_RESOURCE_KIND,
+    resourceId: ent ? ent.id : input.entityId,
+    operation: ent ? 'update' : 'create',
+    mutationPayload: input as unknown as Record<string, unknown>,
+  })
+  if (guard.blockedResponse) return guard.blockedResponse
+
   if (!ent) ent = em.create(CustomEntity, { ...where, createdAt: new Date() })
   ent.label = input.label
   ent.description = input.description ?? null
@@ -150,6 +167,7 @@ export async function POST(req: Request) {
   ent.updatedAt = new Date()
   em.persist(ent)
   await em.flush()
+  await guard.runAfterSuccess()
   // Invalidate sidebar/nav cache for tenant scope (also when tenantId is null)
   try {
     const cache = (await createRequestContainer()).resolve('cache') as any
@@ -168,17 +186,31 @@ export async function DELETE(req: Request) {
   const entityId = body?.entityId
   if (!entityId) return NextResponse.json({ error: 'entityId is required' }, { status: 400 })
 
-  const { resolve } = await createRequestContainer()
+  const container = await createRequestContainer()
+  const { resolve } = container
   const em = resolve('em') as any
 
   const where: any = { entityId, organizationId: auth.orgId ?? null, tenantId: auth.tenantId ?? null }
   const ent = await em.findOne(CustomEntity, where)
   if (!ent) return NextResponse.json({ error: 'Not found' }, { status: 404 })
+
+  const guard = await beginEntitiesMutationGuard({
+    container,
+    auth,
+    req,
+    resourceKind: ENTITY_DEFINITION_RESOURCE_KIND,
+    resourceId: ent.id,
+    operation: 'delete',
+    mutationPayload: { entityId },
+  })
+  if (guard.blockedResponse) return guard.blockedResponse
+
   ent.isActive = false
   ent.updatedAt = new Date()
   ent.deletedAt = ent.deletedAt ?? new Date()
   em.persist(ent)
   await em.flush()
+  await guard.runAfterSuccess()
   // Invalidate sidebar/nav cache for tenant scope (also when tenantId is null)
   try {
     const cache = (await createRequestContainer()).resolve('cache') as any