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

package/src/modules/workflows/lib/run-gantt.ts

@@ -0,0 +1,311 @@
+/**
+ * Run Gantt model (spec §8.3) — PURE.
+ *
+ * > "**Timeline** — a true clock-time **Gantt** (bars per step/activity/task/
+ * > signal, parallel branches as overlapping lanes, with collapsed-wait
+ * > rendering so a 3-day task deadline doesn't flatten the rest; this is what
+ * > makes latency and human-wait visible)"
+ *
+ * Two problems the naive version does not solve.
+ *
+ * **Collapsed waits.** A run that spends 1s executing and three days waiting
+ * for an approval is 99.999% wait on a linear axis: every automated step
+ * collapses to a sub-pixel sliver and the chart shows nothing. So the axis is
+ * PIECEWISE-LINEAR. The run is cut at every start and end into slices; a slice
+ * longer than the collapse threshold is rendered at the threshold's width and
+ * flagged, so the wait is visible AS a wait without eating the chart. Time is
+ * still monotonic and every bar keeps its true duration in `durationMs` — the
+ * compression is a rendering decision, never a reported number.
+ *
+ * **Lanes.** Parallel branches genuinely overlap in clock time, so they cannot
+ * share a row. Bars are grouped by `branchInstanceId` (the engine's own branch
+ * token) and packed greedily inside each group, which keeps one branch reading
+ * top-to-bottom instead of scattering it across the chart.
+ */
+
+import type { StepRunStatus } from './status-colors'
+import { stepInstanceStatusToRunStatus, type RunStepInstanceInput } from './run-execution'
+import { toMillis } from './run-duration'
+
+/** A slice shorter than this is never compressed — sub-second runs stay linear. */
+export const MIN_COLLAPSIBLE_MS = 1000
+
+/**
+ * How many times the typical slice a slice must exceed before it is treated as
+ * a wait rather than work. Four is deliberately conservative: it collapses the
+ * three-day approval and leaves an ordinary slow HTTP call alone.
+ */
+export const COLLAPSE_FACTOR = 4
+
+export type GanttBar = {
+  key: string
+  stepId: string
+  stepName: string
+  stepType: string
+  status: StepRunStatus
+  branchInstanceId: string | null
+  lane: number
+  startMs: number
+  endMs: number
+  /** TRUE elapsed time. Never the compressed one. */
+  durationMs: number
+  /** Position across the rendered (compressed) axis, 0..1. */
+  offsetRatio: number
+  widthRatio: number
+  /** The bar spans at least one collapsed slice, i.e. most of it is waiting. */
+  spansCollapsedWait: boolean
+  /** The step had not finished when the model was built. */
+  running: boolean
+}
+
+export type GanttCollapsedSegment = {
+  startMs: number
+  endMs: number
+  skippedMs: number
+  offsetRatio: number
+  widthRatio: number
+}
+
+export type GanttModel = {
+  bars: GanttBar[]
+  laneCount: number
+  startMs: number
+  endMs: number
+  /** True wall-clock span of the run. */
+  totalDurationMs: number
+  collapsedSegments: GanttCollapsedSegment[]
+  /** Sum of everything the collapsed segments hide, for the "N hidden" caption. */
+  collapsedDurationMs: number
+}
+
+type Slice = {
+  startMs: number
+  endMs: number
+  durationMs: number
+  weight: number
+  collapsed: boolean
+  renderedStart: number
+}
+
+function median(values: readonly number[]): number {
+  if (values.length === 0) return 0
+  const ordered = [...values].sort((left, right) => left - right)
+  const middle = Math.floor(ordered.length / 2)
+  return ordered.length % 2 === 0 ? (ordered[middle - 1] + ordered[middle]) / 2 : ordered[middle]
+}
+
+function resolveCollapseThreshold(sliceDurations: readonly number[]): number {
+  const positive = sliceDurations.filter((duration) => duration > 0)
+  if (positive.length === 0) return Number.POSITIVE_INFINITY
+  return Math.max(MIN_COLLAPSIBLE_MS, median(positive) * COLLAPSE_FACTOR)
+}
+
+function buildSlices(boundaries: readonly number[]): Slice[] {
+  const rawDurations: number[] = []
+  for (let index = 1; index < boundaries.length; index += 1) {
+    rawDurations.push(boundaries[index] - boundaries[index - 1])
+  }
+  const threshold = resolveCollapseThreshold(rawDurations)
+
+  const slices: Slice[] = []
+  let renderedStart = 0
+  for (let index = 1; index < boundaries.length; index += 1) {
+    const startMs = boundaries[index - 1]
+    const endMs = boundaries[index]
+    const durationMs = endMs - startMs
+    const collapsed = durationMs > threshold
+    const weight = collapsed ? threshold : durationMs
+    slices.push({ startMs, endMs, durationMs, weight, collapsed, renderedStart })
+    renderedStart += weight
+  }
+  return slices
+}
+
+function renderedTotal(slices: readonly Slice[]): number {
+  return slices.reduce((total, slice) => total + slice.weight, 0)
+}
+
+/** Map a wall-clock instant onto the compressed axis, in rendered units. */
+function projectToRendered(slices: readonly Slice[], atMs: number): number {
+  if (slices.length === 0) return 0
+  if (atMs <= slices[0].startMs) return 0
+  const last = slices[slices.length - 1]
+  if (atMs >= last.endMs) return last.renderedStart + last.weight
+
+  for (const slice of slices) {
+    if (atMs >= slice.startMs && atMs <= slice.endMs) {
+      if (slice.durationMs === 0) return slice.renderedStart
+      const progress = (atMs - slice.startMs) / slice.durationMs
+      return slice.renderedStart + progress * slice.weight
+    }
+  }
+  return last.renderedStart + last.weight
+}
+
+type BarSeed = {
+  key: string
+  stepId: string
+  stepName: string
+  stepType: string
+  status: StepRunStatus
+  branchInstanceId: string | null
+  startMs: number
+  endMs: number
+  running: boolean
+}
+
+/**
+ * Lanes per branch: every bar carrying the same `branchInstanceId` is packed
+ * into that branch's own block of lanes, so a parallel branch reads as one
+ * band rather than being scattered across the chart by a global packer.
+ */
+function assignLanes(seeds: readonly BarSeed[]): Map<string, number> {
+  const laneByKey = new Map<string, number>()
+  const groups = new Map<string, BarSeed[]>()
+  const groupOrder: string[] = []
+
+  for (const seed of seeds) {
+    const groupKey = seed.branchInstanceId ?? '__main__'
+    const existing = groups.get(groupKey)
+    if (existing) {
+      existing.push(seed)
+    } else {
+      groups.set(groupKey, [seed])
+      groupOrder.push(groupKey)
+    }
+  }
+
+  let nextLaneBase = 0
+  for (const groupKey of groupOrder) {
+    const groupSeeds = groups.get(groupKey) ?? []
+    const laneEnds: number[] = []
+    for (const seed of groupSeeds) {
+      let lane = laneEnds.findIndex((endMs) => endMs <= seed.startMs)
+      if (lane === -1) {
+        lane = laneEnds.length
+        laneEnds.push(seed.endMs)
+      } else {
+        laneEnds[lane] = seed.endMs
+      }
+      laneByKey.set(seed.key, nextLaneBase + lane)
+    }
+    nextLaneBase += Math.max(laneEnds.length, 1)
+  }
+
+  return laneByKey
+}
+
+export type BuildGanttInput = {
+  stepInstances: readonly RunStepInstanceInput[]
+  /** Instance start, so the axis begins where the run began even if step 1 is late. */
+  instanceStartedAt?: string | Date | null
+  instanceCompletedAt?: string | Date | null
+  /** Injected for determinism — an unfinished step is measured against this. */
+  now?: number
+}
+
+export function buildRunGantt(input: BuildGanttInput): GanttModel {
+  const now = input.now ?? Date.now()
+
+  const seeds: BarSeed[] = []
+  for (const [index, stepInstance] of input.stepInstances.entries()) {
+    const startMs = toMillis(stepInstance.enteredAt)
+    if (startMs === null) continue
+    const recordedEnd = toMillis(stepInstance.exitedAt)
+    const running = recordedEnd === null
+    const endMs = Math.max(recordedEnd ?? now, startMs)
+    seeds.push({
+      key: stepInstance.id ?? `${stepInstance.stepId}-${index}`,
+      stepId: stepInstance.stepId,
+      stepName: stepInstance.stepName || stepInstance.stepId,
+      stepType: stepInstance.stepType || '',
+      status: stepInstanceStatusToRunStatus(stepInstance.status),
+      branchInstanceId: stepInstance.branchInstanceId ?? null,
+      startMs,
+      endMs,
+      running,
+    })
+  }
+
+  seeds.sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs)
+
+  const instanceStart = toMillis(input.instanceStartedAt)
+  const instanceEnd = toMillis(input.instanceCompletedAt)
+
+  const candidateStarts = seeds.map((seed) => seed.startMs)
+  const candidateEnds = seeds.map((seed) => seed.endMs)
+  if (instanceStart !== null) candidateStarts.push(instanceStart)
+  if (instanceEnd !== null) candidateEnds.push(instanceEnd)
+
+  if (candidateStarts.length === 0) {
+    return {
+      bars: [],
+      laneCount: 0,
+      startMs: 0,
+      endMs: 0,
+      totalDurationMs: 0,
+      collapsedSegments: [],
+      collapsedDurationMs: 0,
+    }
+  }
+
+  const startMs = Math.min(...candidateStarts)
+  const endMs = Math.max(...candidateEnds, startMs)
+
+  const boundarySet = new Set<number>([startMs, endMs])
+  for (const seed of seeds) {
+    boundarySet.add(seed.startMs)
+    boundarySet.add(seed.endMs)
+  }
+  const boundaries = [...boundarySet].sort((left, right) => left - right)
+
+  const slices = buildSlices(boundaries)
+  const total = renderedTotal(slices)
+  const toRatio = (atMs: number) => (total > 0 ? projectToRendered(slices, atMs) / total : 0)
+
+  const laneByKey = assignLanes(seeds)
+
+  const bars: GanttBar[] = seeds.map((seed) => {
+    const offsetRatio = toRatio(seed.startMs)
+    const endRatio = toRatio(seed.endMs)
+    const spansCollapsedWait = slices.some(
+      (slice) => slice.collapsed && slice.startMs >= seed.startMs && slice.endMs <= seed.endMs
+    )
+    return {
+      key: seed.key,
+      stepId: seed.stepId,
+      stepName: seed.stepName,
+      stepType: seed.stepType,
+      status: seed.status,
+      branchInstanceId: seed.branchInstanceId,
+      lane: laneByKey.get(seed.key) ?? 0,
+      startMs: seed.startMs,
+      endMs: seed.endMs,
+      durationMs: seed.endMs - seed.startMs,
+      offsetRatio,
+      widthRatio: Math.max(endRatio - offsetRatio, 0),
+      spansCollapsedWait,
+      running: seed.running,
+    }
+  })
+
+  const collapsedSegments: GanttCollapsedSegment[] = slices
+    .filter((slice) => slice.collapsed)
+    .map((slice) => ({
+      startMs: slice.startMs,
+      endMs: slice.endMs,
+      skippedMs: slice.durationMs - slice.weight,
+      offsetRatio: total > 0 ? slice.renderedStart / total : 0,
+      widthRatio: total > 0 ? slice.weight / total : 0,
+    }))
+
+  return {
+    bars,
+    laneCount: bars.reduce((highest, bar) => Math.max(highest, bar.lane + 1), 0),
+    startMs,
+    endMs,
+    totalDurationMs: endMs - startMs,
+    collapsedSegments,
+    collapsedDurationMs: collapsedSegments.reduce((total_, segment) => total_ + segment.skippedMs, 0),
+  }
+}

package/src/modules/workflows/lib/run-outcome-evidence.ts

@@ -0,0 +1,60 @@
+/**
+ * Workflows Module — Run Outcome Evidence (the data-access half).
+ *
+ * Counts what the run RECORDED about itself so `resolveRunOutcome`
+ * (`lib/run-outcome.ts`, pure) can reach a verdict. Nothing here decides
+ * anything: the vocabulary and the precedence both live in the pure module, and
+ * this file only turns rows into the counts that module asks for.
+ *
+ * Every query carries `tenantId` AND `organizationId` on top of the instance id.
+ * The instance id alone would already be unique, but a scoped query cannot be
+ * turned into a cross-tenant read by a later refactor that widens it.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+import { StepInstance, WorkflowEvent, type WorkflowInstance } from '../data/entities'
+import {
+  EMPTY_RUN_OUTCOME_EVIDENCE,
+  RUN_OUTCOME_FAILED_STEP_STATUS,
+  RUN_OUTCOME_FAILURE_EVENT_TYPES,
+  RUN_OUTCOME_SKIPPED_STEP_STATUS,
+  RUN_OUTCOME_WARNING_EVENT_TYPES,
+  type RunOutcomeEvidence,
+} from './run-outcome'
+
+/**
+ * Count the run's recorded failure and warning evidence.
+ *
+ * Short-circuits for every terminal status except `COMPLETED`: `cancelled`,
+ * `compensated` and `failure` are decided by the lifecycle alone, so querying
+ * for evidence that cannot change the verdict would add four round trips to
+ * every failing run's termination path.
+ */
+export async function collectRunOutcomeEvidence(
+  em: EntityManager,
+  instance: Pick<WorkflowInstance, 'id' | 'tenantId' | 'organizationId'>,
+  terminalStatus: string,
+): Promise<RunOutcomeEvidence> {
+  if (terminalStatus !== 'COMPLETED') {
+    return { terminalStatus, ...EMPTY_RUN_OUTCOME_EVIDENCE }
+  }
+
+  const scope = {
+    workflowInstanceId: instance.id,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  }
+
+  const [failedSteps, failureEvents, skippedSteps, warningEvents] = await Promise.all([
+    em.count(StepInstance, { ...scope, status: RUN_OUTCOME_FAILED_STEP_STATUS }),
+    em.count(WorkflowEvent, { ...scope, eventType: { $in: [...RUN_OUTCOME_FAILURE_EVENT_TYPES] } }),
+    em.count(StepInstance, { ...scope, status: RUN_OUTCOME_SKIPPED_STEP_STATUS }),
+    em.count(WorkflowEvent, { ...scope, eventType: { $in: [...RUN_OUTCOME_WARNING_EVENT_TYPES] } }),
+  ])
+
+  return {
+    terminalStatus,
+    failureEvidenceCount: failedSteps + failureEvents,
+    warningEvidenceCount: skippedSteps + warningEvents,
+  }
+}

package/src/modules/workflows/lib/run-outcome.ts

@@ -0,0 +1,142 @@
+/**
+ * Workflows Module — Run Outcome (pure)
+ *
+ * The run's **verdict**, alongside — never instead of — its lifecycle `status`.
+ *
+ * `status` answers *did it reach the end?* and drives control flow (is this run
+ * active? may the executor advance it? can it be retried?). It is untouched by
+ * this module. `outcome` answers the other question the same enum used to be
+ * asked to answer on its own: *did everything it attempted actually happen?*
+ * Conflating the two is why a run that swallowed three failed writes reported
+ * the same `COMPLETED` as a clean one.
+ *
+ * | outcome                 | meaning                                                       |
+ * |-------------------------|---------------------------------------------------------------|
+ * | `success`               | Reached END. Nothing failed, nothing was suppressed.           |
+ * | `success_with_warnings` | Reached END and did everything asked, but something is worth reading. |
+ * | `partial_failure`       | Reached END, but at least one activity or step failed and was tolerated. |
+ * | `failure`               | Did not reach END.                                             |
+ * | `cancelled`             | A human stopped it.                                            |
+ * | `compensated`           | Rolled back.                                                   |
+ *
+ * **The invariant this module exists for:**
+ *
+ * > A run that suppressed at least one failure MUST NOT be `success`.
+ *
+ * It holds by construction — `resolveRunOutcome` consults
+ * `failureEvidenceCount` before it can ever return `success`, and it is the ONE
+ * decision point, so no exit point can assemble a friendlier verdict of its own.
+ *
+ * PURE: no ORM, DI, React or registry imports, exactly like `lib/error-routing.ts`,
+ * `lib/breach-routing.ts` and `lib/outcome-routing.ts`. The impure half —
+ * counting the recorded evidence — lives in `lib/run-outcome-evidence.ts`.
+ */
+
+export const WORKFLOW_RUN_OUTCOMES = [
+  'success',
+  'success_with_warnings',
+  'partial_failure',
+  'failure',
+  'cancelled',
+  'compensated',
+] as const
+
+export type WorkflowRunOutcome = (typeof WORKFLOW_RUN_OUTCOMES)[number]
+
+/**
+ * `StepInstance.status` values that ARE recorded failure evidence.
+ *
+ * A step row only becomes FAILED through `markStepInstanceFailed`, which the
+ * enabling fix made unconditional — a tolerated failure is recorded exactly like
+ * a fatal one, because tolerating a failure is a routing decision, not a reason
+ * to forget it happened.
+ */
+export const RUN_OUTCOME_FAILED_STEP_STATUS = 'FAILED'
+
+/** `StepInstance.status` value that is a warning rather than a failure. */
+export const RUN_OUTCOME_SKIPPED_STEP_STATUS = 'SKIPPED'
+
+/**
+ * Event types that are failure evidence a step row does NOT already carry.
+ *
+ * `ACTIVITY_FAILED` is the one that matters: a transition's activities run
+ * LEAVING their source step, whose row has already exited COMPLETED, so a
+ * transition-level `continueOnActivityFailure` (the shipped `order-approval`
+ * shape) leaves no failed step row anywhere — only this event. `STEP_FAILED` is
+ * deliberately absent: it is one-to-one with a FAILED row and counting both
+ * would double-count the same failure.
+ */
+export const RUN_OUTCOME_FAILURE_EVENT_TYPES = ['ACTIVITY_FAILED'] as const
+
+/** Event types that are warning evidence a step row does not already carry. */
+export const RUN_OUTCOME_WARNING_EVENT_TYPES = ['STEP_SKIPPED'] as const
+
+/**
+ * What the run recorded about itself, already counted.
+ *
+ * Counts rather than rows because the decision is a `> 0` test and the collector
+ * answers it with `COUNT(*)`; the numbers are evidence for the verdict, not a
+ * reported metric.
+ *
+ * **Known imprecision, deliberately not papered over:** a run that failed, was
+ * retried and then completed still carries its pre-retry `ACTIVITY_FAILED`
+ * rows, so it reports `partial_failure`. The engine records no attempt boundary
+ * to subtract them by, and over-reporting a degraded run is the safe direction
+ * for a change whose whole purpose is to stop under-reporting one.
+ */
+export type RunOutcomeEvidence = {
+  /** The status the run is terminating with. */
+  terminalStatus: string
+  /** FAILED step rows plus `ACTIVITY_FAILED` events. */
+  failureEvidenceCount: number
+  /** SKIPPED step rows plus `STEP_SKIPPED` events. */
+  warningEvidenceCount: number
+}
+
+export const EMPTY_RUN_OUTCOME_EVIDENCE: Omit<RunOutcomeEvidence, 'terminalStatus'> = {
+  failureEvidenceCount: 0,
+  warningEvidenceCount: 0,
+}
+
+/**
+ * The single decision point. Terminal status first, because `cancelled`,
+ * `compensated` and `failure` are facts about the lifecycle that no amount of
+ * evidence can argue with; only a run that actually reached END is judged on
+ * what it recorded.
+ */
+export function resolveRunOutcome(evidence: RunOutcomeEvidence): WorkflowRunOutcome {
+  if (evidence.terminalStatus === 'CANCELLED') return 'cancelled'
+  if (evidence.terminalStatus === 'COMPENSATED') return 'compensated'
+  if (evidence.terminalStatus !== 'COMPLETED') return 'failure'
+  if (evidence.failureEvidenceCount > 0) return 'partial_failure'
+  if (evidence.warningEvidenceCount > 0) return 'success_with_warnings'
+  return 'success'
+}
+
+/** True for a verdict an operator must look at even though the run reached END. */
+export function isDegradedRunOutcome(outcome: WorkflowRunOutcome | null | undefined): boolean {
+  return outcome === 'partial_failure'
+}
+
+/**
+ * Outcomes the needs-attention / failure queue must include.
+ *
+ * A `partial_failure` is precisely the run nobody looks at because it said
+ * COMPLETED — which is the failure this whole change exists to remove.
+ */
+export const WORKFLOW_ATTENTION_OUTCOMES = ['partial_failure'] as const
+
+/**
+ * `partial_failure` is NOT retryable as a whole run (maintainer decision,
+ * 2026-07-30). It reached END, so replaying the graph would re-run every part
+ * that already succeeded — duplicating their effects to re-attempt the parts
+ * that did not. Recovery is rerun-from-step on the specific failed step, which
+ * is what that feature is for and what the enabling fix unblocked.
+ */
+export function isRetryableRunOutcome(outcome: WorkflowRunOutcome | null | undefined): boolean {
+  return outcome === 'failure'
+}
+
+export function isWorkflowRunOutcome(value: unknown): value is WorkflowRunOutcome {
+  return typeof value === 'string' && (WORKFLOW_RUN_OUTCOMES as readonly string[]).includes(value)
+}

package/src/modules/workflows/lib/sample-resolver.ts

@@ -0,0 +1,113 @@
+/**
+ * Workflows Module - per-step sample resolution (spec
+ * 2026-07-26-workflows-ux-redesign.md section 3.6).
+ *
+ * Pure, dependency-free precedence chain for the context sample shown next to
+ * a step in the editor and used to seed Test-step runs:
+ *
+ *   1. explicit pin — `metadata.editor.samples[stepId]` written by the user
+ *   2. in-memory test output — the last Test-step result for the step
+ *   3. ledger-derived placeholder — synthesized from the step's ledger
+ *      entries so the preview always has an honest, typed shape
+ *
+ * Returns null when none of the three sources can produce anything. No React,
+ * no ORM, no DI — loadable from the browser bundle and server routes alike.
+ */
+
+export type ResolvedSampleSource = 'pin' | 'test' | 'placeholder'
+
+export interface ResolvedStepSample {
+  data: unknown
+  source: ResolvedSampleSource
+}
+
+export interface PinnedSampleEnvelope {
+  pinnedAt: string
+  source: 'manual' | 'test'
+  data: unknown
+}
+
+export interface SampleLedgerEntry {
+  path: string
+  type: string
+  options?: string[]
+}
+
+export interface ResolveStepSampleInput {
+  stepId: string
+  samples?: Record<string, PinnedSampleEnvelope> | null
+  testOutputs?: Record<string, unknown> | null
+  ledgerEntries?: SampleLedgerEntry[] | null
+}
+
+const PLACEHOLDER_DATE_SAMPLE = '2026-01-01T00:00:00.000Z'
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function placeholderValueFor(entry: SampleLedgerEntry): unknown {
+  switch (entry.type) {
+    case 'text':
+      return 'text'
+    case 'number':
+      return 0
+    case 'boolean':
+      return false
+    case 'date':
+      return PLACEHOLDER_DATE_SAMPLE
+    case 'select':
+      return entry.options && entry.options.length > 0 ? entry.options[0] : 'option'
+    case 'object':
+      return {}
+    default:
+      return null
+  }
+}
+
+function assignAtPath(target: Record<string, unknown>, path: string, value: unknown): void {
+  const segments = path.split('.').filter((segment) => segment.length > 0)
+  if (segments.length === 0) return
+  let cursor = target
+  for (const segment of segments.slice(0, -1)) {
+    const existing = cursor[segment]
+    if (isPlainObject(existing)) {
+      cursor = existing
+    } else {
+      const created: Record<string, unknown> = {}
+      cursor[segment] = created
+      cursor = created
+    }
+  }
+  const leaf = segments[segments.length - 1]
+  const current = cursor[leaf]
+  if (isPlainObject(current) && isPlainObject(value)) return
+  cursor[leaf] = value
+}
+
+export function buildPlaceholderFromLedger(entries: SampleLedgerEntry[]): Record<string, unknown> {
+  const placeholder: Record<string, unknown> = {}
+  for (const entry of entries) {
+    assignAtPath(placeholder, entry.path, placeholderValueFor(entry))
+  }
+  return placeholder
+}
+
+export function resolveStepSample({
+  stepId,
+  samples,
+  testOutputs,
+  ledgerEntries,
+}: ResolveStepSampleInput): ResolvedStepSample | null {
+  const pinned = samples ? samples[stepId] : undefined
+  if (pinned !== undefined) {
+    return { data: pinned.data, source: 'pin' }
+  }
+  if (testOutputs && Object.prototype.hasOwnProperty.call(testOutputs, stepId)) {
+    return { data: testOutputs[stepId], source: 'test' }
+  }
+  if (ledgerEntries && ledgerEntries.length > 0) {
+    return { data: buildPlaceholderFromLedger(ledgerEntries), source: 'placeholder' }
+  }
+  return null
+}

package/src/modules/workflows/lib/seeds.ts

@@ -78,11 +78,13 @@ async function seedWorkflowDefinition(
   const seed = readExampleJson<WorkflowSeedDefinition>(fileName)
   const workflowId = requireString(seed.workflowId, 'workflowId')
 
+  // Version-aware: pin to the latest version so re-seeding never updates an
+  // older coexisting version row (workflowId is no longer unique per tenant).
   const existing = await em.findOne(WorkflowDefinition, {
     workflowId,
     tenantId: scope.tenantId,
     organizationId: scope.organizationId,
-  })
+  }, { orderBy: { version: 'DESC' } })
 
   if (existing) {
     // Check if the definition needs to be updated by comparing steps and transitions