@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

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

@@ -10,7 +10,8 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
-import { claimUserTask } from '../../../../lib/task-handler'
+import type { TaskHandlerService } from '../../../../lib/task-handler'
+import { gateTaskAction } from '../../../../lib/task-visibility-request'
 import {
   workflowsTag,
   userTaskClaimResponseSchema,
@@ -57,8 +58,35 @@ export async function POST(
       )
     }
 
+    // §6.4 runs BEFORE the handler, and that ordering is the disclosure fix:
+    // `claimUserTask` reports `TASK_ALREADY_ASSIGNED` before it checks queue
+    // membership, so a caller with no relationship to the task used to learn
+    // that it exists from the status code alone. Now they get the same 404 a
+    // nonexistent id produces, and the handler still owns membership, the
+    // compare-and-set and every error code below.
+    const gate = await gateTaskAction({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      taskId: params.id,
+      organizationId,
+    })
+
+    if (!gate.allowed) {
+      return NextResponse.json(gate.refusal.body, { status: gate.refusal.status })
+    }
+
     // Call task handler to claim task
-    await claimUserTask(em, params.id, auth.sub)
+    const taskHandler = container.resolve<TaskHandlerService>('taskHandler')
+    // Role names are server-derived (`auth.roles`), never read off the request —
+    // a caller who holds none of the task's queues is refused as "not found".
+    await taskHandler.claimUserTask(
+      em,
+      params.id,
+      auth.sub,
+      { tenantId, organizationId },
+      auth.roles ?? [],
+    )
 
     // Fetch updated task
     const { UserTask } = await import('../../../../data/entities')
@@ -82,20 +110,16 @@ export async function POST(
   } catch (error) {
     logger.error('Error claiming user task', { err: error })
 
-    // Handle specific error codes from task-handler
-    if (error instanceof Error) {
-      if (error.message.includes('not found')) {
-        return NextResponse.json(
-          { error: error.message },
-          { status: 404 }
-        )
-      }
-      if (error.message.includes('already')) {
-        return NextResponse.json(
-          { error: error.message },
-          { status: 409 }
-        )
-      }
+    // Keyed on the handler's error CODE rather than on substrings of its
+    // message. The old message matching had no arm for `TASK_NOT_ROLE_ASSIGNED`
+    // ("Task is not assigned to any roles" contains neither "not found" nor
+    // "already"), so a task with an empty queue answered 500.
+    const code = (error as { code?: unknown } | null)?.code
+    if (code === 'TASK_NOT_FOUND') {
+      return NextResponse.json({ error: (error as Error).message }, { status: 404 })
+    }
+    if (code === 'TASK_ALREADY_ASSIGNED' || code === 'TASK_NOT_ROLE_ASSIGNED') {
+      return NextResponse.json({ error: (error as Error).message }, { status: 409 })
     }
 
     return NextResponse.json(
@@ -121,7 +145,8 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Missing tenant or organization context', schema: workflowErrorSchema },
         { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
-        { status: 404, description: 'Task not found', schema: workflowErrorSchema },
+        { status: 403, description: 'The task is visible to the caller but is not theirs to act on — it has no assignee and no role queue, so it must be reassigned first (§6.4: administration widens seeing, never acting).', schema: workflowErrorSchema },
+        { status: 404, description: 'Task not found, or not visible to the caller', schema: workflowErrorSchema },
         { status: 409, description: 'Task already claimed', schema: workflowErrorSchema },
         { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
       ],

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

@@ -11,7 +11,8 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
-import { completeUserTask } from '../../../../lib/task-handler'
+import type { TaskHandlerService } from '../../../../lib/task-handler'
+import { gateTaskAction } from '../../../../lib/task-visibility-request'
 import {
   workflowsTag,
   completeTaskRequestSchema as openApiCompleteTaskSchema,
@@ -31,6 +32,11 @@ export const metadata = {
 const completeTaskSchema = z.object({
   formData: z.record(z.string(), z.any()),
   comments: z.string().optional(),
+  /**
+   * The decision button the assignee pressed. Optional and additive: a task
+   * without decisions completes through the plain form exactly as before.
+   */
+  decisionId: z.string().min(1).optional(),
 })
 
 /**
@@ -89,29 +95,40 @@ export async function POST(
       )
     }
 
-    const { formData, comments } = parseResult.data
-
-    // Verify task belongs to this tenant/org before completing
-    const { UserTask } = await import('../../../../data/entities')
-    const task = await em.findOne(UserTask, {
-      id: params.id,
-      tenantId,
+    const { formData, comments, decisionId } = parseResult.data
+
+    // §6.4 replaces the bare tenant/organization check that used to stand here.
+    // The narrowing D-1 keeps `workflows.tasks.complete` on the route and still
+    // demands: holding it no longer completes anyone ELSE's task. Refusals are
+    // indistinguishable from a nonexistent id unless the caller already sees the
+    // row.
+    const gate = await gateTaskAction({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      taskId: params.id,
       organizationId,
+      // Complete is the one act where the gate, not the handler, decides
+      // ownership: the handler leaves an OWNERLESS row open to anyone holding
+      // the feature, which is exactly the pre-change semantics §6.4 narrows.
+      requireOwnership: true,
     })
 
-    if (!task) {
-      return NextResponse.json(
-        { error: 'Task not found' },
-        { status: 404 }
-      )
+    if (!gate.allowed) {
+      return NextResponse.json(gate.refusal.body, { status: gate.refusal.status })
     }
 
+    const { UserTask } = await import('../../../../data/entities')
+
     // Call task handler to complete task and resume workflow
-    await completeUserTask(em, container, {
+    const taskHandler = container.resolve<TaskHandlerService>('taskHandler')
+    await taskHandler.completeUserTask(em, container, {
       taskId: params.id,
       formData,
       userId: auth.sub,
       comments,
+      decisionId,
+      scope: { tenantId, organizationId },
     })
 
     // Fetch updated task
@@ -130,6 +147,20 @@ export async function POST(
 
     // Handle specific error codes from task-handler
     if (error instanceof Error) {
+      if ((error as { code?: unknown }).code === 'UNKNOWN_DECISION') {
+        return NextResponse.json(
+          { error: error.message },
+          { status: 400 }
+        )
+      }
+      // "Task is assigned to another user" matches none of the message arms
+      // below, so this refusal used to answer 500. It is a conflict.
+      if ((error as { code?: unknown }).code === 'TASK_ASSIGNED_TO_ANOTHER_USER') {
+        return NextResponse.json(
+          { error: error.message },
+          { status: 409 }
+        )
+      }
       if (error.message.includes('not found')) {
         return NextResponse.json(
           { error: error.message },
@@ -177,7 +208,8 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Invalid request body, validation failed, or missing context', schema: workflowErrorSchema },
         { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
-        { status: 404, description: 'Task not found', schema: workflowErrorSchema },
+        { status: 403, description: 'The task is visible to the caller but is not theirs to act on — it has no assignee and no role queue, so it must be reassigned first (§6.4: administration widens seeing, never acting).', schema: workflowErrorSchema },
+        { status: 404, description: 'Task not found, or not visible to the caller', schema: workflowErrorSchema },
         { status: 409, description: 'Task already completed', schema: workflowErrorSchema },
         { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
       ],

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

@@ -0,0 +1,197 @@
+/**
+ * User Task Reassignment API
+ *
+ * Endpoints:
+ * - POST /api/workflows/tasks/[id]/reassign - Move a task to another assignee or role queue
+ *
+ * This is the act half of §6.4's central asymmetry. `workflows.tasks.view_all`
+ * lets an administrator SEE a colleague's task and never lets them finish it, so
+ * the sanctioned path to acting on somebody else's work is to take it first —
+ * here — and the taking is permanently recorded on the audit columns plus a
+ * `WorkflowEvent`.
+ *
+ * It is also the documented remedy for the one shape the model leaves
+ * uncompletable: a task with no assignee, no claim and no role queue belongs to
+ * nobody, so the act routes answer `TASK_NOT_ACTIONABLE` and name this endpoint.
+ * The gate below therefore checks VISIBILITY, never ownership — requiring
+ * ownership would make the unrescuable task unrescuable by definition.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { TaskHandlerService } from '../../../../lib/task-handler'
+import { gateTaskAction } from '../../../../lib/task-visibility-request'
+import { reassignUserTaskSchema } from '../../../../data/validators'
+import { serializeUserTask } from '../../serialize'
+import {
+  workflowsTag,
+  userTaskReassignResponseSchema,
+  workflowErrorSchema,
+} from '../../../openapi'
+
+const logger = createLogger('workflows')
+
+/**
+ * `UserTask` is deliberately absent from the curated optimistic-lock entity
+ * list, and `optimistic-lock-ui-coverage.test.ts` only matches `PUT`/`PATCH`/
+ * `DELETE`, so nothing enforces the header here automatically. The route honours
+ * it explicitly: a client that sends `x-om-ext-optimistic-lock-expected-updated-at`
+ * gets the same structured 409 every CRUD surface returns, and one that does not
+ * is unaffected (the helper is a no-op without the header).
+ */
+const REASSIGN_RESOURCE_KIND = 'workflows.user_task'
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.tasks.reassign'],
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { id: string } },
+) {
+  try {
+    const container = await createRequestContainer()
+    const em = container.resolve('em')
+    const auth = await getAuthFromRequest(request)
+
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const organizationId = scope?.selectedId ?? auth.orgId
+
+    if (!tenantId || !organizationId) {
+      return NextResponse.json(
+        { error: 'Missing tenant or organization context' },
+        { status: 400 },
+      )
+    }
+
+    let payload: unknown
+    try {
+      payload = await request.json()
+    } catch {
+      payload = {}
+    }
+
+    const parsed = reassignUserTaskSchema.safeParse(payload)
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: 'Invalid request body', details: parsed.error.issues },
+        { status: 400 },
+      )
+    }
+
+    // Visibility only — see the file header. A `workflows.tasks.reassign` holder
+    // depends on `workflows.tasks.view_all`, so an administrator reaches every
+    // row in scope, including the ownerless one this endpoint exists to rescue.
+    const gate = await gateTaskAction({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      taskId: params.id,
+      organizationId,
+    })
+
+    if (!gate.allowed) {
+      return NextResponse.json(gate.refusal.body, { status: gate.refusal.status })
+    }
+
+    enforceCommandOptimisticLock({
+      resourceKind: REASSIGN_RESOURCE_KIND,
+      resourceId: gate.task.id,
+      current: gate.task.updatedAt,
+      request,
+    })
+
+    const taskHandler = container.resolve<TaskHandlerService>('taskHandler')
+    const task = await taskHandler.reassignUserTask(em, {
+      taskId: params.id,
+      userId: auth.sub,
+      target: {
+        assignedTo: parsed.data.assignedTo,
+        assignedToRoles: parsed.data.assignedToRoles,
+      },
+      reason: parsed.data.reason,
+      scope: { tenantId, organizationId },
+    })
+
+    return NextResponse.json({
+      data: serializeUserTask(task),
+      message: 'Task reassigned successfully',
+    })
+  } catch (error) {
+    if (isCrudHttpError(error)) {
+      return NextResponse.json(error.body, { status: error.status })
+    }
+
+    const code = (error as { code?: unknown } | null)?.code
+    if (code === 'TASK_NOT_FOUND') {
+      return NextResponse.json({ error: (error as Error).message }, { status: 404 })
+    }
+    if (code === 'TASK_NOT_REASSIGNABLE') {
+      return NextResponse.json(
+        { error: (error as Error).message, code: 'TASK_NOT_REASSIGNABLE' },
+        { status: 409 },
+      )
+    }
+
+    logger.error('Error reassigning user task', { err: error })
+    return NextResponse.json(
+      {
+        error: 'Failed to reassign user task',
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Reassign user task',
+  methods: {
+    POST: {
+      summary: 'Move a task to another assignee or role queue',
+      description:
+        'Records who moved the task, when, and why (`reassignedBy` / `reassignedAt` / `reassignReason`) and logs a `USER_TASK_REASSIGNED` workflow event. Requires `workflows.tasks.reassign`. An in-flight claim is released and an IN_PROGRESS task returns to PENDING; the status vocabulary is unchanged. Honours the optimistic-lock header `x-om-ext-optimistic-lock-expected-updated-at`.',
+      requestBody: { schema: reassignUserTaskSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Task reassigned successfully',
+          schema: userTaskReassignResponseSchema,
+        },
+      ],
+      errors: [
+        {
+          status: 400,
+          description: 'Missing tenant/organization context, or a body naming neither an assignee nor a role queue',
+          schema: workflowErrorSchema,
+        },
+        { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
+        {
+          status: 403,
+          description: 'Visible to the caller but refused by the entity gate, with the blocking entity type named',
+          schema: workflowErrorSchema,
+        },
+        { status: 404, description: 'Task not found, or not visible to the caller', schema: workflowErrorSchema },
+        {
+          status: 409,
+          description: 'Task is in a terminal status, or the record changed since it was loaded (optimistic lock)',
+          schema: workflowErrorSchema,
+        },
+        { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}

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

@@ -13,12 +13,22 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
 import { UserTask } from '../../../data/entities'
+import { serializeUserTask } from '../serialize'
+import { loadTaskDecisionContext } from '../../../lib/task-decision-context'
 import {
   workflowsTag,
   userTaskDetailResponseSchema,
   workflowErrorSchema,
 } from '../../openapi'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  collectTaskEntityTypesFromTasks,
+  decideTaskAccess,
+  resolveTaskAffordancesForRequest,
+  resolveTaskRefusal,
+  resolveTaskVisibilityForRequest,
+  TASK_NOT_FOUND_BODY,
+} from '../../../lib/task-visibility-request'
 
 const logger = createLogger('workflows')
 
@@ -62,15 +72,50 @@ export async function GET(
       ...orgFilter.where,
     })
 
+    // A cross-tenant id, an organization the caller cannot see and a random uuid
+    // all land here with the SAME body — existence must not be disclosed by the
+    // shape of the refusal.
     if (!task) {
-      return NextResponse.json(
-        { error: 'Task not found' },
-        { status: 404 }
-      )
+      return NextResponse.json(TASK_NOT_FOUND_BODY, { status: 404 })
+    }
+
+    const visibility = await resolveTaskVisibilityForRequest({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      organizationIds: orgFilter.organizationIds ?? null,
+      aclOrganizationId: orgFilter.rbacOrganizationId,
+      entityTypes: collectTaskEntityTypesFromTasks([task]),
+    })
+
+    const decision = decideTaskAccess(visibility, task)
+    if (!decision.visible) {
+      // 404 for everyone who has no legitimate knowledge that the row exists;
+      // 403-with-reason only for a caller who already sees it in a list view and
+      // needs to know which binding hid its contents.
+      const refusal = resolveTaskRefusal(visibility, decision)
+      return NextResponse.json(refusal.body, { status: refusal.status })
     }
 
+    // Decision buttons are DERIVED, never stored: the instance pins its
+    // definition version, so re-resolving here always yields the buttons the
+    // author wrote for this step. A task on a step that authored none gets an
+    // empty list and completes through the plain form exactly as before.
+    const { decisions, stepId, formKey } = await loadTaskDecisionContext(em, task)
+
+    // The predicate already answered "may this caller act on this row" above.
+    // Sending it is what stops the page offering a Complete button that 409s for
+    // an administrator, and what lets it name the remedy (reassignment) instead.
+    const affordances = resolveTaskAffordancesForRequest(visibility, task, decision)
+
     return NextResponse.json({
-      data: task,
+      data: {
+        ...serializeUserTask(task),
+        stepId,
+        decisions,
+        formKey,
+        ...affordances,
+      },
     })
   } catch (error) {
     logger.error('Error fetching user task', { err: error })
@@ -97,7 +142,13 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Missing tenant or organization context', schema: workflowErrorSchema },
         { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
-        { status: 404, description: 'Task not found', schema: workflowErrorSchema },
+        {
+          status: 403,
+          description:
+            'The task is bound to an entity type the caller may not view. Returned only to callers holding workflows.tasks.view_all (or a superadmin), who already see the row in a list view; everyone else receives the generic 404.',
+          schema: workflowErrorSchema,
+        },
+        { status: 404, description: 'Task not found, or not visible to the caller', schema: workflowErrorSchema },
         { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
       ],
     },

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

@@ -0,0 +1,132 @@
+/**
+ * User Task Unclaim API
+ *
+ * Endpoints:
+ * - POST /api/workflows/tasks/[id]/unclaim - Release a claimed task back to its
+ *   role queue
+ *
+ * The counterpart of `claim`. New route, so purely additive
+ * (BACKWARD_COMPATIBILITY.md §7); gated on the same `workflows.tasks.claim`
+ * feature, because releasing your own claim is part of claiming rather than a
+ * separate authority.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/core'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { TaskHandlerService } from '../../../../lib/task-handler'
+import { gateTaskAction } from '../../../../lib/task-visibility-request'
+import { serializeUserTask } from '../../serialize'
+import { UserTask } from '../../../../data/entities'
+import {
+  workflowsTag,
+  userTaskClaimResponseSchema,
+  workflowErrorSchema,
+} from '../../../openapi'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.tasks.claim'],
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const container = await createRequestContainer()
+    const em = container.resolve<EntityManager>('em')
+    const auth = await getAuthFromRequest(request)
+
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const organizationId = scope?.selectedId ?? auth.orgId
+
+    if (!tenantId || !organizationId) {
+      return NextResponse.json(
+        { error: 'Missing tenant or organization context' },
+        { status: 400 }
+      )
+    }
+
+    // §6.4 first, so a caller with no relationship to the task cannot tell a
+    // claimed task from a nonexistent one. The handler still enforces that the
+    // caller IS the claimant, with the same compare-and-set.
+    const gate = await gateTaskAction({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      taskId: params.id,
+      organizationId,
+    })
+
+    if (!gate.allowed) {
+      return NextResponse.json(gate.refusal.body, { status: gate.refusal.status })
+    }
+
+    const taskHandler = container.resolve<TaskHandlerService>('taskHandler')
+    await taskHandler.releaseUserTask(em, params.id, auth.sub, { tenantId, organizationId })
+
+    const task = await em.findOne(UserTask, { id: params.id, tenantId, organizationId })
+
+    if (!task) {
+      return NextResponse.json({ error: 'Task not found after release' }, { status: 500 })
+    }
+
+    return NextResponse.json({
+      data: serializeUserTask(task),
+      message: 'Task released successfully',
+    })
+  } catch (error) {
+    logger.error('Error releasing user task', { err: error })
+
+    const code = (error as { code?: unknown } | null)?.code
+    if (code === 'TASK_NOT_FOUND') {
+      return NextResponse.json({ error: (error as Error).message }, { status: 404 })
+    }
+    if (code === 'TASK_ASSIGNED_TO_ANOTHER_USER') {
+      return NextResponse.json({ error: (error as Error).message }, { status: 409 })
+    }
+
+    return NextResponse.json(
+      {
+        error: 'Failed to release user task',
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 }
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Release user task',
+  methods: {
+    POST: {
+      summary: 'Release a claimed task back to its role queue',
+      description:
+        'Clears the caller\'s claim and returns the task to PENDING so another holder of the queued role can pick it up. Refused when the task is claimed by somebody else or is no longer in progress.',
+      responses: [
+        { status: 200, description: 'Task released successfully', schema: userTaskClaimResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Missing tenant or organization context', schema: workflowErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
+        { status: 403, description: 'The task is visible to the caller but is not theirs to act on — it has no assignee and no role queue, so it must be reassigned first (§6.4: administration widens seeing, never acting).', schema: workflowErrorSchema },
+        { status: 404, description: 'Task not found, not visible to the caller, or not claimed', schema: workflowErrorSchema },
+        { status: 409, description: 'Task claimed by another user', schema: workflowErrorSchema },
+        { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}