\section{Architecture and API}
\label{sec:arch}

\raid{} is a C++20 library (MIT licence) with four layers (Figure~\ref{fig:arch}): a \emph{core} of strong types and infrastructure, a \emph{data} layer that turns provider bars into validated, calendar-aware return panels, a \emph{statistics/estimators/models} layer that implements the registry, and a \emph{backend} layer that exposes a small set of batched numerical primitives with a CPU reference implementation and a Metal implementation. Python bindings (nanobind) and a command-line tool sit on top.

\begin{figure}[t]
\centering
\begin{lstlisting}[basicstyle=\ttfamily\tiny]
 Python (nanobind, GIL released)   raid.api / raid.findata        CLI: raid devices|validate|estimate|data
 ------------------------------------------------------------------------------------------------------
 core        types (Timestamp us UTC, Date, Interval, Backend, Precision) | RaidError | log (redaction)
             rng (xoshiro256++ streams) | ThreadPool | SHA-256 | Estimate / Provenance / ExecutionPlan / Manifest
 data        MarketCalendar (XNYS rules, DST, early closes) | BarSeries + QualityReport | returns (session-aware)
             aggregate (calendar-aware bins) | io: CSV fixtures, Parquet/Arrow IPC (projection) | FinData client
 estimators  reductions (Neumaier/pairwise/Welford) | rolling | covariance (HC, HAC, cluster) | OLS/WLS/ridge
             realized (RV, BPV, RSV, RQ, J, TriPV, RCov) | HAR family | GARCH family (QML) | bootstrap | VAR/GFEVD/DY
 backend     Batch = values + CSR offsets  ->  sum_squares | sum_abs_adjacent | semivariances | sum_fourth
             rolling_sum_squares | regression_stats (X'X, X'y, y'y) | garch_nll_batch   [CpuBackend FP64 | MetalBackend FP32]
\end{lstlisting}
\caption{Layers of \raid{}. Estimators consume the backend interface through an \texttt{ExecutionPlan} (\texttt{auto|cpu|metal}); every result is an \texttt{Estimate} carrying coefficients, loss, inference, convergence, warnings, runtime, backend, precision and provenance.}
\label{fig:arch}
\end{figure}

\paragraph{Core types.} Timestamps are microseconds since the Unix epoch in UTC and are never mixed with raw integers; dates use a proleptic-Gregorian day count; intervals are an enumeration. Every estimator returns an \texttt{Estimate}: named coefficients, a loss (residual sum of squares or negative log-likelihood, documented per model), an optional \texttt{InferenceResult} (standard errors, $t$-statistics, $p$-values, covariance, covariance type), a \texttt{Convergence} record (status, iterations, function evaluations, gradient norm, message), warnings, runtime, the backend and precision actually used, and a \texttt{Provenance} record (dataset identifier and version, request identifiers, input hashes, code version). \texttt{Estimate::ok()} requires convergence; a failed optimisation is never reported as a success. An \texttt{ExecutionPlan} selects the backend, the precision policy (FP32 chunk length, compensated accumulation, validation tolerance), determinism, threads and fallback behaviour.

\paragraph{Data layer.} \texttt{BarSeries} stores OHLCV columns, bar-open timestamps and a session index. The \texttt{MarketCalendar} implements the NYSE rules (weekday holidays with the Saturday/Sunday observance rules, Good Friday from the Gregorian Easter, Juneteenth since 2022, special closures, early closes at 13:00, US daylight-saving transitions before and after 2007) and is validated set-for-set against \texttt{exchange\_calendars} over 2000--2026. \texttt{validate()} counts OHLC inconsistencies, non-positive prices, grid misalignment, bars outside the session policy, non-trading days, duplicates, price jumps and the number of regular bars missing relative to the calendar (391 on a normal day, 211 on an early close, the 16:00 closing print included); prices are never altered and bars are never manufactured. Returns are computed within sessions only; the overnight return and the daily open-to-close and close-to-close returns are separate outputs. Aggregation to coarser intervals bins bars from the session open and keeps the closing print as its own bin, which reproduces the provider's derived 5-minute series exactly (Section~\ref{sec:setup}).

\paragraph{Panels and batches.} Batched kernels take a \emph{CSR batch}: one contiguous array of values and an offsets array delimiting segments (a segment is a session, a series, or a window). Ragged panels---different session lengths, early closes, delisted series---are therefore first-class, and no padding is needed. Rectangular panels get a dense column-major view for linear algebra.

\paragraph{Backend contract.} The backend interface has seven primitives (Figure~\ref{fig:arch}). Each has an FP64 CPU implementation (compensated per-segment sums, parallel over segments) and a Metal implementation. Estimators are backend-independent: \texttt{realized\_measures\_batch}, \texttt{har\_batch} and the GARCH grid screen call the primitives and finish in FP64 on the CPU (finite-sample constants, solves, inference). \texttt{resolve(plan)} maps \texttt{auto} to Metal when a device is available and falls back to the CPU otherwise, recording the reason.

\paragraph{FinData client.} The data provider is FinData~OS, a private lakehouse serving FirstRate Data bars through a versioned REST API (Section~\ref{sec:setup}). The client authenticates with a bearer key read from the environment only, redacts secrets from logs, applies a token bucket (5 requests per second against a 600 per minute limit), retries with exponential backoff and \texttt{Retry-After}, follows cursor pagination of Arrow IPC pages, chunks requests to the documented caps (31 days of 1-minute bars per call, 12 years per export), polls asynchronous Parquet exports, and keeps a checksum-verified cache keyed by dataset version. Every exchange's request identifier and dataset version are kept for provenance.

\paragraph{Python and CLI.} The nanobind module releases the GIL around every call, accepts NumPy arrays as views and returns NumPy arrays and JSON-like dictionaries. \texttt{raid.findata} exposes the client; \texttt{raid.api} exposes the estimators with a \texttt{backend} argument. The CLI offers \texttt{raid devices}, \texttt{raid validate}, \texttt{raid estimate realized|har|garch|ols} and \texttt{raid data catalog|bars|export|sessions|coverage|query}.