modules/measurement-rate-control/hyper-p2p-histogram-gossip/docs/architecture.md

Architecture: hyper-p2p-histogram-gossip

Category: measurement-rate-control
Protocol: histogram-gossip/v1

Purpose

Distributed approximate latency/RTT distributions via gossiped histogram buckets.

Per-metric state

{ min, max, counts: number[], total }

Wire messages

type	fields	behavior
histogram-buckets	metric, min, max, counts, peer, at	_mergeBuckets into local histogram; emit remote-buckets

observe → gossip pipeline

_ensure(metric) → update min/max/counts
→ gossipSend full snapshot counts
→ stats.observed++

Percentile estimation

Walk buckets cumulatively until cumulative count ≥ ceil(p/100 * total); return bucket midpoint.

Composition

• Feed SLI checks from hyper-p2p-sla-budget using percentile thresholds
• Pair with hyper-p2p-percentile-sketch locally for exact small-sample stats

Limits

• Merging unlike bucket counts assumes compatible bucket count length
• Min/max drift widens bins over time