@chipmobilesdk/rn-notification 0.1.0

package/src/engine/notify-kit-engine.ts

@@ -0,0 +1,535 @@
+/**
+ * The `react-native-notify-kit` engine implementation.
+ *
+ * Every import of the engine is confined to this file. Nothing above it knows
+ * which engine is in use — which is what allowed the original Notifee choice to
+ * be swapped for its maintained fork without touching a requirement, a test, or
+ * a line of consumer code.
+ *
+ * The module is required lazily so the package loads in Jest and in any
+ * environment without the native module. An absent engine is reported through
+ * the normal diagnostic path rather than crashing at import time.
+ */
+
+import { Platform } from 'react-native';
+import type {
+	NotificationEngineAdapter,
+	EngineCapabilities,
+	EngineScheduleRequest,
+} from './adapter';
+import type { PendingEntry } from '../contract/notification';
+import type { PermissionKind, PermissionState, RestrictionReport } from '../contract/permission';
+import type { ResolvedTone, ChannelGroup } from '../contract/channel';
+import type { InteractionEvent, Unsubscribe } from '../contract/interaction';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+
+/**
+ * iOS keeps only the 64 soonest pending notifications and silently discards the
+ * rest. This number is the entire reason truncation must be computed and
+ * reported by the package rather than left to the platform.
+ */
+const IOS_PENDING_CEILING = 64;
+
+/** Android has no comparable hard ceiling; this bound keeps behavior predictable. */
+const ANDROID_PENDING_BUDGET = 500;
+
+/** Both platforms bound background execution for a silent payload or background action. */
+const BACKGROUND_WINDOW_MS = 30_000;
+
+/**
+ * The engine's own enum values, mirrored as literals.
+ *
+ * These are **numeric** enums in the engine's type definitions, and its native
+ * validator rejects the string names — `importance: 'default'` fails with
+ * "expected a valid Importance". Mirroring them here rather than importing the
+ * enums keeps the engine out of the module graph, which is what lets the
+ * package load without the native module present.
+ *
+ * The package's own `ResolvedTone` deliberately stays platform-neutral strings;
+ * translating to the engine's representation is this adapter's job and nobody
+ * else's.
+ */
+const ANDROID_IMPORTANCE = {
+	none: 0,
+	min: 1,
+	low: 2,
+	default: 3,
+	high: 4,
+} as const;
+
+/** `TriggerType.TIMESTAMP`. */
+const TRIGGER_TYPE_TIMESTAMP = 0;
+
+/** `AlarmType.SET_EXACT_AND_ALLOW_WHILE_IDLE` — exact delivery, survives Doze. */
+const ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE = 3;
+
+/** `AlarmType.SET_AND_ALLOW_WHILE_IDLE` — the approximate degradation of the above. */
+const ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE = 1;
+
+/**
+ * `EventType` values that represent a real user interaction.
+ *
+ * The engine emits far more than interactions on this channel — `DELIVERED`,
+ * `TRIGGER_NOTIFICATION_CREATED`, `CHANNEL_BLOCKED` and others all arrive here.
+ * Treating anything that is not a dismissal as a press would report a
+ * notification *arriving* while the app is open as the user having tapped it,
+ * and the interaction path cancels on tap — so the notification would vanish
+ * from the tray in front of the user, unread.
+ */
+const EVENT_TYPE_DISMISSED = 0;
+const EVENT_TYPE_PRESS = 1;
+const EVENT_TYPE_ACTION_PRESS = 2;
+
+/** Minimal shape used from the engine, so its full surface never leaks into typing. */
+interface NotifyKitModule {
+	createChannel(channel: Record<string, unknown>): Promise<string>;
+	deleteChannel(channelId: string): Promise<void>;
+	getChannels(): Promise<{ id: string }[]>;
+	createChannelGroup(group: Record<string, unknown>): Promise<string>;
+	createTriggerNotification(
+		notification: Record<string, unknown>,
+		trigger: Record<string, unknown>,
+	): Promise<string>;
+	cancelNotification(id: string): Promise<void>;
+	cancelAllNotifications(): Promise<void>;
+	getTriggerNotifications(): Promise<Record<string, unknown>[]>;
+	requestPermission(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+	getNotificationSettings(): Promise<Record<string, unknown>>;
+	openNotificationSettings(): Promise<void>;
+	openAlarmPermissionSettings(): Promise<void>;
+	isBatteryOptimizationEnabled(): Promise<boolean>;
+	onForegroundEvent(handler: (event: Record<string, unknown>) => void): () => void;
+	getInitialNotification(): Promise<Record<string, unknown> | null>;
+}
+
+/**
+ * Drops keys whose value is `undefined`.
+ *
+ * The engine validates its arguments by key presence, not by value: passing
+ * `{ groupId: undefined }` fails with "expected a string value", while omitting
+ * the key entirely is accepted. JavaScript treats the two as interchangeable
+ * almost everywhere, which is exactly why this is easy to get wrong — and why
+ * it only surfaces on a real device, where the native validator runs.
+ */
+function compact<T extends Record<string, unknown>>(value: T): Partial<T> {
+	const output: Record<string, unknown> = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (entry !== undefined) output[key] = entry;
+	}
+	return output as Partial<T>;
+}
+
+function loadEngine(): NotifyKitModule {
+	try {
+		const module = require('react-native-notify-kit') as { default: NotifyKitModule };
+		return module.default;
+	} catch (error) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.PUSH_UNAVAILABLE,
+			'react-native-notify-kit is not installed or its native module is not linked. Install it as a peer dependency and rebuild the app.',
+			{ reason: error instanceof Error ? error.name : 'unknown' },
+		);
+	}
+}
+
+/**
+ * Maps engine authorization values onto our six-state model.
+ *
+ * `notAsked` and `denied` must stay distinguishable — being able to read state
+ * without prompting is worthless if the two collapse. `provisional` is its own
+ * state on both edges, never folded into granted or denied.
+ */
+function toPermissionState(raw: unknown): PermissionState {
+	switch (raw) {
+		case 1:
+		case 'authorized':
+			return 'granted';
+		case 2:
+		case 'provisional':
+			return 'provisional';
+		case 0:
+		case 'denied':
+			return 'denied';
+		case -1:
+		case 'notDetermined':
+			return 'notAsked';
+		default:
+			return 'notAsked';
+	}
+}
+
+export interface NotifyKitEngineOptions {
+	/** Injected in tests; production resolves the real module. */
+	readonly module?: NotifyKitModule;
+	readonly now?: () => number;
+}
+
+export function createNotifyKitEngine(
+	options: NotifyKitEngineOptions = {},
+): NotificationEngineAdapter {
+	let cached: NotifyKitModule | undefined = options.module;
+	const engine = (): NotifyKitModule => (cached ??= loadEngine());
+	const now = options.now ?? (() => Date.now());
+
+	/**
+	 * Round-trips our own metadata through the engine's free-form data bag.
+	 *
+	 * Anchoring mode, generation, and series origin have no engine equivalent,
+	 * and `getPending` must return them (FR-010) or a consumer cannot diff
+	 * against intent. Values are stringified because the platform data bag
+	 * carries strings on both platforms.
+	 */
+	const packData = (request: EngineScheduleRequest): Record<string, string> => ({
+		__cms_anchoring: request.request.moment.anchoring ?? 'wallClock',
+		// The IANA zone, not the tone. Storing the wrong value here does not merely
+		// mislabel an entry: the re-anchoring pass feeds it straight to
+		// Intl.DateTimeFormat, which throws a hard Hermes error on an invalid zone.
+		...(request.anchoringGeneration !== undefined
+			? { __cms_generation: request.anchoringGeneration }
+			: {}),
+		__cms_tone: request.request.tone,
+		__cms_approximate: String(request.approximate),
+		__cms_pushCreated: String(request.pushCreated ?? false),
+		...(request.seriesId !== undefined ? { __cms_series: request.seriesId } : {}),
+		...(request.request.ownerTag !== undefined ? { __cms_owner: request.request.ownerTag } : {}),
+		...(request.request.groupTag !== undefined ? { __cms_group: request.request.groupTag } : {}),
+		...(request.request.routing !== undefined
+			? { __cms_routing: JSON.stringify(request.request.routing) }
+			: {}),
+	});
+
+	const unpackEntry = (raw: Record<string, unknown>): PendingEntry | undefined => {
+		const notification = (raw.notification ?? {}) as Record<string, unknown>;
+		const trigger = (raw.trigger ?? {}) as Record<string, unknown>;
+		const data = (notification.data ?? {}) as Record<string, string>;
+		const id = notification.id;
+
+		if (typeof id !== 'string') return undefined;
+
+		let routing: Record<string, unknown> | undefined;
+		if (typeof data.__cms_routing === 'string') {
+			try {
+				routing = JSON.parse(data.__cms_routing) as Record<string, unknown>;
+			} catch {
+				// A payload we cannot parse is reported as absent rather than as a
+				// crash: the notification is still valid, only its routing is lost.
+				routing = undefined;
+			}
+		}
+
+		return {
+			id,
+			resolvedAt: typeof trigger.timestamp === 'number' ? trigger.timestamp : now(),
+			anchoring: data.__cms_anchoring === 'absolute' ? 'absolute' : 'wallClock',
+			anchoringGeneration:
+				data.__cms_anchoring === 'absolute' ? undefined : data.__cms_generation,
+			content: {
+				title: typeof notification.title === 'string' ? notification.title : '',
+				body: typeof notification.body === 'string' ? notification.body : '',
+				subtitle: typeof notification.subtitle === 'string' ? notification.subtitle : undefined,
+			},
+			tone: data.__cms_tone ?? '',
+			routing,
+			ownerTag: data.__cms_owner,
+			groupTag: data.__cms_group,
+			seriesId: data.__cms_series,
+			mayBeDelayed: data.__cms_approximate === 'true',
+			pushCreated: data.__cms_pushCreated === 'true',
+		};
+	};
+
+	const toInteraction = (raw: Record<string, unknown>): InteractionEvent | undefined => {
+		const eventType = raw.type;
+
+		// Only a dismissal or a press is an interaction. Everything else the
+		// engine emits on this channel — delivery, trigger creation, channel
+		// blocking — is not, and must not be reported as one.
+		if (
+			eventType !== EVENT_TYPE_DISMISSED &&
+			eventType !== EVENT_TYPE_PRESS &&
+			eventType !== EVENT_TYPE_ACTION_PRESS
+		) {
+			return undefined;
+		}
+
+		const detail = (raw.detail ?? {}) as Record<string, unknown>;
+		const notification = (detail.notification ?? {}) as Record<string, unknown>;
+		const pressAction = (detail.pressAction ?? {}) as Record<string, unknown>;
+		const id = notification.id;
+
+		if (typeof id !== 'string') return undefined;
+
+		const data = (notification.data ?? {}) as Record<string, string>;
+		let routing: Record<string, unknown> | undefined;
+		if (typeof data.__cms_routing === 'string') {
+			try {
+				routing = JSON.parse(data.__cms_routing) as Record<string, unknown>;
+			} catch {
+				routing = undefined;
+			}
+		}
+
+		const actionId = typeof pressAction.id === 'string' ? pressAction.id : undefined;
+		// `default` is the engine's own press-action id for tapping the body, so
+		// it is a tap rather than a named action.
+		const isNamedAction = actionId !== undefined && actionId !== 'default';
+		let kind: InteractionEvent['kind'];
+		if (eventType === EVENT_TYPE_DISMISSED) {
+			kind = 'dismiss';
+		} else if (isNamedAction) {
+			kind = 'action';
+		} else {
+			kind = 'tap';
+		}
+
+		return {
+			kind,
+			notificationId: id,
+			actionId: actionId !== 'default' ? actionId : undefined,
+			inputText: typeof detail.input === 'string' ? detail.input : undefined,
+			routing,
+			ownerTag: data.__cms_owner,
+			occurredAt: now(),
+			appState: 'foreground',
+			wasBuffered: false,
+		};
+	};
+
+	return {
+		name: 'react-native-notify-kit',
+
+		async getCapabilities(): Promise<EngineCapabilities> {
+			return {
+				pendingCeiling: Platform.OS === 'ios' ? IOS_PENDING_CEILING : ANDROID_PENDING_BUDGET,
+				supportsExactAlarms: Platform.OS === 'android',
+				supportsChannels: Platform.OS === 'android',
+				supportsTextInputActions: true,
+				supportsDoNotDisturbBypass: Platform.OS === 'android',
+				backgroundWindowMs: BACKGROUND_WINDOW_MS,
+			};
+		},
+
+		async schedule(request: EngineScheduleRequest): Promise<void> {
+			const actions = request.request.actions?.map(action =>
+				compact({
+					title: action.title,
+					pressAction: compact({
+						id: action.id,
+						launchActivity: action.mode === 'foreground' ? 'default' : undefined,
+					}),
+					input: action.input === undefined ? undefined : compact({ placeholder: action.input.placeholder }),
+				}),
+			);
+
+			await engine().createTriggerNotification(
+				compact({
+					id: request.request.id,
+					title: request.request.content.title,
+					body: request.request.content.body,
+					subtitle: request.request.content.subtitle,
+					data: packData(request),
+					android: compact({
+						channelId: request.tone.android.channelId,
+						// Numeric enum, not the string name — see ANDROID_IMPORTANCE.
+						importance: ANDROID_IMPORTANCE[request.tone.android.importance],
+						sound: request.tone.android.sound,
+						groupId: request.tone.android.groupId,
+						actions,
+					}),
+					ios: compact({
+						categoryId: request.tone.ios.categoryId,
+						// This one genuinely is a string union in the engine's types.
+						interruptionLevel: request.tone.ios.interruptionLevel,
+						sound: request.tone.ios.sound,
+					}),
+				}),
+				{
+					type: TRIGGER_TYPE_TIMESTAMP,
+					timestamp: request.resolvedAt,
+					// Approximate mode is a degradation, not a failure: the notification
+					// is still scheduled and the caller is told it may arrive late.
+					alarmManager: {
+						allowWhileIdle: true,
+						type: request.approximate
+							? ALARM_TYPE_INEXACT_AND_ALLOW_WHILE_IDLE
+							: ALARM_TYPE_EXACT_AND_ALLOW_WHILE_IDLE,
+					},
+				},
+			);
+		},
+
+		async cancel(id: string): Promise<void> {
+			await engine().cancelNotification(id);
+		},
+
+		async cancelMany(ids: readonly string[]): Promise<void> {
+			// Sequential rather than parallel: the engine bridges each call to
+			// native, and a burst of concurrent cancels is where duplicate-delivery
+			// races have historically appeared.
+			for (const id of ids) {
+				await engine().cancelNotification(id);
+			}
+		},
+
+		async cancelAll(): Promise<void> {
+			await engine().cancelAllNotifications();
+		},
+
+		async getPending(): Promise<readonly PendingEntry[]> {
+			const raw = await engine().getTriggerNotifications();
+			return raw
+				.map(unpackEntry)
+				.filter((entry): entry is PendingEntry => entry !== undefined)
+				.sort((a, b) => a.resolvedAt - b.resolvedAt);
+		},
+
+		async declareTone(tone: ResolvedTone): Promise<boolean> {
+			if (Platform.OS !== 'android') {
+				// iOS categories are declared at request time rather than up front.
+				return false;
+			}
+
+			const existing = await engine().getChannels();
+			if (existing.some(channel => channel.id === tone.android.channelId)) {
+				// Android silently ignores re-declaration, which is exactly why the
+				// package keeps its own migration ledger rather than asking here.
+				return false;
+			}
+
+			await engine().createChannel(
+				compact({
+					id: tone.android.channelId,
+					name: tone.toneId,
+					importance: ANDROID_IMPORTANCE[tone.android.importance],
+					sound: tone.android.sound,
+					vibration: tone.android.vibration,
+					badge: tone.android.badge,
+					bypassDnd: tone.android.bypassDnd,
+					groupId: tone.android.groupId,
+				}),
+			);
+			return true;
+		},
+
+		async retireTone(channelId: string): Promise<boolean> {
+			if (Platform.OS !== 'android') return false;
+
+			const existing = await engine().getChannels();
+			if (!existing.some(channel => channel.id === channelId)) return false;
+
+			await engine().deleteChannel(channelId);
+			return true;
+		},
+
+		async declareGroups(groups: readonly ChannelGroup[]): Promise<void> {
+			if (Platform.OS !== 'android') return;
+
+			for (const group of groups) {
+				await engine().createChannelGroup(
+					compact({ id: group.id, name: group.name, description: group.description }),
+				);
+			}
+		},
+
+		async listDeclaredChannels(): Promise<readonly string[]> {
+			if (Platform.OS !== 'android') return [];
+			const channels = await engine().getChannels();
+			return channels.map(channel => channel.id);
+		},
+
+		async getPermission(kind: PermissionKind): Promise<PermissionState> {
+			const settings = await engine().getNotificationSettings();
+
+			if (kind === 'display') {
+				// Android below 13 has no runtime display permission at all.
+				if (Platform.OS === 'android' && (Platform.Version as number) < 33) {
+					return 'notRequired';
+				}
+				return toPermissionState(settings.authorizationStatus);
+			}
+
+			// Exact alarms exist only on Android 12+; elsewhere the concept does not
+			// apply, which is "not required" rather than "denied".
+			if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
+				return 'notRequired';
+			}
+
+			const android = (settings.android ?? {}) as Record<string, unknown>;
+			return android.alarm === 1 ? 'granted' : 'denied';
+		},
+
+		async requestPermission(kind: PermissionKind): Promise<PermissionState> {
+			if (kind === 'display') {
+				const result = await engine().requestPermission();
+				return toPermissionState(result.authorizationStatus);
+			}
+
+			// Exact-alarm capability is granted only through system settings on the
+			// versions that gate it — there is no in-app dialog to present.
+			if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
+				return 'notRequired';
+			}
+			await engine().openAlarmPermissionSettings();
+			return this.getPermission('exactAlarm');
+		},
+
+		async openSettings(kind: PermissionKind): Promise<void> {
+			if (kind === 'exactAlarm') {
+				if (Platform.OS !== 'android' || (Platform.Version as number) < 31) {
+					throw new NotificationError(
+						DIAGNOSTIC_CODES.SETTINGS_UNAVAILABLE,
+						'No exact-alarm settings screen exists on this platform version.',
+						{ platform: Platform.OS, version: Platform.Version },
+					);
+				}
+				await engine().openAlarmPermissionSettings();
+				return;
+			}
+			await engine().openNotificationSettings();
+		},
+
+		async getRestrictions(): Promise<RestrictionReport> {
+			if (Platform.OS !== 'android') {
+				return {
+					batteryOptimization: 'unrestricted',
+					autoStart: 'unrestricted',
+					readAt: now(),
+				};
+			}
+
+			let batteryOptimization: RestrictionReport['batteryOptimization'] = 'unknown';
+			try {
+				batteryOptimization = (await engine().isBatteryOptimizationEnabled())
+					? 'restricted'
+					: 'unrestricted';
+			} catch {
+				batteryOptimization = 'unknown';
+			}
+
+			return {
+				batteryOptimization,
+				// No standard API exposes vendor auto-start policy, and guessing would
+				// be worse than admitting it. `unknown` is a first-class answer here.
+				autoStart: 'unknown',
+				readAt: now(),
+			};
+		},
+
+		subscribeToInteractions(handler: (event: InteractionEvent) => void): Unsubscribe {
+			return engine().onForegroundEvent(raw => {
+				const event = toInteraction(raw);
+				if (event !== undefined) handler(event);
+			});
+		},
+
+		async takeInitialInteraction(): Promise<InteractionEvent | undefined> {
+			const raw = await engine().getInitialNotification();
+			if (raw === null) return undefined;
+
+			const event = toInteraction(raw);
+			// A cold-start tap arrives before any handler exists, so it is reported
+			// with the state that actually produced it.
+			return event === undefined ? undefined : { ...event, appState: 'coldStart' };
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,173 @@
+/**
+ * @chipmobilesdk/rn-notification
+ *
+ * Default entrypoint: scheduling, recurrence, reconciliation, permissions,
+ * channels, interaction, and diagnostics.
+ *
+ * Push lives behind `@chipmobilesdk/rn-notification/push` so an app that never
+ * enables it ships no provider code, no push permissions, and no entitlements.
+ * Test doubles live behind `@chipmobilesdk/rn-notification/testing` so they
+ * never reach a production bundle.
+ *
+ * No engine, provider, or storage type is reachable from here — that is what
+ * makes each of them replaceable.
+ */
+
+export type {
+	// Notification
+	AnchoringMode,
+	DeliveryMoment,
+	NotificationContent,
+	RoutingPayload,
+	Action,
+	NotificationRequest,
+	PendingEntry,
+	ScheduleResult,
+	// Recurrence
+	Weekday,
+	DailyPattern,
+	WeeklyPattern,
+	MonthlyByDayPattern,
+	RecurrencePattern,
+	EndCondition,
+	OccurrenceTemplate,
+	RecurrenceRule,
+	LookaheadConfig,
+	SeriesResult,
+	SeriesSummary,
+	// Reconciliation
+	ReconcileInput,
+	ReconcileResult,
+	RejectedEntry,
+	TruncationReport,
+	PendingDiscrepancy,
+	MaintenanceResult,
+	// Permission
+	PermissionKind,
+	PermissionState,
+	PermissionReport,
+	PermissionCapability,
+	RestrictionStatus,
+	RestrictionReport,
+	// Channel
+	ToneUrgency,
+	ToneSound,
+	ToneDeclaration,
+	ChannelGroup,
+	ChannelApplyResult,
+	// Reachable through EngineScheduleRequest, so the engine port is unusable
+	// without it — a consumer supplying its own engine must be able to name it.
+	ResolvedTone,
+	// Interaction
+	InteractionKind,
+	AppStateAtInteraction,
+	InteractionEvent,
+	InteractionHandler,
+	TargetMissingSignal,
+	Unsubscribe,
+	// Diagnostics
+	DiagnosticSeverity,
+	DiagnosticEvent,
+	EventSink,
+	CollectionHealth,
+	StateHealth,
+	StateSnapshot,
+	BurstThreshold,
+	NotificationConfig,
+	InitializeResult,
+} from './contract';
+
+export {
+	DEFAULT_ANCHORING_MODE,
+	DEFAULT_LOOKAHEAD,
+	LOOKAHEAD_BOUNDS,
+	INTERACTION_BUFFER_LIMITS,
+	MAX_ROUTING_PAYLOAD_BYTES,
+	MAX_ACTIONS_PER_NOTIFICATION,
+	DEFAULT_BURST_THRESHOLD,
+	DIAGNOSTIC_CODES,
+	ALL_DIAGNOSTIC_CODES,
+	NotificationError,
+	isNotificationError,
+	isNonFailure,
+} from './contract';
+
+export type { DiagnosticCode } from './contract';
+
+/**
+ * The engine port. Exported so a consuming app can supply its own engine, which
+ * is the mechanism behind provider and engine substitution.
+ */
+export type {
+	NotificationEngineAdapter,
+	EngineCapabilities,
+	EngineScheduleRequest,
+} from './engine/adapter';
+
+/** The default engine. Consumers may substitute their own via the port above. */
+export { createNotifyKitEngine } from './engine/notify-kit-engine';
+
+/** Initialization and the assembled runtime. */
+export { initialize } from './initialize';
+export type { RuntimeDependencies, NotificationRuntime } from './initialize';
+
+/** Scheduling operations. */
+export { createScheduler } from './schedule';
+export type { Scheduler, ScheduleDependencies } from './schedule';
+
+/** Reconciliation — always consumer-invoked, never automatic. */
+export { createReconciler } from './reconcile';
+export type { Reconciler, ReconcileDependencies } from './reconcile';
+
+/** Recurrence — declare a rule once; the package maintains a bounded window. */
+export { createRecurrence } from './recurrence';
+export type { Recurrence, RecurrenceDependencies } from './recurrence';
+export { occurrenceId } from './recurrence/expand';
+
+/** Channels and tones — declared once, mapped to each platform, migrated on change. */
+export { createChannels } from './channel/migrate';
+export type { Channels, ChannelDependencies } from './channel/migrate';
+export { channelIdFor, createToneResolver, parseChannelId, resolveTone } from './channel/tone-map';
+
+/** Interaction routing — one handler for foreground, background, and cold start. */
+export { createInteractions } from './interaction';
+export type { Interactions, InteractionDependencies } from './interaction';
+
+/** Observability — snapshot and burst detection. */
+export { createSnapshot } from './diagnostics/snapshot';
+export type { Snapshot, SnapshotDependencies } from './diagnostics/snapshot';
+export { createBurstDetector } from './diagnostics/burst';
+export type { BurstDetector, BurstStatus } from './diagnostics/burst';
+export { DiagnosticEmitter } from './diagnostics/events';
+
+/** Permission coordination — reading never prompts; a refusal never fails the caller. */
+export { createPermissions } from './permission';
+export type { Permissions, PermissionDependencies, PermissionChangeHandler } from './permission';
+export { canDisplay, capabilityFor, isTerminal, shouldOfferSettings } from './permission/state';
+export type { PlatformInfo } from './permission/state';
+
+/** Maintenance steps, registered with the runtime's registry. */
+export { createPermissionRefreshStep } from './maintenance/permission-refresh';
+export { createReAnchorStep } from './maintenance/reanchor';
+export { createVerifyStep } from './maintenance/verify';
+export { createWindowRefreshStep } from './maintenance/window-refresh';
+export type { MaintenanceStep, MaintenanceTrigger, MaintenanceContext } from './maintenance/cycle';
+export { MaintenanceRegistry, MaintenanceScopeViolation } from './maintenance/cycle';
+export { MaintenanceController } from './maintenance/toggle';
+
+/** Public state controls — the only two ways a consumer may touch persisted state. */
+export { resetState, clearOwner } from './state/reset';
+export type { ResetOutcome } from './state/reset';
+
+/**
+ * State plumbing. The record's *schema* stays private — a consumer can create
+ * and reset the store, but has no way to read or write what is inside it.
+ */
+export { createMmkvStore } from './state/mmkv-store';
+export { StateManager } from './state/record';
+export type { StateStore } from './state/store';
+
+/** Documented limits, exported so a consumer can validate before calling. */
+export { MAX_IDENTIFIER_LENGTH } from './schedule/validate-identifier';
+export { CONTENT_LIMITS } from './schedule/validate-content';
+export { PAST_TOLERANCE_MS } from './schedule/resolve-moment';