@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/api/tasks/route.ts

@@ -6,6 +6,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server'
+import type { z } from 'zod'
 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'
@@ -19,9 +20,22 @@ import {
   workflowErrorSchema,
 } from '../openapi'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { parseNumberWithDefault } from '@open-mercato/shared/lib/number'
+import { serializeUserTask } from './serialize'
+import {
+  buildTaskVisibilityRequestConditions,
+  collectScopedTaskEntityTypes,
+  partitionTaskPage,
+  resolveTaskVisibilityForRequest,
+} from '../../lib/task-visibility-request'
 
 const logger = createLogger('workflows')
 
+const DEFAULT_TASK_LIST_LIMIT = 50
+// The OpenAPI query schema documents `max(100)` and the project rule caps page
+// sizes at 100, but the handler used to `parseInt` whatever arrived.
+const MAX_TASK_LIST_LIMIT = 100
+
 export const metadata = {
   requireAuth: true,
   requireFeatures: ['workflows.tasks.view'],
@@ -68,8 +82,11 @@ export async function GET(request: NextRequest) {
     const workflowInstanceId = searchParams.get('workflowInstanceId')
     const overdue = searchParams.get('overdue') === 'true'
     const myTasks = searchParams.get('myTasks') === 'true'
-    const limit = parseInt(searchParams.get('limit') || '50')
-    const offset = parseInt(searchParams.get('offset') || '0')
+    const limit = Math.min(
+      parseNumberWithDefault(searchParams.get('limit'), DEFAULT_TASK_LIST_LIMIT, { min: 1, integer: true }),
+      MAX_TASK_LIST_LIMIT,
+    )
+    const offset = parseNumberWithDefault(searchParams.get('offset'), 0, { min: 0, integer: true })
 
     // Build where clause with tenant scoping
     const where: any = {
@@ -108,6 +125,26 @@ export async function GET(request: NextRequest) {
       ]
     }
 
+    // §6.4: `workflows.tasks.view` admits the caller to this endpoint, the
+    // visibility rule decides which rows they get. Resolved ONCE — one ACL load,
+    // one classification pass, one tenant-setting read for the whole page.
+    const visibility = await resolveTaskVisibilityForRequest({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      organizationIds: orgFilter.organizationIds ?? null,
+      aclOrganizationId: orgFilter.rbacOrganizationId,
+      entityTypes: await collectScopedTaskEntityTypes(em, {
+        tenantId,
+        organizationIds: orgFilter.organizationIds ?? null,
+      }),
+    })
+
+    const visibilityConditions = buildTaskVisibilityRequestConditions(visibility)
+    if (visibilityConditions.length > 0) {
+      where.$and = [...(Array.isArray(where.$and) ? where.$and : []), ...visibilityConditions]
+    }
+
     const [tasks, total] = await em.findAndCount(
       UserTask,
       where,
@@ -118,15 +155,33 @@ export async function GET(request: NextRequest) {
       }
     )
 
-    return NextResponse.json({
-      data: tasks,
+    // The `WHERE` above IS the predicate, so for an ordinary caller this drops
+    // nothing and `total` stays the count of what they may see. It runs because
+    // the predicate is the single decision point and because a divergence must
+    // lose a row rather than leak one.
+    //
+    // For a principal entitled to a diagnosis the `WHERE` deliberately omits the
+    // entity gate, so the refused rows arrive here and become MARKERS rather
+    // than an unexplained gap in the page (design §3.6). `hasMore` is computed
+    // from the rows the query returned, not from the ones that survived, so
+    // paging still walks the whole set instead of stopping early on a page whose
+    // every row was hidden.
+    const { visible: visibleTasks, entityHidden } = partitionTaskPage(visibility, tasks)
+
+    const body: z.infer<typeof userTaskListResponseSchema> = {
+      data: visibleTasks.map(serializeUserTask),
       pagination: {
         total,
         limit,
         offset,
         hasMore: offset + tasks.length < total,
       },
-    })
+      ...(entityHidden.length > 0
+        ? { diagnostics: { entityHidden, entityHiddenCount: entityHidden.length } }
+        : {}),
+    }
+
+    return NextResponse.json(body)
   } catch (error) {
     logger.error('Error listing user tasks', { err: error })
     return NextResponse.json(

package/src/modules/workflows/api/tasks/serialize.ts

@@ -0,0 +1,119 @@
+import type { z } from 'zod'
+import type { UserTask } from '../../data/entities'
+import type { userTaskRowSchema } from '../openapi'
+
+/**
+ * Work-inbox row projection for `UserTask`.
+ *
+ * The list endpoint used to hand the ORM entities straight to `NextResponse.json`,
+ * so anything a consumer needed that was not a column stayed buried in the
+ * authored `formSchema` blob: the enterprise "Review proposal" row action reads
+ * `row.proposalId`, which lives at `formSchema.proposalId`, and therefore never
+ * fired. This projects those work-item fields to the top level.
+ *
+ * It is a strict SUPERSET of the previous payload — every column the entity dump
+ * carried is still emitted, with dates in the same ISO form `JSON.stringify`
+ * produced (BACKWARD_COMPATIBILITY.md §7: never remove a response field).
+ */
+
+export const USER_TASK_INBOX_KIND = 'user_task'
+
+export type SerializedUserTask = z.infer<typeof userTaskRowSchema>
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  return value as Record<string, unknown>
+}
+
+function readProposalId(task: UserTask): string | null {
+  for (const source of [task.formSchema, task.formData]) {
+    const record = asRecord(source)
+    const value = record?.proposalId ?? record?.proposal_id
+    if (typeof value === 'string' && value.length > 0) return value
+  }
+  return null
+}
+
+/**
+ * Both readers prefer the real column and fall back to the authored
+ * `formSchema` blob. The column is authoritative from the moment task creation
+ * resolves it; the fallback keeps every row written before the column existed
+ * — and every third party that stuffed the value into `formSchema` — reading
+ * exactly as it read before.
+ */
+function readPriority(task: UserTask): string | number | null {
+  if (typeof task.priority === 'string' && task.priority.length > 0) return task.priority
+  const value = asRecord(task.formSchema)?.priority
+  if (typeof value === 'string' && value.length > 0) return value
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  return null
+}
+
+function readEntityBindings(task: UserTask): unknown[] | null {
+  if (Array.isArray(task.entityBindings)) return task.entityBindings
+  const value = asRecord(task.formSchema)?.entityBindings
+  return Array.isArray(value) ? value : null
+}
+
+/**
+ * The stored denormalization when there is one, otherwise derived from the
+ * bindings the row actually carries. The fallback is what keeps a row written
+ * before the column existed reporting the same set the work-inbox projection
+ * computes for it — the two must never disagree, because that disagreement is
+ * exactly a task hidden by the SQL gate and shown by the JS one.
+ */
+function readEntityTypes(task: UserTask): string[] | null {
+  if (Array.isArray(task.entityTypes)) return task.entityTypes
+  const bindings = readEntityBindings(task)
+  if (!bindings) return null
+  const types = new Set<string>()
+  for (const binding of bindings) {
+    const entityType = asRecord(binding)?.entityType
+    if (typeof entityType === 'string' && entityType.length > 0) types.add(entityType)
+  }
+  return types.size > 0 ? [...types] : null
+}
+
+function toIso(value: Date | null | undefined): string | null {
+  return value ? value.toISOString() : null
+}
+
+export function serializeUserTask(task: UserTask): SerializedUserTask {
+  return {
+    id: task.id,
+    workflowInstanceId: task.workflowInstanceId,
+    stepInstanceId: task.stepInstanceId,
+    branchInstanceId: task.branchInstanceId ?? null,
+    taskName: task.taskName,
+    description: task.description ?? null,
+    status: task.status,
+    formSchema: task.formSchema ?? null,
+    formData: task.formData ?? null,
+    assignedTo: task.assignedTo ?? null,
+    // Defaulted rather than coalesced to null: the column is NOT NULL precisely
+    // so no branch has to handle an absent discriminator, and a row read through
+    // a stale projection is a backoffice task like every row that predates it.
+    assigneeKind: task.assigneeKind ?? 'user',
+    assignedToRoles: task.assignedToRoles ?? null,
+    entityTypes: readEntityTypes(task),
+    claimedBy: task.claimedBy ?? null,
+    claimedAt: toIso(task.claimedAt),
+    dueDate: toIso(task.dueDate),
+    escalatedAt: toIso(task.escalatedAt),
+    escalatedTo: task.escalatedTo ?? null,
+    completedBy: task.completedBy ?? null,
+    completedAt: toIso(task.completedAt),
+    comments: task.comments ?? null,
+    reassignedBy: task.reassignedBy ?? null,
+    reassignedAt: toIso(task.reassignedAt),
+    reassignReason: task.reassignReason ?? null,
+    tenantId: task.tenantId,
+    organizationId: task.organizationId,
+    createdAt: task.createdAt.toISOString(),
+    updatedAt: task.updatedAt.toISOString(),
+    kind: USER_TASK_INBOX_KIND,
+    proposalId: readProposalId(task),
+    priority: readPriority(task),
+    entityBindings: readEntityBindings(task),
+  }
+}

package/src/modules/workflows/api/templates/route.ts

@@ -0,0 +1,87 @@
+/**
+ * Workflow Templates API
+ *
+ * Endpoint:
+ * - GET /api/workflows/templates - List seeded workflow templates for the gallery
+ */
+
+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 { loadWorkflowTemplates } from '../../lib/workflow-templates'
+import { workflowsTag, workflowErrorSchema, workflowTemplateListResponseSchema } from '../openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.definitions.view'],
+}
+
+/**
+ * GET /api/workflows/templates
+ *
+ * List the shipped workflow templates (gallery metadata + full definitions).
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const container = await createRequestContainer()
+    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) {
+      return NextResponse.json({ error: 'Missing tenant context' }, { status: 400 })
+    }
+
+    const rbacService = container.resolve('rbacService')
+    const hasPermission = await rbacService.userHasAllFeatures(
+      auth.sub,
+      ['workflows.definitions.view'],
+      { tenantId, organizationId }
+    )
+
+    if (!hasPermission) {
+      return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 })
+    }
+
+    const items = loadWorkflowTemplates()
+
+    return NextResponse.json({ items })
+  } catch (error) {
+    logger.error('Error listing workflow templates', { err: error })
+    return NextResponse.json(
+      { error: 'Failed to list workflow templates' },
+      { status: 500 }
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'List workflow templates',
+  methods: {
+    GET: {
+      summary: 'List seeded workflow templates',
+      description: 'Returns the shipped workflow template gallery: metadata (id, i18n name/description keys, category, icon) plus the complete workflow definition each template seeds.',
+      responses: [
+        { status: 200, description: 'Available workflow templates', schema: workflowTemplateListResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Missing tenant context', schema: workflowErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
+        { status: 403, description: 'Insufficient permissions', schema: workflowErrorSchema },
+        { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/work-inbox/next/route.ts

@@ -0,0 +1,170 @@
+/**
+ * Work Inbox — claim-next (spec §6.2: "a one-click claim-next affordance …
+ * keeps frontline flow").
+ *
+ * Endpoints:
+ * - POST /api/workflows/work-inbox/next — claim the top claimable item
+ *
+ * Atomicity: the candidate list is a plain read and is expected to be stale by
+ * the time it is used. The claim itself is `taskHandler.claimUserTask`, which
+ * takes the row with a conditional `UPDATE … WHERE status = 'PENDING' AND
+ * claimed_by IS NULL`. Two operators pressing the button at the same instant
+ * therefore see the same candidate list and the loser's update affects zero
+ * rows, at which point this handler moves on to the next candidate instead of
+ * failing. Nothing about the claim is re-implemented here (module MUST #1).
+ *
+ * Phase 1 claims workflow tasks only: `taskHandler` is the claim seam for the
+ * `user_task` kind, and a provider-generic claim would need each source to
+ * expose a server-side claim of its own. Other kinds stay claimable through
+ * their own endpoints, which the row's `actions` already advertise.
+ */
+
+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 { USER_TASK_INBOX_KIND } from '../../tasks/serialize'
+import { serializeWorkInboxRow } from '../../../lib/work-inbox/provider'
+import { parseWorkInboxQuery } from '../../../lib/work-inbox/query'
+import { toUserTaskWorkInboxRow } from '../../../lib/work-inbox/user-task-source'
+import type { WorkInboxService } from '../../../lib/work-inbox/service'
+import type { TaskHandlerService } from '../../../lib/task-handler'
+import {
+  collectScopedTaskEntityTypes,
+  resolveTaskVisibilityForRequest,
+} from '../../../lib/task-visibility-request'
+import { UserTask } from '../../../data/entities'
+import {
+  workflowsTag,
+  workInboxClaimNextResponseSchema,
+  workflowErrorSchema,
+} from '../../openapi'
+
+const logger = createLogger('workflows')
+
+/** Codes that mean "someone else got there first" — try the next candidate. */
+const RACE_LOST_CODES = new Set(['TASK_NOT_FOUND', 'TASK_ALREADY_ASSIGNED', 'TASK_NOT_ROLE_ASSIGNED'])
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.tasks.claim'],
+}
+
+function isRaceLost(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false
+  const code = (error as { code?: unknown }).code
+  return typeof code === 'string' && RACE_LOST_CODES.has(code)
+}
+
+export async function POST(request: NextRequest) {
+  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 organizationScope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const tenantId = auth.tenantId
+    const organizationId = organizationScope?.selectedId ?? auth.orgId
+
+    if (!tenantId || !organizationId) {
+      return NextResponse.json(
+        { error: 'Missing tenant or organization context' },
+        { status: 400 },
+      )
+    }
+
+    const roles = auth.roles ?? []
+    const query = parseWorkInboxQuery(new URL(request.url).searchParams, new Date())
+    const workInboxService = container.resolve<WorkInboxService>('workInboxService')
+
+    // The candidate list is a READ, so it is subject to the same §6.4 rule as
+    // every other read. Claiming is gated again by `taskHandler`, which owns
+    // queue membership and the compare-and-set.
+    const organizationIds = [organizationId]
+    const visibility = await resolveTaskVisibilityForRequest({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: roles },
+      organizationIds,
+      aclOrganizationId: organizationId,
+      entityTypes: await collectScopedTaskEntityTypes(em, { tenantId, organizationIds }),
+    })
+
+    const candidates = await workInboxService.listClaimableWorkInbox(
+      {
+        ...query,
+        kinds: [USER_TASK_INBOX_KIND],
+        roles,
+        statuses: ['PENDING'],
+        myWork: false,
+      },
+      {
+        scope: { tenantId, organizationIds, userId: auth.sub, roles, visibility },
+        resolve: <T,>(name: string): T => container.resolve<T>(name),
+      },
+    )
+
+    const taskHandler = container.resolve<TaskHandlerService>('taskHandler')
+
+    for (const candidate of candidates) {
+      try {
+        await taskHandler.claimUserTask(
+          em,
+          candidate.id,
+          auth.sub,
+          { tenantId, organizationId },
+          roles,
+        )
+      } catch (error) {
+        if (isRaceLost(error)) continue
+        throw error
+      }
+
+      const task = await em.findOne(UserTask, { id: candidate.id, tenantId, organizationId })
+      const claimed = task ? toUserTaskWorkInboxRow(task, query.now) : candidate
+
+      return NextResponse.json({
+        data: serializeWorkInboxRow(claimed),
+        message: 'Task claimed successfully',
+      })
+    }
+
+    return NextResponse.json({ data: null, message: 'No claimable work available' })
+  } catch (error) {
+    logger.error('Error claiming the next work item', { err: error })
+    return NextResponse.json(
+      {
+        error: 'Failed to claim the next work item',
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Claim the next work item',
+  methods: {
+    POST: {
+      summary: 'Claim the top claimable item from the work inbox',
+      description:
+        'Walks the caller\'s claimable queue in inbox order and claims the first item it wins. The claim is a conditional update, so concurrent callers never receive the same item — a caller that loses the race moves on to the next candidate. Returns null data when nothing is claimable.',
+      responses: [
+        { status: 200, description: 'The claimed item, or null when nothing was claimable', schema: workInboxClaimNextResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Missing tenant or organization context', schema: workflowErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
+        { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/api/work-inbox/route.ts

@@ -0,0 +1,153 @@
+/**
+ * Work Inbox API — one queue over every registered source (spec §6.2/§6.3).
+ *
+ * Endpoints:
+ * - GET /api/workflows/work-inbox — merged, filtered, ordered work items
+ *
+ * `GET /api/workflows/tasks` is deliberately left untouched: new routes are free
+ * (BACKWARD_COMPATIBILITY.md §7) but removing a shipped one is not, and the
+ * task list is still what a third party integrates against.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/core'
+import type { z } from 'zod'
+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 { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { serializeWorkInboxRow } from '../../lib/work-inbox/provider'
+import { parseWorkInboxQuery } from '../../lib/work-inbox/query'
+import type { WorkInboxService } from '../../lib/work-inbox/service'
+import {
+  collectScopedTaskEntityTypes,
+  resolveTaskVisibilityForRequest,
+} from '../../lib/task-visibility-request'
+import {
+  workflowsTag,
+  workInboxListQuerySchema,
+  workInboxListResponseSchema,
+  workflowErrorSchema,
+} from '../openapi'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.tasks.view'],
+}
+
+/**
+ * GET /api/workflows/work-inbox
+ *
+ * Query params: kind, module, entityType, role, priority, status, overdue,
+ * myWork (alias myTasks), assignedTo, workflowInstanceId, limit (max 100),
+ * offset.
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(request)
+
+    if (!auth) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const tenantId = auth.tenantId
+    if (!tenantId) {
+      return NextResponse.json({ error: 'Missing tenant context' }, { status: 400 })
+    }
+
+    const organizationScope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const orgFilter = resolveOrganizationScopeFilter(organizationScope, auth)
+
+    const { searchParams } = new URL(request.url)
+    const query = parseWorkInboxQuery(searchParams, new Date())
+
+    // §6.4, resolved ONCE for the whole merged page: one ACL load, one entity
+    // classification pass, one tenant-setting read, whatever a source does with
+    // it.
+    const em = container.resolve<EntityManager>('em')
+    const organizationIds = orgFilter.organizationIds ?? null
+    const visibility = await resolveTaskVisibilityForRequest({
+      container,
+      em,
+      auth: { userId: auth.sub, tenantId, roleNames: auth.roles ?? [] },
+      organizationIds,
+      aclOrganizationId: orgFilter.rbacOrganizationId,
+      entityTypes: await collectScopedTaskEntityTypes(em, { tenantId, organizationIds }),
+    })
+
+    const workInboxService = container.resolve<WorkInboxService>('workInboxService')
+    const result = await workInboxService.listWorkInbox(query, {
+      scope: {
+        tenantId,
+        organizationIds,
+        userId: auth.sub,
+        roles: auth.roles ?? [],
+        visibility,
+      },
+      resolve: <T,>(name: string): T => container.resolve<T>(name),
+    })
+
+    const body: z.infer<typeof workInboxListResponseSchema> = {
+      data: result.rows.map(serializeWorkInboxRow),
+      pagination: {
+        total: result.total,
+        limit: query.limit,
+        offset: query.offset,
+        hasMore: query.offset + result.rows.length < result.total,
+      },
+      meta: {
+        kinds: result.kinds,
+        degradedKinds: result.degradedKinds,
+      },
+      // Only ever populated for a caller who already knows the rows are there —
+      // a `workflows.tasks.view_all` holder or a superadmin. Its absence for
+      // everyone else discloses nothing, because the entity gate removed those
+      // rows in SQL before the query ran (design §3.6).
+      ...(result.entityHidden.length > 0
+        ? {
+            diagnostics: {
+              entityHidden: result.entityHidden,
+              entityHiddenCount: result.entityHidden.length,
+            },
+          }
+        : {}),
+    }
+
+    return NextResponse.json(body)
+  } catch (error) {
+    logger.error('Error listing the work inbox', { err: error })
+    return NextResponse.json(
+      {
+        error: 'Failed to list the work inbox',
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: workflowsTag,
+  summary: 'Work inbox',
+  methods: {
+    GET: {
+      summary: 'List work items across every registered source',
+      description:
+        'Merges every registered work-inbox source (workflow user tasks, plus any module that registers a provider) into one queue, filtered by kind/module/entity type/role/priority/status/overdue and ordered by priority, then due date, then age.',
+      query: workInboxListQuerySchema,
+      responses: [
+        { status: 200, description: 'Merged work items with pagination', schema: workInboxListResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Missing tenant context', schema: workflowErrorSchema },
+        { status: 401, description: 'Unauthorized', schema: workflowErrorSchema },
+        { status: 500, description: 'Internal server error', schema: workflowErrorSchema },
+      ],
+    },
+  },
+}

package/src/modules/workflows/backend/config/workflows/page.meta.ts

@@ -0,0 +1,33 @@
+import React from 'react'
+
+const workflowCommandsIcon = React.createElement(
+  'svg',
+  {
+    width: 16,
+    height: 16,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 2,
+    strokeLinecap: 'round',
+    strokeLinejoin: 'round',
+  },
+  React.createElement('rect', { x: 3, y: 3, width: 7, height: 7, rx: 1 }),
+  React.createElement('rect', { x: 14, y: 14, width: 7, height: 7, rx: 1 }),
+  React.createElement('path', { d: 'M10 6.5h4a3 3 0 0 1 3 3V14' }),
+)
+
+export const metadata = {
+  requireAuth: true,
+  // Reading the posture rides on definition authoring; the PUT behind this page
+  // is gated separately on `workflows.manage` by the API route.
+  requireFeatures: ['workflows.definitions.view'],
+  pageTitle: 'Workflow Commands',
+  pageTitleKey: 'workflows.commandSettings.pageTitle',
+  pageGroup: 'Module Configs',
+  pageGroupKey: 'settings.sections.moduleConfigs',
+  pageOrder: 12,
+  icon: workflowCommandsIcon,
+  pageContext: 'settings' as const,
+  breadcrumb: [{ label: 'Workflow Commands', labelKey: 'workflows.commandSettings.pageTitle' }],
+} as const

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

@@ -0,0 +1,12 @@
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { CommandSettingsPageClient } from '../../../components/settings/CommandSettingsPageClient'
+
+export default async function WorkflowCommandSettingsPage() {
+  return (
+    <Page>
+      <PageBody>
+        <CommandSettingsPageClient />
+      </PageBody>
+    </Page>
+  )
+}