The purge keeps the contacts worth a slot, and archives the rest

A device's contact table is finite, and a busy mesh fills it with whatever
adverts arrived — mostly nodes heard once, in passing, four hops out — until
there is no room left to discover anyone new. The age ladder could only ask
how long ago; it had nothing to say about which of two equally quiet contacts
was the one you would miss.

So contacts are now rated. Six weighted terms, each normalised and summed:
direct correspondence heaviest at 30, then how lately heard (25), how often
(15), channel posting (12), hops (10) and distance (8). Additive rather than
multiplicative, because a product lets one zero annihilate a contact that is
strong everywhere else — a node advertising no position would have scored
nothing however much you talk to it.

The rule the whole thing rests on is that an unknown scores *neutral*. Half a
real mesh advertises no location, plenty of nodes are never overheard as a
relayed frame so carry no hop count, and a channel poster whose name two
contacts share can be attributed to neither — the wire gives a channel frame
no sender key at all. A term that cannot be computed takes the population
median of the contacts that could, so the decision falls to the axes that are
known. Scoring those as zero would have swept by how much metadata a node
happens to broadcast. It is also why the two least reliable terms carry the
two smallest weights, and why distance calibrates against this mesh's own
median spread rather than a constant: 50 km is far downtown and unremarkable
in a valley.

A newcomer gets 25 points decaying to nothing over a fortnight, because every
other term rewards accumulated evidence and a node first heard this morning is
otherwise arithmetically identical to one quiet for a year. Four things are
never candidates at all: a watched node, anyone you have sent a message to, a
repeater whose admin login is stored, and a contact MeshTerm has never heard —
that last one predates this history, and sweeping it would be purging by how
long the app has been running. They still rank, since a percentile that
dropped them would not be a rank against your contacts; they just consume no
kept slot, so starring a node never deepens the next sweep.

Only the percentile is ever displayed. A raw 47.3 means nothing without the
distribution it came from and would need a legend the moment the weights were
retuned.

The victims are archived, not deleted: off the device, which is the scarce
resource, and kept here with a stamp. Everything else was already independent
of the contact row — reception history, map position, transcripts — and the
store keeps the full key, so a restore is one write, which the chat screen
already performs on demand when a send is rejected for an unknown recipient.
merge_contacts learns to withhold them, or the union would put them straight
back and the sweep would look like it did nothing.

The old age ladder survives as the second section of the one picker, because
"everything I haven't heard in a year" is a plain predictable operation a
ranking cannot express. Both routes converge on the same preview — weakest
first, with each row's percentile and the two or three facts that put it
there — so an age rung reaching into contacts that rank perfectly well says so
before the typed confirm rather than after.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-01 00:32:55 -04:00
1 parent 8ac0be0928
commit 99cd616ae5
10 files changed
+2098 -241

No files matched your search

+614
View File
@@ -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]
+118 -1
View File
@@ -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 (``<config_dir>/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
+158 -1
View File
@@ -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(
+49 -201
View File
@@ -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
+83 -3
View File
@@ -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
+520
View File
@@ -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))
+335
View File
@@ -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
+79
View File
@@ -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) == []
+85 -33
View File
@@ -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
+57 -2
View File
@@ -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),