Flow Analysis

Flow Analysis

Overview

flow_analysis measures dependency-flow shape across three layers:

• Structural flow from the import graph
• Logical flow from git co-change patterns
• Runtime flow from telemetry-mapped call edges

The metric emits keys under flow_analysis.* and uses a domain-based v2 schema (2.0.0).

Key Groups

Structural graph (flow_analysis.graph.*)

• flow_analysis.graph.node_count
• flow_analysis.graph.edge_count
• flow_analysis.graph.total_weight
• flow_analysis.graph.density
• flow_analysis.graph.avg_out_weight
• flow_analysis.graph.max_fan_in_weight
• flow_analysis.graph.max_fan_out_weight
• flow_analysis.graph.gini_fan_in
• flow_analysis.graph.gini_fan_out
• flow_analysis.graph.flow_hierarchy
• flow_analysis.graph.cycle_edge_ratio
• flow_analysis.graph.global_reaching_centrality

Bow-tie decomposition (flow_analysis.bow_tie.*)

• flow_analysis.bow_tie.gscc_ratio
• flow_analysis.bow_tie.in_ratio
• flow_analysis.bow_tie.out_ratio
• flow_analysis.bow_tie.tendril_ratio
• flow_analysis.bow_tie.disconnected_ratio

Bottlenecks (flow_analysis.bottleneck.*)

• flow_analysis.bottleneck.edge_betweenness_max
• flow_analysis.bottleneck.edge_betweenness_avg
• flow_analysis.bottleneck.high_edge_count
• flow_analysis.bottleneck.edge_betweenness_approx
• flow_analysis.bottleneck.edge_betweenness_skipped
• flow_analysis.bottleneck.top_edges
• flow_analysis.bottleneck.edges_table

Logical overlay (flow_analysis.logical.*)

• flow_analysis.logical.available
• flow_analysis.logical.edge_count
• flow_analysis.logical.total_weight
• flow_analysis.logical.density
• flow_analysis.logical.jaccard_with_static
• flow_analysis.logical.logical_only_ratio
• flow_analysis.logical.static_only_ratio
• flow_analysis.logical.mismatch_score
• flow_analysis.logical.top_hidden_edges
• flow_analysis.logical.edges_table

Runtime overlay (flow_analysis.runtime.*)

• flow_analysis.runtime.available
• flow_analysis.runtime.edge_count
• flow_analysis.runtime.total_traffic_weight
• flow_analysis.runtime.avg_edge_latency_ms
• flow_analysis.runtime.error_edge_ratio
• flow_analysis.runtime.jaccard_with_static
• flow_analysis.runtime.runtime_only_ratio
• flow_analysis.runtime.static_unobserved_ratio
• flow_analysis.runtime.traffic_top1_ratio
• flow_analysis.runtime.mismatch_score
• flow_analysis.runtime.top_hot_edges
• flow_analysis.runtime.edges_table

Shared tables and timings

• flow_analysis.module_table
• flow_analysis.phase.structural_ms
• flow_analysis.phase.bottleneck_ms
• flow_analysis.phase.logical_ms
• flow_analysis.phase.runtime_ms

Core Formulas

• flow_analysis.graph.density = edge_count / (node_count * (node_count - 1)) for directed graphs.
• flow_analysis.graph.flow_hierarchy = 1 - flow_analysis.graph.cycle_edge_ratio.
• flow_analysis.logical.mismatch_score = (logical_only_ratio + static_only_ratio + (1 - jaccard_with_static)) / 3.
• flow_analysis.runtime.mismatch_score = (runtime_only_ratio + static_unobserved_ratio + (1 - jaccard_with_static)) / 3.

Profiles and Availability

• profile: static
  • Logical and runtime overlays are disabled (flow_analysis.logical.available = 0, flow_analysis.runtime.available = 0).
• profile: balanced
  • Logical overlay is enabled.
  • Runtime overlay is enabled only when telemetry traces are present.
• profile: full
  • Runtime overlay is attempted every run.
  • If runtime prerequisites are missing, runtime keys still exist but flow_analysis.runtime.available = 0.

Notes:

• Logical overlay can be enabled but empty (for example, no usable co-change edges).
• Runtime overlay requires mapped runtime data; when mapping is unavailable, runtime values stay at defaults with available = 0.

Configuration Defaults

metrics:
  - id: flow_analysis
    enabled: true
    config:
      profile: balanced
      group_by_folder_depth: null
      cochange_threshold: 2
      edge_betweenness_max_sources: 256
      edge_betweenness_skip_above_nodes: 20000
      high_edge_betweenness_threshold: 0.15
      runtime_min_traffic_weight: 0.01
      density_threshold_small: 0.18
      density_threshold_medium: 0.10
      density_threshold_large: 0.04
      density_threshold_xlarge: 0.015
      emit_phase_timings: true

Findings

flow_analysis emits deterministic findings with these rule_id values:

• flow_analysis.high_density
• flow_analysis.low_hierarchy
• flow_analysis.edge_bottleneck
• flow_analysis.logical_hidden_coupling
• flow_analysis.runtime_hot_path
• flow_analysis.runtime_error_path

Policy Examples

policy:
  invariants:
    - metric: flow_analysis.graph.density
      op: "<="
      value: 0.20
    - metric: flow_analysis.graph.flow_hierarchy
      op: ">="
      value: 0.80
    - metric: flow_analysis.logical.mismatch_score
      op: "<="
      value: 0.35
    - metric: flow_analysis.runtime.traffic_top1_ratio
      op: "<="
      value: 0.35

Breaking Migration (v1 -> v2)

v1 key	v2 key
flow_analysis.nodes	flow_analysis.graph.node_count
flow_analysis.links	flow_analysis.graph.edge_count
flow_analysis.total_flow	flow_analysis.graph.total_weight
flow_analysis.avg_degree	flow_analysis.graph.avg_out_weight
flow_analysis.max_fan_in	flow_analysis.graph.max_fan_in_weight
flow_analysis.max_fan_out	flow_analysis.graph.max_fan_out_weight
flow_analysis.gini_fan_in	flow_analysis.graph.gini_fan_in
flow_analysis.gini_fan_out	flow_analysis.graph.gini_fan_out
flow_analysis.density	flow_analysis.graph.density
flow_analysis.top_fan_in	flow_analysis.module_table (fan-in columns)
flow_analysis.top_fan_out	flow_analysis.module_table (fan-out columns)
flow_analysis.nodes_table	flow_analysis.module_table