# ADR 0013: Numeric code: uniform values, specialised evidence **Status:** Accepted by the project owner on 2026-10-12; proposed 2026-10-09 (issue #61); needs engineering review (#44). ## Context - **Values are uniform** ([ADR 0002](0002-memory-model.md)): every value is one 64-bit word. `Int` is a tagged 63-bit immediate, promoted to a big integer block on overflow ([ADR 0014](0014-arrays-and-bigint.md)); `Float` is a heap block; so is all other data. - **Traits are dictionaries** ([ADR 0007](0007-type-inference-and-traits.md)): `x + 1` on `Int` reads the `Num` dictionary, projects its `add` closure and calls it. ADR 0007 left "known `Impl` evidence at monomorphic call sites can be specialised later". Since issue #34, a dictionary without constraints is static data, but every method call still went through a closure. - **The question (roadmap M2):** should numeric code be monomorphised, that is, compiled per type with unboxed `Int` and `Float` in C locals, or keep the uniform representation? ## Measurements Made before deciding, before big integers (ADR 0014) and multi-shot resumptions (ADR 0017) were merged under this work, on `tests/bench`, release builds with clang 22, one scheduler thread, pinned to performance cores. Counts are user-space instructions and cycles from the CPU's counters, best of 5 interleaved runs (wall time on this shared machine varies by ±15%). **Where `arith` spent its time:** 51% of its cycles were in the closure entries of `Num` and `Ord` methods, 11% in calls of `tl_int_compare`. The tagged arithmetic itself was a small part. **Dictionaries known at compile time, step by step** (cycles, change from the state before the step series): | Step | `arith` | `dict` | `effects` | `lists` | |---|---|---|---|---| | Methods of constant dictionaries called directly, trivial ones inlined | −27% | −21% | −34% | −11% | | … and constrained functions specialised for constant dictionaries | −71% | −22% | −33% | −8% | | … and `Int` comparison, multiplication and division inline in `louise_rt.h` | −84% | −30% | −40% | −18% | **What unboxing `Int` would add:** `arith`'s two hot functions written by hand in C, once as generated today (tagged values, after the steps above) and once with `int64_t` locals, with the same control flow (reduction counter, overflow checks, yield checks). The unboxed version ran **8% more cycles** (307M against 284M) and 14% more instructions. `Int` is 63-bit, so unboxed arithmetic needs explicit range checks, while tagged arithmetic gets them from the 64-bit overflow flag; `dup` and `drop` of a tagged int are one predicted branch. Since ADR 0014, an overflow promotes to a big integer, which an unboxed `int64_t` cannot hold: unboxed code would also need a boxed fallback. **What unboxing `Float` would add:** `tests/bench/floats` (a new benchmark) spent 88% of its cycles allocating and freeing the result of each operation. Unboxed doubles would make such loops several times faster. ## Decision 1. **v1 keeps the uniform representation.** No type-directed monomorphisation, and no second representation of values. 2. **Known evidence is specialised instead** (implemented, `louise_core::evidence`). A Core-to-Core pass, run by the C backend before Perceus: - calls of methods projected from constant dictionaries become direct calls; - methods whose body is one extern call or primitive on their parameters are inlined; - a constrained function called with constant dictionaries gets a copy for that combination, in which the same applies; recursion reuses its copy. At most one copy per function of the program, in total; - the projections and dictionary reads left unused are removed. This is monomorphisation over *dictionaries*, not over *representations*: values stay uniform, so nothing else changes (Perceus, unwinding, sending, the ABI). 3. **`Float` stays boxed in v1.** Its cost is the allocator's fast path, made cheaper in issue #61 (`floats`: −39%). 4. **`Int`'s primitives are inline** in `louise_rt.h`: equality, comparison, multiplication, division and remainder join addition and subtraction. (Issue #47 did this with big-integer slow paths, which replaced this issue's version with panics.) ## Consequences - Generic numeric code called at known types runs like monomorphic code: `arith` −71% cycles, `dict` −34%, `effects` −43% against the v1 chain built with clang (with the runtime changes of issue #61; see `tests/bench/README.md`). - Code does not grow: the specialised C of `http_demo` is 10% *smaller* (4 copies; the closure-call sequences they replace were longer), and compiles 12% faster. - **The interpreter runs Core as lowered.** The differential tests therefore check the pass against unspecialised programs. `LOUISE_NO_SPECIALISE=1` turns it off, to compare or to bisect a miscompilation. - **Preemption points differ from the interpreter's.** The interpreter counts every call as a reduction; inlined methods (and functions that never unwind, ADR 0003 Revision 2's implementation note) no longer count. With `LOUISE_THREADS=1` the native order stays deterministic, but a program whose output depends on where actors are preempted may print in another order than in the interpreter. No `tests/run` program does. - **Not specialised:** dictionaries built from constraints (`Ord>` from `Ord`), and dictionaries captured by closures (`list.sum` passes its `Num` to a lambda). Both could be added to the same pass. (Dictionaries built from constant ones are specialised since issue #278: [ADR 0043's note of 2026-10-23](0043-a-core-optimiser.md#note--2026-10-23-evidence-at-dictionaries-built-from-constant-ones-issue-278).) - Float-heavy code stays slow compared with languages that unbox doubles. ## Alternatives considered - **Monomorphisation with unboxed values** (MLton, Rust). Core is untyped (types are erased by lowering), so it needs types in Core or specialisation before lowering. Unboxed values then need boxing where they meet generic code, Perceus and unwinding that know which locals are not references, and a second calling convention. For `Int` it measured slower; for `Float` it would pay off, but floats are rare in the programs v1 targets (servers, actors). To revisit with a float-heavy use case. - **NaN-boxing floats.** It changes the encoding of every value (pointers and ints included), the ABI and the sanitizer story. Rejected for v1. - **Devirtualisation without copies.** Generic functions stay slow (`arith` −27% instead of −71%). - **Specialising in the interpreter too.** It would speed up `louise run`, but the interpreter is the reference the native backend is tested against.