Architecture Decision Records

This directory captures the foundational architectural decisions behind js2wasm. Each record documents a decision that has already been made, the context in which it was made, and the consequences of that choice. ADRs are not design documents — they are retrospective records intended to make the design auditable for external contributors and reviewers.

The format follows Michael Nygard's 2011 ADR template: Context, Decision, Consequences. Records are short by design (200–400 words).

Index

#	Status	Title
001	Accepted	Hybrid static–dynamic compilation strategy
002	Accepted	Architectural approach: AOT + WasmGC
003	Accepted	WasmGC over linear memory
004	Accepted	AOT compilation over JIT/interpreter
005	Accepted	Object layout via WasmGC struct types (closed-world)
006	Accepted	Boundary guards at host-import surfaces
007	Accepted	Closure conversion via WasmGC ref-cell structs
008	Accepted	Dual string backend: wasm:js-string vs WasmGC i16 arrays
009	Accepted	TypeScript annotations as inference seeds, not ground truth
010	Accepted	Dynamic eval() via host import
011	Accepted	Implementation language: TypeScript with the `typescript` package as the frontend
012	Accepted¹	Intermediate representation: multi-stage typed IR
013	Accepted	Explicit allocation sites in the IR
014	Accepted	Ownership and access-semantics analysis on IR values
017	Accepted	Linear-backend bump/arena allocator; one fixed GC strategy, not pluggable
018	Accepted	Structured IR: optimize inside nested control-flow buffers

¹ ADR-012's high-level-IR / lowered-IR split is superseded in practice by ADR-018 (one structured IR, optimized in place); its other content still holds.

Reading order

For a first read, ADR-002 (architectural approach) and ADR-001 (hybrid compilation strategy) frame everything else. The remaining records are sub-decisions within that frame and can be read in any order.