refactor: rename :native_compiled compiler option to :fuse

The previous name read like a degree of `:native` ("native, but more
compiled"), but the two are orthogonal: `:native` selects the
single-NIF Expr compiler; the second toggle wraps that program in
`mx::compile` to fuse the elementwise runs (and, for a `defn while`,
each loop body). `:fuse` names the behaviour and pairs cleanly with
`:native` at the call site.

Unreleased — the option only exists on feat/expr-compiler, so renaming
before PR #155 merges is a no-op for consumers. The ExUnit tag is
renamed in lockstep so `--only fuse` keeps selecting the fusion lane.

Closes #181

Author: ausimian

RELEASE.md

@@ -117,7 +117,7 @@
   per-op BEAM↔worker round-trips to roughly one per token. Reproduce with
   `bench/qwen3_tokens_per_sec.exs` (baseline vs native lanes).
 
-- **Fused-while decode — `native_compiled: true`.** An opt-in lane that fuses
+- **Fused-while decode — `fuse: true`.** An opt-in lane that fuses
   the `defn while` decode loop's body under `mlx::core::compile`. The outer
   loop is data-dependent and host-controlled, so `mx::compile` can't trace it
   as a whole — but the per-token forward (the loop *body*) is shape-stable
@@ -128,7 +128,7 @@
   Enable it on top of the native generation path:
 
       Nx.Defn.jit(&forward/1,
-        compiler: Emily.Compiler, native: true, native_compiled: true)
+        compiler: Emily.Compiler, native: true, fuse: true)
 
   On Qwen3-0.6B this lifts greedy decode to **~5.4× the evaluator (~1.1× over
   the plain native lane**, ~68 vs ~62 tok/s on an M-series Mac). The trade-off:

bench/qwen3_tokens_per_sec.exs

@@ -8,7 +8,7 @@
 #                    loop, replays as one NIF call per step. Run with
 #                    `native_fallback: :raise`, so the number is a true
 #                    full-native measurement, not a silent fallback.
-#   * native-fused — the native lane plus `native_compiled: true` (CM14): the
+#   * native-fused — the native lane plus `fuse: true` (CM14): the
 #                    decode loop stays host-controlled, but each loop *body*
 #                    (the per-token forward) replays through a per-stream-cached
 #                    `mx::compile`'d callable, fusing the elementwise runs the
@@ -151,7 +151,7 @@ defmodule Emily.Bench.Qwen3 do
           compiler: Emily.Compiler,
           native: true,
           native_fallback: :raise,
-          native_compiled: true
+          fuse: true
         ],
         cfg
       )

lib/emily/compiler.ex

@@ -81,7 +81,7 @@ defmodule Emily.Compiler do
       safe on any model. `:raise` re-raises the lowering error instead —
       use it in CI to prove a model lowers fully native. The per-call
       option wins over `config :emily, :native_fallback, :eval | :raise`.
-    * `:native_compiled` — `true` evals the compiled program in the
+    * `:fuse` — `true` evals the compiled program in the
       `mx::compile`'d mode instead of the plain replay. For a while-free
       forward this fuses the elementwise runs the replay leaves separate
       (the CM6 win); for a `Bumblebee.Text.generation` `defn while` it keeps
@@ -136,7 +136,7 @@ defmodule Emily.Compiler do
     :cache,
     :native,
     :native_fallback,
-    :native_compiled
+    :fuse
   ]
 
   @impl true
@@ -182,7 +182,7 @@ defmodule Emily.Compiler do
           {:ok, ([term()] -> [Nx.Tensor.t()])} | :fallback
   defp build_native(key, vars, fun, opts) do
     # Resolve (and validate) the modes up front so a misconfigured
-    # `:native_fallback` or `:native_compiled` raises on every call —
+    # `:native_fallback` or `:fuse` raises on every call —
     # including the happy path, and the lowering-failure path — rather than
     # lying dormant until the first lowering failure.
     mode = native_fallback_mode(opts)
@@ -208,15 +208,15 @@ defmodule Emily.Compiler do
     end
   end
 
-  # Resolve the program eval mode from `:native_compiled`, validating up front
+  # Resolve the program eval mode from `:fuse`, validating up front
   # (like `native_fallback_mode/1`) so a non-boolean raises on every native
   # call rather than being silently treated as truthy. `true` -> `:compiled`
   # (the `mx::compile` fusion — and, for a `defn while`, fusing each loop
   # *body* under a host-controlled decode loop; see `Emily.Program.eval`),
   # `false` -> `:sync` (the plain, bit-identical replay). Only the native path
   # calls this, so the option is ignored unless `native: true`.
   defp native_eval_mode(opts) do
-    case Keyword.get(opts, :native_compiled, false) do
+    case Keyword.get(opts, :fuse, false) do
       true ->
         :compiled
 
@@ -225,7 +225,7 @@ defmodule Emily.Compiler do
 
       other ->
         raise ArgumentError,
-              "invalid :native_compiled #{inspect(other)}; expected true | false"
+              "invalid :fuse #{inspect(other)}; expected true | false"
     end
   end
 
@@ -292,7 +292,7 @@ defmodule Emily.Compiler do
   # — it ignores keys it doesn't consume, but handing it `native: true`
   # when we've decided *not* to compile natively would be misleading.
   defp drop_native_opts(opts),
-    do: Keyword.drop(opts, [:native, :native_fallback, :native_compiled])
+    do: Keyword.drop(opts, [:native, :native_fallback, :fuse])
 
   defp native_ref(%T{data: %B{ref: r}}), do: r
   defp native_ref(%T{} = t), do: Nx.backend_transfer(t, B).data.ref

test/emily/compiler_test.exs

@@ -55,30 +55,30 @@ defmodule Emily.CompilerTest do
       end
     end
 
-    test "jit rejects a non-boolean :native_compiled" do
+    test "jit rejects a non-boolean :fuse" do
       # Validated up front (like :native_fallback) so a misconfigured value
       # raises rather than being silently treated as truthy.
       fun = fn x -> Nx.add(x, 1.0) end
 
-      assert_raise ArgumentError, ~r/invalid :native_compiled/, fn ->
+      assert_raise ArgumentError, ~r/invalid :fuse/, fn ->
         Nx.Defn.jit_apply(fun, [Nx.tensor([1.0, 2.0])],
           compiler: Emily.Compiler,
           native: true,
-          native_compiled: :yes
+          fuse: :yes
         )
       end
     end
 
-    test "native_compiled is a no-op without native: true" do
-      # Only the native path consults :native_compiled, so with native unset
+    test "fuse is a no-op without native: true" do
+      # Only the native path consults :fuse, so with native unset
       # it is ignored (no fusion, no error) — the defn runs the plain
       # evaluator walk and a bad value is never reached.
       fun = fn x -> Nx.add(x, 1.0) end
 
       result =
         Nx.Defn.jit_apply(fun, [Nx.tensor([1.0, 2.0])],
           compiler: Emily.Compiler,
-          native_compiled: true
+          fuse: true
         )
 
       assert_close(result, Nx.tensor([2.0, 3.0]))

test/emily/compiler_while_test.exs

@@ -19,11 +19,11 @@ defmodule Emily.CompilerWhileTest do
   # CM14: the opt-in fused-while lane — the host-controlled decode loop with
   # each loop *body* fused under `mx::compile`. The fusion reassociates f32,
   # so this is all-close, not bit-identical (asserted with a tolerance below).
-  @native_compiled [
+  @fuse [
     compiler: Emily.Compiler,
     native: true,
     native_fallback: :raise,
-    native_compiled: true
+    fuse: true
   ]
 
   defp t(data), do: Nx.tensor(data, backend: Emily.Backend)
@@ -94,11 +94,11 @@ defmodule Emily.CompilerWhileTest do
     acc
   end
 
-  describe "fused-while (native_compiled) == evaluator within f32 tol" do
+  describe "fused-while (fuse) == evaluator within f32 tol" do
     test "loop body with a softmax run fuses and stays all-close" do
       x = t([[1.0, 2.0, 3.0], [0.5, -1.0, 2.0]])
 
-      fused = Nx.Defn.jit(&loop_softmax/1, @native_compiled).(x)
+      fused = Nx.Defn.jit(&loop_softmax/1, @fuse).(x)
       eval = Nx.Defn.jit(&loop_softmax/1, @eval).(x)
 
       assert %Emily.Backend{} = fused.data
@@ -118,7 +118,7 @@ defmodule Emily.CompilerWhileTest do
       # the condition is still evaluated each step, so a varying trip count
       # still tracks the input (same property as the plain native lane).
       for data <- [[1.0, 1.0], [5.0, 5.0], [20.0, 20.0]] do
-        fused = Nx.Defn.jit(&count_until/1, @native_compiled).(t(data))
+        fused = Nx.Defn.jit(&count_until/1, @fuse).(t(data))
         eval = Nx.Defn.jit(&count_until/1, @eval).(t(data))
 
         drift =
@@ -131,7 +131,7 @@ defmodule Emily.CompilerWhileTest do
 
     test "zero iterations returns the initial state unchanged (fused lane)" do
       x = t([3.0, 4.0])
-      out = Nx.Defn.jit(&zero_iter/1, @native_compiled).(x)
+      out = Nx.Defn.jit(&zero_iter/1, @fuse).(x)
       # No body ran, so nothing was fused — bit-identical to the input.
       assert Nx.to_binary(out) == Nx.to_binary(x)
     end
@@ -144,7 +144,7 @@ defmodule Emily.CompilerWhileTest do
       # result is bit-identical to both the evaluator and the plain native
       # lane here, which pins the dynamic-slice-under-fusion path.
       buf0 = Nx.broadcast(t(0.0), {4})
-      fused = Nx.Defn.jit(&fill_buffer/1, @native_compiled).(buf0)
+      fused = Nx.Defn.jit(&fill_buffer/1, @fuse).(buf0)
       eval = Nx.Defn.jit(&fill_buffer/1, @eval).(buf0)
 
       assert %Emily.Backend{} = fused.data

test/emily/conformance/generation_native_test.exs

@@ -34,11 +34,11 @@ defmodule Emily.Conformance.GenerationNativeTest do
   # decode loop's body is fused under `mx::compile`. The fusion reassociates
   # f32, so logits are not bit-identical; greedy argmax over them is, so the
   # acceptance gate is a token-id match rather than a binary-identical one.
-  @native_compiled [
+  @fuse [
     compiler: Emily.Compiler,
     native: true,
     native_fallback: :raise,
-    native_compiled: true
+    fuse: true
   ]
 
   # Run `model`'s generation through `build_generate` on a fixed in-vocab
@@ -89,7 +89,7 @@ defmodule Emily.Conformance.GenerationNativeTest do
     # flip a token on another model/prompt. Sampling strategies would
     # diverge under fusion, so only greedy is gated.
     gc = configure(ctx.gen_config, %{type: :greedy_search})
-    fused = generate_ids(ctx.model_info, gc, @native_compiled)
+    fused = generate_ids(ctx.model_info, gc, @fuse)
     eval = generate_ids(ctx.model_info, gc, @eval)
     assert fused == eval
   end

test/support/conformance_helper.ex

@@ -50,12 +50,12 @@ defmodule Emily.ConformanceHelper do
     * the native lane binds `predict_opts` to
       `[compiler: Emily.Compiler, native: true, native_fallback: :raise]`
       and is additionally tagged `:native`;
-    * the fusion lane adds `native_compiled: true` (wrapping the replay in
-      `mx::compile`) and is additionally tagged `:native_compiled`.
+    * the fusion lane adds `fuse: true` (wrapping the replay in
+      `mx::compile`) and is additionally tagged `:fuse`.
 
   The module is already tagged `:conformance`, so the native and fusion
   lanes carry that tag too: `mix test --only conformance` runs all three,
-  while `mix test --only native` / `mix test --only native_compiled` run
+  while `mix test --only native` / `mix test --only fuse` run
   one lane each. Because every lane resolves the same HuggingFace repos,
   whichever runs first reads from `~/.cache/bumblebee` for the rest — the
   download is paid once.
@@ -91,7 +91,7 @@ defmodule Emily.ConformanceHelper do
 
     * `:lane_tags` (default `true`) — when `false`, the native and fusion
       lanes are emitted *without* the cross-cutting `:native` /
-      `:native_compiled` tags. The heavyweight `*_full` suites pass
+      `:fuse` tags. The heavyweight `*_full` suites pass
       `lane_tags: false` so their compiler lanes stay gated behind the
       suite's own `:*_full` moduletag; otherwise `--only native` would
       start pulling full-size checkpoints. `--only vit_full` then runs all
@@ -116,10 +116,10 @@ defmodule Emily.ConformanceHelper do
         body
       ),
       lane(
-        [extra_tag, tag_lanes? && :native_compiled],
+        [extra_tag, tag_lanes? && :fuse],
         name,
-        " [native_compiled]",
-        [compiler: Emily.Compiler, native: true, native_fallback: :raise, native_compiled: true],
+        " [fuse]",
+        [compiler: Emily.Compiler, native: true, native_fallback: :raise, fuse: true],
         body
       )
     ]
@@ -132,7 +132,7 @@ defmodule Emily.ConformanceHelper do
   # Build one `mode_test` lane: a `test` that binds `predict_opts` for the
   # body, preceded by one `@tag` per entry in `tags` (nil/false entries are
   # dropped). The `*_full` suites pass `lane_tags: false` to drop the
-  # `:native` / `:native_compiled` tags and rely on their own `:*_full`
+  # `:native` / `:fuse` tags and rely on their own `:*_full`
   # moduletag (or an explicit `:tag`) instead.
   defp lane(tags, name, suffix, predict_opts, body) do
     tags = Enum.reject(tags, &(&1 in [nil, false]))

test/test_helper.exs

@@ -42,28 +42,28 @@
 #
 #     mix test --only fast_kernels_full
 #
-# `:native` and `:native_compiled` are the expression-compiler lanes of
+# `:native` and `:fuse` are the expression-compiler lanes of
 # the tiny-random conformance suites: every `mode_test` (see
 # `Emily.ConformanceHelper`) re-runs the forward pass under
 # `compiler: Emily.Compiler, native: true, native_fallback: :raise`
-# (`:native`) and again with `native_compiled: true` wrapping the replay
-# in `mx::compile` (`:native_compiled`), so the same PyTorch reference
+# (`:native`) and again with `fuse: true` wrapping the replay
+# in `mx::compile` (`:fuse`), so the same PyTorch reference
 # slice validates the evaluator, the native-compiled, and the fused
 # paths. Those tests carry `:conformance` too, so `--only conformance`
 # runs all three lanes; select one lane alone with:
 #
 #     mix test --only native
-#     mix test --only native_compiled
+#     mix test --only fuse
 #
 # Listed in the default exclude defensively — every such test is already
 # `:conformance`-tagged, but this keeps a future `:native`-only or
-# `:native_compiled`-only test out of the default suite.
+# `:fuse`-only test out of the default suite.
 ExUnit.start(
   max_cases: System.schedulers_online(),
   exclude: [
     :conformance,
     :native,
-    :native_compiled,
+    :fuse,
     :vit_full,
     :whisper_full,
     :distilbert_full,