spec(routing): align path-learning with upstream and document PATH_RETURN delay

Two changes:

1. CORRECTION. The path-learning subsection previously described the
   reference implementation's path-replacement as "replace only if
   the new path's hash size is not smaller and SNR is not materially
   worse" — but upstream's BaseChatMesh::onContactPathRecv() does an
   UNCONDITIONAL replace, with an inline comment flagging hash-size/
   SNR selection as future work. The spec now reflects upstream's
   actual behavior and notes that quality heuristics are an
   implementation extension, not a reference-implementation behavior.
   Likewise, removed the implication that the reference implementation
   has a cached-path TTL — it doesn't.

2. ADDITION. Document PATH_RETURN scheduling delay
   (TXT_ACK_DELAY=200ms default in upstream BaseChatMesh.cpp:9), with
   the rationale of spacing PATH_RETURN, ACK, and reply across
   distinct slots.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(BaseChatMesh.cpp:304-307 unconditional replace; cpp:228, 255
TXT_ACK_DELAY-spaced PATH_RETURN emission).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
swaitsandClaude Opus 4.7 committed 2026-05-12 09:25:50 -06:00
1 parent 3a8918fb0e
commit ac581fccda
1 file changed
+20 -8
+20 -8
View File
@@ -112,14 +112,20 @@ parameters (timeouts, queue sizes, retry counts) are implementation-defined.
`path` field records the hops the packet traversed. The receiving node `path` field records the hops the packet traversed. The receiving node
SHOULD cache the **reversed** path keyed by the peer's source hash and SHOULD cache the **reversed** path keyed by the peer's source hash and
subsequently use that cached path to send direct-routed traffic back. subsequently use that cached path to send direct-routed traffic back.
- When multiple paths are observed for the same peer, implementations SHOULD - When multiple paths are observed for the same peer, the **reference
prefer the higher-quality path. The reference implementation's heuristic is implementation unconditionally replaces** the cached path with the most
to replace the cached path only if the new path's hash size is not smaller recently observed one (`BaseChatMesh::onContactPathRecv()` in
and its SNR is not materially worse than the cached path's SNR. The exact `src/helpers/BaseChatMesh.cpp` — its source comment explicitly flags
threshold is implementation-defined. hash-size or SNR-based selection as future work). Implementations MAY
- Cached paths SHOULD expire after a period of inactivity; they MAY be layer a quality heuristic on top (e.g., prefer larger hash sizes or
refreshed whenever a new packet is observed from the same peer. The better SNR margin) if they store and compare multiple candidate paths,
reference implementation does not persist paths across reboots. but this is not part of the reference behavior and the exact policy is
implementation-defined.
- Cached paths in the reference implementation do **not** expire on a
timer; they live as long as the contact entry, and are overwritten
whenever a fresher path is observed. Implementations MAY add a TTL or
age-based eviction policy as an extension. The reference implementation
does not persist paths across reboots.
#### PATH_RETURN #### PATH_RETURN
@@ -130,6 +136,12 @@ sender learn a direct return path before its first reply, converting
subsequent traffic from flood to direct routing. See subsequent traffic from flood to direct routing. See
`BaseChatMesh::onPeerDataRecv()` and `Mesh::createPathReturn()`. `BaseChatMesh::onPeerDataRecv()` and `Mesh::createPathReturn()`.
The reference implementation schedules the PATH_RETURN transmission with a
small delay (`TXT_ACK_DELAY`, default 200 ms) to avoid colliding with other
packets the receiver is about to emit. Exact timing is
implementation-defined; the goal is to space PATH_RETURN, ACK, and any
application reply across distinct on-air slots.
#### Flood Fallback and Retries #### Flood Fallback and Retries
- A sender SHOULD track outstanding DMs by their expected `ack_crc` - A sender SHOULD track outstanding DMs by their expected `ack_crc`