@open-mercato/core 0.10.1-develop.7716.1.cefe7975df → 0.10.1-develop.7721.1.b5c4a00a68

package/src/modules/staff/commands/timesheets-projects.ts

@@ -24,9 +24,6 @@ import {
   type StaffTimeProjectMemberStatus,
 } from '../data/entities'
 
-const timeProjectCrudIndexer: CrudIndexerConfig<StaffTimeProject> = {
-  entityType: 'staff:staff_time_project',
-}
 const timeProjectMemberCrudIndexer: CrudIndexerConfig<StaffTimeProjectMember> = {
   entityType: 'staff:staff_time_project_member',
 }
@@ -41,7 +38,7 @@ import {
   type StaffTimeProjectMemberAssignInput,
   type StaffTimeProjectMemberUpdateInput,
 } from '../data/validators'
-import { staffTimeProjectCrudEvents, staffTimeProjectMemberCrudEvents } from '../lib/crud'
+import { staffTimeProjectCrudEvents, staffTimeProjectCrudIndexer, staffTimeProjectMemberCrudEvents } from '../lib/crud'
 import { DEFAULT_BUDGET_WARN_AT_PERCENT } from '../lib/timesheets-projects/budgetBurn'
 import { seedProjectTaskStatuses } from '../lib/timesheets-tasks/seedProjectStatuses'
 import {
@@ -142,6 +139,7 @@ type TimeProjectSnapshot = {
   budgetKind: string
   budgetValue: string | null
   budgetWarnAtPercent: number
+  defaultAssigneeStaffMemberId: string | null
   deletedAt: string | null
 }
 
@@ -159,6 +157,7 @@ type TimeProjectMemberSnapshot = {
   role: string | null
   status: string
   showInGrid: boolean
+  isAssigner: boolean
   assignedStartDate: string
   assignedEndDate: string | null
   deletedAt: string | null
@@ -199,6 +198,7 @@ async function loadTimeProjectSnapshot(em: EntityManager, id: string, scope?: St
     budgetKind: project.budgetKind ?? 'none',
     budgetValue: project.budgetValue ?? null,
     budgetWarnAtPercent: project.budgetWarnAtPercent ?? DEFAULT_BUDGET_WARN_AT_PERCENT,
+    defaultAssigneeStaffMemberId: project.defaultAssigneeStaffMemberId ?? null,
     deletedAt: project.deletedAt ? project.deletedAt.toISOString() : null,
   }
 }
@@ -221,6 +221,7 @@ async function loadTimeProjectMemberSnapshot(em: EntityManager, id: string, scop
     role: member.role ?? null,
     status: member.status,
     showInGrid: member.showInGrid ?? false,
+    isAssigner: member.isAssigner === true,
     assignedStartDate: member.assignedStartDate instanceof Date ? member.assignedStartDate.toISOString().split('T')[0] : String(member.assignedStartDate),
     assignedEndDate: member.assignedEndDate instanceof Date ? member.assignedEndDate.toISOString().split('T')[0] : (member.assignedEndDate ?? null),
     deletedAt: member.deletedAt ? member.deletedAt.toISOString() : null,
@@ -249,6 +250,7 @@ function timeProjectSeedFromSnapshot(snapshot: TimeProjectSnapshot): Record<stri
     budgetKind: (snapshot.budgetKind ?? 'none') as StaffTimeProjectBudgetKind,
     budgetValue: snapshot.budgetValue ?? null,
     budgetWarnAtPercent: snapshot.budgetWarnAtPercent ?? DEFAULT_BUDGET_WARN_AT_PERCENT,
+    defaultAssigneeStaffMemberId: snapshot.defaultAssigneeStaffMemberId ?? null,
     createdAt: new Date(),
     updatedAt: new Date(),
     deletedAt: null,
@@ -265,6 +267,7 @@ function timeProjectMemberSeedFromSnapshot(snapshot: TimeProjectMemberSnapshot):
     role: snapshot.role ?? null,
     status: (snapshot.status ?? 'active') as StaffTimeProjectMemberStatus,
     showInGrid: snapshot.showInGrid ?? false,
+    isAssigner: snapshot.isAssigner === true,
     assignedStartDate: new Date(snapshot.assignedStartDate),
     assignedEndDate: snapshot.assignedEndDate ? new Date(snapshot.assignedEndDate) : null,
     createdAt: new Date(),
@@ -368,7 +371,7 @@ const createTimeProjectCommand: CommandHandler<StaffTimeProjectCreateInput, { ti
         tenantId: project.tenantId,
       },
       events: staffTimeProjectCrudEvents,
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
 
     return { timeProjectId: project.id }
@@ -418,7 +421,7 @@ const createTimeProjectCommand: CommandHandler<StaffTimeProjectCreateInput, { ti
           tenantId: project.tenantId,
         },
         events: staffTimeProjectCrudEvents,
-        indexer: timeProjectCrudIndexer,
+        indexer: staffTimeProjectCrudIndexer,
       })
     }
   },
@@ -428,10 +431,60 @@ const createTimeProjectCommand: CommandHandler<StaffTimeProjectCreateInput, { ti
     seedFromSnapshot: timeProjectSeedFromSnapshot,
     buildResult: (entity) => ({ timeProjectId: entity.id }),
     events: staffTimeProjectCrudEvents,
-    indexer: timeProjectCrudIndexer,
+    indexer: staffTimeProjectCrudIndexer,
   }),
 }
 
+async function requireAssignerUserAccount(
+  em: EntityManager,
+  member: { staffMemberId: string; tenantId: string; organizationId: string },
+): Promise<void> {
+  const teamMember = await findOneWithDecryption(
+    em,
+    StaffTeamMember,
+    { id: member.staffMemberId, tenantId: member.tenantId, organizationId: member.organizationId, deletedAt: null },
+    undefined,
+    { tenantId: member.tenantId, organizationId: member.organizationId },
+  )
+  if (teamMember?.userId) return
+  const { translate } = await resolveTranslations()
+  const message = translate(
+    'staff.timesheets.errors.assignerNeedsUser',
+    'Only team members with a user account can be assigners, because they must log in and receive notifications.',
+  )
+  throw new CrudHttpError(422, { code: 'assigner_needs_user', error: message, fieldErrors: { isAssigner: message } })
+}
+
+async function requireDefaultAssigneeMember(
+  em: EntityManager,
+  project: { id: string; tenantId: string; organizationId: string },
+  staffMemberId: string,
+): Promise<void> {
+  const membership = await em.findOne(
+    StaffTimeProjectMember,
+    {
+      timeProjectId: project.id,
+      staffMemberId,
+      tenantId: project.tenantId,
+      organizationId: project.organizationId,
+      status: 'active',
+      deletedAt: null,
+    },
+    { fields: ['id'] },
+  )
+  if (membership) return
+  const { translate } = await resolveTranslations()
+  const message = translate(
+    'staff.timesheets.errors.defaultAssigneeNotMember',
+    'The default assignee must be an active member of this project.',
+  )
+  throw new CrudHttpError(422, {
+    code: 'default_assignee_not_member',
+    error: message,
+    fieldErrors: { defaultAssigneeStaffMemberId: message },
+  })
+}
+
 const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { timeProjectId: string }> = {
   id: 'staff.timesheets.time_projects.update',
   async prepare(rawInput, ctx) {
@@ -480,6 +533,10 @@ const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { ti
         ?? (customerUnchanged && nextCustomerId ? project.customerSnapshot ?? null : null)
     }
 
+    if (parsed.defaultAssigneeStaffMemberId) {
+      await requireDefaultAssigneeMember(em, project, parsed.defaultAssigneeStaffMemberId)
+    }
+
     if (parsed.name !== undefined) project.name = parsed.name
     if (parsed.customerId !== undefined) project.customerId = parsed.customerId ?? null
     if (nextCustomerSnapshot !== undefined) project.customerSnapshot = nextCustomerSnapshot
@@ -496,6 +553,7 @@ const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { ti
     if (parsed.budgetKind !== undefined) project.budgetKind = parsed.budgetKind
     if (parsed.budgetValue !== undefined) project.budgetValue = parsed.budgetValue ?? null
     if (parsed.budgetWarnAtPercent !== undefined) project.budgetWarnAtPercent = parsed.budgetWarnAtPercent
+    if (parsed.defaultAssigneeStaffMemberId !== undefined) project.defaultAssigneeStaffMemberId = parsed.defaultAssigneeStaffMemberId ?? null
     // `currency_code` is intentionally absent here and from the update schema:
     // D-3 gives that column to `staff.timesheets.time_projects.change_currency`,
     // which owns the acknowledgement and the locked-entry refusal. A caller that
@@ -536,7 +594,7 @@ const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { ti
         tenantId: project.tenantId,
       },
       events: staffTimeProjectCrudEvents,
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
 
     return { timeProjectId: project.id }
@@ -563,6 +621,7 @@ const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { ti
       'budgetKind',
       'budgetValue',
       'budgetWarnAtPercent',
+      'defaultAssigneeStaffMemberId',
       'deletedAt',
     ])
     // `buildChanges` compares by identity, and the two snapshots are loaded through
@@ -612,6 +671,7 @@ const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { ti
     project.budgetKind = (before.budgetKind ?? 'none') as StaffTimeProjectBudgetKind
     project.budgetValue = before.budgetValue ?? null
     project.budgetWarnAtPercent = before.budgetWarnAtPercent ?? DEFAULT_BUDGET_WARN_AT_PERCENT
+    project.defaultAssigneeStaffMemberId = before.defaultAssigneeStaffMemberId ?? null
     // Undo of a plain update restores what a plain update could change; the currency
     // stays where change_currency left it (D-3).
     project.deletedAt = before.deletedAt ? new Date(before.deletedAt) : null
@@ -628,7 +688,7 @@ const updateTimeProjectCommand: CommandHandler<StaffTimeProjectUpdateInput, { ti
         tenantId: project.tenantId,
       },
       events: staffTimeProjectCrudEvents,
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
   },
 }
@@ -673,7 +733,7 @@ const deleteTimeProjectCommand: CommandHandler<{ id?: string }, { timeProjectId:
         tenantId: project.tenantId,
       },
       events: staffTimeProjectCrudEvents,
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
     return { timeProjectId: project.id }
   },
@@ -759,7 +819,7 @@ const deleteTimeProjectCommand: CommandHandler<{ id?: string }, { timeProjectId:
         tenantId: project.tenantId,
       },
       events: staffTimeProjectCrudEvents,
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
   },
 }
@@ -932,7 +992,7 @@ const changeTimeProjectCurrencyCommand: CommandHandler<
         tenantId: project.tenantId,
       },
       events: timeProjectCurrencyChangeEvents(previousCurrencyCode, parsed.currencyCode),
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
 
     return {
@@ -1002,7 +1062,7 @@ const changeTimeProjectCurrencyCommand: CommandHandler<
         tenantId: project.tenantId,
       },
       events: staffTimeProjectCrudEvents,
-      indexer: timeProjectCrudIndexer,
+      indexer: staffTimeProjectCrudIndexer,
     })
   },
 }
@@ -1048,6 +1108,10 @@ const assignTimeProjectMemberCommand: CommandHandler<StaffTimeProjectMemberAssig
       })
     }
 
+    if (parsed.isAssigner === true) {
+      await requireAssignerUserAccount(em, { staffMemberId: parsed.staffMemberId, tenantId: parsed.tenantId, organizationId: parsed.organizationId })
+    }
+
     const now = new Date()
     const member = em.create(StaffTimeProjectMember, {
       tenantId: parsed.tenantId,
@@ -1057,6 +1121,7 @@ const assignTimeProjectMemberCommand: CommandHandler<StaffTimeProjectMemberAssig
       role: parsed.role ?? null,
       status: parsed.status ?? 'active',
       showInGrid: false,
+      isAssigner: parsed.isAssigner === true,
       assignedStartDate: parsed.assignedStartDate,
       assignedEndDate: parsed.assignedEndDate ?? null,
       createdAt: now,
@@ -1187,9 +1252,13 @@ const updateTimeProjectMemberCommand: CommandHandler<StaffTimeProjectMemberUpdat
     ensureTenantScope(ctx, member.tenantId)
     ensureOrganizationScope(ctx, member.organizationId)
 
+    if (parsed.isAssigner === true && member.isAssigner !== true) {
+      await requireAssignerUserAccount(em, member)
+    }
     if (parsed.role !== undefined) member.role = parsed.role ?? null
     if (parsed.status !== undefined) member.status = parsed.status
     if (parsed.assignedEndDate !== undefined) member.assignedEndDate = parsed.assignedEndDate ?? null
+    if (parsed.isAssigner !== undefined) member.isAssigner = parsed.isAssigner
     member.updatedAt = new Date()
     await em.flush()
 
@@ -1214,6 +1283,7 @@ const updateTimeProjectMemberCommand: CommandHandler<StaffTimeProjectMemberUpdat
       'role',
       'status',
       'assignedEndDate',
+      'isAssigner',
     ])
     const { translate } = await resolveTranslations()
     return {
@@ -1245,6 +1315,7 @@ const updateTimeProjectMemberCommand: CommandHandler<StaffTimeProjectMemberUpdat
     member.role = before.role ?? null
     member.status = (before.status ?? 'active') as StaffTimeProjectMemberStatus
     member.assignedEndDate = before.assignedEndDate ? new Date(before.assignedEndDate) : null
+    member.isAssigner = before.isAssigner === true
     member.updatedAt = new Date()
     await em.flush()
 

package/src/modules/staff/commands/timesheets-task-assignment.ts

@@ -0,0 +1,319 @@
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandHandler, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { emitCrudSideEffects, emitCrudUndoSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { StaffTeamMember, StaffTimeTask, StaffTimeTaskStatus } from '../data/entities'
+import {
+  isActiveProjectAssigner,
+  resolveAssignmentGraceDaysFromContainer,
+} from '../lib/time-tracking/projectAssignment'
+import {
+  TASK_LIST_CACHE_RESOURCE,
+  emitTaskAssigneeChanged,
+  taskCrudEvents,
+  taskCrudIndexer,
+} from './timesheets-tasks'
+import {
+  applyScopeToWhere,
+  commandActorScope,
+  ensureOrganizationScope,
+  ensureTenantScope,
+  extractUndoPayload,
+} from './shared'
+
+export const staffTimeTaskAssignmentCommandIds = {
+  claim: 'staff.timesheets.tasks.claim',
+  release: 'staff.timesheets.tasks.release',
+} as const
+
+export const TASK_ALREADY_CLAIMED_CODE = 'task_already_claimed'
+export const TASK_NOT_CLAIMABLE_CODE = 'task_not_claimable'
+export const TASK_NOT_ASSIGNER_CODE = 'task_not_assigner'
+export const TASK_NOT_ASSIGNEE_CODE = 'task_not_assignee'
+export const TASK_ASSIGNMENT_CHANGED_CODE = 'task_assignment_changed'
+
+const assignmentInputSchema = z.object({ id: z.string().uuid() })
+
+export type StaffTimeTaskAssignmentInput = z.infer<typeof assignmentInputSchema>
+
+export type StaffTimeTaskAssignmentResult = {
+  taskId: string
+  tenantId: string
+  organizationId: string
+  timeProjectId: string
+  assigneeStaffMemberId: string | null
+  updatedAt: string | null
+}
+
+type AssignmentUndoPayload = {
+  taskId: string
+  tenantId: string
+  organizationId: string
+  previousAssigneeStaffMemberId: string | null
+  nextAssigneeStaffMemberId: string | null
+}
+
+type Translate = (key: string, fallback: string) => string
+
+function notFound(translate: Translate): CrudHttpError {
+  return new CrudHttpError(404, {
+    error: translate('staff.time_tracking.tasks.errors.notFound', 'Task not found or not accessible.'),
+  })
+}
+
+function notClaimable(translate: Translate): CrudHttpError {
+  return new CrudHttpError(422, {
+    code: TASK_NOT_CLAIMABLE_CODE,
+    error: translate('staff.timesheets.errors.taskNotClaimable', 'A finished task cannot be claimed.'),
+  })
+}
+
+function alreadyClaimed(translate: Translate): CrudHttpError {
+  return new CrudHttpError(409, {
+    code: TASK_ALREADY_CLAIMED_CODE,
+    error: translate('staff.timesheets.errors.taskAlreadyClaimed', 'Someone else already took this task.'),
+  })
+}
+
+async function loadDoneStatusIds(em: EntityManager, task: StaffTimeTask): Promise<string[]> {
+  const statuses = await em.find(
+    StaffTimeTaskStatus,
+    { timeProjectId: task.timeProjectId, tenantId: task.tenantId, organizationId: task.organizationId, isDone: true },
+    { fields: ['id'] },
+  )
+  return statuses.map((status) => status.id)
+}
+
+async function resolveActorStaffMemberId(em: EntityManager, ctx: CommandRuntimeContext, task: StaffTimeTask): Promise<string | null> {
+  const userId = ctx.auth?.sub ?? null
+  if (!userId) return null
+  const member = await findOneWithDecryption(
+    em,
+    StaffTeamMember,
+    { userId, tenantId: task.tenantId, organizationId: task.organizationId, deletedAt: null },
+    undefined,
+    { tenantId: task.tenantId, organizationId: task.organizationId },
+  )
+  return member?.id ?? null
+}
+
+async function loadScopedTask(em: EntityManager, ctx: CommandRuntimeContext, id: string, translate: Translate): Promise<StaffTimeTask> {
+  const task = await em.findOne(
+    StaffTimeTask,
+    applyScopeToWhere<StaffTimeTask>({ id, deletedAt: null }, commandActorScope(ctx)),
+  )
+  if (!task) throw notFound(translate)
+  ensureTenantScope(ctx, task.tenantId)
+  ensureOrganizationScope(ctx, task.organizationId)
+  return task
+}
+
+async function emitTaskSideEffects(ctx: CommandRuntimeContext, task: StaffTimeTask, undo = false): Promise<void> {
+  const params = {
+    dataEngine: ctx.container.resolve('dataEngine') as DataEngine,
+    action: 'updated' as const,
+    entity: task,
+    identifiers: { id: task.id, organizationId: task.organizationId, tenantId: task.tenantId },
+    events: taskCrudEvents,
+    indexer: taskCrudIndexer,
+  }
+  if (undo) await emitCrudUndoSideEffects(params)
+  else await emitCrudSideEffects(params)
+}
+
+/**
+ * The conditional UPDATE is the only moment this writer owns the row, so the outcome is
+ * built from what it wrote rather than re-read: a later writer may already have replaced
+ * the assignee, and reporting or undoing their value would be wrong.
+ */
+function captureWrittenState(
+  em: EntityManager,
+  task: StaffTimeTask,
+  assigneeStaffMemberId: string | null,
+  updatedAt: Date,
+): StaffTimeTask {
+  em.clear()
+  task.assigneeStaffMemberId = assigneeStaffMemberId
+  task.updatedAt = updatedAt
+  return task
+}
+
+function toResult(task: StaffTimeTask): StaffTimeTaskAssignmentResult {
+  return {
+    taskId: task.id,
+    tenantId: task.tenantId,
+    organizationId: task.organizationId,
+    timeProjectId: task.timeProjectId,
+    assigneeStaffMemberId: task.assigneeStaffMemberId ?? null,
+    updatedAt: task.updatedAt ? task.updatedAt.toISOString() : null,
+  }
+}
+
+async function restoreAssignee(
+  ctx: CommandRuntimeContext,
+  payload: AssignmentUndoPayload,
+): Promise<void> {
+  const em = (ctx.container.resolve('em') as EntityManager).fork()
+  const where = {
+    id: payload.taskId,
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+    assigneeStaffMemberId: payload.nextAssigneeStaffMemberId,
+    deletedAt: null,
+  }
+  const current = await em.findOne(StaffTimeTask, where)
+  if (!current) return
+  const now = new Date()
+  const affected = await em.nativeUpdate(
+    StaffTimeTask,
+    where,
+    { assigneeStaffMemberId: payload.previousAssigneeStaffMemberId, updatedAt: now },
+  )
+  if (affected === 0) return
+  const task = captureWrittenState(em, current, payload.previousAssigneeStaffMemberId, now)
+  await emitTaskSideEffects(ctx, task, true)
+  emitTaskAssigneeChanged(task, payload.nextAssigneeStaffMemberId, 'manual', ctx.auth?.sub ?? null)
+}
+
+const claimTaskCommand: CommandHandler<StaffTimeTaskAssignmentInput, StaffTimeTaskAssignmentResult> = {
+  id: staffTimeTaskAssignmentCommandIds.claim,
+  async execute(rawInput, ctx) {
+    const parsed = assignmentInputSchema.parse(rawInput)
+    const { translate } = await resolveTranslations()
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const task = await loadScopedTask(em, ctx, parsed.id, translate)
+    const scope = { tenantId: task.tenantId, organizationId: task.organizationId }
+
+    const staffMemberId = await resolveActorStaffMemberId(em, ctx, task)
+    const graceDays = await resolveAssignmentGraceDaysFromContainer(ctx.container, task.tenantId)
+    const isAssigner = staffMemberId
+      ? await isActiveProjectAssigner(em, scope, task.timeProjectId, staffMemberId, { graceDays })
+      : false
+    if (!staffMemberId || !isAssigner) {
+      throw new CrudHttpError(403, {
+        code: TASK_NOT_ASSIGNER_CODE,
+        error: translate('staff.timesheets.errors.notAssigner', 'Only active assigners of this project can claim tasks.'),
+      })
+    }
+
+    const doneStatusIds = await loadDoneStatusIds(em, task)
+    if (doneStatusIds.includes(task.taskStatusId)) throw notClaimable(translate)
+    if (task.assigneeStaffMemberId) throw alreadyClaimed(translate)
+
+    const now = new Date()
+    const affected = await em.nativeUpdate(
+      StaffTimeTask,
+      {
+        id: task.id,
+        tenantId: task.tenantId,
+        organizationId: task.organizationId,
+        assigneeStaffMemberId: null,
+        deletedAt: null,
+        ...(doneStatusIds.length > 0 ? { taskStatusId: { $nin: doneStatusIds } } : {}),
+      },
+      { assigneeStaffMemberId: staffMemberId, updatedAt: now },
+    )
+    if (affected === 0) {
+      em.clear()
+      const current = await em.findOne(StaffTimeTask, { id: task.id, tenantId: task.tenantId, organizationId: task.organizationId, deletedAt: null })
+      if (!current) throw notFound(translate)
+      if (!current.assigneeStaffMemberId && doneStatusIds.includes(current.taskStatusId)) throw notClaimable(translate)
+      throw alreadyClaimed(translate)
+    }
+    const claimed = captureWrittenState(em, task, staffMemberId, now)
+    await emitTaskSideEffects(ctx, claimed)
+    emitTaskAssigneeChanged(claimed, null, 'claim', ctx.auth?.sub ?? null)
+    return toResult(claimed)
+  },
+  buildLog: async ({ result }) => {
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('staff.audit.timesheets.tasks.claim', 'Claim task'),
+      resourceKind: 'staff.timesheets.task',
+      resourceId: result.taskId,
+      tenantId: result.tenantId,
+      organizationId: result.organizationId,
+      context: { cacheAliases: [TASK_LIST_CACHE_RESOURCE] },
+      payload: {
+        undo: {
+          taskId: result.taskId,
+          tenantId: result.tenantId,
+          organizationId: result.organizationId,
+          previousAssigneeStaffMemberId: null,
+          nextAssigneeStaffMemberId: result.assigneeStaffMemberId,
+        } satisfies AssignmentUndoPayload,
+      },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<AssignmentUndoPayload>(logEntry)
+    if (!payload?.taskId) return
+    await restoreAssignee(ctx, payload)
+  },
+}
+
+const releaseTaskCommand: CommandHandler<StaffTimeTaskAssignmentInput, StaffTimeTaskAssignmentResult & { previousAssigneeStaffMemberId: string | null }> = {
+  id: staffTimeTaskAssignmentCommandIds.release,
+  async execute(rawInput, ctx) {
+    const parsed = assignmentInputSchema.parse(rawInput)
+    const { translate } = await resolveTranslations()
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const task = await loadScopedTask(em, ctx, parsed.id, translate)
+    const staffMemberId = await resolveActorStaffMemberId(em, ctx, task)
+    if (!staffMemberId || task.assigneeStaffMemberId !== staffMemberId) {
+      throw new CrudHttpError(403, {
+        code: TASK_NOT_ASSIGNEE_CODE,
+        error: translate('staff.timesheets.errors.notAssignee', 'Only the current assignee can release this task.'),
+      })
+    }
+    const now = new Date()
+    const affected = await em.nativeUpdate(
+      StaffTimeTask,
+      { id: task.id, tenantId: task.tenantId, organizationId: task.organizationId, assigneeStaffMemberId: staffMemberId, deletedAt: null },
+      { assigneeStaffMemberId: null, updatedAt: now },
+    )
+    if (affected === 0) {
+      throw new CrudHttpError(409, {
+        code: TASK_ASSIGNMENT_CHANGED_CODE,
+        error: translate('staff.timesheets.errors.taskChanged', 'The task changed while you were releasing it. Refresh and try again.'),
+      })
+    }
+    const released = captureWrittenState(em, task, null, now)
+    await emitTaskSideEffects(ctx, released)
+    emitTaskAssigneeChanged(released, staffMemberId, 'release', ctx.auth?.sub ?? null)
+    return { ...toResult(released), previousAssigneeStaffMemberId: staffMemberId }
+  },
+  buildLog: async ({ result }) => {
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: translate('staff.audit.timesheets.tasks.release', 'Release task'),
+      resourceKind: 'staff.timesheets.task',
+      resourceId: result.taskId,
+      tenantId: result.tenantId,
+      organizationId: result.organizationId,
+      context: { cacheAliases: [TASK_LIST_CACHE_RESOURCE] },
+      payload: {
+        undo: {
+          taskId: result.taskId,
+          tenantId: result.tenantId,
+          organizationId: result.organizationId,
+          previousAssigneeStaffMemberId: result.previousAssigneeStaffMemberId,
+          nextAssigneeStaffMemberId: null,
+        } satisfies AssignmentUndoPayload,
+      },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<AssignmentUndoPayload>(logEntry)
+    if (!payload?.taskId) return
+    await restoreAssignee(ctx, payload)
+  },
+}
+
+registerCommand(claimTaskCommand)
+registerCommand(releaseTaskCommand)