Merge branch 'pratik/otel-phase8-log-correlation' into pratik/otel-phase9-metric-gap-fill

include/xrpl/telemetry/CoroAwareContextStorage.h

@@ -31,9 +31,10 @@
  *              | (swapped by Coro)      |
  *              +------------------------+
  *
- * Install once at telemetry start via
- * opentelemetry::context::RuntimeContext::SetRuntimeContextStorage(), BEFORE
- * any span is created (SDK requirement).
+ * Install once from main() via
+ * opentelemetry::context::RuntimeContext::SetRuntimeContextStorage(), before
+ * any thread is started. That call writes a non-atomic process-global
+ * shared_ptr which every log line reads back, so a later install would race.
  *
  * @note Thread-safety: each thread/coroutine sees its own LocalValue store, so
  * the stack is never shared across threads — no locking needed. The storage
@@ -44,7 +45,7 @@
  * the coroutine's store — not a pattern here (spans are created inside their
  * own coro/job body).
  *
- * Example 1 — install at telemetry start (primary use):
+ * Example 1 — install from main(), before any thread (primary use):
  * @code
  *   using opentelemetry::context::RuntimeContext;
  *   RuntimeContext::SetRuntimeContextStorage(

include/xrpl/telemetry/ValidationTracker.h

@@ -575,6 +575,10 @@ private:
     /**
      * Decide every pending event past the grace period, repair the ones whose
      * other half arrived late, and drop entries too old to repair.
+     *
+     * Newly decided events reach the windows oldest minute first. The windows
+     * only move forward, so an event counted after a later one would land in a
+     * bucket the grid had already rolled past.
      * @param now Current time point.
      */
     void