diff --git a/meshterm/persistence/db.py b/meshterm/persistence/db.py index 46d054b..5614202 100644 --- a/meshterm/persistence/db.py +++ b/meshterm/persistence/db.py @@ -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); diff --git a/meshterm/persistence/repository.py b/meshterm/persistence/repository.py index b875487..76d82d6 100644 --- a/meshterm/persistence/repository.py +++ b/meshterm/persistence/repository.py @@ -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: diff --git a/meshterm/services/records.py b/meshterm/services/records.py new file mode 100644 index 0000000..fa618ec --- /dev/null +++ b/meshterm/services/records.py @@ -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 diff --git a/tests/test_records.py b/tests/test_records.py new file mode 100644 index 0000000..94391d2 --- /dev/null +++ b/tests/test_records.py @@ -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()