Evaluate advert route-evidence semantics against our existing route_mask implementation (upstream 2088) #218

Deferred evaluation

Compare our existing route-mask implementation with upstream PR 2088, merged on 2026-10-03. We already preserve route evidence. This is a semantic/API gap assessment, not a request to install a second storage mechanism.

Snapshot checked 2026-10-04: our master 8bafcdf2a6bb0014127bce4822c8ad0399bd2f12, upstream master 9e49db9725d6346959c41ec23c66d96b7e43cc4c.

What upstream does / potential benefit

Upstream retains bounded advert route evidence, classifies adverts from that evidence and uses it in advert analytics and node flood counts. Its contract distinguishes flood evidence, direct-with-empty-path evidence, mixed evidence and other/unknown cases. Analytics-evidence write failures are reported without blocking core observation/path/liveness updates.

Potential value for us is more explicit classification, consistency between analytics consumers and resilient ingest behavior—not simply another route-history feature.

What we already have / concrete differences

• Same advert seen on flood and zero-hop routes keeps the route of the first inserted observation #89 was resolved by merged Record every observed route per transmission and show mixed ADVERTs in Relay Airtime Share #93: transmissions.route_mask records observed raw route types, with backfill and a route_mask_changes log to refresh a running server. See route_mask.go.
• Relay Airtime Share already distinguishes mixed adverts. feat(nodes): Recent Adverts split into flood / zero-hop / mixed with per-class counts #97 also added node advert classification, per-class lists and counts.
• Our classifier uses raw route-type bits, with a first-stored-route fallback while evidence is unavailable. That is not automatically equivalent to upstream's empty-path evidence contract; a route-type mask alone does not encode remaining path length.
• feat(nodes): Recent Adverts split into flood / zero-hop / mixed with per-class counts #97 deliberately preserves flood_advert_count_7d as a separate route_type = 1 compatibility contract. Upstream broadens its evidence-based count. Changing ours could affect consumers such as ArcScope; this needs an explicit decision, not an incidental port.
• Our node API uses route_class; upstream supplies advert_kind. Identical-sounding labels are not sufficient evidence of equivalent API semantics.

Risks / boundaries

Do not copy the upstream evidence table or backfill over our existing schema without a demonstrated need. Historical overwritten observations cannot be reconstructed reliably. All database writes must remain ingestor-owned; the server remains read-only. An empty remaining path is not proof of original send mode or RF proximity.

Evaluation checklist

• Build a contract matrix for flood, transport flood, direct empty/non-empty paths, mixed, malformed and missing evidence.
• Compare analytics, node counts, cold/chunked load, live refresh and restart behavior against the same fixtures.
• Compare evidence-write failure handling; decide which updates must remain atomic and which may fail independently.
• Document consumer compatibility and unknown/backfill semantics before proposing any API change.
• Benchmark ingest overhead, memory, backfill and query cost on a realistic database copy if a change is proposed.
• Decide: keep ours, adapt a specific semantic improvement, or pursue a separate compatibility/migration design.

The corresponding node-page presentation assessment is #219 and should remain separate from this backend contract decision. No production migration or backfill is authorized by this issue.