feat(contacts): declare READ_CONTACTS + read contact special-dates

Codeberg #15, foundation for the contact special-dates calendars. Declares the
optional, feature-gated READ_CONTACTS permission (never requested at startup)
and adds the offline, read-only contacts reader.

- AndroidManifest: READ_CONTACTS with a comment documenting the opt-in/offline
  one-way-mirror contract.
- domain/contacts: SpecialDateType + ContactSpecialDate model and a pure
  parseContactEventDate covering full (yyyy-MM-dd), year-less (--MM-dd) and
  compact (yyyyMMdd) shapes, with Feb-29 handling via a leap anchor.
- data/contacts: ContactSpecialDatesDataSource querying ContactsContract.Data
  Event rows, split by TYPE, deduped per (contact, type); returns empty without
  the permission so sync can degrade to a stalled state. Hilt-bound.
- Unit tests for the date parser (full/year-less/compact/Feb-29/malformed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/src/main/java/de/jeanlucmakiola/calendula/data/contacts/ContactSpecialDatesDataSource.kt

@@ -0,0 +1,98 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.provider.ContactsContract
+import android.provider.ContactsContract.CommonDataKinds.Event
+import android.util.Log
+import androidx.core.content.ContextCompat
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.domain.contacts.ContactSpecialDate
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+import de.jeanlucmakiola.calendula.domain.contacts.parseContactEventDate
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Reads the dated `Event` rows (birthdays, anniversaries, custom dates) of the
+ * device's contacts. Read-only and offline — the one-way source for the
+ * special-dates mirror. Requires `READ_CONTACTS`; returns an empty list when
+ * the permission is absent so the sync can degrade to a stalled state rather
+ * than crash.
+ */
+interface ContactSpecialDatesDataSource {
+    fun hasPermission(): Boolean
+
+    /** All usable contact special-dates, deduplicated per contact and type. */
+    fun readSpecialDates(): List<ContactSpecialDate>
+}
+
+/** Map a `ContactsContract` event `TYPE` to our calendar bucket. */
+internal fun specialDateTypeForRawEventType(type: Int): SpecialDateType = when (type) {
+    Event.TYPE_BIRTHDAY -> SpecialDateType.Birthday
+    Event.TYPE_ANNIVERSARY -> SpecialDateType.Anniversary
+    else -> SpecialDateType.Custom
+}
+
+@Singleton
+class AndroidContactSpecialDatesDataSource @Inject constructor(
+    @ApplicationContext private val context: Context,
+) : ContactSpecialDatesDataSource {
+
+    override fun hasPermission(): Boolean =
+        ContextCompat.checkSelfPermission(context, Manifest.permission.READ_CONTACTS) ==
+            PackageManager.PERMISSION_GRANTED
+
+    override fun readSpecialDates(): List<ContactSpecialDate> {
+        if (!hasPermission()) return emptyList()
+        val resolver = context.contentResolver
+        // A contact can carry the same date more than once (multiple raw
+        // contacts under one aggregate); keep the first per (contact, type).
+        val seen = HashSet<Pair<String, SpecialDateType>>()
+        val result = ArrayList<ContactSpecialDate>()
+        runCatching {
+            resolver.query(
+                ContactsContract.Data.CONTENT_URI,
+                PROJECTION,
+                "${ContactsContract.Data.MIMETYPE} = ?",
+                arrayOf(Event.CONTENT_ITEM_TYPE),
+                null,
+            )?.use { c ->
+                val idxDate = c.getColumnIndexOrThrow(Event.START_DATE)
+                val idxType = c.getColumnIndexOrThrow(Event.TYPE)
+                val idxLabel = c.getColumnIndexOrThrow(Event.LABEL)
+                val idxLookup = c.getColumnIndexOrThrow(ContactsContract.Data.LOOKUP_KEY)
+                val idxName = c.getColumnIndexOrThrow(ContactsContract.Data.DISPLAY_NAME_PRIMARY)
+                while (c.moveToNext()) {
+                    val lookup = c.getString(idxLookup)?.takeIf { it.isNotEmpty() } ?: continue
+                    val parts = parseContactEventDate(c.getString(idxDate)) ?: continue
+                    val type = specialDateTypeForRawEventType(c.getInt(idxType))
+                    if (!seen.add(lookup to type)) continue
+                    result += ContactSpecialDate(
+                        lookupKey = lookup,
+                        displayName = c.getString(idxName)?.trim().orEmpty(),
+                        type = type,
+                        month = parts.month,
+                        day = parts.day,
+                        year = parts.year,
+                        label = c.getString(idxLabel)?.takeIf { it.isNotBlank() },
+                    )
+                }
+            }
+        }.onFailure { Log.w(TAG, "Reading contact special-dates failed", it) }
+        return result
+    }
+
+    private companion object {
+        const val TAG = "ContactSpecialDates"
+
+        val PROJECTION = arrayOf(
+            ContactsContract.Data.LOOKUP_KEY,
+            ContactsContract.Data.DISPLAY_NAME_PRIMARY,
+            Event.START_DATE,
+            Event.TYPE,
+            Event.LABEL,
+        )
+    }
+}

app/src/main/java/de/jeanlucmakiola/calendula/data/di/DataModule.kt

@@ -14,6 +14,8 @@ import de.jeanlucmakiola.calendula.data.calendar.AndroidCalendarDataSource
 import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource
 import de.jeanlucmakiola.calendula.data.calendar.CalendarRepository
 import de.jeanlucmakiola.calendula.data.calendar.CalendarRepositoryImpl
+import de.jeanlucmakiola.calendula.data.contacts.AndroidContactSpecialDatesDataSource
+import de.jeanlucmakiola.calendula.data.contacts.ContactSpecialDatesDataSource
 import de.jeanlucmakiola.calendula.data.reminders.AndroidReminderAlertStore
 import de.jeanlucmakiola.calendula.data.reminders.ReminderAlertStore
 import kotlinx.coroutines.CoroutineDispatcher
@@ -45,6 +47,12 @@ abstract class DataBindModule {
     abstract fun bindReminderAlertStore(
         impl: AndroidReminderAlertStore,
     ): ReminderAlertStore
+
+    @Binds
+    @Singleton
+    abstract fun bindContactSpecialDatesDataSource(
+        impl: AndroidContactSpecialDatesDataSource,
+    ): ContactSpecialDatesDataSource
 }
 
 @Module

app/src/main/java/de/jeanlucmakiola/calendula/domain/contacts/ContactSpecialDate.kt

@@ -0,0 +1,122 @@
+package de.jeanlucmakiola.calendula.domain.contacts
+
+import java.time.LocalDate
+
+/**
+ * The kinds of contact "special date" Calendula mirrors into local calendars.
+ * Each kind gets its own local calendar, so it inherits per-calendar colour,
+ * visibility and reminder defaults for free. See
+ * docs/design/contact-special-dates.md.
+ */
+enum class SpecialDateType {
+    Birthday,
+    Anniversary,
+
+    /** Everything else — a contact "Event" that is neither birthday nor anniversary. */
+    Custom,
+}
+
+/**
+ * One dated event read from a device contact (a `ContactsContract` `Event`
+ * row). The [lookupKey] is the stable contact identity used to reconcile the
+ * mirror without duplicating; [year] is null when the contact stored the date
+ * without one (`--MM-dd`), in which case age can't be shown.
+ */
+data class ContactSpecialDate(
+    val lookupKey: String,
+    val displayName: String,
+    val type: SpecialDateType,
+    val month: Int,
+    val day: Int,
+    val year: Int?,
+    /** The contact's custom label for a [SpecialDateType.Custom] date, if any. */
+    val label: String? = null,
+)
+
+/** The parsed month/day (+ optional year) of a contact date. */
+data class ContactDateParts(val year: Int?, val month: Int, val day: Int)
+
+/**
+ * A fixed leap year to validate and anchor year-less dates against, so that a
+ * `--02-29` birthday is representable (and, once anchored, only recurs in leap
+ * years — matching how the calendar provider expands a yearly Feb-29 series).
+ */
+const val YEARLESS_ANCHOR_YEAR = 1972
+
+/**
+ * Parse a `ContactsContract.CommonDataKinds.Event.START_DATE` value into its
+ * calendar parts, or null if it isn't a usable date. Handles the three shapes
+ * seen in the wild:
+ * - full `yyyy-MM-dd` (year known),
+ * - year-less `--MM-dd` (year null),
+ * - compact `yyyyMMdd`.
+ *
+ * A date that names an impossible day (e.g. `1999-02-29`) is rejected. Pure, so
+ * it's unit-tested without a device.
+ */
+fun parseContactEventDate(raw: String?): ContactDateParts? {
+    val s = raw?.trim().orEmpty()
+    if (s.isEmpty()) return null
+
+    // Year-less: "--MM-dd" or "--MMdd".
+    if (s.startsWith("--")) {
+        val (m, d) = parseMonthDay(s.substring(2)) ?: return null
+        return validated(null, m, d)
+    }
+
+    if (s.contains('-')) {
+        val parts = s.split('-').filter { it.isNotEmpty() }
+        return when (parts.size) {
+            // "yyyy-MM-dd" — but a leading '-' would have dropped the empty
+            // first part, so require the first token to look like a year.
+            3 -> if (s.startsWith('-')) null else validated(
+                year = parts[0].toIntOrNull() ?: return null,
+                month = parts[1].toIntOrNull() ?: return null,
+                day = parts[2].toIntOrNull() ?: return null,
+            )
+            // Year-less "MM-dd" without the "--" prefix.
+            2 -> validated(
+                year = null,
+                month = parts[0].toIntOrNull() ?: return null,
+                day = parts[1].toIntOrNull() ?: return null,
+            )
+            else -> null
+        }
+    }
+
+    // Compact "yyyyMMdd".
+    if (s.length == 8 && s.all { it.isDigit() }) {
+        return validated(
+            year = s.substring(0, 4).toInt(),
+            month = s.substring(4, 6).toInt(),
+            day = s.substring(6, 8).toInt(),
+        )
+    }
+
+    return null
+}
+
+/** "MM-dd" or compact "MMdd". */
+private fun parseMonthDay(rest: String): Pair<Int, Int>? {
+    if (rest.contains('-')) {
+        val p = rest.split('-').filter { it.isNotEmpty() }
+        if (p.size != 2) return null
+        return (p[0].toIntOrNull() ?: return null) to (p[1].toIntOrNull() ?: return null)
+    }
+    if (rest.length == 4 && rest.all { it.isDigit() }) {
+        return rest.substring(0, 2).toInt() to rest.substring(2, 4).toInt()
+    }
+    return null
+}
+
+/**
+ * Confirm month/day form a real calendar date (validated against the actual
+ * year when known, otherwise the leap anchor so `02-29` survives).
+ */
+private fun validated(year: Int?, month: Int, day: Int): ContactDateParts? {
+    if (month !in 1..12 || day !in 1..31) return null
+    val checkYear = year ?: YEARLESS_ANCHOR_YEAR
+    return runCatching { LocalDate.of(checkYear, month, day) }
+        .map { ContactDateParts(year, month, day) }
+        .getOrNull()
+}