galaaz 2.1.8 → 2.1.9

data/blogs/r_on_rails_ledger/r_on_rails_ledger.tex

@@ -0,0 +1,670 @@
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+  11pt,
+]{article}
+\usepackage{xcolor}
+\usepackage[margin=1in]{geometry}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{5}
+\usepackage{iftex}
+\ifPDFTeX
+  \usepackage[T1]{fontenc}
+  \usepackage[utf8]{inputenc}
+  \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+  \usepackage{unicode-math} % this also loads fontspec
+  \defaultfontfeatures{Scale=MatchLowercase}
+  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+  % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+  \usepackage[]{microtype}
+  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+  \IfFileExists{parskip.sty}{%
+    \usepackage{parskip}
+  }{% else
+    \setlength{\parindent}{0pt}
+    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+  \KOMAoptions{parskip=half}}
+\makeatother
+\usepackage{color}
+\usepackage{fancyvrb}
+\newcommand{\VerbBar}{|}
+\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
+\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
+% Add ',fontsize=\small' for more characters per line
+\usepackage{framed}
+\definecolor{shadecolor}{RGB}{248,248,248}
+\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
+\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
+\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
+\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\BuiltInTok}[1]{#1}
+\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
+\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
+\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
+\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
+\newcommand{\ExtensionTok}[1]{#1}
+\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\ImportTok}[1]{#1}
+\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\NormalTok}[1]{#1}
+\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
+\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
+\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
+\newcommand{\RegionMarkerTok}[1]{#1}
+\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
+\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
+\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\usepackage{longtable,booktabs,array}
+\newcounter{none} % for unnumbered tables
+\usepackage{calc} % for calculating minipage widths
+% Correct order of tables after \paragraph or \subparagraph
+\usepackage{etoolbox}
+\makeatletter
+\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
+\makeatother
+% Allow footnotes in longtable head/foot
+\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
+\makesavenoteenv{longtable}
+\usepackage{graphicx}
+\makeatletter
+\newsavebox\pandoc@box
+\newcommand*\pandocbounded[1]{% scales image to fit in text height/width
+  \sbox\pandoc@box{#1}%
+  \Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}%
+  \Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}%
+  \ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both
+  \ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}%
+  \else\usebox{\pandoc@box}%
+  \fi%
+}
+% Set default figure placement to htbp
+\def\fps@figure{htbp}
+\makeatother
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+% usar portugues do Brasil
+% \usepackage[brazilian]{babel}
+\usepackage[utf8]{inputenc}
+
+\usepackage{geometry}
+\geometry{a4paper, top=1.05in, headheight=30pt, headsep=14pt}
+
+% needed for kableExtra
+\usepackage{longtable}
+\usepackage{multirow}
+\usepackage[table]{xcolor}
+\usepackage{wrapfig}
+\usepackage{float}
+\usepackage{colortbl}
+\usepackage{pdflscape}
+\usepackage{tabu}
+\usepackage{threeparttable}
+\usepackage[normalem]{ulem}
+
+\usepackage{bbm}
+\usepackage{booktabs}
+\usepackage{expex}
+
+\usepackage{graphicx}
+
+\usepackage{fancyhdr}
+% Header: small Galaaz mark (left); page number + section title (right),
+% matching classic LaTeX style: "4  AN EXTENSION TO THE EXAMPLE"
+% (upright page number, uppercase italic section name).
+% Logo paths cover repo blogs (../../sty/), installed ~/sty/, and local images/.
+% Blogs may delay headers with \renewcommand{\galaazheaderfrompage}{3} after this sty
+% (e.g. skip title/TOC and a logo splash page).
+\newcommand{\galaazheaderfrompage}{1}
+\newcommand{\galaazheaderlogo}{%
+  \raisebox{-0.12\height}{%
+    \IfFileExists{../../sty/galaaz-header.png}{%
+      \includegraphics[height=0.32in]{../../sty/galaaz-header.png}%
+    }{%
+      \IfFileExists{galaaz-header.png}{%
+        \includegraphics[height=0.32in]{galaaz-header.png}%
+      }{%
+        \IfFileExists{images/galaaz-header.png}{%
+          \includegraphics[height=0.32in]{images/galaaz-header.png}%
+        }{}%
+      }%
+    }%
+  }%
+}
+% Section title only in marks (no \thesection); page number is separate.
+\renewcommand{\sectionmark}[1]{\markboth{#1}{}}
+\renewcommand{\subsectionmark}[1]{}% keep the current section in the header
+\newcommand{\galaazmaybeheaderlogo}{%
+  \ifnum\value{page}<\galaazheaderfrompage\relax\else\galaazheaderlogo\fi}
+\newcommand{\galaazmayberighthead}{%
+  \ifnum\value{page}<\galaazheaderfrompage\relax
+  \else
+    \textup{\thepage}\hspace{1em}\textit{\MakeUppercase{\leftmark}}%
+  \fi
+}
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[L]{\galaazmaybeheaderlogo}
+\fancyhead[R]{\galaazmayberighthead}
+\renewcommand{\headrulewidth}{0.3pt}
+\makeatletter
+\renewcommand{\headrule}{%
+  \ifnum\value{page}<\galaazheaderfrompage\relax
+  \else
+    \hrule\@height\headrulewidth\@width\headwidth
+    \vskip-\headrulewidth
+  \fi
+}
+\makeatother
+% First page often uses plain; same conditional header logic.
+\fancypagestyle{plain}{%
+  \fancyhf{}%
+  \fancyhead[L]{\galaazmaybeheaderlogo}%
+  \fancyhead[R]{\galaazmayberighthead}%
+  \renewcommand{\headrulewidth}{0.3pt}%
+}
+
+% make available command lastpage
+\usepackage{lastpage}
+
+% default fontsize 11pt better to add
+% fontsize on the yaml header
+% \usepackage[fontsize=11pt]{scrextend}
+
+% comandos para formatar uma tabela
+\usepackage{array}
+\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\newcolumntype{R}[1]{>{\raggedleft\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+
+% necessário if we need to import other latex documents
+\usepackage{import}
+
+% Command to import an R variable to latex
+\newcommand{\RtoLatex}[2]{\newcommand{#1}{#2}}
+
+% Soft-wrap Pandoc highlighted code/output boxes (Shaded + Highlighting).
+% This runs after Pandoc's default \DefineVerbatimEnvironment{Highlighting}
+% (header includes come later in the generated .tex). Prefer manual line
+% breaks in Rmd sources; breaklines is a safety net for leftovers/output.
+% Requires TinyTeX/TeX Live package: tlmgr install fvextra
+\IfFileExists{fvextra.sty}{%
+  \usepackage{fvextra}%
+  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
+    breaklines=true,
+    breakanywhere=true,
+    breakindent=1.5em,
+    fontsize=\small,
+    commandchars=\\\{\}%
+  }%
+}{%
+  % fancyvrb is already loaded by Pandoc; shrink code so more fits per line.
+  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
+    fontsize=\small,
+    commandchars=\\\{\}%
+  }%
+}
+
+% 
+%\newcommand{\atraso}[1]{\color{red} \textbf {Tempo desde a Assinatura do Contrato: #1 dias}}
+% No header on title/TOC (p.1) or splash logo page (p.2);
+% logo + page number + section title from page 3 onward.
+% Load after galaaz.sty.
+\renewcommand{\galaazheaderfrompage}{3}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+\hypersetup{
+  pdftitle={R-on-Rails: ship the ledger on Rails{,} keep the science in R},
+  pdfauthor={Rodrigo Botafogo},
+  hidelinks,
+  pdfcreator={LaTeX via pandoc}}
+
+\title{R-on-Rails: ship the ledger on Rails, keep the science in R}
+\usepackage{etoolbox}
+\makeatletter
+\providecommand{\subtitle}[1]{% add subtitle to \maketitle
+  \apptocmd{\@title}{\par {\large #1 \par}}{}{}
+}
+\makeatother
+\subtitle{A portfolio stress tester that puts SQLite, Hotwire, and GNU R
+on one desk}
+\author{Rodrigo Botafogo}
+\date{2026}
+
+\begin{document}
+\maketitle
+
+{
+\setcounter{tocdepth}{2}
+\tableofcontents
+}
+\begin{center}\includegraphics[width=0.45\linewidth]{images/galaaz-lockup-stacked} \end{center}
+
+\section{Two audiences, one gap}\label{two-audiences-one-gap}
+
+\textbf{If you live in R}, you already have the hard part: VaR, density
+estimates, Monte Carlo, Bioconductor, the whole CRAN catalog. What is
+still painful is turning a notebook into a \textbf{product}---logins, a
+database, background jobs, a page that updates when the job finishes,
+and a deploy story that is not a pile of glue scripts.
+
+\textbf{If you live in Ruby on Rails}, you already have the product
+shell. What is still painful is serious statistics without standing up a
+Python microservice fleet, learning another ORM, and ferrying CSV files
+between processes.
+
+\textbf{R-on-Rails} is the name we give to a simple division of labor:
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{Rails} owns HTTP, Active Record, jobs, Hotwire, and the UX.
+\item
+  \textbf{GNU R} owns the math and the statistical vocabulary.
+\item
+  \textbf{\href{https://github.com/rbotafogo/galaaz}{Galaaz}} is the
+  bridge that makes R feel like a Ruby DSL---and moves bulky tables with
+  Apache Arrow when you need more than a few numbers.
+\end{itemize}
+
+This post walks through a real demo app---the
+\textbf{\href{https://github.com/rbotafogo/r_on_rails_ledger}{R-on-Rails
+Ledger}}--- so you can see the database, the calculators, and the charts
+on one page.
+
+\section{What the Ledger is}\label{what-the-ledger-is}
+
+The Ledger is a \textbf{family-office style portfolio stress tester} on
+\textbf{Rails 8}, \textbf{CRuby}, \textbf{SQLite}, \textbf{Solid Queue /
+Solid Cable}, and \textbf{Hotwire}. It is a sibling app to the Galaaz
+gem (not packaged inside the gem). One click runs two engines on the
+same portfolio return panel:
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{Engine A --- historical:} empirical VaR / expected shortfall /
+  return density from history (\texttt{R.quantile}, \texttt{R.mean},
+  \texttt{R.density}).
+\item
+  \textbf{Engine B --- Monte Carlo:} forward GBM paths calibrated to
+  that history, then forward VaR-style KPIs and a 30-day ``cone.''
+\end{itemize}
+
+Rails stores the book and the job results; R does the science; the
+browser gets Plotly charts from JSON that R (and a little Ruby)
+produced.
+
+\section{What's in Rails (and the
+database)}\label{whats-in-rails-and-the-database}
+
+The ``ledger'' here is a \textbf{portfolio price book}, not double-entry
+accounting:
+
+{\def\LTcaptype{none} % do not increment counter
+\begin{longtable}[]{@{}
+  >{\raggedright\arraybackslash}p{(\linewidth - 2\tabcolsep) * \real{0.5000}}
+  >{\raggedright\arraybackslash}p{(\linewidth - 2\tabcolsep) * \real{0.5000}}@{}}
+\toprule\noalign{}
+\begin{minipage}[b]{\linewidth}\raggedright
+Table
+\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
+Role
+\end{minipage} \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+\texttt{portfolios} & Named book (\texttt{name},
+\texttt{total\_value}) \\
+\texttt{assets} & Tickers + weights \\
+\texttt{historical\_prices} & Bars: \texttt{adjusted\_close},
+\texttt{daily\_return}, \ldots{} \\
+\texttt{stress\_tests} & Job status, scalar KPIs,
+\texttt{chart\_payload} JSON \\
+\texttt{stress\_test\_runs} & Per-engine (\texttt{historical} /
+\texttt{monte\_carlo}) payloads \\
+\end{longtable}
+}
+
+Seed data is \textbf{synthetic GBM} (honest demo data---not a live
+feed). \texttt{SEED\_PROFILE=fast} is laptop-friendly (\textasciitilde10
+assets x 2k bars); \texttt{SEED\_PROFILE=wow} is the ``about a million
+bars'' line.
+
+The click path is ordinary Rails:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{POST /portfolios/:id/stress\_tests}
+\NormalTok{  {-}\textgreater{} StressTestsController\#create}
+\NormalTok{  {-}\textgreater{} StressTestJob.perform\_later(...)}
+\NormalTok{  {-}\textgreater{} Risk::DualOrchestrator}
+\NormalTok{       |{-} Risk::HistoricalEngine}
+\NormalTok{       |{-} Risk::MonteCarloEngine}
+\NormalTok{  {-}\textgreater{} Turbo::StreamsChannel broadcast}
+\NormalTok{  {-}\textgreater{} results partial + Plotly redraw}
+\end{Highlighting}
+\end{Shaded}
+
+No React SPA. No Redis required for the demo. Development often runs the
+job \textbf{\texttt{:async}} in-process so one \texttt{bin/dev} is
+enough; Solid Queue stays in the Gemfile for production-shaped runs.
+
+\section{R calculators that read like
+Ruby}\label{r-calculators-that-read-like-ruby}
+
+After returns land in R (via Arrow---see below), the historical engine
+exposes small methods that call R the way Galaaz intends: \textbf{named
+functions and vectors}, not a wall of quoted R source for every KPI.
+
+From the Ledger's \texttt{Risk::HistoricalEngine} (abbreviated):
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\ControlFlowTok{def}\NormalTok{ historical\_var(returns\_vec, probs}\OperatorTok{:}\NormalTok{)}
+  \DataTypeTok{RValues}\AttributeTok{.scalar\_f}\NormalTok{(}
+    \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+      \ConstantTok{R}\AttributeTok{.quantile}\NormalTok{(returns\_vec,}
+                 \WarningTok{probs:}\NormalTok{ probs,}
+                 \WarningTok{names:} \DecValTok{false}\NormalTok{,}
+                 \WarningTok{type:} \DecValTok{7}\NormalTok{)}
+\NormalTok{    )}
+\NormalTok{  )}
+\ControlFlowTok{end}
+
+\ControlFlowTok{def}\NormalTok{ expected\_shortfall(returns\_vec, var\_level)}
+\NormalTok{  thr }\OperatorTok{=}\NormalTok{ var\_level}\AttributeTok{.is\_a?}\NormalTok{(}\DataTypeTok{Numeric}\NormalTok{) }\OperatorTok{?}
+\NormalTok{    var\_level }\OperatorTok{:} \DataTypeTok{RValues}\AttributeTok{.scalar\_f}\NormalTok{(var\_level)}
+  \DataTypeTok{RValues}\AttributeTok{.scalar\_f}\NormalTok{(}
+    \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+      \ConstantTok{R}\AttributeTok{.mean}\NormalTok{(returns\_vec}\KeywordTok{[}\NormalTok{returns\_vec }\OperatorTok{\textless{}=}\NormalTok{ thr}\KeywordTok{]}\NormalTok{)}
+\NormalTok{    )}
+\NormalTok{  )}
+\ControlFlowTok{end}
+
+\ControlFlowTok{def}\NormalTok{ return\_density(returns\_vec, n}\OperatorTok{:} \DecValTok{128}\NormalTok{)}
+  \DataTypeTok{ArrowHandoff}\AttributeTok{.density\_xy\_for\_plotly}\NormalTok{(returns\_vec, }\WarningTok{n:}\NormalTok{ n)}
+\ControlFlowTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+That is the pitch for Ruby developers: \texttt{R.quantile} is a method
+call. For R developers: the quantile is still \textbf{R's}
+quantile---same \texttt{type\ =\ 7} story you know---just invoked from
+the app that owns the database.
+
+A tiny live taste of the same idea (outside Rails):
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{x }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.c}\NormalTok{(}\OperatorTok{{-}}\FloatTok{0.02}\NormalTok{, }\OperatorTok{{-}}\FloatTok{0.01}\NormalTok{, }\FloatTok{0.0}\NormalTok{, }\FloatTok{0.01}\NormalTok{, }\FloatTok{0.015}\NormalTok{, }\OperatorTok{{-}}\FloatTok{0.005}\NormalTok{)}
+\NormalTok{q05 }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+  \ConstantTok{R}\AttributeTok{.quantile}\NormalTok{(x, }\WarningTok{probs:} \FloatTok{0.05}\NormalTok{, }\WarningTok{names:} \DecValTok{false}\NormalTok{, }\WarningTok{type:} \DecValTok{7}\NormalTok{))}
+\FunctionTok{puts} \StringTok{"5\% quantile: }\SpecialCharTok{\#\{}\NormalTok{q05 }\OperatorTok{\textgreater{}\textgreater{}} \DecValTok{0}\SpecialCharTok{\}}\StringTok{"}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## 5% quantile: -0.017499999999999998
+\end{verbatim}
+
+Engine B calibrates mu/sigma in R, simulates GBM paths, and returns
+structured fields (\texttt{sim\_var\_30d}, sample paths, terminal
+density) that Rails stores on each run's \texttt{payload} JSON.
+
+\section{How data moves (Arrow,
+honestly)}\label{how-data-moves-arrow-honestly}
+
+Crossing a process boundary means you must be honest about
+\textbf{copies}. Galaaz can move columnar data with Apache Arrow in
+three ways:
+
+\begin{enumerate}
+\def\labelenumi{\arabic{enumi}.}
+\tightlist
+\item
+  \textbf{Copy into R} --- Ruby builds batches; R materialises an Arrow
+  table / proxy. Simple and available today.
+\item
+  \textbf{IPC file handoff} --- Ruby writes an Arrow IPC file (often
+  under \texttt{/dev/shm}); R opens it by \textbf{path}. Only the path
+  crosses NewBridge---not megabytes of MsgPack. This is what the Ledger
+  prefers for the return panel.
+\item
+  \textbf{Shared-memory zero-copy} --- both processes attach to one live
+  segment. \textbf{Not implemented yet}; we do not claim it.
+\end{enumerate}
+
+\subsection{Example: copy into R}\label{example-copy-into-r}
+
+Good when the table is modest or you do not have a Ruby Arrow writer
+installed. One call builds the R-side table; then you Remote-Control it.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{arrow\_ok }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Support}\AttributeTok{.eval}\NormalTok{(}
+  \StringTok{"requireNamespace(\textquotesingle{}arrow\textquotesingle{}, quietly=TRUE)"}\NormalTok{) }\OperatorTok{==} \DecValTok{true}
+\ControlFlowTok{unless}\NormalTok{ arrow\_ok}
+  \FunctionTok{puts} \VerbatimStringTok{\textquotesingle{}(Skip: need R package arrow.)\textquotesingle{}}
+\ControlFlowTok{else}
+\NormalTok{  batches }\OperatorTok{=} \KeywordTok{[}
+    \KeywordTok{[}\OperatorTok{\{} \WarningTok{daily\_return:} \OperatorTok{{-}}\FloatTok{0.01} \OperatorTok{\}}\NormalTok{, }\OperatorTok{\{} \WarningTok{daily\_return:} \FloatTok{0.02} \OperatorTok{\}}\KeywordTok{]}\NormalTok{,}
+    \KeywordTok{[}\OperatorTok{\{} \WarningTok{daily\_return:} \FloatTok{0.005} \OperatorTok{\}}\NormalTok{, }\OperatorTok{\{} \WarningTok{daily\_return:} \OperatorTok{{-}}\FloatTok{0.003} \OperatorTok{\}}\KeywordTok{]}
+  \KeywordTok{]}
+\NormalTok{  tbl }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Arrow}\AttributeTok{.from\_ruby\_batches}\NormalTok{(batches)}
+  \FunctionTok{puts} \StringTok{"R class: }\SpecialCharTok{\#\{}\NormalTok{tbl}\AttributeTok{.rclass}\SpecialCharTok{\}}\StringTok{"}
+\NormalTok{  vec }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+    \ConstantTok{R}\AttributeTok{.dplyr\_\_\_collect}\NormalTok{(tbl)}\KeywordTok{[[}\VerbatimStringTok{\textquotesingle{}daily\_return\textquotesingle{}}\KeywordTok{]]}\NormalTok{)}
+\NormalTok{  q05 }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+    \ConstantTok{R}\AttributeTok{.quantile}\NormalTok{(vec, }\WarningTok{probs:} \FloatTok{0.05}\NormalTok{, }\WarningTok{names:} \DecValTok{false}\NormalTok{, }\WarningTok{type:} \DecValTok{7}\NormalTok{))}
+  \FunctionTok{puts} \StringTok{"5\% quantile: }\SpecialCharTok{\#\{}\NormalTok{q05 }\OperatorTok{\textgreater{}\textgreater{}} \DecValTok{0}\SpecialCharTok{\}}\StringTok{"}
+\ControlFlowTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## R class: Table
+## 5% quantile: -0.00895
+\end{verbatim}
+
+The Ledger's fallback path is similar: a small \texttt{data.frame} plus
+\texttt{R::Arrow.table\_from(df)} when IPC is unavailable.
+
+\subsection{Example: IPC file handoff}\label{example-ipc-file-handoff}
+
+Preferred for larger same-machine panels. Ruby writes the file; R opens
+by path; Ruby can unlink after R has the table. The reverse direction
+(\texttt{R::Arrow.write\_ipc} then \texttt{Galaaz::ArrowIpc.read}) is
+how the Ledger can pull density coordinates back for Plotly.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{ipc\_ok }\OperatorTok{=} \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.available?} \OperatorTok{\&\&}
+\NormalTok{  (}\ConstantTok{R}\OperatorTok{::}\DataTypeTok{Support}\AttributeTok{.eval}\NormalTok{(}
+    \StringTok{"requireNamespace(\textquotesingle{}arrow\textquotesingle{}, quietly=TRUE)"}\NormalTok{) }\OperatorTok{==} \DecValTok{true}\NormalTok{)}
+\ControlFlowTok{unless}\NormalTok{ ipc\_ok}
+  \FunctionTok{puts} \VerbatimStringTok{\textquotesingle{}(Skip: need Arrow IPC backend + R arrow.)\textquotesingle{}}
+\ControlFlowTok{else}
+\NormalTok{  returns }\OperatorTok{=} \KeywordTok{[}\OperatorTok{{-}}\FloatTok{0.01}\NormalTok{, }\FloatTok{0.02}\NormalTok{, }\FloatTok{0.005}\NormalTok{, }\OperatorTok{{-}}\FloatTok{0.003}\NormalTok{, }\OperatorTok{{-}}\FloatTok{0.008}\KeywordTok{]}
+\NormalTok{  path }\OperatorTok{=} \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.write}\NormalTok{(}
+    \VerbatimStringTok{\textquotesingle{}daily\_return\textquotesingle{}} \OperatorTok{=\textgreater{}}\NormalTok{ returns}\AttributeTok{.map}\NormalTok{(}\OperatorTok{\&}\WarningTok{:to\_f}\NormalTok{))}
+  \ControlFlowTok{begin}
+\NormalTok{    tbl }\OperatorTok{=} \ConstantTok{R}\OperatorTok{::}\DataTypeTok{Arrow}\AttributeTok{.open\_ipc}\NormalTok{(path)}
+    \FunctionTok{puts} \StringTok{"R class: }\SpecialCharTok{\#\{}\NormalTok{tbl}\AttributeTok{.rclass}\SpecialCharTok{\}}\StringTok{"}
+    \FunctionTok{puts} \StringTok{"IPC: }\SpecialCharTok{\#\{}\DataTypeTok{File}\AttributeTok{.basename}\NormalTok{(path)}\SpecialCharTok{\}}\StringTok{"}
+\NormalTok{    vec }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+      \ConstantTok{R}\AttributeTok{.dplyr\_\_\_collect}\NormalTok{(tbl)}\KeywordTok{[[}\VerbatimStringTok{\textquotesingle{}daily\_return\textquotesingle{}}\KeywordTok{]]}\NormalTok{)}
+\NormalTok{    q05 }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.as\_\_numeric}\NormalTok{(}
+      \ConstantTok{R}\AttributeTok{.quantile}\NormalTok{(vec, }\WarningTok{probs:} \FloatTok{0.05}\NormalTok{, }\WarningTok{names:} \DecValTok{false}\NormalTok{, }\WarningTok{type:} \DecValTok{7}\NormalTok{))}
+    \FunctionTok{puts} \StringTok{"5\% quantile: }\SpecialCharTok{\#\{}\NormalTok{q05 }\OperatorTok{\textgreater{}\textgreater{}} \DecValTok{0}\SpecialCharTok{\}}\StringTok{"}
+  \ControlFlowTok{ensure}
+    \DataTypeTok{Galaaz}\OperatorTok{::}\DataTypeTok{ArrowIpc}\AttributeTok{.release}\NormalTok{(path)}
+  \ControlFlowTok{end}
+\ControlFlowTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## R class: Table
+## IPC: galaaz_ipc_34399_93fe645f9fa9172f.arrow
+## 5% quantile: -0.0096
+\end{verbatim}
+
+Then the product rule is \textbf{Remote Control}: keep the heavy panel
+in R; unbox \textbf{KPIs and chart coordinates} back to Ruby for SQLite
+and the browser.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{SQLite {-}\textgreater{} portfolio return series (Ruby)}
+\NormalTok{      {-}\textgreater{} Arrow IPC file (path on the bridge)}
+\NormalTok{      {-}\textgreater{} GNU R (quantile / density / GBM)}
+\NormalTok{      {-}\textgreater{} JSON{-}ish payloads on SQLite}
+\NormalTok{      {-}\textgreater{} Turbo Stream {-}\textgreater{} Stimulus {-}\textgreater{} Plotly.js}
+\end{Highlighting}
+\end{Shaded}
+
+\section{The page with the charts}\label{the-page-with-the-charts}
+
+After a Local R stress test, the portfolio show page replaces the
+results panel in place. Captures below are from a live run of the demo
+(synthetic seed, Local engines, Plotly in the browser---\textbf{not}
+ggplot2 SVG).
+
+\subsection{Side-by-side KPIs}\label{side-by-side-kpis}
+
+Engine A is \textbf{1-day historical} VaR. Engine B is \textbf{30-day
+forward} Monte Carlo. The UI says so on purpose: compare directionally,
+not as identical metrics.
+
+\begin{figure}
+\includegraphics[width=1\linewidth]{images/01_results_panel} \caption{Ledger results panel: Local R runtime banner, KPI table, and three Plotly charts.}\label{fig:fig_panel}
+\end{figure}
+
+\subsection{Density and tail risk}\label{density-and-tail-risk}
+
+Historical kernel density from Engine A, Monte Carlo terminal-return
+density from Engine B, with VaR markers as vertical lines.
+
+\begin{figure}
+\includegraphics[width=1\linewidth]{images/02_density_tail_risk} \caption{Density and tail risk (Plotly): historical vs Monte Carlo terminal returns.}\label{fig:fig_density}
+\end{figure}
+
+\subsection{Thirty-day Monte Carlo
+cone}\label{thirty-day-monte-carlo-cone}
+
+Sample paths, a 5--95\% band, median, and baseline---forward uncertainty
+as a picture, not only a scalar.
+
+\begin{figure}
+\includegraphics[width=1\linewidth]{images/03_mc_cone} \caption{30-day Monte Carlo cone (Plotly): paths, median, and 5–95\% band.}\label{fig:fig_cone}
+\end{figure}
+
+\subsection{Rolling historical VaR and
+breaches}\label{rolling-historical-var-and-breaches}
+
+Trailing returns against a rolling 95\% VaR line, with breach markers
+when returns punch through the threshold.
+
+\begin{figure}
+\includegraphics[width=1\linewidth]{images/04_rolling_var} \caption{Rolling historical VaR and breaches (Plotly).}\label{fig:fig_rolling}
+\end{figure}
+
+\section{Why this is a production-shaped
+story}\label{why-this-is-a-production-shaped-story}
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{One desk.} Rails conventions for the app; CRAN for the
+  science.
+\item
+  \textbf{Jobs, not request-thread math.} Stress work runs in
+  \texttt{StressTestJob}; the UI waits on Turbo/Cable.
+\item
+  \textbf{Process isolation.} GNU R is a separate process (NewBridge). A
+  bad R call need not take down Puma.
+\item
+  \textbf{Optional dual-version R.} The same job can target Docker
+  images (e.g.~R 3.6.3 \textbar\textbar{} 4.3.3) when you want version
+  isolation; Local alone still tells the Arrow + DSL story.
+\item
+  \textbf{OnRails family.} Ruby on Rails -\textgreater{} Omarchy /
+  LinuxOnRails -\textgreater{} \textbf{R-on-Rails}---same ``one person
+  can ship the whole product'' energy, applied to people whose science
+  already lives in R.
+\end{itemize}
+
+\section{Try it}\label{try-it}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{git}\NormalTok{ clone https://github.com/rbotafogo/r\_on\_rails\_ledger.git}
+\BuiltInTok{cd}\NormalTok{ r\_on\_rails\_ledger}
+\ExtensionTok{bundle}\NormalTok{ install}
+\ExtensionTok{bin/rails}\NormalTok{ db:prepare}
+\VariableTok{SEED\_PROFILE}\OperatorTok{=}\NormalTok{fast }\ExtensionTok{bin/rails}\NormalTok{ db:seed}
+\ExtensionTok{bin/dev}
+\CommentTok{\# open http://localhost:3000 {-}\textgreater{} portfolio {-}\textgreater{} Run stress test}
+\end{Highlighting}
+\end{Shaded}
+
+With a Galaaz checkout nearby, \texttt{galaaz\ add\ ledger} (Omarchy /
+CLI helper) can clone and boot the same demo. In-app docs live at
+\texttt{/docs} (architecture, Ruby DSL excerpts, runbook).
+
+For the bridge itself---JRuby/CRuby, Arrow handoffs,
+\texttt{R::Job}---see the companion post \textbf{Galaaz 2.0} in this
+blog series.
+
+\section{Honest limits}\label{honest-limits}
+
+\begin{itemize}
+\tightlist
+\item
+  Seed prices are \textbf{synthetic}, not broker data.
+\item
+  VaR / GBM here are a \textbf{demo risk stack}, not a bank production
+  engine (no full PerformanceAnalytics suite in the live path).
+\item
+  Charts are \textbf{Plotly.js} fed by JSON coordinates---not ggplot
+  embedded as SVG in this build.
+\item
+  The Ledger's Arrow path is an \textbf{IPC file / mmap handoff}, not
+  shared Ruby/R heap memory (zero-copy is still future work).
+\item
+  Historical and Monte Carlo \textbf{horizons differ}; the KPI footnotes
+  exist so the demo does not oversell a single number.
+\end{itemize}
+
+The point of honesty is the same as the point of the architecture: Rails
+can be the product, R can stay R, and you can show the charts without
+pretending the hard parts vanished.
+
+\end{document}