keyviz

type KeyvizHotKeyEntry struct {
	Key   []byte
	Count uint64
}

type KeyvizHotKeysSnapshot struct {
	RouteID         uint64
	SampledN        uint64    // events the sketch actually saw this window
	DroppedSamples  uint64    // node-global: bounded-queue back-pressure drops
	SkippedLongKeys uint64    // node-global: pre-sample length-cap rejects
	SnapshotAt      time.Time // when the aggregator deep-copied this snapshot
	SampleRate      int       // R at the time of snapshot
	Capacity        int       // m at the time of snapshot
	Entries         []KeyvizHotKeyEntry
}

type MatrixColumn struct {
	At   time.Time
	Rows []MatrixRow
}

type MatrixRow struct {
	RouteID      uint64
	Start, End   []byte
	Aggregate    bool
	MemberRoutes []uint64
	// MemberRoutesTotal is how many distinct route IDs contributed to
	// this row's counters, including ones that exceeded
	// MaxMemberRoutesPerSlot and so are NOT listed in MemberRoutes.
	// Snapshot consumers should treat MemberRoutes as the visible
	// prefix of this list when MemberRoutesTotal > len(MemberRoutes).
	MemberRoutesTotal uint64

	// RaftGroupID + LeaderTerm carry the route's Raft identity at the
	// time the column was flushed. Stamped from the per-group term
	// snapshot SetLeaderTerm publishes (Phase 2-C+ fan-out merge
	// uses (RouteID/BucketID, RaftGroupID, LeaderTerm, columnAt) as
	// the dedupe key). Zero values mean "term not tracked" — emitted
	// when no SetLeaderTerm call has been made for the group yet, or
	// for synthetic virtual-bucket slots that span groups.
	RaftGroupID uint64
	LeaderTerm  uint64

	// SubBucket is this row's sub-range index within its parent route,
	// 0 for the first (or only) sub-bucket. SubBucketCount is how many
	// sub-buckets the route is divided into: 1 for a K==1 / aggregate /
	// degenerate / unbounded-tail slot, > 1 for a genuinely sub-divided
	// route. SubBucketCount is the disambiguator a row's BucketID
	// suffix needs — a K==1 slot's only row and a K>1 slot's bucket-0
	// row both have SubBucket == 0, so the count is what tells them
	// apart (the #subIdx suffix is added only when SubBucketCount > 1).
	// Both are int (bounded 0..MaxKeyBucketsPerRoute); they are
	// keyviz-internal (the proto KeyVizRow has no equivalent), so no
	// fixed-width type is required.
	SubBucket      int
	SubBucketCount int

	Reads      uint64
	Writes     uint64
	ReadBytes  uint64
	WriteBytes uint64
}

type MemSampler struct {
	// contains filtered or unexported fields
}

type MemSamplerOptions struct {
	// Step is the flush interval. The ring buffer's resolution.
	Step time.Duration
	// HistoryColumns caps the ring buffer length. Older columns are
	// dropped on push when the buffer is full.
	HistoryColumns int
	// MaxTrackedRoutes caps the number of routes whose counters are
	// kept individually before coarsening kicks in. RegisterRoute
	// returns false past this cap, the route ID maps into a virtual
	// bucket, and Snapshot reports it with Aggregate=true.
	MaxTrackedRoutes int
	// MaxMemberRoutesPerSlot caps how many distinct RouteIDs a single
	// virtual bucket records in MemberRoutes. Beyond this cap the
	// route still folds into the bucket counters (so traffic is not
	// dropped) but the routeID is not appended — keeping per-column
	// payload size bounded when total routes far exceed
	// MaxTrackedRoutes. Snapshot consumers should treat the list as
	// "first N members" rather than authoritative attribution.
	MaxMemberRoutesPerSlot int
	// KeyBucketsPerRoute (K) is how many order-preserving sub-range
	// buckets each individual route's [Start, End) is divided into for
	// the hot-key heatmap. 1 (the default) disables sub-bucketing and
	// reproduces today's route-granular behaviour exactly. Clamped to
	// [1, MaxKeyBucketsPerRoute] at construction. Virtual aggregate
	// buckets are never sub-divided regardless of this value.
	KeyBucketsPerRoute int
	// HotKeysEnabled opts in to per-route Top-K hot-key tracking that
	// backs the heatmap drill-down (Phase 2-A++; see
	// docs/design/2026_05_28_proposed_keyviz_hot_key_topk.md). When
	// false the hot path adds one early-return branch and nothing else
	// — disabled-case behaviour is byte-identical to today. When true
	// the sampler retains REAL key bytes in memory and exposes them on
	// the admin drill-down API (gated behind admin auth + audit).
	HotKeysEnabled bool
	// HotKeysPerRoute is the Space-Saving sketch capacity m per route
	// (default 64, cap 256 — design §8). Larger m tightens the noise
	// floor (error_bound ≈ N_total / m) at the cost of memory.
	HotKeysPerRoute int
	// HotKeysSampleRate is R: the hot path enqueues 1 in R observes.
	// Default 16, cap 1024. Higher R reduces hot-path cost but raises
	// the probability that a heavy hitter is missed (Chernoff variance
	// over the sampled stream).
	HotKeysSampleRate int
	// HotKeysQueueSize bounds the channel between the hot path and
	// the aggregator goroutine. Defaults 8192, cap 65536. Drops past
	// the queue are counted, not silent (`dropped_samples` →
	// `degraded`).
	HotKeysQueueSize int
	// HotKeysMaxKeyLen caps the key length sampled into the hot-keys
	// sketch. Default 1024 B, cap 4096 B. Longer keys bump the
	// node-global `skipped_long_keys` counter and contribute to the
	// snapshot's `degraded` flag — they are never truncated (truncation
	// would alias different keys).
	HotKeysMaxKeyLen int
	// Now overrides time.Now for tests; nil falls back to time.Now.
	Now func() time.Time
}

type Op uint8

type Sampler interface {
	// Observe records a single request against a route. Op identifies
	// the counter family. The key drives sub-range bucketing (the hot
	// key/sub-range heatmap, see docs/design/2026_05_25_proposed_keyviz_subrange_sampling.md);
	// len(key) and valueLen are summed into the matching *Bytes
	// counter; pass valueLen 0 for read-only ops where the response
	// size is irrelevant. Implementations must no-op (not panic) when
	// invoked on a typed-nil receiver.
	Observe(routeID uint64, key []byte, op Op, valueLen int)
}

type Series uint8