Node detail: draw routes inbound (node → us), keep only good ones

The route graph on the node page is built from observation data — every
route it knows was received, not sent — so it now reads left to right in
that inbound direction: the contact on the left, our star on the right.
Renames the section "Routes heard" and the caption "node → you, as heard",
dropping the "path to node" framing that over-claimed a direction observed
paths may not hold in reverse.

Only good alternatives are drawn now, not every chain ever heard: an
observed route earns a grey lane only when its evidence is fresh (its
stalest hop heard within ~4 evidence half-lives) and not a far-weaker
outlier (score within a quarter of the strongest observed). The
best-evidence route still rides white regardless, and a bare direct
neighbour keeps its zero-hop line.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-21 01:22:28 -04:00
1 parent 7b5b581b4b
commit 9cf5a9cc78
2 files changed
+231 -76

No files matched your search

+126 -65
View File
@@ -10,9 +10,11 @@ the node itself, in full:
* **where it is** — a small static basemap preview (see :class:`~meshterm.ui.minimap.MiniMap`)
centred on the node with the rest of the mesh around it, when the node has advertised a
location;
* **how we reach it** — the observed routes drawn on the shared route graph
(:mod:`~meshterm.ui.pathgraph`), the best-evidence one lit white over the alternatives, so
the path the trace would take reads at a glance;
* **how we hear it** — the routes we've actually heard it arrive over, drawn on the shared
route graph (:mod:`~meshterm.ui.pathgraph`) node→us (the inbound direction the packets
travelled, contact on the left, us on the right), the best-evidence one lit white over the
alternatives. Only *good* routes are drawn — stale evidence and far-weaker outliers are
dropped, so the graph shows the routes worth trusting rather than every chain ever heard;
* **the ways in** — an action list: *Trace target* (armed with the suggested best path, so
Enter walks straight to it), *Open full map*, and *Time machine* (only when the recorder
actually holds history for the node). ↑/↓ move the cursor, Enter commits, Esc backs to the
@@ -29,12 +31,13 @@ from __future__ import annotations
import asyncio
import math
from dataclasses import dataclass, field
from datetime import datetime
from typing import TYPE_CHECKING, Optional
from rich.text import Text
from ..core.geo import EARTH_RADIUS_KM, usable_fix
from ..core.models import NODE_TYPE_LABELS, Contact
from ..core.models import NODE_TYPE_LABELS, Contact, utcnow
from .minimap import MiniMap
from .pathgraph import (
DST_NODE,
@@ -68,17 +71,31 @@ _SELF_GLYPH = ("★", "#facc15")
#: How many character rows the inline location preview draws.
_MAP_ROWS = 7
#: Route-graph tuning for this page. It draws us on the left and the target on the right
#: (us → target, so the graph reads as "how we reach it", left to right). A well-connected
#: node offers several candidate paths at once, and cramming them into a short box overlaps
#: the lanes into an unreadable tangle — so this page gives the fan a generous lane step and
#: row budget, letting each path spread into its own clearly separated track. The height is
#: adaptive: it grows only with the number of distinct lanes, so a node with one or two
#: routes still draws compact while a busy one earns the room it needs. The page scrolls
#: (PgUp/PgDn), so a tall graph never crowds the action rows off-screen.
#: Route-graph tuning for this page. It draws the contact on the left and us on the right
#: (node → us, so the graph reads left to right as the inbound direction its packets
#: travelled to reach us). A well-connected node offers several candidate paths at once, and
#: cramming them into a short box overlaps the lanes into an unreadable tangle — so this page
#: gives the fan a generous lane step and row budget, letting each path spread into its own
#: clearly separated track. The height is adaptive: it grows only with the number of distinct
#: lanes, so a node with one or two routes still draws compact while a busy one earns the room
#: it needs. The page scrolls (PgUp/PgDn), so a tall graph never crowds the action rows off.
_PATH_LANE_STEP = 15
_PATH_MAX_ROWS = 22
#: A drawn route is dropped as *stale* when its freshest-limiting link — the stalest hop it
#: rides through — has not been heard in this many days. A route is only as current as its
#: weakest-heard link: if any hop along it has gone quiet, the whole chain may no longer
#: carry. Matches the spirit of the topology's one-week evidence half-life (four half-lives
#: leaves a link weighted ~1/16), the point past which a path is more memory than fact.
_PATH_STALE_DAYS = 28.0
#: A drawn alternative route is dropped as an *outlier* when its evidence score falls below
#: this fraction of the strongest observed alternative's. Keeps the graph to the handful of
#: routes actually worth trusting rather than every far-weaker chain the evidence can string
#: together. The best-evidence (white) route is always drawn regardless — it is the answer to
#: "how do we reach it", not one of the alternatives being weighed.
_PATH_OUTLIER_RATIO = 0.25
#: Cells the labelled info rows reserve for their label lane, so the value blocks line up
#: and a wrapped value hangs under itself rather than under the label (the app-wide
#: hanging-indent rule). Sized to the widest label the block uses ("packets").
@@ -159,7 +176,7 @@ class NodeDetailScreen(Screen):
minimap: The inline location preview, or ``None`` when the node has no location.
map_caption: A faint line under the preview (its centre/scale), when a map shows.
path: The route-graph view (layers + callbacks, or a muted note), or ``None`` to
omit the whole "Path to node" section (our own node has no route to itself).
omit the whole "Routes heard" section (we never overhear our own node).
"""
super().__init__()
self.title = title
@@ -236,7 +253,7 @@ class NodeDetailScreen(Screen):
lines.extend(render_lines(self._map_caption, width, no_wrap=True))
if self._path is not None:
lines.append("")
lines.extend(render_lines(Text("Path to node", style="accent"), width))
lines.extend(render_lines(Text("Routes heard", style="accent"), width))
lines.extend(self._path_lines(width))
lines.append("")
self._cursor = None
@@ -272,7 +289,7 @@ class NodeDetailScreen(Screen):
max_rows=_PATH_MAX_ROWS,
lane_step=_PATH_LANE_STEP,
)
caption = Text("you → node · white = suggested route", style="faint")
caption = Text("node → you, as heard · white = best route", style="faint")
lines.extend(render_lines(caption, width, no_wrap=True))
if path.legend:
lines.extend(render_lines(node_type_legend(), width, no_wrap=True))
@@ -522,7 +539,7 @@ async def open_node_detail(ctx: "AppContext", contact: Optional["Contact"]) -> N
)
map_caption = Text(f"{label} · centred here", style="faint")
# -- the "path to node" route graph (node → us), best-evidence path white.
# -- the "routes heard" route graph (node → us), best-evidence path white.
path: Optional[_PathView] = None
if not you:
path = _path_view(
@@ -666,18 +683,25 @@ def _path_view(
self_name,
node_label,
) -> _PathView:
"""Build the route-graph layers (us → node) and their draw callbacks, or a muted note.
"""Build the route-graph layers (node → us) and their draw callbacks, or a muted note.
The paths are drawn us-on-the-left to the target-on-the-right — the outbound direction
a trace walks, so the graph reads left to right as "how we reach it" and lines up with
the Path-to-node rows above. The shared :func:`~meshterm.ui.widgets.route_graph_style`
always pins us to the graph's right endpoint (it was built for the Message paths view,
where traffic arrives *at* us), so we hand it the target as its ``source`` and then swap
the two endpoint sentinels in its callbacks — putting the star on the left and the named
target on the right without disturbing the widget's other callers. The best-evidence
route (the observed suggestion, else the firmware's route) is lit white over the
alternatives' grey. With no route evidence at all — no learned route, no observed path,
not even a direct link — there is nothing honest to draw, so a muted note stands in.
The routes are drawn contact-on-the-left to us-on-the-right — the *inbound* direction the
packets travelled to reach us, since everything the graph knows was received, not sent.
That is exactly the orientation the shared :func:`~meshterm.ui.widgets.route_graph_style`
already draws (it was built for the Message paths view, where traffic arrives *at* us on
the right), so we hand it the target as its ``source`` — the left endpoint — and use its
callbacks as they come, only reversing each route's hop order so the drawn line runs from
the contact inward to us. The best-evidence route (the observed suggestion, else the
firmware's learned route) is lit white over the alternatives' grey.
Only *good* alternatives are drawn: an observed route is kept as grey when its evidence is
both **fresh** (its stalest hop heard within :data:`_PATH_STALE_DAYS`) and **not an
outlier** (its score within :data:`_PATH_OUTLIER_RATIO` of the strongest observed one) —
so the graph shows the routes worth trusting rather than every chain ever heard. The
best-evidence route is always drawn, stale or not: it is the page's answer to how we'd
reach the node, not one of the alternatives being weighed. With no route evidence at all —
no learned route, no observed path, not even a direct link — there is nothing honest to
draw, so a muted note stands in.
"""
if canonical_target is None:
return _PathView(note="no key to route to")
@@ -695,18 +719,25 @@ def _path_view(
else device_route if device_route is not None
else None
)
# A node we only ever hear directly (no relays, no learned route) still earns a line —
# the straight zero-hop shot — so the graph shows the direct link rather than a bare note.
if best_hops is None and topo.link(topo.self_id, canonical_target) is not None:
best_hops = ()
layers: list[PathLayer] = []
seen: set[tuple[str, ...]] = set()
def add(hops: tuple[str, ...], priority: int, color: tuple[int, int, int]) -> None:
if hops in seen: # draw us → target (the outbound order the trace walks)
# Reverse the outbound (us-outward) hop order into inbound (node→us) draw order, so
# the contact lands on the left endpoint and our star on the right.
drawn = tuple(reversed(hops))
if drawn in seen:
return
seen.add(hops)
layers.append(PathLayer(hops=hops, color=color, priority=priority))
seen.add(drawn)
layers.append(PathLayer(hops=drawn, color=color, priority=priority))
if best_hops is not None:
add(best_hops, 3, white)
for scenario in scenarios:
for scenario in _good_alternatives(topo, scenarios, canonical_target):
add(scenario.hops, 2, grey)
glyph_of, byte_label_of, label_rgb_of = style(
@@ -717,23 +748,17 @@ def _path_view(
# a relay with only its first hash byte, here each relay wears its resolved contact name
# (its colour is already the name's hue), so the whole route reads as places rather than
# hex; an unidentified relay keeps the byte, the honest most it can be called. The two
# endpoints keep route_graph_style's names.
# endpoints keep route_graph_style's names (target on the left, us on the right).
def label_of(node: str) -> Optional[str]:
if node in (SRC_NODE, DST_NODE):
return byte_label_of(node)
named = resolve(node)
return named if named and named != node else node[:2]
# route_graph_style pins us to DST (the right) and the target to SRC (the left); swap the
# two sentinels so the graph draws us on the left and the target on the right.
glyph_of = _flip_endpoints(glyph_of)
label_of = _flip_endpoints(label_of)
label_rgb_of = _flip_endpoints(label_rgb_of)
# The target wears its own map glyph (▲ repeater, ■ room, ◉ sensor) — the same mark the
# header and the map give it. route_graph_style draws the far endpoint as a plain dot,
# since on its home screen (Message paths) that end is an arbitrary message origin; here
# it is a known contact whose type we can show.
# header and the map give it. route_graph_style draws the far (left) endpoint as a plain
# dot, since on its home screen (Message paths) that end is an arbitrary message origin;
# here it is a known contact whose type we can show.
glyph_of = _with_target_glyph(
glyph_of, _NODE_GLYPHS.get(type_of(canonical_target), _DEFAULT_GLYPH)
)
@@ -747,34 +772,70 @@ def _path_view(
)
def _good_alternatives(topo, scenarios, target) -> list: # noqa: ANN001
"""The observed alternative routes worth drawing: fresh, evidence-backed, not outliers.
Trims the raw scenario list down to the alternatives the graph should show in grey:
* only the **observed** family (the device/direct scenarios are not routes the evidence
*observed* the node arrive over — the device route rides in white on its own when it is
the best, and a bare direct line the evidence never saw is not worth a lane);
* only ones with real evidence behind them (a positive score — an unobserved link scores
zero, see :meth:`~meshterm.services.topology.MeshTopology._score_route`);
* only **fresh** ones — every hop heard within :data:`_PATH_STALE_DAYS`, so a route whose
weakest link has gone quiet drops out rather than lingering as a line that may no longer
carry;
* only ones **not far weaker** than the best observed alternative (score within
:data:`_PATH_OUTLIER_RATIO` of the strongest), so one clearly-best route isn't buried
under a fan of marginal ones.
Returns the survivors in the order :meth:`~meshterm.services.topology.MeshTopology.scenarios`
ranked them (strongest first).
"""
observed = [s for s in scenarios if s.source == "observed" and s.hops and s.score > 0]
if not observed:
return []
best_score = max(s.score for s in observed)
now = utcnow()
return [
s
for s in observed
if s.score >= best_score * _PATH_OUTLIER_RATIO
and _route_is_fresh(topo, s.hops, target, now)
]
def _route_is_fresh(topo, hops: tuple[str, ...], target: str, now: datetime) -> bool:
"""Whether every link along ``us → hops… → target`` was heard within the stale horizon.
A route is only as current as its stalest hop: if any link on it has not been heard in
:data:`_PATH_STALE_DAYS`, the chain may no longer carry, so the whole route counts as
stale. A link with no timestamp (evidence that carries no ``when``, e.g. a firmware route)
is treated as fresh — we have no age to hold against it.
"""
chain = [topo.self_id, *hops, target]
for a, b in zip(chain, chain[1:]):
link = topo.link(a, b)
if link is None:
return False
last = link.last_seen
if last is None or getattr(last, "tzinfo", None) is None:
continue # undated evidence — no age to judge it stale by
if (now - last).total_seconds() > _PATH_STALE_DAYS * 86400.0:
return False
return True
def _with_target_glyph(glyph_of: GlyphOf, target_glyph: tuple[str, str]) -> GlyphOf:
"""Wrap the graph's glyph callback so the target endpoint draws its own node glyph.
The graph's right endpoint is the node this page is about, and here we know its type —
so it draws the map's own mark for that type (``▲`` repeater, ``■`` room, ``◉`` sensor,
``●`` plain), matching the identity header and the location preview, rather than
``route_graph_style``'s generic origin dot. Every other node passes through untouched.
The graph's left endpoint (``SRC_NODE``) is the node this page is about, and here we know
its type — so it draws the map's own mark for that type (``▲`` repeater, ``■`` room,
``◉`` sensor, ``●`` plain), matching the identity header and the location preview, rather
than ``route_graph_style``'s generic origin dot. Every other node passes through
untouched (our own star on the right endpoint keeps the style's ``you`` mark).
"""
def wrapped(node: str) -> tuple[str, str]:
return target_glyph if node == DST_NODE else glyph_of(node)
return wrapped
def _flip_endpoints(callback):
"""Wrap a pathgraph per-node callback so it swaps the two endpoint sentinels.
:func:`~meshterm.ui.widgets.route_graph_style` builds its glyph/label/colour callbacks
with us on the right (``DST_NODE``) and the far node on the left (``SRC_NODE``). Passing
each hop through here maps ``SRC_NODE`` to ``DST_NODE`` and back, so the drawn graph puts
us on the left and the target on the right — relay hops (anything else) pass through
untouched.
"""
def wrapped(node: str): # noqa: ANN202 - forwards whatever the callback returns
if node == SRC_NODE:
node = DST_NODE
elif node == DST_NODE:
node = SRC_NODE
return callback(node)
return target_glyph if node == SRC_NODE else glyph_of(node)
return wrapped
+105 -11
View File
@@ -156,7 +156,7 @@ def test_route_and_suggest_rows_speak_the_evidence() -> None:
def test_path_view_draws_evidence_and_notes_its_absence() -> None:
"""With route evidence the graph draws us→node; without any, a muted note stands in."""
"""With route evidence the graph draws node→us; without any, a muted note stands in."""
topo = _topo_with_route()
style_args = dict(
resolve=make_node_resolver([HUB, FAR]),
@@ -182,8 +182,8 @@ def test_path_view_draws_evidence_and_notes_its_absence() -> None:
assert not note.layers and "no route observed" in note.note
def test_path_view_puts_us_on_the_left_and_the_target_on_the_right() -> None:
"""The route graph reads us → target: our star on the left endpoint, the node on the right."""
def test_path_view_puts_the_contact_on_the_left_and_us_on_the_right() -> None:
"""The graph reads node → us (the inbound direction): the contact on the left, our star right."""
from meshterm.ui.pathgraph import DST_NODE, SRC_NODE
topo = _topo_with_route()
@@ -195,9 +195,9 @@ def test_path_view_puts_us_on_the_left_and_the_target_on_the_right() -> None:
key_of=make_name_key_resolver([HUB, FAR]),
style=route_graph_style, self_name="Us", node_label="Far",
)
assert view.glyph_of(SRC_NODE)[0] == "★" # the left endpoint is our own star
assert view.label_of(SRC_NODE) == "Us" # …labelled as us
assert view.label_of(DST_NODE) == "Far" # the right endpoint is the target
assert view.label_of(SRC_NODE) == "Far" # the left endpoint is the target contact
assert view.glyph_of(DST_NODE)[0] == "★" # the right endpoint is our own star
assert view.label_of(DST_NODE) == "Us" # …labelled as us
# This page names every node: a known relay reads by its contact name, not its hash byte.
assert view.label_of("3d63c6429436") == "Hub"
@@ -217,12 +217,12 @@ def test_path_view_relay_falls_back_to_the_hash_byte_when_unnamed() -> None:
def test_path_view_target_wears_its_node_type_glyph() -> None:
"""The right endpoint draws the target's own map mark (a repeater ▲), not a plain dot."""
"""The left endpoint draws the target's own map mark (a repeater ▲), not a plain dot."""
from meshterm.persistence.repository import TracedPath
from meshterm.ui.pathgraph import DST_NODE
from meshterm.ui.pathgraph import SRC_NODE
leaf = Contact(name="Leaf", public_key="27d4396a2967" + "0" * 52, key_prefix="27d4396a2967")
# Reach the Hub (a repeater) through the Leaf, so the Hub is the drawn right endpoint.
# Reach the Hub (a repeater) through the Leaf, so the Hub is the drawn left endpoint.
walks = [
TracedPath(when=utcnow(), hops=[("27d4", 8.0), ("3d", 6.0), ("27d4", 6.0), (None, 8.0)])
for _ in range(3)
@@ -237,7 +237,101 @@ def test_path_view_target_wears_its_node_type_glyph() -> None:
key_of=make_name_key_resolver([HUB, leaf]),
style=route_graph_style, self_name="Us", node_label="Hub",
)
assert view.glyph_of(DST_NODE)[0] == "▲" # the repeater target keeps its own glyph
assert view.glyph_of(SRC_NODE)[0] == "▲" # the repeater target keeps its own glyph
def test_path_view_draws_routes_inbound_reversing_the_hop_order() -> None:
"""A drawn route runs node → us: the outbound (us-outward) hops reverse into inbound order."""
r1 = Contact(name="R1", public_key="111111111111" + "0" * 52, key_prefix="111111111111")
r2 = Contact(name="R2", public_key="222222222222" + "0" * 52, key_prefix="222222222222")
topo = build_topology(self_id=US + "0" * 52, contacts=[r1, r2, FAR],
trace_paths=[], packet_paths=[], neighbour_links=[])
route = ("111111111111", "222222222222") # us → r1 → r2 → target, outward order
view = _path_view(
topo, topo.scenarios("f2c24f54551e", device_route=route), None, route, "f2c24f54551e",
resolve=make_node_resolver([r1, r2, FAR]),
type_of=make_node_type_resolver([r1, r2, FAR]),
key_of=make_name_key_resolver([r1, r2, FAR]),
style=route_graph_style, self_name="Us", node_label="Far",
)
# Drawn contact→us, so the relay nearest the target leads and the one nearest us trails.
assert view.layers[0].hops == ("222222222222", "111111111111")
def _topo_two_alternatives(): # noqa: ANN202
"""A graph reaching Far two ways: a strong route via Hub and a far weaker one via Alt."""
from meshterm.persistence.repository import TracedPath
alt = Contact(name="Alt", public_key="a1a1a1a1a1a1" + "0" * 52, key_prefix="a1a1a1a1a1a1")
now = utcnow()
strong = [
TracedPath(when=now, hops=[("3d", 12.0), ("f2", 10.0), ("3d", 10.0), (None, 12.0)])
for _ in range(8)
]
weak = [TracedPath(when=now, hops=[("a1", -14.0), ("f2", -14.0), ("a1", -14.0), (None, -14.0)])]
topo = build_topology(
self_id=US + "0" * 52, contacts=[HUB, alt, FAR],
trace_paths=strong + weak, packet_paths=[], neighbour_links=[],
)
return topo
def test_good_alternatives_keeps_observed_routes_and_drops_outliers() -> None:
"""The grey alternatives are the observed routes worth trusting — outliers and the bare
direct/device families don't earn a lane."""
from meshterm.ui.node_detail_screen import _good_alternatives
topo = _topo_two_alternatives()
scenarios = topo.scenarios("f2c24f54551e")
kept = {s.hops for s in _good_alternatives(topo, scenarios, "f2c24f54551e")}
assert ("3d63c6429436",) in kept # the strong observed route survives
assert ("a1a1a1a1a1a1",) not in kept # the far weaker one is trimmed as an outlier
assert () not in kept # the bare direct family is never a grey lane
def test_path_view_draws_a_direct_line_for_a_bare_neighbour() -> None:
"""A node only ever heard directly still draws its zero-hop line, not a muted note."""
from meshterm.persistence.repository import PacketPath
# A single overheard frame straight from Far to us — a direct link, no relays, no route.
topo = build_topology(
self_id=US + "0" * 52, contacts=[FAR],
trace_paths=[],
packet_paths=[PacketPath(when=utcnow(), origin="f2c24f54551e", hops=[], snr=6.0)],
neighbour_links=[],
)
view = _path_view(
topo, topo.scenarios("f2c24f54551e"), topo.suggested("f2c24f54551e"),
None, "f2c24f54551e",
resolve=make_node_resolver([FAR]),
type_of=make_node_type_resolver([FAR]),
key_of=make_name_key_resolver([FAR]),
style=route_graph_style, self_name="Us", node_label="Far",
)
assert view.layers and view.layers[0].hops == () # a straight endpoint-to-endpoint line
def test_route_freshness_drops_a_route_with_a_long_quiet_hop() -> None:
"""A route counts as stale — and is dropped — once its stalest hop goes quiet past the horizon."""
from datetime import timedelta
from meshterm.persistence.repository import TracedPath
from meshterm.ui.node_detail_screen import _route_is_fresh
now = utcnow()
hops = [("3d", 12.0), ("f2", -5.0), ("3d", -5.5), (None, 12.0)]
fresh = build_topology(
self_id=US + "0" * 52, contacts=[HUB, FAR],
trace_paths=[TracedPath(when=now, hops=hops)], packet_paths=[], neighbour_links=[],
)
assert _route_is_fresh(fresh, ("3d63c6429436",), "f2c24f54551e", now) is True
stale = build_topology(
self_id=US + "0" * 52, contacts=[HUB, FAR],
trace_paths=[TracedPath(when=now - timedelta(days=60), hops=hops)],
packet_paths=[], neighbour_links=[],
)
assert _route_is_fresh(stale, ("3d63c6429436",), "f2c24f54551e", now) is False
def test_located_accepts_real_fixes_and_rejects_junk() -> None:
@@ -285,7 +379,7 @@ def test_node_detail_screen_renders_its_sections() -> None:
body = _plain(screen.render_body(72))
assert "Hub" in body and "repeater" in body # identity
assert "42" in body # a packet tally from the info block
assert "Path to node" in body and "no route observed yet" in body
assert "Routes heard" in body and "no route observed yet" in body
assert "Trace target" in body and "Time machine" in body and "Back" in body
# Every rendered line fits the 72-column standard.
for line in screen.render_body(72):