monoruby

monoruby is a Ruby implementation written from scratch in Rust, featuring a register-based bytecode VM and a just-in-time (JIT) compiler for x86-64 and aarch64 (Apple Silicon). It is fast — comparable to CRuby with YJIT/ZJIT on many benchmarks — and has no dependency on any other Ruby runtime.

This site is monoruby’s documentation: how to build and run it, how it performs, and how it works inside.

• The Getting Started section covers installing and building monoruby, and the build options and test workflow used when developing it.
• The Performance and Compatibility section is where the live dashboards are explained: Benchmark for speed against CRuby+YJIT, Compatibility for ruby/spec conformance. The Changelog sits alongside them.
• The Architecture section contains overview pages: start with the Architecture Overview.
• The Design Documents section renders the full design documents from the repository’s doc/ directory (some are written in Japanese, as marked).

Quick start

git clone https://github.com/sisshiki1969/monoruby.git
cd monoruby
cargo install --path monoruby   # nightly Rust is installed automatically by rust-toolchain.toml
monoruby -e 'puts "hello"'

See Installation and Build for prebuilt binaries, the GitHub Action, platform notes and the full command-line reference.

Related resources

• README — features and the monthly changelog
• Benchmark dashboard — continuously updated yjit-bench comparison, re-run on every push to master that touches the interpreter
• ruby/spec dashboard — spec compliance for this repository
• rubyspec-stats — daily ruby/spec pass rates across Ruby implementations

Installation and Build

monoruby is a standalone Ruby implementation: it does not need CRuby or any other Ruby runtime to build or to run. There are two ways to get it — a prebuilt binary, or a build from source.

Supported platforms

Both architectures lower the complete instruction set; the JIT never declines a compile on either. See x86-64 / aarch64 JIT backend differences for what actually differs between the two backends.

Prebuilt binaries

Releases carry prebuilt tarballs, and a rolling nightly prerelease is rebuilt on every push to master. The easiest way to consume them is the setup-monoruby GitHub Action that this repository doubles as, modeled after ruby/setup-ruby. The ref after @ selects the version:

steps:
  - uses: sisshiki1969/monoruby@master # or a release tag
  - run: monoruby my_script.rb

The action downloads a release asset when one exists for the ref and platform (seconds), and otherwise builds from source once per monoruby revision × runner OS/arch and caches the result with actions/cache. Automatic builds cover x86-64 Linux; Linux arm64 and macOS arm64 assets are published on demand by dispatching the release binaries workflow. See the README’s action section for the full input/output table.

Each asset is a tarball containing bin/monoruby, bin/irm, and the monoruby-home/v<version>/ runtime tree described under What the build installs below. Because the binary bakes in the build machine’s install-root path, point MONORUBY_INSTALL_ROOT at wherever you extracted that tree.

Building from source

1. Install Rust

Only nightly Rust works. monoruby uses several nightly-only language features (box_patterns, iter_next_chunk, step_trait, coverage_attribute), so a stable toolchain fails to build.

You do not have to select the channel by hand: rust-toolchain.toml pins the exact nightly the project is developed and tested against, and rustup installs and uses it automatically the first time you run cargo in the checkout.

# rust-toolchain.toml
[toolchain]
channel = "nightly-2026-08-18"

If you have no Rust at all yet, install rustup first.

2. Clone the repository

git clone https://github.com/sisshiki1969/monoruby.git
cd monoruby

3. Platform-specific dependencies

On aarch64 macOS only, monoruby links the system libffi instead of the bundled one (the bundled libffi-sys fails to link _ffi_prep_cif_machdep on arm64):

brew install libffi pkg-config
export PKG_CONFIG_PATH="$(brew --prefix libffi)/lib/pkgconfig"

Linux and x86-64 macOS need nothing extra.

4. Build and run

cargo build --release
cargo run --release -- test.rb

The debug profile is built at opt-level = 1 (set in the workspace Cargo.toml), so a debug build is usable for day-to-day work — but use --release for anything you intend to measure.

A one-liner:

cargo run --release -- -e "puts 100"

5. Install

cargo install --path monoruby

This puts two binaries on your PATH:

monoruby test.rb   # the interpreter
irm                # the REPL

From a checkout you can launch the REPL without installing:

cargo run --bin irm
# or
bin/irm

What the build installs

monoruby/build.rs runs on every cargo build and is host-Ruby independent — it does not need a ruby on PATH to produce a correct, reproducible build. It does two things:

1. Bakes the reported Ruby version. MONORUBY_RUBY_VERSION is read from monoruby/vendor/ruby-stdlib/.ruby-version (currently 4.0.2) and reported at run time as RUBY_VERSION. Taking it from the vendored snapshot rather than a host ruby keeps the version monoruby reports in step with the stdlib it actually ships.

2. Installs the runtime tree into a per-version root, ~/.monoruby/v<version>/ (e.g. ~/.monoruby/v0.3.0/), whose absolute path is baked into the binary as MONORUBY_INSTALL_ROOT:

   Source	Installed as	Contents
   monoruby/vendor/ruby-stdlib/	<root>/lib/	Checked-in CRuby stdlib + default-gem snapshot
   monoruby/builtins/	<root>/builtins/	Ruby files loaded at interpreter start (startup.rb, enumerable.rb, …)
   monoruby/stdlib/, monoruby/gem/	<root>/lib/ and <root>/stub/	monoruby’s own host-independent replacements for C-extension-backed libraries

   The install is staged in a private directory and swapped in with an atomic rename, so a running monoruby never sees a half-populated tree, and the per-version namespacing keeps concurrent builds and multiple checkouts from clobbering each other.

build.rs declares cargo:rerun-if-changed for each of those trees, so editing builtins/, stdlib/ or gem/ reinstalls on the next build, and deleting ~/.monoruby re-triggers the whole install.

Setting MONORUBY_INSTALL_ROOT in the runtime environment overrides the baked path, which is what makes a distributed binary relocatable.

Do I need a host Ruby?

To build and run monoruby: no. The stdlib is vendored and the version is read from the snapshot.

A host ruby is used for exactly two optional things:

• Host-installed (non-default) gems. At startup src/ruby_probe.rs invokes a host ruby once — if one is present and is 4.0 or later — to discover $LOAD_PATH and Gem.paths.path, and caches the answer in ~/.monoruby/{library_path,gem_path} so the ~50 ms spawn is paid once per machine. Precedence is MONORUBY_GEM_PATH / MONORUBY_LOAD_PATH, then GEM_PATH, then the cache files, then the probe. MONORUBY_REPROBE=1 forces a fresh probe. With no host Ruby, those caches stay empty and the vendored stdlib still loads normally — you will just see this on startup:

  Warning: failed to read library path file: "~/.monoruby/library_path". Ruby may not be installed.
  

  It is a warning, not an error: only host-installed gems are unavailable.

• Running the test suite, which compares monoruby’s output against CRuby. See Development and Build Options.

Command-line options

monoruby accepts CRuby’s command-line switches:

Usage: monoruby [switches] [--] [programfile] [arguments]
  -0[octal]       specify record separator (\0, if no argument)
  -a              autosplit mode with -n or -p (splits $_ into $F)
  -i[extension]   edit ARGV files in place (make backup if extension supplied)
  -c              check syntax only
  -Cdirectory     cd to directory before executing your script
  -d, --debug     set debugging flags (set $DEBUG to true)
  -e 'command'    one line of script. Several -e's allowed. Omit [programfile]
  -Eex[:in], --encoding=ex[:in]
                  specify the default external and internal character encodings
  -Fpattern       split() pattern for autosplit (-a)
  -Idirectory     specify $LOAD_PATH directory (may be used more than once)
  -l              enable line ending processing
  -n              assume 'while gets(); ... end' loop around your script
  -p              assume loop like -n but print line also like sed
  -rlibrary       require the library before executing your script
  -s              enable some switch parsing for switches after script name
  -S              look for the script using PATH environment variable
  -U              set the internal encoding to UTF-8
  -v              print the version number, then turn on verbose mode
  -w              turn warnings on for your script
  -W[level=2|:category]
                  set warning level; 0=silence, 1=medium, 2=verbose
  -x[directory]   strip off text before #!ruby line and perhaps cd to directory
  -h              show this message, --help for more options
  --ast           dump the parsed ruby-prism AST and exit
  --no-jit        disable just-in-time compilation
  --no-gc         disable garbage collection
  --enable=feature[,...], --disable=feature[,...]
                  enable or disable features (gems, did_you_mean, rubyopt,
                  frozen-string-literal, all)

RUBYOPT is honoured for the subset of switches CRuby permits there.

The three monoruby-specific switches are worth knowing:

• --no-jit — run everything in the bytecode VM. The JIT is always compiled into the binary; this disables it at run time. Useful for isolating a JIT bug from a VM bug, and as the baseline half of a JIT A/B.
• --no-gc — disable garbage collection entirely.
• --ast — dump the parsed prism AST and exit.

Development and Build Options

This page collects the build features, environment variables and helper scripts used when working on monoruby, rather than with it. For getting a working binary in the first place see Installation and Build.

Cargo features

Every feature is off by default. They are diagnostic or stress switches: none of them changes what a correct program computes, and none is needed for a normal build.

The JIT is always compiled in regardless of features — it is disabled at run time with --no-jit. (The old jit / jit_x86 build cfgs and the no-jit feature are gone; backend selection is purely by target_arch.)

Dumping the compilation pipeline

JIT diagnostics

GC

Register allocation and allocator experiments

The last three are gated on measurement and are off until their A/B clears; see Separating the abstract interpreter from register allocation.

Worked example: reading the pipeline

Everyone loves Fibonacci, so all three dumps below are of the same benchmark/app_fib.rb:

def fib n
  if n < 3
    1
  else
    fib(n-1) + fib(n-2)
  end
end

puts fib(34)

Bytecode (--features emit-bc)

cargo build --release --features emit-bc
target/release/monoruby benchmark/app_fib.rb 2> fib.bytecode > /dev/null

Each method and block is dumped as a register-based instruction listing, grouped into basic blocks (BBx). %n is a bytecode register (SlotId); _%n marks a result the next instruction consumes directly without the value ever being stored. The bracketed columns on the right are inline-cache slots, shown as <INVALID> here because the dump happens at compile time, before any cache has been filled.

<fib> benchmark/app_fib.rb:1
FuncId(3835) SIMPLE stack reg_num:5 owner:[] local_vars:1 temp:3
ParamsInfo { required_num: 1, optional_num: 0, rest: None, rest_is_implicit: false, post_num: 0, args_names: [Some(n)], kw_names: [], kw_required: [], kw_rest: None, block_param: None, forwarding: false, it_param: false, forbid_keyword: false }
[]
  BB0
    :00000 [02] init_method reg:4 arg:1 stack_offset:8
    :00001 [03] %2 = 3
    :00002 [03] _%2 = %1 < %2                        [<INVALID>][<INVALID>]
    :00003 [02] condnotbr _%2 => BB2
  BB1
    :00004 [03] %2 = 1
    :00005 [02] ret %2
  BB2
    :00006 [03] %2 = 1
    :00007 [03] %2 = %1 - %2                         [<INVALID>][<INVALID>]
    :00008 [03] %2 = %0.fib(%2)                      [<INVALID>] -
    :00010 [04] %3 = 2
    :00011 [04] %3 = %1 - %3                         [<INVALID>][<INVALID>]
    :00012 [04] %3 = %0.fib(%3)                      [<INVALID>] -
    :00014 [03] %2 = %2 + %3                         [<INVALID>][<INVALID>]
    :00015 [02] ret %2

%0 is self, %1 is the parameter n, and [nn] is the source line. See Method argument processing for what the ParamsInfo counters mean.

JIT-compiled machine code (--features emit-asm)

cargo build --release --features emit-asm
target/release/monoruby benchmark/app_fib.rb 2> fib.disas > /dev/null

Each bytecode instruction is printed with the machine code it lowered to, so the dump reads as an annotated disassembly. The bracketed columns are now the resolved inline caches — [Integer][Integer] for the arithmetic, and [#<Class:main>] FuncId(3835) for the recursive call — because by the time the JIT runs, the VM has executed the method often enough to fill them. That is exactly the type information the compiler speculates on; see Invariants compiled code speculates on.

==> start whole compile: FuncId(3835) <Object#fib> self_class: #<Class:main> benchmark/app_fib.rb:1
  >>> [0] ISeqId(2164) <Object#fib> self_class:#<Class:main>
      offset:Pos(251180) code: 517 bytes  data: 0 bytes
  BB0
    :00000 init_method reg:4 arg:1 stack_offset:8
      000000: push   rbp
      000001: mov    rbp,rsp
      000004: sub    rsp,0x80
      00000b: movabs rax,0x4
      000015: mov    QWORD PTR [rbp-0x48],rax
      000019: mov    QWORD PTR [rbp-0x50],rax
      00001d: mov    QWORD PTR [rbp-0x58],rax
      000021: cmp    DWORD PTR [rip+0x7ffc2ad4],0x0        # 0x7ffc2afc
      000028: jne    0x3ffc60be
    :00001 %2 = 3
    :00002 _%2 = %1 < %2                        [Integer][Integer]
      00002e: mov    r8,QWORD PTR [rbp-0x40]
      000032: test   r8,0x1
      000039: je     0x3ffc60e9
      00003f: cmp    r8,0x7
      000043: jge    0x55
    :00003 condnotbr _%2 => BB2
  BB1
    :00004 %2 = 1
    :00005 ret %2
      000049: movabs rax,0x3
      000053: leave
      000054: ret
  BB2
    :00006 %2 = 1
    :00007 %2 = %1 - %2                         [Integer][Integer]
      000055: mov    r8,QWORD PTR [rbp-0x40]
      000059: sub    r8,0x2
      00005d: jo     0x3ffc61ce
    :00008 %2 = %0.fib(%2)                      [#<Class:main>] FuncId(3835)
      000063: mov    eax,DWORD PTR [rip+0x7ffc2a6b]        # 0x7ffc2ad4
      000069: cmp    eax,DWORD PTR [rip+0xffffffffffffff8d]        # 0xfffffffc
      00006f: jne    0x3ffc61dd
      000075: cmp    rsp,QWORD PTR [rbx+0x18]
      000079: jle    0x3ffc6344

      … call sequence and the second recursive call elided …

    :00014 %2 = %2 + %3                         [Integer][Integer]
      0001d5: mov    r9,QWORD PTR [rbp-0x48]
      0001d9: test   r9,0x1
      0001e0: je     0x3ffc6540
      0001e6: test   r8,0x1
      0001ed: je     0x3ffc6548
      0001f3: sub    r9,0x1
      0001f7: add    r9,r8
      0001fa: jo     0x3ffc6550
    :00015 ret %2
      000200: mov    rax,r9
      000203: leave
      000204: ret
  <<<
Object#fib #<Class:main> None (522 bytes, 1223 bytes) [wm0:CodePtr(139715286390055)-CodePtr(139715286390577) wm1:CodePtr(139716359894468)-CodePtr(139716359895691)] 5.462877ms
- [ISeqId(2164)] <Object#fib> self_class:#<Class:main>

Things worth reading out of that listing:

• The guards are the speculation. test r8,0x1 / je is the Fixnum tag check on n; the jo after each sub / add catches overflow out of the 63-bit Fixnum range; and movl rax,[rip+global_version] / cmpl rax,[rip+cached_version] / jne before each call is the class-version guard. Every one of those branch targets is a side exit.
• Fixnums are tagged, and the constants are pre-encoded. n < 3 compiles to cmp r8,0x7 because 3 as a Fixnum is 3 << 1 | 1; n - 1 is sub r8,0x2; and the base case returns movabs rax,0x3, which is 1. The final sub r9,0x1; add r9,r8 strips one tag bit before adding. See Value Representation.
• No accumulator register. Values live in whatever GP register the per-basic-block allocator picked (r8 and r9 here), with the frame at [rbp-…]. The fixed r15 accumulator was retired in June 2026.
• cmp rsp,[rbx+0x18] before each call is the stack-limit check; rbx holds &mut Executor.

The summary line reports the code size and the two code regions the compiler emitted into: wm0 is the fast path, wm1 the out-of-line page holding the recompile and deopt stubs each failing guard jumps to.

CFG (--features emit-cfg)

emit-cfg writes one DOT file per JIT-compiled function into a .cfg/ directory under the current working directory, named by FuncId:

cargo build --release --features emit-cfg
target/release/monoruby benchmark/app_fib.rb > /dev/null
dot -Tsvg .cfg/fid-3835.dot -o fib-cfg.svg

Only functions that actually reach the JIT are dumped, so the set of files also tells you what got compiled.

Testing

cargo test              # unit + integration tests
bin/test                # the full CI scope: tests + coverage + benchmarks + optcarrot + spec

bin/test is what CI runs. In order it:

1. Runs cargo llvm-cov nextest with stress-spill-pool (plus gc-stress only when GC_STRESS=1 is exported).
2. Builds a debug benchmark binary with the same feature list, so a GC_STRESS=1 run stresses the benchmark / optcarrot / spec phases too.
3. Runs the benchmark scripts and diffs their output against CRuby (app_fib, tarai, so_nbody, plb2 nqueen / sudoku, and so_mandelbrot both with and without the JIT).
4. Runs optcarrot plain and with --opt, comparing output against CRuby.
5. Runs a ruby/spec subset if ../spec and ../mspec exist.
6. Writes an lcov.info coverage report.

SKIP_COV=1 runs the whole script without llvm-cov instrumentation.

The snapshot oracle

Tests compare monoruby’s output against CRuby, but they do not spawn CRuby per test. The single-code helpers — run_test, run_test_once, run_test2, run_test_with_prelude — memoize expected output in the checked-in file monoruby/tests/ruby_oracle.tsv (code-hash → output, key-sorted and flock-serialized so concurrent nextest processes cooperate). A live ruby is invoked only on a cache miss, and the fresh entry is written back — commit it. The batched helpers (run_tests, run_tests2, and the binop/unop generators built on them) always spawn a live CRuby, because their generated code strings churn too much to be worth snapshotting.

MONORUBY_TEST_ORACLE selects the mode:

rm monoruby/tests/ruby_oracle.tsv && cargo test   # regenerate from scratch
MONORUBY_TEST_ORACLE=ruby cargo test              # re-verify against a new CRuby

Tests whose expected value varies per host or OS must use run_test_live / run_test_once_live, which always compare against a live CRuby: anything touching Dir.home / Dir.pwd, absolute checkout paths, ~user expansion (/root vs macOS /var/root), or realpath under /tmp (a symlink to /private/tmp on macOS). As a safety net a cached entry that disagrees with monoruby is re-verified against a live CRuby before failing — grep test output for re-verifying against a live ruby to find tests that should move to the _live helpers.

Running the suite needs a host ruby matching the vendored pin (4.0.2, from monoruby/vendor/ruby-stdlib/.ruby-version). Since Ruby 3.4 bigdecimal is no longer a default gem, so install it explicitly or every tests/bigdecimal.rs test fails with LoadError:

gem install bigdecimal

GC stress

gc-stress collects at every safepoint. It is what finds unrooted-Value bugs — a builtin that creates a Value and then re-enters Ruby — and it is opt-in precisely because it is expensive: stacked on llvm-cov it took the x86-64 nextest phase from ~10 minutes to ~100, and a full bin/test scope under stress is an hours-scale job.

GC_STRESS=1 bin/test    # applies to every phase, not just nextest

Nothing enables it implicitly, so the automatic CI never pays for it. Instead dispatch the manual gc-stress workflow from the Actions tab when touching the GC, frame layout, argument binding, or any builtin that creates a Value and re-enters Ruby. Its inputs are arch (both / x86_64 / aarch64), scope (nextest = the unit + integration suite, minutes; full = the whole bin/test scope, hours), test_filter (a nextest -E expression), and no_fail_fast. It runs on ubuntu-latest and native arm64 (ubuntu-24.04-arm), not qemu, and collects no coverage.

Tests whose loop counts exist only to reach the JIT thresholds should shrink them under cfg!(feature = "gc-stress") (see tests/method_call.rs), or they blow past nextest’s per-test cap.

ruby/spec

ruby/spec is cloned outside the monoruby repository, alongside it:

parent/
├── monoruby/    # this repository
├── spec/        # ruby/spec
└── mspec/       # the mspec runner

cd /path/to/parent-of-monoruby
git clone --depth 1 https://github.com/ruby/spec.git spec
git clone --depth 1 https://github.com/ruby/mspec.git mspec

cd monoruby && cargo install --path monoruby

cd ../spec
../mspec/bin/mspec run core/array -t monoruby              # one category
../mspec/bin/mspec run core/array/flatten_spec.rb -t monoruby  # one file
../mspec/bin/mspec run core/array -t monoruby --format dotted

bin/spec from the monoruby checkout runs a standard set of categories in one go. Pass rates are published continuously on the spec dashboard; see ruby/spec hang countermeasures for how the suite avoids hangs.

aarch64

On an x86-64 host the aarch64 backend is cross-compiled and run under qemu-user:

bin/setup-aarch64-cross   # qemu-aarch64, aarch64-linux-gnu-gcc, rust std
bin/test-aarch64          # same scope as bin/test, for aarch64

bin/test-aarch64 takes SKIP_HEAVY=1 (skip the benchmarks and specs that take over ten minutes under emulation), SKIP_COV=1, and STRESS=1. The .cargo/config.toml wiring points aarch64-unknown-linux-gnu at that cross toolchain and runner, which is why the CI job on a native arm64 runner overrides CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_{LINKER,RUNNER} — otherwise it would emulate everything.

Measurement and profiling

--features profile collects deopt and recompile statistics: which sites deoptimized, how often, and why. The reasons are the RecompileReason variants — NotCached, MethodNotFound, IvarIdNotFound, ClassVersionGuardFailed, BecamePolymorphic, ConstVersionGuardFailed.

--features deopt logs individual deoptimizations; Reading the deopt log explains the format, including how the log names the guard that actually branched when exits have been deduplicated.

For time rather than counts, see Benchmarks.

JIT thresholds

A function is compiled after 20 calls (COUNT_START_COMPILE) and a loop after 100 iterations (COUNT_LOOP_START_COMPILE). Both drop to 5 and 15 in test builds, so tests reach compiled code without long warm-up loops.

Vendored and pinned dependencies

hashbrown/ is a workspace member (a local fork). smallvec is also a fork but is consumed as a git dependency rather than in-tree.

The ruby-prism wrapper is pinned to the monoruby-vendored branch of sisshiki1969/prism. That fork has two branches:

• monoruby — the minimal upstream-bound diff (the Rust parse_with_options API plus ruby-prism-sys bindgen allowlist additions). The base for any upstream PR to ruby/prism.
• monoruby-vendored — monoruby plus one commit checking in the C sources the upstream vendored.rs build script needs, so consumers need neither bundler nor rake cargo:build.

To bump the prism revision: push to the fork’s monoruby branch, run bin/refresh-prism-vendored (which rebuilds and force-pushes monoruby-vendored), then cargo update -p ruby-prism here.

bin/vendor-ruby-stdlib re-snapshots CRuby’s pure-Ruby stdlib and default gems into monoruby/vendor/ruby-stdlib/. It is a maintenance step, never run by cargo build.

Continuous integration

Neither rust.yml job sets GC_STRESS, so neither pays the per-safepoint cost.

Documentation

This book lives in docs/. docs/build.sh copies doc/*.md and the diagrams into docs/src/design/ (gitignored) and runs mdbook build; docs.yml publishes the result. If you add a design document to doc/, give it a chapter in docs/src/SUMMARY.md — mdBook renders only what SUMMARY.md lists, so an unlisted document is copied and then silently dropped.

bash docs/build.sh          # output in docs/book/
mdbook serve docs           # live preview

The changelog and the README

docs/src/changelog.md is the single source of truth for the monthly changelog. The README shows only the two newest month sections, copied verbatim between its <!-- BEGIN LATEST-MONTHS --> / <!-- END LATEST-MONTHS --> markers — that block is generated, so edit the changelog and regenerate rather than editing the README:

bin/sync-changelog-readme           # rewrite the README block
bin/sync-changelog-readme --check   # exit 1 if the two have drifted

A scheduled Routine runs on the 1st of each month: it summarizes the previous month’s merged PRs into a new ### <Month> <Year> section at the top of the changelog’s current ## <year> group, runs the sync script, and pushes both files. Pushing docs/src/changelog.md also re-triggers docs.yml, so the published book picks the new month up in the same run.

Benchmark

monoruby is performance-focused, and performance is measured continuously rather than quoted from a README. This page covers the live dashboards, how to reproduce a measurement locally, and the historical one-off comparisons that used to live in the project wiki.

Live dashboards

Every push to master that touches the interpreter re-runs the benchmark suite and republishes the project portal:

The portal also hosts the two ruby/spec dashboards; those are covered in Compatibility.

Methodology, from .github/workflows/bench.yml:

• The suite is yjit-bench, run with --rss --harness=harness-warmup, monoruby against ruby --yjit on the same runner in the same job.
• The reference CRuby is 4.0.2 (ruby/setup-ruby), and monoruby is installed with cargo install --path monoruby --locked.
• Each benchmark gets a 400-second timeout per interpreter; a benchmark that times out or exits non-zero is recorded as a failure rather than silently dropped, and shows on the dashboard as a gap.
• The published ratio is × YJIT, higher = monoruby faster, 1× being parity. latest.json and data/history.csv next to each dashboard hold the raw numbers if you want to plot them yourself.

As a snapshot: on the x86-64 run of commit a13bfe0 (2026-08-31), 59 of the 76 benchmarks produced a ratio on both interpreters; over those the geometric mean was 1.28× YJIT, with monoruby ahead on 30 of them. The spread is wide in both directions — from ~16× on string_malloc_pressure down to ~0.3× on send_bmethod — which is the point of reading the dashboard rather than a single headline number.

Reproducing a measurement locally

The helper scripts in bin/ wrap the two harnesses the project uses. Most of them assume benchmark-driver and rbenv-managed reference Rubies; adjust the version strings inside to match what you have installed.

bin/compare is the one to reach for when you want to know whether a change you just made helped:

bin/compare                          # HEAD~1 vs HEAD, standard benchmarks
bin/compare abc1234 def5678          # two specific commits
bin/compare HEAD~5 HEAD app_fib.yml  # one benchmark

For a single script, a release build is enough:

cargo build --release
target/release/monoruby benchmark/app_fib.rb

Benchmark scripts and their benchmark-driver YAML configs live in benchmark/. Passing --no-jit gives you the VM-only baseline for the same script, which is often more informative than an absolute number.

Profiling

# Flame graph via Linux perf (needs ../FlameGraph)
bin/perf benchmark/app_fib.rb

# or by hand
cargo build --release --features perf
perf record target/release/monoruby benchmark/app_fib.rb
perf report

The perf feature makes monoruby emit perf-compatible symbol maps so JIT-compiled frames get names instead of raw addresses. .cargo/config.toml sets -Cforce-frame-pointers=yes globally, which is what makes the stacks walkable.

--features profile collects deopt and recompile statistics instead of a time profile — see Development and Build Options. Where optcarrot –opt spends its time is a worked example of both.

Historical measurements

The two comparisons below are one-off measurements previously published in the project wiki. They are kept for the record and are not re-measured; for current numbers use the live dashboards above.

optcarrot (April 2024)

Measured with optcarrot.

Rubies:

• ruby 3.4.0dev (2024-04-27T08:56:20Z master 9ea77cb351) [x86_64-linux]
• truffleruby 24.0.1, like ruby 3.2.2, Oracle GraalVM JVM [x86_64-linux]
• truffleruby 24.0.1, like ruby 3.2.2, Oracle GraalVM Native [x86_64-linux]
• monoruby 3e348afd4141c40978342e67ad26d42dc0b8d2a7

fps history, 0–3000 frames:

With --opt (optcarrot’s self-rewriting optimization mode):

yjit-bench (December 2024)

Speed ratio against truffleruby; higher is better. Measured with yjit-bench using --rss --harness=harness-warmup. Benchmark sources are from ruby/ruby’s benchmark/ and plb2.

Rubies:

• monoruby 0.3.0
• ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +YJIT +PRISM [x86_64-linux]
• truffleruby 24.1.1, like ruby 3.2.4, Oracle GraalVM Native [x86_64-linux]

Raw data — execution time in milliseconds, resident set size (RSS) in MiB. monoruby/yjit and monoruby/truffle are time ratios; above 1 means monoruby is faster.

Machine

Both historical runs used the same machine:

• Architecture: x86_64
• CPU(s): 32 — 13th Gen Intel(R) Core(TM) i9-13900HX, 16 cores / 2 threads per core
• Caches (sum of all): L1d 768 KiB (16), L1i 512 KiB (16), L2 32 MiB (16), L3 36 MiB (1)

Compatibility

monoruby aims at CRuby 4.0 compatibility, and measures it against ruby/spec — the executable specification suite CRuby itself is tested with. The suite is re-run on every push to master that touches the interpreter, and the results are published as live dashboards.

Dashboards

Each dashboard carries a per-category table, a history chart, and the raw latest.json / data/history.csv behind it. The core dashboard also publishes per-branch pages for branches under active spec work.

Where things stand

As of commit a13bfe0 (2026-08-31):

Additionally, as of July 2026 monoruby passed 100% of the command-line specs and 99.6% of the language specs.

The core figure is the result of a sustained compliance push through 2026 — the first published measurement, on 2026-04-27, was 59.5%:

The largest core categories are in good shape — array 100% over 2898 examples, file 99.6%, kernel 99.5%, module 98.9%, io 96.2%, and string 95.4% over 3905. What remains is concentrated rather than spread out: tracepoint (TracePoint is deliberately not implemented — the JIT’s speculation assumes its absence, see Invariants compiled code speculates on), objectspace at 39.3%, then time, marshal and encoding in the 89–95% band.

The library group is the frontier. matrix and net-http are essentially complete (100% and 99.5%), while the biggest gaps are socket (40.2% over 1129 examples), stringio (67.5%), net-ftp (54.9%) and bigdecimal (68.6%). Libraries needing facilities monoruby does not have — openssl, coverage, mkmf, irb — sit at 0%.

How the numbers are produced

Both dashboards come from the same workflow shape (.github/workflows/spec-core.yml and spec-library.yml):

• Every *_spec.rb under the group is run through mspec, category by category, in batches of 10 files.
• Each batch runs under a hard 60-second deadline with timeout -k 5. The -k matters: monoruby installs its own SIGTERM handler which is deferred to a VM poll point, so a process stuck in a blocking read never dies to a plain TERM.
• A killed batch prints no summary line, which would lose the tally for all ten files, so the batch is re-run one file at a time — completing files are counted after all, and the hanging file is pinned down and recorded in data/timeouts.csv. Both groups currently record zero timeouts.
• --excl-tag fails excludes examples tagged in this repository’s spec/tags/. That list is deliberately tiny — 6 examples in 4 files at present, covering Refinement#import_methods from a C extension, $LOAD_PATH.resolve_feature_path for a .so, the /o Regexp modifier, and three refinement-driven pattern-matching cases. The published pass rate is therefore very close to an unfiltered one.

The audit that cut the skip list down from coarse file-level exclusions to that handful is written up in ruby/spec hang countermeasures. Green threads removed the last structural hangs: blocking IO now parks the calling thread on the scheduler’s fd poller instead of blocking the process, so specs like core/io/copy_stream_spec.rb and core/io/select_spec.rb run to completion.

Running the specs yourself

ruby/spec and mspec are cloned alongside the monoruby checkout, not inside it. See Development and Build Options → ruby/spec for the layout and the commands.

Deliberate differences from CRuby

A few behaviours differ by design rather than by omission:

• TracePoint is not implemented. Compiled code speculates on its absence.
• Backtraces are formatted lazily. Raise, unwind and catch record what is needed; the backtrace string is not built until something asks for it. See Exception handling.
• The garbage collector is non-moving, single-threaded and stop-the-world (generational since June 2026). Compiled code relies on objects not moving.
• Threads are M:1 green threads with time-slice preemption, not OS threads. See Thread / Fiber / non-blocking IO / preemption.
• C extensions cannot be loaded. Libraries that CRuby backs with a C extension — json, date, digest, stringio, zlib, openssl and others — are either reimplemented in Rust/Ruby and shipped in the vendored tree, or unavailable. C extension support is a design study, not a shipped feature.

Changelog

Monthly highlights of monoruby’s development, with representative PRs. The README carries the most recent two months; this page is the full record.

For a prose account of the same period rather than a list — what changed and why, over roughly 500 commits — see Progress summary (April 2025 – April 2026).

Maintenance. This page is the single source of truth. A scheduled Routine appends the previous month on the 1st of each month, then runs bin/sync-changelog-readme, which copies the two newest month sections verbatim into the README between its LATEST-MONTHS markers. The README’s month text is generated — edit this page instead, and re-run the script (bin/sync-changelog-readme --check verifies the two are in sync).

2026

August 2026

• Broad early-month ruby/spec compliance drive across Kernel, Enumerator, IO and process handling: Enumerator::Lazy / Product / Chain, fiber-free #each/#with_index internals, ARGF reimplemented in Rust, Refinements, and a full spawn-exec engine with real Data subclasses (#1039–#1065, notably #1046, #1054, #1064).
• Signal delivery moved onto gated safepoint polls, and the safepoint word was reworked into one process-global, four-byte-lane poll; gc-stress then went opt-in and ran at every safepoint on both arches, catching a string of unrooted-Value and FP-pool bugs (#1070–#1075, #1123–#1125).
• Hash subsystem overhaul: an AR-mode small-hash table embedded directly in the RValue cell, JIT-inlined accessors ([]=, size, default, …), and correctness fixes for tombstone deletes and iteration order (#1060, #1086–#1108).
• JIT dispatch modernization: polymorphic call and comparison sites now dispatch through the PIC instead of guarding and evicting, with BinOp/BinCmp lowering unified into one skeleton (#1110, #1127–#1133).
• Chain deopt became the sole recovery path off a stale JIT frame, followed by a multi-week abstract-state and frame-chain rework (unified joins, outer-frame float promotion across block calls) that got the ActiveRecord benchmark running both correctly and fast (#1134, #1136, #1149–#1168, #1171–#1198).
• aarch64 kept pace with the chain-deopt work: outlined side-exit islands, branch-range relaxation past the Imm19 reach, and ports of the class-version recovery jump-back (#1153, #1175, #1176, #1182, #1183, #1189).
• Late-month perf sprint: cached Symbol#to_proc procs, dispatch-free Array/Range scans and equality-by-identity fast paths, plus a JIT correctness fix for inlined send and method_missing dispatch (#1200–#1214).
• Consolidated the README and wiki into the mdBook documentation site and added this generated Changelog chapter (#1215, #1216).

July 2026

• Big language-semantics compliance drive on the ruby/spec “language” group: destructuring, block-argument semantics, defined?, flip-flops, BEGIN/END, and predefined globals (#804–#874, notably #861).
• Implemented pattern matching (case/in, =>) (#883) and MRI’s full eigenclass tower (#877).
• Green threads (M:1): scheduler core, real Thread / Mutex / Queue, scheduler-integrated blocking IO, and preemptive timeslice multithreading (#941–#944, #962).
• Real TCP / UDP / UNIX-domain sockets (#964, #981); IO::Buffer with mmap file mapping (#927, #931); IO.copy_stream (#924).
• Added the setup-monoruby GitHub Action with prebuilt binaries (#884, #886) and CRuby-compatible command-line option processing (#891).
• Completed the Exception API: raise-time backtraces, full_message, NameError / NoMethodError metadata (#893–#896).
• Brought the aarch64 JIT to optimization parity with x86-64 (#993–#1004) and shrank call frames for ~7% faster fib (#850).
• Completed Fiber — transfer / raise / kill / storage and a real root fiber, making core/fiber fully green (#1036) — and refined Thread semantics: the async Thread#raise protocol and structured Thread::Backtrace::Location (#1026, #1027).
• JIT: object allocation emitted as inline machine code (free-list pop + bump) (#1011), guard-free slot dispatch for method calls on aarch64 (#1010), and trivial-method folding through ... forwards (#1012).
• Encoding: streaming Encoding::Converter state and String#encode fallback / newline decorators (#1018, #1019); Regexp gained native-encoding byte matching for non-UTF-8 subjects plus upstream Onigmo engine fixes (#1037, #1038).
• CRuby-compatible require / load / autoload resolution rules (#1033), a Rust fnmatch engine backing Dir.glob (#1017), and an mdBook documentation site published to the project portal (#1008).

June 2026

• Completed the aarch64 JIT backend: full AsmInst coverage, inline methods, loop JIT, and recompilation on Apple Silicon (#645–#704).
• Introduced a generational GC (RGenGC-style) (#705); GC now also triggers on malloc growth (#732).
• Completed the Prism migration and removed the old hand-written parser (ruruby-parse) (#657).
• New JIT register allocation: LIR-based lowering with a per-basic-block GP register allocator; retired the R15 accumulator (#741, #756, #763).
• Cut allocation/dispatch overhead by 12–26% on addressable benchmarks (#708); zero-copy String operations (gsub, slice, lines, scan) (#722–#724).
• Made the build host-Ruby independent and reproducible (#769).

May 2026

• Switched the parser to Prism, the official Ruby parser (#412).
• Encoding subsystem overhaul: real String#encode (#443), Encoding::Converter (#447, #451), ISO-2022-JP (#449), and EUC-JP / Shift_JIS-aware string operations (#536–#545).
• Native String fast paths (reverse, rindex, case mapping, …) that beat YJIT (#493–#497); dropped per-builtin catch_unwind for +8–10% on optcarrot (#501).
• JIT: virtual FP registers with spill-to-stack (#387), heap-constant folding and Object#is_a? inlining (#504, #505), non-deopting polymorphic comparisons (#519).
• Decoupled monoruby from any host Ruby installation (#579, #595); completed the Marshal format tags (#588–#603); real File::Stat (#607); frame-local $~ / $_ (#608).
• Started the aarch64 port: VM-tier backend and macOS (Apple Silicon) support (#640, #641, #644).
• Continuous yjit-bench benchmarking against YJIT, charted on GitHub Pages (#411, #416).

April 2026

• Reimplemented Rational as a first-class Rust type with literal support (#266).
• Broad ruby/spec compliance work on Integer / Float / Array / Symbol / Class / Module (e.g. #281, #284, #309), with a live spec dashboard published on GitHub Pages (#364, #365).
• Moved shift / bitwise / ** / % into the inline-function JIT pipeline with constant folding (#307, #308), and added frame-free trivial-method optimization via ISeqHint (#290).
• Struct: per-instance slot storage with JIT-inlined member accessors (#367–#369).
• String: encoding-aware data model — code ranges, Encoding::CompatibilityError, encoding-aware char iteration (#382–#384).
• Reworked autoload as a proper state machine (#376) and added lazy heap promotion for Proc / Lambda / Binding captures (#332).

March 2026

• Implemented Marshal.dump / Marshal.load (#121, #125) and the Set class, a CRuby 4.0 built-in (#130).
• Implemented the retry statement (#109), module/class lifecycle hooks (#127), anonymous block forwarding (#128), and regex backreferences / special variables (#129).
• Added Kernel.#load (#105), correct Dir.glob (#106), Kernel.#format / sprintf (#162), and a SQLite3 FFI bridge for the sqlite3 gem (#160).
• Started a large ruby/spec compatibility push: implicit type conversions (#225), frozen-object support (#240), Errno exceptions (#250), and many crash fixes on invalid UTF-8 input (#209–#212).
• Fixed many issues to run optcarrot (#115) and the rubyboy / lee benchmarks (#111, #120).

February 2026

• Optimized rest / keyword-rest parameters in the JIT (#96).
• Corrected / and % semantics for Integer and Float (#97) and fixed Integer#digits (#99).
• Optimized the Range class (#98) and fixed Range#include? for string / beginless / endless ranges (#104).
• Introduced continuation frames (#101) and reworked JIT slot write-back logic (#102).

January 2026

• Hardened JIT frame handling so local frames are never captured by JIT-compiled code (#93).
• Added SAFETY comments to unsafe blocks across the codebase (#94).
• Introduced immediate operands (BytecodeInst::Immediate) into the bytecode (#95).

Architecture Overview

monoruby is a Ruby implementation written from scratch in Rust, featuring a register-based bytecode VM and a just-in-time (JIT) compiler. It has no dependency on CRuby or any other Ruby runtime. This page gives a bird’s-eye view of the system; each section links to a dedicated chapter and to the detailed design documents (rendered in the “Design Documents” section of this book, sourced from the repository’s doc/ directory).

Compilation pipeline

Ruby source
    │
    ▼
prism (ruby-prism)      prism syntax tree — the official Ruby parser
    │
    ▼
parser/ + ast/          monoruby AST
    │
    ▼
bytecodegen/            register-based bytecode
    │
    ▼
Executor (VM)           interpreted execution, machine-code VM tier
    │  when hot (≥20 calls / ≥100 loop iterations)
    ▼
JIT: TraceIR            type-annotated IR built from inline-cache feedback
    │
    ▼
JIT: AsmIR              register-allocated, arch-neutral assembly IR
    │
    ▼
codegen/arch/<arch>     AsmIR → machine code (x86-64 / aarch64 backends)
    │
    ▼
monoasm                 self-made dynamic assembler
    │
    ▼
Native machine code

Ruby source is parsed by prism (consumed as the ruby-prism crate) and converted into monoruby’s own AST. The AST is compiled into register-based bytecode, which the VM executes. Hot methods (≥ 20 calls) and hot loops (≥ 100 iterations) are handed to the JIT, which uses runtime type feedback to produce specialized machine code, falling back to the VM through deoptimization when its assumptions are invalidated. See JIT Compiler for details.

Execution tiers

• VM tier — the bytecode executor. Its dispatch loop and operation handlers are themselves emitted as machine code through monoasm (per target architecture), rather than being a Rust match loop.
• JIT tier — specialized machine code per method / loop, guarded by type and class-version checks. Both x86-64 and aarch64 lower the full instruction set; see aarch64 Backend.

Major subsystems

Source layout

monoruby/                   workspace root
├── monoruby/src/
│   ├── parser/, ast/       prism → monoruby-AST bridge, AST definitions
│   ├── bytecodegen/        AST → register-based bytecode
│   ├── executor/           bytecode interpreter (VM), frames, operator dispatch
│   ├── codegen/            JIT compiler
│   │   ├── jitgen/         bytecode → TraceIR → AsmIR (arch-neutral front-end)
│   │   └── arch/           per-arch backends: x86_64/ and aarch64/
│   ├── value.rs, value/    Value type and heap objects (RValue)
│   ├── alloc.rs            garbage collector
│   ├── globals/            global interpreter state, function/class tables
│   └── builtins/           built-in Ruby classes implemented in Rust
├── monoruby/builtins/      built-in library code written in Ruby
├── monoruby_attr/          proc macros (#[monoruby_builtin], …)
├── rubymap/, hashbrown/    order-preserving hash map for Ruby Hash
└── doc/                    detailed design documents

Key global registers (JIT / VM tier)

On x86-64, JIT-compiled code keeps interpreter state in fixed registers (the aarch64 backend uses an equivalent fixed assignment):

Further reading

• Build and Install — how to build and run monoruby
• Build options for performance tuning — bytecode / TraceIR / assembly dumps
• doc/ directory — the full set of design documents, including C-extension design notes, encoding design, and progress notes

Value Representation

A monoruby Value is a 64-bit non-zero integer (NonZeroU64) using a tagged-union scheme: the lower 3 bits encode the kind of value. It is not NaN-boxing. Because Value is always a single machine word, values can live directly in VM registers, JIT machine registers, and GC-scanned stack slots.

Dispatch on the lower 3 bits

is_packed_value() tests bits & 0b0111 != 0; if true, the value is an immediate and try_rvalue() returns None. If false, the bits are a valid *const RValue pointer (RValues are 8-byte aligned, so their low 3 bits are always zero).

Immediate tag constants

FLOAT_ZERO ((0b1000 << 60) | 0b10) is the flonum encoding of 0.0.

Consequences

• Fixnum covers 63-bit signed integers. Integer results that overflow i63 are promoted to heap-allocated Bignum objects (backed by BigInt).
• Flonum covers most doubles; floats whose exponent falls outside the encodable range are heap-allocated as RValues of class Float.
• nil / false are the only falsy values, and both have bit patterns distinguishable with a single mask — which the JIT exploits for cheap truthiness tests.
• Equality on immediates (Fixnum, Symbol, nil, true, false) is plain 64-bit comparison.

Heap values: RValue

Everything that is not an immediate lives on the GC heap as an RValue (defined under monoruby/src/value/rvalue/): Strings, Arrays, Hashes, objects with instance variables, Bignums, non-flonum Floats, Ranges, Procs, Fibers, and so on. RValues are allocated from the GC’s page-based arena and carry the object’s class, flags (including the generational-GC age bits), and kind-specific payload. See Garbage Collection.

Relevant source

• monoruby/src/value.rs — the Value type and tag scheme
• monoruby/src/value/numeric.rs — Fixnum / Flonum / BigInt helpers
• monoruby/src/value/rvalue/ — heap object representation

JIT Compiler

monoruby executes bytecode in the VM until code gets hot, then compiles it to specialized machine code. This page is an overview; the detailed documents are doc/jit.md (stub/bridge code), doc/lir.md (the low-level IR), doc/regalloc_separation.md (register allocation), and doc/inline.md (inline builtins).

When compilation triggers

• Method JIT — after ≥ 20 calls (COUNT_START_COMPILE; 5 in test mode)
• Loop JIT — after ≥ 100 iterations of a loop (COUNT_LOOP_START_COMPILE; 15 in test mode), compiling the enclosing method from the loop entry

Each function starts with a small wrapper that decrements a counter and falls through to the VM until the counter expires, then triggers compilation and patches itself.

IR pipeline

bytecode ──abstract interpretation──▶ TraceIR ──▶ AsmIR ──▶ LIR ──▶ machine code (monoasm)
                (type feedback from inline caches)        (per-arch encoder)

• TraceIR — bytecode annotated with type information gathered from the VM tier’s inline caches.
• AsmIR (AsmInst) — arch-neutral, register-allocated assembly IR produced by an abstract interpreter that tracks, per slot, whether a value lives on the stack, in a floating-point register (unboxed f64), both, or is a compile-time constant (LinkMode).
• LIR (LInst) — arch-neutral machine-level ops with offsets and labels resolved; the single seam where bytes are emitted. Each architecture implements one encode_linst (see aarch64 Backend).

Specialization and inline caches

Compiled code is specialized per receiver class. The method entry is a chain of self-class guard stubs: each guard tests the receiver’s class and jumps to the machine code compiled for that class; a miss falls through to the next guard or to the VM. Method calls inside JIT code are resolved through inline caches and guarded by a class-version check, so redefining a method invalidates dependent code. Small hot builtins (Array#[], Integer arithmetic, Math.sqrt, Object#is_a?, Struct accessors, Class#new, Fiber.yield, …) are inlined directly by generator functions that can both consult the abstract state (folding results at compile time when types are proven) and emit code; a failed inline attempt rolls back cleanly and falls back to a normal call. Monomorphic methods can additionally be specialized inline — the callee’s frame is inlined into the caller.

Deoptimization and recompilation

JIT code is speculative. Guards — receiver class, class version, array type, frozen state, fixnum overflow, basic-operator (BOP) redefinition, frame capture — branch to side exits that write register-resident values back to the frame and resume in the VM at the equivalent program point. Repeated deopts trigger recompilation with the newly observed classes (e.g. polymorphic call sites, method_missing dispatch, newly resolved constants/ivars). Deopt logging is available with the deopt Cargo feature, recompile/deopt statistics with profile.

Register allocation

• Floating point — virtual FP registers (VirtFPReg) allocated greedily over the physical pool (14 xmm registers on x86-64), with automatic spill-to-stack when the pool is exhausted; loop entries specialize float-typed slots so hot numeric loops keep values unboxed in registers.
• General purpose — a per-basic-block local GP register allocator keeps boxed values (notably Fixnums) in a small pool of scratch registers within a block, eliding redundant fixnum guards, and flushes the pool at calls and GC safepoints (pool registers are not GC roots).

The long-form design discussion — separating type inference from placement, the retirement of the dedicated accumulator register, and measured results — is in doc/regalloc_separation.md and doc/lir.md.

Argument forwarding (D1)

def f(...) forwarding is compiled as an opaque pipe: for simple callees the rest-Array / keyword-Hash allocation is elided entirely and arguments are copied (or lazily deferred) straight from the caller’s frame, with deopt-safe lazy materialization if a side exit or frame capture ever needs the real objects. See doc/arg_forwarding_jit.md.

Observing the JIT

The JIT is always built in; disable it at runtime with --no-jit. See Build options for performance tuning for example output.

Garbage Collection

monoruby has its own garbage collector: a non-moving, single-threaded, stop-the-world, generational mark-and-sweep collector, modeled on CRuby’s RGenGC. This page is an overview; the full design document is doc/gc.md, and the implementation lives in monoruby/src/alloc.rs.

Heap layout

• All heap objects (RValue) are exactly 64 bytes. Memory comes from a single 2 GB virtual arena reserved up front, carved into 256 KB pages of 4032 cells each.
• Mark bits and old bits are stored outside the object cells, as per-page bitmaps. A pointer’s page is found with a single address mask, so bitmap lookup is O(1).
• Objects never move, so raw *const RValue pointers stay valid across collections.
• Allocation pops from a free list when possible, otherwise bump-allocates in the current page. The JIT inlines this free-list fast path directly into compiled code.

Generational collection

Minor collections trace only young objects; old objects are assumed live and their mark bits are seeded from the old bitmap.

• Objects of promotable types (Object, String, Array, Hash, Bignum, Float, Struct) age by one on each minor GC they survive; at age 3 they are promoted to the old generation.
• Write barrier: when a reference is stored into an old object, a single header-bit test decides whether the object must enter the remembered set, whose old→young edges are traced during minor GCs. The JIT emits the barrier inline; bulk operations (Array#concat, …) use a bulk variant.
• A major (full) collection runs when the old-object count crosses an adaptive threshold or after 64 consecutive minors; it clears all generation state and retraces everything. GC.start always forces a major.

The write-barrier / remembered-set interaction (including why a minor GC without the barrier would sweep live objects) is illustrated in doc/gc_write_barrier.svg.

GC triggers and safepoints

Collections are requested by setting a single per-thread alloc_flag, and performed only at safepoints:

• Allocation pressure — every ~8 filled pages trips the flag.
• malloc pressure — a custom #[global_allocator] tracks off-heap allocation (String/Array backing stores etc.) and requests a GC when it outgrows an adaptive threshold, so heavy malloc traffic can’t outrun the heap-cell trigger.
• Explicit — GC.start.

Safepoint polls (compare alloc_flag; conditionally call gc) are emitted at callee entry and loop back-edges in both the VM tier and JIT code. The same poll also drives green-thread preemption and pending-signal delivery (see Threads and Fibers). Rooting is precise: roots are explicitly enumerated — the executor’s frame chain, temporary-value stack, the green-thread scheduler’s thread registry, pending exceptions, and global state — never conservatively scanned off the machine stack; JIT code spills live registers before a safepoint call.

Controlling the GC

Debugging Cargo features: gc-log (stats at exit), gc-debug (assertions), gc-stress (force a collection at every safepoint, unconditionally — used by bin/test’s nextest phase on x86-64 CI), gc-verify (independent re-mark verification after each minor GC).

Further reading

• doc/gc.md — full design document (heap layout, bitmaps, aging/promotion, remembered-set self-cleaning, heap-escaped frame reclamation)
• doc/safepoint.md — the safepoint / poll-flag mechanism shared by GC, preemption, and signals

Threads and Fibers

monoruby implements M:1 green threads: all Ruby Threads are multiplexed onto a single OS thread that runs the VM. There is no parallel Ruby execution (and no GVL — there is simply one VM-running OS thread); short-lived helper OS threads exist only for blocking-syscall offload and the preemption timer, and they never touch the Ruby heap. This page is an overview; the full design document is doc/threads.md.

Scheduler

The scheduler (monoruby/src/scheduler.rs) is a per-OS-thread singleton. Its event loop runs on the main thread’s stack: main enters it as an ordinary function call when it parks, and returns from it when main becomes runnable again; green threads never call the loop themselves — they switch into its saved context. The scheduler tracks live threads (a GC root), a FIFO run queue, sleepers with deadlines, and fd waiters. When idle it poll(2)s the waited fds or sleeps to the nearest deadline; if no thread can ever run again it raises a fatal deadlock error.

Context switching reuses the Fiber stack-switching machinery (rsp exchange): each thread gets its own 256 KiB stack with a guard page and its own Executor.

Cooperative and preemptive switching

Switching is hybrid:

• Cooperative — at blocking points: sleep, Thread.stop, #join, Thread.pass, blocking IO, and synchronization-primitive waits.
• Preemptive — a dedicated timer OS thread ticks every 10 ms (spawned only while ≥ 2 threads are live) and arms the shared poll flag, which acts as if the running thread called Thread.pass at its next safepoint. MONORUBY_NO_PREEMPT=1 disables it; MONORUBY_PREEMPT_STRESS=1 switches at every poll site.

Both kinds of switch happen only at VM safepoints — the same callee-entry / loop-back-edge polls used by the GC (see Garbage Collection and doc/safepoint.md) — so a suspended thread’s frames are always in a GC-complete state. A consequence: Rust builtins are atomic with respect to other threads (like C functions under CRuby’s GVL), but sequences of pure-Ruby statements can interleave, so Ruby code must use locks for compound state transitions.

Blocking IO

Blocking-IO builtins go through a common wrapper that checks buffered data, probes readiness with a zero-timeout poll, and otherwise parks the thread on the scheduler’s fd poller instead of blocking the process. While other threads are live, fds are temporarily set to non-blocking so that a mid-operation would-block parks and resumes without data loss. IO.select, non-blocking TCP connect, and accept retry-loops are integrated with the same poller. The only truly blocking syscalls (flock, FIFO open) are offloaded to short-lived native helper threads that signal completion through a self-pipe registered with the poller.

Synchronization primitives and interrupts

Mutex, Queue, SizedQueue, and ConditionVariable are implemented in Ruby (in builtins/startup.rb), relying on safepoint-free straight-line test-and-set plus a park permit mechanism that closes the classic lost-wakeup race. Locks abandoned by a dead thread are reclaimed by the next acquirer, and Mutex#owned? is per-Fiber.

Thread#kill / #raise are queued and delivered by the scheduler: a parked target is woken and unwinds from its exact blocking point (running ensure blocks); a running target is caught by preemption at its next safepoint, so even busy loops are killable. Thread.handle_interrupt masking is honored at mask boundaries.

Fibers

Threads are built on Fiber’s stack switching, but the two remain distinct: Fibers form an asymmetric resume/yield chain within a thread, while the scheduler schedules threads only. A green thread may park while deep inside a nested Fiber and be resumed exactly there. Signal handling uses the same deferred safepoint model — see doc/signal.md.

State diagrams

Further reading

• doc/threads.md — full design document (scheduler internals, preemption, IO parking, sync primitives, kill/raise delivery)
• doc/scheduler_state_diagram.md — the state diagrams with commentary
• doc/safepoint.md — the unified GC / preemption / signal poll mechanism
• doc/signal.md — async-signal-safe handlers and deferred delivery

Stack Frames and Method Calls

This page describes how monoruby lays out call frames and processes method arguments. Details: doc/stack_frame.md, doc/method_args.md, doc/cref.md, doc/super_resolution.md.

Frame layout

Each Ruby-level call pushes three contiguous regions on the native stack (growing downward):

• Continuation frame — the saved rbp, the return address, the caller’s suspended pc, and a pad word. The saved call-site pc is what powers lazy backtraces, Kernel#caller, and super resolution; the pad is unread on the normal return path and is reused by chain deopt as the converted call’s continuation word.
• Control frame (CFP) — prev cfp and lfp; the executor’s cfp chain links all active frames. Every frame establishes bp == cfp + 8 in its prologue, so the machine frame pointer is recoverable from the CFP alone.
• Local frame (LFP) — the Ruby-visible part, addressed at negative offsets from lfp: outer (for blocks, the enclosing frame), meta (a packed word of FuncId, reg_num, arg mode and flags), svar (frame-local $~ / $_, lazily allocated), block, self, then the argument/local slots arg0, arg1, …. self is register slot %0, so a method’s first parameter is %1.

The bytecode interpreter and JIT code share a fixed register ABI on x86-64 (the aarch64 backend uses an equivalent assignment): rbx = &mut Executor, r12 = &mut Globals, r13 = pc, r14 = lfp, r15 = accumulator. The accumulator is a VM-tier register — JIT’ed code keeps no fixed accumulator and allocates general-purpose registers per basic block instead.

Frames captured by blocks, Procs, or Bindings are promoted to the heap lazily — only when the capture actually escapes — and heap frames are reclaimed by the GC once unreachable.

Argument processing

Formal parameters occupy frame slots in a fixed order: required | optional | rest | keyword | block | destructured-children. At call time the caller copies positional arguments into the callee frame, expanding splats, gathering overflow into rest, filling missing slots with nil/none-markers, and checking arity. Keyword arguments are then assigned by name, with surplus keywords gathered into the keyword-rest slot; if the callee accepts no keywords at all, trailing keywords are packed into a Hash and passed as one extra positional argument. Blocks additionally auto-splat a single Array argument when they take multiple parameters. The callee prologue (InitMethod) then links the frame, homes arguments, nil-fills the remaining slots — and runs the safepoint poll. Destructuring and optional-parameter default initializers are compiled as ordinary bytecode at the top of the method body.

Built-in (native) methods declare their arity and keyword names at registration time (e.g. define_builtin_func_with_kw(..., min, max, rest, kw)), and receive their arguments in the same fixed slot order via Lfp. The #[monoruby_builtin] proc macro wraps a Rust fn(vm, globals, lfp) -> Result<Value> into the VM’s calling convention, converting errors into the VM’s error protocol (vm.set_error).

Lexical scope (CREF)

Where def, constant lookup, and visibility land is decided by monoruby’s CREF model — a compact 16-byte Cref struct kept on a VM-wide stack, distinguishing the definition context (used by def) from the lexical context (used by module/class nesting and unqualified constants). This is monoruby’s counterpart to CRuby’s per-frame rb_cref_t chain; doc/cref.md contrasts the two models in depth, including how class_eval / instance_eval / Kernel#eval push their scopes.

super resolution

CRuby frames carry a callable-method-entry that tells super both the method name to search and where in the ancestor chain to continue. monoruby frames carry only a FuncId, so super reconstructs that information from the caller pc saved in the continuation frame: it recovers the call site’s opcode and call-site info, derives the originally-called name (correct across alias and multi-name define_method), and counts how many times the running body occurs in the ancestor chain so a method aliased into several places supers past the right occurrence. See doc/super_resolution.md.

Further reading

• doc/stack_frame.md — exact slot offsets, pre-call vs post-prologue layouts
• doc/method_args.md — caller/callee argument-processing responsibilities
• doc/native_func.md — builtin registration and argument slots

Exception Handling

monoruby’s exception machinery is built around laziness: at raise time it stores the minimum needed to unwind, and defers every expensive step — building the Ruby exception object, walking callers, formatting strings — until (and unless) something actually asks for it. This page is an overview; the full design document, including a detailed contrast with CRuby, is doc/exception_handling.md.

In-flight errors

While an exception is propagating it is not a Ruby object but a Rust struct, MonorubyErr, stored in the executor. Its kind covers both real exceptions (TypeError, NameError, ArgumentError, …, plus Other(ClassId) for user classes) and control-flow pseudo-exceptions: MethodReturn (non-local return), BlockBreak, Throw (Kernel#throw), Retry, and Redo. Both families share one unwinder, mirroring how CRuby routes break/return through its THROW_DATA tags.

Unwinding

The unwinder runs once per frame. For each interpreted frame it:

1. Dispatches control-flow kinds first — return/break/throw/retry/redo are resolved before any backtrace capture, so non-local control flow never pays for a backtrace or allocates an exception object.
2. Records the frame’s source location into the incremental trace (frames are being destroyed, so this is the only chance).
3. Consults the function’s exception table for the innermost region covering the current pc, yielding a rescue target, an ensure target, and the slot for the error value. Rescue jumps materialize the exception object and set $!; ensure jumps defer the in-flight unwind, resuming it when the ensure body finishes (a new exception raised inside ensure supersedes the deferred one).
4. Otherwise returns the error to the caller frame and repeats.

$! is scoped per rescue region: its previous value is saved on region entry and restored on exit, so nested and non-local exits observe CRuby’s semantics.

Lazy backtraces

Backtrace cost is split into three deferred stages: frames between raise and rescue are captured incrementally during unwinding; frames above the rescuer are filled in only at the catch point (the last moment the stack is coherent), by walking each caller’s saved call-site pc — the same mechanism behind Kernel#caller; and formatting into strings happens only when Exception#backtrace is first called, then is memoized. CRuby, by contrast, captures the full backtrace eagerly at raise time. The practical result: rescue-based control flow in hot code is far cheaper than in CRuby, and StopIteration under Kernel#loop is caught at the Rust level with near-zero cost.

Exception objects

The Ruby exception object is created only at a catch point or at top level. Re-raising an exception object preserves its identity; implicit cause chaining from $! and the explicit raise ..., cause: keyword follow CRuby’s rules. Class-specific payloads (LoadError#path, SystemExit#status, NoMethodError#name/#receiver, …) ride along as hidden instance variables.

Native builtins participate through a simple protocol: a builtin returns a Result<Value>, and on error the #[monoruby_builtin] wrapper stores the MonorubyErr in the executor and returns a sentinel that routes into the same unwinder.

Further reading

• doc/exception_handling.md — full mechanism, exception-table format, $! restoration, ensure deferral, and the CRuby (catch_table / THROW_DATA) comparison

aarch64 Backend

monoruby runs natively on aarch64 — macOS on Apple Silicon is fully supported (VM tier + JIT), and CI runs on GitHub’s Apple Silicon runners. The aarch64 backend was ported in mid-2026 and lowers the complete instruction set: it never declines a compilation. This page is an overview; the detailed comparison is doc/arch_difference.md.

How the backends are organized

codegen/jitgen/                 arch-neutral front-end: bytecode → TraceIR → AsmIR
codegen/jitgen/asmir/           arch-neutral lowering dispatcher (compile_asmir → LIR)
codegen/arch/x86_64/            x86-64 backend: VM tier, invokers, wrappers, encode_linst
codegen/arch/aarch64/           aarch64 backend: same structure, mirrored file layout

Everything above machine-code emission is shared. The arch-neutral dispatcher lowers each AsmInst either through common code paths built on small per-arch emission primitives (emit_reg_move, emit_guard_class, emit_integer_binop, …) or into arch-neutral LIR, which each architecture encodes with its own encode_linst (selected by cfg(target_arch), no dynamic dispatch). Machine code is emitted with the monoasm dynamic assembler, which provides both monoasm! (x86-64) and monoasm_arm64! DSLs.

Full coverage — no bail

Historically the aarch64 port could “bail” (fall back to the VM) on instructions it didn’t yet support — almost always because an offset didn’t fit AArch64’s 12-bit immediate encodings. Today every AsmInst and every side exit is lowered: displacements that fit are folded into ldur/stur/scaled ldr/str, and larger frame/field/sp offsets are materialized through reserved scratch registers (x9/x10). The bool “decline” return still present in some lowering signatures is vestigial.

Register mapping

The C-call ABIs differ (arguments in rdi/rsi/rdx/… vs x0..x7), so call-argument lowering shuffles into the ABI registers explicitly rather than using a 1:1 map.

Remaining differences

Correctness and instruction coverage are identical across the two backends; the few remaining asymmetries only affect transition costs around recompilation (e.g. how a class-version guard miss recovers: x86-64 patches and recompiles in place in some paths where aarch64 deopts and re-JITs via warm-up counters). These are catalogued, with rationale, in doc/arch_difference.md.

Building and testing on aarch64

• On Apple Silicon macOS, a normal cargo build produces a native binary (Homebrew libffi + pkg-config are required — see the target-specific dependency block in monoruby/Cargo.toml).
• From an x86-64 Linux host, bin/setup-aarch64-cross sets up a cross toolchain and bin/test-aarch64 runs the test suite under emulation.
• CI runs the full test scope natively on macos-latest (Apple Silicon) for every push and pull request.

Stub code for JIT’ed code generated by compiler

The exit / vm_entry arrow leaving each class_guard below is the megamorphic gate: a receiver class that misses the whole chain runs the call in the interpreter, and is compiled for only once the stub’s warm-up sampler has seen it twice. That arrow must therefore actually go somewhere — when its label was left unbound the branch became a no-op and every missing class got its own compiled body. Both that gate and what happens when a version guard (rather than a class guard) fails are described in jit_invalidation.md.

before compilation

      wrapper
   +---------------------------------+
   |                                 |
---+-> entry:                        |
   |       jmp [next];               |
   |   next:                         |
   |       subl [rip + counter], 1;  |
   |       jne vm_entry;             |
   |       <exec_compile_and_patch>  |
   |       jmp entry;                |
   |                                 |
   +---------------------------------+

after compilation for self_class1

      wrapper                                class guard stub (1)
   +---------------------------------+     +--------------------------------------------+
   |                                 |     |                                            |
---+-> entry:                        |  +--+-> guard1:                                  |
   |       jmp [guard1]; ------------+-/   |       movq rdi, [r14 - (LFP_SELF)];        |
   |   next:                         |     |       class_guard(self_class1)  -----------+-----> exit
   |       subl [rip + counter], 1;  |     |   patch_point:                             |
   |       jne vm_entry;             |     |       jmp [jit_entry1];                    |
   |       <exec_compile_and_patch>  |     |         |                                  |
   |       jmp entry;                |     +---------+----------------------------------+
   |                                 |               |
   +---------------------------------+               |
                                                     |      JIT code for self_class
                                                     |   +---------------------------+
                                                     |   |                           |
                                                     +---+-> jit_entry1              |
                                                         |                           |
                                                         |     <jit_code>            |
                                                         |                           |
                                                         |                           |
                                                         +---------------------------+

after re-compilation for self_class1

      wrapper                                class guard stub (1)
   +---------------------------------+     +--------------------------------------------+
   |                                 |     |                                            |
---+-> entry:                        |  +--+-> guard1:                                  |
   |       jmp [guard1]; ------------+-/   |       movq rdi, [r14 - (LFP_SELF)];        |
   |   next:                         |     |       class_guard(self_class1)  -----------+-----> exit
   |       subl [rip + counter], 1;  |     |   patch_point:                             |
   |       jne vm_entry;             |     |       jmp [jit_entry2];                    |
   |       <exec_compile_and_patch>  |     |         |                                  |
   |       jmp entry;                |     +---------+----------------------------------+
   |                                 |               |
   +---------------------------------+               |
                                                     |      JIT code for self_class1
                                                     |   +---------------------------+
                                                     |   | +---------------------------+
                                                     |   | |                           |
                                                     +---+-+-> jit_entry2              |
                                                         | |                           |
                                                         | |     <jit_code>            |
                                                         | |                           |
                                                         +-|                           |
                                                           +---------------------------+

after compilation for self_class2

      wrapper                                class guard stub (1)                               class guard stub (2)
   +---------------------------------+     +--------------------------------------------+     +--------------------------------------------+
   |                                 |     |                                            |     |                                            |
---+-> entry:                        |  +--+-> guard1:                                  |   +-+-> guard2:                                  |
   |       jmp [guard1]; ------------+-/   |       movq rdi, [r14 - (LFP_SELF)];        |  /  |       movq rdi, [r14 - (LFP_SELF)];        |
   |   next:                         |     |       class_guard(self_class1)  -----------+-+   |       class_guard(self_class2)  -----------+-----> vm_entry
   |       subl [rip + counter], 1;  |     |   patch_point:                             |     |   patch_point:                             |
   |       jne vm_entry;             |     |       jmp [jit_entry1];                    |     |       jmp [jit_entry2];                    |
   |       <exec_compile_and_patch>  |     |         |                                  |     |         |                                  |
   |       jmp entry;                |     +---------+----------------------------------+     +---------+----------------------------------+
   |                                 |               |                                                  |
   +---------------------------------+               |                                                  |
                                                     |      JIT code for self_class1                    |      JIT code for self_class2
                                                     |   +---------------------------+                  |   +---------------------------+
                                                     |   |                           |                  |   |                           |
                                                     +---+-> jit_entry1:             |                  +---+-> jit_entry2:             |
                                                         |                           |                      |                           |
                                                         |     <jit_code>            |                      |     <jit_code>            |
                                                         |                           |                      |                           |
                                                         |                           |                      |                           |
                                                         +---------------------------+                      +---------------------------+

Unified low-level IR (LIR)

Design notes and migration log for the arch-neutral, machine-level IR that sits between AsmIR and the per-arch monoasm! / monoasm_arm64! byte emission. This is Phase-1 item ① (“a low-level IR that describes amd64 and aarch64 uniformly”).

Status: the great majority of AsmInst families now lower through encode_linst. The model lives in monoruby/src/codegen/jitgen/lir.rs; the per-arch encoder is Codegen::encode_linst, defined once in each arch/<arch>/compile/… file. As of this writing the integer + control-flow core, all addressing modes, the GC write barrier, the common guard/check family, fixnum arithmetic (with overflow deopt), the whole floating-point family, the bounds-checked heap-ivar load/store, and the large runtime-call macro-op families (array/hash/string/range construction, defined?, generic binops, class/method definition, exceptions, yield, the method-prologue guards, …) are all lowered through encode_linst, as is the entire method-call family — argument setup and the call itself (the dispatcher pre-resolves the store/frame-dependent values and the encoder stays store-free) — and the cold deopt side-exit handler blocks. Even the AsmInst::Inline builtin escape hatch now lowers to a carrier LInst::Inline (dispatched via the context-carrying encode_linst_inline), so every AsmInst reaching the dispatcher lowers to LInst. What remains outside encode_linst is the specialized inlined-frame family and the zero-byte patch/recompile bookkeeping that is not byte emission — see §8.

1. Motivation

The original justification (“close the aarch64 bail gap”) is gone: the full aarch64 port (#704) made aarch64 lower every AsmInst (see doc/arch_difference.md). The remaining — and real — motivation is description unification:

• The AsmIR → machine-code step used to be two parallel sets of emit_* primitives (x86 arch/x86_64/compile/*.rs, aarch64 arch/aarch64/compile.rs). LIR makes encode_linst the single seam through which all migrated families emit code.
• LIR is also the concrete code-generation target the future interpreter/JIT DSL (Phase-1 item ③, “derive interpreter + JIT from one description”) lowers to. A hand-written, test-validated LIR gives ③ a well-defined target and a correctness oracle.

2. Where LIR sits

TraceIR
  → AsmIR (AsmInst, arch-neutral, register-allocated)
  → [compile_asmir dispatcher]                         jitgen/asmir/compile_shared.rs
  → LIR (LInst, arch-neutral machine ops)              jitgen/lir.rs            ← this layer
  → [per-arch Codegen::encode_linst]                   arch/<arch>/compile/…
  → monoasm! / monoasm_arm64!
  → bytes

AsmIR stays the register-allocated, arch-neutral front-end output (one AsmInst per semantic operation). The arch-neutral dispatcher compile_asmir (compile_shared.rs) lowers each migrated AsmInst into one or more LInsts and feeds them to encode_linst; not-yet-migrated families still call their per-arch emit_* directly from the dispatcher.

encode_linst is an inherent Codegen method, defined once per arch in the file that the compile module includes for the active target_arch. Because only one compiles per target, no trait/dynamic dispatch is needed — cfg selects the right encoder.

3. Data model

Defined in lir.rs. Branch and side-exit targets carry a resolved monoasm DestLabel (the encoder runs after label resolution), so LInst is #[derive(Debug, Clone)] — DestLabel is Clone but not Copy. PartialEq is intentionally not derived: several payload types reached by the macro-op variants (WriteBack, AsmEvict, FnInitInfo, …) are not PartialEq, and deriving it would force a PartialEq cascade across unrelated types for no benefit. The lir.rs unit test uses matches! instead of ==.

Operands

Instructions (LInst)

Lir is a thin Vec<LInst> builder used where a multi-instruction sequence is convenient.

The macro-op variants do not lower to primitives inside encode_linst; instead each backend’s encode_linst ends with other => self.encode_linst_macro(other), and the arch-neutral encode_linst_macro (compile_shared.rs) delegates each macro-op to the existing per-arch emit_* helper. This keeps the delegation in one place (rather than duplicating it in both backends) while still funnelling all emission through encode_linst. See §5.

The legalization contract (the core idea)

LMem displacements and LOperand::Imm values are unbounded; the per-arch encoder legalizes them:

• x86-64: [reg + disp32] / imm32 cover essentially everything — mostly a no-op.
• aarch64: fixed-width encodings allow only small immediates, so the encoder folds a fitting displacement into the instruction (ldur/stur ±256, scaled ldr/str, sub sp) and otherwise materializes the offset into reserved scratch x9/x10 (the a64_frame_* / a64_field_* / a64_rsp_slot_addr helpers).

4. The two model extensions (Stage 3)

Stages 2-A…2-J were byte-for-byte family ports that fit the data model as-is. Stage 3 extended the model so the harder families could be expressed:

1. Scratch register operand (LReg::Scratch). Lets the LIR express intermediate pointers that map to a different physical register per arch (x86 rdx, aarch64 x9). Without it, an abstract GP would either pick a register that aarch64 keeps allocatable (clobber hazard) or have no name for aarch64’s reserved scratch. First user: the self heap-ivar store (Load{Scratch ← [rdi+VAR]} ; Load{Scratch ← [Scratch+MONOVEC_PTR]} ; Store{[Scratch+idx*8] ← src} ; WriteBarrier).

2. Deopt side-exits. Guard ops carry the resolved side-exit DestLabel they fall through to, making deopt a first-class LIR concept. The arch-neutral dispatcher resolves labels[deopt] and builds the guard; the encoder branches to it. This pattern carries the overflow exit of IntegerBinOp and every guard/check op.

5. Encoding styles: decomposition vs. macro-op

Migrated families use one of two encoder styles, both byte-identical to the prior code:

• Decomposition — the LIR sequence is built from reusable primitives and the per-arch lowering lives in encode_linst. Used by the move/memory/ALU/branch core, the field load/store + write-barrier, and the FP transfer/convert ops (whose spill-aware bodies were moved from emit_* into the encoder arms, deleting those emit_*).
• Macro-op delegation — a single LInst whose encoder calls an existing per-arch helper that stays (the tag-test / page-split / tagged-arith / C-call sequence is irreducibly per-arch). Two sub-cases:
  • decomposed-style delegation (guards, IntegerBinOp): the per-arch encode_linst matches the variant directly and calls the substantive helper (guard_class / a64_guard_class, integer_binop / a64_integer_binop, …); the thin emit_* wrapper is deleted.
  • encode_linst_macro-style delegation (the large runtime-call families): the variant falls through each backend’s other => arm into the arch-neutral encode_linst_macro, which calls the per-arch emit_* helper. The emit_* helper is retained verbatim, so the migration is a pure routing change — the dispatcher arm now builds an LInst and hands it to encode_linst instead of calling emit_* directly. This is how the construction / variable / defined? / definition / control-flow families were migrated (batches A and B).

6. Migration log

Each stage routes one family through encode_linst, commits, and is verified by the full cargo test --lib suite (see §7). All stages are byte-identical (modulo eliding a redundant self-mov when a value is already in the accumulator).

7. Verification

Because the migrations are pure refactors, the safety net is behaviour preservation under a correct reference Ruby:

• The harness compares JIT output against the system ruby, and monoruby targets CRuby 4.0+. With an older Ruby (e.g. 3.3) ~33 --lib tests fail on format differences (3.4 Hash#inspect, etc.) — unrelated to LIR. Every stage here is verified under CRuby 4.0.5, where the baseline is 1702 passed / 0 failed; each migration keeps it at 1702 / 0 with no new warnings.
• Each family migration is local to its emit_* / dispatcher arm and is independently revertible.

Building CRuby 4.x from source in a restricted-network sandbox: the official tarball host (cache.ruby-lang.org) may be blocked while GitHub is reachable. Fetch the git tag source archive from codeload.github.com, install gperf (needed to generate lex.c), empty gems/bundled_gems to skip the bundled-gem download (or set SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt so the bundled-gem fetch trusts the egress proxy CA), then autogen → configure → make → make install.

8. Remaining work

First, what is no longer a blocker. The whole method-call family is now migrated — argument setup (SetupMethodFrame, SetArguments, SetArgumentsForwardedHelper, Preparation, OptCase; B6) and the call itself (Call; B7) lower through encode_linst. The dispatcher — which holds &Store / &mut AsmInfo — resolves every store/frame-dependent value (callee scratch offset, block (fid, arg), heap-ivar table length, jump-table DestLabels, and for Call the codeptr / is_iseq / callee & call-site pcs / x86 JIT entry) and carries them in the LInst, so the per-arch helpers (do_call/a64_do_call, …) are store-free. Call’s encoder also records the return-address patch point, which is captured at the emission point and so belongs with the call’s emission. (The elementary register/stack moves were likewise inlined into the dispatcher in B5, deleting their forwarding wrappers.)

The cold side-exit / deopt handler blocks that guards branch to — laid out by gen_asm before the main instruction loop, not by an AsmInst — are also byte emission, and as of B8 they route through encode_linst via LInst::SideExit (write-back + sp-unwind + VM-resume / unwind). Both arches’ gen_asm side-exit loops now build an LInst::SideExit and the per-arch encoder dispatches on LSideExitKind.

The remaining things handled directly (not through encode_linst):

• Specialized inlined-frame family. MethodRetSpecialized, BlockBreakSpecialized, SpecializedCall, SetupYieldFrame, and SpecializedYield lower an inlined callee/block frame; they resolve frame-local labels and patch points and are dispatched to a per-arch method of the same name (arch/<arch>/compile/…). (AsmInst::Inline is no longer in this group — it lowers to LInst::Inline; see below.)

• The AsmInst::Inline escape hatch. Most builtin inline generators (e.g. emit_math_sqrt) still run a closure that emits arch asm directly via gen. As of the AsmIR→LIR consolidation, AsmInst::Inline does lower to a carrier LIR op — LInst::Inline(InlineProcedure) — so every AsmInst reaching the dispatcher now lowers to LInst. LInst::Inline is the one LIR op whose emit is not store-free: its wrapped closure needs the compile context (&Store, &SideExitLabels, frame base), so it is dispatched at the lowering boundary via encode_linst_inline rather than through the store-free encode_linst. (If it ever reached encode_linst/_macro it hits the unreachable! fallthrough.) This is a transitional carrier: migrating the closures onto typed, arch-neutral LIR ops — so the variant can eventually go away — is goal 2 of the long-term plan (“express the inline-builtin codegen once, arch-neutrally”). The migratable category is the pure generators — property/field readers and trivial C-function wrappers, whose codegen is one existing LIR op with no arch-specific control flow:

  • 64-bit field readers → AsmIr::load_field_to_reg → AsmInst::LoadFieldToReg → existing LInst::Load { Field } (no new op, byte-identical on both arches). Done: Range#begin/end (hand-written emit_range_begin/end deleted) and ArithmeticSequence#begin/#end/#step (via the shared inline_field_load helper; emit_load_value_field deleted from both backends).
  • Bool field readers → AsmIr::bool_field_to_reg → AsmInst::BoolFieldToReg → LInst::BoolFieldToReg (a small macro-op: 32-bit load + shl 3 + or FALSE_VALUE, deduping the two byte-identical emit_*_exclude_end emitters into one encode arm per arch). Done: Range#exclude_end?, ArithmeticSequence#exclude_end?.
  • Container length → AsmIr::array_len_fixnum / string_len_fixnum → AsmInst::ArrayLenFixnum / StringLenFixnum → the matching LInst (a macro-op: load inline capa + conditional-select the heap length when capa exceeds the inline cap + fixnum-tag; the conditional select is the only per-arch part, x86 cmov / aarch64 csel). Done: Array#size, String#bytesize — one op each (differing only in the inline-cap constant, ARRAY_INLINE_CAPA vs STRING_INLINE_CAP), replacing the four emit_array_size/emit_string_bytesize emitters.
  • Fixnum → float (Integer#to_f) → the existing AsmIr::fixnum2fpr → LInst::FixnumToFpr op (untag + cvtsi2sd/scvtf straight into the result fpr). No new primitive; deletes emit_int_to_float from both backends (and drops a redundant xmm0 round-trip the old emitter always did).
  • Bool predicates (Object#nil?, BasicObject#!) → AsmIr::is_nil_to_bool / not_to_bool → LInst::IsNilToBool / NotToBool (a macro-op: compare + conditional-select TRUE/FALSE; the select is the per-arch part, cmov/csel). Replaces the emit_kernel_nil / emit_object_not emitters.
  • C-function wrappers (e.g. Math.sin/cos/atan2, Float#**) are already arch-neutral: they route through the typed AsmInst::CFunc_F_F / CFunc_FF_F (→ existing LInst::CFunc_*), not the closure escape hatch.
  • FP guard + op (Math.sqrt) → AsmIr::math_sqrt → LInst::MathSqrt, a macro-op carrying the deopt label (resolved by the dispatcher like GuardClass). It encapsulates the per-arch domain guard (x86 ucomisd + jp/jb, aarch64 fcmp + b.vs/b.mi) and the sqrtsd/fsqrt in one encode arm per arch — so even a deopt-branching FP builtin migrates without a closure (it does not declare fpr_operands, matching the prior opaque Inline, so the spill-area sizing is unchanged; the fprs are accounted via the surrounding load_fpr/def_F).
  • Integer guard + op (Integer#succ) → AsmIr::integer_succ → LInst::IntegerSucc, a macro-op carrying the deopt label (add+jo / adds+b.vs, deopt → Bignum promotion). The integer analog of MathSqrt.
  • Control-flow predicate (Kernel#block_given?) → AsmIr::block_given → LInst::BlockGiven, a macro-op with a self-contained local exit label (reads [LFP - LFP_BLOCK]). No external context needed.

  What stays a closure is the genuinely complex shapes — object allocation, send, fiddle, the remaining integer shift/division guards, object_id (a runtime call). Several would still benefit from a couple of generic FP/branch/call LIR primitives.

• Pure registration / recompile bookkeeping — the x86/aarch64 non-coverage asymmetry of doc/arch_difference.md §4. The deopt handler emission now goes through LIR (above); what stays out is the part that emits no bytes: ChainExit records a call site’s replay data in chain_deopt_table (zero bytes), and the actual frame conversion happens at BOP-redefinition / deopt time, not at compile time. The clean invariant is therefore:

encode_linst is the single seam for byte emission; zero-byte code-position metadata / runtime patch bookkeeping is not emission and stays in the dispatcher / Codegen.

None of this invalidates the model: encode_linst (with encode_linst_macro, plus the context-carrying encode_linst_inline for the one LInst::Inline op) is the single seam for byte emission. The only arms still handled directly in the dispatcher are the specialized inlined-frame family (which resolve frame-local labels / patch points) and the patch/recompile bookkeeping, which is not emission by the invariant above.

§9 The two-phase pipeline: whole-function buffering + virtual GP + physical allocation

Everything above is the single-pass seam: compile_asmir lowers each AsmInst to one or more LInsts and emits them immediately through encode_linst. That gave us one byte-emission description per op, but it cannot host a register allocator: allocation needs the whole function’s instruction stream in hand to compute liveness, so an op cannot be encoded the instant it is produced.

The next architectural step (the AsmIr → LIR pipeline) splits emission into two phases while keeping AsmIr and LIR as separate layers (collapsing them would just reconstruct AsmIr):

AsmIr (AsmInst, frame-INDEPENDENT, FP already virtual, GP physical)
  │  lower (resolve frame size / labels / patch points)
  ▼
LIR  = Vec<LInst>   ← whole compiled unit, offsets baked in, GP *virtual*
  │  arch-dependent physical-register allocation pass (GP virtual → physical)
  ▼
encode (drain → encode_linst → bytes)

• LIR is barely-arch-independent and offset-baked. Frame base, slot displacements, field offsets, and labels are all resolved when AsmIr lowers to LIR (AsmInst is frame-independent; LInst already carries base). What LIR does not yet bake is the physical register assignment.
• Registers are virtual in LIR. FP registers already are (FPReg = phys-or-spill, resolved by PhysMap at encode time — §25/§27). GP registers are not: today LInst names concrete GPs (R15 = accumulator, R12 = globals, R14 = LFP, plus scratch temporaries). The pipeline introduces a virtual GP (VReg) for the allocatable GP uses; the fixed globals (acc / pc / lfp / globals / executor — see CLAUDE.md) stay pinned and are not virtualized. Only the temporary/scratch GP traffic becomes virtual and is assigned in the post-LIR phase.

Blockers (from the current driver, asmir.rs::compile ~2293–2400)

The single-pass driver interleaves byte emission with ordering operations that are not themselves LInsts emitted through encode_linst:

1. self.jit.label() / bind_label(..) — label creation and binding.
2. self.jit.select_page(1) — cold/hot page selection (x86 lays side-exit handlers on the cold page).
3. frame.sourcemap.push((i, pos)) — source-position records keyed on the current code position.
4. Patch-point / return-address-table bookkeeping (doc/arch_difference.md §4), which emits zero bytes but is position-sensitive.

If LIR buffered only the encode_linst calls and left (1)–(4) inline, replaying the buffer later would desync every label, page boundary, and source mapping. Therefore the buffer must model these as ordering pseudo-ops in the same Vec<LInst> (e.g. LInst::BindLabel, LInst::SelectPage, LInst::SourcePos), so the entire emission stream — bytes and position metadata — is one ordered sequence the allocator can walk and the drainer can replay faithfully.

Staged increments

• 9a — Make the emission stream fully reified. Add the ordering pseudo-ops so compile_asmir + the side-exit loop produce a single Vec<LInst> covering all of byte emission, label binding, page selection, and sourcemap. Verify byte-identical output by draining the buffer immediately (no allocation pass yet) — a pure refactor, gated/shadowed like the §24 placement harness.
• 9b — Introduce VReg (virtual GP) with an identity map. Replace the allocatable GP operands with VReg, lowered through a trivial virtual→physical map that reproduces today’s assignment. Still byte-identical; this only changes the type carried, establishing the seam.
• 9c — Carry liveness / loop metadata into LIR. Per §27.1, re-deriving liveness after LIR-flatten cost 2.5×, so the allocator must consume the metadata the ① fixpoint already computed (loop-carried sets, etc.) rather than recompute it. Thread it onto the buffer.
• 9d — The arch-dependent physical-allocation pass. Walk the buffered LIR, assign physical GPs to VRegs (spilling to frame slots under pressure, exactly as FPReg does for FP), then drain → encode. This is the first point the output may legitimately differ from today’s bytes; like the (since removed) phys-loop-aware experiment (regalloc doc §42, §49), it is a perf experiment gated behind a flag + the M1 A/B bench gate, and the shadow digest becomes a delta meter, not an equality check.

9d allocatable GP pool (design decision)

The VM’s fixed registers stay pinned (acc=R15, lfp=R14, pc=R13, globals=R12, executor=rbx) and the C-ABI / inline-builtin convention regs (rdi=recv, rax=result, rsi/rdx/rcx=call args) are pre-colored by the operations that use them — the allocator cannot move those. The allocatable pool is the otherwise-unused caller-saved scratch set:

• x86-64: r8, r9, r10, r11 (4 registers). These are caller-saved, so any of them that is live across a C-ABI call (e.g. a runtime helper / CFunc_*) must be spilled to the frame and reloaded — the allocator inserts the save/restore exactly as the FP side already does around calls (fpr_save / fpr_restore).
• aarch64: the analogous caller-saved temps left free in the GP::a64 map (x9..x15 minus the encode scratch x9/x10), with the same spill-across-call rule.

So a VReg is either pinned (an ABI/convention register the front-end chose) or allocatable (assigned by 9d to a pool register or a spill slot). The identity map of 9b is the degenerate all-pinned case; 9d makes the front-end emit allocatable VRegs for cross-operation temporaries and colours them into the pool. The payoff is keeping hot bytecode-slot values in r8–r11 instead of re-loading them from the LFP each use.

9a/9b are byte-identical refactors (safe to land once verified); 9c/9d are the substantive allocator work and stay behind a flag until the bench gate clears.

9d placement build order

The placement phase (filling gp_alloc, colouring VReg::Alloc into pool registers, and keeping the frame consistent) is built as a sequence of feature-gated (gp-alloc) increments, each byte-identical while no slot is yet placed in the pool:

1. Write-back + flush pool-support (done). Two seams, both inert until a slot is placed:

   • Side-exit / deopt / GC write-back. WriteBack carries a gp: Vec<(GP, SlotId)> list — the pool-resident slots and their physical registers — alongside the single r15 accumulator. Every such write-back (gen_write_back, gen_write_back_for_deopt, a64_gen_write_back_for_deopt) stores each pool register to its slot’s frame home, exactly as for r15. The producer (wb_gp) scans for slots in mode G(_, VReg::Alloc(_)).
   • In-function flush-at-boundary. writeback_acc — already called before every call / store / definition, and already asserting no G(_, _) slot survives it — now also flushes the pool residents (writeback_pool_state): each G(_, Alloc) slot is stored to its home and dropped to S. Because this runs before every C-ABI call, a pool value never stays resident across a call, so the GP allocator needs no caller-saved spill/reload threading (using_gp) the way the FP side does — the flush already did it.

   Until the placement policy creates a G(_, Alloc(_)) slot both lists are empty, so the fields, their Hash/Debug, and the write-back/flush loops are inert and the emitted bytes are unchanged.

2. Reserve the pool registers (x86-64) (done). The pool design above assumed r8–r11 were “otherwise-unused caller-saved scratch”, but an audit of the JIT-body lowerings found that is not true: r8–r11 are the JIT’s secondary scratch pool, used freely once the primary scratch (rax/rcx/rdx/rsi/rdi) runs out. To hold a value in a pool register across instructions, no intervening lowering may clobber it — so the pool registers must be reserved, exactly as the FP side reserves its xmm pool and confines scratch to xmm0/xmm1.

   The audit (in-scope: every compile.rs / compile/* / guard.rs lowering that can run while a pool value is live; out of scope: vmgen = the VM interpreter, invoker/wrapper = reached via a call boundary) found:

   • r10, r11: unused in JIT-body code.
   • r9: only class_def, a post-flush call-staging use (safe).
   • r8: every use is post-flush call-staging (a method-send/define/store sequence runs writeback_acc first, emptying the pool — so r8 is free there, the GP analogue of using the pool after fpr_save) except one: emit_string_setbyte, a pure inline op that can execute with a pool value live. That one was migrated off r8 (tag scratch → rcx; negative-index adjust → a sign branch instead of a cmov-through-scratch).

   The reservation invariant: a JIT-body lowering may use r8–r11 as scratch only in a post-flush call-staging window (after writeback_acc, where the pool is provably empty). Everywhere a pool value can be live, the pool registers are off-limits. After the migration this holds for the whole x86-64 backend. (aarch64 pool reservation is pending: GP::R8–R11 map to x5–x8; that backend needs the same audit before placement targets it. The gp-alloc feature is x86-first and off by default, so nothing places into the aarch64 pool yet.)

3. Placement policy + multi-residency (done). def_reg2acc_guarded is the trigger: when a new accumulator value arrives from a register other than R15 (so R15 still holds the previous accumulator), try_relocate_acc_to_pool moves that previous value into a free pool register (G(_, Alloc(id))) instead of spilling it. Later reads then come from the register (no LFP reload) until the next flush. Making the state machine track pool residents (not just the single R15 accumulator) required:

   • Placement::Gp(VReg) (load-bearing). SlotState stores place + ty and reconstructs every mode() via from_parts — so the placement must carry the VReg, else set_mode(G(Alloc)) loses the pool-register identity on the very next state read (it round-trips to Stack).
   • Register-aware reads everywhere a G slot is consumed: on_reg / on_reg_or (binop operands), load_state (GpLoad::Reg(vreg.phys())), fetch_for_callee (call-argument materialization), the G→Sf bridge — all resolve vreg.phys() rather than assuming R15.
   • Alloc-aware destructive sites + flush (§1, the gp field / writeback_ pool_state / Alloc-aware clear/write_back_slot).
   • Fixnum-only restriction (GC safety): a pool register is not a GC root, so only values statically guarded Fixnum (immediates — no heap pointer) are relocated. A heap pointer kept solely in r8–r11 across a collection would be freed; heap-value pooling is deferred until pool registers are made GC-rootable. Hot integer loops — the primary target — are covered. Verified byte-identical on default; gp-alloc passes the full suite including gc-stress (GC on every allocation).

4. M1 A/B bench gate before the feature becomes default.

Notes:

• C-ABI call-save is not a separate step: the flush-at-boundary (§1) makes it unnecessary — pool slots are always written back before a call. This holds for every call, not just Ruby method calls: the method-call path flushes via writeback_acc, and every runtime helper (deep_copy_lit, new_array, new_hash, to_a, concat_str, generic_binop, class/method def, defined?, …) flushes the pool at its pre-call get_using_fpr snapshot (which now flushes the GP pool as a side effect — the universal pre-C-call chokepoint). The pool registers are caller-saved, so a Fixnum left resident there would otherwise be clobbered by the helper’s C call (e.g. String#clear’s bytesize in r8, clobbered by the "" literal’s value_deep_copy). The asmir builders that take &AbstractFrame (immutable, so they cannot flush) get an explicit flush_gp in their handler instead.
• Branch-merge reconciliation needs no special pool handling: pool residents are flushed (→ S) before any branch (the compile-loop flush_gp and the back-edge analysis G→S demotion), so a merge never sees a G(_, Alloc) slot.

9d outcome: GP register residency does not pay; the untagged-Fixnum direction does

The temp-relocate placement (§9-3) is correct (full suite incl. gc-stress passes) but the M1 A/B bench gate fails: no benchmark improves beyond noise and binarytrees regresses ~14% (the relocate mov + flush is pure overhead when the pooled value is not reused enough). So gp-alloc stays off.

9d-B: accumulator register file (results born directly in r8–r11)

Instead of the relocate model (new value → R15, then relocate the old R15 resident into the pool), the accumulator register file extends the accumulator’s register set from {R15} to {R15, r8–r11}: a Fixnum result is written directly into a free pool register (try_def_G_pool in def_reg2acc_guarded), with no R15 round-trip and no relocate mov. R15 remains the fallback when the pool is full or the value is not a Fixnum immediate. This removes the relocate overhead that made the temp-relocate version regress binarytrees.

Making it correct required eliminating two latent “the current value is in R15” assumptions that the single-accumulator design relied on:

1. copy_slot’s G arm spilled src then def_G(dst) — which claims R15 without moving the value there. Sound only for Pinned(R15); for a pool resident it left dst reading R15 while the value sat in the pool register. Fixed by transferring the pool register’s ownership to dst (no data move).
2. Caller-saved clobbering across runtime helpers (see the §1 note above): the pool registers are caller-saved, and the flush-at-boundary invariant was only honoured by Ruby method calls, not the runtime helpers. Fixed by folding the GP-pool flush into get_using_fpr, the universal pre-C-call snapshot.

Result: full lib suite green under --features gp-alloc (1678/1678, reduced parallelism — the harness flakes on ruby-subprocess spawn under high parallelism, unrelated to the JIT). A/B (release, best-of-5): binarytrees 0.997× (the −14% regression is gone), app_fib 0.959×, tarai 1.007×, so_nbody 0.999× — i.e. overhead-free but not a speedup. So the register-file fixes the cost of the relocate model without changing the fundamental conclusion below: residency alone is marginal for Fixnums. gp-alloc stays off pending the untagged-Fixnum representation, which supplies the missing per-op cost. The work lives on claude/gp-acc-regfile.

Why register residency alone is marginal for integers. Unlike floats — where the win is avoiding boxing (a heap allocation per spilled float) — a Fixnum is an immediate, so keeping it in a GP register only saves an LFP load/store, and that store is already cheap (L1 + store-to-load forwarding). Locals must also be materialized in the frame at every deopt / call / GC safepoint anyway. Microbench (hand-asm, faithful to the JIT loop body): keeping the loop locals of while i<n; s=s+i; i=i+1; end in registers instead of memory is only ~1.26× on the tightest possible integer loop, diluted to ~noise on real benchmarks.

Loop-carried integer residency (the float-F-mode analogue: promote loop-carried Fixnum locals to pool registers at the loop entry, keep them across the back-edge) was prototyped on branch claude/gp-loop-carried-wip. It promotes, but the JIT’d loop deopts and recompiles ~every iteration (the VM→JIT loop entry / OSR does not set up the pool registers the JIT’d loop head expects). Given the marginal ceiling above, it was not pursued to completion.

The promising direction — untagged Fixnum (“integer F-mode”). A Fixnum is tagged 2n+1, so every integer op pays a tag adjustment (sub 1 / or 1) and a type guard (test $1; je). Give integers a second representation — untagged 2n (LSB cleared), held in a GP register — exactly as a float has boxed Value vs unboxed F (xmm). Within a run of integer ops the value stays untagged; it is tagged (or 1) only when it escapes to a Value context (stored to a boxed slot, passed to a call, …). This removes both per-op costs, because an untagged-integer slot is statically known to be an integer (no guard, like F needs no float guard).

Key properties:

• Overflow detection is preserved by the 2n choice: 2a + 2b = 2(a+b) overflows i64 iff a+b overflows i63 (the Fixnum range), so the existing jo works unchanged. (Raw n would not preserve this.)
• Per-op, not per-loop: the tag/guard elimination helps every integer op, so it benefits straight-line integer code too, not just loops.
• Microbench (hand-asm): untagged + guard-free is ~1.50× over the tagged+guarded in-register loop; compounded with residency, ~1.9× ceiling on the tightest integer loop.

Implementation shape (a substantial change, comparable to introducing F/Sf): a new LinkMode for an untagged integer in a GP register (I, the F analogue) plus an untagged-with-boxed-cache variant (Si, the Sf analogue); integer-op lowerings that consume/produce the untagged form; tag on escape to Value. This is the recorded future direction for integer JIT performance — it supplies the “boxing-like” per-op cost that finally makes GP register residency worthwhile.

Separating the abstract interpreter from register allocation

Design study for Phase-1 item ② (“separate the abstract interpreter / fixpoint search from register allocation”). This is the structural prerequisite for the longer-term goals: collapsing AsmIR into LIR (goal 1) and deriving the VM and JIT from one description via partial evaluation (goal 3 / item ③).

Status: design proposal only — no code has moved yet.

1. Where the two concerns are fused today

The JIT’s middle end runs a single abstract-interpretation pass over TraceIR that simultaneously infers types and assigns physical storage. The fusion lives in three places:

LinkMode — one enum, three concerns

monoruby/src/codegen/jitgen/state/slot.rs:1229

#![allow(unused)]
fn main() {
enum LinkMode {
    V,                  // no value
    None / MaybeNone,   // optional-arg sentinels
    S(Guarded),         // boxed on the stack      + type guard
    G(Guarded),         // boxed in GP r15 (acc)   + type guard
    F(FPReg),           // unboxed f64 in an xmm    (type = Float)
    Sf(FPReg, SfGuarded // unboxed in xmm + boxed cache on stack + type
    C(Value),           // compile-time constant   (type = guarded(v))
}
}

Each variant encodes all three of: the abstract type (Guarded class / float-ness / concrete value), the representation (boxed Value vs unboxed f64), and the location (stack home / GP r15 / xmm pool).

SlotState — type lattice and allocation map in one struct

monoruby/src/codegen/jitgen/state/slot.rs:4

#![allow(unused)]
fn main() {
struct SlotState {
    slots: Vec<LinkMode>,    // per-slot fused type+repr+location
    liveness: Vec<IsUsed>,   // analysis
    vfpr: Vec<Vec<SlotId>>,  // allocation: reverse map xmm/spill -> slots
    r15: Option<SlotId>,     // allocation: who owns the accumulator
    pinned_vfpr: Vec<FPReg>, // allocation directive (anti-aliasing)
    …
}
}

Allocation decisions are taken inside the dataflow

• alloc_fpr (slot.rs:370) does greedy linear-scan allocation (find a vacant physical xmm 0..PHYS_FPR_POOL; else demote an Sf cache; else spill to FPReg(N≥PHYS_FPR_POOL)).
• def_F / def_Sf_* (slot.rs:554) allocate a register and set the slot’s type in one call.
• AbstractFrame::join (state/join.rs:46) merges type guards and reconciles registers together — it can even allocate a fresh xmm mid-merge (try_set_new_F) when two predecessors hold a value in different xmms.

What is already factored out

FPReg (codegen.rs:181) is already a virtual register: FPReg(0..13) → xmm2..xmm15, FPReg(14+) → an 8-byte stack spill, resolved late by FPReg::loc(base) (codegen.rs:188). AsmInst operands carry FPReg, so the operand layer is virtual. What is not factored out is when/where the FPReg assignment is decided — it happens inline with type inference.

Net: type analysis, representation (box/unbox), and register allocation are one pass over one fused LinkMode/SlotState. ② is about teasing these apart.

2. Why separate (the payoff)

• Goal 1 (collapse AsmIR into LIR). Once allocation is a distinct step that emits, it can emit LInst directly; the AsmInst layer (already ~isomorphic to LInst after the B-migrations) stops carrying its own existence.
• Goal 3 (one description → VM + JIT). Partial evaluation needs the analysis to be reusable under two different allocation policies:
  • JIT residual = analysis with inline-cache types + the greedy xmm allocator (today’s behaviour).
  • VM residual = analysis with ⊤ (no specialization) + a fixed-convention allocator (everything boxed in its stack home, no pool). You cannot instantiate two allocators while allocation is welded to inference.
• Maintainability. The join table conflates a type lattice with a register reconciler; splitting them makes each independently testable.

3. Target architecture

Three layers, with a typed IR in the middle:

TraceIR
  │  ① analysis pass  (fixpoint; types + liveness only — NO locations)
  ▼
Typed IR            per-slot `Guarded` type lattice + liveness; operands are
  │                 (slot, representation) — still virtual, no phys regs
  │  ② allocation + lowering pass  (pluggable Allocator)
  ▼
LIR (LInst)         concrete regs/spills; emitted straight to encode_linst
  ▼  encode_linst → bytes

Layer ① — the type lattice (analysis)

A pure lattice element per slot, no location. This is the existing Guarded enum — no new type is needed:

#![allow(unused)]
fn main() {
enum Guarded { Value /*⊤*/, Fixnum, Float, Class(ClassId) }
}

join over Guarded is a pure lattice meet (Guarded::join already exists) — no register churn. Liveness stays here. This is what goal 3’s partial evaluator parameterizes (feed ⊤ for the VM residual, IC-narrowed types for the JIT residual).

Sf is not a type. Per review, the Sf linkage (“Integer def’d, Float use’d, kept coerced to f64”) is not a lattice element but a representation decision taken by a separate analysis. In the typed IR an Sf slot lowers to its plain boxed type (Fixnum); a dedicated def-use + loop pass then marks it for the xmm-coerced representation when:

the slot is def’d as Integer and use’d as Float, and it is a constant/literal or def’d outside a loop and use’d inside it (i.e. the coercion is loop-invariant and worth hoisting into an xmm).

That mark is the FprStack placement. Keeping it out of the type lattice is what lets the VM residual (no marks, everything boxed) and the JIT residual (marks applied) share one analysis.

Layer ② — representation + allocation

Given the typed IR + liveness, a separate step decides:

1. Representation: keep a Float/Fixnum value unboxed where it is consumed by FP arithmetic, else boxed. (Today: the F vs S vs Sf choice.)
2. Placement: assign each live unboxed value an FPReg (pool or spill) and each boxed value its stack home / the r15 accumulator. Insert transfer / spill / φ-move code at edges.

This is the swappable Allocator. The default is the current greedy policy; the VM policy is “no pool, everything in its stack home.”

4. Incremental migration path

Each step is independently shippable and verified at 1702/0 (behaviour preservation under CRuby 4.0+). Order chosen so the risky structural change comes last, after the data is already decoupled.

Step 0a is shipped (Placement + projections + round-trip test). Steps 0b–1 are mechanical decoupling that pay off immediately (clearer code, testable lattice) and de-risk step 2. Steps 3–4 are where goals 1 and 3 land.

5. Hard parts / open questions

• Join-time reallocation. Today join may allocate a fresh xmm when two predecessors hold a value in different registers. Separated, the allocator must resolve this as an SSA-φ with edge moves (insert FprMoves on the CFG edges) rather than reallocation during the meet. This is the crux: step 2 effectively turns the fused greedy pass into a proper linear-scan / SSA allocator with edge fixups. Codegen quality must not regress (the current greedy is decent on the FP-heavy benchmarks).
• Sf (xmm + stack cache). Resolved in review: Sf is a representation decision, not a type. The typed IR carries the plain boxed type (Fixnum); a separate def-use + loop analysis marks the slot for the xmm-coerced representation (the FprStack placement) using the heuristic in §3. The demote-on-pressure logic (try_alloc_fpr phase 1) is a further allocation policy that moves into the Allocator. (In the current fused state the SfGuarded refinement still round-trips losslessly through the paired Guarded, since SfGuarded → Guarded is injective.)
• r15 accumulator. The single GP “accumulator” slot is its own tiny allocation problem fused into SlotState.r15; it follows the same split (type vs placement) but is simpler than the xmm pool.
• Spill-region sizing across joins (grow_fpr_to, gen_bridge) becomes the allocator’s responsibility once placement is its own layer.

6. Progress

Step 0a is done (revised per review). LinkMode now has the placement() / from_parts() projections, and a unit test (linkmode_placement_roundtrip) proves it is isomorphic to (Placement, Guarded). The type lattice is the existing Guarded; Sf is treated as a representation mark (the FprStack placement), not a type, with its refinement recovered from the paired Guarded. No live state changed; suite at 1703/0.

Steps 0a–0c are done. SlotState is backed by place: Vec<Placement> + ty: Vec<Guarded>; the type lattice is a standalone per-slot vector with a reusable meet (join_ty). Crucially, the fused AbstractFrame::join’s type result is exactly that meet for every non-sentinel slot — so the join’s residual work is purely placement reconciliation (the register/φ reconciliation that carries allocation side-effects). That confirms the clean split point: the type analysis is already separable; what remains entangled is allocation, which is precisely what steps 1–2 pull out.

Step 1 is done. The xmm allocation state (vfpr + pinned_vfpr) and its pure pool primitives now live in an FprAllocator struct owned by SlotState, physically separated from the slot type/placement state. The allocation policy still sits on SlotState.

Next: step 2 (standalone analysis pass) — run the Guarded/liveness fixpoint as its own pass (consuming join_ty) producing a typed IR, before the allocation+lowering pass. This is the high-risk structural change; goals 1/3 fall out of steps 3–4 afterward.

9. Step-2 spike: where the analysis/emission fusion actually lives

Before committing to step 2 (the big rewrite), a spike traced exactly how analysis and emission are entangled in compile_instruction. The finding reshapes the plan.

What the spike found

The bytecode handlers (compile_instruction, ~100 TraceIr arms) are not where analysis and emission are knotted together. A handler like LoadGvar is just discard(dst); push(LoadGVar); def_rax2acc(dst). Following that down:

def_rax2acc → def_reg2acc_guarded → def_G → writeback_acc

the only emission on the whole chain is at the very bottom, in a handful of transfer / eviction primitives — writeback_acc (evict the r15 accumulator owner to its stack home), the xmm spill/swap emitters, etc. Almost everything else (the Guarded lattice, liveness, placement bookkeeping in place/ty/FprAllocator) is already pure state.

And those transfer primitives split cleanly. writeback_acc was:

#![allow(unused)]
fn main() {
fn writeback_acc(&mut self, ir) {
    if let Some(slot) = self.r15 {
        self.set_mode(slot, S(self.guarded(slot)));  // state
        self.r15 = None;                              // state
        ir.acc2stack(slot);                           // emission
    }
}
}

The spike split it into writeback_acc_state() -> Option<SlotId> (the pure state transition, returns which slot was evicted) and the residual writeback_acc = if let Some(slot) = self.writeback_acc_state() { ir.acc2stack(slot) }. The emission is fully determined by the slot the state half returns — i.e. the transfer primitive is (state-mutation that yields a transfer record) + (emit from that record). Behaviour-identical; suite 1703/0.

How this reshapes step 2

Step 2 is therefore not “split ~100 op handlers”. It is:

1. Split each transfer/eviction primitive (a bounded set — writeback_acc, the xmm spill/swap/float_to_fpr emitters, def_*’s eviction step) into a state half that returns a transfer record and an emit half that consumes it. The records are exactly the typed IR the analysis pass produces.
2. The standalone analysis pass runs the handlers with the state halves and collects the transfer records (no AsmIr). It already exists in skeleton form: analyse_basic_block reuses compile_instruction but discards its AsmIr — today that discard is wasteful (it builds AsmInst only to drop them); after the split it would call the state halves and skip emission.
3. The lowering pass replays the records, emitting LInst via the emit halves + encode_linst.

This is a far more bounded and mechanical change than a per-handler rewrite, and each primitive split is independently shippable and behaviour-verifiable at 1703/0 (the writeback_acc split is the first). It also subsumes goal 1: once lowering is its own pass, it emits LInst directly and AsmInst retires.

Progress on the transfer-primitive split

Split so far, each behaviour-identical at 1703/0:

• Stack writebacks → the Spill record (None / Fpr / Lit / Acc): writeback_acc, write_back_slot, to_S_unguarded.
• FP-register transfers → the FpXfer record (Move / Swap): to_sf (gen_fpr_swap was already a clean state-line + emit-line).

Each primitive now has a *_state half that performs the abstract-state transition and returns the record, plus a thin codegen wrapper record.emit(ir). The records (Spill, FpXfer) are the growing typed IR vocabulary.

The hard tail: deopt-carrying transfers

The unbox loads (load_fpr and friends) are not a clean (state) + (record → emit) split, because they create a deopt side-exit mid-flight:

#![allow(unused)]
fn main() {
let deopt = ir.new_deopt(self);     // captures state.get_write_back() — a
self.use_as_float(slot);            // SNAPSHOT of the live placement state
match self.mode(slot) { S(_) => { let x = self.set_new_Sf(..); 
    ir.stack2reg(slot, Rdi); ir.float_to_fpr(Rdi, x, deopt); x } … }
}

new_deopt snapshots get_write_back() — which values are unboxed/in-acc and must be restored to the stack if the float guard fails. That snapshot is the placement state at this program point. So in the separated design the deopt is created by the codegen pass, reconstructing the write-back from the analysis-precomputed placement at that point; the typed IR records the deopt program point (pc), not a frozen AsmDeopt. This is the main wrinkle that distinguishes the FP-load transfers from the simple evictions, and it is where the typed IR must carry per-point placement (which the analysis already tracks).

Resolved (load_fpr split). load_fpr / load_fpr_fixnum now split into a load_fpr_state half (allocate the xmm, bind the slot) returning an FprLoad record (None / FromStack / FromAcc / FromF64 / FromFixnum), plus a wrapper that creates the deopt first (so its write-back snapshot is the pre-load placement) and passes it as Option<AsmDeopt> to FprLoad::emit. The deopt is therefore supplied by the codegen side, not frozen into the record; the guard-free numeric variants pass None. This confirms the resolution above concretely — behaviour-identical at 1703/0.

The guard primitive

guard_class (the guard primitive behind guard_fixnum / load_fixnum / load_array_ty) splits into guard_class_state(slot, class) -> bool (refine the slot’s type; return whether a runtime guard must be emitted) plus the emit if guard_class_state { ir.push(GuardClass(r, class, deopt)) }. load_fixnum and load_array_ty then compose split primitives (load + the guard).

load_fpr_fixnum: the interleaving dissolves (single record after all)

load_fpr_fixnum’s S/G arms looked like the case that could not reduce to a single (state) + (record → emit) pair, because they interleave a load, a new_deopt, a guard and the conversion:

stack2reg(Rdi)            // emit  — load the boxed value
new_deopt                 // deopt
guard_class_state         // state (type)
push GuardClass(deopt)    // emit  — Integer guard
set_new_Sf                // state (placement — allocates the xmm)
fixnum2fpr(Rdi, x)        // emit  — int → f64

The deopt snapshot (get_write_back) must precede the placement change (set_new_Sf). The apparent obstacle was that the load (stack2reg) “must” precede the deopt. But stack2reg/reg2stack are pure emits on ir — they push an AsmInst and never touch the frame’s placement state — so new_deopt commutes with them. Reordered, the dependency chain is just new_deopt → {guard_class_state, set_new_Sf}, the same shape load_fpr already solved: create the deopt up front, run the (now reorderable) state half, defer all emission into the record. The guard folds into the record as a bool (guard_class_state’s verdict). So load_fpr_fixnum splits into load_fpr_fixnum_state -> (FPReg, FprFixnumLoad) plus a wrapper that creates the deopt only for the guarded S/G arms (peeking the mode — use_as_value only marks liveness, so the peek is stable) and supplies it to FprFixnumLoad::emit. Behaviour-identical at 1703/0.

The lesson: a “pure emit” instruction between a state mutation and a new_deopt is not a true interleaving — it commutes out to the emit half. The single-record model is therefore more general than first thought, and with this split every transfer/eviction primitive in the table is now decomposed into a *_state analysis half returning a typed-IR record (Spill / FpXfer / FprLoad / GpLoad / FprFixnumLoad, plus the guard_class_state verdict) and a record-replaying emit half. That completes the prerequisite for the two-pass wiring: the analysis pass calls the *_state halves and collects the records; codegen replays record.emit(...). The remaining step is plumbing those two passes through compile_instruction / analyse_basic_block.

10. The analysis/codegen seam already exists: codegen_mode

Before building a two-pass from scratch, a closer read of the driver shows the seam is already present, which reframes step 2.

What is actually there

AsmIr carries codegen_mode: bool (asmir.rs:76), seeded from JitContext::codegen_mode(). Crucially AsmIr::push is already gated on it:

#![allow(unused)]
fn main() {
fn push(&mut self, inst: AsmInst) {
    if self.codegen_mode { self.inst.push(inst); }   // no-op in analysis mode
}
}

Two passes already run the same compile_instruction under the two modes:

• Loop-analysis pre-pass — JitContext::loop_analysis sets codegen_mode: false (context.rs:687). analyse_backedge_fixpoint → analyse_basic_block runs the handlers to compute the loop’s back-edge / liveness fix-point. push is suppressed, so no AsmInst is built — it produces abstract state, not an instruction stream.
• Codegen pass — traceir_to_asmir → compile_basic_block runs with codegen_mode: true, doing analysis and emission in one fused walk.

Handlers that must diverge between the two modes already branch on self.codegen_mode() (e.g. binop_uncached in binary_op.rs:25 widens to S during analysis but emits a per-instruction deopt+recompile during codegen).

Correction to §9: the claim that the analysis pass “builds AsmInst only to drop them” is wrong — push is gated, so analysis never accumulates the stream. The only residual analysis-mode waste is computing a transfer record and then calling its no-op emit, plus ungated side_exit growth (new_deopt / new_label are not gated, but their results are unused in analysis).

What this means for step 2

The separation is not “introduce an analysis pass” — that exists. It is two remaining, independent pieces:

1. De-fuse allocation from the dataflow (the §5 crux). Today both passes allocate: alloc_fpr / join’s register reconciliation mutate placement inside the abstract-interpretation walk. So the loop pre-pass is “analysis + allocation with emission suppressed,” not pure type/liveness analysis. The real work is pulling placement out of the join — turning join-time reallocation into SSA-φ edge moves — so the analysis pass computes only Guarded + liveness and the allocator runs as the second pass over that result. This is the high-risk core; codegen quality (the greedy xmm policy) must not regress.
2. Record-driven lowering (goal 1). Once allocation is its own pass, the codegen walk replays the typed-IR records (Spill / FpXfer / FprLoad / GpLoad / FprFixnumLoad / guard) emitting LInst directly, and AsmInst retires. The transfer-primitive split (now complete) is exactly what makes the replay possible; the open wrinkle is the deopt, which must become a program point reconstructed from the analysis-precomputed placement at that pc rather than the frozen AsmDeopt the records carry today (§9 deopt note).

So the two-mode compile_instruction is the chassis; the remaining engineering is (1) then (2). (1) is the architectural fork — re-execution-based (generalize the codegen_mode pre-pass to all code, feeding precomputed states forward) vs. record-stream-based (collect records, lower from them) — and is the decision to take deliberately, since it sets how allocation is staged.

11. Record collection: the TransferIR stream

The first concrete step of record-driven lowering (chosen over the §5 allocation de-fusing as the lower-risk groundwork): collect the transfer records into a stream so a later pass can replay them.

• Unified element. The five per-primitive records (Spill, FpXfer, GpLoad, FprLoad, FprFixnumLoad) now share one enum TransferIR (state/read_slot.rs) with a single emit dispatch. The two deopt-carrying variants still freeze an AsmDeopt (lifting it to a program point is §9’s open item, the next wall).
• One funnel. AsmIr::transfer(t) is the sole sink: it pushes t onto the new transfers: Vec<TransferIR> (codegen mode only, so it stays in lock-step with the codegen_mode-gated inst) and then emits via t.emit(self). Every transfer/eviction wrapper (load, load_fpr, load_fpr_fixnum, write_back_slot, to_S_unguarded, to_sf) now calls ir.transfer(...) instead of record.emit(ir, …).
• Faithful by construction. The collected t is the record that gets emitted (same value, same call), so the stream is exactly the emitted transfer sequence — no shadow comparison needed; the suite (1703/0) confirms emission is byte-identical. save/restore truncates transfers alongside inst, so the stream survives speculative-emit rollback intact.

The transfers stream is collected but not yet consumed — that is the groundwork. The next steps are (1) lift the deopt to a program point so the stream is codegen-independent, then (2) drive lowering from the stream (replay TransferIR → LInst) and retire the corresponding direct AsmInst emission.

Shadow harness: the records are self-contained

A debug-only shadow check in AsmIr::transfer replays each record alone into a fresh scratch AsmIr and asserts it reproduces exactly the AsmInsts the real emit just appended (compared via Debug, since AsmInst is not PartialEq). This proves TransferIR::emit is a pure function of the record — it reads nothing from self/the frame beyond the record’s own payload. That self- containment is precisely what record-driven lowering needs (it will replay the stream with no analysis frame in hand), and the assert is a standing guard against a future transfer whose emit sneaks in a state dependence. All transfer emit helpers are single deterministic pushes, so the check holds for the whole suite (1703/0, debug build, every codegen-mode transfer exercised).

Deopt program-point-ification: the stream is now codegen-independent

The one remaining codegen dependence in the TransferIR stream was the frozen AsmDeopt (an index into the codegen pass’s side_exit table) carried by the guarded FprLoad / FprFixnumLoad records. That index is meaningless without the exact side_exit table it points into — so a standalone lowering pass could not replay the stream.

Resolved as doc §9 foretold: the records now carry a DeoptPoint — the program point (pc, write_back), both pure analysis values the frame already tracks (get_write_back() is the placement snapshot restored on guard failure). The analysis half (load_fpr / load_fpr_fixnum wrappers) records the point via deopt_point() (no side_exit push); the emit half materializes the actual side-exit via AsmIr::deopt_from_point, so side_exit construction lives entirely on the codegen side. new_deopt is no longer called from the transfer wrappers.

Ordering is preserved exactly: within load_fpr{,_fixnum} the only side_exit push was this one deopt, created “first” — deopt_from_point runs at the top of the emit arm, at the same relative position, so the side_exit table is byte-identical. The guarded-but-guard == false S/G arms still materialize the (dead) deopt, matching the pre-split wrapper.

TransferIR is consequently Clone (not Copy — a DeoptPoint owns a WriteBack). The shadow harness was strengthened accordingly: emit is now a pure function of the record and the side_exit cursor (a guarded record materializes AsmDeopt(side_exit.len())), so the replay pre-pads the scratch’s side_exit to the same length and asserts both the produced AsmInsts and the produced SideExits match (Debug-compared; neither is PartialEq). Suite 1703/0, no replay mismatches — the stream is now fully codegen-independent, the last prerequisite for record-driven lowering (step 3).

Analysis pass skips emission (doc §9 step 2, realized)

With the deopt program-point-ified, AsmIr::transfer now returns immediately in analysis mode (codegen_mode == false). The abstract-state mutation already happened in the wrapper’s *_state half; emit only writes to ir, and the loop pre-pass discards its local AsmIr (analyse_basic_block drops it — the loop_analysis context “emits AsmIr only for analysis, it is never codegen’d”, context.rs:692). So emission in analysis mode was pure dead work — and, since new_deopt/deopt_from_point are not push-gated, it also grew a side_exit table nobody reads (the waste §10 flagged).

This is provably safe: emit’s signature, fn emit(self, ir: &mut AsmIr), cannot touch frame/abstract state — the same property the shadow check independently verifies. So the analysis pass now literally “calls the state halves and skips emission” for every transfer primitive, exactly the §9-step-2 shape. The §10 deopt wrinkle (“the open wrinkle is the deopt … frozen AsmDeopt”) is closed: the records carry a DeoptPoint, and the only thing left fusing analysis and codegen for the transfer primitives is gone. Suite 1703/0.

What remains for full record-driven lowering is the §10-item-1 core (de-fuse allocation from the join — the SSA-φ edge-move rewrite) and lowering the op handlers’ direct emissions through records too; the transfer primitives are done.

12. §5 crux, first cut: de-fusing allocation from the join

The §5 crux is that AbstractFrame::join allocates (try_set_new_F / try_set_new_Sf) during the meet — fusing register allocation into the dataflow. First de-fusion step, mirroring the transfer state/emit split:

The per-slot meet table is now split into

• decide_join(other, i) -> JoinAction — a pure, read-only function of the two predecessors’ LinkModes: the merge decision; and
• apply_join(i, action) — which performs the placement mutation and is the only place the meet allocates an xmm.

JoinAction reifies the nine meet outcomes (Nop / SetMaybeNone / Discard / TryFreshFKeep / TryFreshFElseS / SetSf / TryFreshSfElseKeep / TryFreshSfElseS / SetS). The fresh-xmm rebinds (TryFresh*) are the join-time reallocation §5 targets; they are now isolated in apply_join, behind one seam. Behaviour is identical (the same operations, reorganized) — suite 1703/0.

This is the structural prerequisite for the real change: an allocator pass that consumes the JoinAction stream and assigns registers + inserts edge moves (bridge already emits the FprMove/swap edge fixups), instead of apply_join allocating inline during the meet. The decide/apply boundary is exactly where that pass plugs in. Not yet done: turning the TryFresh* inline allocations into allocator-assigned φ registers (the SSA-φ edge-move rewrite) — but the meet is now cleanly type-decision (decide_join) vs placement-allocation (apply_join).

§5 stage 1: the merge as a replayable record stream

With the meet split into decide_join / apply_join, stage 1 of the safe allocator de-fusion records the per-slot JoinAction stream as the merge runs, then (debug) replays it from a clone of the pre-merge frame and asserts it reproduces the identical placement (every slot’s resulting LinkMode). This is the allocation analog of the transfer shadow harness: it locks the property the separated allocator pass relies on — the decision stream plus apply_join is a complete, replayable record of the meet — and becomes the regression harness future allocator changes shadow against. Suite 1703/0, no replay mismatches.

Key finding for the allocator design — the meet has cross-slot coupling. A TryFresh* action’s allocation (try_alloc_fpr phase 1) can demote other slots’ Sf bindings to S to free a physical xmm. So a later slot’s decide_join may read a LinkMode that an earlier slot’s apply_join mutated: decide and apply are not separable into two clean passes over the slots — they must interleave. The replay shadow confirms this reproduces faithfully (it replays apply_join in order, demotions included). This rules out the naive “decide-all then allocate-all” staging and tells us the allocator pass must model the pool as evolving across the merge’s slots (a linear-scan-style sweep), not a batch assignment — the constraint that shapes stage 2.

§5 stage 2: type-meet separability is now a standing invariant

Stage 2 promotes doc §6’s once-checked claim — “the fused join’s type result is exactly join_ty for every non-sentinel slot” — to a standing debug assertion in verify_join_replay: after each merge, self.guarded(i) equals the standalone join_ty(pre, other)[i] (the allocation-free Guarded meet) for every non-sentinel slot. Verified arm-by-arm and then across the whole suite (1703/0): every meet arm’s result type is join_ty, because the SfGuarded → Guarded projection is a join homomorphism (FixnumOrFloat ↦ Value, matching join_ty(Fixnum, Float) = Value), so even the Sf arms that look like they refine the type actually agree with the plain Guarded meet.

This nails down the type/placement split at the merge: a standalone type+liveness analysis pass — running join_ty with no xmm allocation — computes types identical to the fused meet, and all allocation is isolated in apply_join. Combined with §5 stage 1 (the merge is a replayable record stream) the merge is now cleanly factored into (a) a separable, allocation-free type meet and (b) a recorded placement-allocation stream. What remains for stage 3 is the behaviour-changing switch — an allocator that assigns φ registers (reusing a predecessor’s where it lowers edge-move cost) instead of apply_join’s inline TryFresh* grab — which is benchmark-gated (codegen quality must not regress) and will diverge from the stage-1 placement shadow by construction.

13. §5 stage 3 design: lifting allocation out of the dataflow (the high-risk core)

Stages 1–2 finished the de-fusion inside the merge: the meet is now decide_join (pure, allocation-free, type result proven == join_ty) + a recorded apply_join placement-allocation stream. Stage 3 is the architectural switch — the §10-item-1 / §4-step-2 core — and it is behaviour-changing and benchmark-gated: the stage-1/2 shadows are necessary scaffolding for it but stop applying the moment placements are allowed to diverge.

13.1 What the bridge investigation changed about the plan

A read of the edge-move machinery (AbstractFrame::bridge, slot.rs:1707; driver gen_bridge, state.rs:89; merge in merge.rs:60–116) settled the key question:

• Edge moves already exist. The actual φ-reconciliation MOVs/swaps/spills are emitted by bridge, not by the merge. bridge pattern-matches (pred.mode(slot), target.mode(slot)) and has both placements in hand.
• The merge is commutative and predecessor-blind. decide_join sees only the two LinkModes; it does not know which predecessor carried F(xmm2) vs F(xmm3), nor how many predecessors there are. So a “reuse predecessor p’s register” policy is not expressible at merge time — only the bridge, or a later pass with per-predecessor placement, can express it.

Consequence: the quick “prefer-keep-l instead of grab-fresh” heuristic in the TryFresh* arms is a weak, commutative lever (it biases toward whichever frame happens to be self), not the principled fix. We do not pursue it as stage 3. The principled fix is to move allocation to a pass that runs after the type/liveness fixpoint and can see global/per-predecessor placement — exactly the §3 Layer ② Allocator.

13.2 What stage 3 actually is

Today both compile passes call AbstractFrame::join = decide_join (types) + apply_join (allocation):

• the analysis pre-pass (loop_analysis, codegen_mode:false, context.rs:687) allocates with emission suppressed — so it is “analysis + allocation,” not pure type/liveness;
• the codegen pass (codegen_mode:true) allocates and emits in one walk, and bridge turns the per-edge placement deltas into MOVs.

Stage 2 proved the analysis pass does not need apply_join: its type result is exactly join_ty. Stage 3 acts on that:

The analysis pre-pass computes only join_ty + liveness (no apply_join, no xmm allocation). The codegen pass owns all placement/allocation, and the existing bridge already turns the resulting per-edge placement deltas into edge moves.

This is the de-fusion §10 item 1 calls “the high-risk core; codegen quality (the greedy xmm policy) must not regress.”

13.3 Decomposition (re-narrowing the safe regime)

The naive view is “stage 3 is all benchmark-gated.” It is not — one more slice stays shadow-able:

• 3a — safe: the analysis fixpoint is allocation-independent. The goal was to prove stripping allocation from the analysis pass does not perturb the type + liveness it exists to compute. This splits into two halves:

  • Merge half — already discharged by stage 2. AbstractState::join_entries (state.rs:81) calls AbstractFrame::join, where the stage-2 assertion (self.guarded(i) == join_ty(pre, other)[i]) lives. join_entries is reached from both incoming_context and analyse_backedge_fixpoint (merge.rs:77, 79, 107), and the analysis pre-pass loop_analysis (context.rs:682, codegen_mode:false) drives them. So stage 2 already runs on every analysis-pass merge and every back-edge fixpoint merge; the suite exercises loop JIT and passes 1704/0 with it active. Merge-level type meet is therefore allocation-independent by an assertion that is already live — no duplicate fixpoint harness needed (building one would be disproportionate).
  • Transfer half — by construction, confirmed by the gate. Between merges the fixpoint runs the per-instruction transfer handlers. Their type result is computed from operand Guardeds + IC classes, never from placement (handlers branch on codegen_mode() only to choose emission, e.g. binop_uncached widens to S in analysis — the Guarded it records is the same). A full static shadow of every handler is disproportionate; this half is covered empirically by 3b’s benchmark gate plus the exact CRuby-diff correctness suite (any type-fixpoint perturbation would change output, which the suite catches exactly).

  Net: the safe regime of stage 3 is essentially complete — the merge half is formally asserted (live), the transfer half rests on the handlers’ type/emission split and is confirmed by the gate. The next implementable step is 3b.

• 3b — benchmark-gated: actually strip allocation from the analysis pass. Make loop_analysis (and any other codegen_mode:false walk) call the type-only meet; let the codegen pass allocate from a type-only loop-entry frame. The final asm will differ (the codegen pass no longer inherits the pre-pass’s placements), so the stage-1 placement shadow is expected to diverge and must be scoped off for the codegen_mode:false path. Gate: §13.4.

• 3c — benchmark-gated: improve the allocator with its new global view. Only now is “reuse a predecessor’s register / minimise edge moves” expressible, because the allocator pass can see per-predecessor placements (the BranchEntry states, jitgen.rs:114) instead of the commutative merge. Linear scan over the type/liveness result; spill = today’s try_alloc_fpr phase-1 demotion generalised. Each policy change is an independent benchmark-gated diff.

13.4 The benchmark gate

Baseline must be captured before any 3b change, from a --release build (the debug shadows compile out, so they do not affect it):

1. cargo build --release at the pre-3b commit; record bin/bench numbers and optcarrot fps for the standard set (benchmark/*.rb: app_fib, the binary- trees / so_* set, optcarrot). M1 bin/test already passing is the correctness baseline; the gate adds the speed baseline.
2. Acceptance for promoting 3b/3c to default: no benchmark regresses beyond noise (≈2 %) vs baseline, and the headline JIT benchmarks (optcarrot, app_fib) are within noise or better. A regression that is real and not quickly recoverable parks the change behind a runtime flag (mirroring --no-jit) rather than flipping the default.
3. Run on both backends (x86-64 CI + M1 aarch64) before default-flip, since the bridge emits per-arch and the two backends differ in deopt/recompile handling (x86 recompiles-in-place for non-specialized misses; aarch64 deopts + re-JITs).

13.5 Where the existing harness applies / stops

• Stage-2 type-meet assertion: still valid through 3a/3b — types never depend on allocation, so it keeps guarding the analysis pass after allocation is stripped. Keep it.
• Stage-1 placement replay shadow: valid until 3b — it asserts the recorded stream reproduces the current placements; once the analysis pass stops allocating, the codegen_mode:false path has no placement stream to replay, so the shadow is scoped to the codegen pass only (or retired). It is not a correctness oracle for 3b’s intended divergence.
• Net: 3a is covered by shadows; 3b/3c are covered by the benchmark gate plus the full CRuby-diff suite (output correctness is still an exact oracle — only speed/codegen is what the gate watches).

13.6 Open questions / risks

1. Deopt as a program point. §10 item 2 / §9’s deopt note: once placement is decided in a later pass, a deopt must be reconstructed from the analysis- precomputed placement at that pc, not the frozen AsmDeopt the records carry. 3b can sidestep this only if the codegen pass still decides placement in its own forward walk (it does today) — i.e. 3b strips allocation from analysis but keeps codegen single-walk. Full Layer-② extraction (allocation as a distinct pass feeding codegen) is a later step and is where the deopt-program- point work lands.
2. Loop-entry placement quality. The pre-pass’s allocation currently seeds the loop body with sensible xmm bindings; a type-only fixpoint hands codegen a placement-free entry, so the codegen pass must pick loop-carried xmm bindings itself. This is the most likely source of a 3b regression (loop bodies are the hot JIT path) and is what the optcarrot/app_fib gate specifically watches.
3. Phase-1 demotion as spill. The cross-slot demotion (stage-1 finding) is the allocator’s only spill mechanism today; a linear-scan allocator (3c) subsumes it but must preserve the “stack is canonical, dropping the xmm cache needs no asm” property that makes demotion free.

13.7 §5 stage 3b: landed behind a default-off feature

3b is implemented as the loop-type-only-entry cargo feature (default off, so the shipping build is bit-identical). When on, incoming_context strips the analysis pass’s loop-carried backedge frame to a type-only projection (AbstractState::strip_fpr_to_stack: every F/Sf slot → S(guarded)) before target.join(&backedge), so the codegen pass re-derives the loop-entry xmm bindings itself via the liveness pass (liveness_analysis → use_float’s try_set_new_Sf) instead of inheriting them. This is the minimal, reversible lever for “the codegen pass owns allocation; the analysis pass contributes only types + liveness.”

Verified:

• Default (off): unchanged — the strip is #[cfg]-compiled out; the join takes the placed backedge verbatim.
• Feature on: correct — suite 1704/0 (stage-1/2 shadows active) and the sample programs match CRuby (249750.0, 1249925000.0).
• Codegen neutral on the canonical float loop — emit-asm for the x += i*0.5 while-loop is identical off vs on: the loop-carried accumulator was already Sf (boxed per iteration) in the baseline, and use_float re-promotes it to the same Sf, so the analysis-pass backedge placement was redundant with liveness-driven promotion here. This is the intended behaviour-preserving result — 3b removes the analysis-pass allocation without regressing this hot path.

What 3b does not do: it does not improve the per-iteration box (keeping the float in an xmm across the back-edge is the 3c allocator-policy change). 3b only establishes that de-fusing analysis-pass allocation is codegen-neutral on the canonical case. Cases where liveness-promotion and the analysis backedge diverge (the regression risk surface) are what the broad benchmark A/B on M1 must probe; build --release twice (with/without the feature) and compare bin/bench + optcarrot before considering a default flip / removing the analysis-pass allocation outright.

13.8 §5 stage 3b benchmark verdict: REGRESSION — the analysis-pass backedge is load-bearing

Corrects §13.7. The canonical x += i*0.5 loop produced identical asm off/on, which I wrongly generalised to “codegen neutral.” The real float-heavy benchmarks say otherwise. M1 bin/bench (iter/sec, higher = faster) and an independent x86-64 wall-clock A/B (seconds, lower = faster) both show 3b regressing:

So 3b fails the §13.4 gate (>2% regression on the hot float path). It stays default-off — nothing shipped, and the gate did its job.

The finding (the experiment’s real value). The analysis pre-pass’s backedge placement is load-bearing for float-heavy loops: it captures good loop-carried xmm bindings (floats kept in registers across the back-edge) that liveness-driven re-derivation (use_float) does not recover. The canonical loop was too trivial to show this (its accumulator was already Sf/boxed-per-iteration, so both paths agreed); mandelbrot/nbody carry several live floats across the loop where the fixpoint’s placement genuinely beats a from-scratch use_float pass. This refutes the “backedge placement is redundant with liveness” hypothesis from §13.7.

Consequence for the architecture. De-fusing allocation from the analysis pass cannot simply discard the loop-carried placement and re-derive it from liveness — that information is real and the greedy fixpoint computes it well. The allocator pass (stage 3c / §3 Layer ②) must reconstruct or carry forward at least the quality of the current analysis-pass backedge bindings, i.e. a proper loop-aware allocation (linear-scan with loop-carried liveness), not the liveness-hint promotion use_float does today. The keep-Sf-cache, drop-xmm-free demotion property (stage-1 finding) and the backedge fixpoint together are the bar 3c must clear. Net: 3b is retained as a negative result / regression probe behind its feature flag; the next real step is designing 3c to match-or-beat the backedge, not to replace it with liveness promotion.

14. §5 stage 3c design: a separable allocator that matches the backedge

Stage 3b established the hard constraint: the analysis pre-pass’s loop backedge fixpoint computes loop-carried xmm placements that are load-bearing for tight float loops (mandelbrot 1.9–2.6× slower without them), and a naive liveness-only re-derivation does not recover them. optcarrot was flat base-vs-3b, so the placement quality that matters is localized to tight loops carrying several live floats across the back-edge — that is the regression surface 3c must not touch.

14.1 The realization: loop allocation is already a fixpoint

analyse_backedge_fixpoint (compile/loop_analysis.rs) iterates analyse_loop (≤10 times) until the back-edge AbstractState stops changing (be.equiv). Each iteration runs the per-BB walk with apply_join allocation, so the loop’s placement is the fixed point of the greedy per-merge allocator. The fusion is that this single fixpoint co-evolves types and placements. Stages 2/3a proved the type half is allocation-independent. So the separation is not “remove allocation from the loop” (3b’s mistake) — it is sequence two fixpoints instead of fusing one:

fused today:     one fixpoint over (types + placements)        [analyse_loop ×N]
3c target:       fixpoint-1 over (types + liveness)   — NO placement
                 fixpoint-2 over (placements)         — greedy alloc on fixed types

Because fixpoint-2 runs the same greedy apply_join allocation, just sequenced after type analysis rather than interleaved with it, it converges to the same loop-carried placements — that is what makes the separation behaviour-preserving and shadow-verifiable. 3b failed precisely because it replaced fixpoint-2 with a single use_float liveness hint, not a placement fixpoint.

14.2 Decomposition

• 3c-i — safe / shadow-able: extract the allocation fixpoint as its own pass. Run a type+liveness-only fixpoint first (the §3 Layer-① analysis; the type meet is already join_ty, the liveness is already separate), then run the greedy allocation fixpoint over the frozen types to produce placements. The allocator is now a distinct, pluggable component running today’s greedy policy. Verify with the stage-1 placement replay shadow that the placements equal the fused result, slot-for-slot, including the backedge. No behaviour change — this is the real Layer-② extraction, and the thing 3b should have been. Next implementable step (behind a feature until the shadow is green across the suite + benches).

• 3c-ii — benchmark-gated: swap the greedy fixpoint for linear scan. With the allocator extracted, replace the iterate-to-fixpoint greedy policy with a loop-aware linear-scan over live intervals (below). Gate against the mandelbrot/nbody bar (must match-or-beat the backedge) and optcarrot (must stay flat). Each policy change is an independent gated diff.

14.3 3c-ii allocator shape (the linear-scan)

Inputs (all allocation-independent, already computed by Layer ①):

• per-slot Guarded type at each program point;
• the representation decision kept separate from placement: “this slot is used as f64” (today’s use_float liveness) decides unboxed-float-ness; the allocator then decides which xmm (or spill) — splitting Sf’s two jobs (mark vs register) per §3 Layer ②;
• live intervals per slot, with loop-carried intervals (live across the back-edge) flagged so the scan keeps them resident across the whole loop body — this is what reproduces the backedge’s “float stays in xmm across iterations.”

Output: a placement per (slot, point) + edge moves. The edge moves already exist — AbstractFrame::bridge emits the φ-reconciliation MOV/swap/spill from (pred.mode, target.mode); the allocator only chooses the target registers and the bridge lowers them (so the recently-fixed fpr_swap and the F/Sf/S bridge arms are reused unchanged).

Two properties the scan must preserve (both already in the codebase):

1. Free spill of read-only caches. try_alloc_fpr phase-1 demotes an all-Sf register to S with no asm (stack is canonical). A linear-scan spill of an Sf interval must keep this — spilling a clean float cache costs nothing.
2. Loop-carried priority. The fixpoint today keeps loop-carried floats in xmm by construction; the scan must give intervals that span the back-edge higher priority than intra-loop temporaries when registers are scarce, or it will reintroduce the 3b regression.

14.4 Hard parts carried over

• Deopt as a program point (§10 item 2). Once placement is decided in fixpoint-2, a deopt’s register/stack map must be reconstructed from the allocator’s result at that pc, not the frozen AsmDeopt the transfer records carry today. 3c-i sidesteps this only if fixpoint-2 still emits in a forward walk that knows placements at each pc (it does, today). Full record-driven lowering (goal 1) is where the deopt-program-point work lands.
• Representation vs placement split. Today Sf/F/S bundle “unboxed?” with “which register?”. 3c separates them: liveness marks unboxed-float slots; the allocator assigns registers. The typed IR carries the mark, not the register.

14.5 Why this is the right order

3c-i is the behaviour-preserving separation the whole §5 effort has been building toward (decide/apply split, record stream, type-meet invariant all feed it), and it is shadow-verifiable against the fused result. 3c-ii is the only step that may regress, and it is gated on the exact benchmarks 3b flagged. 3b is retained as the negative-result probe that calibrated the bar: any allocator that cannot match the backedge on mandelbrot/nbody is not ready to land.

14.6 The 3b regression, diagnosed at the asm level (what 3c-ii must reproduce)

Diffing the JIT asm of the mandelbrot kernel (for dummy in 0..ITER with several live floats) base-vs-3b pins the mechanism exactly. do_it grows from 340 → 412 instructions (+21%) under 3b. The delta is not the back-edge box (both box the same loop-carried results); it is the operand loads inside the loop body:

• base keeps the loop-invariant / loop-carried floats (cr, ci, …) resident in xmm across the loop, so each use is a direct movq xmmA,xmmCr; mulsd …:

  movq xmm9,xmm2 ; mulsd xmm9,xmm2      # cr already in xmm2
  

• 3b demotes them to their boxed stack home, so every use re-loads and re-decodes the flonum (~10 insts: tag tests + the sar/add/and/or/rol/movq flonum-decode) before the mulsd:

  mov rdi,[rbp-N]; test rdi,1; jne…; test rdi,2; je…; …; rol rdi,0x3d; movq xmm2,rdi
  movq xmm3,xmm2 ; mulsd xmm3,xmm2
  

Why use_float does not recover it: the inner loop has more simultaneously-live floats than the xmm pool, so the per-entry best-effort try_set_new_Sf promotion loses the race for some of them and they stay boxed — re-decoded every use. The backedge fixpoint instead converges on a stable assignment that keeps the hot floats resident. So the missing quality is not the Sf mark (liveness has it) but the spill choice under pressure.

Spec for 3c-ii, made concrete. The loop-aware linear scan must keep floats whose live interval spans the loop body (loop-invariant operands and loop-carried accumulators) resident in xmm with priority over intra-iteration temporaries, i.e. choose spill victims by furthest next-use across the whole loop — exactly what the backedge fixpoint approximates and what greedy per-entry use_float does not. This is the property §14.3 named, now backed by the asm: optcarrot stayed flat because its hot loops do not exceed the float pool, so the spill choice never bites; mandelbrot/nbody do, so it dominates.

14.7 Negative result: the cheap spill-policy lever does not fix 3b

Tested the simplest 3c-ii lever directly: make use_float’s promotion spill an unboxed float (set_new_Sf → VirtFPReg) instead of leaving it boxed in S when the physical pool is full. No-op — the mandelbrot kernel’s JIT asm was byte-identical to plain 3b (412 insts, same box count). So try_alloc_fpr was already succeeding for the slots use_float touches; the boxed-operand decodes that cause the regression do not originate from use_float’s best-effort fallback. Reverted.

Two refinements this pins down:

1. The regression is specific to for…in loops. A while-loop float kernel (zr/zi loop-carried) produces identical asm base-vs-3b — no regression. mandelbrot/nbody use for…in (inlined, multiple loop_starts within one iseq); that is where the placement divergence lives. The earlier “simple float loop is codegen-neutral” (§13.7) was right and misleading: the neutral case is the while loop; the for…in case is where 3b loses.
2. It is not a local heuristic miss. A point fix to the promotion policy cannot recover it, because the boxed operands are not the ones the promotion pass decides. The analysis-pass backedge fixpoint reaches a globally-consistent loop placement that a single forward use_float pass over a stripped (all-S) entry simply does not reconstruct.

Conclusion — abandon “strip + re-derive” (3b) as the separation mechanism. 3b’s value was diagnostic (it calibrated the bar and proved the backedge is load-bearing). The behaviour-preserving separation is §14.2’s 3c-i: extract the existing allocation fixpoint as its own pass, unchanged, so the placements are identical to today (shadow-verified, zero regression) — not stripped and re-derived. A better policy (3c-ii linear scan) comes only after that seam exists and is benchmark-gated. The loop-type-only-entry feature stays as the negative-result probe.

15. §5 stage 3c-i implementation plan: extract the allocator, unchanged

The behaviour-preserving separation (per §14.7’s conclusion). Surface map of where the JIT allocates an xmm today (outside the merge, which is already decide/apply split):

• operand loads: load_fpr / load_fpr_fixnum / load_binary_fpr / fetch_float_assume (state/read_slot.rs, compile/binary_op.rs) — allocate an xmm for an operand and emit the load (the per-use flonum decode seen in §14.6);
• destination defs: def_F / def_Sf_float (compile/binary_op.rs, method_call.rs, variables.rs, compile.rs);
• the merge: apply_join’s TryFresh* (already isolated, §5 stage 1).

Every one of these funnels through two primitives — SlotState::try_alloc_fpr (phase-0 vacant / phase-1 Sf-demote) and alloc_fpr (+ phase-2 spill). So those two are the universal allocation seam, and the loop-aware spill-victim choice that 3c-ii needs (demote/spill by furthest next-use across the loop, §14.3) lives exactly in phase-1 of try_alloc_fpr.

Increment sequence (each behaviour-identical, suite + stage-1 shadow verified):

1. Extract the register-selection policy into a named alloc_policy unit: try_alloc_fpr / alloc_fpr move out of the SlotState impl into a child module taking &mut SlotState; the methods delegate. No field, no dispatch yet — the seam is the module boundary. This increment.
2. Thread an AllocCtx (the live-interval / loop-membership info 3c-ii’s victim choice needs) into the policy, computed by the existing liveness pass. Default greedy ignores it → identical placements.
3. Add the loop-aware policy (3c-ii) behind the seam: phase-1 picks the victim with the furthest next-use instead of the first all-Sf register; gated on mandelbrot/nbody (match-or-beat backedge) + optcarrot (flat).

The full Layer-② “type-only fixpoint then allocation pass” (un-welding the type computation from the operand-load/def handlers above) is the larger, later arc; 3c-i increments 1–3 deliver the swappable allocator and the measured win first, since that is where the §14.6 regression and the latent base-case back-edge boxing both live.

15.1 Two no-op experiments locate the lever: it is the merge, not the allocator

Increment 1 gave a clean alloc_policy seam, but two targeted experiments behind it both came back byte-identical on the mandelbrot kernel:

• use_float spill fallback (§14.7): promote a pool-full float to an unboxed spill (set_new_Sf) instead of leaving it boxed S. No-op.
• liveness-aware-spill: in try_alloc_fpr phase 1, prefer demoting a clean Sf register whose slots are dead over one still live (using the IsUsed liveness SlotState already carries). No-op (340→340 insts, same decode count).

Two independent per-call allocation levers changing nothing means the per-iteration boxing of loop-carried floats is not decided in alloc_policy or use_float. It is decided at the loop-header merge — decide_join / apply_join choose the loop-carried float’s mode (F pure-xmm vs Sf/S boxed-cache), and that is what the body inherits and re-decodes each iteration (§14.6). The allocator only places what the merge already decided to keep unboxed; it never gets the chance to keep a value the merge boxed.

Redirect for 3c-ii. The lever is the loop-header join’s float placement: why the meet demotes a loop-carried F to Sf/S instead of keeping it F. That is in the already-split decide_join table (the F/F, F/Sf, F/S arms) — and it governs both the 3b regression and the latent base-case back-edge box. Increment 1’s alloc_policy seam stays as valid structural cleanup, but 3c-ii’s measured win must come from the join arms, not the spill policy. The next concrete step is to read the loop-header join decision for a loop-carried float and determine whether keeping it F across the back-edge (no boxed cache) is sound and cheaper.

15.2 jit-debug confirms: loop-carried floats can be F; pressure forces S

jit-debug on the float kernel shows the same loop compiled two ways:

• one specialization keeps the loop-carried floats F(FPReg0) / F(FPReg1) — pure xmm, no per-iteration box, back-edge is an xmm move;
• another puts them in S(Value) (boxed) while the loop-invariant operands take the physical pool as Sf — so the loop-carried values lose the pool and box every iteration.

So F for a loop-carried float is achievable and is the good outcome. The S fallback comes from the loop-header join’s C/F arm TryFreshFElseS (join.rs:228) and the F/F arm TryFreshFKeep: both try a fresh/kept xmm and fall back to S only when no physical xmm is free. The per-iteration box is exactly that fallback firing under register pressure — the loop-carried value losing the pool to other live values.

This closes the diagnosis loop: every lever (use_float promotion, phase-1 spill victim, join arm) ultimately bottoms out at the same thing — which live values hold the physical pool across the loop. Today that is decided greedily in allocation order; the loop-carried/invariant floats must instead win the pool over short-lived temporaries. There is no cheaper intermediate fix (three no-op probes confirm it). 3c-ii is therefore necessarily the loop-aware linear scan over live intervals of §14.3: rank pool occupancy by interval length / loop membership, not allocation order. The seam (incr. 1) and the calibrated bar (mandelbrot/nbody regress, optcarrot flat) are in place; what remains is the interval analysis + the priority allocator, a substantial standalone implementation.

15.3 CORRECTION: it is not register pressure — the loop-entry merge discards the fixpoint’s F

§15.2’s “register pressure forces the S box” is wrong. Re-verified facts:

• No pressure. The float kernel uses 2 of 14 physical xmm; base mandelbrot uses 10 of 14. The pool is never exhausted.
• Spilling is unboxed by design. alloc_fpr phase-2 (push_spill) hands back a VirtFPReg that lives on the stack as a raw f64 (movsd), never a boxed Value. A spilled float is not re-decoded. So boxing ≠ spilling.

The actual mechanism, from jit-debug on the kernel loop:

fixed: 1 { … [%3(zr): F(FPReg4)] [%4(zi): F(FPReg6)] … }   ← backedge fixpoint: F (good)
target:  { … [%3(zr): S(Value)]  [%4(zi): S(Value)]  … }   ← codegen loop-entry: S (boxed!)

The back-edge fixpoint already computes the loop-carried floats as F (pure xmm) — the right answer. But codegen’s loop-entry target is incoming.join(backedge) (merge.rs), and the forward entry (incoming, the first loop entry from outside) holds the loop-carried float as S — the boxed initial value (zr = 0.0 materialised boxed). decide_join has no S/F arm, so (S, F) falls to the default _ => SetS → S. The merge therefore discards the fixpoint’s F and collapses the whole loop body to boxed, decoding+re-boxing the loop-carried float every iteration — with 12 xmm sitting free.

So the lever is neither the allocator, the spill policy, nor register pressure: it is the loop-entry merge letting the forward entry’s boxed initial value win over the back-edge’s unboxed steady-state placement. The fix is to make the loop header adopt the back-edge’s F/Sf placement for loop-carried floats (a one-time unbox of the forward entry at the pre-header bridge, which the bridge’s S -> F/Sf arms already emit) instead of SetS. This is a loop-header-local change to how incoming_context builds the target, not a new allocator — and it fixes the latent base-case box, not just the 3b regression. (The earlier no-op probes were no-ops precisely because they targeted the allocator/promotion, while the value was being boxed by the merge upstream of them.)

15.4 Prototype result: the box CAN be eliminated, but it is blocked by a TYPE loss, not placement

Prototyped the §15.3 fix (loop-keep-float): a new S -> F (and Sf -> F) bridge arm + keep_backedge_floats, which re-adopts the back-edge fixpoint’s F for loop-carried floats the loop-entry merge collapsed.

• Concept proven (x86-64). With an unguarded promotion, the mandelbrot do_it loses all boxing: call float_to_value count 16 → 0, the inner-loop body becomes pure xmm (movq xmm,xmm; mulsd), and the per-iteration flonum-decode moves to a single pre-header unbox. The optimisation is real.
• But it is unsound as written, and that exposed the actual blocker. The loop-carried float is typed S(Value) at the loop-entry merge, not S(Float) (verified in jit-debug: the pre-header forward entry holds %3: S(Value) even though it is zr = 0.0). The fixpoint correctly has it as F (Float); the codegen merge SetS(join(Value, Float)) = Value degrades it. Forcing F on a Value-typed slot then panics at the C(non-float) -> F bridge (a different slot that genuinely is a non-float const in some path) — and would be silently wrong for any slot that is actually sometimes non-float, since an F slot carries no runtime guard.
• The sound guard (guarded == Float) makes it a no-op, because the loop-carried floats are Value-typed: suite 1704/0, but mandelbrot is byte- identical to base (340/16). The placement fix has nothing to act on until the type is Float.

So the lever is the type analysis, not placement or allocation. A loop-carried pure float (zr = 0.0 then float arithmetic) is typed Value at the loop-entry merge instead of Float; fix that precision loss and the (already-prototyped, sound) guarded == Float promotion fires and removes the box — on the shipping build, not just under 3b. This also finally explains the whole §15 thread: every allocator/placement lever was downstream of a value the type meet had already widened to Value. The loop-keep-float feature (default off, 1704/0) and the S -> F / Sf -> F bridge arms are kept as the staging ground; the next step is the loop-carried-float type precision fix. (aarch64 unverified here — no cross toolchain in this container; the new bridge arms reuse float_to_fpr / fpr_move, which both backends already lower, so they are arch-neutral by construction, but this needs an M1 bin/test to confirm.)

15.5 Root cause + sound fix: loop-JIT conservative entry typing

The “type loss” is not a literal-handling bug. jit-debug on a loop-JIT (start:[:loop_start]) shows the loop-entry forward state has every local as S(Value) — because a loop JIT does not see the values produced before the loop (x = 0.0 ran in the VM). So a loop-carried float necessarily enters from the VM as a conservative boxed S(Value), even though the back-edge fixpoint proves it is a Float (F). The merge join(S(Value), F) → S(Value) then forces the body to decode+rebox it every iteration (§15.3/§15.4).

Sound fix (loop-keep-float, suite 1704/0, default-off). At the loop header, adopt the back-edge fixpoint’s F for such a slot. The forward entry is unboxed once at the pre-header by the new S -> F bridge arm, whose float_to_fpr carries the runtime float guard (deopt if the VM value is not a float) — so the specialization is sound for a runtime value. Soundness across all predecessors is enforced by keep_backedge_floats’s promotable(i) gate: promote only when every predecessor entry has a valid _ -> F bridge (F/S/Sf/float-C); a non-float-C path is genuinely not a float, so it is left boxed (this is the gate the earlier guarded == Float over-approximated, which made it a no-op — §15.4).

Result on the mandelbrot kernel: call float_to_value 16 → 0, the hot inner loop becomes pure xmm, and the per-iteration flonum decode collapses to a single guarded pre-header unbox. Correct on the whole suite (1704/0), including the fpr_swap/bridge regression cases. Static do_it grows 340 → 450 (the decodes move to the per-loop-entry pre-headers), so the win is dynamic (hot loop) — to be confirmed by an M1 --release bench A/B (and aarch64, which reuses the same float_to_fpr/fpr_move AsmIR ops). This is the first measured improvement over base in the §5 line, and it lands as a guarded loop-entry type specialization — the same shape YJIT uses — rather than a new allocator.

15.6 Confirmed on both arches

M1 (bin/bench, i/s) base vs loop-keep-float: mandelbrot 24.326 → 27.372 (+12.5 %), everything else flat (fib/nbody/aobench/bf/nqueen/sudoku within noise). Matches the x86-64 local --release result (mandelbrot ~0.80 s → ~0.70 s, ~12 %). So the guarded loop-entry float specialization is a real, arch-neutral win (the S -> F / Sf -> F bridge arms reuse float_to_fpr / fpr_move, which both backends already lower — confirmed on aarch64). fib -1.6 % is noise: fib has no float loop, so keep_backedge_floats never fires and its codegen is byte-identical.

Remaining before default-on: a full bin/bench incl. optcarrot (headline) and the other float loops (matmul/bedcov, which may also improve), confirming no regression; then flip the cargo default to include the feature (and fold the S -> F / Sf -> F bridge arms in unconditionally, as they are general-purpose).

15.7 Landed: default-on

Bench gate cleared on both arches, so the loop-entry float specialization is now default (no feature flag): mandelbrot +12.5 %, matmul +2.4 %, optcarrot 184.8 → 186.2 fps (checksum unchanged, 59662), everything else flat, no regressions; suite 1705/0, mandelbrot do_it call float_to_value 0 in the default build. keep_backedge_floats + the predecessor-gated promotion in incoming_context, and the S -> F / Sf -> F bridge arms, are now unconditional. The two experimental features (loop-keep-float, loop-type-only-entry) and the dead strip_fpr_to_stack probe are removed; loop-type-only-entry’s lesson (the analysis-pass backedge is load-bearing — a naive type-only strip regresses 2.5×) is retained in §13–14 as the calibration that led here. Added test_loop_carried_float_kept_unboxed.

15.8 §5 stage 3c-i increment 2: the allocator consults an explicit AllocCtx

Increment 1 (§15, commit 37ac994) extracted the two universal xmm-allocation primitives into the alloc_policy module. Increment 2 takes the next planned step: thread an explicit AllocCtx into the policy so the spill-victim decision consults a named analysis-facts input instead of reaching into the fused SlotState ad hoc — the structural shape the Layer-② allocator needs.

Concretely, try_alloc_fpr phase 1 (“demote the first xmm whose linked slots are all Sf”) is refactored from a for 0..len { … return first } scan into

#![allow(unused)]
fn main() {
candidates.min_by_key(|&xmm| ctx.victim_rank(xmm))
}

The default AllocCtx::victim_rank is the physical-pool index, so min_by_key selects the same lowest-index register the prior scan returned — placements are byte-identical. Phase 0 (vacant) and phase 2 (spill) are policy-invariant and unchanged. This is exactly the seam 3c-ii’s loop-aware policy plugs in: victim_rank becomes a furthest-next-use / non-loop-carried key fed by the live-interval + loop-membership fields AllocCtx will carry, and no allocation call site changes (operand loads, defs, and the merge’s apply_join all funnel through set_new_*/try_set_new_* → these two primitives).

Verified behaviour-identical. Built under stress-spill-pool (forces PHYS_FPR_POOL to 2, so almost every Float-resident slot is driven through the phase-1 demote path this refactor touches) and ran the lib suite with and without the change: the pass/fail set is identical — 1671 passed; the 34 failures are the pre-existing environment mismatches (CRuby version / timezone / missing bigdecimal gem), present in both runs, the only diff being the wall-clock line. So the refactor exercises the touched path under maximal pressure and does not perturb a single placement.

Honest scope note. §15.1’s two no-op probes already established that a per-call spill-victim change is neutral on mandelbrot — the per-iteration box was the merge discarding the fixpoint’s F (fixed in §15.5–15.7), not the allocator’s victim order. So increment 3’s measured win is likely small or subsumed by the shipped merge fix; the value of increments 2–3 is the structural separation (a swappable allocator fed by an explicit analysis-facts input, decoupled from the placement state), not a fresh benchmark delta. The remaining headline §5 arc stays the larger Layer-② extraction (§4 step 2): a type-only + liveness fixpoint feeding a distinct allocation/lowering pass, which is where “abstract interpretation + fixpoint search” is finally, fully separated from physical register allocation.

15.9 Closing the allocator-policy axis: phase 1 already protects every F

A precise reading of try_alloc_fpr (the universal allocation seam, §15) settles why every spill-victim probe in this thread (§14.7, §15.1’s two no-ops) came back neutral — and retires the 3c-ii “loop-aware victim” line as a performance lever:

• Phase 1 demotes only an all-Sf register. It scans for an xmm whose linked slots are all Sf (Integer-def’d / Float-use’d, kept coerced — the stack already holds the canonical boxed value), demotes them to S, and reuses the freed xmm. The demote emits no asm (the stack is canonical) and the value reloads lazily on its next float use. An xmm holding any F slot is skipped.
• An F (pure unboxed float) therefore never loses its xmm to phase 1, and when the pool is genuinely full, phase 2 (push_spill) hands back a VirtFPReg that lives on the stack as a raw f64 (movsd), still unboxed (§15.3). So no allocation decision ever boxes an F.

Consequently the only freedom the victim policy has is which already-Sf cache to drop — a free, reversible, lazily-reloaded choice among loop-invariant coerced operands. That cannot change the count of per-iteration boxes, which is why §15.1’s dead-vs-live probe and §14.7’s spill-fallback were both byte-for-byte no-ops. The per-iteration box was always upstream — the merge deciding a loop-carried value’s representation (F vs Sf vs S), fixed in §15.5–15.7 by adopting the back-edge’s F at the loop header.

Verdict. The allocator-policy axis (3c-i increment 3 / 3c-ii furthest-next-use) is closed as a performance lever: it is provably neutral by the phase-1 all-Sf restriction. The AllocCtx seam (increment 2) is retained, but its justification is corrected: it exists for goal 3 (§3 Layer ②) — plugging in a different allocation strategy, namely the VM-residual allocator’s fixed “no pool, every value in its stack home” convention — not a better JIT victim rank.

Where the §5 work goes from here. With the merge-representation lever shipped (§15.7) and the allocator-policy lever shown neutral (this section), the remaining separation is purely structural, not perf-seeking: the Layer-② extraction (§4 step 2) — run the Guarded + liveness fixpoint as a standalone, allocation-free pass producing a typed IR, then a distinct allocation/lowering pass consumes it. That is the last place “abstract interpretation + fixpoint search” and “physical register allocation” remain interleaved (in the single forward codegen walk). It is behaviour-preserving by intent (same final placements) but a large structural change, and the one remaining benchmark-gated risk is the loop-entry placement quality the analysis pre-pass currently seeds (§13.8) — now partly de-risked because §15.7’s keep_backedge_floats already reconstructs the load-bearing loop-carried-F placement at the loop header from the back-edge frame.

16. Layer-② extraction: the concrete increment plan

§15 closed the performance line: the merge-representation lever shipped (§15.7) and the allocator-policy lever is provably neutral (§15.9). What remains is the structural separation goal — §4 step 2 / §3 Layer ② — and it is now the only place “abstract interpretation + fixpoint search” and “physical register allocation” are still interleaved: the single forward codegen walk, and the loop analysis pre-pass that allocates while it computes types + liveness.

16.1 The target and the blocker

Target. The analysis pass computes types + liveness only (no xmm allocation), producing a typed IR; a distinct allocation/lowering pass consumes it. The fixpoint searches over Guarded types (stage-2-proven allocation-independent); placement becomes a separate layer.

Blocker (why 3b regressed 2.5×, §13.8). The analysis pre-pass’s allocation is not dead — it computes the loop-carried placement (the back-edge frame), which the codegen pass consumes in two places:

• (a) float adoption — keep_backedge_floats reads backedge.mode(i) == F (§15.7);
• (b) placement reconciliation — target.join(backedge) folds the back-edge placement into the loop-entry target (the φ/edge-move seed).

Naively stripping the allocation (3b) forced codegen to re-derive (a)+(b) from liveness alone, which is worse — hence the regression.

16.2 Strategy: decouple the consumers, then strip

Reroute each consumer of the analysis-pass placement to read the analysis-pass types + liveness instead (both allocation-free, stage-2-proven). When every consumer reads only types+liveness, the analysis-pass allocation has no consumer and can be removed — at which point the analysis pass is the pure Layer-① pass.

Each increment is correctness-verified by the exact CRuby-diff suite here; the behaviour-changing ones (L2-1/2/3) are benchmark-gated on M1 (mandelbrot / nbody / optcarrot, no >2 % regression, §13.4) before any default flip. The order keeps the high-risk placement reconstruction (L2-2) behind the cheap, well-understood float decoupling (L2-1), and the irreversible analysis-pass strip (L2-3) last.

16.3 L2-0 landed (this step)

keep_backedge_floats no longer hard-codes the adoption condition: it takes an adopt: impl Fn(SlotId) -> bool policy from the caller and applies the mechanism (“adopt F for a loop-carried slot the boxed loop-entry left S/Sf, when a physical xmm is free”). incoming_context supplies the current placement-based policy (be.mode(i) == F), so the result is byte-identical — but the representation decision is now a named, swappable policy at the call site, exactly the Layer-② seam L2-1 plugs the type+liveness policy into. Suite green.

16.4 L2-1 landed behind layer2-float-by-type (benchmark probe + a design finding)

L2-1 swaps consumer (a)’s adoption policy from placement (be.mode(i) == F) to the allocation-free type + liveness signal (be.is_float_typed(i) ∧ the slot is in Liveness::loop_used_as_float), behind a default-off feature so the shipping build stays byte-identical.

Verified:

• Default (off): byte-identical — the type policy is #[cfg]-compiled out.
• Feature on: correct — full lib suite identical to baseline (1671 passed; the 34 failures are the pre-existing env mismatches), so the CRuby-diff oracle holds: the type policy never produces a wrong result.
• It is not a no-op — emit-asm on the canonical loop-carried-float kernel (x = x*1.5 + i*0.5; y = y - x*0.25) differs (code 347 → 379 bytes, ~176 normalised asm lines). Both keep the hot loop body at zero boxing (float_to_value count 0 either way — §15.7 already won that); the diff is entirely in the pre-header.

Design finding (why L2-1 is a probe, not an obvious win). The type+liveness policy promotes the superset “Float-typed ∧ used-as-float,” whereas the placement policy promotes exactly the floats the back-edge fixpoint chose to keep in F. On the no-pressure kernel the superset is strictly larger, so L2-1 adds pre-header unboxes that buy nothing in the body — a mild regression risk. In other words, consumer (a) has the same load-bearing-placement property §13.8 found for consumer (b): the fixpoint’s F-selection is real information, and a naive type+liveness re-derivation over-approximates it. try_set_new_F’s self-limiting (promote only when a physical xmm is free) bounds the damage but does not restore the selectivity.

Consequence for the plan. A quality-preserving consumer-(a) decoupling must carry the fixpoint’s per-slot F-preference forward as an explicit allocation-free annotation on the typed IR (a derived bit computed during the fixpoint), not re-derive it from type ∧ liveness. That annotation is the same object L2-2 needs for consumer (b) — so L2-1 and L2-2 share one missing piece: a loop-carried-F preference set produced by the analysis pass as typed-IR metadata (distinct from the live xmm placement). L2-1 stays a default-off benchmark probe (mirroring loop-type-only-entry in §13.8) until the M1 mandelbrot / nbody / optcarrot A/B says whether the superset is neutral in practice; the likely outcome, per this finding, is that the next real increment is the F-preference annotation, after which both consumers decouple cleanly.

16.5 Sharpening §16.4: the F-selection is allocation — the real fork

§16.4 floated carrying the fixpoint’s F-preference forward as an “allocation-free annotation (a bit computed during the fixpoint).” That phrasing is imprecise and worth correcting, because it changes what L2-1’s bench actually decides.

Two facts settle it:

1. Consumer (a) already reads the analysis output, not the live codegen placement. incoming_context derives the adoption set from loop_info(bbid)’s stored back-edge frame (be.mode(i) == F) — the analysis pre-pass’s result, cloned into backedge_for_floats. So the dependency we are trying to remove is specifically on the back-edge frame’s F-placement.
2. That F-placement is produced by allocation, and §13.8 proved the selection is load-bearing (liveness re-derivation regresses 2.5×). The fixpoint chooses which Float-typed, used-as-float slots win the limited pool — and that choice is a register-allocation decision, not a type/liveness fact.

So a “bit computed during the fixpoint” is just be.mode(i) == F renamed: it still requires the analysis pass to allocate. There is no allocation-free annotation that reproduces the selection byte-for-byte — the selection is allocation.

The real fork L2-1’s M1 bench decides:

• (i) Approximate, allocation-free — accept L2-1’s type ∧ liveness superset (and let try_set_new_F’s self-limit bound the over-promotion). If the mandelbrot / nbody / optcarrot A/B is within noise, this is the consumer-(a) decoupling: the analysis pass no longer needs to allocate for consumer (a).
• (ii) Exact, allocation-bearing — if L2-1 regresses (the §16.4 over-promotion finding predicts a mild one), the F-selection genuinely needs allocation quality, so consumer (a) cannot be decoupled in isolation. It folds into L2-2: the codegen-side loop-aware allocator reproduces the fixpoint’s selection (a real linear scan over the loop’s live intervals), and that pass owns the F choice for both consumers (a) and (b) at once.

Either way the next concrete action is the L2-1 A/B on M1; its result picks (i) vs (ii) and is the first hard data on whether the loop-carried F-selection can be made allocation-free at all. (This supersedes §16.4’s “shared F-preference annotation” as the immediate next step — there is no such free annotation; there is a bench that tells us whether we need the L2-2 allocator.)

16.6 L2-1 bench verdict (x86-64): REGRESSION — path (ii) confirmed

x86-64 --release wall-clock A/B (default vs layer2-float-by-type, steady-state median of 6/5 runs, seconds, lower = faster):

L2-1 fails the §13.4 gate (>2 %) on both float loops — exactly the §16.4 over-promotion prediction, now measured. So §16.5’s fork resolves to (ii): the loop-carried F-selection genuinely needs allocation quality; the allocation-free type ∧ liveness superset cannot reproduce it (it promotes loop-invariant / fixpoint-rejected floats, adding pre-header unboxes that cost without body benefit). L2-1 stays default-off as a negative-result probe (mirroring loop-type-only-entry, §13.8), and keep_backedge_floats’s L2-0 mechanism/policy split is retained as the clean seam.

What this proves. This is the second empirical confirmation — after §13.8 for consumer (b) — that the greedy fixpoint’s loop-carried-F selection is load-bearing and not reproducible allocation-free. Both consumers (a) and (b) need it. So decoupling them is not “read types instead of placement”; it requires a codegen-side loop-aware allocator that reproduces the fixpoint’s selection (L2-2). And critically, since the fixpoint’s greedy selection is already good (§15.9: it never boxes an F; §15.7 shipped the merge win), L2-2 is parity at best on perf — its sole payoff is the goal-3 enabler (a swappable allocator for VM-residual codegen / the unified DSL), at real reimplementation risk (it must match the greedy fixpoint byte-for-byte on the hot float loops or regress).

Strategic state of the §5 line. The perf wins are shipped (§15.7) and the two remaining fusion points (consumer (a) here, consumer (b) §13.8) are both proven to need allocation quality. The separation is therefore complete as far as it pays for itself: what remains (L2-2/L2-3 — reimplement the greedy loop-carried selection as a standalone allocation pass, then strip the analysis-pass allocation) is a large, perf-neutral, regression-risky refactor whose only return is the research-grade goal-3. That is a deliberate investment decision, not an incremental win — recorded here so the call is explicit rather than drifted into.

17. L2-2 design: the swappable allocator for goal 3 (the right scoping)

The user chose to invest in L2-2 for goal 3 (VM-residual codegen / the unified interpreter-JIT DSL). The first design task is scoping it correctly, because the naïve scope hits the §16.6 wall and goal 3 does not require crossing it.

17.1 Key reframing: goal 3 does not need to reproduce the fixpoint’s selection

§16.6 proved that reproducing the JIT fixpoint’s loop-carried-F selection allocation-free is hard (it is greedy/emergent) and perf-neutral. But that is the requirement of §4-step-2 for the JIT (eliminate the JIT’s own fixpoint), which is not goal 3. Goal 3 needs a swappable allocation strategy so a different policy plugs in; the JIT keeps its fixpoint as the default strategy. Two strategies:

• JitGreedy (default) — today’s behaviour: the xmm pool + the greedy fixpoint selection (F/Sf where profitable, S otherwise). Must stay byte-identical.
• VmResidual — the VM’s fixed convention: no pool, no unboxed representation; every value lives boxed in its stack home (S). There is no selection problem here — it is the trivial “always S” policy. This is the residual the partial-evaluator emits for the VM (⊤ types, no IC narrowing).

So L2-2 is not “reimplement the fixpoint’s selection.” It is “thread an allocation strategy through the representation/placement decisions; default JitGreedy (byte-identical); add VmResidual.” The §16.6 reproduction problem is sidestepped — the JIT keeps its fixpoint.

17.2 Where the strategy must be consulted

VmResidual is a representation-level decision, not just a pool-size knob: it must prevent any F/Sf from being created, so every value stays S. The sites that create an unboxed float representation, and what each does under VmResidual:

The try_* and merge sites are easy (they already have a “stay S” fallback). The hard one is def_F: a float binary op currently commits to F and emits xmm arithmetic. Under VmResidual the same handler must emit the boxed path (the VM’s float + float → boxed Float). That is exactly generating VM-equivalent code — the goal-3 payoff — and it touches every float-op handler. So the bulk of L2-2 is giving the float-op handlers a VmResidual lowering, gated so JitGreedy is untouched.

17.3 Increment plan (each JitGreedy-byte-identical; M1-gated)

• L2-2.1 — define AllocStrategy { JitGreedy, VmResidual } and thread it on AllocCtx (default JitGreedy). Route the easy sites (try_set_new_*, use_float, the merge TryFresh*/keep_backedge_floats) through it: under VmResidual they skip xmm creation. JitGreedy byte-identical. VmResidual not yet constructed (so float-op handlers still def_F — incomplete, but the representation seam exists and is exercised by a unit smoke test).
• L2-2.2 — give the float-op handlers (binop_float, gen_cmp_float, the unary/def_F consumers) a VmResidual boxed lowering, selected by the strategy. This is the bulk; JitGreedy path unchanged at each.
• L2-2.3 — goal-3 spike: drive a VmResidual codegen for one float bytecode and validate its output equals the VM’s, end to end.
• L2-3 (separate, optional, not goal 3) — only if we later want the JIT fixpoint gone: the §16.6 loop-aware reproduction. Parked behind goal 3.

This order delivers goal 3’s swappable allocator without paying the §16.6 cost, and keeps every step a JitGreedy-byte-identical, M1-benchable diff. L2-2.1 is the next code increment.

17.4 Deferred: goal-3 / VmResidual not pursued now (per user)

Per the user, VM support is not needed at this point, so the goal-3 / VmResidual direction designed in §17.1–17.3 is deferred. The L2-2.1 code (the AllocStrategy { JitGreedy, VmResidual } enum, the SlotState.alloc_strategy field, the try_alloc_fpr VM gate, and the force-vm-residual validation feature) has been reverted to keep the tree focused on the JIT. §17.1–17.3 remain as the record of the goal-3 plan for whenever VM-residual codegen is revisited.

Refocus. The active goal returns to the JIT-internal, behaviour-preserving separation of “abstract interpretation + fixpoint” from “physical register allocation” — §4 step 2 done as a structural refactor that preserves the current greedy placement, not the VM application. Consequence of deferring goal 3: the deepest remaining separation (un-welding the per-instruction handlers’ type/representation decision from their allocation+emission — e.g. binop_float = load_binary_ret_fpr (alloc) + fpr_binop (emit)) loses its near-term functional payoff (it was the enabler for the swappable VM allocator). What is already done de-fuses the merge and the allocation seam (data-model split place/ty, alloc_policy/AllocCtx, decide_join/apply_join, the keep_backedge_floats mechanism/policy split); the remaining handler-level un-welding is a large, IR-introducing refactor whose value, with goal 3 deferred, is architectural cleanliness rather than a feature. That trade-off is the open decision.

18. Handler-level separation (JIT-internal, behaviour-preserving)

With goal-3 deferred (§17.4), the remaining fusion is inside the per-instruction handlers: each float-op handler interleaves the type/representation decision (what the result is, what representation) with allocation (which xmm) and emission (the AsmInst). Un-welding these — behaviour-preserving, the current greedy placement unchanged — is the last structural step of §4-step-2 done as a refactor.

18.1 The template: decision (Layer-①) vs execution (Layer-②), on binop_float

binop_float is split into a pure decision and an execution:

• plan_binop_float(&self, …) -> FloatBinOpPlan — a pure, &self, allocation-free function (Layer-①): it decides Fold(f64) (both operands const floats, result a flonum immediate) vs FprOp, without allocating an xmm or emitting.
• binop_float — executes the plan (Layer-②): Fold → def_C_float (a pure constant, no xmm); FprOp → load_binary_ret_fpr (alloc) + fpr_binop (emit).

What this concretely fixes: the original folded the decision and a side effect together — … && self.def_C_float(dst, result) put the constant definition inside the if condition (the fold “succeeded” only if def_C_float mutated the slot). The split lifts the flonum-representability check into the pure plan_* (Immediate::flonum(result).is_some()) so the decision is a value with no side effect, and the definition happens only in the execute half. Behaviour-identical (suite 1671 passed, baseline-identical failure set; the 34 are the env mismatches).

18.2 Scope: the fold decision separates cleanly; the xmm path needs a virtual-operand IR

This lifts out the fold decision (a pure Layer-① constant). The FprOp execution still fuses allocation and emission internally: load_binary_ret_fpr both allocates an xmm per operand/dest and emits the load, with the xmm identities threading through (operand pins, dst == lhs aliasing). Separating alloc from emit there requires a virtual-operand IR — the float op recorded with slot operands, lowered to physical xmm by a distinct allocation pass — because the allocation produces the operands the emission consumes. That is the substantial next step; this increment establishes the decision/execution seam and the FloatBinOpPlan value that a virtual-operand lowering would carry. The same plan_*/execute shape applies to the other handlers that fold-or-emit (gen_cmp_*, binop_integer) as they are migrated.

18.3 Correction: the FprOp alloc/emit is already split (§9/§11); (b) is record-driven lowering

§18.2 claimed the FprOp path “still fuses allocation and emission internally.” Tracing it precisely, that is wrong — the primitive-level split is already done by the §9/§11 transfer work:

• load_fpr / load_fpr_fixnum are each (*_state) + transfer(TransferIR::…): the state half (load_fpr_state) allocates the xmm and binds the slot (pure abstract-state mutation, no emission); the record (TransferIR::FprLoad, carrying its deopt as a DeoptPoint program point) is what emits. transfer() collects the record into self.transfers and (today) emits it inline, with a debug shadow check proving the record replays to the identical AsmInst/SideExit — i.e. the record is self-contained.
• def_F (the dst) is pure allocation (no emission); fpr_binop is pure emission (no allocation — its operands are already placed).

So in binop_float’s FprOp arm, every call is either allocation (state) or emission (a record / a pure AsmInst); they are not fused, only sequenced. And the handler already consumes virtual operands (FBinOpInfo = slots) and produces physical xmm — it is a virtual→physical lowering. §18.2’s “needs a virtual-operand IR” mis-stated the situation.

What (b) actually is: record-driven lowering (the deferred two-pass). The transfer records are collected but not yet consumed — emission still happens inline during the analysis/allocation walk. The remaining separation is to make emission a distinct pass that replays the record stream, instead of emitting inline. The records already carry everything needed (deopt program points; physical regs assigned during the walk), so replay is behaviour-preserving — the §11 shadow proves it per-call.

The one concrete blocker. The stream is not yet complete: transfers (value-movements) are recorded, but operations (fpr_binop, FloatCmp, the integer ops) and dst-defs are emitted directly to inst, outside transfers. A deferred replay of transfers alone would drop the ops and lose their ordering relative to the loads. So the prerequisite for record-driven lowering is a single ordered record stream that includes the operations, after which a pass-2 replay can emit the whole method from records.

Scope honesty. This is a large, global restructure (route all emission through one ordered record stream; then split the codegen walk into collect-then-replay), not an op-by-op behaviour-preserving edit — the value-movement primitives are already split, so the increments left are (i) inert scaffolding (widen the record stream to cover ops, which does nothing until a replay pass exists) or (ii) the replay pass itself (the deferred two-pass). With goal 3 deferred (§17.4), this restructure’s payoff is purely architectural. The boundary of the primitive-level separation has been reached; crossing into the deferred two-pass is the open, large-investment decision.

19. (B) Record-driven lowering: toward a single ordered codegen record

Per the user the goal is clean architectural layering so optimization logic is easy to add. The record stream (TransferIR, built by §9/§11) is the emerging IR layer between the handlers and the AsmIR/machine code. Today it covers value-movement transfers only; operations emit directly to inst, outside the stream (the §18.3 blocker). (B) unifies them into one ordered stream, then makes lowering replay it.

19.1 Step 1: operations join the record stream (float binop)

The first operation routed in: the float binary op. binop_float’s FprOp arm now emits TransferIR::FloatBinOp { kind, lhs, rhs, dst } through transfer() instead of a direct fpr_binop. The record is pure data (Clone, no closure, no abstract-state read), so transfer() collects it into the transfers stream and the debug shadow check replays it to the identical AsmInst — exactly like the transfer records. Behaviour-preserving: lib suite 1671 passed (baseline-identical failure set), zero replay mismatches.

This proves the pattern: data-only operations can join the record stream and be shadow-verified. In analysis mode transfer() skips emission (the op has no state half, and the pass discards its AsmIr), matching the prior behaviour.

19.2 The plan to a replayable stream

1. Migrate the data-only operations to records — float/integer arithmetic and comparison (FloatCmp, IntegerCmp, IntegerBinOp, …). Each: add a record variant, route the handler through transfer(), verify via the shadow check. (This step: float binop.)
2. Generalize the type — once it carries both transfers and ops, rename TransferIR to a unified LowerRecord / CodegenIR; Transfer no longer fits.
3. Handle the closure-carrying ops (inlined calls, C-func trampolines): these variants of AsmInst are not Clone (they own FnOnce closures), so they cannot be recorded the same way. Either represent the inlined body as a record sub-stream (data), or keep a move-only escape-hatch variant the replay emits in place. This is the hard part of the unification.
4. Build the replay (lowering) pass — collect the full ordered stream during the codegen walk, then emit inst by replaying the records, removing the inline emit. The stream becomes the clean IR layer that optimization passes operate on (the goal). Behaviour-preserving by the per-record shadow property.

Each step (1) is behaviour-preserving and shadow/suite-verified; the risk concentrates in (3) and the (4) switch. Starting from the data-only ops keeps the early increments safe while the stream grows toward completeness.

20. (B) De-closuring the array-index codegen

The array integer-index read/assign sites were the densest remaining ir.inline(|gen| …) closures on the hot path. The 8 closures (x86 + aarch64, read + assign, with/without bounds info) became typed data records AsmInst::ArrayIndex / ArrayIndexAssign (carrying an ArrayIndexKind), with the moved closure bodies living in per-arch gen_array_index / gen_array_index_assign. The two array_integer_index{,_assign} builders in jitgen/compile/index.rs are now cfg-gated twins that just ir.push the same arch-neutral variant.

This is independently valuable (it removes opaque closures from inst, making those ops inspectable by any pass over the stream) and is the concrete precedent for §19’s step (3): a closure-carrying op can be turned into inspectable data when its body is arch-uniform enough. Behaviour-preserving (lib suite identical, zero replay mismatches). Commit 818c15c.

21. The realization: inst already is the replayable stream — add the seam

§19.2’s step (4) sketched a move-based rewrite — records own the AsmInsts, a replay pass rebuilds inst — as the way to reach “a clean IR layer optimization passes operate on”. That rewrite is unnecessary: inst: Vec<AsmInst> is already the ordered, replayable stream. Handlers build it during the analysis/codegen walk (traceir_to_asmir); Codegen::gen_machine_code replays it afterwards to emit machine code (compile_asmir, one match arm per AsmInst). The hot ops are already typed variants in it (FloatBinOp, IntegerBinOp, IntegerCmp, ArrayIndex, … — §19/§20), directly inspectable.

So Path 2’s actual goal — a place to add optimization logic over a typed, arch-neutral instruction stream — is reached simply by adding an optimization hook over inst between AsmIR construction and emission, not by the §19.2(4) rewrite, and not by making AsmInst: Clone (blocked anyway: ~52 inline-builtin closures across the builtins/*.rs use ir.inline, not the 8 array-index sites).

21.1 The seam

AsmIr::optimize_peephole(&mut self) -> usize (in asmir.rs, where inst is private) runs peephole passes over a block’s stream and returns the count removed. gen_machine_code calls it just after frame.detach_ir() — over every main block and every inline/outline bridge AsmIr — before the emission loop. Optimizing the bridges before thread_empty_outline_bridges lets one that collapses to nothing be jump-threaded away as usual.

Soundness of dropping instructions here: branch targets are labels (JitLabel); deopt targets index the side_exit vec (AsmEvict / AsmDeopt), never inst positions. So removing an instruction cannot perturb control-flow or deopt resolution. (BcIndex source-map markers are likewise emission-time, not position-indexed.) No block can be emptied by the pass — each carries a leading Label — so live_bb / is_empty accounting is unaffected.

21.2 Pass 1: self-move elimination

AsmInst::is_self_move flags RegMove(r, r) / FprMove(r, r) (dst == src); the pass retains the rest. A self-move is inert (mov r, r does not even set flags; movapd x, x is a no-op). Under the jit-log feature the call site prints the removed count.

Observed: across the lib suite and the benchmarks (app_fib, so_nbody, app_aobench, …) the count is 0 — the allocator does not currently emit self-moves (its move-insertion guards against src == dst). That is the expected “safe first pass that rarely fires”; the seam is the deliverable — the typed stream now has a layer boundary where real passes (peephole arithmetic identities, dead FprSave-pair removal, redundant load/store elision) attach with no further plumbing. Behaviour-preserving: lib suite 1705 passed, 0 failed (this environment’s CRuby-4.0.2 baseline), zero transfer() replay mismatches.

22. The ①/②/③ reframing and the PhysMap seam (phase-0/1)

A fresh framing of the whole §5 effort, stated as three phases:

① abstract interpretation + fixpoint subtyping and assignment to virtual registers (types + liveness + representation + a virtual FP register per value); ② physical register allocation (virtual → the 14-wide xmm pool ∪ spill slots); ③ machine-code generation.

This is a better cut than §3’s “analysis with NO locations vs allocation+lowering” because it puts the representation decision in ①, which dissolves the wall §13.8 and §16.6 hit twice.

22.1 Why this cut dissolves the §13.8/§16.6 wall

Those sections proved the fixpoint’s loop-carried-F selection is load-bearing and not reproducible allocation-free (a liveness re-derivation regresses 2.5×). But that “selection” fuses two decisions:

• (A) representation — is a value unboxed (F/Sf) or boxed (S)? This is the load-bearing part (§14.6: boxing → a ~10-inst flonum decode every use).
• (B) physical placement — which xmm, and who spills under pressure? §15.9 proved this is perf-neutral (phase-1 only demotes all-Sf caches; an F is never boxed; pool overflow spills F as raw f64, never re-decoded).

The ①/②/③ cut keeps (A) in ① (the fixpoint, unchanged) and moves only the perf-neutral (B) into ②. We never try to reproduce the selection allocation-free — that was the 3b/L2-1 mistake. So the regression driver (boxing) is structurally absent from ②.

22.2 The f64-spill axiom (②’s cost model)

The defining Float constraint — boxing/unboxing is expensive, so an overflowing unboxed float spills as f64 rather than boxing — fixes ②’s spill cost model and its vocabulary. ② may place a value in {physical xmm, raw-f64 spill slot, or (for an Sf cache) drop-the-cache}; boxing an F is not in ②’s vocabulary:

The worst case ② can produce is therefore a movsd (or one decode for an Sf cache), never the per-use decode storm that sank 3b — the downside is capped by construction. Re-cast in canonical/cache terms, the three LinkModes split cleanly across the layers: F = unboxed-canonical (① picks it; ② places it in xmm or f64-spill); S/Sf = boxed-canonical-with-optional-cache (① marks “float-used / cache-eligible”; ② decides whether the coercion cache is materialised in an xmm (Sf) or dropped (S)).

Key soundness fact. Because pressure never changes representation today (§15.9: spill ≠ box), F/Sf/S counts are already pressure-independent — which is exactly the precondition that lets “representation in ①, placement in ②” be behaviour-preserving. (Open check before P2: confirm the “Sf canonical = boxed” premise holds across all arms, incl. keep_backedge_floats’s Sf→F promotion, §15.7.)

22.3 The linchpin: decouple FPReg from its physical slot

The one structural blocker is that FPReg(usize) conflates the virtual id with the physical slot: loc() was id < PHYS_FPR_POOL ? xmm(id+2) : spill, so the pool-vs-spill decision is the FPReg number, chosen greedily inside the ① fixpoint by try_alloc_fpr. (This corrects §1’s “FPReg is already a virtual register” — it is pool-number-encoded, not a true virtual register.) The fix is a PhysMap: FPReg → FPRegLoc produced by ②; ① assigns unbounded virtual FPRegs, ② maps them to physical, ③ resolves through the map.

22.4 Increment plan

22.5 P0/P1 landed

PhysMap is the lone FPReg → FPRegLoc resolver; all 22 arch emission sites call PhysMap::new(base).resolve(reg) instead of the deleted FPReg::loc. Pure seam-creation, behaviour-identical: both x86-64 and aarch64 build clean; lib suite 1706 passed, 0 failed (1705 baseline + physmap_resolve_formula). ② will later swap the formula for an explicit per-FPReg table behind this same resolve, with no emission-site change.

23. Pre-P2 verification: the premise holds, with one coupling to preserve

Before touching the fixpoint (P2), §22.2’s open check — “is Sf always boxed-canonical, and does placement ever change representation?” — was resolved against the code. Result: the correctness premise holds unconditionally, and there is exactly one representation↔placement coupling, which is perf-load- bearing (not correctness-bearing).

23.1 Correctness premise — holds at the type level

LinkMode (slot.rs) encodes the split directly:

• F(fpr) — “mutation of the fpr lazily affects the stack slot”: unboxed- canonical, stack is stale. Canonical value lives in the fpr.
• Sf(fpr, _) — “on the stack slot and the fpr which is read-only”: boxed-canonical on the stack, fpr is a droppable read-only cache.
• S(_) — boxed on the stack only.

The placement phases (alloc_policy::try_alloc_fpr, slot.rs:73–127) respect this:

So no placement action ever boxes an F, unboxes anything, or evicts an F. An F (stale-stack) is structurally excluded from Phase-1 victims, and Phase-2 only ever hands a fresh spill slot to a new allocation. The _ => unreachable!() at slot.rs:107 is the live guard for “Phase-1 demotion only touches Sf”; the full x86-64 (1706) and aarch64 (22 float/numeric) suites exercise it without firing — the empirical confirmation. ② can therefore be split out with zero correctness risk.

23.2 The one coupling: the promotion gate (perf-load-bearing)

keep_backedge_floats (merge.rs:123/130 → slot.rs:648) is the loop-back-edge representation decision: for each loop-carried slot that is S|Sf and float-typed (adopt && promotable), promote it to unboxed F — but only via try_set_new_F → try_alloc_fpr()? (slot.rs:703), i.e. Phase 0/1 only, no spill. If only a Phase-2 spill could free an fpr, it returns None and the slot stays boxed (S/Sf).

That is the crux: ① decides representation (box vs unbox) by querying ②’s physical-pool occupancy (“can the greedy allocator seat this in xmm2..15 without spilling?”). This is precisely the §13.8/§16.6 load-bearing selection — benign for correctness (the fallback “stay boxed” is always sound) but it determines which loop floats are unboxed, which is the entire perf delta.

23.3 Consequence for P2 (refines §22.4)

P2 is therefore not merely “drop the pool/spill encoding from try_alloc_fpr”. The promotion gate must keep producing the same decisions, so:

1. ① cannot ask a raw physical question (“is FPReg(i) vacant?”) once VRegs are unbounded. The gate must be re-expressed as a virtual-pressure predicate that P3’s greedy ② reproduces exactly: “would ② seat this VReg in the PHYS_FPR_POOL-wide pool rather than spill it, at this program point?”
2. The low-risk route to byte-identity: share one allocator oracle. Keep keep_backedge_floats calling try_alloc_fpr (now ②’s policy object), let ① record the tentative virtual assignment it returns, and have ② reuse that same assignment. Since P3’s ② is today’s greedy try_alloc_fpr, ①’s gate and ②’s placement read identical occupancy ⇒ byte-identical output by construction. The PhysMap seam (§22.5) is what lets ②’s final physical slot later diverge from the gate’s tentative one without touching ① or ③.
3. Validation: P2/P3 land behind a feature flag; perf-neutrality of the promotion gate must be confirmed on real Apple-silicon / x86 hardware (qemu gives no perf signal), A/B against the stage-1 placement shadow, before default- on. Correctness is already covered by §23.1 + the shadow’s byte-compare.

Net: the separation is more tractable than §16.6 feared — ① and ② already meet at a single oracle (try_alloc_fpr), so the job is to make that oracle a shared ② object rather than to re-derive a second allocator. The risk is confined to the promotion gate’s perf, which the feature flag + M1 A/B gate-keeps.

24. Stage-1 placement shadow (the P3 byte-identity oracle)

Per §23.3, P2/P3 stay perf-neutral only if the separated ② emits the same physical placements as today’s greedy allocator. §24 lands the verification harness for that, ahead of P2 (so the oracle exists before the risky change).

24.1 What it captures

The shadow records, in emission order, every FPRegLoc that PhysMap::resolve returns during a compilation — one entry per resolve at the §22.5 chokepoint. Because every arch emission site (all 22) funnels through resolve, this Vec is a faithful, order-preserving fingerprint of ③’s entire FP-placement output, on both x86-64 and aarch64, with zero per-site plumbing. API (codegen.rs, placement_shadow, feature shadow-placement, default-off):

• begin() — start recording.
• record(loc) — append (called inside resolve under #[cfg]; no-op when idle).
• take() -> Option<Vec<FPRegLoc>> — stop and return the fingerprint.

FPRegLoc now derives PartialEq, Eq, Hash, so two fingerprints compare with plain Vec equality.

24.2 How P3 uses it

baseline = { begin(); jit_compile(f, greedy ②);      take() }   // shipping
candidate = { begin(); jit_compile(f, separated ②);   take() }   // P2/P3 build
assert_eq!(baseline, candidate);   // byte-identical placement ⇒ perf-neutral

Today there is only one allocator, so the harness is validated on the identity / determinism case: placement_shadow_fingerprint (codegen.rs tests) asserts the fingerprint matches the resolve order exactly and is byte-identical across two passes, and that recording is correctly scoped (off after take). The full lib suite under --features shadow-placement builds and passes (1706 + the gated test); the default build is byte-for-byte untouched (the record call is #[cfg]-gated, resolve is otherwise unchanged).

24.3 Why this shape

The fingerprint is the emission-order sequence of physical locations, not a per-FPReg table, because that is precisely what must be invariant for ③ to produce identical machine code: P2/P3 may renumber virtual FPRegs freely (① assigns unbounded VRegs; ② maps them to physical), and renumbering is invisible to ③ iff the resolved FPRegLoc stream is unchanged. Comparing the resolved stream — rather than the VReg ids — is therefore the right and minimal oracle: it permits VReg renumbering while pinning the observable placement.

24.4 Wired into jit_compile; validated on real emission

The shadow is now bracketed around the whole ③ emission in jit_compile (jitgen.rs): begin() before gen_machine_code, take() after — and since the driver recurses into inlined callees, one bracket captures the entire compilation unit. Under --features shadow-placement each compile logs [shadow] iseq=<id> type=entry|loop n=<len> digest=<fnv64> (a compact FNV-1a-64 of the fingerprint; order-sensitive, so any placement or ordering change shows up). M1 bin/test already runs the P0/P1 + shadow code green on real Apple silicon.

Validated end-to-end on x86-64:

• A hot float loop (while i<N: s += i.to_f*1.5 + 0.25) JITs to iseq=… type=loop n=12 digest=0x01531d81c82b05c4, byte-identical across repeated runs — the deterministic baseline a P3 candidate must reproduce.
• Most non-float compilations log n=0 (no FP placement emitted) — expected; the fingerprint only grows where ③ actually lowers FP operands.
• Default build (feature off) is byte-for-byte unchanged; the lib suite under the feature passes (1706 + the gated placement_shadow_fingerprint, now also asserting digest stability + order-sensitivity).

Baseline-capture recipe (run on M1 before P2 flips ② on):

cargo run --features shadow-placement -- benchmark/so_nbody.rb 2>&1 \
  | grep '\[shadow\]' | sort > baseline.txt
# … after P2/P3 land behind their flag, same command → candidate.txt
diff baseline.txt candidate.txt   # must be empty ⇒ ② is byte-identical ⇒ perf-neutral

25. P2 step 1: extract ②’s placement policy out of ③ (byte-identical)

FPReg(usize) is deeply physical in ①: FprAllocator.vfpr is indexed by fpr.0, and add/remove/clear/swap/pin plus every LinkMode::F(fpr) / Sf(fpr) store the physical id. A full virtual-id renumbering of ① therefore touches a large, swap/pin-coupled surface and is deferred. P2 starts at the other end — the cheap, byte-identical half — by moving the placement policy to where ② will own it:

25.1 What moved

Before, PhysMap::resolve (③) hardcoded the rule id < PHYS_FPR_POOL ? xmm(id+2) : spill(base-24+8·(id-POOL)). Now:

• ② (codegen::phys_alloc) owns the rule as policy(i) -> PhysSlot, where PhysSlot is a frame-independent placement (Xmm(p) or Spill(n), the n-th f64 slot). With feature phys-table, policy is memoised into an explicit per-compilation table (phys_alloc::slot, grown lazily); without it, policy is called directly. Both yield identical PhysSlots.
• ③ (PhysMap::resolve) is now policy-free: ask ② for the virtual fpr’s PhysSlot, then apply_base turns a Spill(n) into the frame’s concrete [rbp/x29 - off]. The frame base is the only thing ③ still contributes.

This is the clean split the §22 framing wants: which physical resource is a ② decision (frame-independent), where on this frame’s stack is a ③ mechanic (base-relative). P4 swaps phys_alloc’s table for a loop-aware allocation with zero change to ③ or the 22 emission sites.

25.2 Why byte-identical, and the evidence

policy(i) reproduces the old formula termwise (Xmm(i+2) for the pool; Spill(i-POOL) + apply_base’s base-24+8n for the rest), so the resolved FPRegLoc stream is unchanged. Verified with the §24 shadow:

• hot float loop: digest=0x01531d81c82b05c4 identical with and without phys-table.
• so_nbody: all 79 per-compilation fingerprints byte-identical across the flag (diff empty).
• x86-64 lib suite 1706 passed / 0 failed with --features phys-table; default build and aarch64 build both clean.

25.3 What is not yet done (P2 step 2)

① still hands out physical ids (fpr.0 = pool/spill index); the phys-table is therefore still the identity policy. The remaining, riskier half — making ① assign unbounded virtual ids and having ② pack them into PhysSlots (the genuine decoupling, §22.3) — requires threading a virt→phys indirection through FprAllocator’s swap/pin/vfpr surface and every LinkMode::F/Sf store. With ③ already policy-free and the table seam in place, that change is now confined to ①

• phys_alloc, and its output stays checkable by the same shadow diff.

26. P2 step 2 finding: true virtual-id decoupling is not byte-identical

Designing step 2 (① assigns unbounded virtual ids; ② packs them into PhysSlots) surfaced a hard fact that reshapes the roadmap.

26.1 Greedy placement is time-varying

FPReg.0 is not just “physical” — a live value’s physical register changes over its lifetime. At every control-flow merge / loop back-edge, the bridge reconciles the current state against the target block’s expected assignment (slot.rs ~1806):

#![allow(unused)]
fn main() {
(LinkMode::F(l), LinkMode::F(r)) => if l != r {
    if self.is_fpr_vacant(r) { self.set_F(slot, r); ir.fpr_move(l, r); }
    else { self.gen_fpr_swap(ir, l, r); }   // move a LIVE value l -> r
}
}

So a loop-carried float can occupy xmm5 in the body and xmm7 at the header, reconciled by an FprMove/FprSwap mid-life. The physical placement is a function of program point, not a single value per virtual register.

26.2 Why that blocks a byte-identical step 2

A genuine ② (the point of decoupling) assigns each virtual register one physical location for its whole live range — SSA/linear-scan style. That:

• eliminates the back-edge FprMove/FprSwap reconciliations greedy emits (a global assignment needs no per-edge shuffle for a value it pins), and
• changes which physical register each value sits in.

Both change ③’s emitted FPRegLoc stream. Therefore the §24 shadow diff cannot be empty for a real step 2 — byte-identity and decoupling are mutually exclusive here. (Reuse of a physical slot across non-overlapping lifetimes is fine for stable mapping; only the mid-life moves of §26.1 are the obstacle, and they are intrinsic to greedy’s per-edge reconciliation.)

26.3 Consequence: step 1 is the byte-identical terminus

The separation splits cleanly into two regimes:

Step 2 is thus a perf experiment, not a safe refactor: it must beat greedy on real hardware to be worth the §16.6-class risk, and the shadow’s role flips from “prove zero change” to “quantify the placement delta”. The earlier “feature flag + shadow diff = byte-identical step 2” framing (§22.4/§23.3) was wrong on this point: it assumed a stable mapping could reproduce greedy, but greedy has no stable mapping to reproduce.

27. The real ② global allocator: constraints and staging

Per the §26 decision to build a genuine global ② (not the byte-identical relabel), investigation fixed two hard constraints that shape how:

27.1 Two constraints

1. Not as an AsmIR post-pass. Re-deriving liveness/CFG from the flattened AsmIR and allocating there is exactly the allocation-free re-derivation §13.8 / §16.6 measured at a 2.5× regression. The allocator must live inside the ① fixpoint, where types, liveness and loop structure are already computed.
2. The lever is Phase 0/2, not victim_rank. §15.9 (and the AllocCtx header) prove the Phase-1 victim choice is performance-neutral: it only drops an Sf read-only cache, never boxes an F. The decisions that move the needle are Phase 0 (which physical register a fresh value gets, hence pool-vs-spill at the boundary) and Phase 2 (spill vs. keep). A real ② must steer those.

27.2 Stage 1 (landed): widen the seam to Phase 0

AllocCtx gains pick_vacant(state) -> Option<FPReg> — the Phase-0 placement hook — alongside the existing victim_rank. The default reproduces the historical lowest-physical-index first-fit, so it is byte-identical (hot-float-loop digest 0x01531d81c82b05c4 unchanged; x86 lib suite 1706/0; aarch64 builds). The seam now covers the real lever: a global policy overrides pick_vacant to seat loop-carried values where they will not be evicted, with zero default-path cost (the default is the original Phase-0 scan).

27.3 Stage 2+ (next): the loop-aware policy

The perf-bearing work, all inside the fixpoint and all non-byte-identical (so shadow diff becomes a delta measurement, M1 A/B is the gate):

Stage 1 keeps the shipping build byte-identical while making Stage 2 a contained, fixpoint-local change behind AllocCtx, gated by the §24 shadow (now a delta meter) and real-hardware benchmarks.

28. Stage 2b design: capacity-reservation, the real loop-aware lever

Scoping the loop-aware policy pinned down what actually moves the needle, which is subtler than “pick a better vacant register”.

28.1 Why pick_vacant’s choice is (mostly) neutral, and what isn’t

Choosing which vacant pool register a value lands in is a renaming — perf- neutral (§15.9). And an already-resident F is never evicted (Phase 2 spills the new value; Phase 1 only drops Sf caches). So the only way a loop-carried float ends up non-resident is at promotion time: keep_backedge_floats → try_set_new_F → try_alloc_fpr returns None because the pool is full (no vacant, no all-Sf victim), so the slot stays boxed S/Sf and reloads every loop iteration. The lever is therefore pool capacity at promotion, not victim choice.

28.2 The mechanism: reserve pool capacity for loop-carried floats

The loop-carried-float set is already available at the back-edge merge (liveness.loop_used_as_float() ∧ be.is_float_typed, merge.rs ~118-130). A loop-aware AllocCtx uses the previous fixpoint iteration’s set L (the loop re-runs to convergence, so the prior pass’s L is known when allocating the current one) to:

• Reserve the top min(|L|, PHYS_FPR_POOL) pool slots: pick_vacant for a non-loop-carried allocation skips reserved slots (falls through to Phase 1/2, i.e. spills a short-lived temporary instead of consuming a slot a loop-carried value will need).
• Loop-carried allocations may use any slot, so their try_set_new_F promotion succeeds where it previously overflowed → resident across the loop → no per- iteration reload.

This needs the allocation entry points (set_new_F/try_set_new_F/… → alloc_fpr) to pass which slot / is-loop-carried into the policy — a signature widening of alloc_fpr/try_alloc_fpr and their ~10 callers (FPReg stays an opaque handle; only the policy reads the context).

28.3 Correctness, convergence, verification

• Correctness: reservation only changes placement (resident vs spilled- unboxed / boxed), never representation soundness — a spilled or boxed float is always a valid materialisation. The full suite must pass with the flag on (different digests, still correct).
• Convergence: the reserve count comes from the prior iteration’s L; since L is monotone over the back-edge fixpoint (§14.1) the reserve count stabilises with it. Cap reservation at PHYS_FPR_POOL - 1 so a degenerate |L| can never starve the allocator into livelock.
• Risk: over-reserving forces more temporary spills; net effect is empirical. Gate: §24 shadow as a delta meter (placements changed, back-edge FprMove/FprSwap removed) + M1 A/B on mandelbrot/nbody/optcarrot. Default- on only on a win; this is the §16.6-class risk the experiment exists to test.

Stage 1 (§27) already exposes the pick_vacant hook this rides on; Stage 2b is the contained AllocCtx body + the allocation-entry signature widening, behind a new default-off feature.

29. Stage 2b result: the reservation policy is inert (forward-fixpoint limit)

Stage 2b (§28) was implemented behind phys-loop-aware: target: SlotId threaded through the six FP allocation entry points → alloc_fpr/try_alloc_fpr → AllocCtx::should_reserve, a loop_float set captured in liveness_analysis, and the capacity-reservation gate at the top of try_alloc_fpr_ctx. It is correct (full lib suite 1706/0 under stress-spill-pool,phys-loop-aware; default build byte-identical, hot-float digest unchanged) — but empirically inert.

29.1 The measurement

should_reserve never fires. Instrumentation showed state.loop_float is always empty at every allocation, on every probe — so_nbody (pool 14), a 16-accumulator loop, and a single-accumulator loop under stress-spill-pool (pool 2). Placement digests are identical with and without the feature in all cases (diff empty).

29.2 Why — the same forward-fixpoint wall

The loop-carried set L is produced by liveness.loop_used_as_float() and consumed at the back-edge merge (liveness_analysis, merge.rs:89). But the body’s float registers are allocated once, during the forward body walk, which runs before the back-edge is reached. So at every allocation decision L is not yet known (loop_float empty); by the time L exists, the placements are committed. This is exactly the §13.8/§16.6 limitation — the information a better allocation needs is downstream of the point that needs it — now confirmed at the allocation seam itself. (And loop_used_as_float at that merge was empty for the probes anyway, a second symptom of the same ordering.)

29.3 Consequence

A binding loop-aware allocator cannot be a tweak inside the forward fixpoint; it needs L (per-loop float liveness) surfaced to the body walk — i.e. a preliminary liveness pass feeding the allocation pass. That is a two-pass re-architecture, and §16.6 measured a 2.5× regression for the nearest prior attempt at allocating with re-derived (rather than fixpoint-native) liveness. So Stage 2b’s lever, as a forward-fixpoint reservation, does not bind, and the two-pass alternative is high-risk.

Standing decision: Stage 1 (§27 — ③ policy-free, ② owns the placement table, Phase-0 seam) remains the byte-identical, shipping terminus. The Stage 2b seam (should_reserve + target threading + loop_float) is kept, feature-gated and inert, as the documented attachment point: a future two-pass L-surfacing pass plugs a binding policy in here, gated by the §24 shadow (delta meter) + M1 A/B.

30. Correction: the bridge can spill — the bottleneck is the join’s target policy

§29 (and the prior explanation) leaned on “the merge has no AsmIr, so a pool-overflow loop float must stay boxed”. That framing is wrong, and the correction reshapes the real lever.

30.1 The bridge materialises S→F, spill included

AbstractFrame::bridge(ir: &mut AsmIr, target, slot, pc) — the per-incoming-edge reconciliation stub — has AsmIr and already handles S → F (slot.rs:1957):

#![allow(unused)]
fn main() {
(LinkMode::S(_), LinkMode::F(x)) => {            // boxed home -> unboxed fpr
    ir.stack2reg(slot, GP::Rax);
    let deopt = ir.new_deopt_with_pc(&self, pc + 1);
    if self.is_fpr_vacant(x) {
        ir.float_to_fpr(GP::Rax, x, deopt);      // box→f64 decode, on the edge
        self.set_F(slot, x);
    } else {
        let tmp = self.set_new_F(slot);          // ← spill-capable, WITH AsmIr
        ir.float_to_fpr(GP::Rax, tmp, deopt);
        self.gen_fpr_swap(ir, x, tmp);
    }
}
}

So the edge stub can decode a boxed float into an fpr — and into a spilled F (set_new_F → push_spill, line 1968) when no physical reg is free. Every incoming edge to a merge/back-edge gets such a stub. Materialisation of an f64-spill loop float is therefore fully supported infrastructure.

30.2 The real division of labour

• join / apply_join / keep_backedge_floats (no AsmIr) decide the target representation. They use try_set_new_F (no Phase-2 spill): set the target to F only when a physical fpr is free, otherwise leave it S/Sf.
• bridge (AsmIr) materialises each edge into that target, spilling if needed.

So a pool-overflow loop float stays boxed because the join declined to make the target F, not because materialisation is impossible. §28’s “reserve a physical slot” was the wrong lever; the actual knob is the target-representation policy at the join.

30.3 The correct Stage 2b retry (replaces §28)

For a known loop float — be.is_float_typed(i) ∧ loop_used_as_float(i) (the non-speculative signal already wired in merge.rs:128, feature layer2-float-by-type) — commit the target to F via the spill-capable path rather than try_set_new_F:

#![allow(unused)]
fn main() {
// keep_backedge_floats, for confirmed loop floats only:
self.set_new_F(i);            // instead of try_set_new_F(i)
}

Then the bridge’s S → F arm materialises an f64-spill resident binding: one box→f64 decode per edge (loop pre-header + back-edge), and raw movsd f64 in the body — eliminating the §29 per-iteration decode at the boxed home. No physical reservation, no L-at-allocation-time problem (§29): the decision is at the back-edge, exactly where L is known.

30.4 Risks to clear first

• The noted past bug. keep_backedge_floats deliberately uses the no-spill variant because spill-promotion was “exercised wrongly under register pressure (the stress-spill-pool path)” (slot.rs:758-763). Diagnose that failure mode before re-enabling — start by switching only the layer2-float-by-type confirmed-loop-float arm and running the suite under stress-spill-pool.
• Cost trade. Gains one f64-spill home (per-iteration movsd) but pays a decode on each incoming edge and grows the spill region by |overflow loop floats|. Net is empirical: gate on the §24 shadow (now a delta meter — expect S→F edges to appear) + M1 A/B on float-heavy loops that overflow the 14-wide pool. Only such loops benefit; with ≤14 live floats nothing changes.

This is the architecturally-supported lever the §28 reservation should have been: edge-materialised f64-spill residency for confirmed loop floats, driven by the back-edge L and the existing S→F bridge arm.

31. Stage 2b/§30 result: inconclusive — confounded by a pre-existing layer2 bug

§30 (edge f64-spill residency: keep_backedge_floats using the spill-capable set_new_F for confirmed loop floats) was implemented under phys-loop-aware. The meaningful test needs the confirmed loop-float signal, i.e. running together with layer2-float-by-type. Under layer2-float-by-type,phys-loop-aware,stress-spill-pool, test_join_float_register_disagreement failed with a garbage f64 (-1.0 != 6.9…e-310, an uninitialised spill slot). I first attributed this to §30.

That attribution was wrong. The same test fails with layer2-float-by-type,stress-spill-pool without phys-loop-aware, and — the decisive check — it fails identically at commit bfc4ef1 (P0/P1, before any of this Stage-2 work existed). So:

• There is a pre-existing latent bug in layer2-float-by-type under register pressure (stress-spill-pool). The two flags are never combined in CI (stress-spill-pool runs without layer2-float-by-type), so it went unnoticed. layer2-float-by-type’s broader type+liveness adoption promotes more slots to loop-carried F, and something in that path reads an uninitialised spill under pool=2. This is independent of §28/§30 and is the real bug to file.
• §30’s own soundness is therefore inconclusive. Its only meaningful exercise (the confirmed signal) is confounded by the layer2 bug, and without layer2-float-by-type the be.mode == F adopt signal barely fires under pressure, so §30 could not be cleanly evaluated either way. The §31-draft claim that §30 was “architecturally unsound” was not actually demonstrated; the ordering concern it raised (keep_backedge_floats overrides the loop entry after analyse_backedge_fixpoint has frozen the body placements, merge.rs:79 vs 123) remains a real risk hypothesis, not a proven cause.

31.1 Actions

• §28 (reservation) and §30 (set_new_F at the back-edge) code are reverted; the tree is restored to §27 Stage 1 (③ policy-free, ② owns the placement table, Phase-0 pick_vacant seam — byte-identical, shipping-safe). The phys-loop-aware feature is removed.
• The pre-existing layer2-float-by-type × stress-spill-pool failure is recorded here as a separate bug to fix before that feature’s M1 bench gate.

31.2 Standing conclusion (§27–§31)

§27 Stage 1 is the durable result of the whole “real ② allocator” effort. Three distinct attempts to make ② beat greedy failed, and a fourth was confounded: §28 (reservation) inert (L unknown at allocation, §29); §30 (entry spill-promote) inconclusive + risky (post-fixpoint override); §16.6 (post-pass) regressed. The robust invariant stands: a better FP placement must be decided inside the back-edge fixpoint with its native type/liveness/CFG state. Before any such work, the layer2-float-by-type pressure bug (§31) must be fixed, since that feature is the intended carrier of the confirmed loop-float signal.

32. Diagnosis of the pre-existing layer2-float-by-type × stress-spill-pool bug

§31 flagged that test_join_float_register_disagreement fails under layer2-float-by-type,stress-spill-pool independently of §28/§30. This section roots it out.

32.1 Reproduction and symptom

Reproduced standalone by replicating run_test’s wrapper (__res = (CODE); for __i in 0..24 { (CODE) }; (CODE) — the outer for loop-JITs and the snippet redefines+calls test each iteration) with the test-mode thresholds. Only the first loop iteration’s float is wrong: res[0] is a denormalised garbage f64 (6.9…e-310) instead of -1.0; iterations 1–4 are correct. Default (pool 14) and default-adopt (no layer2-float-by-type) are both correct.

32.2 Root cause: entry promotion inconsistent with the body fixpoint

Instrumenting keep_backedge_floats shows the only difference: under layer2-float-by-type it promotes slot %3 = endv (the loop-carried 1.0) from Sf(FPReg0) to F(FPReg1); the default adopt promotes nothing.

endv is float-typed and used-as-float in the loop, so layer2’s type+liveness adopt fires — **even though the back-edge fixpoint (analyse_backedge_fixpoint, merge.rs:79, run before keep_backedge_floats at

123. placed endv as Sf, not F.** The entry state is thus overridden to a representation (F) the already-frozen loop body was never analysed for. Under stress-spill-pool (pool 2) the freshly allocated FPReg1 is exactly a register the body reuses for a temporary, so the loop-entry binding and the body disagree and the value is read before it is materialised → uninitialised garbage.

This is the §31.3 invariant, now confirmed from the opposite direction: a loop-entry placement/representation must be a subset of what the body fixpoint produced. The default adopt (be.mode == F) is sound precisely because it only re-adopts placements the body already made F. layer2-float-by-type’s whole premise — decouple adoption from the analysis-pass placement, drive it from type+liveness — violates that invariant whenever the body kept the value boxed.

32.3 Why the obvious fixes do not work

• Reuse the incumbent fpr (Sf(x) → F(x) instead of allocating a fresh one): tried, still corrupts. The fault is the F vs Sf representation mismatch between entry and body, not which register.
• Restrict to free fprs (try_set_new_F, already the case): does not help — the body still treats endv as Sf.

A correct fix must keep layer2’s adoption consistent with the body fixpoint’s representation — i.e. either re-run the body fixpoint after adoption, or only adopt slots the body’s back-edge state already carries as F. The latter is essentially the default adopt, so layer2-float-by-type as specified cannot be made sound without folding the adoption decision into analyse_backedge_fixpoint (the §31.4 conclusion: placement lives inside the fixpoint).

32.4 Status

layer2-float-by-type is default-off and explicitly “flip after the M1 bench gate clears”, so this latent bug ships to nobody. It is left as-is with this diagnosis; fixing it is the same fixpoint-internal-placement work the §27–§31 arc converged on, and is the prerequisite for that feature (the intended carrier of the confirmed loop-float signal) ever being enabled.

33. IR/asm-level root cause of the §32 bug: side-branch F→Sf(spill) not materialised

Visualised the failing compile with jit-debug (per-instruction TraceIR + abstract states; note: dump-traceir alone is silent — the trace is gated on jit-debug, compile.rs:158) and emit-asm (machine code). The bug is now pinned to the exact instruction.

33.1 The abstract-state divergence

The body snippet is the diamond a = -1.0 + i*0.5; a = endv if a > endv; res << a. Under layer2-float-by-type, keep_backedge_floats promotes endv (%3) to F(FPReg1) at the compilation loop header (it fires in the compilation’s incoming_context but not in the analysis/frame-sizing pass, whose loop_info isn’t ready). With endv pinned to a physical reg under stress-spill-pool (pool 2), a (%4) at the BB4 merge resolves to Sf(FPReg2) — a spill (its two predecessors are BB2: F(FPReg0) via the condnotbr side exit, and BB3: Sf).

33.2 The faulting machine code

0000d5: ucomisd xmm3,xmm2        ; a(xmm3) > endv(xmm2)
0000d9: jbe     0xffdf4fd        ; a<=endv: side-branch BB2->BB4  (a stays in xmm3)
        ; BB3 (a>endv): a = endv
0000df: movq    [rbp-0xa8],xmm2  ; endv -> a's FPReg2 spill slot   ✓ written here
        ; BB4:
0000fd: movq    xmm0,[rbp-0xa8]  ; read a for `res << a`           ← reads the spill

a’s spill slot [rbp-0xa8] is written only on the BB3 path. On the BB2→BB4 side exit (a <= endv, taken for i=0: -1.0 <= 1.0), a is live in xmm3 (F(FPReg0)) and the side-branch bridge must store it to [rbp-0xa8] (F → Sf(spill)), but it does not — so BB4 reads the uninitialised slot (6.9e-310). Only the first iteration is wrong because later iterations leave stale-but-plausible data there.

33.3 Root cause and trigger

• Proximate bug: the side-exit (condnotbr) bridge does not materialise an F(physical) → Sf(spill) value into the spill slot. The normal (F, Sf) arm (slot.rs:1916: fpr2stack + to_sf→FprMove) does emit the spill store (FprMove(Xmm→Spill) lowers to movsd [spill],xmm), so the defect is in how the side-branch stub is generated/reconciled, not in FprMove itself.
• Trigger: layer2-float-by-type. Its type-based promotion of endv to a physical F is what forces a’s merge onto a spill and thus exercises this side-branch F→Sf(spill) path; the default adopt never creates it, which is why stress-spill-pool alone (CI) is green. So this is a latent side-branch/spill bridge bug, surfaced by layer2 under pressure — not unique to layer2.

33.4 Status

Precise, actionable diagnosis reached; no code change (thresholds restored, tree clean). The fix lives in the side-branch bridge generation (ensure a condbr/side-exit edge runs the full F→Sf(spill) materialisation, i.e. emits the FprMove to the spill slot). That is the concrete next task; it would fix the §32 layer2-float-by-type corruption and harden the side-branch spill path generally.

34. Correction to §33: the bridge IS correct — it is an uninitialised-spill Heisenbug

Deeper IR/asm tracing (instrumenting gen_bridge, the outline-bridge emission loop, and the FprMove lowering) corrects §33. The side-branch F→Sf(spill) bridge is not missing — every link in the chain is individually correct:

• Bridge IR (gen_bridges_for_branches, Side mode): the BB2→BB4 side bridge is FprMove(FPReg0 → FPReg2) — a (FPReg0, the addsd result) moved to its spill FPReg2. Exactly the materialisation the target Sf(FPReg2) needs.
• Survives optimisation: not a self-move (0 != 2), so optimize_peephole keeps it; non-empty, so thread_empty_outline_bridges does not drop it.
• Reaches emission: the outline-bridge loop emits it with base=192, so FPReg2 resolves to Spill(192-24)=Spill(0xa8) — the same [rbp-0xa8] the BB3 path writes and BB4 reads.
• Lowering is correct: FprMove(Xmm(s), Spill(d)) → movq [rbp-d], xmm(s) (x86_64/compile/mod.rs:485). So the bridge does store a to [rbp-0xa8].

So §33’s “the side bridge does not materialise the value” was wrong.

34.1 What it actually is

The defect is an uninitialised-spill Heisenbug: adding any eprintln instrumentation (in gen_bridge or the emit loop) makes the corruption vanish (run_test’s mismatch stops firing). That is the signature of a read of uninitialised/aliased stack, perturbed by the extra code. Two corroborating facts:

1. a’s spill slot [rbp-0xa8] (FPReg2) is aliased with the scratch staging used to load the 0.5 and -1.0 constants in the body (movq [rbp-0xa8],xmm0 appears for both the constant staging and as a’s home). Under pool=2 the spill region is tiny and heavily reused.
2. test is JIT-compiled twice — a loop-JIT (partial) and a method-JIT (whole) — and the two place a in different fprs (FprMove(FPReg0,…) vs FprMove(FPReg1,…)). A deopt/transition between the two, or the first-iteration pre-header path, reads the slot before the responsible store on that exact path.

34.2 Status and honest limit

This is a genuine uninitialised-memory/spill-aliasing bug, exposed only by layer2-float-by-type shifting a onto a pool=2 spill, and it is a Heisenbug — instrumentation masks it, so the standard dump/trace tools cannot pin the faulting store/read ordering. Pinning it further needs a non-perturbing probe (e.g. poisoning spill slots with a sentinel and watching which read survives, or a single-stepped memory watch), which is beyond what jit-debug/emit-asm provide.

The whole §27–§34 arc is recorded; the shipping result remains §27 Stage 1 (byte-identical, default build clean, CI green). The layer2-float-by-type spill-aliasing Heisenbug (default-off, unflipped) is the precisely-scoped open item: it lives in the pool=2 spill-slot lifetime/aliasing under that feature’s loop-entry float promotion, not in the bridge generation (§33 corrected).

35. Ruled out: it is not a stack-reservation / spill-clobber bug

Tested the hypothesis that the compiler (or a callee) clobbers the spill region because the frame’s sub rsp does not reserve enough — i.e. the spill slots sit at/below rsp and something writing below the frame corrupts them.

Test: the method prologue is sub rsp, 0xb0 (init_func, prologue_bytes), and the two spills land at [rbp-0xa8] / [rbp-0xb0] — the latter exactly at rsp. Added a 256-byte safety buffer below the frame (sub rsp, prologue_bytes + 256). Against the reliable oracle (the cargo test … test_join_float_register_disagreement run, which fails deterministically — unlike the standalone repro, which is an intermittent Heisenbug), the bug still reproduces (-1.0 != 6.9…e-310).

So extending the frame below the spill region does not help: the spill slot is not being clobbered from below by an under-sized frame or by the compiler’s stack (the compile trampolines already sub rsp, 4088 before calling in, far below the 0xb0 frame). The hypothesis is ruled out.

This confirms §34’s framing: it is a genuine read of an un-written spill slot on a specific path, not a clobber. The side-branch FprMove(FPReg0→FPReg2) that should write [rbp-0xa8] is present and reaches emission (§34), yet the slot reads uninitialised — so the live suspects narrow to (a) the outline-bridge entry label not actually being where the jbe side exit lands (the store is emitted but jumped over), or (b) an allocation disagreement between the loop-JIT (partial) and method-JIT (whole) compiles that place a in different fprs, so one compile’s read path expects the value where the other’s store put it. Both are control-flow/label or cross-compile issues, not stack sizing. Code unchanged; tree clean.

36. Definitive: the machine code is correct — the store IS present

The remaining question — does the emitted machine code load a from an uninitialised spill slot, or is the slot always written first? — is now answered from the actual bytes of the outline (cold-page) bridge, read via get_label_address(&entry).as_ptr() (emit-asm/dump_disas only lists the hot page, which is why the side bridge was never visible before):

66 0f d6 95 58 ff ff ff    movq [rbp-0xa8], xmm2     ; a -> FPReg2 spill slot
e9 c2 0c 02 f0             jmp  BB4

66 0F D6 /r is MOVQ m64, xmm; ModRM 95 = [rbp+disp32], xmm2; disp32 = 0xffffff58 = -0xa8. So the BB2→BB4 side-exit bridge does store a to [rbp-0xa8] and then jumps to BB4 — exactly the materialisation §33 wrongly suspected was missing. (The second fpr bridge is the symmetric movq [rbp-0xa8], xmm3.) And on the path into the bridge, xmm2 holds a (addsd xmm2,xmm1; ucomisd xmm2,xmm3; jbe <bridge> — nothing clobbers xmm2 between).

So the machine code is correct: every path to the BB4 read writes the spill slot first. It is not an uninitialised-load bug at the machine-code level.

36.1 What this leaves

Every artefact that can be observed — bridge IR, emission, FprMove lowering, and now the emitted bytes — is correct, yet the un-instrumented build still corrupts (-1.0 != 6.9…e-310) and any probe (emit-asm, jit-debug, an eprintln, even a stray finalize) makes it vanish. That is a textbook layout-sensitive Heisenbug: the observed build and the failing build differ in register/spill layout, and only the unobserved layout hits the fault. The correct machine code above is the observed layout; the failing layout is, by construction, the one we cannot print.

Pinning it now requires a non-perturbing technique — e.g. poisoning every spill slot with a NaN sentinel in the prologue (changes data, not layout) and seeing which load returns the sentinel, or a hardware watchpoint on the slot — rather than any dump/trace, all of which move the layout. That is the precise, and only, remaining way forward. Code unchanged; tree clean; shipping result stays §27 Stage 1.

37. Captured under emit-asm via recompile; every observable path is correct

A breakthrough on observability: the bug is captured under emit-asm when the failure happens on a partial-recompile (ClassVersionGuardFailed) path — the run_test wrapper drives Array-class version bumps that trigger loop recompiles, and one of those recompiled-loop runs prints the garbage (res[0] = 6.9…e-310) with full asm. So that path is not Heisenbug-masked, and the cold-page side bridge could finally be read.

Using §36’s get_label_address(&entry).as_ptr() byte read in the outline-bridge emit loop, every side-exit fpr bridge in the failing run is:

66 0f d6 95 58 ff ff ff    movq [rbp-0xa8], xmm2    ; a -> FPReg2 spill
e9 .. .. .. ..             jmp  BB4

i.e. correct — the store is present even when the run corrupts. And the two compiles of test (first + recompile) have identical, correct main-page code.

Then the last runtime suspect — the deopt writeback of a spilled live float (a at [rbp-0xa8], only spilled because layer2 pins endv to a physical reg under pool=2) — was checked and is also correct: FprToStack → fpr_to_stack → load_fpr_into_xmm0(fpr, base), which for fpr.0 >= PHYS_FPR_POOL loads movq xmm0, [rbp-(base-24+8·n)] — the right spill slot.

37.1 Every observable artefact is correct; the bug remains layout-Heisenbug

Verified correct, in the failing configuration: the main-block code, the side- exit outline bridge bytes, the FprMove and FprToStack lowerings, the deopt writeback’s spill read, and the frame’s sub rsp reservation (§35). Yet the un-instrumented build still corrupts res[0] and every probe heals it. The conclusion of §36 stands and is now airtight: this is a layout-sensitive uninitialised/aliased-memory Heisenbug whose failing register/spill layout is, by construction, the one no dump can print — not a defect in any single emitted instruction. The res[0]-only / first-iteration-after-recompile signature most likely implicates the transition (old-compile deopt → VM → recompiled-loop re-entry) leaving a‘s spill slot in a state the fresh layout reads before its own store on exactly that entry — but that crosses two compiles’ layouts, so it too resists a single-build dump.

Only a non-perturbing probe can close it: poison every spill slot with a NaN sentinel in the prologue (data, not layout) and see whether res[0] returns the sentinel (⇒ a genuine pre-store read on the re-entry path) or unrelated garbage (⇒ cross-compile transition). Shipping result unchanged: §27 Stage 1; the bug is default-off (layer2-float-by-type), x86-only, never in CI.

38. The NaN-poison probe fires — §37 is falsified; it is a boxed→F unbox gap

§37’s non-perturbing probe was run: init_func’s prologue now fills the JIT-grown spill region (every 8-byte slot below the last temp, before the nil-clear loop re-clears the temps) with the quiet-NaN sentinel 0x7ff8_0000_dead_beef. This is data, not layout-only in spirit, but note it does add instructions — and the bug still reproduced under cargo test --features layer2-float-by-type,stress-spill-pool test_join_float_register_disagreement:

expected:[-1.0, -0.5, 0.0, 0.5, 1.0]
actual  :[6.92321020550915e-310, -0.5, 0.0, 0.5, 1.0]

Two findings overturn §34–§37:

1. It is not a pure Heisenbug. Adding the whole poison-fill prologue (a real layout change) did not heal it. The “every probe heals it” claim was an artefact of where the earlier probes sat (in the emit/print path), not a law.

2. §37’s “uninitialised spill read” hypothesis is falsified. If res[0] were a pre-store read of a spilled a, the poison would surface as NaN. It does not. 6.92321020550915e-310 has bits 0x0000_7f71_f000_1e02 — a 0x7f… userspace pointer (low nibble 0x2, not 16-byte-aligned, so not a clean RValue ptr; its low two bits 0b10 are the flonum tag). So res[0] is a heap Float whose stored f64 is a boxed Value’s pointer bits read as a raw IEEE-754 double, then re-boxed by f64_to_val/float_heap. The corruption is a boxed↔unboxed LinkMode disagreement, not uninitialised memory and not a missing spill store.

3. Only res[0] (the forward-entry / first iteration) is wrong; res[1..4] (back-edge-resident iterations) are correct. So the defect is on the forward entry into the loop — the pre-header S → F bridge fails to unbox a slot the body then consumes as F, leaving the F home holding the raw boxed pointer. This vindicates §32 (entry-vs-body adopt-set mismatch) and retracts §34’s walk-back.

38.1 Where the seam is

merge.rs:incoming_context builds the loop-entry target and, under layer2-float-by-type, adopts slot i as F iff be.is_float_typed(i) && loop_float.contains(&i) (type+liveness) — a different set from the default mode==F (placement). gen_bridges_for_branches then reconciles each forward entry to target via state.gen_bridge. The hypothesis: layer2 adopts a loop-carried float (endv, or whichever slot aliases a’s physical home) whose forward-entry gen_bridge does not emit the guarded float_to_fpr unbox into the adopted F home (or emits it into the wrong home), so the i=0 body reads the still-boxed pointer. The poison rules the home out of the spill file (not NaN), so the mis-loaded F home is a pool xmm, narrowing the search to the S/Sf/C(float) → F(pool) forward-bridge path under the layer2 adopt set.

38.2 The F home is actively mis-loaded, not read uninitialised

Extending the probe to also poison the pool xmms (movq xmm2..xmm15, NaN at prologue) did not change the outcome: res[0] stays a fresh 0x7f… pointer (6.936…e-310) every run, never the NaN. So the consumed F home is not read before a store — a raw boxed pointer is actively moved into it (a movq xmm, [r14-conv(slot)] from a boxed stack slot, with no float_to_fpr unbox). The pointer shifts run-to-run (ASLR), confirming it is a live heap address, not a constant — and since a’s own values (±1.0/±0.5/0.0) are flonum immediates (never pointers), the mis-read slot is a different slot that holds a heap object. The only loop-live heap object is res (the Array). So on the i=0 forward entry, res’s boxed Array pointer is unboxed-as-float into the home the body reads for a, then re-boxed and pushed — an entry-bridge that unboxes the wrong slot into a’s F home (a register-aliasing / adopt-set mismatch, §32), not a missing store. Next: read gen_bridge’s S/C → F emission for the layer2 adopt set to find the slot whose forward bridge writes a’s home. Shipping result unchanged: §27 Stage 1; bug still default-off, x86-only, never in CI.

38.3 Bridge dump: layer2 forces a to spill; corruption is runtime, not IR

Instrumenting gen_bridges_for_branches to print every loop-merge bridge (entry → target, with the emitted inst stream) for the failing recompile of test pins the placement exactly. Slot map: %1=res, %2=i, %3=endv, %4=a. The forward (method/loop) entry bridge is correct:

BRIDGE BB1 (loop head) entry=all-S
  target: [%3: F(FPReg(1))] [%4: S(Value)] …
  inst  : [StackToReg(%3,Rax), FloatToFpr(Rax,FPReg(1),deopt)]   ; endv unboxed, guarded

Under layer2-float-by-type, endv (%3) is adopted F for the whole loop and permanently pins the physical reg FPReg(1). With stress-spill-pool (POOL=2, only FPReg(0..1) physical), the body then computes a (%4) into the one remaining physical FPReg(0), and at the diamond join BB4 must move it to FPReg(2) — a spill (id 2 ≥ POOL):

BRIDGE BB4 Side(BB2)  entry [%4:F(FPReg(0))] → target [%4:F(FPReg(2))]  inst [FprMove(FPReg(0),FPReg(2))]

Every iteration takes this same Side path (a = -1+i·0.5 ≤ 1.0 = endv always, so a > endv is always false), so the IR is identical for i=0..4 — there is no IR-level distinction for the corrupted first iteration. The spill offsets agree: the store FprMove(FPReg(0)→FPReg(2)) and the res << a read (FprToStack → fpr_to_stack → load_fpr_into_xmm0) both resolve FPReg(2) to [rbp-168] (base_stack_offset=192, 168 = 192-24+8·0), well clear of the live slots (conv(%1)=72, conv(%4)=96) — so no slot/spill aliasing, and 168 is inside the poisoned region yet res[0] is still the pointer, not NaN.

Conclusion. The store writes xmm2 (FPReg(0)) to [rbp-168]; the read loads it back; both offsets are correct and poisoned. So on the i=0 path xmm2 itself transiently holds a boxed pointer at the moment a’s value is spilled — the a = -1.0 + i*0.5 computation deposits a non-float into its result reg on exactly the first iteration. This is a runtime register-state corruption, not a missing store, not an aliased slot, not an uninitialised read (all falsified). It is caused by the layer2 × spill interaction (pinning endv forces a to live in FPReg(0)/spill under POOL=2), but the defect is upstream of the bridge: the first-iteration float computation feeding FPReg(0). Pinning the exact instruction needs a runtime watch on xmm2 across i=0’s a-computation (gdb/hardware watchpoint) — the IR and emitted bytes are now exhausted as evidence. Shipping result unchanged: §27 Stage 1; bug default-off (layer2-float-by-type), x86-only, never in CI.

39. SOLVED — the deopt write-back undoes the loop sp-bump too early

The gdb watch closed it, and it is not a regalloc bug at all — §32/§38’s “upstream of the bridge” instinct was right but the culprit is the deopt side-exit handler, and the trigger is mundane stack discipline.

39.1 The decisive observation

Break on Value::float_heap (called only for the bug, since ±1/±0.5/0 are all flonum immediates → no heap Float on the happy path). It fires with num = 0x00007fff_40001e02. That is not a float and not res — it is a code address on the cold page (0x7fff40000000…). Disassembling there:

0x7fff40001df5: add  $0x10,%rsp           ; ← undo the loop-JIT rsp bump
0x7fff40001df9: movq %xmm3,%xmm0          ; box endv
0x7fff40001dfd: call f64_to_val           ; pushes ret-addr 0x7fff40001e02 at [rsp-8]
0x7fff40001e02: mov  %rax,-0x40(%r14)
0x7fff40001e06: movq -0xa8(%rbp),%xmm0    ; read a's spill — now 0x7fff40001e02 !
0x7fff40001e0e: call f64_to_val           ; box the garbage → float_heap(num)

num equals the return address of the immediately-preceding call in the same bridge. Proof, not inference: that call pushed its return address at [rsp-8], and [rsp-8] == [rbp-0xa8] because the bridge had just done add $0x10,%rsp. The constant pool was verified correct in the same session (0.5 = 0x3fe0…, -1.0 = 0xbff0…), ruling out the const-corruption hypothesis.

39.2 Root cause

side_exit_with_label (the deopt / evict / recompile handler) did:

if loop_jit_spill_bytes > 0 { addq rsp, bytes }   // undo bump
gen_write_back_for_deopt(wb, base)                 // box spilled floats via calls

The loop-JIT entry’s subq rsp, bytes (emit_loop_jit_rsp_bump) is exactly what keeps rsp below the spill region ([rbp-(base-24+8n)]). Undoing it before the write-back exposes the spill slots: the write-back boxes each spilled float with a call, and the call’s pushed return address lands on the very slot it is about to read. The first boxed value (endv) corrupts the second (a), so the deopt writes a code pointer reinterpreted as f64 back to the VM frame, and the VM resumes the loop body with that garbage as a → res[0].

This is why it is first-iteration-only (the partial recompile’s class-version guard deopts once, on entry, while the version is still stale), spill-only (no spill ⇒ no slot below the restored rsp), and layer2-dependent (pinning endv to a physical reg under POOL=2 is what forces a to spill in the first place). It also explains why every static artefact looked correct: the corruption happens at runtime, inside the cold deopt bridge, between the boxing call and the spill read.

39.3 Fix

Reorder: run gen_write_back_for_deopt first (while the bump still protects the spill slots — the boxing calls then push below the region), then undo the bump. Applied to x86 side_exit_with_label; the aarch64 twins (a64_gen_deopt, a64_gen_handle_error) had the identical undo-before-write-back order and were reordered to match (the other aarch64 unwinders — emit_raise/retry/redo/ensure_end — already undo after their call, so they were correct). The aarch64 emit_loop_jit_rsp_bump likewise lowers sp below the fp-relative spills, so the same hazard and the same fix apply.

Verified on x86: test_join_float_register_disagreement passes under layer2-float-by-type,stress-spill-pool; the full default lib suite is 1706/0; stress-spill-pool alone and layer2+stress codegen suites are green. The aarch64 reorder is by symmetry (untested on the x86 host; M1 CI will confirm).

39.4 Bearing on §5

This was a latent deopt-bridge bug, not a flaw in the §27 Stage-1 ②/③ split — the regalloc separation work is vindicated. The bug was merely exposed by layer2-float-by-type because that policy is the first thing that reliably drives a loop-carried float into a spill slot whose deopt write-back then trips the stack-discipline error. With §39 fixed, layer2-float-by-type no longer has a known correctness blocker under stress-spill-pool.

40. Bench gate for layer2-float-by-type: a −9% mandelbrot regression, root-caused and fixed

With §39 unblocking correctness, the bench gate (§13.4) was run on x86-64, layer2-float-by-type ON vs OFF (release, best-of-N min):

mandelbrot regressed ~9 %, and the regression scaled with the float loop (600² 2.2 % → 2000² 9 %), so it was steady-state, not noise — and on the default POOL=14 build, so not spill pressure.

40.1 Root cause (emit-asm of the kernel loop)

emit-asm of the isolated complex-iteration kernel (tr=zr²−zi²+cr; ti=2zr·zi+ci; zr,zi=tr,ti) showed the back-edge bridge:

• OFF: 4 pure movq xmm,xmm (carried floats stay F, unboxed).
• ON: 4× movq xmm0,xmmN; call f64_to_val; mov [rbp-off],rax — i.e. it boxes the carried floats every iteration, then reloads them at loop entry.

So layer2’s loop-entry/back-edge target held the carried floats as S (boxed), not F. The cause: the L2-1 adopt set is_float_typed(i) ∧ loop_used_as_float(i) is narrower than the fixpoint’s mode==F — it misses copy-aliased carried floats (the zr,zi = tr,ti duplicates, written by copy and only read as float next iteration, so their UseTy isn’t Float). OFF unboxes 6, ON only 4; the missing 2 get boxed/reboxed per iteration.

40.2 Fix — adopt the union (layer2 ⊇ greedy)

#![allow(unused)]
fn main() {
let adopt = |i| (be.is_float_typed(i) && loop_float.contains(&i))
             || matches!(be.mode(i), LinkMode::F(_));
}

Keep the type+liveness signal (the L2-1 decoupling intent — it can still adopt more than placement), but never adopt a narrower set than the fixpoint, so a carried float the fixpoint kept F can never be boxed at the back-edge. This re-introduces a floor dependence on placement (mode==F), which is acceptable: §16.6 already established that fully placement-free adoption is perf-neutral at best, and the gate is what matters for default-promotion.

40.3 Result — gate passes

Release best-of-13, layer2-fixed vs base: mandelbrot 0.995 (regression gone, 0.5 % faster), aobench 0.987 (1.3 % faster), nbody ≈1.0. All within noise or better → the bench gate passes. Correctness preserved: the full stress suite (stress-spill-pool,gc-stress,layer2-float-by-type) is 2090/2090. The default build is unchanged (the adopt block is layer2-float-by-type-gated). layer2-float-by-type is now a candidate for default-on.

41. layer2-float-by-type promoted to default-on (bench gate cleared, both arches)

The §40 union-adopt fix cleared the bench gate on both architectures, so layer2-float-by-type is added to default in monoruby/Cargo.toml.

x86-64 (release, best-of-13, layer2/base): mandelbrot 0.995, aobench 0.987, nbody ≈1.0 — no regression, mandelbrot/aobench faster.

M1 / arm64-apple-darwin (benchmark-driver, i/s, layer2/base):

No benchmark regresses beyond noise; aobench/nqueen/bedcov gain ~2 %. The mandelbrot −9 % seen with the old (pre-§40) adopt is gone on both arches.

The feature is kept (not yet folded) so --no-default-features rolls back to the greedy placement adopt and the A/B stays available; it will be folded once it has soaked. Correctness already covered: the full stress suite (stress-spill-pool,gc-stress,layer2-float-by-type) is 2090/2090 on x86-64, and bin/test passes on M1 + x86-64.

Note (separate, pre-existing): a standalone (single cold run) so_nbody / size-2000 so_mandelbrot raises a spurious ZeroDivisionError on arm64-apple-darwin plain release builds — impossible under correct Ruby float semantics, so a darwin-aarch64 codegen miscompile in the POOL=14 float path. It is sidestepped by stress-spill-pool (so bin/test and the benchmark-driver warmup path are unaffected) and is unrelated to layer2 (reproduces on base). Tracked separately; not reproducible under linux-aarch64 QEMU.

42. Stage 2a+2b landed behind phys-loop-aware: §29 inertness cracked (under pressure)

Implements the §27.3 loop-aware allocator and — unlike the reverted §28/§29 attempt — verifies it is non-inert.

Stage 2a (collect L). A loop_carried: HashSet<SlotId> on SlotState records the loop-carried float set (slots F/Sf at the back-edge), populated at the loop-entry merge from backedge_for_floats. The timing §29 lacked is solved by the multi-iteration fixpoint: the back-edge is already computed before real codegen, so L is known at merge time. It propagates into the body for free via Clone and the &mut self joins (a correctness-neutral hint). Confirmed populated: the complex-iteration kernel gives L=6 (F=4, Sf=2); so_nbody L=8 (F=7, Sf=1).

Stage 2b (use L). The phase-1 spill-victim filter (gated on phys-loop-aware) excludes an all-Sf fpr that holds a loop-carried slot, so a fresh value takes a phase-2 spill instead of evicting a loop-carried Sf cache — fewer in-loop reloads (§27.3-2b).

Non-inertness (the verification the user asked for). Via the §24 shadow digest, on the kernel:

The digest differs and the placement count drops 28 → 26 — keeping the loop-carried Sf resident removed two in-loop reload placements, exactly §26’s predicted “fewer back-edge moves / different placement”. So the §29 wall (“L always empty at allocation”) is cracked: L is available and changes placement.

Scope / honest caveat. The lever only engages under register pressure: phase 1 (the Sf-demote it gates) runs only when phase 0 finds no vacant fpr. Under the shipping POOL=14, float loops with < 14 simultaneously-live floats never hit phase 1, so phys-loop-aware is inert there and the shipping build stays byte-identical (the so_nbody POOL=14 digest diff is empty). It bites under stress-spill-pool (POOL=2) and on genuinely high-pressure loops (the doom-renderer ≈14-float class). So its real-hardware value is narrow, and 2c (the M1 perf A/B) measures exactly that.

Correctness. stress-spill-pool,gc-stress,phys-loop-aware (the lever firing under GC) is 2090/2090. Default build unaffected (the field is an inert, #[allow(dead_code)] hint; all policy code is phys-loop-aware-gated).

Status. Stage 2a+2b are implemented and proven non-inert; 2c (M1 perf A/B on high-pressure float code) is the gate, and given the POOL=14 inertness it should be evaluated on whether any shipping benchmark has enough FP pressure to benefit.

43. (2) the global-pin lever: headroom measured, win is copy coalescing (partial)

Per the user’s choice to pursue the §26 “eliminate back-edge moves” lever (which, unlike §42’s pressure-gated policy, can bite under shipping POOL=14), the back-edge FP-reconciliation move count was measured (default build, POOL=14, per loop iteration):

So there is per-iteration headroom under POOL=14. But the emit-asm decomposition of the kernel’s 4 fixes what kind of move, and it reshapes (2):

000265: movq xmm4,xmm9     ; zr (new, in xmm9) -> xmm4
00026a: movq xmm5,xmm8     ; zi (new, in xmm8) -> xmm5
000273: movq xmm6,xmm9     ; zr -> xmm6   ← duplicate copy of zr
000278: movq xmm7,xmm8     ; zi -> xmm7   ← duplicate copy of zi

The 4 moves are 2 reconciliations (zr,zi land in the header’s regs) + 2 duplications (zr is kept in two regs xmm4/xmm6, zi in xmm5/xmm7, because two copy-aliased slots each got their own fpr).

43.1 Only the duplications are eliminable

• The reconciliations are intrinsic. zr := tr produces the new zr in tr’s reg; landing it in the header’s expected reg costs one move somewhere. Pinning zr to a fixed reg merely relocates that move from the back-edge bridge into the body assignment — same per-iteration cost (confirmed by the SSA model: a relabel reconciliation cannot be moved off the critical path, only shifted).
• The duplications are coalescable. FprAllocator.vfpr is Vec<Vec<SlotId>> — one fpr already can hold several slots. The two zr-aliases sit in separate fprs only because the parallel-assignment codegen split them. Coalescing copy-aliased loop-carried floats into one fpr removes the duplicate back-edge move (kernel 4 → 2).

43.2 Consequence

(2) is a copy-coalescing optimization, not a generic “global pin”: it recovers ~half the back-edge moves (the duplications), and the rest are intrinsic. That is a real but partial win, a substantial fixpoint-allocator change (coalesce decision threaded through copy_slot + the merge target), squarely in §16.6’s regressed- before risk class, and still M1-gated. The cheaper §42 phys-loop-aware lever is orthogonal (pressure-gated); coalescing is the POOL=14-relevant one but pays only on copy-heavy loop-carried floats (the a,b = c,d swap/rotate shape).

44. layer2-float-by-type folded into the default and removed

The type+liveness loop-entry float adoption (§16 L2-1, promoted to default-on in §41) has soaked as the default with no regression, so the Cargo feature is now removed rather than merely default-on:

• the adopt block in merge.rs is unconditional (the union-adopt of §40 — the mandelbrot-safe signal be.is_float_typed(i) && loop_used_as_float(i) ∪ be.mode(i) == F);
• the A/B-only #[cfg(not(feature = "layer2-float-by-type"))] placement-based adopt path is deleted;
• layer2-float-by-type is dropped from [features] and the default set in monoruby/Cargo.toml, and the bin/ harness (test, bench, doom) no longer passes it.

Only the build knob is gone; runtime behaviour is unchanged from the default-on state. The §31/§32 layer2-float-by-type × stress-spill-pool history is retained above as the record of the pressure bug that §39/§40 fixed.

45. Slot copies share a GP register (many slots per register, as the fpr file)

%dst = %src used to be a load/store pair through the stack home — and, since Mov flushed the GP file first, it also ended every run of register-resident integer work. On a copy-heavy body (yjit-bench 30k_variables: 100 locals per method, mostly vN = vM) that was ~300 memory ops per call, each copy’s load waiting on the previous copy’s store (a store-forwarding chain), and 12× the cost of ZJIT’s SSA form, where a copy is a renaming.

The fpr file has always let one xmm back several slots (vfpr: Vec<Vec<SlotId>>, the F/Sf sharing copy_slot relies on). GpRegFile now has the same shape: holders: Vec<Vec<Holder>>, one holder set per allocatable register, each holder carrying its own dirty bit. copy_slot’s S arm binds dst dirty to src’s register (loading src clean into a fresh register first if it was not resident) and emits nothing; Mov no longer flushes for an S/C source. The store to dst’s home is owed at the register’s eviction or the next flush, and is dropped if dst dies first (a ret, a popped temporary — free_above_sp retains per holder). Eviction spills every dirty holder of the victim (alloc_reg returns a Vec of spills; evict_reg is the shared primitive, also used where Mul/Div are about to destroy rhs’s register).

Two rules follow from sharing:

• An op may compute in place only in a register that will hold nothing but its lhs (will_hold_at_most); a register shared with copies carries their only value, so the result takes a distinct register.
• The result register must be reserved before the deopt snapshot (plan_dst_reg → GpRegFile::reserve, then new_deopt, then take_dst_reg). The snapshot is taken before the popped operands are cleared so the interpreter can re-read them from their homes; a victim evicted after it stayed listed in it, and an overflow side exit then stored the register — by now holding the result — into the victim’s home. Copies made this latent ordering bug reachable (plb2 bedcov’s splitmix32: z = x kept x resident for the whole body, the second multiply overflowed to a Bignum, and x came back a Float); it is fixed for the copy-free case too.

Result (x86-64, release): 30k_variables 306 ms → 25 ms per iteration; the other benchmarks are flat. Tests: tests/copy_propagation.rs (in-place ops on a shared register, Mul/Div clobbering a shared operand, overflow and type deopts with copies outstanding, calls/allocations, loops, non-fixnum values, the splitmix32 shape) and the gp_alloc unit tests.

46. place/ty folded back into one Vec<Slot> (the scaffolding is retired)

Steps 0b–0c split SlotState.slots: Vec<LinkMode> into place: Vec<Placement>

• ty: Vec<Guarded> so a standalone analysis pass could consume the type vector alone. That pass never materialised in the shape the split assumed: the attempts to run allocation apart from the fixpoint (§13.8, §16.6, §26.3, §31.2) all lost to the greedy backedge placement, and the durable results are the seams that were kept (decide_join/apply_join, alloc_policy, the transfer records, the keep_backedge_floats mechanism/policy split) — none of which reads place or ty separately. After §44 the only consumer of the split was join_ty, called from the debug-only verify_join_replay; the Placement enum had no consumer at all. Meanwhile every mode() recomposed the pair through from_parts and every set_mode() decomposed it, with the sentinels (None / MaybeNone / V) needing a “no type” special case on both sides.

So the split is undone: LinkMode is stored directly again, Placement / placement() / from_parts() and the round-trip test are gone, and join_ty is computed from the stored modes (sentinels read as ⊤, as the stored ty did) for the assertion that still uses it. The type-meet separability invariant (§12 stage 2) is unchanged — it is a property of LinkMode::guarded and Guarded::join, not of how the pair is stored.

At the same time the per-slot vectors that had accumulated beside place/ty — liveness, dynvar_src, subtree_float_read, dynvar_alias — became one Vec<Slot> record, so a per-slot fact is added, cleared (clear / discard) and merged (join_subtree_read_meta) in one place; and deferred_forward, which is fixed for the compile unit, moved from the per-path SlotState to AbstractFrame next to invariants. Verified byte-identical: emit-asm dumps of app_fib, so_mandelbrot, so_nbody, binarytrees, quick_sort, bf, tarai, loop_whileloop are identical to master modulo the compile-time lines; app_aobench differs at one site that master itself emits differently from run to run (a pre-existing nondeterminism, not this change).

What was not folded, and why:

• pending_outer_float_reads (the stage-A report queue). The natural replacement — marking the owner frame directly at the raw-f64 consumption — needs the chain, and the consumption sites (load_fpr_state and the float binop helpers) are AbstractFrame methods that only see their own frame. A per-slot “pending” bit instead of the queue loses the report when the slot is redefined in the same instruction (a = a * 2.0 consumes a and then discards it before the next boundary). The queue is the honest representation of “events for a frame this frame cannot see”.
• FprAllocator’s reverse map (vfpr). It is derivable from the slot modes, and deriving it would remove the fpr_add / fpr_remove / swap bookkeeping and the desync class the alloc_fpr aliasing regression belonged to. But the map’s per-register slot order is the binding order, and the deopt write-back (wb_fpr) emits stores in that order — a derived map would emit them in slot order, so the change is semantics-preserving but not byte-identical. Left for its own change with its own gate.

47. The fpr file is derived from the slot modes (and the stale entry it was hiding)

FprAllocator kept a reverse map vfpr: Vec<Vec<SlotId>> — for each fpr, the slots bound to it — maintained by fpr_add / fpr_remove / clear / swap alongside every F / Sf mode transition. The map is a function of the modes, so it is now computed from them: SlotState::fpr_slots(fpr) and a one-pass pool_occupancy() (per pool register: occupied?, all-Sf?) serve the allocator’s two phases, is_fpr_vacant, the call-site save set and the deopt write-back. FprAllocator keeps only what is not derivable: the number of ids issued (spill ids are never re-issued once vacant — §46’s pick_vacant note) and the pin set. set_F / set_Sf / clear no longer touch a file, and the bookkeeping that the alloc_fpr aliasing regression lived in is gone.

What the reverse map was hiding. The suite caught the derivation: outer_float_write_through’s type-flip tests returned wrong values. The emitted code differed from master at exactly one place — the each call site in the owner loop saved xmm2 on master and not on the branch — and the block compiled inside that call then read the owner’s a where it meant to read i (the _%2 = %2 == %3 [Float][Integer] deopt storm: the block’s static frame-chain offsets were off by the missing 16-byte save).

The mechanism: specialized_compile freezes the caller’s FP save set before the nested compile (stack_offset = using_fpr_offset().offset() lays out the callee’s extra chain offsets over it), while the call emission after the compile took get_using_fpr again. In between, the callee’s compile can widen a caller slot (StoreDynVar through the chain → widen_outer_slot → invalidate_slot, which set S without fpr_remove). With the map, the stale entry kept xmm2 “occupied”, so both sets agreed by accident (and the register was leaked for the rest of the compile). Derived from the modes, the second set was smaller than the first, and the callee’s offsets no longer matched the frame the call actually built.

Fixed at the root, not by re-adding the map: the frozen set rides back on the compiled frame (JitStackFrame::call_site_using_fpr, surfaced as SpecializedCompileResult::using_fpr), and both specialized call sites emit that set — get_using_fpr still runs for its GP flush and alias kill, and a debug assertion checks the live set is a subset of the frozen one (it can only shrink: a suspended frame never gains a pool register). Saving a register the caller no longer needs is harmless; saving fewer than the callee was laid out over was the bug.

Verified: emit-asm dumps of the nine benchmarks are identical to master (app_aobench included this time), the JIT lib tests and the float / block / loop integration tests pass, and the full cargo test suite passes.

48. One write_back(slot, Keep) for the four write-back policies

SlotState had four ways to put a slot’s value into its frame slot, each a function with its own prose: write_back_slot (keep everything), unbox_to_S with keep_claims == false (drop views and claims, keep the type) and == true (the specialized-call demotion: keep claims, move a pool F to a spill home), to_S_unguarded (forget everything), plus give_up_const as the C arm of the second. Their differences — what each mode becomes, what is written, what is forgotten — were spread over four bodies and their comments, and the GP-resident re-homing preamble was copied into three of them.

They are now one function, write_back(ir, slot, Keep), whose match is the mode × policy table (reproduced in its doc comment), and one enum:

Arm for arm the transitions and emissions are the ones the four functions performed (the GP-resident flush under every policy, the resident drop only under All, clear where the old bodies cleared), so the change is byte-identical: emit-asm dumps of the nine benchmarks match master, the JIT lib tests, the float / block / loop integration tests and the full cargo test suite pass. The *_state analysis-half split of the two old functions (write_back_slot_state, to_S_unguarded_state) is folded in as well: the Spill record is still computed by the state transition and emitted through ir.spill, so analysis mode still emits nothing.

49. phys-loop-aware removed

The §42 loop-aware spill-victim policy (loop_carried on SlotState, filled at the loop-entry merge from the back-edge fixpoint; the phase-1 filter that kept a loop-carried Sf cache resident) is deleted along with its Cargo feature. It was default-off, not built by CI, and — as §42 itself records — inert under the shipping POOL=14: phase 1 runs only when no pool register is vacant, so the lever bit only under stress-spill-pool or a ≈14-live-float loop, and its M1 A/B (§27.3-2c) was never run. The L-collection timing finding (§42: the multi-iteration fixpoint makes the back-edge available at merge time) stays in the record for whoever revisits loop-aware allocation; the code it justified no longer earns its field in the per-path state.

50. pending_outer_float_reads removed: the mark lands at the consumption

§46 kept the stage-A report queue on the grounds that the raw-f64 consumption sites (load_fpr_state and the float binop helpers) were AbstractFrame methods that only see their own frame, so the owner frame of a dynvar-loaded value could not be marked there and the pair had to wait for the next compile_instruction boundary, where the JitContext holds the chain.