@open-mercato/core 0.6.6-develop.6204.1.30b1f58642 → 0.6.6-develop.6227.1.2695efff30

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

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

@@ -539,6 +539,26 @@ export async function DELETE(req: Request) {
     if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
     const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
+
+    try {
+      const currentUpdatedAt = await readCustomEntityRecordUpdatedAt(em, {
+        entityType: entityId,
+        entityId: recordId,
+        organizationId: targetOrgId,
+      })
+      enforceCommandOptimisticLock({
+        resourceKind: CUSTOM_ENTITY_RECORD_RESOURCE_KIND,
+        resourceId: recordId,
+        current: currentUpdatedAt,
+        request: req,
+      })
+    } catch (lockError) {
+      if (isCrudHttpError(lockError)) {
+        return NextResponse.json(lockError.body, { status: lockError.status })
+      }
+      throw lockError
+    }
+
     await de.deleteCustomEntityRecord({ entityId, recordId, organizationId: targetOrgId, tenantId: auth.tenantId!, soft: true })
     return NextResponse.json({ ok: true })
   } catch (e) {

package/src/modules/entities/backend/entities/user/[entityId]/records/page.tsx

@@ -17,6 +17,7 @@ import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
 import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
@@ -67,6 +68,7 @@ export default function RecordsPage({ params }: { params: { entityId?: string }
 }
 
 function RecordsPageInner({ params }: { params: { entityId?: string } }) {
+  const t = useT()
   const entityId = decodeURIComponent(params?.entityId || '')
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'id', desc: false }])
   const [page, setPage] = React.useState(1)
@@ -80,6 +82,16 @@ function RecordsPageInner({ params }: { params: { entityId?: string } }) {
   const [loading, setLoading] = React.useState(false)
   const scopeVersion = useOrganizationScopeVersion()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
+  const deleteMutationContextId = `entities.user.records.${entityId}: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 { data: cfDefs = [] } = useCustomFieldDefs(entityId, {
     enabled: Boolean(entityId),
     keyExtras: [scopeVersion],
@@ -367,22 +379,33 @@ export RECORD_ID="<record uuid>"`}</code></pre>
               items={[
                 { id: 'edit', label: 'Edit', href: `/backend/entities/user/${encodeURIComponent(entityId)}/records/${encodeURIComponent(String((row as any).id))}` },
                 { id: 'delete', label: 'Delete', destructive: true, onSelect: async () => {
+                  const recordId = String((row as any).id)
                   try {
                     const confirmed = await confirm({
                       title: 'Delete this record?',
                       variant: 'destructive',
                     })
                     if (!confirmed) return
-                    const deleteCall = await withScopedApiRequestHeaders(
-                      buildOptimisticLockHeader((row as any).updatedAt),
-                      () => apiCall(
-                        `/api/entities/records?entityId=${encodeURIComponent(entityId)}&recordId=${encodeURIComponent(String((row as any).id))}`,
-                        { method: 'DELETE' },
-                      ),
-                    )
-                    if (!deleteCall.ok) {
-                      await raiseCrudError(deleteCall.response, 'Failed to delete record')
-                    }
+                    await runDeleteMutation({
+                      operation: async () => {
+                        const deleteCall = await withScopedApiRequestHeaders(
+                          buildOptimisticLockHeader((row as any).updatedAt),
+                          () => apiCall(
+                            `/api/entities/records?entityId=${encodeURIComponent(entityId)}&recordId=${encodeURIComponent(recordId)}`,
+                            { method: 'DELETE' },
+                          ),
+                        )
+                        if (!deleteCall.ok) {
+                          await raiseCrudError(deleteCall.response, 'Failed to delete record')
+                        }
+                      },
+                      context: {
+                        formId: deleteMutationContextId,
+                        resourceKind: 'entities.record',
+                        resourceId: recordId,
+                        retryLastMutation: retryDeleteMutation,
+                      },
+                    })
                     const j = await readApiResultOrThrow<RecordsResponse>(
                       `/api/entities/records?entityId=${encodeURIComponent(entityId)}&page=${page}&pageSize=${pageSize}`,
                       undefined,

package/src/modules/feature_toggles/api/overrides/route.ts

@@ -6,6 +6,10 @@ import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/op
 import { getOverrides } from '../../lib/queries'
 import { 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 { logCrudAccess } from '@open-mercato/shared/lib/crud/factory'
 import { FeatureToggleOverride } from '../../data/entities'
 import { buildContext } from '../../lib/utils'
@@ -75,7 +79,7 @@ export async function PUT(req: Request) {
       return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
     }
 
-    const { scope } = await resolveFeatureCheckContext({
+    const { scope, organizationId } = await resolveFeatureCheckContext({
       container: ctx.container,
       auth: ctx.auth,
       request: req
@@ -104,6 +108,31 @@ export async function PUT(req: Request) {
       })
     }
 
+    // Run the CRUD mutation guard lifecycle so this custom write route honors
+    // module-level guard injections (and after-success hooks) like every other
+    // mutating endpoint. The override either updates an existing row or creates a
+    // new one, so the resource id falls back to the toggle id when no row exists.
+    const guardUserId = ctx.auth?.userId ?? ctx.auth?.sub ?? null
+    if (!guardUserId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const guardResourceKind = 'feature_toggles.feature_toggle_override'
+    const guardResourceId = existingOverride?.id ?? parsed.data.toggleId
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: scope.tenantId,
+      organizationId: organizationId ?? null,
+      userId: guardUserId,
+      resourceKind: guardResourceKind,
+      resourceId: guardResourceId,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: parsed.data,
+    })
+    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<ProcessedChangeOverrideStateInput, { overrideToggleId: string | null }>('feature_toggles.overrides.changeState', {
       input: {
@@ -115,6 +144,20 @@ export async function PUT(req: Request) {
       ctx,
     })
 
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: scope.tenantId,
+        organizationId: organizationId ?? null,
+        userId: guardUserId,
+        resourceKind: guardResourceKind,
+        resourceId: result?.overrideToggleId ?? guardResourceId,
+        operation: 'update',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     const response = NextResponse.json({
       ok: true,
       overrideToggleId: result?.overrideToggleId ?? null,

package/src/modules/inbox_ops/api/emails/[id]/route.ts

@@ -1,6 +1,10 @@
 import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { InboxEmail } from '../../../data/entities'
 import {
   resolveRequestContext,
@@ -62,6 +66,20 @@ export async function DELETE(req: Request) {
 
     const ctx = await resolveRequestContext(req)
 
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      userId: ctx.userId,
+      resourceKind: 'inbox_ops:inbox_email',
+      resourceId: id,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     const updated = await ctx.em.nativeUpdate(
       InboxEmail,
       {
@@ -77,6 +95,20 @@ export async function DELETE(req: Request) {
       return NextResponse.json({ error: 'Email not found' }, { status: 404 })
     }
 
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        resourceKind: 'inbox_ops:inbox_email',
+        resourceId: id,
+        operation: 'delete',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     return NextResponse.json({ ok: true })
   } catch (err) {
     if (err instanceof UnauthorizedError) {

package/src/modules/inbox_ops/api/proposals/[id]/accept-all/route.ts

@@ -1,6 +1,10 @@
 import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { runWithCacheTenant } from '@open-mercato/cache'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { acceptAllActions } from '../../../../lib/executionEngine'
 import { resolveCache, invalidateCountsCache } from '../../../../lib/cache'
 import {
@@ -22,6 +26,20 @@ export async function POST(req: Request) {
     const proposal = await resolveProposal(new URL(req.url), ctx)
     if (isErrorResponse(proposal)) return proposal
 
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      userId: ctx.userId,
+      resourceKind: 'inbox_ops:inbox_proposal',
+      resourceId: proposal.id,
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     const entities = resolveCrossModuleEntities(ctx.container)
     const { results, stoppedOnFailure } = await acceptAllActions(
       proposal.id,
@@ -31,6 +49,20 @@ export async function POST(req: Request) {
     const succeeded = results.filter((r) => r.success).length
     const failed = results.filter((r) => !r.success).length
 
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        resourceKind: 'inbox_ops:inbox_proposal',
+        resourceId: proposal.id,
+        operation: 'custom',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     const cache = resolveCache(ctx.container)
     await runWithCacheTenant(ctx.tenantId, () => invalidateCountsCache(cache, ctx.tenantId))
 

package/src/modules/inbox_ops/api/proposals/[id]/actions/[actionId]/route.ts

@@ -1,6 +1,10 @@
 import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { runWithCacheTenant } from '@open-mercato/cache'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { actionEditSchema, validateActionPayloadForType } from '../../../../../data/validators'
 import { emitInboxOpsEvent } from '../../../../../events'
 import { resolveCache, invalidateCountsCache } from '../../../../../lib/cache'
@@ -39,9 +43,38 @@ export async function PATCH(req: Request) {
       return NextResponse.json({ error: payloadValidation.error }, { status: 400 })
     }
 
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      userId: ctx.userId,
+      resourceKind: 'inbox_ops:inbox_proposal_action',
+      resourceId: action.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: parsed.data,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     action.payload = mergedPayload
     await ctx.em.flush()
 
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        resourceKind: 'inbox_ops:inbox_proposal_action',
+        resourceId: action.id,
+        operation: 'update',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     const cache = resolveCache(ctx.container)
     await runWithCacheTenant(ctx.tenantId, () => invalidateCountsCache(cache, ctx.tenantId))
 

package/src/modules/inbox_ops/api/proposals/[id]/categorize/route.ts

@@ -1,6 +1,10 @@
 import { NextResponse } from 'next/server'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { runWithCacheTenant } from '@open-mercato/cache'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { categorizeProposalSchema } from '../../../../data/validators'
 import { resolveCache, invalidateCountsCache } from '../../../../lib/cache'
 import {
@@ -27,10 +31,39 @@ export async function POST(req: Request) {
       return NextResponse.json({ error: `Invalid category: ${issues}` }, { status: 400 })
     }
 
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      userId: ctx.userId,
+      resourceKind: 'inbox_ops:inbox_proposal',
+      resourceId: proposal.id,
+      operation: 'update',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: parsed.data,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     const previousCategory = proposal.category || null
     proposal.category = parsed.data.category
     await ctx.em.flush()
 
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        resourceKind: 'inbox_ops:inbox_proposal',
+        resourceId: proposal.id,
+        operation: 'update',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     const cache = resolveCache(ctx.container)
     await runWithCacheTenant(ctx.tenantId, () => invalidateCountsCache(cache, ctx.tenantId))
 

package/src/modules/messages/components/message-detail/hooks/useMessageDetailsActions.ts

@@ -5,6 +5,7 @@ import type { UseQueryResult } from '@tanstack/react-query'
 import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
 import type { MessageActionsProps, MessageContentProps } from '@open-mercato/shared/modules/messages/types'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
 import type {
   ActionResult,
@@ -21,6 +22,13 @@ type RequestAndRefreshOptions = {
 
 type ConversationActionKind = 'archiveConversation' | 'deleteConversation' | 'markAllUnread'
 
+type MessageDetailMutationContext = {
+  resourceKind: 'message' | 'conversation'
+  messageId: string
+  action: string
+  retryLastMutation: () => Promise<boolean>
+}
+
 type UseMessageDetailsActionsInput = {
   id: string
   t: TranslateFn
@@ -51,6 +59,10 @@ export function useMessageDetailsActions({
   const [deleteConfirmationOpen, setDeleteConfirmationOpen] = React.useState(false)
   const [activeConversationAction, setActiveConversationAction] = React.useState<ConversationActionKind | null>(null)
 
+  const { runMutation, retryLastMutation } = useGuardedMutation<MessageDetailMutationContext>({
+    contextId: 'messages-detail-actions',
+  })
+
   const requestAndRefresh = React.useCallback(async (
     url: string,
     method: 'PUT' | 'DELETE',
@@ -58,18 +70,24 @@ export function useMessageDetailsActions({
   ) => {
     setUpdatingState(true)
     try {
-      const call = await apiCall<{ ok?: boolean }>(url, { method })
-      if (!call.ok) {
-        throw new Error(
-          toErrorMessage(call.result)
-          ?? t('messages.errors.stateChangeFailed', 'Failed to update message state.'),
-        )
-      }
-      if (options?.skipDetailAutoMarkRead) {
-        await refreshDetailWithoutAutoMarkRead()
-      } else {
-        await detailQuery.refetch()
-      }
+      await runMutation({
+        operation: async () => {
+          const call = await apiCall<{ ok?: boolean }>(url, { method })
+          if (!call.ok) {
+            throw new Error(
+              toErrorMessage(call.result)
+              ?? t('messages.errors.stateChangeFailed', 'Failed to update message state.'),
+            )
+          }
+          if (options?.skipDetailAutoMarkRead) {
+            await refreshDetailWithoutAutoMarkRead()
+          } else {
+            await detailQuery.refetch()
+          }
+        },
+        context: { resourceKind: 'message', messageId: id, action: 'state-change', retryLastMutation },
+        mutationPayload: { messageId: id, action: 'state-change', url, method },
+      })
     } catch (err) {
       flash(
         err instanceof Error
@@ -80,17 +98,23 @@ export function useMessageDetailsActions({
     } finally {
       setUpdatingState(false)
     }
-  }, [detailQuery, refreshDetailWithoutAutoMarkRead, t])
+  }, [detailQuery, id, refreshDetailWithoutAutoMarkRead, retryLastMutation, runMutation, t])
 
   const handleDelete = React.useCallback(async () => {
     setUpdatingState(true)
     try {
-      const call = await apiCall<{ ok?: boolean }>(`/api/messages/${encodeURIComponent(id)}`, {
-        method: 'DELETE',
+      await runMutation({
+        operation: async () => {
+          const call = await apiCall<{ ok?: boolean }>(`/api/messages/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+          })
+          if (!call.ok) {
+            throw new Error(toErrorMessage(call.result) ?? t('messages.errors.deleteFailed', 'Failed to delete message.'))
+          }
+        },
+        context: { resourceKind: 'message', messageId: id, action: 'delete', retryLastMutation },
+        mutationPayload: { messageId: id, action: 'delete' },
       })
-      if (!call.ok) {
-        throw new Error(toErrorMessage(call.result) ?? t('messages.errors.deleteFailed', 'Failed to delete message.'))
-      }
       flash(t('messages.flash.deleted', 'Message deleted.'), 'success')
       onDeleted()
     } catch (err) {
@@ -103,7 +127,7 @@ export function useMessageDetailsActions({
     } finally {
       setUpdatingState(false)
     }
-  }, [id, onDeleted, t])
+  }, [id, onDeleted, retryLastMutation, runMutation, t])
 
   const runConversationAction = React.useCallback(async (
     action: ConversationActionKind,
@@ -117,13 +141,19 @@ export function useMessageDetailsActions({
   ) => {
     setActiveConversationAction(action)
     try {
-      const call = await apiCall<{ ok?: boolean; affectedCount?: number }>(options.url, { method: options.method })
-      if (!call.ok) {
-        throw new Error(
-          toErrorMessage(call.result)
-          ?? t('messages.errors.conversationActionFailed', 'Failed to update conversation.'),
-        )
-      }
+      await runMutation({
+        operation: async () => {
+          const call = await apiCall<{ ok?: boolean; affectedCount?: number }>(options.url, { method: options.method })
+          if (!call.ok) {
+            throw new Error(
+              toErrorMessage(call.result)
+              ?? t('messages.errors.conversationActionFailed', 'Failed to update conversation.'),
+            )
+          }
+        },
+        context: { resourceKind: 'conversation', messageId: id, action, retryLastMutation },
+        mutationPayload: { messageId: id, action, url: options.url, method: options.method },
+      })
 
       flash(options.successMessage, 'success')
 
@@ -147,7 +177,7 @@ export function useMessageDetailsActions({
     } finally {
       setActiveConversationAction(null)
     }
-  }, [detailQuery, refreshDetailWithoutAutoMarkRead, t])
+  }, [detailQuery, id, refreshDetailWithoutAutoMarkRead, retryLastMutation, runMutation, t])
 
   const archiveConversation = React.useCallback(async (messageId?: string) => {
     const targetMessageId = messageId ?? id
@@ -194,21 +224,29 @@ export function useMessageDetailsActions({
   const executeAction = React.useCallback(async (action: MessageAction, payload?: Record<string, unknown>) => {
     setExecutingActionId(action.id)
     try {
-      const call = await apiCall<ActionResult>(
-        `/api/messages/${encodeURIComponent(id)}/actions/${encodeURIComponent(action.id)}`,
-        {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload ?? {}),
+      const call = await runMutation({
+        operation: async () => {
+          const result = await apiCall<ActionResult>(
+            `/api/messages/${encodeURIComponent(id)}/actions/${encodeURIComponent(action.id)}`,
+            {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(payload ?? {}),
+            },
+          )
+
+          if (!result.ok) {
+            throw new Error(
+              toErrorMessage(result.result)
+              ?? t('messages.errors.actionFailed', 'Failed to execute action.'),
+            )
+          }
+
+          return result
         },
-      )
-
-      if (!call.ok) {
-        throw new Error(
-          toErrorMessage(call.result)
-          ?? t('messages.errors.actionFailed', 'Failed to execute action.'),
-        )
-      }
+        context: { resourceKind: 'message', messageId: id, action: 'execute-action', retryLastMutation },
+        mutationPayload: { messageId: id, action: 'execute-action', actionId: action.id },
+      })
 
       flash(t('messages.flash.actionSuccess', 'Action completed.'), 'success')
 
@@ -233,7 +271,7 @@ export function useMessageDetailsActions({
     } finally {
       setExecutingActionId(null)
     }
-  }, [detailQuery, id, t])
+  }, [detailQuery, id, retryLastMutation, runMutation, t])
 
   const handleExecuteAction = React.useCallback(async (action: MessageAction, payload?: Record<string, unknown>) => {
     if (executingActionId || detail?.actionTaken) return