Limelight RFC

Design documents for Limelight: a compiled runtime for PHP with a memory-first architecture. PHP source compiles through LLVM to machine code; memory is managed by arenas, compiler-tracked ownership, and pluggable garbage collection instead of a one-size-fits-all VM heap.

Status: design phase. These RFCs fix the architecture before the first vertical slice is built. Deferred work lives in BACKLOG.md.

Architecture at a glance

Pillar	Idea	RFC
Memory categories	Every managed entity lives in a category: request arena, long-lived, immortal, or GC heap. Most entities are reclaimed with their arena in O(1) and are invisible to the GC	arenas, arena-reset
Static lifetimes	The compiler tracks ownership and moves, Rust-style but with a runtime fallback instead of compile errors. Proven objects get zero refcounting and a scheduled destructor call	static-lifetimes
Pluggable GC	The collector is a build-time strategy behind a fixed contract. One strategy is in force, rc-cycle: ARC + arenas + on-the-fly cycle collection from a mutator-fed candidate set	strategies, rc-cycle, heap-design
Actors	#[Actor] classes own their arenas and execute serially; mailboxes are the only communication channel between actors. Collection runs per actor at message boundaries; each actor may bind its own GC	actors
Object model	C++-grade dispatch for PHP: inline-trailing vtables, COM-style itables, fat interface references, inline caches that never invalidate	classes, lowering, caches
Exceptions	Two channels — table-driven unwinding and an error-return channel — with the compiler choosing, not the programmer. The return channel is also the portability baseline: it needs no host support, which is what makes the embedded/WASM/JVM modes possible. The design has known open defects, listed in the document	exceptions
Values	16-byte ValueBox for the dynamic world, raw unboxed slots for declared types, COW as a per-object flag	values, strings, arrays

Document map

model/ — language and memory model

• values.md — ValueBox/unboxed contracts, Optional, UNINIT, COW protocol
• strings.md — string layout, string-as-class, interpolated template class
• arrays.md — one array class, three storage strategies
• arrays-hashtable.md — the ordered hash: entry layout, index, deletion, flood defense
• classes.md — object layout, class descriptors, vtables, itables, property access
• lowering.md — the C structures and LLVM IR behind the model
• caches.md — every cache site, why none carries a replacement policy, and what each does when it fills
• model/memory/ — arenas, arena reset, static lifetimes, ARC optimizations
• model/gc/ — the strategy contract, rc-cycle and its question graph, heap design, research survey; the index also says what was deleted on 2026-08-26 and where it is

runtime/ — execution substrate

• implementation-language.md — Rust core + thin C++ LLVM layer
• object-lifecycle.md — new and the three-phase teardown
• actors.md — actor contexts, message queues, per-actor GC
• exceptions.md — throw/try/finally: two error channels, trace materialization, and why try costs nothing

Other areas

• interop/ — IR-level interop with C++/Rust (research)
• io/, stdlib/ — placeholders, not yet designed
• attributes.md — the attributes principle (root document)
• BACKLOG.md — deferred work, collected from all RFCs
• dev/GLOSSARY.md — normative technical vocabulary and context-sensitive replacements for retired terms

HIR is not designed here. It was, in hir/, until 2026-09-06; the design of record is amber/design/, and this repository keeps only what the runtime model owes it (dev/DECISIONS.md, 2026-09-06).

The key principle

Attributes are the language surface. Limelight adds zero new keywords and zero new syntax to PHP. Every capability (actors, GC hints, generics) enters through standard PHP 8 attributes under the Limelight\ namespace, and the compiler's whole-program analysis materializes its findings back into source as the same attributes. A Limelight program is, syntactically, a valid PHP program.

Reading order

New to the project? Read in this order:

1. attributes.md — the principle everything hangs on
2. model/memory/arenas.md — memory categories, the core bet
3. model/gc/strategies.md — how collection is organized
4. model/values.md and model/classes.md — what a value and an object are
5. runtime/actors.md — the concurrency story