From 32734cc51a63d78907c694f42bf8e1c115caabdf Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 14 Jul 2026 03:11:28 -0400 Subject: [PATCH] Trace path: reverse a walk to measure it the other direction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Radio links rarely read the same both ways — a route that carries cleanly outbound can be marginal on the return — but Trace path only ever walked a route in the direction it was built. Add a Reverse path action that flips the walk's hop order (us → a → b → c becomes us → c → b → a), so one composed route can be measured in both directions. It lives only in path mode: a target-mode route is a symmetric boomerang, so reversing it changes nothing. Reverse sits in the build-path group beside Compose and adopts the flipped spec exactly like any other path change — the forward run's aggregates clear (they described the other direction) and Trace stays idle, so you flip, then trace; reverse again to go back. Both readings persist to history for side-by-side comparison. Disabled, with the same "compose a path first" note as Trace, until there's a multi-hop path to flip. Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 2 +- meshterm/ui/trace_screen.py | 68 +++++++++++++++++++++++++++++++------ tests/test_live_screens.py | 55 ++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fa63ca4..6be4c6f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,7 +95,7 @@ Relative ages: `format_ago` for prose ("now", "5m ago", "never" — never "now a 🔑 channel/credential key · 🔐 identity/auth secret · 🗑 clear/delete · ✎ compose/edit · ⚙ parameter · `#` count · ▶ run · ⚡ explore/probe · ★ best/winner · ⭐ watch · 📤 send now · 📨 courier/queue · 💬 chat · 🔔 notify · 🔕 mute (notifications off) · - 📱 QR · 🔗 link · ↻ re-read · ↕ reorder · + 📱 QR · 🔗 link · ↻ re-read · ↕ reorder · ⇄ reverse (flip a path's direction) · ⌨ command line · 🚪 quit. Packet-class icons (feed/viewer lane): 📢 advert · 📊 telemetry · 📦 packet · 💬 message · ✅ ack. diff --git a/meshterm/ui/trace_screen.py b/meshterm/ui/trace_screen.py index 5b937f9..bb3d71d 100644 --- a/meshterm/ui/trace_screen.py +++ b/meshterm/ui/trace_screen.py @@ -22,6 +22,13 @@ whatever you make it, and nothing transmits until you say so. An action list dri repeater you hold admin credentials for, the composer can also *fetch that repeater's neighbour table* over the mesh (login required; firmware ignores guests): second-vantage evidence, persisted and folded straight back into the suggestions. +* **Reverse path** (Trace path only — a target-mode route is a symmetric boomerang, + so flipping it changes nothing) reverses the walk's hop order: ``us → a → b → c`` + becomes ``us → c → b → a``. Radio links rarely read the same both ways, so this + measures the route you built in the opposite direction. It adopts the reversed spec + like any path change (the forward run's aggregates clear) and leaves Trace idle — + nothing auto-fires — so you flip, then trace; reverse again to go back. The stored + history keeps both directions. * **Explore paths** (Trace target only — candidates need a destination) explores scenarios: ranked candidate routes to the target straight from the topology evidence (the device's own learned route, the direct shot, and the strongest observed @@ -223,12 +230,13 @@ class TraceScreen(Screen): One screen serves both trace features; ``mode`` decides which. ``"target"`` traces a pinned destination over a symmetric (mirrored) route and offers *Explore paths*; ``"path"`` walks a hand-composed route with no target at all — no Explore (ranked - candidates need a destination), no device routing, and Trace stays inert until a - path exists to walk (composed here, or auto-resolved from the last stored walk). + candidates need a destination), no device routing, but a *Reverse path* that flips + the asymmetric walk end-for-end, and Trace stays inert until a path exists to walk + (composed here, or auto-resolved from the last stored walk). - Adopting a different path — composed, explored, or re-rendered at a new width — - restarts the measurement: the aggregates, per-hop medians, and trace log all - described the old route, so they clear as if the screen had just opened. + Adopting a different path — composed, explored, reversed, or re-rendered at a new + width — restarts the measurement: the aggregates, per-hop medians, and trace log + all described the old route, so they clear as if the screen had just opened. ↑/↓ move the cursor over the action rows and Enter commits the selected one — the cursor opens on Trace, so plain Enter still just traces. The results (per-hop @@ -332,9 +340,12 @@ class TraceScreen(Screen): self._spinner = Spinner() self._worker: Optional[asyncio.Task] = None self._flight: Optional[TracingDialog] = None - # The action rows, in display order. Explore needs a destination to rank - # candidates for, so path mode drops it; the cursor opens on Trace either way. - actions = ["compose"] + (["explore"] if mode == "target" else []) + # The action rows, in display order. The build-path group leads: Compose, + # then Explore (target mode) or Reverse (path mode). Explore needs a + # destination to rank candidates for, so path mode drops it; and only a path + # walk is asymmetric enough to flip end-for-end, so only it offers Reverse. + # The cursor opens on Trace either way. + actions = ["compose", "explore"] if mode == "target" else ["compose", "reverse"] actions += ["width", "samples", "trace", "back"] self._actions: tuple[str, ...] = tuple(actions) self._index = self._actions.index("trace") @@ -484,6 +495,8 @@ class TraceScreen(Screen): # (empty on first open) stored spec, so opening Compose always resumes # from the visible route. self._open_flow(self._compose_path, seed=self._effective_spec()[0]) + elif key == "reverse": + self._reverse_path() elif key == "explore" and self._explore is not None: self._open_flow(self._explore) elif key == "back": @@ -526,6 +539,35 @@ class TraceScreen(Screen): asyncio.ensure_future(run()) + def _reverse_path(self) -> None: + """Flip the walked path end-for-end and re-arm on the reversed direction. + + A path walk is the one asymmetric trace: ``us → a → b → c → us`` and + ``us → c → b → a → us`` cross the same links the opposite way, and radio + links rarely read the same in both — so reversing the hop order lets one + route be measured out and back. It adopts the reversed spec exactly like any + other path change: the aggregates and log described the forward run, so they + clear, and Trace stays idle until the user commits it (nothing auto-fires). + Reverse again to walk it the original way; the stored history keeps both + directions for side-by-side comparison. + + A no-op when there is nothing to flip: no path, or a single hop (its own + mirror), or already mid-trace/mid-dialog. + """ + if self._dialog_open or self._running: + return + spec, _ = self._effective_spec() + tokens = [h.strip() for h in spec.split(",") if h.strip()] + if len(tokens) < 2: + return + reversed_spec = ",".join(reversed(tokens)) + if reversed_spec == self._path_spec: + return + self._path_spec = reversed_spec + self._traces.clear() + self._status = "" + self._session.invalidate() + # --- rendering ----------------------------------------------------------------- def render_body(self, width: int) -> list[str]: @@ -556,9 +598,9 @@ class TraceScreen(Screen): self._cursor = len(lines) lines.append(render_to_ansi(text, width)) # Set the next group apart: after the build-path group (Explore in target - # mode; Compose itself in path mode, which has no Explore) and after the + # mode, Reverse in path mode — whichever closes it) and after the # trace-settings group. - if key in ("explore", "samples") or (key == "compose" and self._mode == "path"): + if key in ("explore", "reverse", "samples"): lines.append("") tail = self._tail_lines(stats, current, width) if tail: @@ -607,6 +649,12 @@ class TraceScreen(Screen): if key == "compose": text.append("✎ ", style="brand") text.append("Compose path") + elif key == "reverse": + text.append("⇄ ", style="accent") + if self._effective_spec()[0]: + text.append("Reverse path — trace it the other way") + else: + text.append("Reverse path — compose a path first", style="muted") elif key == "explore": text.append("⚡ ", style="warn") text.append("Explore paths") diff --git a/tests/test_live_screens.py b/tests/test_live_screens.py index 6016436..1e2501c 100644 --- a/tests/test_live_screens.py +++ b/tests/test_live_screens.py @@ -586,6 +586,61 @@ async def test_trace_screen_path_mode_arms_from_the_previous_walk() -> None: assert len(screen._traces) == 1 +def test_reverse_is_a_path_mode_only_action() -> None: + """A target route is a symmetric boomerang, so only path mode offers Reverse. + + In path mode the row sits in the build-path group, between Compose and the + trace-settings, so the whole "define the path" cluster reads together. + """ + target, _ = _trace_screen(mode="target") + assert "reverse" not in target._actions + assert "Reverse path" not in _plain(target.render_body(100)) + + walk, _ = _trace_screen(mode="path") + assert "reverse" in walk._actions + body = _plain(walk.render_body(100)) + assert body.index("Compose path") < body.index("Reverse path") < body.index("Path width") + + +async def test_reverse_flips_a_path_walk_and_restarts_the_run() -> None: + """Reverse flips the hop order and clears the forward run, like any path change.""" + screen, _ = _trace_screen(mode="path") + screen._path_spec = "3d,f2,27" + screen.start_trace() + await screen._worker + assert screen._traces # a forward reading stands + screen._index = screen._actions.index("reverse") + screen.handle("enter") + assert screen._path_spec == "27,f2,3d" # end-for-end + assert screen._traces == [] # the forward aggregates cleared + assert screen._total_traces == 1 # the session count survives the restart + assert "Us → 27 → f2 → 3d → Us" in screen._planned_route().plain + + +def test_reverse_adopts_and_flips_the_visible_auto_walk() -> None: + """With only the auto walk showing, Reverse pins its mirror as the path to walk.""" + screen, _ = _trace_screen( + mode="path", auto_spec=lambda: "3d,f2", auto_source="last walk" + ) + assert screen._path_spec == "" # nothing composed yet; the plan is auto + screen._index = screen._actions.index("reverse") + screen.handle("enter") + assert screen._path_spec == "f2,3d" # the shown auto walk, flipped and pinned + assert "Us → f2 → 3d → Us" in screen._planned_route().plain + + +def test_reverse_is_inert_without_a_reversible_path() -> None: + """No path (or a single hop, its own mirror) leaves nothing to flip.""" + screen, _ = _trace_screen(mode="path") # no spec, no auto walk + assert "Reverse path — compose a path first" in _plain(screen.render_body(100)) + screen._index = screen._actions.index("reverse") + screen.handle("enter") + assert screen._path_spec == "" + screen._path_spec = "3d" # a lone hop reverses to itself + screen.handle("enter") + assert screen._path_spec == "3d" + + async def test_adopting_a_new_path_restarts_the_measurement() -> None: """A different spec clears the aggregates and log, like a freshly opened screen.