HydraIssues

HydraNeck needs a diagnostics ingest so heads can report path quality
open unclassified Project: hydraneck Parent: #714 Reporter: 15 Sep 2026 19:49

Description

#397 and #402 both say network-quality results are reported to HydraNeck, filterable by district, venue, body, path, tier and transport. HydraNeck has no such endpoint today. Its API is venue-centric: venues, network, scan, bandwidth, wg, torch, log tail. There is nowhere for a head to POST a measurement.

That gap is why the in-head probe (#397, being built now) ships as an on-demand command and local API endpoint first: an operator triggers it and reads the result over the cluster exec channel. That unblocks the venue campaign but leaves the measurement manual.

Wanted

  1. POST /api/v1/diagnostics/network accepting the PLAN 4.6 record verbatim. The record already carries venue, region, path, profile, client, gateway, transport, the percentile blocks, loss, reorder, rx_timestamp and verdict, so no new schema is needed. PLAN 4.9 is explicit that the qualification record and the per-session record are the SAME document, in two contexts.
  2. Storage with a retention policy. This is unbounded continuous telemetry, unlike the finite qualification runs that live in git (hydrahyperscaler docs/DATA-HOME.md explains the split). Follow the hydraneck convention, no new database if the existing store fits.
  3. GET with filters on venue, district, path, tier and time range, so operations can answer "why did streaming feel bad at venue X last Tuesday" with data. That question is the whole motivation in #402.
  4. Auth: heads present the same credential they already use elsewhere; do not invent a new one.

Why it is worth doing

With it, qualifying a region stops being an expedition and becomes a query over telemetry that already exists, and venue network problems become visible continuously instead of being discovered during a campaign. ad6's roughly 10 ms of LAN jitter (#724) had been there for an unknown length of time and was found only because someone went looking.

Dependency: the in-head probe (#397) must emit first. The reporter seam is being left in place deliberately.

Related: #397, #402, #714, #732, #724.