@chipmobilesdk/rn-notification 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.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.**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

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

@@ -3,7 +3,7 @@ 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, 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.2.0"
+  packageVersion: "0.2.1"
 user-invocable: true
 disable-model-invocation: false
 ---

package/src/channel/validate-tone.ts

@@ -1,61 +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);
-	}
-}
+/**
+ * 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);
+	}
+}

package/src/repeat/expiry.ts

@@ -1,55 +1,55 @@
-/**
- * Repeat expiry.
- *
- * When a stop marker is delivered, the alert it guards has run its declared
- * course. This handler ends the sound and leaves the notification exactly where
- * it is, then removes the marker.
- *
- * Nothing here imports the engine. It talks to the port, which is what lets the
- * whole mechanism be proven on a virtual clock with no device.
- */
-
-import type { DeliveryEvent, NotificationEngineAdapter } from '../engine/adapter';
-
-export interface RepeatExpiryDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export interface RepeatExpiryHandler {
-	/** Reacts to one delivery. Ignores anything that is not a stop marker. */
-	handle(event: DeliveryEvent): Promise<void>;
-	/** Removes the marker guarding a target, when the target is cancelled or replaced. */
-	release(targetId: string): Promise<void>;
-}
-
-export function createRepeatExpiryHandler(
-	deps: RepeatExpiryDependencies,
-): RepeatExpiryHandler {
-	return {
-		async handle(event: DeliveryEvent): Promise<void> {
-			const stop = event.repeatStop;
-			if (stop === undefined) return;
-
-			// Order matters. Silence first, remove the marker second: if the
-			// process dies between the two, a marker left behind is harmless
-			// noise, whereas a device left sounding is the failure this exists to
-			// prevent.
-			//
-			// `silenceDelivered` returning false is the ordinary case, not an
-			// error — it means the user already handled the notification. Checking
-			// the tray rather than racing to cancel the marker on interaction is
-			// what makes early handling correct by construction: even if the marker
-			// fires, there is nothing left to act on.
-			await deps.engine.silenceDelivered(stop.targetId);
-			await deps.engine.cancel(stop.markerId);
-		},
-
-		async release(targetId: string): Promise<void> {
-			const outstanding = await deps.engine.listRepeatStops();
-			const marker = outstanding.find(stop => stop.targetId === targetId);
-			if (marker === undefined) return;
-			await deps.engine.cancel(marker.markerId);
-		},
-	};
-}
+/**
+ * Repeat expiry.
+ *
+ * When a stop marker is delivered, the alert it guards has run its declared
+ * course. This handler ends the sound and leaves the notification exactly where
+ * it is, then removes the marker.
+ *
+ * Nothing here imports the engine. It talks to the port, which is what lets the
+ * whole mechanism be proven on a virtual clock with no device.
+ */
+
+import type { DeliveryEvent, NotificationEngineAdapter } from '../engine/adapter';
+
+export interface RepeatExpiryDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export interface RepeatExpiryHandler {
+	/** Reacts to one delivery. Ignores anything that is not a stop marker. */
+	handle(event: DeliveryEvent): Promise<void>;
+	/** Removes the marker guarding a target, when the target is cancelled or replaced. */
+	release(targetId: string): Promise<void>;
+}
+
+export function createRepeatExpiryHandler(
+	deps: RepeatExpiryDependencies,
+): RepeatExpiryHandler {
+	return {
+		async handle(event: DeliveryEvent): Promise<void> {
+			const stop = event.repeatStop;
+			if (stop === undefined) return;
+
+			// Order matters. Silence first, remove the marker second: if the
+			// process dies between the two, a marker left behind is harmless
+			// noise, whereas a device left sounding is the failure this exists to
+			// prevent.
+			//
+			// `silenceDelivered` returning false is the ordinary case, not an
+			// error — it means the user already handled the notification. Checking
+			// the tray rather than racing to cancel the marker on interaction is
+			// what makes early handling correct by construction: even if the marker
+			// fires, there is nothing left to act on.
+			await deps.engine.silenceDelivered(stop.targetId);
+			await deps.engine.cancel(stop.markerId);
+		},
+
+		async release(targetId: string): Promise<void> {
+			const outstanding = await deps.engine.listRepeatStops();
+			const marker = outstanding.find(stop => stop.targetId === targetId);
+			if (marker === undefined) return;
+			await deps.engine.cancel(marker.markerId);
+		},
+	};
+}

package/src/repeat/index.ts

@@ -1,54 +1,54 @@
-/**
- * Repeat expiry — bounding an alert that repeats until it is handled.
- *
- * The one piece of this package a consumer has to wire up themselves. The
- * engine registers its background task at module scope, outside the React tree,
- * and no library can perform that registration on an app's behalf.
- *
- * An app that declares no repeating tone needs none of this.
- */
-
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import { createRepeatExpiryHandler } from './expiry';
-
-export { createRepeatExpiryHandler } from './expiry';
-export type { RepeatExpiryHandler, RepeatExpiryDependencies } from './expiry';
-export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from './marker';
-
-export interface BackgroundHandlerRegistration {
-	readonly engine: NotificationEngineAdapter;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-/**
- * Registers the handler that ends a repeating alert while the app is dead.
- *
- * Call this at module scope in `index.js`, beside the app registration — not
- * inside a component, and not inside an effect. By the time a component mounts,
- * the process that needed this handler has already been asked to run it.
- *
- * Without it a repeating alert still starts and still stops when the user
- * handles it, but nothing ends it on a device left face-down on a table. That
- * is the whole reason the feature exists, so `apply()` reports its absence
- * rather than letting anyone find out the hard way.
- */
-export function registerBackgroundNotificationHandler(
-	registration: BackgroundHandlerRegistration,
-): void {
-	const handler = createRepeatExpiryHandler(registration);
-
-	registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event));
-
-	// Both paths, not just the background one. The engine routes a delivery to
-	// the foreground listener while the app is alive and to the headless task
-	// only when it is not — so registering only the latter leaves the alert
-	// sounding for anyone holding the phone when the window runs out, which is
-	// the one case they would certainly notice.
-	registration.engine.subscribeToDeliveries(event => {
-		// Deliberately not awaited: the engine's foreground listener is
-		// synchronous, and a rejection here must not take the subscription down
-		// with it — a handler that stopped listening would leave every later
-		// alarm unbounded.
-		handler.handle(event).catch(() => {});
-	});
-}
+/**
+ * Repeat expiry — bounding an alert that repeats until it is handled.
+ *
+ * The one piece of this package a consumer has to wire up themselves. The
+ * engine registers its background task at module scope, outside the React tree,
+ * and no library can perform that registration on an app's behalf.
+ *
+ * An app that declares no repeating tone needs none of this.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { createRepeatExpiryHandler } from './expiry';
+
+export { createRepeatExpiryHandler } from './expiry';
+export type { RepeatExpiryHandler, RepeatExpiryDependencies } from './expiry';
+export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from './marker';
+
+export interface BackgroundHandlerRegistration {
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+/**
+ * Registers the handler that ends a repeating alert while the app is dead.
+ *
+ * Call this at module scope in `index.js`, beside the app registration — not
+ * inside a component, and not inside an effect. By the time a component mounts,
+ * the process that needed this handler has already been asked to run it.
+ *
+ * Without it a repeating alert still starts and still stops when the user
+ * handles it, but nothing ends it on a device left face-down on a table. That
+ * is the whole reason the feature exists, so `apply()` reports its absence
+ * rather than letting anyone find out the hard way.
+ */
+export function registerBackgroundNotificationHandler(
+	registration: BackgroundHandlerRegistration,
+): void {
+	const handler = createRepeatExpiryHandler(registration);
+
+	registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event));
+
+	// Both paths, not just the background one. The engine routes a delivery to
+	// the foreground listener while the app is alive and to the headless task
+	// only when it is not — so registering only the latter leaves the alert
+	// sounding for anyone holding the phone when the window runs out, which is
+	// the one case they would certainly notice.
+	registration.engine.subscribeToDeliveries(event => {
+		// Deliberately not awaited: the engine's foreground listener is
+		// synchronous, and a rejection here must not take the subscription down
+		// with it — a handler that stopped listening would leave every later
+		// alarm unbounded.
+		handler.handle(event).catch(() => {});
+	});
+}

package/src/repeat/marker.ts

@@ -1,72 +1,72 @@
-/**
- * Stop-marker identity.
- *
- * A repeating alert has to end without the app being alive, and no platform
- * offers "stop the sound at time T but keep the notification". So the package
- * schedules its own notification at T and reacts to its delivery. That
- * notification is a *marker*: it exists to be delivered and immediately
- * removed, never to be read.
- *
- * The marker's identifier is derived from the target's by hashing rather than by
- * concatenation. Concatenation would overflow the package's 128-character
- * identifier limit for any target already near it, and would make the marker's
- * identity a function of a value the consumer controls — which is how a
- * consumer identifier ends up colliding with an internal one.
- */
-
-import type { RepeatStop } from '../engine/adapter';
-
-/**
- * Reserved identifier namespace.
- *
- * Rejected as a consumer identifier prefix. A consumer id colliding with a
- * marker would not merely confuse a listing: the expiry handler cancels
- * markers, so the collision would delete a real notification.
- */
-export const REPEAT_STOP_PREFIX = 'cms.stop:';
-
-/**
- * FNV-1a, 32-bit. Deterministic, dependency-free, and stable across releases.
- *
- * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
- * equivalents would not wrap to 32 bits, and a marker id that changed between
- * releases would orphan every marker already scheduled on a device.
- */
-/* eslint-disable no-bitwise */
-function fnv1a(value: string, basis: number): number {
-	let hash = basis;
-	for (let index = 0; index < value.length; index += 1) {
-		hash ^= value.codePointAt(index) ?? 0;
-		hash = Math.imul(hash, 0x01000193) >>> 0;
-	}
-	return hash >>> 0;
-}
-/* eslint-enable no-bitwise */
-
-function hex8(value: number): string {
-	return value.toString(16).padStart(8, '0');
-}
-
-/**
- * The marker identifier for a target notification.
- *
- * Two independent hashes rather than one: a single 32-bit hash collides often
- * enough to matter once a device holds a handful of alarms, and a collision here
- * means one alarm's marker silences the other alarm and never silences its own.
- */
-export function markerIdFor(targetId: string): string {
-	return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
-}
-
-export function isRepeatStopId(id: string): boolean {
-	return id.startsWith(REPEAT_STOP_PREFIX);
-}
-
-/** Describes the stop for a target whose alert must end at a known instant. */
-export function repeatStopFor(targetId: string, deliveredAt: number, forMs: number): RepeatStop {
-	return {
-		markerId: markerIdFor(targetId),
-		targetId,
-		dueAt: deliveredAt + forMs,
-	};
-}
+/**
+ * Stop-marker identity.
+ *
+ * A repeating alert has to end without the app being alive, and no platform
+ * offers "stop the sound at time T but keep the notification". So the package
+ * schedules its own notification at T and reacts to its delivery. That
+ * notification is a *marker*: it exists to be delivered and immediately
+ * removed, never to be read.
+ *
+ * The marker's identifier is derived from the target's by hashing rather than by
+ * concatenation. Concatenation would overflow the package's 128-character
+ * identifier limit for any target already near it, and would make the marker's
+ * identity a function of a value the consumer controls — which is how a
+ * consumer identifier ends up colliding with an internal one.
+ */
+
+import type { RepeatStop } from '../engine/adapter';
+
+/**
+ * Reserved identifier namespace.
+ *
+ * Rejected as a consumer identifier prefix. A consumer id colliding with a
+ * marker would not merely confuse a listing: the expiry handler cancels
+ * markers, so the collision would delete a real notification.
+ */
+export const REPEAT_STOP_PREFIX = 'cms.stop:';
+
+/**
+ * FNV-1a, 32-bit. Deterministic, dependency-free, and stable across releases.
+ *
+ * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
+ * equivalents would not wrap to 32 bits, and a marker id that changed between
+ * releases would orphan every marker already scheduled on a device.
+ */
+/* eslint-disable no-bitwise */
+function fnv1a(value: string, basis: number): number {
+	let hash = basis;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.codePointAt(index) ?? 0;
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash >>> 0;
+}
+/* eslint-enable no-bitwise */
+
+function hex8(value: number): string {
+	return value.toString(16).padStart(8, '0');
+}
+
+/**
+ * The marker identifier for a target notification.
+ *
+ * Two independent hashes rather than one: a single 32-bit hash collides often
+ * enough to matter once a device holds a handful of alarms, and a collision here
+ * means one alarm's marker silences the other alarm and never silences its own.
+ */
+export function markerIdFor(targetId: string): string {
+	return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
+}
+
+export function isRepeatStopId(id: string): boolean {
+	return id.startsWith(REPEAT_STOP_PREFIX);
+}
+
+/** Describes the stop for a target whose alert must end at a known instant. */
+export function repeatStopFor(targetId: string, deliveredAt: number, forMs: number): RepeatStop {
+	return {
+		markerId: markerIdFor(targetId),
+		targetId,
+		dueAt: deliveredAt + forMs,
+	};
+}

package/src/repeat/place.ts

@@ -1,73 +1,73 @@
-/**
- * Keeping a notification's stop marker in step with the notification.
- *
- * Shared by the scheduler and the reconciler rather than written twice. They are
- * two doors into the same act — reconciliation is how most consumers schedule —
- * and a bound that only existed on one path would be a bound that mostly did not
- * exist.
- */
-
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { ResolvedTone } from '../contract/channel';
-import { repeatStopFor } from './marker';
-
-export interface StopPlacement {
-	/**
-	 * Places the marker for a repeating notification, replacing any it already
-	 * had.
-	 *
-	 * Called on every schedule, replacements included: re-scheduling under an
-	 * identifier that already had one must leave exactly one entry and exactly
-	 * one marker, and the old marker's instant is no longer the right one.
-	 *
-	 * Nothing is placed when the tone does not repeat or the platform will not
-	 * honour repetition, so a non-repeating notification costs no extra platform
-	 * capacity at all.
-	 */
-	sync(targetId: string, tone: ResolvedTone, deliversAt: number): Promise<void>;
-	/** Drops any marker still guarding an identifier. */
-	release(targetId: string): Promise<void>;
-}
-
-export function createStopPlacement(engine: NotificationEngineAdapter): StopPlacement {
-	const release = async (targetId: string): Promise<void> => {
-		const outstanding = await engine.listRepeatStops();
-		const held = outstanding.find(stop => stop.targetId === targetId);
-		if (held !== undefined) {
-			await engine.cancel(held.markerId);
-		}
-	};
-
-	return {
-		release,
-
-		async sync(targetId, tone, deliversAt) {
-			await release(targetId);
-
-			const forMs = tone.android.repeatForMs;
-			if (!tone.android.loopSound || forMs === undefined) return;
-
-			const capabilities = await engine.getCapabilities();
-			if (!capabilities.supportsRepeatingAlert) return;
-
-			const stop = repeatStopFor(targetId, deliversAt, forMs);
-			await engine.schedule({
-				request: {
-					id: stop.markerId,
-					// Deliberately empty. A marker is delivered and removed within the
-					// same handler invocation; anything readable here would be text a
-					// user might glimpse and be confused by.
-					content: { title: '', body: '' },
-					tone: tone.toneId,
-					// Absolute: the bound is a duration from a known instant, not a
-					// wall-clock time that should follow the user across time zones.
-					moment: { at: stop.dueAt, anchoring: 'absolute' },
-				},
-				resolvedAt: stop.dueAt,
-				tone,
-				approximate: false,
-				repeatStop: stop,
-			});
-		},
-	};
-}
+/**
+ * Keeping a notification's stop marker in step with the notification.
+ *
+ * Shared by the scheduler and the reconciler rather than written twice. They are
+ * two doors into the same act — reconciliation is how most consumers schedule —
+ * and a bound that only existed on one path would be a bound that mostly did not
+ * exist.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { ResolvedTone } from '../contract/channel';
+import { repeatStopFor } from './marker';
+
+export interface StopPlacement {
+	/**
+	 * Places the marker for a repeating notification, replacing any it already
+	 * had.
+	 *
+	 * Called on every schedule, replacements included: re-scheduling under an
+	 * identifier that already had one must leave exactly one entry and exactly
+	 * one marker, and the old marker's instant is no longer the right one.
+	 *
+	 * Nothing is placed when the tone does not repeat or the platform will not
+	 * honour repetition, so a non-repeating notification costs no extra platform
+	 * capacity at all.
+	 */
+	sync(targetId: string, tone: ResolvedTone, deliversAt: number): Promise<void>;
+	/** Drops any marker still guarding an identifier. */
+	release(targetId: string): Promise<void>;
+}
+
+export function createStopPlacement(engine: NotificationEngineAdapter): StopPlacement {
+	const release = async (targetId: string): Promise<void> => {
+		const outstanding = await engine.listRepeatStops();
+		const held = outstanding.find(stop => stop.targetId === targetId);
+		if (held !== undefined) {
+			await engine.cancel(held.markerId);
+		}
+	};
+
+	return {
+		release,
+
+		async sync(targetId, tone, deliversAt) {
+			await release(targetId);
+
+			const forMs = tone.android.repeatForMs;
+			if (!tone.android.loopSound || forMs === undefined) return;
+
+			const capabilities = await engine.getCapabilities();
+			if (!capabilities.supportsRepeatingAlert) return;
+
+			const stop = repeatStopFor(targetId, deliversAt, forMs);
+			await engine.schedule({
+				request: {
+					id: stop.markerId,
+					// Deliberately empty. A marker is delivered and removed within the
+					// same handler invocation; anything readable here would be text a
+					// user might glimpse and be confused by.
+					content: { title: '', body: '' },
+					tone: tone.toneId,
+					// Absolute: the bound is a duration from a known instant, not a
+					// wall-clock time that should follow the user across time zones.
+					moment: { at: stop.dueAt, anchoring: 'absolute' },
+				},
+				resolvedAt: stop.dueAt,
+				tone,
+				approximate: false,
+				repeatStop: stop,
+			});
+		},
+	};
+}

package/src/state/mmkv-store.ts

@@ -22,10 +22,11 @@ import { createMemoryStore } from './store';
 
 const INSTANCE_ID = 'chipmobilesdk.notification';
 
+/** The slice of a react-native-mmkv v4 instance this store uses (v4 names). */
 interface MmkvLike {
 	getString(key: string): string | undefined;
 	set(key: string, value: string): void;
-	delete(key: string): void;
+	remove(key: string): unknown;
 	clearAll(): void;
 	getAllKeys(): string[];
 }
@@ -42,11 +43,14 @@ export function createMmkvStore(): StateStore {
 
 	try {
 		// Required lazily so the package loads in environments without the native module.
-		const { MMKV } = require('react-native-mmkv') as {
-			MMKV: new (config: { id: string; path?: string }) => MmkvLike;
+		// v4's factory: up to 0.2.0 this called the v3 `new MMKV()`, which v4 — the
+		// only major the peer range allows — no longer exports as a value, so every
+		// device silently got the session-scoped memory store.
+		const { createMMKV } = require('react-native-mmkv') as {
+			createMMKV: (config: { id: string; path?: string }) => MmkvLike;
 		};
 
-		instance = new MMKV({
+		instance = createMMKV({
 			id: INSTANCE_ID,
 			// Caches is backup-excluded by platform design; see the note above.
 			path: Platform.OS === 'ios' ? 'Library/Caches/chipmobilesdk-notification' : undefined,
@@ -58,7 +62,7 @@ export function createMmkvStore(): StateStore {
 	return {
 		getString: key => instance.getString(key),
 		setString: (key, value) => instance.set(key, value),
-		delete: key => instance.delete(key),
+		delete: key => instance.remove(key),
 		clearAll: () => instance.clearAll(),
 		approximateBytes: () => {
 			let total = 0;

package/src/testing/measure.ts

@@ -76,10 +76,10 @@ const TONE: ResolvedTone = {
 		importance: 'default',
 		vibration: false,
 		badge: false,
-		bypassDnd: false,
-			name: 'Fixture tone',
-			loopSound: false,
-			alarmCategory: false,
+		bypassDnd: false,
+			name: 'Fixture tone',
+			loopSound: false,
+			alarmCategory: false,
 		},
 	ios: { categoryId: 'perf', interruptionLevel: 'active', badge: false, repeatRefused: false },
 };