feat(keyviz): per-cell conflict wire format + SPA per-cell hatching (Phase 2-C+ PR-3d) (#824)

bootjp · web-flow · commit 563dd92eb813 · 2026-05-25T17:56:17.000+09:00
## Summary Promotes the row-level `conflict` bool to a per-cell `Conflicts []bool` on the JSON `KeyVizRow`, so the SPA hatches only the columns that saw a within-term fan-out merge disagreement instead of the whole row. The per-cell conflict bit is **already computed** in the merge accumulator (`cellMergeAcc.hasConflict`); PR-3c (#822) collapsed it to a row-level OR. This closes that gap and aligns with parent design §9.1 ("the cell is surfaced with `conflict=true`"). Design doc: `docs/design/2026_05_25_proposed_keyviz_per_cell_conflict.md` (committed first). - `internal/admin/keyviz_handler.go` — `KeyVizRow` gains `Conflicts []bool` (`json:"conflicts,omitempty"`), parallel to `Values[]`. - `internal/admin/keyviz_fanout.go` — `resolveRowMergeAcc` stamps `Conflicts[j]` per write cell; row-level `Conflict` stays the OR for older clients. - `web/admin/src/pages/KeyViz.tsx` — `ConflictOverlay` hatches individual cells when `conflicts[]` is present, falls back to whole-row hatch when only the row-level `conflict` flag is set (legacy server). - `web/admin/src/api/client.ts` — `KeyVizRow` type gains `conflicts?: boolean[]`. ## Scope notes - **JSON-only, no proto/gRPC change.** `proto.KeyVizRow` has never carried a conflict field: conflict is a fan-out *merge* artifact, and fan-out is JSON-over-HTTP peer aggregation; the single-node gRPC `GetKeyVizMatrix` never merges. Adding `conflicts` to the proto would be a field with no producer/consumer. - **No algorithm change** — PR-3c's `(group, term)` dedupe + fallback-max path is untouched; PR-3d only widens how the already-computed per-cell bit reaches the client. - **No new flag.** `omitempty` keeps `conflicts` off the wire on the single-node / no-fan-out path. ## Compatibility | Server | SPA | Behaviour | |---|---|---| | new | new | per-cell hatch | | new | old | whole-row hatch (reads only `conflict`) | | old | new | falls back to whole-row hatch | | old | old | whole-row hatch (unchanged) | ## Self-review (five lenses) 1. **Data loss** — none; read-only admin path, no Raft/FSM/Pebble interaction. `conflicts[]` is derived from existing merge state. 2. **Concurrency / distributed** — none new; merge runs synchronously after the parallel peer fetch, no new shared mutable state. Caller-audited `resolveRowMergeAcc` (one caller) and `.Conflict`/`.Conflicts` (set only in `keyviz_fanout.go`; SPA is the only consumer, via JSON). 3. **Performance** — one `make([]bool, width)` per merged write row (bounded by the 1024-row budget); the conflict bit was already computed per cell, no extra pass. `omitempty` avoids wire growth on quiet matrices. 4. **Data consistency** — row-level `conflict` stays the exact OR of `conflicts[]`; per-cell is strictly more precise. `(group, term)` dedupe unchanged. 5. **Test coverage** — added `TestMergeKeyVizMatricesPerCellConflictMarksOnlyAffectedColumn` (only the disagreeing column flagged, row-level OR still true) and `TestMergeKeyVizMatricesReadsLeaveConflictsNil`. ## Test evidence - `go test -race -count=1 ./internal/admin/...` — pass - `golangci-lint run internal/admin/...` — 0 issues - `cd web/admin && npm run build` (`tsc -b && vite build`) — pass (type-check clean) - ⚠️ SPA rendering not verified in a live browser (no display in this environment); change is rendering-only and type-checked.  ## Summary by CodeRabbit ## Release Notes * **New Features** * Enhanced KeyViz to display per-cell conflict detection with granular heatmap overlay visualization, providing more detailed conflict reporting for individual cells while maintaining backward compatibility. * **Tests** * Added comprehensive test coverage for per-cell conflict detection and JSON serialization behavior. * **Documentation** * Added design documentation for per-cell conflict reporting implementation.  [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/bootjp/elastickv/pull/824?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
diff --git a/docs/design/2026_05_25_proposed_keyviz_per_cell_conflict.md b/docs/design/2026_05_25_proposed_keyviz_per_cell_conflict.md
@@ -0,0 +1,158 @@
+---
+status: proposed
+phase: 2-C+
+parent_design: docs/admin_ui_key_visualizer_design.md
+date: 2026-05-25
+---
+
+# KeyViz Per-Cell Conflict Wire Format (Phase 2-C+ PR-3d)
+
+## 1. Background
+
+Phase 2-C+ PR-3c (#822) replaced the legacy §4.2 row-level max-merge
+with the canonical §9.1 `(raftGroupID, leaderTerm)` per-cell dedupe:
+the fan-out aggregator now collapses write samples to one value per
+`(bucketID, raftGroupID, leaderTerm, windowStart)` and sums across
+distinct terms for the same `(group, window)`. When two sources
+report different non-zero values for the **same** `(group, term,
+column)` tuple — a Raft-invariant violation, since at most one leader
+exists per term per group — the merge flags a conflict.
+
+That conflict detection already happens **per cell** inside the merge
+accumulator (`cellMergeAcc.hasConflict()` in
+`internal/admin/keyviz_fanout.go`). But the wire format only carries a
+single **row-level** `conflict bool`: `resolveRowMergeAcc` ORs every
+cell's conflict into one boolean for the whole row. The SPA's
+`ConflictOverlay` then hatches the **entire row**, even when the
+disagreement was confined to one column during a brief leadership
+flip.
+
+Parent design §9.1 actually describes the conflict signal at cell
+granularity — *"if they differ, the cell is surfaced with
+`conflict=true`"* and *"The heatmap hatches rows or time windows whose
+expected source node failed."* The row-level collapse was an explicit
+PR-3c simplification (see the deferral note in
+`keyviz_handler.go`'s `KeyVizRow.Conflict` doc comment); PR-3d closes
+that gap.
+
+## 2. Scope
+
+### 2.1 In scope
+
+- Add a per-cell `Conflicts []bool` field to the **JSON** `KeyVizRow`
+  (`internal/admin/keyviz_handler.go`), parallel to `Values[]` —
+  `Conflicts[j]` is true when column `j` saw a within-term
+  disagreement during fan-out merge.
+- Stamp `Conflicts[j]` from the existing per-cell
+  `cellMergeAcc.hasConflict()` in `resolveRowMergeAcc`.
+- Keep the row-level `Conflict bool` on the wire as the OR of all
+  cells, so an **older SPA** that only reads `conflict` keeps hatching
+  the whole row (no behavioural regression).
+- SPA `ConflictOverlay`: hatch the **individual cells** where
+  `conflicts[j]` is true. When a response carries only row-level
+  `conflict` (legacy server, no `conflicts` array), fall back to the
+  current whole-row hatch.
+- Tests: per-cell conflict assertions in `keyviz_fanout_test.go`.
+
+### 2.2 Out of scope / non-goals
+
+- **No proto / gRPC change.** The `proto.KeyVizRow` (gRPC
+  `GetKeyVizMatrix`) has **never** carried a conflict field. Conflict
+  is a fan-out *merge* artifact, and fan-out is implemented as
+  JSON-over-HTTP peer aggregation (`KeyVizFanout.Run`); the single-node
+  gRPC RPC never merges and therefore never produces a conflict.
+  Adding `conflicts` to the proto would introduce a field with no
+  producer and no consumer — speculative, so explicitly excluded.
+- No change to the merge *algorithm* — PR-3c's `(group, term)` dedupe
+  and fallback-max path are unchanged. PR-3d only widens how the
+  already-computed per-cell conflict bit reaches the client.
+- No new `--flag`; conflict reporting is intrinsic to fan-out and was
+  already on by default whenever fan-out is configured.
+
+## 3. Wire format
+
+`KeyVizRow` (JSON) gains:
+
+```go
+// Conflicts[j] is true when fan-out merge saw two sources report
+// different non-zero values for the same (bucket, raft_group_id,
+// leader_term, column j) tuple. Parallel to Values[]; allocated
+// lazily so it is nil whenever the row had no conflict (single-node,
+// legacy server, OR a cleanly merged row) — omitempty then keeps it
+// off the wire. Otherwise len == len(Values). The row-level Conflict
+// bool remains the OR of this slice for older clients.
+Conflicts []bool `json:"conflicts,omitempty"`
+```
+
+Compatibility matrix:
+
+| Server | Client (SPA) | Behaviour |
+|---|---|---|
+| new (emits `conflicts[]` + `conflict`) | new | per-cell hatch |
+| new | old (reads only `conflict`) | whole-row hatch (unchanged) |
+| old (emits only `conflict`) | new | falls back to whole-row hatch |
+| old | old | whole-row hatch (unchanged) |
+
+`omitempty` keeps the field off the wire for the single-node /
+no-fan-out path (the merge that produces conflicts only runs with ≥2
+matrices), so quiet deployments see no payload growth.
+
+## 4. Merge changes
+
+`resolveRowMergeAcc` (`keyviz_fanout.go`) already iterates every cell
+to resolve writes. It will additionally:
+
+1. On the first conflicting cell, **lazily** allocate
+   `row.Conflicts = make([]bool, width)` — never up front, so a
+   cleanly merged row keeps `Conflicts == nil` and `omitempty` drops
+   it from the wire (a non-nil `[]bool` is never "empty" for
+   `omitempty`, so eager allocation would emit `[false,...]` on every
+   merged write row and balloon the payload).
+2. Set `row.Conflicts[j] = true` and `row.Conflict = true` for that
+   cell.
+
+The read path (`useGroupTermDedupe == false`) never sets conflict, so
+it leaves `Conflicts` nil — consistent with today's row-level
+behaviour.
+
+## 5. SPA changes
+
+`ConflictOverlay` currently emits one full-width `<rect>` per
+conflicting row. PR-3d:
+
+- When `row.conflicts` is present, emit one `<rect>` per conflicting
+  **cell** at `x = j * cellW`, `width = cellW`, `y = i * cellH`.
+- When `row.conflicts` is absent but `row.conflict` is true (legacy
+  server), keep the full-row rect.
+- The `RowDetail` "conflict" pill keeps using the row-level
+  `row.conflict` (it is a row-scoped summary, unchanged).
+
+The hatch `<pattern>` is unchanged. Per-cell rects reuse the same
+`fill="url(#keyviz-conflict-hatch)"`.
+
+## 6. Self-review (per CLAUDE.md five lenses)
+
+1. **Data loss** — none. Read-only admin path; no Raft / FSM / Pebble
+   interaction. `conflicts[]` is derived from existing merge state.
+2. **Concurrency / distributed** — none new. Merge runs synchronously
+   after the parallel peer fetch; no shared mutable state added.
+3. **Performance** — one `make([]bool, width)` only for rows that
+   actually conflict (lazy allocation), bounded by the 1024-row
+   budget; the conflict bit was already computed per cell, so no extra
+   passes. Lazy alloc + `omitempty` means clean rows add zero wire
+   bytes and zero allocations.
+4. **Data consistency** — the row-level `conflict` stays the exact OR
+   of `conflicts[]`, so the coarse signal is unchanged; per-cell is
+   strictly more precise. No change to `(group, term)` dedupe.
+5. **Test coverage** — new table cases assert `Conflicts[j]` is true
+   only at the conflicting column and that the row-level OR still
+   fires. SPA change is rendering-only; covered by the existing
+   manual heatmap check.
+
+## 7. Rollout
+
+Forwards- and backwards-compatible (see §3 matrix). No flag, no schema,
+no state on disk. Mixed-version clusters: a new aggregator merging an
+old peer's matrix simply gets no `conflicts[]` from that peer and ORs
+its row-level `conflict` as before; a new SPA against an old server
+falls back to whole-row hatch.
diff --git a/internal/admin/keyviz_fanout.go b/internal/admin/keyviz_fanout.go
@@ -108,10 +108,10 @@ type FanoutNodeStatus struct {
 //
 //   - Reads / read_bytes: sum across nodes (each node served distinct
 //     follower reads).
-//   - Writes / write_bytes: max across nodes; when the per-cell values
-//     disagree we set Conflict=true on the row (best-effort dedup
-//     during a leadership flip; the canonical (raftGroupID, leaderTerm)
-//     dedup lands in Phase 2-C+ when we extend the wire format).
+//   - Writes / write_bytes: §9.1 canonical (raftGroupID, leaderTerm)
+//     dedupe; when two sources disagree within the same (group, term,
+//     column) we set Conflicts[column]=true (and the row-level OR
+//     Conflict) so the SPA can hatch the affected cell.
 type KeyVizFanout struct {
 	self      string
 	peers     []string
@@ -475,8 +475,9 @@ func buildKeyVizPeerURL(peer string, params keyVizParams) (string, error) {
 //     max within the same (group, term) (canonical Raft invariant:
 //     at most one leader per term per group), then SUM across
 //     distinct LeaderTerm values for the same (group, column).
-//     Surface conflict=true at the row level when ≥2 sources
-//     disagree within the SAME (group, term, column). Fall back to
+//     Surface Conflicts[column]=true (and the row-level OR Conflict)
+//     when ≥2 sources disagree within the SAME (group, term, column).
+//     Fall back to
 //     legacy max-merge (§4.2) for any cell where at least one source
 //     reports a zero/unknown identity (RaftGroupID=0 or
 //     LeaderTerm=0) so a legacy peer that doesn't yet emit the
@@ -716,9 +717,9 @@ func (c *cellMergeAcc) recordTermContribution(key termKey, value uint64) {
 // resolveRowMergeAcc materialises a KeyVizRow from the accumulator.
 // For reads: cell.sum + last identity. For writes: either §9.1 sum
 // across (group, term) or fallback max-merge when hasUnknownTerm.
-// Sets row-level Conflict to any-cell-saw-conflict — Phase 2-C+
-// PR-3c keeps the wire-level conflict at row granularity; future
-// PR-3d may promote it to per-cell.
+// The write path stamps per-cell Conflicts[j] (Phase 2-C+ PR-3d) and
+// keeps row-level Conflict as their OR so an older SPA that only reads
+// `conflict` still hatches the whole row.
 func resolveRowMergeAcc(acc *rowMergeAcc, useGroupTermDedupe bool) KeyVizRow {
 	width := len(acc.cells)
 	row := KeyVizRow{
@@ -738,6 +739,14 @@ func resolveRowMergeAcc(acc *rowMergeAcc, useGroupTermDedupe bool) KeyVizRow {
 		if useGroupTermDedupe {
 			row.Values[j], row.RaftGroupIDs[j], row.LeaderTerms[j] = c.resolveWrite()
 			if c.hasConflict() {
+				// Allocate Conflicts lazily so a clean row keeps it nil
+				// and `json:"conflicts,omitempty"` omits it — otherwise
+				// every merged write row would serialize a full
+				// [false,...] array and balloon the wire payload.
+				if row.Conflicts == nil {
+					row.Conflicts = make([]bool, width)
+				}
+				row.Conflicts[j] = true
 				row.Conflict = true
 			}
 		} else {
diff --git a/internal/admin/keyviz_fanout_test.go b/internal/admin/keyviz_fanout_test.go
@@ -203,6 +203,8 @@ func TestMergeKeyVizMatricesGroupTermConflictWithinSameTerm(t *testing.T) {
 	require.Equal(t, []uint64{55}, merged.Rows[0].Values, "within-term disagreement keeps the larger value")
 	require.True(t, merged.Rows[0].Conflict,
 		"§9.1: within-(group, term) disagreement must raise the conflict flag — Raft invariant says one leader per term per group, so disagreement signals a real divergence operators need to see")
+	require.Equal(t, []bool{true}, merged.Rows[0].Conflicts,
+		"the per-cell slice must flag the single conflicting column, not just the row-level OR")
 }
 
 // TestMergeKeyVizMatricesGroupTermFallbackOnUnknownTerm pins the
@@ -234,6 +236,8 @@ func TestMergeKeyVizMatricesGroupTermFallbackOnUnknownTerm(t *testing.T) {
 	require.Equal(t, []uint64{50}, merged.Rows[0].Values,
 		"unknown-term fallback returns max-merge (50), not sum (80) — summing across an unknown term risks double-counting overlapping windows")
 	require.True(t, merged.Rows[0].Conflict, "fallback path raises conflict when ≥2 distinct non-zero values were seen")
+	require.Equal(t, []bool{true}, merged.Rows[0].Conflicts,
+		"the per-cell slice must flag the conflicting column under the fallback path too")
 }
 
 // TestMergeKeyVizMatricesFallbackPreservesKnownTermWinnerIdentity
@@ -307,6 +311,90 @@ func TestMergeKeyVizMatricesPerCellIdentityMatchesValueOwner(t *testing.T) {
 		"col0's identity comes from exLeader (term 42, won 50 vs 0); col1's identity comes from newLeader (term 43, won 80 vs 0)")
 }
 
+// TestMergeKeyVizMatricesPerCellConflictMarksOnlyAffectedColumn pins
+// PR-3d: per-cell Conflicts[] must flag ONLY the column that saw a
+// within-term disagreement, not the whole row. col0 disagrees
+// (30 vs 55 for the same group/term), col1 agrees (10 == 10), so
+// Conflicts must be [true, false] while the row-level OR Conflict
+// stays true for older clients.
+func TestMergeKeyVizMatricesPerCellConflictMarksOnlyAffectedColumn(t *testing.T) {
+	t.Parallel()
+	col := []int64{1_700_000_000_000, 1_700_000_001_000}
+	a := KeyVizMatrix{
+		ColumnUnixMs: col,
+		Series:       keyVizSeriesWrites,
+		Rows: []KeyVizRow{
+			{BucketID: "route:9", Values: []uint64{30, 10}, RaftGroupIDs: []uint64{7, 7}, LeaderTerms: []uint64{42, 42}},
+		},
+	}
+	b := KeyVizMatrix{
+		ColumnUnixMs: col,
+		Series:       keyVizSeriesWrites,
+		Rows: []KeyVizRow{
+			{BucketID: "route:9", Values: []uint64{55, 10}, RaftGroupIDs: []uint64{7, 7}, LeaderTerms: []uint64{42, 42}},
+		},
+	}
+	merged := mergeKeyVizMatrices([]KeyVizMatrix{a, b}, keyVizSeriesWrites)
+	require.Len(t, merged.Rows, 1)
+	require.Equal(t, []uint64{55, 10}, merged.Rows[0].Values, "within-term disagreement keeps the larger value per cell")
+	require.Equal(t, []bool{true, false}, merged.Rows[0].Conflicts,
+		"only col0 disagreed (30 vs 55); col1 agreed (10 == 10) so it must not be hatched")
+	require.True(t, merged.Rows[0].Conflict,
+		"row-level Conflict stays the OR of Conflicts[] so an older SPA still hatches the row")
+}
+
+// TestMergeKeyVizMatricesWritesWithoutConflictLeaveConflictsNil pins
+// the lazy-allocation contract: a write merge with no within-term
+// disagreement (stable leader, one source non-zero) must leave
+// Conflicts nil so json:"conflicts,omitempty" omits it. Allocating a
+// full [false,...] array per clean row would balloon the wire payload.
+func TestMergeKeyVizMatricesWritesWithoutConflictLeaveConflictsNil(t *testing.T) {
+	t.Parallel()
+	col := []int64{1_700_000_000_000, 1_700_000_001_000}
+	leader := KeyVizMatrix{
+		ColumnUnixMs: col,
+		Series:       keyVizSeriesWrites,
+		Rows: []KeyVizRow{
+			{BucketID: "route:9", Values: []uint64{30, 40}, RaftGroupIDs: []uint64{7, 7}, LeaderTerms: []uint64{42, 42}},
+		},
+	}
+	follower := KeyVizMatrix{
+		ColumnUnixMs: col,
+		Series:       keyVizSeriesWrites,
+		Rows: []KeyVizRow{
+			{BucketID: "route:9", Values: []uint64{0, 0}, RaftGroupIDs: []uint64{7, 7}, LeaderTerms: []uint64{42, 42}},
+		},
+	}
+	merged := mergeKeyVizMatrices([]KeyVizMatrix{leader, follower}, keyVizSeriesWrites)
+	require.Len(t, merged.Rows, 1)
+	require.Equal(t, []uint64{30, 40}, merged.Rows[0].Values)
+	require.Nil(t, merged.Rows[0].Conflicts, "a cleanly merged write row must leave Conflicts nil for omitempty")
+	require.False(t, merged.Rows[0].Conflict)
+}
+
+// TestMergeKeyVizMatricesReadsLeaveConflictsNil pins that the read
+// merge path never allocates Conflicts — reads are independent local
+// serves that sum and can never conflict, so the per-cell slice stays
+// nil and is omitted from the wire.
+func TestMergeKeyVizMatricesReadsLeaveConflictsNil(t *testing.T) {
+	t.Parallel()
+	col := []int64{1_700_000_000_000}
+	a := KeyVizMatrix{
+		ColumnUnixMs: col,
+		Series:       keyVizSeriesReads,
+		Rows:         []KeyVizRow{{BucketID: "route:1", Values: []uint64{10}}},
+	}
+	b := KeyVizMatrix{
+		ColumnUnixMs: col,
+		Series:       keyVizSeriesReads,
+		Rows:         []KeyVizRow{{BucketID: "route:1", Values: []uint64{25}}},
+	}
+	merged := mergeKeyVizMatrices([]KeyVizMatrix{a, b}, keyVizSeriesReads)
+	require.Len(t, merged.Rows, 1)
+	require.Nil(t, merged.Rows[0].Conflicts, "reads never conflict — Conflicts stays nil")
+	require.False(t, merged.Rows[0].Conflict)
+}
+
 // TestMergeKeyVizMatricesWritesMaxLeadershipFlip pins §4.2 under a
 // mid-window flip: two nodes report non-zero, disagreeing values
 // for the same cell. The merge keeps the larger value and raises
diff --git a/internal/admin/keyviz_handler.go b/internal/admin/keyviz_handler.go
@@ -76,13 +76,13 @@ type KeyVizMatrix struct {
 // merge disagreement. For writes the predicate fires when ≥2 sources
 // reported different non-zero values for the SAME
 // (bucket, raft_group_id, leader_term, column) tuple — a Raft
-// invariant violation (at most one leader per term per group), so
-// the SPA hatches the row. Phase 2-C+ PR-3c upgraded the merge from
+// invariant violation (at most one leader per term per group). It is
+// the OR of Conflicts[] and stays on the wire as the coarse signal an
+// older SPA hatches the whole row from; newer clients prefer the
+// per-cell Conflicts slice. Phase 2-C+ PR-3c upgraded the merge from
 // the Phase 2-C row-level §4.2 max-merge to the canonical §9.1
-// per-cell (group, term)-keyed dedupe + sum-across-terms; the
-// row-level Conflict flag stays as the coarse SPA signal and a
-// per-cell `Conflicts []bool` is deferred to a future wire-format
-// extension.
+// per-cell (group, term)-keyed dedupe + sum-across-terms; PR-3d
+// surfaces that per-cell conflict bit on the wire via Conflicts[].
 type KeyVizRow struct {
 	BucketID          string   `json:"bucket_id"`
 	Start             []byte   `json:"start"`
@@ -93,6 +93,15 @@ type KeyVizRow struct {
 	RouteCount        uint64   `json:"route_count"`
 	Values            []uint64 `json:"values"`
 	Conflict          bool     `json:"conflict,omitempty"`
+	// Conflicts[j] is true when fan-out merge saw ≥2 sources report
+	// different non-zero values for the same
+	// (bucket, raft_group_id, leader_term, column j) tuple, so the SPA
+	// can hatch the individual cell rather than the whole row. Allocated
+	// lazily and only on the write path: nil whenever the row had no
+	// conflict (single-node, no fan-out, legacy server, or a cleanly
+	// 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"`
 	// 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
diff --git a/web/admin/src/api/client.ts b/web/admin/src/api/client.ts
@@ -346,12 +346,17 @@ export interface KeyVizRow {
   route_ids_truncated?: boolean;
   route_count: number;
   values: number[];
-  // Phase 2-C row-level conflict flag (always present on the wire,
-  // defaults to false). True when ≥2 nodes reported a non-zero
-  // value for the same cell — typically a leadership flip mid-
-  // window. Per design 4.2 / PR-1, this is a row-level signal; it
-  // moves to per-cell when the proto extension lands in 2-C+.
+  // Row-level conflict flag — the OR of conflicts[]. True when ≥2
+  // nodes reported a different non-zero value for the same cell,
+  // typically a leadership flip mid-window. Kept on the wire so an
+  // older client without per-cell support still hatches the row.
   conflict?: boolean;
+  // Per-cell conflict flags (Phase 2-C+ PR-3d), parallel to values[].
+  // conflicts[j] is true when column j saw a within-term merge
+  // disagreement. Absent on the single-node / no-fan-out path and from
+  // legacy servers; when absent the SPA falls back to the row-level
+  // conflict flag.
+  conflicts?: boolean[];
 }
 
 // Per-node entry in the KeyVizMatrix.fanout block. OK=true means
diff --git a/web/admin/src/pages/KeyViz.tsx b/web/admin/src/pages/KeyViz.tsx
