feat(contacts): idempotent special-dates sync engine

The engine reconciles device contact dates into the per-type local calendars.
Each run is an idempotent diff keyed on the deterministic UID_2445:

- new contacts inserted (seeding reminders via resolveDefaultReminder, plus a
  useful per-calendar all-day default of on-the-day + a week before so birthdays
  get lead time out of the box);
- changed contacts get a targeted managed-column update (title/dtstart/rrule
  only) — reminders/location/notes are never re-touched, so user edits survive;
- removed contacts deleted.

Managed calendars are created/adopted/removed per enabled type (reconcileCalendars,
self-healing against a stored-id that no longer exists), all-day FREQ=YEARLY
events anchored at the birth year (or a leap anchor when year-less). Pure helpers
(uid, anchor, age snapshot, title templating) and the diff are extracted for
unit testing; a stateful fake exercises full-run idempotency and user-data
preservation.

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

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

@@ -0,0 +1,41 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.content.Context
+import dagger.hilt.android.qualifiers.ApplicationContext
+import de.jeanlucmakiola.calendula.R
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Resolves the localized calendar names/templates and per-type colours the
+ * mirror creates its calendars with. The colours are picked from the shared
+ * palette so managed calendars look native alongside user calendars.
+ */
+@Singleton
+class AndroidSpecialDatesCalendarSpec @Inject constructor(
+    @ApplicationContext private val context: Context,
+) : SpecialDatesCalendarSpec {
+
+    override fun displayName(type: SpecialDateType): String = context.getString(
+        when (type) {
+            SpecialDateType.Birthday -> R.string.special_dates_calendar_birthday
+            SpecialDateType.Anniversary -> R.string.special_dates_calendar_anniversary
+            SpecialDateType.Custom -> R.string.special_dates_calendar_custom
+        },
+    )
+
+    override fun defaultTitleTemplate(type: SpecialDateType): String = context.getString(
+        when (type) {
+            SpecialDateType.Birthday -> R.string.special_dates_default_title_birthday
+            SpecialDateType.Anniversary -> R.string.special_dates_default_title_anniversary
+            SpecialDateType.Custom -> R.string.special_dates_default_title_custom
+        },
+    )
+
+    override fun color(type: SpecialDateType): Int = when (type) {
+        SpecialDateType.Birthday -> 0xFF8E24AA.toInt() // purple
+        SpecialDateType.Anniversary -> 0xFFD50000.toInt() // red
+        SpecialDateType.Custom -> 0xFF039BE5.toInt() // blue
+    }
+}

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

@@ -0,0 +1,277 @@
+package de.jeanlucmakiola.calendula.data.contacts
+
+import android.provider.CalendarContract
+import de.jeanlucmakiola.calendula.data.calendar.CalendarDataSource
+import de.jeanlucmakiola.calendula.data.calendar.ManagedEventRow
+import de.jeanlucmakiola.calendula.data.calendar.toWriteTimes
+import de.jeanlucmakiola.calendula.data.prefs.CalendarReminderOverride
+import de.jeanlucmakiola.calendula.data.prefs.SettingsPrefs
+import de.jeanlucmakiola.calendula.data.prefs.resolveDefaultReminder
+import de.jeanlucmakiola.calendula.domain.Availability
+import de.jeanlucmakiola.calendula.domain.EventForm
+import de.jeanlucmakiola.calendula.domain.RecurrenceFreq
+import de.jeanlucmakiola.calendula.domain.SimpleRecurrence
+import de.jeanlucmakiola.calendula.domain.contacts.ContactSpecialDate
+import de.jeanlucmakiola.calendula.domain.contacts.SpecialDateType
+import de.jeanlucmakiola.calendula.domain.contacts.anchorDate
+import de.jeanlucmakiola.calendula.domain.contacts.ageAtNextOccurrence
+import de.jeanlucmakiola.calendula.domain.contacts.managedEventUid
+import de.jeanlucmakiola.calendula.domain.contacts.renderSpecialDateTitle
+import de.jeanlucmakiola.calendula.domain.toRRule
+import kotlinx.coroutines.flow.first
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.LocalTime
+import java.time.ZoneId
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/** Outcome of one mirror reconcile, reported back so the worker can record status. */
+enum class SpecialDatesSyncResult { Success, Disabled, PermissionMissing }
+
+/**
+ * Localized, per-type presentation the engine needs but can't derive purely
+ * (calendar display name, colour, and the default title template). Kept behind
+ * an interface so the engine's diff stays unit-testable without Android
+ * resources.
+ */
+interface SpecialDatesCalendarSpec {
+    fun displayName(type: SpecialDateType): String
+    fun color(type: SpecialDateType): Int
+    fun defaultTitleTemplate(type: SpecialDateType): String
+}
+
+/**
+ * Mirrors contact birthdays/anniversaries/custom dates into local calendars,
+ * one per type. Every reconcile is an idempotent diff keyed on the deterministic
+ * `UID_2445` ([managedEventUid]): new contacts are inserted (seeding user-owned
+ * fields once), changed contacts get a *targeted* managed-column update, and
+ * removed contacts are deleted — so a user's own edits (reminders, location,
+ * notes) are never clobbered. See docs/design/contact-special-dates.md.
+ */
+@Singleton
+class SpecialDatesSyncEngine @Inject constructor(
+    private val contacts: ContactSpecialDatesDataSource,
+    private val calendars: CalendarDataSource,
+    private val prefs: SettingsPrefs,
+    private val spec: SpecialDatesCalendarSpec,
+) {
+
+    /**
+     * Reconcile every enabled type against the device's contacts. [today] anchors
+     * the age snapshot. Returns why it stopped early (disabled / permission gone)
+     * or [SpecialDatesSyncResult.Success].
+     */
+    suspend fun sync(today: LocalDate): SpecialDatesSyncResult {
+        if (!prefs.specialDatesEnabled.first()) return SpecialDatesSyncResult.Disabled
+        if (!contacts.hasPermission()) return SpecialDatesSyncResult.PermissionMissing
+
+        val enabledTypes = prefs.specialDatesTypes.first()
+        val calendarByType = reconcileCalendars(enabledTypes)
+
+        val desiredByType = contacts.readSpecialDates().groupBy { it.type }
+        val reminderCtx = readReminderContext()
+        val templates = prefs.specialDatesTitleTemplates.first()
+        val showAge = prefs.specialDatesShowAge.first()
+
+        calendarByType.forEach { (type, calendarId) ->
+            val template = templates[type]?.takeIf { it.isNotBlank() }
+                ?: spec.defaultTitleTemplate(type)
+            syncType(
+                calendarId = calendarId,
+                type = type,
+                contactsOfType = desiredByType[type].orEmpty(),
+                today = today,
+                template = template,
+                showAge = showAge,
+                reminderCtx = reminderCtx,
+            )
+        }
+        return SpecialDatesSyncResult.Success
+    }
+
+    /** Delete every managed calendar and forget its id — used when the feature is turned off. */
+    suspend fun teardown() {
+        calendars.findManagedCalendars().forEach { calendars.deleteCalendar(it.id) }
+        SpecialDateType.entries.forEach { prefs.setSpecialDatesCalendarId(it, null) }
+    }
+
+    /**
+     * Ensure each enabled type has exactly one managed calendar (adopting an
+     * existing one, or the stored id if it still exists, else creating one) and
+     * that disabled types have none. Returns the calendar id per enabled type.
+     */
+    private suspend fun reconcileCalendars(enabledTypes: Set<SpecialDateType>): Map<SpecialDateType, Long> {
+        val foundByType = calendars.findManagedCalendars()
+            .groupBy({ it.type }, { it.id })
+            .mapValues { it.value.first() }
+        val stored = prefs.specialDatesCalendars.first()
+        val result = LinkedHashMap<SpecialDateType, Long>()
+        for (type in SpecialDateType.entries) {
+            // A stored id counts only if the calendar still exists (the user may
+            // have deleted it in system settings); otherwise adopt a found one.
+            val existingId = stored[type]?.takeIf { id -> foundByType.containsValue(id) }
+                ?: foundByType[type]
+            if (type in enabledTypes) {
+                val id = existingId ?: createCalendar(type)
+                if (stored[type] != id) prefs.setSpecialDatesCalendarId(type, id)
+                result[type] = id
+            } else {
+                if (existingId != null) calendars.deleteCalendar(existingId)
+                if (stored.containsKey(type)) prefs.setSpecialDatesCalendarId(type, null)
+            }
+        }
+        return result
+    }
+
+    private suspend fun createCalendar(type: SpecialDateType): Long {
+        val id = calendars.createManagedCalendar(spec.displayName(type), spec.color(type), type)
+        prefs.setSpecialDatesCalendarId(type, id)
+        // Seed a useful all-day reminder default (on the day + a week before), so
+        // birthdays get lead time out of the box. Per-calendar, user-adjustable —
+        // only set when the user hasn't already configured this calendar.
+        if (!prefs.perCalendarAllDayReminderOverride.first().containsKey(id)) {
+            prefs.setCalendarAllDayReminderOverride(
+                id,
+                CalendarReminderOverride.Minutes(DEFAULT_REMINDER_MINUTES),
+            )
+        }
+        return id
+    }
+
+    private suspend fun syncType(
+        calendarId: Long,
+        type: SpecialDateType,
+        contactsOfType: List<ContactSpecialDate>,
+        today: LocalDate,
+        template: String,
+        showAge: Boolean,
+        reminderCtx: ReminderContext,
+    ) {
+        val built = contactsOfType.map { sd ->
+            buildManagedEvent(calendarId, type, sd, today, template, showAge, reminderCtx)
+        }
+        val diff = diffManagedEvents(built.map { it.desired }, calendars.queryManagedEvents(calendarId))
+        val formByUid = built.associate { it.desired.uid to it.form }
+        diff.insertUids.forEach { uid ->
+            calendars.insertManagedEvent(formByUid.getValue(uid), uid, reminderCtx.allDayTimeMinutes)
+        }
+        diff.updates.forEach { calendars.updateManagedFields(it.eventId, it.columns) }
+        diff.deleteEventIds.forEach { calendars.deleteEvent(it) }
+    }
+
+    private fun buildManagedEvent(
+        calendarId: Long,
+        type: SpecialDateType,
+        sd: ContactSpecialDate,
+        today: LocalDate,
+        template: String,
+        showAge: Boolean,
+        reminderCtx: ReminderContext,
+    ): BuiltManagedEvent {
+        val anchor = sd.anchorDate()
+        val start = LocalDateTime(anchor, LocalTime(0, 0))
+        val age = if (showAge) sd.ageAtNextOccurrence(today) else null
+        val title = renderSpecialDateTitle(template, sd.displayName, age)
+        val form = EventForm(
+            calendarId = calendarId,
+            title = title,
+            isAllDay = true,
+            start = start,
+            end = start,
+            reminders = reminderCtx.resolveAllDay(calendarId),
+            availability = Availability.Free,
+            rrule = YEARLY_RRULE,
+        )
+        val dtStartMillis = form.toWriteTimes(ZoneId.systemDefault()).dtStartMillis
+        return BuiltManagedEvent(
+            desired = ManagedEventDesired(
+                uid = managedEventUid(type, sd.lookupKey),
+                title = title,
+                dtStartMillis = dtStartMillis,
+                rrule = YEARLY_RRULE,
+            ),
+            form = form,
+        )
+    }
+
+    private suspend fun readReminderContext(): ReminderContext = ReminderContext(
+        timedGlobal = prefs.defaultReminderMinutes.first(),
+        allDayGlobal = prefs.defaultAllDayReminderMinutes.first(),
+        timedOverrides = prefs.perCalendarReminderOverride.first(),
+        allDayOverrides = prefs.perCalendarAllDayReminderOverride.first(),
+        allDayTimeMinutes = prefs.allDayReminderTimeMinutes.first(),
+    )
+
+    private data class ReminderContext(
+        val timedGlobal: List<Int>,
+        val allDayGlobal: List<Int>,
+        val timedOverrides: Map<Long, List<Int>>,
+        val allDayOverrides: Map<Long, List<Int>>,
+        val allDayTimeMinutes: Int,
+    ) {
+        fun resolveAllDay(calendarId: Long): List<Int> = resolveDefaultReminder(
+            timedGlobal = timedGlobal,
+            allDayGlobal = allDayGlobal,
+            timedOverrides = timedOverrides,
+            allDayOverrides = allDayOverrides,
+            calendarId = calendarId,
+            isAllDay = true,
+        )
+    }
+
+    private data class BuiltManagedEvent(val desired: ManagedEventDesired, val form: EventForm)
+
+    private companion object {
+        /** "On the day" (0) + one week before (7 days), as all-day lead minutes. */
+        val DEFAULT_REMINDER_MINUTES = listOf(0, 7 * 24 * 60)
+        val YEARLY_RRULE = SimpleRecurrence(freq = RecurrenceFreq.Yearly).toRRule()
+    }
+}
+
+/** The managed columns of a desired event, compared against the existing row. */
+internal data class ManagedEventDesired(
+    val uid: String,
+    val title: String,
+    val dtStartMillis: Long,
+    val rrule: String?,
+)
+
+internal data class ManagedFieldUpdate(val eventId: Long, val columns: Map<String, Any?>)
+
+internal data class ManagedDiff(
+    val insertUids: List<String>,
+    val updates: List<ManagedFieldUpdate>,
+    val deleteEventIds: List<Long>,
+)
+
+/**
+ * The idempotent diff at the heart of the mirror, keyed on `UID_2445`:
+ * desired-not-existing → insert, existing-not-desired → delete, and for events
+ * in both only the *changed* managed columns (title/dtstart/rrule) are emitted —
+ * so a re-run with no contact changes produces nothing, and a managed update
+ * never touches user-owned columns or reminder rows. Pure, so it's unit-tested.
+ */
+internal fun diffManagedEvents(
+    desired: List<ManagedEventDesired>,
+    existing: List<ManagedEventRow>,
+): ManagedDiff {
+    val desiredByUid = desired.associateBy { it.uid }
+    val existingByUid = existing.associateBy { it.uid }
+    val insertUids = desired.filter { it.uid !in existingByUid }.map { it.uid }
+    val deleteEventIds = existing.filter { it.uid !in desiredByUid }.map { it.eventId }
+    val updates = buildList {
+        for (d in desired) {
+            val row = existingByUid[d.uid] ?: continue
+            val columns = buildMap<String, Any?> {
+                if (row.title != d.title) put(CalendarContract.Events.TITLE, d.title)
+                if (row.dtStartMillis != d.dtStartMillis) {
+                    put(CalendarContract.Events.DTSTART, d.dtStartMillis)
+                }
+                if (row.rrule != d.rrule) put(CalendarContract.Events.RRULE, d.rrule)
+            }
+            if (columns.isNotEmpty()) add(ManagedFieldUpdate(row.eventId, columns))
+        }
+    }
+    return ManagedDiff(insertUids, updates, deleteEventIds)
+}

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

@@ -15,7 +15,9 @@ 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.AndroidSpecialDatesCalendarSpec
 import de.jeanlucmakiola.calendula.data.contacts.ContactSpecialDatesDataSource
+import de.jeanlucmakiola.calendula.data.contacts.SpecialDatesCalendarSpec
 import de.jeanlucmakiola.calendula.data.reminders.AndroidReminderAlertStore
 import de.jeanlucmakiola.calendula.data.reminders.ReminderAlertStore
 import kotlinx.coroutines.CoroutineDispatcher
@@ -53,6 +55,12 @@ abstract class DataBindModule {
     abstract fun bindContactSpecialDatesDataSource(
         impl: AndroidContactSpecialDatesDataSource,
     ): ContactSpecialDatesDataSource
+
+    @Binds
+    @Singleton
+    abstract fun bindSpecialDatesCalendarSpec(
+        impl: AndroidSpecialDatesCalendarSpec,
+    ): SpecialDatesCalendarSpec
 }
 
 @Module

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

@@ -0,0 +1,50 @@
+package de.jeanlucmakiola.calendula.domain.contacts
+
+import kotlinx.datetime.LocalDate
+import kotlinx.datetime.number
+
+/**
+ * The deterministic `Events.UID_2445` that ties a mirrored event to its source
+ * contact date. Stable across syncs (the reconciliation key), and namespaced by
+ * type so the same contact's birthday and anniversary never collide.
+ */
+fun managedEventUid(type: SpecialDateType, lookupKey: String): String =
+    "contact-${type.name.lowercase()}:$lookupKey@calendula"
+
+/**
+ * The all-day date the recurring `FREQ=YEARLY` series is anchored at: the real
+ * date when the year is known (so age can be derived), otherwise the month/day
+ * on a fixed leap anchor year so a `--02-29` date stays representable and the
+ * anchor never drifts between syncs.
+ */
+fun ContactSpecialDate.anchorDate(): LocalDate =
+    LocalDate(year ?: YEARLESS_ANCHOR_YEAR, month, day)
+
+/**
+ * The age the contact reaches on the *upcoming* occurrence of this date,
+ * relative to [today], or null when the year is unknown. Because a
+ * `FREQ=YEARLY` event carries a single static title, this is a snapshot taken
+ * at sync time (refreshed on the next sync), not a per-occurrence value.
+ */
+fun ContactSpecialDate.ageAtNextOccurrence(today: LocalDate): Int? {
+    val birthYear = year ?: return null
+    val monthDayPassedThisYear = month < today.month.number ||
+        (month == today.month.number && day < today.day)
+    val nextYear = if (monthDayPassedThisYear) today.year + 1 else today.year
+    return nextYear - birthYear
+}
+
+/**
+ * Render a title [template] for a contact, substituting `{name}` and `{age}`
+ * (the latter empty when [age] is null). Collapses the whitespace the empty
+ * `{age}` may leave behind, so "{name}'s birthday ({age})" degrades cleanly to
+ * "Jane's birthday" when no year is known.
+ */
+fun renderSpecialDateTitle(template: String, name: String, age: Int?): String =
+    template
+        .replace("{name}", name)
+        .replace("{age}", age?.toString().orEmpty())
+        // Drop an empty "()" left by an unresolved {age}, then tidy spacing.
+        .replace(Regex("""\(\s*\)"""), "")
+        .replace(Regex("""\s+"""), " ")
+        .trim()

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

@@ -462,4 +462,13 @@
     <string name="crash_report_body_paste">_(The report was too long for this link — paste it from your clipboard here.)_</string>
     <string name="report_issue_url" translatable="false">https://codeberg.org/jlmakiola/calendula/issues/new</string>
     <string name="report_issue_choose_url" translatable="false">https://codeberg.org/jlmakiola/calendula/issues/new/choose</string>
+
+    <!-- Contact special dates (issue #15). {name} is the contact, {age} the age
+         at the upcoming date (dropped when the year is unknown or Show age is off). -->
+    <string name="special_dates_calendar_birthday">Birthdays</string>
+    <string name="special_dates_calendar_anniversary">Anniversaries</string>
+    <string name="special_dates_calendar_custom">Special dates</string>
+    <string name="special_dates_default_title_birthday">{name}\'s birthday ({age})</string>
+    <string name="special_dates_default_title_anniversary">{name}\'s anniversary ({age})</string>
+    <string name="special_dates_default_title_custom">{name}</string>
 </resources>