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>
This commit is contained in:
1 parent
7ac50ade53
commit
f1385666a8
4 files changed
+776
-3
No files matched your search
@@ -10,7 +10,7 @@ from __future__ import annotations
|
||||
import sqlite3
|
||||
from pathlib import Path
|
||||
|
||||
SCHEMA_VERSION = 10
|
||||
SCHEMA_VERSION = 11
|
||||
|
||||
_SCHEMA = """
|
||||
CREATE TABLE IF NOT EXISTS schema_meta (
|
||||
@@ -96,6 +96,25 @@ CREATE TABLE IF NOT EXISTS neighbour_reports (
|
||||
fetched_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- One record-holding walk in the trophy case (v11), scored from a trace that came
|
||||
-- home (see services/records). Records live per
|
||||
-- (category, width_bytes) because the per-hop hash width bounds both the walk's maximum
|
||||
-- length (the path field is 64 bytes) and its collision odds — a 1-byte record is not
|
||||
-- comparable to a 4-byte one. Standalone rows (no run_id): the walks' traces are already
|
||||
-- persisted under their own runs, and a record must outlive history pruning. app_version
|
||||
-- stamps the discoverer so future schema/scoring migrations can tell eras apart.
|
||||
CREATE TABLE IF NOT EXISTS discovered_paths (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
category TEXT NOT NULL,
|
||||
width_bytes INTEGER NOT NULL,
|
||||
spec TEXT NOT NULL, -- the transmitted hex spec, comma-separated
|
||||
route_json TEXT NOT NULL, -- canonical walked node ids, aligned with spec
|
||||
score REAL NOT NULL,
|
||||
stats_json TEXT NOT NULL,
|
||||
app_version TEXT NOT NULL,
|
||||
discovered_at TEXT NOT NULL
|
||||
);
|
||||
|
||||
-- One packet overheard while passively monitoring the mesh (advert/telemetry/...).
|
||||
CREATE TABLE IF NOT EXISTS observations (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
@@ -138,6 +157,7 @@ CREATE INDEX IF NOT EXISTS idx_traces_run ON traces(run_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_trace_hops_trace ON trace_hops(trace_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_tx_samples_run ON tx_samples(run_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_neighbour_reports_pair ON neighbour_reports(repeater, neighbour);
|
||||
CREATE INDEX IF NOT EXISTS idx_discovered_paths_cat ON discovered_paths(category, width_bytes);
|
||||
CREATE INDEX IF NOT EXISTS idx_observations_run ON observations(run_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_observations_node ON observations(node);
|
||||
CREATE INDEX IF NOT EXISTS idx_messages_peer ON messages(peer);
|
||||
|
||||
@@ -174,6 +174,38 @@ class NeighbourLink:
|
||||
snr: Optional[float]
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class DiscoveredPath:
|
||||
"""One record-holding walk in the trophy case (a discipline's leaderboard).
|
||||
|
||||
Records are kept per ``(category, width_bytes)`` — the per-hop hash width bounds
|
||||
both a walk's maximum length (the transmitted path field is 64 bytes) and its
|
||||
collision odds, so boards at different widths measure different games.
|
||||
|
||||
Attributes:
|
||||
id: Primary key (the handle deletion takes).
|
||||
category: The category id the record was set in (``grand_tour``, …).
|
||||
width_bytes: The per-hop path-hash width the walk was transmitted at.
|
||||
spec: The transmitted spec — comma-separated hex hashes, in walk order.
|
||||
route: Canonical node ids aligned with the spec's hops, for stable display
|
||||
resolution (a 1-byte spec hop is too ambiguous to re-resolve later).
|
||||
score: The category score (its unit is the category's: km, nodes, dB, km²).
|
||||
stats: The walk's measured statistics (hop count, distinct nodes, km, …).
|
||||
app_version: The MeshTerm version that discovered it, for future migrations.
|
||||
discovered_at: When the record-setting walk came home (UTC).
|
||||
"""
|
||||
|
||||
id: int
|
||||
category: str
|
||||
width_bytes: int
|
||||
spec: str
|
||||
route: tuple[str, ...]
|
||||
score: float
|
||||
stats: dict
|
||||
app_version: str
|
||||
discovered_at: datetime
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RunRecord:
|
||||
"""A summary row from the ``runs`` table.
|
||||
@@ -413,8 +445,9 @@ class Repository:
|
||||
This feeds the target picker's *Recently traced* section, so the list is
|
||||
deliberately short and recency-ordered: an all-time tally only ever grows,
|
||||
burying current work under stale names (``--mock`` targets included).
|
||||
Target-less path walks (recorded under :data:`~meshterm.core.models.
|
||||
PATH_TRACE_TARGET`) are excluded — they aren't destinations one can pick.
|
||||
Target-less walks — the hand-composed ones recorded under
|
||||
:data:`~meshterm.core.models.PATH_TRACE_TARGET` — are excluded: they aren't
|
||||
destinations one can pick.
|
||||
|
||||
Args:
|
||||
limit: Maximum number of distinct targets to return.
|
||||
@@ -637,6 +670,192 @@ class Repository:
|
||||
)
|
||||
self._conn.commit()
|
||||
|
||||
# -- discovered paths (trophy-case records) ----------------------------------
|
||||
|
||||
def record_discovery(
|
||||
self,
|
||||
category: str,
|
||||
width_bytes: int,
|
||||
spec: str,
|
||||
route: tuple[str, ...] | list[str],
|
||||
*,
|
||||
score: float,
|
||||
stats: dict,
|
||||
app_version: str,
|
||||
keep: int = 5,
|
||||
ascending: bool = False,
|
||||
) -> Optional[int]:
|
||||
"""Offer one walk to a category leaderboard; store it only if it places.
|
||||
|
||||
The leaderboard invariant lives here so every caller shares it: a walk enters
|
||||
the ``(category, width_bytes)`` board when it beats the standing entries (or
|
||||
the board isn't full), an identical spec only ever keeps its *best* score
|
||||
(re-walking a known route never duplicates a row), and the board is pruned
|
||||
back to ``keep`` rows on the way out.
|
||||
|
||||
Args:
|
||||
category: The category id the walk is offered to.
|
||||
width_bytes: The per-hop hash width the walk was transmitted at.
|
||||
spec: The transmitted spec (comma-separated hex hashes).
|
||||
route: Canonical node ids aligned with the spec's hops.
|
||||
score: The category score of this walk.
|
||||
stats: JSON-serializable walk statistics.
|
||||
app_version: The running MeshTerm version, stamped on the row.
|
||||
keep: Board size (rows kept per category and width).
|
||||
ascending: ``True`` for categories where *lower* scores win
|
||||
(Thin thread hunts the weakest surviving link).
|
||||
|
||||
Returns:
|
||||
The stored row's id when the walk placed (a fresh row or an improved
|
||||
re-walk), or ``None`` when it didn't make the board.
|
||||
"""
|
||||
def beats(challenger: float, standing: float) -> bool:
|
||||
return challenger < standing if ascending else challenger > standing
|
||||
|
||||
existing = self._conn.execute(
|
||||
"SELECT id, score FROM discovered_paths "
|
||||
"WHERE category = ? AND width_bytes = ? AND spec = ?",
|
||||
(category, width_bytes, spec),
|
||||
).fetchone()
|
||||
if existing is not None:
|
||||
# A known route: keep the row (and its discovery date) unless this walk
|
||||
# genuinely bettered its own record.
|
||||
if not beats(score, float(existing["score"])):
|
||||
return None
|
||||
self._conn.execute(
|
||||
"UPDATE discovered_paths SET score = ?, stats_json = ?, "
|
||||
"app_version = ?, discovered_at = ? WHERE id = ?",
|
||||
(
|
||||
score,
|
||||
json.dumps(stats),
|
||||
app_version,
|
||||
utcnow().isoformat(),
|
||||
existing["id"],
|
||||
),
|
||||
)
|
||||
self._conn.commit()
|
||||
return int(existing["id"])
|
||||
cursor = self._conn.execute(
|
||||
"INSERT INTO discovered_paths "
|
||||
"(category, width_bytes, spec, route_json, score, stats_json, "
|
||||
"app_version, discovered_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
|
||||
(
|
||||
category,
|
||||
width_bytes,
|
||||
spec,
|
||||
json.dumps(list(route)),
|
||||
score,
|
||||
json.dumps(stats),
|
||||
app_version,
|
||||
utcnow().isoformat(),
|
||||
),
|
||||
)
|
||||
new_id = int(cursor.lastrowid)
|
||||
# Prune the board back to ``keep``: worst scores go, oldest first among ties,
|
||||
# so the walk that set a mark holds it against an equal latecomer.
|
||||
order = "ASC" if not ascending else "DESC" # worst-first for deletion
|
||||
overflow = self._conn.execute(
|
||||
"SELECT id FROM discovered_paths WHERE category = ? AND width_bytes = ? "
|
||||
f"ORDER BY score {order}, id DESC",
|
||||
(category, width_bytes),
|
||||
).fetchall()
|
||||
doomed = [row["id"] for row in overflow[: max(0, len(overflow) - keep)]]
|
||||
if doomed:
|
||||
self._conn.executemany(
|
||||
"DELETE FROM discovered_paths WHERE id = ?", [(i,) for i in doomed]
|
||||
)
|
||||
self._conn.commit()
|
||||
return None if new_id in doomed else new_id
|
||||
|
||||
def discoveries(
|
||||
self, category: Optional[str] = None, *, width_bytes: Optional[int] = None
|
||||
) -> list[DiscoveredPath]:
|
||||
"""Return stored trophy-case records, optionally narrowed.
|
||||
|
||||
Rows come back unranked (grouped by category, newest first within one) — the
|
||||
service layer owns each category's score direction and sorts for display.
|
||||
|
||||
Args:
|
||||
category: Only this category's records, or ``None`` for all.
|
||||
width_bytes: Only records at this hash width, or ``None`` for all.
|
||||
|
||||
Returns:
|
||||
The matching :class:`DiscoveredPath` rows.
|
||||
"""
|
||||
clauses, params = ["1=1"], []
|
||||
if category is not None:
|
||||
clauses.append("category = ?")
|
||||
params.append(category)
|
||||
if width_bytes is not None:
|
||||
clauses.append("width_bytes = ?")
|
||||
params.append(width_bytes)
|
||||
rows = self._conn.execute(
|
||||
"SELECT * FROM discovered_paths WHERE " + " AND ".join(clauses) +
|
||||
" ORDER BY category, id DESC",
|
||||
params,
|
||||
).fetchall()
|
||||
out: list[DiscoveredPath] = []
|
||||
for row in rows:
|
||||
try:
|
||||
when = datetime.fromisoformat(row["discovered_at"])
|
||||
except (TypeError, ValueError):
|
||||
when = utcnow()
|
||||
try:
|
||||
route = tuple(json.loads(row["route_json"]))
|
||||
except (TypeError, ValueError):
|
||||
route = ()
|
||||
try:
|
||||
stats = json.loads(row["stats_json"]) or {}
|
||||
except (TypeError, ValueError):
|
||||
stats = {}
|
||||
out.append(
|
||||
DiscoveredPath(
|
||||
id=int(row["id"]),
|
||||
category=row["category"],
|
||||
width_bytes=int(row["width_bytes"]),
|
||||
spec=row["spec"],
|
||||
route=route,
|
||||
score=float(row["score"]),
|
||||
stats=stats,
|
||||
app_version=row["app_version"],
|
||||
discovered_at=when,
|
||||
)
|
||||
)
|
||||
return out
|
||||
|
||||
def delete_discovery(self, discovery_id: int) -> bool:
|
||||
"""Delete one trophy-case record by id; ``True`` when a row actually went."""
|
||||
cursor = self._conn.execute(
|
||||
"DELETE FROM discovered_paths WHERE id = ?", (discovery_id,)
|
||||
)
|
||||
self._conn.commit()
|
||||
return cursor.rowcount > 0
|
||||
|
||||
def delete_discoveries(
|
||||
self, category: Optional[str] = None, *, width_bytes: Optional[int] = None
|
||||
) -> int:
|
||||
"""Delete trophy-case records wholesale, optionally narrowed; returns the count.
|
||||
|
||||
Args:
|
||||
category: Only this category's records, or ``None`` for every category.
|
||||
width_bytes: Only records at this hash width, or ``None`` for all widths.
|
||||
|
||||
Returns:
|
||||
How many records were deleted.
|
||||
"""
|
||||
clauses, params = ["1=1"], []
|
||||
if category is not None:
|
||||
clauses.append("category = ?")
|
||||
params.append(category)
|
||||
if width_bytes is not None:
|
||||
clauses.append("width_bytes = ?")
|
||||
params.append(width_bytes)
|
||||
cursor = self._conn.execute(
|
||||
"DELETE FROM discovered_paths WHERE " + " AND ".join(clauses), params
|
||||
)
|
||||
self._conn.commit()
|
||||
return cursor.rowcount
|
||||
|
||||
# -- observations (passive monitoring) --------------------------------------
|
||||
|
||||
def record_observation(self, run_id: int, obs: Observation) -> None:
|
||||
|
||||
@@ -0,0 +1,337 @@
|
||||
"""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
|
||||
@@ -0,0 +1,197 @@
|
||||
"""Unit tests for the trophy-case records: walk scoring, derivation, and persistence.
|
||||
|
||||
The scoring layer is pure measurement (the UI owns the radio), so everything here runs
|
||||
headless: hand-built trace results, synthetic positions, and a temp repository for the
|
||||
leaderboard invariants.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from meshterm.core.models import Hop, TraceResult
|
||||
from meshterm.persistence.repository import Repository
|
||||
from meshterm.services.records import (
|
||||
CATEGORY_BY_ID,
|
||||
compute_walk_stats,
|
||||
max_hops,
|
||||
walk_from_trace,
|
||||
walk_scores,
|
||||
)
|
||||
|
||||
#: Montréal-ish positions ~1.1 km apart, so distance scores are easy to sanity-check.
|
||||
SELF_POS = (45.500, -73.600)
|
||||
HUB_ID, FAR_ID, LEAF_ID = "3d63c6429436", "f2c24f54551e", "27d4396a2967"
|
||||
POSITIONS = {
|
||||
HUB_ID: (45.510, -73.600), # ~1.11 km north of us
|
||||
FAR_ID: (45.510, -73.585), # north-east of us
|
||||
LEAF_ID: (45.490, -73.600), # ~1.11 km south of us
|
||||
}
|
||||
|
||||
|
||||
def _result(*snrs: float, rtt: float = 250.0, nodes=None) -> TraceResult: # noqa: ANN001
|
||||
"""A successful walk reply: one hop per SNR, the last one hash-less (us)."""
|
||||
hops = []
|
||||
for i, snr in enumerate(snrs):
|
||||
node = None if i == len(snrs) - 1 else (nodes[i] if nodes else f"{i:02x}")
|
||||
hops.append(Hop(index=i, node=node, snr=snr))
|
||||
return TraceResult(target="walk", success=True, hops=hops, round_trip_ms=rtt)
|
||||
|
||||
|
||||
# --- scoring ---------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_walk_stats_measure_distance_reach_and_area() -> None:
|
||||
"""The circuit us→Hub→Far→us is positioned end to end: exact km, far, and area."""
|
||||
stats = compute_walk_stats(
|
||||
(HUB_ID, FAR_ID), _result(8.0, 6.0, 7.0).hops, rtt_ms=250.0,
|
||||
positions=POSITIONS, self_pos=SELF_POS,
|
||||
)
|
||||
assert stats.km_complete
|
||||
assert stats.km_travelled > 2.0 # up ~1.1 km, across, and back home
|
||||
assert stats.far_km is not None and 1.0 < stats.far_km < 2.5
|
||||
assert stats.area_km2 is not None and stats.area_km2 > 0.3
|
||||
assert stats.distinct_nodes == 2 and not stats.repeats
|
||||
assert stats.min_snr == 6.0
|
||||
|
||||
|
||||
def test_walk_stats_unpositioned_segments_score_a_lower_bound() -> None:
|
||||
"""A hop with no position contributes 0 km and clears the complete flag."""
|
||||
positions = {HUB_ID: POSITIONS[HUB_ID]} # Far is off the map
|
||||
stats = compute_walk_stats(
|
||||
(HUB_ID, FAR_ID), _result(8.0, 6.0, 7.0).hops, rtt_ms=None,
|
||||
positions=positions, self_pos=SELF_POS,
|
||||
)
|
||||
assert not stats.km_complete
|
||||
assert 1.0 < stats.km_travelled < 1.3 # only the positioned us→Hub leg counts
|
||||
|
||||
|
||||
def test_cross_category_scores_score_every_game_at_once() -> None:
|
||||
"""One walk competes everywhere it can — the every-board-at-once rule."""
|
||||
stats = compute_walk_stats(
|
||||
(HUB_ID, FAR_ID, HUB_ID), _result(8.0, -11.0, 7.0, 9.0).hops, rtt_ms=100.0,
|
||||
positions=POSITIONS, self_pos=SELF_POS,
|
||||
)
|
||||
scores = walk_scores(stats)
|
||||
assert scores["grand_tour"] == 2.0 # two distinct nodes, revisit allowed
|
||||
assert "clean_trail" not in scores # Hub repeats: disqualified, not zeroed
|
||||
assert scores["thin_thread"] == -11.0 # the weakest surviving link
|
||||
assert scores["long_haul"] > 3.0
|
||||
assert scores["far_point"] > 1.0
|
||||
|
||||
|
||||
def test_category_titles_are_plain_and_ids_are_stable() -> None:
|
||||
"""Ids are database keys (unchanged); titles read plainly for the trophy case."""
|
||||
assert CATEGORY_BY_ID["grand_tour"].title == "Most nodes"
|
||||
assert CATEGORY_BY_ID["thin_thread"].title == "Weakest link"
|
||||
assert CATEGORY_BY_ID["long_haul"].title == "Longest distance"
|
||||
# Every id still resolves — the persisted keys never changed under the rename.
|
||||
assert set(CATEGORY_BY_ID) == {
|
||||
"long_haul", "far_point", "grand_tour", "clean_trail", "thin_thread", "big_loop"
|
||||
}
|
||||
|
||||
|
||||
def test_max_hops_follows_the_64_byte_path_field() -> None:
|
||||
"""The width bounds the walk: 64 hops at 1 byte, 16 at 4."""
|
||||
assert max_hops(1) == 64
|
||||
assert max_hops(2) == 32
|
||||
assert max_hops(4) == 16
|
||||
|
||||
|
||||
# --- deriving a walk from a trace ---------------------------------------------------
|
||||
|
||||
|
||||
def test_walk_from_trace_derives_spec_route_and_stats() -> None:
|
||||
"""A successful reply yields its re-walkable spec, canonical route, and stats."""
|
||||
result = _result(8.0, 6.0, 7.0, nodes=["3d", "f2"]) # two relays, then us
|
||||
canon = {"3d": HUB_ID, "f2": FAR_ID}
|
||||
derived = walk_from_trace(
|
||||
result, canonical=lambda h: canon.get(h),
|
||||
positions=POSITIONS, self_pos=SELF_POS,
|
||||
)
|
||||
assert derived is not None
|
||||
spec, route, stats = derived
|
||||
assert spec == "3d,f2" # the reply hops, joined — re-walkable verbatim
|
||||
assert route == (HUB_ID, FAR_ID) # canonicalized for stable display + geometry
|
||||
assert stats.km_complete and stats.far_km is not None
|
||||
|
||||
|
||||
def test_walk_from_trace_ignores_a_failure_or_a_reply_with_no_relays() -> None:
|
||||
"""A failed trace, or one that only came back off us, scores nothing."""
|
||||
failed = TraceResult(target="walk", success=False, hops=[])
|
||||
assert walk_from_trace(failed, canonical=lambda h: h, positions={}, self_pos=None) is None
|
||||
# A direct-to-us reply carries only the hash-less homecoming hop: no relay to score.
|
||||
direct = TraceResult(target="walk", success=True, hops=[Hop(index=0, node=None, snr=9.0)])
|
||||
assert walk_from_trace(direct, canonical=lambda h: h, positions={}, self_pos=None) is None
|
||||
|
||||
|
||||
# --- the leaderboards ----------------------------------------------------------------
|
||||
|
||||
|
||||
def test_leaderboard_keeps_five_dedupes_and_prunes_the_worst(tmp_path) -> None: # noqa: ANN001
|
||||
"""Placement, spec dedupe, and pruning hold the top-5 invariant."""
|
||||
repo = Repository(tmp_path / "t.db")
|
||||
try:
|
||||
for i in range(6):
|
||||
repo.record_discovery(
|
||||
"grand_tour", 1, f"a{i},b{i}", (f"a{i}", f"b{i}"),
|
||||
score=float(i), stats={}, app_version="0.1.0",
|
||||
)
|
||||
rows = repo.discoveries("grand_tour", width_bytes=1)
|
||||
assert len(rows) == 5
|
||||
assert min(r.score for r in rows) == 1.0 # the 0-score walk fell off
|
||||
# Re-walking a stored spec only ever *improves* its row.
|
||||
assert repo.record_discovery(
|
||||
"grand_tour", 1, "a5,b5", ("a5", "b5"),
|
||||
score=2.0, stats={}, app_version="0.1.0",
|
||||
) is None
|
||||
improved = repo.record_discovery(
|
||||
"grand_tour", 1, "a5,b5", ("a5", "b5"),
|
||||
score=9.0, stats={"hop_count": 2}, app_version="0.1.1",
|
||||
)
|
||||
assert improved is not None
|
||||
rows = repo.discoveries("grand_tour", width_bytes=1)
|
||||
assert len(rows) == 5
|
||||
top = max(rows, key=lambda r: r.score)
|
||||
assert top.score == 9.0 and top.app_version == "0.1.1"
|
||||
finally:
|
||||
repo.close()
|
||||
|
||||
|
||||
def test_leaderboard_ascends_for_thin_thread(tmp_path) -> None: # noqa: ANN001
|
||||
"""Weakest link keeps the *lowest* scores: a strong link never places."""
|
||||
repo = Repository(tmp_path / "t.db")
|
||||
try:
|
||||
for i, snr in enumerate((-2.0, -8.0, -5.0, -11.0, -3.0)):
|
||||
repo.record_discovery(
|
||||
"thin_thread", 1, f"c{i}", (f"c{i}",),
|
||||
score=snr, stats={}, app_version="0.1.0", ascending=True,
|
||||
)
|
||||
strong = repo.record_discovery(
|
||||
"thin_thread", 1, "c9", ("c9",),
|
||||
score=7.0, stats={}, app_version="0.1.0", ascending=True,
|
||||
)
|
||||
assert strong is None # +7 dB is a great link and a terrible record
|
||||
rows = repo.discoveries("thin_thread", width_bytes=1)
|
||||
assert len(rows) == 5 and max(r.score for r in rows) == -2.0
|
||||
finally:
|
||||
repo.close()
|
||||
|
||||
|
||||
def test_record_deletion_by_row_category_and_wholesale(tmp_path) -> None: # noqa: ANN001
|
||||
"""The three deletion grains: one record, one category, everything."""
|
||||
repo = Repository(tmp_path / "t.db")
|
||||
try:
|
||||
for category in ("grand_tour", "long_haul"):
|
||||
for width in (1, 2):
|
||||
repo.record_discovery(
|
||||
category, width, f"{category[:2]},{width}", ("x",),
|
||||
score=1.0, stats={}, app_version="0.1.0",
|
||||
)
|
||||
first = repo.discoveries("grand_tour", width_bytes=1)[0]
|
||||
assert repo.delete_discovery(first.id)
|
||||
assert not repo.delete_discovery(first.id) # already gone
|
||||
assert repo.delete_discoveries("grand_tour") == 1 # the width-2 row
|
||||
assert repo.discoveries("grand_tour") == []
|
||||
assert repo.delete_discoveries() == 2 # long_haul at both widths
|
||||
assert repo.discoveries() == []
|
||||
finally:
|
||||
repo.close()
|
||||
Reference in new issue
Block a user