\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.

\input{sections/architecture_fig}

\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).