// Realized measures from intraday returns (per session). Definitions (registry keys realized.*), with M intraday
// returns r_1..r_M of one session:
//   RV   = Σ r_j²                                                   (Andersen–Bollerslev–Diebold–Labys 2003)
//   BPV  = μ₁⁻² · (M/(M−1)) · Σ_{j=2}^{M} |r_j||r_{j−1}|,  μ₁ = √(2/π)   (Barndorff-Nielsen & Shephard 2004; the finite-sample
//          factor M/(M−1) is optional: `bpv_finite_sample` — highfrequency::rBPCov applies it by default (makeReturns scaling))
//   RSV− = Σ r_j² 1{r_j<0},  RSV+ = Σ r_j² 1{r_j>0}                 (Barndorff-Nielsen–Kinnebrock–Shephard 2010)
//   RQ   = (M/3) · Σ r_j⁴                                             (Barndorff-Nielsen & Shephard 2002; BPQ 2016 HARQ)
//   J    = max(RV − BPV, 0), relative jump = J / RV                  (Andersen–Bollerslev–Diebold 2007 proxy, no test)
//   TriPV = μ_{4/3}⁻³ · (M/(M−2)) · Σ |r_j|^{4/3}|r_{j−1}|^{4/3}|r_{j−2}|^{4/3},  μ_{4/3} = 2^{2/3} Γ(7/6)/Γ(1/2)
//   BNS ratio test statistic (Tier C, Huang–Tauchen 2005 log version) is NOT implemented in Tier A.
// Realized covariance: RCov_{ab} = Σ_j r_{a,j} r_{b,j} on synchronized grids (same session, same timestamps).
#pragma once
#include <span>
#include <vector>
#include <string>
#include <Eigen/Dense>
#include "raid/core/types.hpp"
#include "raid/core/plan.hpp"
#include "raid/data/returns.hpp"
#include "raid/data/panel.hpp"
#include "raid/backend/backend.hpp"

namespace raid::est {

struct RealizedOptions {
  bool bpv_finite_sample{true};
  bool fuse_kernels{true};      // Metal: one fused pass for all accumulators (ablation: false → 4 kernels)
  bool annualize{false};        // multiply variances by `periods_per_year`
  f64 periods_per_year{252.0};
  ExecutionPlan plan{};
};

struct RealizedMeasures {
  std::vector<Date> sessions;
  std::vector<usize> n_returns;     // M per session
  std::vector<f64> rv, bpv, rsv_neg, rsv_pos, rq, jump, tripv;
  std::vector<f64> daily_return;    // Σ r_j (open-to-close log return when log returns are used)
  backend::KernelStats stats;       // backend / precision / timing of the batched part
  std::vector<std::string> warnings;
};

/// Per-session realized measures for one instrument from intraday returns (data::IntradayReturns).
RealizedMeasures realized_measures(const data::IntradayReturns& ir, const RealizedOptions& opt = {});
/// Batched over a CSR batch of return segments (one segment = one session or one series), returns the same vectors.
RealizedMeasures realized_measures_batch(const backend::Batch& b, const RealizedOptions& opt = {});

/// Realized covariance / correlation of N aligned return series (T × N dense).
struct RealizedCov { Eigen::MatrixXd cov; Eigen::MatrixXd corr; usize n_obs; };
RealizedCov realized_covariance(const Eigen::Ref<const Eigen::MatrixXd>& R);

/// Finite-sample constants exposed for tests and the paper appendix.
constexpr f64 kMu1 = 0.7978845608028654;      // √(2/π)
f64 mu_p(f64 p);                               // E|Z|^p for Z ~ N(0,1)

}  // namespace raid::est