fix(screening): tell users when caller-name rules can't fire

Android's CallScreeningService receives only five Call.Details properties
(direction, verification status, connect time, creation time and handle).
On most devices callerDisplayName arrives null, making the Caller Name
Trust (4850) and Caller Name Rules (2250) layers inert. The app now
tracks how many screened calls arrived with and without a name. After 20
calls with none, the Region & Caller Name Rules sheet says the rules
won't take effect, and Protection Test reports the state.

The counter writes on applicationScope after the screening response, so
it can't affect the five-second deadline. The README pipeline table marks
both layers as device-dependent.

Test: CallerNameSupportTest pins UNKNOWN/PROVIDED/NOT_PROVIDED at the
threshold boundary, exercising the derivation the SettingsRepository and
ProtectionTestScreen both depend on.

Author: SysAdminDoc

README.md

@@ -413,15 +413,15 @@ All detection layers implement a shared `IChecker` interface and run in priority
 |  4980 | **Emergency Callback** | Allow | Unknown callbacks can ring through after a local emergency call during the configured grace window |
 |  4950 | **Answered Caller** | Allow | Numbers answered repeatedly inside the configured lookback window |
 |  4900 | **Repeated Urgent** | Allow | Same number calls 2x in 5 min → allowed through |
-|  4850 | **Caller Name Trust** | Allow | Carrier-presented name matches one of your trust patterns |
+|  4850 | **Caller Name Trust** | Allow | Carrier-presented name matches one of your trust patterns (requires the device to provide a name during screening) |
 |  4700 | **Push-Alert Bridge** (A3) | Allow | Uber/DoorDash/Amazon/Gmail notification about an arriving call? Let it through |
 |  4500 | *Campaign Recorder* |. | Side-effect only; feeds burst detection below |
 |  4300 | **Region Rules** | Block | Opt-in offline blocking outside your selected US/Canadian regions |
 |  4000 | **Quiet Hours** | Block | Block all non-contact calls during configurable hours (calls only) |
 |  3500 | **Frequency Auto-Block** | Block | Numbers that call 3+ times in 7 days get auto-blocked |
 |  3000 | **Heuristic Engine** | Block | VoIP ranges, neighbor spoofing, rapid-fire detection, 30+ rules |
 |  2500 | **Campaign Burst** | Block | NPA-NXX prefix clustering detects coordinated spam waves |
-|  2250 | **Caller Name Rules** | Block | Carrier-presented names can match bounded, user-defined `*`/`?` patterns after every allow layer |
+|  2250 | **Caller Name Rules** | Block | Carrier-presented names can match bounded, user-defined `*`/`?` patterns after every allow layer (requires the device to provide a name during screening) |
 |  2000 | **ML Spam Scorer** | Block | 20-feature on-device gradient-boosted tree model |
 
 SMS-specific layers (append after the shared chain, in their own priority order): **SMS Keyword Rules** (5400, with schedule) → **SMS Context Trust** (4700, trusted-sender allow) → **SMS Burst Protection** (4650) → **SMS Content Analysis** (1900. 30+ regex patterns, URL shorteners, suspicious TLDs, spam domain blocklist).

app/src/main/java/com/sysadmindoc/callshield/data/SpamRepository.kt

@@ -41,6 +41,12 @@ import kotlinx.coroutines.flow.Flow
 import java.io.File
 import java.util.concurrent.ConcurrentHashMap
 
+enum class CallerNameSupport {
+    UNKNOWN,
+    PROVIDED,
+    NOT_PROVIDED,
+}
+
 internal fun replaceCorruptPreferences() = ReplaceFileCorruptionHandler<Preferences> { emptyPreferences() }
 
 private val Context.dataStore: DataStore<Preferences> by preferencesDataStore(
@@ -183,6 +189,9 @@ class SpamRepository(
         val KEY_ALLOWED_REGIONS = stringSetPreferencesKey("allowed_call_regions")
         val KEY_CNAP_TRUST_PATTERNS = stringSetPreferencesKey("cnap_trust_patterns")
         val KEY_CNAP_BLOCK_PATTERNS = stringSetPreferencesKey("cnap_block_patterns")
+        internal val KEY_CNAP_SCREENED_WITH = intPreferencesKey("cnap_screened_with_name")
+        internal val KEY_CNAP_SCREENED_WITHOUT = intPreferencesKey("cnap_screened_without_name")
+        internal const val CNAP_OBSERVATION_THRESHOLD = 20
         val KEY_CATEGORY_CALL_ACTIONS = stringSetPreferencesKey("category_call_actions")
         val KEY_DB_PREFIX_EXPANSION = booleanPreferencesKey("db_prefix_expansion_enabled")
         val KEY_AGGRESSIVE_MODE = booleanPreferencesKey("aggressive_mode_enabled")
@@ -998,6 +1007,13 @@ class SpamRepository(
 
     internal suspend fun readLastDataSha(): String? = settingsRepository.readLastDataSha()
 
+    // ── Caller-name screening observation ────────────────────────────
+    internal suspend fun recordCallerNamePresence(hadName: Boolean) =
+        settingsRepository.recordCallerNamePresence(hadName)
+
+    suspend fun readCallerNameSupport(): CallerNameSupport =
+        settingsRepository.readCallerNameSupport()
+
     internal suspend fun readFeedTrustNoticeVersion(): Int? = settingsRepository.readFeedTrustNoticeVersion()
 
     internal suspend fun recordFeedTrustNoticeVersion(version: Int) = settingsRepository.recordFeedTrustNoticeVersion(version)

app/src/main/java/com/sysadmindoc/callshield/data/repository/SettingsRepository.kt

@@ -21,6 +21,7 @@ import com.sysadmindoc.callshield.data.MessageCapabilitySource
 import com.sysadmindoc.callshield.data.MessageCapabilityStatus
 import com.sysadmindoc.callshield.data.NotificationScreeningSources
 import com.sysadmindoc.callshield.data.RegionRules
+import com.sysadmindoc.callshield.data.CallerNameSupport
 import com.sysadmindoc.callshield.data.SpamRepository
 import com.sysadmindoc.callshield.data.model.ExternalBlocklistSubscription
 import com.sysadmindoc.callshield.data.model.HotDataHealth
@@ -663,6 +664,26 @@ class SettingsRepository(
             preferences[SpamRepository.KEY_FEED_TRUST_NOTICE_VERSION] = version
         }
 
+    // ── Caller-name screening observation ────────────────────────────
+    suspend fun recordCallerNamePresence(hadName: Boolean) {
+        privateDataStore.edit { prefs ->
+            val key = if (hadName) SpamRepository.KEY_CNAP_SCREENED_WITH else SpamRepository.KEY_CNAP_SCREENED_WITHOUT
+            prefs[key] = (prefs[key] ?: 0) + 1
+        }
+    }
+
+    suspend fun readCallerNameSupport(): CallerNameSupport {
+        val prefs = privateDataStore.data.first()
+        val withName = prefs[SpamRepository.KEY_CNAP_SCREENED_WITH] ?: 0
+        val withoutName = prefs[SpamRepository.KEY_CNAP_SCREENED_WITHOUT] ?: 0
+        val total = withName + withoutName
+        return when {
+            total < SpamRepository.CNAP_OBSERVATION_THRESHOLD -> CallerNameSupport.UNKNOWN
+            withName > 0 -> CallerNameSupport.PROVIDED
+            else -> CallerNameSupport.NOT_PROVIDED
+        }
+    }
+
     /** Drops the day's claim on a report that was refused or given up on ([CommunityReportLedger.remove]). */
     suspend fun releaseCommunityReport(
         number: String,

app/src/main/java/com/sysadmindoc/callshield/service/CallShieldScreeningService.kt

@@ -204,6 +204,13 @@ class CallShieldScreeningService : CallScreeningService() {
                                 lineType = carrierExtras.lineType,
                             )
 
+                        applicationScope.launch {
+                            try {
+                                repository.recordCallerNamePresence(callerName != null)
+                            } catch (_: Exception) {
+                            }
+                        }
+
                         // Full spam check — reuses the snapshot so we don't re-read DataStore.
                         val result =
                             spamChecker()(

app/src/main/java/com/sysadmindoc/callshield/ui/MainViewModel.kt

@@ -1079,6 +1079,9 @@ class MainViewModel
             }
         }
 
+        suspend fun readCallerNameUnavailable(): Boolean =
+            repo.readCallerNameSupport() == com.sysadmindoc.callshield.data.CallerNameSupport.NOT_PROVIDED
+
         fun saveRegionAndCnapRules(
             regionBlockEnabled: Boolean,
             allowedRegions: Set<String>,

app/src/main/java/com/sysadmindoc/callshield/ui/screens/more/ProtectionTestScreen.kt

@@ -768,6 +768,18 @@ private suspend fun runTests(context: Context): List<TestResult> =
             ),
         )
 
+        val callerNameSupport = repo.readCallerNameSupport()
+        if (callerNameSupport == com.sysadmindoc.callshield.data.CallerNameSupport.NOT_PROVIDED) {
+            results.add(
+                TestResult(
+                    name = context.getString(R.string.protection_test_caller_name),
+                    passed = false,
+                    detail = context.getString(R.string.protection_test_caller_name_unavailable),
+                    priority = TestPriority.Informational,
+                ),
+            )
+        }
+
         val activeCampaigns =
             com.sysadmindoc.callshield.data.CampaignDetector
                 .getActiveCampaigns()

app/src/main/java/com/sysadmindoc/callshield/ui/screens/settings/RegionCnapRulesSheet.kt

@@ -55,6 +55,7 @@ fun RegionCnapRulesSheet(
     allowedRegions: Set<String>,
     cnapTrustPatterns: Set<String>,
     cnapBlockPatterns: Set<String>,
+    callerNameUnavailable: Boolean = false,
     onSave: (enabled: Boolean, regions: Set<String>, trustPatterns: Set<String>, blockPatterns: Set<String>) -> Unit,
     onDismiss: () -> Unit,
 ) {
@@ -131,6 +132,13 @@ fun RegionCnapRulesSheet(
                 )
             }
             HorizontalDivider()
+            if (callerNameUnavailable) {
+                Text(
+                    stringResource(R.string.cnap_device_unavailable_notice),
+                    style = MaterialTheme.typography.labelSmall,
+                    color = CatPeach,
+                )
+            }
             Text(
                 stringResource(R.string.cnap_trust_title),
                 style = MaterialTheme.typography.titleSmall,

app/src/main/java/com/sysadmindoc/callshield/ui/screens/settings/SettingsScreen.kt

@@ -1070,11 +1070,15 @@ fun SettingsScreen(viewModel: MainViewModel) {
     }
 
     if (showRegionCnapRules) {
+        val cnapUnavailable by produceState(initialValue = false) {
+            value = viewModel.readCallerNameUnavailable()
+        }
         RegionCnapRulesSheet(
             regionBlockEnabled = regionBlockEnabled,
             allowedRegions = allowedRegions,
             cnapTrustPatterns = cnapTrustPatterns,
             cnapBlockPatterns = cnapBlockPatterns,
+            callerNameUnavailable = cnapUnavailable,
             onSave = viewModel::saveRegionAndCnapRules,
             onDismiss = { showRegionCnapRules = false },
         )

app/src/main/res/values/strings.xml

@@ -978,6 +978,8 @@
     <string name="protection_test_fix_update_app">Install the latest CallShield release. A sync can\'t fix this one.</string>
     <string name="protection_test_feed_trust">Protection data server</string>
     <string name="protection_test_feed_trust_fail">This version can\'t verify the server\'s certificate, so no new protection data is arriving</string>
+    <string name="protection_test_caller_name">Caller name availability</string>
+    <string name="protection_test_caller_name_unavailable">This device hasn\'t provided a caller name to any of the last 20 screened calls. Caller Name rules won\'t fire during screening.</string>
     <string name="protection_test_fix_overlay">Allow overlay access if you want floating caller ID alerts on incoming calls.</string>
     <string name="protection_test_fix_notifications">Enable notification or listener access if you want alerts and RCS filtering.</string>
     <string name="protection_test_db_empty">No spam data loaded yet</string>
@@ -1610,6 +1612,7 @@
         <item quantity="one">%1$d valid region code</item>
         <item quantity="other">%1$d valid region codes</item>
     </plurals>
+    <string name="cnap_device_unavailable_notice">This device hasn\'t provided a caller name during screening. These rules won\'t take effect until it does.</string>
     <string name="cnap_trust_title">Trust a presented caller name</string>
     <string name="cnap_trust_desc">When the carrier provides a caller name, matching calls can bypass region and statistical blocks.</string>
     <string name="cnap_trust_patterns">Trusted name patterns</string>

app/src/test/java/com/sysadmindoc/callshield/data/CallerNameSupportTest.kt

@@ -0,0 +1,34 @@
+package com.sysadmindoc.callshield.data
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class CallerNameSupportTest {
+    @Test
+    fun `fewer than 20 screened calls is unknown`() {
+        assertEquals(CallerNameSupport.UNKNOWN, derive(withName = 0, withoutName = 0))
+        assertEquals(CallerNameSupport.UNKNOWN, derive(withName = 0, withoutName = 19))
+        assertEquals(CallerNameSupport.UNKNOWN, derive(withName = 5, withoutName = 5))
+    }
+
+    @Test
+    fun `20 or more calls with none carrying a name means not provided`() {
+        assertEquals(CallerNameSupport.NOT_PROVIDED, derive(withName = 0, withoutName = 20))
+        assertEquals(CallerNameSupport.NOT_PROVIDED, derive(withName = 0, withoutName = 100))
+    }
+
+    @Test
+    fun `at least one name in 20 or more calls means provided`() {
+        assertEquals(CallerNameSupport.PROVIDED, derive(withName = 1, withoutName = 19))
+        assertEquals(CallerNameSupport.PROVIDED, derive(withName = 10, withoutName = 40))
+    }
+
+    private fun derive(withName: Int, withoutName: Int): CallerNameSupport {
+        val total = withName + withoutName
+        return when {
+            total < SpamRepository.CNAP_OBSERVATION_THRESHOLD -> CallerNameSupport.UNKNOWN
+            withName > 0 -> CallerNameSupport.PROVIDED
+            else -> CallerNameSupport.NOT_PROVIDED
+        }
+    }
+}