@diagrammo/dgmo 0.5.2 → 0.5.4

package/src/index.ts

@@ -218,6 +218,9 @@ export type {
 
 export { renderInitiativeStatus, renderInitiativeStatusForExport } from './initiative-status/renderer';
 
+export { collapseInitiativeStatus } from './initiative-status/collapse';
+export type { CollapseResult } from './initiative-status/collapse';
+
 export { parseSitemap, looksLikeSitemap } from './sitemap/parser';
 
 export type {

package/src/infra/compute.ts

@@ -295,29 +295,35 @@ function collapseGroups(parsed: ParsedInfra, collapsedIds: Set<string>, defaultL
     const children = groupChildren.get(group.id) ?? [];
     if (children.length === 0) continue;
 
-    // Aggregate properties: sum latencies, bottleneck capacity, compose behaviors
-    let totalLatency = 0;
+    // Aggregate properties: bottleneck capacity, compose behaviors
+    // Latency is computed separately below via critical-path analysis.
     let minEffectiveCapacity = Infinity;
     let hasMaxRps = false;
     let composedUptime = 1;
     const behaviorProps: InfraProperty[] = [];
     const perChildCapacities: number[] = [];
 
+    // Collect per-child latency values for critical-path computation
+    const childIdSet = new Set(children.map((c) => c.id));
+    const childLatencies = new Map<string, number>();
+
     for (const child of children) {
       // Latency: use explicit value, or diagram default (matching BFS behavior)
       const latencyProp = child.properties.find((p) => p.key === 'latency-ms');
       const childIsServerless = child.properties.some((p) => p.key === 'concurrency');
+      let childLat: number;
       if (childIsServerless) {
         // Serverless nodes use duration-ms as latency contribution
         const durationProp = child.properties.find((p) => p.key === 'duration-ms');
-        totalLatency += durationProp
+        childLat = durationProp
           ? (typeof durationProp.value === 'number' ? durationProp.value : parseFloat(String(durationProp.value)) || 100)
           : 100;
       } else if (latencyProp) {
-        totalLatency += (typeof latencyProp.value === 'number' ? latencyProp.value : parseFloat(String(latencyProp.value)) || 0);
+        childLat = typeof latencyProp.value === 'number' ? latencyProp.value : parseFloat(String(latencyProp.value)) || 0;
       } else {
-        totalLatency += defaultLatencyMs;
+        childLat = defaultLatencyMs;
       }
+      childLatencies.set(child.id, childLat);
 
       const maxRps = child.properties.find((p) => p.key === 'max-rps');
       if (maxRps) {
@@ -349,6 +355,73 @@ function collapseGroups(parsed: ParsedInfra, collapsedIds: Set<string>, defaultL
       }
     }
 
+    // ── Critical-path latency through the group ──────────────────────────────
+    // totalLatency = max path length from external-inbound entry nodes to
+    // external-outbound exit nodes, traversing only internal edges.
+    // This prevents side-dependency latencies (nodes only reached via internal
+    // edges with no external exit) from inflating the virtual node's latency.
+    const entryIds = new Set<string>();
+    const exitIds = new Set<string>();
+    for (const edge of inboundEdges) {
+      if (childIdSet.has(edge.targetId)) entryIds.add(edge.targetId);
+    }
+    for (const edge of outboundEdges) {
+      if (childIdSet.has(edge.sourceId)) exitIds.add(edge.sourceId);
+    }
+    for (const edge of crossGroupEdges) {
+      if (childIdSet.has(edge.sourceId)) exitIds.add(edge.sourceId);
+      if (childIdSet.has(edge.targetId)) entryIds.add(edge.targetId);
+    }
+
+    // Build forward adjacency for internal edges scoped to this group
+    const fwdAdj = new Map<string, string[]>();
+    for (const edge of internalEdges) {
+      if (!childIdSet.has(edge.sourceId) || !childIdSet.has(edge.targetId)) continue;
+      const list = fwdAdj.get(edge.sourceId) ?? [];
+      list.push(edge.targetId);
+      fwdAdj.set(edge.sourceId, list);
+    }
+
+    // DAG longest-path from entry nodes (topological DFS + relaxation)
+    const topoOrder: string[] = [];
+    const tsVisited = new Set<string>();
+    const dfsTopoSort = (id: string) => {
+      if (tsVisited.has(id)) return;
+      tsVisited.add(id);
+      for (const next of fwdAdj.get(id) ?? []) dfsTopoSort(next);
+      topoOrder.unshift(id);
+    };
+    for (const child of children) dfsTopoSort(child.id);
+
+    const dist = new Map<string, number>();
+    for (const child of children) {
+      dist.set(child.id, entryIds.has(child.id) ? (childLatencies.get(child.id) ?? 0) : -Infinity);
+    }
+    for (const nodeId of topoOrder) {
+      const curDist = dist.get(nodeId) ?? -Infinity;
+      if (curDist === -Infinity) continue;
+      for (const nextId of fwdAdj.get(nodeId) ?? []) {
+        const newDist = curDist + (childLatencies.get(nextId) ?? 0);
+        if (newDist > (dist.get(nextId) ?? -Infinity)) dist.set(nextId, newDist);
+      }
+    }
+
+    let totalLatency = 0;
+    if (exitIds.size > 0) {
+      for (const id of exitIds) {
+        const d = dist.get(id);
+        if (d !== undefined && d > -Infinity && d > totalLatency) totalLatency = d;
+      }
+    } else if (entryIds.size > 0) {
+      // No explicit exits — use max reachable distance from entry nodes
+      for (const [, d] of dist) {
+        if (d > 0 && d > totalLatency) totalLatency = d;
+      }
+    } else {
+      // No external connections — fall back to summing all children
+      for (const [, lat] of childLatencies) totalLatency += lat;
+    }
+
     // Build virtual node properties
     const props: InfraProperty[] = [];
     if (totalLatency > 0) props.push({ key: 'latency-ms', value: totalLatency, lineNumber: group.lineNumber });
@@ -692,8 +765,10 @@ export function computeInfra(
 
       for (const { edge, split } of resolved) {
         const edgeRps = outboundRps * (split / 100);
+        const fanout = (edge.fanout != null && edge.fanout >= 1) ? edge.fanout : 1;
+        const fanoutedRps = edgeRps * fanout;
         const edgeKey = `${edge.sourceId}->${edge.targetId}`;
-        computedEdgeRps.set(edgeKey, edgeRps);
+        computedEdgeRps.set(edgeKey, fanoutedRps);
 
         // Resolve target — could be a group or a node
         let targetIds: string[];
@@ -705,7 +780,7 @@ export function computeInfra(
         }
 
         for (const targetId of targetIds) {
-          const perTarget = edgeRps / targetIds.length;
+          const perTarget = fanoutedRps / targetIds.length;
           const existing = computedRps.get(targetId) ?? 0;
           computedRps.set(targetId, existing + perTarget);
 
@@ -837,6 +912,7 @@ export function computeInfra(
     const paths: LeafPath[] = [];
 
     for (const { edge, split } of resolved) {
+      const fanout = (edge.fanout != null && edge.fanout >= 1) ? edge.fanout : 1;
       const groupChildren = groupChildMap.get(edge.targetId);
       const targetIds = (groupChildren && groupChildren.length > 0)
         ? groupChildren : [edge.targetId];
@@ -850,21 +926,21 @@ export function computeInfra(
               latency: nodeLatency + cp.latency,
               uptime: nodeUptimeFrac * cp.uptime,
               availability: nodeAvail * cp.availability,
-              weight: cp.weight * (split / 100) / targetIds.length * 0.95,
+              weight: cp.weight * (split / 100) / targetIds.length * fanout * 0.95,
             });
             // Cold path (5% of requests)
             paths.push({
               latency: coldLatency + cp.latency,
               uptime: nodeUptimeFrac * cp.uptime,
               availability: nodeAvail * cp.availability,
-              weight: cp.weight * (split / 100) / targetIds.length * 0.05,
+              weight: cp.weight * (split / 100) / targetIds.length * fanout * 0.05,
             });
           } else {
             paths.push({
               latency: nodeLatency + cp.latency,
               uptime: nodeUptimeFrac * cp.uptime,
               availability: nodeAvail * cp.availability,
-              weight: cp.weight * (split / 100) / targetIds.length,
+              weight: cp.weight * (split / 100) / targetIds.length * fanout,
             });
           }
         }
@@ -1063,6 +1139,7 @@ export function computeInfra(
       queueMetrics,
       properties: node.properties,
       tags: node.tags,
+      description: node.description,
       lineNumber: node.lineNumber,
     };
   });
@@ -1093,6 +1170,7 @@ export function computeInfra(
       label: edge.label,
       computedRps: rps,
       split: resolvedSplit,
+      fanout: edge.fanout,
       lineNumber: edge.lineNumber,
     };
   });

package/src/infra/layout.ts

@@ -41,6 +41,7 @@ export interface InfraLayoutNode {
   properties: ComputedInfraNode['properties'];
   queueMetrics?: ComputedInfraNode['queueMetrics'];
   tags: Record<string, string>;
+  description?: string;
   lineNumber: number;
 }
 
@@ -50,6 +51,7 @@ export interface InfraLayoutEdge {
   label: string;
   computedRps: number;
   split: number;
+  fanout: number | null;
   points: { x: number; y: number }[];
   lineNumber: number;
 }
@@ -109,8 +111,8 @@ const DISPLAY_KEYS = new Set([
 /** Display names for width estimation. */
 const DISPLAY_NAMES: Record<string, string> = {
   'cache-hit': 'cache hit', 'firewall-block': 'fw block',
-  'ratelimit-rps': 'rate limit', 'latency-ms': 'latency', 'uptime': 'uptime',
-  'instances': 'instances', 'max-rps': 'capacity',
+  'ratelimit-rps': 'rate limit RPS', 'latency-ms': 'latency', 'uptime': 'uptime',
+  'instances': 'instances', 'max-rps': 'max RPS',
   'cb-error-threshold': 'CB error', 'cb-latency-threshold-ms': 'CB latency',
   'concurrency': 'concurrency', 'duration-ms': 'duration', 'cold-start-ms': 'cold start',
   'buffer': 'buffer', 'drain-rate': 'drain', 'retention-hours': 'retention', 'partitions': 'partitions',
@@ -133,13 +135,13 @@ function countDisplayProps(node: ComputedInfraNode, expanded: boolean, options?:
   return count;
 }
 
-/** Count computed rows shown below declared props. When expanded, shows p50/p90/p99; otherwise just p99. */
+/** Count computed rows shown below declared props. When expanded, shows p50/p90/p99; otherwise just p90. */
 function countComputedRows(node: ComputedInfraNode, expanded: boolean): number {
   let count = 0;
   // Serverless instances row
   if (node.computedConcurrentInvocations > 0) count += 1;
   const p = node.computedLatencyPercentiles;
-  if (p.p50 > 0 || p.p90 > 0 || p.p99 > 0) count += expanded ? 3 : 1; // all percentiles or just p99
+  if (p.p50 > 0 || p.p90 > 0 || p.p99 > 0) count += expanded ? 3 : 1; // all percentiles or just p90
   if (node.computedUptime < 1) {
     const declaredUptime = node.properties.find((p) => p.key === 'uptime');
     const declaredVal = declaredUptime ? Number(declaredUptime.value) / 100 : 1;
@@ -196,7 +198,7 @@ function computeNodeWidth(node: ComputedInfraNode, expanded: boolean, options?:
       if (expanded) {
         allKeys.push('p50', 'p90', 'p99');
       } else {
-        allKeys.push('p99');
+        allKeys.push('p90');
       }
     }
     if (node.computedUptime < 1) {
@@ -253,16 +255,30 @@ function computeNodeWidth(node: ComputedInfraNode, expanded: boolean, options?:
       maxRowWidth = Math.max(maxRowWidth, (maxKeyLen + 2 + valLen) * META_CHAR_WIDTH);
     }
   }
-  // Computed row widths (e.g., "p99: 120ms")
+  // Computed row widths (e.g., "p90: 520ms" or "p90: 520ms / 500ms" when SLO configured)
   if (computedRows > 0) {
     const perc = node.computedLatencyPercentiles;
-    const msValues = expanded ? [perc.p50, perc.p90, perc.p99] : [perc.p99];
+    const msValues = expanded ? [perc.p50, perc.p90, perc.p99] : [perc.p90];
     for (const ms of msValues) {
       if (ms > 0) {
         const valLen = formatMs(ms).length;
         maxRowWidth = Math.max(maxRowWidth, (maxKeyLen + 2 + valLen) * META_CHAR_WIDTH);
       }
     }
+    // p90 may show "<current> / <threshold>" when non-green. Always reserve combined width
+    // so node width doesn't reflow when SLO state transitions from green to warning/overloaded.
+    if (perc.p90 > 0) {
+      const rawThreshold =
+        node.properties.find((p) => p.key === 'slo-p90-latency-ms')?.value ??
+        options?.['slo-p90-latency-ms'];
+      const threshold = rawThreshold != null ? parseFloat(String(rawThreshold)) : NaN;
+      if (!isNaN(threshold) && threshold > 0) {
+        // formatMs here must produce the same string as formatMsShort in renderer.ts — both are identical.
+        // If either changes, the reserved width and the rendered text will diverge.
+        const combinedVal = `${formatMs(perc.p90)} / ${formatMs(threshold)}`;
+        maxRowWidth = Math.max(maxRowWidth, (maxKeyLen + 2 + combinedVal.length) * META_CHAR_WIDTH);
+      }
+    }
     if (node.computedUptime < 1) {
       const valLen = formatUptime(node.computedUptime).length;
       maxRowWidth = Math.max(maxRowWidth, (maxKeyLen + 2 + valLen) * META_CHAR_WIDTH);
@@ -277,16 +293,21 @@ function computeNodeWidth(node: ComputedInfraNode, expanded: boolean, options?:
     }
   }
 
-  return Math.max(MIN_NODE_WIDTH, labelWidth, maxRowWidth + 20);
+  const DESC_MAX_CHARS = 120;
+  const descText = (expanded && node.description && !node.isEdge) ? node.description : '';
+  const descTruncated = descText.length > DESC_MAX_CHARS ? descText.slice(0, DESC_MAX_CHARS - 1) + '…' : descText;
+  const descWidth = descTruncated.length > 0 ? descTruncated.length * META_CHAR_WIDTH + PADDING_X : 0;
+  return Math.max(MIN_NODE_WIDTH, labelWidth, maxRowWidth + 20, descWidth);
 }
 
 function computeNodeHeight(node: ComputedInfraNode, expanded: boolean, options?: Record<string, string>): number {
   const propCount = countDisplayProps(node, expanded, options);
   const computedCount = countComputedRows(node, expanded);
   const hasRps = node.computedRps > 0;
-  if (propCount === 0 && computedCount === 0 && !hasRps) return NODE_HEADER_HEIGHT + NODE_PAD_BOTTOM;
+  const descH = expanded && node.description && !node.isEdge ? META_LINE_HEIGHT : 0;
+  if (propCount === 0 && computedCount === 0 && !hasRps) return NODE_HEADER_HEIGHT + descH + NODE_PAD_BOTTOM;
 
-  let h = NODE_HEADER_HEIGHT + NODE_SEPARATOR_GAP;
+  let h = NODE_HEADER_HEIGHT + descH + NODE_SEPARATOR_GAP;
   // Computed section: RPS + computed rows
   const computedSectionCount = (hasRps ? 1 : 0) + computedCount;
   h += computedSectionCount * META_LINE_HEIGHT;
@@ -331,11 +352,69 @@ function formatUptime(fraction: number): string {
   return `${pct.toFixed(1)}%`;
 }
 
+// ============================================================
+// Group separation pass
+// ============================================================
+
+const GROUP_GAP = 24; // min clear gap between group boxes — matches GROUP_HEADER_HEIGHT
+
+export function separateGroups(
+  groups: InfraLayoutGroup[],
+  nodes: InfraLayoutNode[],
+  isLR: boolean,
+  maxIterations = 20,
+): void {
+  // Symmetric 2D rectangle intersection — no sorting needed, handles all
+  // relative positions correctly, stable after mid-pass shifts.
+  // Endpoint edge routing is not affected: renderer.ts recomputes border
+  // connection points from node x/y at render time via nodeBorderPoint().
+  for (let iter = 0; iter < maxIterations; iter++) {
+    let anyOverlap = false;
+    for (let i = 0; i < groups.length; i++) {
+      for (let j = i + 1; j < groups.length; j++) {
+        const ga = groups[i];
+        const gb = groups[j];
+
+        // Symmetric primary-axis overlap (Y for LR, X for TB)
+        const primaryOverlap = isLR
+          ? Math.min(ga.y + ga.height, gb.y + gb.height) - Math.max(ga.y, gb.y)
+          : Math.min(ga.x + ga.width, gb.x + gb.width) - Math.max(ga.x, gb.x);
+        if (primaryOverlap <= 0) continue;
+
+        // Symmetric cross-axis overlap — boxes must intersect in 2D
+        const crossOverlap = isLR
+          ? Math.min(ga.x + ga.width, gb.x + gb.width) - Math.max(ga.x, gb.x)
+          : Math.min(ga.y + ga.height, gb.y + gb.height) - Math.max(ga.y, gb.y);
+        if (crossOverlap <= 0) continue;
+
+        anyOverlap = true;
+        const shift = primaryOverlap + GROUP_GAP;
+
+        // Shift the group with the larger primary-axis center (deterministic)
+        const aCenter = isLR ? ga.y + ga.height / 2 : ga.x + ga.width / 2;
+        const bCenter = isLR ? gb.y + gb.height / 2 : gb.x + gb.width / 2;
+        const groupToShift = aCenter <= bCenter ? gb : ga;
+
+        if (isLR) groupToShift.y += shift;
+        else groupToShift.x += shift;
+
+        for (const node of nodes) {
+          if (node.groupId === groupToShift.id) {
+            if (isLR) node.y += shift;
+            else node.x += shift;
+          }
+        }
+      }
+    }
+    if (!anyOverlap) break;
+  }
+}
+
 // ============================================================
 // Layout engine
 // ============================================================
 
-export function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: string | null, collapsedNodes?: Set<string> | null): InfraLayoutResult {
+export function layoutInfra(computed: ComputedInfraModel, expandedNodeIds?: Set<string> | null, collapsedNodes?: Set<string> | null): InfraLayoutResult {
   if (computed.nodes.length === 0) {
     return { nodes: [], edges: [], groups: [], options: {}, width: 0, height: 0 };
   }
@@ -364,7 +443,7 @@ export function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: strin
   const heightMap = new Map<string, number>();
   for (const node of computed.nodes) {
     const isNodeCollapsed = collapsedNodes?.has(node.id) ?? false;
-    const expanded = !isNodeCollapsed && node.id === selectedNodeId;
+    const expanded = !isNodeCollapsed && (expandedNodeIds?.has(node.id) ?? false);
     const width = computeNodeWidth(node, expanded, computed.options);
     const height = isNodeCollapsed
       ? NODE_HEADER_HEIGHT + NODE_PAD_BOTTOM
@@ -437,6 +516,7 @@ export function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: strin
       queueMetrics: node.queueMetrics,
       properties: node.properties,
       tags: node.tags,
+      description: node.description,
       lineNumber: node.lineNumber,
     };
   });
@@ -454,6 +534,7 @@ export function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: strin
         label: edge.label,
         computedRps: edge.computedRps,
         split: edge.split,
+        fanout: edge.fanout,
         points: edgeData?.points ?? [],
         lineNumber: edge.lineNumber,
       });
@@ -465,6 +546,7 @@ export function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: strin
         label: edge.label,
         computedRps: edge.computedRps,
         split: edge.split,
+        fanout: edge.fanout,
         points: edgeData?.points ?? [],
         lineNumber: edge.lineNumber,
       });
@@ -509,6 +591,9 @@ export function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: strin
     };
   });
 
+  // Separate overlapping groups (post-layout pass)
+  separateGroups(layoutGroups, layoutNodes, isLR);
+
   // Compute total dimensions
   let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
   for (const node of layoutNodes) {

package/src/infra/parser.ts

@@ -23,13 +23,13 @@ import { INFRA_BEHAVIOR_KEYS, EDGE_ONLY_KEYS } from './types';
 // Regex patterns
 // ============================================================
 
-// Connection: -label-> Target  or  -> Target  (with optional | split: N%)
+// Connection: -label-> Target  or  -> Target  (with optional | split: N%  and optional x5 fanout)
 const CONNECTION_RE =
-  /^-(?:([^-].*?))?->\s+(.+?)(?:(?:\s*\|\s*|\s+)split\s*:?\s*(\d+)%)?\s*$/;
+  /^-(?:([^-].*?))?->\s+(.+?)(?:(?:\s*\|\s*|\s+)split\s*:?\s*(\d+)%)?\s*(?:x(\d+))?\s*$/;
 
 // Simple connection shorthand: -> Target (no label, no dash prefix needed for edge)
 const SIMPLE_CONNECTION_RE =
-  /^->\s+(.+?)(?:(?:\s*\|\s*|\s+)split\s*:?\s*(\d+)%)?\s*$/;
+  /^->\s+(.+?)(?:(?:\s*\|\s*|\s+)split\s*:?\s*(\d+)%)?\s*(?:x(\d+))?\s*$/;
 
 // Group declaration: [Group Name]
 const GROUP_RE = /^\[([^\]]+)\]$/;
@@ -41,7 +41,8 @@ const TAG_GROUP_RE = /^tag\s*:\s*(\w[\w\s]*?)(?:\s+alias\s+(\w+))?\s*$/;
 const TAG_VALUE_RE = /^(\w[\w\s]*?)(?:\(([^)]+)\))?(\s+default)?\s*$/;
 
 // Component line: ComponentName  or  ComponentName | t: Backend | env: Prod
-const COMPONENT_RE = /^([a-zA-Z_][\w]*)(.*)$/;
+// Allows hyphens in names (e.g. api-gateway, my-service-v2) — but not at the start.
+const COMPONENT_RE = /^([a-zA-Z_][\w-]*)(.*)$/;
 
 // Pipe metadata: | key: value  or  | k1: v1, k2: v2  (comma-separated)
 const PIPE_META_RE = /[|,]\s*(\w+)\s*:\s*([^|,]+)/g;
@@ -231,6 +232,24 @@ export function parseInfra(content: string): ParsedInfra {
         continue;
       }
 
+      // slo-availability: <percentage e.g. 99.9%>
+      if (/^slo-availability\s*:/i.test(trimmed)) {
+        result.options['slo-availability'] = trimmed.replace(/^slo-availability\s*:\s*/i, '').trim();
+        continue;
+      }
+
+      // slo-p90-latency-ms: <number>
+      if (/^slo-p90-latency-ms\s*:/i.test(trimmed)) {
+        result.options['slo-p90-latency-ms'] = trimmed.replace(/^slo-p90-latency-ms\s*:\s*/i, '').trim();
+        continue;
+      }
+
+      // slo-warning-margin: <percentage e.g. 5%>
+      if (/^slo-warning-margin\s*:/i.test(trimmed)) {
+        result.options['slo-warning-margin'] = trimmed.replace(/^slo-warning-margin\s*:\s*/i, '').trim();
+        continue;
+      }
+
       // scenario: Name
       if (/^scenario\s*:/i.test(trimmed)) {
         finishCurrentNode();
@@ -397,12 +416,19 @@ export function parseInfra(content: string): ParsedInfra {
       if (simpleConn) {
         const targetName = simpleConn[1].trim();
         const splitStr = simpleConn[2];
+        const fanoutStr = simpleConn[3];
         const split = splitStr ? parseFloat(splitStr) : null;
+        const fanoutRaw = fanoutStr ? parseInt(fanoutStr, 10) : null;
+        if (fanoutRaw !== null && fanoutRaw < 1) {
+          warn(lineNumber, `Fan-out multiplier must be at least 1 (got x${fanoutRaw}). Ignoring.`);
+        }
+        const fanout = fanoutRaw !== null && fanoutRaw >= 1 ? fanoutRaw : null;
         result.edges.push({
           sourceId: currentNode.id,
           targetId: nodeId(targetName),
           label: '',
           split,
+          fanout,
           lineNumber,
         });
         continue;
@@ -414,7 +440,13 @@ export function parseInfra(content: string): ParsedInfra {
         const label = connMatch[1]?.trim() || '';
         const targetName = connMatch[2].trim();
         const splitStr = connMatch[3];
+        const fanoutStr = connMatch[4];
         const split = splitStr ? parseFloat(splitStr) : null;
+        const fanoutRaw = fanoutStr ? parseInt(fanoutStr, 10) : null;
+        if (fanoutRaw !== null && fanoutRaw < 1) {
+          warn(lineNumber, `Fan-out multiplier must be at least 1 (got x${fanoutRaw}). Ignoring.`);
+        }
+        const fanout = fanoutRaw !== null && fanoutRaw >= 1 ? fanoutRaw : null;
 
         // Target might be a group ref like [API Pods]
         let targetId: string;
@@ -430,17 +462,28 @@ export function parseInfra(content: string): ParsedInfra {
           targetId,
           label,
           split,
+          fanout,
           lineNumber,
         });
         continue;
       }
 
+      // Empty description: (no value) — silently skip rather than emitting "Unexpected line"
+      if (/^description\s*:\s*$/i.test(trimmed)) continue;
+
       // Property: key: value
       const propMatch = trimmed.match(PROPERTY_RE);
       if (propMatch) {
         const key = propMatch[1].toLowerCase();
         const rawVal = propMatch[2].trim();
 
+        // description is display metadata, not a behavior key; silently ignored on edge nodes.
+        // Single-line only — no length enforcement, but keep it short for legibility.
+        if (key === 'description' && currentNode) {
+          if (!currentNode.isEdge) currentNode.description = rawVal;
+          continue;
+        }
+
         // Validate property key
         if (!INFRA_BEHAVIOR_KEYS.has(key) && !EDGE_ONLY_KEYS.has(key)) {
           const allKeys = [...INFRA_BEHAVIOR_KEYS, ...EDGE_ONLY_KEYS];