galaaz 2.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36c8fe0bf29440d8d32a8db947e498218fa0faf56101e7de7cce13617b55e8e3
-  data.tar.gz: cdb7054da85e241919d2ed286b8371a57eb893e9011991df8818823919748cf0
+  metadata.gz: 671c2fe1fb15dbd12a7f491e52c318d01ebe9625e78d9acdaaa3dffbe3efbd3d
+  data.tar.gz: 2d4d63f915f0b8a09cff53df98802f7bcaff0298f9247ef38b583b2a0e902730
 SHA512:
-  metadata.gz: 2d4503d53a53e77401eef84f0fadd7c7ab91d4b4a8e5ba95079947b96f8cea7b3438e3b312f1a2da4687729abc90a48c2644a4f5c501c3b050896897a8b98b13
-  data.tar.gz: f6c8fb1df8558f06c6149fadcc4af865af56afc0805e852b367d2b90ca110e8d062b14696112c28689947f17ee6a45c6ca02be669fb6a875bb18c9c74d77ce93
+  metadata.gz: 1dc8f434731a05f495909d5f8bc70949f7ec7ae8034fbe8dd6a026f6b9592d426d573dffc0f13326ddfb7c830112bd6922fcdb8ca717e091d8722e219ea43de6
+  data.tar.gz: d594128365977ac52a3a2d15f6e3dd5f1b97ee312c0c6232883f6fb8838fb7c1440f2272c3302e53853026befd7e625f6e4124a8d3ddd32959f7bf665cb8cda7

data/CHANGELOG.md

@@ -1,26 +1,64 @@
 # Changelog
 
+## 2.1.1
+
+### Added
+
+- CLI on `bin/galaaz`: `setup`, `blogs init`, `doctor`, `add` (knit / arrow / tex / bio /
+  examples / ledger / demo). Legacy unknown args still forward to rake.
+- Omarchy dogfood helpers under `script/omarchy/` (install/remove scripts + menu overlay).
+- `galaaz doctor` reports both CRuby and JRuby when available (mise-aware).
+- Package lists `r_requires/knit.txt`, `knit-extras.txt`, `arrow.txt` for add-on installs.
+- Cold-install CRuby path uses `galaaz setup` + `galaaz blogs init`.
+
+### Notes
+
+- Omarchy / stranger install remains `gem install galaaz` then `galaaz setup` (no
+  `bundle install` for core use). See `Documentation/PLAN_OMARCHY_INTEGRATION.md`.
+
+## 2.1.0
+
+Galaaz **2.1** keeps the **galaaz2_0** integration line as the main development branch and marks
+**CRuby + JRuby** NewBridge support as a released milestone (R-on-Rails positioning).
+
+### Added
+
+- First-class **CRuby** NewBridge path alongside JRuby (engine-aware launchers, cold-install /
+  CI coverage for both).
+- Docs: treat JRuby and CRuby as equal supported runtimes for the bridge.
+- [Documentation/ROADMAP_ARROW_RUBY_R.md](Documentation/ROADMAP_ARROW_RUBY_R.md) — stages A (copy),
+  B1/B2 (IPC/mmap file; shipped), C (shared-memory bus; future).
+- Stage **B1/B2** APIs: `Galaaz::ArrowIpc`, `R::Arrow.open_ipc`, `R::Arrow.write_ipc` (CRuby
+  red-arrow + system Arrow GLib; JRuby Arrow Java + `JAVA_OPTS` nio opens).
+
+### Notes
+
+- Git branch **`galaaz2_0`** remains the integration branch name; the gem version is **2.1.0**.
+- Apache Arrow **zero-copy shared RAM** (Stage C) is still future work. Stage A copies into R;
+  Stage B uses an IPC file and only the path crosses NewBridge. See the roadmap.
+
 ## 2.0.0
 
-Galaaz 2.0 drives **GNU R** from **JRuby** over a process bridge. It is not the older GraalVM / TruffleRuby / FastR stack, and it does not embed Renjin. Developed and tested on **JRuby 10.1.1.0** (Ruby 4.0) with **Java 21**.
+Galaaz 2.0 drives **GNU R** from **JRuby** or **CRuby** over a process bridge. It is not the older GraalVM / TruffleRuby / FastR stack, and it does not embed Renjin. Both Rubies are supported for NewBridge (tested on **JRuby 10.1.1.0** with **Java 21**, and **CRuby 3.3.12**).
 
 ### Added
 
-- NewBridge: JRuby talks to standard GNU R (CRAN / Bioconductor, including compiled packages).
+- NewBridge: Ruby talks to standard GNU R (CRAN / Bioconductor, including compiled packages).
 - Native gatekeeper under `ext/new_bridge` (Rcpp / C++); compile after install with `make -C ext/new_bridge all`.
 - Optional Apache Arrow helpers for large tables on the R side.
 - Rendered manuals, blogs, and examples on [GitHub Pages](https://rbotafogo.github.io/galaaz/).
-- Ubuntu cold-install proof (`docker/cold-install`) and GitHub Actions CI for the fast suite plus that image.
+- Ubuntu cold-install proof (`docker/cold-install` for JRuby, `docker/cold-install-cruby` for CRuby) and GitHub Actions CI for the fast suite on both engines plus those images.
+- Engine-aware launchers (`GALAAZ_RUBY`, `bin/galaaz-ruby`) so the same NewBridge runs under JRuby or CRuby.
 
 ### Changed
 
 - The gem ships sources, specs, and examples; it does not pack prebuilt `.so` objects or knitted HTML/PDF.
-- The supported install is `jruby -S gem install galaaz`, then compile the gatekeeper (see the README). A git clone is for contributors.
+- The supported install is `gem install galaaz` (under JRuby or CRuby), then compile the gatekeeper (see the README). A git clone is for contributors.
 
 ### Known limits
 
 - Primary targets are Linux (x86_64) and macOS; on Windows use WSL2. Native Windows is not supported.
-- `grun`, `gknit_Rscript`, and the polyglot path in `gknit-draft` are leftover from the Graal era; use `galaaz-jruby` / `gknit`.
+- `grun`, `gknit_Rscript`, and the polyglot path in `gknit-draft` are leftover from the Graal era; use `galaaz-jruby` / `gknit` (or `GALAAZ_RUBY=ruby` for CRuby).
 - The gatekeeper must be compiled on the install machine (Rcpp + C++ toolchain); it is not a prebuilt binary in the gem.
 - Multi-runtime Docker R (Phase 4.5) is a slow integration spec, not part of cold-install CI.
 - The gknit installation-timeout spec is skipped pending a dedicated pass; SimpleCov is a development gem and is not installed in the smoke image.

data/README.md

@@ -1,8 +1,8 @@
 ---
 title: "Galaaz Manual"
-subtitle: "Coupling Ruby (JRuby) and GNU R for data science"
+subtitle: "R-on-Rails: GNU R meets Ruby for the web"
 author: "Rodrigo Botafogo"
-tags: [Galaaz, Ruby, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
+tags: [Galaaz, "R-on-Rails", Ruby, Rails, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow]
 date: "2026"
 bibliography: "../../examples/Bibliography/stats.bib"
 output:
@@ -28,64 +28,66 @@ fontsize: 11pt
 
 # Introduction
 
-Galaaz is a system for tightly coupling Ruby and R. Ruby is a powerful language, with a large 
-community, a very large set of libraries and great for web development. However, it lacks 
-libraries for data science, statistics, scientific plotting and machine learning. On the 
-other hand, R is considered one of the most powerful languages for solving all of the above 
-problems. **Python** is a strong competitor: NumPy, pandas, SciPy, and scikit-learn are
-widely used building blocks, and **PyPI** hosts many thousands of other packages for
-numerical work, machine learning, and beyond.
-
-With Galaaz we do not intend to re-implement any of the scientific libraries in R, we allow
-for very tight coupling between the two languages to the point that the Ruby developer does
-not need to know that there is an R engine running.
-
-According to Wikipedia "Ruby is a dynamic, interpreted, reflective, object-oriented, 
-general-purpose programming language. It was designed and developed in the mid-1990s by Yukihiro 
-"Matz" Matsumoto in Japan."  It reached high popularity with the development of Ruby on Rails
-(RoR) by David Heinemeier Hansson. RoR is a web application framework first released
-around 2005. It makes extensive use of Ruby's metaprogramming features.  With RoR,
-Ruby became very popular.  According to [Ruby’s place in the TIOBE index](https://www.tiobe.com/tiobe-index/ruby/)
-it peaked in popularity around 2008, then declined until 2015 when it started picking up again.
-Ruby remains a significant language in web development and general-purpose scripting.
-
-Python, a language similar to Ruby, ranks 4th in the index.  Java, C and C++ take the
-first three positions.  Ruby is often criticized for its focus on web applications.
-But Ruby can do [much more](https://github.com/markets/awesome-ruby) than just web applications.
-Yet, for scientific computing, Ruby lags behind Python and R.  Python offers Django and
-similar frameworks for the web, plus NumPy, pandas, and a deep catalog of science and ML libraries.
-R is a free software environment for statistical computing and graphics with thousands
-of libraries for data analysis. 
-
-Until recently, there was no real perspective for Ruby to bridge this gap.
-Implementing a complete scientific computing infrastructure would take too long.
-
-**Galaaz 2.0** couples **JRuby** (Ruby on the JVM) with **GNU R**—the same R you use for
-CRAN and Bioconductor. Ruby and R run in **separate processes**; the **Galaaz bridge**
-sends requests to R and returns results to Ruby. From your point of view you still write
-Ruby: `R.c(...)`, `R.library('ggplot2')`, `~R[:mtcars]`, and dplyr-style chains on R objects.
-You do not need to learn R syntax to get a lot done, though reading R documentation for
-individual packages remains useful.
-
-Earlier experiments with Galaaz used Oracle’s **GraalVM** with TruffleRuby and FastR so that
-Ruby and R could share one runtime. That path is no longer the focus: **standard GNU R**
-gives full compatibility with the R package ecosystem (including compiled extensions and
-Bioconductor) while JRuby gives a mature Ruby with **real multithreading** for application
-and I/O code.
-
-The bridge handles **communication and typing** between the two worlds; large tables can
-also flow through **Apache Arrow** on the R side when you use the optional helpers described
-later in this manual.
-
-Library wrapping is a common way to bring features from one language into another.
-To improve performance, Python often wraps more efficient C libraries. For the
-Python developer, the existence of such C libraries is hidden.  The problem with
-library wrapping is that for any new library, there is the need to handcraft a new
-wrapper.
-
-Galaaz, instead of wrapping a single C or R library, wraps the whole R language
-in Ruby.  Doing so, all thousands of R libraries are available immediately
-to Ruby developers without any new wrapping effort.
+**Galaaz is R-on-Rails:** keep **GNU R** for statistics, graphics, and the CRAN /
+Bioconductor ecosystem, and use **Ruby** (with **Rails** when you need a web app) for
+everything R was never meant to own—HTTP, auth, databases, background jobs, HTML, APIs.
+
+The primary audience is the **R scientist** who already has models, dplyr/ggplot pipelines,
+and domain knowledge, and wants a **one-person path to production on the web**. Learning
+enough Ruby and Rails to ship an app is usually easier than hiring (or becoming) a dedicated
+web-and-stats dual specialist. Ruby developers gain full access to R libraries as a
+secondary benefit; the design priority is **R workflow first, web second**.
+
+Galaaz does **not** re-implement scientific libraries in Ruby. Ruby and R run in **separate
+processes**; the **Galaaz bridge** sends requests to standard **GNU R** and returns typed
+results. You keep calling familiar ideas from Ruby (`R.c(...)`, `R.library('ggplot2')`,
+`~R[:mtcars]`, dplyr-style chains) while Rails (or plain Ruby) owns the application shell.
+
+**Python** remains a strong competitor for end-to-end data science stacks (NumPy, pandas,
+SciPy, scikit-learn, Django/Flask). Galaaz’s bet is different: if your science already lives
+in **R**, do not rewrite it in Python to get a website—**put R on Rails**.
+
+Ruby is a dynamic, object-oriented language that became widely known through **Ruby on Rails**
+(RoR). It remains a practical choice for web applications and general-purpose scripting.
+Until Galaaz, Ruby lacked a tight, ecosystem-complete bridge to GNU R. Library wrapping
+(one gem per package) does not scale; Galaaz wraps **the R language**, so thousands of R
+packages are available without a new handcrafted wrapper for each one.
+
+**Galaaz 2.0** supports **JRuby** and **CRuby** equally for the same NewBridge protocol.
+Pick the Ruby that fits your app: JRuby when you want real multithreading for web and I/O;
+CRuby when you prefer MRI. R remains the same **GNU R** you use interactively—including
+compiled extensions and Bioconductor. Earlier GraalVM / TruffleRuby / FastR experiments
+are no longer the focus.
+
+The bridge handles **communication and typing** between the two worlds. Large tables can use
+**Apache Arrow** in two shipped modes (described later): **Stage A** copies Ruby batches into an
+R-side Arrow table (`R::Arrow.from_ruby_batches`); **Stage B** writes an Arrow IPC file and only
+the **path** crosses NewBridge (`Galaaz::ArrowIpc` + `R::Arrow.open_ipc` / `write_ipc`). Shared-heap
+zero-copy is **Stage C** and is not shipped.
+
+## R-on-Rails: the one-person app for R scientists
+
+If you already think in R, the usual web options are painful: Shiny for some apps, or a full
+rewrite in another stack. **R-on-Rails** means:
+
+1. **Keep your science in R** — packages, formulas, plots, Bioconductor, the same engine as RStudio.
+2. **Learn enough Ruby/Rails** — routes, controllers, views, jobs, auth—not a second statistics career.
+3. **Call R from the app** — Galaaz loads R behind the scenes; long jobs can complete asynchronously
+   while Rails stays responsive (see later sections on the bridge and `R::Async`).
+4. **Ship alone when you need to** — one developer can own both the analysis and the product UI,
+   without waiting for a separate “stats engineer” and “Rails engineer.”
+
+Typical shape:
+
+- Interactive exploration and reports: **gstudio**, **gknit** (R Markdown with Ruby chunks).
+- Product: a **Rails** (or Sinatra) app that calls `R.*` for the heavy statistical steps.
+- Scale for many users: more **R worker processes/containers** behind the app (R is single-threaded
+   per process); the Ruby web tier scales separately (JRuby threads or a multi-process CRuby
+   setup). Galaaz’s instance manager is the starting point for that pattern—not a rewrite of
+   every algorithm à la enterprise ScaleR.
+
+Rubyists are welcome: the same bridge exposes CRAN to application code. The **intended** on-ramp,
+though, is **R scientist → small Rails app**, not “hire a stats team to teach Rails developers R.”
 
 ## What does Galaaz mean
 
@@ -108,10 +110,11 @@ The Galaaz repository ships many helpers under **`bin/`**. When working from a *
 them as **`bin/<name>`** from the project root (or `./bin/<name>`). If you install the **gem**,
 only a subset is guaranteed on your `PATH` (see the gemspec: **`galaaz`**, **`gstudio`**, **`gknit`**, **`grun`**, **`gknit-draft`**); for development and CI, prefer the **`bin/`** copies so JVM flags and paths stay correct.
 
-Below, **current (Galaaz 2.0 + JRuby + GNU R)** means the tool is wired to **`jruby`** and
-**`bin/galaaz_jruby_env.inc.sh`** (or equivalent logic in Ruby via `lib/galaaz_jruby.rb`). **Legacy**
-means the script still targets **GraalVM** polyglot Ruby / FastR-era invocation and is **not**
-expected to work on a typical JRuby-only setup.
+Below, **current (Galaaz 2.0 + JRuby or CRuby + GNU R)** means the tool uses **`bin/galaaz-ruby`**
+/ **`GALAAZ_RUBY`** (default: `ruby` on `PATH`) and applies JVM flags only when the interpreter is
+JRuby (`bin/galaaz_jruby_env.inc.sh` / `lib/galaaz_jruby.rb`). **`bin/galaaz-jruby`** forces JRuby.
+**Legacy** means the script still targets **GraalVM** polyglot Ruby / FastR-era invocation and is
+**not** expected to work on a typical JRuby or CRuby NewBridge setup.
 
 **Table layout:** names in the first column are **`bin/`** filenames (run as `bin/<name>` from the repo root). Long options and examples sit **outside** the tables so PDF columns stay readable.
 
@@ -131,14 +134,24 @@ expected to work on a typical JRuby-only setup.
    <td style="text-align:left;"> WSL2 helper: Docker checks; optional TinyTeX or poppler for gKnit PDF. </td>
    <td style="text-align:left;"> Yes* </td>
   </tr>
+  <tr>
+   <td style="text-align:left;"> galaaz-ruby </td>
+   <td style="text-align:left;"> Selected Ruby (default: ruby on PATH) with repo lib/ on LOAD_PATH; JVM flags only on JRuby. </td>
+   <td style="text-align:left;"> Yes </td>
+  </tr>
   <tr>
    <td style="text-align:left;"> galaaz-jruby </td>
-   <td style="text-align:left;"> JRuby with repo lib/ on LOAD_PATH and required JVM flags (e.g. Arrow). </td>
+   <td style="text-align:left;"> Thin wrapper that forces JRuby (same flags as galaaz-ruby under JRuby). </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
+  <tr>
+   <td style="text-align:left;"> galaaz_ruby_env.inc.sh </td>
+   <td style="text-align:left;"> Sourced by bash wrappers; sets GALAAZ_RUBY_BIN and optional JVM args. </td>
+   <td style="text-align:left;"> Yes† </td>
+  </tr>
   <tr>
    <td style="text-align:left;"> galaaz_jruby_env.inc.sh </td>
-   <td style="text-align:left;"> Sourced by bash wrappers; sets GALAAZ_REQUIRED_JRUBY_J_ARGS. </td>
+   <td style="text-align:left;"> Sourced when the interpreter is JRuby; sets GALAAZ_REQUIRED_JRUBY_J_ARGS. </td>
    <td style="text-align:left;"> Yes† </td>
   </tr>
   <tr>
@@ -153,11 +166,13 @@ expected to work on a typical JRuby-only setup.
 
 † Not run directly.
 
-**`galaaz-jruby` examples** (from repo root):
+**`galaaz-ruby` / `galaaz-jruby` examples** (from repo root):
 
 ```text
+bin/galaaz-ruby my_script.rb
+GALAAZ_RUBY=jruby bin/galaaz-ruby my_script.rb
 bin/galaaz-jruby my_script.rb
-bin/galaaz-jruby -S rspec
+bin/galaaz-ruby -S rspec
 ```
 
 ## Interactive use, examples, and Rake
@@ -173,17 +188,17 @@ bin/galaaz-jruby -S rspec
 <tbody>
   <tr>
    <td style="text-align:left;"> gstudio </td>
-   <td style="text-align:left;"> IRB or Pry with Galaaz preloaded (JRuby + JVM flags). </td>
+   <td style="text-align:left;"> IRB or Pry with Galaaz preloaded (ruby on PATH; JVM flags on JRuby). </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
    <td style="text-align:left;"> run_example </td>
-   <td style="text-align:left;"> Run one Ruby file using the same JRuby/JVM setup as tests. </td>
+   <td style="text-align:left;"> Run one Ruby file using the same Ruby/JVM setup as tests. </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
    <td style="text-align:left;"> galaaz </td>
-   <td style="text-align:left;"> Forward arguments to rake (needs rake; usually JRuby). </td>
+   <td style="text-align:left;"> Forward arguments to rake (needs rake; same GALAAZ_RUBY as other launchers). </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
 </tbody>
@@ -202,7 +217,7 @@ bin/galaaz-jruby -S rspec
 <tbody>
   <tr>
    <td style="text-align:left;"> gknit </td>
-   <td style="text-align:left;"> Knit .Rmd via JRuby and R Markdown render. </td>
+   <td style="text-align:left;"> Knit .Rmd via ruby on PATH (JRuby or CRuby) and R Markdown render. </td>
    <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
@@ -212,8 +227,8 @@ bin/galaaz-jruby -S rspec
   </tr>
   <tr>
    <td style="text-align:left;"> gknit-draft.rb </td>
-   <td style="text-align:left;"> Ruby entry: GKnit.draft (use with JRuby + LOAD_PATH). </td>
-   <td style="text-align:left;"> JRuby </td>
+   <td style="text-align:left;"> Ruby entry: GKnit.draft (use with galaaz-ruby + LOAD_PATH). </td>
+   <td style="text-align:left;"> Yes </td>
   </tr>
   <tr>
    <td style="text-align:left;"> gknit_Rscript </td>
@@ -290,21 +305,23 @@ Prefer **`galaaz-jruby`** for **`gknit-draft`** workflows until that wrapper mat
 </tbody>
 </table>
 
-For day-to-day **2.0** use, rely on **`bin/galaaz-jruby`**, **`bin/gstudio`**, **`bin/gknit`**, **`bin/run_example`**, **`bin/run_rspec`** / **`bin/run_all_rspec`**, and **`bin/galaaz-bootstrap`** on WSL when using Dockerized R. Treat **`grun`**, **`gknit_Rscript`**, and the polyglot **`ruby`** invocation in **`gknit-draft`** as **legacy** until they are ported to the same JRuby path as **`gknit`**.
+For day-to-day **2.0** use, rely on **`bin/galaaz-ruby`** (or **`bin/galaaz-jruby`** when you want to force JRuby), **`bin/gstudio`**, **`bin/gknit`**, **`bin/run_example`**, **`bin/run_rspec`** / **`bin/run_all_rspec`**, and **`bin/galaaz-bootstrap`** on WSL when using Dockerized R. Treat **`grun`**, **`gknit_Rscript`**, and the polyglot **`ruby`** invocation in **`gknit-draft`** as **legacy** until they are ported to the same launcher path as **`gknit`**.
 
 # System Compatibility
 
 Typical development and CI targets:
 
 * **Linux** — recent Ubuntu LTS or comparable distributions (x86_64).
-* **macOS** — recent releases with JRuby and GNU R available.
+* **macOS** — recent releases with JRuby or CRuby and GNU R available.
 * **Windows** — use **WSL2** (same Linux stack as above); native Windows is not the primary target.
 
 The native **gatekeeper** component under `ext/new_bridge` is built with `make` and a C++ toolchain; see the project `README` if compilation fails on your platform.
 
 # Dependencies
 
-* **JRuby** — Galaaz 2.0 requires JRuby (tested with **10.1.1.0**) and a matching **JDK** (tested with **Java 21**). MRI Ruby is not supported.
+* **Ruby** — **JRuby** or **CRuby** (both supported for NewBridge). Tested with **JRuby 10.1.1.0**
+  (+ **JDK 21**) and **CRuby 3.3.12**. Use `bin/galaaz-ruby` (honors `GALAAZ_RUBY`) or plain
+  `gem install galaaz` under the Ruby you choose.
 * **GNU R** — `R` and `Rscript` on your `PATH` (tested with **4.3.3**), plus a C++ toolchain (`g++`, `make`) and the **Rcpp** package to compile the gatekeeper.
 * **galaaz gem** — runtime dependency `msgpack` is pulled in by `gem install`.
 * Optional: **Docker** — if you run R in a container (common on WSL2); see bootstrap below.
@@ -314,29 +331,34 @@ The native **gatekeeper** component under `ext/new_bridge` is built with `make`
 
 The supported install is **`gem install` + compile the gatekeeper**. You do not need a git clone.
 
-1. Install **JRuby**, a compatible **JDK**, and **GNU R** (with `Rscript` and a C++ compiler).
+1. Install **JRuby** (and a compatible **JDK**) **or CRuby 3.3+**, plus **GNU R** (with `Rscript` and a C++ compiler).
 2. In R, install **Rcpp**: `install.packages("Rcpp")`.
-3. Install the gem: `jruby -S gem install galaaz`
+3. Install the gem: `jruby -S gem install galaaz` (or `gem install galaaz` under CRuby).
 4. Compile the native gatekeeper from the installed gem:
 
    ```
-   gem_dir="$(jruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")"
+   gem_dir="$(ruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")"
+   # under JRuby: gem_dir="$(jruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")"
    make -C "${gem_dir}/ext/new_bridge" all
    ```
 
-5. Ensure **`R`** starts GNU R and can install packages (network access to CRAN when you first call `R.install_and_loads`). For **Apache Arrow** on Java 9+, pass `-J--add-opens=java.base/java.nio=ALL-UNNAMED` to JRuby (from a checkout, `bin/galaaz-jruby` does this).
+5. Ensure **`R`** starts GNU R and can install packages (network access to CRAN when you first call `R.install_and_loads`). For **Apache Arrow** on **JRuby** (Java 9+), the child JVM needs `--add-opens=java.base/java.nio=ALL-UNNAMED` via **`JAVA_OPTS`** (from a checkout, `bin/galaaz-jruby` and `mise.toml` set this; a leading `jruby -J... -S bundle exec` does **not** pass `-J` to rspec). On **CRuby**, install Apache Arrow GLib (`libarrow-glib-dev` from the [Apache Arrow APT](https://arrow.apache.org/install/) repo) and `gem install red-arrow` matching `pkg-config --modversion arrow-glib`. Do not install the unrelated Rubygems package named `arrow`.
 
 For **gKnit**, **knitr**, **rmarkdown**, and LaTeX (PDF output), install the corresponding R packages, **Pandoc**, and a TeX distribution if you need PDF; the repository includes helpers such as **`bin/install-tinytex`** where appropriate.
 
-A **table of all `bin/` scripts** (bootstrap, JRuby wrapper, gstudio, gknit, test runners, and which ones are legacy) is in the section **Command-line tools (`bin/`)** earlier in this manual.
+A **table of all `bin/` scripts** (bootstrap, Ruby launcher, gstudio, gknit, test runners, and which ones are legacy) is in the section **Command-line tools (`bin/`)** earlier in this manual.
 
 ### From a repository checkout (contributors)
 
-1. Install **bundler** if needed, then run **`jruby -S bundle install`** in the repository root.
+1. Install **bundler** if needed, then run **`bundle install`** with your chosen Ruby
+   (`jruby -S bundle install` or CRuby `bundle install`) in the repository root.
 2. Build the bridge native code: **`make -C ext/new_bridge all`** (or **`rake compile_gatekeeper`**).
-3. Run scripts with **`bin/galaaz-jruby`** (sources **`bin/galaaz_jruby_env.inc.sh`** and adds **`-I lib`**).
+3. Run scripts with **`bin/galaaz-ruby`** (uses `ruby` on `PATH`; set **`GALAAZ_RUBY=jruby`** or
+   **`GALAAZ_RUBY=ruby`** to force an engine). Spec runners: **`bin/run_rspec`** /
+   **`bin/run_all_rspec`** (same `GALAAZ_RUBY` rule). **`bin/galaaz-jruby`** remains a thin
+   wrapper that forces JRuby.
 
-Maintainers can prove a built `.gem` on a throwaway Ubuntu machine (no repo inside the container) with **`./docker/cold-install/run.sh`**.
+A **gstudio** try image (JRuby + R + Galaaz already installed) is **`docker run --rm -it ghcr.io/rbotafogo/galaaz-try:gstudio`** (or **`./docker/try-gstudio/run.sh`** from a checkout). Maintainers can prove a RubyGems install on a throwaway Ubuntu machine (no repo inside the container) with **`./docker/cold-install/run.sh published-specs`** (JRuby) or **`./docker/cold-install-cruby/run.sh published-specs`** (CRuby).
 
 ## Windows + WSL2 (optional: Docker / R in a container)
 
@@ -404,11 +426,13 @@ WSL integration is enabled for the distro where Galaaz is installed.
   
   > galaaz master_list:scatter_plot
 
-# JRuby, multithreading, and the R bridge
+# JRuby, CRuby, multithreading, and the R bridge
 
-Galaaz 2.0 runs Ruby on **JRuby**, so your application can use **real parallel threads** for
-I/O-bound work (HTTP clients, database connections, message consumers, and so on). R itself is
-still executed in a **single GNU R process** behind the Galaaz bridge.
+Galaaz 2.0 supports **JRuby** and **CRuby** equally for NewBridge. On **JRuby**, your
+application can use **real parallel threads** for I/O-bound work (HTTP clients, database
+connections, message consumers, and so on). On **CRuby**, prefer multi-process scaling for
+CPU-bound concurrency. R itself is still executed in a **single GNU R process** behind the
+Galaaz bridge (use multiple R workers when you need more R throughput).
 
 When several Ruby threads call into R at the same time, the bridge **serializes** those calls:
 each request is matched to a reply using an internal per-call **queue**, so you do not need to
@@ -420,13 +444,15 @@ A practical pattern is:
 
 1. Use threads (or a connection pool) to read from **multiple databases or shards** in parallel.
 2. Merge the rows in Ruby under a `Mutex` if you collect into one structure.
-3. Hand the merged table to R **once** (for example with `R::Arrow.from_ruby_batches` and dplyr,
-   or by building a data frame) so heavy statistics run in R with fewer bridge round-trips.
+3. Hand the merged table to R **once**: **`R::Arrow.from_ruby_batches`** (Stage A: copy into R) or
+   **`Galaaz::ArrowIpc.write` / `write_batches`** then **`R::Arrow.open_ipc`** (Stage B: IPC file;
+   only the path crosses the bridge). Then run dplyr in R.
 
 A runnable sketch lives in
 `examples/multithread_shards_to_r/shards_to_r.rb` (simulated shard queries; swap in your DB
 driver). For concurrency tests on the bridge itself, see `specs/bridge_concurrent_spec.rb` and
-`specs/arrow_from_ruby_batches_spec.rb`.
+`specs/arrow_from_ruby_batches_spec.rb`. Stage B IPC tests: `specs/arrow_ipc_handoff_spec.rb`,
+`specs/arrow_ipc_export_spec.rb`.
 
 ## Long-running R calls and a completion block
 
@@ -488,19 +514,22 @@ the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, et
 Ruby pattern above is only to show **when** the result exists (inside the block, or after data
 written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**.
 
-## Galaaz + Rails (JRuby) integration baseline
+## Galaaz + Rails (R-on-Rails) integration baseline
 
-This section documents the baseline we used to create a working Rails app with Galaaz in WSL.
-The goals were:
+This is the practical **R-on-Rails** starter: an R scientist’s analysis behind a small Rails
+app. The baseline we used in WSL aimed at:
 
-1. Rails boots under **JRuby**.
+1. Rails boots under **JRuby or CRuby** (same bridge; see Installation).
 2. Galaaz is loaded from a local checkout (before publishing to RubyGems).
-3. A request path can execute **`R.eval(...)`** and return a result.
+3. A request path can execute **`R.eval(...)`** (or `R.*`) and return a result.
 
-### 1) Create the app with JRuby-friendly options
+You keep statistical work in R; Rails owns HTTP, sessions, and HTML. See **R-on-Rails: the
+one-person app for R scientists** in the Introduction for the product framing.
 
-Rails defaults can pull gems that are not ideal on JRuby-first setups (for example sqlite native
-extension paths and deployment extras). A minimal app avoids early friction:
+### 1) Create the app with Ruby-friendly options
+
+Rails defaults can pull gems that are awkward on some setups (for example sqlite native
+extension paths on JRuby, or deployment extras you do not need). A minimal app avoids early friction:
 
 ```bash
 cd /home/rbotafogo/desenv_linux
@@ -788,7 +817,7 @@ puts vec.map { |x| x + 2 }
 
 This manual has been formatted using gKnit.  gKnit uses knitr and R Markdown to knit 
 a document in Ruby or R and output it in any of the available formats for R Markdown.
-gKnit runs with **JRuby**, **GNU R**, and Galaaz.  In gKnit, Ruby variables are persisted between 
+gKnit runs with **JRuby or CRuby**, **GNU R**, and Galaaz.  In gKnit, Ruby variables are persisted between 
 chunks, making it an ideal solution for literate programming. Also, since it is based 
 on Galaaz, Ruby chunks can have access to R variables and combining Ruby with R in one 
 document is natural.
@@ -4000,35 +4029,77 @@ ans = flights[:all, E.list(R[:arr_delay], R[:dep_delay])]
 # Apache Arrow
 
 [Apache Arrow](https://arrow.apache.org/) is a **columnar** in-memory format used heavily in R
-and Python for analytics. In Galaaz, **Ruby does not hold an Arrow C++ table itself**; instead you
-build ordinary Ruby structures (arrays of row hashes), and **`R::Arrow.from_ruby_batches`** creates
-a real **Arrow `Table` inside GNU R**. From there you use R’s **`arrow`** and **`dplyr`** packages
-as usual: **`group_by`** on the Arrow table, **`summarise`** for aggregates, then **`collect()`** to
-materialize a tibble when you need in-memory R rows.
-
-That pattern matches production use: **JRuby threads** (or sequential code) assemble many rows in
-Ruby; you pay **one** bridge-heavy handoff to R; **dplyr** runs vectorised work on the Arrow table
-in R.
+and Python for analytics. GNU R still runs in a **separate process**. Ruby does **not** hold a
+shared Arrow C++ table with R. Stages:
+
+1. **Stage A (copy over the bridge):** Ruby row hashes → **`R::Arrow.from_ruby_batches`** builds
+   an Arrow `Table` **inside GNU R**. You get a **proxy**.
+2. **Stage B1 (Ruby → R IPC file):** **`Galaaz::ArrowIpc.write`** / **`write_batches`** writes an
+   Arrow IPC file (prefer **`/dev/shm`**); **`R::Arrow.open_ipc(path)`** opens it in R. Only the
+   **path** crosses NewBridge. This is **mmap/IPC file handoff**, not a shared heap.
+3. **Stage B2 (R → Ruby IPC file):** **`R::Arrow.write_ipc(obj)`** writes uncompressed IPC; Ruby
+   reads with **`Galaaz::ArrowIpc.read`** (column hash) or **`read_batches`** (row hashes). Call
+   **`Galaaz::ArrowIpc.release(path)`** when finished.
+4. **Stage C (not shipped):** named shared-memory bus. Do not claim 0 ms shared RAM until then.
+   See **`Documentation/ROADMAP_ARROW_RUBY_R.md`**.
+
+After ingest, use R’s **`arrow`** / **`dplyr`** on the proxy (`group_by`, `summarise`, `collect`)
+and unbox only KPIs you need in Ruby.
+
+**Optional Ruby backends for Stage B**
+
+* **CRuby:** Apache **red-arrow** — `gem install red-arrow` pinned to the same major as
+  `pkg-config --modversion arrow-glib`, plus system **Arrow GLib** (`libarrow-glib-dev` from the
+  [Apache Arrow APT](https://arrow.apache.org/install/) repo). Do **not** install the unrelated
+  legacy Rubygems package named `arrow`. `bundle exec` still sees a user-installed `red-arrow`
+  via Galaaz’s load-path helper.
+* **JRuby:** Apache Arrow **Java** JARs — **`GALAAZ_ARROW_JARS`**, `~/arrow_jars`, or
+  `jar-dependencies`. Export **`JAVA_OPTS=--add-opens=java.base/java.nio=ALL-UNNAMED`** on the
+  **child** JVM (`bin/galaaz-jruby`, `mise.toml`). `jruby -J... -S bundle exec rspec` does **not**
+  pass `-J` to rspec.
+
+**R packages:** **`arrow`** and **`dplyr`**. B2 writes IPC with **`compression: 'uncompressed'`**
+so JRuby Arrow Java can read without extra compression JARs.
+
+**Tests:** `specs/arrow_from_ruby_batches_spec.rb` (A);
+`specs/arrow_ipc_handoff_spec.rb`, `specs/arrow_ipc_export_spec.rb` (B, sync);
+`new_bridge_specs/arrow_ipc_async_spec.rb`, `new_bridge_specs/arrow_ipc_export_async_spec.rb` (B, async).
+
+## `R::Arrow` and `Galaaz::ArrowIpc`
+
+* **`R::Arrow.from_ruby_batches`** — Stage A ingest.
+* **`R::Arrow.open_ipc(path)`** — Stage B1: IPC file → R Table proxy.
+* **`R::Arrow.write_ipc(obj, path = nil)`** — Stage B2: R Table/tibble → IPC path (scratch if omitted).
+* **`Galaaz::ArrowIpc.write` / `write_batches` / `read` / `read_batches` / `allocate_path` / `release` / `available?`**
+* **`R::Arrow.table_from(df)`** — wrap an R `data.frame` / tibble as an Arrow table.
+* **`R::Arrow.read_feather` / `write_feather`**, **`read_parquet`**, **`dataset(path)`** — file and
+  dataset IO on paths visible to R.
 
-**Prerequisites:** install R packages **`arrow`** and **`dplyr`**. Run scripts with
-**`bin/galaaz-jruby`** (or the same JVM flags as in **`docs/testing.md`**) so the Arrow JNI stack is
-available.
+## Example: Stage B round-trip (IPC file)
 
-## Other `R::Arrow` helpers
+Requires `Galaaz::ArrowIpc.available?` (red-arrow or Arrow JARs) and R **`arrow`**. Not knitted
+below so a machine without the optional backend still builds this manual.
 
-The Ruby module **`R::Arrow`** (see `lib/R_interface/r_arrow.rb`) also includes:
+```ruby
+path = Galaaz::ArrowIpc.write(id: [1, 2, 3], grp: %w[a a b], value: [1.0, 2.0, 3.5])
+tbl  = R::Arrow.open_ipc(path)
+Galaaz::ArrowIpc.release(path)
 
-* **`R::Arrow.table_from(df)`** — wrap an R `data.frame` / tibble as an Arrow table.
-* **`R::Arrow.read_feather` / `write_feather`**, **`read_parquet`**, **`dataset(path)`** — file and
-  dataset IO on paths visible to R.
+summed   = R.dplyr___summarise(R.dplyr___group_by(tbl, :grp), total: E.sum(:value))
+out_path = R::Arrow.write_ipc(summed)
+rows     = Galaaz::ArrowIpc.read_batches(out_path)
+Galaaz::ArrowIpc.release(out_path)
+# rows => [{:grp=>"a", :total=>3.0}, {:grp=>"b", :total=>3.5}]  (illustrative)
+```
 
 ## Example: many Ruby rows → Arrow in R → grouped statistics
 
 The repository test **`slow-specs/arrow_large_pipeline_spec.rb`** builds **200k rows** in parallel
-(eight threads × 25,000 rows), pushes them through **`R::Arrow.from_ruby_batches`**, then checks that
-**dplyr** group summaries match a Ruby reference calculation. The same logic appears below at a
-**smaller scale** so this manual can knit quickly; increase `thread_count` and `rows_per_thread`
-when experimenting locally.
+(eight threads × 25,000 rows), pushes them through **`R::Arrow.from_ruby_batches`** (Stage A), then
+checks that **dplyr** group summaries match a Ruby reference calculation. The same logic appears
+below at a **smaller scale** so this manual can knit quickly; increase `thread_count` and
+`rows_per_thread` when experimenting locally. For the same ingest **without** copying every cell
+over NewBridge, use Stage B (`write_batches` + `open_ipc`) instead of `from_ruby_batches`.
 
 
 ``` ruby
@@ -4094,10 +4165,10 @@ end
 ```
 
 **What to notice:** (1) Ruby only sees **`Hash`** rows and Ruby **`Thread`** objects; (2) a single
-**`from_ruby_batches`** call creates the Arrow table in R; (3) **`dplyr___group_by`** /
+**`from_ruby_batches`** call **copies** those columns into an Arrow table in R; (3) **`dplyr___group_by`** /
 **`dplyr___summarise`** / **`dplyr___collect`** mirror **`dplyr::group_by`** /
 **`dplyr::summarise`** / **`dplyr::collect`** on an Arrow-backed table. For a lighter test, see
-**`specs/arrow_from_ruby_batches_spec.rb`**; for the full-size benchmark, run
+**`specs/arrow_from_ruby_batches_spec.rb`**; for the full-size Stage A benchmark, run
 **`bin/run_slow_rspec slow-specs/arrow_large_pipeline_spec.rb`**.
 
 # Bioconductor and DESeq2
@@ -4235,8 +4306,9 @@ Practical tips:
   glue.
 * **Reuse one process**: running many short scripts cold-starts Ruby, the JVM, and R each time;
   a long-lived process or repeated calls in one run amortize setup (see benchmarks below).
-* **Batch data**: merge shards in Ruby, then call **`R::Arrow.from_ruby_batches`** (or build one
-  data frame) instead of millions of tiny R calls.
+* **Batch data**: merge shards in Ruby, then **`R::Arrow.from_ruby_batches`** (Stage A) or
+  **`Galaaz::ArrowIpc`** + **`R::Arrow.open_ipc`** (Stage B) instead of millions of tiny R calls.
+  When Ruby needs a bulky result table back, **`R::Arrow.write_ipc`** + **`Galaaz::ArrowIpc.read_batches`**.
 
 For measured discussion (including DESeq2-style workloads and warm comparisons), see
 **`docs/performance.md`** and **`docs/deseq2_airway_benchmark.md`** in the Galaaz repository.
@@ -4923,8 +4995,8 @@ arguments.
 
 * Fork it
 * Create your feature branch (`git checkout -b my-new-feature`)
-* Write tests — use **`bin/run_rspec`** or **`bin/run_all_rspec`** with **JRuby** so JVM flags and
-  the load path match **`docs/testing.md`**
+* Write tests — use **`bin/run_rspec`** or **`bin/run_all_rspec`** (JRuby or CRuby via
+  **`GALAAZ_RUBY`**) so JVM flags and the load path match **`docs/testing.md`**
 * Commit your changes (`git commit -am 'Add some feature'`)
 * Push to the branch (`git push origin my-new-feature`)
 * Open a pull request