Android 15 16KB Page Size Native Library Memory Invariant

Enforces strict 16KB (0x4000) ELF load segment alignment across all compiled C/C++ native shared objects (.so files) and build configurations targeted for Android 15 (API level 35) and above. Failure to align ELF segments on 16KB boundaries causes immediate mmap failures, dynamic linker aborts (SIGSEGV/SIGBUS), and application crashes on devices running 16KB page size kernels. All NDK toolchains, CMake scripts, and Gradle build configurations must explicitly configure max-page-size linker flags and audit prebuilt binary dependencies.

--- description: Android 15 16KB Page Size Native Library Memory Invariant - Enforces strict 16KB (0x4000) ELF load segment alignment across all compiled C/C++ native shared objects (.so files) and build configurations targeted for Android 15 (API level 35) and above. Failure to align ELF segments on 16KB boundaries causes immediate mmap failures, dynamic linker aborts (SIGSEGV/SIGBUS), and application crashes on devices running 16KB page size kernels. All NDK toolchains, CMake scripts, and Gradle build configurations must explicitly configure max-page-size linker flags and audit prebuilt binary dependencies. globs: **/CMakeLists.txt, **/Android.mk, **/build.gradle, **/build.gradle.kts, **/*.cmake alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-size-alignment-guardrail" --- # Android 15 16KB Page Size Native Library Memory Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Compiling or bundling 4KB-aligned native shared libraries (.so) causing dynamic linker crashes on Android 15 16KB kernel targets ## System Constraints You are a Principal Mobile Systems Architect enforcing the Android 15 16KB Page Size Native Library Memory Invariant. Mandate strict ELF segment alignment (-Wl,-z,max-page-size=16384) in all CMake, ndk-build, and Gradle compilation scripts. Reject prebuilt libraries that fail 16KB boundary checks, ensure mmap/munmap operations use dynamic sysconf(_SC_PAGESIZE) or getpagesize(), and prevent hardcoded 4096-byte memory assumptions in native code. ## Strict Guidelines - Engineers MUST ALWAYS supply '-Wl,-z,max-page-size=16384' to linker flags across all CMake, ndk-build, and custom toolchain scripts targeting Android NDK r27 or earlier (NDK r28+ defaults to 16KB). - Engineers MUST NOT hardcode 4096 or 4KB page size constants in native C/C++ code; dynamic queries via sysconf(_SC_PAGESIZE) or getpagesize() MUST be used for memory mappings and buffer alignments. - Build systems MUST audit all third-party prebuilt .so binaries using llvm-readelf or readelf (-lW) to verify that LOAD segments exhibit 'Align' values >= 0x4000 (16384 bytes). - Gradle scripts MUST enforce 'packaging { jniLibs { useLegacyPackaging = false } }' or equivalent uncompressed, page-aligned page-zip alignment when bundling native libraries inside APKs. - Engineers MUST NEVER suppress or bypass Android 15 16KB runtime checks using legacy ABI fallback mechanisms or unsupported linker flags. - Native memory allocators and custom ring buffers MUST calculate alignments using round-up macros parameterized by the runtime system page size rather than bit-shift constants like '>> 12'. ## Bad vs Good Implementations ### CMake Native Linker Configuration for 16KB Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting explicit max-page-size linker flags on NDK versions prior to r28 compiles ELF segments with 4KB (0x1000) alignment. When loaded on Android 15 devices running a 16KB page size kernel, linker64 fails to mmap the segment, triggering a fatal abort during dlopen(). ```cmake # CMakeLists.txt - Implicitly defaults to legacy 4KB (0x1000) ELF segment alignment cmake_minimum_required(VERSION 3.22.1) project(native_crypto) add_library(native_crypto SHARED src/crypto.cpp src/memory_pool.cpp ) target_link_libraries(native_crypto android log ) ``` #### Production Standard (Correct) > **Standard**: Explicitly passing '-Wl,-z,max-page-size=16384' instructs the linker (lld) to align all PT_LOAD segment virtual addresses and file offsets to 16KB boundaries, satisfying the Android 15 kernel invariant without breaking backwards compatibility on 4KB devices. ```cmake # CMakeLists.txt - Explicitly enforces 16KB (0x4000) ELF segment alignment cmake_minimum_required(VERSION 3.22.1) project(native_crypto) add_library(native_crypto SHARED src/crypto.cpp src/memory_pool.cpp ) # Mandate 16KB max page size alignment for Android 15 compatibility target_link_options(native_crypto PRIVATE "-Wl,-z,max-page-size=16384" ) target_link_libraries(native_crypto android log ) ``` ### Native C++ Memory Allocation Dynamic Page Sizing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Hardcoding 4096-byte page sizes causes memory calculations to produce lengths and alignments incompatible with 16KB kernels. Calling mmap with sizes misaligned with true kernel page sizes causes sub-page aliasing bugs, and munmap with sub-16KB sizes fails or unmaps unintended memory ranges. ```cpp // memory_pool.cpp - Hardcoded 4KB page size assumptions #include <sys/mman.h> #include <unistd.h> #define PAGE_SIZE_BYTES 4096 #define PAGE_ALIGN_MASK (~(PAGE_SIZE_BYTES - 1)) void* allocate_page_aligned(size_t size) { // Fails on 16KB page kernels: mmap length must be a multiple of the actual page size size_t aligned_size = (size + PAGE_SIZE_BYTES - 1) & PAGE_ALIGN_MASK; void* ptr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); return ptr; } ``` #### Production Standard (Correct) > **Standard**: Queries sysconf(_SC_PAGESIZE) dynamically at runtime and caches the result. Memory boundary math adapts transparently to both 4KB legacy devices and 16KB Android 15 devices, ensuring mmap, munmap, and mprotect operations operate on valid boundary multiples. ```cpp // memory_pool.cpp - Dynamically resolved system page size #include <sys/mman.h> #include <unistd.h> #include <cstdint> inline size_t get_system_page_size() { static const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE)); return page_size; } void* allocate_page_aligned(size_t size) { const size_t page_size = get_system_page_size(); const size_t page_mask = ~(page_size - 1); size_t aligned_size = (size + page_size - 1) & page_mask; void* ptr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); return (ptr == MAP_FAILED) ? nullptr : ptr; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page Size Native Library Memory Invariant

Android 15 16KB Page Size Native Library Memory Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces strict 16KB (0x4000) ELF load segment alignment across all compiled C/C++ native shared objects (.so files) and build configurations targeted for Android 15 (API level 35) and above. Failure to align ELF segments on 16KB boundaries causes immediate mmap failures, dynamic linker aborts (SIGSEGV/SIGBUS), and application crashes on devices running 16KB page size kernels. All NDK toolchains, CMake scripts, and Gradle build configurations must explicitly configure max-page-size linker flags and audit prebuilt binary dependencies. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Compiling or bundling 4KB-aligned native shared libraries (.so) causing dynamic linker crashes on Android 15 16KB kernel targets Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Compiling or bundling 4KB-aligned native shared libraries (.so) causing dynamic linker crashes on Android 15 16KB kernel targets	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS supply '-Wl,-z,max-page-size=16384' to linker flags across all CMake, ndk-build, and custom toolchain scripts targeting Android NDK r27 or earlier (NDK r28+ defaults to 16KB).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.