.known-couplings/allocator-alignment.md
align attributes must match the runtime's guaranteeinit_runtime (src/libponyc/codegen/codegen.c) declares an align return attribute on each runtime allocator — HEAP_MIN for the heap allocators (pony_alloc*) and POOL_MIN for the pool allocators (pony_create, pony_alloc_msg). These must equal the alignment the runtime actually provides (HEAP_MIN in src/libponyrt/mem/heap.h, POOL_MIN in src/libponyrt/mem/pool.h): declaring more is undefined behaviour, and declaring less under-aligns object fields — the HeapToStack pass (src/libponyc/codegen/genopt.cc) derives a promoted stack alloca's alignment from these attributes, so too-weak values crash optimised builds for types with over-aligned fields like U128 (issue #5462). The bug only manifests in release/optimised builds, so debug tests pass while release ones crash. Run: make test-core (it runs the full-program tests in both debug and release). HEAP_MIN has a second codegen consumer: pointer_min_alloc (src/libponyc/codegen/genprim.c) lowers Pointer._min_alloc() to max(1, HEAP_MIN / element_size), the floor String/Array use when allocating (constructors, reserve, compact) so they never record a capacity below the block the allocator returns. Its failure mode is milder (suboptimal reallocations, not UB), but changing HEAP_MIN changes those collections' minimum capacity. Both consumers are noted at the HEAP_MIN definition in heap.h. Run: make test-stdlib-debug test-stdlib-release.