Capacitor 7 Synchronous JSI Native Bridge Memory Alignment Invariant

--- description: Capacitor 7 Synchronous JSI Native Bridge Memory Alignment Invariant - Mandates strict zero-copy memory alignment and deterministic ArrayBuffer recycling for high-frequency native telemetry through Capacitor 7 JSI bridge interfaces. Prohibits JSON serialization, asynchronous message queuing, and unaligned byte-offset memory operations across the native runtime boundary to eliminate main-thread UI stalls. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/capacitor-7-jsi-bridge-memory-alignment-invariant" --- # Capacitor 7 Synchronous JSI Native Bridge Memory Alignment Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Streaming high-frequency hardware sensor data across the legacy asynchronous JSON bridge with unaligned, continuously re-allocated buffers. ## System Constraints You are a Principal Mobile Architect enforcing Capacitor 7 Synchronous JSI Native Bridge Memory Alignment Invariants. You must eliminate all main-thread UI stalls and frame drops in real-time mobile applications by mandating synchronous zero-copy JavaScript Interface (JSI) host object communication for high-frequency hardware data (>= 60Hz). Reject asynchronous postMessage bridges, JSON serialization, unaligned TypedArray byte offsets, and per-frame heap allocations. ## Strict Guidelines - Engineers MUST ALWAYS verify that native memory pointers bound to TypedArrays are strictly aligned to the element byte width (e.g., 4-byte boundaries for Float32Array/Uint32Array, 8-byte boundaries for Float64Array). - Engineers MUST NOT route high-frequency (>60Hz) telemetry, audio buffers, or sensor frames through the standard Capacitor asynchronous JSON message bridge (`Capacitor.toNative` / `Capacitor.fromNative`). - Code SHOULD pre-allocate static, reusable `ArrayBuffer` instances to prevent garbage collection pauses during high-frequency telemetry loops. - Services MUST validate that underlying `ArrayBuffer` instances have not been detached or transferred before executing synchronous JSI invocations. - Components NEVER instantiate dynamic TypedArray views inside requestAnimationFrame or microtask loops without verifying that `byteOffset % TypedArray.BYTES_PER_ELEMENT === 0`. ## Bad vs Good Implementations ### High-Frequency Native Telemetry Ingestion #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Routing 120Hz sensor updates through the asynchronous Capacitor message bridge forces JSON stringification, native-to-JS bridge dispatch queues, and per-frame heap allocations. This introduces 16-33ms main-thread UI frame stalls and trigger garbage collection freezes. ```typescript import { Plugins } from '@capacitor/core'; const { MotionTracker } = Plugins; // Anti-pattern: High-frequency telemetry via asynchronous message queue with JSON serialization export function listenToHardwareMotion() { MotionTracker.addListener('telemetryFrame', (data: { x: number; y: number; z: number; timestamp: number }) => { // JSON deserialization, bridge queue congestion, and main-thread JS heap thrashing updateSceneOrientation(data.x, data.y, data.z); }); } ``` #### Production Standard (Correct) > **Standard**: Uses direct synchronous JSI memory passing via a pre-allocated, 8-byte aligned Float64Array. Data is transferred via zero-copy native memory reference semantics with zero JSON serialization, avoiding bridge queues and heap churn entirely. ```typescript interface JsiNativeTelemetryBridge { syncDirectTelemetry(buffer: ArrayBuffer, byteOffset: number, byteLength: number): number; } declare const __NativeTelemetryJSI: JsiNativeTelemetryBridge | undefined; const FLOAT64_BYTES = 8; const TELEMETRY_FIELD_COUNT = 4; // x, y, z, timestamp const BUFFER_SIZE_BYTES = TELEMETRY_FIELD_COUNT * FLOAT64_BYTES; // Pre-allocated static buffer to guarantee zero allocation in critical path const telemetryBuffer = new ArrayBuffer(BUFFER_SIZE_BYTES); const telemetryView = new Float64Array(telemetryBuffer); export function pollHardwareMotionZeroCopy(): { x: number; y: number; z: number; timestamp: number } { if (!__NativeTelemetryJSI) { throw new Error('Capacitor JSI Bridge runtime binding unavailable'); } // Invariant: Verify buffer is attached if (telemetryBuffer.byteLength === 0) { throw new RangeError('Telemetry ArrayBuffer has been detached'); } // Invariant: Enforce 8-byte memory alignment boundary for 64-bit float access if (telemetryView.byteOffset % FLOAT64_BYTES !== 0) { throw new TypeError(`Memory unaligned: byteOffset ${telemetryView.byteOffset} must align to ${FLOAT64_BYTES} bytes`); } const bytesRead = __NativeTelemetryJSI.syncDirectTelemetry( telemetryBuffer, telemetryView.byteOffset, telemetryView.byteLength ); if (bytesRead !== BUFFER_SIZE_BYTES) { throw new Error(`Incomplete JSI memory copy: expected ${BUFFER_SIZE_BYTES} bytes, received ${bytesRead}`); } return { x: telemetryView[0], y: telemetryView[1], z: telemetryView[2], timestamp: telemetryView[3], }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Capacitor 7 Synchronous JSI Native Bridge Memory Alignment Invariant

Capacitor 7 Synchronous JSI Native Bridge Memory Alignment Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates strict zero-copy memory alignment and deterministic ArrayBuffer recycling for high-frequency native telemetry through Capacitor 7 JSI bridge interfaces. Prohibits JSON serialization, asynchronous message queuing, and unaligned byte-offset memory operations across the native runtime boundary to eliminate main-thread UI stalls. 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: Streaming high-frequency hardware sensor data across the legacy asynchronous JSON bridge with unaligned, continuously re-allocated buffers. 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	Streaming high-frequency hardware sensor data across the legacy asynchronous JSON bridge with unaligned, continuously re-allocated buffers.	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 verify that native memory pointers bound to TypedArrays are strictly aligned to the element byte width (e.g., 4-byte boundaries for Float32Array/Uint32Array, 8-byte boundaries for Float64Array).

Engineers MUST ALWAYS verify that native memory pointers bound to TypedArrays are strictly aligned to the element byte width (e.g., 4-byte boundaries for Float32Array/Uint32Array, 8-byte boundaries for Float64Array).

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.