From 99cd616ae5f941cb382e4402016bb3b35421e572 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 1 Sep 2026 00:32:55 -0400 Subject: [PATCH] The purge keeps the contacts worth a slot, and archives the rest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A device's contact table is finite, and a busy mesh fills it with whatever adverts arrived — mostly nodes heard once, in passing, four hops out — until there is no room left to discover anyone new. The age ladder could only ask how long ago; it had nothing to say about which of two equally quiet contacts was the one you would miss. So contacts are now rated. Six weighted terms, each normalised and summed: direct correspondence heaviest at 30, then how lately heard (25), how often (15), channel posting (12), hops (10) and distance (8). Additive rather than multiplicative, because a product lets one zero annihilate a contact that is strong everywhere else — a node advertising no position would have scored nothing however much you talk to it. The rule the whole thing rests on is that an unknown scores *neutral*. Half a real mesh advertises no location, plenty of nodes are never overheard as a relayed frame so carry no hop count, and a channel poster whose name two contacts share can be attributed to neither — the wire gives a channel frame no sender key at all. A term that cannot be computed takes the population median of the contacts that could, so the decision falls to the axes that are known. Scoring those as zero would have swept by how much metadata a node happens to broadcast. It is also why the two least reliable terms carry the two smallest weights, and why distance calibrates against this mesh's own median spread rather than a constant: 50 km is far downtown and unremarkable in a valley. A newcomer gets 25 points decaying to nothing over a fortnight, because every other term rewards accumulated evidence and a node first heard this morning is otherwise arithmetically identical to one quiet for a year. Four things are never candidates at all: a watched node, anyone you have sent a message to, a repeater whose admin login is stored, and a contact MeshTerm has never heard — that last one predates this history, and sweeping it would be purging by how long the app has been running. They still rank, since a percentile that dropped them would not be a rank against your contacts; they just consume no kept slot, so starring a node never deepens the next sweep. Only the percentile is ever displayed. A raw 47.3 means nothing without the distribution it came from and would need a legend the moment the weights were retuned. The victims are archived, not deleted: off the device, which is the scarce resource, and kept here with a stamp. Everything else was already independent of the contact row — reception history, map position, transcripts — and the store keeps the full key, so a restore is one write, which the chat screen already performs on demand when a send is rejected for an unknown recipient. merge_contacts learns to withhold them, or the union would put them straight back and the sweep would look like it did nothing. The old age ladder survives as the second section of the one picker, because "everything I haven't heard in a year" is a plain predictable operation a ranking cannot express. Both routes converge on the same preview — weakest first, with each row's percentile and the two or three facts that put it there — so an age rung reaching into contacts that rank perfectly well says so before the typed confirm rather than after. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/core/contact_score.py | 614 +++++++++++++++++++++++++++++ meshterm/core/contact_store.py | 119 +++++- meshterm/persistence/repository.py | 159 +++++++- meshterm/ui/contacts_screen.py | 250 +++--------- meshterm/ui/node_detail_screen.py | 86 +++- meshterm/ui/purge_screen.py | 520 ++++++++++++++++++++++++ tests/test_contact_score.py | 335 ++++++++++++++++ tests/test_contact_store.py | 79 ++++ tests/test_device_config.py | 118 ++++-- tests/test_gallery.py | 59 ++- 10 files changed, 2098 insertions(+), 241 deletions(-) create mode 100644 meshterm/core/contact_score.py create mode 100644 meshterm/ui/purge_screen.py create mode 100644 tests/test_contact_score.py diff --git a/meshterm/core/contact_score.py b/meshterm/core/contact_score.py new file mode 100644 index 0000000..395a2a3 --- /dev/null +++ b/meshterm/core/contact_score.py @@ -0,0 +1,614 @@ +"""Rating contacts by how much they are worth a slot in the device's contact table. + +A companion's contact table is finite, and a mesh fills it with whatever adverts happen to +arrive — so a radio left running long enough ends up holding mostly nodes heard once, in +passing, from four hops away, while there is no room left to *discover* anyone new. The +Contacts screen's bulk sweep (see :func:`~meshterm.ui.purge_screen.purge_contacts`) is how +that table gets its headroom back, and this module is the judgement it runs on: one score +per contact, so the sweep can take the weakest and leave the ones you would actually miss. + +**The score is additive, never multiplicative.** Six terms, each normalised to ``0..1`` and +weighted (:class:`ScoreWeights`), summed. A product would let a single zero annihilate an +otherwise strong contact — a node that never advertised a position would score nothing at +all however much you talk to it — which is exactly the failure mode a "quality" heuristic +must not have. + +**An unknown scores neutral, not zero.** This is the load-bearing rule. Roughly half the +contacts on a real mesh advertise no location, plenty are never overheard as a relayed +packet so have no hop count, and a channel poster whose name matches no contact cannot be +attributed at all. If "we don't know" resolved to ``0.0``, every one of those would sink to +the bottom *together*, and the sweep would purge by how much metadata a node happens to +broadcast rather than by how much it is worth. So a term that cannot be computed returns +``None`` and is filled with the **population median** of the contacts that could compute it +(:func:`_fill_unknowns`) — the contact lands exactly where an average peer would on that +axis, and the decision falls to the axes that *are* known. It is also why the two least +reliable terms carry the two smallest weights. + +**A newcomer gets time to earn its keep.** Every term above rewards accumulated evidence, +so a node first heard this morning is indistinguishable from one that has been quiet for a +year — both have one advert and no history. :attr:`ScoreWeights.grace` therefore adds a +bonus that decays linearly to nothing over :attr:`ScoreWeights.grace_days`, enough to lift a +newcomer clear of the sweep for a fortnight while it either becomes a real neighbour or +doesn't. A contact MeshTerm has *never* heard (added by hand, or inherited from the device +before this history began) has no arrival time to decay from and is protected outright +rather than being punished for MeshTerm's own ignorance — see :data:`PROTECT_UNOBSERVED`. + +**Some contacts are never candidates.** A score is a heuristic and a heuristic must not +overrule an explicit choice, so :func:`protection_for` short-circuits four cases before any +arithmetic: a watched node, anyone you have sent a direct message to, a repeater whose +admin credentials are stored, and the unobserved contact above. They are still scored and +still ranked — they are real contacts and the percentile scale is the whole population — +but they are never swept. + +**What is displayed is the percentile, never the score.** A raw ``47.3`` means nothing +without the distribution it came from; a contact's *rank against your other contacts* is +self-calibrating, needs no legend, and stays comparable when the weights change. So +:class:`ScoredContact` carries :attr:`~ScoredContact.percentile` and the UI shows only that +(see :func:`percentile_rank`). +""" + +from __future__ import annotations + +import math +from dataclasses import dataclass, replace +from statistics import median +from typing import Optional, Sequence + +from .geo import haversine_km +from .models import Contact + +#: Protection reason: the node is starred in the Watchtower. An explicit pin outranks every +#: heuristic in this module — the user already said this one matters. +PROTECT_WATCHED = "watched" + +#: Protection reason: you have sent this contact a direct message. Choosing to talk to +#: someone is the strongest statement of intent the app can observe, and it should not be +#: undone by a score. (Inbound-only traffic does *not* protect — anyone can message you.) +PROTECT_MESSAGED = "messaged" + +#: Protection reason: a repeater or room server whose admin password is stored. Purging it +#: costs the login, which is a far larger loss than a contact slot is a gain. +PROTECT_ADMIN = "admin" + +#: Protection reason: MeshTerm has never heard this contact, so every evidence term is +#: empty for a reason that says nothing about the node. It came from the device's own table +#: (or was added by hand) before this history began; sweeping it would be purging by how +#: long MeshTerm has been running rather than by anything the contact did. +PROTECT_UNOBSERVED = "unobserved" + +#: The order protections are reported in when a contact qualifies for several — most +#: deliberate first, so the preview explains a row by the strongest claim on it. +PROTECTION_ORDER = (PROTECT_WATCHED, PROTECT_MESSAGED, PROTECT_ADMIN, PROTECT_UNOBSERVED) + +#: How a protection reads in the UI, keyed by the constants above. +PROTECTION_LABELS = { + PROTECT_WATCHED: "watched", + PROTECT_MESSAGED: "you messaged", + PROTECT_ADMIN: "admin login", + PROTECT_UNOBSERVED: "never heard here", +} + + +@dataclass(frozen=True) +class ScoreWeights: + """The weights and half-lives the score is built from. + + The six term weights sum to 100, so a score reads as "out of 100" before the grace + bonus is added — though nothing displays it (see the module docstring: the UI shows the + percentile). Their relative sizes encode the ranking the operator asked for: direct + correspondence far above everything, recency next, then raw volume, then the three + weaker signals — of which the two least reliable (hops, distance) carry the least. + + Attributes: + dm: Weight of direct-message correspondence — the heaviest term. A conversation is + the only signal here that required a human decision on *both* ends. + recency: Weight of how lately the contact was heard. + volume: Weight of how many times it has been heard. + channel: Weight of posting in channels the device is configured for. + hops: Weight of topological closeness (fewer relays is better). + distance: Weight of geographic closeness — the least reliable term, since about + half of a real mesh advertises no position at all. + grace: Bonus points a brand-new contact starts with, decaying linearly to zero over + :attr:`grace_days`. Large enough to clear most of the field, because the whole + point is that a newcomer has no evidence yet. + grace_days: How long the newcomer bonus takes to fade completely. + recency_half_life_days: Half-life of the recency term. Two weeks: long enough to + ride out a node that adverts weekly, short enough that a month of silence tells. + dm_half_life_days: Half-life of *conversation* recency. Deliberately much longer + than :attr:`recency_half_life_days` — someone you exchanged messages with in + the spring is still someone you correspond with, while a node last overheard in + the spring is simply gone. + volume_saturation: The packet count at which the volume term reaches ``1.0``. + dm_saturation: The message count at which the conversation-volume half reaches + ``1.0``. + channel_saturation: The post count at which the channel term reaches ``1.0``. + hops_midpoint: Hop count at which the hops term falls to ``0.5``. + """ + + dm: float = 30.0 + recency: float = 25.0 + volume: float = 15.0 + channel: float = 12.0 + hops: float = 10.0 + distance: float = 8.0 + + grace: float = 25.0 + grace_days: float = 14.0 + + recency_half_life_days: float = 14.0 + dm_half_life_days: float = 90.0 + volume_saturation: float = 100.0 + dm_saturation: float = 50.0 + channel_saturation: float = 30.0 + hops_midpoint: float = 2.0 + + +#: The default weighting, used everywhere unless a caller passes its own. +DEFAULT_WEIGHTS = ScoreWeights() + + +@dataclass(frozen=True) +class ContactSignals: + """Everything the score reads about one contact, already gathered from the history. + + Assembled by :meth:`~meshterm.persistence.repository.Repository.contact_signals` in a + handful of grouped queries rather than per contact, so scoring a table of several + hundred costs a constant number of scans. Every optional field means *unknown* and is + filled with the population median before it is scored — never treated as zero. + + Attributes: + node: The contact's 12-hex canonical id (how observations key a node). + heard_age_days: Days since the contact was last heard, or ``None`` if never. + packets: How many transmissions MeshTerm has heard *from* this node. Counts the + app's own reception history, so a fresh install legitimately reads zero for + everyone — which is why the sweep shows the whole ranked preview before acting. + dm_total: Direct messages exchanged with this contact, both directions. + dm_outbound: How many of those we sent. Non-zero protects the contact outright. + dm_age_days: Days since the most recent direct message either way, or ``None``. + channel_posts: Messages this contact posted on a configured channel, attributed by + the ``Name: `` prefix a channel message carries (the wire has no sender key). + channel_attributed: Whether that attribution was even possible — ``False`` when the + contact's name is shared by another contact or never appeared, so the term + reads unknown rather than "posted nothing". + hops: Median relay count of packets seen originating from this node, or ``None`` + when none was ever overheard as a relayed frame. + distance_km: Great-circle distance from our own node, or ``None`` when either end + advertises no position. + known_days: Days since MeshTerm first heard this node, or ``None`` if never heard — + which is what :data:`PROTECT_UNOBSERVED` keys on. + watched: Whether the node is starred in the Watchtower. + has_admin: Whether admin credentials are stored for it. + """ + + node: str + heard_age_days: Optional[float] = None + packets: int = 0 + dm_total: int = 0 + dm_outbound: int = 0 + dm_age_days: Optional[float] = None + channel_posts: int = 0 + channel_attributed: bool = False + hops: Optional[float] = None + distance_km: Optional[float] = None + known_days: Optional[float] = None + watched: bool = False + has_admin: bool = False + + +@dataclass(frozen=True) +class ScoredContact: + """One contact's standing among the others: its score, its percentile, and why. + + Attributes: + contact: The contact this describes. + signals: The evidence the score was computed from. + score: The weighted sum plus any newcomer grace. Never displayed — see + :attr:`percentile`, and the module docstring for why. + percentile: Percentile rank within the scored population, ``0``–``100``. **This is + the only number the UI shows**: it is self-calibrating (a mesh of 30 contacts + and one of 300 both read the same way), needs no legend, and stays meaningful + if the weights are ever retuned. + protection: Why this contact can never be swept, or ``None`` if it can. One of the + ``PROTECT_*`` constants. + reasons: Short lowercase phrases naming what this contact's standing rests on — + its weakest lanes when it is a purge candidate, so the preview row explains + itself without the reader having to know the formula. + """ + + contact: Contact + signals: ContactSignals + score: float + percentile: int + protection: Optional[str] = None + reasons: tuple[str, ...] = () + + @property + def protected(self) -> bool: + """Whether this contact is exempt from the sweep whatever its score.""" + return self.protection is not None + + @property + def protection_label(self) -> str: + """The protection's UI wording, or the empty string when unprotected.""" + return PROTECTION_LABELS.get(self.protection or "", "") + + +# -- the individual terms --------------------------------------------------------------- +# +# Each returns a value in 0..1, or ``None`` for "cannot be computed from this contact's +# evidence" — which the caller resolves to the population median rather than to zero. + + +def _decay(age_days: Optional[float], half_life: float) -> Optional[float]: + """Exponential decay from ``1.0`` at age zero, halving every ``half_life`` days. + + Args: + age_days: How old the event is, or ``None`` if it never happened. + half_life: Days for the value to halve. + + Returns: + The decayed weight, or ``None`` when ``age_days`` is ``None``. + """ + if age_days is None: + return None + return 0.5 ** (max(0.0, age_days) / half_life) + + +def _saturating(count: float, ceiling: float) -> float: + """A logarithmic ramp from ``0`` at zero to ``1`` at ``ceiling``, clipped above it. + + Logarithmic because the interesting difference is between 1 packet and 10, not between + 90 and 100: a node heard ten times is emphatically not one tenth as established as one + heard a hundred times, and a linear ramp would say exactly that. + + Args: + count: The observed tally. + ceiling: The tally at which the term reaches ``1.0``. + + Returns: + The ramped value, in ``0..1``. + """ + if count <= 0: + return 0.0 + return min(1.0, math.log1p(count) / math.log1p(ceiling)) + + +def term_recency(signals: ContactSignals, weights: ScoreWeights) -> Optional[float]: + """How lately the contact was heard, decaying with a two-week half-life. + + A contact never heard at all scores ``0.0`` rather than unknown: unlike a missing + location, "we have never received anything from this node" is real evidence about the + node, not a gap in what it chose to broadcast. (A contact MeshTerm has never heard + *because the history is younger than the contact* is caught earlier, by + :data:`PROTECT_UNOBSERVED`.) + """ + if signals.heard_age_days is None: + return 0.0 + return _decay(signals.heard_age_days, weights.recency_half_life_days) + + +def term_volume(signals: ContactSignals, weights: ScoreWeights) -> Optional[float]: + """How much traffic MeshTerm has heard from this node, on a saturating log ramp.""" + return _saturating(signals.packets, weights.volume_saturation) + + +def term_dm(signals: ContactSignals, weights: ScoreWeights) -> Optional[float]: + """Direct correspondence: mostly how much, partly how lately. + + Split 60/40 between volume and recency so that a long exchange which has gone quiet + still counts for most of what it was worth — a conversation is a standing relationship, + not an event that expires. A contact with no messages at all scores ``0.0``: an absent + conversation is evidence, not a gap. + """ + if signals.dm_total <= 0: + return 0.0 + volume = _saturating(signals.dm_total, weights.dm_saturation) + recency = _decay(signals.dm_age_days, weights.dm_half_life_days) or 0.0 + return 0.6 * volume + 0.4 * recency + + +def term_channel(signals: ContactSignals, weights: ScoreWeights) -> Optional[float]: + """How much this contact posts on the channels the device is configured for. + + Returns ``None`` when the contact could not be attributed at all — a channel message + carries no sender key, only a ``Name: `` prefix, so a contact whose name is shared with + another contact (or which has simply never appeared as a prefix) is *unmeasured* rather + than silent. Scoring that as zero would quietly demote everyone whose name happens to + collide, which is a property of the name and not of the node. + """ + if not signals.channel_attributed: + return None + return _saturating(signals.channel_posts, weights.channel_saturation) + + +def term_hops(signals: ContactSignals, weights: ScoreWeights) -> Optional[float]: + """Topological closeness — a hyperbolic falloff, ``1.0`` direct and ``0.5`` at the midpoint. + + Hyperbolic rather than exponential because the difference between four hops and five + barely matters, while the difference between zero and one matters a great deal. + """ + if signals.hops is None: + return None + return 1.0 / (1.0 + max(0.0, signals.hops) / weights.hops_midpoint) + + +def term_distance(signals: ContactSignals, midpoint_km: Optional[float]) -> Optional[float]: + """Geographic closeness, scaled against *this mesh's own* median distance. + + The midpoint is the population's median known distance rather than a constant, so the + term reads the same way on a dense downtown mesh and a sparse rural one — 50 km is far + in the first and unremarkable in the second, and a hardcoded threshold would have to be + wrong on at least one of them. Unknown when either end advertises no position, or when + too few contacts do for a median to mean anything. + """ + if signals.distance_km is None or not midpoint_km: + return None + return 1.0 / (1.0 + max(0.0, signals.distance_km) / midpoint_km) + + +def term_grace(signals: ContactSignals, weights: ScoreWeights) -> float: + """The newcomer bonus, in points (not ``0..1``), decaying linearly to zero. + + Returns ``0.0`` for a contact with no arrival time — that case is protected outright + (:data:`PROTECT_UNOBSERVED`) rather than granted a bonus it could keep forever. + """ + if signals.known_days is None: + return 0.0 + remaining = 1.0 - (max(0.0, signals.known_days) / weights.grace_days) + return weights.grace * max(0.0, remaining) + + +# -- protections ------------------------------------------------------------------------ + + +def protection_for(signals: ContactSignals) -> Optional[str]: + """Why this contact can never be swept, or ``None`` if the score decides its fate. + + Checked in :data:`PROTECTION_ORDER` — most deliberate claim first — so a contact that + is both watched and messaged is explained by the star the user actually set. + + Args: + signals: The contact's gathered evidence. + + Returns: + One of the ``PROTECT_*`` constants, or ``None``. + """ + claims = { + PROTECT_WATCHED: signals.watched, + PROTECT_MESSAGED: signals.dm_outbound > 0, + PROTECT_ADMIN: signals.has_admin, + PROTECT_UNOBSERVED: signals.known_days is None, + } + for reason in PROTECTION_ORDER: + if claims[reason]: + return reason + return None + + +# -- the population pass ---------------------------------------------------------------- + + +#: How many contacts must advertise a position before their median is trusted as the +#: distance term's midpoint. Below this the term is dropped for everyone (it would be +#: calibrated against one or two nodes), which the median-fill then handles as any other +#: unknown. +_MIN_LOCATED = 4 + +#: The term names, in the order a :class:`ScoredContact` reports its reasons. +_TERM_NAMES = ("dm", "recency", "volume", "channel", "hops", "distance") + + +def _fill_unknowns(column: list[Optional[float]]) -> list[float]: + """Replace every ``None`` in one term's column with the median of the known values. + + THE rule that keeps the sweep honest (see the module docstring): a contact that could + not be measured on an axis lands exactly where an average peer lands on it, so the + decision falls to the axes that *were* measurable. A column nobody could compute + collapses to ``0.5`` throughout — neutral, and therefore inert once weighted, since it + then shifts every contact by the same amount and changes no ordering. + + Args: + column: One term's value per contact, with ``None`` for unknown. + + Returns: + The same column with the gaps filled. + """ + known = [v for v in column if v is not None] + fill = median(known) if known else 0.5 + return [fill if v is None else v for v in column] + + +def _self_distance( + contact: Contact, self_lat: Optional[float], self_lon: Optional[float] +) -> Optional[float]: + """Great-circle km from our own node to ``contact``, or ``None`` if either end is unplaced.""" + if self_lat is None or self_lon is None or not contact.has_location: + return None + return haversine_km(self_lat, self_lon, float(contact.lat), float(contact.lon)) + + +def percentile_rank(score: float, population: Sequence[float]) -> int: + """The percentile rank of ``score`` within ``population``, as an integer ``0``–``100``. + + Uses the standard mid-rank definition — everything strictly below, plus half of + everything equal — so a field of identical scores reads ``50`` for all of them rather + than ``0`` or ``100``, and the median contact reads about ``50``. + + Args: + score: The value to place. + population: Every score in the population, ``score`` included. + + Returns: + The percentile rank, rounded to an integer. + """ + if not population: + return 0 + below = sum(1 for value in population if value < score) + equal = sum(1 for value in population if value == score) + return int(round(100.0 * (below + 0.5 * equal) / len(population))) + + +def _reasons( + signals: ContactSignals, terms: dict[str, float], weights: ScoreWeights +) -> tuple[str, ...]: + """Name what this contact's standing rests on, weakest lane first. + + The preview has one line per contact and the reader should not have to know the formula + to audit a sweep — so each row says, in plain words, the two things that put it where it + is. Phrases are drawn from the *measured* signals rather than from the term values, so + "3 packets" is the actual tally and not a normalised fraction. + """ + phrases: list[tuple[float, str]] = [] + contribution = { + "dm": terms["dm"] * weights.dm, + "recency": terms["recency"] * weights.recency, + "volume": terms["volume"] * weights.volume, + "hops": terms["hops"] * weights.hops, + } + if signals.dm_total: + phrases.append((contribution["dm"], f"{signals.dm_total} messages")) + else: + phrases.append((0.0, "never messaged")) + if signals.heard_age_days is None: + phrases.append((0.0, "never heard")) + else: + phrases.append((contribution["recency"], _age_phrase(signals.heard_age_days))) + phrases.append((contribution["volume"], f"{signals.packets} pkts")) + if signals.hops is not None: + hops = signals.hops + label = "direct" if hops < 0.5 else f"{hops:g} hops" + phrases.append((contribution["hops"], label)) + phrases.sort(key=lambda pair: pair[0]) + return tuple(phrase for _, phrase in phrases[:3]) + + +def _age_phrase(days: float) -> str: + """A last-heard age in the fewest words: ``today`` / ``4d`` / ``6w`` / ``9mo`` / ``2y``.""" + if days < 1: + return "today" + if days < 14: + return f"{int(days)}d" + if days < 60: + return f"{int(days / 7)}w" + if days < 365: + return f"{int(days / 30)}mo" + return f"{days / 365:.0f}y" + + +def rank_contacts( + contacts: Sequence[Contact], + signals: dict[str, ContactSignals], + *, + self_lat: Optional[float] = None, + self_lon: Optional[float] = None, + weights: ScoreWeights = DEFAULT_WEIGHTS, +) -> list[ScoredContact]: + """Score and rank a whole contact table, strongest first. + + One pass to compute every term (leaving unknowns as ``None``), one pass to fill each + term's gaps with that term's population median, then the weighted sum plus grace. The + percentile is taken over the **whole** population — protected contacts included, since + they are real contacts and a rank that silently excluded them would not be a rank + against your contacts at all. + + Args: + contacts: The contacts to rank (our own node is not among them). + signals: Gathered evidence keyed by 12-hex node id; a contact with no entry is + scored from an empty :class:`ContactSignals`, which protects it as unobserved. + self_lat: Our own node's advertised latitude, if it has one. + self_lon: Our own node's advertised longitude, if it has one. + weights: The weighting to score under. + + Returns: + One :class:`ScoredContact` per input contact, highest score first. Ties break by + name so the order is stable between runs. + """ + if not contacts: + return [] + + gathered: list[ContactSignals] = [] + for contact in contacts: + node = _node_id(contact) + found = signals.get(node) or ContactSignals(node=node) + gathered.append( + replace(found, distance_km=_self_distance(contact, self_lat, self_lon)) + ) + + # The distance term calibrates against this mesh's own spread, so it needs the whole + # population before any single contact can be scored on it. + located = [s.distance_km for s in gathered if s.distance_km is not None] + midpoint = median(located) if len(located) >= _MIN_LOCATED else None + + columns: dict[str, list[Optional[float]]] = { + "dm": [term_dm(s, weights) for s in gathered], + "recency": [term_recency(s, weights) for s in gathered], + "volume": [term_volume(s, weights) for s in gathered], + "channel": [term_channel(s, weights) for s in gathered], + "hops": [term_hops(s, weights) for s in gathered], + "distance": [term_distance(s, midpoint) for s in gathered], + } + filled = {name: _fill_unknowns(column) for name, column in columns.items()} + + scores: list[float] = [] + per_contact_terms: list[dict[str, float]] = [] + for index, sig in enumerate(gathered): + terms = {name: filled[name][index] for name in _TERM_NAMES} + total = ( + terms["dm"] * weights.dm + + terms["recency"] * weights.recency + + terms["volume"] * weights.volume + + terms["channel"] * weights.channel + + terms["hops"] * weights.hops + + terms["distance"] * weights.distance + + term_grace(sig, weights) + ) + per_contact_terms.append(terms) + scores.append(total) + + ranked = [ + ScoredContact( + contact=contact, + signals=sig, + score=score, + percentile=percentile_rank(score, scores), + protection=protection_for(sig), + reasons=_reasons(sig, terms, weights), + ) + for contact, sig, score, terms in zip( + contacts, gathered, scores, per_contact_terms + ) + ] + ranked.sort(key=lambda scored: (-scored.score, scored.contact.name.casefold())) + return ranked + + +def sweep_candidates(ranked: Sequence[ScoredContact], keep: int) -> list[ScoredContact]: + """The contacts a "keep the strongest ``keep``" sweep would actually remove, weakest first. + + Protected contacts are never candidates, and — the subtlety — they **do not consume** + one of the kept slots: a table of 100 with 30 protected and ``keep=50`` sweeps the 50 + weakest *sweepable* contacts, leaving 50 unprotected plus the 30 protected. Counting + protections against the target instead would mean starring a node quietly deepened the + next sweep, which is the opposite of what a star is for. The picker's rungs therefore + report their own real removal counts rather than arithmetic on the table size (see + :func:`~meshterm.ui.purge_screen.purge_contacts`). + + Args: + ranked: The full ranking from :func:`rank_contacts`, strongest first. + keep: How many unprotected contacts to keep. + + Returns: + The victims, weakest first — so the preview reads bottom-up, and a truncated read + of it still shows the ones going first. + """ + sweepable = [scored for scored in ranked if not scored.protected] + if keep >= len(sweepable): + return [] + victims = sweepable[keep:] if keep > 0 else list(sweepable) + return list(reversed(victims)) + + +def _node_id(contact: Contact) -> str: + """The 12-hex canonical id a contact's history is keyed by (see ``observations.node``).""" + ident = contact.public_key or contact.key_prefix or "" + return ident.lower().removeprefix("0x")[:12] diff --git a/meshterm/core/contact_store.py b/meshterm/core/contact_store.py index cd50ec4..b2b07d4 100644 --- a/meshterm/core/contact_store.py +++ b/meshterm/core/contact_store.py @@ -19,6 +19,24 @@ every remembered contact is already present and nothing is added — no device-t Recording never *removes* a contact on a device's empty read, so a bridge that just restarted doesn't wipe the memory of what it knew. +A contact can also be **archived**, which is the opposite arrangement and the one the +Contacts sweep uses (see :mod:`~meshterm.core.contact_score`): the contact is deleted from +the *device*, freeing a slot in a companion's finite contact table, and kept here with an +:attr:`~RememberedContact.archived_at` stamp so nothing about it is actually lost. +:func:`merge_contacts` skips an archived contact — without that the union above would put it +straight back into every list, indistinguishable from a live one, and the sweep would appear +to have done nothing. What survives an archive is everything except the device row: the +node's whole reception history (untouched — it lives in the SQLite database, not here), its +direct-message transcript (keyed by key prefix, not by a contact row), and its full public +key, which is exactly what :meth:`~meshterm.core.connection.Device.add_contact` needs to put +it back. So a restore is one write, and the chat screen already performs it on demand when a +send is rejected for an unknown recipient (see +:class:`~meshterm.core.connection.ContactNotOnDeviceError`). + +The one place to be careful is a firmware-less bridge, whose contact table is RAM-only and +for which this store *is* the memory: archiving there removes the contact from the lists for +real, and only a restore brings it back. + Like the other operator state (mutes, remembered channels, saved settings), this is global machine state in a small JSON file (``/contacts.json``), not the per-invocation SQLite database. Reads are served from memory after the first load; a write happens only when the @@ -74,6 +92,10 @@ class RememberedContact: list's last-heard column; ``None`` when unknown. lat: Last advertised latitude, if it shared one. lon: Last advertised longitude, if it shared one. + archived_at: Unix seconds when this contact was swept off the device, or ``None`` + while it is a live contact. An archived contact is remembered in full but kept + *out* of :func:`merge_contacts`, so it stops occupying a device slot without + being forgotten — and the stamp is what lets a list say how long ago it went. """ public_key: str @@ -82,6 +104,12 @@ class RememberedContact: last_advert: Optional[int] = None lat: Optional[float] = None lon: Optional[float] = None + archived_at: Optional[int] = None + + @property + def archived(self) -> bool: + """Whether this contact has been swept off the device but kept here.""" + return self.archived_at is not None @classmethod def from_contact(cls, contact: Contact) -> "RememberedContact": @@ -197,6 +225,88 @@ class ContactStore: self._state[dev] = current self._save() + def archived(self, device_pubkey: str) -> list[RememberedContact]: + """The contacts archived off this device, most recently archived first. + + The Contacts screen's ``Archived`` section. Ordered by when each was swept rather + than by name, because that is the question the section answers — *what did the last + sweep take?* — and a fresh sweep's work should be at the top of it. + """ + remembered = self._state.get(_norm(device_pubkey), {}).values() + return sorted( + (c for c in remembered if c.archived), + key=lambda c: (-(c.archived_at or 0), c.name.lower()), + ) + + def archive(self, device_pubkey: str, contact: Contact, *, when: int) -> None: + """Mark one contact archived — remembered in full, but no longer merged into lists. + + The store half of a sweep: the device half is + :meth:`~meshterm.core.connection.Device.remove_contact`, and this is what keeps the + removal from being a loss. The contact is *upserted* first, so archiving one the + store had never recorded (a live-only contact on a firmware radio, which is the + usual case) still remembers everything needed to put it back. + + Args: + device_pubkey: The device's own public key. + contact: The contact being swept. + when: Unix seconds to stamp the archive with. + """ + dev = _norm(device_pubkey) + if not dev or not contact.public_key: + return # unaddressable — there would be nothing to restore it by + remembered = RememberedContact.from_contact(contact) + entry = RememberedContact( + public_key=remembered.public_key, + name=remembered.name, + node_type=remembered.node_type, + last_advert=remembered.last_advert, + lat=remembered.lat, + lon=remembered.lon, + archived_at=int(when), + ) + current = dict(self._state.get(dev, {})) + if current.get(entry.public_key) == entry: + return + current[entry.public_key] = entry + self._state[dev] = current + self._save() + + def restore(self, device_pubkey: str, contact_pubkey: str) -> Optional[RememberedContact]: + """Clear one contact's archived mark, returning what was archived. + + Only the *store* side: the caller writes the contact back onto the device (see + :meth:`~meshterm.core.connection.Device.add_contact`) and calls this once that + succeeded, so a failed write never leaves a contact listed as live on a device that + doesn't hold it. + + Args: + device_pubkey: The device's own public key. + contact_pubkey: The contact to un-archive. + + Returns: + The record as it was archived, or ``None`` if no archived contact matched. + """ + dev = _norm(device_pubkey) + key = _norm(contact_pubkey) + contacts = self._state.get(dev) or {} + entry = contacts.get(key) + if entry is None or not entry.archived: + return None + current = dict(contacts) + current[key] = RememberedContact( + public_key=entry.public_key, + name=entry.name, + node_type=entry.node_type, + last_advert=entry.last_advert, + lat=entry.lat, + lon=entry.lon, + archived_at=None, + ) + self._state[dev] = current + self._save() + return entry + def forget(self, device_pubkey: str, contact_pubkey: str) -> None: """Drop one remembered contact; persist only a real change.""" dev = _norm(device_pubkey) @@ -239,6 +349,8 @@ def _contact_to_json(contact: RememberedContact) -> dict: entry["lat"] = contact.lat if contact.lon is not None: entry["lon"] = contact.lon + if contact.archived_at is not None: + entry["archived_at"] = contact.archived_at return entry @@ -257,6 +369,7 @@ def _contact_from_json(entry: object) -> Optional[RememberedContact]: last_advert=_opt_int(entry.get("last_advert")), lat=_opt_float(entry.get("lat")), lon=_opt_float(entry.get("lon")), + archived_at=_opt_int(entry.get("archived_at")), ) @@ -282,6 +395,10 @@ def merge_contacts( extra = [ remembered.to_contact() for remembered in store.contacts(device_pubkey) - if remembered.public_key and remembered.public_key not in present + # An archived contact is deliberately withheld: it was swept off the device to free + # a slot, and merging it back would undo the sweep in the only place anyone looks. + if remembered.public_key + and not remembered.archived + and remembered.public_key not in present ] return list(live) + extra diff --git a/meshterm/persistence/repository.py b/meshterm/persistence/repository.py index 5f10a3b..5e2edc4 100644 --- a/meshterm/persistence/repository.py +++ b/meshterm/persistence/repository.py @@ -12,7 +12,7 @@ import statistics from dataclasses import dataclass from datetime import datetime, timedelta from pathlib import Path -from typing import Any, Optional +from typing import TYPE_CHECKING, Any, Optional, Sequence from ..core.frames import CHANNEL_CLASSES, ENDPOINT_HASH_BYTES from ..core.models import ( @@ -29,6 +29,9 @@ from ..core.models import ( ) from . import db +if TYPE_CHECKING: + from ..core.contact_score import ContactSignals + #: The trailing window the dashboard's live observation stats and packet feed prune to #: — "what's happening right now" territory, labelled "reception over 2 h" on the RF @@ -54,6 +57,14 @@ ACTIVITY_BUCKETS = 72 #: characters. The rest of :data:`ACTIVITY_BUCKETS` feeds the scaling peak but isn't shown. ACTIVITY_DRAWN_BUCKETS = 24 +#: How many recent packet frames the contact-scoring hop median is drawn from (see +#: :meth:`Repository.contact_signals`). The same order of magnitude as +#: :meth:`Repository.packet_paths`' own cap, and for the same reasons: it is the one scan +#: there that materialises a row per packet, and old hops describe a topology that has since +#: moved. Deep enough that every contact heard at all in the recent past gets several +#: readings to take a median over. +HOP_EVIDENCE_LIMIT = 20000 + def _packet_raw(row: sqlite3.Row) -> Optional[dict]: """Rebuild the minimal raw payload a stored ``packet`` observation is read back with. @@ -1628,6 +1639,152 @@ class Repository: ] return sorted(nodes, key=lambda n: n.last_seen, reverse=True) + def contact_signals(self, nodes: "Sequence[str]") -> "dict[str, ContactSignals]": + """Gather every scoring signal for a set of nodes, in a fixed number of scans. + + The evidence behind the Contacts sweep (see + :mod:`~meshterm.core.contact_score`). Deliberately *set-based*: a table of several + hundred contacts is answered by five grouped passes over the history rather than by + five queries per contact, so the sweep's cost tracks the size of the database and + not the size of the table being swept. + + Each pass fills one part of :class:`~meshterm.core.contact_score.ContactSignals`: + + * **Reception** — first heard, last heard, and the transmission tally, from + ``observations``. ``packet`` rows are excluded exactly as :meth:`heard_nodes` + excludes them, so the tally means "heard *from* this node" and stays the same + number the contact list's ``PKTS`` lane shows. + * **Hops** — the median relay count of packets seen originating from the node, from + the ``packet`` rows this time, since those are the only ones carrying a path (see + :meth:`packet_paths`). Median rather than minimum: one lucky direct reception + shouldn't make a four-hop node read as a neighbour. + * **Direct messages** — totals, our own outbound share, and the age of the latest, + matched by *prefix*: ``messages.peer`` holds whatever width the wire addressed, + which is not always the 12 hex an observation keys on (see + :meth:`last_message_by_peer`). + * **Channel posts** — attributed by the ``Name: `` prefix a channel message + carries, because the wire gives a channel frame no sender key at all. A name held + by two contacts attributes to *neither*: the caller marks those unattributed so + the score reads them as unknown rather than as silence. + + Args: + nodes: The 12-hex canonical node ids to gather for. Anything absent from the + history simply comes back with an empty record, which the score protects + rather than punishes. + + Returns: + One :class:`~meshterm.core.contact_score.ContactSignals` per requested node, + keyed by that id. Name-keyed channel attribution is *not* filled in here (the + repository knows nothing about which name belongs to which contact) — see + :meth:`channel_post_counts`. + """ + from ..core.contact_score import ContactSignals + + wanted = {n for n in nodes if n} + if not wanted: + return {} + now = utcnow() + + def age_days(iso: Optional[str]) -> Optional[float]: + """Days from a stored ISO stamp to now, or ``None`` for an unparseable one.""" + if not iso: + return None + try: + when = datetime.fromisoformat(iso) + except (TypeError, ValueError): + return None + return max(0.0, (now - when).total_seconds() / 86400.0) + + # -- reception: one grouped pass over the non-packet history ------------------ + heard: dict[str, tuple[str, str, int]] = {} + for row in self._conn.execute( + "SELECT node, MIN(observed_at) AS first, MAX(observed_at) AS last, " + "COUNT(*) AS n FROM observations " + "WHERE node IS NOT NULL AND kind != 'packet' GROUP BY node" + ): + if row["node"] in wanted: + heard[row["node"]] = (row["first"], row["last"], int(row["n"] or 0)) + + # -- hops: the median relay count of packets originating from each node ------- + # Bounded to the most recent frames, like :meth:`packet_paths`, and for the same + # two reasons: this is the one pass that builds a row object per packet rather than + # aggregating in SQL, and a year-old hop count is evidence about a topology that no + # longer exists. Newest first, so the cap keeps the readings worth having. + hop_counts: dict[str, list[int]] = {} + for row in self._conn.execute( + "SELECT node, path FROM observations " + "WHERE kind = 'packet' AND node IS NOT NULL AND path IS NOT NULL " + "ORDER BY id DESC LIMIT ?", + (HOP_EVIDENCE_LIMIT,), + ): + if row["node"] not in wanted: + continue + hops = [h for h in (row["path"] or "").split(",") if h] + hop_counts.setdefault(row["node"], []).append(len(hops)) + + # -- direct messages: totals, our share, and the latest, matched by prefix ---- + dm_rows = self._conn.execute( + "SELECT peer, COUNT(*) AS total, SUM(outbound) AS sent, " + "MAX(created_at) AS last FROM messages " + "WHERE is_channel = 0 AND peer IS NOT NULL GROUP BY peer" + ).fetchall() + + signals: dict[str, ContactSignals] = {} + for node in sorted(wanted): + first, last, packets = heard.get(node, (None, None, 0)) + hops = hop_counts.get(node) + total = sent = 0 + latest: Optional[str] = None + for row in dm_rows: + peer = (row["peer"] or "").lower() + # Either side may be the shorter: the wire addresses at whatever width it + # likes, so a stored 6-hex peer and a 12-hex node id are the same node when + # one is a prefix of the other. + if not peer or not (peer.startswith(node) or node.startswith(peer)): + continue + total += int(row["total"] or 0) + sent += int(row["sent"] or 0) + if latest is None or (row["last"] or "") > latest: + latest = row["last"] + signals[node] = ContactSignals( + node=node, + heard_age_days=age_days(last), + packets=packets, + dm_total=total, + dm_outbound=sent, + dm_age_days=age_days(latest), + hops=statistics.median(hops) if hops else None, + known_days=age_days(first), + ) + return signals + + def channel_post_counts(self) -> "dict[str, int]": + """How many channel messages each *name* has posted, lowercased. + + A channel frame carries no sender key — senders identify themselves by prefixing + the text with ``Name: `` (see + :func:`~meshterm.core.channels.split_channel_sender`), so this is the only + attribution available and it is by display name alone. The caller is responsible + for refusing to trust a name two contacts share; this method only counts. + + Our own outbound posts are excluded: they say nothing about anyone else. + + Returns: + Post counts keyed by lowercased sender name. Messages whose text carries no + usable name prefix contribute nothing. + """ + from ..core.channels import split_channel_sender + + counts: dict[str, int] = {} + for row in self._conn.execute( + "SELECT text FROM messages WHERE is_channel = 1 AND outbound = 0" + ): + name, _ = split_channel_sender(row["text"] or "") + if name: + key = name.strip().casefold() + counts[key] = counts.get(key, 0) + 1 + return counts + # -- chat messages ---------------------------------------------------------- def record_chat_message( diff --git a/meshterm/ui/contacts_screen.py b/meshterm/ui/contacts_screen.py index e634a6b..28a8242 100644 --- a/meshterm/ui/contacts_screen.py +++ b/meshterm/ui/contacts_screen.py @@ -10,34 +10,38 @@ and backing out of that page returns to the list right where it stood. The one-s (``meshterm contacts --sort …``) still renders the static :func:`~meshterm.ui.widgets.contacts_table`; only the menu gets the live list. -Removing *one* named contact belongs to that contact, not to the list: it is the last -action on its Node detail page (see :mod:`~meshterm.ui.node_detail_screen`), where the -reader is already looking at the node they mean to drop. The list only rebuilds afterwards. +Below the contacts sits the list's own maintenance action — **Purge contacts** — the bulk +counterpart, which exists because a companion's contact table is finite and a busy mesh +fills it with nodes heard once in passing until there is no room left to discover anyone +new. It ranks the whole table (see :mod:`~meshterm.core.contact_score`) and archives the +weakest off the device while MeshTerm keeps them; the flow, its ladder and its preview live +in :mod:`~meshterm.ui.purge_screen`. Our own node, pinned above the list, is never a +candidate — it isn't in the device's contact table. -Below the contacts sits the list's own maintenance action — **Purge stale contacts** — the -bulk counterpart, sweeping out the contacts a device has accumulated but no longer hears. It -offers an age ladder (a day up to a year, plus a *never heard* bucket), each rung showing a -live count of how many contacts it would remove, so the impact is visible before anything is -chosen; the pick is then gated behind a typed ``delete`` confirm. Either way — one contact -or a sweep — the removal lands in both halves of what the list shows: the device's own -table, and the cross-session store (see :mod:`~meshterm.core.contact_store`), so a -firmware-less bridge doesn't merge them back. Only the *contact* is dropped: each node's -reception history and overheard traffic in MeshTerm are untouched. Our own node, pinned above -the list, is never a purge candidate (it isn't in the device's contact table). +The contacts a sweep archived are listed under their own **Archived** section at the foot of +this screen. They are shown rather than hidden because silent archiving is how a reader +loses track of what they archived, and because the section is the route back: Enter opens +the node's detail page, which offers to restore it. + +Removing *one* named contact for good still belongs to that contact rather than to the list: +it is the last action on its Node detail page, where the reader is already looking at the +node they mean to drop. That one is a real deletion — it lands in both halves of what the +list shows, the device's own table and the cross-session store (see +:mod:`~meshterm.core.contact_store`), so a firmware-less bridge doesn't merge it back. +Either way, only the *contact* goes: each node's reception history and overheard traffic in +MeshTerm are untouched. """ from __future__ import annotations -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Optional -from rich.text import Text - -from ..core.connection import ContactNotOnDeviceError from .contactlist import ContactListScreen, ContactRow -from .menus import marked_label, menu_rows +from .menus import marked_label +from .purge_screen import archived_rows, purge_contacts from .tui import Choice, Separator from .tui.screen import CANCEL -from .widgets import ContactsSort, _age_seconds, _contact_pkts +from .widgets import ContactsSort, _contact_pkts if TYPE_CHECKING: from ..context import AppContext @@ -51,55 +55,6 @@ YOU = ("you",) #: and from :data:`YOU`): the purge action row and the bare ``Back`` exit row. _PURGE = ("purge",) -#: A day in seconds, for the purge age ladder. -_DAY = 86400 - -#: The age rungs the purge picker offers, ``(label, min_age_seconds)``. A contact qualifies -#: for a rung when its last-heard age is *at least* that long; a never-heard contact — one -#: with no advert time at all — is excluded here and swept only by the separate never-heard -#: bucket, so an age rung never quietly deletes a freshly-added contact that hasn't had time -#: to advert yet. -PURGE_RUNGS: tuple[tuple[str, int], ...] = ( - ("Older than 1 day", _DAY), - ("Older than 1 week", 7 * _DAY), - ("Older than 10 days", 10 * _DAY), - ("Older than 2 weeks", 14 * _DAY), - ("Older than 1 month", 30 * _DAY), - ("Older than 3 months", 90 * _DAY), - ("Older than 6 months", 180 * _DAY), - ("Older than 1 year", 365 * _DAY), -) - -#: The picker value for the never-heard bucket (contacts with no advert time at all). -_NEVER = "__never__" - - -def stale_past(contacts: "list[Contact]", min_age_seconds: float) -> "list[Contact]": - """Contacts last heard at least ``min_age_seconds`` ago. - - Never-heard contacts (no last-heard time) are *excluded* — they have their own bucket - (see :func:`never_heard`), so an age rung sweeps only contacts that were once heard and - have since gone quiet, never a contact that has simply not adverted yet. - """ - out: list["Contact"] = [] - for contact in contacts: - secs = _age_seconds(contact.last_seen) - if secs is not None and secs >= min_age_seconds: - out.append(contact) - return out - - -def never_heard(contacts: "list[Contact]") -> "list[Contact]": - """Contacts with no advert time at all — ones we have never heard broadcasting.""" - return [c for c in contacts if _age_seconds(c.last_seen) is None] - - -def _count_desc(n: int) -> str: - """The count shown against a purge rung: ``no contacts`` / ``1 contact`` / ``n contacts``.""" - if n == 0: - return "no contacts" - return f"{n} contact{'' if n == 1 else 's'}" - class ContactsScreen(ContactListScreen): """A full-screen, Ctrl+arrow-sortable list of this node and its known contacts. @@ -117,6 +72,7 @@ class ContactsScreen(ContactListScreen): prefix_bytes: int, counts: dict[str, int], sort: ContactsSort, + archived: Optional[list] = None, ) -> None: """Create the contacts screen over already-fetched contact data. @@ -130,7 +86,11 @@ class ContactsScreen(ContactListScreen): sort: The initial sort; mutated in place by the Ctrl+arrows. Its ring should span :data:`~meshterm.ui.contactlist.SORT_COLUMNS` so the hash sort is reachable. + archived: Pre-built rows for the ``Archived`` section (see + :func:`~meshterm.ui.purge_screen.archived_rows`), appended after the purge + action. ``None`` draws no section at all. """ + archived = list(archived or []) rows = [ContactRow(value=YOU, name=self_name, key=self_key, you=True)] for c in contacts: rows.append( @@ -147,16 +107,19 @@ class ContactsScreen(ContactListScreen): ) # The maintenance action closes the list, past every contact whatever the sort: a # blank spacer, then the err-tinted purge row (a `…` — it opens further prompts). - # Offered only when there are contacts to purge. + # Offered only when there are contacts to purge. Anything already archived follows + # it in its own section, so the two halves of the sweep — what it can still take, + # and what it has taken — sit together at the foot of the list. tail: list = [] if contacts: tail = [ Separator(" "), Choice( - title=marked_label("🗑", "Purge stale contacts…", "err"), + title=marked_label("🗑", "Purge contacts…", "err"), value=_PURGE, ), ] + tail += archived super().__init__( f"Contacts · {len(contacts)} known", rows=rows, @@ -183,7 +146,9 @@ async def open_contacts( removes a contact — a purge here, or the detail page's own single-contact ``Remove contact…`` — ends the visit, re-reads the device and starts a fresh one, so the contacts that went are gone from the list. That rebuild is the deliberate exception to - keeping the screen: the rows it was holding a place in no longer exist. + keeping the screen: the rows it was holding a place in no longer exist. A row under the + ``Archived`` section is a rebuilt :class:`~meshterm.core.models.Contact` like any other, + so Enter on one opens the same detail page — where it can be restored to the device. Args: ctx: Shared application context (must be in the interactive menu). @@ -204,7 +169,10 @@ async def open_contacts( if not isinstance(ctx.ui, TuiUi): # pragma: no cover - guarded by the menu-only caller raise RuntimeError("the interactive contacts list is only available in the menu") session = ctx.ui.session - screen = ContactsScreen(self_name, self_key, contacts, prefix_bytes, counts, sort) + screen = ContactsScreen( + self_name, self_key, contacts, prefix_bytes, counts, sort, + archived=archived_rows(ctx, self_key), + ) while True: rebuild = False async with session.stay(screen) as visit: @@ -213,11 +181,12 @@ async def open_contacts( if chosen is CANCEL or chosen is None: # Esc return if chosen == _PURGE: - # The purge picker and its confirm float over the list, which is already - # the backdrop. A purge that removed anything invalidates the contacts - # cache, so the list is re-read and rebuilt — the one deliberate reset in - # this screen's life, because the rows it was keeping a place in are gone. - if await _purge_stale(ctx, self_key): + # The purge ladder, its preview and its confirm all float over the list, + # which is already the backdrop. A sweep that archived anything + # invalidates the contacts cache, so the list is re-read and rebuilt — + # the one deliberate reset in this screen's life, because the rows it was + # keeping a place in are genuinely gone from the device. + if await purge_contacts(ctx, self_key): rebuild = True break continue @@ -232,128 +201,7 @@ async def open_contacts( if not rebuild: return contacts = await ctx.devstate.contacts() - screen = ContactsScreen(self_name, self_key, contacts, prefix_bytes, counts, sort) - - -async def _purge_stale(ctx: "AppContext", self_key: str) -> int: - """Pick an age threshold, confirm, and remove every contact past it. Returns the count removed. - - Shows the age ladder (each rung carrying a live count of the contacts it would sweep, - plus a never-heard bucket), gates the pick behind a typed ``delete`` confirm, then deletes - each victim from the device's contact table and forgets it from the cross-session store so - a forgetful bridge doesn't merge it back. Only the *contact* is dropped — each node's - reception history in MeshTerm stays. Runs over the pushed contacts list as its backdrop. - - The sweep itself runs under the app's progress dialog — one command per victim, so the - bar has a real total to count down — and its outcome lands in a dialog the reader - dismisses, rather than in a note they would only meet on their way off the screen. - - Args: - ctx: Shared application context (interactive menu). - self_key: The device's own public key (hex) — how the contact store scopes this - device's remembered contacts. - - Returns: - How many contacts were removed (``0`` if cancelled or nothing matched). - """ - from .surface import TuiUi - - assert isinstance(ctx.ui, TuiUi) # guaranteed by open_contacts - session = ctx.ui.session - - # Read fresh so the counts match the device right now (own node is never in this list, so - # a purge can't touch it). - contacts = await ctx.devstate.contacts() - - rungs = [(label, secs, stale_past(contacts, secs)) for label, secs in PURGE_RUNGS] - never = never_heard(contacts) - rows = [(label, _count_desc(len(victims)), secs) for label, secs, victims in rungs] - rows.append(("Never heard", _count_desc(len(never)), _NEVER)) - - from .tui import SelectScreen - - items = menu_rows(rows) - picked = await session.run_screen( - SelectScreen( - f"Purge stale contacts — {len(contacts)} known", - items, - prompt="Remove contacts you haven't heard from in the chosen span.", - footer_hint="↑↓ move · Enter select · Esc back", - filterable=False, - wrap=False, + screen = ContactsScreen( + self_name, self_key, contacts, prefix_bytes, counts, sort, + archived=archived_rows(ctx, self_key), ) - ) - if picked is CANCEL or picked is None: - return 0 - - if picked == _NEVER: - victims = never - warning = ( - f"This deletes {_count_desc(len(victims))} you've never heard an advert from, " - "removing them from this device's contact list." - ) - else: - span = next(label for label, secs in PURGE_RUNGS if secs == picked).lower() - victims = stale_past(contacts, int(picked)) - warning = ( - f"This deletes {_count_desc(len(victims))} {span}, removing them from this " - "device's contact list. Their reception history in MeshTerm is kept." - ) - if not victims: - ctx.ui.note("[muted]no contacts that stale — nothing to purge[/muted]") - return 0 - - if not await ctx.ui.typed_confirm(warning, "delete", title="Purge stale contacts"): - return 0 - - device = await ctx.device() - dev_pub = (self_key or "").lower().removeprefix("0x") - store = ctx.contact_store - removed = 0 - failed = 0 - # A companion-local command per contact (no LoRa transmission), so a straight sequential - # sweep — not paced radio traffic. It runs under the app's progress dialog rather than - # the busy overlay (JP, 2026-08-10): the sweep is one command per victim over a link that - # can be slow, so its end is a *count* away and the reader deserves to watch it come - # down. The overlay only ever said "working", and only in the gaps between screens — - # over a pushed list it drew nothing at all, so a hundred-contact purge looked like a - # screen that had simply stopped answering while the arrow keys still moved a cursor - # nothing was being done with. The dialog swallows every key for its whole lifetime, so - # the list underneath holds still until the work is actually finished. - with ctx.ui.progress("Purge stale contacts") as progress: - task = progress.add_task("Purging", total=len(victims)) - for contact in victims: - try: - await device.remove_contact(contact) - except ContactNotOnDeviceError: - # The device has no such contact, so the sweep's work for it is already - # done: this one is listed only because MeshTerm remembers it for the - # device. It still counts as purged — forgetting it below is what makes - # the row go away — and there is nothing here for the reader to fix. - ctx.log.debug("contacts: %s was not on the device; purging ours", contact.name) - except Exception as exc: # noqa: BLE001 - one bad removal shouldn't abort the sweep - failed += 1 - ctx.log.debug("contacts: purge failed for %s: %s", contact.name, exc) - continue - finally: - progress.advance(task) - if store is not None and dev_pub and contact.public_key: - store.forget(dev_pub, contact.public_key) - removed += 1 - # Drop the cached contact list so the rebuilt screen (and the dashboard) re-read the - # device without the swept contacts. - ctx.devstate.invalidate_contacts() - - # The outcome lands in a dialog the reader dismisses, not in a note they would only - # meet on their way out of the screen: they asked for this sweep and waited on its bar, - # so what it did belongs in front of them while the list they purged is still behind it. - if removed and not failed: - outcome = Text(f"✓ purged {_count_desc(removed)}", style="ok") - elif removed: - outcome = Text( - f"purged {_count_desc(removed)}; {failed} could not be removed", style="warn" - ) - else: - outcome = Text("no contacts could be removed", style="err") - await session.message_dialog(outcome, title="Purge stale contacts") - return removed diff --git a/meshterm/ui/node_detail_screen.py b/meshterm/ui/node_detail_screen.py index 399b547..ebcb54a 100644 --- a/meshterm/ui/node_detail_screen.py +++ b/meshterm/ui/node_detail_screen.py @@ -1345,6 +1345,13 @@ async def open_node_detail(ctx: "AppContext", contact: Optional["Contact"]) -> b full_key = key.lower().removeprefix("0x") if len(full_key) == 64 and _is_hex(full_key): info_actions.append(_Action("share", "📱", "", "Share contact — QR / link")) + # An archived contact is off the device but remembered in full (see + # :mod:`~meshterm.ui.purge_screen`), so the page it opens from the Contacts list's + # ``Archived`` section offers the way back rather than the way out. Above the removal, + # because it is the constructive one of the pair. + archived = _is_archived(ctx, contact, self_key) + if archived: + info_actions.append(_Action("restore", "📂", "ok", "Restore to device")) # The page's one destructive action, and so its last row: drop this single contact from # the device's table. Offered only for a contact we can actually address by key — our own # node is no contact, and a node with neither key nor prefix has nothing to delete by. @@ -1414,6 +1421,14 @@ async def open_node_detail(ctx: "AppContext", contact: Optional["Contact"]) -> b await open_timemachine_self(ctx) else: await open_timemachine_node(ctx, node_id, label) + elif action == "restore": + # A restore writes the contact back and ends the visit for the same reason a + # removal does: the page was opened from the Archived section, and the row it + # was opened from is about to stop existing there. + assert contact is not None # the row only exists for a real contact + if await _restore_archived(ctx, contact, self_key, label): + contact_removed = True + break elif action == "remove": # The confirm floats over this page, which is already the backdrop — the # reader confirms against the node they are looking at. A removal ends the @@ -1431,14 +1446,79 @@ async def open_node_detail(ctx: "AppContext", contact: Optional["Contact"]) -> b return contact_removed +def _is_archived( + ctx: "AppContext", contact: "Optional[Contact]", self_key: str +) -> bool: + """Whether this contact was swept off the device and is being kept by MeshTerm. + + Read straight from the contact store rather than passed in, so the page answers for + itself wherever it was opened from — the Contacts list's ``Archived`` section, a map + marker, a route row — instead of only where the caller happened to know. + """ + store = getattr(ctx, "contact_store", None) + dev_pub = (self_key or "").lower().removeprefix("0x") + if store is None or contact is None or not dev_pub or not contact.public_key: + return False + key = contact.public_key.lower().removeprefix("0x") + return any(c.public_key == key for c in store.archived(dev_pub)) + + +async def _restore_archived( + ctx: "AppContext", contact: "Contact", self_key: str, label: str +) -> bool: + """Write an archived contact back onto the device; ``True`` once it is live again. + + The inverse of the Contacts sweep, one contact at a time (see + :mod:`~meshterm.ui.purge_screen`). The device write comes **first** and the store's + archive mark is cleared only once it succeeded — a failed write must never leave a + contact listed as live on a radio that doesn't hold it, which would be a row you cannot + message and cannot restore. + + No confirm: restoring is constructive, reversible by the sweep that archived it, and + costs one contact slot. The dialog is kept for the failures, which are the only part the + reader can't infer from the list coming back with the row in it. + + Args: + ctx: The shared application context (interactive menu; the page is the backdrop). + contact: The archived contact to write back. + self_key: The device's own public key (hex). + label: How the node is named on the page, for the failure notice. + + Returns: + ``True`` if the contact is back on the device, ``False`` if the write was refused. + """ + from .surface import TuiUi + + assert isinstance(ctx.ui, TuiUi) # guaranteed by open_node_detail + session = ctx.ui.session + + device = await ctx.device() + try: + await device.add_contact(contact) + except Exception as exc: # noqa: BLE001 - a refused write is reported, not raised + ctx.log.debug("contacts: restore failed for %s: %s", contact.name, exc) + await session.message_dialog( + Text(f"✗ couldn't restore {label} — {exc}", style="err"), + title="Restore contact", + ) + return False + + dev_pub = (self_key or "").lower().removeprefix("0x") + if ctx.contact_store is not None and dev_pub and contact.public_key: + ctx.contact_store.restore(dev_pub, contact.public_key) + ctx.devstate.invalidate_contacts() + return True + + async def _remove_contact( ctx: "AppContext", contact: "Contact", self_key: str, label: str ) -> bool: """Confirm and drop one contact from the device; ``True`` once it is gone. - The single-contact counterpart to the Contacts list's bulk purge (see - :func:`~meshterm.ui.contacts_screen._purge_stale`), and it removes the contact in the - same two places, because the list a screen sees is the *union* of the two: the device's + The single-contact counterpart to the Contacts list's bulk sweep (see + :func:`~meshterm.ui.purge_screen.purge_contacts`) — but a *deletion* where that one + archives: this is the way to make MeshTerm forget a node entirely, so it removes the + contact in both places, because the list a screen sees is the *union* of the two: the device's own contact table, and the contacts MeshTerm remembers for that device (see :mod:`meshterm.core.contact_store`). Forget only the first and the store merges the contact straight back on the next read, so the deletion would look like a screen that diff --git a/meshterm/ui/purge_screen.py b/meshterm/ui/purge_screen.py new file mode 100644 index 0000000..62220b3 --- /dev/null +++ b/meshterm/ui/purge_screen.py @@ -0,0 +1,520 @@ +"""The Contacts sweep: rank the whole contact table, archive the weakest off the device. + +A companion's contact table is finite and a busy mesh fills it with whatever adverts +arrived — mostly nodes heard once, in passing, four hops out — until there is no room left +to discover anyone new. This is the flow that gets that headroom back, in three steps over +the pushed Contacts list: + +1. **Pick a target**, from a ladder in two sections. *By standing* rungs keep the + strongest share of the table and archive the rest; *long silent* rungs sweep by + last-heard age — the plain, predictable operation a ranking can't express ("everything I + haven't heard in a year"). Both carry the real number of contacts they would archive, + computed from the actual ranking rather than from arithmetic on the table size, because + protected contacts are never victims. +2. **Read the list.** Every contact the sweep would take, weakest first, with its + percentile and the two or three facts that put it there — for the age rungs too, since + knowing how the contacts an age threshold caught actually *rank* is exactly the check + that threshold cannot do for itself. Ending in the Apply/Back pair that + :func:`~meshterm.ui.menus.exit_rows` draws for staged changes, because that is what this + is: a choice with a cost on both sides, not an exit. +3. **Confirm by typing.** The bulk-deletion gate, red like every other. + +**Only the percentile is ever shown.** A raw score means nothing without the distribution +it came from, and would need a legend the moment the weights were ever retuned; a contact's +rank against your other contacts explains itself. See :mod:`~meshterm.core.contact_score` +for the scoring itself, which is pure and lives in core. + +**Archived, not deleted.** The sweep removes each contact from the *device* — freeing the +slot, which is the whole point — and records it in the cross-session store with an archive +stamp (see :meth:`~meshterm.core.contact_store.ContactStore.archive`). Nothing else moves: +the node's reception history, its position on the map, its Time Machine record and its +direct-message transcript are all keyed by node id rather than by a contact row and are +untouched. Because the store keeps the full public key, one write puts a contact back — +which is exactly what the chat screen already offers when a send is rejected for a +recipient the device no longer holds +(:class:`~meshterm.core.connection.ContactNotOnDeviceError`), so an archived contact you +message anyway is restored in passing rather than being a dead end. +""" + +from __future__ import annotations + +import time +from dataclasses import replace +from typing import TYPE_CHECKING, Optional + +from rich.text import Text + +from ..core.connection import ContactNotOnDeviceError +from ..core.contact_score import ( + ScoredContact, + rank_contacts, + sweep_candidates, +) +from ..core.models import Contact +from .menus import Lane, column_header, fit_cells, menu_rows, section_heading +from .theme import name_style +from .tui import Choice, Separator +from .tui.screen import CANCEL + +if TYPE_CHECKING: + from ..context import AppContext + +#: The keep-the-strongest rungs the target picker offers, as a share of the *sweepable* +#: contacts. Percentages rather than absolute counts because the score itself is only ever +#: read as a percentile: a rung and the lane it filters against then speak one language, and +#: the ladder means the same thing on a table of thirty and a table of three hundred without +#: a single value needing to be retuned. Coarse at the aggressive end — the difference +#: between keeping 90% and 75% is a tidy-up, between 50% and 25% a decision. +KEEP_RUNGS: tuple[int, ...] = (90, 75, 60, 50, 25) + +#: The sweep's own tail sentinels, distinct from any :class:`ScoredContact`. +_APPLY = ("apply",) +_BACK = ("back",) + +#: A day in seconds, for the age ladder. +_DAY = 86400 + +#: The last-heard rungs, ``(label, min_age_seconds)``. A contact qualifies when its age is +#: *at least* that long; a never-heard contact is excluded here and swept only by +#: :data:`_NEVER`, so an age rung can't quietly take a contact that simply hasn't adverted +#: yet. The same ladder the age-only purge offered before this flow absorbed it. +AGE_RUNGS: tuple[tuple[str, int], ...] = ( + ("Not heard in 1 week", 7 * _DAY), + ("Not heard in 1 month", 30 * _DAY), + ("Not heard in 3 months", 90 * _DAY), + ("Not heard in 6 months", 180 * _DAY), + ("Not heard in 1 year", 365 * _DAY), +) + +#: The age-rung value meaning the never-heard bucket (contacts with no advert time at all). +_NEVER = -1 + +#: Percentile lane width, plus its gap — three digits and two cells of air. +_PCTL_W = 5 + +#: Name lane width in the preview, plus its gap. Wide enough for the 20-odd bytes a +#: MeshCore advert name runs to, and narrow enough to leave the reasons lane readable at +#: the PicoCalc's 53 columns. +_NAME_W = 22 + + +def _pctl_style(percentile: int) -> str: + """The style a percentile is drawn in — the same quality reading ``snr_style`` gives SNR. + + Three bands rather than a gradient: the heat ramp is spoken for (it colours *ages*, and + a second gradient in a neighbouring lane would read as the same scale), and a percentile + in a purge preview only ever answers one question — is this contact near the bottom? + """ + if percentile >= 66: + return "ok" + if percentile >= 33: + return "warn" + return "err" + + +def _pctl_cell(percentile: int) -> Text: + """One right-aligned percentile lane: the number alone, coloured by band.""" + return Text(f"{percentile:>3} ", style=_pctl_style(percentile)) + + +def _preview_header(width: int) -> str: + """The preview's pinned column header, fitted to the terminal.""" + return column_header( + [ + Lane("PCTL", _PCTL_W), + Lane("NAME", _NAME_W), + Lane(("WHY IT RANKS LOW", "WHY")), + ], + width, + ) + + +def _victim_row(scored: ScoredContact) -> Text: + """One preview line: percentile, the contact's name in its own hue, then why it ranks low. + + The name keeps its key-derived colour like everywhere else in the app — this is a list + of nodes, and a reader picking one out of thirty rows should not have to read it letter + by letter because the screen it is on happens to be about deleting things. + """ + contact = scored.contact + row = _pctl_cell(scored.percentile) + name = contact.name or contact.key_prefix or "?" + # Through ``fit_cells``, so an over-long name ends on an ellipsis that says it was + # shortened — and so the lane is measured in display cells, which is the only measure + # that keeps the column straight once a name carries a wide glyph. + row.append( + fit_cells(name, _NAME_W - 2) + " ", + style=name_style(name, contact.public_key or contact.key_prefix), + ) + row.append(" · ".join(scored.reasons), style="muted") + return row + + +def _rung_desc(archived: int, cutoff: Optional[int]) -> str: + """A rung's description lane: what it archives, and how far up the ranking it reaches. + + The cutoff is the *highest* percentile among the contacts the rung would take — so an + age rung reaching into contacts that rank perfectly well says so on its own row, which + is the thing an age threshold can never tell the reader by itself. + + Phrased as "the weakest *n*%" rather than as an ordinal percentile. Two reasons, and the + second is the one that settled it: the phrase means the same thing to a reader who has + never met a percentile, and — after the label lane — a 53-column console leaves this + lane 27 cells, which "up to the 11th percentile" overran by twenty. A rung whose only + interesting half is clipped away on the platform that needs it most is a rung that + doesn't say anything. + """ + if not archived: + return "nothing to archive" + head = f"{archived} contact{'' if archived == 1 else 's'}" + return head if cutoff is None else f"{head} · weakest {cutoff}%" + + +async def _rank(ctx: "AppContext", contacts: list[Contact]) -> list[ScoredContact]: + """Gather every signal these contacts have and rank them, strongest first. + + Five grouped scans of the history (:meth:` + ~meshterm.persistence.repository.Repository.contact_signals`), one pass over the channel + transcript for name attribution, and the two stores that carry the explicit protections + — the Watchtower's stars and the remembered admin logins. Our own position comes from + the device's self-info, and is simply absent on a device that advertises none, which the + distance term reads as unknown for everybody. + + Args: + ctx: Shared application context. + contacts: The device's contacts (our own node is not among them). + + Returns: + The full ranking, strongest first. + """ + from ..core.contact_score import _node_id + + nodes = [_node_id(c) for c in contacts] + signals = ctx.repo.contact_signals(nodes) + + # Channel attribution is by display name — a channel frame carries no sender key — so a + # name two contacts share attributes to neither of them. Counting it for both would + # award one node's standing to another; counting it for the first would pick by list + # order. Both stay *unattributed*, which the score reads as unknown rather than as + # silence, and the median fill puts them where an average contact sits. + posts = ctx.repo.channel_post_counts() + seen: dict[str, int] = {} + for contact in contacts: + folded = (contact.name or "").strip().casefold() + if folded: + seen[folded] = seen.get(folded, 0) + 1 + + watch = getattr(ctx, "watch_store", None) + admin = getattr(ctx, "admin_store", None) + for contact, node in zip(contacts, nodes): + found = signals.get(node) + if found is None: + continue + folded = (contact.name or "").strip().casefold() + unique = bool(folded) and seen.get(folded) == 1 + signals[node] = replace( + found, + channel_posts=posts.get(folded, 0) if unique else 0, + channel_attributed=unique, + watched=bool(watch is not None and watch.is_watched(node)), + has_admin=bool(admin is not None and admin.get(contact)), + ) + + self_lat = self_lon = None + try: + info = await ctx.devstate.self_info() + lat, lon = info.get("adv_lat"), info.get("adv_lon") + # A device that has never had a position set advertises 0/0, which is a point in the + # Atlantic rather than a location — the same reading the node detail page takes. + if lat and lon: + self_lat, self_lon = float(lat), float(lon) + except Exception as exc: # noqa: BLE001 - an unplaced device just loses one weak term + ctx.log.debug("purge: no self position (%s); distance term stays unknown", exc) + + return rank_contacts(contacts, signals, self_lat=self_lat, self_lon=self_lon) + + +async def purge_contacts(ctx: "AppContext", self_key: str) -> int: + """Run the whole sweep — rank, pick a target, preview, confirm, archive. Returns the count. + + Runs over the pushed Contacts list as its backdrop, so every step floats and Esc walks + back out one frame at a time. Each step is a real step back: Esc from the preview + returns to the ladder with the reader's rung still highlighted, rather than abandoning + the flow and making them start over. + + The ranking is computed **once**, before the ladder is drawn, and reused for every rung + and both routes — it is five scans of the history, and a rung's count would be a lie if + it were measured against a different pass than the preview it opens. + + Args: + ctx: Shared application context (interactive menu). + self_key: The device's own public key (hex) — how the contact store scopes this + device's remembered contacts. + + Returns: + How many contacts were archived (``0`` if cancelled or nothing matched). + """ + from .surface import TuiUi + + assert isinstance(ctx.ui, TuiUi) # guaranteed by the Contacts screen + session = ctx.ui.session + + async with ctx.ui.busy_overlay("Rating contacts"): + contacts = await ctx.devstate.contacts() + ranked = await _rank(ctx, contacts) + + sweepable = [scored for scored in ranked if not scored.protected] + if not sweepable: + ctx.ui.note("[muted]every contact is protected — nothing to sweep[/muted]") + return 0 + + while True: + picked = await session.run_screen(_target_screen(ranked, sweepable)) + if picked is CANCEL or picked is None: + return 0 + victims = victims_for(ranked, sweepable, picked) + if not victims: + ctx.ui.note("[muted]nothing matches that — no contacts to archive[/muted]") + continue + if await _preview(ctx, victims): + return await _sweep(ctx, self_key, victims) + + +def _age_seconds(scored: ScoredContact) -> Optional[float]: + """A scored contact's last-heard age in seconds, or ``None`` if it was never heard.""" + days = scored.signals.heard_age_days + return None if days is None else days * _DAY + + +def victims_for( + ranked: list[ScoredContact], + sweepable: list[ScoredContact], + picked: tuple, +) -> list[ScoredContact]: + """The contacts one rung would archive, weakest first. + + Weakest first on **both** routes, the age ones included: the preview is read top-down, + and a reader who skims only its first screen should be seeing the contacts they are + least likely to want back — not whichever ones the age filter happened to list first. + + Args: + ranked: The full ranking, strongest first. + sweepable: Its unprotected subset, in the same order. + picked: The rung's value — ``("keep", share)`` or ``("age", seconds)``. + + Returns: + The victims, weakest first. + """ + route, value = picked + if route == "keep": + return sweep_candidates(ranked, keep=round(len(sweepable) * int(value) / 100)) + matched = [] + for scored in sweepable: + age = _age_seconds(scored) + if value == _NEVER: + if age is None: + matched.append(scored) + elif age is not None and age >= value: + matched.append(scored) + return list(reversed(matched)) + + +def _target_screen(ranked: list[ScoredContact], sweepable: list[ScoredContact]): + """Build the two-section ladder, every rung carrying its own real archive count. + + Grouped through :func:`~meshterm.ui.menus.section_heading` rather than drawn as two + lists, so the headings pin as the ladder scrolls and the section jumps step by them — + and so the two routes read as two ways of answering one question rather than as two + separate features that happen to share a screen. + """ + from .tui import SelectScreen + + protected = len(ranked) - len(sweepable) + + def rung(label: str, value: tuple) -> tuple: + victims = victims_for(ranked, sweepable, value) + cutoff = max((v.percentile for v in victims), default=None) + return (label, _rung_desc(len(victims), cutoff), value) + + items: list = [section_heading("By standing")] + items += menu_rows( + [rung(f"Keep the strongest {share}%", ("keep", share)) for share in KEEP_RUNGS] + ) + items.append(section_heading("Long silent")) + items += menu_rows( + [rung(label, ("age", secs)) for label, secs in AGE_RUNGS] + + [rung("Never heard at all", ("age", _NEVER))] + ) + held = f" · {protected} protected" if protected else "" + return SelectScreen( + f"Purge contacts — {len(ranked)} known{held}", + items, + prompt=( + "Contacts are ranked on how lately and often you hear them, whether you have " + "messaged, how near they are, and how much they post. The weakest are archived " + "off the device and kept here." + ), + footer_hint="↑↓ move · Enter select · Esc back", + filterable=False, + wrap=False, + ) + + +def _preview_items(victims: list[ScoredContact]) -> list: + """The preview's rows: a pinned column header, one line per victim, then Apply/Back.""" + return [ + Separator(_preview_header, pinned=True), + *(Choice(title=_victim_row(v), value=v) for v in victims), + # The same shape ``exit_rows`` draws, in this flow's own words: Apply has no key of + # its own, so it needs a visible counterpart naming what the other way out costs. + # Not ``exit_rows`` itself — these are not *staged changes* to a set of values, and + # the pair should say what it actually archives. + Separator(" "), + Choice( + title=Text.assemble(("✓ ", "ok"), f"Archive {_count_desc(len(victims))}"), + value=_APPLY, + ), + Choice(title=Text.assemble(("✗ ", "err"), "Back — keep them all"), value=_BACK), + ] + + +def _preview_screen(items: list, count: int): + """The preview screen over already-built rows.""" + from .tui import SelectScreen + + return SelectScreen( + f"Purge contacts — {_count_desc(count)} to archive", + items, + prompt="Archived contacts leave the device but stay here, with their history.", + footer_hint="↑↓ move · type to filter · Enter select · Esc back", + default=_APPLY, + wrap=False, + ) + + +async def _preview(ctx: "AppContext", victims: list[ScoredContact]) -> bool: + """Show exactly who would go, weakest first; return whether the reader committed. + + The audit step, and the reason the sweep is safe to offer at all: archiving several + dozen contacts on a number nobody can check is precisely the operation that deserves to + be looked at once. The list is filterable like any other — a reader who wants to know + whether one particular node is in it should be able to type its name. + """ + items = _preview_items(victims) + while True: + chosen = await ctx.ui.session.run_screen(_preview_screen(items, len(victims))) + if chosen is CANCEL or chosen is None or chosen == _BACK: + return False + if chosen == _APPLY: + return True + # Any other row is a contact: Enter opens its node detail page, so a reader who + # doesn't recognise a name can go and look before archiving it. The preview stays + # pushed underneath, so Esc from the page lands back on the row it was opened from. + from .node_detail_screen import open_node_detail + + await open_node_detail(ctx, chosen.contact) + + +def _count_desc(n: int) -> str: + """``no contacts`` / ``1 contact`` / ``n contacts`` — the sweep's counting phrase.""" + if n == 0: + return "no contacts" + return f"{n} contact{'' if n == 1 else 's'}" + + +async def _sweep( + ctx: "AppContext", self_key: str, victims: list[ScoredContact] +) -> int: + """Confirm, then remove each victim from the device and archive it here. Returns the count. + + The removal is a companion-local command per contact — no LoRa traffic — so it runs + straight through under the progress dialog rather than being paced. The store write + follows each successful removal rather than being batched at the end, so an interrupted + sweep leaves a consistent state: every contact off the device is recorded as archived. + """ + warning = ( + f"This archives {_count_desc(len(victims))}, removing them from this device's " + "contact list to free space for new ones. MeshTerm keeps them — with their " + "reception history and message transcripts — and can put any of them back." + ) + if not await ctx.ui.typed_confirm(warning, "archive", title="Purge contacts"): + return 0 + + device = await ctx.device() + dev_pub = (self_key or "").lower().removeprefix("0x") + store = ctx.contact_store + stamp = int(time.time()) + archived = failed = 0 + with ctx.ui.progress("Purge contacts") as progress: + task = progress.add_task("Archiving", total=len(victims)) + for scored in victims: + contact = scored.contact + try: + await device.remove_contact(contact) + except ContactNotOnDeviceError: + # Already absent from the radio: the sweep's device-side work is done, and + # archiving it here is what makes the row go away. Not a failure. + ctx.log.debug("purge: %s was not on the device; archiving ours", contact.name) + except Exception as exc: # noqa: BLE001 - one bad removal mustn't abort the sweep + failed += 1 + ctx.log.debug("purge: could not remove %s: %s", contact.name, exc) + continue + finally: + progress.advance(task) + if store is not None and dev_pub: + store.archive(dev_pub, contact, when=stamp) + archived += 1 + ctx.devstate.invalidate_contacts() + + if archived and not failed: + outcome = Text(f"✓ archived {_count_desc(archived)}", style="ok") + elif archived: + outcome = Text( + f"archived {_count_desc(archived)}; {failed} could not be removed", style="warn" + ) + else: + outcome = Text("no contacts could be archived", style="err") + await ctx.ui.session.message_dialog(outcome, title="Purge contacts") + return archived + + +def archived_rows(ctx: "AppContext", self_key: str) -> list: + """The Contacts list's ``Archived`` section: the contacts swept off this device. + + Drawn always rather than behind a toggle. Silent archiving is how a reader loses track + of what they archived — and the section is also the only route back: Enter on a row + opens the node's detail page, where ``Restore to device`` puts it back. + + Args: + ctx: Shared application context. + self_key: The device's own public key (hex). + + Returns: + The rows to append after the live contacts, or nothing when none are archived. + """ + store = ctx.contact_store + dev_pub = (self_key or "").lower().removeprefix("0x") + if store is None or not dev_pub: + return [] + archived = store.archived(dev_pub) + if not archived: + return [] + rows: list = [section_heading("Archived")] + for remembered in archived: + contact = remembered.to_contact() + label = Text( + remembered.name, + style=name_style(remembered.name, remembered.public_key), + ) + label.append(f" · archived {_ago(remembered.archived_at)}", style="muted") + rows.append(Choice(title=label, value=contact)) + return rows + + +def _ago(stamp: Optional[int]) -> str: + """How long ago an archive stamp was, in the prose form ``format_ago`` speaks.""" + from .widgets import format_ago + + if not stamp: + return "some time ago" + return format_ago(max(0.0, time.time() - stamp)) diff --git a/tests/test_contact_score.py b/tests/test_contact_score.py new file mode 100644 index 0000000..1c232e2 --- /dev/null +++ b/tests/test_contact_score.py @@ -0,0 +1,335 @@ +"""Tests for rating contacts by how much they are worth a device slot (``core.contact_score``). + +The scoring is pure — no device, no database, no screen — so these exercise the rules the +sweep's safety actually rests on: that an unknown signal is neutral rather than damning, +that an explicit choice outranks the arithmetic, that a newcomer is given time, and that +what a caller reads back is a percentile rather than a raw number. +""" + +from __future__ import annotations + +from meshterm.core.contact_score import ( + PROTECT_ADMIN, + PROTECT_MESSAGED, + PROTECT_UNOBSERVED, + PROTECT_WATCHED, + ContactSignals, + percentile_rank, + protection_for, + rank_contacts, + sweep_candidates, + term_channel, + term_distance, + term_grace, + term_hops, +) +from meshterm.core.models import Contact + +#: A contact whose evidence every test then varies one axis of. +_BASE = dict(heard_age_days=30.0, packets=10, known_days=200.0) + + +def _contact(name: str, *, lat=None, lon=None) -> Contact: # noqa: ANN001 + """A contact with a distinct key (so its hue and its node id differ from its neighbours').""" + byte = f"{(sum(map(ord, name)) % 256):02x}" + return Contact( + name=name, public_key=byte * 32, key_prefix=byte * 6, lat=lat, lon=lon + ) + + +def _rank(*specs) -> list: # noqa: ANN001 + """Rank ``(name, signal-overrides)`` pairs, returning the scored contacts strongest first.""" + contacts = [_contact(name) for name, _ in specs] + signals = {} + for contact, (_, overrides) in zip(contacts, specs): + node = contact.public_key[:12] + signals[node] = ContactSignals(node=node, **{**_BASE, **overrides}) + return rank_contacts(contacts, signals) + + +def _by_name(ranked) -> dict: # noqa: ANN001 + """The ranking keyed by contact name, for asserting on one row at a time.""" + return {scored.contact.name: scored for scored in ranked} + + +def test_an_unknown_signal_scores_neutral_not_zero() -> None: + """A contact that advertises no position lands mid-field on that axis, not at the bottom. + + THE rule the whole sweep's fairness rests on. About half a real mesh advertises no + location at all, plenty of nodes are never overheard as a relayed packet so carry no hop + count, and a channel poster whose name matches no contact can't be attributed. If any of + those resolved to zero, every unmeasurable contact would sink together and the sweep + would be purging by how much metadata a node happens to broadcast. + """ + # Two contacts identical in every measured way; one is simply unplaced and unrouted. + ranked = _by_name( + _rank( + ("Placed", {"hops": 2.0}), + ("Unplaced", {"hops": None}), + # Two more placed contacts so the hop column has a median to fill from. + ("Near", {"hops": 1.0}), + ("Far", {"hops": 3.0}), + ) + ) + # The unmeasured contact sits exactly where the median of the measured ones puts it — + # between the near and the far, not beneath both. + assert ranked["Near"].score > ranked["Unplaced"].score > ranked["Far"].score + # And it is emphatically not at the bottom of the field. + assert ranked["Unplaced"].percentile > 0 + + +def test_a_column_nobody_can_measure_changes_no_ordering() -> None: + """When *no* contact can be scored on an axis, that axis shifts everyone equally. + + The fill collapses to a flat 0.5, which is inert once weighted: it moves every score by + the same amount, so a signal the whole mesh is silent about can never reorder the field. + """ + ranked = _by_name(_rank(("A", {"packets": 40}), ("B", {"packets": 3}))) + # Nobody carries hops, distance or channel attribution here, and the packet counts still + # decide it. + assert ranked["A"].score > ranked["B"].score + + +def test_an_unattributable_channel_name_reads_unknown_not_silent() -> None: + """A contact whose channel posts can't be attributed is unmeasured, not proven quiet. + + A channel frame carries no sender key — only a ``Name: `` prefix — so a name two + contacts share attributes to neither. That has to read as "we don't know", because + reading it as "posted nothing" would demote a node for a property of its *name*. + """ + unattributed = ContactSignals(node="a" * 12, channel_attributed=False, channel_posts=0) + silent = ContactSignals(node="b" * 12, channel_attributed=True, channel_posts=0) + from meshterm.core.contact_score import DEFAULT_WEIGHTS + + assert term_channel(unattributed, DEFAULT_WEIGHTS) is None + assert term_channel(silent, DEFAULT_WEIGHTS) == 0.0 + + +def test_distance_calibrates_against_this_mesh_rather_than_a_constant() -> None: + """The distance midpoint is the population's own median, so it means the same everywhere. + + 50 km is far on a downtown mesh and unremarkable in a valley; a hardcoded threshold + would have to be wrong on one of them. + """ + near = ContactSignals(node="a" * 12, distance_km=5.0) + # On a tight mesh (median 5 km) a 5 km contact is average; on a sparse one (median + # 100 km) the same contact is *close*, and scores higher. + assert term_distance(near, 100.0) > term_distance(near, 5.0) + # Too few located contacts for a median to mean anything: the term goes unknown. + assert term_distance(near, None) is None + + +def test_a_newcomer_is_given_a_fortnight_to_earn_its_keep() -> None: + """The grace bonus lifts a brand-new contact clear of the sweep, then fades to nothing. + + Every other term rewards accumulated evidence, so a node first heard this morning is + arithmetically indistinguishable from one that has been quiet for a year — both have one + advert and no history. + """ + from meshterm.core.contact_score import DEFAULT_WEIGHTS as w + + assert term_grace(ContactSignals(node="a" * 12, known_days=0.0), w) == w.grace + # Half-way through, half the bonus. + assert term_grace(ContactSignals(node="a" * 12, known_days=7.0), w) == w.grace / 2 + # Past the window it is gone, and the contact competes on merit. + assert term_grace(ContactSignals(node="a" * 12, known_days=14.0), w) == 0.0 + assert term_grace(ContactSignals(node="a" * 12, known_days=400.0), w) == 0.0 + + # End to end: a newcomer heard once outranks an equally thin contact known for months. + ranked = _by_name( + _rank( + ("Newcomer", {"packets": 1, "heard_age_days": 0.1, "known_days": 1.0}), + ("Stale", {"packets": 1, "heard_age_days": 0.1, "known_days": 300.0}), + ) + ) + assert ranked["Newcomer"].score > ranked["Stale"].score + + +def test_protections_outrank_the_arithmetic() -> None: + """A star, a sent message, an admin login or an unheard contact is never a candidate. + + A heuristic must not overrule an explicit choice, and it must not punish a contact for + MeshTerm's own ignorance. + """ + assert protection_for(ContactSignals(node="a" * 12, **_BASE, watched=True)) == PROTECT_WATCHED + assert ( + protection_for(ContactSignals(node="a" * 12, **_BASE, dm_outbound=1)) + == PROTECT_MESSAGED + ) + assert protection_for(ContactSignals(node="a" * 12, **_BASE, has_admin=True)) == PROTECT_ADMIN + # No arrival time at all: the contact predates this history (or was added by hand), so + # every evidence term is empty for a reason that says nothing about the node. + assert protection_for(ContactSignals(node="a" * 12)) == PROTECT_UNOBSERVED + # Ordinary evidence, no claims: the score decides. + assert protection_for(ContactSignals(node="a" * 12, **_BASE)) is None + + +def test_inbound_messages_alone_do_not_protect() -> None: + """Being messaged is not choosing to talk — anyone on the mesh can message you.""" + inbound_only = ContactSignals(node="a" * 12, **_BASE, dm_total=20, dm_outbound=0) + assert protection_for(inbound_only) is None + + +def test_a_protected_contact_still_ranks_but_is_never_swept() -> None: + """Protections are excluded from the victims, not from the population the rank is against. + + A percentile that silently dropped them would not be a rank against *your contacts*. + """ + ranked = _rank( + ("Strong", {"packets": 90, "heard_age_days": 0.1}), + ("Starred", {"packets": 1, "heard_age_days": 500.0, "watched": True}), + ("Weak", {"packets": 1, "heard_age_days": 500.0}), + ("Weaker", {"packets": 0, "heard_age_days": 900.0}), + ) + by_name = _by_name(ranked) + assert by_name["Starred"].protected + assert by_name["Starred"].percentile is not None # it is ranked like everyone else + # Keeping one unprotected contact sweeps the other two — never the starred one, however + # badly it scores. + victims = {v.contact.name for v in sweep_candidates(ranked, keep=1)} + assert "Starred" not in victims + assert victims == {"Weak", "Weaker"} + + +def test_a_protection_does_not_consume_a_kept_slot() -> None: + """``keep`` counts unprotected contacts, so starring a node never deepens the next sweep. + + Counting protections against the target would mean a star quietly cost some other + contact its place, which is the opposite of what a star is for. + """ + ranked = _rank( + ("Starred", {"watched": True}), + ("A", {"packets": 50}), + ("B", {"packets": 20}), + ("C", {"packets": 1}), + ) + # Three sweepable contacts, keep two: exactly one goes, and the star is untouched. + victims = sweep_candidates(ranked, keep=2) + assert [v.contact.name for v in victims] == ["C"] + + +def test_victims_come_back_weakest_first() -> None: + """The preview is read top-down, so the first rows are the least likely to be missed.""" + ranked = _rank( + ("Best", {"packets": 90}), + ("Middle", {"packets": 20}), + ("Worst", {"packets": 0, "heard_age_days": 900.0}), + ) + assert [v.contact.name for v in sweep_candidates(ranked, keep=1)] == ["Worst", "Middle"] + + +def test_percentile_is_a_mid_rank_so_a_flat_field_reads_fifty() -> None: + """Ties share their rank rather than all reading 0 or 100 — the standard definition.""" + assert percentile_rank(5.0, [5.0, 5.0, 5.0]) == 50 + assert percentile_rank(9.0, [1.0, 2.0, 9.0]) == 83 + assert percentile_rank(1.0, [1.0, 2.0, 9.0]) == 17 + assert percentile_rank(1.0, []) == 0 + + +def test_direct_correspondence_is_the_heaviest_single_signal() -> None: + """No other lane moves a score as far — a conversation took a decision on both ends. + + Heaviest *single* lane, deliberately not heavier than two strong ones combined: a node + heard constantly and heard often is genuinely worth a slot, and one axis that could + overrule two others outright would be a weighting with a single point of failure. + + Note what this comparison is really about. A contact you have *replied* to is protected + outright (:data:`~meshterm.core.contact_score.PROTECT_MESSAGED`) and never reaches the + arithmetic at all, so the DM term does its work on inbound-only history — someone who + messaged you and got no answer — which is exactly the case where it should count for a + lot but not for everything. + """ + quiet = {"packets": 2, "heard_age_days": 60.0} + ranked = _by_name( + _rank( + ("Correspondent", {**quiet, "dm_total": 30, "dm_age_days": 20.0}), + ("Chatty", {**quiet, "channel_attributed": True, "channel_posts": 100}), + ("Near", {**quiet, "hops": 0.0}), + ("Nobody", quiet), + ) + ) + # Against contacts alike in every other way, the conversation wins by the widest margin. + base = ranked["Nobody"].score + assert ranked["Correspondent"].score - base > ranked["Chatty"].score - base + assert ranked["Correspondent"].score - base > ranked["Near"].score - base + + +def test_no_single_signal_overrules_two_strong_ones() -> None: + """A node heard constantly *and* heard often outranks one lane maxed out on its own. + + The reason the score is a weighted sum with a bounded heaviest term rather than a + ranking with a dominant key: a contact that is genuinely present on the mesh should not + be swept because it never sent a direct message. + """ + ranked = _by_name( + _rank( + ("Present", {"packets": 100, "heard_age_days": 0.1, "dm_total": 0}), + ("Inbox", {"packets": 2, "heard_age_days": 60.0, "dm_total": 30, + "dm_age_days": 20.0}), + ) + ) + assert ranked["Present"].score > ranked["Inbox"].score + + +def test_a_quiet_conversation_keeps_most_of_its_worth() -> None: + """Correspondence ages far more slowly than adverts: it is a relationship, not an event.""" + ranked = _by_name( + _rank( + ("Recent", {"dm_total": 10, "dm_age_days": 1.0}), + ("Lapsed", {"dm_total": 10, "dm_age_days": 120.0}), + ("Never", {"dm_total": 0}), + ) + ) + assert ranked["Recent"].score > ranked["Lapsed"].score + # …but the lapsed conversation is still worth far more than none at all. + gap_to_recent = ranked["Recent"].score - ranked["Lapsed"].score + gap_to_never = ranked["Lapsed"].score - ranked["Never"].score + assert gap_to_never > gap_to_recent + + +def test_fewer_hops_ranks_higher() -> None: + """Topological closeness, hyperbolic: zero-to-one matters, four-to-five barely does.""" + from meshterm.core.contact_score import DEFAULT_WEIGHTS as w + + direct = term_hops(ContactSignals(node="a" * 12, hops=0.0), w) + one = term_hops(ContactSignals(node="a" * 12, hops=1.0), w) + four = term_hops(ContactSignals(node="a" * 12, hops=4.0), w) + five = term_hops(ContactSignals(node="a" * 12, hops=5.0), w) + assert direct == 1.0 + assert direct - one > four - five + + +def test_ranking_an_empty_table_is_empty_not_an_error() -> None: + """A device with no contacts has nothing to rank — the sweep's own guard reads this.""" + assert rank_contacts([], {}) == [] + + +def test_a_contact_with_no_signals_at_all_is_protected() -> None: + """A contact the history has never met is protected rather than swept as worthless.""" + contact = _contact("Inherited") + ranked = rank_contacts([contact], {}) + assert ranked[0].protection == PROTECT_UNOBSERVED + + +def test_reasons_name_the_weakest_lanes_in_plain_words() -> None: + """Each preview row explains itself without the reader having to know the formula.""" + ranked = _rank(("Quiet", {"packets": 3, "heard_age_days": 240.0, "dm_total": 0})) + reasons = ranked[0].reasons + assert "never messaged" in reasons + assert "3 pkts" in reasons + # The age reads in the fewest words that are still true — months, here. + assert any(r.endswith("mo") for r in reasons) + + +def test_a_stronger_contact_never_scores_below_a_weaker_one_on_every_axis() -> None: + """Sanity: dominance is preserved — better everywhere means ranked above.""" + ranked = _by_name( + _rank( + ("Better", {"packets": 50, "heard_age_days": 1.0, "dm_total": 5, + "dm_age_days": 1.0, "hops": 1.0}), + ("Worse", {"packets": 2, "heard_age_days": 300.0, "dm_total": 0, + "hops": 4.0}), + ) + ) + assert ranked["Better"].score > ranked["Worse"].score + assert ranked["Better"].percentile > ranked["Worse"].percentile diff --git a/tests/test_contact_store.py b/tests/test_contact_store.py index 1e67700..42d3eba 100644 --- a/tests/test_contact_store.py +++ b/tests/test_contact_store.py @@ -228,3 +228,82 @@ async def test_devstate_merge_keeps_a_repeater_a_repeater(ctx) -> None: repeater = next(c for c in restored if c.public_key == "ab" * 32) assert repeater.node_type == NODE_TYPE_REPEATER assert not is_direct_messageable(repeater.node_type) + + +def test_an_archived_contact_is_remembered_but_kept_out_of_the_merge(tmp_path) -> None: # noqa: ANN001 + """Archiving frees a device slot without losing the contact — and without undoing itself. + + The sweep's whole shape (see :mod:`meshterm.ui.purge_screen`): the contact is deleted + from the *device*, which is the scarce resource, and kept here in full. The subtlety is + the merge — this store's normal job is to union remembered contacts back into any list + the device isn't reporting, which would put an archived contact straight back and make + the sweep look like it did nothing. + """ + from meshterm.core.models import Contact + + store = ContactStore(tmp_path / "contacts.json") + alice = Contact(name="Alice", public_key="aa" * 32, key_prefix="aa" * 6) + bob = Contact(name="Bob", public_key="bb" * 32, key_prefix="bb" * 6) + store.remember_all(PUB_A, [alice, bob]) + + store.archive(PUB_A, alice, when=1_700_000_000) + + # Remembered in full — the public key that makes a restore possible is still here. + archived = store.archived(PUB_A) + assert [c.name for c in archived] == ["Alice"] + assert archived[0].public_key == "aa" * 32 + assert archived[0].archived_at == 1_700_000_000 + + # …but withheld from the union, so the device's slot really is free. + merged = merge_contacts(store, PUB_A, []) + assert [c.name for c in merged] == ["Bob"] + + # Survives a reload: the mark is persisted, not just held in memory. + reloaded = ContactStore(tmp_path / "contacts.json") + assert [c.name for c in reloaded.archived(PUB_A)] == ["Alice"] + assert [c.name for c in merge_contacts(reloaded, PUB_A, [])] == ["Bob"] + + +def test_restoring_clears_the_mark_and_the_contact_merges_again(tmp_path) -> None: # noqa: ANN001 + """A restore is the exact inverse — the contact rejoins every list it was withheld from.""" + from meshterm.core.models import Contact + + store = ContactStore(tmp_path / "contacts.json") + alice = Contact(name="Alice", public_key="aa" * 32, key_prefix="aa" * 6) + store.archive(PUB_A, alice, when=1_700_000_000) + assert merge_contacts(store, PUB_A, []) == [] + + was = store.restore(PUB_A, "aa" * 32) + assert was is not None and was.name == "Alice" + assert store.archived(PUB_A) == [] + assert [c.name for c in merge_contacts(store, PUB_A, [])] == ["Alice"] + + # Restoring one that isn't archived is a no-op, not an error. + assert store.restore(PUB_A, "aa" * 32) is None + assert store.restore(PUB_A, "ff" * 32) is None + + +def test_archiving_a_contact_the_store_never_saw_still_remembers_it(tmp_path) -> None: # noqa: ANN001 + """The usual case: a firmware radio's contact is live-only until the sweep takes it. + + Archiving upserts first, so the record that makes a restore possible exists precisely + because the sweep created it — there is no earlier read to depend on. + """ + from meshterm.core.models import Contact + + store = ContactStore(tmp_path / "contacts.json") + unseen = Contact(name="Carol", public_key="cc" * 32, key_prefix="cc" * 6, lat=45.5, lon=-73.6) + store.archive(PUB_A, unseen, when=1_700_000_000) + + archived = store.archived(PUB_A) + assert [c.name for c in archived] == ["Carol"] + assert (archived[0].lat, archived[0].lon) == (45.5, -73.6) + + +def test_a_keyless_contact_cannot_be_archived(tmp_path) -> None: # noqa: ANN001 + """Nothing to restore it by, so archiving it would be a silent deletion.""" + from meshterm.core.models import Contact + + store = ContactStore(tmp_path / "contacts.json") + store.archive(PUB_A, Contact(name="Ghost"), when=1_700_000_000) + assert store.archived(PUB_A) == [] diff --git a/tests/test_device_config.py b/tests/test_device_config.py index 05f192a..f06e23a 100644 --- a/tests/test_device_config.py +++ b/tests/test_device_config.py @@ -318,36 +318,50 @@ def test_contacts_screen_lists_contacts_in_the_shared_lanes() -> None: assert resolved == [highlighted, CANCEL] -def test_purge_buckets_split_stale_from_never_heard() -> None: - """``stale_past`` counts heard-but-old contacts; never-heard falls only in its own bucket.""" - from datetime import timedelta +def test_purge_age_rungs_split_stale_from_never_heard() -> None: + """An age rung takes only contacts once heard and since gone quiet; never-heard has its own. - from meshterm.core.models import Contact, utcnow - from meshterm.ui.contacts_screen import _DAY, never_heard, stale_past + The ladder's second section is the plain predictable operation a ranking cannot express, + and its one subtlety is that a contact with no advert time at all must not fall into it: + a freshly added contact that hasn't had time to advert yet reads as infinitely old, and + an age rung that swept it would be deleting nodes for being new. + """ + from meshterm.core.contact_score import ContactSignals, ScoredContact + from meshterm.core.models import Contact + from meshterm.ui.purge_screen import _DAY, _NEVER, victims_for - now = utcnow() - fresh = Contact(name="Fresh", public_key="aa" * 32, last_seen=now - timedelta(hours=1)) - quiet = Contact(name="Quiet", public_key="ee" * 32, last_seen=now - timedelta(days=3)) - old = Contact(name="Old", public_key="bb" * 32, last_seen=now - timedelta(days=45)) - ancient = Contact(name="Ancient", public_key="cc" * 32, last_seen=now - timedelta(days=400)) - unheard = Contact(name="Unheard", public_key="dd" * 32) # no last_seen - contacts = [fresh, quiet, old, ancient, unheard] + def scored(name: str, days, score: float) -> ScoredContact: # noqa: ANN001 + contact = Contact(name=name, public_key=f"{ord(name[0]):02x}" * 32) + return ScoredContact( + contact=contact, + signals=ContactSignals(node="0" * 12, heard_age_days=days), + score=score, + percentile=int(score), + ) - # A day catches everything heard but not heard *today* — the tightest rung the ladder - # offers (JP, 2026-08-10), so a contact three days quiet is swept where the week rung - # would still have kept it. - assert {c.name for c in stale_past(contacts, _DAY)} == {"Quiet", "Old", "Ancient"} - # A week catches the two aged ones but not the fresh — and never the never-heard one. - week = {c.name for c in stale_past(contacts, 7 * _DAY)} - assert week == {"Old", "Ancient"} + # Strongest first, as `rank_contacts` returns them. + ranked = [ + scored("Fresh", 0.04, 90.0), + scored("Quiet", 3.0, 70.0), + scored("Old", 45.0, 50.0), + scored("Ancient", 400.0, 30.0), + scored("Unheard", None, 10.0), + ] + names = lambda picked: [v.contact.name for v in victims_for(ranked, ranked, picked)] # noqa: E731 + + # A week catches the two aged ones — never the fresh, and never the never-heard. + assert set(names(("age", 7 * _DAY))) == {"Old", "Ancient"} # A year catches only the truly ancient. - assert {c.name for c in stale_past(contacts, 365 * _DAY)} == {"Ancient"} + assert names(("age", 365 * _DAY)) == ["Ancient"] # The never-heard bucket is exactly the contact with no advert time. - assert [c.name for c in never_heard(contacts)] == ["Unheard"] + assert names(("age", _NEVER)) == ["Unheard"] + # Weakest first on the age route too, so a reader skimming the preview's first screen + # sees what they are least likely to want back. + assert names(("age", 7 * _DAY)) == ["Ancient", "Old"] async def test_purge_sweeps_under_a_progress_bar_and_reports_in_a_dialog() -> None: - """The purge counts down a real bar, then hands its outcome back in a dialog. + """The sweep counts down a real bar, then hands its outcome back in a dialog. Two things the busy overlay could not do (JP, 2026-08-10). It only ever said "working", and only in the gaps *between* screens — over the pushed contacts list it drew nothing @@ -359,16 +373,16 @@ async def test_purge_sweeps_under_a_progress_bar_and_reports_in_a_dialog() -> No """ import asyncio import logging + from datetime import timedelta from types import SimpleNamespace + from meshterm.core.contact_score import ContactSignals from meshterm.core.models import Contact, utcnow - from meshterm.ui.contacts_screen import _purge_stale + from meshterm.ui.purge_screen import purge_contacts from meshterm.ui.surface import TuiUi from meshterm.ui.tui.progress import ProgressScreen from meshterm.ui.tui.session import TuiSession - from datetime import timedelta - old = utcnow() - timedelta(days=400) victims = [ Contact(name=f"Old{i}", public_key=f"{i:02x}" * 32, key_prefix=f"{i:02x}" * 6, @@ -382,40 +396,73 @@ async def test_purge_sweeps_under_a_progress_bar_and_reports_in_a_dialog() -> No await asyncio.sleep(0) # a real companion command takes a turn of the loop removed_from_device.append(contact.name) + class _Repo: + @staticmethod + def contact_signals(nodes): # noqa: ANN001 + # Long silent, never messaged, heard a handful of times — the shape of exactly + # what the sweep exists to clear out. + return { + node: ContactSignals(node=node, heard_age_days=400.0, packets=2, + known_days=420.0) + for node in nodes + } + + @staticmethod + def channel_post_counts(): + return {} + session = TuiSession() ui = TuiUi(session) ui.typed_confirm = lambda *a, **k: _true() # the red gate is its own tested thing ctx = SimpleNamespace( ui=ui, log=logging.getLogger("test.purge"), + repo=_Repo(), contact_store=None, + watch_store=None, + admin_store=None, devstate=SimpleNamespace( - contacts=lambda: _contacts(victims), invalidate_contacts=lambda: None + contacts=lambda: _contacts(victims), + self_info=lambda: _self_info({}), + invalidate_contacts=lambda: None, ), device=lambda: _device(_Device()), ) - task = asyncio.ensure_future(_purge_stale(ctx, "cc" * 32)) + task = asyncio.ensure_future(purge_contacts(ctx, "cc" * 32)) - # The age ladder: Enter on its first rung (a week) sweeps every one of these. - ladder = await _step_until_screen(session, lambda s: s.title.startswith("Purge stale")) + # Walk past the five standing rungs into the second section and take "not heard in 1 + # year", which catches all three — the standing rungs keep a share, so none of them + # ever takes a whole table. + ladder = await _step_until_screen(session, lambda s: s.title.startswith("Purge contacts")) + for _ in range(9): + ladder.handle("down") ladder.handle("enter") + # The preview lists exactly who would go, and commits on its Apply row (the default). + preview = await _step_until_screen( + session, lambda s: "to archive" in getattr(s, "title", "") + ) + body = _screen_text(preview) + assert "PCTL" in body # the standing lane is a percentile, never a raw score + assert all(v.name in body for v in victims) + preview.handle("enter") + # The sweep now runs under the progress dialog, which is the frontmost screen for its # whole lifetime — so the list underneath cannot be walked while it works. bar = await _step_until_screen(session, lambda s: isinstance(s, ProgressScreen)) - assert bar.title == "Purge stale contacts" + assert bar.title == "Purge contacts" assert bar.render_body(60) # a real bar, with a real total to count down bar.handle("down") # every key is swallowed; nothing underneath moves # …and the count lands in a dialog, not in a note read on the way out. done = await _step_until_screen( - session, lambda s: not isinstance(s, ProgressScreen) and "purged" in _screen_text(s) + session, lambda s: not isinstance(s, ProgressScreen) and "archived" in _screen_text(s) ) - assert "purged 3 contacts" in _screen_text(done) + assert "archived 3 contacts" in _screen_text(done) done.handle("escape") assert await task == 3 - assert removed_from_device == ["Old0", "Old1", "Old2"] + assert sorted(removed_from_device) == ["Old0", "Old1", "Old2"] async def test_removing_one_contact_drops_it_from_the_device_and_the_store() -> None: @@ -612,6 +659,11 @@ async def test_a_contact_the_device_never_held_is_still_removed_here() -> None: assert invalidated == [True] +async def _self_info(info): # noqa: ANN001, ANN201 + """Await to the given self-info dict (the device read the ranking makes).""" + return info + + async def _true() -> bool: return True diff --git a/tests/test_gallery.py b/tests/test_gallery.py index 4bb56ae..0eef7a0 100644 --- a/tests/test_gallery.py +++ b/tests/test_gallery.py @@ -71,7 +71,8 @@ from meshterm.ui.records_screen import RecordDialog from meshterm.ui.remote_cli import RemoteCliScreen from meshterm.ui.timemachine_screen import TimeMachineScreen from meshterm.ui.trace_screen import TraceScreen -from meshterm.ui.tui import Screen, frame +from meshterm.ui.menus import section_heading +from meshterm.ui.tui import Choice, Screen, Separator, frame from meshterm.ui.tx_screen import TxSweepScreen from meshterm.ui.walk_screen import WalkScreen from meshterm.ui.theme import name_style @@ -145,7 +146,59 @@ def _contacts(cols: int, rows: int) -> Screen: Contact(name="Alice", public_key="aa" * 32), Contact(name="A Rather Long Repeater Name For Width", public_key=_HUB_KEY), ] - return ContactsScreen("Homestead", "cc" * 32, contacts, 1, {"aa" * 6: 7}, sort) + # An archived row too: the sweep's section is part of this screen's populated state, + # and its "· archived 3d ago" suffix is the widest thing the tail ever draws. + archived = [ + Separator(" "), + section_heading("Archived"), + Choice(title=Text("hop-9 · archived 3d ago", style="muted"), value=contacts[0]), + ] + return ContactsScreen( + "Homestead", "cc" * 32, contacts, 1, {"aa" * 6: 7}, sort, archived=archived + ) + + +def _purge_scored(name: str, key: str, percentile: int, **signals): # noqa: ANN001, ANN201 + """One ranked contact for the sweep's screens, built through the real dataclasses.""" + from meshterm.core.contact_score import ContactSignals, ScoredContact, _reasons + from meshterm.core.contact_score import DEFAULT_WEIGHTS as w + + sig = ContactSignals(node=key[:12], **signals) + terms = {"dm": 0.0, "recency": 0.1, "volume": 0.2, "channel": 0.5, + "hops": 0.3, "distance": 0.5} + return ScoredContact( + contact=Contact(name=name, public_key=key, key_prefix=key[:12]), + signals=sig, + score=float(percentile), + percentile=percentile, + reasons=_reasons(sig, terms, w), + ) + + +def _purge_victims(): # noqa: ANN201 + """The sweep's victim list — a long name, a deep age, and a never-heard row.""" + return [ + _purge_scored("hop-9", "9a" * 32, 2, heard_age_days=400.0, packets=1, + known_days=420.0, hops=4.0), + _purge_scored("A Rather Long Repeater Name For Width", _HUB_KEY, 7, + heard_age_days=95.0, packets=3, known_days=200.0, + hops=2.0), + _purge_scored("Alice", "aa" * 32, 11, packets=6, known_days=90.0), + ] + + +def _purge_ladder(cols: int, rows: int) -> Screen: + from meshterm.ui.purge_screen import _target_screen + + ranked = _purge_victims() + return _target_screen(ranked, ranked) + + +def _purge_preview(cols: int, rows: int) -> Screen: + from meshterm.ui.purge_screen import _preview_items, _preview_screen + + victims = _purge_victims() + return _preview_screen(_preview_items(victims), len(victims)) def _node_detail_header() -> Text: @@ -416,6 +469,8 @@ def _support_project(cols: int, rows: int) -> Screen: _ENTRIES: list[_Entry] = [ _Entry("dashboard", _dashboard), _Entry("contacts", _contacts), + _Entry("purge_ladder", _purge_ladder), + _Entry("purge_preview", _purge_preview), _Entry("node_detail", _node_detail), _Entry("map", _map), _Entry("chat", _chat),