@chipmobilesdk/rn-notification 0.5.0 → 0.7.0

package/package.json

@@ -1,25 +1,56 @@
 {
 	"name": "@chipmobilesdk/rn-notification",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"private": false,
 	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
+	"source": "./src/index.ts",
+	"main": "./lib/commonjs/index.js",
+	"module": "./lib/module/index.js",
+	"types": "./lib/typescript/commonjs/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
+			"chipmobilesdk-source": "./src/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/index.d.ts",
+				"default": "./lib/module/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/index.d.ts",
+				"default": "./lib/commonjs/index.js"
+			}
+		},
+		"./advanced": {
+			"chipmobilesdk-source": "./src/advanced.ts",
+			"import": {
+				"types": "./lib/typescript/module/advanced.d.ts",
+				"default": "./lib/module/advanced.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/advanced.d.ts",
+				"default": "./lib/commonjs/advanced.js"
+			}
 		},
 		"./push": {
-			"types": "./src/push/index.ts",
-			"react-native": "./src/push/index.ts",
-			"default": "./src/push/index.ts"
+			"chipmobilesdk-source": "./src/push/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/push/index.d.ts",
+				"default": "./lib/module/push/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/push/index.d.ts",
+				"default": "./lib/commonjs/push/index.js"
+			}
 		},
 		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
+			"chipmobilesdk-source": "./src/testing/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/testing/index.d.ts",
+				"default": "./lib/module/testing/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/testing/index.d.ts",
+				"default": "./lib/commonjs/testing/index.js"
+			}
 		}
 	},
 	"files": [
@@ -27,35 +58,55 @@
 		"!src/**/__tests__",
 		"skills",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"lib"
 	],
 	"sideEffects": false,
 	"scripts": {
+		"build": "bob build",
 		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
-		"pack:check": "npm pack --dry-run"
+		"pack:check": "npm pack --dry-run",
+		"prepack": "npm run build"
 	},
 	"dependencies": {
-		"@chipmobilesdk/rn-core": "^0.1.0"
+		"@chipmobilesdk/rn-core": "^0.2.0"
 	},
 	"peerDependencies": {
-		"@react-native-firebase/app": ">=26.0.0",
-		"@react-native-firebase/messaging": ">=26.0.0",
-		"react": ">=19",
+		"@react-native-firebase/messaging": "^26.0.0",
 		"react-native": ">=0.85",
-		"react-native-localize": ">=3.7.0",
-		"react-native-mmkv": ">=4.0.0",
-		"react-native-notify-kit": ">=10.5.0"
+		"react-native-localize": "^3.7.0",
+		"react-native-mmkv": "^4.0.0",
+		"react-native-notify-kit": "^10.5.0"
 	},
 	"peerDependenciesMeta": {
-		"@react-native-firebase/app": {
+		"@react-native-firebase/messaging": {
 			"optional": true
 		},
-		"@react-native-firebase/messaging": {
+		"react-native-localize": {
 			"optional": true
 		}
 	},
 	"publishConfig": {
 		"access": "public",
 		"registry": "https://registry.npmjs.org/"
+	},
+	"react-native-builder-bob": {
+		"source": "src",
+		"output": "lib",
+		"targets": [
+			[
+				"commonjs",
+				{
+					"esm": true
+				}
+			],
+			[
+				"module",
+				{
+					"esm": true
+				}
+			],
+			"typescript"
+		]
 	}
 }

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

@@ -35,11 +35,12 @@ Three things cause most of the bugs, and none is visible in the type signatures:
 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.** Maintenance steps registered on
-   `runtime.registry` (window refresh, re-anchoring, verification, permission re-read) run
-   on every foreground return, but the package never invents a desired set. Data changed
-   and you did not call `reconcile()` means the device is stale, by design. The steps are
-   not registered for you — they need your rules and expected ids.
+3. **Reconciliation is never automatic.** Start from `createNotifications(config, deps)`:
+   it registers re-anchoring and the permission re-read, plus window refresh when you pass
+   `recurrenceRules`, and runs them on every foreground return. It never invents a desired
+   set: data changed and you did not call `reconcile()` means the device is stale, by
+   design. Wiring with `initialize()` and the factories from `./advanced` leaves step
+   registration to you.
 
 Read `## Choosing identifiers`, `## Choosing an anchoring mode`, and
 `## Maintenance versus reconciliation` before designing anything.

package/src/advanced.ts

@@ -0,0 +1,35 @@
+/**
+ * `@chipmobilesdk/rn-notification/advanced`: the individual factories, for an app
+ * that wires the package itself instead of using `createNotifications` (NOT-07).
+ *
+ * The package root still exports them too, for compatibility; new code that needs
+ * them should import from here, where they are documented as the advanced path.
+ */
+export { initialize } from './initialize';
+export type { NotificationRuntime, RuntimeDependencies } from './initialize';
+export { createScheduler } from './schedule';
+export type { Scheduler, ScheduleDependencies } from './schedule';
+export { createReconciler } from './reconcile';
+export type { Reconciler, ReconcileDependencies } from './reconcile';
+export { createRecurrence } from './recurrence';
+export type { Recurrence, RecurrenceDependencies } from './recurrence';
+export { createChannels } from './channel/migrate';
+export type { ChannelDependencies, Channels } from './channel/migrate';
+export { createToneResolver } from './channel/tone-map';
+export { createInteractions } from './interaction';
+export type { InteractionDependencies, Interactions } from './interaction';
+export { createSnapshot } from './diagnostics/snapshot';
+export type { Snapshot, SnapshotDependencies } from './diagnostics/snapshot';
+export { createBurstDetector } from './diagnostics/burst';
+export { createPermissions } from './permission';
+export type { PermissionDependencies, Permissions } from './permission';
+export { createPermissionRefreshStep } from './maintenance/permission-refresh';
+export { createReAnchorStep } from './maintenance/reanchor';
+export { createVerifyStep } from './maintenance/verify';
+export { createWindowRefreshStep } from './maintenance/window-refresh';
+export { MaintenanceController } from './maintenance/toggle';
+export { MaintenanceRegistry } from './maintenance/cycle';
+export type { MaintenanceContext, MaintenanceStep, MaintenanceTrigger } from './maintenance/cycle';
+export { StateManager } from './state/record';
+export { createMmkvStore } from './state/mmkv-store';
+export { createPlatformTimeZoneReader } from './schedule/anchor';

package/src/channel/migrate.ts

@@ -74,192 +74,202 @@ export function createChannels(deps: ChannelDependencies) {
 	// has to follow, or it would retire with the old channel.
 	const writer = createScheduleWriter(deps.engine);
 
-	return {
-		/**
-		 * Applies a tone configuration, migrating any tone whose version moved.
-		 *
-		 * Applying an unchanged configuration performs no work at all: no channel
-		 * is recreated and no migration is triggered.
-		 */
-		async apply(
-			tones: readonly ToneDeclaration[],
-			groups: readonly ChannelGroup[] = [],
-		): Promise<ChannelApplyResult> {
-			// Validation completes before the first engine call, so a rejected
-			// declaration leaves the device exactly as it was — the same order the
-			// scheduler has always used.
-			validateToneDeclarations(tones);
+	const applyTones = async (
+		tones: readonly ToneDeclaration[],
+		groups: readonly ChannelGroup[],
+	): Promise<ChannelApplyResult> => {
+		// Validation completes before the first engine call, so a rejected
+		// declaration leaves the device exactly as it was — the same order the
+		// scheduler has always used.
+		validateToneDeclarations(tones);
 
-			const now = deps.now();
+		const now = deps.now();
 
-			const created: string[] = [];
-			const migrated: { toneId: string; from: number; to: number }[] = [];
-			const labelsRefreshed: string[] = [];
-			const retired: string[] = [];
-			const reHomed: string[] = [];
-			const cancelled: string[] = [];
-			const bypassUnavailable: string[] = [];
-			const repeatUnavailable: string[] = [];
-			const unchanged: string[] = [];
+		const created: string[] = [];
+		const migrated: { toneId: string; from: number; to: number }[] = [];
+		const labelsRefreshed: string[] = [];
+		const retired: string[] = [];
+		const reHomed: string[] = [];
+		const cancelled: string[] = [];
+		const bypassUnavailable: string[] = [];
+		const repeatUnavailable: string[] = [];
+		const unchanged: string[] = [];
 
-			if (groups.length > 0) {
-				await deps.engine.declareGroups(groups);
-			}
+		if (groups.length > 0) {
+			await deps.engine.declareGroups(groups);
+		}
+
+		const capabilities = await deps.engine.getCapabilities();
 
-			const capabilities = await deps.engine.getCapabilities();
+		for (const tone of tones) {
+			const previous = ledgerFor(deps.state, tone.id);
+			const resolved = resolveTone(tone);
+			const fingerprint = toneLabelFingerprint(tone);
 
-			for (const tone of tones) {
-				const previous = ledgerFor(deps.state, tone.id);
-				const resolved = resolveTone(tone);
-				const fingerprint = toneLabelFingerprint(tone);
+			// Refusals are reported for every tone that asked, whether or not
+			// anything else about it moved. A platform declining an attribute
+			// says nothing about whether the channel is new.
+			if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
+				// Reported honestly rather than silently dropped — a consumer that
+				// asked for a bypass deserves to know the platform refused.
+				bypassUnavailable.push(tone.id);
+				emit(
+					DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
+					`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
+					{ toneId: tone.id },
+				);
+			}
 
-				// Refusals are reported for every tone that asked, whether or not
-				// anything else about it moved. A platform declining an attribute
-				// says nothing about whether the channel is new.
-				if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
-					// Reported honestly rather than silently dropped — a consumer that
-					// asked for a bypass deserves to know the platform refused.
-					bypassUnavailable.push(tone.id);
+			if (tone.repeatAlert !== undefined) {
+				if (!capabilities.supportsRepeatingAlert) {
+					repeatUnavailable.push(tone.id);
 					emit(
-						DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,
-						`Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`,
+						DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
+						`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
+						{ toneId: tone.id },
+					);
+				} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
+					// Said out loud at declaration time, because the alternative is a
+					// user meeting it as a phone that will not stop ringing.
+					emit(
+						DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
+						`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
 						{ toneId: tone.id },
 					);
 				}
+			}
 
-				if (tone.repeatAlert !== undefined) {
-					if (!capabilities.supportsRepeatingAlert) {
-						repeatUnavailable.push(tone.id);
-						emit(
-							DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE,
-							`Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`,
-							{ toneId: tone.id },
-						);
-					} else if (!deps.engine.hasBackgroundDeliveryHandler()) {
-						// Said out loud at declaration time, because the alternative is a
-						// user meeting it as a phone that will not stop ringing.
-						emit(
-							DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING,
-							`Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`,
-							{ toneId: tone.id },
-						);
-					}
-				}
-
-				const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
-
-				if (previous !== undefined && !versionMoved) {
-					// The version is the same, so nothing the platform freezes has
-					// changed. Only the labels can still be stale — and correcting
-					// those must cost the user nothing, so the platform is touched
-					// only when the fingerprint actually moved.
-					if (previous.labelFingerprint === fingerprint) {
-						unchanged.push(tone.id);
-						continue;
-					}
-
-					const outcome = await deps.engine.declareTone(resolved);
-					if (outcome === 'created') {
-						// The channel was gone — deleted by the user, or lost with the
-						// app's data — so this is a first declaration rather than a
-						// refresh, whatever our ledger believed.
-						created.push(resolved.android.channelId);
-					} else if (outcome === 'labelsRefreshed') {
-						labelsRefreshed.push(tone.id);
-						emit(
-							DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
-							`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
-							{ toneId: tone.id },
-						);
-					} else {
-						unchanged.push(tone.id);
-					}
+			const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
 
-					recordApplied(deps.state, tone, now, undefined, fingerprint);
+			if (previous !== undefined && !versionMoved) {
+				// The version is the same, so nothing the platform freezes has
+				// changed. Only the labels can still be stale — and correcting
+				// those must cost the user nothing, so the platform is touched
+				// only when the fingerprint actually moved.
+				if (previous.labelFingerprint === fingerprint) {
+					unchanged.push(tone.id);
 					continue;
 				}
 
 				const outcome = await deps.engine.declareTone(resolved);
 				if (outcome === 'created') {
+					// The channel was gone — deleted by the user, or lost with the
+					// app's data — so this is a first declaration rather than a
+					// refresh, whatever our ledger believed.
 					created.push(resolved.android.channelId);
+				} else if (outcome === 'labelsRefreshed') {
+					labelsRefreshed.push(tone.id);
+					emit(
+						DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED,
+						`Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`,
+						{ toneId: tone.id },
+					);
+				} else {
+					unchanged.push(tone.id);
 				}
 
-				if (previous === undefined) {
-					recordApplied(deps.state, tone, now, undefined, fingerprint);
-					continue;
-				}
+				recordApplied(deps.state, tone, now, undefined, fingerprint);
+				continue;
+			}
 
-				// A version moved, so this is a migration rather than a first
-				// declaration. Re-home before retiring: the reverse order would leave
-				// live notifications attached to a channel that no longer exists.
-				emit(
-					DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
-					`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
-					{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
-				);
+			const outcome = await deps.engine.declareTone(resolved);
+			if (outcome === 'created') {
+				created.push(resolved.android.channelId);
+			}
 
-				const pending = await deps.engine.getPending();
-				const affected = pending.filter(entry => entry.tone === tone.id);
+			if (previous === undefined) {
+				recordApplied(deps.state, tone, now, undefined, fingerprint);
+				continue;
+			}
 
-				for (const entry of affected) {
-					await writer.write({
-						request: {
-							id: entry.id,
-							content: entry.content,
-							tone: entry.tone,
-							moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
-							routing: entry.routing,
-							actions: entry.actions,
-							ownerTag: entry.ownerTag,
-							groupTag: entry.groupTag,
-						},
-						resolvedAt: entry.resolvedAt,
-						tone: resolved,
-						// Re-homing changes the channel, not the anchoring — preserve it.
-						anchoringGeneration: entry.anchoringGeneration,
-						approximate: entry.mayBeDelayed,
-						seriesId: entry.seriesId,
-						pushCreated: entry.pushCreated,
-					});
-					reHomed.push(entry.id);
-				}
+			// A version moved, so this is a migration rather than a first
+			// declaration. Re-home before retiring: the reverse order would leave
+			// live notifications attached to a channel that no longer exists.
+			emit(
+				DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
+				`Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`,
+				{ toneId: tone.id, from: previous.appliedVersion, to: tone.version },
+			);
 
-				const didRetire = await deps.engine.retireTone(previous.channelId);
-				if (didRetire) {
-					retired.push(previous.channelId);
-				}
+			const pending = await deps.engine.getPending();
+			const affected = pending.filter(entry => entry.tone === tone.id);
 
-				// A version move outranks a label change: the new channel simply
-				// carries the new labels, and reporting it as a refresh would hide a
-				// migration the consumer needs to know about.
-				migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
-				recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
+			for (const entry of affected) {
+				await writer.write({
+					request: {
+						id: entry.id,
+						content: entry.content,
+						tone: entry.tone,
+						moment: { at: entry.resolvedAt, anchoring: entry.anchoring },
+						routing: entry.routing,
+						actions: entry.actions,
+						ownerTag: entry.ownerTag,
+						groupTag: entry.groupTag,
+					},
+					resolvedAt: entry.resolvedAt,
+					tone: resolved,
+					// Re-homing changes the channel, not the anchoring — preserve it.
+					anchoringGeneration: entry.anchoringGeneration,
+					approximate: entry.mayBeDelayed,
+					seriesId: entry.seriesId,
+					pushCreated: entry.pushCreated,
+				});
+				reHomed.push(entry.id);
 			}
 
-			// Anything left on a retired channel would be an orphan — a notification
-			// the user can no longer control from system settings.
-			const orphans = await findOrphans(deps, tones);
-			if (orphans.length > 0) {
-				await deps.engine.cancelMany(orphans);
-				cancelled.push(...orphans);
-				emit(
-					DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
-					`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
-					{ count: orphans.length },
-				);
+			const didRetire = await deps.engine.retireTone(previous.channelId);
+			if (didRetire) {
+				retired.push(previous.channelId);
 			}
 
-			return {
-				created,
-				migrated,
-				labelsRefreshed,
-				retired,
-				reHomed,
-				cancelled,
-				bypassUnavailable,
-				repeatUnavailable,
-				unchanged,
-			};
+			// A version move outranks a label change: the new channel simply
+			// carries the new labels, and reporting it as a refresh would hide a
+			// migration the consumer needs to know about.
+			migrated.push({ toneId: tone.id, from: previous.appliedVersion, to: tone.version });
+			recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
+		}
+
+		// Anything left on a retired channel would be an orphan — a notification
+		// the user can no longer control from system settings.
+		const orphans = await findOrphans(deps, tones);
+		if (orphans.length > 0) {
+			await deps.engine.cancelMany(orphans);
+			cancelled.push(...orphans);
+			emit(
+				DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND,
+				`${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`,
+				{ count: orphans.length },
+			);
+		}
+
+		return {
+			created,
+			migrated,
+			labelsRefreshed,
+			retired,
+			reHomed,
+			cancelled,
+			bypassUnavailable,
+			repeatUnavailable,
+			unchanged,
+		};
+	};
+
+	return {
+		/**
+		 * Applies a tone configuration, migrating any tone whose version moved.
+		 *
+		 * Applying an unchanged configuration performs no work at all: no channel
+		 * is recreated and no migration is triggered.
+		 */
+		apply(
+			tones: readonly ToneDeclaration[],
+			groups: readonly ChannelGroup[] = [],
+		): Promise<ChannelApplyResult> {
+			// The declared channels are read once for the whole apply rather than once
+			// per tone, when the engine can hold them (NOT-08).
+			const run = () => applyTones(tones, groups);
+			return deps.engine.withChannelSnapshot ? deps.engine.withChannelSnapshot(run) : run();
 		},
 
 		/** Which version of each tone this device actually holds. */
@@ -278,8 +288,16 @@ async function findOrphans(
 	tones: readonly ToneDeclaration[],
 ): Promise<readonly string[]> {
 	const declared = new Set(tones.map(tone => tone.id));
+	// Only tones this package once applied can leave orphans (NOT-05). An entry
+	// with no tone metadata was scheduled by other code through the same engine,
+	// and a tone the ledger has never seen is not ours to judge either: cancelling
+	// on "not in this call's list" silently deleted other libraries' notifications,
+	// and a feature module's own when it applied only its subset of tones.
+	const onceApplied = new Set(deps.state.read().migrationLedger.map(entry => entry.toneId));
 	const pending = await deps.engine.getPending();
-	return pending.filter(entry => !declared.has(entry.tone)).map(entry => entry.id);
+	return pending
+		.filter(entry => entry.tone !== '' && onceApplied.has(entry.tone) && !declared.has(entry.tone))
+		.map(entry => entry.id);
 }
 
 export type Channels = ReturnType<typeof createChannels>;

package/src/channel/tone-map.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ResolvedTone, ToneDeclaration, ToneUrgency } from '../contract/channel';
+import { fnv1a, hex8 } from '../contract/hash';
 
 type AndroidImportance = ResolvedTone['android']['importance'];
 type IosInterruption = ResolvedTone['ios']['interruptionLevel'];
@@ -109,16 +110,7 @@ export function toneLabelFingerprint(tone: ToneDeclaration): string {
 	// of the two would never get its correction.
 	const source = `${tone.name}\u0000${tone.description ?? ''}`;
 
-	// FNV-1a. Bitwise operators are the algorithm, not a micro-optimisation:
-	// arithmetic equivalents would not wrap to 32 bits and the hash would drift.
-	/* eslint-disable no-bitwise */
-	let hash = 0x811c9dc5;
-	for (let index = 0; index < source.length; index += 1) {
-		hash ^= source.codePointAt(index) ?? 0;
-		hash = Math.imul(hash, 0x01000193) >>> 0;
-	}
-	return (hash >>> 0).toString(16).padStart(8, '0');
-	/* eslint-enable no-bitwise */
+	return hex8(fnv1a(source));
 }
 
 /** Builds a lookup over a declared configuration. */

package/src/contract/errors.ts

@@ -73,6 +73,12 @@ export const DIAGNOSTIC_CODES = {
 	/** The durable store could not open; state lasts for this session only. */
 	STATE_STORE_DEGRADED: 'STATE_STORE_DEGRADED',
 	STATE_CAP_EVICTED: 'STATE_CAP_EVICTED',
+	/**
+	 * A ledger holds more live entries than its cap (0.6.0). They are all kept:
+	 * dropping a live series or channel record would lose a migration or reset a
+	 * series count. Reported so the cap can be raised or the app's use reviewed.
+	 */
+	STATE_CAP_EXCEEDED: 'STATE_CAP_EXCEEDED',
 
 	// --- Volume --------------------------------------------------------------
 	BURST_THRESHOLD_EXCEEDED: 'BURST_THRESHOLD_EXCEEDED',
@@ -129,6 +135,7 @@ export const NON_FAILURE_CODES: readonly DiagnosticCode[] = Object.freeze([
 	DIAGNOSTIC_CODES.PAYLOAD_VERSION_SKEW,
 	DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE,
 	DIAGNOSTIC_CODES.STATE_CAP_EVICTED,
+	DIAGNOSTIC_CODES.STATE_CAP_EXCEEDED,
 	DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT,
 	DIAGNOSTIC_CODES.BACKGROUND_RESTRICTION_UNKNOWN,
 	DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE,

package/src/contract/hash.ts

@@ -0,0 +1,26 @@
+/**
+ * FNV-1a, 32-bit: the package's one hash (NOT-19). Deterministic,
+ * dependency-free, and stable across releases.
+ *
+ * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
+ * equivalents would not wrap to 32 bits. Stability matters: a marker id or a
+ * label fingerprint that changed between releases would orphan every marker
+ * already scheduled, or refresh every channel label once more.
+ */
+export const FNV_OFFSET_BASIS = 0x811c9dc5;
+
+/* eslint-disable no-bitwise */
+export function fnv1a(value: string, basis: number = FNV_OFFSET_BASIS): 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 */
+
+/** Eight lowercase hex digits. */
+export function hex8(value: number): string {
+	return value.toString(16).padStart(8, '0');
+}