Imported from dwijendrapydimarri-collab/cardinal (AGENTS.md). Install upstream with npx skills add dwijendrapydimarri-collab/cardinal. Copyright stays with the author.

Cardinal: On-Device Perceptual Threat Defense Architecture

1. Operational Directives & Golden Path

Cardinal is a real-time, 100% on-device perceptual threat defense system engineered for Android (optimized for iQOO / Vivo devices with Snapdragon Hexagon NPU). It intercepts screen content via MediaProjection, processes downsampled perceptual probes, detects sensitive information exposures (OTP, PAN) and phishing attempts, and applies hardware-accelerated overlays (redaction masks and non-occluding threat banners).

5-Phase Golden Path

1. Phase 1: Foundation
   • MediaProjection foreground service (CardinalProjectionService) with foregroundServiceType="mediaProjection".
   • VirtualDisplay calibrated at 270x600 probe intake.
   • ImageReader buffer intake with zero-allocation direct byte buffer pool.
   • WindowManager TYPE_APPLICATION_OVERLAY passthrough canvas harness.
2. Phase 2: Deterministic Fast-Path
   • Bundled offline ML Kit Latin Text Recognition.
   • Deterministic Regex matchers for 6-digit OTPs (\b(?<!\d)\d{6}(?!\d)\b) and Indian PAN identifiers ([A-Z]{5}[0-9]{4}[A-Z]{1}).
   • ProximityAnchorGraph linking contextual auth anchors ("OTP", "Code", "PAN") to numeric tokens via spatial 2D Euclidean distance.
   • RedactionMaskView dynamic coordinate black box with 500ms hold-to-reveal safety mechanism.
3. Phase 3: Catalytic Risk Engine & Threat Card
   • FrameAdmissionController 64-bit luminance pHash change gate with Hamming distance < 2 static frame rejection.
   • Vivo/iQOO secure keyboard lower 40% screen blackout handling.
   • Dark mode contrast inversion LUT for OCR fidelity.
   • CatalyticPolicyArbiter multiplicative risk formula: compositeScore = clamp(0, 100, floor(BaseScore * AttackMultiplier * TrustModifier))
   • ThreatCardView non-occluding bottom banner with 36dp lateral margins and systemGestureExclusionRects = emptyList().
4. Phase 4: On-Device Model & Hardware Acceleration
   • ExecuTorch runtime integration targeting Snapdragon Hexagon NPU.
   • 3-tier fallback architecture: NPU Hexagon delegate -> Quantized CPU thread -> Deterministic Heuristic Arbiter.
5. Phase 5: Test Lab & Airplane Mode Hardening
   • DemoHarnessActivity offline test lab with mock fixtures in assets.
   • DeskLensActivity with CameraX offline scanning.
   • Zero-network manifest verification test.
   • Unit and integration tests covering pHash, admission, regex, proximity graph, policy arbiter, and SHA-256 tamper-evident hash chain.

2. Hardware Invariants & Coding Rules

1. Zero-Egress Invariant:

   • android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE are strictly forbidden.
   • Zero network libraries (no OkHttp, Retrofit, Ktor, Volley).
   • Cardinal runs completely offline, guaranteed in Airplane Mode.

2. Buffer Lifecycle Management:

   • Always acquire and release Image objects inside try-finally immediately (image.close() in finally).
   • Prevents ImageReader queue starvation and pipeline stalls.

3. Zero Allocations in the Per-Frame Hot Loop:

   • No Bitmap.createBitmap(), new ByteArray(), or short-lived allocations inside onImageAvailable() or frame admission.
   • Direct ByteBuffers (ByteBuffer.allocateDirect()) and bitmaps are pre-allocated and pooled.

4. System Touch & Gesture Safety:

   • Redaction overlays must declare FLAG_NOT_FOCUSABLE and FLAG_NOT_TOUCH_MODAL.
   • Passthrough outside bounds: Touch events outside redaction boxes return false to allow normal OS interaction.
   • Threat cards enforce 36dp lateral touch corridors for edge back gestures.

5. Coordinate Space Affine Mapping:

   • Overlay positions are dynamically scaled from 270x600 probe intake coordinates to device window metrics bounds (WindowManager.currentWindowMetrics.bounds).