Bump version to v0.18.0

Author: lance0

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] - 2026-02-13
+
+### Added
+- **ECMP classification**: Detects per-flow vs per-packet ECMP using primary concentration heuristics. Paths column now accurately reflects observed responder count for per-packet load balancing (#46)
+- **`E` indicator**: New ECMP indicator in main table replaces misleading `!` (route flap) when ECMP is the actual cause
+- **Effective flow capability**: Runtime detection of protocol flow support. `--flows > 1` with ICMP now warns and collapses to single-flow instead of silently doing nothing
+- **Receiver flow attribution hardening**: Out-of-range source ports (NAT/CGNAT) no longer force-attributed to flow 0. Unknown-flow responses only match pending probes when unambiguous
+- **Hop detail view**: Per-packet ECMP section shows responder count and path count; per-flow ECMP section unchanged
+- **Last RTT semantics documented**: `Last` column tracks primary responder's most recent RTT (code docs + KNOWN_ISSUES)
+- **Main table layout guard tests**: Header/cell/width count parity verified across Auto/Compact/Wide x single-flow/multi-flow
+- **IPv6 RAW payload fallback tests**: Echo Reply and Time Exceeded parsing tests for IPv6
+
+### Changed
+- **Flap detection suppressed during ECMP**: `!` indicator no longer fires when per-packet ECMP is detected at a hop
+- **Probe engines use per-session config**: Each target's engine sees the effective flow count, not the raw CLI value
+
 ## [0.17.0] - 2026-02-12
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "ttl"
-version = "0.17.0"
+version = "0.18.0"
 edition = "2024"
 rust-version = "1.88"
 description = "Modern traceroute/mtr-style TUI with hop stats and optional ASN/geo enrichment"

Cargo.toml

@@ -78,7 +78,7 @@ This document tracks known limitations and edge cases that are documented but no
 
 ### `--flows` Has No Effect with ICMP Protocol
 
-ICMP probes have no source/destination port to vary, so all probes are sent as flow 0 regardless of the `--flows` value. Multi-flow ECMP detection requires `--protocol udp` or `--protocol tcp`. A runtime warning will be added in a future release (#46).
+ICMP probes have no source/destination port to vary, so all probes are sent as flow 0 regardless of the `--flows` value. Multi-flow ECMP detection requires `--protocol udp` or `--protocol tcp`. ttl warns at runtime when `--flows > 1` resolves to effective ICMP probing.
 
 ### macOS Requires Root
 
@@ -104,7 +104,7 @@ Linux delivers ICMPv6 Echo Reply only to the socket that sent the request, not t
 
 ### Last RTT Not Persisted in JSON
 
-`last_rtt` is intentionally `#[serde(skip)]` — it represents the most recent probe response and is inherently a live-only metric. The `Last` column in TUI and `last_ms` in CSV will show "-"/empty for replayed sessions. All other RTT and jitter stats are persisted and display correctly.
+`last_rtt` is intentionally `#[serde(skip)]` — it represents a live-only sample. The `Last` column in TUI and `last_ms` in CSV are sourced from the current primary responder's `last_rtt`, and will show "-"/empty for replayed sessions. All other RTT and jitter stats are persisted and display correctly.
 
 ### TCP Bitrate Not Paced
 

KNOWN_ISSUES.md

@@ -35,6 +35,7 @@ See [Installation](#installation) below for setup instructions.
 - **Fast continuous path monitoring** with detailed hop statistics
 - **Multiple simultaneous targets** - trace to several destinations at once
 - **Paris/Dublin traceroute** - multi-flow probing for ECMP path enumeration
+- **ECMP classification** - distinguishes per-flow vs per-packet load balancing
 - **Path MTU discovery** - binary search for maximum unfragmented size
 - **NAT detection** - identify when NAT devices rewrite source ports
 - **Route flap detection** - alert on path changes indicating routing instability
@@ -215,7 +216,7 @@ Unstable BGP or failover issues cause intermittent problems that are hard to cat
 sudo ttl -i 0.5 production-server.com
 ```
 
-TTL tracks when the responding IP at a hop changes. The `!` indicator flags route flaps, and hop details show change history.
+TTL tracks when the responding IP at a hop changes. The `!` indicator flags route flaps, and hop details show change history. ECMP load balancing shows `E` instead, so you can distinguish real instability from expected multi-path behavior.
 
 ### Detect Transparent Proxies
 

README.md

@@ -5,7 +5,7 @@
 **mtr is the de facto standard** for interactive traceroute but hasn't seen major feature development in years. **trippy** (Rust) is the main modern alternative but focuses on a different feature set.
 
 **Key advantages ttl already has:**
-- ECMP path enumeration (Paris/Dublin traceroute with `--flows`)
+- ECMP path enumeration with per-flow/per-packet classification (`--flows`)
 - NAT detection (source port rewrite analysis)
 - ICMP rate limit detection (distinguish rate limiting from real loss)
 - Route flap and asymmetric routing detection
@@ -60,7 +60,7 @@
 - [x] Update notifications (checks GitHub releases, install-method-aware)
 - [x] FreeBSD support (experimental, raw sockets)
 
-## Completed (v0.15.x - v0.17.x)
+## Completed (v0.15.x - v0.18.x)
 
 - [x] Animated replay (`--replay file --animate`) with speed control
 - [x] Probe event recording for replay accuracy
@@ -72,6 +72,11 @@
 - [x] Last RTT column in main table (mtr parity — `Loss% Snt Last Avg Min Max StdDev`)
 - [x] JAvg and JMax columns in Wide display mode
 - [x] Wider ASN column for full AS name visibility
+- [x] ECMP classification: per-flow vs per-packet detection with primary_ratio heuristic (#46)
+- [x] Paths column reflects actual responder count for per-packet ECMP (#46)
+- [x] `E` indicator for ECMP detected vs `!` for route flap (#46)
+- [x] Effective flow capability: `--flows` + ICMP warns and collapses to single-flow (#46)
+- [x] Receiver flow attribution hardening: unknown flows only match when unambiguous (#46)
 
 ---
 
@@ -81,20 +86,20 @@
 
 **Why this matters:** Per-packet load balancing (common on Arista, Juniper, Cisco) is undercounted by the current flow-primary model. Users see 8 responders in the detail view but "Paths: 1" in the main table. Related: #46
 
-- [ ] Detect per-packet vs per-flow ECMP (primary_ratio heuristic per flow)
-- [ ] Paths column reflects actual responder count for per-packet ECMP
-- [ ] Separate indicators: `E` for ECMP detected vs `!` for route flap
-- [ ] Warn when `--flows > 1` with effective ICMP probing (`-p icmp`, or `-p auto` when auto-select resolves to ICMP)
-- [ ] Define `-p auto` warning semantics for multi-target/mixed-family runs (warn if any target resolves to effective ICMP, avoid duplicate spam)
-- [ ] Track effective flow capability at runtime (requested `--flows` vs effective protocol) and use it for flap detection + NAT/Paths column visibility
-- [ ] Add CLI/TUI hint that flow-based ECMP detection is meaningful with UDP/TCP probes
-- [ ] Keep Paths value + highlight + host indicator driven by one shared ECMP classification (avoid count/style drift)
-- [ ] Handle out-of-range returned src ports as unknown flow (not forced flow 0) to avoid false per-flow attribution behind NAT/CGNAT
-- [ ] Update indicator/UI budget for new `E` marker (host width autosize currently assumes `" !~^"`)
-- [ ] Update user-facing indicator docs/help (`E` vs `!`) in CLI help + docs pages
-- [ ] Add tests for per-packet ECMP classification, `-p auto` ICMP warning behavior, and out-of-range src-port flow attribution
-- [ ] #46 acceptance: per-packet ECMP no longer presents as misleading `Paths: 1` when many responders are observed
-- [ ] #46 acceptance: `E` (ECMP) and `!` (route flap) are no longer conflated in the same scenario
+- [x] Detect per-packet vs per-flow ECMP (primary_ratio heuristic per flow)
+- [x] Paths column reflects actual responder count for per-packet ECMP
+- [x] Separate indicators: `E` for ECMP detected vs `!` for route flap
+- [x] Warn when `--flows > 1` with effective ICMP probing (`-p icmp`, or `-p auto` when auto-select resolves to ICMP)
+- [x] Define `-p auto` warning semantics for multi-target/mixed-family runs (warn if any target resolves to effective ICMP, avoid duplicate spam)
+- [x] Track effective flow capability at runtime (requested `--flows` vs effective protocol) and use it for flap detection + NAT/Paths column visibility
+- [x] Add CLI/TUI hint that flow-based ECMP detection is meaningful with UDP/TCP probes
+- [x] Keep Paths value + highlight + host indicator driven by one shared ECMP classification (avoid count/style drift)
+- [x] Handle out-of-range returned src ports as unknown flow (not forced flow 0) to avoid false per-flow attribution behind NAT/CGNAT
+- [x] Update indicator/UI budget for new `E` marker (host width autosize currently assumes `" !~^"`)
+- [x] Update user-facing indicator docs/help (`E` vs `!`) in CLI help + docs pages
+- [x] Add tests for per-packet ECMP classification, `-p auto` ICMP warning behavior, and out-of-range src-port flow attribution
+- [x] #46 acceptance: per-packet ECMP no longer presents as misleading `Paths: 1` when many responders are observed
+- [x] #46 acceptance: `E` (ECMP) and `!` (route flap) are no longer conflated in the same scenario
 - [ ] Paris strategy for UDP (`--strategy paris` — fixed 5-tuple, checksum encodes sequence) *(follow-on after #46 core fix)*
 - [ ] Dublin strategy for UDP (`--strategy dublin` — IP ID field encodes sequence) *(follow-on after #46 core fix)*
 
@@ -137,9 +142,9 @@
 ### Quick Wins (low effort, high impact)
 - [ ] **Progress indicator in replay** — show position in timeline during animated replay
 - [ ] **Interactive replay** — step through events, jump to time
-- [ ] **Last metric semantics** — decide and document whether `Last` is hop-most-recent (any responder) or primary-responder-most-recent; align TUI/CSV behavior and labels
-- [ ] **IPv6 RAW payload fallback tests** — unit tests for IPv6 Echo Reply and Time Exceeded parsing
-- [ ] **Main table layout tests** — verify header/cell/width count parity across Auto/Compact/Wide × single-flow/multi-flow modes
+- [x] **Last metric semantics** — documented as primary-responder-most-recent; TUI/CSV aligned
+- [x] **IPv6 RAW payload fallback tests** — unit tests for IPv6 Echo Reply and Time Exceeded parsing
+- [x] **Main table layout tests** — verify header/cell/width count parity across Auto/Compact/Wide × single-flow/multi-flow modes
 
 ### Medium Effort (moderate effort, high impact)
 - [ ] **PCAP export** — write probe/response packets to .pcap for Wireshark analysis
@@ -210,7 +215,7 @@
 | trippy | Rust | Yes (UDP) | No | No | Yes | Active |
 | traceroute | C | No | Yes | No | No | Maintenance |
 | tracepath | C | No | Yes | No | No | Maintenance |
-| **ttl** | Rust | Yes | Yes | Yes | Yes | Active |
+| **ttl** | Rust | Yes (per-flow + per-packet) | Yes | Yes | Yes | Active |
 
 ---
 

ROADMAP.md

@@ -22,5 +22,5 @@ Only the latest release is supported with security updates.
 
 | Version | Supported |
 |---------|-----------|
-| 0.17.x  | Yes       |
-| < 0.17  | No        |
+| 0.18.x  | Yes       |
+| < 0.18  | No        |

SECURITY.md

@@ -23,6 +23,7 @@ How ttl compares to other traceroute and network diagnostic tools.
 | IX detection | :white_check_mark: | :x: | :x: | :x: | :x: |
 | **ECMP** ||||||
 | Multi-path detection | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
+| Per-flow/per-packet classification | :white_check_mark: | :x: | :x: | :x: | :x: |
 | Paris traceroute | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: |
 | **TUI** ||||||
 | Interactive | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: |

docs/COMPARISON.md

@@ -60,6 +60,17 @@ ECMP routers hash on the 5-tuple: (src_ip, dst_ip, src_port, dst_port, protocol)
 - The TUI shows a "Paths" column when `--flows > 1`
 - Paths are highlighted when multiple responders are detected
 
+### ECMP Classification
+
+ttl distinguishes two types of ECMP:
+
+- **Per-flow ECMP**: Each flow consistently maps to one next-hop. Different flows take different paths. The Paths column shows unique flow primaries.
+- **Per-packet ECMP**: Responses rotate between responders regardless of flow. The Paths column shows the actual number of observed responders.
+
+Classification uses a primary concentration heuristic: if no single responder dominates a flow's responses (below 70% threshold), it's per-packet. The `E` indicator appears in the main table when ECMP is detected at a hop.
+
+**Note:** `--flows` requires UDP or TCP probing (`-p udp` or `-p tcp`). ICMP probes have no port to vary, so flows are always 1 in ICMP mode. ttl warns at startup if `--flows > 1` resolves to effective ICMP probing.
+
 ### Paris vs Dublin
 
 - **Paris traceroute**: Varies source port to enumerate paths
@@ -113,9 +124,10 @@ Trace all IP addresses that a hostname resolves to. Useful for:
 
 ttl detects route instability when the primary responder IP changes at a hop:
 
-- Main table shows "!" indicator after hostname when route changes detected
+- Main table shows `!` indicator after hostname when route changes detected
+- `!` is suppressed when ECMP is detected at the hop (`E` shown instead) — per-packet load balancing is expected multi-path behavior, not instability
 - Hop detail view (Enter key) shows route change history with timestamps
-- Uses hysteresis (margin of 2 responses) to avoid false positives from per-packet load balancing
+- Uses hysteresis (margin of 2 responses) to avoid false positives
 - Requires 5+ responses before recording changes (avoids startup noise)
 - History capped at 50 changes per hop
 - Only active in single-flow mode (disabled when `--flows > 1` since ECMP expects path variation)

docs/FEATURES.md

@@ -32,7 +32,8 @@ DETECTION INDICATORS:
     [RL?]  - Router rate-limiting ICMP (loss may be artificial)
     [ASYM] - Asymmetric routing detected (return path differs)
     [TTL!] - TTL manipulation detected (middlebox modifying TTL)
-    !      - Route flap at this hop (path instability)
+    E      - ECMP detected at this hop (single-flow marker; see Paths in multi-flow)
+    !      - Route flap at this hop (path instability, when ECMP not indicated)
     ~      - Asymmetric routing suspected at this hop
     ^      - TTL manipulation suspected at this hop