[MeshCore P3] Tier 1 — path_hashes on channel TextMessage observations (heard MVP)

[pskillen]

Parent

Part of #267 — MeshCore Phase 3 traceroute / path parity (passive path track).

MVP tier: Tier 1 from gap analysis — get real #channel traffic showing hash hop chains in Messages → Heard (schematic per feeder). Geographic hop polylines on the map are Tier 2 (hash→node resolution + UI); out of scope here.

Problem (pre-prod confirmed Jun 2026)

TextMessage.original_mc_packet observations for channel_text usually have empty path_hashes even though feeders overhear paths on other frame types.

Source	path on wire?	Uploaded?	Linked to TextMessage?
channel_message → channel_text	Usually no (path_len / path_hash_mode only)	Yes	Yes — empty paths
rx_log_data ADVERT	Often yes	Yes (ADVERT only)	No TextMessage
rx_log_data TEXT_MSG / PATH	Often yes in captures	No (MeshCoreSkipUpload)	—

Precursor work (#369, #360, meshflow-bot#119, meshflow-ui#304, meshflow-ui#311) already exposes heard[] when path_hashes exist — no new UI required for Tier 1.

Detail: packet-path-tracing-outstanding.md § Message path data chain, phase-3-outstanding.md.

Design direction (thin bot / fat server)

Prefer server-led ingest per packet-path-tracing-outstanding.md:

1. Bot (minimal): Upload additional rx_log_data typenames (e.g. TEXT_MSG / PATH) as thin envelopes — pass through path, path_hash_size, path_hash_mode, pkt_hash; no bot-side _path_hashes() duplication or message↔packet correlation.
2. API: Split path hex → path_hashes on ingest when present; correlate PATH/TEXT_MSG observations to the channel_text row / TextMessage.original_mc_packet (by pkt_hash, time window, and/or dedup rules — spike in this ticket).
3. Optional: If path later appears on channel_message JSON from meshcore lib, existing bot forward + API path split should work without new bot logic.

Sample fixtures: docs/meshcore_packets/ (channel_message without path; rx_log_data PATH/ADVERT with path).

Cross-repo work

Repo	Work
meshflow-api	Ingest + correlation design; unit/integration tests; OpenAPI if contract changes
meshflow-bot	Relax rx_log_data upload filter (TEXT_MSG/PATH or raw pass-through); ensure path / path_hash_* forwarded on uploaded envelopes
meshflow-ui	None for Tier 1 (verify heard dialog only)
ops	Deploy precursor + this slice to pre-prod

Branch prefix: api-<N>/… in all repos per meshflow-git-workflow.

Out of scope (Tier 2+)

• Hash→node matcher (#373), proactive resolver (#374)
• heard[] wired to MeshCorePathSegmentResolution (M1)
• Hop polylines on HeardPathGeoMap for MeshCore
• Neo4j export, realtime path WS, M7 topology UI (#309)
• Active MeshCore traceroute

Acceptance criteria

• Design note or ADR section: correlation rules (pkt_hash / time / dedup) and failure modes (orphan PATH rows, duplicate feeders).
• After deploy, a real pre-prod channel TextMessage has heard[].path_hashes with length ≥ 1 for at least one feeder observation tied to original_mc_packet.
• GET /api/messages/text/?protocol=meshcore returns non-empty path_hashes on heard[] for that message (v1 resolved_path may remain all unknown).
• UI: Messages → Heard → per-feeder schematic chain is not “No path recorded” for that traffic.
• Unit tests use fixtures from docs/meshcore_packets/ (channel_text + correlated PATH/TEXT_MSG ingest).
• Bot PR: uploads required rx_log_data types without new path-splitting logic.
• Update phase-3-progress.md when merged.

Verification checklist

1. DB: MeshCorePacketObservation for message’s original_mc_packet_id has non-null path_hashes.
2. API: heard[0].path_hashes non-empty.
3. UI heard dialog: PathHopChain / MeshCoreHeardPathsPanel show hashes.
4. Geo map: feeder markers unchanged; hops still schematic (expected until Tier 2).

References

• Epic #267
• Phase 2 epic #266 (ingest surface)
• M1 subsystem #372 — rollups can use ADVERT paths in parallel; this ticket unblocks message heard

[pskillen]

Related: cross-feeder duplicate TextMessage rows (same on-air ping, two feeders) tracked in #387. Tier 1 path twin-merge works best when ingest collapses to one packet + N observations first; consider sequencing or stacking PRs with #387.