# ADR-0002: Use sparse software mappings for the browser interpreter

- Status: accepted for the interpreter
- Date: 2026-07-24
- Owners: project maintainers

## Context

Phase 2 requires either Memory64 integration or a documented interim browser
memory design. Chrome can compile and instantiate Memory64, as proven by the
Worker feature gate, but a Memory64 linear memory does not by itself provide
Linux-style sparse mappings, per-region permissions, guard pages, or cheap
unmapping. The current execution engine is an interpreter rather than the
planned P-code-to-Wasm translator.

## Decision

Use `binarrow-guest-memory` unchanged on native and `wasm32-unknown-unknown`
for the browser interpreter. Guest addresses remain 64-bit values. Each mapped
Linux region owns a bounded byte vector inside the browser runtime's ordinary
Wasm32 memory, while a sorted region table enforces guest read, write, and
execute permissions. Mapping, protection, splitting, unmapping, and committed
byte accounting remain project-owned and host-independent.

The loader and Linux runtime apply the same configurable committed-memory
limit in native and browser hosts. The browser also exposes instruction,
syscall, output, and ephemeral-filesystem limits. A Memory64 probe remains a
required Chrome gate so the future translator can adopt direct 64-bit linear
addressing without discovering a missing platform capability later.

Do not expose the interim backing representation through the loader, CPU,
Linux, or host-service APIs. The future translator may replace region byte
vectors with a Memory64-backed page store behind `AddressSpace` while retaining
the same checked mapping contract.

## Consequences

### Positive

- Native and browser interpreters execute identical memory code and semantic
  tests.
- Sparse high guest addresses do not force a correspondingly large browser
  allocation.
- Guard pages and Linux permission changes are enforced immediately.
- Committed bytes are bounded independently from the guest virtual address
  range.
- Phase 2 does not couple interpreter correctness to translator layout work.

### Negative

- Every guest access performs software region lookup and bounds checking.
- Guest bytes are copied into ordinary Wasm32 allocations rather than directly
  addressed through a Memory64 memory.
- Large workloads will require paging and translator-oriented invalidation
  work before the browser can host CPython or compilers efficiently.

## Validation

The Worker dynamically instantiates the generated Memory64 probe, then runs the
same C, Rust, filesystem, and non-terminating AArch64 fixtures as the native
runtime. Playwright verifies the Memory64 gate, deterministic guest results,
structured instruction-limit diagnostics, and unconditional Worker
termination. Workspace checks compile the production crates for
`wasm32-unknown-unknown`.