Capacitor 7 Android 16KB Page-Alignment Runtime Invariant

--- description: Capacitor 7 Android 16KB Page-Alignment Runtime Invariant - Enforces that all bundled native NDK dependencies, custom C/C++ plugins, and third-party shared libraries (.so) in Capacitor 7 projects strictly comply with Android 15 (API level 35+) 16KB memory page alignment. Non-compliant 4KB-aligned ELF segments fail dynamic linker verification on 16KB kernels, leading to immediate SIGSEGV crashes at process startup. globs: android/app/build.gradle, android/build.gradle, android/app/CMakeLists.txt, android/app/src/main/jniLibs/**, scripts/**/*.{js,ts,sh} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-android-16kb-page-alignment" --- # Capacitor 7 Android 16KB Page-Alignment Runtime Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Shipping unaligned 4KB ELF dynamic libraries or unverified native NDK binaries that trigger SIGSEGV dynamic linker crashes on Android 15+ devices. ## System Constraints You are a Principal Mobile Systems Architect enforcing the Capacitor 7 Android 16KB Page-Alignment Runtime Invariant. Android 15 introduces support for 16KB memory page sizes alongside traditional 4KB pages. Any native shared library (.so) packaged into an APK/AAB whose PT_LOAD ELF segments are aligned to only 4KB boundaries will immediately crash via linker segmentation fault (SIGSEGV) when loaded on 16KB kernels. You must ensure NDK compilation flags, Gradle packaging parameters, and CI validation pipelines explicitly enforce and verify 16KB alignment across all architectures (arm64-v8a, x86_64). ## Strict Guidelines - Engineers MUST ALWAYS compile native C/C++ code using NDK r27 or newer with linker flags `-Wl,-z,max-page-size=16384`. - Engineers MUST NEVER package unverified legacy third-party `.so` binaries without running dynamic linker alignment audits via readelf or llvm-objdump. - Build scripts SHOULD execute automated pre-bundle validation checks checking `LOAD` segment alignment boundaries across all `.so` files in `android/app/build/intermediates/merged_native_libs`. - Gradle build files MUST configure packagingOptions to avoid unaligned zip compression of native libraries when targeting Android 15+. - CI pipelines MUST fail builds immediately if any ELF shared library contains a loadable segment with alignment less than 0x4000 (16384 bytes). ## Bad vs Good Implementations ### Configuring CMakeLists.txt and build.gradle for 16KB Alignment Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default NDK builds prior to r28 or projects missing explicit max-page-size linker flags produce 4KB-aligned ELF segments. When the Capacitor app is deployed on an Android 15 device with 16KB kernel pages enabled, dlopen() fails and terminates the process with SIGSEGV. ```groovy // android/app/build.gradle - Anti-pattern: Missing max-page-size linker flags and zero ELF validation android { compileSdkVersion 35 defaultConfig { applicationId "com.example.app" minSdkVersion 24 targetSdkVersion 35 ndk { abiFilters 'arm64-v8a', 'x86_64' } } // Leaves native shared libraries bundled at default 4KB page alignment } ``` #### Production Standard (Correct) > **Standard**: Configures the NDK linker flags to mandate `-Wl,-z,max-page-size=16384`, ensures uncompressed page-aligned native library packaging via useLegacyPackaging = false, and registers an automated build verification step ensuring PT_LOAD segments conform to 0x4000 boundary constraints. ```groovy // android/app/build.gradle - Production standard: Explicit linker flags and verification task android { compileSdkVersion 35 defaultConfig { applicationId "com.example.app" minSdkVersion 24 targetSdkVersion 35 ndk { abiFilters 'arm64-v8a', 'x86_64' } externalNativeBuild { cmake { arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON", "-DCMAKE_SHARED_LINKER_FLAGS=-Wl,-z,max-page-size=16384" } } } packagingOptions { jniLibs { useLegacyPackaging = false } } } tasks.register('verify16kbPageAlignment') { doLast { fileTree(dir: "$buildDir/intermediates/merged_native_libs", include: '**/*.so').each { file -> def proc = ["readelf", "-l", "${file.absolutePath}"].execute() def output = proc.text if (output.contains("LOAD") && !output.contains("0x4000")) { throw new GradleException("16KB alignment violation detected in: ${file.name}") } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Android 16KB Page-Alignment Runtime Invariant

Capacitor 7 Android 16KB Page-Alignment Runtime Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces that all bundled native NDK dependencies, custom C/C++ plugins, and third-party shared libraries (.so) in Capacitor 7 projects strictly comply with Android 15 (API level 35+) 16KB memory page alignment. Non-compliant 4KB-aligned ELF segments fail dynamic linker verification on 16KB kernels, leading to immediate SIGSEGV crashes at process startup. 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 unaligned 4KB ELF dynamic libraries or unverified native NDK binaries that trigger SIGSEGV dynamic linker crashes on Android 15+ devices. 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 unaligned 4KB ELF dynamic libraries or unverified native NDK binaries that trigger SIGSEGV dynamic linker crashes on Android 15+ devices.	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 compile native C/C++ code using NDK r27 or newer with linker flags `-Wl,-z,max-page-size=16384`.

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.