@chipmobilesdk/rn-notification 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -38,6 +38,7 @@
 		"src/schedule",
 		"src/state",
 		"src/testing",
+		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],

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

@@ -0,0 +1,102 @@
+---
+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."
+metadata:
+  package: "@chipmobilesdk/rn-notification"
+  packageVersion: "0.1.1"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-notification
+
+Scheduled local notifications with stable identity and idempotent reconciliation,
+provider-agnostic push, permissions, declarative channels and tones, and tap routing that
+survives a cold start.
+
+## Use this when
+
+- Scheduling, replacing, or cancelling a notification
+- 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
+- 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
+data (`@chipmobilesdk/rn-local-db`), or for translating text — resolve strings yourself.
+
+## Read before writing any code
+
+Three things cause most of the bugs, and none is visible in the type signatures:
+
+1. **Identifiers are yours and must be derived from data.** `crypto.randomUUID()` means
+   you can never replace or cancel what you scheduled. Nothing is normalized, so
+   `Task:1` and `task:1` are two different notifications.
+2. **Wall-clock is the default anchoring mode** — an 08:00 reminder stays 08:00 after the
+   user changes time zone. One case re-anchoring cannot fix: read
+   `### What re-anchoring cannot fix` before promising exact behaviour to anyone.
+3. **Reconciliation is never automatic.** The package maintains its own recurrence windows
+   and re-anchoring, but never invents a desired set. Data changed and you did not call
+   `reconcile()` means the device is stale, by design.
+
+Read `## Choosing identifiers`, `## Choosing an anchoring mode`, and
+`## Maintenance versus reconciliation` before designing anything.
+
+**A refusal must never break the user's work.** Permission denial is a degradation, not a
+failure: the caller's operation still succeeds and the lost capability is reported
+separately. Without exact-alarm capability notifications are still scheduled, flagged
+`mayBeDelayed`. Never gate a user action on a permission answer.
+
+## Android: two manifest entries you must add yourself
+
+Consumer-owned; this package cannot ship either.
+
+- **`SCHEDULE_EXACT_ALARM` arrives whether you want it or not** — the engine declares it
+  and manifest merging is transitive. It is store-restricted and needs a Play Console
+  declaration. Remove it with `tools:node="remove"` unless you need precise timing.
+- **Backup exclusion** for the state record — a deduplication ledger restored onto another
+  device claims payloads were already delivered, silently suppressing real ones.
+
+See `### Android` and `### Backup exclusion`.
+
+## Public API
+
+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`.
+**`/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
+engine and provider, the conformance suite and the fault injector.
+
+Enumerate exact names from `node_modules/@chipmobilesdk/rn-notification/src/index.ts`
+rather than guessing.
+
+## Where the detail lives
+
+`node_modules/@chipmobilesdk/rn-notification/README.md`:
+
+| Need | Section |
+|---|---|
+| Install, peers, enabling push | `## Installation`, `### Enabling push (optional)` |
+| Native setup | `### iOS`, `### Android`, `### Backup exclusion` |
+| Naming notifications | `## Choosing identifiers` |
+| Time zones and travel | `## Choosing an anchoring mode` |
+| Automatic vs your responsibility | `## Maintenance versus reconciliation` |
+| Converging the device to your data | `## Reconciliation`, `## Recurrence` |
+| Permission timing and recovery | `## Permissions` |
+| Taps, actions, cold start | `## Interaction` |
+| Push and the backend contract | `## Push` |
+| On-device storage and privacy | `## What is persisted`, `## Data behaviour …` |
+| Limits and timing budgets | `## Budgets` |
+| Error codes | `## Diagnostic identifiers` |
+
+## Debugging "it did not arrive"
+
+Capture a state snapshot (`createSnapshot`) before guessing — permissions, applied channel
+versions, pending set, last maintenance cycle, discrepancies and state health, in one
+place. Some codes are **reported outcomes, not failures** (`TRUNCATED_OVER_CEILING`,
+`EXACT_ALARM_UNAVAILABLE`, `PENDING_SET_DISCREPANCY`, `BURST_THRESHOLD_EXCEEDED`,
+`PAYLOAD_VERSION_SKEW`); use `isNonFailure(code)` rather than treating every code as an
+error.

package/src/index.ts

@@ -171,3 +171,14 @@ export type { StateStore } from './state/store';
 export { MAX_IDENTIFIER_LENGTH } from './schedule/validate-identifier';
 export { CONTENT_LIMITS } from './schedule/validate-content';
 export { PAST_TOLERANCE_MS } from './schedule/resolve-moment';
+
+/**
+ * Reads the platform time zone, which anchoring depends on.
+ *
+ * Exported because every consumer needs it and pure JavaScript cannot provide
+ * it reliably — `Intl.DateTimeFormat().resolvedOptions().timeZone` does not
+ * update when the device zone changes. Leaving consumers to write this
+ * themselves is how a subtly wrong version ends up in each of them.
+ */
+export { createPlatformTimeZoneReader, isValidTimeZone } from './schedule/anchor';
+export type { TimeZoneReader } from './schedule/anchor';

package/src/state/dedup-ledger.ts

@@ -1,39 +1,35 @@
-/**
- * The push deduplication ledger.
- *
- * Providers redeliver. The redelivery typically arrives in a **fresh process**,
- * which is precisely why this is persisted rather than held in memory — an
- * in-memory set would forget exactly when it matters.
- *
- * Bounded by cap and retention. A payload redelivered after its entry has aged
- * out is treated as new: that is the documented bound of the guarantee, not a
- * defect.
- */
-
-import type { StateManager } from './record';
-
-export function isDuplicate(state: StateManager, dedupId: string): boolean {
-	return state.read().dedupLedger.some(entry => entry.dedupId === dedupId);
-}
-
-/**
- * Records a payload as seen.
- *
- * Returns true when it was already known, so a caller can branch on the same
- * read that records it rather than checking twice.
- */
-export function recordSeen(
-	state: StateManager,
-	dedupId: string,
-	now: number,
-	ownerTag?: string,
-): boolean {
-	if (isDuplicate(state, dedupId)) return true;
-
-	state.update('dedupLedger', current => [...current, { at: now, dedupId, ownerTag }]);
-	return false;
-}
-
-export function dedupCount(state: StateManager): number {
-	return state.read().dedupLedger.length;
-}
+/**
+ * The push deduplication ledger.
+ *
+ * Providers redeliver. The redelivery typically arrives in a **fresh process**,
+ * which is precisely why this is persisted rather than held in memory — an
+ * in-memory set would forget exactly when it matters.
+ *
+ * Bounded by cap and retention. A payload redelivered after its entry has aged
+ * out is treated as new: that is the documented bound of the guarantee, not a
+ * defect.
+ */
+
+import type { StateManager } from './record';
+
+export function isDuplicate(state: StateManager, dedupId: string): boolean {
+	return state.read().dedupLedger.some(entry => entry.dedupId === dedupId);
+}
+
+/**
+ * Records a payload as seen.
+ *
+ * Returns true when it was already known, so a caller can branch on the same
+ * read that records it rather than checking twice.
+ */
+export function recordSeen(
+	state: StateManager,
+	dedupId: string,
+	now: number,
+	ownerTag?: string,
+): boolean {
+	if (isDuplicate(state, dedupId)) return true;
+
+	state.update('dedupLedger', current => [...current, { at: now, dedupId, ownerTag }]);
+	return false;
+}

package/src/testing/index.ts

@@ -11,6 +11,8 @@ export { createFakeEngine } from './fake-engine';
 export { createFakeProvider } from './fake-provider';
 export { createFaultInjector } from './faults';
 export { runConformanceSuite } from './conformance';
+export { runMeasurementHarness, PERF_BUDGETS } from './measure';
+export type { MeasurementReport, Measurement, BudgetName, MeasureOptions } from './measure';
 export type { ConformanceReport, ConformanceCheck, ConformanceOptions } from './conformance';
 export type { FaultInjector, FaultKind, FaultRecord, Disposable } from './faults';
 export type { FakeProvider, FakeProviderOptions, FakeProviderControls } from './fake-provider';

package/src/testing/measure.ts

@@ -0,0 +1,334 @@
+/**
+ * The PERF-001 measurement harness.
+ *
+ * Every budget in the specification, measured against the real code paths and
+ * reported as pass or fail with the number that produced the verdict. Written
+ * as a plain async function rather than a Jest suite so the same harness runs
+ * in continuous integration and from the demo app on a physical device — which
+ * matters, because PERF-003 forbids emulator numbers standing in as evidence.
+ *
+ * Five budgets are deliberately absent and reported as such: delivery accuracy,
+ * cold-start latency, startup delta and frame rate cannot be measured
+ * in-process. The first needs the OS to actually fire an alarm, the second a
+ * real process death. Pretending to measure them here would be worse than
+ * leaving the gap visible.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { NotificationRequest } from '../contract/notification';
+import type { ResolvedTone } from '../contract/channel';
+import type { RecurrenceRule } from '../contract/recurrence';
+import { createScheduler } from '../schedule';
+import { createReconciler } from '../reconcile';
+import { createRecurrence } from '../recurrence';
+import { createPermissions } from '../permission';
+import { createReAnchorStep } from '../maintenance/reanchor';
+import { MaintenanceRegistry } from '../maintenance/cycle';
+import { StateManager } from '../state/record';
+import { createMemoryStore } from '../state/store';
+import { planReAnchor } from '../schedule/anchor';
+import { recordSeen } from '../state/dedup-ledger';
+
+/** Every budget PERF-001 states, in milliseconds unless the name says otherwise. */
+export const PERF_BUDGETS = {
+	scheduleOne: 50,
+	readPending100: 200,
+	reconcileNoChange100: 150,
+	reconcile500With100Changes: 1_500,
+	maintenanceIdleCycle: 300,
+	windowRefresh32Series: 500,
+	reAnchor100: 1_000,
+	reAnchorNoChangeCheck: 20,
+	permissionRead: 50,
+	dedupCheck: 20,
+	interfaceThreadUnit: 16,
+	stateFootprintBytes: 1_048_576,
+} as const;
+
+export type BudgetName = keyof typeof PERF_BUDGETS;
+
+export interface Measurement {
+	readonly name: BudgetName;
+	readonly label: string;
+	/** Milliseconds, or bytes for the footprint budget. */
+	readonly measured: number;
+	readonly budget: number;
+	readonly unit: 'ms' | 'bytes';
+	readonly passed: boolean;
+	/** Present where the budget also demands zero platform operations. */
+	readonly operationCount?: number;
+}
+
+export interface MeasurementReport {
+	readonly measurements: readonly Measurement[];
+	readonly passed: number;
+	readonly failed: number;
+	/** Budgets this harness structurally cannot measure. Never silently omitted. */
+	readonly requiresDevice: readonly string[];
+	readonly ranAt: number;
+}
+
+const TONE: ResolvedTone = {
+	toneId: 'perf',
+	version: 1,
+	android: {
+		channelId: 'perf.v1',
+		importance: 'default',
+		vibration: false,
+		badge: false,
+		bypassDnd: false,
+	},
+	ios: { categoryId: 'perf', interruptionLevel: 'active', badge: false },
+};
+
+export interface MeasureOptions {
+	/** Defaults to the real clock, which is what a device run needs. */
+	readonly clock?: () => number;
+	/** Identifier prefix, so a device run cannot collide with real notifications. */
+	readonly prefix?: string;
+}
+
+export async function runMeasurementHarness(
+	engine: NotificationEngineAdapter,
+	options: MeasureOptions = {},
+): Promise<MeasurementReport> {
+	const clock = options.clock ?? (() => Date.now());
+	const prefix = options.prefix ?? 'perf';
+	const measurements: Measurement[] = [];
+
+	const now = () => Date.now();
+	const zone = 'UTC';
+	const state = new StateManager({ store: createMemoryStore(), now });
+	const resolveTone = () => TONE;
+
+	const record = (
+		name: BudgetName,
+		label: string,
+		measured: number,
+		operationCount?: number,
+	): void => {
+		const budget = PERF_BUDGETS[name];
+		// A budget that also demands zero operations fails on either count.
+		const opsOk = operationCount === undefined || operationCount === 0;
+		measurements.push({
+			name,
+			label,
+			measured,
+			budget,
+			unit: name === 'stateFootprintBytes' ? 'bytes' : 'ms',
+			passed: measured <= budget && opsOk,
+			operationCount,
+		});
+	};
+
+	/** Median of three, so one scheduler hiccup does not decide a verdict. */
+	const timeOf = async (run: () => Promise<unknown>): Promise<number> => {
+		const samples: number[] = [];
+		for (let i = 0; i < 3; i += 1) {
+			const started = clock();
+			await run();
+			samples.push(clock() - started);
+		}
+		return samples.sort((a, b) => a - b)[1];
+	};
+
+	const request = (id: string, at: number): NotificationRequest => ({
+		id: `${prefix}:${id}`,
+		content: { title: id, body: 'Measurement harness entry' },
+		tone: 'perf',
+		moment: { at },
+		groupTag: prefix,
+	});
+
+	const scheduler = createScheduler({
+		engine,
+		resolveTone,
+		timeZone: () => zone,
+		now,
+		canScheduleExactly: () => true,
+	});
+
+	await engine.cancelAll();
+
+	// --- Scheduling -----------------------------------------------------------
+
+	record(
+		'scheduleOne',
+		'Single schedule operation',
+		await timeOf(() => scheduler.schedule(request('single', now() + 3_600_000))),
+	);
+
+	for (let i = 0; i < 100; i += 1) {
+		await scheduler.schedule(request(`bulk:${i}`, now() + (i + 1) * 60_000));
+	}
+
+	record('readPending100', 'Read pending set of 100', await timeOf(() => scheduler.getPending()));
+
+	// --- Reconciliation -------------------------------------------------------
+
+	const reconciler = createReconciler({
+		engine,
+		resolveTone,
+		timeZone: () => zone,
+		now,
+		canScheduleExactly: () => true,
+	});
+
+	const hundred = Array.from({ length: 100 }, (_, i) =>
+		request(`recon:${i}`, now() + (i + 1) * 60_000),
+	);
+	await reconciler.reconcile({ domain: prefix, desired: hundred });
+
+	let noChangeOps = 0;
+	const noChangeMs = await timeOf(async () => {
+		const result = await reconciler.reconcile({ domain: prefix, desired: hundred });
+		noChangeOps = result.operationCount;
+	});
+	record('reconcileNoChange100', 'No-change reconcile over 100', noChangeMs, noChangeOps);
+
+	const fiveHundred = Array.from({ length: 500 }, (_, i) =>
+		request(`recon:${i}`, now() + (i + 1) * 60_000),
+	);
+	await reconciler.reconcile({ domain: prefix, desired: fiveHundred });
+
+	const changed = fiveHundred.map((entry, i) =>
+		i < 100 ? { ...entry, content: { title: `changed-${i}`, body: entry.content.body } } : entry,
+	);
+	record(
+		'reconcile500With100Changes',
+		'500-entry reconcile with 100 changes',
+		await timeOf(() => reconciler.reconcile({ domain: prefix, desired: changed })),
+	);
+
+	// --- Re-anchoring ---------------------------------------------------------
+
+	const pending = await engine.getPending();
+	record(
+		'reAnchorNoChangeCheck',
+		'Re-anchor check with no zone change',
+		await timeOf(async () => planReAnchor(pending, zone)),
+		planReAnchor(pending, zone).rewrites.length,
+	);
+
+	const context = { trigger: 'foreground' as const, now: now(), ownedIds: new Set<string>() };
+	const travelled = createReAnchorStep({
+		engine,
+		timeZone: () => 'Asia/Tokyo',
+		resolveTone,
+		canScheduleExactly: () => true,
+	});
+	record('reAnchor100', 'Re-anchor after a zone change', await timeOf(() => travelled.run(context)));
+
+	// --- Maintenance ----------------------------------------------------------
+
+	const registry = new MaintenanceRegistry();
+	registry.register(
+		createReAnchorStep({
+			engine,
+			timeZone: () => zone,
+			resolveTone,
+			canScheduleExactly: () => true,
+		}),
+	);
+
+	let idleOps = 0;
+	const idleMs = await timeOf(async () => {
+		const result = await registry.run({ ...context, now: now() });
+		idleOps = result.operationCount;
+	});
+	record('maintenanceIdleCycle', 'Idle maintenance cycle', idleMs, idleOps);
+
+	// --- Recurrence -----------------------------------------------------------
+
+	const recurrence = createRecurrence({
+		engine,
+		state,
+		resolveTone,
+		timeZone: () => zone,
+		now,
+		lookahead: { days: 60, occurrencesPerSeries: 32 },
+		canScheduleExactly: () => true,
+	});
+
+	const series: RecurrenceRule[] = Array.from({ length: 32 }, (_, i) => ({
+		id: `${prefix}:series:${i}`,
+		pattern: { kind: 'daily', hour: i % 24, minute: 0 },
+		end: { kind: 'count', count: 2 },
+		template: {
+			content: { title: `Series ${i}`, body: 'Measurement harness series' },
+			tone: 'perf',
+			groupTag: prefix,
+		},
+	}));
+
+	for (const rule of series) {
+		await recurrence.registerSeries(rule);
+	}
+
+	record(
+		'windowRefresh32Series',
+		'Window refresh across 32 series',
+		await timeOf(async () => {
+			for (const rule of series) {
+				await recurrence.refreshSeries(rule);
+			}
+		}),
+	);
+
+	// --- Permissions ----------------------------------------------------------
+
+	const permissions = createPermissions({
+		engine,
+		state,
+		platform: { os: 'android', apiLevel: 34 },
+		now,
+	});
+	record(
+		'permissionRead',
+		'Read all permission states',
+		await timeOf(() => permissions.getPermissions()),
+	);
+
+	// --- Deduplication and footprint -----------------------------------------
+
+	for (let i = 0; i < 400; i += 1) {
+		recordSeen(state, `${prefix}:dedup:${i}`, now());
+	}
+	record(
+		'dedupCheck',
+		'Deduplication ledger check',
+		await timeOf(async () => recordSeen(state, `${prefix}:dedup:probe`, now())),
+	);
+
+	record(
+		'stateFootprintBytes',
+		'Persisted state on disk at caps',
+		state.health().approximateBytes,
+	);
+
+	// The interface-thread ceiling is a property of one chunked unit of work, not
+	// of a whole pass, so it is measured per entry rather than per reconcile.
+	const chunkMs = await timeOf(() =>
+		reconciler.reconcile({ domain: prefix, desired: hundred.slice(0, 25) }),
+	);
+	record('interfaceThreadUnit', 'Single chunked unit of reconcile work', chunkMs / 25);
+
+	await engine.cancelAll();
+
+	const passed = measurements.filter(measurement => measurement.passed).length;
+
+	return {
+		measurements,
+		passed,
+		failed: measurements.length - passed,
+		// Stated rather than silently omitted — these need real hardware.
+		requiresDevice: [
+			'Delivery accuracy, exact mode (60 s) — needs the OS to fire a real alarm',
+			'Delivery accuracy, approximate mode (15 min) — needs a device under no vendor restriction',
+			'Cold-start tap to handler (500 ms) — needs a real process death and relaunch',
+			'App startup delta (100 ms) — needs a real cold start',
+			'Sustained frame rate during reconcile (55 fps) — needs a rendering device',
+		],
+		ranAt: now(),
+	};
+}