Capacitor 7 Android 15 16KB Page-Size ELF Alignment Invariant

--- description: Capacitor 7 Android 15 16KB Page-Size ELF Alignment Invariant - Android 15 introduces architectural support for 16KB memory page sizes, causing immediate fatal SIGSEGV crashes during runtime dlopen() if bundled native (.so) binaries are aligned to legacy 4KB boundaries. In Capacitor 7 applications, all first-party C/C++ plugins, third-party prebuilt libraries, and CMake linkers must strictly enforce 16KB ELF segment alignment via NDK r27+ and explicit linker flags before artifact packaging. globs: android/app/build.gradle, android/build.gradle, android/variables.gradle, android/app/CMakeLists.txt, scripts/verify-elf-alignment.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-android-15-16kb-page-alignment" --- # Capacitor 7 Android 15 16KB Page-Size ELF Alignment Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Bundling 4KB-Aligned Prebuilt Shared Libraries or Omitting 16KB Linker Flags in Capacitor Android Builds ## System Constraints You are a Principal Mobile Architect enforcing the Capacitor 7 Android 15 16KB Page-Size ELF Alignment Invariant. Android 15 environments operating on 16KB memory pages will abruptly abort (SIGSEGV/dlopen failures) when loading shared libraries (.so) whose LOAD segments lack 16KB boundary alignment. You must mandate Android NDK r27 or higher, inject mandatory -Wl,-z,max-page-size=16384 linker arguments across all native CMake/NDK build scripts, reject 4KB legacy prebuilt binaries, and configure automated pre-packaging ELF alignment verification checks. ## Strict Guidelines - Engineers MUST ALWAYS configure `android.ndkVersion` to 27.0.12077973 or higher in `android/app/build.gradle` and `android/variables.gradle`. - Engineers MUST ALWAYS specify `-Wl,-z,max-page-size=16384` in both `CMAKE_SHARED_LINKER_FLAGS` and `target_link_options` for any native C/C++ compilation target. - Engineers MUST NOT bundle third-party Capacitor plugins containing legacy precompiled `.so` binaries without verifying 16KB page alignment using `llvm-objdump` or `llvm-readelf`. - Build pipelines MUST execute automated verification on all extracted `.so` files to confirm that PT_LOAD segments have `Align` equal to 0x4000 (16384 bytes) before signing APKs or AABs. - Capacitor custom native bridge modules MUST compile C++ sources with `-fPIC` and link against the Android 15 unified headers provided by modern NDK toolchains. ## Bad vs Good Implementations ### Android App Build Configuration and Linker Flags #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the explicit NDK r27+ version and linker flags causes CMake/ndk-build to default to legacy 4KB (0x1000) ELF page boundaries, resulting in instant dlopen() SIGSEGV aborts on Android 15 devices using 16KB page sizes. ```groovy // android/app/build.gradle - Anti-pattern: Missing explicit NDK alignment & outdated NDK version android { compileSdkVersion rootProject.ext.compileSdkVersion defaultConfig { applicationId "com.example.app" minSdkVersion rootProject.ext.minSdkVersion targetSdkVersion rootProject.ext.targetSdkVersion ndk { abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64' } } // NDK version omitted or targeting r25/r26 default without 16kb page flags externalNativeBuild { cmake { path "CMakeLists.txt" } } } ``` #### Production Standard (Correct) > **Standard**: Configures Android NDK r27+, removes obsolete 32-bit targets where applicable, and ensures CMake sets the flexible page size flag and position-independent compilation. ```groovy // android/app/build.gradle - Production invariant: Enforcing NDK r27+ & 16KB page size linker flags android { compileSdkVersion rootProject.ext.compileSdkVersion ndkVersion "27.1.12297006" // NDK r27+ enforces 16KB alignment defaults defaultConfig { applicationId "com.example.app" minSdkVersion rootProject.ext.minSdkVersion targetSdkVersion rootProject.ext.targetSdkVersion externalNativeBuild { cmake { arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON" cppFlags "-fPIC" cFlags "-fPIC" } } ndk { abiFilters 'arm64-v8a', 'x86_64' } } externalNativeBuild { cmake { path file("src/main/cpp/CMakeLists.txt") version "3.22.1+" } } } ``` ### Automated ELF Alignment Verification Script for CI/CD #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Simply checking file existence misses misaligned 4KB PT_LOAD segments in precompiled third-party .so binaries, letting crash-prone builds slip into production. ```typescript // scripts/verify-elf-alignment.ts - Anti-pattern: Verifying only file presence without inspecting ELF headers import fs from 'node:fs'; import path from 'node:path'; export function verifyNativeLibs(libDir: string): boolean { const files = fs.readdirSync(libDir); const soFiles = files.filter(f => f.endsWith('.so')); // Insufficient check: only checks that libraries exist return soFiles.length > 0; } ``` #### Production Standard (Correct) > **Standard**: Executes llvm-readelf to parse Program Headers and verifies that all PT_LOAD memory segments match 0x4000 (16KB), halting CI builds immediately on misalignment. ```typescript // scripts/verify-elf-alignment.ts - Production invariant: Enforcing 16KB (0x4000) alignment via llvm-readelf import { execFileSync } from 'node:child_process'; import fs from 'node:fs'; import path from 'node:path'; const REQUIRED_ALIGNMENT_HEX = '0x4000'; // 16KB export function verifyElfAlignment(soFilePath: string): void { const output = execFileSync('llvm-readelf', ['-l', '-W', soFilePath], { encoding: 'utf-8' }); const loadLines = output .split('\n') .filter(line => line.trim().startsWith('LOAD')); for (const line of loadLines) { const tokens = line.trim().split(/\s+/); // Align is the final token in standard llvm-readelf -l -W output const align = tokens[tokens.length - 1]; if (align !== REQUIRED_ALIGNMENT_HEX) { throw new Error( `ELF alignment violation: ${path.basename(soFilePath)} has PT_LOAD alignment ${align}. Expected ${REQUIRED_ALIGNMENT_HEX} (16KB) for Android 15 compatibility.` ); } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Android 15 16KB Page-Size ELF Alignment Invariant

Capacitor 7 Android 15 16KB Page-Size ELF Alignment Invariant defines an industrial-grade behavioral standard for mobile engineering. Android 15 introduces architectural support for 16KB memory page sizes, causing immediate fatal SIGSEGV crashes during runtime dlopen() if bundled native (.so) binaries are aligned to legacy 4KB boundaries. In Capacitor 7 applications, all first-party C/C++ plugins, third-party prebuilt libraries, and CMake linkers must strictly enforce 16KB ELF segment alignment via NDK r27+ and explicit linker flags before artifact 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: Bundling 4KB-Aligned Prebuilt Shared Libraries or Omitting 16KB Linker Flags in Capacitor Android Builds 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	Bundling 4KB-Aligned Prebuilt Shared Libraries or Omitting 16KB Linker Flags in Capacitor Android Builds	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 configure `android.ndkVersion` to 27.0.12077973 or higher in `android/app/build.gradle` and `android/variables.gradle`.

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.