Rewrite docs/Arena.md as a docs/ companion to AddressSpace.md

* Drop the LargeBuddyRange framing (that range no longer exists).
* Align the mechanism description with the in-tree code, which builds
  positive serve masks rather than the inverse skip masks the original
  sketch used.
* Add brief sections on the two-tree structure (one bin tree per
  non-empty bin + one range tree for coalescing) and on the two reps
  Arena ships with: PagemapRep behind LargeArenaRange for whole-chunk
  allocations, InplaceRep behind SmallArenaRange for sub-chunk metadata.
* Link out to AddressSpace.md.

Also add PLAN.md to .gitignore so contributors can keep a local
planning document without committing it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mjp41

.gitignore

@@ -27,3 +27,4 @@
 
 # rust target
 /target
+PLAN.md

docs/Arena.md

@@ -1,125 +1,152 @@
-# Bitmap-Indexed Coalescing Range
+# The Arena: A Bitmap-Indexed Coalescing Range
+
+`Arena` is snmalloc's address-space range that stores free blocks at their
+**natural** size — no power-of-two rounding — and serves any request from the
+full snmalloc size-class sequence. It sits in the per-thread range pipeline
+underneath the slab caches and replaces the historical buddy-based ranges.
+
+This document is the conceptual introduction. For where `Arena` plugs into
+the wider range chain, see [`AddressSpace.md`](AddressSpace.md).
 
 ## The problem
 
-snmalloc's `LargeBuddyRange` only stores power-of-two blocks. A request for 5
-chunks must be served from an 8-chunk buddy block, wasting 3 chunks. We want
-to store blocks at their actual size and use snmalloc's full size class
-sequence at the range level.
+A buddy allocator only stores power-of-two blocks. A request for 5 chunks
+must be served from an 8-chunk buddy block, wasting 3 chunks. We wanted a
+range that
+
+* stores blocks at their actual size,
+* uses snmalloc's full `(exponent, mantissa)` size-class sequence at the
+  range level, and
+* still answers "find a block that can serve this request" in O(1).
 
-## The core idea: search upward, skip a mask
+## The core idea: search upward, mask out exceptions
 
-Free blocks are binned by the set of size classes they can serve. To allocate,
-search upward through bins — any larger block can be carved down. This almost
-works perfectly, but some bins hold blocks whose alignment is too poor to
-serve certain smaller, more-aligned sizes. Those bins must be masked out
-during the search.
+Free blocks are binned by the *set of size classes they can serve* — the
+**servable set**. To allocate, you walk a per-arena non-empty-bins bitmap
+upward through the bins; any larger block can be carved down. This almost
+works perfectly. The exception is alignment: some bins hold blocks whose
+address alignment is too poor to serve certain smaller, *more* aligned size
+classes. Those bins must be excluded from the search for those requests.
 
-The mechanism: `find_first_set(bitmap & ~skip_mask)`. The skip mask depends
-only on the requested size class, not on the block. It's a small constant
-that can be precomputed.
+The implementation builds the per-request filter *positively* as a **serve
+mask** — bit `k` set means bin `k` can serve this request — and the lookup
+is `find_first_set(bitmap & serve_mask, start_word)`. The serve mask
+depends only on the requested size class, not on the block, so it is
+precomputed at compile time.
 
-## Why skips exist
+(The original sketch of this design used the equivalent inverse framing of
+a "skip mask" with `bitmap & ~skip_mask`; see `arenabins.h` for the
+in-tree explanation of why positive is preferred.)
+
+## Why the exceptions exist
 
 snmalloc's size classes follow `S = 2^e + m · 2^(e−B)`, where `B` is the
-number of intermediate bits. Each size class has a natural alignment
-`align(S) = S & ~(S−1)`.
+mantissa-bit width (`INTERMEDIATE_BITS`, 2 in production). Each size class
+has a natural alignment `align(S) = S & -S`.
 
 A size class with high alignment needs padding to reach an aligned address
 within a block. A block of a *larger* size class with *lower* alignment may
 not have room for that padding. Concretely: a block of size 5 at address 1
-can serve size 5 (alignment 1) but cannot serve size 4 (alignment 4) — there
-aren't enough chunks left after padding to the first 4-aligned address.
+can serve size 5 (alignment 1) but cannot serve size 4 (alignment 4) —
+there is not enough space after padding to the first 4-aligned address.
+
+Same size block, different address, different servable set. This is why
+distinct bins per servable-set are needed.
 
-Same size block, different address, different capability. This is what creates
-the need for separate bins and skip masks.
+## Bin count grows slowly in B
 
-## The general structure
+At each exponent, the distinct servable sets are enumerated exhaustively:
 
-At each exponent level, the distinct "servable sets" (which size classes a
-block can serve) form a structure with some incomparable pairs. Exhaustive
-enumeration shows:
+| B | Mantissas/exponent | Bins/exponent | Max mask bits |
+|---|-------------------:|--------------:|--------------:|
+| 1 | 2                  | 2             | 0             |
+| 2 | 4                  | 5             | 1             |
+| 3 | 8                  | 13            | 4             |
+| 4 | 16                 | 34            | 11            |
 
-| B | Mantissas/exponent | Bins/exponent | Max skip mask bits |
-|---|-------------------:|--------------:|-------------------:|
-| 1 | 2                  | 2             | 0                  |
-| 2 | 4                  | 5             | 1                  |
-| 3 | 8                  | 13            | 4                  |
-| 4 | 16                 | 34            | 11                 |
+Most requests need no exceptions at all. Only size classes whose alignment
+exceeds the expected alignment for their position in the sequence have any
+bits to mask. The whole structure is constant-folded into a few small tables.
 
-Each bin corresponds to a distinct servable set. The bins are ordered so that
-upward search is almost always correct — the skip mask handles the exceptions.
+## The two-tree structure
 
-For any B, the structure is:
-- **Most requests need no skips.** Only size classes with alignment higher
-  than expected for their position in the sequence need to mask anything.
-- **The skip mask is a small constant** per size class, precomputable at
-  compile time.
-- **The mechanism is identical** regardless of B:
-  `find_first_set(bitmap & ~skip_mask, start_bit)`.
+A bitmap alone is not enough — when a bin is non-empty, the arena still has
+to *retrieve* and *coalesce* blocks. Each `Arena` therefore maintains:
 
-`prototype/skip_analysis.py` verifies this exhaustively for B = 1, 2, 3.
+* **One red-black tree per non-empty bin** (the "bin trees"), keyed by
+  block address, giving O(log n) selection within a bin. The non-empty-bins
+  bitmap is the index over these trees.
 
-## The bitmap design
+* **One red-black tree of all free blocks** (the "range tree"), keyed by
+  address, used to find a block's left/right neighbours for coalescing on
+  free.
 
-Each free block gets one bin based on its size and alignment. Within each
-exponent, there are as many bins as there are distinct servable sets (5 for
-B=2, 13 for B=3). A flat bitmap tracks which bins are non-empty.
+On allocation: bitmap lookup → choose the bin → pop a block from its
+bin tree → `carve` returns pre-pad / aligned request / post-pad → pre and
+post (if any) re-enter the arena via the bin and range trees.
 
-To allocate size class `(e, m)`:
+On free: range tree lookup → coalesce with neighbours if their tags allow
+→ insert the resulting (possibly merged) block.
 
-1. Compute the **start bit** — the first bin that could serve this size class.
-2. Compute the **skip mask** — bits for bins that can't serve this request.
-3. `find_first_set(bitmap & ~skip_mask, start_bit)` → pop a block from that
-   bin.
+## Two variants over the same Arena
 
-The returned block may not be exactly aligned for the requested size class.
-The caller **carves** the aligned region and returns any prefix/suffix
-remainders to the free pool.
+`Arena` is parameterised by a **Rep** (representation) that decides where
+the per-block tree-node state lives. Two reps ship today:
 
-## Contrast with buddy allocators
+* **`PagemapRep`** — node state lives in the pagemap entry that already
+  covers the block. Used by **`LargeArenaRange`**, which manages whole
+  chunks and larger. Node access is a pagemap lookup; no in-band space is
+  consumed.
 
-A buddy allocator guarantees alignment by construction — a 16-chunk buddy is
-always 16-aligned — but wastes space by decomposing everything into
-power-of-two pieces.
+* **`InplaceRep`** — node state lives *in the free block itself*, in the
+  first units. Used by **`SmallArenaRange`**, which manages sub-chunk
+  metadata fragments where no pagemap entry exists for the fragment. The
+  layout packs the bin tree pointers, the range tree pointers, and (for
+  blocks ≥ 3 units) a large-size word into the leading units of the free
+  block. Unit size is `next_pow2(2 · sizeof(CapPtr))` — 16 B without
+  CHERI, 32 B with pure-capability CHERI/Morello — large enough to hold
+  the two pointers a free block must store.
 
-This design stores blocks at their actual size (no decomposition, no waste)
-and handles alignment at allocation time by carving. The skip mask makes
-lookup O(1) despite blocks having arbitrary size and alignment.
+Both reps drive the same bin / range tree logic in `arena.h`; the bin
+classifier and bitmap in `arenabins.h` are shared.
 
-## Concrete example (B = 2)
+## Why this matters for metadata
 
-At exponent `e = 2`, the size classes are 4, 5, 6, 7. There are 5 bins,
-each labeled by the set of size classes it can serve at this exponent:
+Slab metadata typically wants a pow2 client structure (e.g. a 128 B
+bitmap) plus a fixed ~32 B header. A buddy-based small range rounds
+`160 B → 256 B` (96 B wasted per slab). `SmallArenaRange` rounds to a unit
+multiple (`MIN_META_ALIGN`), so the same allocation costs ~160 B. Across
+many slabs and large heaps this is real memory.
+
+## Concrete example (B = 2, in-production)
+
+At exponent `e = 2` the size classes are 4, 5, 6, 7, and there are 5 bins,
+each labeled by the set of sizes it can serve at this exponent:
 
     Bin 0: serves {4}
     Bin 1: serves {5}
     Bin 2: serves {4, 5}
     Bin 3: serves {4, 5, 6}
     Bin 4: serves {4, 5, 6, 7}
 
-Allocation searches upward from the smallest sufficient bin:
-
-    Request for 7: can use bin 4                       → search bits {4}
-    Request for 6: can use bins 3, 4                   → search bits {3, 4}
-    Request for 5: can use bins 1, 2, 3, 4             → search bits {1, 2, 3, 4}
-    Request for 4: can use bins 0, 2, 3, 4 — skip 1   → search bits {0, 2, 3, 4}
-
-Only the request for size 4 needs to skip a bin: bin 1 holds blocks that can
-serve 5 but not 4. The skip mask is just bit 1.
-
-## Concrete example (B = 3)
+The per-request serve masks (within this exponent — higher exponents
+always serve, so their bits are set):
 
-At exponent `e = 4`, the size classes are 16, 18, 20, 22, 24, 26, 28, 30.
-There are 13 bins. The skip analysis shows:
+    Request for 7: serve bins {4}
+    Request for 6: serve bins {3, 4}
+    Request for 5: serve bins {1, 2, 3, 4}
+    Request for 4: serve bins {0, 2, 3, 4}   — bin 1 holds only {5} blocks
 
-    Request for 16 (align 16): must skip bins for {18}, {20}, {22}, {26}
-    Request for 24 (align  8): must skip bin for {26}
-    All other requests: no skips needed
+Only the size-4 request has an exception: bin 1 must not be picked. All
+other requests get the simple "everything at or above" mask.
 
-The pattern: size 16 has high alignment and must skip 4 bins whose blocks
-are large enough but too poorly aligned. Size 24 is a "sub-power-of-two"
-(alignment 8) and must skip 1 bin. All odd-coefficient sizes have low
-alignment and never need to skip anything.
+## Where to look in the code
 
-Same mechanism, wider mask, same `find_first_set(bitmap & ~mask)` operation.
+* `src/snmalloc/backend_helpers/arenabins.h` — bin classification, serve
+  masks, the non-empty-bins bitmap, the `carve` primitive.
+* `src/snmalloc/backend_helpers/arena.h` — bin-tree-per-bin + range-tree
+  structure, allocation and free / coalesce paths.
+* `src/snmalloc/backend_helpers/largearenarange.h` — `Arena<PagemapRep>`
+  for whole-chunk allocations.
+* `src/snmalloc/backend_helpers/smallarenarange.h`,
+  `inplacerep.h` — `Arena<InplaceRep>` for sub-chunk metadata.