@open-mercato/core 0.6.6-develop.6089.1.a7ed560528 → 0.6.6-develop.6121.1.5797a901b3

package/src/modules/messages/commands/actions.ts

@@ -15,6 +15,13 @@ import {
 import { getMessageType } from '../lib/message-types-registry'
 import { assertOrganizationAccess, type MessageScopeInput } from './shared'
 
+const actionStateSnapshotSchema = z.object({
+  actionTaken: z.string().nullable(),
+  actionTakenByUserId: z.string().nullable(),
+  actionTakenAt: z.string().nullable(),
+  actionResult: z.record(z.string(), z.unknown()).nullable(),
+})
+
 const recordTerminalActionSchema = z.object({
   messageId: z.string().uuid(),
   actionId: z.string().min(1),
@@ -22,6 +29,10 @@ const recordTerminalActionSchema = z.object({
   tenantId: z.string().uuid(),
   organizationId: z.string().uuid().nullable(),
   userId: z.string().uuid(),
+  // Optional pre-claim snapshot supplied by `messages.actions.execute` so the
+  // undo log records the true (un-taken) state even though the terminal action
+  // was atomically claimed before this finalizer runs.
+  previousState: actionStateSnapshotSchema.optional(),
 })
 
 type RecordTerminalActionInput = z.infer<typeof recordTerminalActionSchema>
@@ -121,12 +132,35 @@ const recordTerminalActionCommand: CommandHandler<unknown, { ok: true }> = {
     const input = recordTerminalActionSchema.parse(rawInput)
     const em = (ctx.container.resolve('em') as EntityManager).fork()
     const message = await requireActionTarget(em, input)
-    if (message.actionTaken) {
-      throw new Error('Action already taken')
+    const claimedByCaller =
+      message.actionTaken === input.actionId && message.actionTakenByUserId === input.userId
+    if (!claimedByCaller) {
+      if (message.actionTaken) {
+        throw new Error('Action already taken')
+      }
+      // Atomic compare-and-set: only one concurrent request transitions the
+      // message out of the un-taken state. nativeUpdate runs as a single
+      // `UPDATE ... WHERE action_taken IS NULL` so the loser matches 0 rows.
+      const claimedRows = await em.nativeUpdate(
+        Message,
+        { id: input.messageId, tenantId: input.tenantId, actionTaken: null, deletedAt: null },
+        {
+          actionTaken: input.actionId,
+          actionTakenByUserId: input.userId,
+          actionTakenAt: new Date(),
+        },
+      )
+      if (claimedRows === 0) {
+        throw new Error('Action already taken')
+      }
+      message.actionTaken = input.actionId
+      message.actionTakenByUserId = input.userId
+    }
+    if (!message.actionTakenAt) {
+      message.actionTakenAt = new Date()
     }
-    message.actionTaken = input.actionId
-    message.actionTakenByUserId = input.userId
-    message.actionTakenAt = new Date()
+    // action_result is an encrypted column, so it must be written through the
+    // flush path (the encryption subscriber) rather than nativeUpdate.
     message.actionResult = input.result
     await em.flush()
     return { ok: true }
@@ -139,6 +173,13 @@ const recordTerminalActionCommand: CommandHandler<unknown, { ok: true }> = {
   },
   buildLog: async ({ input, snapshots }) => {
     const parsed = recordTerminalActionSchema.parse(input)
+    // When the action was pre-claimed by `messages.actions.execute`, the
+    // prepare-captured snapshot already reflects the claimed state, so prefer
+    // the explicit pre-claim snapshot for the undo baseline.
+    const before =
+      (parsed.previousState as ActionStateSnapshot | undefined) ??
+      (snapshots.before as ActionStateSnapshot | undefined) ??
+      null
     return {
       actionLabel: 'Execute message terminal action',
       resourceKind: 'messages.message',
@@ -147,11 +188,11 @@ const recordTerminalActionCommand: CommandHandler<unknown, { ok: true }> = {
       organizationId: parsed.organizationId,
       payload: {
         undo: {
-          before: (snapshots.before as ActionStateSnapshot | undefined) ?? null,
+          before,
           after: (snapshots.after as ActionStateSnapshot | undefined) ?? null,
         } satisfies UndoPayload<ActionStateSnapshot>,
       },
-      snapshotBefore: snapshots.before ?? null,
+      snapshotBefore: before,
       snapshotAfter: snapshots.after ?? null,
     }
   },
@@ -209,6 +250,52 @@ const executeActionCommand: CommandHandler<
       }
     }
 
+    // Capture the un-taken state for the undo log before reserving the action.
+    const previousState = snapshotActionState(message)
+    let claimedTerminal = false
+    const releaseTerminalClaim = async () => {
+      if (!claimedTerminal) return
+      claimedTerminal = false
+      await em.nativeUpdate(
+        Message,
+        {
+          id: message.id,
+          tenantId: input.tenantId,
+          actionTaken: action.id,
+          actionTakenByUserId: input.userId,
+        },
+        { actionTaken: null, actionTakenByUserId: null, actionTakenAt: null },
+      )
+    }
+
+    if (shouldRecordActionTaken) {
+      // Atomically reserve the terminal action BEFORE running the target
+      // command so concurrent requests cannot both execute it. The losing
+      // request matches 0 rows and surfaces the existing 409 response.
+      const claimedRows = await em.nativeUpdate(
+        Message,
+        { id: message.id, tenantId: input.tenantId, actionTaken: null, deletedAt: null },
+        {
+          actionTaken: action.id,
+          actionTakenByUserId: input.userId,
+          actionTakenAt: new Date(),
+        },
+      )
+      if (claimedRows === 0) {
+        const current = await findOneWithDecryption(
+          em,
+          Message,
+          { id: message.id, tenantId: input.tenantId, deletedAt: null },
+          undefined,
+          { tenantId: input.tenantId, organizationId: input.organizationId },
+        )
+        throw Object.assign(new Error('Action already taken'), {
+          actionTaken: current?.actionTaken ?? message.actionTaken ?? action.id,
+        })
+      }
+      claimedTerminal = true
+    }
+
     const commandBus = ctx.container.resolve('commandBus') as {
       execute: (
         commandId: string,
@@ -263,6 +350,9 @@ const executeActionCommand: CommandHandler<
         operationLogEntry = commandResult.logEntry ?? null
       } catch (err) {
         console.error('[messages] executeActionCommand sub-command failed', err)
+        // The target command never completed — release the reservation so the
+        // action stays retryable, matching the pre-claim failure semantics.
+        await releaseTerminalClaim()
         throw new Error('Action failed')
       }
     } else if (action.href) {
@@ -272,10 +362,12 @@ const executeActionCommand: CommandHandler<
         userId: input.userId,
       })
       if (!safeRedirect) {
+        await releaseTerminalClaim()
         throw new Error('Action has an unsafe redirect target')
       }
       result = { redirect: safeRedirect }
     } else {
+      await releaseTerminalClaim()
       throw new Error('Action has no executable target')
     }
 
@@ -288,6 +380,7 @@ const executeActionCommand: CommandHandler<
           tenantId: input.tenantId,
           organizationId: input.organizationId,
           userId: input.userId,
+          previousState,
         },
         ctx: {
           container: ctx.container,

package/src/modules/perspectives/api/[tableId]/[perspectiveId]/route.ts

@@ -2,6 +2,10 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { deleteUserPerspective } from '@open-mercato/core/modules/perspectives/services/perspectiveService'
 import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { perspectivesTag, perspectivesErrorSchema, perspectivesSuccessSchema } from '../../openapi'
@@ -40,7 +44,22 @@ export async function DELETE(req: Request, ctx: { params: { tableId: string; per
     }
   })()
 
-  await deleteUserPerspective(em, cache, {
+  const guardResult = await validateCrudMutationGuard(container, {
+    tenantId: auth.tenantId ?? '',
+    organizationId: auth.orgId ?? null,
+    userId: auth.sub,
+    resourceKind: 'perspectives.perspective',
+    resourceId: perspectiveId,
+    operation: 'delete',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+    mutationPayload: { tableId, perspectiveId },
+  })
+  if (guardResult && !guardResult.ok) {
+    return NextResponse.json(guardResult.body, { status: guardResult.status })
+  }
+
+  const deleted = await deleteUserPerspective(em, cache, {
     scope: {
       userId: auth.sub,
       tenantId: auth.tenantId ?? null,
@@ -50,6 +69,20 @@ export async function DELETE(req: Request, ctx: { params: { tableId: string; per
     perspectiveId,
   })
 
+  if (deleted && guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(container, {
+      tenantId: auth.tenantId ?? '',
+      organizationId: auth.orgId ?? null,
+      userId: auth.sub,
+      resourceKind: 'perspectives.perspective',
+      resourceId: perspectiveId,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      metadata: guardResult.metadata ?? null,
+    })
+  }
+
   return NextResponse.json({ success: true })
 }
 

package/src/modules/perspectives/api/[tableId]/roles/[roleId]/route.ts

@@ -2,6 +2,10 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { clearRolePerspectives } from '@open-mercato/core/modules/perspectives/services/perspectiveService'
 import { Role } from '@open-mercato/core/modules/auth/data/entities'
 import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
@@ -48,13 +52,42 @@ export async function DELETE(req: Request, ctx: { params: { tableId: string; rol
   const role = await em.findOne(Role, { id: roleId, deletedAt: null, ...(scope as any) } as any)
   if (!role) return NextResponse.json({ error: 'Role not found' }, { status: 404 })
 
-  await clearRolePerspectives(em, cache, {
+  const guardResult = await validateCrudMutationGuard(container, {
+    tenantId: auth.tenantId ?? '',
+    organizationId: auth.orgId ?? null,
+    userId: auth.sub,
+    resourceKind: 'perspectives.role_perspective',
+    resourceId: roleId,
+    operation: 'delete',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+    mutationPayload: { tableId, roleId },
+  })
+  if (guardResult && !guardResult.ok) {
+    return NextResponse.json(guardResult.body, { status: guardResult.status })
+  }
+
+  const clearedCount = await clearRolePerspectives(em, cache, {
     tableId,
     tenantId: auth.tenantId ?? null,
     organizationId: auth.orgId ?? null,
     roleIds: [roleId],
   })
 
+  if (clearedCount > 0 && guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(container, {
+      tenantId: auth.tenantId ?? '',
+      organizationId: auth.orgId ?? null,
+      userId: auth.sub,
+      resourceKind: 'perspectives.role_perspective',
+      resourceId: roleId,
+      operation: 'delete',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      metadata: guardResult.metadata ?? null,
+    })
+  }
+
   return NextResponse.json({ success: true })
 }
 

package/src/modules/perspectives/api/[tableId]/route.ts

@@ -4,6 +4,10 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { perspectiveSaveSchema } from '@open-mercato/core/modules/perspectives/data/validators'
 import {
   loadPerspectivesState,
@@ -168,6 +172,7 @@ export async function POST(req: Request, ctx: { params: { tableId: string } }) {
   const applyToRoles = Array.from(new Set(parsed.data.applyToRoles ?? [])).filter((id) => id.trim().length > 0)
   const clearRoleIds = Array.from(new Set(parsed.data.clearRoleIds ?? [])).filter((id) => id.trim().length > 0)
   const hasRoleOps = applyToRoles.length > 0 || clearRoleIds.length > 0
+  const targetRoleIds = Array.from(new Set([...applyToRoles, ...clearRoleIds]))
 
   if (hasRoleOps) {
     const canApplyToRoles = await rbac.userHasAllFeatures?.(
@@ -183,7 +188,6 @@ export async function POST(req: Request, ctx: { params: { tableId: string } }) {
     const roleScope = auth.tenantId
       ? { $or: [{ tenantId: auth.tenantId }, { tenantId: null }] }
       : { tenantId: null }
-    const targetRoleIds = Array.from(new Set([...applyToRoles, ...clearRoleIds]))
     const roles = await em.find(Role, {
       id: { $in: targetRoleIds as any },
       ...(roleScope as any),
@@ -197,44 +201,86 @@ export async function POST(req: Request, ctx: { params: { tableId: string } }) {
     }
   }
 
+  const guardResourceId = parsed.data.perspectiveId ?? tableId
+  const guardResult = await validateCrudMutationGuard(container, {
+    tenantId: auth.tenantId ?? '',
+    organizationId: auth.orgId ?? null,
+    userId: auth.sub,
+    resourceKind: 'perspectives.perspective',
+    resourceId: guardResourceId,
+    operation: 'custom',
+    requestMethod: req.method,
+    requestHeaders: req.headers,
+    mutationPayload: { ...parsed.data, tableId },
+  })
+  if (guardResult && !guardResult.ok) {
+    return NextResponse.json(guardResult.body, { status: guardResult.status })
+  }
+
+  let roleGuardResult: Awaited<ReturnType<typeof validateCrudMutationGuard>> | null = null
+  if (hasRoleOps) {
+    roleGuardResult = await validateCrudMutationGuard(container, {
+      tenantId: auth.tenantId ?? '',
+      organizationId: auth.orgId ?? null,
+      userId: auth.sub,
+      resourceKind: 'perspectives.role_perspective',
+      resourceId: targetRoleIds.join(','),
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      mutationPayload: {
+        tableId,
+        applyToRoles,
+        clearRoleIds,
+        name: parsed.data.name,
+        settings: parsed.data.settings,
+        setRoleDefault: parsed.data.setRoleDefault ?? false,
+      },
+    })
+  }
+  if (roleGuardResult && !roleGuardResult.ok) {
+    return NextResponse.json(roleGuardResult.body, { status: roleGuardResult.status })
+  }
+
   let saved: Awaited<ReturnType<typeof saveUserPerspective>> | null = null
   let updatedRolePerspectives: Awaited<ReturnType<typeof saveRolePerspectives>> | null = null
+  let clearedRolePerspectiveCount = 0
 
   try {
     await withAtomicFlush(em, [
-    async () => {
-      saved = await saveUserPerspective(em, cache, {
-        scope,
-        tableId,
-        input: parsed.data,
-        request: req,
-      })
-    },
-    async () => {
-      if (applyToRoles.length) {
-        updatedRolePerspectives = await saveRolePerspectives(em, cache, {
-          tableId,
-          tenantId: auth.tenantId ?? null,
-          organizationId: auth.orgId ?? null,
-          input: {
-            roleIds: applyToRoles,
-            name: parsed.data.name,
-            settings: parsed.data.settings,
-            setDefault: parsed.data.setRoleDefault ?? false,
-          },
-        })
-      }
-    },
-    async () => {
-      if (clearRoleIds.length) {
-        await clearRolePerspectives(em, cache, {
+      async () => {
+        saved = await saveUserPerspective(em, cache, {
+          scope,
           tableId,
-          tenantId: auth.tenantId ?? null,
-          organizationId: auth.orgId ?? null,
-          roleIds: clearRoleIds,
+          input: parsed.data,
+          request: req,
         })
-      }
-    },
+      },
+      async () => {
+        if (applyToRoles.length) {
+          updatedRolePerspectives = await saveRolePerspectives(em, cache, {
+            tableId,
+            tenantId: auth.tenantId ?? null,
+            organizationId: auth.orgId ?? null,
+            input: {
+              roleIds: applyToRoles,
+              name: parsed.data.name,
+              settings: parsed.data.settings,
+              setDefault: parsed.data.setRoleDefault ?? false,
+            },
+          })
+        }
+      },
+      async () => {
+        if (clearRoleIds.length) {
+          clearedRolePerspectiveCount = await clearRolePerspectives(em, cache, {
+            tableId,
+            tenantId: auth.tenantId ?? null,
+            organizationId: auth.orgId ?? null,
+            roleIds: clearRoleIds,
+          })
+        }
+      },
     ], { transaction: true })
   } catch (err) {
     if (isCrudHttpError(err)) {
@@ -243,6 +289,35 @@ export async function POST(req: Request, ctx: { params: { tableId: string } }) {
     throw err
   }
 
+  if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(container, {
+      tenantId: auth.tenantId ?? '',
+      organizationId: auth.orgId ?? null,
+      userId: auth.sub,
+      resourceKind: 'perspectives.perspective',
+      resourceId: guardResourceId,
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      metadata: guardResult.metadata ?? null,
+    })
+  }
+
+  const didWriteRolePerspectives = applyToRoles.length > 0 || clearedRolePerspectiveCount > 0
+  if (didWriteRolePerspectives && roleGuardResult?.ok && roleGuardResult.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(container, {
+      tenantId: auth.tenantId ?? '',
+      organizationId: auth.orgId ?? null,
+      userId: auth.sub,
+      resourceKind: 'perspectives.role_perspective',
+      resourceId: targetRoleIds.join(','),
+      operation: 'custom',
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+      metadata: roleGuardResult.metadata ?? null,
+    })
+  }
+
   return NextResponse.json({
     perspective: saved,
     rolePerspectives: updatedRolePerspectives ?? [],

package/src/modules/perspectives/services/perspectiveService.ts

@@ -309,7 +309,7 @@ export async function deleteUserPerspective(
   em: EntityManager,
   cache: CacheStrategy | null | undefined,
   options: { scope: PerspectiveScope; tableId: string; perspectiveId: string },
-): Promise<void> {
+): Promise<boolean> {
   const { scope, tableId, perspectiveId } = options
   const tenantId = scope.tenantId ?? null
   const organizationId = scope.organizationId ?? null
@@ -322,7 +322,7 @@ export async function deleteUserPerspective(
     tableId,
     deletedAt: null,
   })
-  if (!existing) return
+  if (!existing) return false
 
   existing.deletedAt = new Date()
   existing.isDefault = false
@@ -331,6 +331,8 @@ export async function deleteUserPerspective(
   if (cache?.deleteByTags) {
     await cache.deleteByTags([userTag(scope, tableId)])
   }
+
+  return true
 }
 
 export async function saveRolePerspectives(
@@ -430,13 +432,13 @@ export async function clearRolePerspectives(
     organizationId?: string | null
     roleIds: string[]
   },
-): Promise<void> {
+): Promise<number> {
   const { tableId, roleIds } = options
   const tenantId = options.tenantId ?? null
   const organizationId = options.organizationId ?? null
-  if (!roleIds.length) return
+  if (!roleIds.length) return 0
 
-  await em.nativeUpdate(
+  const affected = await em.nativeUpdate(
     RolePerspective,
     {
       roleId: { $in: roleIds as any },
@@ -452,4 +454,6 @@ export async function clearRolePerspectives(
     const tags = roleIds.map((roleId) => roleTag(roleId, tableId, tenantId))
     await cache.deleteByTags(tags)
   }
+
+  return affected
 }

package/src/modules/planner/api/access.ts

@@ -79,3 +79,12 @@ export async function assertAvailabilityWriteAccess(
   }
   return access
 }
+
+export function resolveAvailabilityActorId(auth: AuthContext): string {
+  if (auth) {
+    if (typeof auth.sub === 'string' && auth.sub.trim().length > 0) return auth.sub
+    if (typeof auth.userId === 'string' && auth.userId.trim().length > 0) return auth.userId
+    if (typeof auth.keyId === 'string' && auth.keyId.trim().length > 0) return auth.keyId
+  }
+  return 'system'
+}

package/src/modules/planner/api/availability-date-specific.ts

@@ -11,9 +11,13 @@ import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { plannerAvailabilityDateSpecificReplaceSchema } from '../data/validators'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import { PlannerAvailabilityRule } from '../data/entities'
 import { parseAvailabilityRuleWindow } from '../lib/availabilitySchedule'
-import { assertAvailabilityWriteAccess } from './access'
+import { assertAvailabilityWriteAccess, resolveAvailabilityActorId } from './access'
 
 export const metadata = {
   POST: { requireAuth: true },
@@ -93,8 +97,25 @@ export async function POST(req: Request) {
         }
       }
     }
+    const guardInput = {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      userId: resolveAvailabilityActorId(ctx.auth),
+      resourceKind: 'planner.availability',
+      resourceId: input.subjectId,
+      operation: 'custom' as const,
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    }
+    const guardResult = await validateCrudMutationGuard(ctx.container, { ...guardInput, mutationPayload: input })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
     const commandBus = ctx.container.resolve('commandBus') as CommandBus
     const { logEntry } = await commandBus.execute('planner.availability.date-specific.replace', { input, ctx })
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, { ...guardInput, metadata: guardResult.metadata ?? null })
+    }
     const response = NextResponse.json({ ok: true })
     if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
       response.headers.set(

package/src/modules/planner/api/availability-weekly.ts

@@ -9,7 +9,11 @@ import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/er
 import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { plannerAvailabilityWeeklyReplaceSchema } from '../data/validators'
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
-import { assertAvailabilityWriteAccess } from './access'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+import { assertAvailabilityWriteAccess, resolveAvailabilityActorId } from './access'
 
 export const metadata = {
   POST: { requireAuth: true },
@@ -55,8 +59,25 @@ export async function POST(req: Request) {
     const payload = await req.json().catch(() => ({}))
     const input = parseScopedCommandInput(plannerAvailabilityWeeklyReplaceSchema, payload, ctx, translate)
     await assertAvailabilityWriteAccess(ctx, { subjectType: input.subjectType, subjectId: input.subjectId }, translate)
+    const guardInput = {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      userId: resolveAvailabilityActorId(ctx.auth),
+      resourceKind: 'planner.availability',
+      resourceId: input.subjectId,
+      operation: 'custom' as const,
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    }
+    const guardResult = await validateCrudMutationGuard(ctx.container, { ...guardInput, mutationPayload: input })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
     const commandBus = ctx.container.resolve('commandBus') as CommandBus
     const { logEntry } = await commandBus.execute('planner.availability.weekly.replace', { input, ctx })
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, { ...guardInput, metadata: guardResult.metadata ?? null })
+    }
     const response = NextResponse.json({ ok: true })
     if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
       response.headers.set(

package/src/modules/resources/api/resources/tags/assign/route.ts

@@ -9,6 +9,10 @@ import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/er
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
 import {
   resourcesResourceTagAssignmentSchema,
   type ResourcesResourceTagAssignmentInput,
@@ -37,16 +41,54 @@ async function buildContext(
   return { ctx, translate }
 }
 
+function resolveActorId(ctx: CommandRuntimeContext): string {
+  const auth = ctx.auth
+  if (auth && typeof auth.sub === 'string' && auth.sub.trim().length > 0) return auth.sub
+  if (auth && typeof auth.userId === 'string' && auth.userId.trim().length > 0) return auth.userId
+  if (auth && typeof auth.keyId === 'string' && auth.keyId.trim().length > 0) return auth.keyId
+  return 'system'
+}
+
 export async function POST(req: Request) {
   try {
     const { ctx, translate } = await buildContext(req)
     const body = await req.json().catch(() => ({}))
     const input = parseScopedCommandInput(resourcesResourceTagAssignmentSchema, body, ctx, translate)
+    const actorId = resolveActorId(ctx)
+    const guardResult = await validateCrudMutationGuard(ctx.container, {
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      userId: actorId,
+      resourceKind: 'resources.resourceTagAssignment',
+      resourceId: input.resourceId,
+      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<ResourcesResourceTagAssignmentInput, { assignmentId: string }>(
       'resources.resourceTags.assign',
       { input, ctx },
     )
+    if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(ctx.container, {
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+        userId: actorId,
+        resourceKind: 'resources.resourceTagAssignment',
+        resourceId: input.resourceId,
+        operation: 'custom',
+        requestMethod: req.method,
+        requestHeaders: req.headers,
+        metadata: guardResult.metadata ?? null,
+      })
+    }
+
     const response = NextResponse.json({ id: result?.assignmentId ?? null }, { status: 201 })
     if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
       response.headers.set(