feat(nodes): estimated advert intervals (flood / zero-hop) per node, then mesh-wide settings analytics

[dborup]

Goal

Show each node's estimated advert intervals (flood and zero-hop) on the node detail page. Later, analyse the distribution across the mesh, i.e. which settings nodes run with.

Motivation: a repeater operator could see from CoreScope that a node sends flood adverts about every 47 h and no zero-hop adverts (the zero-hop interval was set to 0). After changing the setting, the effect should be visible on the node page.

Background

• Every ADVERT carries the sender's own timestamp, and node detail already classifies adverts by route (include=advertRoutes: recentAdvertsByRoute, advertCounts, from [feat] node detail, separate flood-adv from zero-hop adv Kpa-clawbot/CoreScope#2073 / route_mask).
• Firmware sends flood adverts on one interval (hours) and zero-hop ("local") adverts on another (minutes), and either can be off. The exact setting names, units, allowed ranges and defaults must be taken from the MeshCore firmware source (src/, docs/cli_commands.md), not guessed (AGENTS.md).
• A zero-hop advert is only recorded if an observer hears it directly, so "no zero-hop adverts observed" can also mean "no observer in direct range". The UI must word it that way.

M1: estimate per node, shown in node detail

Estimator (pure, unit-tested):

• Work per route class (flood, zero-hop) over the node's distinct adverts (deduplicated by content hash) inside retention.
• Prefer the advert's own sender timestamp. Fall back to first-seen when the sender clock is clearly wrong (in the future, or not monotonic).
• Be robust:
  • use the median of the gaps;
  • treat gaps that are about an integer multiple of the interval as missed adverts;
  • drop gaps far shorter than the interval (manual adverts, reboots);
  • require a minimum number of samples.
• Snap the result to the nearest value the firmware allows, if the firmware has discrete steps.
• Output per class: interval_s, samples, confidence (high / medium / low / none), and last_advert.

API:

• A new field advertIntervals on GET /api/nodes/{pubkey}, ideally under the existing include=advertRoutes opt-in so other callers do not pay for it.
• Use a named Go struct, with no new map[string]interface{}.
• Document it in openapi.go and docs/api-spec.md.

UI:

• In the node detail advert section, e.g. "Estimated flood interval ≈ 47 h (14 adverts, high confidence)".
• When no zero-hop adverts were observed, show "Zero-hop: none observed (off, or no observer in direct range)".
• No hardcoded colours, and all text escaped.

Perf: O(adverts of this node) per request, with no store-wide scan in the request path.

M2 (later, separate PR): analytics across nodes

An analytics view showing:

• the distribution of flood and zero-hop intervals by role and region;
• how many nodes have zero-hop off or not observed;
• outliers, i.e. very frequent adverts.

It is computed once per analytics cache cycle, not per request. It is only started after M1 has run on staging for a while.

Later (rule 8)

Expose the confidence thresholds and the minimum samples in the customizer.

Acceptance (M1)

• Unit tests for the estimator:
  • a regular series;
  • missed adverts (2× and 3× gaps);
  • manual or extra adverts;
  • sender-clock jumps or a wrong clock;
  • too few samples;
  • zero-hop absent.
• Snapping matches the firmware's allowed values, cited from the firmware source.
• The node detail shows both classes, and an E2E checks the rendering against a seeded node with known advert gaps.
• The API is documented. cmd/server stays read-only.

[dborup-agent]

Plan — CS-pve-agent3 #245 M1

Scope: M1 only (per-node estimate on node detail). M2 analytics is not part of this PR.

Firmware findings (MeshCore firmware/ @ a366955)

	Flood	Zero-hop ("local")
CLI setting	flood.advert.interval	advert.interval
Pref field	flood_advert_interval (uint8, hours), src/helpers/CommonCLI.h:34	advert_interval (uint8, minutes / 2), src/helpers/CommonCLI.h:33
Allowed values	0 = off, else 3–168 whole hours (src/helpers/CommonCLI.cpp:486-495: Error: interval range is 3-168 hours)	0 = off, else 60–240 minutes, stored as mins / 2, so effectively even minutes (src/helpers/CommonCLI.cpp:496-505, MIN_LOCAL_ADVERT_INTERVAL 60 at :160; docs/cli_commands.md:661-668 "rounded down to the nearest multiple of 2")
Default (code)	47 h for repeater and room server (examples/simple_repeater/MyMesh.cpp:904, examples/simple_room_server/MyMesh.cpp:662); 0 (off) for sensor (examples/simple_sensor/SensorMesh.cpp:727). docs/cli_commands.md:657 and docs/faq.md:209 still say 12 h, which is stale against the code.	2 min (advert_interval = 1) "for NEW installs" (examples/simple_repeater/MyMesh.cpp:903). The first savePrefs() turns anything below 60 min off (src/helpers/CommonCLI.cpp:162-165). So the allowed set is {2 min (untouched new install)} ∪ {60, 62, …, 240 min}.
Companions	Do not advertise on a timer; adverts are manual only (docs/faq.md:209; the prefs are commented out in examples/companion_radio/NodePrefs.h:127-128).	same

Timer behaviour that affects the estimator (examples/simple_repeater/MyMesh.cpp):

• :1044-1058: both timers use futureMillis(interval) from the moment they are (re)armed, so the series is regular apart from loop latency.
• :1294-1306: when the flood advert fires, the zero-hop timer is re-armed too ("so they don't overlap"). The zero-hop gap across a flood advert is therefore irregular, between Z and 2Z.
• examples/simple_repeater/main.cpp:119: a zero-hop advert at boot (ENABLE_ADVERT_ON_BOOT). A reboot also restarts both timers.
• src/helpers/CommonCLI.cpp:191-198: the manual advert (flood) and advert.zerohop commands send an extra advert without re-arming the timer. An extra advert splits one regular gap into two short ones.
• src/Mesh.cpp:418: the advert's timestamp is the sender's RTC (_rtc->getCurrentTime()). clkreboot (CommonCLI.cpp:187-190) and RTC-less boards make that clock jump or start in 2024.

Estimator (pure Go function, cmd/server/advert_intervals.go)

Input per class: (sender_ts, first_seen) of the node's distinct adverts, using the same newest 20 per class that the Flood / Zero-hop panels list. transmissions.hash is UNIQUE, so the rows are already deduplicated by content hash. Mixed and unknown adverts are not used, because their class is ambiguous.

1. Sort the adverts by first_seen.
2. For each consecutive pair, compute the gap.
   • Use the sender gap when both sender timestamps are plausible. A timestamp is not plausible when it is missing, or when it is ahead of first_seen by more than 10 min.
   • Otherwise use the first_seen gap. This also applies when the sender gap is ≤ 0 (not monotonic), or when it disagrees with the first_seen gap by more than max(10 min, 10 %), as with a clock jump.
3. Return confidence: none and no interval when there are fewer than 3 adverts (2 gaps).
4. Set T to the median of the gaps. Then refine it up to 3 times.
   • A gap that fits k·T (k = 1..4, |gap − k·T| ≤ 10 % of T) counts as k − 1 missed adverts and contributes gap / k.
   • Shorter gaps and gaps between multiples (manual or extra adverts, reboots, a zero-hop timer re-armed by a flood advert) are dropped.
   • The new T is the median of the contributions.
5. Check for a sub-multiple. If the gaps cluster at T/2, T/3 or T/4 (at least 2 gaps and ≥ 25 % of them), most adverts were missed, and T is replaced by that value.
6. Snap T to the firmware values, but only when it lies within 10 % of the allowed range:
   • flood: the nearest whole hour, clamped to 3–168 h;
   • zero-hop: 2 min, or the nearest even minute, clamped to 60–240.
   • Otherwise interval_s stays the unsnapped value and snapped: false.
7. Set the confidence from the gaps that fit a multiple of T:
   • high: ≥ 6 fitting gaps and ≥ 75 % of all gaps fit;
   • medium: ≥ 3 fitting gaps and ≥ 50 % fit;
   • low: anything less;
   • none: fewer than 2 fitting gaps.

The thresholds stay hardcoded for now. Rule 8: the minimum samples and the confidence thresholds should later be exposed in the customizer, as the issue's "Later" section says.

Data source and performance

• The estimate is under the existing include=advertRoutes opt-in. It is computed once per breakdown scan from the per-class rows GetNodeAdvertRoutes already fetches (recentAdvertsByRoute, [feat] node detail, separate flood-adv from zero-hop adv Kpa-clawbot/CoreScope#2073 route_mask classification), and is cached in the same per-node entry (nodeAdvertRouteCache, 30 s TTL).
• There is no extra query and no store-wide scan. The cost is O(40 rows) of JSON timestamp parsing on top of the existing O(the node's adverts) scan.
• cmd/server stays read-only.

API

advertIntervals on GET /api/nodes/{pubkey}?include=advertRoutes. It is absent without the opt-in, and absent for hidden identities, like advertCounts.

"advertIntervals": {
  "window": 20,
  "flood":    {"interval_s": 43200, "raw_interval_s": 43195, "snapped": true, "samples": 10, "gaps_used": 7, "confidence": "high", "last_advert": "2026-…Z"},
  "zero_hop": {"interval_s": null, "raw_interval_s": null, "snapped": false, "samples": 0, "gaps_used": 0, "confidence": "none", "last_advert": null}
}

The response uses named structs (NodeAdvertIntervals, AdvertIntervalEstimate), with no new map[string]interface{}. The schemas are documented in openapi.go, which TestOpenAPI_NodeAdvertRouteSchemas checks for field completeness, and in docs/api-spec.md ("Advert route classes" section).

UI

The text goes in node detail → Recent Adverts, under the 24h / 7d counts. It is also shown in the side pane, which uses the same NodeAdverts.render.

• Estimated flood interval ≈ 12 h (10 adverts, high confidence)
• Estimated zero-hop interval ≈ 120 min (6 adverts, medium confidence)
• Estimated zero-hop interval: none observed (off, or no observer in direct range)
• … : not enough adverts (2), and … : irregular (N adverts) when no stable interval fits.
• The flood value is in hours and the zero-hop value in minutes, matching the CLI units. A tooltip explains the method.
• The text is plain and fully escaped, and the CSS uses variables only (no colours).

Tests and mutants

• Go unit tests for the estimator:
  • a regular series;
  • 2× and 3× gaps;
  • manual or extra adverts;
  • a sender clock that jumps back (clkreboot), jumps forward, is ahead of first_seen, or is wrong by a steady offset (the sender clock is still used);
  • too few samples;
  • zero-hop absent;
  • mostly missed adverts (the sub-multiple check);
  • snapping tables for both classes, with firmware citations in the test comments.
• Go handler test:
  • the field is present with the opt-in, with flood estimated from flood rows and zero-hop from zero-hop rows;
  • the field is absent without the opt-in and for hidden identities;
  • the OpenAPI check is extended.
• Frontend unit tests in test-node-adverts.js: the rendered text for every state, and escaping.
• E2E: test-issue-245-advert-intervals-e2e.js runs against the new test-fixtures/seed-245-advert-intervals.sql. CI applies the seed after the migration, like seed-2073 and seed-199. The seed has two nodes:
  • a 12 h flood series with a 2× gap, a 3× gap and a manual advert, plus a 120 min zero-hop series;
  • a flood-only node whose sender clock jumps, where zero-hop shows "none observed".
• Mutants (each must turn a test red):
  • median → mean;
  • multiples not handled (k = 1 only);
  • wrong snapping (whole minutes or no clamp);
  • flood and zero-hop swapped;
  • the sender-clock fallback removed.
• Browser validation: a local Go server on the migrated and seeded e2e-fixture.db, with a screenshot of node detail.

[dborup]

M1 (per-node estimate on node detail) is merged via #247 as ae126374. M2 (mesh-wide analytics) is still open. Its notes include F7/N4 from the #247 reviews: flood re-arming the zero-hop timer.