@chipmobilesdk/rn-notification 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,109 +1,174 @@
-# 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).
-
-## [0.3.0] — 2026-10-13
-
-Documentation release: the agent skill now matches the code `0.2.1` shipped. **No code,
-API, storage or behaviour change** — upgrading from `0.2.1` changes nothing at runtime.
-Released as its own version so the skill a consuming app syncs (`packageVersion`) always
-matches the package it came from.
-
-### Changed
-
-- Skill, `## Debugging "it did not arrive"`: check the installed version first — before
-  `0.2.1` the state record never persisted on a device, so deduplication and cold-start
-  tap buffering lasted one session. Require `0.2.1` or later.
-
-## [0.2.1] — 2026-10-12
-
-Patch release. No consumer change required.
-
-### Fixed
-
-- **The state store never reached the device's storage.** It opened MMKV with
-  `new MMKV()`, the react-native-mmkv **v3** constructor. In v4 — the only major the peer
-  range (`>=4.0.0`) allows — `MMKV` is a type, not a value, so the call threw and the
-  package fell back to its memory store on every device. Deduplication and cold-start
-  buffering were therefore session-scoped — the documented degradation for a missing
-  native module, applied where the module was present. The store now uses v4's
-  `createMMKV` and `remove`.
-- The repository's test double exported a v3 `MMKV` class, so no test could see it. The
-  double now mirrors v4, and `mmkv-store.test.ts` fails against the old code.
-
-## [0.2.0]
-
-Additive minor, delivering on the reserved **additional tone attributes** commitment below. **No consumer source change, no configuration change, and no tone version bump is required.**
-
-### Added
-
-- **Alarm-capable tones.** `ToneDeclaration` gains `repeatAlert` — an alert sound that repeats until the user handles the notification — and `timeSensitive`, which asks the platform for its time-sensitive treatment. `repeatAlert` carries a **required** duration, so an unbounded repeating alert is unrepresentable rather than merely discouraged; the range is 1 to 60 minutes, exported as `REPEAT_ALERT_BOUNDS`.
-- **A repeating alert stops on its own, and the notification stays.** When the declared window elapses the sound ends and the notification remains in the tray. Handling it earlier stops the sound immediately. Both hold with the app process dead, which is where the expiry almost always falls.
-- **`registerBackgroundNotificationHandler`.** The one piece a consumer wires up themselves, at module scope in `index.js`. Required only by an app that declares a repeating tone; its absence is reported as `REPEAT_STOP_HANDLER_MISSING` rather than discovered as a phone that will not stop ringing.
-- **`ChannelApplyResult.labelsRefreshed`** and **`ChannelApplyResult.repeatUnavailable`**, so a caller can tell a label correction from a creation, a migration, and a no-op — and can see which attributes the platform refused.
-- Four diagnostic identifiers: `INVALID_TONE_REPEAT`, and the non-failures `TONE_LABELS_REFRESHED`, `REPEAT_ALERT_UNAVAILABLE`, `REPEAT_STOP_HANDLER_MISSING`. The stable set is now **43**.
-
-### Fixed
-
-- **Tone labels reach system settings.** `ToneDeclaration.name` was documented as the name shown in system settings and never reached one: `ResolvedTone` carried no label at all, so the adapter passed the tone *identifier* as the channel name. Users read `reminder` where a consumer had written a localized label. `description` shared the same fate.
-- **A tone label can be corrected after the first install.** Declaring a tone the device already held returned early, so a label could be set exactly once per device, forever. Android permits updating a channel's name and description in place — and ignores everything else, which is precisely what keeps the user's own importance, sound, and Do-Not-Disturb choices intact. Correcting a label now costs no version bump and no user setting.
-
-### Changed
-
-- **One-time label refresh on upgrade.** The first `apply()` after upgrading performs a single label-refresh write per existing tone, because every channel on every existing device currently carries the tone id as its name. Every apply after that is zero-operation again, as before. Nothing is recreated, retired, re-homed, or cancelled.
-- **`NotificationEngineAdapter` gained members** (*Experimental* per the stability table below): `declareTone` now returns `'created' | 'labelsRefreshed' | 'unchanged'` instead of a boolean, `EngineCapabilities` gained `supportsRepeatingAlert`, and the port gained `silenceDelivered`, `listRepeatStops`, `subscribeToDeliveries`, `registerBackgroundDeliveryHandler`, and `hasBackgroundDeliveryHandler`. Only an app supplying its own engine is affected.
-- **`cms.stop:` is now a reserved identifier prefix.** Repeat expiry cancels its markers by identifier, so a consumer identifier that looked like one would be deleted out from under a real notification.
-
-### Platform limits — stated rather than papered over
-
-- **iOS does not repeat an alert sound.** There is no looping API, and the one interruption level that overrides the mute switch requires an entitlement Apple grants by application — which this package does not hold and does not request. A repeating alert on iOS is reported in `repeatUnavailable`; the notification still delivers and still sounds once.
-- **iOS `timeSensitive` needs the consuming app's own Time Sensitive Notifications capability.** Without it iOS delivers at `active`. This was already true for `urgency: 'max'` in 0.1.x and was previously undocumented.
-- **The declared window is a floor, not a precise stop.** The entry that ends the alert is scheduled like any other notification and inherits the same delivery accuracy — within 60 s with exact alarms, up to 15 minutes without. Measured on an emulator without `SCHEDULE_EXACT_ALARM`: a declared 2-minute window ran 2m35s and 3m00s.
-- **Android alarm audio uses the notification volume, not the alarm volume.** A device with notifications muted stays silent. Not fixable without native changes.
-- **Android also stops an insistent sound when the user opens the notification shade** — platform behaviour, and arguably the right one.
-- **The stop marker is briefly visible in the tray** before it is removed, on a minimum-importance, silent channel. A scheduled notification is the only OS-driven execution the engine offers.
-- **Without the registered background handler, a repeating alert does not stop while the app is dead.**
-- **Aggressive vendor battery management can delay marker delivery**, in the same way and for the same reasons the package already reports `mayBeDelayed` and `unknown`.
-
-### Migration
-
-None required. Every addition is optional, `repeatAlert` and `timeSensitive` are realized per notification rather than as channel configuration, and labels are updated in place — so no tone version moves and no channel is recreated. Only an app that declares a repeating tone needs the new setup step in `index.js`.
-
-## [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~~ *(delivered in 0.2.0)*, additional diagnostic identifiers, a consumer-supplied storage port, and in-app notification presentation.
+# @chipmobilesdk/rn-notification
+
+## 0.4.1
+
+### Patch Changes
+
+- Packaging only; no code change. The package no longer declares `engines.node`: a
+  React Native package does not run on Node, so the field only produced install
+  warnings in apps on another Node version. rn-i18n's command-line tooling does run
+  on Node; its README's compatibility table states the version it needs. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
+
+## [0.4.0] — 2026-11-01
+
+Fixes two defects that delivered the wrong number of notifications, plus the
+maintenance and write-path gaps behind them. **One breaking change**: occurrence
+identifiers changed format (see Changed). Existing series migrate on their next
+refresh with no app action.
+
+### Fixed
+
+- **A count-limited series delivers exactly its count.** Every window refresh added
+  the still-pending occurrences to the emitted count again, so a series with
+  `count` larger than `occurrencesPerSeries` ended after roughly half its
+  occurrences. The ledger now records the last emitted occurrence and counts each
+  occurrence once.
+- **A time-zone change no longer duplicates occurrences.** Re-anchoring kept an
+  occurrence's identifier while the next window refresh derived a new one from the
+  new instant, so the same slot was scheduled twice. Identifiers now come from the
+  calendar slot and do not change with the zone.
+- **Every write keeps its stop marker in step.** Recurrence, re-anchoring and channel
+  re-homing wrote straight to the engine, so a repeating alarm in a series never got
+  a stop marker and a re-anchored one stopped at the old instant. All write paths now
+  go through one internal `ScheduleWriter`. Recurrence also respects the platform
+  ceiling, and `registerSeries` validates its template as a direct schedule would —
+  an undeclared tone throws `NotificationError(UNDECLARED_TONE)`, not a plain `Error`.
+- **Reconcile is idempotent on a device for notifications with actions.** The real
+  engine never read `actions` back, so every pass replaced them; the fake stored
+  requests verbatim and hid it. Actions now round-trip through the data bag, and the
+  fake goes through the same codec as the real engine.
+- **Automatic maintenance runs.** `initialize()` now applies `config.tones` (and any
+  channel migration) and runs the steps registered on `runtime.registry` when the app
+  returns to the foreground, triggered as `timeZoneChange` when the zone moved.
+  Ownership is decided per pending occurrence, so a legitimate cancel is no longer
+  reported as a `MaintenanceScopeViolation`. `durationMs` is measured.
+- **A maintenance call that overlaps a running cycle waits for it.** It used to
+  return an empty result at once. With the automatic foreground cycle above, an app
+  that runs maintenance and then reconciles on the same foreground event got that
+  empty result and reconciled while the window refresh was still writing, so a
+  reminder the reconcile cancelled could be scheduled again. Overlapping calls now
+  join the running cycle and receive its result; the work still runs once.
+
+### Changed
+
+- **Breaking:** occurrence identifiers are `<seriesId>#YYYYMMDDTHHmm` instead of
+  `<seriesId>#<epoch ms>`, and `occurrenceId(seriesId, slot)` takes wall-clock parts
+  or a slot key instead of an instant. Occurrences already on a device under the old
+  format are cancelled and rescheduled on the series' next refresh. A count-limited
+  series registered under 0.3 keeps the count it had recorded, which may be too high.
+- `InitializeResult.tonesApplied` and `migrationsRun` report real values instead of `0`.
+
+### Added
+
+- `NotificationRuntime.channels`, `lastAutomaticMaintenance()` and `dispose()`.
+- `RuntimeDependencies.appState` and `timeZone`, for tests.
+- `SeriesResult.cancelled`; the window-refresh step reports those identifiers to the
+  scope guard.
+- Diagnostic code `MAINTENANCE_FAILED`.
+
+## [0.3.0] — 2026-10-13
+
+Documentation release: the agent skill now matches the code `0.2.1` shipped. **No code,
+API, storage or behaviour change** — upgrading from `0.2.1` changes nothing at runtime.
+Released as its own version so the skill a consuming app syncs (`packageVersion`) always
+matches the package it came from.
+
+### Changed
+
+- Skill, `## Debugging "it did not arrive"`: check the installed version first — before
+  `0.2.1` the state record never persisted on a device, so deduplication and cold-start
+  tap buffering lasted one session. Require `0.2.1` or later.
+
+## [0.2.1] — 2026-10-12
+
+Patch release. No consumer change required.
+
+### Fixed
+
+- **The state store never reached the device's storage.** It opened MMKV with
+  `new MMKV()`, the react-native-mmkv **v3** constructor. In v4 — the only major the peer
+  range (`>=4.0.0`) allows — `MMKV` is a type, not a value, so the call threw and the
+  package fell back to its memory store on every device. Deduplication and cold-start
+  buffering were therefore session-scoped — the documented degradation for a missing
+  native module, applied where the module was present. The store now uses v4's
+  `createMMKV` and `remove`.
+- The repository's test double exported a v3 `MMKV` class, so no test could see it. The
+  double now mirrors v4, and `mmkv-store.test.ts` fails against the old code.
+
+## [0.2.0] — 2026-08-30
+
+Additive minor, delivering on the reserved **additional tone attributes** commitment below. **No consumer source change, no configuration change, and no tone version bump is required.**
+
+### Added
+
+- **Alarm-capable tones.** `ToneDeclaration` gains `repeatAlert` — an alert sound that repeats until the user handles the notification — and `timeSensitive`, which asks the platform for its time-sensitive treatment. `repeatAlert` carries a **required** duration, so an unbounded repeating alert is unrepresentable rather than merely discouraged; the range is 1 to 60 minutes, exported as `REPEAT_ALERT_BOUNDS`.
+- **A repeating alert stops on its own, and the notification stays.** When the declared window elapses the sound ends and the notification remains in the tray. Handling it earlier stops the sound immediately. Both hold with the app process dead, which is where the expiry almost always falls.
+- **`registerBackgroundNotificationHandler`.** The one piece a consumer wires up themselves, at module scope in `index.js`. Required only by an app that declares a repeating tone; its absence is reported as `REPEAT_STOP_HANDLER_MISSING` rather than discovered as a phone that will not stop ringing.
+- **`ChannelApplyResult.labelsRefreshed`** and **`ChannelApplyResult.repeatUnavailable`**, so a caller can tell a label correction from a creation, a migration, and a no-op — and can see which attributes the platform refused.
+- Four diagnostic identifiers: `INVALID_TONE_REPEAT`, and the non-failures `TONE_LABELS_REFRESHED`, `REPEAT_ALERT_UNAVAILABLE`, `REPEAT_STOP_HANDLER_MISSING`. The stable set is now **43**.
+
+### Fixed
+
+- **Tone labels reach system settings.** `ToneDeclaration.name` was documented as the name shown in system settings and never reached one: `ResolvedTone` carried no label at all, so the adapter passed the tone *identifier* as the channel name. Users read `reminder` where a consumer had written a localized label. `description` shared the same fate.
+- **A tone label can be corrected after the first install.** Declaring a tone the device already held returned early, so a label could be set exactly once per device, forever. Android permits updating a channel's name and description in place — and ignores everything else, which is precisely what keeps the user's own importance, sound, and Do-Not-Disturb choices intact. Correcting a label now costs no version bump and no user setting.
+
+### Changed
+
+- **One-time label refresh on upgrade.** The first `apply()` after upgrading performs a single label-refresh write per existing tone, because every channel on every existing device currently carries the tone id as its name. Every apply after that is zero-operation again, as before. Nothing is recreated, retired, re-homed, or cancelled.
+- **`NotificationEngineAdapter` gained members** (*Experimental* per the stability table below): `declareTone` now returns `'created' | 'labelsRefreshed' | 'unchanged'` instead of a boolean, `EngineCapabilities` gained `supportsRepeatingAlert`, and the port gained `silenceDelivered`, `listRepeatStops`, `subscribeToDeliveries`, `registerBackgroundDeliveryHandler`, and `hasBackgroundDeliveryHandler`. Only an app supplying its own engine is affected.
+- **`cms.stop:` is now a reserved identifier prefix.** Repeat expiry cancels its markers by identifier, so a consumer identifier that looked like one would be deleted out from under a real notification.
+
+### Platform limits — stated rather than papered over
+
+- **iOS does not repeat an alert sound.** There is no looping API, and the one interruption level that overrides the mute switch requires an entitlement Apple grants by application — which this package does not hold and does not request. A repeating alert on iOS is reported in `repeatUnavailable`; the notification still delivers and still sounds once.
+- **iOS `timeSensitive` needs the consuming app's own Time Sensitive Notifications capability.** Without it iOS delivers at `active`. This was already true for `urgency: 'max'` in 0.1.x and was previously undocumented.
+- **The declared window is a floor, not a precise stop.** The entry that ends the alert is scheduled like any other notification and inherits the same delivery accuracy — within 60 s with exact alarms, up to 15 minutes without. Measured on an emulator without `SCHEDULE_EXACT_ALARM`: a declared 2-minute window ran 2m35s and 3m00s.
+- **Android alarm audio uses the notification volume, not the alarm volume.** A device with notifications muted stays silent. Not fixable without native changes.
+- **Android also stops an insistent sound when the user opens the notification shade** — platform behaviour, and arguably the right one.
+- **The stop marker is briefly visible in the tray** before it is removed, on a minimum-importance, silent channel. A scheduled notification is the only OS-driven execution the engine offers.
+- **Without the registered background handler, a repeating alert does not stop while the app is dead.**
+- **Aggressive vendor battery management can delay marker delivery**, in the same way and for the same reasons the package already reports `mayBeDelayed` and `unknown`.
+
+### Migration
+
+None required. Every addition is optional, `repeatAlert` and `timeSensitive` are realized per notification rather than as channel configuration, and labels are updated in place — so no tone version moves and no channel is recreated. Only an app that declares a repeating tone needs the new setup step in `index.js`.
+
+## [0.1.2] — 2026-08-29
+
+The first release. 0.1.0 and 0.1.1 (2026-08-17) were published from the feature
+branch before it merged; 0.1.2 is the merged release of the same work.
+
+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~~ *(delivered in 0.2.0)*, additional diagnostic identifiers, a consumer-supplied storage port, and in-app notification presentation.