wake-alarm/MIGRATION.md

Migration: GitHub Gist → shared crdt_sync

phone_app's alarm sync was moved off a bespoke GitHub Gist onto the shared crdt_sync library (pinned tag crdt_sync_dart-v0.2.0 — see phone_app/pubspec.yaml, which is the authority; pubspec.lock resolves it to 5be99ab), matching how the other companion apps sync. A crdt_sync_dart-v0.3.0 tag also exists upstream and is not in use here — bumping to it is an untaken decision, not a drift to fix.

What changed

• phone_app (Dart): gist_service.dart is gone. AlarmSyncService stores the alarm locally in a crdt_sync LogStore (one HLC-stamped Record) and pushes it to wake-alarm-sync/devices/phone/alarm.json in kuhyx/syncs via crdt_sync's GitHubClient. The device-flow OAuth scope moved gist → repo (the Contents API needs private-repo access).
• shutdown-wrapper.sh (PC, Bash): now reads that alarm from the Contents API (Accept: application/vnd.github.raw, so no base64) and parses the crdt_sync Record log with jq (.alarm.fields.alarm_hour[0]). Config moved from ~/.config/wake_alarm/gist_sync.json {token, gist_id} to ~/.config/wake_alarm/sync.json {token} (repo-scoped).

Setup after pulling this

1. On the phone: Settings → Connect GitHub (now requests repo scope; the old gist-scoped token won't reach the Contents API).
2. On the PC: ~/.config/wake_alarm/sync.json → { "token": "<repo-scoped>" }, then re-run install.sh so /usr/local/bin/shutdown picks up the new reader.

Surprises / non-obvious decisions

• The consumer is a Python-less Bash reader (shutdown-wrapper.sh runs at shutdown, when a Python runtime may not be available), so it can't use the crdt_sync library — it parses the log with jq. What makes that tractable: Hlc.toStr() is lexicographically sortable == chronological, so "latest wins" across device dirs is a plain string max, no date math.
• The phone is push-only (sole writer); there is no pull/merge. Its local LogStore is always the source of truth.
• Any parse miss still falls back to WAKE_AFTER_HOURS, so a bad read can never brick the morning wake.

Migration: hibernate-scheduled → per-minute trigger timer

The PC is no longer shut down at night, which broke the whole scheduling model: the wake time used to be decided once, at hibernate, and baked into the RTC. With no shutdown there is no resume, so nothing fired the alarm at all — and wake-alarm.service was WantedBy=graphical-session.target, so on an always-on machine it fired at login time instead (_should_run_alarm() has no time gate).

What changed

• New wake-alarm-trigger.timer ticks every minute and runs wake_alarm._trigger, which fires morning-routine.service when the current local time is inside [phone alarm, phone alarm + TRIGGER_CATCHUP_MINUTES). This is now the primary path; the phone can move the alarm at any hour and the PC follows.
• New wake_alarm/_sync.py — a Python reader for the same alarm file shutdown-wrapper.sh parses with jq, plus an on-disk cache (~/.config/wake_alarm/alarm_cache.json).
• wake-alarm.service lost its [Install] section and is no longer enabled; install.sh disables it to clear stale symlinks.
• Token resolution gained a fallback to the sibling apps' ~/.config/{diet_guard,screen_locker}/sync_token, in both readers.
• shutdown-wrapper.sh and sleep-hook.sh keep working unchanged, now as the PC-is-powered-down fallback rather than the main mechanism.

Surprises / non-obvious decisions

• A timer, not a resident scheduler. Each tick is a fresh process, so there is no daemon to die silently and no wall-clock jump to reason about across suspend/resume. Persistent=true plus the catch-up window is what makes a suspended PC still fire on resume.
• Per-minute ticks, but a 5-minute cache. Ticking every 5 minutes would also quantise firing to 5 minutes (07:03 → 07:05). Ticking every minute and only hitting the network when the cache is stale gives exact-minute firing at ~288 GitHub reads/day.
• Degraded reads log at INFO. At one tick a minute, a WARNING on a persistent condition is 1440 journal lines a day. The single WARNING that survives is _trigger's "firing now on a degraded source".
• The sync had been dead since the crdt_sync migration. wake-alarm-sync/ did not exist in kuhyx/syncs at all — the phone had never successfully pushed, and ~/.config/wake_alarm/sync.json was never created, so the hibernate path had been silently using the +8h fallback. The phone app needs one successful "Set Alarm & Sync" to create that path.
• Still open: alarms edited directly in the Android Clock app do not reach the sync. Closing that needs an ACTION_NEXT_ALARM_CLOCK_CHANGED receiver in the phone app — planned, not yet built.