keyviz admin: precompute row totals + deterministic budget tie-break

Round-1 review fixes for PR #660 (Gemini medium):

The rows-budget sort previously called rowActivityTotal inside the
comparator, paying O(M) per pair × O(N log N) comparisons —
quadratic-ish in column count for the cost of one HTTP request.
Worse, the lack of a tie-breaker made truncation non-deterministic:
two refreshes against identical data could return different row
sets, surfacing as flicker in the SPA heatmap.

Accumulate a precomputed row.total during the pivot phase (json:"-"
field, internal only) and sort on it in the budget step. Add
BucketID as the tie-breaker so identical data → identical response.

Test TestKeyVizHandlerRowsBudgetTieBreakDeterministic stages three
routes with equal Writes, requests rows=2 three times in a row, and
asserts the same two routes (lowest BucketID) survive every time.

Author: bootjp

internal/admin/keyviz_handler.go

@@ -73,6 +73,11 @@ type KeyVizRow struct {
 	RouteIDsTruncated bool     `json:"route_ids_truncated,omitempty"`
 	RouteCount        uint64   `json:"route_count"`
 	Values            []uint64 `json:"values"`
+	// total accumulates the sum of Values during pivot so the
+	// rowBudget sort is O(N log N) on a precomputed key rather
+	// than O(N log N × M) recomputing the sum per comparison.
+	// Not on the wire — clients read activity off Values directly.
+	total uint64
 }
 
 // KeyVizHandler serves GET /admin/api/v1/keyviz/matrix.
@@ -262,7 +267,9 @@ func pivotKeyVizColumns(cols []keyviz.MatrixColumn, series KeyVizSeries, rowBudg
 				rowsByID[mr.RouteID] = row
 				order = append(order, mr.RouteID)
 			}
-			row.Values[j] = pick(mr)
+			v := pick(mr)
+			row.Values[j] = v
+			row.total += v
 		}
 	}
 	matrix.Rows = make([]KeyVizRow, len(order))
@@ -320,24 +327,24 @@ func bucketIDFor(mr keyviz.MatrixRow) string {
 // activity-descending truncation rather than design §5.5's lexicographic
 // merge. Future work should swap in the spec'd merge once the
 // virtual-bucket plumbing supports synthesis at the response layer.
+//
+// Sort uses the precomputed row.total (accumulated during pivot) so
+// the comparator is O(1), not O(M). BucketID breaks activity ties
+// deterministically — the SPA refresh on the same data must yield the
+// same row set.
 func applyKeyVizRowBudget(rows []KeyVizRow, budget int) []KeyVizRow {
 	if budget <= 0 || len(rows) <= budget {
 		return rows
 	}
 	sort.Slice(rows, func(i, j int) bool {
-		return rowActivityTotal(rows[i]) > rowActivityTotal(rows[j])
+		if rows[i].total != rows[j].total {
+			return rows[i].total > rows[j].total
+		}
+		return rows[i].BucketID < rows[j].BucketID
 	})
 	return rows[:budget]
 }
 
-func rowActivityTotal(r KeyVizRow) uint64 {
-	var sum uint64
-	for _, v := range r.Values {
-		sum += v
-	}
-	return sum
-}
-
 func sortKeyVizRowsByStart(rows []KeyVizRow) {
 	sort.Slice(rows, func(i, j int) bool {
 		if c := bytes.Compare(rows[i].Start, rows[j].Start); c != 0 {

internal/admin/keyviz_handler_test.go

@@ -256,3 +256,34 @@ func TestKeyVizHandlerEncodesAggregateBucket(t *testing.T) {
 	require.True(t, r.RouteIDsTruncated)
 	require.Equal(t, []uint64{2, 3}, r.RouteIDs)
 }
+
+// TestKeyVizHandlerRowsBudgetTieBreakDeterministic pins Gemini round-1
+// nit: when two rows tie on activity total, the rows-budget truncation
+// must pick the same set every refresh. Tie-break is BucketID
+// ascending so a re-poll on identical data yields identical rows.
+func TestKeyVizHandlerRowsBudgetTieBreakDeterministic(t *testing.T) {
+	t.Parallel()
+	srv := newKeyVizTestServer(t, &fakeKeyVizSource{cols: []keyviz.MatrixColumn{
+		{
+			At: time.Unix(1_700_000_000, 0),
+			Rows: []keyviz.MatrixRow{
+				{RouteID: 3, Start: []byte("c"), End: []byte("d"), Writes: 10},
+				{RouteID: 1, Start: []byte("a"), End: []byte("b"), Writes: 10},
+				{RouteID: 2, Start: []byte("b"), End: []byte("c"), Writes: 10},
+			},
+		},
+	}})
+	defer srv.Close()
+
+	for i := 0; i < 3; i++ {
+		resp := keyVizGet(t, srv.URL+"?rows=2")
+		var matrix KeyVizMatrix
+		require.NoError(t, json.NewDecoder(resp.Body).Decode(&matrix))
+		resp.Body.Close()
+		require.Len(t, matrix.Rows, 2, "iteration %d", i)
+		// BucketID tie-break: route:1, route:2 win over route:3.
+		// After the budget cap they sort by Start, giving "a" then "b".
+		require.Equal(t, "route:1", matrix.Rows[0].BucketID, "iteration %d", i)
+		require.Equal(t, "route:2", matrix.Rows[1].BucketID, "iteration %d", i)
+	}
+}