Pr1.5 tmm nexthop

[NomDeTom]

What's in this PR

1. Flat TMM unified cache + persistent next-hop overflow store
Replaces the cuckoo-hash TrafficManagementModule cache with a flat 1000-entry × 10 B
array (free-running tick model), and adds a next-hop overflow store that retains confirmed
next-hop bytes for nodes aged out of the hot NodeDB. New API: setNextHop,
getNextHopHint, clearNextHop, preloadNextHopsFromNodeDB.

2. NextHop route-recovery mitigations (M1–M3) — docs/nexthop-routing-reliability.md

• M1/M2 — interpretation-side gate. NodeDB::resolveLastByte() resolves a last byte to
  Unique / Ambiguous / None. A stored/learned next_hop is only emitted (and only
  learned from an ACK) when it maps to a single, currently reachable direct neighbor;
  otherwise we flood (managed flooding still delivers). Applies to both the hot-store route
  and the more collision-prone TMM overflow byte.
• M3 — recovery-side decay. A bounded RAM route-health table (32 slots, 30-min TTL,
  3-consecutive-failure threshold) ages out stale/failing routes so they get re-discovered;
  re-learning the same hop keeps the failure count (asymmetric-link safe).
• Net effect: a DM that today silently misroutes or black-holes instead falls back to
  managed flooding and re-learns a fresh route. Sparse-mesh happy paths are unchanged.

3. Warm-store device role + protected category
Caches each evicted node's device role (4 bits) + a protected category (2 bits) in
the low bits of the warm record's last_heard — at zero record-size cost (entry stays
40 B; no RAM/flash growth). The high bits remain a real timestamp quantised to 64 s, which
is ample for warm LRU ordering. NodeDB classifies and stores it at each eviction site;
take() restores the cached role on re-admission; WarmNodeStore::lookupMeta() exposes it
to consumers (e.g. the future hop-trim "protected node" path). Feeds later traffic-management work.

4. Warm-store format migration (v1 → v2)
Both backends (nRF52840 raw-flash ring and warm.dat) bump their magic
(WRNG→WRN2 / WRM1→WRM2). Migration keeps each node's identity + public key and
discards only last_heard (whose low bits would otherwise be misread as the new
role/protected metadata) — it does not drop the warm tier, so PKI keys survive the
upgrade. The ring forces a head-page rotation if the active page is v1, so new v2 records
never land in a v1-headed page; legacy pages convert as the ring rotates.

---

Compatibility / format notes

• No protobuf or LoRa wire-format change. All routing state is RAM-only.
• Warm-store flash format changes (magic bumps) with in-place migration — no data
  loss; identity + public keys are preserved, only last_heard recency is reset and
  re-learned on next contact.
• Tombstone (last_heard == 0xFFFFFFFF) and erased-flash (num) sentinels are unaffected.

🤝 Attestations

• I have tested that my proposed changes behave as described.
• I have tested that my proposed changes do not cause any obvious regressions on the following devices:
  • Heltec (Lora32) V3
  • LilyGo T-Deck
  • LilyGo T-Beam
  • RAK WisBlock 4631
  • Seeed Studio T-1000E tracker card
  • Other (please specify below)

[github-actions]

⚡ Try this PR in the Web Flasher

Note

Building this pull request… the flash button, badges and supported-board
list will appear here automatically once CI finishes.

[Copilot]

Pull request overview

This PR strengthens direct-message NextHop routing reliability on dense meshes by adding ambiguity-aware last-byte resolution in NodeDB, introducing RAM-only route-health decay, and persisting confirmed next-hop hints beyond hot NodeDB eviction via a TrafficManagementModule (TMM) overflow cache. It also extends the warm-node store format to carry device role/protection metadata in-place (no record size growth) with migration support, and adds unit + hardware-bench coverage for the new routing behavior.

Changes:

• Add NodeDB::resolveLastByte() / resolveUniqueLastByte() and wire them into hop-preservation + next-hop learning/emission to avoid last-byte collision misrouting.
• Add NextHop route-health tracking (TTL + failure threshold) and a TMM next-hop overflow cache with preload-from-NodeDB support.
• Extend WarmNodeStore records by packing role/protected metadata into last_heard low bits, including v1→v2 migration and associated tests.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/test_warm_store/test_main.cpp	Updates warm-store unit tests for role/protected metadata packing and adds a v1 warm.dat migration test.
test/test_traffic_management/test_main.cpp	Adjusts TMM tests for congestion-gated hop exhaustion and adds tests for next-hop overflow cache behavior.
test/test_nodedb_blocked/test_main.cpp	Adds coverage ensuring NodeDB eviction carries role/protected metadata into the warm tier.
test/test_nexthop_routing/test_main.cpp	New unit test suite covering last-byte resolution, NextHop emission/learning gates, route-health decay, and hop-limit preservation behavior.
src/modules/TrafficManagementModule.h	Documents and exposes next-hop overflow cache APIs; updates cache entry layout for next_hop; adds epoch rebase API.
src/modules/TrafficManagementModule.cpp	Replaces cuckoo cache with flat scan/eviction, adds epoch rebase logic, and implements next-hop overflow cache + preload.
src/modules/TraceRouteModule.cpp	Mirrors traceroute-derived next-hop into the TMM overflow cache when available.
src/mesh/WarmNodeStore.h	Defines metadata packing helpers (role/protected) in warm records and adds lookupMeta() plus legacy-aware ring header read.
src/mesh/WarmNodeStore.cpp	Bumps warm-store magic and implements v1→v2 migration (discarding last_heard, preserving identity/key) for both backends.
src/mesh/Router.cpp	Switches favorite-router hop-limit preservation to ambiguity-aware resolution (resolveUniqueLastByte).
src/mesh/ReliableRouter.cpp	Records route success on end-to-end ACK receipt to refresh route-health state.
src/mesh/PacketHistory.cpp	Clarifies byte-domain semantics for relayer checks; learning is now collision-gated elsewhere.
src/mesh/NodeDB.h	Adds LastByteResolution, ResolvedNode, and last-byte resolver APIs.
src/mesh/NodeDB.cpp	Installs always-on TMM defaults for never-configured devices, adds warm-tier protected-category classification, and implements last-byte resolution.
src/mesh/NextHopRouter.h	Adds bounded route-health table + helpers and exposes getNextHop for unit tests under PIO_UNIT_TESTING.
src/mesh/NextHopRouter.cpp	Gates learning/emission of next-hop bytes through ambiguity-aware resolution; adds route decay and integrates TMM overflow hints.
src/mesh/MeshTypes.h	Adds NEXTHOP_NEIGHBOR_FRESH_SECS for strict neighbor freshness scoping.
src/mesh/mesh-pb-constants.h	Changes default HAS_TRAFFIC_MANAGEMENT to enabled and sets default cache size when enabled.
src/mesh/Default.h	Adjusts the default position precision bits (24 → 19).
mcp-server/tests/mesh/test_nexthop_multihop_recovery.py	Adds a hardware bench test that self-discovers a true multi-hop topology and validates DM delivery + relay recovery.
docs/nexthop-routing-reliability.md	Adds an in-repo analysis/plan document describing mitigations M1–M4 and verification strategy/status.