Files
MeshTerm/meshterm/services/records.py
T
Jean-Pierre MartineauandClaude Opus 4.8 f1385666a8 Records: score every walk into a trophy case, per discipline
A walk is any trace — it starts and ends at our node (a Trace path route
directly, a Trace target boomerang just the same) — so every walk home can
be measured and scored. services/records.py owns that scoring: measure a
walk once (distance, reach, node counts, weakest link, enclosed area) and
offer it to every one of six disciplines it places in — Longest distance,
Farthest node, Most nodes, No revisits, Weakest link, Biggest loop.
walk_from_trace turns a reply into its re-walkable spec, canonical route,
and stats in one call.

Records persist per (category, hash width) in the discovered_paths table
(schema v11) — the 64-byte path field makes each width its own game — kept
top-5 with spec-dedupe and worst-first pruning, stamped with the app
version. Disciplines carry plain descriptive names; their ids stay stable
database keys so stored records survive the naming.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-15 13:16:18 -04:00

338 lines
13 KiB
Python

"""Walk records: how a completed trace is measured and scored for the trophy case.
A *walk* is one trace whose route starts and ends at our node — we transmit the first
hop and the final hop's transmission lands back on us. Every trace is one:
* **Trace path** composes the whole circuit by hand and only has to end within our
earshot, so its route *is* the walk;
* **Trace target** walks the symmetric boomerang ``us → out… → target → out reversed…
→ us``, which starts and ends at us just the same.
So any successful trace can be scored, and the trophy case keeps the record-setters in
six disciplines — the longest distance, the farthest node, the most nodes (with and
without revisits), the weakest surviving link, and the widest enclosed loop. This module
is pure measurement: :func:`walk_from_trace` turns a reply into a spec, a canonical
route, and its :class:`WalkStats`; :func:`walk_scores` scores those stats against every
discipline at once (a walk found while tracing one thing still counts everywhere it
places). The UI owns the radio and the database; nothing here transmits or persists.
Records live per ``(category, width_bytes)`` because the per-hop hash width bounds both a
walk's maximum length (the transmitted path field is :data:`MAX_PATH_BYTES`) and its
collision odds — a 1-byte board and a 4-byte board are different games.
"""
from __future__ import annotations
import math
from dataclasses import dataclass
from typing import Callable, Optional, Sequence
from ..core.geo import haversine_km
from ..core.models import Hop, TraceResult
#: The transmitted path field is fixed at 64 bytes (see the contact-route parsing in
#: :mod:`~meshterm.core.connection`), so a walk may carry at most this many bytes of
#: hop hashes — the hard reason records are kept per hash width.
MAX_PATH_BYTES = 64
def max_hops(width_bytes: int) -> int:
"""The most hops a spec can carry at ``width_bytes`` per hop (64-byte field)."""
return MAX_PATH_BYTES // max(1, width_bytes)
# --------------------------------------------------------------------------- scoring
@dataclass(slots=True)
class WalkStats:
"""Everything a finished walk is scored and displayed by.
Attributes:
node_ids: Canonical ids of the walked hops, in walk order (us excluded; the
walk implicitly starts and ends at our node).
hop_count: Hops in the transmitted spec (= relay transmissions out there).
distinct_nodes: How many different nodes the walk visited.
repeats: Whether any node was visited more than once.
min_snr: The weakest per-hop reading of the walk (dB), when measured.
rtt_ms: The walk's round trip, when measured.
km_travelled: Great-circle km summed over the circuit us → hops… → us.
Segments touching an unpositioned node add 0, making this a lower bound.
km_complete: Whether every segment was positioned (``km_travelled`` exact).
far_km: The furthest hop's distance from us (km), when both ends are
positioned; ``None`` without our own or any hop's position.
area_km2: The unsigned area enclosed by the circuit's positioned points in
walk order (km², shoelace over a local plane). ``None`` below three
positioned points; self-crossing walks score their net algebraic area.
"""
node_ids: tuple[str, ...]
hop_count: int
distinct_nodes: int
repeats: bool
min_snr: Optional[float]
rtt_ms: Optional[float]
km_travelled: float
km_complete: bool
far_km: Optional[float]
area_km2: Optional[float]
def as_dict(self) -> dict:
"""The stats as a JSON-serializable dict (the ``stats_json`` column)."""
return {
"hop_count": self.hop_count,
"distinct_nodes": self.distinct_nodes,
"repeats": self.repeats,
"min_snr": self.min_snr,
"rtt_ms": self.rtt_ms,
"km_travelled": round(self.km_travelled, 3),
"km_complete": self.km_complete,
"far_km": round(self.far_km, 3) if self.far_km is not None else None,
"area_km2": round(self.area_km2, 3) if self.area_km2 is not None else None,
}
@dataclass(frozen=True, slots=True)
class Category:
"""One trophy-case discipline: what makes a walk a record.
Attributes:
id: Stable identifier (the database key — never renamed, unlike the title).
title: Display name, sentence case ("Most nodes").
icon: Single glyph for menu rows.
description: One-line description of the game being played, shown under the
section heading on the records screen (word-wrapped when it must).
unit: Short unit suffix for scores ("km", "nodes", "dB", "km²").
ascending: ``True`` when *lower* scores win (Weakest link hunts the weakest
link that still carried a walk home).
needs_positions: Whether scoring requires node positions, so the UI can say
why the category is starved rather than silently scoring nothing.
score: Maps a walk's stats to its score — ``None`` when the walk simply
can't compete in this category (no positions, a repeat in No revisits).
"""
id: str
title: str
icon: str
description: str
unit: str
score: Callable[[WalkStats], Optional[float]]
ascending: bool = False
needs_positions: bool = False
def format_score(self, value: float) -> str:
"""Render a score in the category's own unit (``12.4 km``, ``7 nodes``)."""
if self.unit == "nodes":
count = int(value)
return f"{count} node{'s' if count != 1 else ''}"
if self.unit == "dB":
return f"{value:+.1f} dB"
return f"{value:.1f} {self.unit}"
def _score_long_haul(stats: WalkStats) -> Optional[float]:
return stats.km_travelled if stats.km_travelled > 0 else None
def _score_far_point(stats: WalkStats) -> Optional[float]:
return stats.far_km
def _score_grand_tour(stats: WalkStats) -> Optional[float]:
return float(stats.distinct_nodes) if stats.distinct_nodes else None
def _score_clean_trail(stats: WalkStats) -> Optional[float]:
if stats.repeats or not stats.distinct_nodes:
return None
return float(stats.distinct_nodes)
def _score_thin_thread(stats: WalkStats) -> Optional[float]:
return stats.min_snr
def _score_big_loop(stats: WalkStats) -> Optional[float]:
if stats.area_km2 is None or stats.area_km2 <= 0:
return None
return stats.area_km2
#: The six disciplines. Ids are stable database keys and must never change; titles and
#: descriptions are display-only and kept plain and descriptive.
CATEGORIES: tuple[Category, ...] = (
Category(
id="long_haul", title="Longest distance", icon="🛣", unit="km",
description="travel the greatest distance and come home",
score=_score_long_haul, needs_positions=True,
),
Category(
id="far_point", title="Farthest node", icon="🎯", unit="km",
description="reach the node furthest from here",
score=_score_far_point, needs_positions=True,
),
Category(
id="grand_tour", title="Most nodes", icon="🧳", unit="nodes",
description="visit the most nodes, passing through some twice is fine",
score=_score_grand_tour,
),
Category(
id="clean_trail", title="No revisits", icon="👣", unit="nodes",
description="visit the most nodes without passing through any twice",
score=_score_clean_trail,
),
Category(
id="thin_thread", title="Weakest link", icon="🕸", unit="dB",
description="come home over the weakest link that still carries",
score=_score_thin_thread, ascending=True,
),
Category(
id="big_loop", title="Biggest loop", icon="🔆", unit="km²",
description="enclose the largest area inside the walk",
score=_score_big_loop, needs_positions=True,
),
)
CATEGORY_BY_ID: dict[str, Category] = {c.id: c for c in CATEGORIES}
def _local_xy(
origin: tuple[float, float], point: tuple[float, float]
) -> tuple[float, float]:
"""Project a lat/lon onto a local plane around ``origin``, in km.
An equirectangular approximation — exact enough for mesh-sized areas (a few tens
of km) and keeps the shoelace area in honest km².
"""
lat0, lon0 = origin
lat, lon = point
x = (lon - lon0) * 111.320 * math.cos(math.radians(lat0))
y = (lat - lat0) * 110.574
return x, y
def compute_walk_stats(
node_ids: Sequence[str],
hops: Sequence[Hop],
*,
rtt_ms: Optional[float],
positions: dict[str, tuple[float, float]],
self_pos: Optional[tuple[float, float]],
) -> WalkStats:
"""Measure one successful walk for every category at once.
Args:
node_ids: Canonical ids of the walked hops, in walk order (us excluded).
hops: The trace reply's per-hop readings (the final hash-less hop, our own
device, contributes its SNR like any other — it is the reading on the
homecoming link).
rtt_ms: The walk's measured round trip.
positions: Known node positions keyed by canonical id.
self_pos: Our own node's position, or ``None`` when the device shares none.
Returns:
The walk's :class:`WalkStats`.
"""
ids = tuple(node_ids)
snrs = [h.snr for h in hops if h.snr is not None]
# The walked circuit for geometry: us, every hop in order, us again.
points: list[Optional[tuple[float, float]]] = [self_pos]
points.extend(positions.get(node) for node in ids)
points.append(self_pos)
km = 0.0
complete = True
for a, b in zip(points, points[1:]):
if a is None or b is None:
complete = False
continue
km += haversine_km(a[0], a[1], b[0], b[1])
far: Optional[float] = None
if self_pos is not None:
dists = [
haversine_km(self_pos[0], self_pos[1], p[0], p[1])
for p in points[1:-1]
if p is not None
]
far = max(dists) if dists else None
area: Optional[float] = None
if self_pos is not None:
placed = [p for p in points[:-1] if p is not None] # circuit closes itself
if len(placed) >= 3:
xy = [_local_xy(self_pos, p) for p in placed]
twice = sum(
xy[i][0] * xy[(i + 1) % len(xy)][1] - xy[(i + 1) % len(xy)][0] * xy[i][1]
for i in range(len(xy))
)
area = abs(twice) / 2.0
return WalkStats(
node_ids=ids,
hop_count=len(ids),
distinct_nodes=len(set(ids)),
repeats=len(set(ids)) < len(ids),
min_snr=min(snrs) if snrs else None,
rtt_ms=rtt_ms,
km_travelled=km,
km_complete=complete,
far_km=far,
area_km2=area,
)
def walk_scores(stats: WalkStats) -> dict[str, float]:
"""Score a walk against every category (the every-board-at-once rule).
Returns:
``category id → score`` for each category the walk can compete in.
"""
out: dict[str, float] = {}
for category in CATEGORIES:
value = category.score(stats)
if value is not None:
out[category.id] = value
return out
def walk_from_trace(
result: TraceResult,
*,
canonical: Callable[[str], Optional[str]],
positions: dict[str, tuple[float, float]],
self_pos: Optional[tuple[float, float]],
) -> Optional[tuple[str, tuple[str, ...], WalkStats]]:
"""Derive the walk a successful trace just made: its spec, route, and stats.
Every trace is a walk (it starts and ends at us — see the module docstring), so a
successful reply is scoreable straight from its hops. The reply's addressed hops are
the relays it rode, in order, with a final hash-less hop that is our own device
coming home; the relays become both the re-walkable spec (their hashes, joined —
exactly what *Trace this path* forces to walk it again) and, canonicalized, the
route the geometry is measured over.
Args:
result: The trace reply to measure (must have succeeded).
canonical: Folds a hop hash to its canonical node id (the topology's resolver),
so positions line up and re-walks resolve; unknown hops keep their hash.
positions: Known node positions keyed by canonical id.
self_pos: Our own node's position, or ``None`` when the device shares none.
Returns:
``(spec, route, stats)`` — the comma-separated hex spec, the canonical route
aligned with it, and the walk's :class:`WalkStats` — or ``None`` when the trace
failed or carried no addressable relay to score.
"""
if not result.success:
return None
hashes = tuple(h.node.lower() for h in result.hops if h.node)
if not hashes:
return None
route = tuple(canonical(h) or h for h in hashes)
stats = compute_walk_stats(
route, result.hops, rtt_ms=result.round_trip_ms,
positions=positions, self_pos=self_pos,
)
return ",".join(hashes), route, stats