@chipmobilesdk/rn-notification 0.1.2 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.1.2",
+	"version": "0.2.1",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -34,6 +34,7 @@
 		"src/permission",
 		"src/push",
 		"src/recurrence",
+		"src/repeat",
 		"src/reconcile",
 		"src/schedule",
 		"src/state",

package/skills/sdk-rn-notification/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: sdk-rn-notification
-description: "Local and push notifications via @chipmobilesdk/rn-notification: scheduling, identifiers, wall-clock vs absolute anchoring, idempotent reconciliation, recurrence windows, permissions, Android channel migration, tap routing, FCM. Use when scheduling a reminder, handling a notification tap, requesting notification permission, changing a channel, or debugging a notification that did not arrive."
+description: "Local and push notifications via @chipmobilesdk/rn-notification: scheduling, identifiers, wall-clock vs absolute anchoring, idempotent reconciliation, recurrence windows, permissions, alarm-style repeating tones with a bounded window, tone labels in system settings, Android channel migration, tap routing, FCM. Use when scheduling a reminder or alarm, making a notification repeat until handled, naming a tone users see in settings, handling a notification tap, requesting notification permission, changing a channel, or debugging a notification that did not arrive."
 metadata:
   package: "@chipmobilesdk/rn-notification"
-  packageVersion: "0.1.1"
+  packageVersion: "0.2.1"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -20,6 +20,7 @@ survives a cold start.
 - Reacting to a tap, an action button, or a dismissal
 - Requesting notification or exact-alarm permission
 - Declaring or changing a tone/channel, or enabling push
+- Building an alarm-style reminder that repeats until the user handles it
 - Debugging a notification that did not arrive, or arrived twice
 
 **Not** for in-app banners or an inbox (this package renders nothing), for storing app
@@ -64,7 +65,8 @@ See `### Android` and `### Backup exclusion`.
 Three entrypoints. The **root** exports one factory per concern (`createScheduler`,
 `createReconciler`, `createRecurrence`, `createPermissions`, `createChannels`,
 `createInteractions`, `createSnapshot`), the maintenance steps and their registry, plus
-`resolveTone`, `resetState`, `clearOwner`, `isNonFailure` and `DIAGNOSTIC_CODES`.
+`resolveTone`, `registerBackgroundNotificationHandler`, `resetState`, `clearOwner`,
+`isNonFailure`, `REPEAT_ALERT_BOUNDS` and `DIAGNOSTIC_CODES`.
 **`/push`** carries the push gate, FCM provider, instruction handler and sign-out —
 **import it only if you enable push**, because an app that never touches this subpath ships
 no provider code, no push permissions, and no entitlements. **`/testing`** carries the fake
@@ -82,6 +84,7 @@ rather than guessing.
 | Install, peers, enabling push | `## Installation`, `### Enabling push (optional)` |
 | Native setup | `### iOS`, `### Android`, `### Backup exclusion` |
 | Naming notifications | `## Choosing identifiers` |
+| Tones, alarms, labels, version bumps | `## Tones and channels` |
 | Time zones and travel | `## Choosing an anchoring mode` |
 | Automatic vs your responsibility | `## Maintenance versus reconciliation` |
 | Converging the device to your data | `## Reconciliation`, `## Recurrence` |
@@ -92,6 +95,68 @@ rather than guessing.
 | Limits and timing budgets | `## Budgets` |
 | Error codes | `## Diagnostic identifiers` |
 
+## Alarm-style tones (0.2.0+)
+
+For a reminder that must not be missed — medication, a wake-up, an appointment — declare
+the repeat on the **tone**, not on each notification:
+
+```ts
+await channels.apply([{
+  id: 'medication',
+  name: t('notifications.medication.name'),   // localized; users read this in settings
+  description: t('notifications.medication.hint'),
+  urgency: 'max',
+  sound: { name: 'chime' },
+  vibration: true,
+  bypassDoNotDisturb: true,                    // an alarm silenced by DND is not an alarm
+  repeatAlert: { forMs: 15 * 60 * 1000 },      // required bound, 1–60 minutes
+  timeSensitive: true,
+  version: 1,                                  // unchanged — these need no bump
+}]);
+```
+
+Four things to get right, none of them visible in the signatures:
+
+1. **The duration is mandatory and bounded (1–60 min, `REPEAT_ALERT_BOUNDS`).** There is no
+   unbounded form; the type forbids it. Do not reach for a workaround — an alert with no
+   bound means a user comes home to a phone still ringing.
+2. **Expiry stops the sound; it never removes the notification.** The user must still be
+   able to see what they missed. If you find yourself cancelling at expiry, you have
+   inverted the requirement. The window is a **floor**, not a precise stop — the entry
+   that ends the alert inherits normal delivery accuracy, so without exact alarms it
+   overruns (a declared 2 min measured 2m35s–3m00s). Never promise a caller an exact cut-off.
+3. **Repeating tones need one setup step**, at module scope in `index.js`, never in a
+   component or an effect:
+   ```js
+   import { registerBackgroundNotificationHandler } from '@chipmobilesdk/rn-notification';
+   registerBackgroundNotificationHandler({ engine });
+   ```
+   Without it nothing ends the alert while the app is dead. `apply()` reports
+   `REPEAT_STOP_HANDLER_MISSING`. An app with no repeating tone needs none of this.
+4. **iOS refuses repetition entirely** — no looping API exists, and the alert level that
+   would need an Apple-granted entitlement does not loop either. It is reported in
+   `result.repeatUnavailable`; the notification still delivers and sounds once. Never
+   promise a caller an iOS alarm loops. `timeSensitive` on iOS also needs the consuming
+   app's own Time Sensitive Notifications capability, or it degrades to `active`.
+
+Read `## Tones and channels` before promising behaviour to anyone: it carries the
+per-platform matrix and six limits that stay true (notification volume rather than alarm
+volume on Android, the shade stopping an insistent sound, vendor battery management).
+
+## Changing a tone: when a version bump is required
+
+A bump means a **new channel**, and a new channel means the user loses every setting they
+adjusted. Never bump one to fix a label.
+
+| Change | Bump `version`? |
+|---|---|
+| `name`, `description` | **No** — updated in place on existing installs |
+| `repeatAlert`, `timeSensitive` | **No** — realized per notification |
+| `urgency`, `sound`, `vibration`, `badge`, `groupId`, `bypassDoNotDisturb` | **Yes** |
+
+`apply()` reports a label correction as `labelsRefreshed`, distinct from `created`,
+`migrated`, and `unchanged`.
+
 ## Debugging "it did not arrive"
 
 Capture a state snapshot (`createSnapshot`) before guessing — permissions, applied channel

package/src/channel/migrate.ts

@@ -20,7 +20,8 @@ import type {
 import type { NotificationEngineAdapter } from '../engine/adapter';
 import type { StateManager, MigrationEntry } from '../state/record';
 import { DIAGNOSTIC_CODES } from '../contract/errors';
-import { channelIdFor, resolveTone } from './tone-map';
+import { channelIdFor, resolveTone, toneLabelFingerprint } from './tone-map';
+import { validateToneDeclarations } from './validate-tone';
 
 export interface ChannelDependencies {
 	readonly engine: NotificationEngineAdapter;
@@ -37,7 +38,8 @@ function recordApplied(
 	state: StateManager,
 	tone: ToneDeclaration,
 	now: number,
-	retiredChannelId?: string,
+	retiredChannelId: string | undefined,
+	labelFingerprint: string,
 ): void {
 	state.update('migrationLedger', current => {
 		const withoutTone = current.filter(entry => entry.toneId !== tone.id);
@@ -63,6 +65,7 @@ function recordApplied(
 				appliedVersion: tone.version,
 				channelId: channelIdFor(tone.id, tone.version),
 				retired: false,
+				labelFingerprint,
 			},
 		];
 	});
@@ -82,14 +85,21 @@ export function createChannels(deps: ChannelDependencies) {
 			tones: readonly ToneDeclaration[],
 			groups: readonly ChannelGroup[] = [],
 		): Promise<ChannelApplyResult> {
+			// Validation completes before the first engine call, so a rejected
+			// declaration leaves the device exactly as it was — the same order the
+			// scheduler has always used.
+			validateToneDeclarations(tones);
+
 			const now = deps.now();
 
 			const created: string[] = [];
 			const migrated: { toneId: string; from: number; to: number }[] = [];
+			const labelsRefreshed: string[] = [];
 			const retired: string[] = [];
 			const reHomed: string[] = [];
 			const cancelled: string[] = [];
 			const bypassUnavailable: string[] = [];
+			const repeatUnavailable: string[] = [];
 			const unchanged: string[] = [];
 
 			if (groups.length > 0) {
@@ -101,12 +111,11 @@ export function createChannels(deps: ChannelDependencies) {
 			for (const tone of tones) {
 				const previous = ledgerFor(deps.state, tone.id);
 				const resolved = resolveTone(tone);
+				const fingerprint = toneLabelFingerprint(tone);
 
-				if (previous !== undefined && previous.appliedVersion === tone.version) {
-					unchanged.push(tone.id);
-					continue;
-				}
-
+				// Refusals are reported for every tone that asked, whether or not
+				// anything else about it moved. A platform declining an attribute
+				// says nothing about whether the channel is new.
 				if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
 					// Reported honestly rather than silently dropped — a consumer that
 					// asked for a bypass deserves to know the platform refused.
@@ -118,13 +127,65 @@ export function createChannels(deps: ChannelDependencies) {
 					);
 				}
 
-				const didCreate = await deps.engine.declareTone(resolved);
-				if (didCreate) {
+				if (tone.repeatAlert !== undefined) {
+					if (!capabilities.supportsRepeatingAlert) {
+						repeatUnavailable.push(tone.id);
+						emit(
+							DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
+							`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
+							{ toneId: tone.id },
+						);
+					} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
+						// Said out loud at declaration time, because the alternative is a
+						// user meeting it as a phone that will not stop ringing.
+						emit(
+							DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
+							`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
+							{ toneId: tone.id },
+						);
+					}
+				}
+
+				const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
+
+				if (previous !== undefined && !versionMoved) {
+					// The version is the same, so nothing the platform freezes has
+					// changed. Only the labels can still be stale — and correcting
+					// those must cost the user nothing, so the platform is touched
+					// only when the fingerprint actually moved.
+					if (previous.labelFingerprint === fingerprint) {
+						unchanged.push(tone.id);
+						continue;
+					}
+
+					const outcome = await deps.engine.declareTone(resolved);
+					if (outcome === 'created') {
+						// The channel was gone — deleted by the user, or lost with the
+						// app's data — so this is a first declaration rather than a
+						// refresh, whatever our ledger believed.
+						created.push(resolved.android.channelId);
+					} else if (outcome === 'labelsRefreshed') {
+						labelsRefreshed.push(tone.id);
+						emit(
+							DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
+							`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
+							{ toneId: tone.id },
+						);
+					} else {
+						unchanged.push(tone.id);
+					}
+
+					recordApplied(deps.state, tone, now, undefined, fingerprint);
+					continue;
+				}
+
+				const outcome = await deps.engine.declareTone(resolved);
+				if (outcome === 'created') {
 					created.push(resolved.android.channelId);
 				}
 
 				if (previous === undefined) {
-					recordApplied(deps.state, tone, now);
+					recordApplied(deps.state, tone, now, undefined, fingerprint);
 					continue;
 				}
 
@@ -168,8 +229,11 @@ export function createChannels(deps: ChannelDependencies) {
 					retired.push(previous.channelId);
 				}
 
+				// A version move outranks a label change: the new channel simply
+				// carries the new labels, and reporting it as a refresh would hide a
+				// migration the consumer needs to know about.
 				migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
-				recordApplied(deps.state, tone, now, previous.channelId);
+				recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
 			}
 
 			// Anything left on a retired channel would be an orphan — a notification
@@ -185,7 +249,17 @@ export function createChannels(deps: ChannelDependencies) {
 				);
 			}
 
-			return { created, migrated, retired, reHomed, cancelled, bypassUnavailable, unchanged };
+			return {
+				created,
+				migrated,
+				labelsRefreshed,
+				retired,
+				reHomed,
+				cancelled,
+				bypassUnavailable,
+				repeatUnavailable,
+				unchanged,
+			};
 		},
 
 		/** Which version of each tone this device actually holds. */

package/src/channel/tone-map.ts

@@ -1,90 +1,130 @@
-/**
- * Tone-to-platform mapping.
- *
- * A tone is declared once and realized on each platform here, so consumer code
- * contains zero platform branches. The two platforms model urgency differently
- * — Android by channel importance, iOS by interruption level — and reconciling
- * that difference is exactly the work this package exists to absorb.
- *
- * The channel id carries the tone version. Android channels are immutable once
- * created and re-declaration is silently ignored, so a configuration change has
- * to produce a *new* channel or it will never reach a device that already holds
- * the old one.
- */
-
-import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
-
-type AndroidImportance = ResolvedTone['android']['importance'];
-type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
-
-const ANDROID_IMPORTANCE: Record<ToneUrgency, AndroidImportance> = {
-	min: 'min',
-	low: 'low',
-	default: 'default',
-	high: 'high',
-	// Android has no level above `high`; max urgency is expressed by the DND
-	// bypass rather than by a distinct importance.
-	max: 'high',
-};
-
-const IOS_INTERRUPTION: Record<ToneUrgency, IosInterruption> = {
-	min: 'passive',
-	low: 'passive',
-	default: 'active',
-	high: 'active',
-	// `timeSensitive` is the highest level available without the Critical Alerts
-	// entitlement, which is out of scope for v1.
-	max: 'timeSensitive',
-};
-
-/** Channel id for a tone at a given version. Stable, derived, never random. */
-export function channelIdFor(toneId: string, version: number): string {
-	return `${toneId}.v${version}`;
-}
-
-/** Extracts the tone and version encoded in a channel id, if it is one of ours. */
-export function parseChannelId(
-	channelId: string,
-): { readonly toneId: string; readonly version: number } | undefined {
-	const separator = channelId.lastIndexOf('.v');
-	if (separator === -1) return undefined;
-
-	const version = Number.parseInt(channelId.slice(separator + 2), 10);
-	if (!Number.isInteger(version) || version < 1) return undefined;
-
-	return { toneId: channelId.slice(0, separator), version };
-}
-
-export function resolveTone(tone: ToneDeclaration): ResolvedTone {
-	const silent = tone.sound?.enabled === false;
-
-	return {
-		toneId: tone.id,
-		version: tone.version,
-		android: {
-			channelId: channelIdFor(tone.id, tone.version),
-			importance: ANDROID_IMPORTANCE[tone.urgency],
-			sound: silent ? undefined : tone.sound?.name,
-			vibration: tone.vibration ?? false,
-			badge: tone.badge ?? false,
-			bypassDnd: tone.bypassDoNotDisturb ?? false,
-			groupId: tone.groupId,
-		},
-		ios: {
-			// iOS categories are not versioned: they carry actions rather than
-			// user-adjustable settings, so re-declaring one is harmless.
-			categoryId: tone.id,
-			interruptionLevel: IOS_INTERRUPTION[tone.urgency],
-			sound: silent ? undefined : tone.sound?.name,
-			badge: tone.badge ?? false,
-		},
-	};
-}
-
-/** Builds a lookup over a declared configuration. */
-export function createToneResolver(
-	tones: readonly ToneDeclaration[],
-): (toneId: string) => ResolvedTone | undefined {
-	const resolved = new Map(tones.map(tone => [tone.id, resolveTone(tone)]));
-	return toneId => resolved.get(toneId);
-}
+/**
+ * Tone-to-platform mapping.
+ *
+ * A tone is declared once and realized on each platform here, so consumer code
+ * contains zero platform branches. The two platforms model urgency differently
+ * — Android by channel importance, iOS by interruption level — and reconciling
+ * that difference is exactly the work this package exists to absorb.
+ *
+ * The channel id carries the tone version. Android channels are immutable once
+ * created and re-declaration is silently ignored, so a configuration change has
+ * to produce a *new* channel or it will never reach a device that already holds
+ * the old one.
+ */
+
+import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
+
+type AndroidImportance = ResolvedTone['android']['importance'];
+type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
+
+const ANDROID_IMPORTANCE: Record<ToneUrgency, AndroidImportance> = {
+	min: 'min',
+	low: 'low',
+	default: 'default',
+	high: 'high',
+	// Android has no level above `high`; max urgency is expressed by the DND
+	// bypass rather than by a distinct importance.
+	max: 'high',
+};
+
+const IOS_INTERRUPTION: Record<ToneUrgency, IosInterruption> = {
+	min: 'passive',
+	low: 'passive',
+	default: 'active',
+	high: 'active',
+	// `timeSensitive` is the highest level available without the Critical Alerts
+	// entitlement, which is out of scope for v1.
+	max: 'timeSensitive',
+};
+
+/** Channel id for a tone at a given version. Stable, derived, never random. */
+export function channelIdFor(toneId: string, version: number): string {
+	return `${toneId}.v${version}`;
+}
+
+/** Extracts the tone and version encoded in a channel id, if it is one of ours. */
+export function parseChannelId(
+	channelId: string,
+): { readonly toneId: string; readonly version: number } | undefined {
+	const separator = channelId.lastIndexOf('.v');
+	if (separator === -1) return undefined;
+
+	const version = Number.parseInt(channelId.slice(separator + 2), 10);
+	if (!Number.isInteger(version) || version < 1) return undefined;
+
+	return { toneId: channelId.slice(0, separator), version };
+}
+
+export function resolveTone(tone: ToneDeclaration): ResolvedTone {
+	const silent = tone.sound?.enabled === false;
+	const repeats = tone.repeatAlert !== undefined;
+
+	return {
+		toneId: tone.id,
+		version: tone.version,
+		android: {
+			channelId: channelIdFor(tone.id, tone.version),
+			// The declared label, not the identifier. Passing the identifier here
+			// is what put a technical string on the one screen these exist for.
+			name: tone.name,
+			description: tone.description,
+			importance: ANDROID_IMPORTANCE[tone.urgency],
+			sound: silent ? undefined : tone.sound?.name,
+			vibration: tone.vibration ?? false,
+			badge: tone.badge ?? false,
+			bypassDnd: tone.bypassDoNotDisturb ?? false,
+			groupId: tone.groupId,
+			// Both are per-notification rather than channel configuration, which
+			// is precisely why neither obliges a consumer to bump `version`.
+			loopSound: repeats,
+			alarmCategory: tone.timeSensitive ?? false,
+			repeatForMs: tone.repeatAlert?.forMs,
+		},
+		ios: {
+			// iOS categories are not versioned: they carry actions rather than
+			// user-adjustable settings, so re-declaring one is harmless.
+			categoryId: tone.id,
+			interruptionLevel:
+				tone.timeSensitive === true ? 'timeSensitive' : IOS_INTERRUPTION[tone.urgency],
+			sound: silent ? undefined : tone.sound?.name,
+			badge: tone.badge ?? false,
+			// iOS exposes no looping-sound API at all. Recorded as data so the
+			// refusal can be reported rather than discovered.
+			repeatRefused: repeats,
+		},
+	};
+}
+
+/**
+ * A stable fingerprint of a tone's user-visible labels.
+ *
+ * Lets an unchanged configuration skip the platform entirely, which is what
+ * keeps "re-applying changes nothing" literally true rather than merely
+ * approximately true. A hash rather than the labels themselves, so persisted
+ * state continues to hold no consumer-supplied text.
+ */
+export function toneLabelFingerprint(tone: ToneDeclaration): string {
+	// The separator matters: without it, a name of "ab" with description "c" and
+	// a name of "a" with description "bc" would fingerprint identically, and one
+	// of the two would never get its correction.
+	const source = `${tone.name}\u0000${tone.description ?? ''}`;
+
+	// FNV-1a. Bitwise operators are the algorithm, not a micro-optimisation:
+	// arithmetic equivalents would not wrap to 32 bits and the hash would drift.
+	/* eslint-disable no-bitwise */
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < source.length; index += 1) {
+		hash ^= source.codePointAt(index) ?? 0;
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return (hash >>> 0).toString(16).padStart(8, '0');
+	/* eslint-enable no-bitwise */
+}
+
+/** Builds a lookup over a declared configuration. */
+export function createToneResolver(
+	tones: readonly ToneDeclaration[],
+): (toneId: string) => ResolvedTone | undefined {
+	const resolved = new Map(tones.map(tone => [tone.id, resolveTone(tone)]));
+	return toneId => resolved.get(toneId);
+}

package/src/channel/validate-tone.ts

@@ -0,0 +1,61 @@
+/**
+ * Tone declaration validation.
+ *
+ * Runs before the first engine call, like every other validation in this
+ * package: a rejected declaration must leave the device exactly as it was.
+ *
+ * Only the new alert attributes are checked here. The rest of a tone has always
+ * been validated by the platform's own charset and shape rules, and duplicating
+ * those would create two sources of truth for the same constraint.
+ */
+
+import type { ToneDeclaration } from '../contract/channel';
+import { REPEAT_ALERT_BOUNDS } from '../contract/channel';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+
+/**
+ * Throws when a tone's repeating alert is unusable.
+ *
+ * The type already forbids a repeat without a duration. What it cannot forbid
+ * is a duration of zero, a fractional millisecond, or an hour and a half — and
+ * an alert that repeats for an unchecked span is the failure this whole feature
+ * exists to prevent.
+ */
+export function validateToneDeclaration(tone: ToneDeclaration): void {
+	const repeat = tone.repeatAlert;
+	if (repeat === undefined) return;
+
+	if (!Number.isInteger(repeat.forMs)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
+			`Tone "${tone.id}" declared a repeating alert whose duration is not a whole number of milliseconds.`,
+			{ toneId: tone.id, forMs: repeat.forMs },
+		);
+	}
+
+	if (repeat.forMs < REPEAT_ALERT_BOUNDS.minMs || repeat.forMs > REPEAT_ALERT_BOUNDS.maxMs) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
+			`Tone "${tone.id}" declared a repeating alert of ${repeat.forMs}ms, outside the permitted ${REPEAT_ALERT_BOUNDS.minMs}–${REPEAT_ALERT_BOUNDS.maxMs}ms range. A shorter repeat is indistinguishable from a single chime; a longer one outlasts anyone's willingness to respond.`,
+			{ toneId: tone.id, forMs: repeat.forMs, ...REPEAT_ALERT_BOUNDS },
+		);
+	}
+
+	if (tone.sound?.enabled === false) {
+		// Two instructions that cannot both be honoured. Picking one silently
+		// would ship whichever the reader did not expect, and the consumer would
+		// discover it on a device rather than here.
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_TONE_REPEAT,
+			`Tone "${tone.id}" declares both a repeating alert and a silent sound. Repeating silence is not a behaviour; drop one of the two.`,
+			{ toneId: tone.id },
+		);
+	}
+}
+
+/** Validates a whole configuration before any of it is applied. */
+export function validateToneDeclarations(tones: readonly ToneDeclaration[]): void {
+	for (const tone of tones) {
+		validateToneDeclaration(tone);
+	}
+}