Android 15 Native Shared Object 16KB Page-Size Alignment Invariant

Android 15 introduces runtime support for 16KB physical page sizes, deprecating legacy 4KB-only kernel assumptions across ARM64 and x86_64 targets. Any native shared library (.so) packaged without strict 16KB ELF segment alignment fails linker load verification, triggering fatal SIGSEGV crashes and dynamic linker aborts upon dlopen. This guardrail mandates minimum NDK r27+ toolchains, explicit -Wl,-z,max-page-size=16384 linker flags across all build layers, and automated verification before APK/AAB packaging.

--- description: Android 15 Native Shared Object 16KB Page-Size Alignment Invariant - Android 15 introduces runtime support for 16KB physical page sizes, deprecating legacy 4KB-only kernel assumptions across ARM64 and x86_64 targets. Any native shared library (.so) packaged without strict 16KB ELF segment alignment fails linker load verification, triggering fatal SIGSEGV crashes and dynamic linker aborts upon dlopen. This guardrail mandates minimum NDK r27+ toolchains, explicit -Wl,-z,max-page-size=16384 linker flags across all build layers, and automated verification before APK/AAB packaging. globs: **/CMakeLists.txt, **/Android.mk, **/build.gradle, **/build.gradle.kts, **/Cargo.toml, **/scripts/**/*.sh alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-alignment-guardrail" --- # Android 15 Native Shared Object 16KB Page-Size Alignment Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Shipping 4KB-Aligned Native Binaries Triggering Silent Linker Aborts and SIGSEGV on 16KB Android 15 Runtimes ## System Constraints You are a Principal Mobile Architect enforcing Android 15 16KB page-size alignment invariants. Mandate that all cross-compiled native code (CMake, ndk-build, Rust cargo-ndk, Go cgo, prebuilts) uses minimum 16384-byte ELF load segment alignment (-Wl,-z,max-page-size=16384) and NDK r27+. Reject any configuration that relies on default 4KB page assumptions or omits ELF segment verification in CI. ## Strict Guidelines - Engineers MUST ALWAYS upgrade the Android NDK to version r27 or higher in build.gradle(.kts) to ensure default 16KB page alignment in standard Clang/LLD toolchains. - Engineers MUST explicitly set -Wl,-z,max-page-size=16384 in CMakeLists.txt and Android.mk linker flags to guarantee compatibility when compiling with legacy NDK r26 or external native build systems. - Engineers MUST NOT bundle third-party or vendored prebuilt .so binaries without validating that every PT_LOAD segment's p_align attribute is >= 0x4000 (16384). - CI/CD pipelines MUST execute an automated verification script inspecting uncompressed ELF headers in compiled APK/AAB archives using readelf or llvm-readelf before release signing. - Native memory mmap calls inside C/C++/Rust code MUST NOT hardcode 4096 (PAGE_SIZE); code MUST dynamically query sysconf(_SC_PAGESIZE) or getpagesize() for all buffer allocations and mprotect boundaries. - Packaging configurations in build.gradle(.kts) MUST ensure android:extractNativeLibs is preserved correctly, and uncompressed native libs in the zip archive are 16KB-boundary aligned using zipalign -p 16384. ## Bad vs Good Implementations ### Gradle KTS and CMake Alignment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using an outdated NDK (< r27) without explicitly overriding max-page-size yields PT_LOAD segment alignment of 0x1000 (4KB). When executed on Android 15 running a 16KB kernel, the dynamic linker rejects the shared object, causing SIGSEGV or dlopen failure. ```kotlin // build.gradle.kts android { ndkVersion = "25.2.9519653" // NDK r25 defaults to 4KB page alignment defaultConfig { ndk { abiFilters += listOf("arm64-v8a", "x86_64") } externalNativeBuild { cmake { // Missing max-page-size flag; linker defaults to 4096 bytes cppFlags += listOf("-O3") } } } } ``` #### Production Standard (Correct) > **Standard**: NDK r27+ coupled with -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON configures the LLD linker to emit 16KB (0x4000) PT_LOAD alignment. Disabling legacy packaging ensures AGP runs zipalign with 16KB page boundary alignment for uncompressed .so files. ```kotlin // build.gradle.kts android { ndkVersion = "27.1.12297006" // NDK r27+ supports 16KB page alignment natively defaultConfig { ndk { abiFilters += listOf("arm64-v8a", "x86_64") } externalNativeBuild { cmake { // Explicitly ensure 16KB page boundary alignment across all link steps arguments += listOf("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON") cppFlags += listOf("-O3") cFlags += listOf("-O3") } } } packaging { jniLibs { useLegacyPackaging = false // Enforces uncompressed 16KB-aligned packaging } } } ``` ### CMakeLists.txt Linker Configuration and Verification Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Standard target compilation without explicit linker flags on older toolchains defaults to 4KB max-page-size. If compiled with pre-r27 NDK or customized sysroots, the generated ELF will crash on 16KB Android 15 runtimes. ```cmake # CMakeLists.txt cmake_minimum_required(VERSION 3.22.1) project("native_engine") add_library(native_engine SHARED native_engine.cpp) target_link_libraries(native_engine android log) ``` #### Production Standard (Correct) > **Standard**: Explicitly passing '-Wl,-z,max-page-size=16384' forces the linker to align ELF segments to 16KB boundaries (0x4000), making the shared library executable on both 4KB and 16KB page-size Android kernels. ```cmake # CMakeLists.txt cmake_minimum_required(VERSION 3.22.1) project("native_engine") add_library(native_engine SHARED native_engine.cpp) # Enforce 16KB alignment for both 64-bit architectures supported on Android 15 if(ANDROID_ABI STREQUAL "arm64-v8a" OR ANDROID_ABI STREQUAL "x86_64") target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384") endif() target_link_libraries(native_engine android log) ``` ### CI Automated ELF Alignment Verification Script #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Simply checking file existence misses misaligned PT_LOAD segments in third-party or vendored prebuilts. ```bash #!/usr/bin/env bash # Checks existence but fails to verify ELF segment alignment for so in $(find app/build/intermediates -name "*.so"); do echo "Found shared library: $so" done echo "Verification passed!" ``` #### Production Standard (Correct) > **Standard**: Parses every PT_LOAD segment using llvm-readelf, verifying that alignment is >= 16384 bytes (0x4000). Immediately fails CI before release artifacts can reach production. ```bash #!/usr/bin/env bash set -euo pipefail # Scan all 64-bit shared objects for Android 15 16KB page alignment FAILED=0 while IFS= read -r -d '' so_file; do # Extract LOAD segment alignments using llvm-readelf or readelf alignments=$(llvm-readelf -lW "$so_file" | awk '/LOAD/ { print $NF }') for align in $alignments; do # 0x4000 = 16384 bytes (16KB) minimum if [[ "$((align))" -lt 16384 ]]; then echo "ERROR: $so_file has misaligned LOAD segment (alignment: $align, expected >= 16384)" >&2 FAILED=1 fi done done < <(find . -type f -name "*.so" -path "*/arm64-v8a/*" -print0) if [[ $FAILED -ne 0 ]]; then echo "Android 15 16KB Page Alignment Invariant Violated. Aborting build." >&2 exit 1 fi echo "All native libraries satisfy 16KB alignment." ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 Native Shared Object 16KB Page-Size Alignment Invariant

Android 15 Native Shared Object 16KB Page-Size Alignment Invariant defines an industrial-grade behavioral standard for mobile engineering. Android 15 introduces runtime support for 16KB physical page sizes, deprecating legacy 4KB-only kernel assumptions across ARM64 and x86_64 targets. Any native shared library (.so) packaged without strict 16KB ELF segment alignment fails linker load verification, triggering fatal SIGSEGV crashes and dynamic linker aborts upon dlopen. This guardrail mandates minimum NDK r27+ toolchains, explicit -Wl,-z,max-page-size=16384 linker flags across all build layers, and automated verification before APK/AAB packaging. 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: Shipping 4KB-Aligned Native Binaries Triggering Silent Linker Aborts and SIGSEGV on 16KB Android 15 Runtimes 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	Shipping 4KB-Aligned Native Binaries Triggering Silent Linker Aborts and SIGSEGV on 16KB Android 15 Runtimes	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 upgrade the Android NDK to version r27 or higher in build.gradle(.kts) to ensure default 16KB page alignment in standard Clang/LLD toolchains.

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.