AlarmKit integration
ORIX 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.
The API surface used here was read from the SDK interface shipped with Xcode 27.2 (AlarmKit.swiftinterface), not from memory.
What is scheduled
| App concept | AlarmKit call | Identifier |
|---|---|---|
| One-time alarm | .alarm(schedule: .relative(time, repeats: .never)) |
the alarm's UUID |
| Weekly alarm | .alarm(schedule: .relative(time, repeats: .weekly([Locale.Weekday]))) |
the alarm's UUID |
| Snooze follow-up | .timer(duration:) with a countdown presentation (Live Activity) |
StableID.snoozeID(alarm, n) — deterministic UUID derived with SHA-256 |
| Focus timer | .timer(duration:) with pause / resume |
fixed UUID AppModel.focusTimerID |
Schedules 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.
The 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.
Authorization
NSAlarmKitUsageDescription is declared. Authorization is requested at the end of onboarding or on the first save. When it is denied:
- the alarm is still saved locally,
savereturns an error, the editor stays open and says the alarm is not scheduled; - every list shows the status "Not scheduled" / "Cannot verify" and a banner with a link to Settings;
- when the user allows alarms later, the next activation reconciles and schedules everything.
The database is not proof
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):
- enabled locally, absent from the system → scheduled again (
missing); - present with another schedule → rescheduled (
mismatched); - system alarm that no definition, running snooze or focus timer explains → cancelled (orphan);
- system state unreadable → status
unverifiable, never shown as scheduled.
Each alarm displays this verified status. AlarmManager.alarmUpdates is observed while the app runs.
Buttons and intents
AlarmKit shows a system Stop control and at most one secondary button.
| Alarm | Stop intent | Secondary button |
|---|---|---|
| Snooze allowed | StopAlarmIntent or StopAndOpenMissionIntent |
Snooze → SnoozeAlarmIntent (custom behaviour) |
| No snooze, has a mission | StopAndOpenMissionIntent |
Mission → OpenMissionIntent |
| No snooze, no mission | StopAlarmIntent |
none |
The intents are LiveActivityIntents 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).
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.
Three different events
- System acknowledgment — the user stopped the alert (
acknowledged). - Mission completion — the mission sequence was finished in the app (
missionCompleted), or left through the emergency exit (missionBypassed). - Wake confirmation — the user tapped "I'm up" (
wakeConfirmed).
Only the third counts as a wake-up in statistics. Stopping an alarm proves nothing about being awake.
What ORIX Alarm does not and cannot do
- 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.
- 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.
- It cannot change the device volume.
- 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.
One-time alarms
A 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.
Verification status
| Behaviour | Evidence |
|---|---|
| Request building, reconciliation, snooze chain, one-time retirement, permission denial, relaunch, lost system state | integration tests against FakeAlarmService (Tests/AppModelTests.swift) |
| Recurrence, DST, time zones, policies | unit tests (Packages/AlarmCore/Tests) |
| Real AlarmKit scheduling and alert | see docs/TESTING.md for what was run on the simulator |
| Lock screen, silent mode, Focus, restart, Bluetooth routing on a real iPhone | not verified — no device was available |