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

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

@@ -0,0 +1,292 @@
+/**
+ * Per-definition KPI rollup (spec §8.5) — the data-access half.
+ *
+ * The arithmetic lives in `./definition-metrics` and is pure; everything here is
+ * about reading the right rows and writing the bucket exactly once.
+ *
+ * **Idempotency contract.** A pass never increments anything. It snaps the
+ * window boundaries to `WORKFLOW_ROLLUP_BUCKET_MS`, RECOMPUTES the whole window
+ * from the source rows, and writes the result at
+ * `(tenantId, organizationId, workflowId, windowKey, windowStart)` — a key the
+ * database enforces as unique. Running the same pass twice inside one bucket
+ * therefore produces byte-identical rows and never a duplicate; running it after
+ * the bucket rolls over produces a NEW row for the new bucket rather than
+ * mutating history.
+ *
+ * **Scoping contract.** Every query below carries `tenantId` AND
+ * `organizationId`. The worker enumerates scopes and calls this per scope; it
+ * never widens a query to "all tenants" and then partitions in JS.
+ *
+ * **Dry-run contract.** `isDryRun: false` is on every instance query, and the
+ * task query reaches tasks only through the ids of those instances — so a dry
+ * run cannot contribute a run, a duration or an SLA sample by any path.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { UserTask, WorkflowDefinitionMetricRollup, WorkflowInstance } from '../../data/entities'
+import {
+  WORKFLOW_ROLLUP_WINDOW_KEYS,
+  WORKFLOW_ROLLUP_WINDOW_MS,
+  WORKFLOW_TERMINAL_STATUSES,
+  buildDefinitionMetrics,
+  floorToRollupBucket,
+  type DefinitionMetrics,
+  type WorkflowRollupWindowKey,
+} from './definition-metrics'
+
+const logger = createLogger('workflows')
+
+export type RollupScope = {
+  tenantId: string
+  organizationId: string
+}
+
+/**
+ * Read-side scope.
+ *
+ * A rollup ROW is always per-organization, but a reader's organization scope can
+ * legitimately cover several organizations (`filterIds`) or every organization in
+ * the tenant (an unrestricted scope). Counts across organizations would sum, but
+ * a percentile would not — a p95 cannot be recovered from three stored p95s — so
+ * a multi-organization read is answered by live compute over the resolved set
+ * rather than by pretending the rollup covers it. `organizationIds: undefined`
+ * means "every organization in this tenant"; `tenantId` is never optional, so no
+ * shape of this type can escape the tenant.
+ */
+export type MetricsReadScope = {
+  tenantId: string
+  organizationIds?: string[]
+}
+
+function organizationFilter(scope: MetricsReadScope): { organizationId?: { $in: string[] } } {
+  return scope.organizationIds ? { organizationId: { $in: scope.organizationIds } } : {}
+}
+
+export type RollupWindowBounds = {
+  windowKey: WorkflowRollupWindowKey
+  windowStart: Date
+  windowEnd: Date
+}
+
+/**
+ * How many instances one window's duration sample may draw from. A percentile
+ * needs the values, not a count, so this is the one query that cannot be a
+ * `COUNT(*)`; the cap keeps a pathological definition from pulling a month of
+ * rows into memory. Exceeding it biases the sample toward the NEWEST runs,
+ * which is the least misleading truncation available and is reported to the
+ * reader through `durationSampleCount` sitting beside the percentile.
+ */
+export const ROLLUP_DURATION_SAMPLE_LIMIT = 5000
+
+/** How many tasks one window's SLA hit-rate may draw from, for the same reason. */
+export const ROLLUP_TASK_SAMPLE_LIMIT = 5000
+
+/** Resolve the bucket-aligned bounds of every rollup window at `nowMs`. */
+export function resolveWindowBounds(nowMs: number): RollupWindowBounds[] {
+  const windowEndMs = floorToRollupBucket(nowMs)
+  return WORKFLOW_ROLLUP_WINDOW_KEYS.map((windowKey) => ({
+    windowKey,
+    windowStart: new Date(windowEndMs - WORKFLOW_ROLLUP_WINDOW_MS[windowKey]),
+    windowEnd: new Date(windowEndMs),
+  }))
+}
+
+/**
+ * Logical workflow ids that have any non-dry-run activity in the widest window.
+ *
+ * Bounded by the widest window rather than by all history so a workflow retired
+ * a year ago stops costing a row every quarter of an hour.
+ */
+export async function listActiveWorkflowIds(
+  em: EntityManager,
+  scope: RollupScope,
+  since: Date,
+): Promise<string[]> {
+  const rows = await em.find(
+    WorkflowInstance,
+    {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      isDryRun: false,
+      deletedAt: null,
+      startedAt: { $gte: since },
+    },
+    { fields: ['workflowId'] },
+  )
+  return Array.from(new Set(rows.map((row) => row.workflowId))).sort((left, right) =>
+    left.localeCompare(right),
+  )
+}
+
+/**
+ * Compute one workflow's metrics for one window, straight from the source rows.
+ *
+ * Also the live-compute fallback the read route uses when no fresh rollup row
+ * exists, which is what keeps the two paths from disagreeing: there is one
+ * implementation of "what do these numbers mean", not two.
+ */
+export async function computeDefinitionMetrics(
+  em: EntityManager,
+  scope: MetricsReadScope,
+  args: { workflowId: string; windowStart: Date; windowEnd: Date },
+): Promise<DefinitionMetrics> {
+  const baseScope = {
+    tenantId: scope.tenantId,
+    ...organizationFilter(scope),
+    workflowId: args.workflowId,
+    isDryRun: false,
+    deletedAt: null,
+  } as const
+  const window = { $gte: args.windowStart, $lt: args.windowEnd }
+
+  const runsStarted = await em.count(WorkflowInstance, {
+    ...baseScope,
+    startedAt: window,
+  })
+
+  // A run is "terminal in this window" by its terminal TIMESTAMP, never by its
+  // status alone — a run that failed last month is not this week's failure.
+  // `completedAt` covers COMPLETED, FAILED and COMPENSATED, `cancelledAt`
+  // covers CANCELLED. A run compensated before the engine started stamping a
+  // terminal timestamp has neither, so it matches nothing here and falls into
+  // no window — unchanged, and deliberately not backfilled.
+  const terminalInstances = await em.find(
+    WorkflowInstance,
+    {
+      ...baseScope,
+      status: { $in: [...WORKFLOW_TERMINAL_STATUSES] },
+      $or: [{ completedAt: window }, { cancelledAt: window }],
+    },
+    {
+      orderBy: { startedAt: 'DESC' },
+      limit: ROLLUP_DURATION_SAMPLE_LIMIT,
+      fields: ['id', 'status', 'outcome', 'startedAt', 'completedAt', 'cancelledAt'],
+    },
+  )
+
+  const terminalRuns = terminalInstances.map((instance) => ({
+    status: instance.status,
+    outcome: instance.outcome ?? null,
+    startedAt: instance.startedAt ?? null,
+    terminalAt: instance.completedAt ?? instance.cancelledAt ?? null,
+  }))
+
+  // Tasks carry no workflow id of their own, so they are reached through the
+  // instances above. That indirection is also what excludes dry runs from the
+  // SLA metric structurally rather than by a second flag: a dry run creates no
+  // task row at all, and the instance ids fed in here are already dry-run free.
+  const instanceIds = terminalInstances.map((instance) => instance.id)
+  const completedTasks = instanceIds.length
+    ? await em.find(
+        UserTask,
+        {
+          tenantId: scope.tenantId,
+          ...organizationFilter(scope),
+          workflowInstanceId: { $in: instanceIds },
+          status: 'COMPLETED',
+          dueDate: { $ne: null },
+          completedAt: window,
+        },
+        { limit: ROLLUP_TASK_SAMPLE_LIMIT, fields: ['dueDate', 'completedAt'] },
+      )
+    : []
+
+  return buildDefinitionMetrics({
+    runsStarted,
+    terminalRuns,
+    completedTasks: completedTasks.map((task) => ({
+      dueDate: task.dueDate ?? null,
+      completedAt: task.completedAt ?? null,
+    })),
+  })
+}
+
+/**
+ * Write (or overwrite) one bucket's row.
+ *
+ * Read-then-write against the unique key. The constraint is the real guarantee;
+ * this lookup only avoids the round trip through a conflict in the common case.
+ */
+async function upsertRollup(
+  em: EntityManager,
+  scope: RollupScope,
+  args: { workflowId: string; bounds: RollupWindowBounds; metrics: DefinitionMetrics; now: Date },
+): Promise<void> {
+  const key = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    workflowId: args.workflowId,
+    windowKey: args.bounds.windowKey,
+    windowStart: args.bounds.windowStart,
+  }
+  const existing = await em.findOne(WorkflowDefinitionMetricRollup, key)
+  if (existing) {
+    existing.windowEnd = args.bounds.windowEnd
+    existing.computedAt = args.now
+    existing.metrics = { ...args.metrics }
+    em.persist(existing)
+    return
+  }
+  em.persist(
+    em.create(WorkflowDefinitionMetricRollup, {
+      ...key,
+      windowEnd: args.bounds.windowEnd,
+      computedAt: args.now,
+      metrics: { ...args.metrics },
+      createdAt: args.now,
+    }),
+  )
+}
+
+export type RollupPassResult = {
+  workflowIds: number
+  written: number
+}
+
+/**
+ * One rollup pass for one tenant + organization.
+ *
+ * Returns counts rather than rows so the worker can log a one-line summary
+ * without holding the whole result set.
+ */
+export async function writeRollupsForScope(
+  em: EntityManager,
+  scope: RollupScope,
+  options: { now?: Date } = {},
+): Promise<RollupPassResult> {
+  const now = options.now ?? new Date()
+  const bounds = resolveWindowBounds(now.getTime())
+  const widest = bounds.reduce((oldest, candidate) =>
+    candidate.windowStart < oldest.windowStart ? candidate : oldest,
+  )
+
+  const workflowIds = await listActiveWorkflowIds(em, scope, widest.windowStart)
+  let written = 0
+
+  const readScope: MetricsReadScope = {
+    tenantId: scope.tenantId,
+    organizationIds: [scope.organizationId],
+  }
+
+  for (const workflowId of workflowIds) {
+    for (const windowBounds of bounds) {
+      const metrics = await computeDefinitionMetrics(em, readScope, {
+        workflowId,
+        windowStart: windowBounds.windowStart,
+        windowEnd: windowBounds.windowEnd,
+      })
+      await upsertRollup(em, scope, { workflowId, bounds: windowBounds, metrics, now })
+      written += 1
+    }
+  }
+
+  await em.flush()
+  logger.debug('Wrote workflow definition metric rollups', {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    workflowIds: workflowIds.length,
+    written,
+  })
+  return { workflowIds: workflowIds.length, written }
+}

package/src/modules/workflows/lib/node-config-summary.ts

@@ -0,0 +1,235 @@
+/**
+ * Workflows Module - One-line node config summary (pure)
+ *
+ * Fidelity gap #6. The design's nodes are not bigger than ours — measured, ours
+ * are WIDER — they are more informative, because the body line states the step's
+ * CONFIGURATION (`customers.deals.update · retries 3×`) instead of two clamped
+ * lines of the author's prose, which truncate mid-word and cannot tell you which
+ * command runs, which agent is invoked, or what the threshold is.
+ *
+ * The summary is derived, never authored: everything below already sits on the
+ * step. `description` is not lost — it becomes the card's tooltip.
+ *
+ * PURE: no React, no `@xyflow/react`, no ORM, so the rule is testable without a
+ * canvas and `graph-utils` could consume it if the layout ever needs to.
+ */
+
+import type { TranslateFn, TranslateParams } from '@open-mercato/shared/lib/i18n/context'
+
+export type NodeConfigSummaryTranslationKey =
+  | 'workflows.nodeSummary.alwaysAsk'
+  | 'workflows.nodeSummary.assigned'
+  | 'workflows.nodeSummary.autoApproveThreshold'
+  | 'workflows.nodeSummary.bound'
+  | 'workflows.nodeSummary.decisions'
+  | 'workflows.nodeSummary.retries'
+  | 'workflows.nodeSummary.role'
+  | 'workflows.nodeSummary.until'
+
+/** A summary is segments so command ids can render monospaced and labels can be translated. */
+export type NodeConfigSummarySegment =
+  | {
+      text: string
+      translationKey?: never
+      translationParams?: never
+      mono?: boolean
+    }
+  | {
+      text?: never
+      translationKey: NodeConfigSummaryTranslationKey
+      translationParams?: TranslateParams
+      mono?: boolean
+    }
+
+export const NODE_CONFIG_SUMMARY_SEPARATOR = ' · '
+
+export interface NodeConfigSummarySource {
+  activities?: Array<{ activityType?: string; config?: Record<string, unknown> } | null> | null
+  activityType?: string
+  activityId?: string
+  activityConfig?: Record<string, unknown> | null
+  retryPolicy?: { maxAttempts?: number } | null
+  agentId?: string
+  assignedTo?: string
+  assignedToRoles?: string[] | null
+  entityBindings?: Array<unknown> | null
+  decisions?: Array<unknown> | null
+  signalName?: string
+  duration?: string
+  until?: string
+  config?: Record<string, unknown> | null
+  subWorkflowId?: string
+  [key: string]: unknown
+}
+
+function text(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+function firstActivityConfig(
+  data: NodeConfigSummarySource,
+  activityType: string,
+): Record<string, unknown> | null {
+  const match = (data.activities ?? []).find(
+    (activity) => activity && activity.activityType === activityType,
+  )
+  if (match?.config) return match.config
+  if (data.activityType === activityType && data.activityConfig) return data.activityConfig
+  return null
+}
+
+function retrySegment(data: NodeConfigSummarySource): NodeConfigSummarySegment | null {
+  const attempts = data.retryPolicy?.maxAttempts
+  if (typeof attempts !== 'number' || attempts <= 1) return null
+  return {
+    translationKey: 'workflows.nodeSummary.retries',
+    translationParams: { count: attempts },
+  }
+}
+
+function automatedSummary(data: NodeConfigSummarySource): NodeConfigSummarySegment[] {
+  const segments: NodeConfigSummarySegment[] = []
+
+  const updateEntity = firstActivityConfig(data, 'UPDATE_ENTITY')
+  const commandId = text(updateEntity?.commandId)
+  const executeFunction = firstActivityConfig(data, 'EXECUTE_FUNCTION')
+  const functionName = text(executeFunction?.functionName)
+  const emitEvent = firstActivityConfig(data, 'EMIT_EVENT')
+  const eventId = text(emitEvent?.eventId) ?? text(emitEvent?.event)
+
+  const identifier = commandId ?? functionName ?? eventId
+  if (identifier) {
+    segments.push({ text: identifier, mono: true })
+  } else {
+    const activityType =
+      text(data.activityType) ??
+      text((data.activities ?? []).find((activity) => activity?.activityType)?.activityType)
+    if (activityType) segments.push({ text: activityType, mono: true })
+  }
+
+  const retries = retrySegment(data)
+  if (retries) segments.push(retries)
+  return segments
+}
+
+function invokeAgentSummary(data: NodeConfigSummarySource): NodeConfigSummarySegment[] {
+  const agentConfig = firstActivityConfig(data, 'INVOKE_AGENT')
+  const agentId = text(data.agentId) ?? text(agentConfig?.agentId)
+  const segments: NodeConfigSummarySegment[] = []
+  if (agentId) segments.push({ text: agentId, mono: true })
+
+  // The threshold is the single most consequential thing about an agent step —
+  // it decides whether a human ever sees the proposal — so it belongs on the
+  // face rather than three clicks into the inspector.
+  const onResult = agentConfig?.onResult as
+    | { autoApproveThreshold?: unknown; alwaysAsk?: unknown }
+    | undefined
+  if (onResult?.alwaysAsk === true) {
+    segments.push({ translationKey: 'workflows.nodeSummary.alwaysAsk' })
+  } else if (typeof onResult?.autoApproveThreshold === 'number') {
+    segments.push({
+      translationKey: 'workflows.nodeSummary.autoApproveThreshold',
+      translationParams: { threshold: onResult.autoApproveThreshold },
+    })
+  }
+  return segments
+}
+
+function userTaskSummary(data: NodeConfigSummarySource): NodeConfigSummarySegment[] {
+  const segments: NodeConfigSummarySegment[] = []
+  const roles = (data.assignedToRoles ?? []).filter((role): role is string => !!text(role))
+  if (roles.length > 0) {
+    segments.push({
+      translationKey: 'workflows.nodeSummary.role',
+      translationParams: { roles: roles.join(', ') },
+    })
+  } else if (text(data.assignedTo)) {
+    segments.push({ translationKey: 'workflows.nodeSummary.assigned' })
+  }
+
+  const bindings = data.entityBindings ?? []
+  if (bindings.length > 0) {
+    segments.push({
+      translationKey: 'workflows.nodeSummary.bound',
+      translationParams: { count: bindings.length },
+    })
+  }
+
+  const decisions = (data.decisions ?? []).length
+  if (decisions > 0) {
+    segments.push({
+      translationKey: 'workflows.nodeSummary.decisions',
+      translationParams: { count: decisions },
+    })
+  }
+  return segments
+}
+
+function waitForSignalSummary(data: NodeConfigSummarySource): NodeConfigSummarySegment[] {
+  const signalName =
+    text(data.signalName) ??
+    text((data.config as { signalName?: unknown } | null)?.signalName) ??
+    text((data as { signalConfig?: { signalName?: unknown } }).signalConfig?.signalName)
+  return signalName ? [{ text: signalName, mono: true }] : []
+}
+
+function waitForTimerSummary(data: NodeConfigSummarySource): NodeConfigSummarySegment[] {
+  const duration = text(data.duration) ?? text((data.config as { duration?: unknown } | null)?.duration)
+  if (duration) return [{ text: duration }]
+  const until = text(data.until) ?? text((data.config as { until?: unknown } | null)?.until)
+  return until
+    ? [{
+        translationKey: 'workflows.nodeSummary.until',
+        translationParams: { value: until },
+      }]
+    : []
+}
+
+function subWorkflowSummary(data: NodeConfigSummarySource): NodeConfigSummarySegment[] {
+  const subWorkflowId =
+    text(data.subWorkflowId) ?? text((data.config as { subWorkflowId?: unknown } | null)?.subWorkflowId)
+  return subWorkflowId ? [{ text: subWorkflowId, mono: true }] : []
+}
+
+const SUMMARY_BUILDERS: Record<string, (data: NodeConfigSummarySource) => NodeConfigSummarySegment[]> = {
+  automated: automatedSummary,
+  invokeAgent: invokeAgentSummary,
+  userTask: userTaskSummary,
+  waitForSignal: waitForSignalSummary,
+  waitForTimer: waitForTimerSummary,
+  subWorkflow: subWorkflowSummary,
+}
+
+/**
+ * The card's body line for a node type, or an empty list when the step carries
+ * nothing worth stating — in which case the card falls back to the author's
+ * description exactly as it did before, so an unconfigured node never gets
+ * emptier than it was.
+ */
+export function buildNodeConfigSummary(
+  nodeType: string,
+  data: NodeConfigSummarySource | null | undefined,
+): NodeConfigSummarySegment[] {
+  const builder = SUMMARY_BUILDERS[nodeType]
+  if (!builder || !data) return []
+  return builder(data)
+}
+
+export function resolveNodeConfigSummarySegment(
+  segment: NodeConfigSummarySegment,
+  translate: TranslateFn,
+): string {
+  if (segment.translationKey) {
+    return translate(segment.translationKey, segment.translationParams)
+  }
+  return segment.text
+}
+
+export function formatNodeConfigSummary(
+  segments: NodeConfigSummarySegment[],
+  translate: TranslateFn,
+): string {
+  return segments
+    .map((segment) => resolveNodeConfigSummarySegment(segment, translate))
+    .join(NODE_CONFIG_SUMMARY_SEPARATOR)
+}

package/src/modules/workflows/lib/node-geometry.ts

@@ -0,0 +1,168 @@
+/**
+ * Rendered node geometry — the SINGLE source of truth for how much space a
+ * workflow node occupies AND for how big its connection handles are.
+ *
+ * Two consumers need the same numbers and used to keep private copies in sync
+ * behind a comment: `components/WorkflowNodeCard.tsx` (which renders the card)
+ * and `lib/graph-utils.ts` (which reserves the footprint dagre lays out). Drift
+ * between them is invisible until ranks silently overlap, so the numbers live
+ * here instead. This module stays PURE — no React, no `lucide-react`, no
+ * `@xyflow/react` — so the layout transform can import it in node and jest
+ * contexts without pulling in the editor's render chain.
+ *
+ * The handle constants below joined it for the same reason: every node
+ * component spelled its own `!w-3 !h-3 !border-2 !border-background` and the
+ * outcome-row footer spelled a smaller one, so a footer dot and the source
+ * handle floating beside it rendered at different diameters on the same card.
+ * Tailwind scans this file (`@source ".../@open-mercato/core/src/**\/*.{ts,tsx}"`),
+ * so the literals here are real utilities, not dead strings.
+ */
+
+/** Narrowest a `w-fit` card may render. */
+export const NODE_MIN_WIDTH = 180
+/** Widest a `w-fit` card may render before its content wraps. */
+export const NODE_MAX_WIDTH = 280
+/**
+ * Height of a title-only card: the type row plus the title row, plus the 4px
+ * node-type accent cap (`border-t-4`) that replaced the card's 1px top border.
+ * Under-estimating here is what makes dagre pack ranks tight enough to overlap,
+ * so this errs toward the real footprint.
+ */
+export const NODE_HEIGHT = 88
+/** Extra height the two-line `line-clamp-2` description adds to a card. */
+export const NODE_DESCRIPTION_HEIGHT = 24
+
+/**
+ * Height one outcome row adds to a card's footer (fidelity gap #4): a 16px row
+ * plus the 2px grid gap. An agent node with four wired outcomes is materially
+ * taller than a bare one, and dagre reserves boxes from these numbers — under-
+ * estimating is exactly what makes ranks overlap.
+ */
+export const NODE_OUTCOME_ROW_HEIGHT = 18
+
+/**
+ * Fixed chrome the footer costs once it exists at all: the hairline rule plus
+ * its 4px vertical padding, and the inheritance note an agent node states.
+ */
+export const NODE_OUTCOME_FOOTER_CHROME_HEIGHT = 22
+
+/**
+ * Footprint of a terminal (START / END) node. Terminals render as compact
+ * auto-width pills rather than full step cards, so reserving a card-sized box
+ * for them would push the first and last rank apart for nothing.
+ */
+export const TERMINAL_NODE_MIN_WIDTH = 96
+export const TERMINAL_NODE_HEIGHT = 36
+
+/**
+ * Footprint of the canvas trigger node (fidelity gap #5) — the pill that states
+ * how a definition is entered, drawn in the gutter BEFORE the START terminal.
+ *
+ * It is derived rather than measured for the same reason the outcome-row footer
+ * is: the node is minted at render time from the definition's triggers and has
+ * to be placed before React Flow has laid a single card out. It is never handed
+ * to dagre (it is not a step and has no rank), so these numbers do not reserve a
+ * box — they position one, and `TRIGGER_NODE_GAP` matches dagre's own `ranksep`
+ * so the pill sits one rank-gap ahead of START rather than at some second
+ * spacing nothing else on the canvas uses.
+ */
+export const TRIGGER_NODE_WIDTH = 200
+/** The pill itself: icon + label, at the terminal pills' vertical rhythm. */
+export const TRIGGER_NODE_HEADER_HEIGHT = 32
+/** One dashed event tag (or the manual-start / overflow line) plus its gap. */
+export const TRIGGER_NODE_ROW_HEIGHT = 22
+/** Horizontal clearance between the trigger pill and the START terminal. */
+export const TRIGGER_NODE_GAP = 80
+
+/**
+ * Diameter, in px, of a connection handle. One number for the target handle,
+ * every source handle, the error handle and the terminal pills' handles: a
+ * canvas where the dots differ in size reads as a rendering bug, and the
+ * maintainer's report of "different sizes" was exactly a 10px footer dot next
+ * to a 12px floating one.
+ */
+export const NODE_HANDLE_SIZE = 12
+
+/** Tailwind form of {@link NODE_HANDLE_SIZE}. */
+export const NODE_HANDLE_SIZE_CLASS = '!h-3 !w-3'
+
+/**
+ * The ring that lifts a handle off whatever it overlaps. Kept with the size so
+ * a handle can never be resized without its border following.
+ */
+export const NODE_HANDLE_BORDER_CLASS = '!border-2 !border-background'
+
+/** Size + ring. Callers add only the DS colour token the handle speaks with. */
+export const NODE_HANDLE_CLASS = `${NODE_HANDLE_SIZE_CLASS} ${NODE_HANDLE_BORDER_CLASS}`
+
+/**
+ * How far a handle overhangs the edge it sits on — half its diameter, so it
+ * straddles the border rather than floating beside it. React Flow positions
+ * edge-anchored handles itself; this is for handles placed by a row's own
+ * layout (the outcome footer), which have to reproduce the same overhang.
+ */
+export const NODE_HANDLE_EDGE_OFFSET = -(NODE_HANDLE_SIZE / 2)
+
+/**
+ * Sub-workflow IO ports are deliberately smaller than a control-flow handle:
+ * a sub-workflow fans out one per declared input/output along an edge a
+ * control-flow handle owns alone. Registered here anyway so the two sizes are
+ * a decision made in one file rather than a drift discovered on a card.
+ */
+export const NODE_PORT_HANDLE_SIZE_CLASS = '!h-2.5 !w-2.5'
+export const NODE_PORT_HANDLE_CLASS = `${NODE_PORT_HANDLE_SIZE_CLASS} !border !border-background`
+
+/**
+ * Geometry of the chips a route renders at its midpoint (`WorkflowRouteChips`,
+ * #4244) — the condition summary, the activity icons and the `+N` overflow.
+ *
+ * They live here for the reason the handle constants do: a canvas element whose
+ * size is spelled inline in the component that draws it drifts. The activity
+ * chip was the drift's first casualty — an icon at `size-3` in `px-1.5 py-0.5`
+ * padding rendered an ~18px box carrying a 12px glyph, which is the size of a
+ * connection handle and unreadable at any canvas zoom below 1. A route chip is
+ * something the author reads, not a dot they aim at, so it is sized against the
+ * card it sits between rather than against the handle it sits near: the icon is
+ * {@link ROUTE_CHIP_ICON_SIZE}px and the box lands near {@link ROUTE_CHIP_HEIGHT}px,
+ * comfortably under half of {@link NODE_HEIGHT} so a chip never competes with the
+ * steps it connects.
+ *
+ * The label stays `text-xs` — the DS floor the node config summaries already
+ * hold — so a chip grows by its glyph and its padding, never by inventing a
+ * type size the design system does not have.
+ */
+export const ROUTE_CHIP_ICON_SIZE = 20
+
+/**
+ * Tailwind form of {@link ROUTE_CHIP_ICON_SIZE}. For the ICON-ONLY activity
+ * chip, where the glyph is the whole chip and has to carry it alone.
+ */
+export const ROUTE_CHIP_ICON_CLASS = 'size-5'
+
+/**
+ * The glyph on a chip that also carries text (the condition summary, the
+ * `otherwise` marker). It sits on the label's optical line, so it is sized
+ * against the `text-xs` next to it rather than against the canvas — at
+ * {@link ROUTE_CHIP_ICON_SIZE} it would tower over its own label.
+ */
+export const ROUTE_CHIP_LABEL_ICON_CLASS = 'size-3.5'
+
+/** Breathing room around a chip's glyph, on the DS spacing scale. */
+export const ROUTE_CHIP_PADDING_CLASS = 'px-2 py-1'
+
+/**
+ * Rendered height of a chip: the glyph plus {@link ROUTE_CHIP_PADDING_CLASS}'s
+ * 4px vertical padding on each side plus the 1px border on each side. Derived
+ * so the ratio to the node card stays checkable.
+ */
+export const ROUTE_CHIP_HEIGHT = ROUTE_CHIP_ICON_SIZE + 8 + 2
+
+/**
+ * Everything a chip shares regardless of what it says. Callers add only the DS
+ * colour tokens and the interaction states their own chip speaks with.
+ *
+ * On the radius: the DS scale has no 4px step for a chip — it is either
+ * `rounded-full` (pill) or `rounded-md`. Bare `rounded` was neither, and read as
+ * a slightly squared-off box next to every other chip in the product.
+ */
+export const ROUTE_CHIP_CLASS = `inline-flex items-center gap-1 rounded-md border bg-card ${ROUTE_CHIP_PADDING_CLASS} text-xs font-medium`