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

package/src/modules/workflows/api/instances/failure-queue/route.ts

@@ -0,0 +1,197 @@
+/**
+ * Failure-queue triage API (spec §8.4)
+ *
+ * Endpoint:
+ * - GET /api/workflows/instances/failure-queue
+ *
+ * The triage set is "instances parked by a `failureQueue` directive PLUS FAILED
+ * instances". The list route cannot express that: its `attention` and `status`
+ * filters are ANDed, and this is a union.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import { raw } from '@mikro-orm/core'
+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 { WorkflowInstance } from '../../../data/entities'
+import { workflowInstanceResponseSchema, paginationSchema } from '../../openapi'
+import {
+  groupFailures,
+  matchesFailureGroup,
+  type TriageInstanceInput,
+} from '../../../lib/failure-grouping'
+import { WORKFLOW_ATTENTION_OUTCOMES } from '../../../lib/run-outcome'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.instances.view'],
+}
+
+/** Platform list cap. */
+export const FAILURE_QUEUE_PAGE_SIZE_MAX = 100
+
+/**
+ * How many rows the error grouping scans. Grouping normalizes each message in
+ * JS, so it cannot be a SQL `GROUP BY`; the response reports `scannedCount` and
+ * `groupsTruncated` rather than pretending the groups cover everything.
+ */
+export const FAILURE_GROUP_SCAN_LIMIT = 500
+
+function parsePositiveInt(rawValue: string | null, fallback: number): number {
+  if (rawValue === null) return fallback
+  const parsed = Number.parseInt(rawValue, 10)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function toTriageInput(instance: WorkflowInstance): TriageInstanceInput {
+  return {
+    id: instance.id,
+    workflowId: instance.workflowId,
+    status: instance.status,
+    errorMessage: instance.errorMessage ?? null,
+    attentionReason: instance.metadata?.attention?.reason ?? null,
+    outcome: instance.outcome ?? null,
+  }
+}
+
+export async function GET(request: NextRequest) {
+  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 orgFilter = resolveOrganizationScopeFilter(scope, auth)
+
+    if (!tenantId) {
+      return NextResponse.json({ error: 'Missing tenant context' }, { status: 400 })
+    }
+
+    const { searchParams } = new URL(request.url)
+    const workflowId = searchParams.get('workflowId')
+    const errorGroup = searchParams.get('errorGroup')
+    const requestedLimit = parsePositiveInt(searchParams.get('limit'), 50)
+    const limit = Math.min(Math.max(requestedLimit, 1), FAILURE_QUEUE_PAGE_SIZE_MAX)
+    const offset = Math.max(parsePositiveInt(searchParams.get('offset'), 0), 0)
+
+    const attentionPath = raw(`(metadata #>> '{attention,reason}')`)
+    const where: Record<string, unknown> = {
+      tenantId,
+      ...orgFilter.where,
+      // A simulation that "failed" is a report about a definition, never a run
+      // an operator must triage — and replaying one from here would start a
+      // REAL instance from a dry-run's context. The run list has excluded dry
+      // runs by default since spec §8.2; this union missed the same filter.
+      isDryRun: false,
+      // A `partial_failure` reached END and was written COMPLETED, so neither
+      // the status arm nor the attention arm reaches it — and a run nobody
+      // looks at because it said COMPLETED is exactly the failure the outcome
+      // verdict exists to remove. Third arm, same union.
+      $or: [
+        { status: 'FAILED' },
+        { outcome: { $in: [...WORKFLOW_ATTENTION_OUTCOMES] } },
+        { [attentionPath]: { $ne: null } },
+      ],
+    }
+    if (workflowId) where.workflowId = workflowId
+
+    // Grouping first, over a bounded scan, so the group counts describe the
+    // same set the caller is paging through.
+    const scanned = (await em.find(WorkflowInstance, where, {
+      orderBy: { createdAt: 'DESC' },
+      limit: FAILURE_GROUP_SCAN_LIMIT,
+    })) as WorkflowInstance[]
+    const scannedInputs = scanned.map(toTriageInput)
+    const groups = groupFailures(scannedInputs)
+
+    let rows = scanned
+    if (errorGroup) {
+      rows = scanned.filter((instance) => matchesFailureGroup(toTriageInput(instance), errorGroup))
+    }
+
+    const total = errorGroup
+      ? rows.length
+      : await em.count(WorkflowInstance, where)
+
+    return NextResponse.json({
+      data: rows.slice(offset, offset + limit),
+      groups,
+      grouping: {
+        scannedCount: scanned.length,
+        scanLimit: FAILURE_GROUP_SCAN_LIMIT,
+        truncated: scanned.length >= FAILURE_GROUP_SCAN_LIMIT,
+      },
+      pagination: {
+        total,
+        limit,
+        offset,
+        hasMore: offset + limit < total,
+      },
+    })
+  } catch (error) {
+    logger.error('Error listing the workflow failure queue', { err: error })
+    return NextResponse.json({ error: 'Failed to list the workflow failure queue' }, { status: 500 })
+  }
+}
+
+export const failureGroupSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+  count: z.number().int().nonnegative(),
+  workflowIds: z.array(z.string()),
+  instanceIds: z.array(z.string().uuid()),
+})
+
+export const openApi = {
+  methods: {
+    GET: {
+      summary: 'List the workflow failure queue',
+      description:
+        'Triage list of instances parked by a failure-queue error directive together with FAILED instances, plus normalized error groups so a batch of similar failures reads as one row.',
+      tags: ['Workflows'],
+      query: z.object({
+        workflowId: z.string().optional(),
+        errorGroup: z.string().optional().describe('Narrow the list to one normalized error group key.'),
+        limit: z.number().int().positive().max(FAILURE_QUEUE_PAGE_SIZE_MAX).default(50).optional(),
+        offset: z.number().int().min(0).default(0).optional(),
+      }),
+      responses: [
+        {
+          status: 200,
+          description: 'Failure queue',
+          schema: z.object({
+            data: z.array(workflowInstanceResponseSchema),
+            groups: z.array(failureGroupSchema),
+            grouping: z.object({
+              scannedCount: z.number().int().nonnegative(),
+              scanLimit: z.number().int().positive(),
+              truncated: z.boolean(),
+            }),
+            pagination: paginationSchema,
+          }),
+        },
+        {
+          status: 401,
+          description: 'Unauthorized',
+          schema: z.object({ error: z.string() }),
+        },
+        {
+          status: 500,
+          description: 'Internal server error',
+          schema: z.object({ error: z.string() }),
+        },
+      ],
+    },
+  },
+}

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

@@ -8,6 +8,8 @@
 
 import { NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
+import { raw } from '@mikro-orm/core'
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 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'
@@ -17,6 +19,7 @@ import {
   startWorkflowInputSchema,
   type StartWorkflowApiInput,
   workflowInstanceStatusSchema,
+  workflowRunOutcomeSchema,
 } from '../../data/validators'
 import {
   workflowInstanceResponseSchema,
@@ -25,6 +28,10 @@ import {
 } from '../openapi'
 import * as workflowExecutor from '../../lib/workflow-executor'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findWorkflowDefinition } from '../../lib/find-definition'
+import { isComponentKind } from '../../lib/component-guard'
+import { buildStartedAtRange } from '../../lib/instance-date-filter'
+import { isWorkflowRunOutcome } from '../../lib/run-outcome'
 
 const logger = createLogger('workflows')
 
@@ -62,12 +69,28 @@ export async function GET(request: NextRequest) {
     const { searchParams } = new URL(request.url)
     const workflowId = searchParams.get('workflowId')
     const status = searchParams.get('status')
+    const outcome = searchParams.get('outcome')
     const correlationKey = searchParams.get('correlationKey')
     const entityType = searchParams.get('entityType')
     const entityId = searchParams.get('entityId')
+    const parentInstanceId = searchParams.get('parentInstanceId')
+    const hasParent = parseBooleanToken(searchParams.get('hasParent'))
+    const attention = parseBooleanToken(searchParams.get('attention'))
+    const dryRun = parseBooleanToken(searchParams.get('dryRun'))
     const limit = parseInt(searchParams.get('limit') || '50')
     const offset = parseInt(searchParams.get('offset') || '0')
 
+    // Spec 8.3 run-list date filter. An unparseable bound is a 400, never a
+    // dropped predicate — a query built from an Invalid Date answers nothing
+    // while looking like it answered something.
+    const startedAtRange = buildStartedAtRange(
+      searchParams.get('startedFrom'),
+      searchParams.get('startedTo')
+    )
+    if (!startedAtRange.ok) {
+      return NextResponse.json({ error: startedAtRange.error }, { status: 400 })
+    }
+
     // Build where clause with tenant scoping
     const where: any = {
       tenantId,
@@ -88,10 +111,40 @@ export async function GET(request: NextRequest) {
       }
     }
 
+    // Outcome (the run's VERDICT) filters independently of `status` — the two
+    // answer different questions and a caller narrowing by one must not have
+    // the other narrowed for them. An unrecognised value is a 400 rather than a
+    // dropped predicate: a filter that silently matches everything is the exact
+    // invisible-omission failure this column exists to remove.
+    if (outcome) {
+      const requested = outcome.split(',').map((value) => value.trim()).filter(Boolean)
+      const invalid = requested.filter((value) => !isWorkflowRunOutcome(value))
+      if (invalid.length > 0) {
+        return NextResponse.json(
+          { error: `Unknown outcome: ${invalid.join(', ')}` },
+          { status: 400 }
+        )
+      }
+      if (requested.length === 1) {
+        where.outcome = requested[0]
+      } else if (requested.length > 1) {
+        where.outcome = { $in: requested }
+      }
+    }
+
     if (correlationKey) {
       where.correlationKey = correlationKey
     }
 
+    // Simulations are excluded from the run list by DEFAULT (spec section 8.2:
+    // "excludes the instance from KPIs"). A caller that wants them asks for
+    // them with `dryRun=true`; `dryRun=false` is the same as omitting it.
+    where.isDryRun = dryRun === true
+
+    if (startedAtRange.range) {
+      where.startedAt = startedAtRange.range
+    }
+
     // For JSONB metadata filtering, use $contains with explicit key-value pairs
     // MikroORM's dot notation creates table joins, not JSON access
     if (entityType || entityId) {
@@ -108,6 +161,34 @@ export async function GET(request: NextRequest) {
       }
     }
 
+    // Parent/sub-workflow filtering. The parent linkage is stored in
+    // metadata.labels.parentInstanceId (set by the SUB_WORKFLOW step handler).
+    // - parentInstanceId: return only the direct children of that parent
+    //   (JSONB containment; works for equality).
+    // - hasParent=false: return only top-level/standalone instances, and
+    //   hasParent=true only children. Absence of a key cannot be expressed via
+    //   $contains, so use a JSON-path predicate (null = IS NULL).
+    if (parentInstanceId) {
+      where.$and = where.$and || []
+      where.$and.push({
+        metadata: { $contains: { labels: { parentInstanceId } } },
+      })
+    } else if (hasParent !== null) {
+      where.$and = where.$and || []
+      // Unqualified column reference is unambiguous here — the instance list
+      // query is single-table (tenant/org scope adds predicates, not joins).
+      const parentIdPath = raw(`(metadata #>> '{labels,parentInstanceId}')`)
+      where.$and.push({ [parentIdPath]: hasParent ? { $ne: null } : null })
+    }
+
+    // Failure-queue park filter (spec 5.9): instances parked by a `failureQueue`
+    // error directive carry an engine-owned metadata.attention marker.
+    if (attention !== null) {
+      where.$and = where.$and || []
+      const attentionPath = raw(`(metadata #>> '{attention,reason}')`)
+      where.$and.push({ [attentionPath]: attention ? { $ne: null } : null })
+    }
+
     const [instances, total] = await em.findAndCount(
       WorkflowInstance,
       where,
@@ -196,10 +277,46 @@ export async function POST(request: NextRequest) {
 
     const input: StartWorkflowApiInput = validation.data
 
+    // Dry run (spec section 8.2) is the definition-author's test loop, not a
+    // way to start instances, so it carries its own grant on top of
+    // `instances.create` — the same feature the per-node Test step uses.
+    if (input.dryRun || input.stepThrough) {
+      const canTestRun = await rbacService.userHasAllFeatures(
+        auth.sub,
+        ['workflows.definitions.test_run'],
+        { tenantId, organizationId }
+      )
+      if (!canTestRun) {
+        return NextResponse.json(
+          { error: 'Insufficient permissions' },
+          { status: 403 }
+        )
+      }
+    }
+
+    // Reject standalone start of a reusable component. Components have no
+    // trigger and may only be invoked as a SUB_WORKFLOW; this guard lives on
+    // the manual-start path only, so sub-workflow invocation is unaffected.
+    const startDefinition = await findWorkflowDefinition(em, {
+      workflowId: input.workflowId,
+      version: input.version,
+      tenantId,
+      organizationId,
+    })
+    if (startDefinition && isComponentKind(startDefinition.kind)) {
+      return NextResponse.json(
+        { error: 'This workflow is a reusable component and cannot be started standalone; invoke it from a SUB_WORKFLOW step.' },
+        { status: 400 }
+      )
+    }
+
     // Server-authoritative actor; do not trust client-supplied metadata.initiatedBy.
+    // The step-through marker is engine-owned for the same reason: it is set
+    // ONLY from the feature-gated flag above, never from client metadata.
     const metadata = {
       ...input.metadata,
       initiatedBy: auth.sub,
+      ...(input.stepThrough ? { stepThrough: { enabled: true as const, releaseStepId: null } } : {}),
     }
 
     // Start workflow
@@ -209,12 +326,16 @@ export async function POST(request: NextRequest) {
       initialContext: input.initialContext || {},
       correlationKey: input.correlationKey,
       metadata,
+      isDryRun: input.dryRun === true,
       tenantId,
       organizationId,
     })
 
-    // Execute workflow in background (non-blocking for demo visibility)
-    // This allows the frontend to see step-by-step progress via polling
+    // Advance the workflow asynchronously after responding (non-blocking, so the
+    // frontend can poll step-by-step progress). This is a fire-and-forget task in
+    // this process — NOT a durable queue job — so it does not survive a process
+    // restart; the executor durably marks the instance FAILED on error, and the
+    // async-activity worker / retry endpoint resume any instance left mid-flight.
     setImmediate(async () => {
       try {
         // Create new container and EM for background execution
@@ -235,7 +356,7 @@ export async function POST(request: NextRequest) {
           execution: {
             status: instance.status,
             currentStep: instance.currentStepId,
-            message: 'Workflow execution started in background',
+            message: 'Workflow execution started',
           },
         },
         message: 'Workflow started successfully',
@@ -293,9 +414,15 @@ export const openApi = {
       query: z.object({
         workflowId: z.string().optional(),
         status: workflowInstanceStatusSchema.optional(),
+        outcome: workflowRunOutcomeSchema.optional().describe('Filter by the run VERDICT, independently of status. Comma-separated for several (e.g. partial_failure,failure). An unknown value is a 400.'),
         correlationKey: z.string().optional(),
         entityType: z.string().optional(),
         entityId: z.string().optional(),
+        parentInstanceId: z.string().optional().describe('Return only direct sub-workflow children of this parent instance.'),
+        hasParent: z.boolean().optional().describe('false = only top-level/standalone instances; true = only sub-workflow children. Ignored when parentInstanceId is set.'),
+        attention: z.boolean().optional().describe('true = only instances parked by a failure-queue error directive; false = only instances without an attention marker.'),
+        startedFrom: z.string().optional().describe('Lower bound on startedAt. A calendar day (YYYY-MM-DD) is taken from 00:00:00.000Z; a full ISO timestamp is taken verbatim.'),
+        startedTo: z.string().optional().describe('Upper bound on startedAt, inclusive. A calendar day (YYYY-MM-DD) covers the whole day up to 23:59:59.999Z.'),
         limit: z.number().int().positive().default(50).optional(),
         offset: z.number().int().min(0).default(0).optional(),
       }),
@@ -308,6 +435,11 @@ export const openApi = {
             pagination: paginationSchema,
           }),
         },
+        {
+          status: 400,
+          description: 'Invalid date range or unknown outcome',
+          schema: z.object({ error: z.string() }),
+        },
         {
           status: 401,
           description: 'Unauthorized',

package/src/modules/workflows/api/metrics/definitions/route.ts

@@ -0,0 +1,262 @@
+/**
+ * Per-definition operational KPIs (spec §8.5).
+ *
+ * Endpoint:
+ * - GET /api/workflows/metrics/definitions?window=7d&workflowIds=a,b,c
+ *
+ * Batch by design: the caller is a definitions list asking about the rows it
+ * currently has on screen, which is one request rather than one per row. This
+ * mirrors `agent_orchestrator`'s `/api/agent_orchestrator/metrics/agents?ids=`
+ * batch route, including its rollup-preferred / live-fallback rule.
+ *
+ * **Rollup or live, never a lie about which.** A stored row is used only when it
+ * covers the requested window, is fresher than `ROLLUP_FRESHNESS_MS`, and still
+ * parses against `workflowDefinitionMetricsSchema`; otherwise the window is
+ * recomputed from the source rows through the SAME function the worker uses.
+ * Every item reports `source` so a reader can tell a 15-minute-old aggregate
+ * from a live one, and `computedAt` so they can tell how old.
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
+import { WorkflowDefinitionMetricRollup } from '../../../data/entities'
+import {
+  workflowDefinitionMetricsQuerySchema,
+  workflowDefinitionMetricsSchema,
+  type WorkflowDefinitionMetricsPayload,
+} from '../../../data/metrics-validators'
+import {
+  WORKFLOW_ROLLUP_BUCKET_MS,
+  WORKFLOW_ROLLUP_WINDOW_KEYS,
+  WORKFLOW_ROLLUP_WINDOW_MS,
+  floorToRollupBucket,
+  type WorkflowRollupWindowKey,
+} from '../../../lib/metrics/definition-metrics'
+import {
+  computeDefinitionMetrics,
+  type MetricsReadScope,
+} from '../../../lib/metrics/rollup-service'
+
+const logger = createLogger('workflows')
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['workflows.metrics.view'],
+}
+
+/**
+ * How many definitions one request may ask about. Well under the platform's
+ * page-size ceiling of 100 because each miss costs a live recompute, and a page
+ * of 50 rows is already the largest list this module renders.
+ */
+export const WORKFLOW_METRICS_MAX_IDS = 50
+
+/**
+ * A rollup older than two bucket ticks is treated as stale and recomputed. Two
+ * rather than one so a single missed scheduler tick degrades to a slightly old
+ * number instead of to a full live recompute for every row on the page.
+ */
+export const ROLLUP_FRESHNESS_MS = 2 * WORKFLOW_ROLLUP_BUCKET_MS
+
+type MetricsItem = {
+  workflowId: string
+  window: WorkflowRollupWindowKey
+  windowStart: string
+  windowEnd: string
+  computedAt: string
+  source: 'rollup' | 'live'
+  /**
+   * The VALIDATED payload, not `DefinitionMetrics`: a rollup row written before
+   * a metric existed simply lacks that key, and the reader must see it absent
+   * rather than have a zero invented for it here. A live compute always carries
+   * every key, and is assignable to this wider shape.
+   */
+  metrics: WorkflowDefinitionMetricsPayload
+}
+
+function parseWorkflowIds(rawValue: string): string[] {
+  return Array.from(
+    new Set(
+      rawValue
+        .split(',')
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0),
+    ),
+  )
+}
+
+export async function GET(request: NextRequest) {
+  try {
+    const container = await createRequestContainer()
+    const em = container.resolve('em') as EntityManager
+    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 orgScope = await resolveOrganizationScopeForRequest({ container, auth, request })
+    const orgFilter = resolveOrganizationScopeFilter(orgScope, auth)
+    const readScope: MetricsReadScope = {
+      tenantId,
+      organizationIds: orgFilter.organizationIds,
+    }
+    // A stored rollup row is per-organization, so it can answer only a
+    // single-organization read. A multi-organization or tenant-wide scope is
+    // live-computed instead: counts would sum, but a percentile cannot be
+    // recovered from several stored percentiles, and a KPI that is right about
+    // three numbers and wrong about the fourth is worse than a slower one.
+    const singleOrganizationId =
+      orgFilter.organizationIds?.length === 1 ? orgFilter.organizationIds[0] : null
+
+    const { searchParams } = new URL(request.url)
+    const parsed = workflowDefinitionMetricsQuerySchema.safeParse({
+      window: searchParams.get('window') ?? undefined,
+      workflowIds: searchParams.get('workflowIds') ?? undefined,
+    })
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: 'Invalid query', details: parsed.error.flatten() },
+        { status: 400 },
+      )
+    }
+
+    const windowKey = parsed.data.window as WorkflowRollupWindowKey
+    const workflowIds = parseWorkflowIds(parsed.data.workflowIds)
+    if (workflowIds.length === 0) {
+      return NextResponse.json({ error: 'workflowIds must name at least one workflow' }, { status: 400 })
+    }
+    if (workflowIds.length > WORKFLOW_METRICS_MAX_IDS) {
+      return NextResponse.json(
+        { error: `workflowIds accepts at most ${WORKFLOW_METRICS_MAX_IDS} ids` },
+        { status: 400 },
+      )
+    }
+
+    const now = new Date()
+    const windowEndMs = floorToRollupBucket(now.getTime())
+    const windowEnd = new Date(windowEndMs)
+    const windowStart = new Date(windowEndMs - WORKFLOW_ROLLUP_WINDOW_MS[windowKey])
+
+    const freshestByWorkflowId = new Map<string, WorkflowDefinitionMetricRollup>()
+    if (singleOrganizationId) {
+      const storedRows = await em.find(
+        WorkflowDefinitionMetricRollup,
+        {
+          tenantId,
+          organizationId: singleOrganizationId,
+          workflowId: { $in: workflowIds },
+          windowKey,
+        },
+        { orderBy: { computedAt: 'DESC' } },
+      )
+      for (const row of storedRows) {
+        if (!freshestByWorkflowId.has(row.workflowId)) freshestByWorkflowId.set(row.workflowId, row)
+      }
+    }
+
+    const data: MetricsItem[] = []
+    for (const workflowId of workflowIds) {
+      const stored = freshestByWorkflowId.get(workflowId)
+      const isFresh = stored ? now.getTime() - stored.computedAt.getTime() <= ROLLUP_FRESHNESS_MS : false
+      const validated = stored && isFresh ? workflowDefinitionMetricsSchema.safeParse(stored.metrics) : null
+
+      if (stored && validated?.success) {
+        data.push({
+          workflowId,
+          window: windowKey,
+          windowStart: stored.windowStart.toISOString(),
+          windowEnd: stored.windowEnd.toISOString(),
+          computedAt: stored.computedAt.toISOString(),
+          source: 'rollup',
+          metrics: validated.data,
+        })
+        continue
+      }
+
+      const metrics = await computeDefinitionMetrics(em, readScope, {
+        workflowId,
+        windowStart,
+        windowEnd,
+      })
+      data.push({
+        workflowId,
+        window: windowKey,
+        windowStart: windowStart.toISOString(),
+        windowEnd: windowEnd.toISOString(),
+        computedAt: now.toISOString(),
+        source: 'live',
+        metrics,
+      })
+    }
+
+    return NextResponse.json({ data })
+  } catch (error) {
+    logger.error('Error reading workflow definition metrics', { err: error })
+    return NextResponse.json({ error: 'Failed to read workflow definition metrics' }, { status: 500 })
+  }
+}
+
+const metricsItemSchema = z.object({
+  workflowId: z.string(),
+  window: z.enum(WORKFLOW_ROLLUP_WINDOW_KEYS as [string, ...string[]]),
+  windowStart: z.string(),
+  windowEnd: z.string(),
+  computedAt: z.string(),
+  source: z.enum(['rollup', 'live']),
+  metrics: workflowDefinitionMetricsSchema,
+})
+
+export const openApi = {
+  methods: {
+    GET: {
+      summary: 'Read per-definition workflow operational KPIs',
+      description:
+        'Batch KPI read for the named workflow ids over a sliding window: runs started, terminal runs by outcome, success rate, run-duration p50/p95 and task SLA hit-rate. Dry runs are excluded from every figure. Served from the precomputed rollup when one is fresh, recomputed live otherwise; each item reports which.',
+      tags: ['Workflows'],
+      query: z.object({
+        window: z
+          .enum(WORKFLOW_ROLLUP_WINDOW_KEYS as [string, ...string[]])
+          .default('7d')
+          .optional()
+          .describe('Sliding window length.'),
+        workflowIds: z
+          .string()
+          .describe(
+            `Comma-separated logical workflow ids, at most ${WORKFLOW_METRICS_MAX_IDS} per request.`,
+          ),
+      }),
+      responses: [
+        {
+          status: 200,
+          description: 'Per-definition metrics',
+          schema: z.object({ data: z.array(metricsItemSchema) }),
+        },
+        {
+          status: 400,
+          description: 'Invalid query or missing tenant context',
+          schema: z.object({ error: z.string() }),
+        },
+        {
+          status: 401,
+          description: 'Unauthorized',
+          schema: z.object({ error: z.string() }),
+        },
+        {
+          status: 500,
+          description: 'Internal server error',
+          schema: z.object({ error: z.string() }),
+        },
+      ],
+    },
+  },
+}