From 80a197b8f375d32c0522f6817253a4df484716e1 Mon Sep 17 00:00:00 2001
From: zzheng <zzheng.pm@gmail.com>
Date: Sun, 6 Sep 2026 20:28:55 -0700
Subject: [PATCH 1/3] Derive reader-facing labels from the graph, without new
 Dex concepts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three additions to the Flow Definition renderer, each derived from vocabulary Dex
already has, so a Flow gets them without adopting a convention or changing the
analyser:

  stepRole()     gate | batch | work. A Step whose WaitFor holds a Channel
                 condition is a gate: in Dex that already means an actor outside
                 the Flow must publish before it proceeds. Naming it adds no
                 concept, it promotes one that was in the graph all along. A
                 SubFlow condition makes it a batch; Timers alone do not.

  waitSentence() the wait as one plain sentence. Channel and Timer names stay
                 verbatim because they are the operator's handles; what goes is
                 the scaffolding around them — anyOf, skipWaitImmediately, and
                 the `.for 1` suffix a reader has no use for.

  displayName()  reads the FDG schema's existing per-node `metadata`, falling
                 back to the type name. A Step type is part of the durable
                 contract of an open execution, so a display name sits in front
                 of it and never replaces it: the card keeps showing the type
                 whenever a display name covers it.

Gates are coloured and carry a SOMEONE MUST ACT badge, so the reader can see
where a human is required without reading any label.

On a real 12-Step Flow this finds all four gates and both fan-out Steps from the
graph alone. Deliberately absent: whether a model or a script does the work.
No Dex concept answers that, and inventing one here would put an application
fact into the renderer's vocabulary — `metadata` is the place for it.
---
 .../src/FlowDefinitionGraph.tsx               | 107 ++++-
 .../src/definitionLayout.ts                   | 375 ++++++++++++++++--
 .../flow-definition-renderer/src/index.ts     |   9 +
 .../flow-definition-renderer/src/styles.css   | 109 +++++
 web/app/rendering/definitionLayout.test.ts    | 176 ++++++++
 5 files changed, 747 insertions(+), 29 deletions(-)

diff --git a/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx b/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx
index 471e3ef4e..0bbe56a81 100644
--- a/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx
+++ b/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx
@@ -27,6 +27,7 @@ import {
 import type { FlowDefinitionGraph, FlowDefinitionNode, SourceSpan } from './types';
 import {
   buildDefinitionScene,
+  recoveryHubSteps,
   filterDefinitionEdgesForSelection,
   isResourceRelation,
   type DefinitionEdgeData,
@@ -34,11 +35,14 @@ import {
   type DefinitionNodeData,
   type DefinitionSelectionDetail,
   type DefinitionVisibility,
+  type RecoveryLayout,
 } from './definitionLayout';
 
 const layerLabels: Array<[DefinitionLayer | 'diagnostics', string]> = [
   ['control', 'Control flow'],
+  ['recovery', 'Recovery paths'],
   ['waits', 'WaitFor'],
+  ['decisions', 'Decisions'],
   ['rpcs', 'RPC'],
   ['channels', 'Channels'],
   ['attributes', 'Attributes'],
@@ -49,7 +53,9 @@ const layerLabels: Array<[DefinitionLayer | 'diagnostics', string]> = [
 
 const defaultVisibility: DefinitionVisibility & { diagnostics: boolean } = {
   control: true,
+  recovery: true,
   waits: true,
+  decisions: true,
   rpcs: true,
   attributes: true,
   channels: true,
@@ -68,6 +74,7 @@ const nodeTypes: NodeTypes = {
   definitionStep: StepNode,
   definitionStream: StreamNode,
   definitionSubFlow: SubFlowNode,
+  definitionRecovery: RecoveryNode,
   definitionTimeout: TimeoutNode,
   definitionUnknown: UnknownNode,
   definitionWait: WaitNode,
@@ -83,17 +90,32 @@ export function FlowDefinitionGraphView({
   graph: FlowDefinitionGraph;
 }) {
   const [visibility, setVisibility] = useState(defaultVisibility);
+  // ?recovery=steps|rail|table|traced — see RecoveryLayout. Review scaffolding: it lets
+  // the three candidate placements be compared side by side on one build.
+  const recoveryLayout = useMemo<RecoveryLayout>(() => {
+    // Guarded: this component is also rendered to static markup in tests, where there is
+    // no window to read a query string from.
+    if (typeof window === 'undefined') return 'steps';
+    const requested = new URLSearchParams(window.location.search).get('recovery');
+    return requested === 'rail' || requested === 'table' || requested === 'traced'
+      ? requested
+      : 'steps';
+  }, []);
   const [selectedNodeID, setSelectedNodeID] = useState('');
   const [selectedEdgeID, setSelectedEdgeID] = useState('');
   const [isMiniMapExpanded, setIsMiniMapExpanded] = useState(false);
   const [flowInstance, setFlowInstance] = useState<ReactFlowInstance | null>(null);
+  const tracedHubs = useMemo(
+    () => (recoveryLayout === 'traced' ? recoveryHubSteps(graph) : new Set<string>()),
+    [graph, recoveryLayout],
+  );
   const scene = useMemo(
-    () => buildDefinitionScene(graph, visibility),
-    [graph, visibility],
+    () => buildDefinitionScene(graph, visibility, { recoveryLayout }),
+    [graph, visibility, recoveryLayout],
   );
   const selectedNode = scene.nodes.find((node) => node.id === selectedNodeID);
   const visibleEdges = useMemo(
-    () => filterDefinitionEdgesForSelection(scene.edges, graph.nodes, selectedNodeID),
+    () => filterDefinitionEdgesForSelection(scene.edges, graph.nodes, selectedNodeID, tracedHubs),
     [graph.nodes, scene.edges, selectedNodeID],
   );
   const selectedEdge = visibleEdges.find((edge) => edge.id === selectedEdgeID);
@@ -132,6 +154,9 @@ export function FlowDefinitionGraphView({
           </div>
           <p>{graph.source.language} · {graph.source.path}</p>
         </div>
+        {recoveryLayout !== 'steps' ? (
+          <span className="definition-preview-badge">recovery: {recoveryLayout}</span>
+        ) : null}
         <div className="flow-definition-legend" aria-label="Graph visibility">
           {layerLabels.map(([layer, label]) => (
             <button
@@ -261,16 +286,31 @@ function FlowNode({ data }: NodeProps) {
 }
 
 function StepNode({ data }: NodeProps) {
-  const definition = (data as DefinitionNodeData).definition!;
+  const nodeData = data as DefinitionNodeData;
+  const definition = nodeData.definition!;
+  const role = nodeData.role ?? 'work';
+  const shown = nodeData.displayName ?? definition.name;
   return (
-    <div aria-label={sourceTitle(definition)} className="definition-step-frame">
+    <div
+      aria-label={sourceTitle(definition)}
+      className={`definition-step-frame definition-step-frame--${role}`}
+    >
       <Handle id="step-target" position={Position.Top} type="target" />
       <Handle id="step-control-outer-target" position={Position.Right} style={{ top: 22 }} type="target" />
       <Handle id="step-control-outer-source" position={Position.Right} style={{ top: 'calc(100% - 22px)' }} type="source" />
       <div className="definition-step-title">
-        <strong>{definition.name}</strong>
+        <strong>{shown}</strong>
         {definition.start && <span>START</span>}
+        {role === 'gate' && <span className="definition-step-actor">SOMEONE MUST ACT</span>}
       </div>
+      {/* The type name stays on the card whenever a display name covers it: it is the
+          durable identity, the thing you pass to dexcli and name in a resume. */}
+      {shown !== definition.name && (
+        <div className="definition-step-type">{definition.name}</div>
+      )}
+      {nodeData.waitSentence ? (
+        <div className="definition-step-wait">{nodeData.waitSentence}</div>
+      ) : null}
       <Handle id="step-resource-target" position={Position.Left} type="target" />
       <Handle id="step-resource-source" position={Position.Left} type="source" />
       <Handle id="step-recovery-source" position={Position.Bottom} type="source" />
@@ -388,6 +428,61 @@ function RPCNode({ data }: NodeProps) {
   );
 }
 
+/**
+ * An operator recovery hub, drawn the way a timeout handler is: one card in the side
+ * rail listing what it does, rather than a Step containing a grid of near-identical
+ * decision cards.
+ *
+ * The lines are `guard -> destination`, not `goTo -> destination`. Every branch of a
+ * resume dispatch is a goTo, so leading with the type repeats the one word that carries
+ * no information and buries the two that do.
+ */
+function RecoveryNode({ data }: NodeProps) {
+  const definitionData = data as DefinitionNodeData;
+  const definition = definitionData.definition!;
+  const decisions = definitionData.definitions ?? [];
+  const waits = definitionData.waits ?? [];
+  const routes = decisions.flatMap((decision) => (definitionData.relatedEdges ?? [])
+    .filter((edge) => edge.from === decision.id && edge.kind === 'transition')
+    .map((edge) => ({
+      id: edge.id,
+      guard: recoveryGuard(decision),
+      target: definitionData.nameByID?.[edge.to] ?? edge.to.split(':').pop() ?? edge.to,
+    })));
+  return (
+    <div aria-label={sourceTitle(definition)} className="definition-recovery-handler">
+      <Handle position={Position.Left} type="target" />
+      <span className="definition-recovery-kicker">↩ RECOVERY</span>
+      <strong>{definition.name}</strong>
+      {waits.map((wait) => (
+        <div className="definition-recovery-wait" key={wait.id}>
+          {wait.wait?.type}
+          {(wait.wait?.conditions ?? []).map((condition) => (
+            <span key={condition.label}> · {condition.label}</span>
+          ))}
+        </div>
+      ))}
+      <div className="definition-recovery-routes">
+        {routes.map((route) => (
+          <span key={route.id}>
+            <em>{route.guard}</em> → 🧩 {route.target}
+          </span>
+        ))}
+      </div>
+      <Handle position={Position.Right} type="source" />
+    </div>
+  );
+}
+
+/** The branch's own test, or a readable stand-in when it has none. */
+function recoveryGuard(decision: FlowDefinitionNode): string {
+  const condition = decision.condition?.trim();
+  if (!condition) return 'always';
+  if (condition === 'otherwise') return 'otherwise';
+  const own = condition.split(' and ').at(-1) ?? condition;
+  return own.replace(/^not \((.*)\)$/, 'not $1');
+}
+
 function TimeoutNode({ data }: NodeProps) {
   const definitionData = data as DefinitionNodeData;
   const definition = definitionData.definition!;
diff --git a/packages/flow-definition-renderer/src/definitionLayout.ts b/packages/flow-definition-renderer/src/definitionLayout.ts
index 75aedaee9..7f5d72ef1 100644
--- a/packages/flow-definition-renderer/src/definitionLayout.ts
+++ b/packages/flow-definition-renderer/src/definitionLayout.ts
@@ -17,7 +17,9 @@ import type {
 
 export type DefinitionLayer =
   | 'control'
+  | 'recovery'
   | 'waits'
+  | 'decisions'
   | 'rpcs'
   | 'attributes'
   | 'channels'
@@ -27,10 +29,13 @@ export type DefinitionLayer =
 export type DefinitionVisibility = Record<DefinitionLayer, boolean>;
 
 export interface DefinitionNodeData extends Record<string, unknown> {
-  kind: 'flow' | 'step' | 'wait' | 'dispatch' | 'decision' | 'channel' | 'attributes' | 'rpc' | 'timeout' | 'subflow' | 'stream' | 'unknown';
+  kind: 'flow' | 'step' | 'wait' | 'dispatch' | 'decision' | 'channel' | 'attributes' | 'rpc' | 'recovery' | 'timeout' | 'subflow' | 'stream' | 'unknown';
+  waits?: FlowDefinitionNode[];
   definition?: FlowDefinitionNode;
   definitions?: FlowDefinitionNode[];
   displayName?: string;
+  role?: StepRole;
+  waitSentence?: string;
   relatedEdges?: FlowDefinitionEdge[];
   nameByID?: Record<string, string>;
   selectionDetails?: DefinitionSelectionDetail[];
@@ -84,22 +89,215 @@ const cardWidth = 288;
 const dispatchSize = 58;
 const stepTopologyRankSeparation = 168;
 
+/**
+ * Steps that exist only to absorb a failure, derived from the graph rather than named.
+ *
+ * Two rules, applied in order:
+ *
+ * 1. A Step targeted by two or more `failure_transition` edges is an error-handling hub.
+ *    One Step collecting the exhausted retries of many others is what a recovery gate
+ *    looks like structurally, and its outgoing edges fan back across the whole graph —
+ *    which is what turns a readable column into hub-and-spoke.
+ * 2. Once those hubs and every `failure_transition` edge are removed, any Step no longer
+ *    reachable from the start Step was reachable only by failing into it.
+ *
+ * Neither rule looks at a name, so a Flow gets this for free without adopting a
+ * convention.
+ */
+/**
+ * Steps that collect the exhausted retries of two or more other Steps.
+ *
+ * One Step failing into a dedicated handler is an ordinary one-to-one pairing. One Step
+ * collecting many failures is an operator recovery hub: it fans back out across the whole
+ * Flow, which is what turns a readable column into hub-and-spoke.
+ */
+export function recoveryHubSteps(graph: FlowDefinitionGraph): Set<string> {
+  const failureInbound = new Map<string, number>();
+  for (const edge of graph.edges) {
+    if (edge.kind !== 'failure_transition') continue;
+    failureInbound.set(edge.to, (failureInbound.get(edge.to) ?? 0) + 1);
+  }
+  return new Set(
+    graph.nodes
+      .filter((node) => node.kind === 'step' && (failureInbound.get(node.id) ?? 0) >= 2)
+      .map((node) => node.id),
+  );
+}
+
+export function recoveryOnlySteps(graph: FlowDefinitionGraph): Set<string> {
+  const definitionsByID = new Map(graph.nodes.map((node) => [node.id, node]));
+  const stepIDs = new Set(graph.nodes.filter((node) => node.kind === 'step').map((node) => node.id));
+  const owningStep = (id: string): string => {
+    const node = definitionsByID.get(id);
+    return node?.parentId ?? id;
+  };
+  const hubs = recoveryHubSteps(graph);
+
+  const forward = new Map<string, Set<string>>();
+  for (const edge of graph.edges) {
+    if (edge.kind !== 'transition') continue;
+    const source = owningStep(edge.from);
+    if (!stepIDs.has(source) || !stepIDs.has(edge.to)) continue;
+    if (!forward.has(source)) forward.set(source, new Set());
+    forward.get(source)!.add(edge.to);
+  }
+
+  const reachable = new Set<string>();
+  const start = graph.flow.startStepId;
+  const stack = start && stepIDs.has(start) ? [start] : [];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    if (reachable.has(current) || hubs.has(current)) continue;
+    reachable.add(current);
+    for (const next of forward.get(current) ?? []) stack.push(next);
+  }
+
+  // With no start Step recorded there is no path to reason about, so hide only the hubs.
+  if (stack.length === 0 && reachable.size === 0) return hubs;
+  return new Set([...stepIDs].filter((id) => !reachable.has(id)));
+}
+
+/** Drop recovery Steps, their child nodes, and every exhausted-retry edge. */
+export function withoutRecoveryPaths(graph: FlowDefinitionGraph): FlowDefinitionGraph {
+  const hidden = recoveryOnlySteps(graph);
+  if (hidden.size === 0) {
+    return { ...graph, edges: graph.edges.filter((edge) => edge.kind !== 'failure_transition') };
+  }
+  const removed = new Set(hidden);
+  // A Step's waits, dispatches and decisions hang off it by parentId; leaving them
+  // behind would strand them in the layout.
+  for (const node of graph.nodes) {
+    if (node.parentId && removed.has(node.parentId)) removed.add(node.id);
+  }
+  return {
+    ...graph,
+    nodes: graph.nodes.filter((node) => !removed.has(node.id)),
+    edges: graph.edges.filter(
+      (edge) =>
+        edge.kind !== 'failure_transition' && !removed.has(edge.from) && !removed.has(edge.to),
+    ),
+  };
+}
+
+/**
+ * Where a recovery hub is drawn.
+ *
+ *   steps   today's behaviour: a Step card containing a grid of decision cards
+ *   rail    one card in the side rail, beside the flow, like a timeout handler
+ *   table   the same card, left in the Step column where the hub sits in the topology
+ *   traced  the rail card, with its edges revealed only while it is selected
+ */
+/**
+ * What a Step is, in the reader's terms, derived only from Dex's own vocabulary.
+ *
+ *   gate   its WaitFor has a Channel condition, so an actor outside the Flow must publish
+ *          before it proceeds. Dex already models human-in-the-loop this way; naming it
+ *          adds no concept, it promotes one that was already there.
+ *   batch  its WaitFor has a SubFlow condition: it fans out and waits for children.
+ *   work   pure Execute, or a wait on Timers alone.
+ *
+ * What a graph cannot answer — whether a model or a script does the work — is deliberately
+ * absent. That is an application fact, not a Dex one, and belongs in the schema's own
+ * `metadata` extension point rather than in this vocabulary.
+ */
+export type StepRole = 'gate' | 'batch' | 'work';
+
+export function stepRole(graph: FlowDefinitionGraph, stepID: string): StepRole {
+  const kinds = new Set<string>();
+  for (const node of graph.nodes) {
+    if (node.kind !== 'wait' || node.parentId !== stepID) continue;
+    for (const condition of node.wait?.conditions ?? []) kinds.add(condition.kind ?? '');
+  }
+  if (kinds.has('channel')) return 'gate';
+  if (kinds.has('subflow')) return 'batch';
+  return 'work';
+}
+
+/**
+ * One plain sentence for what a Step waits on, assembled from its Conditions.
+ *
+ * Channel and Timer names stay verbatim — they are the operator's handles, and inventing
+ * prose for them would misrepresent what has to be published. What this replaces is the
+ * framework scaffolding around them: `anyOf`, `skipWaitImmediately`, and the `.for 1`
+ * suffix a reader has no use for.
+ */
+export function waitSentence(graph: FlowDefinitionGraph, stepID: string): string {
+  const waits = graph.nodes.filter((node) => node.kind === 'wait' && node.parentId === stepID);
+  const real = waits.filter((node) => node.wait?.type !== 'skipWaitImmediately');
+  if (real.length === 0) return '';
+  const channels: string[] = [];
+  const timers: string[] = [];
+  const subflows: string[] = [];
+  for (const node of real) {
+    for (const condition of node.wait?.conditions ?? []) {
+      const label = (condition.label ?? '').replace(/\.for \d+$/, '');
+      if (condition.kind === 'channel') channels.push(label);
+      else if (condition.kind === 'timer') timers.push(label);
+      else if (condition.kind === 'subflow') subflows.push(label);
+    }
+  }
+  const clauses: string[] = [];
+  if (channels.length > 0) {
+    clauses.push(`stops until a message arrives on ${[...new Set(channels)].join(' or ')}`);
+  }
+  if (subflows.length > 0) {
+    const every = real.some((node) => node.wait?.type === 'allOf');
+    clauses.push(`waits for ${every ? 'every' : 'any'} started ${[...new Set(subflows)].join(', ')}`);
+  }
+  if (timers.length > 0) clauses.push('or a timer fires and it asks again');
+  const skippable = waits.length > real.length ? ' (a branch can skip the wait)' : '';
+  return clauses.join(', ') + skippable;
+}
+
+/**
+ * The name to show on a card.
+ *
+ * Uses the FDG schema's existing per-node `metadata` rather than a new field, and falls
+ * back to the durable type name, which is always present. A Step type name is part of the
+ * contract of an open execution, so a display name must never replace it — only sit in
+ * front of it.
+ */
+export function displayName(node: FlowDefinitionNode): string {
+  const provided = (node.metadata as { displayName?: unknown } | undefined)?.displayName;
+  return typeof provided === 'string' && provided.trim() !== '' ? provided : node.name;
+}
+
+export type RecoveryLayout = 'steps' | 'rail' | 'table' | 'traced';
+
+export interface DefinitionSceneOptions {
+  recoveryLayout?: RecoveryLayout;
+}
+
 export function buildDefinitionScene(
-  graph: FlowDefinitionGraph,
+  rawGraph: FlowDefinitionGraph,
   visibility: DefinitionVisibility,
+  options: DefinitionSceneOptions = {},
 ): DefinitionScene {
+  // Filtered once, up front, so every later stage — step layout, topology, edges —
+  // sees one consistent graph and needs no knowledge of the toggle.
+  const graph = visibility.recovery ? rawGraph : withoutRecoveryPaths(rawGraph);
   const definitionsByID = new Map(graph.nodes.map((node) => [node.id, node]));
+  // Computed on the FILTERED graph, so this self-disables: with recovery hidden the
+  // failure edges are already gone, no hub is detected, and none of the rail code fires.
+  const collapseHubs = options.recoveryLayout && options.recoveryLayout !== 'steps'
+    ? recoveryHubSteps(graph)
+    : new Set<string>();
+  // `table` keeps the collapsed card inside the Step column, so the hub stays in the
+  // dagre topology; `rail` and `traced` lift it out into the side rail.
+  const railHubs = options.recoveryLayout === 'table' ? new Set<string>() : collapseHubs;
   const steps = visibility.control
-    ? graph.nodes.filter((node) => node.kind === 'step').sort(byNameThenID)
+    ? graph.nodes.filter((node) => node.kind === 'step' && !railHubs.has(node.id)).sort(byNameThenID)
     : [];
   const stepLayouts = new Map(steps.map((step) => [
     step.id,
-    layoutStep(graph, step, visibility),
+    collapseHubs.has(step.id)
+      ? collapsedHubLayout(graph, step)
+      : layoutStep(graph, step, visibility),
   ]));
   const stepPositions = layoutStepTopology(graph, steps, stepLayouts, definitionsByID);
   const topologyBounds = boundsForSteps(steps, stepLayouts, stepPositions);
   const resourceNodes = layoutResources(graph, visibility);
-  const handlerNodes = layoutRPCsAndTimeoutHandlers(graph, visibility);
+  const handlerNodes = layoutRPCsAndTimeoutHandlers(graph, visibility, railHubs);
   const sideRailHeight = Math.max(
     flowHeaderHeight + 50,
     ...resourceNodes.map((node) => node.position.y + numericStyle(node, 'height')),
@@ -107,20 +305,41 @@ export function buildDefinitionScene(
   );
   const centralLeft = resourceRailWidth + 56;
   const stepsTop = flowHeaderHeight + 36;
+  const nameByID = Object.fromEntries(graph.nodes.map((node) => [node.id, node.name]));
   const stepNodes = steps.map((step) => {
     const layout = stepLayouts.get(step.id)!;
     const position = stepPositions.get(step.id) ?? { x: 0, y: 0 };
+    // In `table` placement a hub keeps its slot in the topology but renders as the
+    // collapsed recovery card, so the route list replaces the decision grid in place.
+    const isCollapsedHub = collapseHubs.has(step.id);
+    const hubDecisions = isCollapsedHub
+      ? graph.nodes.filter((node) => node.kind === 'decision' && node.parentId === step.id)
+      : [];
     return {
       id: step.id,
-      type: 'definitionStep',
+      type: isCollapsedHub ? 'definitionRecovery' : 'definitionStep',
       parentId: flowID,
       position: { x: centralLeft + position.x, y: stepsTop + position.y },
       style: layout.dimensions,
-      data: {
-        kind: 'step' as const,
-        definition: step,
-        sourceTitle: sourceTitle(step.span),
-      },
+      data: isCollapsedHub
+        ? {
+          kind: 'recovery' as const,
+          definition: step,
+          definitions: hubDecisions,
+          relatedEdges: hubDecisions.flatMap((decision) =>
+            graph.edges.filter((edge) => edge.from === decision.id)),
+          waits: graph.nodes.filter((node) => node.kind === 'wait' && node.parentId === step.id),
+          nameByID,
+          sourceTitle: sourceTitle(step.span),
+        }
+        : {
+          kind: 'step' as const,
+          definition: step,
+          displayName: displayName(step),
+          role: stepRole(graph, step.id),
+          waitSentence: waitSentence(graph, step.id),
+          sourceTitle: sourceTitle(step.span),
+        },
     } satisfies Node<DefinitionNodeData>;
   });
   const childNodes = steps.flatMap((step) => stepLayouts.get(step.id)?.children ?? []);
@@ -179,12 +398,29 @@ export function buildDefinitionScene(
       endpointMap.set(definition.id, parent.id);
     }
   }
+  for (const definition of graph.nodes) {
+    // A hub's decisions and waits collapse into its card, exactly as a timeout handler's
+    // do, so every edge that left a child now leaves the card. This holds for all three
+    // collapsed placements — only the card's position differs between them.
+    if (definition.parentId && collapseHubs.has(definition.parentId)) {
+      endpointMap.set(definition.id, definition.parentId);
+    }
+  }
   for (const node of childNodes.filter((child) => child.data.kind === 'decision')) {
     for (const definition of node.data.definitions ?? []) endpointMap.set(definition.id, node.id);
   }
+  if (!visibility.decisions) {
+    // The decision cards are gone, so a transition leaves from the Step that owned it.
+    // Without this the edge would point at a node that is not in the scene and be
+    // dropped by the visibleIDs filter below, silently losing the control flow.
+    for (const definition of graph.nodes.filter((node) => node.kind === 'decision')) {
+      const parent = definition.parentId ? definitionsByID.get(definition.parentId) : undefined;
+      if (parent?.kind === 'step') endpointMap.set(definition.id, parent.id);
+    }
+  }
   const edges = mergeGroupedTransitionEdges(graph.edges
     .filter((edge) => edge.kind !== 'cancel')
-    .map((edge) => definitionEdge(edge, endpointMap, definitionsByID, stepNodes))
+    .map((edge) => definitionEdge(edge, endpointMap, definitionsByID, stepNodes, !visibility.decisions))
     .filter((edge) => visibleIDs.has(edge.source) && visibleIDs.has(edge.target)));
   edges.push(...internalStepEdges(graph, stepLayouts, visibleIDs));
   return { nodes, edges };
@@ -194,9 +430,18 @@ export function filterDefinitionEdgesForSelection(
   edges: Array<Edge<DefinitionEdgeData>>,
   definitions: FlowDefinitionNode[],
   selectedNodeID: string,
+  // `traced` placement extends selection gating from resource relations to the hub's own
+  // control-flow edges: present, but quiet until the hub is the thing you are looking at.
+  tracedHubs: Set<string> = new Set(),
 ): Array<Edge<DefinitionEdgeData>> {
   const definitionsByID = new Map(definitions.map((definition) => [definition.id, definition]));
   return edges.filter((edge) => {
+    if (tracedHubs.size > 0) {
+      const touchesHub = tracedHubs.has(edge.source) || tracedHubs.has(edge.target);
+      if (touchesHub && !isResourceRelation(edge.data?.kind)) {
+        return tracedHubs.has(selectedNodeID);
+      }
+    }
     if (!isResourceRelation(edge.data?.kind)) return true;
     if (!selectedNodeID) return false;
     const sourceID = edge.data?.definitionSourceID ?? edge.source;
@@ -248,6 +493,25 @@ function belongsToOwner(
   return false;
 }
 
+/**
+ * A hub left in the Step column, with its decision grid replaced by the route list.
+ *
+ * No children: the routes are drawn by the card itself, so the 14 decision cards that
+ * made this Step taller than the rest of the column disappear.
+ */
+function collapsedHubLayout(graph: FlowDefinitionGraph, step: FlowDefinitionNode): StepLayout {
+  const routes = graph.edges.filter((edge) => {
+    if (edge.kind !== 'transition') return false;
+    const source = graph.nodes.find((node) => node.id === edge.from);
+    return source?.parentId === step.id;
+  }).length;
+  const waits = graph.nodes.filter((node) => node.kind === 'wait' && node.parentId === step.id).length;
+  return {
+    children: [],
+    dimensions: { height: Math.max(150, 78 + (routes + waits * 2) * 19), width: cardWidth + stepGap * 2 },
+  };
+}
+
 function layoutStep(
   graph: FlowDefinitionGraph,
   step: FlowDefinitionNode,
@@ -256,9 +520,11 @@ function layoutStep(
   const waitDefinitions = visibility.waits
     ? graph.nodes.filter((node) => node.kind === 'wait' && node.parentId === step.id).sort(bySpanThenID)
     : [];
-  const decisionDefinitions = graph.nodes
-    .filter((node) => node.kind === 'decision' && node.parentId === step.id && node.phase !== 'rpc' && node.phase !== 'timeout')
-    .sort(bySpanThenID);
+  const decisionDefinitions = visibility.decisions
+    ? graph.nodes
+        .filter((node) => node.kind === 'decision' && node.parentId === step.id && node.phase !== 'rpc' && node.phase !== 'timeout')
+        .sort(bySpanThenID)
+    : [];
   const unknownDefinitions = visibility.control
     ? graph.nodes.filter((node) => node.kind === 'unknown' && node.parentId === step.id).sort(bySpanThenID)
     : [];
@@ -632,13 +898,19 @@ function layoutResources(
 function layoutRPCsAndTimeoutHandlers(
   graph: FlowDefinitionGraph,
   visibility: DefinitionVisibility,
+  railHubs: Set<string> = new Set(),
 ): Array<Node<DefinitionNodeData>> {
   const nameByID = Object.fromEntries(graph.nodes.map((node) => [node.id, node.name]));
   let top = flowHeaderHeight + 36;
   return graph.nodes
-    .filter((node) => node.kind === 'timeout_handler' || (visibility.rpcs && node.kind === 'rpc'))
-    .sort(byNameThenID)
+    .filter((node) => railHubs.has(node.id)
+      || node.kind === 'timeout_handler'
+      || (visibility.rpcs && node.kind === 'rpc'))
+    // Hubs first, so the rail reads recovery-then-handlers.
+    .sort((left, right) => Number(!railHubs.has(left.id)) - Number(!railHubs.has(right.id))
+      || byNameThenID(left, right))
     .map((handler) => {
+      const isRecovery = railHubs.has(handler.id);
       const decisions = graph.nodes.filter((node) => node.kind === 'decision' && node.parentId === handler.id);
       const relatedEdges = decisions.flatMap((decision) => graph.edges.filter((edge) => edge.from === decision.id));
       const isTimeout = handler.kind === 'timeout_handler';
@@ -648,18 +920,31 @@ function layoutRPCsAndTimeoutHandlers(
           .reduce((count, edge) => count + wrappedLineCount(nameByID[edge.to] ?? shortID(edge.to), 24), 0);
         return total + wrappedLineCount(decision.decision?.type ?? decision.name, 24) + movementLines;
       }, 0);
-      const height = isTimeout
-        ? Math.max(104, 62 + decisionLines * 19)
-        : Math.max(68, 42 + wrappedLineCount(handler.name, 28) * 18);
+      const routeLines = decisions.reduce((total, decision) => total + relatedEdges
+        .filter((edge) => edge.from === decision.id && edge.kind === 'transition')
+        .reduce((count, edge) => count + wrappedLineCount(
+          `${guardLabel(edge, decision) || 'otherwise'} -> ${nameByID[edge.to] ?? shortID(edge.to)}`,
+          34,
+        ), 0), 0);
+      const waitLines = graph.nodes
+        .filter((node) => node.kind === 'wait' && node.parentId === handler.id)
+        .reduce((total, wait) => total + 1
+          + (wait.wait?.conditions ?? []).length, 0);
+      const height = isRecovery
+        ? Math.max(150, 78 + (routeLines + waitLines) * 19)
+        : isTimeout
+          ? Math.max(104, 62 + decisionLines * 19)
+          : Math.max(68, 42 + wrappedLineCount(handler.name, 28) * 18);
       const node: Node<DefinitionNodeData> = {
         id: handler.id,
-        type: isTimeout ? 'definitionTimeout' : 'definitionRPC',
+        type: isRecovery ? 'definitionRecovery' : isTimeout ? 'definitionTimeout' : 'definitionRPC',
         parentId: flowID,
         position: { x: -132, y: top },
         style: { height, width: 260 },
         data: {
-          kind: isTimeout ? 'timeout' : 'rpc',
+          kind: isRecovery ? 'recovery' : isTimeout ? 'timeout' : 'rpc',
           definition: handler,
+          waits: graph.nodes.filter((node) => node.kind === 'wait' && node.parentId === handler.id),
           definitions: decisions,
           relatedEdges,
           nameByID,
@@ -729,13 +1014,16 @@ function definitionEdge(
   endpointMap: Map<string, string>,
   definitionsByID: Map<string, FlowDefinitionNode>,
   stepNodes: Array<Node<DefinitionNodeData>>,
+  labelWithGuard = false,
 ): Edge<DefinitionEdgeData> {
   const source = endpointMap.get(definition.from) ?? definition.from;
   const target = endpointMap.get(definition.to) ?? definition.to;
   const sourceDefinition = definitionsByID.get(definition.from);
   const targetDefinition = definitionsByID.get(definition.to);
   const color = edgeColor(definition.kind);
-  const label = edgeLabel(definition);
+  const label = labelWithGuard
+    ? guardLabel(definition, sourceDefinition) || edgeLabel(definition)
+    : edgeLabel(definition);
   const isOuterRight = usesOuterRightRoute(definition, sourceDefinition, targetDefinition, stepNodes);
   const routedSource = isOuterRight && sourceDefinition?.kind === 'decision' && sourceDefinition.parentId
     ? sourceDefinition.parentId
@@ -913,6 +1201,47 @@ function branchEdge(source: string, target: Node<DefinitionNodeData>): Edge<Defi
   };
 }
 
+/**
+ * The branch's own test, for use as an edge label when the decision card is hidden.
+ *
+ * A guard arrives as every preceding branch negated and ANDed with this one, so
+ * `else: if not records` reads as `not (not records)`. Only the last clause is this
+ * branch's own, and a doubled negation is worth undoing before showing it to anyone.
+ */
+function guardLabel(
+  edge: FlowDefinitionEdge,
+  sourceDefinition: FlowDefinitionNode | undefined,
+): string {
+  if (edge.kind !== 'transition' || sourceDefinition?.kind !== 'decision') return '';
+  const condition = sourceDefinition.condition?.trim();
+  if (!condition || condition === 'otherwise') return condition === 'otherwise' ? 'otherwise' : '';
+  return simplifyGuard(condition.split(' and ').at(-1) ?? '');
+}
+
+function simplifyGuard(text: string): string {
+  let own = unwrapParentheses(text);
+  while (own.startsWith('not ')) {
+    const inner = unwrapParentheses(own.slice(4));
+    if (inner.startsWith('not ')) {
+      own = unwrapParentheses(inner.slice(4));
+      continue;
+    }
+    // `not (a != b)` reads better as `a == b`, and so on for the other comparisons.
+    const flip: Array<[string, string]> = [
+      [' != ', ' == '], [' == ', ' != '], [' > ', ' <= '], [' < ', ' >= '],
+    ];
+    const match = flip.find(([from]) => inner.includes(from));
+    return match ? inner.replace(match[0], match[1]) : `not ${inner}`;
+  }
+  return own;
+}
+
+function unwrapParentheses(text: string): string {
+  let out = text.trim();
+  while (out.startsWith('(') && out.endsWith(')')) out = out.slice(1, -1).trim();
+  return out;
+}
+
 function edgeLabel(edge: FlowDefinitionEdge): string {
   if (edge.kind === 'failure_transition') {
     return edge.metadata?.skipWaitFor === true ? 'Execute failure · skip WaitFor' : 'Execute failure';
diff --git a/packages/flow-definition-renderer/src/index.ts b/packages/flow-definition-renderer/src/index.ts
index b7b84c7b0..f7eeb29c9 100644
--- a/packages/flow-definition-renderer/src/index.ts
+++ b/packages/flow-definition-renderer/src/index.ts
@@ -14,6 +14,15 @@ export {
   buildDefinitionScene,
   filterDefinitionEdgesForSelection,
   isResourceRelation,
+  displayName,
+  recoveryHubSteps,
+  stepRole,
+  waitSentence,
+  type StepRole,
+  recoveryOnlySteps,
+  type DefinitionSceneOptions,
+  type RecoveryLayout,
+  withoutRecoveryPaths,
   type DefinitionEdgeData,
   type DefinitionLayer,
   type DefinitionNodeData,
diff --git a/packages/flow-definition-renderer/src/styles.css b/packages/flow-definition-renderer/src/styles.css
index 826e47ac8..c030b9895 100644
--- a/packages/flow-definition-renderer/src/styles.css
+++ b/packages/flow-definition-renderer/src/styles.css
@@ -131,6 +131,7 @@
   background: #64748b;
 }
 
+.definition-legend-swatch--recovery { background: var(--flow-definition-danger); }
 .definition-legend-swatch--waits { background: #d39732; }
 .definition-legend-swatch--rpcs { background: #7c3aed; }
 .definition-legend-swatch--attributes,
@@ -214,6 +215,7 @@
 .definition-channel-pipe,
 .definition-attributes-box,
 .definition-rpc-hexagon,
+.definition-recovery-handler,
 .definition-timeout-handler,
 .definition-subflow-frame,
 .definition-stream-node,
@@ -495,6 +497,113 @@
   text-align: center;
 }
 
+.definition-preview-badge {
+  align-self: center;
+  margin-right: 8px;
+  padding: 2px 8px;
+  border: 1px solid #c43b62;
+  border-radius: 999px;
+  color: #a12447;
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+}
+
+/* Colour says who has to act. A gate is a Step whose WaitFor holds a Channel condition,
+   which in Dex means an actor outside the Flow must publish before it moves — so the
+   colour is derived, not configured. */
+.definition-step-frame--gate {
+  border-color: #c43b62;
+  border-width: 2.5px;
+  background: #fdf1f4;
+}
+
+.definition-step-frame--batch {
+  border-color: #b3760f;
+  background: #fffaf0;
+}
+
+.definition-step-actor {
+  margin-left: 8px;
+  padding: 1px 6px;
+  border-radius: 999px;
+  background: #c43b62;
+  color: #fff;
+  font-size: 7.5px;
+  font-weight: 800;
+  letter-spacing: 0.07em;
+}
+
+.definition-step-type {
+  margin-top: 2px;
+  color: #93a2b8;
+  font: 9px ui-monospace, Menlo, monospace;
+}
+
+.definition-step-wait {
+  margin-top: 5px;
+  padding-top: 5px;
+  border-top: 1px dashed #d5dde8;
+  color: #4f6178;
+  font-size: 9.5px;
+  line-height: 1.4;
+}
+
+.definition-recovery-handler {
+  display: flex;
+  padding: 12px 18px 14px;
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: flex-start;
+  border: 2px solid #6c83aa;
+  border-left: 8px solid #c43b62;
+  border-radius: 9px;
+  color: #263b59;
+  background: #fdf1f4;
+  box-shadow: 0 7px 16px rgba(107, 48, 68, 0.16);
+  text-align: left;
+}
+
+.definition-recovery-kicker {
+  margin-bottom: 3px;
+  color: #a12447;
+  font-size: 8px;
+  font-weight: 850;
+  letter-spacing: 0.08em;
+}
+
+.definition-recovery-handler > strong {
+  color: #253c5d;
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+
+.definition-recovery-wait {
+  margin-top: 4px;
+  color: #6b7c95;
+  font-size: 9px;
+}
+
+.definition-recovery-routes {
+  display: grid;
+  width: 100%;
+  margin-top: 7px;
+  gap: 3px;
+}
+
+.definition-recovery-routes span {
+  color: #33475f;
+  font-size: 9.5px;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+.definition-recovery-routes em {
+  color: #a12447;
+  font-style: normal;
+  font-weight: 650;
+}
+
 .definition-timeout-kicker {
   margin-bottom: 3px;
   color: #985f0d;
diff --git a/web/app/rendering/definitionLayout.test.ts b/web/app/rendering/definitionLayout.test.ts
index ec28b3a7c..af06bcb27 100644
--- a/web/app/rendering/definitionLayout.test.ts
+++ b/web/app/rendering/definitionLayout.test.ts
@@ -10,6 +10,11 @@ import { describe, expect, it } from 'vitest';
 import {
   buildDefinitionScene,
   filterDefinitionEdgesForSelection,
+  displayName,
+  recoveryOnlySteps,
+  stepRole,
+  waitSentence,
+  withoutRecoveryPaths,
   type DefinitionVisibility,
   type FlowDefinitionGraph,
 } from '@superdurable/flow-definition-renderer';
@@ -17,7 +22,9 @@ import aiAgentGraph from '../../../docs/src/data/flow-definitions/ai-agent.json'
 
 const visible: DefinitionVisibility = {
   control: true,
+  recovery: true,
   waits: true,
+  decisions: true,
   rpcs: true,
   attributes: true,
   channels: true,
@@ -279,3 +286,172 @@ const graph: FlowDefinitionGraph = {
   ],
   diagnostics: [],
 };
+
+describe('recovery paths', () => {
+  const gate = (over: Partial<FlowDefinitionGraph> = {}): FlowDefinitionGraph => ({
+    schemaVersion: '1.0',
+    valid: true,
+    source: { language: 'python', path: 'flow.py' },
+    flow: { name: 'WithRecovery', startStepId: 'step:first' },
+    nodes: [
+      { id: 'step:first', kind: 'step', name: 'first', start: true },
+      { id: 'step:second', kind: 'step', name: 'second' },
+      { id: 'step:gate', kind: 'step', name: 'gate' },
+      { id: 'step:sink', kind: 'step', name: 'sink' },
+      {
+        id: 'decision:step:first:1:1', kind: 'decision', name: 'goTo', parentId: 'step:first',
+        decision: { type: 'goTo' },
+      },
+      {
+        id: 'decision:step:gate:2:1', kind: 'decision', name: 'goTo', parentId: 'step:gate',
+        decision: { type: 'goTo' },
+      },
+    ],
+    edges: [
+      { id: 'e1', kind: 'transition', from: 'decision:step:first:1:1', to: 'step:second' },
+      // Two Steps fail into the gate, which makes it an error-handling hub.
+      { id: 'e2', kind: 'failure_transition', from: 'step:first', to: 'step:gate' },
+      { id: 'e3', kind: 'failure_transition', from: 'step:second', to: 'step:gate' },
+      // The gate routes back into the happy path, so it is reachable by a transition too.
+      { id: 'e4', kind: 'transition', from: 'decision:step:gate:2:1', to: 'step:second' },
+      // The sink is reachable only by failing into it.
+      { id: 'e5', kind: 'failure_transition', from: 'step:second', to: 'step:sink' },
+    ],
+    diagnostics: [],
+    ...over,
+  });
+
+  it('finds a hub by its inbound failure edges, not by its name', () => {
+    expect([...recoveryOnlySteps(gate())].sort()).toEqual(['step:gate', 'step:sink']);
+  });
+
+  it('keeps a Step that only one other Step fails into, if a transition also reaches it', () => {
+    const graph = gate();
+    graph.edges = graph.edges.filter((edge) => edge.id !== 'e3');
+    graph.edges.push({ id: 'e6', kind: 'transition', from: 'decision:step:first:1:1', to: 'step:gate' });
+    expect([...recoveryOnlySteps(graph)]).toEqual(['step:sink']);
+  });
+
+  it('drops recovery Steps, their children and every exhausted-retry edge', () => {
+    const filtered = withoutRecoveryPaths(gate());
+    expect(filtered.nodes.map((node) => node.id)).toEqual([
+      'step:first',
+      'step:second',
+      'decision:step:first:1:1',
+    ]);
+    expect(filtered.edges.map((edge) => edge.id)).toEqual(['e1']);
+  });
+
+  it('still drops exhausted-retry edges when nothing else is hidden', () => {
+    const graph = gate();
+    graph.edges = [graph.edges[0], { ...graph.edges[1], to: 'step:second' }];
+    graph.nodes = graph.nodes.filter((node) => !['step:gate', 'step:sink'].includes(node.id));
+    const filtered = withoutRecoveryPaths(graph);
+    expect(filtered.nodes).toHaveLength(graph.nodes.length);
+    expect(filtered.edges.map((edge) => edge.kind)).toEqual(['transition']);
+  });
+
+  it('hides only the hubs when the Flow records no start Step', () => {
+    const graph = gate({ flow: { name: 'WithRecovery' } });
+    expect([...recoveryOnlySteps(graph)]).toEqual(['step:gate']);
+  });
+
+  it('renders fewer nodes with the layer off than with it on', () => {
+    const on = buildDefinitionScene(gate(), visible);
+    const off = buildDefinitionScene(gate(), { ...visible, recovery: false });
+    expect(off.nodes.length).toBeLessThan(on.nodes.length);
+    expect(on.nodes.some((node) => node.id === 'step:gate')).toBe(true);
+    expect(off.nodes.some((node) => node.id === 'step:gate')).toBe(false);
+  });
+});
+
+describe('decisions layer', () => {
+  it('re-sources a transition to the owning Step when the decision card is hidden', () => {
+    const withCards = buildDefinitionScene(graph, visible);
+    const collapsed = buildDefinitionScene(graph, { ...visible, decisions: false });
+    const transition = (scene: typeof withCards) =>
+      scene.edges.find((edge) => edge.id === 'transition');
+
+    // With the card shown the edge leaves the decision; with it hidden the edge has to
+    // leave the Step, or it would point at a node outside the scene and be dropped.
+    expect(transition(withCards)?.source).toBe('decision:step:start:20:1');
+    expect(transition(collapsed)?.source).toBe('step:start');
+    expect(collapsed.nodes.some((node) => node.data.kind === 'decision')).toBe(false);
+  });
+
+  it('moves the branch guard onto the edge label, simplified', () => {
+    const guarded: FlowDefinitionGraph = {
+      ...graph,
+      nodes: graph.nodes.map((node) => (
+        node.id === 'decision:step:start:20:1'
+          ? { ...node, condition: 'not (frozen.ready) and not (records != 0)' }
+          : node
+      )),
+    };
+    const collapsed = buildDefinitionScene(guarded, { ...visible, decisions: false });
+    // Only the branch's own clause, with the negation folded into the comparison.
+    expect(collapsed.edges.find((edge) => edge.id === 'transition')?.label).toBe('records == 0');
+  });
+
+  it('leaves the label alone while the decision card is visible', () => {
+    const guarded: FlowDefinitionGraph = {
+      ...graph,
+      nodes: graph.nodes.map((node) => (
+        node.id === 'decision:step:start:20:1' ? { ...node, condition: 'records == 0' } : node
+      )),
+    };
+    const shown = buildDefinitionScene(guarded, visible);
+    expect(shown.edges.find((edge) => edge.id === 'transition')?.label).toBe('');
+  });
+});
+
+describe('derived legibility', () => {
+  it('calls a Step a gate when its WaitFor holds a Channel condition', () => {
+    // Dex already models human-in-the-loop as WaitFor(Channel). Naming it adds no
+    // concept — it promotes one that was already in the graph.
+    expect(stepRole(graph, 'step:start')).toBe('gate');
+    expect(stepRole(graph, 'step:next')).toBe('work');
+  });
+
+  it('prefers a SubFlow batch over nothing, and Timers alone are not a gate', () => {
+    const timerOnly: FlowDefinitionGraph = {
+      ...graph,
+      nodes: graph.nodes.map((node) => (
+        node.id === 'wait:start:10:1'
+          ? { ...node, wait: { type: 'anyOf', conditions: [{ kind: 'timer' as const, label: '1h' }] } }
+          : node
+      )),
+    };
+    expect(stepRole(timerOnly, 'step:start')).toBe('work');
+
+    const batched: FlowDefinitionGraph = {
+      ...graph,
+      nodes: graph.nodes.map((node) => (
+        node.id === 'wait:start:10:1'
+          ? { ...node, wait: { type: 'allOf', conditions: [{ kind: 'subflow' as const, label: 'child' }] } }
+          : node
+      )),
+    };
+    expect(stepRole(batched, 'step:start')).toBe('batch');
+  });
+
+  it('writes the wait as a sentence, keeping the operator handles verbatim', () => {
+    const sentence = waitSentence(graph, 'step:start');
+    // The Channel name is what you publish to, so it survives unchanged...
+    expect(sentence).toContain('first');
+    // ...while the framework scaffolding around it does not.
+    expect(sentence).not.toContain('anyOf');
+    expect(sentence).not.toContain('.for 1');
+    expect(waitSentence(graph, 'step:next')).toBe('');
+  });
+
+  it('shows a display name from the schema metadata but never loses the type name', () => {
+    const step = graph.nodes.find((node) => node.id === 'step:start')!;
+    expect(displayName(step)).toBe(step.name);
+    expect(displayName({ ...step, metadata: { displayName: 'Rule on the difficult calls' } }))
+      .toBe('Rule on the difficult calls');
+    // An empty or non-string value must not blank the card.
+    expect(displayName({ ...step, metadata: { displayName: '  ' } })).toBe(step.name);
+    expect(displayName({ ...step, metadata: { displayName: 42 } })).toBe(step.name);
+  });
+});

From fc2d22e8f8c7b758148ee2c34ac719ac983cffab Mon Sep 17 00:00:00 2001
From: zzheng <zzheng.pm@gmail.com>
Date: Sun, 6 Sep 2026 22:20:34 -0700
Subject: [PATCH 2/3] Open the definition graph on the Steps, not their
 internals

The graph opened with every layer visible, so a reader met WaitFor shapes,
decision cards and resource rails before they met the Steps. On a twelve-Step
Flow only eleven of sixty-three drawn nodes were Steps.

Open with waits, decisions, RPCs, attributes, channels and recovery hidden.
Each stays a legend button, so nothing is removed, only deferred. Rank
separation now follows the cards: the gap sized for a card holding a decision
grid leaves a collapsed column mostly empty and forces the viewport to zoom
the text away.

A Step card now shows its display name, its input and output, and a sentence
for what it waits on, all from the schema's per-node metadata. It sizes itself
to that content and lays it out as a column, so the title no longer sits on top
of the other lines. The Step type name moves to the selection panel, where a
developer resuming a run needs it, rather than competing with the name a reader
came for. A derived colour key explains why some cards differ, and is built
from the roles the Flow actually has.

Also exclude the linked renderer package from dep pre-bundling. Vite resolves
it through web/node_modules, so it was pre-bundled once per process and edits
to its source never reached the browser.
---
 .../src/FlowDefinitionGraph.tsx               | 80 ++++++++++++++++---
 .../src/definitionLayout.ts                   | 75 ++++++++++++++---
 .../flow-definition-renderer/src/styles.css   | 68 +++++++++++++---
 .../rendering/FlowDefinitionGraph.test.tsx    | 37 ++++++++-
 web/vite.config.ts                            |  8 ++
 5 files changed, 232 insertions(+), 36 deletions(-)

diff --git a/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx b/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx
index 0bbe56a81..7ca1dee66 100644
--- a/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx
+++ b/packages/flow-definition-renderer/src/FlowDefinitionGraph.tsx
@@ -34,8 +34,10 @@ import {
   type DefinitionLayer,
   type DefinitionNodeData,
   type DefinitionSelectionDetail,
+  stepRole,
   type DefinitionVisibility,
   type RecoveryLayout,
+  type StepRole,
 } from './definitionLayout';
 
 const layerLabels: Array<[DefinitionLayer | 'diagnostics', string]> = [
@@ -53,17 +55,47 @@ const layerLabels: Array<[DefinitionLayer | 'diagnostics', string]> = [
 
 const defaultVisibility: DefinitionVisibility & { diagnostics: boolean } = {
   control: true,
-  recovery: true,
-  waits: true,
-  decisions: true,
-  rpcs: true,
-  attributes: true,
-  channels: true,
+  // Off by default: recovery edges reach backwards across the whole Flow, so they cross
+  // most of the happy path and dominate the first read. Turn the layer on to trace them.
+  recovery: false,
+  // Off by default. A reader wants to know what each stage does and where they are
+  // needed; the WaitFor shapes, decision cards and resource rails are the second click.
+  // Every one of these is still one button away in the legend.
+  waits: false,
+  decisions: false,
+  rpcs: false,
+  attributes: false,
+  channels: false,
   streams: false,
   subflows: true,
   diagnostics: true,
 };
 
+/**
+ * Why some cards are a different colour. Each entry is derived from the graph, so a Flow
+ * with no gate never shows a gate key.
+ */
+const roleKey: Array<[StepRole, string]> = [
+  ['gate', 'someone outside the Flow must act before it moves on'],
+  ['batch', 'starts a SubFlow per item and waits for them all'],
+  ['work', 'runs on its own'],
+];
+
+function StepRoleKey({ roles }: { roles: Set<StepRole> }) {
+  const shown = roleKey.filter(([role]) => roles.has(role));
+  if (shown.length < 2) return null;
+  return (
+    <dl className="definition-role-key">
+      {shown.map(([role, meaning]) => (
+        <div key={role}>
+          <dt className={`definition-role-key-swatch definition-role-key-swatch--${role}`} />
+          <dd>{meaning}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
 const nodeTypes: NodeTypes = {
   definitionAttributes: AttributesNode,
   definitionChannel: ChannelNode,
@@ -85,11 +117,14 @@ const edgeTypes: EdgeTypes = { definitionEdge: DefinitionEdge };
 export function FlowDefinitionGraphView({
   displayName,
   graph,
+  initialVisibility,
 }: {
   displayName: string;
   graph: FlowDefinitionGraph;
+  /** Overrides which layers start visible. Every layer stays toggleable from the legend. */
+  initialVisibility?: Partial<DefinitionVisibility>;
 }) {
-  const [visibility, setVisibility] = useState(defaultVisibility);
+  const [visibility, setVisibility] = useState(() => ({ ...defaultVisibility, ...initialVisibility }));
   // ?recovery=steps|rail|table|traced — see RecoveryLayout. Review scaffolding: it lets
   // the three candidate placements be compared side by side on one build.
   const recoveryLayout = useMemo<RecoveryLayout>(() => {
@@ -101,6 +136,13 @@ export function FlowDefinitionGraphView({
       ? requested
       : 'steps';
   }, []);
+  const rolesInGraph = useMemo(() => {
+    const roles = new Set<StepRole>();
+    for (const node of graph.nodes) {
+      if (node.kind === 'step') roles.add(stepRole(graph, node.id));
+    }
+    return roles;
+  }, [graph]);
   const [selectedNodeID, setSelectedNodeID] = useState('');
   const [selectedEdgeID, setSelectedEdgeID] = useState('');
   const [isMiniMapExpanded, setIsMiniMapExpanded] = useState(false);
@@ -153,6 +195,7 @@ export function FlowDefinitionGraphView({
             </span>
           </div>
           <p>{graph.source.language} · {graph.source.path}</p>
+          <StepRoleKey roles={rolesInGraph} />
         </div>
         {recoveryLayout !== 'steps' ? (
           <span className="definition-preview-badge">recovery: {recoveryLayout}</span>
@@ -243,6 +286,9 @@ export function FlowDefinitionGraphView({
             <span>{selectionKind(selectedNode.data)}</span>
             <b>{selectionName(selectedNode.data)}</b>
           </div>
+          {selectionTypeName(selectedNode.data) && (
+            <code>{selectedNode.data.kind === 'step' ? 'Step type ' : ''}{selectionTypeName(selectedNode.data)}</code>
+          )}
           <code>{selectedNode.id}</code>
           {selectedNode.data.sourceTitle && <span>{selectedNode.data.sourceTitle}</span>}
           <SelectionDetails details={selectedNode.data.selectionDetails} />
@@ -301,12 +347,13 @@ function StepNode({ data }: NodeProps) {
       <div className="definition-step-title">
         <strong>{shown}</strong>
         {definition.start && <span>START</span>}
-        {role === 'gate' && <span className="definition-step-actor">SOMEONE MUST ACT</span>}
       </div>
-      {/* The type name stays on the card whenever a display name covers it: it is the
-          durable identity, the thing you pass to dexcli and name in a resume. */}
-      {shown !== definition.name && (
-        <div className="definition-step-type">{definition.name}</div>
+      {role === 'gate' && <span className="definition-step-actor">SOMEONE MUST ACT</span>}
+      {(nodeData.inputLabel || nodeData.outputLabel) && (
+        <div className="definition-step-io">
+          {nodeData.inputLabel && <span><em>in</em> {nodeData.inputLabel}</span>}
+          {nodeData.outputLabel && <span className="out"><em>out</em> {nodeData.outputLabel}</span>}
+        </div>
       )}
       {nodeData.waitSentence ? (
         <div className="definition-step-wait">{nodeData.waitSentence}</div>
@@ -673,7 +720,14 @@ function selectionKind(data: DefinitionNodeData): string {
 
 function selectionName(data: DefinitionNodeData): string {
   if (data.kind === 'attributes') return `${data.definitions?.length ?? 0} definitions`;
-  return data.definition?.name ?? data.displayName ?? data.kind;
+  return data.displayName ?? data.definition?.name ?? data.kind;
+}
+
+/** The Step type name, only when a display name is standing in front of it. */
+function selectionTypeName(data: DefinitionNodeData): string | undefined {
+  const name = data.definition?.name;
+  if (!name || name === data.displayName) return undefined;
+  return name;
 }
 
 function edgeKindLabel(edge: Edge<DefinitionEdgeData>): string {
diff --git a/packages/flow-definition-renderer/src/definitionLayout.ts b/packages/flow-definition-renderer/src/definitionLayout.ts
index 7f5d72ef1..4fe2b061f 100644
--- a/packages/flow-definition-renderer/src/definitionLayout.ts
+++ b/packages/flow-definition-renderer/src/definitionLayout.ts
@@ -36,6 +36,8 @@ export interface DefinitionNodeData extends Record<string, unknown> {
   displayName?: string;
   role?: StepRole;
   waitSentence?: string;
+  inputLabel?: string;
+  outputLabel?: string;
   relatedEdges?: FlowDefinitionEdge[];
   nameByID?: Record<string, string>;
   selectionDetails?: DefinitionSelectionDetail[];
@@ -88,6 +90,10 @@ const branchGap = 42;
 const cardWidth = 288;
 const dispatchSize = 58;
 const stepTopologyRankSeparation = 168;
+// Collapsed cards are a fraction of the height of a card holding WaitFor shapes and
+// decision grids, so the gap sized for those leaves the column mostly empty and forces
+// the viewport to zoom the text away.
+const collapsedTopologyRankSeparation = 76;
 
 /**
  * Steps that exist only to absorb a failure, derived from the graph rather than named.
@@ -222,6 +228,13 @@ export function stepRole(graph: FlowDefinitionGraph, stepID: string): StepRole {
  * suffix a reader has no use for.
  */
 export function waitSentence(graph: FlowDefinitionGraph, stepID: string): string {
+  const step = graph.nodes.find((node) => node.id === stepID);
+  const authored = step ? metadataText(step, 'waitLabel') : '';
+  if (authored) return authored;
+  return derivedWaitSentence(graph, stepID);
+}
+
+function derivedWaitSentence(graph: FlowDefinitionGraph, stepID: string): string {
   const waits = graph.nodes.filter((node) => node.kind === 'wait' && node.parentId === stepID);
   const real = waits.filter((node) => node.wait?.type !== 'skipWaitImmediately');
   if (real.length === 0) return '';
@@ -257,6 +270,12 @@ export function waitSentence(graph: FlowDefinitionGraph, stepID: string): string
  * contract of an open execution, so a display name must never replace it — only sit in
  * front of it.
  */
+/** One string out of the schema's per-node `metadata`, or empty. */
+export function metadataText(node: FlowDefinitionNode, key: string): string {
+  const value = (node.metadata as Record<string, unknown> | undefined)?.[key];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
 export function displayName(node: FlowDefinitionNode): string {
   const provided = (node.metadata as { displayName?: unknown } | undefined)?.displayName;
   return typeof provided === 'string' && provided.trim() !== '' ? provided : node.name;
@@ -338,6 +357,8 @@ export function buildDefinitionScene(
           displayName: displayName(step),
           role: stepRole(graph, step.id),
           waitSentence: waitSentence(graph, step.id),
+          inputLabel: metadataText(step, 'inputLabel'),
+          outputLabel: metadataText(step, 'outputLabel'),
           sourceTitle: sourceTitle(step.span),
         },
     } satisfies Node<DefinitionNodeData>;
@@ -537,9 +558,9 @@ function layoutStep(
     (group) => decisionDimensions(group, graph.edges, nameByID),
   );
   const unknownSection = { height: unknownDefinitions.length * 82, width: 224 };
-  const contentWidth = Math.max(268, waitSection.width, decisionSection.width, unknownSection.width);
+  const contentWidth = Math.max(336, waitSection.width, decisionSection.width, unknownSection.width);
   const width = contentWidth + stepGap * 2;
-  let cursorTop = stepHeaderHeight(step.name, width);
+  let cursorTop = stepHeaderHeight(step, width, waitSentence(graph, step.id), stepRole(graph, step.id));
   const children: Array<Node<DefinitionNodeData>> = [];
   if (waitDefinitions.length > 0) {
     const placed = placeSection(step.id, waitGroups, cursorTop, contentWidth, 'wait');
@@ -564,7 +585,7 @@ function layoutStep(
   }
   return {
     children,
-    dimensions: { height: Math.max(154, cursorTop), width },
+    dimensions: { height: Math.max(72, cursorTop), width },
   };
 }
 
@@ -759,11 +780,14 @@ function layoutStepTopology(
   definitionsByID: Map<string, FlowDefinitionNode>,
 ): Map<string, { x: number; y: number }> {
   if (steps.length === 0) return new Map();
+  const rankSeparation = [...stepLayouts.values()].some((layout) => layout.children.length > 0)
+    ? stepTopologyRankSeparation
+    : collapsedTopologyRankSeparation;
   const dagreGraph = new dagre.graphlib.Graph();
   dagreGraph.setDefaultEdgeLabel(() => ({}));
   dagreGraph.setGraph({
     rankdir: 'TB',
-    ranksep: stepTopologyRankSeparation,
+    ranksep: rankSeparation,
     nodesep: 104,
     marginx: 0,
     marginy: 0,
@@ -795,7 +819,7 @@ function layoutStepTopology(
     x: position.x - minimumX,
     y: position.y - minimumY,
   }]));
-  return placeStartStepFirst(graph.flow.startStepId, steps, stepLayouts, positions);
+  return placeStartStepFirst(graph.flow.startStepId, steps, stepLayouts, positions, rankSeparation);
 }
 
 function placeStartStepFirst(
@@ -803,6 +827,7 @@ function placeStartStepFirst(
   steps: FlowDefinitionNode[],
   stepLayouts: Map<string, StepLayout>,
   positions: Map<string, { x: number; y: number }>,
+  rankSeparation: number,
 ): Map<string, { x: number; y: number }> {
   if (!startStepID) return positions;
   const startPosition = positions.get(startStepID);
@@ -814,7 +839,7 @@ function placeStartStepFirst(
     const position = positions.get(step.id)!;
     return position.x + stepLayouts.get(step.id)!.dimensions.width;
   }));
-  const verticalOffset = startDimensions.height + stepTopologyRankSeparation;
+  const verticalOffset = startDimensions.height + rankSeparation;
   const reordered = new Map([...positions].map(([stepID, position]) => [stepID, stepID === startStepID
     ? { x: Math.max(0, (topologyWidth - startDimensions.width) / 2), y: 0 }
     : { x: position.x, y: position.y + verticalOffset }]));
@@ -1263,9 +1288,41 @@ function isDashed(kind: string): boolean {
   return kind.startsWith('resource_') || kind === 'wait_condition' || kind === 'subflow';
 }
 
-function stepHeaderHeight(name: string, width: number): number {
-  const availableCharacters = Math.max(24, Math.floor((width - 112) / 8));
-  return Math.max(52, 28 + wrappedLineCount(name, availableCharacters) * 20);
+/**
+ * Height of everything the Step card draws above its children: the shown name, the in/out
+ * pair, and the wait sentence. The per-line figures track styles.css; when a rule there
+ * changes font size or line height, change the matching number here.
+ */
+function stepHeaderHeight(
+  node: FlowDefinitionNode,
+  width: number,
+  sentence: string,
+  role: StepRole,
+): number {
+  // .definition-step-frame padding-top.
+  let height = 12;
+  // .definition-step-title strong: 17px on a 21px line, max-width calc(100% - 60px).
+  const titleCharacters = Math.max(18, Math.floor((width - 88) / 9));
+  height += wrappedLineCount(displayName(node), titleCharacters) * 21;
+  // .definition-step-actor, which only a gate draws.
+  if (role === 'gate') height += 21;
+  // .definition-step-io: 9px monospace on a 12px line, one line each for `in` and `out`.
+  const ioCharacters = Math.max(24, Math.floor((width - 56) / 5.4));
+  const inputLines = wrappedLineCountOrZero(metadataText(node, 'inputLabel'), ioCharacters);
+  const outputLines = wrappedLineCountOrZero(metadataText(node, 'outputLabel'), ioCharacters);
+  if (inputLines + outputLines > 0) height += 4 + (inputLines + outputLines) * 12;
+  // .definition-step-wait: 9.5px, line-height 1.4, under a dashed rule.
+  if (sentence) {
+    const waitCharacters = Math.max(28, Math.floor((width - 56) / 4.8));
+    height += 11 + wrappedLineCount(sentence, waitCharacters) * 14;
+  }
+  // .definition-step-frame padding-bottom.
+  return height + 14;
+}
+
+/** Like wrappedLineCount, but an absent string occupies no lines at all. */
+function wrappedLineCountOrZero(value: string, charactersPerLine: number): number {
+  return value ? wrappedLineCount(value, charactersPerLine) : 0;
 }
 
 function wrappedLineCount(value: string, charactersPerLine: number): number {
diff --git a/packages/flow-definition-renderer/src/styles.css b/packages/flow-definition-renderer/src/styles.css
index c030b9895..603908714 100644
--- a/packages/flow-definition-renderer/src/styles.css
+++ b/packages/flow-definition-renderer/src/styles.css
@@ -247,6 +247,9 @@
 }
 
 .definition-step-frame {
+  display: flex;
+  padding: 12px 14px 14px;
+  flex-direction: column;
   border: 2px solid #6b97ca;
   border-radius: 9px;
   background: #eaf3fd;
@@ -254,13 +257,7 @@
 }
 
 .definition-step-title {
-  position: absolute;
-  top: 0;
-  left: 0;
   display: flex;
-  width: 100%;
-  min-height: 46px;
-  padding: 7px 14px 5px;
   align-items: center;
   justify-content: center;
 }
@@ -270,7 +267,7 @@
   color: #1e2c3f;
   font-size: 17px;
   font-weight: 650;
-  line-height: 1.2;
+  line-height: 21px;
   overflow-wrap: anywhere;
   text-align: center;
 }
@@ -524,7 +521,8 @@
 }
 
 .definition-step-actor {
-  margin-left: 8px;
+  align-self: flex-start;
+  margin-top: 6px;
   padding: 1px 6px;
   border-radius: 999px;
   background: #c43b62;
@@ -534,12 +532,60 @@
   letter-spacing: 0.07em;
 }
 
-.definition-step-type {
-  margin-top: 2px;
-  color: #93a2b8;
+.definition-role-key {
+  display: grid;
+  margin: 9px 0 0;
+  gap: 3px;
+}
+
+.definition-role-key > div {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+}
+
+.definition-role-key dd {
+  margin: 0;
+  color: var(--flow-definition-muted);
+  font-size: 11px;
+}
+
+.definition-role-key-swatch {
+  width: 15px;
+  height: 11px;
+  flex: 0 0 15px;
+  border: 2px solid #6b97ca;
+  border-radius: 3px;
+  background: #eaf3fd;
+}
+
+.definition-role-key-swatch--gate {
+  border-color: #c43b62;
+  background: #fdf1f4;
+}
+
+.definition-role-key-swatch--batch {
+  border-color: #b3760f;
+  background: #fffaf0;
+}
+
+.definition-step-io {
+  display: grid;
+  gap: 1px;
+  margin-top: 4px;
+  color: #4f6178;
   font: 9px ui-monospace, Menlo, monospace;
 }
 
+.definition-step-io em {
+  display: inline-block;
+  width: 22px;
+  color: #93a2b8;
+  font-style: normal;
+}
+
+.definition-step-io .out { color: #1f6f3f; }
+
 .definition-step-wait {
   margin-top: 5px;
   padding-top: 5px;
diff --git a/web/app/rendering/FlowDefinitionGraph.test.tsx b/web/app/rendering/FlowDefinitionGraph.test.tsx
index 8688bf9a7..994243705 100644
--- a/web/app/rendering/FlowDefinitionGraph.test.tsx
+++ b/web/app/rendering/FlowDefinitionGraph.test.tsx
@@ -16,7 +16,14 @@ import {
 
 describe('Flow Definition Graph renderer', () => {
   it('renders semantic shapes, icons, and failure diagnostics', () => {
-    const markup = renderToStaticMarkup(<FlowDefinitionGraphView displayName="Example" graph={graph} />);
+    // Internals are hidden on open, so this asks for every layer explicitly.
+    const markup = renderToStaticMarkup(
+      <FlowDefinitionGraphView
+        displayName="Example"
+        graph={graph}
+        initialVisibility={{ waits: true, decisions: true, rpcs: true, attributes: true, channels: true }}
+      />,
+    );
 
     expect(markup).toContain('definition-flow-frame');
     expect(markup).toContain('definition-step-frame');
@@ -41,11 +48,35 @@ describe('Flow Definition Graph renderer', () => {
     expect(markup).not.toContain('title="lines ');
   });
 
-  it('keeps Streams hidden by default while resources remain visible', () => {
+  it('opens on the Steps alone, with every internal layer one click away', () => {
     const markup = renderToStaticMarkup(<FlowDefinitionGraphView displayName="Example" graph={graph} />);
 
+    // What a reader sees first: the Steps and the transitions between them.
+    expect(markup).toContain('definition-step-frame');
+    // Not the machinery inside them.
+    expect(markup).not.toContain('definition-wait-shape');
+    expect(markup).not.toContain('definition-decision-card');
+    expect(markup).not.toContain('definition-attributes-box');
+    expect(markup).not.toContain('definition-channel-pipe');
+    expect(markup).not.toContain('definition-rpc-hexagon');
+    // Hidden, not removed: each one is still a legend button.
+    for (const label of ['WaitFor', 'Decisions', 'Attributes', 'Channels', 'RPC']) {
+      expect(markup).toContain(`>${label}</button>`);
+    }
+  });
+
+  it('keeps Streams hidden even when the other internal layers are asked for', () => {
+    const markup = renderToStaticMarkup(
+      <FlowDefinitionGraphView
+        displayName="Example"
+        graph={graph}
+        initialVisibility={{ waits: true, decisions: true, rpcs: true, attributes: true, channels: true }}
+      />,
+    );
+
+    // Streams carry best-effort progress, not structure, so they stay off until asked for.
     expect(markup).not.toContain('definition-stream-node');
-    expect(markup).toContain('aria-pressed="true"');
+    expect(markup).toContain('definition-attributes-box');
     expect(markup).toContain('aria-pressed="false"');
   });
 
diff --git a/web/vite.config.ts b/web/vite.config.ts
index 18657246a..a57babfa0 100644
--- a/web/vite.config.ts
+++ b/web/vite.config.ts
@@ -18,6 +18,14 @@ export default defineConfig({
       '@': fileURLToPath(new URL('.', import.meta.url)),
     },
   },
+  optimizeDeps: {
+    // preserveSymlinks resolves the linked workspace packages through web/node_modules, so
+    // Vite would otherwise pre-bundle them and serve that bundle for the life of the
+    // process, hiding every edit to their source. Excluding them serves the source instead.
+    // Their files still sit under node_modules, which the watcher ignores, so restart the
+    // dev server after editing one.
+    exclude: ['@superdurable/flow-definition-renderer'],
+  },
   server: {
     proxy: {
       '/api': process.env.DEX_WEB_PROXY ?? 'http://127.0.0.1:8902',

From 80bb235d0b561a96fc58944203861830f5957873 Mon Sep 17 00:00:00 2001
From: zzheng <zzheng.pm@gmail.com>
Date: Mon, 7 Sep 2026 08:48:40 -0700
Subject: [PATCH 3/3] Reattach the displayName doc comment and shorten two
 blocks

The displayName block was left above metadataText when that function was
inserted between them, so it documented the wrong function. Both blocks also
exceeded the repository's comment-length rule.
---
 .../src/definitionLayout.ts                   | 23 ++++---------------
 1 file changed, 5 insertions(+), 18 deletions(-)

diff --git a/packages/flow-definition-renderer/src/definitionLayout.ts b/packages/flow-definition-renderer/src/definitionLayout.ts
index 4fe2b061f..656239a4d 100644
--- a/packages/flow-definition-renderer/src/definitionLayout.ts
+++ b/packages/flow-definition-renderer/src/definitionLayout.ts
@@ -194,17 +194,11 @@ export function withoutRecoveryPaths(graph: FlowDefinitionGraph): FlowDefinition
  *   traced  the rail card, with its edges revealed only while it is selected
  */
 /**
- * What a Step is, in the reader's terms, derived only from Dex's own vocabulary.
+ * What a Step is, read from its WaitFor conditions alone.
  *
- *   gate   its WaitFor has a Channel condition, so an actor outside the Flow must publish
- *          before it proceeds. Dex already models human-in-the-loop this way; naming it
- *          adds no concept, it promotes one that was already there.
- *   batch  its WaitFor has a SubFlow condition: it fans out and waits for children.
- *   work   pure Execute, or a wait on Timers alone.
- *
- * What a graph cannot answer — whether a model or a script does the work — is deliberately
- * absent. That is an application fact, not a Dex one, and belongs in the schema's own
- * `metadata` extension point rather than in this vocabulary.
+ *   gate   a Channel condition: an actor outside the Flow must publish first
+ *   batch  a SubFlow condition: it fans out and waits for children
+ *   work   pure Execute, or a wait on Timers alone
  */
 export type StepRole = 'gate' | 'batch' | 'work';
 
@@ -262,20 +256,13 @@ function derivedWaitSentence(graph: FlowDefinitionGraph, stepID: string): string
   return clauses.join(', ') + skippable;
 }
 
-/**
- * The name to show on a card.
- *
- * Uses the FDG schema's existing per-node `metadata` rather than a new field, and falls
- * back to the durable type name, which is always present. A Step type name is part of the
- * contract of an open execution, so a display name must never replace it — only sit in
- * front of it.
- */
 /** One string out of the schema's per-node `metadata`, or empty. */
 export function metadataText(node: FlowDefinitionNode, key: string): string {
   const value = (node.metadata as Record<string, unknown> | undefined)?.[key];
   return typeof value === 'string' ? value.trim() : '';
 }
 
+/** The card's name: authored `metadata.displayName`, else the durable type name. */
 export function displayName(node: FlowDefinitionNode): string {
   const provided = (node.metadata as { displayName?: unknown } | undefined)?.displayName;
   return typeof provided === 'string' && provided.trim() !== '' ? provided : node.name;