# The R runtime

This is a design draft: how ry becomes an R implementation of its own, in what order to build it,
and why. Built so far are the object model and collector in `crates/heap`, the C API as `libR.so`
in `crates/libr` (the whole measured surface, ALTREP and connections), package installation in
`crates/rcmd`, an interpreter in `crates/interp` with a tier-0 bytecode (`ry run`),
a first Cranelift JIT in `crates/jit` (section 5, "What tier 1 does today"), and a table engine in
`crates/table`. Not built are compiled-to-compiled calls of general (non-scalar) functions, ry's own base R (base R's R
code still comes from a GNU R installation), and the table type's use from the interpreter. `ry run`
runs on ry's runtime, and `ry R` drives GNU R. The C API measurements in section 2 are real and
reproducible. Where section 4 describes something built, `.agents/memory/decisions/heap-gc.md` ("the runtime's object model, collector and native
boundary") records the settled details.

## 1. The recommendations

The rest of the page argues for each of these, and section 10 orders them into a build plan.

- **Implement R's C API as an ABI-compatible `libR`.** A package's compiled code must load and run
  unchanged, including binaries built against GNU R's headers. This is cheap to promise, because
  since R 4.2.0 the public headers treat `SEXP` as an opaque pointer, so ry's object layout stays
  its own. The surface is the whole public header set of R 4.6, not a subset: the benchmark's
  dependency closure uses 792 distinct API names (plus 150 BLAS and LAPACK routines), and covering
  even half of its compiled packages takes the 495 most widely used ones.
- **Keep the object model close to GNU R where native code can see it,** and free everywhere else.
  Objects that native code touches do not move, `PROTECT` keeps its stack semantics, strings are
  interned so pointer equality works, and ALTREP is a first-class mechanism. Inside the interpreter
  and the JIT, scalars stay unboxed and environments are materialized only when something needs one.
- **Write the runtime in Rust, with a thin C layer at the native boundary** that turns R's
  `longjmp`-based errors into Rust results and back.
- **Execute in two tiers:** a bytecode interpreter with inline caches and type feedback, then
  an optimizing JIT on Cranelift with speculation and deoptimization. A baseline tier between them
  was measured and removed, because tier 0's dispatch is too small a share of the time. ry's static types seed the speculation, so code runs fast before it has
  warmed up.
- **Load packages lazily from ry's own analysis index.** A top-level function definition becomes a
  binding that compiles on first use; other top-level code runs eagerly in collation order. Reloading
  replaces exactly the items that changed and removes deleted ones, which loadfast cannot do.
- **Build the table type on Polars, linked as a Rust crate,** and expose its columns to R and to
  native code as ALTREP vectors. Typed columns come from ry's record types.
- **Share one type model between checker and runtime.** The runtime consumes the checker's types
  through a small, stable projection. Types are hints by default; in strict mode they become
  guarantees wherever a runtime check backs them.
- **Get real packages running first.** The interpreter and the C API come before the JIT, the table
  type and the inline syntax, because nothing else can be measured until the benchmark code runs.

## 2. The C API surface, measured

### What was measured

The scripts are in `tools/research/`. `r_api_usage.py` resolves the dependency closure of the
benchmark's `Imports` (following `Depends`, `Imports` and `LinkingTo`, recursively, but not
`Suggests`) against CRAN, the extra repository `ak-finccam.github.io/r-packages` (which supplies
`azidentity`, `polars` and `Rblpapi`), and the two GitHub remotes. It downloads every source package
and scans the compiled code under `src/` and `inst/include/` for identifiers declared in R 4.6.2's
public headers (`R.h`, `Rinternals.h`, `Rdefines.h`, `Rembedded.h`, `Rinterface.h`,
`Rconnections.h`, `Rmath.h` and every `R_ext/*.h`). `r_api_summary.py` turns the result into the
figures below. The raw data is in `tools/research/data/`: `symbols.csv` has one row per name with
its class, declaring header and the packages that use it, `packages.csv` one row per package,
`r_calls.csv` the R-level foreign calls, and `summary.txt` the output every figure here is quoted
from.

R classifies its own entry points, and the scan keeps that classification:

- **API** and **experimental** are the names *Writing R Extensions* documents with `@apifun`,
  `@apivar`, `@eapifun` and `@eapivar`.
- **Embedding** is the API for programs that embed R.
- **Non-API** is the list `tools:::nonAPI` that `R CMD check` warns about.
- **BLAS/LAPACK** is every routine declared in `R_ext/BLAS.h`, `Lapack.h` and `Linpack.h`. These are
  Fortran libraries to link against, not R API to reimplement, so they are reported separately.
- **Header** is everything else declared in a public header: mostly types (`SEXP`, `R_xlen_t`), type
  codes (`INTSXP`), constants, the Rmath distribution functions and the graphics engine.

The scan is lexical, and its limits matter when you read the numbers:

- A file counts only if it can see R's headers. That means it includes one, or it is connected to
  such a file through the package's own `#include` edges in either direction, which is how Rcpp's
  umbrella header reaches the many files that use the API without including anything. A vendored C
  library that no R-facing file includes stays out.
- Unprefixed names such as `length` count only where R would remap them. They do not count in C++
  files (since R 4.5.0, `R CMD INSTALL` compiles C++ with `-DR_NO_REMAP`), in packages that define
  `R_NO_REMAP`, or for Rmath's short names (`dt`, `df`, `beta`) in files that do not include
  `Rmath.h`.
- Both branches of an `#if` are counted, so a fallback branch for an older R counts as much as the
  modern one. Names that R 4.6 removed from its public headers (`TRUELENGTH`, `SETLENGTH`,
  `IS_GROWABLE`) are not counted at all, so the measured surface is R 4.6's, not what those
  fallbacks need.
- A package-local macro that shadows an API name still counts as that name. Two known cases are
  data.table's own `BODY` macro and simdjson's `OBJECT` enumerator.
- `polars` and `azidentity` fetch their Rust dependencies with Cargo at build time. Only the code in
  the tarball is scanned, which includes each package's own glue but not `savvy-ffi` or `libR-sys`,
  where their calls into the API live.

### The closure

| | |
| --- | --- |
| Packages in the closure, base packages excluded | 232 |
| ... whose compiled code uses the R API | 121 |
| Direct (non-base) dependencies | 67; 36 ship code that uses the API (35 compile, and `progress` ships a header) |
| Compiled source lines: C / C++ / headers | 1.21M / 0.64M / 3.97M |
| Compiled source lines: Fortran / Rust | 24.7K / 11.6K |

The header count is dominated by vendored libraries: `BH` (Boost), `RcppArmadillo`, `stringi`'s ICU
and the SuiteSparse copy inside `Matrix`. That code never sees `SEXP`, but it has to compile and link,
so ry's package build must handle large C++ code bases and Fortran.

Most packages call the C API directly rather than through a binding layer:

| Binding layer | Packages |
| --- | --- |
| The C API directly | 91 |
| Rcpp | 19 (`rugarch`, `rmgarch`, `RcppDE`, `FLSSS`, `Rblpapi`, `RcppSimdJson`, `odbc`, `openxlsx`, `pdftools`, `httpuv`, `later`, ...) |
| cpp11 | 9 (`readr`, `readxl`, `vroom`, `tzdb`, `systemfonts`, ...) |
| Rust | 2 (`polars` through savvy, `azidentity` through extendr) |

### The names

The closure uses **942 distinct names** from R's headers, 131,275 times in total. 150 of them are
BLAS and LAPACK routines, which leaves **792 names of R API proper** (130,074 occurrences). By class,
307 are API, 102 experimental, 5 embedding, 30 non-API and 348 header-only. Of the 570 names R
documents as API or experimental API, the closure uses 409.

The most widely used names are the ones any implementation starts with:

| Name | Class | Packages | Occurrences |
| --- | --- | ---: | ---: |
| `R_registerRoutines`, `R_useDynamicSymbols` | api | 117 | 133 each |
| `SEXP` | header | 107 | 41,844 |
| `Rf_error` | api | 83 | 5,836 |
| `R_NilValue` | api | 82 | 2,429 |
| `PROTECT` / `UNPROTECT` (`Rf_protect` / `Rf_unprotect`) | api | 79 / 78 | 5,092 / 3,144 |
| `Rf_allocVector` | api | 77 | 2,791 |
| `INTEGER` | api | 71 | 3,391 |
| `STRING_ELT` | api | 70 | 1,717 |
| `CHAR` (`R_CHAR`) | api | 68 | 1,449 |
| `Rf_length` | api | 65 | 2,568 |
| `REAL` | api | 61 | 3,777 |
| `TYPEOF` | api | 59 | 1,333 |
| `SET_VECTOR_ELT` / `VECTOR_ELT` | api | 50 / 47 | 1,635 / 1,519 |
| `Rf_setAttrib` / `Rf_getAttrib` | api | 48 / 39 | 664 / 590 |
| `Rf_mkChar` | api | 47 | 651 |
| `Rf_install` | api | 45 | 843 |
| `Rf_eval` | api | 38 | 195 |
| `R_RegisterCCallable` | api | 25 | 276 |
| `R_ExternalPtrAddr` | api | 25 | 469 |

But the distribution has a long tail, and the tail is not optional. 499 names are used by at least
two packages, 249 by at least five, 145 by at least ten, and only 24 by fifty or more. The coverage
curve shows what that means: if ry implemented the N most widely used names, this many of the 121
compiled packages would have every name they use.

| Names implemented | 25 | 50 | 100 | 150 | 200 | 300 | 400 | 500 | all 942 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Packages fully covered | 2 | 5 | 9 | 19 | 24 | 33 | 43 | 62 | 121 |

Covering half of the compiled packages takes the 495 most widely used names. The curve charges a
package with the names of every header-only layer in its `LinkingTo` as well as its own, which
overstates Rcpp's share: Rcpp's headers mention 358 names, most of them Rmath distribution functions
it wraps, and an unused inline wrapper never reaches a package's binary. In their own code, the
packages that use the most names are the ones the benchmark cannot do without: Rcpp (358),
`Matrix` (257), `vctrs` (250), `pak` (237), `rlang` (233) and `data.table` (202). So the target is the
public header set as a whole, and a "most common 200" subset would leave the core of the tidyverse
and data.table unable to load.

Grouped by subsystem (by declaring header, then by name; the rules are in `r_api_summary.py`):

| Subsystem | Names | Packages using any |
| --- | ---: | ---: |
| Registration and cross-package C calls | 8 | 117 |
| Vector data access (`INTEGER`, `REAL`, `VECTOR_ELT`, lengths, resizable vectors) | 50 | 96 |
| Non-local exits, errors and interrupts | 19 | 93 |
| Allocation, coercion, duplication | 24 | 85 |
| Protection and GC | 13 | 82 |
| Strings and encodings | 33 | 82 |
| Math and RNG (Rmath, `R_ext/Random.h`, `Arith.h`, `Applic.h`) | 172 | 77 |
| Attributes, classes and S4 | 30 | 58 |
| Evaluation, calls and pairlists | 45 | 57 |
| Environments, closures, promises | 57 | 39 |
| External pointers, weak references, finalizers | 18 | 28 |
| BLAS, LAPACK and LINPACK | 150 | 10 |
| ALTREP | 31 | 9 |
| Connections | 5 | 5 |
| Graphics engine and devices | 112 | 5 |
| Types, constants and everything else | 175 | 121 |

### Interfaces that shape the runtime

A few interfaces are used by fewer packages but constrain the design far more than their counts
suggest:

- **ALTREP** (9 packages: `cli`, `cpp11`, `data.table`, `lazyeval`, `pak`, `rlang`, `stringi`,
  `vctrs`, `vroom`). Four of them define ALTREP classes of their own (`vroom` builds its lazily
  parsed columns on it, and `cli`, `vctrs` and `pak` define classes too), and the rest test for ALTREP
  objects or read them through the region and element accessors.
- **Cross-package C callables** (27 packages register or fetch them with `R_RegisterCCallable` and
  `R_GetCCallable`, among them `Rcpp`, `rlang`, `vctrs`, `xts`, `zoo`, `Matrix` and `data.table`).
  `xts` calls `zoo`'s C functions this way (`R_GetCCallable("zoo", "zoo_lag")`), so native libraries
  must be able to find each other through the runtime.
- **External pointers and finalizers** (27 packages). Every handle to a database connection,
  HTTP session, git repository or parser lives in one.
- **Non-local exits** (15 packages use `R_UnwindProtect`, `R_ToplevelExec`, `R_tryEval` or their
  relatives). Rcpp and cpp11 call `R_UnwindProtect` directly so that C++ destructors run when an R
  error unwinds through their frames; savvy and extendr do the same for Rust from crates the scan
  does not see.
- **Connections** (`readr`, `vroom` and `xml2` read and write R connections; `curl` and `pak` create
  custom ones), which exposes the `Rconnection` struct layout, versioned by `R_CONNECTIONS_VERSION`.
- **Graphics** (5 packages: `ragg` implements a device, and `systemfonts`, `farver`, `later` and `pak`
  use smaller parts). The device API can come late, but the graphics headers also declare
  `Rf_ucstoutf8` and the interrupt-suspension macros, which `rlang`, `readxl` and `later` use, and
  Rcpp, rlang and vctrs include them, so the headers themselves and those few names are needed early.

At the R level, 104 packages call `.Call` (4,255 call sites), 18 use `.C` (443), 5 use `.Fortran`
(127), and 8 use `.External` or `.External2` (58). Three call `.Internal` directly (`pkgload`,
`processx`, `renv`), which means ry must also expose some of base R's internal entry points by name.

### The non-API surface is shrinking, and ry should follow it

30 non-API names appear in the closure, used by 28 packages. The heaviest users are `rlang`,
`vctrs`, `lazyeval` (which vendors rlang) and `magrittr` (promise and environment internals such as
`PRVALUE`, `SET_PRENV`, `ENCLOS`), `data.table` (`DATAPTR`, `LEVELS`, `IS_UTF8`) and Rcpp
(`STRING_PTR`, `PRCODE`, `CLOENV`, `BODY`).

Many of these uses are fallbacks. R 4.5 and 4.6 added API replacements for the internals packages
used to reach for, such as `R_ParentEnv`, `R_getVar`, `R_ClosureFormals` and the resizable-vector
functions `R_allocResizableVector`, `R_resizeVector` and `R_mapAttrib`, and the packages switched
with version guards. `rlang`'s `env.h` returns `R_ParentEnv(env)` under
`#if R_VERSION >= R_Version(4, 5, 0)` and `ENCLOS(env)` only otherwise, `cli` maps `R_getVar` to
`Rf_findVar` only before R 4.5, and `data.table` 1.18 keeps its `TRUELENGTH`-based growable vectors
only as a backport for older R. The `TRUELENGTH` family is no longer declared in R 4.6's public
headers at all.

So **ry should present itself as R 4.6**, which makes every guarded package take the modern branch.
That means `R_VERSION` and `Rversion.h`, and also `R_SVN_REVISION`: data.table's guard is
`R_VERSION < R_Version(4, 6, 0) || R_SVN_REVISION < 89077` (and `< 89194` for `R_mapAttrib`), so ry
must report a revision of at least 89194 or data.table takes the backport.

In practice the runtime runs the base R code of the GNU R installation its R home links, so ry
presents that installation's version. `R.version`, `getRversion()` and the home's generated
`Rversion.h` all come from its `library/base/DESCRIPTION`, and the revision is raised to at least
89194. Linked to R 4.6, ry presents 4.6 as recommended here. Linked to an older R, such as the 4.3.3
the corpus baseline runs on, it presents that version, because a package whose C code takes the 4.6
branches while its R code runs on a 4.3 base breaks (rlang's `ns_registry_env()` is one example).

A real non-API surface remains after that, unguarded: the promise accessors in `rlang`, `vctrs`,
`lazyeval` and `magrittr` and `PRCODE`/`PRENV` in Rcpp's `Promise.h`, `ATTRIB` and `SET_ATTRIB`,
`IS_UTF8` and `IS_ASCII` in `stringi`, `fansi` and data.table's `forder.c`, `Rf_findVarInFrame` in
`S7`, `BODY` in Rcpp's `Function.h`, `OBJECT` in `reshape2` and `R_Outputfile` in `Rmpfr`. `later`
declares `R_GlobalContext` itself rather than taking it from a header. ry should implement all of
these, because a package that does not load is a failed benchmark, whatever R core's policy says.

### What the API implies for the object model

**`SEXP` is opaque.** Since R 4.2.0, defining `USE_RINTERNALS` no longer exposes R's internal
structures. In R 4.6's `Rinternals.h`, `SEXP` is `typedef struct SEXPREC *SEXP` with no definition
of the struct, and every accessor (`INTEGER`, `LENGTH`, `TYPEOF`, `CAR`) is a function. A compiled
package therefore depends on R's *function* ABI, not its object layout, which is what makes an
ABI-compatible reimplementation possible at all.

What native code does rely on, and ry must keep:

- **Pointer identity.** Code compares `x == R_NilValue`, compares symbols by pointer after
  `Rf_install`, and compares `CHARSXP` strings by pointer, because `Rf_mkChar` returns the one
  interned copy of each string. So handles must be canonical: one object, one pointer.
- **Stable, writable data pointers.** `INTEGER(x)` returns a pointer into the vector's storage, and
  code keeps it across later allocations and writes through it. Objects reachable from native code
  must not move, and a pointer handed out by a writable accessor must point at memory that native
  code may write.
- **Writes that ignore reference counts.** Correct code checks `MAYBE_SHARED` before mutating, but
  some code mutates in place on purpose: data.table's `:=`, `set()` and `setattr()` write into the
  object they are given. The runtime cannot assume a vector's contents survive a native call.
- **Precise rooting through `PROTECT`.** An unprotected object may be collected at the next
  allocation, and correct packages protect everything they keep. `PROTECT_WITH_INDEX`,
  `R_PreserveObject` and the protected slot of an external pointer are the other roots.
- **Pairlists.** Calls (`LANGSXP`), `.External` arguments and attribute lists are walked with `CAR`
  and `CDR`, so these stay linked lists at the boundary.
- **Value semantics by reference count.** Since R 4.0, copy-on-modify uses reference counts, and
  packages check `MAYBE_SHARED` before mutating in place.
- **Struct layouts that are part of the API:** `Rcomplex`, `R_CallMethodDef` and its siblings,
  `Rconnection` (versioned), the graphics `DevDesc`, ALTREP class handles, and the bit patterns of
  `NA_integer_` (`INT_MIN`) and `NA_real_` (a NaN with payload 1954).
- **`longjmp` errors.** `Rf_error` never returns; it jumps to the nearest context. Code between the
  error and the handler is skipped without running destructors, which is why C++ bindings wrap their
  calls in `R_UnwindProtect`.

None of this pins down how ry stores an object internally. The constraints are on the objects native
code can reach, which are exactly the objects passed to or created by it.

### The decision: ABI-compatible `libR`

ry should ship a shared library that exports R's public function and data symbols with GNU R's
calling conventions (`libR.so`, `libR.dylib`, `R.dll`), plus a header set that is source-compatible
with R 4.6's. Packages are built with ry's headers, and binaries built against GNU R's headers load
too. The alternative, source compatibility only, saves almost nothing, because the opaque `SEXP`
already forces ry to provide every accessor as a real function. What ABI compatibility adds is the
data symbols (`R_NilValue`, `R_GlobalEnv`, `R_NaInt`, `R_NamesSymbol`, ...), stable struct layouts for
the few structs above, and the exact type-code numbering. In return it buys three things:

- **Prebuilt binaries.** Posit Package Manager and r-universe ship compiled Linux, macOS and
  Windows binaries. Being able to install them skips compiling `stringi`'s ICU, Boost-heavy and
  Armadillo-heavy packages, which is the slowest part of setting up the benchmark environment.
- **A differential oracle.** The same compiled package binary can run under GNU R and under ry, so
  a behavioral difference is ry's bug, not a build difference.
- **A migration path for users,** who can point an existing library tree at ry.

The cost is that ry's internal object header is free, but the handle it hands out is a raw pointer
to a non-moving object, so the GC design follows (section 4).

## 3. Prior art

Every serious attempt at a faster R either forked GNU R, and inherited its C API for free but also
its limits, or reimplemented R and then struggled with packages. That pattern is the main lesson.

| Project | Approach | Native packages | Outcome |
| --- | --- | --- | --- |
| GNU R + `compiler` | AST interpreter plus a stack bytecode compiler (Tierney), JIT on by default since R 3.4.0 | Native: it *is* the API | The baseline; the bytecode removes interpretive overhead on scalar loops but keeps R's environments, promises and boxed values |
| pqR (Neal) | Fork of R 2.15 with a faster interpreter, deferred evaluation on helper threads, and lower allocation | Native, as a fork | Real speedups, but it never followed mainline R, so it fell behind the packages |
| CXXR / Rho | Incremental C++ rewrite of R's internals, later with an LLVM JIT | Kept R's API by construction | Discontinued |
| Riposte (Talbot et al.) | Tracing JIT and parallel VM for vector code | None | Research prototype; showed large gains from fusing vector operations, beside scalar trace compilation |
| Renjin | JVM interpreter; GCC-Bridge compiled C and Fortran to JVM bytecode | Recompiled, with no raw memory model | No longer maintained; packages relying on pointer-level behavior broke |
| [FastR](https://github.com/oracle/fastr) (Oracle) | Truffle AST interpreter with Graal partial evaluation | Emulated C API over Java objects, so a raw data pointer required native memory to be kept in sync with the Java-side vector | Large speedups on R code, but the native boundary was slow and incomplete; no longer actively developed, last release 22.3 |
| TERR (TIBCO, now Spotfire) | Closed-source clean-room engine from the S-PLUS lineage | Own implementation of the C API | Commercial and still shipped; checks CRAN compatibility on every release, which is the cost of not being a fork |
| [Ř / rir](https://github.com/reactorlabs/rir) (Vitek group) | Bytecode tier plus an optimizing tier with an SSA IR (PIR), speculation, deoptimization and contextual dispatch, LLVM backend | Native: built on a patched GNU R | Large speedups on R-level code in the published evaluations; remains a research VM tied to its GNU R base |
| [rcp](https://ch-rigid.github.io/publications/kocourek_copyandpatch_2025.pdf) (Kocourek, Křikava, Vitek, 2025) | Copy-and-patch JIT from GNU R bytecode, as a package | Native, inside GNU R | 1.15x to 1.91x over GNU R on 57 programs, at about 980 bytecode instructions per millisecond of compile time |

What carries over to ry:

- **The C API is the gate.** FastR and Renjin had excellent engines and lost on packages, because
  emulating raw pointers (copying data out to native memory, or translating C to the JVM) was slow
  and leaky. ry avoids that by making its native representation the real one: an R vector is a
  contiguous buffer that `INTEGER()` returns directly.
- **Forks do not keep up.** pqR and Ř get the API for free but cannot follow upstream R. ry should not
  fork GNU R's C sources. It reimplements the runtime, and treats GNU R as an oracle, not a codebase.
- **Most of R's cost is semantic, not instruction dispatch.** Ř's papers show that the wins come from
  removing environment allocation, promise creation and argument matching through speculation and
  deoptimization. rcp's 1.15x to 1.91x for a fast template JIT is consistent with it: compiling R's bytecode
  faster does not remove the R semantics it encodes.
- **Riposte's lesson** is that vector code wants fusion (`sum(x * y + z)` without temporaries),
  which a scalar JIT does not give you.
- **TERR shows the reimplementation path is viable** commercially, at the price of a permanent
  compatibility test against CRAN. ry should build that test from day one (section 10).

## 4. The runtime

### Language and structure

The runtime is Rust, in new crates beside the analysis: `heap` for the object model and GC, one for
the interpreter and the base library, one for the JIT, and `libr` for the C API. `libr` builds the
shared `libR` and contains a small amount of C, for the reason in "Errors across the boundary" below.
Because a package built against GNU R records `libR.so` as a needed library, `libR` is the whole
runtime: the interpreter and the JIT link into it, and the `ry` binary loads it.
The `repl` crate drives both: GNU R behind `ry R`, and ry's runtime behind `ry run`.

### Objects

Every R value is a heap object with a header that ry defines: type code, flags (object bit, S4 bit,
named or shared bits), a reference count, the attribute pairlist and the GC bits. Vectors store
their elements inline after the header, so `INTEGER()` and `REAL()` return a pointer into the
object. Long vectors use `R_xlen_t` lengths throughout.

- **Interned strings.** `CHARSXP`s live in a global, weakly held intern table keyed by bytes and
  encoding, so pointer equality means string equality, as native code expects. Encoding flags
  (`IS_UTF8`, `IS_ASCII`) are stored at interning time. The table is one open-addressed array of
  slots that pack each address with hash bits, so a lookup touches a string only when the hash
  bits match and its cost does not grow with the number of live strings.
- **Symbols** are interned `SYMSXP`s with a cached global binding cell, which is what makes base
  function lookup and JIT watchpoints cheap.
- **Pairlists** are kept for language objects, attributes and `.External` arguments, because native
  code walks them. Ordinary function calls inside the interpreter never build them.
- **Environments** are a hashed frame of binding cells, with a fast path for small frames. A binding
  cell is a heap object of its own holding the symbol, the value and the active-binding and locked
  flags, so its address is stable for as long as anything references it and the JIT can watch it
  for redefinition. The base environment's cells hang off the symbols.
- **ALTREP is native.** An ALTREP object is a vector whose methods table decides length, element
  access, region access and dataptr materialization. Package-defined classes use the R API; ry's own
  compact sequences, memory-mapped vectors and table columns (section 6) use the same mechanism.
  The interpreter reads an element of a long ALTREP vector through its `Elt` method, so
  `x <- seq_len(2^31 - 1); x[c(1, 2^31 - 1)]` reads two elements instead of expanding 8 GB.

### Memory management

The GC is a **non-moving, generational mark-sweep collector with size-segregated pages**, which is
the design GNU R uses, kept because native code holds raw pointers to object data. Reference counts
drive copy-on-modify exactly as `MAYBE_SHARED` expects. The roots are the `PROTECT` stack, the
precious list behind `R_PreserveObject`, global variables, the interpreter's frames, and JIT frames
through Cranelift's stack maps. A minor collection marks only the root-stack entries pushed since
the previous collection, because marks stay set until the next major one, so the cost of a minor
collection does not grow with the roots that lazy-loading base leaves behind.

Collections run on GNU R's schedule, so a script's peak memory follows GNU R's. Objects age one
generation per collection: a minor collection makes a young survivor old, and a deeper collection
makes an old survivor tenured. An intermediate collection frees dead old objects that are not yet
tenured and takes tenured ones as roots through the remembered set. A major collection frees
everything dead. The heap has two limits, as GNU R's `R_VSize` and `R_NSize` do: one on large
vectors (at least 64 MB) and one on small objects (at least 32 MB). When a minor collection leaves
less than a fifth of a limit's minimum free, an intermediate collection runs, then a major one if
that is still not enough. An intermediate collection is skipped when it would not free enough: the
share of the younger old objects (old but not yet tenured) that the last intermediate collection
found dead predicts what it frees now, so a program that keeps what it builds goes straight to the
major collection instead of tracing its young structure twice. A major collection does not update
that share, because a dead tenured object keeps its younger children alive for an intermediate
collection, and after four predicted major collections in a row an intermediate one runs anyway to
measure again. After each major collection the limits move with GNU R's fractions: a
limit grows by a fifth when the survivors plus that fifth fill more than 70% of it, and shrinks by
a fifth when they fill less than 30%. A major collection that escalation forced before the program
allocated a limit's worth of vectors grows the vector limit too, because the working set it keeps
promoting is larger than the survivors show. GNU R's `R_GC_MEM_GROW` and its fraction variables
set the same numbers ([CLI reference](/reference/cli.md#memory)). The nursery's budget for small
objects scales with the old small objects only, as GNU R's cons-cell trigger ignores vector memory,
so a few big live vectors do not let as many bytes of small garbage pile up.

`R_PreserveObject` sets a flag bit in the object's header and appends the object to a dense vector
of preserved objects with their counts, so a frame release asks the header, not a hash table,
whether native code preserved the environment or one of the promises the frame holds. `R_ReleaseObject` searches the vector from its newest entry,
as GNU R's precious list does.

The write barrier is one load and one compare on the parent's header: a store into a young object,
or into an old one that is already remembered, does nothing more. An old object that receives a
younger child joins the remembered set, and a minor collection rescans only what in it can point at
young objects. A list or character vector too large for the small-object pages (2 KB) keeps one card byte per 128
elements after its data, so its stores keep reaching the barrier while it is remembered and the
rescan visits only the dirty cards. An environment's spilled frame keeps a watermark instead,
because its bindings are only appended or compacted: the rescan marks the cells appended since the
last scan, which keeps a namespace that is filled during a load from being rescanned whole at every
collection.

**Native code gets no barrier, so its element pointers escape.** Every C API function that hands
out a pointer into a list's or character vector's elements (`DATAPTR`, `DATAPTR_RO`,
`DATAPTR_OR_NULL`, `STRING_PTR`, `STRING_PTR_RO`, `VECTOR_PTR`, `VECTOR_PTR_RO`, an ALTREP
class's `Dataptr` or `Dataptr_or_null` over such a vector) marks the vector escaped, read-only
pointers included. Packages write through read-only pointers: data.table's `setcolorder` and
`setorder` permute columns and character data with `memcpy` through `DATAPTR_RO`. GNU R
remembers a whole object, so a permutation inside one vector is harmless there, but ry remembers
per card, and moving a young element from a dirty card to a clean one hides it from the next minor
collection, which then frees it. Every collection marks all of an escaped vector's children (a
minor collection does so for a character vector by marking every young string), and a writable
pointer to an old vector remembers it at once, because native code may store a young element
through it. When the outermost native call returns, an old escaped vector that may hold a younger
child has all its cards marked dirty and joins the remembered set, so the next minor collection
rescans it once and its later stores go through the barrier again. It may hold one when it is
remembered (which covers barriered stores and writable pointers) or when a collection ran during
the escape, which can age its children without remembering it. Any other old vector held only old
children throughout, and permuting them cannot change that, so the read-only pointers data.table
takes on every column it only reads cost no rescan. Deferring the rescan to the next collection,
rather than rescanning at return, costs one scan however many native calls touched the vector
between two collections. `RY_GC_VERIFY=1` checks this contract before every collection short of a
major one ([Robustness](/development/robustness.md)).

The escape lasts until the outermost native call returns, so a pointer native code keeps after
that, across two `.Call`s or taken by an embedding host outside any call, is unprotected if it
later moves elements.

Reference counts are settled per list, from an entry the escape records. A writable pointer takes
a snapshot of the list's elements, because native code may replace elements uncounted, and the
retirement counts what the list then holds and releases what the snapshot names. A
`SET_VECTOR_ELT` into that list in between counts the new value at once, so copy-on-modify sees it
shared, and adds it to the snapshot; the value it replaced keeps its count until the retirement
releases it. Collections keep every value the snapshot names allocated until then, which
`RY_GC_VERIFY=1` checks. A read-only pointer records only a digest of the elements that ignores
their order, because permuting them leaves the counts right and copying a large list on every
`DATAPTR_RO` would cost more than the call that reads it. If the digest differs, native code
stored something other than a permutation through the read-only pointer, and every element the
list then holds is counted once more: the counts err high, which keeps objects alive and makes
copy-on-modify copy, but never frees anything still held. The first counted change to such a
list (a `SET_VECTOR_ELT` or a resize) checks the digest that way and takes the snapshot, because
a counted store releases what the slot held, which native code may have put there uncounted. A
resize of a list with a snapshot leaves the dropped slots to the retirement. A list that dies, or
whose elements move to a grown list, before its escape retires is settled from the same entry.
Pointers into atomic vectors need none of this, because their elements are not objects.

A lazy-load fetch allocates pretenured: what it reads is a package's functions and data, which live
as long as the session, so a minor collection would trace them only to promote them. Small objects
come from separate allocation runs whose pages hold no young objects, and no collection runs while
a fetch reads. Their bytes stay out of the nursery's budget, which bounds young garbage, and count
toward the small-object limit once flushed. The next collection flushes them: it makes them old and marked, and remembers each
one that points at a young object. Stores into a pretenured object pass no barrier before that
flush, because the object still looks young, so the flush's check of every child is what keeps the
remembered set exact. A large object is made old when the fetch ends, with the same check. R code
that the reader calls (a namespace or package hook) allocates young, since its temporaries are
garbage.

Vectors of 1 MB or more get an anonymous mapping each. A dead one's mapping is kept for the next
large vector while the kept mappings fit the vector limit, and resized with `mremap`, so a loop's
temporaries reuse resident pages instead of page-faulting in fresh ones. Keeping them never raises
the peak, because a kept mapping is reused before any new one is mapped.

Reference counts also free large temporaries before any collection finds them. A store that
drops a list's or a large atomic vector's count to zero puts it in a zero-count table, and once the
table's vectors add up to 4 MB, the next allocation reconciles it. Reconciling marks the roots one
level deep (the protect stack, the precious set, handles, the interpreter's frames and bytecode
registers, the fields of objects whose stores do not count, and the elements of lists native code
has seen). Then it frees each entry still at zero and unmarked, so a dead list gives up its
elements and a dead large vector's mapping goes back at once. It runs only at an allocation because
C code may hold an unprotected `SEXP` until its next one. Environments, closures and promises stay
with the tracing collector, which also takes care of cycles. Counts only ever overcount, so a
missed decrement leaves an object to tracing and never frees one early. `RY_GC_VERIFY=1` makes a
reconcile free nothing and run a full collection instead, which panics if the collection reaches an
object the reconcile would have freed.

Vectors of a megabyte or more get an anonymous mapping each (`crates/heap/src/large.rs`), which
goes back to the kernel when the vector dies, as glibc's `mmap` threshold returns GNU R's large
vectors. libR's global allocator does the same for its own blocks of that size, so the buffers a
builtin fills before copying them into a vector go back too. A small pool of freed mappings,
resized with `mremap`, saves the next vector's page faults. It holds at most a quarter of the
collection limit, and when no kept mapping is long enough for a new vector it grows the longest
and unmaps the rest, so it never holds memory idle while a vector adds pages. Between those
moments the idle mappings do count toward resident memory, and a major collection trims the
pool to its limit.

The JIT recovers what a moving nursery would buy in other VMs by not allocating in the first place:
unboxed scalars, scalar-replaced temporaries, and vectors fused across a loop (section 5). If
profiling later shows fragmentation, Immix-style regions with opportunistic, pinning-aware compaction
of objects that native code has never seen are the upgrade path, and they need no API change.

**Native calls get a handle scope.** Every object passed into `.Call` stays alive until that call
returns, and so do the objects the API most recently handed to native code: at least the last 1,024
of them, as if they were protected. This makes ry strictly more forgiving than GNU R (code that
forgets to `PROTECT` a recent temporary keeps working, where GNU R could collect it at the next
allocation) while `PROTECT` itself keeps its exact semantics for objects that outlive the call
through globals or preserved references. A loop that allocates and drops millions of temporaries
still runs in bounded memory, because older handouts leave the scope. The scope roots results, not
allocations, so the temporaries of an `Rf_eval` that native code calls stay collectable, and a result
reachable through the argument it was read from (a list element, a cell's `CAR`, an attribute) takes
no handle at all. A view ry builds of something GNU R stores in the argument, such as `FRAME`'s
pairlist, stays rooted until the call returns, because correct code walks it unprotected. Each
native call also owns a region of the `PROTECT` stack: unprotecting below it
is an error, and a region left unbalanced on return is a warning and is cut back.

**Hot accessors are inline.** `Rinternals.h` defines `INTEGER`, `REAL`, `LOGICAL`, `RAW`,
`COMPLEX`, their `_RO` and `_ELT` forms, `DATAPTR`, `DATAPTR_RO`, `STRING_ELT`, `VECTOR_ELT`,
`TYPEOF`, `LENGTH`, `XLENGTH`, `Rf_length`, `Rf_xlength`, `Rf_isNull`, `R_CHAR`, `CAR`, `CDR`,
`TAG`, `CADR`, `CDDR` and `CADDR` as inline functions that read the object header and fall back to
libR for anything unusual (an ALTREP instance, a wrong type, an index out of bounds). `DATAPTR`
and `DATAPTR_RO` are inline for atomic vectors only, and `STRING_PTR_RO` is not inline at all,
because a pointer into a list or character vector must reach libR to escape the vector (see the
write barrier above). A package built against older ry headers inlines those pointers, so ry
refuses to load it until it is reinstalled (`RyAbi:`, in [Packaging](/development/design/packaging.md)). The exported functions take the same fast paths before entering the API, so binaries built
against GNU R's headers benefit too. A package that defines `RY_NO_INLINE_ACCESSORS` gets plain
calls.

Ready finalizers run when a native call returns and on `R_gc`, not inside the collection that found
them, because a collection happens deep inside an allocation, where no native code may run.

**`R_alloc` is an arena.** R frees `R_alloc` memory when the `.C`, `.Call` or `.External` call that
allocated it returns, and `vmaxget`/`vmaxset` let code reset it earlier, so it is a stack of nested
watermarks. ry implements it as a bump allocator that keeps R's alignment and restores the watermark
on return and on a `longjmp`.

**Interpreter hot paths make no Rust allocations.** Every R object comes from the heap's own
allocator, so a Rust `Vec` or `String` that lives only for one call is pure overhead: a `malloc`,
a `free`, and a cache line the next call does not reuse. Three rules keep them off the hot paths:

- A list that is usually short lives on the stack (`SmallVec`), such as the dims of an array, a
  match's capture groups, a parsed `gsub` replacement and the pieces of a `strsplit` element.
- Data that already exists is borrowed: a pattern is looked up by `&str`, a replacement refers to
  slices of its template, and `return()` or `break` unwinds with the jump inline in `Unwind`.
- Text of unbounded length is assembled in one scratch buffer the interpreter owns
  (`Interp::text_buffer`, through `strings::with_text_buffer`). It is an explicit allocator, not a
  thread-local cache: each use takes it, clears it and puts it back, so a nested use gets a fresh
  buffer and the outer one is never clobbered.

A pairlist result is linked cell by cell as it is built (`PairlistBuilder`), with the head rooted,
instead of collected into a vector first. A handler that `withCallingHandlers` or `tryCatch`
establishes comes from a pool of at most 64 entries on the interpreter, and returns to it when its
frame exits unless something still shares it. `crates/interp/tests/test_rust_allocations.rs` pins
the property: it runs pinned shapes (`return()`, `break`, `c()`, group dispatch, `sprintf`,
`paste`, `gsub`, handler setup and others) warm under a counting allocator, and each must stay
within its budget. The budget is zero for all but two shapes: `gsub` with capture groups, whose
regex engine allocates one capture set per match, and `mapply`, whose closure calls build their
call and frame through the general call protocol.

### Errors across the boundary

R signals an error with `longjmp`, and a `longjmp` across Rust frames is undefined behavior. So the
boundary is a thin C layer with two directions:

- **ry calling native code** (`.Call`, `.External`, ALTREP methods, finalizers, C callables) goes
  through a C trampoline that sets up a jump target. A native `Rf_error` or an R error raised in a
  nested `Rf_eval` jumps back to the trampoline, which returns an error value to Rust.
- **Native code calling ry** (every API function) enters Rust through a wrapper that catches the
  Rust-side error (and any panic), drops everything, and only then calls the C function that
  performs the `longjmp` to the innermost native context. The jump skips only the wrapper's frame and
  the exported function's, which hold nothing with a destructor at that point. No Rust frame with
  pending destructors is ever crossed.

`R_UnwindProtect`, `R_ToplevelExec`, `R_ExecWithCleanup` and `R_tryCatch` are C contexts of their
own, because the callbacks native code hands them are native code too, and a C++ exception that a
binding throws from an `R_UnwindProtect` cleanup to run its destructors must unwind only C frames.
`R_tryEval` is plain Rust, because inside Rust an error is already a value. R conditions, restarts
and `on.exit` are implemented natively in Rust, with the C layer only as the bridge. The variadic
functions (`Rf_error`, `Rprintf` and their family) are C too, because stable Rust cannot define a C
variadic function.

### Native packages

Package libraries load with `dlopen`, then `R_init_<pkg>` runs and registers its routines.
`useDynLib` resolves registered symbols first, and C callables live in a global table keyed by
package and name. ry builds source packages itself (`R CMD INSTALL` semantics, `Makevars`, the
compiler flags `R CMD config` reports), and installs prebuilt binaries when the platform matches.

A package library built by GNU R must bind its API calls to ry's `libR`, not GNU R's. On Linux it
names its dependency by soname, `libR.so`, and ry's library carries that soname and is loaded with
`RTLD_GLOBAL` first, so the dynamic loader reuses it. Mach-O binds each symbol to a named library
instead (the two-level namespace), and CRAN's binaries name
`/Library/Frameworks/R.framework/Versions/4.x-arm64/Resources/lib/libR.dylib` while Homebrew's name
its own `libR.dylib`. ry therefore loads a copy of each such library whose `libR` load command is
rewritten in place to `@rpath/libR.dylib`, the install name of ry's `libR.dylib`, and re-signed ad
hoc (`crates/libr/src/macho.rs`, `crates/libr/src/dynload.rs`). dyld matches that load command
against the already loaded image with the same install name, so the package binds to ry. A
dependency the package finds relative to itself must resolve from the copy too, so the cache
mirrors the original's surroundings with links: the copy's directory links to every file beside
the original, and when a load command or rpath climbs (`@loader_path/../lib`), as many ancestor
directories are mirrored as it climbs, each linking to the original's entries. Packages
that `rcmd` builds on macOS link with `-undefined dynamic_lookup` and record no `libR` at all, so
the same build loads under ry and under GNU R. `decisions/libr-rcmd.md` ("macOS packages bind to ry's libR")
has the reasoning.

Windows needs no rewriting. A package DLL that Rtools built imports from `R.dll` by module name,
and the Windows loader satisfies that from an already loaded module with the same base name, so
naming ry's library `R.dll` and loading it first is enough. Package DLLs load with `LoadLibraryExW`
and `LOAD_WITH_ALTERED_SEARCH_PATH`, so a package's own dependent DLLs in `libs/x64/` resolve.

### Threads

R's API is single-threaded, and so is ry's R-level evaluation. Packages such as `RcppParallel`,
`data.table` (OpenMP) and polars run threads that never call the API, which needs no support beyond
the API not being reentrant. `parallel`, `callr`, `future` and `doParallel` use processes, so ry
must be a working `Rscript` replacement that worker processes can start.

## 5. Execution: interpreter and JIT

### The performance bar

Bun's speed comes from three things, and only one of them is the JIT. JavaScriptCore runs four tiers
(the LLInt interpreter, a baseline JIT, the DFG optimizer and the FTL backend) with inline caches,
value profiling and watchpoints, so code warms up gradually and optimized code is invalidated when an
assumption breaks. Bun adds fast startup (a transpiler cache by default, and opt-in bytecode caching with
`bun build --bytecode`), and it implements its hot
builtins in a systems language instead of in JavaScript. ry's equivalents are:

- **A fast first tier and bytecode built ahead of time,** so `ry run script.R` starts in
  milliseconds and a package's compiled code is reused across sessions (see "Where bytecode comes
  from" below).
- **Base R's primitives in Rust,** with vectorized kernels (SIMD where it pays) for arithmetic,
  comparison, subsetting, `sum`, `cumsum`, `match`, `order` and `paste`. Much real R code is a
  sequence of calls to these, and no JIT can make a slow primitive fast.
- **An optimizing JIT for the R code in between,** which is what the rest of this section is about.

Where ry stands against that bar on untyped code: the application workloads (`just bench
applications`: S3 objects, conditions, validation, strings, `lapply` pipelines, records, tables,
xts and zoo, and a testthat suite of small `test_that()` blocks) run faster than on GNU R, but far
from the bar (`benchmarks.mdx` has the current geometric means). The rest is decided by tier 0, the call path and
builtins, because their hot closures run a few hundred to a few thousand times, under tier 1's
threshold. A user's profile of a package test suite agrees: builtins 33% of the time, tier 0 26%,
call setup 22%, GC 8%, and compiled code under 1%, with every closure running inside testthat's
calling handlers. The testthat workload stands in for that suite.

### Where bytecode comes from

Bytecode is build output, never a cache, so nothing checks whether a stored copy is still valid:

- **Installed packages.** `ry install` and `R CMD INSTALL` compile every closure of the package and
  write the bytecode beside its lazy-load database, stamped with the ry build that wrote it. A
  different ry build ignores a stamp it did not write and compiles at first call instead, which is
  always correct; reinstalling refreshes it. This is the code image, described below.
- **Base R.** The base and recommended packages are compiled when the base image is built and live
  in a section of the image beside the heap arenas, keyed by the same runtime hash that keys the
  image (`base-image.md`).
- **Code under development.** `ry load` and scripts compile each closure at its first call. That
  first tier must be cheap enough that compiling a session's working set costs less than reading a
  cache would, which is the bar `ry load`'s lazy loading sets.

### When code compiles and what it binds

Compiled code calls the base functions GNU R's compiler inlines (`+`, `<-`, `if`, `[`, `c` and the
rest of its 233 inline handlers) without looking them up, exactly where GNU R 4.6.2 at its default
optimization level would have compiled the code. A function that masks one of them afterwards
does not reach that code, as in GNU R:

```r
minus <- function(a, b) base::`-`(a, b)
total <- 0
for (i in 1:40) {
  if (i == 10) attach(list(`+` = minus), name = "masking_plus")
  total <- total + 1
}
print(total)
#> [1] 40
```

**When GNU R compiles.** ry follows `R_CheckJIT`, with the `JIT_score` of the body (a loop scores
`MIN_JIT_SCORE`, 50):

| closure | score ≥ 50 | score < 50 |
|---|---|---|
| over the global environment | first call | second call |
| over any other environment | second call | never |
| in a namespace | first call | second call |

GNU R installs a package's closures compiled; ry compiles them at their first call with a loop and
otherwise at their second, binding as GNU R's installed code does. A loop the tree walker
evaluates in the global environment compiles when it starts. A function
defined inside compiled code compiles with it, against its compile-time frames. A closure GNU R
never compiles compiles at its second call, and a typed one at its first, with a guard on every
base function it inlines, so it looks each name up as it runs.

**Closures over one body.** Every closure made from one `function` expression shares the body, and
so do R6's copies of each method. Code compiled for one of them serves the others whose formals and
srcref are the same, from their first call. Guarded code serves any closure that would also guard.
Code that binds serves a closure only under GNU R's `jit_env_match`: its top environment is the
one the code compiled under, and every name its formals and local frames bind was bound in the
compiling closure's frames too. A closure that masks a base function in its own frames therefore
never runs a sibling's code that bound it. It compiles its own code with guards, as GNU R marks
such a closure never to compile.

**What binds.** At compile time, a call binds to base when its head is a symbol that is not one of
the function's locals (GNU R's `findLocals`: formals, `<-`, `=`, `for` variables, literal `assign`
targets) or an enclosing compiled function's, and whose first binding outward from the enclosure
is:

- in a namespace's code, base's binding, for any inline handler;
- elsewhere, `baseenv()`'s binding for one of GNU R's `languageFuns` (`+`, `<-`, `if`, `function`,
  `[` and so on); a mask in the global environment or an attached frame keeps the call dynamic.

`::` and `:::` never bind, `local` binds only with one argument, and `function` does not bind when
its body may call `browser`. Everything else looks the function up as it runs, including every
name without an inline handler (`sqrt`, `paste`).

**Known differences.** Promise code of a call's arguments compiles when the call site first runs,
not with its function, so it binds what the names find then, against the function's locals only.
GNU R's JIT also shares code between two global closures whose bodies are structurally equal, so
the later one inherits the earlier one's bindings; ry compiles each body object on its own.
Pinned by the oracle case `base__compile_time_binding`.

### Code images of installed packages

`R CMD INSTALL` writes `R/<package>.<build>.ryc` beside `R/<package>.rdb` (`crates/interp/src/code_image.rs`).
After the R code is installed, a fresh session loads the namespace, fetches every binding from the
lazy-load database, and compiles each closure the fetches made, nested function bodies included.
When a later session fetches the same record, it notes where each closure's code lies in the image,
and the call that would compile the closure (its second, or its first when the body has a loop)
decodes that code instead. Decoding costs about as much as compiling, so the image does not move
compilation earlier: a namespace fetches many closures it never calls, such as every S3 method it
registers, and calls many others only once. What the image adds is what compiling cannot produce,
the trained profile below. An image holds no machine code (`decisions/jit-ssa.md`, "No baseline tier, and code
images hold bytecode only").

- **Identity.** A record is identified by its offset and length in the database, and a closure
  within the record by the order the stream reader creates closures. The image is stamped with the
  database's length and modification time, so an image written for another database (a reinstall
  by GNU R, another version) is ignored whole. A copy that does not keep modification times loses
  the image, never serves a stale record.
- **Streams.** The image also holds the serialized stream of every record the install fetched,
  uncompressed, after the payloads. A fetch from a database with an image reads that stream in
  place from the mapped file: it does not read the database, inflate the record or copy it, and
  processes that load the same package share the pages. A record the install did not fetch is read
  from the database. Each stream carries a hash that is checked the first time the stream is read
  (`stream_hash`, a word-at-a-time hash, since only one build ever reads the image); a mismatch is
  damage, below, and the fetch reads the database instead.
- **No copy of the source.** A code object points into its closure's body, so the image stores those
  pointers as the preorder position of the object in the body. The body itself comes from the
  database, as without an image.
- **Stamp.** The file starts with a layout magic and the runtime build's identity; any other build
  reads the image as absent and compiles at the second call as usual.
- **Formals.** The compiler's output depends on the closure's formals as well as its body (which
  names the frame can bind, which call updates its first parameter in place), and `formals<-` or
  `as.function` makes a closure that shares a fetched body under other formals. Each noted closure
  therefore keeps its formals, and only a closure with those same formals takes the code; any
  other compiles its own.
- **Damage.** The image only saves compiling, so a damaged one never stops a package from loading.
  A file that cannot be read or parsed, a payload whose hash does not match (checked when the first
  closure of its record is called), a stream whose hash does not match, a record whose closures do not match the database's, or code
  the decoder rejects each print one warning to the console (`cannot use the code image ..., so its
  functions compile as they run; reinstall the package to repair it`). The warning is not
  signalled as a condition, so neither a handler nor `options(warn = 2)` can turn the damage into
  an error. The image is then ignored for the rest of the session, and its waiting code is
  dropped.
- **Verified code.** Tier 0 reads instruction operands, registers, inline-cache slots and jump
  targets without bounds checks, so decoded code passes a linear verifier (`verify` in
  `crates/interp/src/bytecode.rs`) before it runs: every opcode is known, every operand is below its
  table's size, every jump lands on an instruction start, the last instruction cannot fall through,
  and the side tables (loops, feedback, hints, profile) have the lengths the code implies. The
  payload hash is FNV-1a, which catches damage but not a crafted file, so the verifier is what keeps
  a bad image from reading out of bounds. It checks tier 0's assumptions only: an instruction's
  register dataflow is guarded at run time where that is cheap, and the optimizing tier trusts the
  shape the compiler produces. Record instructions carry process-local layout ids, so code that
  holds one is not written, and field and item shape caches are written empty. The decoder also
  keeps only the object bits the encoder can write (the S4 bit) of each constant.
- **Lifetime.** Waiting code holds its body, its formals and the mapped file. `lazyLoadDBflush`,
  which `unloadNamespace` calls, drops all three for its database.
- **Writing.** The image is written to `R/<package>.<build>.ryc.partial`, synced to disk, and renamed over
  the old image, so a crash leaves the old image or the new one. It is never rewritten in place: a
  process that maps the old file would see its pages change under it, or die with `SIGBUS` once
  the file shrank. A failed write removes the staging file.
- **Off switches.** `RY_CODE_IMAGE=0` ignores images when loading; `R CMD INSTALL
  --ry-no-code-image` writes none. A failure while writing an image warns and installs the package
  without one.

The image is uncompressed and about six times the size of the compressed database (MASS: 706 KB
against 120 KB). It is mapped, not read, so a session pays only for the pages of the records it
fetches.

### Tiers

**Tier 0 is a register-based bytecode interpreter.** A closure body compiles to bytecode at its
second call, or its first if it has a loop, unless its bytecode was built ahead of time. Calls count
per body expression, not per closure, and the compiled code belongs to the expression: every closure
made from one `function` expression, and every copy `environment<-` makes (as R6 does for each
object's methods), runs it from its first call when its formals and srcref are the same objects. The code is freed
with the last closure that runs it. A
body changed in place through the C API compiles again for new closures, as in GNU R's JIT cache.
Each call site, variable lookup and
arithmetic operation carries an inline cache and a small type profile: observed `SEXPTYPE`, length
one or not, attributes or none, NA seen or not.

Tier 0 gets its speed from facts fixed before the code runs, not from caches that have to be
checked and refilled:

- **Op words carry their operand count.** Each instruction word holds the opcode in its low 8 bits
  and the operand count above them, so the next instruction's position is one shift and one add,
  with no table lookup.
- **One dispatch loop.** `interpret` in `crates/interp/src/bytecode.rs` keeps the frame, the code,
  the registers and the heap in locals for the whole run, and an error leaves the loop through one
  exit (the `tri!` macro) that hands it to the code's handler table. Single-stepping for the
  debugger is the same loop, compiled with `SINGLE = true`.
- **Slot hints.** Every call of one function binds its formals and locals in the same order, so a
  `GetVar` or `SetVar` site remembers the position in the frame where it last found its symbol.
  The frame's symbol filter is checked first, because most probes miss, and a hint that no longer
  matches falls back to a search and is updated. A wrong hint costs a search, never a wrong answer.
- **Lookups skip function frames.** A function lookup past the local frame walks only the frames
  that can bind the symbol, using the same hints.
- **The call entry reads its fixed facts raw.** The compiler builds the constant pool and the
  vectors in its fixed entries (register count, profile, feedback, slots), so none is ALTREP and
  the entry indexes them directly. The tiers' schedule is checked against one counter, and only a
  call that reaches it leaves the inlined fast path.
- **A new register window is cleared.** Each call's window is filled with `NULL` when it grows, so
  a register the frame has not written yet never holds what an earlier call left there, and a
  collection inside the window frees exactly what GNU R would.
- **Base `.Internal` wrappers are inlined.** A call of one of GNU R's "safe base internals"
  (`nchar`, `typeof`, `inherits`, `identical`, `match`, `rep_len`, `vector`, `which.max` and the
  rest of the list in GNU R's `cmp.R`), or of a frame-free wrapper ry adds (`paste`, `paste0`,
  `sprintf`, `character` and the rest of the `vector` family, `startsWith`, `make.unique`,
  `.row_names_info`), compiles to a guard that the name still means base's closure, the internal's
  arguments evaluated in the caller, and the internal called directly. It applies only when the
  closure's body is exactly `.Internal(f(...))` over its formals and literals, and every default is
  a constant. A `...` formal takes the arguments R's matching gives it and is passed on as the
  internal's own arguments (`sprintf`) or as `list(...)` (`paste`). The internal sees base's
  namespace as its environment, as it would from the closure's frame, and reports errors and
  warnings against the original call, so a message reads `Error in nchar(x, ...)` as in GNU R. A
  failed guard makes the ordinary call, so a replaced base binding is always reached, where GNU
  R's compiled code keeps the original.
- **Builtin checks are derived at registration.** Arity, names, replacement form and which
  arguments a builtin accepts as native values are computed once per builtin (`Checks` in
  `crates/interp/src/builtins.rs`), so a call does not re-derive them from the builtin's name.

**Tier 1 is an optimizing compiler on Cranelift.** Hot functions and hot loops (through on-stack
replacement) compile from bytecode to an SSA IR with R-specific operations, in the style of Ř's PIR.
The IR represents environments, promises and boxed values explicitly, so they can be optimized away:

- **Speculation with deoptimization.** The compiler assumes what the profile and the static types
  say (this `x` is a length-one double without attributes, `+` is base `+`, `f` is the closure seen
  before) and guards each assumption. A failed guard rebuilds the interpreter frame, including any
  environment and promises it elided, and continues in tier 0.
- **Watchpoints instead of guards** for facts that change rarely: a binding cell for `+`, `c` or a
  package function carries a watch set, and redefining it invalidates the dependent compiled code.
- **Environment elision.** A function whose body never reflects on its frame needs no environment
  object. Reflection is visible statically (`environment()`, `sys.function`, `eval`, `assign`,
  `parent.frame` in a callee that the compiler cannot see) and dynamically through the callee check.
- **Promise elision.** An argument that is always forced, and whose expression has no effects,
  is evaluated eagerly, which removes the promise. This is where ry's static analysis helps most,
  because effects and strictness are facts the checker can compute per function.
- **Unboxing and scalar replacement.** Length-one vectors without attributes become machine
  integers and doubles. `NA_integer_` is `INT_MIN`, so integer NA checks are a compare and overflow
  checks are the hardware flag.
- **Vector fusion.** Element-wise chains over vectors of equal length compile into one loop, without
  intermediate allocations, writing into a result allocated once at its final size (construction in
  place, as in goose).
- **Reference-count elision.** Inside compiled code, counts are tracked precisely and increments
  and decrements that cancel are dropped, as Roc does with Perceus. A binding in an elided
  environment still counts as a reference, so `y <- x; x[1] <- 0` copies, and deoptimization
  rebuilds the exact counts. A loop like `for (i in ...) x[i] <- v` copies at most once, on entry if
  `x` is shared, and the per-iteration sharing check is hoisted out. Every elided count is
  materialized before a native call, and native code may write into any vector it is given (section
  2), so the JIT assumes nothing about a vector's contents across one.
- **Borrowed arguments.** An argument the callee only reads is passed without touching its count,
  as Bend's and Roc's borrow inference do. This is a speculation: it applies only when the whole
  callee is compiled and visible, any call to unknown R code or to `.Call` or `.External` counts as an
  escape, and deoptimization restores the counts.
- **Bounds-check elimination** over difference constraints between loop indices and vector lengths,
  as goose does, so `for (i in seq_along(x)) y[i] <- x[i]` runs without per-iteration checks. Only
  positive in-range subscripts are bounds facts; zero, negative and `NA` subscripts, `[[`, and classed
  vectors with their own `[` methods stay behind guards, and a fact about `length(x)` dies when `x` is
  rebound in the loop body.
- **Closure specialization at higher-order call sites.** A call like `vapply(xs, function(x) x * 2,
  double(1))` with a known closure compiles to a loop that calls it directly (ordinary callback
  inlining, inspired by Roc's lambda sets), guarded so that reflection on the closure still works.
  This covers base R's higher-order functions, which ry implements itself; `purrr::map` runs its loop
  in the package's own C code, which the JIT cannot see into.

Cranelift is the right backend: it is a Rust crate, it was designed to compile much faster than
LLVM's optimizing pipeline, and it supports the stack maps the GC needs. LLVM would add a large C++
dependency and compile latency in exchange for low-level optimizations that matter less than the
R-level ones above. A baseline tier between the two, in the style of V8's Sparkplug, was built,
measured and removed: tier 0's dispatch is too small a share of the time for one to pay off (see
the roadmap below).

### What tier 1 does today

`crates/jit` implements the core of this design for loops; the rest of the list above is still
ahead. The JIT is on by default, and `RY_JIT=off` turns it off.

- **When it compiles.** Tier 0 counts entries and backward jumps per body. A body compiles on its
  3000th entry, and a running loop compiles after 10,000 backward jumps and continues in compiled
  code at the loop header (on-stack replacement). A body waits one more threshold per 250
  instruction words before it compiles, because compile cost grows with size (about 10 µs per
  word, 200 ms for `rbind`) and the saving per entry does not, and the wait doubles with each
  recompile. Tier 0 records type feedback
  only over the last eighth of the entry threshold, from half the back-edge threshold, after a
  body's compiled code is discarded, and in the first activation of a body with a loop; a body
  with compiled code records nothing. Each call compares its entry count with the one at which
  the next tier decision is due, so a call with no decision due costs one comparison. The thresholds are high because Cranelift is an
  optimizing compiler: a lower one compiled the methods package's code that a package load runs
  only a few dozen times, which made the load slower, and on a test suite, whose bodies mostly run
  a few hundred to a few thousand times, 1000 entries cost more to compile than it saved. A fully typed closure, one with an inline
  type on every formal, compiles on its first entry instead: the declared types seed the type
  feedback of the instructions that have not run yet, and the guards on them stay. A base builtin
  call or an element-wise operation that has not returned yet takes the type the builtin computes
  for its argument types (`seq_len(n)` an integer vector, `sum` of doubles a double, `x * y` on
  double vectors a double vector), checked after the call like any fed-back type. When an
  operand's type is still unknown (the result of an untyped closure, say), the first-call compile
  is declined without counting against the body, which then follows the thresholds.
- **What it compiles.** A hot body compiles only when compiled code would save work. The planner
  counts three kinds of work in the body: instructions it runs natively, calls it removes or
  makes direct, and instructions it hands back to tier 0 one at a time. A native instruction
  saves about 130 machine instructions and a removed call about 1000. A step back to tier 0 costs
  about 300 more than tier 0 running the instruction itself, and entering compiled code costs
  about 570 more than starting the body in tier 0. A loop-free body whose balance is not positive
  stays in tier 0 for good, `function(x) x^2` for one, and so does a loop whose iterations would
  mostly step, where an instruction in an inner loop weighs eight times one in the loop around
  it. A refused body keeps its type feedback, so a compiled caller can still inline it, and its
  loops stop counting and recording. `RY_JIT_LOG=1` prints each decision with its counts.
- **The IR.** The analysis turns the bytecode and its type feedback (one byte per instruction) into
  a typed plan: one action per instruction plus the abstract state before it, which records each
  register's and variable's type and where each variable's value lives. The translator builds the
  plan into the mid-level SSA IR of `crates/ssa`, which the typed core builds too, and that crate's
  one lowering emits it through Cranelift. A guard in the IR is an instruction whose failure
  branches to a cold deoptimization block. The optimizations that need an R-level IR above it
  (vector fusion, bounds-check elimination) are not built.
- **Unboxing.** Integers, doubles and logicals of length one without attributes live in machine
  registers, with R's `NA` and overflow rules. Element reads and writes on integer, double and
  logical vectors are inline, and a write copies only when the vector is shared. So are `m[i, j]`
  and `m[[i, j]]` reads with scalar subscripts on an ordinary matrix; a subscript out of range,
  `NA` or below 1 hands the read to tier 0, which raises the error.
- **Loops over sequences.** A `for` loop over a compact sequence such as `1:n` or `seq_len(n)`
  never expands it: both tiers compute each element from the first element and the increment, so
  `for (i in 1:1e8)` runs in constant memory. The loop state carries the index, the count, the
  first element and the increment (an increment of 0 means the loop reads the vector's storage),
  and deoptimization hands all four to tier 0.
- **Variables.** A body that never reflects on its frame keeps its variables in slots instead of
  its environment. The environment object still exists, but compiled code writes a variable back
  only before something that could observe it runs (a generic call, a dispatching operation, the
  first read of a formal whose default is an expression, a return, a deoptimization) and reloads it
  after something that could change it. A scalar written back goes into the box the variable
  holds when that box is a plain scalar of the same type that nothing else references, so a loop
  that calls a closure on every iteration does not allocate for its counters.
- **Calls without a frame.** A call of a known closure runs inside the caller's compiled code
  with no interpreter frame, environment or promises, behind a guard on the callee's code. The
  call must bind as tier 0 would bind it without code running: positional, named and omitted
  arguments and literal defaults qualify, and `...`, a default that is code and is read, a loop
  in the callee, a recursive call and a callee without type feedback do not. Every argument the
  callee reads is computed before the call as an unboxed scalar, and the callee's free variables
  are read from its enclosing frames inline. The callee's frame exists only in the frame states
  of its exits: when one is taken, the runtime builds the interpreter frames of the inlined
  calls from the saved values and tier 0 continues inside the callee. The start of such a call
  is one leaf helper that checks what would make a real frame necessary (a calling handler, the
  debugger, a changed closure), and when it declines, tier 0 runs the call instruction.
- **Other calls.** A call to an effect-free closure whose binding was resolved at compile time is direct:
  effect-free arguments are evaluated eagerly and passed as already forced promises, bound by
  position without the general matcher. Evaluating early is invisible only if nothing can assign
  what an argument reads before the callee forces it, so the callee must be effect-free (the fact
  tier 0 also reads, `crates/interp/src/effects.rs`): its body and defaults call only itself, a
  fixed list of base builtins and other effect-free closures, and assign only its own locals.
  When a calling handler is established, a handler could run R code in between, so compiled code
  then runs tier 0's call instruction, which makes the call lazily, and continues after it. A test
  harness always has handlers, so leaving the body for tier 0 there would interpret most of it. A call of a closure that computes a scalar from scalars without
  effects is inlined on unboxed registers, whether the closure is made in the same body or bound
  globally (then guarded by the binding epoch), and whether its body is one expression or a block
  of local assignments ending in a value or `return(value)`. A failed guard inside the inlined
  body hands the whole call back to tier 0, which reruns it lazily; nothing is lost, because the
  body has no effects. A closure whose whole body is
  such a computation, branches, locals and calls of itself or other such closures included, is
  compiled once per argument type to a native function on unboxed values with no frame
  (`crates/jit/src/native.rs`), so a recursive scalar function runs entirely in machine code. It
  counts the expression-depth limit down itself, and anything that would warn or raise returns a
  failure status before anything visible happens, so tier 0 reruns the call. A typed closure's
  checks are decided when its native function compiles. Function bindings are speculated
  against one global binding epoch, which the heap bumps whenever a watched binding changes or a
  watched name is defined in a function frame. Any other closure call is a step: tier 0 enters
  the callee in its own dispatch loop and hands the result back to the compiled code.
- **Returns.** A compiled return writes the assigned locals back to the frame only when something
  can still read it: the frame has an environment, registered exit code, or a promise or closure
  that captured it. Otherwise the locals are dropped with the frame.
- **Speculation and deoptimization.** A guard checks each fed-back type, and a function lookup is
  speculated against the binding epoch. A failed guard boxes the live values, writes back the dirty
  variables and the loop states, and continues in tier 0 at the guarded instruction; the code is
  then invalidated and may recompile, up to four times per body. An R error, `break` or `next`
  raised inside a helper leaves compiled code the same way, so tier 0 handles every non-local exit.
  Compiled code returns to tier 0's loop to deoptimize rather than calling into it, so repeated
  deoptimization never deepens the native stack.
- **Warnings.** A warning can run a calling handler, which may read or assign the frame's
  variables. The fast paths that can warn (integer overflow, an out-of-range read, `sqrt` or `log`
  of a negative number) leave for tier 0 at that instruction without invalidating the code, and
  plain arithmetic or a pure builtin writes the frame back and reloads it afterwards whenever a
  calling handler is established.
- **The C API and the collector.** Every boxed value compiled code holds is stored in the register
  window or a slot's root cell, which the collector scans, so every object is a valid `SEXP` at every
  allocation and every helper call.
- **Measured and removed: a baseline tier.** ry had a Sparkplug-style baseline tier below tier 1:
  per instruction, a call to tier 0's step for it, emitted by ry's own x86-64 and aarch64
  assembler. It ran 6.7% more instructions than tier 0 on `testthat_full` at run time and 3.1%
  more with its compile excluded, while tier 0's whole dispatch is about 3.1% of that workload,
  which bounds what any baseline could save. It was deleted, together with writing its code into
  the code image (`decisions/jit-ssa.md`, "No baseline tier, and code images hold bytecode only").
- **Not yet built:** calls from compiled code straight into the callee's compiled code (a direct
  call still enters through tier 0's call path and allocates a frame and forced promises), result
  types for multi-index subscripts such as `m[i, ]`, and freeing the machine code of invalidated
  bodies.

### Untyped performance roadmap

Plain untyped R decides how ry compares with GNU R, because most hot R code sits in closures called
a few thousand times, under tier 1's entry threshold. This table lists every idea ry has adopted,
plans or rejected for that code, in the order it is built. A status changes with the pull request
that changes it. `prior-art.md` gives the reasoning behind each source engine's verdict.

The gaps come from `ry run --profile-summary` on the application workloads (JIT on: tier-0
instructions 23 to 44% of the time, closure call setup 12 to 24%, builtins about 25%, S3 method
lookup up to 17%) and from callgrind on `seq(1, 10, by = 2)`, which costs 121.4k instructions per
call on ry (JIT off, down from 141.6k when this table started) and about 106k on GNU R 4.3.3. A
plain closure call, `f(x, y = 2) x + y` called from a loop, costs 3,968 instructions on ry and
4,602 on GNU R; timed as the median of 9 interleaved runs of 3 million calls, it takes 0.445 µs
on ry and 0.525 µs on GNU R.

What remains of the `seq()` gap is spread thin. Tier-0 dispatch (loading the op word, decoding it
and jumping) costs about 11k instructions per call, about 13 per op over about 860 ops: 196 jumps,
154 guards, 95 variable reads, 75 constants and 69 builtin calls. Of the rest, `pmin()` costs
55.9k on ry against 43.5k on GNU R, mostly in the `vapply()` it calls. No single step-2 row closes
a gap that size, so shrinking the op count and the cost per op (step 3) comes forward.

**Target.** Untyped R with the JIT on runs at 10 times GNU R's speed on one thread, measured as the
geometric mean over the application workloads (`just bench applications`) and over the package
test suites (`just bench packages`). The milestones are 1.5x and then 3x; `benchmarks.mdx` has
where both suites stand. Parallelism
is deferred: the architecture keeps it possible (`decisions/interp.md`, "Single-thread first, parallel-ready architecture (user directive)"), but the
target does not count on it.

**Where the time goes.** `ry run --profile-summary` splits a run into the buckets below. R code is
everything the evaluator does for R-level code: tier-0 instructions, closure call setup, lookups,
S3 and S4 dispatch, condition handling and tier-1 code. Native code is split by owner: ry's own
ports of base and recommended code (nmath, fft and the rest of `stats`) are ry's to speed up, while
third-party CRAN C code is fixed on one thread, because packages assume R's C API is
single-threaded. I/O is the file and connection builtins, and waiting is `Sys.sleep` and waits on
child processes (`processx`). Shares are of one run with the JIT on.

| Workload | R code | builtins | native, ry ports | native, CRAN | GC | I/O | waiting | start-up |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| conditions | 72% | 20% | 0% | 0% | 5% | 0% | 0% | 3% |
| functional | 64% | 21% | 0% | 3% | 10% | 0% | 0% | 2% |
| objects | 66% | 26% | 0% | 0% | 6% | 0% | 0% | 2% |
| records | 55% | 31% | 0% | 0% | 11% | 0% | 0% | 3% |
| simulation | 3% | 51% | 40% (`stats`) | 0% | 2% | 0% | 0% | 4% |
| strings | 62% | 30% | 0% | 1% | 4% | 0% | 0% | 2% |
| tables | 53% | 27% | 4% | 9% (`data.table`) | 2% | 0% | 0% | 5% |
| timeseries | 59% | 24% | 0% | 13% (`xts`) | 3% | 0% | 0% | 1% |
| validation | 71% | 24% | 0% | 0% | 3% | 0% | 0% | 2% |
| **workload mean** | **56%** | **28%** | **5%** | **3%** | **5%** | **0%** | **0%** | **3%** |
| **corpus mean** (26 packages) | **45%** | **30%** | | **4%** (all native) | **8%** | **1.5%** | **4%** | **7%** |

The corpus row is the mean of per-package shares; the corpus profile does not split native code
by owner. `rlang` and `purrr` set `Config/testthat/parallel: true`, so testthat runs their tests in
a callr worker even on one CPU, and their row comes from the worker's profile
(`RY_PROFILE_SUMMARY_DIR` writes one summary per process): the main process only waits for the
worker in `processx`'s native code. Weighted by time, R code is 53% of the corpus, builtins 23%,
native code 5%, I/O 0.7% and waiting 9.5%. Most I/O is `unlink` (1.7 s of a 158 s corpus run), and most
of that removes single files, such as the `verify_exec_*` files testthat writes around each
snapshot test in `cli`, which cost GNU R the same system call. Removing a directory tree costs
more, because `rmdir` waits on the ext4 journal (0.1 ms on an idle disk, 2 to 4 ms under writes),
and GNU R pays that wait too: a testthat-shaped tree takes about 0.35 ms on both idle and 2.6 ms on
both under write load (`decisions/builtins.md`, "unlink() follows GNU R's R_unlink, with directory descriptors"). The waiting is the suites' own `Sys.sleep`
(`foreach` 77%, `lgr` 22%, `cachem` 10%), which GNU R pays too. Child R processes started through
`callr` and `processx` run ry, because `R.home()`'s `bin/R` and `bin/Rscript` start ry, and
`Rscript -e` starts in 32 ms against GNU R's 140 ms. Start-up dominates the smallest suites
(`abind` 74%, `zoo` 81%). Averaged over the nine workloads, the builtins that take the most time are `[<-` and
`exp` (1.8% each, all on `simulation`'s 30,000-element vectors, where ry already runs twice as fast
as GNU R), then `vapply` (1.2%), `ryStructure`, `.Call`, `<-`, `[`, `lapply`, `list`,
`ryFormatDefault` and `forceAndCall` (0.7 to 1.0% each). On the corpus they are `as.POSIXlt`, `[[`,
`c`, `[`, `lazyLoadDBfetch` and `match` (measured before the row (a) fast paths below).
Counted by calls rather than time, the builtins that compiled code reached outside any fast path
were `!` (476k), `length` (381k), `[[` (257k), `is.null` (181k), `missing` (136k), `[` (127k),
`.Call` (122k), `match` (116k), `is.na` (108k), `identical` (105k), `==` (104k), `names` (92k),
`is.logical` (91k), `is.character` (69k) and `is.function` (64k); the small base closures with the
most self time were `identical` (2.4%), `match` (2.2%), `nrow` (1.5%), `isTRUE` (1.4%), `vapply`
(1.4%), `stopifnot` (1.3%), `%in%` (1.0%) and `%||%` (0.9%).

**The arithmetic.** Speeding each bucket up by the factor below, with CRAN native code, I/O and
waiting fixed, gives these geometric means over GNU R (Amdahl's law per workload, starting from
today's ratio):

| Plan | R code | builtins | ry ports | GC, start-up | workloads | corpus |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 1.5x milestone | 2x | 1.5x | 1x | 1x | 1.43x | 2.96x |
| corpus 1.5x | 3x | 2x | 1x | 2x | | 4.28x |
| 3x milestone | 5x | 3x | 3x | 2x | 3.08x | 5.74x |
| 10x target | 30x | 10x | 10x | 10x | 10.96x | 15.52x |
| ceiling: only the fixed buckets left | | | | | `tables` 8.9x, `timeseries` 8.1x | 34.4x |

So 10x on the workloads is reachable on one thread: R code needs about 30x (tier 1 for most of it,
row (c) below) and builtins about 10x (row (a)). `tables` and `timeseries` stop near 9x and 8x
because of `data.table`'s and `xts`'s C code, and the geometric mean carries them. The corpus
runs at 2.01x GNU R today (geometric mean over the 21 packages that pass on both engines, 95%
interval 1.83x to 2.20x). The corpus runs offline: `run.py` drops test files that fetch URLs
(`NETWORK_TESTS`, such as `jsonlite`'s `test-network-*.R`, whose GitHub requests cost both engines
the same 0.2 s each) and routes both engines through a proxy that refuses every request, so a test
that reaches for the network fails the run. Its column counts all native code as fixed, because the profile does not
split ry's ports from CRAN code, and its single-thread ceiling is 34.4x, because I/O, waiting and
native code are small. The lowest per-suite ceilings are `lgr`'s 7.7x (its `Sys.sleep`), then
`rlang`, `withr` and `cli` at 11x to 12x (their native code and waiting).

| Target row | Status | What it needs |
| --- | --- | --- |
| (a) Builtins several times faster than GNU R's C: no allocation on the fast path, SIMD kernels, fused element-wise temporaries | in progress | builtins from 28% (workloads and corpus) to 10x faster; the top of the ranking above first. Built: `attributes`, `c`, `[[` and `[[<-` with constant subscripts, `forceAndCall`, a builtin `FUN` in the apply family, `Reduce`, the one-argument builtins `!`, `length`, `is.null`, `is.na`, `is.character`, `is.logical` and `is.function` in compiled calls, and native entries for `identical`, `isTRUE`, `isFALSE`, `nrow`, `ncol`, `match`, `%in%` and `%||%` (the "Builtin fast paths" rows below), compiled call sites that force the strict arguments of `typeof`, `identical`, `inherits`, `is.vector` and `match` as GNU R's compiler does, so an argument that is still an unforced promise over R code (a caller's `g(k + 1L)`) takes the native entry too (per call, JIT off: `typeof` through two wrapper layers 9,232 to 6,317 instructions, GNU R 5,834; `typeof(k + 1L)` 6,729 to 4,162, GNU R 3,244), a tier-0 op for `missing()`, `lapply` and `vapply` that reuse `i` and read `X[[i]]` directly per element, `structure()` that sets attributes in place, tier-0 `%%` and `%/%`, element assignments indexed by `$` and `[[` reads, a `.Call` that resolves its routine from the address pointer, `x[i] <- v` written in place, direct entries for `[`, `.Call` and `round` (the entry takes the call, so builtins that name it in errors qualify), names appended in place by `$<-` and `[[<-`, `m[, j] <- v` as contiguous block copies, array reads such as `X[, , k]` that walk the selected offsets without listing them (1.7x to 2.5x faster than before on a 1000 x 1000 x 20 double array, ahead of GNU R), scalar `-x`, a native `Reduce(accumulate = TRUE)`, element assignments that stay in slot frames, element stores with computed subscripts that stay in bytecode and append at `length(x) + 1` with amortized growth (tier 0, per iteration: `x[length(x) + 1L] <- k` 1,557 instructions, GNU R 2,550; `x[[length(x) + 1L]] <- k` on a list 1,622, GNU R 5,445), character element reads, `c()` of lists as one copy per argument, and negative subscripts and builtin argument matching without allocation. Under the JIT, `x[[i]]`, `x[[i]] <- v` and `x[i] <- v` run at a tenth of GNU R's instructions or less; at tier 0 the scalar reads and stores, list stores included, cost less than GNU R's net of the loop (`x[2L]` 4% more), through fast handlers for the ops around the builtin (the fourth table under "Builtin fast paths"). Per call, `[` with a negative, logical or character subscript, `round`, `m[, j] <- v`, name appends and `Reduce` match or beat GNU R (the second table under "Builtin fast paths"). Next: what is left is closure frame setup inside `structure()`, `format.default` and `Reduce`'s callee, which is the frames and call convention of row (c), and `.Call`'s loop and JIT call sequence |
| (b) Automatic parallelism for effect-free apply-family calls and long element-wise operations, deterministic, with bit-identical reductions | deferred, architecture-ready | the effect-free fact per function and the invariants in `decisions/interp.md`; package native code stays single-threaded. Deferred because the target users already run their test suites in parallel across processes and are CPU bound, so every core is busy and threads inside one process would only compete with the other workers. Single-core speed is the goal, and every cost paid per process (warm-up, compile time, package loading, resident memory) is paid once per worker |
| (c) Tier-1 compilation of most R-level time | planned | R code from 56% (workloads) to 30x faster; tier 1 today runs under 3% of the time on eight of nine workloads |
| (d) Native code shrinks only through faster ry ports or parallelism; third-party C is not replaced | in progress | ry's own ports are ry's to speed up; third-party C stays: `data.table` and `xts` on the workloads, `data.table` and `rlang` on the corpus. Built: vector kernels for the d/p/q functions, batched samplers, and AVX2 twister, tempering and inversion lanes, bit-identical to GNU R ("Distribution functions and the RNG run as vector kernels and batched samplers" in `decisions/builtins.md`). `rnorm` costs 67 instructions per normal (164 before); per element at length 1e6 `rnorm` is 3.2x GNU R, `runif` 5.7x, `qnorm` 3.0x, `pnorm` 1.7x and `rpois` 1.1x. The native bucket of `simulation` fell from 0.53 s (53%) to 0.30 s (40%), and the workload runs 1.26x faster (1.15 to 1.43 over 9 rounds). `sample` draws its indices in integers: per element at length 1e6, `sample(1e6)` is 2.7x GNU R and `sample(1e6, replace = TRUE)` 3.7x. Stats closures of the form `.Call(C_routine, ...)` enter their routine directly, without a frame, and decline to the R body on any warning or error ("Stats distribution closures enter their routine directly" in `decisions/builtins.md`): per call, `dnorm(x)` and `pnorm(x)` take about 0.46 µs (GNU R 1.0 and 1.1 µs) and `rnorm(1)` 0.68 µs (GNU R 2.8 µs). `pnorm`'s exponentials and the `qnorm` tail logarithms run on the exact vector ports of glibc's FMA `exp` and `log` that the fused element-wise kernels use: per element at length 1e6, `pnorm` is 1.80x GNU R (1.19x over the scalar loop) and `qnorm` on tail probabilities 2.09x (1.19x). `sample.int(N, n)` with `N / 128 <= n` tracks drawn values in a bitset, 2.64x GNU R at `sample.int(1e8, 1e6)` (1.21x over the hash set) |

| Idea | Source engine | Status | Measured gap it targets | Code |
| --- | --- | --- | --- | --- |
| **1. Tier-0 call path** | | | | |
| Op words carry their operand count; one cold error exit | JSC LLInt | built | dispatch, about 15 instructions per op | `interpret`, `failed` in `crates/interp/src/bytecode.rs` |
| Slot hints at lookup sites, behind the frame's symbol filter | JSC, V8 inline caches | built | variable lookup | `cached_cell`, `Frame::find_hinted` in `crates/heap/src/env.rs` |
| Function lookups skip frames that cannot bind the symbol | ry | built | `lookup_function` | `lookup_function` in `bytecode.rs` |
| Lookup stamps compared as their bits | V8 | built | 1.25k per `seq()` call | `LookupCache` in `bytecode.rs` |
| Index only for frames over 32 bindings: one open-addressed block of packed (hash, position) words | ry | built | 3k per `seq()` call (`Frame::insert`) | `INDEX_THRESHOLD` in `env.rs` |
| Literal `pkg::name` reads the namespace binding it found, while the stamps of the bindings that led there stand still | JSC watchpoints | built | `namespace_lookup` on testthat_full, JIT off: 33,841 calls to 1,549 over five repetitions | `Op::Namespace` in `bytecode.rs`, `namespace_binding` in `envir.rs` |
| Frameless `GetFun` for a slot holding a function and for a cached global function | LuaJIT, CPython | built | testthat_full, JIT off: the `GetFun` handler 22.7M to 12.4M instructions per repetition | `get_fun_fast` in `bytecode.rs` |
| Builtin checks derived at registration | GNU R `PRIMARITY` | built | builtin call overhead | `Checks` in `crates/interp/src/builtins.rs` |
| A call plan per call site: arguments written straight into the callee's slots | JSC `CodeBlock`, V8 | built | `run_closure`'s matching and binding; a call from a loop costs 2,330 instructions, down from 3,065 on heap frames | `direct_plan` in `bytecode.rs`, `call_with_plan` in `eval.rs` |
| Closure frames in fixed slots: a call builds its frame in the slot above the top and pops by lowering the depth, never moving it | CPython 3.11 frame stack, Lua `CallInfo` reuse | built | frame push and pop: a call from a loop costs 2,844 instructions, down from 2,927; testthat_full -1.16% with the JIT off and -1.17% with it on, `validation` -0.91% | `FrameStack` in `crates/interp/src/interp.rs` |
| Tier 0 continues its dispatch loop in the callee: a call to a compiled body pushes a resume record instead of entering Rust, and every way out of the body goes back through it | CPython 3.11 inlined Python calls, LuaJIT | built | the Rust entry and exit per call: the planned `h -> f` pair 4,127 to 2,725 instructions, and with the JIT off `expr_tree` -10.4%, `validation` -1.5%, `objects` -0.8%, `conditions` +0.0% | `enter_in_place`, `finished` in `bytecode.rs`; `enter`, `leave`, `apply_closure_entering` in `eval.rs` |
| **2. Call facts ahead of time** | | | | |
| Version-stamped bindings: a function guard is one compare | JSC watchpoints, V8 property cells | built | 154 guards per `seq()` call; 141.6k to 139.7k instructions per call | the `Op::Guard` arm and `cached_cell` in `bytecode.rs` |
| A guard on a base function is two bit tests and one load: no binding of the symbol outside base and an attached enclosure chain mean the base binding answers it. Every route that binds a symbol in a frame marks the symbol, and the mark never clears | JSC watchpoints | built | testthat_full over five repetitions, JIT off: 4,145.6M to 4,132.8M instructions (-0.31%), `run_guard` 26.1M to 13.7M; an environment write costs 6 more (934 to 940) | `guard_fast` in `bytecode.rs`; `BOUND_ELSEWHERE`, `DETACHED` and `mark_bound_elsewhere` in `crates/heap/src/env.rs` |
| Frames cleared in place, without copying the cell list | ry | built | `clear_frame`; 139.7k to 136.6k per `seq()` call, with the two rows below | `Heap::clear_frame` in `crates/heap/src/heap.rs` |
| Untyped closures skip the signature lookup; `on.exit` handling only when an exit expression exists | ry | built | part of the 3.1k above | `signature_of` in `crates/interp/src/annotations.rs`, `run_closure` in `eval.rs` |
| Frames as slot arrays, with an environment that binds a variable only when a lookup asks for it | Ř, V8 | built | binding cells, promises and environments per call (`slot-frames.md`, "Measured") | `bind_slots`, `pending_env`, `box_variable`, `lift_frame` in `eval.rs`; `slot-frames.md` |
| Promise elision for strict, effect-free arguments | Ř | done in tier 0 (`crates/interp/src/effects.rs`) | `closure_args_into` 3.8% of a call microbenchmark | `f(i, 1)` 3,968 to 3,411 instructions per call; `seq()` unchanged, its helpers are not effect-free |
| Cheaper promises: created lazily, held inline in the frame slot, or allocated from a per-call arena | Ř, GNU R | rejected, measured | a closure call on the testthat workload costs about 8,100 instructions with 1.2 promises; allocating a promise is a nursery bump, and promises are 1.4 of the 7.4 objects freed per call. None of the three designs saves more than that allocation, and each changes what `PRCODE`, `PRENV`, `substitute` and `delayedAssign` see | |
| Formals bound in one pass; a forced promise settled with one barrier; the stack check against a cached floor | ry | built | defining formals 270, settling 87 and `stacker`'s thread-local lookup per call; 8,174 to 8,140 instructions per closure call on the testthat workload | `Frame::insert_formals` in `crates/heap/src/env.rs`, `Heap::settle_promise`, `on_large_stack` in `eval.rs` |
| The promargs pairlist built only when asked for | GNU R | planned | `args_pairlist` 2.7% of a call microbenchmark | |
| Argument-match caches, one entry per closure body | V8, JSC | done (`eval::match_args_cached`) | `match_args` 2.8k, `bind_arguments` 2.8k per `seq()` call | matching in `seq()` 3.6k to 1.0k instructions; 1.0 to 1.2 million named calls per application workload |
| Polymorphic inline caches for S3 and S4, keyed on the class vector | Self, V8 | built | S3 method lookup up to 17% (`timeseries`); instructions per dispatch: `UseMethod` 8.75k to 7.69k (GNU R 9.82k), with `NextMethod` 23.14k to 19.04k (GNU R 19.03k); one `NextMethod` level from a method in slots 20.55k to 17.16k (GNU R 4.6.2 17.74k), `standardGeneric` 14.26k to 8.69k (GNU R 11.68k) | `resolve_s3`, `site_hit` in `crates/interp/src/dispatch.rs`; `S4Cache`, `dispatch_generic` in `crates/interp/src/methods.rs` |
| Closed bindings per locked namespace, reopened by `unlockBinding` and `assignInNamespace` | Bun, Roc | planned | namespace function lookups | |
| Precise counts and borrowed parameters in tier 0 | Roc (Perceus) | planned | copies and peak memory | |
| Setter instruction for one-level complex assignment | GNU R bytecode | built | `attributes(m) <- NULL` 4.2k to 1.5k instructions (GNU R 1.1k); `mostattributes(m) <-` 11.0k to 9.5k (GNU R 6.9k); `seq()` 136.2k to 135.0k | `Op::Replace`, `replace_variable` in `bytecode.rs` |
| Native prologues for hot base closures (`match.arg`, `stopifnot`, `setdiff`, `structure`, `format.default`, `Reduce`), installed by hash on the R version they were written from | ry, after the methods core | built | `validation` workload 0.6x to 1.87x GNU R; 2.71G to 1.32G instructions (JIT off) | `crates/interp/src/base_fast_paths.rs` |
| Native prologues for hot package closures, installed by hash from `registerS3methods()` on each namespace load: rlang 1.3.0's `trace_back`, which every `expect_error()` and `expect_warning()` runs | ry | built | testthat workload 6.79G to 4.69G instructions (JIT on and off) | `crates/interp/src/package_fast_paths.rs` |
| Builtin fast paths without string round trips or repeated evaluation: `attributes` and `c` take names as CHARSXPs instead of interning them again; the compiled `[[` read serves classless lists and the in-place element assignment takes a constant name; `forceAndCall` reuses its call's argument cells; `lapply` and `vapply` hand a builtin `FUN` (or `[[`) the element they read; `Reduce` gets a native prologue | ry | built | instructions per call, JIT off, before and after (GNU R): `attributes` on an xts object 4,183 to 1,786 (2,692); `c(1:3, 4.5)` 4,262 to 2,131 (2,731); `c(a, z = 3)` 5,964 to 4,616 (4,299); `x[[2L]]` 1,150 to 698 (709); `x[["fee"]]` 1,674 to 693 (1,805); `x[["net"]] <- 3` 4,910 to 987 (2,011); `forceAndCall(2, f, x, y)` 5,520 to 4,232 (5,198); `` vapply(rows, `[[`, 0, "fee") `` over 100 rows 421.8k to 260.0k (363.4k); `Reduce(f, x)` over 100 elements 748.7k to 423.1k (688.8k) | `do_attributes`, `do_c` in `crates/interp/src/subset.rs`; `cached_item` in `records.rs`; `do_force_and_call`, `force_and_call_with`, `call_with_values` in `eval.rs`; `do_reduce` in `base_fast_paths.rs` |
| One-argument builtins without dispatch, and native entries for small base closures: compiled code calls a builtin's `unary` function with the operand register before any dispatch, and a call to a hash-guarded base closure whose arguments are already values runs natively without a frame | ry | built | instructions per call, JIT off, before and after (GNU R): `!x` 944 to 563 (750); `length(x)` 1,002 to 772 (1,232); `is.null(x)` 754 to 575 (697); `is.na(x)` 1,128 to 641 (1,490); `is.character(x)` 754 to 574 (699); `identical(x, y)` 8,545 to 1,818 (3,149); `isTRUE(x)` 6,087 to 1,114 (5,594); `nrow(m)` 4,575 to 1,324 (4,075); `match(x, t)` 6,869 to 1,905 (2,963); `x %in% t` 11,327 to 1,745 (8,226); `x %\|\|% y` 3,293 to 1,027 (absent in GNU R 4.3.3) | `BuiltinDef::unary` in `builtins.rs`, its call in `op_call_builtin` (`bytecode.rs`); `native_entry` and `NATIVE_ENTRIES` in `base_fast_paths.rs` |
| Getter instructions for nested complex assignment (`names(x)[2] <-`, `x$a$b <-`) | GNU R bytecode | planned | `complex_assign` calls a primitive setter with its values and builds a call for each getter level | |
| **3. LLInt- and LuaJIT-grade tier 0** | | | | |
| In-place specialization (quickening) with value profiles | CPython (PEP 659), JSC | built for scalar integer and double arithmetic and comparisons; a comparison that a `JumpUnless` tests takes the branch itself | `while (i < n) i <- i + 1L`, JIT off: 1,123 to 406 instructions per iteration with the two rows below | `QUICK_ARITHMETIC`, `quick_arithmetic`, `arithmetic_miss` in `bytecode.rs` |
| Frameless fast handlers: a call-free fast path per hot instruction, with the generic handler a tail jump away | LuaJIT, LLInt | built for `GetVar`, `SetVar`, `Guard`, `JumpUnless`, `Jump`, `Constant`, `SetSrcref`, `EndStatement` and the quickened arithmetic | the callee-saved spills of every handler; scalar results from `Heap::try_alloc_scalar`, which never calls | `fast_paths!`, `GENERIC_HANDLERS` in `bytecode.rs` |
| Cold fallbacks of in-loop instructions after the back edge | LuaJIT, V8 | built | loop bodies contiguous in the code vector | `back_edge` in `bytecode.rs` |
| Guards folded into one version check per body entry; code, registers and pc pinned as handler arguments; the visible flag set once per statement | LuaJIT | planned | the warmed loop's remaining 406 instructions: three guards (about 34 each), three `GetVar`s (about 31 each), `SetVar` (52) | |
| Tail-call dispatch, one indirect jump per handler | LuaJIT, JSC | built | the shared indirect jump; measured level with the match loop (121.4k against 120.8k per `seq()`), since handlers that call out still need a frame. The handler signature is `(activation, pc)` so that few values stay live across calls | `handlers!` in `bytecode.rs` |
| Superinstructions for the most frequent op pairs | CPython, LuaJIT | rejected, measured | the 20 hottest pairs cover 38.8% of executed ops on testthat_full, JIT off, yet instructions moved +0.08% and wall time stayed within noise: with one indirect jump per handler, a fused pair saves a jump the branch predictor already predicts | the branch `perf/tier0-superinstructions` |
| Dense feedback storage, one slot per profiled instruction | V8 | planned | feedback is one `i32` per code word | |
| One kernel layer for vector builtins: vectorized slice kernels, results written into dead temporaries, and an `Op::Fused` superinstruction that evaluates an element-wise tree in 512-element chunks or declines before anything observable happens | pqR (`R_allocOrReuseVector`, task merging), Riposte | in progress | builtins 51% of `simulation`; one allocation and one pass per operator. `y <- exp(-x^2/2) * k` runs at 1.4 to 1.6 ns per element against GNU R's 6.3 (4x), `x * k + 1` at 0.3 against 1.8 | `crates/interp/src/kernels.rs`, `vector_math.rs` |
| **4. Optimizing tiers** | | | | |
| Per-argument-type native functions for scalar closures | Julia | built | recursive scalar functions | `crates/jit/src/native.rs` |
| Baseline compiler from bytecode, no optimization | V8 Sparkplug | built, measured and removed | warm code under the 3000-entry threshold. It compiled in a median of 28 µs per body, but ran 6.7% more instructions than tier 0 on `testthat_full` (3.1% with its compile excluded), while tier 0's whole dispatch is 2.66% of that workload (about 3.1% with pc bookkeeping), so no call-threaded baseline can pay off | `decisions/jit-ssa.md`, "No baseline tier, and code images hold bytecode only" |
| A lower Cranelift threshold | HotSpot, .NET tiering | measured, kept at 3000 entries; large bodies wait in proportion to their size, and a loop-free body compiles only when its call rate over the recording window (its share of the session's closure calls) promises enough calls to repay the compile | tier 1 under 3% of the time on eight of nine workloads. Callgrind geomean against JIT off: 1000 entries 1.015, 2000 1.016, 3000 1.013, 6000 1.010, 10,000 1.010, so the threshold does not decide on against off. The rate check took testthat's JIT-on cost over JIT off from 17.6M to 5.6M instructions and kept every functional callback compiling | `SIZE_WAIT_WORDS` and `repays` in `crates/jit/src/jit.rs` |
| Cross-closure inlining with deoptimization | Ř (PIR) | partly built: effect-free closures, single-expression or block bodies, guarded on callee identity; a failed guard reruns the whole call in tier 0. Callees with effects, which need frame materialization, are planned | calls from compiled code re-enter tier 0 | `inline`, `lower_block` in `crates/jit/src/analysis.rs` |
| Escape analysis, scalar replacement, vector fusion | Graal, goose | planned | scalar and intermediate vector allocation | |
| Per-signature numeric specialization of vector code | Julia | planned | | |
| Effect-free `lapply`, `vapply`, `Map` and long element-wise operations across cores; reductions stay sequential | Bend | planned | wall time of independent per-element work | |
| **5. Memory and start-up** | | | | |
| A start-up image of the heap's pages at a fixed address, mapped privately and shared until written | V8 snapshots, Bun | built | empty `ry run` 121.5M to 47.9M instructions, 38.5 to 29.2 ms; 4 concurrent workers 117 to 87 MB Pss | `crates/heap/src/image.rs`, `fill_from` in `crates/interp/src/image.rs` |
| No major collection while a namespace loads; the limit is rebased when the outermost load returns | ry | built | 2 major collections to 0 loading testthat, xts, data.table and a 40,744-object package; GC 15.7% to about 5% of the load | `enter_namespace_load` in `crates/heap/src/heap.rs` |
| Lazy-load records read with borrowed strings, bulk vectors and iterative pairlists; `makeLazy` with GNU R's shared environment; S4-generic checks answered from a record's header | GNU R | built | `library()` of 11 packages: 1,197.8M to 1,133.0M instructions, 914 records fetched to 651 | `crates/interp/src/serialize.rs`, `do_local_s4_generics` in `envir.rs` |
| Card marking for remembered old objects | V8, HotSpot | planned | minor collections during a load cost about 24M instructions each, mostly re-marking namespace frames being filled | |
| A buffered `unserializeFromConn` | GNU R | planned | it reads a few bytes per call: 93M instructions of the 11-package `library()` | |
| Per-package code images written at install time, beside the lazy-load database | Bun | built, no speedup yet | package load and warm-up; decoding a closure costs about what compiling it does, so untrained images cost 1.3% more instructions on `library(survival)` | `crates/interp/src/code_image.rs` |
| Install-time machine code from whole-program facts (checker types, closed namespace bindings, effect-free functions), values from outside tested once where they enter, no profiles | Bun (`--aot`) | built for scalar numeric closures, measured neutral, removed (`decisions/jit-ssa.md`, "No baseline tier, and code images hold bytecode only") | testthat workload 7.850G against 7.834G instructions with images off, because few package functions are scalar numeric | |
| One SSA IR for tier 1 and the typed core: typed facts unguarded, untyped speculations guarded with deoptimization exits; install-time code through the typed AOT pipeline, with its deoptimization metadata and watched bindings in the code file | Ř (PIR), Graal | IR built; install-time code planned | two SSA forms and two lowerings to Cranelift | `crates/ssa` |
| Profiles from a training run (the package's tests and examples) stored in the per-package image | HHVM Jump-Start, Project Leyden | built, no speedup yet: loops tier up within their first call anyway, and a training run on other types makes the JIT refuse to recompile | hot closures that never reach tier 1's thresholds | |
| Images shared across worker processes | Bun | planned | resident memory per `parallel` worker | |
| Concurrent tracing and Immix line reuse | LXR | planned, after collector pauses are measured | collector pauses, fragmentation | |
| A stackless tier 0 | Bend | planned, on the tail-call handlers | Rust frame setup per R call | |
| **Rejected** | | | | |
| Copy-and-patch as a tier | CPython (PEP 744) | rejected | | |
| Meta-tracing | PyPy | rejected | | |
| A partial-evaluation framework (AST interpreters) | Truffle and Graal | rejected | | |
| Generating the interpreter from LLVM IR | Deegen | rejected | | |
| Freeing R objects when their count reaches zero | LXR | rejected | | |
| Lazy fused vectors as ALTREP objects | Riposte, pqR | rejected | every reader, C code through `DATAPTR` included, would materialize them, and where a deferred warning surfaces would become observable | |

### The vector kernel layer

R's vector builtins share one kernel layer in `crates/interp/src/kernels.rs`, which is target row
(a)'s design for element-wise work. It has three parts.

- **Slice kernels.** A kernel takes each operand as a slice or a scalar and writes into an output
  slice. It touches no R object, allocates nothing and raises nothing: an integer kernel returns an
  overflow flag, and its caller warns. The loops vectorize for the baseline instruction set (SSE2
  on x86-64). There is no separate AVX2 build: the loops are bound by memory traffic, and a second
  copy of every kernel costs resident code. Compiled code calls this layer directly.
- **Reuse.** An operation writes its result into an operand's buffer when the bytecode compiler
  marked the operand's register as a temporary read only by this instruction, and at run time the
  value's count is zero, it is mutable, not ALTREP, and has the result's type and length. The
  compiler's mark is needed because registers hold uncounted references, so a zero count alone does
  not prove the value dead. This is pqR's `R_allocOrReuseVector` rule, restricted to what the
  compiler proves. The evaluator offers a second destination: in `x <- f(x, ...)`, where `f` is an
  element-wise builtin and `x`'s binding holds the only reference to its value, the result goes
  into `x`'s buffer. Every kernel takes its destination as an argument that may be one of its
  operands, and reads that operand from the output buffer, so aliasing is exact under recycling.
  A destination of length one is never reused, because the shared `TRUE`, `FALSE` and `NA`
  constants can look private. A scalar operand of a math function, a comparison or unary minus is answered without the element loop.
- **Complex arithmetic.** `+`, `-`, `*`, `/` and `^` with a complex operand run as slice kernels
  under the same reuse rule. `*` and `/` are ports of libgcc's `__muldc3` and `__divdc3`, which
  GCC-compiled GNU R uses and Rust's runtime replaces with compiler-rt's, and every step keeps
  GCC's operand order so the same NaN payload wins: results match GNU R bit for bit, `NA` versus
  `NaN` included. `^` is GNU R's `mycpow`, and `z^2` reproduces `R_cpow_n`'s `1 * (z * z)`. A double
  beside a complex vector is lifted per element, NA as `NA + 0i`.
- **Reductions.** `sum` on integers, `any`, `all`, `min`, `max` and `range` are SIMD kernels;
  `range` finds both bounds in one pass. `prod` and the double `sum` accumulate in x87 long double
  as GNU R does, so they keep scalar loops.
- **Fusion.** For an element-wise tree such as `a * b + c` or `sum(x > 0)` whose leaves are
  constants and variables, the compiler emits `Op::Fused` in front of the ordinary code. The
  instruction reads the leaves in the ordinary code's order (forcing an argument's promise as a
  variable read would) and checks every operator's binding through its guard cache. It declines
  and falls through to the ordinary code on anything observable (an active binding, an attribute,
  an object, ALTREP, recycling other than scalar against equal lengths, integer overflow, a NaN
  that a math function produced), so fused and unfused evaluation cannot be told apart. It also
  declines when every leaf is a scalar or the tree's vectors are shorter than 64 elements, where
  the ordinary instructions are cheaper because a short vector saves little allocation. Otherwise
  it runs the tree in 512-element chunks, writes only the root, and records the type feedback of
  the instructions it skipped, so the JIT, which compiles the ordinary code, sees the same types.
  A leaf may also be a call the pass cannot compute, such as `mean(x)` in `sum(x - mean(x) > 0)`,
  as long as no operator of the tree runs before it. The compiler first checks the guards of the
  operators R looks up before the call, then evaluates the call and the variables read before it
  into registers, in R's order, and both the fused pass and the ordinary code read those
  registers, so the call runs exactly once. If one of those guards fails (an operator redefined
  in the frame), the whole expression goes to the evaluator before anything ran. A call that may
  modify a variable in place (an assignment, `eval`, a replacement call) stays unfused. A site
  that declines 16 times in a row rewrites its opcode to `Op::Unfused`, which does nothing, and
  drops its program, so a site that never fuses costs one dispatch in tier 0 and no heap.
- **Assignment into the old buffer.** For `y <- expr`, a fused double pass writes its result into
  the vector `y` already holds when nothing else can see that vector: the binding is not active
  or locked, the vector's count is one, and it has the result's type and length. `y` may be a
  leaf of the tree, as in `x <- exp(-x^2 / 2) * 0.5 + x`; the pass then keeps each chunk in
  scratch and copies it over `y`'s elements only after every node has read them. A loop that
  reassigns a vector therefore allocates nothing after its first pass. Integer passes never
  reuse, because an overflow halfway through declines to the ordinary code, which must still
  read the old value.
- **SIMD `exp` and `log`.** On x86-64 with AVX2 and FMA, `exp` and `log` of doubles, alone or
  inside a fused pass, run four lanes at a time (`crates/numeric/src/vector_math.rs`). They are
  ports of glibc's `__exp_fma` and `__log_fma`, the variants GNU R calls on such a machine, and
  agree with them bit for bit; the first call compares both on edge values and falls back to
  glibc when they differ. `pnorm` and the `qnorm` tails call the same kernels on batches of
  their exponent and logarithm arguments. Table lookups use paired 128-bit loads rather than gathers, which the
  Gather Data Sampling mitigation makes slow. `x^2` is `x * x` and division by a power of two is
  multiplication by its exact reciprocal, which give GNU R's bits, NA's quieted payload included.

NaN results match GNU R 4.3.3 on x86-64, where an operation on two NaNs returns the first
operand's payload. GNU R's compiled loops swap the operands of `+` and `*` on two doubles when the
left one is a scalar beside a longer vector or when both recycle, so `NA_real_ + c(NaN, 1)` is
`NaN` while `c(NA, 1) + NaN` is `NA`; with an integer operand, and for `-`, `/` and `%/%`, the
first operand's payload wins. The kernels reproduce each case. Beside a scalar that is not NaN,
only the vector's element can be NaN and the hardware's `+` and `*` return its payload in either
operand order, so those loops carry no per-element NaN test.

### The native execution model

Package code is meant to run as machine code calling machine code, with tier 0 kept for `eval`,
non-standard evaluation and whatever compiled code declines. Four parts make that up, and they
are one design because each constrains the others: the frame is what compiled code reads, the
calling convention decides what a frame holds on entry, unboxed values decide when the frame is
written, and compiling ahead decides which of these facts are known before the first call.

| Part | Status | Owner |
| --- | --- | --- |
| Slot frames, environments made on demand and filled one variable at a time | built (`slot-frames.md`) | frames |
| A direct calling convention between closures | built from tier 0 to tier 0; machine to machine planned | frames (tier 0), JIT (machine code) |
| Unboxed length-1 doubles, integers and logicals in compiled code | built inside tier 1 and native functions; across calls planned | JIT |
| Whole-package compilation at install, with entry guards and deoptimization to tier 0 | measured and removed for untyped closures (`decisions/jit-ssa.md`, "No baseline tier, and code images hold bytecode only"); strict typed closures planned | JIT |

The targets are at least 80% of closures in rlang, cli and testthat running as machine code (5 to
11% today), 30% fewer instructions on the testthat workload, and the application workloads at twice GNU R's
speed. Vector kernels are a separate module behind a narrow interface that compiled code calls.

**Frame layout.** A call's frame is a window of the register file: a header register, one slot per
symbol the body can bind (formals first, in order, then locals numbered by the compiler's slot
table), then the body's own registers. The header holds the frame's environment once one exists
and `NULL` before. Each slot counts one reference and holds a value, a promise, the empty argument
for a missing formal, the unbound marker for an unassigned local, or for `...` the `DOTSXP` the
call collected. `Frame.missing` carries one missing bit per formal (up to 64 formals). Machine code
uses the same window: its spilled values live in the slots, so a frame looks the same whichever
tier is running it, and switching tiers moves no values.

**Calling convention.** A call site that calls closures carries a plan in its constants. The first
call of a body there marks the site, and the second builds the plan: for each formal of the
callee, the position of the argument that fills its slot, or -1 when the site supplies none.
Later calls of the same formals and body skip argument matching and write the arguments straight
into the callee's slots (`eval::call_with_plan`); a site that has seen eight different bodies stops
planning. A plan exists only when matching cannot depend on the values: the callee has no `...`
formal, the site passes no `...` or `..N`, and every formal the site leaves out has a literal
default. Everything else binds through the matcher (`bind_slots`, with its per-body match cache),
still into a slot frame. Arguments go in as values when they are constants, or variables passed
to an effect-free callee; otherwise as argument references, which name the caller's slot or the
argument's compiled code and come from a pool, so they allocate nothing and need no environment.
A reference becomes a promise object only when something keeps the argument past the call. A call
that passes `...` on appends the arguments the caller's `...` slot collected.

Between machine code (planned), a call of a sibling closure in a locked namespace is a direct
machine call to the callee's entry for the argument types at hand, guarded once per call. Pure arguments (`native::pure_value`) are passed evaluated and unboxed; the rest are
passed as promises over the caller's frame, exactly as tier 0 passes them.

**What makes the environment.** A slot frame has no environment object until something names the
frame: a promise or a closure made in it, `parent.frame()`, `sys.function`, S3 and S4 dispatch, a
builtin that receives the calling environment, `PRENV`, `R_GetCurrentEnv` or the `rho` of
`.External2`. `eval::frame_env`, `eval::frame_sys_parent` and `Call::env` are the only ways to get
one, and what they hand out binds nothing. A variable moves from its slot into a binding cell when
a lookup through the environment asks for that name, and the frame's own code reads by name from
then on. Every variable moves only when something lists the bindings or the environment outlives
the call. `missing`, `nargs`, `sys.call`, `substitute(name)`, `on.exit`, `return` and forwarding
`...` read the frame record or the slots and make nothing. `slot-frames.md` has the states, the
triggers and the invariants.

**What stays on heap frames.** A body runs in a heap frame from the start when the compiler
refuses it a slot table, which it does when the body may bind a name its own text does not show
or hands its frame to code that may: a bare `environment()`, `sys.frames()`, `attach` or `source`,
an `eval`, `evalq`, `assign`, `delayedAssign` or `rm` without an explicit environment, an
assignment to a string target, or a read of an S3 dispatch variable. A call also binds a heap
frame under the debugger, for a closure with a type signature, and when a missing formal's
default cannot be compiled with its own slot table. `slot-frames.md`, "The shape", is the full
list.

**Deoptimization and frame state.** Machine code that leaves for tier 0 continues on the same
window. Each exit carries a frame-state map: for every live slot and register, whether it is
already in the window or is a machine value of a known type, plus the tier-0 instruction to resume
at. Leaving boxes the machine values, writes them into their slots, restores the missing bits and
jumps into tier 0's loop; it makes no environment, because only a trigger does. A callee can make
the frame read its variables by name while machine code waits on the call, and then the header
register holds the environment, so machine code checks the header after every call that can do
that and leaves for tier 0 when it is set.

Tier-1 code runs in slot frames. It reads the header register on every
variable probe: while it is `NULL`, a variable the slot table numbers loads straight from its slot
at an index fixed when the code compiles, and a name the table does not number is looked up from
the closure's environment. Tier 1 keeps its own copies of the variables it loaded and writes a
changed one back through the frame (`Machine::assign`), into the slot or, once the frame reads by
name, into its binding, so it needs no exit when a callee switches the frame under it.

**Boxing.** A length-1 double, integer or logical without attributes stays in a machine register
while compiled code uses it, with R's `NA` and overflow rules. It is boxed when it escapes: written
to a slot before anything that can read the frame (a generic call, a dispatching operation, a
trigger, a deoptimization, a return to tier 0), passed to a callee that is not machine code,
stored into a vector or list, captured by a promise, or returned to a caller that expects a
`SEXP`. A machine-to-machine call passes and returns it unboxed, per the callee's specialization.

### Builtin fast paths

Row (a) of the roadmap goes builtin by builtin, starting from the top of the Amdahl ranking:
attribute access, `c`, `[[` and `[[<-`, then `[` and `[<-`, the apply family and `.Call`. Each
builtin gets one implementation in its end shape, in its own module, which the full call and the
fast entry both use, so there is no second copy of the semantics to drift.

- **Direct entries.** A builtin may register a `direct` function that takes its argument values
  in formal order and returns `None` to decline. Compiled code calls it when no argument is
  tagged or empty, before it builds an argument vector, runs the call checks or opens a handle
  scope. A replacement called from a complex assignment (`attr(x, "a") <- v`) uses it too, with
  the trailing `value` argument. The entry declines whatever the full call treats differently:
  an object that dispatches, ALTREP, a ry native value, and any argument the full call reports an
  error for.
- **Strings by identity.** Attribute names, class names and list names are interned `CHARSXP`s,
  and interned ASCII strings are equal exactly when they are the same object. A lookup compares
  pointers and reads bytes only when a string is not ASCII or a partial match is asked for.
- **No intermediate structures.** `c()` and `unlist()` follow GNU R's two passes: the first
  finds the result type, the length and whether any name exists, and the second writes elements
  and names straight into the result. When every argument is an atomic vector without
  attributes, no name can arise, so `c()` skips the naming walk entirely.

Instructions per call at tier 0, measured with callgrind net of the loop:

| Call | Before | After | GNU R 4.3 |
| --- | ---: | ---: | ---: |
| `attr(x, "a")` | 1006 | 590 | 1814 |
| `attr(x, "a") <- v` | 3174 | 992 | 2520 |
| `names(x) <- v` | 1668 | 1191 | 1520 |
| `inherits(x, "c")` | 1266 | 795 | 1469 |
| `c(a, 4.5)` | 1782 | 863 | 1877 |
| `c(a, a, a)` | 2315 | 1351 | 2050 |
| `c(list(1, 2), list(3))` | 3425 | 3032 | 2700 |
| `x[[i]]`, double vector | 1155 | 925 | 223 |
| `x[i] <- 1`, index `c(2L, 5L)` | 5273 | 2146 | 1580 |
| `.Call(r, x)`, a registered routine | 4133 | 2916 | 830 |

A second round took the call machinery itself. A direct entry receives the call as well as
the values, so `[`, `.Call` and `round`, whose errors name the call, skip the argument list, the
dispatch probe and the handle scope. Appending a name grows an unshared vector in place, a matrix
column assignment copies contiguous runs, and `Reduce(accumulate = TRUE)` runs natively.
Instructions per loop iteration with the JIT on, measured with callgrind:

| Call | Before | After | GNU R 4.3 |
| --- | ---: | ---: | ---: |
| `x[-1L]`, five doubles | 3179 | 2485 | 2372 |
| `x[m]`, logical `m` | 1467 | 1132 | 1948 |
| `l[c("a", "c")]`, a list | 2295 | 1959 | 3775 |
| `round(x, 2)`, a scalar | 1785 | 1129 | 2526 |
| `round(x)`, per element of a double vector | 63 | 29 | 76 |
| `x <- list(a = 1); x$b <- 2` | 7739 | 4292 | 4387 |
| `x <- list(a = 1); x[["b"]] <- 2` | 7937 | 4289 | 6112 |
| `m[, j] <- v`, per element | 35 | 8 | 20 |
| `.Call(f, 1)` with a registered routine | 2229 | 2021 | 964 |
| `Reduce(f, 1:20, accumulate = TRUE)`, per call | 208.4k | 93.4k | 190.9k |
| `c(a = 1, b = k)` | 4282 | 3698 | 4149 |

On whole programs (callgrind, JIT on), instruction counts fall by 7.9% on records, 7.9% on
simulation, 5.4% on tables, 2.5% on functional and 0.2% on testthat, and change by less than
0.5% on the rest. Peak memory falls by 14 MB on functional and 4 MB on objects and is level
elsewhere.

- **Assignment in place.** Compiled `x[i] <- v` on an unshared atomic vector without
  attributes writes the selected elements directly, recycling `v` as GNU R does. It declines to
  the full `[<-` whenever the result would change shape or a warning is due: NA or zero
  positions, growth, a coercion that widens `x`, or a length that does not divide.
- **`vapply` results.** One module checks each result against `FUN.VALUE` and copies it into
  the preallocated answer, widening integer and logical values inline, then sets names, dims and
  dimnames once. Every loop that calls `FUN` per element uses it, so the checks and their error
  text exist once.
- **`.Call` by address.** A routine is native code exactly when its `NativeSymbolInfo`'s
  `address` pointer has no tag and a non-null address, so the call reads two slots by position
  and passes its arguments from the stack, with no name search or allocation before native code
  runs. A `PACKAGE` argument or an arity mismatch goes to the general path, which reports the
  errors.

A third round kept element assignments in slot frames: a `for` variable the body never reads
gets a slot, `ForStep` and `SubAssign` find their slot through a constant-to-slot map built with
the code, a parenthesized subscript counts as side-effect free, and `x[i] <- list(v)` writes a
list in place. Negative subscripts and builtin argument matching stopped allocating. Instructions
per loop iteration, loop included (an empty loop costs 98 in GNU R, 249 at tier 0 and 44 under
the JIT):

| Loop body | Tier 0 before | Tier 0 after | JIT before | JIT after | GNU R 4.3 |
| --- | ---: | ---: | ---: | ---: | ---: |
| `s <- x[[i]]` | 1456 | 1196 | 70 | 66 | 617 |
| `x[[i]] <- 5` | 1032 | 939 | 77 | 76 | 571 |
| `x[i] <- 5` | 1030 | 943 | 72 | 71 | 571 |
| `x[[(k %% 8L) + 1L]] <- 1` | 8660 | 1741 | 9450 | 118 | 1585 |
| `x[(k %% 8L) + 1L] <- 1` | 8351 | 1749 | 9141 | 118 | 1585 |
| `x[i] <- list(5)` | 5928 | 2229 | 6307 | 2446 | 2183 |
| `s <- x[["b"]]`, a list | 1019 | 821 | 670 | 668 | 1489 |
| `s <- x[[i, 2L]]`, a matrix | 1545 | 1292 | 968 | 144 | 723 |
| `x$b <- k` | 1316 | 1219 | 1203 | 1081 | 989 |
| `s <- x[-1L]`, five doubles | 2455 | 2149 | | 2174 | 2372 |

Under the JIT the scalar element ops run at a fifth of GNU R or less. At tier 0 what is left is
dispatch around the builtin rather than the builtin: for `x[[i]]`, the function lookup, the
primitive and object branches, the call and the jump cost about 300 instructions around a
130-instruction read, and an assignment's two guards cost about 100. The computed-subscript read
`x[[(k %% 8L) + 1L]]` still leaves the JIT for tier 0, and `x[i] <- list(5)` costs more under the
JIT than at tier 0.

A fourth round gave tier 0 fast handlers for those ops (beside `GetFun`'s, which reads a
binding cell from the lookup cache): the primitive and object branches, `CallBuiltin` on `[[`
and `[` through `element_access::element_position`, and `SubAssign` in place, by position or by
an existing ASCII name. Each declines to the general handler with no side effect, so the op
stream the JIT reads does not change. Instructions per loop iteration at tier 0, measured with
callgrind against GNU R 4.6.2 (an empty loop costs 180 at tier 0 and 99 in GNU R):

| Loop body | Before | After | JIT | GNU R 4.6 |
| --- | ---: | ---: | ---: | ---: |
| `s <- x[[i]]` | 846 | 599 | 70 | 553 |
| `s <- x[2L]` | 886 | 587 | 56 | 492 |
| `x[[i]] <- 5` | 726 | 467 | 76 | 519 |
| `x[i] <- 5` | 727 | 470 | 72 | 519 |
| `x[[i]] <- 5`, a list | 708 | 486 | 268 | 687 |
| `x[i] <- list(5)` | 1917 | 1050 | 2428 | 1941 |
| `x$b <- k` | 1006 | 678 | 1080 | 878 |
| `s <- x[["b"]]`, a list | 556 | 546 | 657 | 1293 |
| `s <- x[-1L]`, declined | 1761 | 1853 | 1982 | 2113 |
| `x[["b"]] <- 2`, a name append, declined | 3565 | 3672 | 4031 | 5243 |

Net of the loop, every read and store the handlers take is below GNU R except `x[2L]`, 4%
above. A shape they decline pays for the attempt, about 5% on a negative subscript. The JIT
column shows where compiled code is slower than tier 0: its fallback for a list's `[<-`, `$<-`,
`$` and a name read calls the general path.

### How the static types feed the JIT

ry's types are not sound in plain R, because R code can redefine anything at any time. So the JIT
treats them in two ways, depending on whether a guarantee exists:

- **Default mode: types are profiles that arrive early.** A function annotated
  `fn(values: double[], scale: double) -> double[]` starts with that type profile before its first
  call, so tier 1 compiles it at its first call instead of after warmup. The guards stay. The
  runtime reads the signature wherever it is written: inline, on the assigned name, or in the
  `#:` block above.
- **Strict mode: types are guarantees where a check backs them.** Strict mode does not report every
  imprecision (it never reports `Any`, nor an `Unknown` nested inside a type, and the stubs use `Any`
  on purpose), so a strict package can still receive an imprecise value from typed code. ry
  therefore inserts a check wherever an `Any` or `Unknown` value flows into a precise type, at an
  untyped caller and inside typed code alike, and keeps guards on facts that come only from
  hand-written stubs, because a wrong stub must never mean memory-unsafe compiled code. An atomic
  type costs a type-code, length and attribute check; a record or list type costs a walk of the
  value; a function type cannot be checked at the boundary at all and needs a wrapper that checks
  each call. Between checks, the body is compiled without guards on the checked facts.

The ideas above that come from Roc, Bend and goose, and the ones from those languages and from Vx
that ry rejects, are argued in [prior art from new language implementations](/development/design/prior-art.md).
The JIT never reads the checker's internal data structures. It consumes the per-function summaries
of section 8, which the analysis computes and which are stored with the bytecode.

## 6. Lazy package loading

### How the existing tools work

`devtools::load_all` (implemented by `pkgload`) builds a fresh namespace environment, processes
`NAMESPACE` imports, sources every file in `R/` in `Collate` order, runs `.onLoad`, registers S3
methods and exports, compiles `src/` if needed, and attaches the result. It does all of it on every
call.

`loadfast` keeps the same steps for the first load and makes later loads incremental: it hashes the
`R/` files with MD5 and re-sources only those that changed, rebuilds S3 method tables, and tracks
which loaded packages import from which, so reloading a dependency upgrades its importers' next load
to a full reload. Its documentation is candid about the limits: the README explains that it does not
track which symbols came from which file, so deleted files and removed functions leave stale objects
until a full reload, and `TECHNICAL_DEBT.md` records that it does not re-read `NAMESPACE`, so new
exports or imports also need one. Compiled code is rebuilt into a new temporary
library and loaded beside the old one.

Both tools are eager: every top-level expression in every file runs before the first function is
called. GNU R's *installed* packages are already lazy, because `R CMD INSTALL` serializes each
object into a lazy-load database and the namespace holds promises that fetch an object on first use.
The cost there is the install step, which is exactly what the development loop wants to avoid.

### ry's design

The loader is built, ahead of the runtime, on the GNU R backend that `ry R` embeds
([loading packages](/reference/package-loading.md) is the user page). It splits into three parts, and only the
last one knows which runtime runs the code:

- **The item index** (`semantics::load_index`) is derived from the analysis: per item a content
  hash, whether it is a function definition, the S4, R6 and S3 registrations it makes, and the names
  it reads while it runs; per file the text R reads and each item's position; per package which
  names are lazy. It is incremental like the rest of the analysis
  ([architecture](/development/architecture.md#the-package-load-index)).
- **The plan** (`crates/loader`) is the diff between the index a session has loaded and the current
  one: what to bind lazily, which statements to run in which order, which bindings to remove, which
  registrations to undo or make, and whether imports, exports, data, compiled code and hooks need
  work. It says nothing about how.
- **A backend** applies the plan. The GNU R backend sends it to R as an RDS file, and R code
  installed in the session (`runtime.R`) applies it. ry's runtime will apply the same plan natively,
  so neither the index nor the diff changes when it arrives.

The rules the implementation settled:

- **A function definition is lazy when its name has exactly one top-level writer.** The namespace
  holds a promise that parses and evaluates only that definition on first access. On GNU R the
  promises are made in C by the `makeLazy` internal that installed packages use, so binding 24,500
  definitions takes about 30 ms. Any second writer, conditional or replacing (`f <- memoise(f)`),
  makes every writer of the name eager, in order.
- **Every other top-level expression runs eagerly in `Collate` order**, then the files `Collate`
  leaves out in C-locale order, as `load_all` does. The code files include `R/unix/` (or
  `R/windows/`), and `Collate.unix` overrides `Collate`, as in R CMD INSTALL. Making a provably
  pure constructor call lazy is not implemented.
- **Imports are copies, and a reload rebuilds them when `NAMESPACE` imports change.** Updating the
  copies other development packages hold is done after every load: each loaded development package
  whose `NAMESPACE` imports from the reloaded one runs its import directives again
  (`.ry_update_importers` in `runtime.R`), which costs one pass over those directives.
- **A reload is a diff over items.** A changed or new function is rebound and a deleted one removed.
  Statements in a changed file are matched to the file's old statements by content, in order, so an
  inserted statement runs alone while two swapped writers of a name rerun. A statement reruns when it
  is new, when it read a binding that changed while it ran (it holds the old value), or when it
  writes a name that changed (the last writer must win again). A rerun statement that reads a name
  it or a later statement rewrites first reruns that name's earlier writers, so `f <- memoise(f)`
  sees `f` as at load time. A reorder of files by `Collate` falls back to a full load. The property
  test in `crates/loader/tests/test_reload_fuzz.rs` checks all of this against a fresh load.
- **Compiled code** is built by pkgbuild into `src/` and loaded, and a rebuild unloads the previous
  library first, as `load_all` does. Loading a rebuild under a new name, so objects that point into
  the old library stay valid, is not implemented.
- **Installed packages** keep GNU R's installed layout, so the same directory serves GNU R and ry.
  ry reads their lazy-load databases and `.rds` files, and builds the object index and bytecode on
  first load into a cache of its own, never into the package
  ([packages and R versions](/development/design/packaging.md)). This part waits for the runtime.

Hooks run where R runs them: `.onLoad` after the eager expressions and S3 registration, `.onAttach`
on attach. A reload runs `.onLoad` again only when the `.onLoad` definition changed, because it
usually sets options or registers things once. `ry load` and the `ry R` console are the entry points, and
`load_all()`, attached in `tools:ry`, serves both ry's console and plain R sessions; ry does not
intercept `devtools::load_all()`.

## 7. The table type

### What has to be beaten

data.table is fast for specific, well-known reasons: a parallel radix sort (`forder`) that also
drives grouping and joins, "GForce", which replaces common aggregations inside `[` (`sum`, `mean`,
`min`, `max`, `.N`, ...) with specialized grouped C loops, keyed and indexed binary-search joins,
in-place update by reference with `:=` (columns are over-allocated so that adding one does not copy
the table), and a multithreaded `fread`. Its weak spots are equally clear: anything outside GForce
evaluates R code once per group, all of it is single-threaded at the R level, and its query is not
optimized as a whole.

### Recommendation: Polars, linked as a Rust crate

Polars is a Rust dataframe engine on Arrow's columnar memory, with multithreaded hash group-by and
join kernels, a lazy query planner (predicate and projection pushdown, common-subexpression
elimination) and a streaming engine. Because ry is Rust, it can link `polars-core` and `polars-lazy`
directly, with no FFI layer between the runtime and the engine. The R package `polars` in the
benchmark closure already does this through savvy, which proves the engine works for R users; ry's
table type removes the binding layer and teaches the type checker about it.

The alternatives are weaker for this purpose. DuckDB is excellent, and it already scans R data
frames and Arrow data without copying (duckdb-r returns ALTREP-backed results), but it is a C++
engine with a SQL-shaped planner, so ry would embed it through a C API rather than link a Rust
library whose plan it can build directly. Arrow's own compute
kernels lack a query planner. A custom engine would spend years re-deriving what Polars has.

### The design

The engine is `crates/table` and its query IR; `crates/frames/src/frame.rs` makes frames
interpreter values and lowers queries into the IR, and `crates/libr/src/frame_altrep.rs` exposes
columns as ALTREP vectors to native code. The user guide is [DataFrames](/reference/dataframes.md).

- **The type is `DataFrame`, an external pointer that owns a Polars `DataFrame`.** The runtime
  class is `"DataFrame"` alone (a DataFrame is no `data.frame`; `as.data.frame()` and
  `as.DataFrame()` convert), and the checker types it as
  `DataFrame{id: integer[], price: double[], ticker: character[]}` (the "DataFrames" section of the
  typing reference). `LazyFrame` holds a plan instead of a table, and `GroupBy` a DataFrame or plan
  plus its keys.
- **The primary API is Polars' verbs over expressions** (`DataFrame.select`, `with_columns`,
  `filter`, `group_by` + `GroupBy.agg`, `sort`, `join`, `head`, with `Expr.col("x")` expressions), all
  qualified names in `package:ry`. Every verb builds a step of `table::lazy::Plan`, and an eager
  verb collects at once. The planner pushes filters below `with_columns` and projections, and pushes
  filters, needed columns and row limits into a file scan. The bracket syntax below stays as
  data.table compatibility and lowers to the same IR.
- **A column reaches R code as a copied R vector, and native code as an ALTREP vector over the
  Arrow buffer.** The interpreter copies a column when R code reads it (`$`, `as.list`, a data
  mask), which is cheap next to the query. The ALTREP path in `libr` is built but no interpreter
  path hands it out yet. Element and region reads
  go to the buffer, and so does `DATAPTR_OR_NULL` or a read-only data pointer for an integer or
  double column without nulls, because those bytes are identical in both layouts. A writable pointer
  (`INTEGER`, `REAL`, `DATAPTR`), a column with nulls and a logical column (bit-packed in Arrow,
  32-bit in R) materialize R's layout once into the ALTREP object's `data2`. A write through that
  pointer changes the R vector and never the frame, which is R's value semantics. Character columns
  intern their `CHARSXP`s on first access, and factors are copied, because R's one-based `int` codes
  differ from the enum's codes. A column R never materialized comes back into a frame as the same
  Arrow buffer.
- **Residency is per column:** a column lives in the Arrow buffer until R code or native code needs
  R's layout. Vx tracks where data lives in the type and makes every transfer explicit
  ([prior art](/development/design/prior-art.md#vx)); ry keeps the transfer implicit, and plans a lint
  for typed code that forces a column to materialize inside a loop.
- **NA maps onto Arrow validity, and NaN stays a value.** Integer NA (`INT_MIN`) and double NA (the
  `NaN` with low word 1954) are rewritten into validity at the boundary. A vector coming in from R
  is copied into a new Arrow buffer; only a column R never materialized comes back zero-copy.
- **Queries go through a small IR to a Polars lazy plan.** The evaluator and the bytecode hand
  `tbl[...]` on a DataFrame to the lowering before `i`, `j` and `by` are evaluated, so
  `tbl[price > 0, .(total = sum(price)), by = ticker]` becomes a `Query` (rows, `j`, `by`, `keyby`), which lowers to one lazy frame, so the
  planner sees the whole query and every grouping expression runs as a Polars kernel. The IR covers
  filters, ordering, positions, projections, grouped aggregation over data.table's GForce set (`sum`,
  `mean`, `min`, `max`, `.N`, `first`, `last`, `median`, `sd`, `var`, plus `head` and `cor`), equi,
  keyed, rolling and non-equi joins, `by = .EACHI`, `mult =`, and `:=`. Lowering adds R's
  semantics where Polars differs: integer overflow becomes NA, aggregates propagate NA unless `na.rm`, `%/%` and `%%` follow R's signs, and
  joins follow data.table's row and column layout. A query returns the warnings data.table would
  raise (an overflowing grouped integer sum, a lossy `:=`) as data, and the interpreter raises them as R warnings. Anything
  the IR does not cover, such as an R function inside an aggregation, runs as R code once per group
  in a data mask that binds the columns it mentions; a lint saying so is planned.
- **`:=` is copy-on-write with reference counts,** not over-allocation. A frame whose reference count
  is one is updated in place, so `tbl[, x := y * 2]` costs one new column, and a shared frame first
  copies only its column list, because the Arrow buffers themselves are immutable and shared. In the
  checker, `:=` rebinds the frame to its extended type. data.table's `:=` on a `data.table` object
  keeps data.table's own by-reference semantics, because that package runs unchanged.
- **Interop is zero-copy through the Arrow C data interface,** for a single column and for a whole
  frame as a struct array, which is how the R `polars` and `arrow` packages, duckdb and nanoarrow
  exchange data.

The claim that the frame outperforms data.table rests on a benchmark of its own
(`tools/bench/internal/table/`): the db-benchmark group-by and join questions (the suite H2O started and
DuckDB Labs maintains), `:=` update loops and a keyed rolling join, run on the same machine against
data.table with all threads. `just bench-table <dir> --rows 1e7` regenerates a table below (it
generates the data on first use), and `--groupby-only` limits a run to the group-by questions.

At db-benchmark's 0.5 GB size (1e7 rows, 4 threads), DataFrames from R code under
`ry run` beat data.table under GNU R on every question, and all three runs give the same
checksums. The loop that updates 1% of the rows writes only the matching rows, in place, in both
engines: data.table builds an index on `id4` during the first pass, and a DataFrame builds a row
index of `id4` on the second `id4 == step` filter and keeps it until `id4` changes. Each cell is
the faster of two runs, in seconds, and the last row is each engine's peak resident memory over
the whole run, which is the loop that adds 100 columns. The last column is the same engine
driven from Rust, without R.

| Question | data.table | ry, from R | ry, from Rust |
|---|---|---|---|
| groupby q1: `sum(v1)` by `id1` | 0.148 | 0.018 | 0.026 |
| groupby q2: `sum(v1)` by `id1, id2` | 0.148 | 0.020 | 0.026 |
| groupby q3: `sum(v1)`, `mean(v3)` by `id3` | 0.293 | 0.084 | 0.097 |
| groupby q4: three means by `id4` | 0.222 | 0.103 | 0.105 |
| groupby q5: three sums by `id6` | 0.301 | 0.107 | 0.102 |
| groupby q6: `median(v3)`, `sd(v3)` by `id4, id5` | 0.915 | 0.097 | 0.121 |
| groupby q7: `max(v1) - min(v2)` by `id3` | 0.603 | 0.040 | 0.038 |
| groupby q8: the two largest `v3` by `id6` | 1.679 | 0.139 | 0.133 |
| groupby q9: `cor(v1, v2)^2` by `id2, id4` | 0.632 | 0.060 | 0.060 |
| groupby q10: `sum(v3)`, count by all six ids | 1.675 | 0.656 | 0.640 |
| `:=` on a whole column, 100 times | 4.858 | 0.430 | 0.555 |
| `:=` on 1% of rows, 100 times | 0.356 | 0.111 | 0.105 |
| `:=` adding a column, 100 times | 4.920 | 0.965 | 0.755 |
| join q1: small, on `id1` | 0.363 | 0.096 | 0.114 |
| join q2: medium, on `id2` | 0.498 | 0.088 | 0.103 |
| join q3: medium, left, on `id2` | 0.720 | 0.123 | 0.132 |
| join q4: medium, on factor `id5` | 0.543 | 0.093 | 0.099 |
| join q5: big, on `id3` | 2.978 | 0.339 | 0.391 |
| keyed rolling join | 0.120 | 0.055 | 0.053 |
| total | 21.97 | 3.62 | 3.66 |
| peak memory (GB) | 7.7 | 4.5 | 4.8 |

At db-benchmark's 5 GB size (1e8 rows) the table holds the ten group-by questions alone,
because the `:=` loop that adds 100 columns needs more than this machine's 15 GB. The peak is
q10, whose answer has nearly one group per row. The R script's checksum sums an answer's numeric
columns in the engine (`DataFrame.select` of one `Expr.sum` per column), because reading a
1e8-row column back as an R vector would copy it.

| Question | data.table | ry, from R | ry, from Rust |
|---|---|---|---|
| groupby q1: `sum(v1)` by `id1` | 1.399 | 0.179 | 0.164 |
| groupby q2: `sum(v1)` by `id1, id2` | 1.674 | 0.199 | 0.212 |
| groupby q3: `sum(v1)`, `mean(v3)` by `id3` | 1.954 | 1.238 | 1.197 |
| groupby q4: three means by `id4` | 1.831 | 1.034 | 0.971 |
| groupby q5: three sums by `id6` | 2.129 | 1.309 | 1.242 |
| groupby q6: `median(v3)`, `sd(v3)` by `id4, id5` | 9.314 | 1.130 | 1.123 |
| groupby q7: `max(v1) - min(v2)` by `id3` | 6.729 | 0.813 | 0.677 |
| groupby q8: the two largest `v3` by `id6` | 17.289 | 2.510 | 2.185 |
| groupby q9: `cor(v1, v2)^2` by `id2, id4` | 3.155 | 0.582 | 0.521 |
| groupby q10: `sum(v3)`, count by all six ids | 17.497 | 8.289 | 8.588 |
| total | 62.97 | 17.28 | 16.88 |
| peak memory (GB) | 12.5 | 8.5 | 8.5 |

The two `:=` loops that write existing columns fit at this size as well
(`just bench-table <dir> --rows 1e8 --updates-only`). The subset loop writes one million rows
per pass.

| Question | data.table | ry, from R | ry, from Rust |
|---|---|---|---|
| `:=` on a whole column, 100 times | 37.738 | 6.616 | 6.431 |
| `:=` on 1% of rows, 100 times | 3.079 | 0.987 | 1.040 |
| total | 40.82 | 7.60 | 7.47 |
| peak memory (GB) | 10.8 | 6.6 | 6.6 |

The join questions are measured separately at db-benchmark's 5 GB size
(`just bench-table <dir> --rows 1e8 --joins-only`), because their inputs are twice the group-by
file: `join_x` and `join_big` are 5.1 GB of CSV each, and `join_x` has 63.2 million distinct `id6`
strings. ry answers all five joins at a peak of 11.6 GB from R and 12.0 GB from Rust. data.table
runs out of memory before its first answer: the kernel stops it at 14.3 GB resident.

| Question | data.table | ry, from R | ry, from Rust |
|---|---|---|---|
| join q1: small, on `id1` | out of memory | 1.090 | 0.994 |
| join q2: medium, on `id2` | out of memory | 1.177 | 1.315 |
| join q3: medium, left, on `id2` | out of memory | 1.449 | 1.457 |
| join q4: medium, on factor `id5` | out of memory | 1.191 | 1.197 |
| join q5: big, on `id3` | out of memory | 5.863 | 6.165 |
| total | out of memory | 10.77 | 11.13 |
| peak memory (GB) | over 14.3 | 11.6 | 12.0 |

Three choices keep the joins inside the machine:

- **A factor is a code column plus one level table**
  (`crates/table/src/factor.rs`). The table stores its labels sorted by bytes and front-coded in
  blocks of 16: each label records how many bytes it shares with the label before it, then the
  rest. Looking a label up is a binary search over the blocks' first labels and a scan of one
  block, so there is no hash index. In `tests/test_memory.rs`, a table shaped like `join_x` holds
  32 bytes per row, its seven columns' values and level tables together.
- **A join buckets one side's rows by a dense code of the key**, coded over that side's value
  range alone (`crates/table/src/join.rs`). The bucketed side is the right table of
  `DataFrame.join`, unless the left table has at most 65,536 rows and no more than the right. The
  bucket index is two flat arrays, the probe counts its matches before it writes them, and the
  answer's columns are gathered one side at a time.
- **A block of a megabyte or more has a mapping of its own**, which returns to the kernel when
  the block is freed (`heap::large::Mapped`), so the reader's and a join's scratch memory does
  not stay resident beside the next answer. While a table operation runs, a mapping of 2 MiB or
  more asks for huge pages, because a query maps its buffers afresh and would otherwise take a
  page fault per 4 KiB. Outside a table operation a block gets small pages, so a session that
  uses no table commits only the memory it touches.

`tests/test_memory.rs` in `crates/table` pins the bytes per row that the reader, each join
question and the grouped sums allocate at their peak and hold afterwards, on four threads and
with a margin of 1 to 4 bytes per row. A buffer that scales with the rows, outlives its use and
is larger than that margin fails the test. The test counts allocated bytes, not resident memory,
and does not check the answers, which `tests/test_table.rs` does.

The R script uses the Polars-style verbs for every question except the `:=` loops, which measure
in-place update and so keep data.table's syntax. The Rust driver runs the same lazy plans on the
same allocator as libR (mimalloc for small blocks, a mapping of its own for each large one), so it
measures the engine without the R calls around it.

`tools/bench/internal/table/ops.R` times data.table's helpers on the db-benchmark group-by file (10 million
rows, 4 threads), and the `ops_benchmark` bench in `crates/table` times the engine's kernels for the
same operations from Rust. All three columns give the same checksums. R calls to these names run
data.table's own C under ry's runtime, which is the middle column; calls from R do not reach the
engine's kernels.

| Operation | data.table on GNU R | data.table on ry's runtime | ry engine, from Rust |
|---|---|---|---|
| `fread` | 3.16 | 2.36 | 1.39 |
| `fwrite` | 0.84 | 0.60 | 0.70 |
| `setkey` | 0.43 | 0.42 | 0.46 |
| `setorder` | 0.90 | 0.83 | 0.69 |
| `unique` | 0.083 | 0.085 | 0.09 |
| `uniqueN` | 0.12 | 0.12 | 0.10 |
| `rbindlist` | 0.90 | 0.71 | 0.29 |
| `melt` | 1.21 | 0.94 | 0.39 |
| `dcast` | 0.21 | 0.14 | 0.26 |
| `shift` | 0.024 | 0.006 | 0.004 |
| `fifelse` | 0.092 | 0.044 | 0.050 |
| `fcoalesce` | 0.063 | 0.028 | 0.047 |
| `nafill` | 0.085 | 0.051 | 0.042 |
| `rleid` | 0.026 | 0.011 | 0.011 |
| `between` | 0.022 | 0.013 | 0.013 |
| `%chin%` | 0.078 | 0.067 | 0.036 |
| `tstrsplit` | 5.73 | 3.71 | 1.86 |

Each cell is the faster of two runs. Under ry's runtime `unique` is at parity (its median over the
two runs is 0.086 s against 0.10 s) and every other helper is faster than on GNU R. The 5 GB size
(1e8 rows) needs more than the 15 GB of memory the measuring machine has, because `rbindlist(list(x,
x))` alone holds 15 GB of columns.

### Real code: the benchmark modules

The three benchmark code bases each have a module built on data.table (`tables` in data science,
`market_data` in finance, `trials` in biostatistics). Their templates carry a DataFrame variant
next to the data.table code, and the typed program uses it, so the typed module is ordinary ry
code that checks clean in strict mode. `just bench-frames` generates both variants from one seed,
strict-checks the typed one, runs each module's functions end to end on the same inputs (the
driver is `tools/bench/internal/table/frames_driver.R`), and refuses the result if any step's checksum differs.
Each cell is a step's faster run in seconds; memory is each engine's peak resident size.

10,000,000 rows:

| Step | data.table on GNU R | data.table on ry | DataFrame on ry, typed |
|---|---:|---:|---:|
| `tables`: `make_events` | 1.714 | 1.245 | 1.601 |
| `tables`: `summarise_groups` | 0.547 | 0.425 | 0.433 |
| `tables`: `add_features` | 3.734 | 3.643 | 1.727 |
| `tables`: `join_labels` | 1.301 | 1.586 | 0.255 |
| `tables`: `reshape_wide` | 0.318 | 0.358 | 0.429 |
| `market_data`: `fetch_prices` | 1.193 | 0.724 | 1.249 |
| `market_data`: `latest_prices` | 1.129 | 0.818 | 0.393 |
| `market_data`: `to_wide` | 2.590 | 2.589 | 0.884 |
| `market_data`: `read_reference` | 0.653 | 0.678 | 0.590 |
| `trials`: `enrol` | 1.023 | 0.514 | 0.647 |
| `trials`: `visit_schedule` | 4.274 | 3.370 | 1.488 |
| `trials`: `visits_per_month` | 1.898 | 1.797 | 1.929 |
| total | 20.37 | 17.75 | 11.62 |
| peak memory (GB) | 1.53 | 2.29 | 2.24 |

The typed program wins where the engine does the work (windows, joins, pivots, grouped
aggregation) and loses a little where a step mostly builds R vectors and hands them over. Building
a DataFrame copies each column into the engine, where `data.table()` keeps R's vectors, which is
most of the gap in `make_events`, `fetch_prices` and `enrol`; `visits_per_month` spends its time in
`lubridate::floor_date` on both sides.

## 8. Typing integration

### The inline syntax

Three drafts and decisions bear on this, and the mandate settles what they left open.
`decisions/syntax-semantics.md` ("An annotation is one concept with pluggable spellings") makes the surface spelling
pluggable at lowering, names a valid-R inline form through R 4.4's `declare()` primitive as the route
that keeps every file ordinary R, and leaves a superset dialect as a product decision.
`development/design/inline-type-syntax.md` costed that superset as a dialect compiled to plain R, in
its own `.ry` files, and recommended against building it for inline types alone. The mandate now
requires an inline syntax that is on by default and that ry warns about when it is turned off. A
`declare()` form is valid R, so it would need no switch and no warning, which means the mandate asks
for the superset. A runtime also changes the draft's cost argument: ry executes the syntax directly,
so there is no compile step and no generated R to keep in sync.

The recommendation is therefore the superset, using the four positions the draft chose:

```
scale_by <- function<T: numeric>(values: T, scale: T) -> T {
  values * scale
}
count: integer <- 0L
```

The parameter, return and binder positions are syntax errors in GNU R (checked with R 4.3.3:
`unexpected '<'`, `unexpected ':'` and `unexpected '->'`), so no valid R program changes meaning. The
binding position is the one subtle case. R parses `count: integer <- 0L` as an assignment to
`count:integer`, and running it fails, with `object 'count' not found` when `count` does not exist
yet and `could not find function ":<-"` when it does. So the only R programs it could change are ones
that already fail. The rest follows from the mandate:

- **The syntax is on by default** in ry's parser and runtime, and ry warns when a project turns it off
  in `ry.toml`.
- **`declare(type(...))` stays a recognized spelling** of the same annotation, for code that must
  remain valid R, as the pluggable design intends.
- **A typed file keeps the `.R` extension,** which reverses the draft's `.ry` files: in a runtime
  that executes the syntax, a second extension buys nothing. The cost is real, though. Every other R
  tool (`R CMD check`, roxygen2, lintr, styler) fails on a typed file under `R/`. Code that must also
  run on GNU R, such as a package submitted to CRAN, therefore needs a strip step: a `ry build`
  command would write plain R with the inline types moved into `#:` comments.
- **Comment and inline annotations must agree.** When both annotate the same item, ry compares them
  as types, after alias expansion, and reports a warning on the inline annotation when they differ.
- **Strict mode rejects untyped code.** The settled rule is in the typing reference
  ([untyped parameters](/reference/type-system.md#untyped-parameters)): a parameter nothing constrains
  is reported, while an undetermined return or binding is reported once, at the origin it traces to.

This settles the question `decisions/syntax-semantics.md` left open, and the decision is recorded there ("The inline
annotation syntax is a superset of R").

### One type model

The checker's types (`TyKind` in `crates/semantics/src/types.rs`) are interned in the salsa database
and reference inference variables and arena names, which the runtime should not depend on. So the
runtime receives two small, owned, serializable values per function, computed by tracked queries:

- **The runtime type summary** comes from the checker's exported scheme. It keeps what the runtime
  can use (atomic type, scalar or vector shape, names, record fields, function arity, nominal types)
  and collapses what it cannot check cheaply (type parameters, deep unions) to "unknown". It changes
  only when the function's interface changes.
- **The runtime body facts** come from the function's body, not its scheme: whether it reflects on
  its frame, which parameters it always forces, which it only reads, and whether it is free of
  effects. They change on any body edit, so they live in their own query, and only the function's
  own compiled code depends on them. The JIT's callers read a callee's facts through a watchpoint,
  so an edit deoptimizes the callers that relied on the old facts instead of widening the interface,
  which keeps the interface firewall that makes incremental analysis cheap.

Both are written with a package's bytecode when it is installed (see "Where bytecode comes from"),
so no process needs a cache keyed by content, and salsa's ids, stable only inside one database,
never leave the analysis. This keeps a single source of truth (the
checker's types and the syntax tree) and makes the runtime's copies derived, recomputable
projections. The same summary drives strict mode's boundary checks, the JIT's initial
profiles, and the table type's column checks.

## 9. The benchmark code bases

The three code bases (finance, data science, biostatistics, about 300,000 lines in about 500 files
each, all using the dependency set in `AGENTS.md`) do not exist yet. They should be generated, and
built to exercise what real code exercises rather than to be easy to run:

- **Generator.** A ry tool (`tools/benchmark-gen/`) emits each code base as an R package with a
  `DESCRIPTION` that has exactly the benchmark `Imports`, `R/` files of 400 to 800 lines, and
  `tests/testthat/`. A seeded generator composes modules from domain templates (pricing, risk,
  yield curves and GARCH models for finance; data cleaning, feature pipelines, model fitting and
  reporting for data science; survival, trial simulation and mixed models for biostatistics), so a
  code base can be regenerated at any size.
- **Realism.** Each template uses the dependencies the way real code does: data.table with `:=` and
  `by`, R6 classes, S4 generics, `purrr` maps, `foreach` with `doParallel`, `httr2` and Azure clients
  behind mocks, `testthat` suites, `lgr` logging, and `rlang` tidy evaluation. A fraction of each code
  base carries `#:` annotations, and a fraction carries inline ones, so the analysis has typed and
  untyped code to check. GNU R runs the inline-typed files only after the strip step of section 8.
- **Hermetic runs.** Network-dependent packages (Azure, Bloomberg via `Rblpapi`, ODBC) run against
  local mocks or fakes, so a benchmark run is deterministic.
- **Three measurements:** run the test suite under GNU R (on the stripped sources) and under ry (wall
  time, and outputs must match), check the code base with `ry check` (cold and incremental keystroke latency), and load it
  with `ry load` (cold and incremental reload).

## 10. Build order

Each step ends with something real running, and each one is a large, whole change.

1. **Corpus and oracle first.** Fetch the benchmark closure (the scripts in `tools/research/`
   already resolve it) together with the `Suggests` its packages' tests need, install it into a GNU R
   library, and build a differential harness that runs
   an R file under GNU R and under ry and compares output, errors and warnings. Write the benchmark
   generator and generate small versions of the three code bases.
2. **The object model, GC and C API skeleton (done).** Objects, interned strings and symbols, the GC
   with `PROTECT`, and the `libR` shared library with the top 150 or so symbols, enough for a C
   package to load and run its `.Call` entry points from a Rust test harness. `libR` exports 149 of
   the 150 API names the closure uses most (the gap is `R_ParseVector`, which needs the parser) and
   195 of the top 200. brio from the closure and a purpose-written package run under it, built both
   against ry's headers and by GNU R's `R CMD SHLIB`.
3. **The interpreter and base R.** The tier-0 bytecode interpreter, closures, promises, environments,
   conditions, S3 dispatch, and base R's primitives and internals in Rust. Base R's R code (the
   `base`, `stats`, `utils`, `methods`, `tools` and `parallel` sources) is reused as R source, so only
   the internals behind `.Internal` and `.Primitive` are reimplemented. Run the base package's own
   tests through the oracle.

   The interpreter runs. Every oracle case in `crates/oracle/cases` matches GNU R 4.3.3
   (`oracle compare --engine ry`). Of GNU R 4.3.3's own `tests/*.R`, 64 of 66 end with GNU R's
   exit status and 27 print exactly GNU R's output. The others come from three known cases, two of them accepted divergences
   (`pf` to the last bit, and `env.profile` counts that follow GNU R's string hash), and
   `reg-large` needs tens of gigabytes of memory. All six corpus packages that run R code while
   loading (S7, arrow, nanoarrow, reticulate, minqa and yaml) now load under `ry run`.
   Parsed code keeps source references when `keep.source` asks for them. Connections, sockets included (so `parallel`'s PSOCK clusters run), are a single
   implementation shared by the interpreter and `libR`. R's graphics engine runs on ry's runtime
   with the R_GE_version 17 device API, so base graphics, grid, lattice and device packages such as
   ragg share one engine, and the built-in `pdf`, `svg`, `postscript`, `png`, `jpeg`, `bmp` and
   `tiff` devices are engine devices too. On ragg captures, base graphics, grid and lattice match
   GNU R pixel for pixel.

   At the full benchmark size (about 308,000 lines per code base), ry's test suites match GNU R on
   every test of all three code bases. With the JIT off, finbench's suite takes 1.13x GNU R's time;
   with it on, finbench, dsbench and biobench take 1.30x, 1.35x and 1.21x, so the JIT currently costs
   cold code about 15% (`.agents/memory/backlog.md`, "Open: the benchmark packages under ry's
   runtime", has the levers).
4. **The full C API and packages.** The rest of the 792 measured names and the BLAS and LAPACK
   interfaces, ALTREP, connections,
   unwind protection, C callables, `R CMD INSTALL` semantics and binary installs. Exit criterion: all
   232 packages of the closure install and pass their own tests under ry (with their `Suggests`
   installed), and the three generated
   code bases pass their test suites with output identical to GNU R.

   The C API is done, with evaluation behind a hook the interpreter installs
   (`libr::eval::Evaluator`). `libR` declares and exports all 985 function and variable names that
   GNU R's public headers declare, which covers the 444 the closure uses (the rest of the 792 are
   types, macros and enum constants in the headers). `crates/libr/tests/test_headers.rs` checks the
   list in `tests/headers/r_api_names.txt` against ry's headers and the exports. `libR` implements Rmath, Applic, LINPACK, ALTREP, connections and serialization; BLAS and LAPACK
   are declared in headers and come from the system libraries. Against the corpus library (GNU R
   4.3.3 binaries, `tests/test_corpus_binaries.rs`), 192 of the closure's 199 non-base compiled
   packages load and register under ry. Of the other seven, six evaluate R code while loading (S7,
   arrow, nanoarrow, reticulate, minqa, yaml) and tesseract needs a system library that is not
   installed. All 23 recorded `.Call` routines that need no evaluation return what GNU R returns
   (`tests/test_corpus_calls.rs`). The `rcmd` crate compiles packages from source as
   `R CMD INSTALL` does: 111 of the 113 compiled packages in the pinned sources build and load.
   Rblpapi needs Bloomberg's proprietary blpapi3 library and Rmpfr needs the MPFR headers. `rcmd`
   also runs the R-level half of installation (the lazy-load database, `Meta/` and help indices)
   on ry's interpreter, and `oracle install` installs the whole corpus that way: 236 of 238
   packages install from source and load. Rblpapi needs blpapi3 and magick needs ImageMagick's
   Magick++. Two package-test rates are tracked, both counting only the packages whose
   tests pass under GNU R. With the packages GNU R installed (`.corpus/library`, `oracle packages`),
   ry passes the tests of 140 of 144 (97.2%). With the packages ry installed itself
   (`.corpus/ry-library`, `oracle packages --installed`), it passes 155 of 164 (94.5%). The rest
   fail on interpreter gaps, and the classes are listed in `.agents/memory/backlog.md`.
5. **Lazy loading.** The item-based loader on top of the analysis index, replacing `load_all` and
   `loadfast` for the code bases. Built ahead of steps 1 to 4 on the GNU R backend; once the runtime
   exists it applies the same plans.
6. **Inline syntax, agreement warnings and strict mode (done),** in the parser, the checker and the
   runtime, with the runtime type summary and body facts.
7. **The JIT (loops and scalar functions done, general calls next).** The SSA IR, speculation, deoptimization and Cranelift backend, then environment and
   promise elision, then vector fusion, driven by the benchmark code bases and a microbenchmark set
   (the Ř benchmark suite is a good public start).
8. **The table type,** on Polars, with its own benchmark against data.table. The engine, its query
   IR, ALTREP exposure and the checker's `DataFrame` type exist (section 7); the interpreter now
   runs DataFrames and their Polars-style verbs, and data.table is a normal package that runs on its own code.
   data.table's readers, writers and helpers (`fread`, `fwrite`, `rbindlist`, `setkey`, `dcast`,
   `melt` and the rest) run data.table's own C, which under ry is at or below GNU R's time; ry
   never re-routes them. On db-benchmark's questions at 1e7 rows on four cores, ry called from R is
   faster than data.table on every one (section 7 has the table).

9. **Portability.** macOS runs the runtime: `libR.dylib` builds with the install name
   `@rpath/libR.dylib` and the full export list, GNU R's package binaries are rebound to it (section
   4), and `rcmd` reads its toolchain from GNU R's `Makeconf`. All of this is verified by
   cross-compiling from Linux for `aarch64-apple-darwin` and `x86_64-apple-darwin` and by running
   the Mach-O rewriter on a linker-built package; the release smoke test is the first run on a Mac.
   Windows builds `R.dll` and `ry.exe` for `x86_64-pc-windows-gnullvm` (the UCRT), and `ry run`
   runs base R and Rtools-built packages under Wine. `rcmd` also follows Rtools' conventions for
   `R CMD INSTALL` on Windows, verified only by installing from a Linux host, and the session reports
   a UTF-8 locale as `.utf8`, as GNU R does. What is verified and what is open is in section 11.

The JIT comes late on purpose. Until real packages run, there is nothing representative to optimize,
and an object model or calling convention changed for the JIT's sake after the C API exists would
break every package. The C API and the object model are designed first, as section 2 argues, and the
JIT fits around them.

## 11. Open questions

- **Windows runtime.** Built for `x86_64-pc-windows-gnullvm` and run under Wine, not yet on
  Windows. What exists:
  - `libr` builds as `R.dll` and the CLI as `ry.exe`, both for gnullvm, so both link the UCRT
    (`api-ms-win-crt-*`), as Rtools 4.2 and newer build packages. One C runtime matters because
    `errno`, `FILE *` and `malloc`/`free` pairs cross the API: a package that frees what R
    allocated, or reads `errno` after `Riconv`, must see the same runtime's state. Rust's
    `windows-gnu` target links `msvcrt.dll` instead, so it is not used.
  - `native.c` marks its exports `__declspec(dllexport)` and rustc exports the Rust side, so no
    `.def` file is needed, and the linker writes the import library `libR.dll.a` beside the DLL.
  - The headers' `LibExtern` is `__declspec(dllimport) extern` under `_WIN32`, as in GNU R, so a
    package reaches data exports such as `R_NilValue` through the import table.
  - R.dll carries the Windows-only parts of GNU R's interface that packages link: the
    `libintl_gettext` family (GNU R's `libintl.h` renames `gettext` to it; messages are not
    translated, so each returns its message id), `EmitEmbeddedUTF8`, and `xerbla_`, the BLAS
    error handler that R's `Rblas.dll` and `Rlapack.dll` import from R.dll. `xerbla_` raises
    GNU R's error when a package calls the routine, but returns while the interpreter calls BLAS
    or LAPACK from Rust (`DirectFortran` in `crates/interp/src/linalg.rs`), because the jump
    would cross Rust frames; the routine then returns a negative `info`, which the interpreter
    reports.
  - `native.c` jumps with the CRT's `_setjmp(buffer, NULL)` and `longjmp`. The null frame makes
    `longjmp` restore registers only, as on Unix, instead of unwinding through SEH. Neither
    mingw's `setjmp` macro (which unwinds) nor clang's `__builtin_setjmp` works: the builtin
    saves the canonical frame address but its landing code treats it as the frame pointer, so a
    function whose frame pointer sits above its stack pointer, as `R_UnwindProtect`'s does,
    resumes with every local misread.
  - The interpreter's operating-system calls go through `crates/interp/src/platform.rs`: CPU
    times, file modes, the umask, file times, links, globbing, processes, dynamic libraries,
    `errno`, the native codeset and `iconv`. Windows has no `iconv(3)`, so ry converts there
    itself (UTF-8, Latin-1, ASCII, UTF-16, UTF-32, and the other encodings `encoding_rs` knows),
    behind the same interface `Riconv` exposes to packages.
  - The session reports itself as Windows: `.Platform$OS.type` is `"windows"`, the path
    separator `;`, the platform `x86_64-w64-mingw32`, and `normalizePath` returns backslashes
    (or `winslash`) without the `\\?\` prefix Rust's canonical paths carry, makes a missing path
    absolute as GNU R does, and rejects a `winslash` other than `"/"` or `"\\"`. The default
    packages' DLLs are found under `library/<pkg>/libs/x64/`, and the Windows-only routines that
    `utils` and `grDevices` call at load time (`winver`, `getIdentification`, `readRegistry` and
    so on) are registered (`WINDOWS_ROUTINES` in `crates/interp/src/builtin_libraries.rs`).
  - `ry.exe` and `ry-rcmd.exe` reserve a 64 MiB main-thread stack and embed `ry.exe.manifest`,
    which makes UTF-8 the active code page as `R.exe`'s manifest does (`crates/ry/build.rs`,
    through `windres`, which `rcmd` names as its build script too). The session also switches each
    locale category's codeset to UTF-8 at startup, so it holds even where the manifest is ignored,
    and reports the codeset as `.utf8`, as GNU R does (Wine's CRT names it `.65001`).
  - `rcmd` builds packages the Windows way when the R home's `etc/Makeconf` says `SHLIB_EXT =
    .dll`, the one fact every other convention is derived from (`Platform::of_home`):
    `Makevars.ucrt`, then `Makevars.win`, then `Makevars`; `configure.ucrt` or `configure.win` and
    `Makefile.ucrt` or `Makefile.win`, with no fallback to the Unix files; DLLs installed under
    `libs/x64/`; and `R_ARCH=/x64` for the build and for `install.libs.R`. Its `Makeconf` follows
    the Rtools ABI of GNU R's `etc/x64/Makeconf`: `gcc`/`g++`/`gfortran`, `-shared
    -static-libgcc`, no PIC flags, and `-L"$(R_HOME)/bin/x64" -lR` against the `libR.dll.a` that
    the home keeps beside `R.dll` in `bin/x64/`. A DLL exports what the package's
    `<name>-win.def` lists, or else every global symbol, as GNU R's `winshlib.mk` links it. Before
    an `R CMD` command the front end reads the home's `etc/Rcmd_environ`, linked from GNU R, as
    GNU R's `Rcmd.exe` does, which puts that R version's Rtools first on `PATH`, so Rtools' GCC
    finds Rtools' assembler even when another toolchain (MSYS2's clang64, say) comes earlier on
    `PATH`. Windows runs no shell scripts, so the home's
    `bin/R.exe`, `bin/Rscript.exe`, `bin/x64/Rcmd.exe` and `bin/x64/Rterm.exe` (which callr starts)
    are copies of `ry-rcmd.exe`, which reads which front end it is from its file name and the home
    from its location, ignoring an inherited `R_HOME`. The paths it exports to `configure` and
    `make` use forward slashes, because both read a backslash as an escape. Directories that
    cannot be linked (Windows needs Developer Mode for symbolic links) are copied.
  - `ry run` loads `R.dll` from beside `ry.exe`, and BLAS and LAPACK from the R installation's
    `bin/x64/Rblas.dll` and `Rlapack.dll`. DLLs load with `LOAD_WITH_ALTERED_SEARCH_PATH` from a
    backslashed path, so `Rlapack.dll` finds `Rblas.dll` in its own directory.
  - `ry R` loads GNU R's `R.dll` before its siblings, by full path. ry's own `R.dll` beside
    `ry.exe` is first in the default search order, and Windows binds a later import of `R.dll` by
    name to whichever module of that name loaded first. This ordering is unverified, because the
    checks do not run GNU R's DLLs.

  Both binaries must be linked with LLVM's `lld`. GNU ld as packaged by Ubuntu's mingw-w64
  (2.41) emits a base relocation for each `SECREL32` thread-local offset, so when Windows loads
  the DLL at another address than its preferred one (ASLR does this routinely), every
  `thread_local` access lands on a garbage address. The release workflow uses MSYS2's clang64
  environment on the Windows runner. Cross-building from Linux needs clang, lld, `llvm-windres`
  and a clang64 sysroot (MSYS2's `crt`, `headers`, `winpthreads`, `libunwind` and `compiler-rt`
  packages, or an llvm-mingw release), with a wrapper `x86_64-w64-mingw32-clang` that runs
  `clang --target=x86_64-w64-windows-gnu --sysroot=SYSROOT -rtlib=compiler-rt
  -unwindlib=libunwind -fuse-ld=lld`:

  ```sh
  CARGO_TARGET_X86_64_PC_WINDOWS_GNULLVM_LINKER=x86_64-w64-mingw32-clang \
  CC_x86_64_pc_windows_gnullvm=x86_64-w64-mingw32-clang AR_x86_64_pc_windows_gnullvm=llvm-ar \
  WINDRES=llvm-windres cargo build --target x86_64-pc-windows-gnullvm -p libr -p ry-lang
  ```

  Verified under Wine 9 with a Windows R 4.5 home whose own DLLs were not executed:
  - Base R scripts that print, sort, summarize `mtcars`, format dates, run regular expressions,
    read files, load `stats`, `utils` and `tools`, catch errors and call `normalizePath()`
    print what GNU R prints (compared with GNU R's documented and Unix output, since GNU R
    itself did not run). `l10n_info()` reports code page 65001.
  - Package DLLs built from CRAN sources against `R.dll`'s import library with the Rtools ABI
    (GCC 14's headers and static `libstdc++` from MSYS2's ucrt64 environment, driven by clang
    and lld): jsonlite, data.table (grouping, keys, `fwrite`/`fread`, its error messages), digest,
    cli, uuid and Rcpp, plus a test package that throws Rcpp and C++ exceptions, calls back into R,
    and lets an R error cross its C++ frames, with every destructor run once.
  - `R CMD INSTALL` of those six packages through `rcmd`'s Windows conventions, then `library()`
    and a call into each one's DLL from `libs/x64/` under `ry.exe`. The install was cross-hosted,
    because running MSYS2's `gcc`, `make` or `sh` under Wine is not allowed in the environment
    that verified it: `rcmd` on Linux, with a home whose `Makeconf` is the Windows one and whose
    compilers are clang wrappers over the ucrt64 sysroot that link libstdc++, winpthreads and zlib
    statically, as Rtools' GCC does. The R-code half of that install ran on Linux ry, so the
    `Built:` platform was restamped before loading. `ry-rcmd.exe assemble` under Wine wrote the
    Windows home, and its `R.exe RHOME` and `Rscript.exe` (loading digest, reporting `.utf8`
    locales and code page 65001) ran from it.
  - The BLAS path, with a stand-in `Rblas.dll` built from C that imports `xerbla_` from `R.dll`
    as R's own does: ry loads and calls it, and a bad argument becomes the R error `BLAS/LAPACK
    routine 'DGEMM ' gave error code -3`. R's own `Rblas.dll` and `Rlapack.dll` import nothing
    else from R.dll, which their import tables show.

  Open:
  - Nothing has run on Windows itself; the release smoke test (`tools/smoke-test.sh`, which runs
    a script, a BLAS and LAPACK call and a CRAN binary of jsonlite) is the first run.
  - `R CMD INSTALL` driving Rtools' own `make`, `sh` and GCC on Windows has not run; the release
    smoke test should install a source package with a `Makevars.win` (data.table) on the runner.
  - `win.version()` and `Sys.info()` report a fixed `Windows 10 x64` with no build number.
- **Bytecode compatibility.** Installed binary packages contain GNU R bytecode in their lazy-load
  databases. ry can ignore it and recompile from the deparsed closures, which is the current plan,
  but it costs install time.
- **How much of base R to reimplement natively versus reuse as R source.** The plan above reuses the
  R sources, which is less work but ties ry to GNU R's base implementation details.

Settled: **licensing.** The runtime is GPL-2.0-or-later, as GNU R is, because parts of it
translate R's C sources ([licensing](/reference/licensing.md)). ry still loads base R's R sources
at runtime from the user's own GNU R installation instead of vendoring them, which keeps ry small
and lets it behave like the R version it finds; the reasoning is in
`.agents/memory/decisions/docs-process.md` ("licensing").

## Sources

- R 4.6.2 sources: `src/include/` (the public headers), `doc/manual/R-exts.texi` (API classes),
  `src/library/tools/R/sotools.R` (the non-API list).
- The measured data: `tools/research/data/` and the scripts beside it.
- loadfast: [github.com/finccam/loadfast](https://github.com/finccam/loadfast), README and
  `TECHNICAL_DEBT.md`.
- Ř: [reactorlabs/rir](https://github.com/reactorlabs/rir) and its [benchmarking tools](https://github.com/reactorlabs/rbenchmarking); Flückiger et al., "R Melts Brains: An IR for First-Class Environments and Lazy Effectful
  Arguments" (DLS 2019) and "Contextual Dispatch for Function Specialization" (OOPSLA 2020).
- rcp: Kocourek, Křikava and Vitek, "Copy-and-Patch Just-in-Time Compiler for R" (VMIL 2025),
  [d3s.mff.cuni.cz](https://d3s.mff.cuni.cz/publications/kocourek_copyandpatch_2025/).
- FastR status: the [GraalVM R runtime reference manual](https://www.graalvm.org/dev/reference-manual/r).
- Renjin status: [renjin.org/support](https://www.renjin.org/support.html).
- TERR package compatibility: the [Spotfire Enterprise Runtime for R release notes](https://docs.tibco.com/pub/enterprise-runtime-for-R/6.0.3/doc/html/TIB_terr_Documentation/relnotes/topics/package_compatibility.html).
- Riposte: Talbot, DeVito and Hanrahan, "Riposte: A Trace-Driven Compiler and Parallel VM for Vector
  Code in R" (PACT 2012).
- Copy-and-patch: Xu and Kjolstad, "Copy-and-Patch Compilation" (OOPSLA 2021).
