keyviz: label sub-ranges in the SPA and document the K tradeoff

docs/design/2026_05_25_implemented_keyviz_subrange_sampling.md

@@ -402,10 +402,13 @@ gains a sub-range discriminator keyed on `SubBucketCount` (§4.3):
 
 The SPA heatmap renders rows by `Start`/`End` and already supports an
 arbitrary number of rows under the row budget, so **no structural SPA
-change is required** to see hot sub-ranges. Two small polish items
-(optional, can be a follow-up PR): the `RowDetail` panel labels a
-sub-row with its narrowed range, and tooltips show "route N · sub-range
-i/K". The fan-out wire fields (`conflicts[]`, `raft_group_ids[]`,
+change is required** to see hot sub-ranges. Two small polish items, **now implemented**: the `RowDetail` panel
+labels a sub-row with `sub-range i/K` and renames its Start/End rows to
+`Sub-range start`/`Sub-range end` so the narrowed bounds are not read as
+the whole route's, with a tooltip explaining the split. The wire carries
+`sub_bucket` / `sub_bucket_count` for this, both omitted unless the
+route is genuinely sub-divided so the payload is byte-identical at the
+`K=1` default. The fan-out wire fields (`conflicts[]`, `raft_group_ids[]`,
 `leader_terms[]`) are unaffected — they are per-column and travel on
 each sub-row unchanged.
 
@@ -453,7 +456,8 @@ of 1024). Two consequences to document for operators:
 - The per-request `rows` budget (`keyVizRowBudgetCap`, 1024) now buys
   roughly `budget / active_subbuckets_per_route` *routes* shown at full
   resolution — i.e. raising `K` trades route breadth for intra-route
-  depth at a fixed payload size. The doc/flag help text should say so.
+  depth at a fixed payload size. **The `--keyvizKeyBucketsPerRoute` help
+  text now states this.**
 - The intermediate 160k-row materialisation is bounded and transient
   (one column build), but if it proves heavy, `Flush` can apply a
   cheap per-slot top-sub-bucket cap before the global budget. Noted as

internal/admin/keyviz_handler.go

@@ -103,6 +103,17 @@ type KeyVizRow struct {
 	// merged row) so omitempty keeps it off the wire; otherwise
 	// len == len(Values). Conflict is the OR of this slice.
 	Conflicts []bool `json:"conflicts,omitempty"`
+	// SubBucket / SubBucketCount expose the order-preserving sub-range
+	// position within a route, so the SPA can label a sub-row as
+	// "sub-range i/K" instead of leaving the operator to parse the
+	// "#i" suffix out of BucketID.
+	//
+	// Both are omitted unless the route is genuinely sub-divided
+	// (SubBucketCount > 1), matching bucketIDFor: at the K=1 default,
+	// for aggregate rows, and for degenerate slots the wire is byte
+	// -identical to before, so an older SPA sees no change.
+	SubBucket      int `json:"sub_bucket,omitempty"`
+	SubBucketCount int `json:"sub_bucket_count,omitempty"`
 	// RaftGroupIDs[j] and LeaderTerms[j] carry the route's Raft
 	// identity at the time column j was flushed (parallel to
 	// Values[]). Phase 2-C+ fan-out uses
@@ -409,6 +420,8 @@ func newKeyVizRowFrom(mr keyviz.MatrixRow, numCols int) *KeyVizRow {
 	}
 	row := &KeyVizRow{
 		BucketID:          bucketIDFor(mr),
+		SubBucket:         subBucketIndexFor(mr),
+		SubBucketCount:    subBucketCountFor(mr),
 		Label:             string(mr.Label),
 		Start:             append([]byte(nil), mr.Start...),
 		End:               append([]byte(nil), mr.End...),
@@ -428,6 +441,28 @@ func newKeyVizRowFrom(mr keyviz.MatrixRow, numCols int) *KeyVizRow {
 	return row
 }
 
+// subBucketIndexFor and subBucketCountFor mirror bucketIDFor's
+// "genuinely sub-divided" test, so the two cannot disagree about
+// whether a row is a sub-range: a bucket_id carrying "#i" always has
+// the matching fields, and one without always omits them.
+func subBucketIndexFor(mr keyviz.MatrixRow) int {
+	if !isSubDividedRow(mr) {
+		return 0
+	}
+	return mr.SubBucket
+}
+
+func subBucketCountFor(mr keyviz.MatrixRow) int {
+	if !isSubDividedRow(mr) {
+		return 0
+	}
+	return mr.SubBucketCount
+}
+
+func isSubDividedRow(mr keyviz.MatrixRow) bool {
+	return !mr.Aggregate && mr.SubBucketCount > 1
+}
+
 func bucketIDFor(mr keyviz.MatrixRow) string {
 	if mr.Aggregate {
 		return "virtual:" + strconv.FormatUint(mr.RouteID, 10)

internal/admin/keyviz_subbucket_test.go

@@ -0,0 +1,67 @@
+package admin
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/bootjp/elastickv/keyviz"
+	"github.com/stretchr/testify/require"
+)
+
+// TestSubBucketFieldsStayOffTheWireUnlessSubDivided pins that the new
+// fields are inert at the K=1 default. The keyviz response is consumed
+// by an SPA that ships separately from the server, so a field that
+// appeared on every row would change the payload for every existing
+// deployment that never enabled sub-bucketing.
+func TestSubBucketFieldsStayOffTheWireUnlessSubDivided(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		row  keyviz.MatrixRow
+	}{
+		{name: "K=1 route", row: keyviz.MatrixRow{RouteID: 7, SubBucketCount: 1}},
+		{name: "unset count", row: keyviz.MatrixRow{RouteID: 7}},
+		{name: "aggregate row", row: keyviz.MatrixRow{RouteID: 7, Aggregate: true, SubBucketCount: 4, SubBucket: 2}},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			encoded, err := json.Marshal(KeyVizRow{
+				BucketID:       bucketIDFor(tc.row),
+				SubBucket:      subBucketIndexFor(tc.row),
+				SubBucketCount: subBucketCountFor(tc.row),
+			})
+			require.NoError(t, err)
+			require.NotContains(t, string(encoded), "sub_bucket",
+				"the sub-range fields must not appear for a non-sub-divided row")
+		})
+	}
+}
+
+// TestSubBucketFieldsAgreeWithTheBucketID pins that the fields and the
+// "#i" suffix cannot disagree about whether a row is a sub-range —
+// they share one predicate, so an SPA can trust either.
+func TestSubBucketFieldsAgreeWithTheBucketID(t *testing.T) {
+	t.Parallel()
+
+	subdivided := keyviz.MatrixRow{RouteID: 42, SubBucket: 3, SubBucketCount: 8}
+	require.Equal(t, "route:42#3", bucketIDFor(subdivided))
+	require.Equal(t, 3, subBucketIndexFor(subdivided))
+	require.Equal(t, 8, subBucketCountFor(subdivided))
+
+	encoded, err := json.Marshal(KeyVizRow{
+		BucketID:       bucketIDFor(subdivided),
+		SubBucket:      subBucketIndexFor(subdivided),
+		SubBucketCount: subBucketCountFor(subdivided),
+	})
+	require.NoError(t, err)
+	require.Contains(t, string(encoded), `"sub_bucket_count":8`)
+
+	// Bucket zero of a subdivided route: the index is legitimately 0,
+	// so only the count keeps it on the wire — which is why the count
+	// is what the SPA must test, not the index.
+	first := keyviz.MatrixRow{RouteID: 42, SubBucket: 0, SubBucketCount: 8}
+	require.Equal(t, "route:42#0", bucketIDFor(first))
+	require.Equal(t, 8, subBucketCountFor(first))
+}

main.go

@@ -257,7 +257,7 @@ var (
 	keyvizMaxTrackedRoutes       = flag.Int("keyvizMaxTrackedRoutes", keyviz.DefaultMaxTrackedRoutes, "Maximum routes tracked individually before excess routes coarsen into virtual buckets")
 	keyvizMaxMemberRoutesPerSlot = flag.Int("keyvizMaxMemberRoutesPerSlot", keyviz.DefaultMaxMemberRoutesPerSlot, "Maximum members listed on a virtual bucket; excess routes still drive the bucket counters")
 	keyvizHistoryColumns         = flag.Int("keyvizHistoryColumns", keyviz.DefaultHistoryColumns, "Maximum matrix columns retained in the keyviz ring buffer (each column = one Step)")
-	keyvizKeyBucketsPerRoute     = flag.Int("keyvizKeyBucketsPerRoute", keyviz.DefaultKeyBucketsPerRoute, "Order-preserving sub-range buckets per individual route for the hot-key heatmap; 1 disables sub-bucketing (route-granular, today's behaviour). Capped at 256; memory is ~K*32 bytes/route, so K_max ~= memBudget/(32*keyvizMaxTrackedRoutes)")
+	keyvizKeyBucketsPerRoute     = flag.Int("keyvizKeyBucketsPerRoute", keyviz.DefaultKeyBucketsPerRoute, "Order-preserving sub-range buckets per individual route for the hot-key heatmap; 1 disables sub-bucketing (route-granular, today's behaviour). Raising K trades route BREADTH for intra-route DEPTH at a fixed payload size: each route emits up to K sub-rows that compete for the same row budget, so fewer distinct routes fit in one response. Capped at 256; memory is ~K*32 bytes/route, so K_max ~= memBudget/(32*keyvizMaxTrackedRoutes)")
 	keyvizLabelsEnabled          = flag.Bool("keyvizLabelsEnabled", false, "Enable per-adapter KeyViz row labels. Default false keeps legacy route-only rows during rolling upgrades")
 
 	// Hot-key drill-down (Phase 2-A++; design 2026_05_28_implemented_keyviz_hot_key_topk).

web/admin/src/api/client.ts

@@ -349,6 +349,12 @@ export interface KeyVizRow {
   route_ids?: number[];
   route_ids_truncated?: boolean;
   route_count: number;
+  // Present only when the route is genuinely sub-divided
+  // (sub_bucket_count > 1). Test sub_bucket_count, never sub_bucket:
+  // bucket zero of a sub-divided route legitimately has index 0 and
+  // is omitted from the JSON by omitempty.
+  sub_bucket?: number;
+  sub_bucket_count?: number;
   values: number[];
   // Row-level conflict flag — the OR of conflicts[]. True when ≥2
   // nodes reported a different non-zero value for the same cell,

web/admin/src/pages/KeyViz.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
-import { parseBucketID } from "./KeyViz";
+import type { KeyVizRow } from "../api/client";
+import { parseBucketID, subRangeLabel } from "./KeyViz";
 
 describe("parseBucketID", () => {
   it("parses legacy and labeled route bucket IDs", () => {
@@ -16,3 +17,33 @@ describe("parseBucketID", () => {
     expect(parseBucketID("route:7:redis#")).toBeNull();
   });
 });
+
+describe("subRangeLabel", () => {
+  const row = (over: Partial<KeyVizRow>): KeyVizRow => ({
+    bucket_id: "route:7",
+    start: "",
+    end: "",
+    aggregate: false,
+    route_count: 1,
+    values: [],
+    ...over,
+  });
+
+  it("labels a sub-divided route as 1-based i/K", () => {
+    expect(subRangeLabel(row({ sub_bucket: 0, sub_bucket_count: 8 }))).toBe("sub-range 1/8");
+    expect(subRangeLabel(row({ sub_bucket: 7, sub_bucket_count: 8 }))).toBe("sub-range 8/8");
+  });
+
+  // The index is omitted from the JSON for bucket zero, so the label
+  // must key off the COUNT. Testing sub_bucket instead would hide the
+  // first sub-range of every route.
+  it("labels bucket zero even though the index is absent from the wire", () => {
+    expect(subRangeLabel(row({ sub_bucket_count: 4 }))).toBe("sub-range 1/4");
+  });
+
+  it("returns null when the route is not sub-divided", () => {
+    expect(subRangeLabel(row({}))).toBeNull();
+    expect(subRangeLabel(row({ sub_bucket_count: 0 }))).toBeNull();
+    expect(subRangeLabel(row({ sub_bucket_count: 1 }))).toBeNull();
+  });
+});

web/admin/src/pages/KeyViz.tsx

@@ -534,14 +534,35 @@ interface RowDetailProps {
   index: number;
 }
 
+// subRangeLabel renders "sub-range i/K" for a sub-divided route, or
+// null when the route is not sub-divided.
+//
+// It keys off sub_bucket_count rather than sub_bucket because bucket
+// zero of a sub-divided route has index 0, which omitempty strips from
+// the JSON — testing the index would hide exactly the first sub-range.
+export function subRangeLabel(row: KeyVizRow): string | null {
+  const count = row.sub_bucket_count ?? 0;
+  if (count <= 1) return null;
+  return `sub-range ${(row.sub_bucket ?? 0) + 1}/${count}`;
+}
+
 function RowDetail({ row, index }: RowDetailProps) {
+  const subRange = subRangeLabel(row);
   const total = row.values.reduce((a, b) => a + b, 0);
   return (
     <div className="card text-sm">
       <div className="flex items-center gap-2 mb-2 flex-wrap">
         <span className="text-xs text-muted">Row {index}</span>
         <span className="font-mono">{row.bucket_id}</span>
         {row.aggregate && <span className="pill-muted text-xs">aggregate</span>}
+        {subRange && (
+          <span
+            className="pill-muted text-xs"
+            title="This route is split into order-preserving sub-ranges by --keyvizKeyBucketsPerRoute. Start/End below are the narrowed bounds of this sub-range, not the whole route."
+          >
+            {subRange}
+          </span>
+        )}
         {row.conflict && (
           <span
             className="pill-muted text-xs"
@@ -552,9 +573,9 @@ function RowDetail({ row, index }: RowDetailProps) {
         )}
       </div>
       <dl className="grid grid-cols-2 gap-x-4 gap-y-1 text-xs">
-        <dt className="text-muted">Start</dt>
+        <dt className="text-muted">{subRange ? "Sub-range start" : "Start"}</dt>
         <dd className="font-mono break-all">{decodePreview(row.start)}</dd>
-        <dt className="text-muted">End</dt>
+        <dt className="text-muted">{subRange ? "Sub-range end" : "End"}</dt>
         <dd className="font-mono break-all">{decodePreview(row.end)}</dd>
         <dt className="text-muted">Routes</dt>
         <dd className="font-mono">