fix(data): level-per-emission pyramid cover, relaxed-atomic ring slots

cover_buckets chose one level per pass, so an odd first whole bucket (half of all

measurement ranges) never reached a level above 0 and folded every remaining

bucket at level 0 -- 15624 entries for a 1e6-sample pyramid. Pick the largest

aligned, in-range, materialised level at each cursor instead; the new cost test

counts folded entries through a PLOT_PYRAMID_COUNT_COVERS-only hook (absent from

normal builds) and fails on the old body.

Ring slots are now relaxed std::atomic: overwrite-on-full means the producer

reuses the slot of a snapshot's oldest sample while the consumer reads it, which

was a data race, not just a stale value. copy_from loads explicitly instead of

std::copy; push stays lock-free. A new producer/consumer case is the one TSan

flags without this.

Also extends the wrapped-window test with x0/bounds/pyramid/sum/sumsq/gather

checks, and corrects the StreamSeries threading note to the sample-count bound.

include/plot/data/detail/cover_count.hpp

@@ -0,0 +1,29 @@
+#pragma once
+
+#ifdef PLOT_PYRAMID_COUNT_COVERS
+
+#include <atomic>
+
+#include <plot/core/types.hpp>
+
+namespace plot::data::detail {
+
+/// Test-only instrumentation. Counts the pyramid entries the covering
+/// decomposition has emitted since the counter was last reset.
+///
+/// The decomposition's *cost* is invisible in every answer -- a decomposition
+/// that walks the range one level-0 bucket at a time returns exactly the same
+/// min/max/sum as the O(log n) one -- so a test that wants to pin "at most two
+/// entries per level" has to count entries. The counter exists only when
+/// PLOT_PYRAMID_COUNT_COVERS is defined (the test build defines it), so every
+/// normal build carries no counter and no increment on the query path.
+///
+/// Not part of the query surface and not meant for production use.
+inline std::atomic<u64>& cover_entry_count() {
+  static std::atomic<u64> count{0};
+  return count;
+}
+
+}  // namespace plot::data::detail
+
+#endif  // PLOT_PYRAMID_COUNT_COVERS

include/plot/data/ring_buffer.hpp

@@ -1,8 +1,6 @@
 #pragma once
-#include <algorithm>
 #include <atomic>
 #include <bit>
-#include <cstddef>
 #include <vector>
 
 #include <plot/core/types.hpp>
@@ -16,6 +14,15 @@ namespace plot::data {
 /// sample count with a release store; a consumer that observes that count with an
 /// acquire load is guaranteed to see the slot contents written before it.
 ///
+/// Slots are std::atomic and every slot access is relaxed. Because the ring
+/// *overwrites*, the producer's next push reuses the slot of the snapshot's
+/// oldest retained element while the consumer may still be reading it, so a plain
+/// load/store there would be a data race (UB), not merely a stale value. A
+/// relaxed atomic load/store is a plain mov/ldr/str on the supported targets, so
+/// the sample path costs the same. Relaxed is enough because the ordering lives in
+/// the count handshake above; the count fixes *which* indices a snapshot reads,
+/// not that the slots still hold those samples (see StreamSeries).
+///
 /// A push into a full ring silently discards the oldest element: for a live
 /// plotting stream the newest sample is the interesting one and the retained
 /// window slides forward.
@@ -29,6 +36,8 @@ namespace plot::data {
 ///    such a snapshot and then reads only absolute indices.
 template <typename T>
 class RingBuffer {
+  static_assert(std::atomic<T>::is_always_lock_free,
+                "RingBuffer slots are atomic and must be lock-free: the sample path may not lock");
  public:
   explicit RingBuffer(u64 capacity)
       : cap_(std::bit_ceil(capacity < 1 ? u64{1} : capacity)),
@@ -38,7 +47,7 @@ class RingBuffer {
   /// Producer thread only.
   void push(T v) {
     const u64 i = produced_.load(std::memory_order_relaxed);
-    buf_[static_cast<usize>(i & mask_)] = v;
+    buf_[static_cast<usize>(i & mask_)].store(v, std::memory_order_relaxed);
     produced_.store(i + 1, std::memory_order_release);
   }
 
@@ -66,24 +75,25 @@ class RingBuffer {
   }
 
   /// Single-threaded: retained-window index (0 = oldest retained). `i` must be
-  /// < size().
-  const T& operator[](u64 i) const noexcept {
-    return buf_[static_cast<usize>((base() + i) & mask_)];
+  /// < size(). Returns by value: the slot is an atomic, so a relaxed load is the
+  /// only way to observe it.
+  T operator[](u64 i) const noexcept {
+    return buf_[static_cast<usize>((base() + i) & mask_)].load(std::memory_order_relaxed);
   }
 
   /// Consumer: copies the `n` elements at absolute indices [absolute, absolute+n)
-  /// into `out`, splitting the copy at the ring's wrap point. The caller must hold
-  /// a snapshot that retains those indices; this never consults the live count, so
-  /// a pushing producer cannot shift the read.
+  /// into `out`, masking the index to wrap. The caller must hold a snapshot
+  /// that retains those indices; this never consults the live count, so
+  /// a pushing producer cannot shift the read -- but it fixes only *which*
+  /// indices are read, not that the slots still hold those samples: a producer
+  /// that overtakes capacity() has already rewritten the oldest ones (see the
+  /// class note).
   void copy_from(u64 absolute, u64 n, T* out) const {
     if (n == 0) return;
-    const u64 s = absolute & mask_;
-    const u64 run = std::min(n, cap_ - s);
-    const auto first = buf_.begin() + static_cast<std::ptrdiff_t>(s);
-    std::copy(first, first + static_cast<std::ptrdiff_t>(run), out);
-    if (run < n) {
-      std::copy(buf_.begin(), buf_.begin() + static_cast<std::ptrdiff_t>(n - run),
-                out + static_cast<std::ptrdiff_t>(run));
+    // Explicit relaxed loads: std::copy cannot read atomic slots, and the mask
+    // makes the wrap split unnecessary.
+    for (u64 i = 0; i < n; ++i) {
+      out[i] = buf_[static_cast<usize>((absolute + i) & mask_)].load(std::memory_order_relaxed);
     }
   }
 
@@ -94,7 +104,7 @@ class RingBuffer {
  private:
   u64 cap_;
   u64 mask_;
-  std::vector<T> buf_;
+  std::vector<std::atomic<T>> buf_;
   std::atomic<u64> produced_{0};
 };
 

include/plot/data/stream_series.hpp

@@ -30,15 +30,23 @@ namespace plot::data {
 ///
 /// THREADING NOTE. The ring overwrites the oldest samples -- that is what keeps a
 /// live stream showing the newest data, and what the drop test pins down -- so a
-/// producer racing past capacity() can write the very slot the consumer is reading
-/// at the window's oldest edge. That read is not ordered against the write, so a
-/// race detector flags it: the value is still a single f32 (no tearing on
-/// supported targets) and the worst case is one stale or too-new sample at the
-/// oldest edge, corrected by the next acquire() once it sees the base moved. The
-/// pyramid itself never mixes windows, because acquire() derives the whole window
-/// from one count. Ingest that is race-free even at the edge needs the producer to
-/// stop before unread data (drop-on-full) or a claim protocol, i.e. a different
-/// contract from the one this class specifies.
+/// producer can overwrite the slots a consumer is reading even while it holds a
+/// snapshot. Those slots are relaxed atomics (see RingBuffer), so this is not a
+/// data race and no value tears; what it is not is a frozen window.
+///
+/// The bound is the sample count, not the geometry. A snapshot count fixes *which
+/// absolute indices* a read walks, not that the slots still hold those samples:
+/// every push after the snapshot overwrites exactly one slot, the one belonging to
+/// the sample capacity() positions behind it. So if the producer pushes k samples
+/// while a read is in flight, the first k positions of that read window can hold
+/// one of those k newer samples (or a still-newer sample, once the producer has
+/// lapped again) instead of the sample the snapshot names. Nothing else moves: the
+/// count, the absolute index -> x mapping and the newest end of the window are
+/// derived from the one published count, and the next acquire() rebuilds from the
+/// base it observes, so the pyramid never mixes two windows. Ingest with no reuse
+/// underneath a read at all needs the producer to stop before unread data
+/// (drop-on-full) or a claim protocol, i.e. a different contract from the one this
+/// class specifies.
 class StreamSeries final : public Series {
  public:
   explicit StreamSeries(u64 capacity, f64 x0, f64 dx);