@ciphore/radiocli 0.2.1 → 0.2.3

package/dist/alarms/runner.js

@@ -0,0 +1,342 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { assessScheduledOccurrence, NATIVE_DISPATCH_TOLERANCE_MS, nextOccurrenceForAlarm } from './schedule.js';
+import { startActiveAlarmSession } from './active-session.js';
+export async function runAlarm(alarmId, scheduledAtText, deps) {
+    if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(scheduledAtText))
+        throw new Error('Scheduled alarm occurrence must be an absolute date.');
+    const scheduledAt = new Date(scheduledAtText);
+    if (!Number.isFinite(scheduledAt.getTime()))
+        throw new Error('Scheduled alarm occurrence must be an absolute date.');
+    const releaseLock = deps.acquireLock(alarmId, scheduledAt.toISOString());
+    if (!releaseLock) {
+        const current = deps.store.getAlarm(alarmId);
+        if (current)
+            try {
+                await deps.scheduler.sync(current);
+            }
+            catch { }
+        return { duplicate: true, message: 'This alarm occurrence is already running or completed.' };
+    }
+    let alarm = deps.store.getAlarm(alarmId);
+    let outcome;
+    let session;
+    let lease;
+    let systemVolumeLease;
+    let listening = false;
+    let firedAt;
+    let preserveNextOverride = false;
+    let preserveSystemVolume = false;
+    let validTerminalOccurrence = false;
+    let signalReceived = false;
+    let resolveEarlySignal = () => { };
+    let onPlaybackSignal = () => { };
+    const earlySignal = new Promise(resolve => { resolveEarlySignal = resolve; });
+    const unsubscribeSignals = deps.subscribeSignals?.(() => { signalReceived = true; resolveEarlySignal(); onPlaybackSignal(); void deps.player.stop().catch(() => undefined); });
+    const finish = (status, message) => ({ status, scheduledAt: scheduledAt.toISOString(), ...(firedAt ? { firedAt: firedAt.toISOString() } : {}), finishedAt: deps.now().toISOString(), ...(message ? { message } : {}) });
+    let action;
+    let keepPlaying = false;
+    let resolveAction = () => { };
+    const actionPromise = new Promise(resolve => { resolveAction = resolve; });
+    try {
+        if (!alarm || !alarm.enabled)
+            return { message: 'Alarm is missing or disabled.' };
+        const expected = nextExpectedOccurrence(alarm, scheduledAt);
+        if (!expected || Math.abs(expected.getTime() - scheduledAt.getTime()) > 1000) {
+            outcome = finish('missed', 'Ignored a stale native task whose occurrence no longer matches this alarm.');
+            return { status: 'missed', message: outcome.message };
+        }
+        const assessment = assessScheduledOccurrence(scheduledAt, deps.now(), alarm.reliability.missedRunGraceMinutes);
+        if (assessment === 'pending') {
+            outcome = finish('failed', 'Scheduler launched the alarm before its occurrence.');
+            return { status: outcome.status, message: outcome.message };
+        }
+        validTerminalOccurrence = true;
+        if (assessment === 'missed') {
+            outcome = finish('missed', 'Alarm was outside its missed-run grace window.');
+            return { status: outcome.status, message: outcome.message };
+        }
+        const claimingStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: alarm.station.name, station: alarm.station, startedAt: deps.now().toISOString(), state: 'starting' };
+        const creatingSession = deps.createSession(claimingStatus, {
+            onDismiss: () => { action = 'dismissed'; resolveAction('dismissed'); resolveEarlySignal(); },
+            onSnooze: minutes => { deps.store.snoozeAlarm(alarmId, new Date(deps.now().getTime() + minutes * 60_000)); preserveNextOverride = true; action = 'snoozed'; resolveAction('snoozed'); resolveEarlySignal(); },
+            onKeepPlaying: () => { keepPlaying = true; session?.update({ keepPlaying: true }); },
+            onHandoff: () => { if (!listening)
+                throw new Error('Alarm playback is still starting.'); preserveSystemVolume = true; action = 'handoff'; resolveAction('handoff'); }
+        });
+        void creatingSession.then(created => { if (signalReceived)
+            void created.close().catch(() => undefined); }).catch(() => { });
+        const created = await Promise.race([creatingSession.then(value => ({ value })), earlySignal.then(() => ({ signal: true }))]);
+        if ('signal' in created) {
+            outcome = finish('dismissed', 'Alarm interrupted while local controls were starting.');
+            return { status: 'dismissed', message: outcome.message };
+        }
+        session = created.value;
+        const claimed = deps.store.getAlarm(alarmId);
+        if (claimed?.enabled && claimed.schedule.type === 'recurring') {
+            if (deps.scheduler.syncClaimed)
+                await deps.scheduler.syncClaimed(claimed, scheduledAt);
+            else
+                await deps.scheduler.sync(claimed);
+        }
+        let resolvedStation = alarm.station;
+        let lastError;
+        let interactivePreempted = false;
+        let outputPrepared = false;
+        const candidates = [alarm.station, alarm.station, alarm.playback.fallbackStation].filter((item) => Boolean(item));
+        for (const [candidateIndex, candidate] of candidates.entries()) {
+            try {
+                const resolved = await Promise.race([deps.providers.resolve(candidate).then(stream => ({ stream })), earlySignal.then(() => ({ signal: true }))]);
+                if ('signal' in resolved) {
+                    outcome = finish('dismissed', 'Alarm interrupted before playback started.');
+                    return { status: 'dismissed', message: outcome.message };
+                }
+                if (!interactivePreempted) {
+                    interactivePreempted = true;
+                    try {
+                        await deps.preemptInteractivePlayback?.();
+                    }
+                    catch (error) {
+                        deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: true, message: `Alarm continued after interactive playback could not be stopped cleanly: ${errorMessage(error)}` });
+                    }
+                }
+                if (!outputPrepared) {
+                    outputPrepared = true;
+                    if (deps.systemVolume)
+                        try {
+                            systemVolumeLease = await deps.systemVolume.acquireMinimum(alarm.playback.volume);
+                            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: true, active: true, message: systemVolumeLease.message });
+                        }
+                        catch (error) {
+                            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: false, message: `Alarm will use player volume, but system output could not be raised: ${errorMessage(error)}` });
+                        }
+                }
+                const playPromise = deps.player.play(candidate, resolved.stream.url);
+                const tuned = await Promise.race([playPromise.then(() => ({ played: true })), earlySignal.then(() => ({ signal: true }))]);
+                if ('signal' in tuned || signalReceived) {
+                    void playPromise.then(() => deps.player.stop()).catch(() => undefined);
+                    outcome = finish('dismissed', 'Alarm interrupted while playback was starting.');
+                    return { status: 'dismissed', message: outcome.message };
+                }
+                resolvedStation = candidate;
+                lastError = undefined;
+                break;
+            }
+            catch (error) {
+                lastError = error;
+            }
+            if (candidateIndex < candidates.length - 1) {
+                const remaining = scheduledAt.getTime() + Math.max(NATIVE_DISPATCH_TOLERANCE_MS, alarm.reliability.missedRunGraceMinutes * 60_000) - deps.now().getTime();
+                if (remaining <= 0)
+                    break;
+                const backoff = await Promise.race([deps.wait(Math.min(remaining, 1_000, 500 * (candidateIndex + 1))).then(() => ({ waited: true })), earlySignal.then(() => ({ signal: true }))]);
+                if ('signal' in backoff) {
+                    outcome = finish('dismissed', 'Alarm interrupted during station retry backoff.');
+                    return { status: 'dismissed', message: outcome.message };
+                }
+            }
+        }
+        if (lastError)
+            throw lastError;
+        firedAt = deps.now();
+        try {
+            const acquiring = deps.inhibitor.acquire('RadioCLI alarm playback');
+            void acquiring.then(acquired => { if (signalReceived)
+                void acquired.release().catch(() => undefined); }).catch(() => { });
+            const acquired = await Promise.race([acquiring.then(value => ({ value })), earlySignal.then(() => ({ signal: true }))]);
+            if ('signal' in acquired) {
+                outcome = finish('dismissed', 'Alarm interrupted while sleep protection was starting.');
+                return { status: 'dismissed', message: outcome.message };
+            }
+            lease = acquired.value;
+            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: true, active: true, message: 'Sleep inhibition active while playing.' });
+            void lease.unexpectedExit?.then(error => { try {
+                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: false, active: false, message: `Playback continues after sleep protection exited: ${error.message}` });
+            }
+            catch { } }).catch(() => { });
+        }
+        catch (error) {
+            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: false, active: false, message: `Playback continues without sleep protection: ${errorMessage(error)}` });
+        }
+        const startedAt = deps.now();
+        deps.store.addRecent(resolvedStation);
+        deps.store.startListeningSession(resolvedStation, startedAt);
+        listening = true;
+        const activeStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: resolvedStation.name, station: resolvedStation, startedAt: startedAt.toISOString(), state: 'playing' };
+        session.update(activeStatus);
+        void deps.openControls?.(activeStatus).catch(error => { try {
+            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: true, message: `Alarm is playing, but RadioCLI controls could not open automatically: ${errorMessage(error)}` });
+        }
+        catch { } });
+        onPlaybackSignal = () => { action = 'signal'; resolveAction('signal'); };
+        if (signalReceived)
+            onPlaybackSignal();
+        {
+            const supportsFade = deps.player.getState().backend === 'mpv';
+            if (supportsFade && alarm.playback.fadeSeconds > 0) {
+                const zero = await deps.player.setVolume(0);
+                if (zero.ok) {
+                    const steps = Math.min(1800, Math.max(1, Math.ceil(alarm.playback.fadeSeconds / 2)));
+                    for (let step = 1; step <= steps && !action; step += 1) {
+                        await Promise.race([deps.wait(alarm.playback.fadeSeconds * 1000 / steps), actionPromise]);
+                        if (!action) {
+                            const changed = await deps.player.setVolume(Math.round(alarm.playback.volume * step / steps));
+                            if (!changed.ok) {
+                                await deps.player.setVolume(alarm.playback.volume);
+                                break;
+                            }
+                        }
+                    }
+                }
+                else
+                    await deps.player.setVolume(alarm.playback.volume);
+            }
+            else {
+                const volume = await deps.player.setVolume(alarm.playback.volume);
+                if (!volume.ok)
+                    deps.health?.record({ alarmId, component: 'runner', healthy: true, message: volume.message ?? 'The selected backend does not support runtime volume; it started with the configured alarm volume.' });
+            }
+            if (!action) {
+                const elapsed = Math.max(0, deps.now().getTime() - startedAt.getTime());
+                const timeout = deps.wait(Math.max(0, alarm.playback.stopAfterMinutes * 60_000 - elapsed)).then(() => keepPlaying ? new Promise(() => { }) : 'timeout');
+                action = await Promise.race([actionPromise, timeout]);
+            }
+        }
+        outcome = finish(action === 'dismissed' || action === 'snoozed' || action === 'signal' ? 'dismissed' : 'played', action === 'snoozed' ? 'Snoozed.' : action === 'handoff' ? 'Handed off to interactive playback.' : action === 'signal' ? 'Interrupted.' : undefined);
+        return { status: outcome.status, message: outcome.message };
+    }
+    catch (error) {
+        outcome = finish('failed', errorMessage(error));
+        return { status: 'failed', message: outcome.message };
+    }
+    finally {
+        unsubscribeSignals?.();
+        try {
+            await deps.player.stop();
+        }
+        catch { }
+        if (!preserveSystemVolume)
+            try {
+                await systemVolumeLease?.release();
+            }
+            catch (error) {
+                try {
+                    deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: false, message: `Previous system output volume could not be restored: ${errorMessage(error)}` });
+                }
+                catch { }
+            }
+        if (listening) {
+            try {
+                deps.store.checkpointActiveListeningSession(deps.now());
+                deps.store.finishActiveListeningSession(deps.now());
+            }
+            catch { }
+        }
+        try {
+            await lease?.release();
+            if (lease)
+                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: true, active: false, message: 'Playback sleep inhibition released.' });
+        }
+        catch (error) {
+            try {
+                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: false, active: true, message: `Unable to verify inhibitor release: ${errorMessage(error)}` });
+            }
+            catch { }
+        }
+        try {
+            await session?.close();
+        }
+        catch { }
+        if (alarm && outcome) {
+            try {
+                deps.store.recordAlarmOutcome(alarmId, outcome, { clearNextOverride: !preserveNextOverride });
+                const latest = deps.store.getAlarm(alarmId);
+                if (alarm.schedule.type === 'once' && latest?.schedule.type === 'once' && latest.schedule.at === alarm.schedule.at && validTerminalOccurrence && !preserveNextOverride)
+                    deps.store.toggleAlarm(alarmId, false);
+            }
+            catch { }
+        }
+        alarm = deps.store.getAlarm(alarmId);
+        if (alarm)
+            try {
+                if (deps.scheduler.syncClaimed)
+                    await deps.scheduler.syncClaimed(alarm, scheduledAt);
+                else
+                    await deps.scheduler.sync(alarm);
+            }
+            catch { }
+        try {
+            releaseLock();
+        }
+        catch (error) {
+            try {
+                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: false, message: `Occurrence lock cleanup failed: ${errorMessage(error)}` });
+            }
+            catch { }
+        }
+        try {
+            await deps.scheduler.completeOccurrence?.(alarmId, scheduledAt);
+        }
+        catch (error) {
+            try {
+                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'scheduler', healthy: false, message: `Completed launch job cleanup failed: ${errorMessage(error)}` });
+            }
+            catch { }
+        }
+    }
+}
+export function acquireOccurrenceLock(alarmId, scheduledAt, root = defaultAlarmRuntimeDirectory()) {
+    const safe = `${alarmId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80)}-${Buffer.from(scheduledAt).toString('base64url')}`;
+    const path = join(root, 'locks', safe);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    pruneCompletedOccurrenceLocks(root);
+    try {
+        mkdirSync(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        try {
+            if (existsSync(join(path, 'completed')))
+                return null;
+            const pid = Number(readFileSync(join(path, 'running'), 'utf8'));
+            if (Number.isInteger(pid) && processAlive(pid))
+                return null;
+            rmSync(path, { recursive: true, force: true });
+            mkdirSync(path, { mode: 0o700 });
+        }
+        catch {
+            return null;
+        }
+    }
+    writeFileSync(join(path, 'running'), String(process.pid), { mode: 0o600 });
+    return () => { rmSync(join(path, 'running'), { force: true }); writeFileSync(join(path, 'completed'), new Date().toISOString(), { mode: 0o600 }); };
+}
+export function pruneCompletedOccurrenceLocks(root = defaultAlarmRuntimeDirectory(), olderThanMs = 30 * 24 * 60 * 60_000, now = Date.now()) { const directory = join(root, 'locks'); if (!existsSync(directory))
+    return 0; let removed = 0; for (const name of readdirSync(directory)) {
+    const completed = join(directory, name, 'completed');
+    try {
+        if (existsSync(completed) && now - statSync(completed).mtimeMs > olderThanMs) {
+            rmSync(join(directory, name), { recursive: true, force: true });
+            removed += 1;
+        }
+    }
+    catch { }
+} return removed; }
+export function defaultAlarmRuntimeDirectory() { if (process.env.RADIOCLI_HOME)
+    return join(process.env.RADIOCLI_HOME, 'runtime'); if (process.platform === 'win32')
+    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime'); return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli'); }
+export const defaultRunnerUtilities = { acquireLock: acquireOccurrenceLock, createSession: startActiveAlarmSession, wait: (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)), subscribeSignals: (handler) => { process.once('SIGTERM', handler); process.once('SIGHUP', handler); process.once('SIGINT', handler); return () => { process.off('SIGTERM', handler); process.off('SIGHUP', handler); process.off('SIGINT', handler); }; } };
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function processAlive(pid) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} }
+function nextExpectedOccurrence(alarm, scheduledAt) { if (alarm.nextOverride)
+    return new Date(alarm.nextOverride.at); if (alarm.schedule.type === 'once')
+    return new Date(alarm.schedule.at); return nextOccurrenceForAlarmAt(alarm, new Date(scheduledAt.getTime() - 1500)); }
+function nextOccurrenceForAlarmAt(alarm, now) { return nextOccurrenceForAlarm(alarm, now); }

package/dist/alarms/runtime-health.js

@@ -0,0 +1,79 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { defaultAlarmRuntimeDirectory } from './runner.js';
+/** Machine-local operational state; deliberately excluded from profile exports. */
+export class AlarmRuntimeHealthStore {
+    filePath;
+    now;
+    constructor(filePath = join(defaultAlarmRuntimeDirectory(), 'alarm-health.json'), now = () => new Date()) {
+        this.filePath = filePath;
+        this.now = now;
+    }
+    record(entry) { const current = this.now(); const value = { ...entry, updatedAt: current.toISOString() }; validateEntry(value); const release = acquireHealthLock(this.filePath); try {
+        const entries = pruneEntries([value, ...this.list().filter(item => !(item.alarmId === entry.alarmId && item.component === entry.component && item.occurrenceAt === entry.occurrenceAt))], current);
+        this.write({ version: 1, entries });
+        return value;
+    }
+    finally {
+        release();
+    } }
+    get(alarmId, component) { return this.list().filter(item => item.alarmId === alarmId && (!component || item.component === component)); }
+    list() { if (!existsSync(this.filePath))
+        return []; try {
+        const file = JSON.parse(readFileSync(this.filePath, 'utf8'));
+        if (file.version !== 1 || !Array.isArray(file.entries))
+            return [];
+        return file.entries.filter(entry => { try {
+            validateEntry(entry);
+            return true;
+        }
+        catch {
+            return false;
+        } });
+    }
+    catch {
+        return [];
+    } }
+    remove(alarmId, component) { const release = acquireHealthLock(this.filePath); try {
+        this.write({ version: 1, entries: this.list().filter(item => item.alarmId !== alarmId || (component && item.component !== component)) });
+    }
+    finally {
+        release();
+    } }
+    write(file) { mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 }); const temp = `${this.filePath}.tmp-${process.pid}`; try {
+        writeFileSync(temp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temp, this.filePath);
+        if (process.platform !== 'win32')
+            chmodSync(this.filePath, 0o600);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    } }
+}
+function validateEntry(entry) { if (!entry || typeof entry.alarmId !== 'string' || !entry.alarmId || !['scheduler', 'power', 'runner'].includes(entry.component) || typeof entry.healthy !== 'boolean' || (entry.active !== undefined && typeof entry.active !== 'boolean') || typeof entry.message !== 'string' || !Number.isFinite(Date.parse(entry.updatedAt)) || (entry.occurrenceAt !== undefined && !Number.isFinite(Date.parse(entry.occurrenceAt))) || (entry.nextOccurrence !== undefined && !Number.isFinite(Date.parse(entry.nextOccurrence))))
+    throw new Error('Invalid alarm runtime health entry.'); }
+function pruneEntries(entries, now) { const activeCutoff = now.getTime() - 24 * 60 * 60_000; const active = entries.filter(item => item.active === true && Date.parse(item.updatedAt) >= activeCutoff).slice(0, 128); const counts = new Map(); const inactive = entries.filter(item => item.active !== true).filter(item => { const key = `${item.alarmId}\0${item.component}`; const count = counts.get(key) ?? 0; if (count >= 8)
+    return false; counts.set(key, count + 1); return true; }).slice(0, 256); return [...active, ...inactive]; }
+function acquireHealthLock(filePath) { const path = `${filePath}.lock`; mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 }); const deadline = Date.now() + 1000; while (true) {
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        return () => rmSync(path, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        try {
+            if (Date.now() - statSync(path).mtimeMs > 10_000) {
+                rmSync(path, { recursive: true, force: true });
+                continue;
+            }
+        }
+        catch {
+            continue;
+        }
+        if (Date.now() >= deadline)
+            throw new Error('Alarm runtime health state is busy.');
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+} }

package/dist/alarms/schedule.js

@@ -0,0 +1,149 @@
+export const NATIVE_DISPATCH_TOLERANCE_MS = 30_000;
+const formatterCache = new Map();
+export function isValidTimeZone(timezone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: timezone }).format();
+        return timezone.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function canonicalizeTimeZone(timezone) {
+    const value = timezone.trim();
+    if (!isValidTimeZone(value)) {
+        throw new Error(`Invalid IANA timezone: ${timezone}`);
+    }
+    return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
+}
+export function canonicalizeAlarmTime(time) {
+    const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+    const hour = Number(match?.[1]);
+    const minute = Number(match?.[2]);
+    if (!match || !Number.isInteger(hour) || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+        throw new Error(`Invalid alarm time: ${time}. Use HH:mm in 24-hour time.`);
+    }
+    return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+}
+export function canonicalizeIsoWeekdays(weekdays) {
+    if (weekdays.length === 0 || weekdays.some(day => !Number.isInteger(day) || day < 1 || day > 7)) {
+        throw new Error('Alarm weekdays must contain ISO weekday numbers from 1 (Monday) to 7 (Sunday).');
+    }
+    return [...new Set(weekdays)].sort((left, right) => left - right);
+}
+/**
+ * Finds the next instant strictly after `now`.
+ *
+ * Recurring alarms are resolved from their civil date/time. During a spring DST
+ * gap, the first valid minute following the gap is used. During a fall overlap,
+ * the earlier of the two matching instants is used, so the occurrence fires once.
+ */
+export function nextAlarmOccurrence(schedule, now) {
+    assertValidDate(now, 'now');
+    if (schedule.type === 'once') {
+        const occurrence = new Date(schedule.at);
+        assertValidDate(occurrence, 'one-time alarm instant');
+        if (occurrence.getUTCSeconds() !== 0 || occurrence.getUTCMilliseconds() !== 0)
+            throw new Error('One-time alarms use minute precision; seconds must be zero.');
+        return occurrence.getTime() > now.getTime() ? occurrence : null;
+    }
+    const timezone = canonicalizeTimeZone(schedule.timezone);
+    const time = canonicalizeAlarmTime(schedule.time);
+    const weekdays = new Set(canonicalizeIsoWeekdays(schedule.weekdays));
+    const [hourText, minuteText] = time.split(':');
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const localNow = zonedParts(now, timezone);
+    for (let offset = 0; offset <= 7; offset += 1) {
+        const date = addCivilDays(localNow, offset);
+        if (!weekdays.has(isoWeekday(date.year, date.month, date.day)))
+            continue;
+        const occurrence = resolveCivilOccurrence({ ...date, hour, minute }, timezone);
+        if (occurrence && occurrence.getTime() > now.getTime())
+            return occurrence;
+    }
+    return null;
+}
+export function nextOccurrenceForAlarm(alarm, now) {
+    if (!alarm.enabled)
+        return null;
+    if (alarm.nextOverride) {
+        const override = new Date(alarm.nextOverride.at);
+        assertValidDate(override, 'alarm next override');
+        if (override.getTime() > now.getTime())
+            return override;
+    }
+    return nextAlarmOccurrence(alarm.schedule, now);
+}
+export function assessScheduledOccurrence(scheduledAt, now, missedRunGraceMinutes) {
+    assertValidDate(scheduledAt, 'scheduled occurrence');
+    assertValidDate(now, 'now');
+    if (!Number.isFinite(missedRunGraceMinutes) || missedRunGraceMinutes < 0) {
+        throw new Error('Missed-run grace must be a non-negative number of minutes.');
+    }
+    const elapsed = now.getTime() - scheduledAt.getTime();
+    if (elapsed < 0)
+        return 'pending';
+    return elapsed <= Math.max(NATIVE_DISPATCH_TOLERANCE_MS, missedRunGraceMinutes * 60_000) ? 'due' : 'missed';
+}
+function zonedParts(instant, timezone) {
+    let formatter = formatterCache.get(timezone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-CA', {
+            timeZone: timezone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            hourCycle: 'h23'
+        });
+        formatterCache.set(timezone, formatter);
+    }
+    const values = Object.fromEntries(formatter.formatToParts(instant)
+        .filter(part => part.type !== 'literal')
+        .map(part => [part.type, Number(part.value)]));
+    return {
+        year: values.year ?? 0,
+        month: values.month ?? 0,
+        day: values.day ?? 0,
+        hour: values.hour ?? 0,
+        minute: values.minute ?? 0
+    };
+}
+function resolveCivilOccurrence(target, timezone) {
+    const estimate = Date.UTC(target.year, target.month - 1, target.day, target.hour, target.minute);
+    const start = estimate - 18 * 60 * 60_000;
+    const end = estimate + 18 * 60 * 60_000;
+    let firstAfterGap = null;
+    for (let time = start; time <= end; time += 60_000) {
+        const candidate = new Date(time);
+        const local = zonedParts(candidate, timezone);
+        if (!sameCivilDate(local, target))
+            continue;
+        const comparison = compareCivilClock(local, target);
+        if (comparison === 0)
+            return candidate;
+        if (comparison > 0 && firstAfterGap === null)
+            firstAfterGap = candidate;
+    }
+    return firstAfterGap;
+}
+function addCivilDays(date, days) {
+    const result = new Date(Date.UTC(date.year, date.month - 1, date.day + days));
+    return { year: result.getUTCFullYear(), month: result.getUTCMonth() + 1, day: result.getUTCDate() };
+}
+function isoWeekday(year, month, day) {
+    const sundayBased = new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+    return (sundayBased === 0 ? 7 : sundayBased);
+}
+function sameCivilDate(left, right) {
+    return left.year === right.year && left.month === right.month && left.day === right.day;
+}
+function compareCivilClock(left, right) {
+    return left.hour * 60 + left.minute - (right.hour * 60 + right.minute);
+}
+function assertValidDate(date, label) {
+    if (!Number.isFinite(date.getTime()))
+        throw new Error(`Invalid ${label}.`);
+}