From 5d0edee216df4213ff5f569b65fafaa1b1fbcff7 Mon Sep 17 00:00:00 2001
From: Owais Jamil <desertthunder.dev@gmail.com>
Date: Tue, 9 Jun 2026 17:03:28 -0500
Subject: [PATCH] docs: allocation/allocators chapter

---
 docs/src/SUMMARY.md                           |   9 +-
 docs/src/chapter_10.md                        |  47 +++++++
 docs/src/chapter_10/arena_allocator.md        |  52 ++++++++
 docs/src/chapter_10/collector_families.md     | 119 ++++++++++++++++++
 docs/src/chapter_10/growth_and_failure.md     |  49 ++++++++
 docs/src/chapter_10/host_pointers.md          |  47 +++++++
 .../development/runtime_memory_management.md  |  56 +++++++++
 .../specs/12_runtime_memory_and_semantics.md  |  61 ---------
 .../tasks/12_runtime_memory_and_semantics.md  |  21 ----
 9 files changed, 376 insertions(+), 85 deletions(-)
 create mode 100644 docs/src/chapter_10.md
 create mode 100644 docs/src/chapter_10/arena_allocator.md
 create mode 100644 docs/src/chapter_10/collector_families.md
 create mode 100644 docs/src/chapter_10/growth_and_failure.md
 create mode 100644 docs/src/chapter_10/host_pointers.md
 create mode 100644 docs/src/internal/development/runtime_memory_management.md
 delete mode 100644 docs/src/internal/specs/12_runtime_memory_and_semantics.md
 delete mode 100644 docs/src/internal/tasks/12_runtime_memory_and_semantics.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 3149b5c..24ae7ee 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -46,7 +46,11 @@
   - [Project input and module graph](./chapter_9/project_to_modules.md)
   - [Artifacts and execution](./chapter_9/artifacts_execution.md)
 - [WebAssembly In-Depth (TODO)]()
-- [Runtime Memory Management (TODO)]()
+- [Runtime Memory Management](./chapter_10.md)
+  - [The arena allocator](./chapter_10/arena_allocator.md)
+  - [Growth and allocation failure](./chapter_10/growth_and_failure.md)
+  - [Host pointers and reset boundaries](./chapter_10/host_pointers.md)
+  - [Future collectors](./chapter_10/collector_families.md)
 
 <!--
 TODO:
@@ -69,6 +73,7 @@ TODO:
   - [Core IR](internal/development/architecture/core_ir.md)
     - [Runtime representation](internal/development/architecture/runtime_representation.md)
   - [WASM backend and runtime](internal/development/architecture/wasm_backend_and_runtime.md)
+  - [Runtime memory](internal/development/runtime_memory_management.md)
   - [Outputs](internal/development/cli_and_build_outputs.md)
 - [Contributing]()
   - [Tests & Documentation](internal/development/contributor/testing.md)
@@ -91,10 +96,8 @@ TODO:
 # Inflight Work
 
 - [Specs]()
-  - [Runtime memory](internal/specs/12_runtime_memory_and_semantics.md)
   - [Stdlib and host interop](internal/specs/14_stdlib_and_host_interop.md)
   - [CLI and build outputs](internal/specs/15_cli_and_build_outputs.md)
 - [Task Trackers]()
-  - [Runtime memory](internal/tasks/12_runtime_memory_and_semantics.md)
   - [Stdlib and host interop](internal/tasks/14_stdlib_and_host_interop.md)
   - [CLI and build outputs](internal/tasks/15_cli_and_build_outputs.md)
diff --git a/docs/src/chapter_10.md b/docs/src/chapter_10.md
new file mode 100644
index 0000000..c6ae8b7
--- /dev/null
+++ b/docs/src/chapter_10.md
@@ -0,0 +1,47 @@
+# Runtime memory management
+
+The compiler has enough information to type-check a tuple, but WebAssembly has
+no tuple value. It has numbers, functions, tables, globals, and linear memory.
+Regulus has to decide where managed values live, how generated code allocates
+them, when those allocations can fail, and how long host code may read the
+resulting pointers.
+
+This chapter covers the current memory design:
+
+- the resettable bump arena used by the runtime prelude
+- checked growth with `memory.grow`
+- panic payloads for allocation failure
+- borrowed host pointers and reset boundaries
+- the information needed before reference counting or tracing GC can replace
+  the arena
+
+The design is intentionally small. It supports deterministic tests,
+short-running compiled programs, and proof of the runtime object layout. Longer
+executions will need a collector or region reset plan.
+
+## Why memory management is explicit
+
+WebAssembly linear memory is a mutable byte array owned by a module instance.
+The core specification describes a memory as raw bytes with an initial page
+count and an optional maximum page count.[^wasm-memory] WebAssembly does not
+know that a range of bytes is a Gleam string or a custom value. The compiler and
+runtime prelude assign that meaning.
+
+Managed Regulus values use the layout from chapter 6. The value crossing an
+internal or host ABI boundary is usually an `i32` byte offset into linear
+memory. Generated code can pass the offset around cheaply. Runtime helpers can
+inspect the object header at that offset.
+
+That choice turns memory management into part of the ABI. If allocation can
+move objects, every saved pointer rule changes. If the host owns a pointer, the
+guest cannot reset the arena without a transfer protocol. If allocation failure
+traps without state, tests and adapters cannot report which allocation failed.
+
+## Contents
+
+- [The arena allocator](./chapter_10/arena_allocator.md)
+- [Growth and allocation failure](./chapter_10/growth_and_failure.md)
+- [Host pointers and reset boundaries](./chapter_10/host_pointers.md)
+- [Future collectors](./chapter_10/collector_families.md)
+
+[^wasm-memory]: WebAssembly Core Specification, "Modules", memories: https://webassembly.github.io/spec/core/syntax/modules.html#memories
diff --git a/docs/src/chapter_10/arena_allocator.md b/docs/src/chapter_10/arena_allocator.md
new file mode 100644
index 0000000..1178db5
--- /dev/null
+++ b/docs/src/chapter_10/arena_allocator.md
@@ -0,0 +1,52 @@
+# The arena allocator
+
+Regulus currently allocates managed runtime values in a resettable bump arena.
+An arena is the region of memory used by an allocator, and a bump allocator is
+the simple version of allocation: keep a pointer to the next free byte, return
+that pointer for each request, and move it forward.
+
+The runtime prelude keeps that next-free offset in a mutable WebAssembly global:
+
+```wat
+(memory (export "memory") 1)
+(global $__heap (mut i32) ...)
+```
+
+Static managed values, such as string literals, are emitted as data segments
+near the beginning of memory. The dynamic heap starts after those bytes. When a
+helper needs a string, tuple, list cons cell, record, custom value, closure, or
+panic object, it calls `__alloc`.
+
+## Allocation shape
+
+An allocation request has three steps:
+
+1. Round the requested object size up to the runtime alignment.
+2. Check that the aligned end offset fits in current linear memory.
+3. Return the old heap pointer and store the aligned end as the new heap
+   pointer.
+
+The runtime uses 8-byte alignment. That matches the object layout from chapter
+6, where payload fields that can hold arbitrary Gleam values use 8-byte slots.
+Alignment affects correctness as well as speed. A memory manager has to
+allocate blocks with the alignment required by the objects stored
+there.[^alignment]
+
+The allocator does not keep a free list. It does not split blocks, merge
+adjacent free space, or reclaim individual objects. Those techniques matter in
+general-purpose allocators, but they add machinery that Regulus does not yet
+need. The current runtime allocates many small immutable objects and resets the
+whole instance between tests or executions.
+
+## Non-moving objects
+
+Objects allocated by the arena are non-moving. A string pointer returned from a
+function keeps pointing to the same byte offset after later allocations. A tuple
+field that points at a list keeps the same offset too.
+
+This property matters because managed values cross the raw ABI as `i32`
+pointers. Generated code stores those pointers in locals and object fields.
+Wasmtime tests read them from exported functions. A moving collector would need
+root tracking and pointer updates before it could preserve those guarantees.
+
+[^alignment]: Memory Management Reference, "alignment": https://www.memorymanagement.org/glossary/a.html#alignment
diff --git a/docs/src/chapter_10/collector_families.md b/docs/src/chapter_10/collector_families.md
new file mode 100644
index 0000000..a60206a
--- /dev/null
+++ b/docs/src/chapter_10/collector_families.md
@@ -0,0 +1,119 @@
+# Collector families
+
+An arena answers one memory question: where does the next object go? A
+collector answers a different question: which old objects can be reused?
+
+Collector design is a set of tradeoffs about pauses, throughput, memory
+overhead, pointer stability, implementation size, and how much type information
+the compiler can give the runtime. This section surveys the common families a
+language runtime can choose from.
+
+## Reference counting
+
+Reference counting stores a count of references to each object. Copying a
+pointer increments the count. Overwriting or dropping a pointer decrements it.
+When the count reaches zero, the runtime can reclaim the object.[^recycling]
+
+The appeal is prompt reclamation. When the last reference goes away, the object
+can usually be freed immediately. That can help runtimes with scarce memory or
+objects that hold external resources.
+
+The costs are paid on ordinary program operations. Assignments, function calls,
+returns, and field updates may need count changes. Simple reference counting
+also does not collect cycles, because two dead objects can keep each other's
+counts above zero. Deferred, weighted, and one-bit variants reduce some costs,
+but they add their own rules.
+
+## Mark-sweep tracing
+
+Tracing collectors start from roots: stack slots, globals, registers, host
+handles, and other places that can directly hold live pointers. The collector
+follows pointers from those roots and marks every reachable object. A sweep pass
+then reclaims unmarked objects.[^recycling]
+
+Mark-sweep does not move live objects. That makes raw pointers stable, which is
+useful for simple ABIs and host inspection. The tradeoff is fragmentation. Over
+time, free memory can be split into many small holes, and allocating large
+objects can become harder even when total free memory is high.
+
+The runtime also needs to know which words are pointers. Exact tracing uses
+compiler-provided metadata for stack slots and object fields. Conservative
+tracing treats pointer-shaped words as possible pointers, which can keep dead
+objects alive.
+
+## Copying and compacting collectors
+
+Copying collectors move live objects into another region and reclaim the old
+region as a whole. Compacting collectors move objects to reduce gaps inside a
+region. Both approaches improve locality and reduce fragmentation.[^recycling]
+
+Moving objects requires pointer updates. Every pointer in an object field,
+local, global, stack slot, and host handle must be found and rewritten. That
+makes copying and compacting collectors depend on accurate root metadata and
+clear rules for pointers outside the guest runtime.
+
+The payoff can be large. Allocation after copying can look like arena
+allocation again: bump a pointer through contiguous free space.
+
+## Generational collectors
+
+Generational collectors divide objects by age. New objects are allocated in a
+young generation, often called a nursery. Objects that survive collections are
+promoted to older generations. The design relies on the generational
+hypothesis: most young objects die young.[^generational]
+
+Collecting a small nursery can be much cheaper than scanning the whole heap.
+The hard part is tracking pointers from old objects into young objects. A
+runtime usually maintains remembered sets with write barriers. A write barrier
+is code that runs when a pointer field changes, so the collector can later find
+cross-generation references without scanning all old objects.
+
+Generational collection is often paired with copying collection for the nursery
+and mark-sweep or mark-compact collection for older objects.
+
+## Incremental and concurrent collectors
+
+Basic tracing can pause the program until marking and sweeping finish.
+Incremental collectors split that work into smaller steps. Concurrent
+collectors do some work while the program continues to run.[^recycling]
+
+These collectors improve latency, but they need more bookkeeping. While the
+collector is marking, the program can allocate new objects and change pointers.
+The runtime must preserve the collector's invariants with barriers, safe
+points, or cooperation from the compiler.
+
+The main question is no longer only "is this object live?" The runtime also has
+to know whether the collector and program agree about the state of the object
+graph at each point where execution can continue.
+
+## WebAssembly GC
+
+WebAssembly GC adds Wasm-level aggregate and reference types for languages that
+want the engine to manage objects rather than storing every managed value in
+linear memory.[^wasmgc] A compiler targeting those features can represent some
+runtime values as Wasm GC objects instead of raw byte layouts.
+
+That changes the boundary. The engine can collect GC references, but the
+compiler must map source values into the available Wasm GC types and still
+define how values cross imports, exports, JavaScript, WASI, or another host
+environment. Linear memory may still be useful for byte buffers, custom ABIs,
+or compatibility with non-GC targets.
+
+## Choosing a collector
+
+There is no collector that dominates every workload. Reference counting gives
+prompt reclamation but charges pointer operations. Mark-sweep preserves object
+addresses but can fragment memory. Copying collectors make allocation cheap
+after collection but move objects. Generational collectors exploit common object
+lifetime patterns but require barriers. Incremental and concurrent collectors
+reduce pauses by increasing runtime complexity.
+
+For a compiler book, the important lesson is that memory management depends on
+representation. Object headers, field layouts, root metadata, host handles, and
+ABI rules decide which collectors are possible.
+
+[^recycling]: Memory Management Reference, "Recycling techniques": https://www.memorymanagement.org/mmref/recycle.html
+
+[^generational]: Memory Management Reference, "generational garbage collection": https://www.memorymanagement.org/glossary/g.html#generational-garbage-collection
+
+[^wasmgc]: WebAssembly GC proposal overview: https://github.com/WebAssembly/gc/blob/main/proposals/gc/Overview.md
diff --git a/docs/src/chapter_10/growth_and_failure.md b/docs/src/chapter_10/growth_and_failure.md
new file mode 100644
index 0000000..f202707
--- /dev/null
+++ b/docs/src/chapter_10/growth_and_failure.md
@@ -0,0 +1,49 @@
+# Growth and allocation failure
+
+WebAssembly memory is measured in pages. One page is 64 KiB, and `memory.grow`
+asks the engine to add more pages to a memory instance. On success it returns
+the previous page count. On failure it returns `-1`.[^memory-grow]
+
+Regulus treats growth as part of allocation, not as a separate operation that
+callers perform by hand. Every runtime helper that constructs a managed value
+uses `__alloc` or calls another helper that uses it.
+
+## Checked growth
+
+`__alloc` first computes the aligned allocation end. If the end fits in current
+memory, no growth is needed. If it does not fit, the helper computes how many
+additional pages are required and calls `memory.grow`.
+
+That check has to cover arithmetic before the final store. A requested size can
+overflow when aligned or added to the heap pointer. The required page count can
+overflow before `memory.grow` receives it. Those cases are allocation failure.
+The runtime must not wrap around and overwrite earlier objects.
+
+After a successful growth, the old pointer values remain valid as byte offsets.
+The module's memory has more bytes, but the objects already written keep the
+same offsets. That gives Regulus stable managed pointers while still allowing
+large strings, lists, or nested values to grow beyond the initial page.
+
+## Structured failure
+
+Allocation failure produces a runtime panic payload. The prelude records it in
+`__last_panic`, then traps.
+
+The payload uses the same tag-10 panic object family described in chapter 6:
+
+```text
+tag:        10
+reason:     1
+payload 0: requested allocation size
+payload 1: heap pointer before allocation
+```
+
+This keeps failed growth inspectable. A Wasmtime test can call an exported
+function, observe the trap, then read `__last_panic` to confirm that the failure
+came from allocation and that the runtime recorded the request that failed.
+
+Direct trapping would be simpler, but it would lose information. A compiler
+runtime benefits from failures that are easy to classify, especially while the
+object layout and helper set are still growing.
+
+[^memory-grow]: MDN, "`memory.grow`": https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Memory/grow
diff --git a/docs/src/chapter_10/host_pointers.md b/docs/src/chapter_10/host_pointers.md
new file mode 100644
index 0000000..d7292b0
--- /dev/null
+++ b/docs/src/chapter_10/host_pointers.md
@@ -0,0 +1,47 @@
+# Host pointers and reset boundaries
+
+Managed values cross the raw host boundary as borrowed `i32` pointers into
+WebAssembly linear memory. The guest owns the object. The host may read it using
+the exported memory and the documented object layout.
+
+For a Wasmtime test, the pattern is direct:
+
+1. Call an exported function.
+2. Receive an `i32` pointer.
+3. Read the exported memory at that offset.
+4. Check the object tag, size word, and payload.
+
+The pointer remains stable after the call returns. Later allocations and memory
+growth do not move the object.
+
+## Borrowed, not owned
+
+A borrowed pointer is valid until a reset boundary. Today the main reset
+boundary is the Wasm instance itself: create a new instance, get a new heap.
+Future explicit arena reset points will also be reset boundaries.
+
+Hosts must not treat guest pointers as durable handles. They are offsets into a
+particular memory instance at a particular runtime epoch. If a browser adapter
+wants a JavaScript string that outlives the call, it should copy the bytes out
+of guest memory. If it wants to pass a value back into the guest later, it
+should use an adapter with documented ownership rules.
+
+## Browser memory views
+
+Browser hosts have one extra hazard. JavaScript reads WebAssembly memory through
+an `ArrayBuffer` and typed array views. When memory grows, existing views may no
+longer be the right view of the current memory buffer.[^js-grow] Browser
+adapters should refresh their typed arrays after calls that can allocate.
+
+This does not change guest pointer stability. The `i32` offset is still the
+same offset. The host-side view used to read that offset may need to be rebuilt.
+
+## Why this boundary is small
+
+The raw ABI does not try to expose Gleam values as rich host objects. It exposes
+scalars as WebAssembly values and managed values as pointers. Higher-level
+adapters can decode strings, lists, records, and custom values for a particular
+host. Keeping the raw boundary small lets tests exercise the same representation
+that generated code uses internally.
+
+[^js-grow]: MDN, "`WebAssembly.Memory.prototype.grow()`": https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/JavaScript_interface/Memory/grow
diff --git a/docs/src/internal/development/runtime_memory_management.md b/docs/src/internal/development/runtime_memory_management.md
new file mode 100644
index 0000000..d233ab0
--- /dev/null
+++ b/docs/src/internal/development/runtime_memory_management.md
@@ -0,0 +1,56 @@
+# Runtime memory management
+
+Runtime memory management is implemented in the WebAssembly runtime prelude.
+The prelude is emitted only for modules that need managed values or runtime
+helpers.
+
+## Current model
+
+Regulus uses a resettable bump arena in linear memory.
+
+- Static managed objects are emitted as data segments before the dynamic heap.
+- `$__heap` is the next dynamic allocation offset.
+- `__alloc` aligns each request to 8 bytes.
+- Allocation advances the heap pointer and never frees individual objects.
+- Objects are non-moving until the Wasm instance is reset or a future explicit
+  arena reset runs.
+
+This keeps allocation small and makes raw `i32` managed-value pointers stable
+for generated code and Wasmtime tests.
+
+## Growth and failure
+
+Every allocator path must call `__alloc` or a helper that delegates to it.
+`__alloc` checks whether the aligned allocation end fits in current linear
+memory. If it does not fit, it computes the required page count and calls
+`memory.grow`.
+
+Allocation fails when:
+
+- size arithmetic overflows,
+- the required page count cannot be represented, or
+- `memory.grow` returns `-1`.
+
+Allocation failure records a tag-10 panic payload through `__last_panic`. The
+payload reason tag is `1`; slot 0 is the requested allocation size and slot 1 is
+the heap pointer before allocation.
+
+## Host ownership
+
+Managed pointers exported to a host are borrowed. The guest runtime owns the
+object. A borrowed pointer remains stable after the exporting call returns, but
+the host must not retain it across Wasm instance reset or a future arena reset.
+
+Browser adapters must refresh typed array views after memory growth. Wasmtime
+tests can read the exported memory directly after each call.
+
+## Deferred work
+
+Reference counting and tracing garbage collection are deferred. Either design
+needs complete root metadata, stack and local tracking, clear host ownership
+rules, and tests for pointer lifetime across host calls.
+
+See also:
+
+- [Runtime representation](./architecture/runtime_representation.md)
+- [WASM backend and runtime](./architecture/wasm_backend_and_runtime.md)
diff --git a/docs/src/internal/specs/12_runtime_memory_and_semantics.md b/docs/src/internal/specs/12_runtime_memory_and_semantics.md
deleted file mode 100644
index cf8d5db..0000000
--- a/docs/src/internal/specs/12_runtime_memory_and_semantics.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Open runtime memory and value semantics
-
-Current runtime layout and helper behavior are documented in
-[Runtime representation][runtime] and [WASM backend and runtime][wasm]. This
-spec tracks the remaining design decisions.
-
-## Memory management
-
-Regulus uses a resettable bump arena for managed values. Allocation moves a heap
-pointer forward, objects are non-moving, and individual objects are not freed.
-The arena lifetime lasts until the Wasm instance is reset or a future explicit
-arena reset point is reached.
-
-Allocator paths should check available memory and use `memory.grow` before
-failing. Allocation failure is a structured runtime panic payload. Host code
-borrows managed pointers; those pointers remain stable until reset.
-
-Reference counting and tracing garbage collection are deferred until the
-compiler has complete root metadata, stack/local tracking, and host ownership
-rules.
-
-## Equality and ordering
-
-Runtime equality matches Gleam semantics for comparable scalar and managed
-values. Managed value equality is recursive and structural for strings, bit
-arrays, lists, tuples, records, custom values, results, options, errors, and
-panics. Runtime values are acyclic, so equality does not need cycle detection.
-
-Closures and opaque values only compare equal when they are the same object.
-Distinct closure or opaque objects are not structurally comparable.
-
-Ordering helpers support orderable scalar values and recursive ordering for
-managed values used by runtime helpers. Strings and bit arrays use lexicographic
-byte ordering. Lists, tuples, records, custom values, errors, and panics compare
-slot-by-slot after tag, length, or constructor metadata. Closures and opaque
-values have pointer ordering only as a runtime fallback. Source-level ordering
-operators reject unsupported types before WAT assembly.
-
-## Inspection and debug rendering
-
-String inspection and debug rendering produce deterministic text for runtime
-objects. Rendering handles nested lists, tuples, records, custom values, bit
-arrays, strings, opaque placeholders, errors, and panics. Scalar values in
-runtime slots render as their numeric slot value.
-
-Debug rendering is a host inspection facility. It does not replace source-level
-Gleam `String.inspect` semantics for every type name or constructor name.
-
-## Error and panic reporting
-
-Panic, todo, assert, pattern-match failure, and runtime error objects use the
-existing tag-9 error and tag-10 panic layouts: reason tag at offset 8 followed
-by 8-byte payload slots. Hosts can inspect reason tags, payload slots, and
-rendered payload fields without knowing compiler internals.
-
-## Active tasks
-
-See [Runtime memory tasks](../tasks/12_runtime_memory_and_semantics.md).
-
-[runtime]: ../development/architecture/runtime_representation.md
-[wasm]: ../development/architecture/wasm_backend_and_runtime.md
diff --git a/docs/src/internal/tasks/12_runtime_memory_and_semantics.md b/docs/src/internal/tasks/12_runtime_memory_and_semantics.md
deleted file mode 100644
index 845dac0..0000000
--- a/docs/src/internal/tasks/12_runtime_memory_and_semantics.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Runtime memory tasks
-
-## Goal
-
-Complete runtime memory management and allocation failure behavior.
-
-## Tasks
-
-### Memory management
-
-- [x] Choose a resettable bump arena with checked `memory.grow`.
-- [x] Implement checked allocation and heap growth for every allocator path.
-- [x] Define allocation failure as a structured runtime panic payload.
-- [x] Keep managed objects non-moving until instance reset or arena reset.
-- [x] Document host pointers as borrowed and stable until reset.
-- [x] Add Wasmtime tests for growth, failed growth, and pointer stability.
-
-## Done when
-
-Memory management has explicit, tested allocation, growth, failure, and lifetime
-rules.
-- 
2.51.2