Node "Heard By" card: decide whether to show direct-RF observers (defer)

[dborup]

Why this issue exists

Upstream merged Kpa-clawbot/CoreScope#2057 ("list only observers that heard the node on air"). This issue records the options so we can decide later. Nothing is planned yet.

What we do today

GetNodeHealth and GetBulkHealth (cmd/server/store.go) walk byNode[pubkey], meaning every transmission the node is involved in: as originator, as destination, or as a resolved relay hop. For each transmission they aggregate the representative observation's observer, SNR and RSSI. The "Heard By" card on the node page shows that list with packet count, avg SNR and avg RSSI.

The same observers array feeds:

• the home page, through the My Nodes "Heard by" line (home.js);
• the Analytics "most observers" ranking (analytics.js, via bulk-health);
• the Live node panel (live.js).

Known problem: the SNR and RSSI in a row belong to whichever node last transmitted the copy the observer received, often a repeater, and not to the node the card is about. For a repeater, the list mixes observers that hear it on air with observers that only heard its traffic further downstream.

Options

A. Keep today's behaviour

Pros

• No work, no risk, no conflict with our node-liveness changes (fix(nodes): separate advert timestamps from confirmed relay activity #64) in the same functions.
• The list is "complete": every observer that saw anything involving the node.
• Cheap: one representative observation per transmission, no background job.

Cons

• The SNR and RSSI columns are misleading. They describe the last transmitter, not the node.
• "Heard by" suggests radio range that often isn't there, which matters most for repeater owners judging coverage.
• The card label and the data disagree.

B. Port upstream Kpa-clawbot#2057

Rule: flood routes credit the last path hop; an empty flood path credits the ADVERT originator; the hop must resolve to exactly one relay-capable node; direct routes never credit. The results come from a background recomputer (every 5 min, full pass over all observations under the store read lock) and are published as an atomic snapshot. Observers outside the direct set are reported as relayObserverCount.

Pros

• Signal numbers are attributed to the node that actually transmitted.
• Requests are cheap: reads are O(direct observers) from a snapshot.
• Upstream parity makes future upstream health-card changes easier to take.

Cons

• Zero-hop adverts are dropped. Firmware sends them as ROUTE_TYPE_DIRECT with path_len = 0 (Mesh::sendZeroHop), and the rule excludes every direct route. That is the clearest direct-RF evidence there is. We reported it upstream on fix(node-health): list only observers that heard the node on air Kpa-clawbot/CoreScope#2057; it is unresolved at the time of writing.
• Sparse result. By upstream's own numbers, only 234 of 1,860 nodes get any direct observer, so for most nodes the card becomes an empty list plus a relay count.
• Uniqueness is not proof. The last-hop credit relies on 1-byte prefixes. A hop matching exactly one known node can still belong to an unknown node, or to a node in another region that shares the prefix.
• Semantic change elsewhere. observers changes meaning in home.js, analytics.js and live.js, which upstream did not update or test.
• Cost. One more recomputer holding s.mu.RLock over the whole store (about 63 ms per 3M observations in upstream's benchmark), and data up to 5 min stale.
• Merge conflicts with fix(nodes): separate advert timestamps from confirmed relay activity #64 in GetNodeHealth and GetBulkHealth.

C. Own variant: direct RF from the node's own adverts only

Credit an observer as "heard directly" only for observations of the node's own ADVERT with an empty path, covering both flood adverts with an empty path and zero-hop direct adverts. Show all other observers as a count, without signal numbers.

Pros

• No prefix guessing: the advert carries the pubkey in the clear, and an empty path means the observer heard the node itself. SNR and RSSI are genuinely the node's.
• Can be computed per request without a recomputer, because it only walks observations of the node's own adverts (few per node). No new lock hold over the whole store.
• Covers repeaters well, since they send periodic zero-hop adverts.
• Small, self-contained change, with a lower conflict surface than B.

Cons

• Misses nodes that are heard directly but whose adverts never reach an observer zero-hop, for example companions that rarely advert, or nodes heard only through their traffic.
• Diverges from upstream, so future upstream changes to this card need manual merging.
• Still changes what observers means for home, analytics and live, so those consumers need a deliberate decision (keep the old list under a new field, or relabel).

Suggested decision criteria

• Did upstream fix the zero-hop issue on fix(node-health): list only observers that heard the node on air Kpa-clawbot/CoreScope#2057? If yes, B becomes more attractive.
• Do users (repeater owners) actually use the Heard By SNR/RSSI to judge coverage? If yes, A is actively misleading and C is the smallest honest fix.
• Are we willing to accept a mostly empty card in exchange for accuracy (B), or would we rather have a narrower but reliable signal (C)?

Not in scope

No implementation, staging or upstream work until a decision is made here.

[dborup]

Update 2026-09-23: upstream fixed the zero-hop gap, so option B's biggest flaw is gone.

After we reported it on Kpa-clawbot/CoreScope#2057, the upstream maintainer verified the mechanism against the firmware and a production database, and merged two follow-ups on 2026-09-22:

• Kpa-clawbot/CoreScope#2064 — an ADVERT on ROUTE_TYPE_DIRECT or ROUTE_TYPE_TRANSPORT_DIRECT with an empty path now credits the advertiser. Every other direct case still credits nobody. They also noted a source we had missed: sendSelfAdvertisement with flood=false sends that way too.
• Kpa-clawbot/CoreScope#2063 — the empty state no longer claims the node is out of range. It now reads "No observation proves a direct reception here, which is not the same as being out of range", with a tooltip explaining why the evidence is incomplete.

Their measurements over 7 days, which correct our expectation of the impact:

zero-hop advert observations previously dropped	8,166
distinct nodes evidenced	139
node-observer pairs evidenced	185
pairs not already credited via an empty-path flood advert	52

Of 30 sampled nodes with zero-hop evidence, 29 already had at least one direct observer, because they also flood their adverts. So the fix mostly enriches lists that were already populated; it does not make the sparse card meaningfully denser.

They also sampled 40 repeaters after #2057 merged: 16 showed the "out of range" line while having a non-zero relayObserverCount, i.e. the card contradicting itself two lines apart. That is what #2063 addresses.

Effect on the options above

• B (port upstream): the "zero-hop adverts are dropped" con is resolved, and the misleading empty state is resolved. The remaining cons stand: sparse result for most nodes, uniqueness of a 1-byte prefix is not proof, observers silently changes meaning for home.js/analytics.js/live.js, one more recomputer holding the store read lock, and conflicts with fix(nodes): separate advert timestamps from confirmed relay activity #64. A port would now be three upstream commits, not one.
• C (own advert-only variant): unchanged in substance. Note that upstream's numbers say flood adverts with an empty path already carry most of the evidence (217 pairs vs 52 from zero-hop), which is evidence that an advert-only rule would capture a large share of what B finds, without any prefix guessing.
• A (keep today's behaviour): unchanged.

Still no decision, and nothing is planned.

[dborup]

Follow-up after reviewing upstream Kpa-clawbot#2063 and Kpa-clawbot#2064 against the current fork

The zero-hop and empty-state improvements make option B worth reconsidering, but the upstream implementation still has correctness gaps that should be resolved in our design rather than cherry-picked:

• direct_heard.go classifies every observation using the representative transmission's RouteType. StoreObs does not retain RawHex/per-observation route type. If the same hash is observed on different route types, attribution is still first-ingested-route dependent — the same class of bug already handled in our Same advert seen on flood and zero-hop routes keeps the route of the first inserted observation #89/feat(nodes): separate flood and zero-hop adverts in node details Kpa-clawbot/CoreScope#2085 work.
• relayObserverCount scans only the representative tx.ObserverID instead of all tx.Observations, so it can undercount observers that saw only relayed copies.
• Tooltip/documentation still describes flood-only evidence, even after fix(node-health): credit zero-hop adverts as direct reception Kpa-clawbot/CoreScope#2064 added zero-hop DIRECT and TRANSPORT_DIRECT adverts.

Recommendation: keep this as a decision issue, but re-evaluate option B using per-observation route evidence, preserve the fork's #64 health/liveness semantics, count relay observers from all observations, and update every consumer/tooltip deliberately. Do not port the three upstream commits unchanged.