Application allocator selection

Sigil selects mimalloc 3.5.3 for the shipped Linux x86_64 static sigil CLI, Linux x86_64 static-musl applications and C-to-WASM builds using toolchain: 'zig and target: "wasm32-wasi". Other targets retain their current libc allocator. Direct-WASM retains its linear-memory allocator. JavaScript buffers remain owned by JavaScript.

Selection belongs to the final application's build config. To use libc:

(config
  name: 'web-stock
  toolchain: 'zig
  target: "wasm32-wasi"
  features: '(release allocator-stock))

allocator-mimalloc explicitly requests mimalloc; it fails on an unqualified target. Declaring both selection features is an error. Dependencies do not select the executable's allocator.

WASI allocator objects automatically receive these compile-time defines:

MI_FREE_USE_PAGEMAP=1
MI_DEFAULT_ARENA_RESERVE=4096
MI_ARENA_SLICE_SHIFT=14

The arena reservation is in KiB; the slice shift selects 16 KiB slices. An application may override these three settings through typed defines: pairs in its config, for example defines: '((MI_DEFAULT_ARENA_RESERVE . 8192)). Pagemap accepts 0 or 1, reservation accepts 1024–2097152 KiB, and the slice shift accepts 14–20. Invalid or duplicate settings fail. Defaults are the qualified configuration; different settings need application measurement. The reservation ceiling is 2 GiB, leaving headroom below wasm32's 4 GiB address-space limit and avoiding overflowing a 32-bit size calculation. Typed MI_* settings require the WASI mimalloc backend; other targets, explicit stock selection and unknown MI_* names are rejected. These settings apply only to the WASI mimalloc object. Raw -DMI_*/-UMI_* C flags are rejected so the selected policy is explicit.

Arena reservation also has an upstream runtime option (mi_option_arena_reserve) for future reservations. A runtime change cannot reverse previous WASM memory growth. The browser loader supplies no WASI environment entries, so shell allocator environment variables do not configure a browser application.

The final link supplies one allocator object before runtime and vendor archives. The object cache records the source files, compiler/SDK contents, target and effective flags; changing settings selects a new recipe and requires relinking and WASM post-processing. Selection features also enter Sigil compile identities, so switching to stock can recompile modules. Typed WASI settings also enter the libsigil archive key through config-defines, so changing one forces a libsigil rebuild; unaffected module objects remain reusable when their other compile inputs are unchanged. Compilers or wrappers without a complete SDK fingerprint rebuild the allocator object rather than reuse an uncertain result. Stock selection removes the malloc override. Zig SDK preparation still protects stock SmpAllocator fallback configurations.

(sigil meta) exports (sigil-allocator) to report the linked allocator identity, including target, pinned source digest and effective mimalloc defines. Native and WASI links also write a .allocator identity sidecar beside the executable or WebAssembly module.

The C interface is in <sigil/allocator.h>. It defines allocation, zeroing, reallocation, aligned allocation, freeing and snapshots. Returned pointers use the executable's libc allocation domain without a private block header. Foreign libraries with private allocation domains must retain their own destructors. Failed reallocation preserves the input; a zero-size reallocation frees it.

Snapshot contract-call/request totals and backend capacity are distinct. Requested bytes are cumulative successful requests, not current live bytes. Availability bits identify backend reservation, commitment and cumulative purge measurements; unavailable measurements remain zero. The counters do not claim a census of libc/vendor calls or resident memory. GC sizing, trim and scratch cache policy remain separate.

make test-allocators runs the actual-link matrix, guarded-process checks, foreign-pointer ownership/SQLite controls and release-identity checks against the built static CLI and its archives. Set ALLOCATOR_TOOLCHAIN_DIR to the pinned Zig SDK root (containing zig/zig) and ALLOCATOR_TEST_CONFIG to the static config being checked. This gate is required by CI, full release builds and make test-release-suite; missing inputs fail rather than skip.