Repository Public License
1<!--2ORIX Alarm3File: docs/ALARMKIT.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# AlarmKit integration89ORIX Alarm rings through **AlarmKit** (iOS 26). The system owns the alarm: it rings when the app is closed, the iPhone is locked, a Focus is on or the ring switch is silent, exactly like the Clock app. The app never relies on a background process, a background timer or a local notification to ring the main alarm.1011The API surface used here was read from the SDK interface shipped with Xcode 27.2 (`AlarmKit.swiftinterface`), not from memory.1213## What is scheduled1415| App concept | AlarmKit call | Identifier |16|---|---|---|17| One-time alarm | `.alarm(schedule: .relative(time, repeats: .never))` | the alarm's UUID |18| Weekly alarm | `.alarm(schedule: .relative(time, repeats: .weekly([Locale.Weekday])))` | the alarm's UUID |19| Snooze follow-up | `.timer(duration:)` with a countdown presentation (Live Activity) | `StableID.snoozeID(alarm, n)` — deterministic UUID derived with SHA-256 |20| Focus timer | `.timer(duration:)` with pause / resume | fixed UUID `AppModel.focusTimerID` |2122Schedules are **relative** (wall-clock): an alarm set for 07:00 rings at 07:00 in whatever time zone the device is in, and the system handles daylight saving. The app's own next-occurrence maths (`Recurrence`, used for display, widgets and the "rang while the app was away" detection) uses `Calendar.nextDate(matchingPolicy: .nextTime, repeatedTimePolicy: .first)`: a time skipped in spring fires at the first valid instant after the gap, a time repeated in autumn fires once.2324The alert sound is a bundled file passed as `AlertConfiguration.AlertSound.named(…)` (system limit: about 30 seconds, then it loops). Every request carries `ORIXAlarmMetadata` (alarm id, name, role, symbol) for the Live Activity.2526## Authorization2728`NSAlarmKitUsageDescription` is declared. Authorization is requested at the end of onboarding or on the first save. When it is denied:2930- the alarm is still saved locally, `save` returns an error, the editor stays open and says the alarm is **not scheduled**;31- every list shows the status "Not scheduled" / "Cannot verify" and a banner with a link to Settings;32- when the user allows alarms later, the next activation reconciles and schedules everything.3334## The database is not proof3536`AppModel.reconcile()` runs at launch, on every activation and after every change. It reads `AlarmManager.alarms` and compares it with the library (`Reconciler`, pure and unit-tested):3738- enabled locally, absent from the system → scheduled again (`missing`);39- present with another schedule → rescheduled (`mismatched`);40- system alarm that no definition, running snooze or focus timer explains → cancelled (orphan);41- system state unreadable → status `unverifiable`, never shown as scheduled.4243Each alarm displays this verified status. `AlarmManager.alarmUpdates` is observed while the app runs.4445## Buttons and intents4647AlarmKit shows a system Stop control and at most one secondary button.4849| Alarm | Stop intent | Secondary button |50|---|---|---|51| Snooze allowed | `StopAlarmIntent` or `StopAndOpenMissionIntent` | **Snooze** → `SnoozeAlarmIntent` (custom behaviour) |52| No snooze, has a mission | `StopAndOpenMissionIntent` | **Mission** → `OpenMissionIntent` |53| No snooze, no mission | `StopAlarmIntent` | none |5455The intents are `LiveActivityIntent`s compiled into the app and the widget extension; they run in the app process and forward an event to the model through `IntentBridge` (events arriving before the model exists are queued).5657**Snooze is implemented by the app**, not by AlarmKit's built-in countdown, so the policy can be enforced: fixed or decreasing durations, a maximum count, optional difficulty escalation. On a snooze request the app stops the alert and schedules a timer-style follow-up whose alert only offers Snooze again if the policy still allows one. If the follow-up cannot be scheduled, the failure is recorded and shown, and the app falls back to the wake mission instead of leaving the user without anything.5859## Three different events60611. **System acknowledgment** — the user stopped the alert (`acknowledged`).622. **Mission completion** — the mission sequence was finished in the app (`missionCompleted`), or left through the emergency exit (`missionBypassed`).633. **Wake confirmation** — the user tapped "I'm up" (`wakeConfirmed`).6465Only the third counts as a wake-up in statistics. Stopping an alarm proves nothing about being awake.6667## What ORIX Alarm does not and cannot do6869- It cannot prevent the user from stopping or silencing a system alarm. A mission is a commitment the user sets for themself; the emergency exit is always available and recorded.70- It cannot start audio, light the screen or run a sunrise before the alarm while the app is closed or the iPhone locked. Progressive wake needs the app open in Nightstand mode. The system alarm rings regardless.71- It cannot change the device volume.72- Whether stopping an alarm from the Lock Screen brings the app to the foreground (`openAppWhenRun`) is decided by iOS. If it does not, the mission is presented the next time the app is opened within three hours of the alarm.7374## One-time alarms7576A one-time alarm leaves the system when it is stopped. The app then disables its definition so reconciliation does not schedule it again for the next day. If it rang while the app was not running, the next launch sees that its expected fire date is in the past, records the firing with the note `from-schedule` (derived, not observed) and retires it.7778## Verification status7980| Behaviour | Evidence |81|---|---|82| Request building, reconciliation, snooze chain, one-time retirement, permission denial, relaunch, lost system state | integration tests against `FakeAlarmService` (`Tests/AppModelTests.swift`) |83| Recurrence, DST, time zones, policies | unit tests (`Packages/AlarmCore/Tests`) |84| Real AlarmKit scheduling and alert | see `docs/TESTING.md` for what was run on the simulator |85| Lock screen, silent mode, Focus, restart, Bluetooth routing on a real iPhone | **not verified** — no device was available |86