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),