Proposal: opt-in mobile client-RX coverage (crowdsourced RF reach) + /api/nodes/resolve

[efiten]

Summary

I'd like to contribute an opt-in, crowdsourced RF-coverage feature, plus a small node-name lookup endpoint. The whole thing is gated behind one config flag and is disabled by default, so it has zero impact on existing deployments unless an operator turns it on. A clean branch off master is ready (efiten:feat/client-rx-coverage-pr) and I can open a PR — opening this issue first to check the design is welcome, since the feature has a companion-app dependency worth discussing up front.

What it adds

1. Mobile client-RX coverage. A roaming MeshCore companion radio — driven by an open-source Android PWA, corescope-rx (GPLv3) — reports which nodes it heard directly, tagged with the phone's GPS and the packet's SNR/RSSI. CoreScope ingests these into a new client_receptions table and renders:

• per-node hex coverage as an overlay on the existing Reach page, and
• a standalone Coverage dashboard (#/rx-coverage) with a top-mobile-observers leaderboard.

2. GET /api/nodes/resolve?prefix=<hex> — a tiny read-only lookup that resolves a pubkey prefix to {name, pubkey, ambiguous}. The companion app uses it to show friendly node names; it's generally useful and not coverage-specific.

How it works

companion ──BLE 0x88 (snr+rssi+raw)──▶ corescope-rx PWA ──▶ MQTT meshcore/client/{pubkey}/packets
                                                                      │
                                          ingestor (gated) ──▶ client_receptions (GPS + SNR + heard-key)
                                                                      │
              server: pure-Go hex grid ──▶ GeoJSON ──▶ Reach hex overlay + Coverage dashboard

• Direct-only capture: records only what the companion heard itself and directly — a 0-hop advert's pubkey, or path[last] (the last forwarder) for FLOOD routes; a ≥2-byte path-hash is required. Upstream hops are discarded.
• Pure Go, no new deps: hexbins are a pointy-top grid over Web Mercator (cmd/server/hexgrid.go) computed at query time — CGO_ENABLED=0 / modernc.org/sqlite friendly. The frontend draws with the existing Leaflet.
• Trust: the companion pubkey is the identity; an EMQX ACL binds each client to publish only to its own meshcore/client/{pubkey}/packets topic (soft attribution).
• The MQTT payload contract is documented in docs/client-rx-coverage.md.

Opt-in — default OFF

Everything is behind one flag, off by default:

"clientRxCoverage": { "enabled": false }

When disabled (the default): the ingestor writes no client_receptions; the three coverage endpoints return a clean 404; the frontend hides the Coverage nav link, the #/rx-coverage route, and the Reach-page toggle. /api/nodes/resolve is always available (it isn't coverage-specific).

Why opt-in / default-off

A coverage feature only makes sense for operators who want to invite users to run the companion app and contribute GPS-tagged receptions — it's a privacy/storage choice. Default-off means existing deployments are completely unaffected, and there's no crowdsourced GPS data stored unless the operator explicitly enables it.

Status

• Built and running on a fork deployment; this is the clean upstream extraction (no fork-specific analytics/customizations).
• Server + ingestor build and test green (new opt-in gate tests in both: off → no rows / 404, on → works); JS unit + Playwright e2e tests included (the e2e skips when coverage is disabled, so it's CI-safe under the default).

Would you accept a PR for this? Branch is ready and I'll open the PR linked to this issue. Happy to adjust the design (e.g. the data model, the companion-app boundary, or how the routes are documented in the OpenAPI spec).

[Kpa-clawbot]

Severity: P3 — proposal for a brand-new opt-in feature (default OFF, new tables, new endpoints, new companion app dep). Not a bug; design-discussion gate.

Claim: unverifiable as stated — branch efiten:feat/client-rx-coverage-pr not yet a PR; no diff to review. Companion app (efiten/corescope-rx) is GPLv3, external.

Code today: N/A — net-new surfaces:

• client_receptions table (new schema)
• cmd/server/hexgrid.go (new)
• GET /api/nodes/resolve?prefix= (new) — overlaps with existing prefix search; see cmd/server/routes.go prefix search handlers (a11y CI: expand axe route coverage to remaining 7 analytics tabs #1706/Implement strict Content-Security-Policy (long-running, multi-PR project) #1554 context).
• New MQTT topic meshcore/client/{pubkey}/packets (new ACL/contract).
• Frontend: #/rx-coverage route + Reach-page overlay toggle.

Findings:

• (munger): Lollapalooza of dependencies — external companion app, external PWA, new MQTT topic, new schema, new endpoints, new route, new overlay. "Opt-in default-off" is real but the maintenance surface is not opt-in once merged. Each piece is a future support obligation.
• (carmack): The hexbin-at-query-time over Web Mercator is fine for small datasets; needs a benchmark + bound on client_receptions row count before merge (what's the retention story? per-pubkey rate limit on the MQTT topic? EMQX ACL details?).
• (meshcore): Trust model — "companion pubkey is the identity, EMQX ACL binds publish topic" is sound if the broker is operator-controlled. CoreScope deployments without EMQX ACL enforcement get spoof-able GPS. Needs explicit doc that the feature requires ACL-capable broker.

Fix path: N/A — this is a multi-PR umbrella, NOT a bug. Should be:

1. operator decision first: accept the feature in principle? (scope, maintenance, companion-app coupling).
2. If yes: split into ≥3 PRs — (a) /api/nodes/resolve standalone, (b) opt-in schema + ingest + gated endpoints, (c) frontend route + Reach overlay.
3. Spec doc docs/client-rx-coverage.md reviewed BEFORE code PR.

Effort: L (multi-PR, design-coupled).

Dup check: searched "client RX coverage" / "rx-coverage" / "/api/nodes/resolve" — none. #1268 (enrich nodes with map.meshcore.io RF params) is adjacent (RF enrichment) but server-side / non-crowdsourced. #1566 (visualize route patterns) is map-overlay-adjacent.

Triage verdict: needs-operator-input — operator must decide accept/reject before any worker spawns. If accepted: requires spec doc PR first, then split impl across ≥3 PRs.