Add free-list allocator information.

docs/concepts/architecture.mdx

@@ -83,12 +83,17 @@ This design decouples EVM logic from zkVM specifics at the ELF/ABI level.
 Adding support for a new zkVM requires only a new host object that satisfies the symbol
 contract; the EVM implementation itself does not change.
 
-Memory is a joint concern. The zkVM's linker script places the ELF object, stack, and heap
-in the guest address space, while Zesu manages that heap itself with a
-[bump allocator](https://github.com/Consensys/zesu/blob/main/src/zkvm/bump_alloc.zig) that
-never reclaims memory.
-Skipping deallocation keeps the execution trace simpler and cheaper to prove, which differs
-from how many guest programs manage memory.
+Memory is a joint concern.
+The zkVM's linker script places the ELF object, stack, and heap in the guest
+address space, while Zesu manages that heap itself.
+The allocator is selected at build time.
+The guest build defaults to a
+[free-list allocator](https://github.com/Consensys/zesu/blob/main/src/zkvm/FREELIST_ALLOC.md)
+that reclaims freed memory and reuses it within the fixed heap, which prevents
+heap exhaustion on allocation-heavy blocks.
+The source also retains a simpler bump allocator that never reclaims memory: it
+keeps the execution trace cheaper to prove, but it can exhaust the fixed heap, so
+it is no longer the default.
 
 Pre-built `zesu.rv64im.o` artifacts are published as
 [GitHub releases](https://github.com/Consensys/zesu/releases) so zkVM hosts can integrate
@@ -114,8 +119,8 @@ The extern references that zkVM hosts must satisfy fall into three categories.
 commitment back. The two I/O symbols (`read_input` and `write_output`) are the only channel
 between the guest and the host at runtime.
 
-- **Runtime**: execution environment support: logging, process termination, and the bump
-heap allocator's position and upper-bound variables. These let Zesu operate in a
+- **Runtime**: execution environment support: logging, process termination, and the heap
+allocator's position and upper-bound variables. These let Zesu operate in a
 freestanding environment without an operating system.
 
 - **Accelerators**: EVM precompile operations (keccak256, secp256k1 recovery, BN254

docs/reference/glossary.mdx

@@ -11,7 +11,7 @@ This glossary defines common terms used across the Zesu documentation.
 
 ### Bump allocator
 
-The heap allocator Zesu uses inside a zkVM. It advances a cursor as memory is requested and never reclaims memory, which keeps the execution trace simpler and cheaper to prove.
+A heap allocator retained in the Zesu source; the free-list allocator is the default. It advances a cursor as memory is requested and never reclaims memory, which keeps the execution trace cheaper to prove but can exhaust the fixed guest heap.
 
 ### ELF object
 
@@ -29,6 +29,10 @@ The compact zero-knowledge proof produced by running Zesu inside a zkVM, attesti
 
 A record of the chain state a block's transactions access, captured as Merkle proofs against the block's pre-state root. The execution client produces it and Zesu consumes it to re-execute a block without holding chain state.
 
+### Free-list allocator
+
+The default heap allocator for the Zesu guest. It recycles freed memory within the fixed heap by keeping freed blocks on per-size-class lists, which prevents heap exhaustion on allocation-heavy blocks in exchange for a small proving-cost increase.
+
 ### Guest program
 
 A program that runs inside a zkVM. Zesu is a guest program: it executes blocks inside the zkVM, which then produces a proof that the execution was correct.

docs/reference/zkvm-symbols.mdx

@@ -45,12 +45,30 @@ public output bytes.
 Runtime symbols provide execution environment support for logging, process termination,
 and memory management.
 
-| Symbol          | Signature                       | Description                                  |
-|-----------------|---------------------------------|----------------------------------------------|
-| `zkvm_log`      | `(u8, [*]const u8, usize) void` | Log a message at the given level             |
-| `zkvm_exit`     | `(i32) noreturn`                | Terminate execution with the given exit code |
-| `ZKVM_HEAP_POS` | `usize` (var)                   | Bump heap cursor advanced by the allocator   |
-| `ZKVM_HEAP_TOP` | `usize` (var)                   | Heap upper bound checked by the allocator    |
+| Symbol          | Signature                       | Description                                            |
+|-----------------|---------------------------------|--------------------------------------------------------|
+| `zkvm_log`      | `(u8, [*]const u8, usize) void` | Log a message at the given level                       |
+| `zkvm_exit`     | `(i32) noreturn`                | Terminate execution with the given exit code           |
+| `ZKVM_HEAP_POS` | `usize` (var)                   | Heap cursor the allocator advances when it grows the heap |
+| `ZKVM_HEAP_TOP` | `usize` (var)                   | Heap upper bound the allocator must not exceed         |
+
+:::note
+On the `zesu.rv64im.o` guest build, Zesu defaults to a
+[free-list allocator](https://github.com/Consensys/zesu/blob/main/src/zkvm/FREELIST_ALLOC.md) that
+recycles freed memory within the heap region `[ZKVM_HEAP_POS, ZKVM_HEAP_TOP)`.
+
+The allocator is selected at build time, and the source also retains a simpler
+bump allocator that never reclaims memory.
+To use the bump allocator instead, build the guest object from source with that
+allocator wired in, or import the allocator you want when you embed Zesu's
+modules in your own build.
+The bump allocator can exhaust the fixed heap on large blocks, so the free-list
+allocator is the default and the recommended choice.
+Allocator selection affects only how the guest manages the heap.
+The host contract is unchanged, because the host still reserves the heap region
+that these two symbols describe.
+
+:::
 
 ## Accelerator symbols
 

src/lib/glossary.json

@@ -3,7 +3,7 @@
   "terms": [
     {
       "term": "Bump allocator",
-      "definition": "The heap allocator Zesu uses inside a zkVM. It advances a cursor as memory is requested and never reclaims memory, which keeps the execution trace simpler and cheaper to prove."
+      "definition": "A heap allocator retained in the Zesu source; the free-list allocator is the default. It advances a cursor as memory is requested and never reclaims memory, which keeps the execution trace cheaper to prove but can exhaust the fixed guest heap."
     },
     {
       "term": "ELF object",
@@ -21,6 +21,10 @@
       "term": "Execution witness",
       "definition": "A record of the chain state a block's transactions access, captured as Merkle proofs against the block's pre-state root. The execution client produces it and Zesu consumes it to re-execute a block without holding chain state."
     },
+    {
+      "term": "Free-list allocator",
+      "definition": "The default heap allocator for the Zesu guest. It recycles freed memory within the fixed heap by keeping freed blocks on per-size-class lists, which prevents heap exhaustion on allocation-heavy blocks in exchange for a small proving-cost increase."
+    },
     {
       "term": "Guest program",
       "definition": "A program that runs inside a zkVM. Zesu is a guest program: it executes blocks inside the zkVM, which then produces a proof that the execution was correct."