@chipmobilesdk/rn-notification 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-notification` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] — 0.1.0
+
+First release. New package, no existing consumers, no migration burden.
+
+### Added
+
+- **Scheduling** — caller-supplied identifiers, replacement semantics, a two-sided 60-second tolerance window, and full-detail pending reads that let a consumer diff the device against its own intent.
+- **Time anchoring** — wall-clock (default) and absolute modes, with re-anchoring on device time-zone change and an `anchoringGeneration` on every entry so the one case re-anchoring cannot fix stays detectable.
+- **Reconciliation** — desired-set convergence that is idempotent, domain-scoped, chunked, and serialized against itself.
+- **Recurrence** — declare a rule once; the package maintains a bounded 60-day / 32-occurrence window and refreshes it, with deterministic daylight-saving resolution and clock-discontinuity bounding.
+- **Permissions** — six states that never collapse, independent display and exact-alarm requests, per-permission settings deep links, external-change detection, and manufacturer restriction reporting that admits `unknown`.
+- **Channels and tones** — one declarative configuration mapped to each platform, with a real migration path for Android's immutable channels.
+- **Interaction** — one handler for foreground, background, and cold start, backed by a durable buffer that survives process death.
+- **Push** — a provider-agnostic gate with a normalized envelope, token lifecycle, deduplication across process death, and best-effort handling of newer payload versions.
+- **Observability** — a structured event stream with content redaction, a state snapshot, burst detection, fault injection, and a shared conformance suite.
+
+### Notes
+
+- **Local engine substitution — approved 2026-08-16.** The specification named Notifee as the default engine. Its repository was archived on 2026-04-07 with its last release in December 2024, failing the constitution's actively-maintained-dependency requirement. This package uses `react-native-notify-kit`, the maintained 100%-API-compatible fork, **confirmed by the project owner**. The engine sits behind `NotificationEngineAdapter` and no consumer-facing behaviour depends on the choice — this substitution changed no functional requirement, success criterion, or user story. `expo-notifications` is the recorded migration target should the fork stall.
+- **Push is an optional peer.** An app that never imports `/push` ships no provider code, no push permissions, and no entitlements, and takes on none of the provider's data-collection declarations.
+- **No exact-alarm permission is declared by this package.** Consumers opt in; without it, notifications are scheduled in approximate mode with an explicit `mayBeDelayed` flag. `USE_EXACT_ALARM` is never recommended — Google Play restricts it to alarm, timer, and calendar apps.
+
+### Stability
+
+| Surface | Stability |
+|---|---|
+| Identifier rules | Stable — breaking to change (persisted by the platform on user devices) |
+| Routing payload contract | Stable — breaking to change |
+| Push payload contract | Stable — **append-only**; repurposing a released field is a contract violation, not a version bump |
+| Scheduling, reconciliation, permissions, interaction | Stable — additive minor releases only |
+| Adapter ports | Experimental — may gain members in minor releases |
+| Persisted state schema | Private — incompatible versions are discarded and rebuilt, never migrated |
+
+### Reserved for additive minor releases
+
+Additional push provider adapters, additional recurrence kinds, additional tone attributes, additional diagnostic identifiers, a consumer-supplied storage port, and in-app notification presentation.

package/README.md

@@ -0,0 +1,306 @@
+# @chipmobilesdk/rn-notification
+
+Shared notification library for bare React Native apps on iOS and Android.
+
+Scheduled local notifications with deterministic identity and idempotent reconciliation, provider-agnostic push, permission coordination, declarative channels and tones, action and tap routing across every app state, and a decision core you can test on a laptop.
+
+## Why this exists
+
+Every notification feature re-solves the same problems, and most of them are discovered after shipping:
+
+- Identifiers must be **derived from data**, not random, or you can never replace a notification you already scheduled.
+- The OS will not hold an unbounded repeating series, and iOS silently discards past **64 pending notifications**.
+- Reconciling "what my data implies" against "what the device holds" must be **idempotent**, or it is untestable.
+- Display permission and exact-alarm permission are **different things**, asked separately, and a refusal must not break the user's actual work.
+- Android channels are **immutable once created** — changing one is a migration, not an assignment.
+
+## Installation
+
+```sh
+npm install @chipmobilesdk/rn-notification
+npm install react-native-notify-kit react-native-mmkv react-native-localize
+cd ios && pod install
+```
+
+### Peer dependencies
+
+| Package | Required | Purpose |
+|---|---|---|
+| `react` >= 19, `react-native` >= 0.85 | yes | Host framework |
+| `react-native-notify-kit` >= 10.5.0 | yes | Local notification engine |
+| `react-native-mmkv` >= 4.0.0 | yes | Bounded persisted state |
+| `react-native-localize` >= 3.7.0 | yes | Platform time zone for re-anchoring |
+| `@react-native-firebase/app` >= 26.0.0 | **optional** | Push only — required *by* messaging |
+| `@react-native-firebase/messaging` >= 26.0.0 | **optional** | Push only |
+
+### Enabling push (optional)
+
+> ⚠️ **Install both Firebase packages, and add the config files.** `@react-native-firebase/messaging` will not build without `@react-native-firebase/app`, and `app` will not build without a Firebase config file. Installing messaging alone fails the Android build at configure time with `Could not find the react-native-firebase/app package`.
+
+```sh
+npm install @react-native-firebase/app @react-native-firebase/messaging
+cd ios && pod install
+```
+
+Then add the config files **before building** — they are not optional:
+
+- Android → `android/app/google-services.json`, plus the `com.google.gms:google-services` plugin
+- iOS → `ios/<App>/GoogleService-Info.plist`
+
+**If you are not enabling push, install none of this.** The package's push code lives behind the `/push` subpath and is never imported by the default entrypoint, so a local-only app ships zero provider code, zero push permissions, and zero entitlements — and takes on none of the provider's data-collection declarations.
+
+> **On the engine.** The original design named Notifee. Its repository was archived on 2026-04-07 with its last release in December 2024, so this package uses `react-native-notify-kit` — the maintained, 100%-API-compatible fork Invertase itself points to. The engine sits behind `NotificationEngineAdapter`; nothing consumer-facing depends on which one is in use.
+
+## Native setup
+
+### iOS
+
+Notification authorization needs **no `Info.plist` usage string**. Push additionally requires:
+
+- the `aps-environment` entitlement
+- the `remote-notification` background mode
+
+### Android
+
+| Permission | When | Notes |
+|---|---|---|
+| `POST_NOTIFICATIONS` | API 33+ | Runtime; requested only when you call for it |
+| `RECEIVE_BOOT_COMPLETED` | always | Restores scheduled notifications after a restart |
+| `SCHEDULE_EXACT_ALARM` | **opt-in** | You add it; requires a Play Console declaration |
+
+**Never use `USE_EXACT_ALARM` unless your app *is* an alarm clock, timer, or calendar.** Google Play restricts it and will disallow publishing for apps that do not qualify.
+
+#### ⚠️ You must actively *remove* `SCHEDULE_EXACT_ALARM` if you do not need it
+
+This package declares no exact-alarm permission — but **the notification engine does**, unconditionally, in its own manifest. Android's manifest merger is transitive, so it lands in your merged manifest whether you asked for it or not. Verified on a real build: `SCHEDULE_EXACT_ALARM` appears in the installed package even when nothing opts in.
+
+`SCHEDULE_EXACT_ALARM` requires a **Play Console Restricted Permissions declaration**. If your app does not need precise timing, strip it:
+
+```xml
+<!-- android/app/src/main/AndroidManifest.xml -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          xmlns:tools="http://schemas.android.com/tools">
+
+    <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"
+                     tools:node="remove" />
+```
+
+Without exact alarms, notifications are still scheduled — in approximate mode, with `mayBeDelayed: true` on the result. Nothing breaks.
+
+**Verify after building**, because a merged manifest is the only thing that tells the truth:
+
+```sh
+adb shell dumpsys package <your.package.id> | grep -E "android\.permission\.(SCHEDULE|USE)_EXACT_ALARM"
+# no output = correctly removed
+```
+
+> Match on `android.permission.` specifically. A loose `grep -i EXACT_ALARM` also hits
+> `android.app.action.SCHEDULE_EXACT_ALARM_PERMISSION_STATE_CHANGED` — a broadcast the
+> engine legitimately listens for, not a permission — and reports a false failure.
+
+The engine also contributes `WAKE_LOCK`, `VIBRATE`, `FOREGROUND_SERVICE`, `INTERNET`, and `ACCESS_NETWORK_STATE`. None is store-restricted, but review them against your own privacy declarations — and remove any you can prove unnecessary using the same `tools:node="remove"` mechanism.
+
+### Backup exclusion
+
+State lives under `Library/Caches` on iOS (backup-excluded by platform design). On Android, add to your `data_extraction_rules.xml` and `full_backup_content`:
+
+```xml
+<exclude domain="file" path="mmkv/chipmobilesdk.notification" />
+```
+
+## Choosing identifiers
+
+Identifiers are **yours**. The package never generates one, because only you can derive a reproducible identifier from your own data.
+
+```ts
+const id = `task:${task.id}:reminder:${index}`;   // ✅ derived, reproducible
+const id = crypto.randomUUID();                    // ❌ you can never replace it
+```
+
+**Charset**: `A–Z a–z 0–9` and `. _ - : /`, at most 128 characters. Whitespace and control characters are rejected.
+
+**Nothing is normalized.** `Task:1` and `task:1` are different identifiers. That is deliberate — silently folding them would hide a bug — but it is also how you accidentally create two notifications for one subject. Derive identifiers from a single canonical source.
+
+Owner tags and group tags follow the same rule.
+
+## Choosing an anchoring mode
+
+```ts
+moment: { at }                            // wall-clock (default)
+moment: { at, anchoring: 'absolute' }     // fixed instant worldwide
+```
+
+**Wall-clock** means the local clock time you named. An 08:00 reminder stays 08:00 after your user flies to Tokyo. This is the default because reminders are wall-clock things.
+
+**Absolute** means one instant everywhere — a match kickoff, a market open.
+
+### What re-anchoring cannot fix
+
+The package re-anchors wall-clock notifications when it notices the device zone changed. It notices during maintenance, which runs while the app is running.
+
+**If a wall-clock notification's moment arrives while the app has not run since the zone changed, it fires at the previously anchored instant.** This is stated rather than hidden: every pending entry carries an `anchoringGeneration`, so you can detect and explain the condition instead of being told nothing happened.
+
+## Maintenance versus reconciliation
+
+| The package does automatically | You call explicitly |
+|---|---|
+| Lookahead window refresh | `reconcile()` — the desired set |
+| Recurrence expansion | |
+| Wall-clock re-anchoring | |
+| Pending-set verification (reports only) | |
+| Permission re-read | |
+
+**Reconciliation never runs on its own.** Only you know what your data implies; a package that guessed would cancel notifications it does not understand.
+
+**Automatic maintenance is strictly additive.** It may act only on recurrence series the package owns, and can *never* cancel a notification you scheduled directly. That rule is enforced in code (`MaintenanceScopeViolation`), not merely documented.
+
+Call `reconcile()` after: mutating data that implies notifications, sign-in, sign-out, display permission becoming granted, **a device restart**, and app start.
+
+## Reconciliation
+
+```ts
+const result = await reconciler.reconcile({ domain: 'tasks', desired });
+// result.operationCount === 0 on an unchanged second pass
+```
+
+- **Idempotent** — a second consecutive pass with unchanged input performs **zero** platform operations.
+- **Domain-scoped** — never cancels outside `domain`, including notifications from other libraries.
+- **Duplicates**: every copy of a repeated identifier is rejected; anything already scheduled under it is **left in place**. A rejection is not a cancellation.
+- **Truncation**: over the platform ceiling, the furthest-out entries are dropped and *reported*. They return as nearer ones deliver.
+
+## Recurrence
+
+```ts
+await recurrence.registerSeries({
+  id: 'series:medication',
+  pattern: { kind: 'daily', hour: 8, minute: 0 },
+  end: { kind: 'unbounded' },
+  template: { content: { title: 'Medication', body: 'Time for your dose' }, tone: 'reminder' },
+});
+```
+
+Default window: **60 days or 32 occurrences per series**, whichever comes first. Bounded by both because either alone fails — a duration alone lets a frequent series exhaust the platform ceiling; a count alone leaves an annual series scheduled a decade out.
+
+Months lacking the requested day are **skipped, not clamped**: day 31 means day 31.
+
+## Permissions
+
+```ts
+const report = await permissions.getPermissions();          // never prompts
+await permissions.requestDisplayPermission();               // independent
+await permissions.requestExactAlarmPermission();            // independent
+await permissions.openSettings('display');                  // per-permission
+```
+
+Six states, never collapsed: `notAsked`, `granted`, `denied`, `permanentlyDenied`, `provisional`, `notRequired`.
+
+**Ask after intent, never on first launch.** A prompt at the wrong moment is a permanent denial.
+
+**A refusal never fails your operation.** The user's work completes; the lost capability is reported separately.
+
+## Interaction
+
+```ts
+notifications.onInteraction(async event => {
+  if (event.kind === 'tap') navigate(event.routing);
+});
+```
+
+One handler, identical shape in foreground, background, and cold start. Events that arrive before your handler registers are **buffered durably** — they survive process death, which is exactly what a cold-start tap is.
+
+When the target is gone, call `reportTargetMissing()` and pick your own fallback. No platform error is ever shown to the user.
+
+## Push
+
+```ts
+import { createPushGate } from '@chipmobilesdk/rn-notification/push';
+```
+
+Kept on its own subpath so an app that never imports it ships **zero** provider code, permissions, or entitlements.
+
+Foreground pushes are **never auto-displayed** — presentation is your decision.
+
+### The payload contract (for backend teams)
+
+```jsonc
+{ "v": 1, "kind": "display", "id": "task:1234:due",
+  "content": { "title": "…", "body": "…" }, "tone": "reminder",
+  "routing": { "screen": "task" }, "dedupId": "evt-9f2c" }
+```
+
+`kind`: `display` | `data` | `schedule` | `cancel`.
+
+**Append-only discipline — binding, not advisory.** An unrecognized version is processed **best-effort**: known fields honoured, unknown fields ignored. That is safe *only* while a released field's meaning is never repurposed.
+
+> ⚠️ **Changing what a released field means will be silently misprocessed by every installed app running an older contract version.** Express a semantic change as a **new field**, never a changed one. Adding a field is additive and never breaking.
+
+Local schedules take precedence over push for the same identifier. A server that wants to override sends `cancel` then `schedule`.
+
+## What is persisted
+
+Six collections, in app-private, backup-excluded storage:
+
+| Collection | Cap | Retention |
+|---|---|---|
+| Deduplication ledger | 500 | 24 hours |
+| Interaction buffer | 50 | 7 days |
+| Migration ledger | 20 | — |
+| Series ledger | 32 | — |
+| Permission history | 64 | — |
+| Last reconcile summary | 1 | — |
+
+**No notification content, no push token, no desired set.** The interaction buffer is the sole content-bearing exception, and it evicts on delivery.
+
+Corrupt state is **discarded and rebuilt**, never blocking. What you lose: deduplication history and buffered interactions. What is unaffected: **every notification already scheduled with the OS**.
+
+## Testing without a device
+
+```ts
+import { createFakeEngine, createFakeProvider, runConformanceSuite } from '@chipmobilesdk/rn-notification/testing';
+```
+
+The fakes simulate virtual time, time-zone travel, process death, boot-restoration gaps, redelivery, and platform truncation — so every decision path is provable with no device, no emulator, and no live provider.
+
+## Budgets
+
+| Item | Limit |
+|---|---|
+| Identifier | 128 characters (hard) |
+| Routing payload | 4 KB (hard) |
+| Content | 512 / 3072 / 512 bytes, 3584 total (hard) |
+| Actions per notification | 10 |
+| iOS pending notifications | 64 (platform) |
+| Desired set per pass | 500 (soft) |
+| Recurrence series | 32 |
+
+Delivery accuracy: within **60 s** with exact alarms; within **15 min** without, on a device under no manufacturer restriction. Under aggressive vendor battery management this bound does **not** hold, and the package reports the restriction where it can detect it.
+
+## Data behaviour (for your privacy declarations)
+
+- **Local-only adoption changes no privacy declaration.** State is app-private, backup-excluded, capped, time-evicted, and never transmitted. The package opens **no** network connection.
+- **Enabling push does change it.** The registration token is a device-scoped identifier your app sends to your server, and Firebase Cloud Messaging collects device data — both require declaration in Apple App Privacy and Google Play Data safety.
+- Disable analytics collection so adoption cannot create an ATT-relevant posture:
+  `firebase_analytics_collection_enabled=false`, `google_analytics_adid_collection_enabled=false`.
+- **Notification content appears on a locked screen.** Keep anything sensitive out of the body and put it in the structured routing payload instead.
+- User-generated content delivered through notifications remains **your** moderation obligation.
+- Do not use notification content to route around store billing.
+
+## Compatibility
+
+| Item | Supported |
+|---|---|
+| React | >= 19 |
+| React Native | >= 0.85 |
+| iOS | >= 15.1 |
+| Android | `minSdkVersion` 24, `targetSdkVersion` 36 |
+| Node | >= 22.11.0 |
+
+## Diagnostic identifiers
+
+39 stable identifiers across validation, reconciliation, permissions, channels, interaction, push, state, and volume. Every one is reachable through the fault injector. See `ALL_DIAGNOSTIC_CODES`.
+
+Some are **reported outcomes, not failures** — the operation succeeded and something you should know happened alongside it: `TRUNCATED_OVER_CEILING`, `EXACT_ALARM_UNAVAILABLE`, `TARGET_MISSING`, `PENDING_SET_DISCREPANCY`, `BURST_THRESHOLD_EXCEEDED`, `PAYLOAD_VERSION_SKEW`, `PAYLOAD_DUPLICATE`, `STATE_CAP_EVICTED`, `STATE_CORRUPT_REBUILT`. Use `isNonFailure(code)`.
+
+## License
+
+UNLICENSED — internal ChipMobileSdk package.

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "@chipmobilesdk/rn-notification",
+	"version": "0.1.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./push": {
+			"types": "./src/push/index.ts",
+			"react-native": "./src/push/index.ts",
+			"default": "./src/push/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/initialize.ts",
+		"src/channel",
+		"src/contract",
+		"src/diagnostics",
+		"src/engine",
+		"src/interaction",
+		"src/maintenance",
+		"src/permission",
+		"src/push",
+		"src/recurrence",
+		"src/reconcile",
+		"src/schedule",
+		"src/state",
+		"src/testing",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"@react-native-firebase/app": ">=26.0.0",
+		"@react-native-firebase/messaging": ">=26.0.0",
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-localize": ">=3.7.0",
+		"react-native-mmkv": ">=4.0.0",
+		"react-native-notify-kit": ">=10.5.0"
+	},
+	"peerDependenciesMeta": {
+		"@react-native-firebase/app": {
+			"optional": true
+		},
+		"@react-native-firebase/messaging": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/src/channel/migrate.ts

@@ -0,0 +1,211 @@
+/**
+ * Channel declaration and migration.
+ *
+ * Android channels are immutable once created: declaring a channel whose id
+ * already exists silently keeps the original configuration. That single fact is
+ * why changing a tone is a **migration** rather than an assignment, and why
+ * this package keeps its own ledger — the platform will not tell you which
+ * version of a channel a device already holds.
+ *
+ * Migration creates the new channel, re-homes notifications still pointing at
+ * the old one, and only then retires it. That order matters: retiring first
+ * would leave live notifications attached to a channel that no longer exists.
+ */
+
+import type {
+	ChannelApplyResult,
+	ChannelGroup,
+	ToneDeclaration,
+} from '../contract/channel';
+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';
+
+export interface ChannelDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly now: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+function ledgerFor(state: StateManager, toneId: string): MigrationEntry | undefined {
+	return state.read().migrationLedger.find(entry => entry.toneId === toneId && !entry.retired);
+}
+
+function recordApplied(
+	state: StateManager,
+	tone: ToneDeclaration,
+	now: number,
+	retiredChannelId?: string,
+): void {
+	state.update('migrationLedger', current => {
+		const withoutTone = current.filter(entry => entry.toneId !== tone.id);
+		const retired =
+			retiredChannelId === undefined
+				? []
+				: [
+						{
+							at: now,
+							toneId: tone.id,
+							appliedVersion: 0,
+							channelId: retiredChannelId,
+							retired: true,
+						},
+					];
+
+		return [
+			...withoutTone,
+			...retired,
+			{
+				at: now,
+				toneId: tone.id,
+				appliedVersion: tone.version,
+				channelId: channelIdFor(tone.id, tone.version),
+				retired: false,
+			},
+		];
+	});
+}
+
+export function createChannels(deps: ChannelDependencies) {
+	const emit = deps.emit ?? (() => {});
+
+	return {
+		/**
+		 * Applies a tone configuration, migrating any tone whose version moved.
+		 *
+		 * Applying an unchanged configuration performs no work at all: no channel
+		 * is recreated and no migration is triggered.
+		 */
+		async apply(
+			tones: readonly ToneDeclaration[],
+			groups: readonly ChannelGroup[] = [],
+		): Promise<ChannelApplyResult> {
+			const now = deps.now();
+
+			const created: string[] = [];
+			const migrated: { toneId: string; from: number; to: number }[] = [];
+			const retired: string[] = [];
+			const reHomed: string[] = [];
+			const cancelled: string[] = [];
+			const bypassUnavailable: string[] = [];
+			const unchanged: string[] = [];
+
+			if (groups.length > 0) {
+				await deps.engine.declareGroups(groups);
+			}
+
+			const capabilities = await deps.engine.getCapabilities();
+
+			for (const tone of tones) {
+				const previous = ledgerFor(deps.state, tone.id);
+				const resolved = resolveTone(tone);
+
+				if (previous !== undefined && previous.appliedVersion === tone.version) {
+					unchanged.push(tone.id);
+					continue;
+				}
+
+				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.
+					bypassUnavailable.push(tone.id);
+					emit(
+						DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
+						`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
+						{ toneId: tone.id },
+					);
+				}
+
+				const didCreate = await deps.engine.declareTone(resolved);
+				if (didCreate) {
+					created.push(resolved.android.channelId);
+				}
+
+				if (previous === undefined) {
+					recordApplied(deps.state, tone, now);
+					continue;
+				}
+
+				// A version moved, so this is a migration rather than a first
+				// declaration. Re-home before retiring: the reverse order would leave
+				// live notifications attached to a channel that no longer exists.
+				emit(
+					DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
+					`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
+					{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
+				);
+
+				const pending = await deps.engine.getPending();
+				const affected = pending.filter(entry => entry.tone === tone.id);
+
+				for (const entry of affected) {
+					await deps.engine.schedule({
+						request: {
+							id: entry.id,
+							content: entry.content,
+							tone: entry.tone,
+							moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
+							routing: entry.routing,
+							actions: entry.actions,
+							ownerTag: entry.ownerTag,
+							groupTag: entry.groupTag,
+						},
+						resolvedAt: entry.resolvedAt,
+						tone: resolved,
+						// Re-homing changes the channel, not the anchoring — preserve it.
+						anchoringGeneration: entry.anchoringGeneration,
+						approximate: entry.mayBeDelayed,
+						seriesId: entry.seriesId,
+						pushCreated: entry.pushCreated,
+					});
+					reHomed.push(entry.id);
+				}
+
+				const didRetire = await deps.engine.retireTone(previous.channelId);
+				if (didRetire) {
+					retired.push(previous.channelId);
+				}
+
+				migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
+				recordApplied(deps.state, tone, now, previous.channelId);
+			}
+
+			// Anything left on a retired channel would be an orphan — a notification
+			// the user can no longer control from system settings.
+			const orphans = await findOrphans(deps, tones);
+			if (orphans.length > 0) {
+				await deps.engine.cancelMany(orphans);
+				cancelled.push(...orphans);
+				emit(
+					DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
+					`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
+					{ count: orphans.length },
+				);
+			}
+
+			return { created, migrated, retired, reHomed, cancelled, bypassUnavailable, unchanged };
+		},
+
+		/** Which version of each tone this device actually holds. */
+		appliedVersions(): readonly { readonly toneId: string; readonly appliedVersion: number }[] {
+			return deps.state
+				.read()
+				.migrationLedger.filter(entry => !entry.retired)
+				.map(entry => ({ toneId: entry.toneId, appliedVersion: entry.appliedVersion }));
+		},
+	};
+}
+
+/** Notifications whose tone is no longer declared at all. */
+async function findOrphans(
+	deps: ChannelDependencies,
+	tones: readonly ToneDeclaration[],
+): Promise<readonly string[]> {
+	const declared = new Set(tones.map(tone => tone.id));
+	const pending = await deps.engine.getPending();
+	return pending.filter(entry => !declared.has(entry.tone)).map(entry => entry.id);
+}
+
+export type Channels = ReturnType<typeof createChannels>;