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:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-15 13:16:18 -04:00
1 parent 7ac50ade53
commit f1385666a8
4 files changed
+776 -3

No files matched your search

+21 -1
View File
@@ -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);
+221 -2
View File
@@ -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:
+337
View File
@@ -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
+197
View File
@@ -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()