pierrelf.com
Implement a tri-color mark-and-sweep garbage collector for the JavaScript engine.
Scope#
Build a GC that manages heap-allocated JS objects (Objects, Arrays, Strings, Functions, etc.) using the tri-color invariant (white/gray/black) as specified in CLAUDE.md.
Heap#
- GC-managed heap with object headers (mark color, type tag, size)
- Allocation: bump pointer or free-list allocator
- Object graph traversal through property references
Tri-Color Marking#
- White: not yet visited (candidates for collection)
- Gray: visited but children not yet scanned
- Black: visited and all children scanned
- Mark phase: start from roots, color gray, process gray objects (scan children, color black)
- Sweep phase: free all white objects, reset black to white
Roots#
- Global object
- VM register file (all active call frames)
- Operand stack / temporary values
- Native function closures holding GC references
GC-Safe Handles#
GcRef<T>/Handle<T>type for safe GC pointer access- Root registration for values that must survive collection
- Write barrier (if needed for incremental/generational — basic version can skip this)
Collection Triggers#
- Allocation threshold (collect when heap exceeds N bytes)
- Manual trigger for testing
Acceptance Criteria#
- GC heap with allocation and object headers
- Tri-color mark phase correctly traverses object graph
- Sweep phase reclaims unreachable objects
- Root scanning from VM registers and global scope
- GcRef/Handle types for safe pointer usage
- No use-after-free or dangling pointer bugs
- Stress test: allocate many objects, verify collection reclaims memory
- Cycle collection: circular references are properly collected
-
unsafeconfined to thejscrate only (per CLAUDE.md policy)
Phase 10 — JavaScript Engine (issue 5 of 15). Depends on: JS Virtual Machine.