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

package/src/modules/workflows/lib/ledger-schema-flatten.ts

@@ -0,0 +1,137 @@
+/**
+ * Workflows Module - Zod-to-ledger schema flattener (spec
+ * 2026-07-26-workflows-ux-redesign.md section 3.1).
+ *
+ * Pure translation of an activity output Zod schema (e.g. a command's
+ * `outputSchema` resolved by UPDATE_ENTITY's outputContract) into the minimal
+ * `LedgerContract` shape `computeContextLedger` consumes through its injected
+ * `resolveOutputContract` seam. Only value dependency is zod itself
+ * (browser-safe, already loaded by the validators) — no React, no ORM, no DI.
+ *
+ * Mapping rules, honest by construction:
+ * - Only object roots flatten: each property becomes a dot-path entry
+ *   (`customer.address.city`). Non-object roots (scalars, arrays, effects)
+ *   return the string `'unknown'` because the ledger namespaces contract
+ *   entries under a result key and a root scalar has no property path.
+ * - Scalars map string→text, number→number, boolean→boolean, enum→select,
+ *   date→date. Pass-through wrappers that do not hide the inner type
+ *   (optional, nullable, default, readonly, nonoptional, catch) are unwrapped
+ *   first.
+ * - Arrays of objects collapse to one `object`-typed entry for the array path
+ *   — indices are never exploded. Arrays of anything else are `unknown`.
+ * - Nested objects recurse up to `maxDepth` path segments (default 3); an
+ *   object property sitting at the cap is emitted as one `object`-typed entry
+ *   instead of recursing.
+ * - Anything unmappable — unions of mixed kinds, records, pipes/transforms
+ *   that hide the inner type, literals — becomes a named `unknown` entry
+ *   rather than a guessed type; an empty or fully-unresolvable shape returns
+ *   `'unknown'` outright.
+ */
+
+import { ZodType } from 'zod'
+import type { ZodTypeAny } from 'zod'
+import type { LedgerContract, LedgerType } from './context-ledger'
+
+export interface FlattenSchemaOptions {
+  maxDepth?: number
+}
+
+const DEFAULT_MAX_DEPTH = 3
+const WRAPPER_UNWRAP_CAP = 8
+
+const SCALAR_KIND_MAP: Record<string, LedgerType> = {
+  string: 'text',
+  number: 'number',
+  boolean: 'boolean',
+  enum: 'select',
+  date: 'date',
+}
+
+const WRAPPER_KINDS = new Set([
+  'optional',
+  'nullable',
+  'default',
+  'readonly',
+  'nonoptional',
+  'catch',
+])
+
+type UnknownRecord = Record<string, unknown>
+
+type ContractEntry = LedgerContract['entries'][number]
+
+function isZodSchema(value: unknown): value is ZodTypeAny {
+  return value instanceof ZodType
+}
+
+function defOf(schema: ZodTypeAny): UnknownRecord {
+  const def = (schema as unknown as { def?: unknown }).def
+  return typeof def === 'object' && def !== null ? (def as UnknownRecord) : {}
+}
+
+function kindOf(schema: ZodTypeAny): string {
+  const kind = defOf(schema).type
+  return typeof kind === 'string' ? kind : 'unknown'
+}
+
+function unwrapSchema(schema: ZodTypeAny): ZodTypeAny {
+  let current = schema
+  for (let pass = 0; pass < WRAPPER_UNWRAP_CAP; pass += 1) {
+    if (!WRAPPER_KINDS.has(kindOf(current))) return current
+    const inner = defOf(current).innerType
+    if (!isZodSchema(inner)) return current
+    current = inner
+  }
+  return current
+}
+
+function arrayEntryType(arraySchema: ZodTypeAny): LedgerType {
+  const element = defOf(arraySchema).element
+  if (isZodSchema(element) && kindOf(unwrapSchema(element)) === 'object') return 'object'
+  return 'unknown'
+}
+
+function collectObjectEntries(
+  objectSchema: ZodTypeAny,
+  prefix: string,
+  depth: number,
+  maxDepth: number,
+  entries: ContractEntry[],
+): void {
+  const shape = defOf(objectSchema).shape
+  if (typeof shape !== 'object' || shape === null) return
+  for (const [name, property] of Object.entries(shape as UnknownRecord)) {
+    if (!name || !isZodSchema(property)) continue
+    const path = prefix ? `${prefix}.${name}` : name
+    const resolved = unwrapSchema(property)
+    const kind = kindOf(resolved)
+    const scalarType = SCALAR_KIND_MAP[kind]
+    if (scalarType) {
+      entries.push({ path, type: scalarType })
+    } else if (kind === 'object') {
+      if (depth < maxDepth) {
+        collectObjectEntries(resolved, path, depth + 1, maxDepth, entries)
+      } else {
+        entries.push({ path, type: 'object' })
+      }
+    } else if (kind === 'array') {
+      entries.push({ path, type: arrayEntryType(resolved) })
+    } else {
+      entries.push({ path, type: 'unknown' })
+    }
+  }
+}
+
+export function flattenSchemaToContract(
+  schema: ZodTypeAny,
+  options?: FlattenSchemaOptions,
+): LedgerContract | 'unknown' {
+  const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH
+  if (maxDepth < 1) return 'unknown'
+  const root = unwrapSchema(schema)
+  if (kindOf(root) !== 'object') return 'unknown'
+  const entries: ContractEntry[] = []
+  collectObjectEntries(root, '', 1, maxDepth, entries)
+  if (entries.length === 0) return 'unknown'
+  return { entries }
+}

package/src/modules/workflows/lib/metrics/definition-metrics.ts

@@ -0,0 +1,268 @@
+/**
+ * Per-definition operational KPIs (spec §8.5) — the PURE arithmetic half.
+ *
+ * This module contains no ORM, DI, React or registry import, so every rule it
+ * encodes is unit-testable without a database. `lib/metrics/rollup-service.ts`
+ * owns the queries and the upsert; this file owns what the numbers MEAN.
+ *
+ * Three honesty rules govern what may appear here:
+ *
+ * 1. **A metric is computed only from a column the engine actually writes.**
+ *    `StepInstance.executionTimeMs` is deliberately NOT used: `exitStep` writes
+ *    it on the COMPLETED path only, while every FAILED path
+ *    (`step-handler`, `activity-worker-handler`, `condition-handler`) sets
+ *    `exitedAt` and leaves it null. A p95 over that column would silently be a
+ *    success-only latency wearing the name of a step latency. Run duration is
+ *    measured instead, from `startedAt` → the terminal timestamp, both of which
+ *    the engine always writes.
+ * 2. **Dry runs never count.** `WorkflowInstance.isDryRun` is the flag
+ *    (spec §8.2: "excludes the instance from KPIs"); the caller filters on it
+ *    and the shapes below carry only already-filtered rows.
+ * 3. **A denominator is always reported next to a rate.** `successRate` without
+ *    `runsTerminal` and `taskSlaHitRate` without `tasksWithDeadline` are both
+ *    unreadable — 100% over one run is not the same claim as 100% over 4,000.
+ * 4. **A run that tolerated a failure is not a success.** `successRate` counts
+ *    the run's VERDICT, not its lifecycle status: a `partial_failure` reached
+ *    END but did not do everything it was asked to. It is reported as its own
+ *    number (`runsPartialFailure`) rather than folded into either bucket.
+ */
+
+import type { WorkflowRunOutcome } from '../run-outcome'
+
+/** Rollup window lengths, mirroring `AgentMetricRollup`'s window vocabulary. */
+export const WORKFLOW_ROLLUP_WINDOW_MS = {
+  '24h': 24 * 60 * 60 * 1000,
+  '7d': 7 * 24 * 60 * 60 * 1000,
+  '30d': 30 * 24 * 60 * 60 * 1000,
+} as const
+
+export type WorkflowRollupWindowKey = keyof typeof WORKFLOW_ROLLUP_WINDOW_MS
+
+export const WORKFLOW_ROLLUP_WINDOW_KEYS = Object.keys(
+  WORKFLOW_ROLLUP_WINDOW_MS,
+) as WorkflowRollupWindowKey[]
+
+/**
+ * Bucket the window boundaries snap to. Recomputing the SAME `windowStart` is
+ * what makes a repeated rollup pass an overwrite rather than a second row, so
+ * the bucket — not the wall clock — is the row's identity.
+ */
+export const WORKFLOW_ROLLUP_BUCKET_MS = 15 * 60 * 1000
+
+/** Snap a timestamp down to the rollup bucket grid. */
+export function floorToRollupBucket(epochMs: number): number {
+  return Math.floor(epochMs / WORKFLOW_ROLLUP_BUCKET_MS) * WORKFLOW_ROLLUP_BUCKET_MS
+}
+
+/**
+ * Terminal statuses a run can reach.
+ *
+ * `COMPENSATED` used to be absent because the engine wrote it NO terminal
+ * timestamp — `compensation-handler` flipped the status and `completeWorkflow`
+ * returned before its own `completedAt` assignment — so a compensated run had
+ * no instant to attribute to any window. The run-outcome write now stamps that
+ * timestamp on the compensating path, so a compensated run finally belongs to
+ * the window it terminated in. Rows compensated BEFORE that fix still carry a
+ * null timestamp and, exactly as before, fall into no window at all: nothing is
+ * backfilled.
+ */
+export const WORKFLOW_TERMINAL_STATUSES = ['COMPLETED', 'FAILED', 'CANCELLED', 'COMPENSATED'] as const
+
+export type WorkflowTerminalStatus = (typeof WORKFLOW_TERMINAL_STATUSES)[number]
+
+/** One terminal run, already scoped and already dry-run filtered by the caller. */
+export type TerminalRunSample = {
+  status: string
+  /**
+   * The run's VERDICT (`WorkflowInstance.outcome`), or null for a row written
+   * before outcomes existed. Null is NOT read as `success`: a pre-upgrade
+   * COMPLETED run counts exactly as it did before, so upgrading does not
+   * retroactively rewrite a window's history.
+   */
+  outcome?: WorkflowRunOutcome | null
+  startedAt: Date | null
+  /** `completedAt` for COMPLETED/FAILED/COMPENSATED, `cancelledAt` for CANCELLED. */
+  terminalAt: Date | null
+}
+
+/** One completed task carrying an authored deadline. */
+export type TaskDeadlineSample = {
+  dueDate: Date | null
+  completedAt: Date | null
+}
+
+export type DefinitionMetrics = {
+  /** Runs whose `startedAt` falls in the window. */
+  runsStarted: number
+  /** Runs whose terminal timestamp falls in the window — the rate denominator. */
+  runsTerminal: number
+  runsCompleted: number
+  runsFailed: number
+  runsCancelled: number
+  /**
+   * COMPLETED runs whose verdict is `partial_failure` — they reached END while
+   * tolerating at least one activity or step failure.
+   *
+   * Its own number, folded into NEITHER bucket. It is not added to `runsFailed`
+   * (the run did reach END, and a failure-queue count that included it would
+   * disagree with the lifecycle) and it is excluded from `successRate`'s
+   * numerator (the work it skipped never happened). It stays in `runsTerminal`,
+   * so the denominators still add up.
+   */
+  runsPartialFailure: number
+  /**
+   * Runs rolled back by compensation. Its own number for the same reason
+   * `runsPartialFailure` is: a compensated run is neither a success nor an
+   * ordinary failure, and folding it into either would misstate both.
+   */
+  runsCompensated: number
+  /**
+   * `(runsCompleted - runsPartialFailure) / runsTerminal`, or null when nothing
+   * terminated.
+   */
+  successRate: number | null
+  /** Terminal runs that also had a usable `startedAt` — the duration denominator. */
+  durationSampleCount: number
+  avgDurationMs: number | null
+  p50DurationMs: number | null
+  p95DurationMs: number | null
+  /** Completed tasks that carried a `dueDate` — the SLA denominator. */
+  tasksWithDeadline: number
+  tasksMetDeadline: number
+  /** `tasksMetDeadline / tasksWithDeadline`, or null when no task had a deadline. */
+  taskSlaHitRate: number | null
+}
+
+export const EMPTY_DEFINITION_METRICS: DefinitionMetrics = {
+  runsStarted: 0,
+  runsTerminal: 0,
+  runsCompleted: 0,
+  runsFailed: 0,
+  runsCancelled: 0,
+  runsPartialFailure: 0,
+  runsCompensated: 0,
+  successRate: null,
+  durationSampleCount: 0,
+  avgDurationMs: null,
+  p50DurationMs: null,
+  p95DurationMs: null,
+  tasksWithDeadline: 0,
+  tasksMetDeadline: 0,
+  taskSlaHitRate: null,
+}
+
+/**
+ * Nearest-rank percentile over an unsorted sample; null when empty.
+ *
+ * Nearest rank (`percentile_disc` semantics) rather than interpolation, for the
+ * same reason `agent_orchestrator`'s `percentileOf` chose it: every value it
+ * returns is a duration some run actually took, which is what an operator
+ * clicking through to that run needs to be true. It is also the variant that
+ * behaves sanely on the small samples this rollup normally sees — a definition
+ * with three runs a day has no meaningful interpolant.
+ *
+ * The rank is `ceil(fraction * n) - 1`, clamped into range, so p95 of a
+ * one-element sample is that element and p95 of a 20-element sample is the
+ * 19th-largest — never an off-by-one past the end of the array.
+ */
+export function percentileOf(values: number[], fraction: number): number | null {
+  if (values.length === 0) return null
+  const sorted = [...values].sort((left, right) => left - right)
+  const rank = Math.min(sorted.length - 1, Math.max(0, Math.ceil(fraction * sorted.length) - 1))
+  return sorted[rank]
+}
+
+/** Mean of a sample, rounded to whole milliseconds; null when empty. */
+export function meanOf(values: number[]): number | null {
+  if (values.length === 0) return null
+  const total = values.reduce((sum, value) => sum + value, 0)
+  return Math.round(total / values.length)
+}
+
+/**
+ * A rate reported as a fraction in [0, 1], or null when the denominator is 0.
+ *
+ * Null rather than 0: "no runs finished" and "every run failed" are opposite
+ * facts and a KPI card that paints both as 0% is worse than one that says it
+ * has nothing to show.
+ */
+export function rateOf(numerator: number, denominator: number): number | null {
+  if (denominator <= 0) return null
+  return numerator / denominator
+}
+
+/**
+ * Wall-clock run duration, or null when either end is missing or the pair is
+ * inverted (a clock skew or a hand-edited row must not contribute a negative
+ * sample that drags a mean below zero).
+ */
+export function runDurationMs(run: TerminalRunSample): number | null {
+  if (!run.startedAt || !run.terminalAt) return null
+  const durationMs = run.terminalAt.getTime() - run.startedAt.getTime()
+  if (!Number.isFinite(durationMs) || durationMs < 0) return null
+  return durationMs
+}
+
+/** True when a completed task landed on or before its authored deadline. */
+export function taskMetDeadline(task: TaskDeadlineSample): boolean {
+  if (!task.dueDate || !task.completedAt) return false
+  return task.completedAt.getTime() <= task.dueDate.getTime()
+}
+
+export type DefinitionMetricsInput = {
+  runsStarted: number
+  terminalRuns: TerminalRunSample[]
+  completedTasks: TaskDeadlineSample[]
+}
+
+/**
+ * Fold the sampled rows into one window's metrics.
+ *
+ * Pure and total: given the same input it returns the same output, which is
+ * precisely what lets the rollup worker recompute a bucket instead of
+ * incrementing it.
+ */
+export function buildDefinitionMetrics(input: DefinitionMetricsInput): DefinitionMetrics {
+  const terminalRuns = input.terminalRuns
+  let runsCompleted = 0
+  let runsFailed = 0
+  let runsCancelled = 0
+  let runsPartialFailure = 0
+  let runsCompensated = 0
+  const durations: number[] = []
+
+  for (const run of terminalRuns) {
+    if (run.status === 'COMPLETED') {
+      runsCompleted += 1
+      if (run.outcome === 'partial_failure') runsPartialFailure += 1
+    }
+    else if (run.status === 'FAILED') runsFailed += 1
+    else if (run.status === 'CANCELLED') runsCancelled += 1
+    else if (run.status === 'COMPENSATED') runsCompensated += 1
+    const duration = runDurationMs(run)
+    if (duration !== null) durations.push(duration)
+  }
+
+  const tasksWithDeadline = input.completedTasks.filter((task) => task.dueDate !== null).length
+  const tasksMetDeadline = input.completedTasks.filter(
+    (task) => task.dueDate !== null && taskMetDeadline(task),
+  ).length
+
+  return {
+    runsStarted: input.runsStarted,
+    runsTerminal: terminalRuns.length,
+    runsCompleted,
+    runsFailed,
+    runsCancelled,
+    runsPartialFailure,
+    runsCompensated,
+    successRate: rateOf(runsCompleted - runsPartialFailure, terminalRuns.length),
+    durationSampleCount: durations.length,
+    avgDurationMs: meanOf(durations),
+    p50DurationMs: percentileOf(durations, 0.5),
+    p95DurationMs: percentileOf(durations, 0.95),
+    tasksWithDeadline,
+    tasksMetDeadline,
+    taskSlaHitRate: rateOf(tasksMetDeadline, tasksWithDeadline),
+  }
+}

package/src/modules/workflows/lib/metrics/metrics-display.ts

@@ -0,0 +1,57 @@
+/**
+ * Presentation rules for the per-definition KPIs (spec §8.5) — PURE.
+ *
+ * Separate from the arithmetic so "what does a 60% success rate LOOK like" is
+ * testable without a canvas, and separate from the cell component so the
+ * thresholds live in one place rather than in three `className` ternaries.
+ */
+
+export type MetricTone = 'success' | 'warning' | 'error' | 'neutral'
+
+/**
+ * Thresholds for the success-rate and SLA-hit-rate tones.
+ *
+ * Deliberately generous at the top: a workflow that fails one run in twenty is
+ * not healthy, and painting 95% green would make the column decorative.
+ */
+export const METRIC_RATE_GOOD = 0.95
+export const METRIC_RATE_FAIR = 0.8
+
+/**
+ * Tone for a rate in [0, 1].
+ *
+ * `null` — no denominator — is NEUTRAL, never an error tone: "nothing terminated in
+ * this window" is not a failure, and a red cell would send an operator hunting
+ * for a problem that does not exist.
+ */
+export function rateTone(rate: number | null): MetricTone {
+  if (rate === null) return 'neutral'
+  if (rate >= METRIC_RATE_GOOD) return 'success'
+  if (rate >= METRIC_RATE_FAIR) return 'warning'
+  return 'error'
+}
+
+/**
+ * A rate as a whole-percent string, or `null` when there is no denominator.
+ *
+ * Whole percents because the underlying sample is usually tens of runs, where a
+ * decimal place implies a precision the sample does not have.
+ */
+export function formatRate(rate: number | null): string | null {
+  if (rate === null) return null
+  return `${Math.round(rate * 100)}%`
+}
+
+/**
+ * DS token classes per tone.
+ *
+ * Colour is never the only carrier — every cell using these also renders the
+ * number itself and an `sr-only` name — but the tone still has to come from
+ * status tokens rather than raw Tailwind shades.
+ */
+export const METRIC_TONE_CLASS: Record<MetricTone, string> = {
+  success: 'text-status-success-text',
+  warning: 'text-status-warning-text',
+  error: 'text-status-error-text',
+  neutral: 'text-muted-foreground',
+}

package/src/modules/workflows/lib/metrics/rollup-schedule.ts

@@ -0,0 +1,26 @@
+/**
+ * Scheduling constants for the per-definition KPI rollup (spec §8.5).
+ *
+ * Kept in their own module so `setup.ts` can import them without dragging in
+ * the ORM entities that `rollup-service.ts` pulls: tenant setup runs on a path
+ * where importing the whole engine would be a needless cost.
+ */
+
+/**
+ * Queue the scheduled tick targets. Duplicated as a string literal in
+ * `workers/workflow-definition-metric-rollup.worker.ts` because the generator's
+ * AST extractor cannot resolve an imported queue name — see the NOTE there.
+ * `workers/__tests__/definition-metric-rollup.worker.test.ts` asserts the two
+ * spellings stay identical, so the duplication cannot drift.
+ */
+export const WORKFLOW_DEFINITION_METRIC_ROLLUP_QUEUE = 'workflow-definition-metric-rollup'
+
+/**
+ * How often a rollup pass runs, as a `@open-mercato/scheduler` interval.
+ *
+ * Matched to `WORKFLOW_ROLLUP_BUCKET_MS` (15 minutes): ticking faster than the
+ * bucket only rewrites the same row with the same numbers, and ticking slower
+ * leaves buckets with no row at all, which the read route then has to
+ * live-compute.
+ */
+export const WORKFLOW_DEFINITION_METRIC_ROLLUP_INTERVAL = '900s'