@chipmobilesdk/rn-notification 0.4.0 → 0.4.1

package/src/schedule/resolve-moment.ts

@@ -1,80 +1,80 @@
-/**
- * Delivery moment resolution.
- *
- * Two rules, and they are two sides of one decision rather than a threshold:
- * a moment more than the tolerance in the past is a caller error and is
- * refused; a moment a few seconds in the past is a processing delay and is
- * delivered promptly. Both outcomes are reported, so a caller never has to
- * guess which happened.
- *
- * Sixty seconds is long enough to absorb reconciling a large desired set, cold
- * start work, and clock skew, and short enough that a genuinely stale schedule
- * is still caught rather than fired at the user minutes late with no
- * explanation.
- */
-
-import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-import type { DeliveryMoment } from '../contract/notification';
-
-export const PAST_TOLERANCE_MS = 60_000;
-
-export type MomentResolution =
-	| { readonly kind: 'future'; readonly at: number }
-	| { readonly kind: 'immediate'; readonly at: number; readonly lateBy: number };
-
-/**
- * Classifies a resolved instant against now.
- *
- * Takes an already-anchored instant: anchoring decides *which* instant a moment
- * means, and this decides whether that instant is usable. Keeping them separate
- * is what lets each be tested without the other.
- */
-export function resolveMoment(resolvedAt: number, now: number): MomentResolution {
-	if (!Number.isFinite(resolvedAt)) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
-			'A delivery moment must be a finite epoch-millisecond timestamp.',
-			{ received: String(resolvedAt) },
-		);
-	}
-
-	if (resolvedAt >= now) {
-		return { kind: 'future', at: resolvedAt };
-	}
-
-	const lateBy = now - resolvedAt;
-
-	if (lateBy <= PAST_TOLERANCE_MS) {
-		return { kind: 'immediate', at: now, lateBy };
-	}
-
-	throw new NotificationError(
-		DIAGNOSTIC_CODES.MOMENT_IN_PAST,
-		`Delivery moment is ${Math.round(lateBy / 1000)}s in the past, beyond the ${PAST_TOLERANCE_MS / 1000}s tolerance. ` +
-			'It was not scheduled, because handing it to the platform would fire it immediately without explanation.',
-		{ lateByMs: lateBy, toleranceMs: PAST_TOLERANCE_MS },
-	);
-}
-
-/** Validates the shape of a caller-supplied moment before anchoring resolves it. */
-export function validateMoment(moment: DeliveryMoment): void {
-	if (typeof moment.at !== 'number' || !Number.isFinite(moment.at)) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
-			'A delivery moment must carry a finite epoch-millisecond `at` value.',
-			{ received: typeof moment.at },
-		);
-	}
-
-	if (
-		moment.anchoring !== undefined &&
-		moment.anchoring !== 'wallClock' &&
-		moment.anchoring !== 'absolute'
-	) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
-			'Anchoring must be either "wallClock" or "absolute".',
-			{ received: String(moment.anchoring) },
-		);
-	}
-}
+/**
+ * Delivery moment resolution.
+ *
+ * Two rules, and they are two sides of one decision rather than a threshold:
+ * a moment more than the tolerance in the past is a caller error and is
+ * refused; a moment a few seconds in the past is a processing delay and is
+ * delivered promptly. Both outcomes are reported, so a caller never has to
+ * guess which happened.
+ *
+ * Sixty seconds is long enough to absorb reconciling a large desired set, cold
+ * start work, and clock skew, and short enough that a genuinely stale schedule
+ * is still caught rather than fired at the user minutes late with no
+ * explanation.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import type { DeliveryMoment } from '../contract/notification';
+
+export const PAST_TOLERANCE_MS = 60_000;
+
+export type MomentResolution =
+	| { readonly kind: 'future'; readonly at: number }
+	| { readonly kind: 'immediate'; readonly at: number; readonly lateBy: number };
+
+/**
+ * Classifies a resolved instant against now.
+ *
+ * Takes an already-anchored instant: anchoring decides *which* instant a moment
+ * means, and this decides whether that instant is usable. Keeping them separate
+ * is what lets each be tested without the other.
+ */
+export function resolveMoment(resolvedAt: number, now: number): MomentResolution {
+	if (!Number.isFinite(resolvedAt)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+			'A delivery moment must be a finite epoch-millisecond timestamp.',
+			{ received: String(resolvedAt) },
+		);
+	}
+
+	if (resolvedAt >= now) {
+		return { kind: 'future', at: resolvedAt };
+	}
+
+	const lateBy = now - resolvedAt;
+
+	if (lateBy <= PAST_TOLERANCE_MS) {
+		return { kind: 'immediate', at: now, lateBy };
+	}
+
+	throw new NotificationError(
+		DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+		`Delivery moment is ${Math.round(lateBy / 1000)}s in the past, beyond the ${PAST_TOLERANCE_MS / 1000}s tolerance. ` +
+			'It was not scheduled, because handing it to the platform would fire it immediately without explanation.',
+		{ lateByMs: lateBy, toleranceMs: PAST_TOLERANCE_MS },
+	);
+}
+
+/** Validates the shape of a caller-supplied moment before anchoring resolves it. */
+export function validateMoment(moment: DeliveryMoment): void {
+	if (typeof moment.at !== 'number' || !Number.isFinite(moment.at)) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+			'A delivery moment must carry a finite epoch-millisecond `at` value.',
+			{ received: typeof moment.at },
+		);
+	}
+
+	if (
+		moment.anchoring !== undefined &&
+		moment.anchoring !== 'wallClock' &&
+		moment.anchoring !== 'absolute'
+	) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.MOMENT_IN_PAST,
+			'Anchoring must be either "wallClock" or "absolute".',
+			{ received: String(moment.anchoring) },
+		);
+	}
+}

package/src/schedule/validate-content.ts

@@ -1,111 +1,111 @@
-/**
- * Content validation.
- *
- * The package passes content through **unchanged** and never truncates it.
- * Display truncation is the platform's decision and differs between them; a
- * library that pre-truncated would be guessing at a rule it does not own, and
- * would corrupt content that would have displayed fine.
- *
- * What it does refuse is content over the platform's hard payload limit, where
- * the alternative is not a shortened notification but a failed or undefined
- * delivery. That is a real error and is reported as one, before any platform
- * call.
- */
-
-import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-import type { NotificationContent } from '../contract/notification';
-
-/**
- * Hard payload ceilings.
- *
- * These are *not* display limits. A title longer than a phone shows is fine and
- * is passed through; the README documents where each platform visually
- * truncates so a caller can decide for itself.
- *
- * The total is deliberately lower than the sum of the parts, so it actually
- * binds — a per-field check that can never be exceeded in aggregate would be
- * dead code. It sits under the 4 KB payload budget both platforms enforce,
- * leaving headroom for the routing payload that shares it.
- */
-export const CONTENT_LIMITS = {
-	maxTitleBytes: 512,
-	maxBodyBytes: 3072,
-	maxSubtitleBytes: 512,
-	maxTotalBytes: 3584,
-} as const;
-
-/** UTF-8 byte length — the unit the platforms actually bound. */
-export function byteLength(value: string): number {
-	let bytes = 0;
-	for (const char of value) {
-		const code = char.codePointAt(0) ?? 0;
-		if (code <= 0x7f) bytes += 1;
-		else if (code <= 0x7ff) bytes += 2;
-		else if (code <= 0xffff) bytes += 3;
-		else bytes += 4;
-	}
-	return bytes;
-}
-
-function requireString(value: unknown, field: string): string {
-	if (typeof value !== 'string') {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
-			`Notification content field "${field}" must be a string of resolved display text. The package performs no locale resolution.`,
-			{ field, received: typeof value },
-		);
-	}
-	return value;
-}
-
-/**
- * Validates content and returns it **byte-identical**.
- *
- * The return value is the same object reference where possible, so nothing
- * downstream can mistake this for a transformation step.
- */
-export function validateContent(content: NotificationContent): NotificationContent {
-	const title = requireString(content.title, 'title');
-	const body = requireString(content.body, 'body');
-	const subtitle =
-		content.subtitle === undefined ? undefined : requireString(content.subtitle, 'subtitle');
-
-	if (title.length === 0 && body.length === 0) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
-			'A notification must carry a title or a body; both were empty.',
-			{ field: 'title+body' },
-		);
-	}
-
-	const checks: [string, string, number][] = [
-		['title', title, CONTENT_LIMITS.maxTitleBytes],
-		['body', body, CONTENT_LIMITS.maxBodyBytes],
-	];
-	if (subtitle !== undefined) {
-		checks.push(['subtitle', subtitle, CONTENT_LIMITS.maxSubtitleBytes]);
-	}
-
-	for (const [field, value, limit] of checks) {
-		const size = byteLength(value);
-		if (size > limit) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
-				`Notification "${field}" is ${size} bytes, over the ${limit}-byte platform limit. ` +
-					'It was refused rather than truncated, because the package does not decide where a caller\'s content should be cut.',
-				{ field, bytes: size, limit },
-			);
-		}
-	}
-
-	const total = byteLength(title) + byteLength(body) + (subtitle ? byteLength(subtitle) : 0);
-	if (total > CONTENT_LIMITS.maxTotalBytes) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
-			`Notification content totals ${total} bytes, over the ${CONTENT_LIMITS.maxTotalBytes}-byte payload limit.`,
-			{ field: 'total', bytes: total, limit: CONTENT_LIMITS.maxTotalBytes },
-		);
-	}
-
-	return content;
-}
+/**
+ * Content validation.
+ *
+ * The package passes content through **unchanged** and never truncates it.
+ * Display truncation is the platform's decision and differs between them; a
+ * library that pre-truncated would be guessing at a rule it does not own, and
+ * would corrupt content that would have displayed fine.
+ *
+ * What it does refuse is content over the platform's hard payload limit, where
+ * the alternative is not a shortened notification but a failed or undefined
+ * delivery. That is a real error and is reported as one, before any platform
+ * call.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import type { NotificationContent } from '../contract/notification';
+
+/**
+ * Hard payload ceilings.
+ *
+ * These are *not* display limits. A title longer than a phone shows is fine and
+ * is passed through; the README documents where each platform visually
+ * truncates so a caller can decide for itself.
+ *
+ * The total is deliberately lower than the sum of the parts, so it actually
+ * binds — a per-field check that can never be exceeded in aggregate would be
+ * dead code. It sits under the 4 KB payload budget both platforms enforce,
+ * leaving headroom for the routing payload that shares it.
+ */
+export const CONTENT_LIMITS = {
+	maxTitleBytes: 512,
+	maxBodyBytes: 3072,
+	maxSubtitleBytes: 512,
+	maxTotalBytes: 3584,
+} as const;
+
+/** UTF-8 byte length — the unit the platforms actually bound. */
+export function byteLength(value: string): number {
+	let bytes = 0;
+	for (const char of value) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code <= 0x7f) bytes += 1;
+		else if (code <= 0x7ff) bytes += 2;
+		else if (code <= 0xffff) bytes += 3;
+		else bytes += 4;
+	}
+	return bytes;
+}
+
+function requireString(value: unknown, field: string): string {
+	if (typeof value !== 'string') {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+			`Notification content field "${field}" must be a string of resolved display text. The package performs no locale resolution.`,
+			{ field, received: typeof value },
+		);
+	}
+	return value;
+}
+
+/**
+ * Validates content and returns it **byte-identical**.
+ *
+ * The return value is the same object reference where possible, so nothing
+ * downstream can mistake this for a transformation step.
+ */
+export function validateContent(content: NotificationContent): NotificationContent {
+	const title = requireString(content.title, 'title');
+	const body = requireString(content.body, 'body');
+	const subtitle =
+		content.subtitle === undefined ? undefined : requireString(content.subtitle, 'subtitle');
+
+	if (title.length === 0 && body.length === 0) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+			'A notification must carry a title or a body; both were empty.',
+			{ field: 'title+body' },
+		);
+	}
+
+	const checks: [string, string, number][] = [
+		['title', title, CONTENT_LIMITS.maxTitleBytes],
+		['body', body, CONTENT_LIMITS.maxBodyBytes],
+	];
+	if (subtitle !== undefined) {
+		checks.push(['subtitle', subtitle, CONTENT_LIMITS.maxSubtitleBytes]);
+	}
+
+	for (const [field, value, limit] of checks) {
+		const size = byteLength(value);
+		if (size > limit) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+				`Notification "${field}" is ${size} bytes, over the ${limit}-byte platform limit. ` +
+					"It was refused rather than truncated, because the package does not decide where a caller's content should be cut.",
+				{ field, bytes: size, limit },
+			);
+		}
+	}
+
+	const total = byteLength(title) + byteLength(body) + (subtitle ? byteLength(subtitle) : 0);
+	if (total > CONTENT_LIMITS.maxTotalBytes) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.CONTENT_TOO_LARGE,
+			`Notification content totals ${total} bytes, over the ${CONTENT_LIMITS.maxTotalBytes}-byte payload limit.`,
+			{ field: 'total', bytes: total, limit: CONTENT_LIMITS.maxTotalBytes },
+		);
+	}
+
+	return content;
+}

package/src/schedule/validate-identifier.ts

@@ -1,126 +1,126 @@
-/**
- * Identifier validation.
- *
- * Identity is the caller's contract: only the caller can derive an identifier
- * reproducibly from its own data, so the package never generates one.
- *
- * The charset is composite-friendly because real derived keys are hierarchical
- * — `task:1234:reminder:2`. A charset that forced encoding of natural keys
- * would work against caller-supplied identity being readable and reproducible,
- * which is most of its value.
- *
- * Nothing is normalized, trimmed, case-folded, or hashed. Two identifiers
- * differing in any character are different identifiers, and the value visible
- * at the platform boundary is exactly what the caller supplied — which is what
- * lets a notification be traced back to the data that produced it.
- */
-
-import { DIAGNOSTIC_CODES, NotificationError, type DiagnosticCode } from '../contract/errors';
-import { REPEAT_STOP_PREFIX } from '../repeat/marker';
-
-export const MAX_IDENTIFIER_LENGTH = 128;
-
-/** `A–Z a–z 0–9 . _ - : /` — printable, unambiguous, and safe at every boundary. */
-const IDENTIFIER_PATTERN = /^[A-Za-z0-9._:/-]+$/;
-
-/** Reports the first offending character so a failure is actionable without echoing the value. */
-function firstInvalidCharacter(value: string): { char: string; index: number } | undefined {
-	for (let index = 0; index < value.length; index += 1) {
-		const char = value[index];
-		if (!/[A-Za-z0-9._:/-]/.test(char)) {
-			return { char, index };
-		}
-	}
-	return undefined;
-}
-
-export type IdentifierKind = 'id' | 'ownerTag' | 'groupTag' | 'seriesId' | 'actionId';
-
-const EMPTY_CODE: Record<IdentifierKind, DiagnosticCode> = {
-	id: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
-	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
-	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
-	seriesId: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
-	actionId: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
-};
-
-const LENGTH_CODE: Record<IdentifierKind, DiagnosticCode> = {
-	id: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
-	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
-	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
-	seriesId: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
-	actionId: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
-};
-
-const CHARSET_CODE: Record<IdentifierKind, DiagnosticCode> = {
-	id: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
-	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
-	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
-	seriesId: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
-	actionId: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
-};
-
-/**
- * Throws a typed error naming the violated rule.
- *
- * The offending character and its position are reported; the value itself never
- * is, because an identifier can carry user data a caller derived it from.
- */
-export function validateIdentifier(value: unknown, kind: IdentifierKind = 'id'): string {
-	if (typeof value !== 'string' || value.length === 0) {
-		throw new NotificationError(
-			EMPTY_CODE[kind],
-			`A ${kind} must be a non-empty string supplied by the caller. The package never generates one.`,
-			{ kind, received: typeof value },
-		);
-	}
-
-	if (value.length > MAX_IDENTIFIER_LENGTH) {
-		throw new NotificationError(
-			LENGTH_CODE[kind],
-			`A ${kind} must be at most ${MAX_IDENTIFIER_LENGTH} characters.`,
-			{ kind, length: value.length, max: MAX_IDENTIFIER_LENGTH },
-		);
-	}
-
-	if (value.startsWith(REPEAT_STOP_PREFIX)) {
-		// Not a style rule. Repeat expiry cancels markers by identifier, so a
-		// consumer identifier that looks like one would be deleted out from under
-		// a real notification.
-		throw new NotificationError(
-			CHARSET_CODE[kind],
-			`A ${kind} may not begin with "${REPEAT_STOP_PREFIX}" — that prefix is reserved for the package's own repeat-expiry markers, which are cancelled automatically.`,
-			{ kind, reservedPrefix: REPEAT_STOP_PREFIX },
-		);
-	}
-
-	if (!IDENTIFIER_PATTERN.test(value)) {
-		const offender = firstInvalidCharacter(value);
-		throw new NotificationError(
-			CHARSET_CODE[kind],
-			`A ${kind} may contain only A-Z, a-z, 0-9, and the separators . _ - : / — whitespace and control characters are not permitted.`,
-			{ kind, index: offender?.index, charCode: offender?.char.charCodeAt(0) },
-		);
-	}
-
-	return value;
-}
-
-/** Non-throwing form, for validating a batch without unwinding on the first failure. */
-export function isValidIdentifier(value: unknown): value is string {
-	return (
-		typeof value === 'string' &&
-		value.length > 0 &&
-		value.length <= MAX_IDENTIFIER_LENGTH &&
-		IDENTIFIER_PATTERN.test(value)
-	);
-}
-
-/** Validates an optional tag, returning undefined when absent rather than failing. */
-export function validateOptionalTag(
-	value: string | undefined,
-	kind: Extract<IdentifierKind, 'ownerTag' | 'groupTag'>,
-): string | undefined {
-	if (value === undefined) return undefined;
-	return validateIdentifier(value, kind);
-}
+/**
+ * Identifier validation.
+ *
+ * Identity is the caller's contract: only the caller can derive an identifier
+ * reproducibly from its own data, so the package never generates one.
+ *
+ * The charset is composite-friendly because real derived keys are hierarchical
+ * — `task:1234:reminder:2`. A charset that forced encoding of natural keys
+ * would work against caller-supplied identity being readable and reproducible,
+ * which is most of its value.
+ *
+ * Nothing is normalized, trimmed, case-folded, or hashed. Two identifiers
+ * differing in any character are different identifiers, and the value visible
+ * at the platform boundary is exactly what the caller supplied — which is what
+ * lets a notification be traced back to the data that produced it.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError, type DiagnosticCode } from '../contract/errors';
+import { REPEAT_STOP_PREFIX } from '../repeat/marker';
+
+export const MAX_IDENTIFIER_LENGTH = 128;
+
+/** `A–Z a–z 0–9 . _ - : /` — printable, unambiguous, and safe at every boundary. */
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9._:/-]+$/;
+
+/** Reports the first offending character so a failure is actionable without echoing the value. */
+function firstInvalidCharacter(value: string): { char: string; index: number } | undefined {
+	for (let index = 0; index < value.length; index += 1) {
+		const char = value[index];
+		if (!/[A-Za-z0-9._:/-]/.test(char)) {
+			return { char, index };
+		}
+	}
+	return undefined;
+}
+
+export type IdentifierKind = 'id' | 'ownerTag' | 'groupTag' | 'seriesId' | 'actionId';
+
+const EMPTY_CODE: Record<IdentifierKind, DiagnosticCode> = {
+	id: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
+	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
+	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
+	seriesId: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
+	actionId: DIAGNOSTIC_CODES.INVALID_ID_EMPTY,
+};
+
+const LENGTH_CODE: Record<IdentifierKind, DiagnosticCode> = {
+	id: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
+	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
+	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
+	seriesId: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
+	actionId: DIAGNOSTIC_CODES.INVALID_ID_LENGTH,
+};
+
+const CHARSET_CODE: Record<IdentifierKind, DiagnosticCode> = {
+	id: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
+	ownerTag: DIAGNOSTIC_CODES.INVALID_OWNER_TAG,
+	groupTag: DIAGNOSTIC_CODES.INVALID_GROUP_TAG,
+	seriesId: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
+	actionId: DIAGNOSTIC_CODES.INVALID_ID_CHARSET,
+};
+
+/**
+ * Throws a typed error naming the violated rule.
+ *
+ * The offending character and its position are reported; the value itself never
+ * is, because an identifier can carry user data a caller derived it from.
+ */
+export function validateIdentifier(value: unknown, kind: IdentifierKind = 'id'): string {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new NotificationError(
+			EMPTY_CODE[kind],
+			`A ${kind} must be a non-empty string supplied by the caller. The package never generates one.`,
+			{ kind, received: typeof value },
+		);
+	}
+
+	if (value.length > MAX_IDENTIFIER_LENGTH) {
+		throw new NotificationError(
+			LENGTH_CODE[kind],
+			`A ${kind} must be at most ${MAX_IDENTIFIER_LENGTH} characters.`,
+			{ kind, length: value.length, max: MAX_IDENTIFIER_LENGTH },
+		);
+	}
+
+	if (value.startsWith(REPEAT_STOP_PREFIX)) {
+		// Not a style rule. Repeat expiry cancels markers by identifier, so a
+		// consumer identifier that looks like one would be deleted out from under
+		// a real notification.
+		throw new NotificationError(
+			CHARSET_CODE[kind],
+			`A ${kind} may not begin with "${REPEAT_STOP_PREFIX}" — that prefix is reserved for the package's own repeat-expiry markers, which are cancelled automatically.`,
+			{ kind, reservedPrefix: REPEAT_STOP_PREFIX },
+		);
+	}
+
+	if (!IDENTIFIER_PATTERN.test(value)) {
+		const offender = firstInvalidCharacter(value);
+		throw new NotificationError(
+			CHARSET_CODE[kind],
+			`A ${kind} may contain only A-Z, a-z, 0-9, and the separators . _ - : / — whitespace and control characters are not permitted.`,
+			{ kind, index: offender?.index, charCode: offender?.char.charCodeAt(0) },
+		);
+	}
+
+	return value;
+}
+
+/** Non-throwing form, for validating a batch without unwinding on the first failure. */
+export function isValidIdentifier(value: unknown): value is string {
+	return (
+		typeof value === 'string' &&
+		value.length > 0 &&
+		value.length <= MAX_IDENTIFIER_LENGTH &&
+		IDENTIFIER_PATTERN.test(value)
+	);
+}
+
+/** Validates an optional tag, returning undefined when absent rather than failing. */
+export function validateOptionalTag(
+	value: string | undefined,
+	kind: Extract<IdentifierKind, 'ownerTag' | 'groupTag'>,
+): string | undefined {
+	if (value === undefined) return undefined;
+	return validateIdentifier(value, kind);
+}