@open-mercato/core 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4544.1.71c003c861

package/src/modules/staff/commands/job-histories.ts

@@ -19,9 +19,15 @@ import {
 } from './shared'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  enforceCommandOptimisticLock,
+  enforceRecordGoneIsConflict,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-command'
 import type { CrudIndexerConfig } from '@open-mercato/shared/lib/crud/types'
 import { E } from '#generated/entities.ids.generated'
 
+const JOB_HISTORY_LOCK_RESOURCE_KIND = 'staff.jobHistory'
+
 const jobHistoryCrudIndexer: CrudIndexerConfig<StaffTeamMemberJobHistory> = {
   entityType: E.staff.staff_team_member_job_history,
 }
@@ -36,6 +42,7 @@ type JobHistorySnapshot = {
   description: string | null
   startDate: string
   endDate: string | null
+  updatedAt: string
 }
 
 type JobHistoryUndoPayload = {
@@ -56,6 +63,7 @@ async function loadJobHistorySnapshot(em: EntityManager, id: string): Promise<Jo
     description: record.description ?? null,
     startDate: record.startDate.toISOString(),
     endDate: record.endDate ? record.endDate.toISOString() : null,
+    updatedAt: record.updatedAt.toISOString(),
   }
 }
 
@@ -149,9 +157,24 @@ const updateJobHistoryCommand: CommandHandler<StaffTeamMemberJobHistoryUpdateInp
     const parsed = staffTeamMemberJobHistoryUpdateSchema.parse(rawInput)
     const em = (ctx.container.resolve('em') as EntityManager).fork()
     const record = await em.findOne(StaffTeamMemberJobHistory, { id: parsed.id })
-    if (!record) throw new CrudHttpError(404, { error: 'Job history entry not found' })
+    if (!record) {
+      enforceRecordGoneIsConflict({
+        resourceKind: JOB_HISTORY_LOCK_RESOURCE_KIND,
+        resourceId: parsed.id,
+        expected: parsed.updatedAt ?? null,
+        request: ctx.request ?? null,
+      })
+      throw new CrudHttpError(404, { error: 'Job history entry not found' })
+    }
     ensureTenantScope(ctx, record.tenantId)
     ensureOrganizationScope(ctx, record.organizationId)
+    enforceCommandOptimisticLock({
+      resourceKind: JOB_HISTORY_LOCK_RESOURCE_KIND,
+      resourceId: record.id,
+      current: record.updatedAt ?? null,
+      expected: parsed.updatedAt ?? null,
+      request: ctx.request ?? null,
+    })
 
     if (parsed.entityId !== undefined) {
       const member = await requireTeamMember(em, parsed.entityId, 'Team member not found')
@@ -268,7 +291,7 @@ const updateJobHistoryCommand: CommandHandler<StaffTeamMemberJobHistoryUpdateInp
   },
 }
 
-const deleteJobHistoryCommand: CommandHandler<{ body?: Record<string, unknown>; query?: Record<string, unknown> }, { jobHistoryId: string }> =
+const deleteJobHistoryCommand: CommandHandler<{ id?: string; updatedAt?: string; body?: Record<string, unknown>; query?: Record<string, unknown> }, { jobHistoryId: string }> =
   {
     id: 'staff.team-member-job-histories.delete',
     async prepare(input, ctx) {
@@ -279,11 +302,27 @@ const deleteJobHistoryCommand: CommandHandler<{ body?: Record<string, unknown>;
     },
     async execute(input, ctx) {
       const id = requireId(input, 'Job history id required')
+      const expectedUpdatedAt = typeof input.updatedAt === 'string' ? input.updatedAt : undefined
       const em = (ctx.container.resolve('em') as EntityManager).fork()
       const record = await em.findOne(StaffTeamMemberJobHistory, { id })
-      if (!record) throw new CrudHttpError(404, { error: 'Job history entry not found' })
+      if (!record) {
+        enforceRecordGoneIsConflict({
+          resourceKind: JOB_HISTORY_LOCK_RESOURCE_KIND,
+          resourceId: id,
+          expected: expectedUpdatedAt ?? null,
+          request: ctx.request ?? null,
+        })
+        throw new CrudHttpError(404, { error: 'Job history entry not found' })
+      }
       ensureTenantScope(ctx, record.tenantId)
       ensureOrganizationScope(ctx, record.organizationId)
+      enforceCommandOptimisticLock({
+        resourceKind: JOB_HISTORY_LOCK_RESOURCE_KIND,
+        resourceId: record.id,
+        current: record.updatedAt ?? null,
+        expected: expectedUpdatedAt ?? null,
+        request: ctx.request ?? null,
+      })
       em.remove(record)
       await em.flush()
 

package/src/modules/staff/components/LeaveRequestForm.tsx

@@ -32,6 +32,7 @@ export type LeaveRequestFormValues = {
   unavailabilityReasonEntryId?: string | null
   unavailabilityReasonValue?: string | null
   note?: string | null
+  updatedAt?: string | null
 }
 
 export type LeaveRequestFormProps = {
@@ -317,6 +318,7 @@ export function LeaveRequestForm(props: LeaveRequestFormProps) {
       title={title}
       fields={fields}
       initialValues={normalizedInitialValues}
+      optimisticLockUpdatedAt={normalizedInitialValues.updatedAt}
       submitLabel={submitLabel}
       backHref={backHref}
       cancelHref={cancelHref}

package/src/modules/staff/components/TeamForm.tsx

@@ -12,6 +12,7 @@ export type TeamFormValues = {
   name: string
   description?: string | null
   isActive?: boolean
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 export type TeamFormProps = {
@@ -89,6 +90,7 @@ export function TeamForm(props: TeamFormProps) {
       groups={groups}
       entityId={E.staff.staff_team}
       initialValues={initialValues}
+      optimisticLockUpdatedAt={initialValues.updatedAt}
       onSubmit={onSubmit}
       onDelete={onDelete}
       isLoading={isLoading}

package/src/modules/staff/components/TeamMemberForm.tsx

@@ -32,6 +32,7 @@ export type TeamMemberFormValues = {
   roleIds?: string[]
   tags?: string[]
   isActive?: boolean
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 export type TeamMemberFormProps = {
@@ -515,6 +516,7 @@ export function TeamMemberForm(props: TeamMemberFormProps) {
       groups={groups}
       entityId={E.staff.staff_team_member}
       initialValues={initialValues}
+      optimisticLockUpdatedAt={initialValues.updatedAt}
       onSubmit={onSubmit}
       onDelete={onDelete}
       isLoading={isLoading}

package/src/modules/staff/components/TeamRoleForm.tsx

@@ -14,6 +14,7 @@ export type TeamRoleFormValues = {
   name: string
   description?: string | null
   appearance?: { icon?: string | null; color?: string | null }
+  updatedAt?: string | null
 } & Record<string, unknown>
 
 export type TeamRoleOption = {
@@ -152,6 +153,7 @@ export function TeamRoleForm(props: TeamRoleFormProps) {
       groups={groups}
       entityId={E.staff.staff_team_role}
       initialValues={initialValues}
+      optimisticLockUpdatedAt={initialValues.updatedAt}
       onSubmit={onSubmit}
       onDelete={onDelete}
       isLoading={isLoading}

package/src/modules/staff/components/detail/JobHistorySection.tsx

@@ -9,6 +9,7 @@ import { LoadingMessage, ErrorMessage, TabEmptyState } from '@open-mercato/ui/ba
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 
@@ -19,6 +20,7 @@ type JobHistoryRecord = {
   description: string | null
   startDate: string | null
   endDate: string | null
+  updatedAt: string | undefined
 }
 
 type JobHistoryResponse = {
@@ -54,6 +56,7 @@ export function JobHistorySection({ memberId }: { memberId: string | null }) {
     errorLoad: t('staff.teamMembers.detail.jobHistory.errorLoad', 'Failed to load job history.'),
     errorSave: t('staff.teamMembers.detail.jobHistory.errorSave', 'Failed to save job history.'),
     errorDelete: t('staff.teamMembers.detail.jobHistory.errorDelete', 'Failed to delete job history.'),
+    conflict: t('staff.teamMembers.detail.jobHistory.conflict', 'This record was modified by someone else. Refresh and try again.'),
     loading: t('staff.teamMembers.detail.jobHistory.loading', 'Loading job history...'),
     saved: t('staff.teamMembers.detail.jobHistory.saved', 'Job history saved.'),
     updated: t('staff.teamMembers.detail.jobHistory.updated', 'Job history updated.'),
@@ -137,7 +140,11 @@ export function JobHistorySection({ memberId }: { memberId: string | null }) {
     if (!memberId) return
     const payload = buildJobHistoryPayload(values)
     if (dialogMode === 'edit' && activeRecord) {
-      await updateCrud('staff/job-histories', { id: activeRecord.id, ...payload }, { errorMessage: labels.errorSave })
+      // Let any error (including the optimistic-lock 409) propagate so the
+      // enclosing CrudForm surfaces the unified "Record changed" conflict bar
+      // via surfaceRecordConflict. Catching it here and routing it to a flash
+      // toast would hide the conflict bar (see TC-LOCK-OSS-036).
+      await updateCrud('staff/job-histories', { id: activeRecord.id, updatedAt: activeRecord.updatedAt, ...payload }, { errorMessage: labels.errorSave })
       flash(labels.updated, 'success')
     } else {
       await createCrud('staff/job-histories', { entityId: memberId, ...payload }, { errorMessage: labels.errorSave })
@@ -145,7 +152,7 @@ export function JobHistorySection({ memberId }: { memberId: string | null }) {
     }
     closeDialog()
     setReloadToken((prev) => prev + 1)
-  }, [activeRecord, closeDialog, dialogMode, labels.errorSave, labels.saved, labels.updated, memberId])
+  }, [activeRecord, closeDialog, dialogMode, labels.conflict, labels.errorSave, labels.saved, labels.updated, memberId])
 
   const handleDelete = React.useCallback(async (record: JobHistoryRecord) => {
     const confirmed = await confirmDialog({
@@ -153,10 +160,19 @@ export function JobHistorySection({ memberId }: { memberId: string | null }) {
       variant: 'destructive',
     })
     if (!confirmed) return
-    await deleteCrud('staff/job-histories', { id: record.id, errorMessage: labels.errorDelete })
-    flash(labels.deleted, 'success')
-    setReloadToken((prev) => prev + 1)
-  }, [labels.deleteConfirm, labels.deleted, labels.errorDelete, confirmDialog])
+    try {
+      await deleteCrud('staff/job-histories', {
+        id: record.id,
+        body: { id: record.id, updatedAt: record.updatedAt },
+        errorMessage: labels.errorDelete,
+      })
+      flash(labels.deleted, 'success')
+      setReloadToken((prev) => prev + 1)
+    } catch (error) {
+      if (surfaceRecordConflict(error, t)) return
+      flash(labels.errorDelete, 'error')
+    }
+  }, [labels.deleteConfirm, labels.deleted, labels.errorDelete, confirmDialog, t])
 
   const dialogTitle = dialogMode === 'edit' ? labels.edit : labels.add
 
@@ -240,6 +256,7 @@ export function JobHistorySection({ memberId }: { memberId: string | null }) {
           <CrudForm<JobHistoryFormValues>
             fields={fields}
             initialValues={initialValues}
+            optimisticLockUpdatedAt={activeRecord?.updatedAt ?? null}
             onSubmit={handleSubmit}
             submitLabel={dialogMode === 'edit' ? labels.update : labels.save}
             extraActions={(
@@ -290,6 +307,11 @@ function normalizeJobHistoryItems(items?: Record<string, unknown>[]): JobHistory
           : typeof record.endDate === 'string'
             ? record.endDate
             : null,
+        updatedAt: typeof record.updated_at === 'string'
+          ? record.updated_at
+          : typeof record.updatedAt === 'string'
+            ? record.updatedAt
+            : undefined,
       }
     })
     .filter((value): value is JobHistoryRecord => value !== null)

package/src/modules/staff/data/validators.ts

@@ -10,6 +10,11 @@ const projectColorSchema = z
 
 const tagsSchema = z.array(z.string().min(1)).optional().default([])
 
+export const optimisticUpdatedAtSchema = z.string().refine(
+  (value) => !Number.isNaN(new Date(value).getTime()),
+  { message: 'Invalid datetime' },
+)
+
 const scopedCreateFields = {
   tenantId: z.string().uuid(),
   organizationId: z.string().uuid(),
@@ -121,6 +126,7 @@ export const staffTeamMemberJobHistoryCreateSchema = z.object({
 export const staffTeamMemberJobHistoryUpdateSchema = z
   .object({
     id: z.string().uuid(),
+    updatedAt: optimisticUpdatedAtSchema.optional(),
   })
   .merge(staffTeamMemberJobHistoryCreateSchema.partial())
 

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

@@ -702,6 +702,7 @@
   "staff.teamMembers.detail.inline.urlInvalid": "Geben Sie eine gültige URL ein",
   "staff.teamMembers.detail.jobHistory.add": "Job hinzufügen",
   "staff.teamMembers.detail.jobHistory.cancel": "Abbrechen",
+  "staff.teamMembers.detail.jobHistory.conflict": "Dieser Datensatz wurde von jemand anderem geändert. Bitte aktualisieren und erneut versuchen.",
   "staff.teamMembers.detail.jobHistory.deleteConfirm": "Diesen Eintrag im Beschäftigungsverlauf löschen?",
   "staff.teamMembers.detail.jobHistory.deleted": "Beschäftigungsverlauf gelöscht.",
   "staff.teamMembers.detail.jobHistory.edit": "Job bearbeiten",

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

@@ -702,6 +702,7 @@
   "staff.teamMembers.detail.inline.urlInvalid": "Enter a valid URL",
   "staff.teamMembers.detail.jobHistory.add": "Add job",
   "staff.teamMembers.detail.jobHistory.cancel": "Cancel",
+  "staff.teamMembers.detail.jobHistory.conflict": "This record was modified by someone else. Refresh and try again.",
   "staff.teamMembers.detail.jobHistory.deleteConfirm": "Delete this job history entry?",
   "staff.teamMembers.detail.jobHistory.deleted": "Job history deleted.",
   "staff.teamMembers.detail.jobHistory.edit": "Edit job",

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

@@ -702,6 +702,7 @@
   "staff.teamMembers.detail.inline.urlInvalid": "Introduce una URL válida",
   "staff.teamMembers.detail.jobHistory.add": "Agregar empleo",
   "staff.teamMembers.detail.jobHistory.cancel": "Cancelar",
+  "staff.teamMembers.detail.jobHistory.conflict": "Otro usuario modificó este registro. Actualiza e inténtalo de nuevo.",
   "staff.teamMembers.detail.jobHistory.deleteConfirm": "¿Eliminar esta entrada de historial laboral?",
   "staff.teamMembers.detail.jobHistory.deleted": "Historial laboral eliminado.",
   "staff.teamMembers.detail.jobHistory.edit": "Editar empleo",

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

@@ -702,6 +702,7 @@
   "staff.teamMembers.detail.inline.urlInvalid": "Wprowadź prawidłowy adres URL",
   "staff.teamMembers.detail.jobHistory.add": "Dodaj stanowisko",
   "staff.teamMembers.detail.jobHistory.cancel": "Anuluj",
+  "staff.teamMembers.detail.jobHistory.conflict": "Ten rekord został zmieniony przez inną osobę. Odśwież i spróbuj ponownie.",
   "staff.teamMembers.detail.jobHistory.deleteConfirm": "Usunąć ten wpis historii zatrudnienia?",
   "staff.teamMembers.detail.jobHistory.deleted": "Wpis historii zatrudnienia usunięty.",
   "staff.teamMembers.detail.jobHistory.edit": "Edytuj stanowisko",

package/src/modules/staff/lib/leaveRequestHelpers.ts

@@ -18,6 +18,8 @@ export type LeaveRequestRecord = {
   decision_comment?: string | null
   decidedAt?: string | null
   decided_at?: string | null
+  updatedAt?: string | null
+  updated_at?: string | null
 } & Record<string, unknown>
 
 export type NormalizedLeaveRequest = {
@@ -33,6 +35,7 @@ export type NormalizedLeaveRequest = {
   note: string | null
   decisionComment: string | null
   decidedAt: string | null
+  updatedAt: string | null
 } & Record<string, unknown>
 
 export function normalizeLeaveRequest(record: LeaveRequestRecord): NormalizedLeaveRequest {
@@ -50,6 +53,7 @@ export function normalizeLeaveRequest(record: LeaveRequestRecord): NormalizedLea
     note: record.note ?? null,
     decisionComment: record.decisionComment ?? record.decision_comment ?? null,
     decidedAt: record.decidedAt ?? record.decided_at ?? null,
+    updatedAt: record.updatedAt ?? record.updated_at ?? null,
   }
 }
 

package/src/modules/translations/components/TranslationManager.tsx

@@ -7,7 +7,8 @@ import { Input } from '@open-mercato/ui/primitives/input'
 import { ComboboxInput } from '@open-mercato/ui/backend/inputs'
 import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
-import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { useCustomFieldDefs } from '@open-mercato/ui/backend/utils/customFieldDefs'
 import { Save, Plus, X } from 'lucide-react'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
@@ -238,13 +239,16 @@ export function TranslationManager({
         console.warn('[translations] Save skipped: payload is empty — no locale contains any non-empty field')
         throw new Error(t('translations.manager.errors.nothingToSave', 'Nothing to save — enter a translation first'))
       }
-      const res = await apiCall(
-        `/api/translations/${encodeURIComponent(entityType)}/${encodeURIComponent(recordId)}`,
-        {
-          method: 'PUT',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify(body),
-        },
+      const res = await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(translationData?.updatedAt),
+        () => apiCall(
+          `/api/translations/${encodeURIComponent(entityType)}/${encodeURIComponent(recordId)}`,
+          {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+          },
+        ),
       )
       if (!res.ok) {
         throw new Error(t('translations.manager.errors.save', 'Failed to save translations'))
@@ -539,6 +543,7 @@ export function LocaleManager() {
 
   const mutation = useMutation({
     mutationFn: async (updatedLocales: string[]) => {
+      // optimistic-lock-exempt: single-row tenant supported-locales settings list — no per-record version / concurrent record edit
       const res = await apiCall<{ locales: string[] }>('/api/translations/locales', {
         method: 'PUT',
         headers: { 'content-type': 'application/json' },

package/src/modules/workflows/api/definitions/[id]/route.ts

@@ -21,6 +21,21 @@ import {
 import { serializeWorkflowDefinition, serializeCodeWorkflowDefinition } from '../serialize'
 import { invalidateTriggerCache } from '../../../lib/event-trigger-service'
 import { getCodeWorkflow } from '../../../lib/code-registry'
+import { createGenericOptimisticLockReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { registerOptimisticLockReaderIfAbsent } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
+import { validateCrudMutationGuard, runCrudMutationGuardAfterSuccess } from '@open-mercato/shared/lib/crud/mutation-guard'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+
+registerOptimisticLockReaderIfAbsent({
+  'workflows.definition': createGenericOptimisticLockReader({
+    entity: WorkflowDefinition,
+    idField: 'id',
+    tenantField: 'tenantId',
+    orgField: 'organizationId',
+    softDeleteField: 'deletedAt',
+  }),
+})
 
 export const metadata = {
   requireAuth: true,
@@ -151,6 +166,20 @@ export async function PUT(
     }
 
     const input: UpdateWorkflowDefinitionApiInput = validation.data
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId: tenantId ?? '',
+      organizationId: organizationId ?? null,
+      userId: auth.sub ?? '',
+      resourceKind: 'workflows.definition',
+      resourceId: params.id,
+      operation: 'update',
+      requestMethod: 'PUT',
+      requestHeaders: request.headers,
+      mutationPayload: input as Record<string, unknown>,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
 
     // Handle customizing a code-based workflow definition
     if (params.id.startsWith('code:')) {
@@ -171,6 +200,19 @@ export async function PUT(
 
       let savedOverride: WorkflowDefinition
       if (existingOverride) {
+        try {
+          enforceCommandOptimisticLock({
+            resourceKind: 'workflows.definition',
+            resourceId: existingOverride.id,
+            current: existingOverride.updatedAt ?? null,
+            request,
+          })
+        } catch (lockError) {
+          if (isCrudHttpError(lockError)) {
+            return NextResponse.json(lockError.body, { status: lockError.status })
+          }
+          throw lockError
+        }
         // Revive if soft-deleted, then apply updates
         existingOverride.deletedAt = null
         existingOverride.workflowName = codeDef.workflowName
@@ -230,6 +272,20 @@ export async function PUT(
         console.error('Failed to emit workflows.definition.customized event:', eventError)
       }
 
+      if (guardResult?.shouldRunAfterSuccess) {
+        await runCrudMutationGuardAfterSuccess(container, {
+          tenantId: tenantId ?? '',
+          organizationId: organizationId ?? null,
+          userId: auth.sub ?? '',
+          resourceKind: 'workflows.definition',
+          resourceId: String(savedOverride.id),
+          operation: 'update',
+          requestMethod: 'PUT',
+          requestHeaders: request.headers,
+          metadata: guardResult.metadata,
+        })
+      }
+
       return NextResponse.json({
         data: serializeWorkflowDefinition(savedOverride),
         message: 'Workflow definition customized successfully',
@@ -251,6 +307,20 @@ export async function PUT(
       )
     }
 
+    try {
+      enforceCommandOptimisticLock({
+        resourceKind: 'workflows.definition',
+        resourceId: definition.id,
+        current: definition.updatedAt ?? null,
+        request,
+      })
+    } catch (lockError) {
+      if (isCrudHttpError(lockError)) {
+        return NextResponse.json(lockError.body, { status: lockError.status })
+      }
+      throw lockError
+    }
+
     // Update fields. workflowId is intentionally ignored — it identifies the
     // row and renaming would break references. Version is user-managed and
     // applied when supplied so the edit form can bump it explicitly.
@@ -283,6 +353,20 @@ export async function PUT(
 
     await em.flush()
 
+    if (guardResult?.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: tenantId ?? '',
+        organizationId: organizationId ?? null,
+        userId: auth.sub ?? '',
+        resourceKind: 'workflows.definition',
+        resourceId: String(definition.id),
+        operation: 'update',
+        requestMethod: 'PUT',
+        requestHeaders: request.headers,
+        metadata: guardResult.metadata,
+      })
+    }
+
     // Embedded triggers may have changed; invalidate the in-memory cache so
     // the wildcard event subscriber reloads them on the next event.
     if (tenantId) invalidateTriggerCache(tenantId, organizationId ?? undefined)
@@ -356,6 +440,20 @@ export async function DELETE(
       )
     }
 
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId: tenantId ?? '',
+      organizationId: organizationId ?? null,
+      userId: auth.sub ?? '',
+      resourceKind: 'workflows.definition',
+      resourceId: params.id,
+      operation: 'delete',
+      requestMethod: 'DELETE',
+      requestHeaders: request.headers,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     // Check if there are active workflow instances using this definition
     const { WorkflowInstance } = await import('../../../data/entities')
     const activeInstances = await em.count(WorkflowInstance, {
@@ -378,6 +476,20 @@ export async function DELETE(
 
     await em.flush()
 
+    if (guardResult?.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: tenantId ?? '',
+        organizationId: organizationId ?? null,
+        userId: auth.sub ?? '',
+        resourceKind: 'workflows.definition',
+        resourceId: String(definition.id),
+        operation: 'delete',
+        requestMethod: 'DELETE',
+        requestHeaders: request.headers,
+        metadata: guardResult.metadata,
+      })
+    }
+
     if (tenantId) invalidateTriggerCache(tenantId, organizationId ?? undefined)
 
     return NextResponse.json({

package/src/modules/workflows/backend/definitions/[id]/page.tsx

@@ -8,8 +8,9 @@ import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
+import { apiFetch, withScopedApiHeaders } from '@open-mercato/ui/backend/utils/api'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
-import { apiFetch } from '@open-mercato/ui/backend/utils/api'
 import { readJsonSafe } from '@open-mercato/ui/backend/utils/serverErrors'
 import { formatWorkflowValidationError } from '../../../lib/format-validation-error'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
@@ -95,17 +96,32 @@ export default function EditWorkflowDefinitionPage() {
 
   const handleSubmit = async (values: WorkflowDefinitionFormValues) => {
     const payload = buildWorkflowPayload({ ...values, triggers })
+    const optimisticLockHeader = buildOptimisticLockHeader(
+      typeof definition?.updatedAt === 'string' ? definition.updatedAt : null,
+    )
 
     await runMutation({
       operation: async () => {
-        const response = await apiFetch(`/api/workflows/definitions/${definitionId}`, {
+        const updateDefinition = () => apiFetch(`/api/workflows/definitions/${definitionId}`, {
           method: 'PUT',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(payload),
         })
+        const response = Object.keys(optimisticLockHeader).length > 0
+          ? await withScopedApiHeaders(optimisticLockHeader, updateDefinition)
+          : await updateDefinition()
         if (!response.ok) {
-          const errorBody = await readJsonSafe<{ error?: string; details?: Array<{ path?: Array<string | number>; message?: string }> }>(response, null)
-          throw new Error(formatWorkflowValidationError(errorBody, t('workflows.errors.updateFailed')))
+          const errorBody = await readJsonSafe<{
+            error?: string
+            code?: string
+            currentUpdatedAt?: string
+            expectedUpdatedAt?: string
+            details?: Array<{ path?: Array<string | number>; message?: string }>
+          }>(response, null)
+          throw Object.assign(
+            new Error(formatWorkflowValidationError(errorBody, t('workflows.errors.updateFailed'))),
+            { status: response.status, ...(errorBody ?? {}) },
+          )
         }
         return response
       },

package/src/modules/workflows/backend/definitions/page.tsx

@@ -18,7 +18,9 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@open-mercato/ui/primitives/dialog'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, 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 { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -86,7 +88,7 @@ export default function WorkflowDefinitionsListPage() {
   const router = useRouter()
   const queryClient = useQueryClient()
   const [filterValues, setFilterValues] = React.useState<FilterValues>({})
-  const [deleteTarget, setDeleteTarget] = React.useState<{ id: string; name: string } | null>(null)
+  const [deleteTarget, setDeleteTarget] = React.useState<{ id: string; name: string; updatedAt: string | null } | null>(null)
 
   const { data, isLoading, error } = useQuery({
     queryKey: ['workflow-definitions', 'list', filterValues, page],
@@ -121,22 +123,31 @@ export default function WorkflowDefinitionsListPage() {
     },
   })
 
-  const handleDelete = (id: string, workflowName: string) => {
-    setDeleteTarget({ id, name: workflowName })
+  const handleDelete = (id: string, workflowName: string, updatedAt: string | null) => {
+    setDeleteTarget({ id, name: workflowName, updatedAt })
   }
 
   const confirmDelete = async () => {
     if (!deleteTarget) return
 
-    const result = await apiCall(`/api/workflows/definitions/${deleteTarget.id}`, {
-      method: 'DELETE',
-    })
+    const result = await withScopedApiRequestHeaders(
+      buildOptimisticLockHeader(deleteTarget.updatedAt),
+      () => apiCall(`/api/workflows/definitions/${deleteTarget.id}`, {
+        method: 'DELETE',
+      }),
+    )
 
     if (result.ok) {
       flash(t('workflows.messages.deleted'), 'success')
       queryClient.invalidateQueries({ queryKey: ['workflow-definitions'] })
     } else {
-      flash(t('workflows.messages.deleteFailed'), 'error')
+      const conflictError = Object.assign(new Error(t('workflows.messages.deleteFailed')), {
+        status: result.status,
+        ...(result.result && typeof result.result === 'object' ? result.result : {}),
+      })
+      if (!surfaceRecordConflict(conflictError, t)) {
+        flash(t('workflows.messages.deleteFailed'), 'error')
+      }
     }
     setDeleteTarget(null)
   }
@@ -354,7 +365,7 @@ export default function WorkflowDefinitionsListPage() {
           ...(!isCodeOnly ? [{
             id: 'delete',
             label: t('common.delete'),
-            onSelect: () => handleDelete(row.original.id, row.original.workflowName),
+            onSelect: () => handleDelete(row.original.id, row.original.workflowName, row.original.updatedAt),
             destructive: true,
           }] : []),
         ]