@chipmobilesdk/rn-local-db 0.2.1 → 0.4.0

package/src/adapter/schema-sync.ts

@@ -0,0 +1,155 @@
+/**
+ * Bringing the physical tables in line with the declared schema, and skipping
+ * that work when nothing changed (LDB-07, LDB-11).
+ *
+ * Until 0.4.0 every open ran the whole set — CREATE TABLE, PRAGMA table_info,
+ * CREATE INDEX per index, for every collection — some sixty native round-trips
+ * for ten collections, on the startup path. The applied schema is now recorded
+ * in `_meta`; an open whose declaration matches it runs no DDL at all.
+ */
+import type { DatabaseConfig } from '../contract/config';
+import type { CollectionSchema } from '../contract/schema';
+import { ensureAttachmentTable } from '../artifacts/store';
+import type { Connection } from '../sqlite/connection';
+import {
+	addColumnSql,
+	createIndexSql,
+	createTableSql,
+	physicalIndexName,
+} from '../sqlite/row-codec';
+import { text } from '../sqlite/values';
+
+/** Bumped whenever the DDL this package generates changes, so it is re-applied once. */
+const DDL_VERSION = 1;
+const FINGERPRINT_KEY = 'schema_fingerprint';
+
+/** What was declared, and by which generation of this package's DDL. */
+function fingerprintOf(config: DatabaseConfig): string {
+	return JSON.stringify([DDL_VERSION, config.collections]);
+}
+
+async function appliedFingerprint(connection: Connection): Promise<string | null> {
+	try {
+		const result = await connection.execute('SELECT value FROM _meta WHERE key = ?', [
+			FINGERPRINT_KEY,
+		]);
+		const row = result.rows[0];
+		return row ? text(row.value) : null;
+	} catch {
+		// A database that has never been opened has no `_meta` yet.
+		return null;
+	}
+}
+
+/** `unique` and the column list of an index, read back from the statement SQLite stored. */
+function definitionOf(sql: string): string {
+	const unique = /^\s*CREATE\s+UNIQUE\s/i.test(sql);
+	const columns = sql.slice(sql.lastIndexOf('(') + 1, sql.lastIndexOf(')')).replace(/["\s]/g, '');
+	return `${unique ? 'unique' : 'plain'}:${columns}`;
+}
+
+/**
+ * Indexes follow their declaration (LDB-11). `CREATE INDEX IF NOT EXISTS` keyed
+ * on the name alone meant that adding `unique: true` to an existing index, or
+ * changing its fields, did nothing, and an index no longer declared stayed
+ * forever. An index whose definition changed is dropped and recreated, and one
+ * of this package's that is no longer declared is dropped. Only indexes carrying
+ * the collection's own prefix are touched.
+ */
+async function syncIndexes(connection: Connection, schema: CollectionSchema): Promise<void> {
+	const table = `c_${schema.name}`;
+	const existing = await connection.execute(
+		"SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL",
+		[table],
+	);
+	const current = new Map(existing.rows.map(row => [text(row.name), text(row.sql)]));
+	const wanted = new Map(
+		createIndexSql(schema).map(statement => {
+			const name = /INDEX IF NOT EXISTS "([^"]+)"/.exec(statement)?.[1] ?? '';
+			return [name, statement] as const;
+		}),
+	);
+
+	for (const index of schema.indexes ?? []) {
+		// Indexes created before 0.2.0 carry the bare declared name; they are
+		// recreated under the collection-scoped one. No row data moves.
+		if (current.has(index.name) && index.name !== physicalIndexName(schema, index.name)) {
+			await connection.execute(`DROP INDEX IF EXISTS "${index.name}"`);
+		}
+	}
+	for (const [name, sql] of current) {
+		const statement = wanted.get(name);
+		const ours = name.startsWith(`${table}__`);
+		if (
+			(statement === undefined && ours) ||
+			(statement && definitionOf(statement) !== definitionOf(sql))
+		) {
+			await connection.execute(`DROP INDEX IF EXISTS "${name}"`);
+		}
+	}
+	for (const statement of wanted.values()) {
+		await connection.execute(statement);
+	}
+}
+
+/**
+ * Adding a column rather than recreating the table is what makes declaring a
+ * new queryable field non-destructive: the payload already holds the value, so
+ * the new column is backfilled from it and no record is rewritten by hand
+ * (research.md R6).
+ */
+async function ensureCollection(connection: Connection, schema: CollectionSchema): Promise<void> {
+	await connection.execute(createTableSql(schema));
+
+	const info = await connection.execute(`PRAGMA table_info("c_${schema.name}")`);
+	const present = new Set(info.rows.map(row => text(row.name)));
+
+	for (const field of schema.fields ?? []) {
+		const column = `f_${field.name}`;
+		if (present.has(column)) {
+			continue;
+		}
+		await connection.execute(addColumnSql(schema, field));
+		// The same projection a write applies (`projectValue`): an object or an
+		// array projects to NULL. A bare json_extract backfilled those as JSON
+		// text, so a filter matched old records and new ones differently (LDB-11).
+		const path = `'$."${field.name}"'`;
+		await connection.execute(
+			`UPDATE "c_${schema.name}" SET "${column}" = CASE WHEN json_type(payload, ${path}) IN ('object', 'array') THEN NULL ELSE json_extract(payload, ${path}) END`,
+		);
+	}
+
+	await syncIndexes(connection, schema);
+}
+
+export interface SchemaSync {
+	/** True when the stored schema already matched, so `_meta` exists and no DDL ran. */
+	readonly unchanged: boolean;
+	/** Records the declaration as applied. Call once the open has succeeded. */
+	record(): Promise<void>;
+}
+
+export async function syncSchema(
+	connection: Connection,
+	config: DatabaseConfig,
+): Promise<SchemaSync> {
+	const fingerprint = fingerprintOf(config);
+	if ((await appliedFingerprint(connection)) === fingerprint) {
+		return { unchanged: true, record: async () => undefined };
+	}
+
+	for (const schema of config.collections) {
+		await ensureCollection(connection, schema);
+	}
+	await ensureAttachmentTable(connection);
+
+	return {
+		unchanged: false,
+		async record() {
+			await connection.execute(
+				'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+				[FINGERPRINT_KEY, fingerprint],
+			);
+		},
+	};
+}

package/src/artifacts/cascade.ts

@@ -19,7 +19,6 @@ import type { Executor } from '../sqlite/connection';
 import { artifactPath } from './paths';
 import {
 	deleteReference,
-	listReferences,
 	listReferencesFor,
 	type ArtifactContext,
 	type DeferredUnlinks,
@@ -99,16 +98,3 @@ export async function cascadeForOwner(
 		deferred,
 	);
 }
-
-/** Everything in the scope, for scope deletion. */
-export async function cascadeAll(
-	context: ArtifactContext,
-	executor: Executor,
-): Promise<DeletionOutcome> {
-	const references = await listReferences(executor);
-	return removeAll(
-		context,
-		executor,
-		references.map(reference => reference.id),
-	);
-}

package/src/artifacts/store.ts

@@ -152,6 +152,12 @@ async function writePlaintext(path: string, content: string): Promise<void> {
 	await fileSystem().writeFile(path, content, 'base64');
 }
 
+/** Where an artifact's bytes come from: how many, and any one chunk of them. */
+type ByteSource = {
+	size: number;
+	chunk(offset: number, length: number): Promise<Uint8Array>;
+};
+
 /**
  * Encrypted write, one chunk in flight.
  *
@@ -159,43 +165,87 @@ async function writePlaintext(path: string, content: string): Promise<void> {
  * plaintext length — are all known from the input length before any
  * encryption happens. Only the tags depend on the ciphertext, and they follow
  * their own chunk, so the whole write is append-only and peak memory is one
- * chunk regardless of artifact size (FR-107a).
+ * chunk regardless of artifact size when the source is a file (FR-107a).
  */
 async function writeEncrypted(
 	path: string,
 	key: Uint8Array,
-	plaintext: Uint8Array,
+	source: ByteSource,
 ): Promise<{ chunkSize: number; chunkCount: number }> {
-	const header = headerFor(plaintext.length, Budgets.ARTIFACT_CHUNK_BYTES);
+	const header = headerFor(source.size, Budgets.ARTIFACT_CHUNK_BYTES);
 	await fileSystem().writeFile(path, bytesToBase64(encodeHeader(header)), 'base64');
 
 	for (let index = 0; index < header.chunkCount; index += 1) {
-		const start = index * header.chunkSize;
-		const chunk = plaintext.subarray(start, start + chunkPlaintextLength(header, index));
+		const chunk = await source.chunk(index * header.chunkSize, chunkPlaintextLength(header, index));
 		await fileSystem().appendFile(path, bytesToBase64(encryptChunk(key, index, chunk)), 'base64');
 	}
 
 	return { chunkSize: header.chunkSize, chunkCount: header.chunkCount };
 }
 
+function sourceFileOf(input: AttachmentInput): string | null {
+	if (typeof input.sourcePath !== 'string') {
+		return null;
+	}
+	return input.sourcePath.startsWith('file://')
+		? input.sourcePath.slice('file://'.length)
+		: input.sourcePath;
+}
+
+/**
+ * The input as something to read from. A base64 `content` is decoded whole,
+ * which is the cost of that form; a `sourcePath` is only measured here and
+ * read a chunk at a time, or not read by JS at all (LDB-09).
+ */
+async function byteSourceFor(input: AttachmentInput): Promise<ByteSource> {
+	const file = sourceFileOf(input);
+	if (file === null) {
+		if (typeof input.content !== 'string') {
+			raise(DiagnosticCodes.CONFIG_INVALID, {
+				message: 'an attachment needs content or sourcePath',
+				detail: { attachmentId: input.id },
+			});
+		}
+		const plaintext = base64ToBytes(input.content);
+		return {
+			size: plaintext.length,
+			chunk: async (offset, length) => plaintext.subarray(offset, offset + length),
+		};
+	}
+	let size: number;
+	try {
+		size = (await fileSystem().stat(file)).size;
+	} catch (error) {
+		raiseNative(error, { operation: 'attachment' });
+	}
+	return {
+		size,
+		chunk: async (offset, length) =>
+			base64ToBytes(await fileSystem().read(file, length, offset, 'base64')),
+	};
+}
+
 export async function writeArtifact(
 	context: ArtifactContext,
 	input: AttachmentInput,
 ): Promise<AttachmentReference> {
 	throwIfFaulted('attachmentWrite');
-	const plaintext = base64ToBytes(input.content);
-	assertArtifactWithinBudget(input.id, plaintext.length);
+	const source = await byteSourceFor(input);
+	assertArtifactWithinBudget(input.id, source.size);
 
 	const path = artifactPath(context.layout, context.scopeKey, input.id);
 	const key = context.artifactKey(input.id);
+	const file = sourceFileOf(input);
 
 	let chunking: { chunkSize: number; chunkCount: number } | undefined;
 	try {
 		await fileSystem().mkdir(artifactsDirectory(context.layout, context.scopeKey));
 		if (key) {
-			chunking = await writeEncrypted(path, key, plaintext);
+			chunking = await writeEncrypted(path, key, source);
+		} else if (file !== null) {
+			await fileSystem().copyFile(file, path);
 		} else {
-			await writePlaintext(path, input.content);
+			await writePlaintext(path, input.content as string);
 		}
 	} catch (error) {
 		// A partial file with no reference is an orphan reconciliation can
@@ -207,7 +257,7 @@ export async function writeArtifact(
 	const reference: AttachmentReference = {
 		id: input.id,
 		contentType: input.contentType,
-		size: plaintext.length,
+		size: source.size,
 		createdAt: context.now(),
 	};
 	if (input.owner) {

package/src/contract/attachment.ts

@@ -11,18 +11,39 @@ export type AttachmentOwner = {
 	id: string;
 };
 
-export type AttachmentInput = {
+type AttachmentDescription = {
 	id: string;
 	/** Absent means the attachment belongs to the scope rather than a record. */
-	owner?: AttachmentOwner;
+	owner?: AttachmentOwner | undefined;
 	contentType: string;
-	/** Base64 content. Written incrementally; never held whole when encrypted. */
-	content: string;
 };
 
+/**
+ * Where the bytes come from. Exactly one of the two.
+ *
+ * `sourcePath` is the one to use for anything large — a photo, a recording.
+ * The file is copied (or, when encrypted, read and encrypted 256 KB at a
+ * time), so memory does not grow with its size. `content` holds the whole
+ * payload in JS as base64 and is decoded in one piece: fine for a thumbnail,
+ * several times the file's size in memory for a video.
+ */
+export type AttachmentInput = AttachmentDescription &
+	(
+		| {
+				/** The complete content, base64. Held and decoded whole. */
+				content: string;
+				sourcePath?: undefined;
+		  }
+		| {
+				/** Absolute path of a file the app can read. A `file://` prefix is accepted. */
+				sourcePath: string;
+				content?: undefined;
+		  }
+	);
+
 export type AttachmentReference = {
 	id: string;
-	owner?: AttachmentOwner;
+	owner?: AttachmentOwner | undefined;
 	contentType: string;
 	/** Plaintext byte length, <= 100 MB (FR-088). */
 	size: number;

package/src/contract/config.ts

@@ -35,7 +35,7 @@ export type DatabaseConfig = {
 	collections: CollectionSchema[];
 	migrations?: Migration[];
 	/** Absent means unencrypted (FR-097). */
-	encryption?: EncryptionConfig;
+	encryption?: EncryptionConfig | undefined;
 	/** Absent means excluded from platform backup (FR-109). */
 	backup?: BackupConfig;
 	/** Governs whether deleting a record removes its artifacts (FR-070). */
@@ -46,7 +46,7 @@ export type DatabaseConfig = {
 export type ScopeTargetConfig = {
 	name: string;
 	scope: ScopeDescriptor;
-	encryption?: EncryptionConfig;
+	encryption?: EncryptionConfig | undefined;
 };
 
 export type DatabaseTargetConfig = {

package/src/contract/migration.ts

@@ -10,9 +10,12 @@ import type { Transaction } from './transaction';
 /** Low-level escape hatch for schema work a migration needs. */
 // Attachments are not part of a migration: a migration reshapes records, and
 // files written inside one would survive its rollback with nothing to own them.
+/** A value SQLite can bind. */
+export type SqlParameter = string | number | boolean | null;
+
 export type MigrationContext = Omit<Transaction, 'attachments'> & {
 	/** Execute a raw statement against the scope's database. */
-	execute(sql: string, params?: unknown[]): Promise<void>;
+	execute(sql: string, params?: SqlParameter[]): Promise<void>;
 };
 
 export type Migration = {

package/src/contract/query.ts

@@ -51,13 +51,13 @@ export type PageRequest = {
 	/** 1..500 (FR-036, FR-088). */
 	size: number;
 	/** Opaque keyset cursor from a previous page. */
-	cursor?: string;
+	cursor?: string | undefined;
 };
 
 export type Query = {
-	filter?: FilterNode;
-	sort?: SortKey[];
-	page?: PageRequest;
+	filter?: FilterNode | undefined;
+	sort?: SortKey[] | undefined;
+	page?: PageRequest | undefined;
 	/** Soft-deleted records are excluded unless this is true (FR-021). */
 	includeSoftDeleted?: boolean;
 };
@@ -65,7 +65,7 @@ export type Query = {
 export type ResultPage<T extends StorableRecordData = StorableRecordData> = {
 	records: StoredRecord<T>[];
 	/** Absent when there is no further page. */
-	cursor?: string;
+	cursor?: string | undefined;
 	hasMore: boolean;
 };
 
@@ -76,6 +76,6 @@ export type ResultPage<T extends StorableRecordData = StorableRecordData> = {
 export type IndexCoverageReport = {
 	collection: string;
 	usesIndex: boolean;
-	indexName?: string;
+	indexName?: string | undefined;
 	detail: string;
 };

package/src/crypto/provider.ts

@@ -9,8 +9,10 @@
  * was asked for and cannot be delivered (research.md R1a).
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
 import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
+import { StorageError } from '../diagnostics/errors';
 
 export type CipherModule = {
 	createCipheriv(
@@ -43,39 +45,31 @@ export type CipherModule = {
 	};
 };
 
-let override: CipherModule | null = null;
-let cached: CipherModule | null = null;
+/** Loaded on first use (rn-core's lazy peer); optional, so absence is a normal answer. */
+const cipher = lazyPeer('react-native-quick-crypto', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-quick-crypto') as CipherModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
 
+/** Swap the module. Tests only; `null` goes back to the real one. */
 export function setCipherModule(module: CipherModule | null): void {
-	override = module;
-	cached = null;
+	cipher.override(module ?? undefined);
 }
 
 export function isCipherAvailable(): boolean {
-	if (override) {
-		return true;
-	}
-	try {
-		require('react-native-quick-crypto');
-		return true;
-	} catch {
-		return false;
-	}
+	return cipher.isAvailable();
 }
 
 export function cipherModule(): CipherModule {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('react-native-quick-crypto') as CipherModule;
-		} catch (error) {
-			raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+	return cipher.require(
+		(_peer, cause) =>
+			new StorageError(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
 				message: 'cipher peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
+				cause,
+			}),
+	);
 }

package/src/diagnostics/dev-log.ts

@@ -7,10 +7,12 @@
  * payload, so a future caller cannot pass one by accident.
  */
 
+import { createDiagnosticChannel, hasSdkSinks } from '@chipmobilesdk/rn-core';
+
 export type DiagnosticEvent = {
 	operation: string;
 	durationMs?: number;
-	count?: number;
+	count?: number | undefined;
 	collection?: string;
 	adapter?: 'sqlite' | 'memory';
 	/** A diagnostic code when the operation failed. Never a message. */
@@ -29,10 +31,27 @@ export function setDiagnosticLogger(next: DiagnosticLogger | null): void {
 function isDevelopmentBuild(): boolean {
 	// __DEV__ is a React Native global; the typeof guard keeps this usable
 	// under plain Node when the package is exercised from Jest.
-	return typeof __DEV__ !== 'undefined' ? __DEV__ === true : process.env.NODE_ENV !== 'production';
+	if (typeof __DEV__ !== 'undefined') return __DEV__ === true;
+	const { process } = globalThis as { process?: { env?: Record<string, string | undefined> } };
+	return process?.env?.NODE_ENV !== 'production';
 }
 
+/**
+ * A failed operation also reaches the app's SDK sinks (`installSdkSink` from
+ * rn-core, CORE-08), in any build: its code, the operation and the collection,
+ * which are identifiers this package defines. Successes stay with the
+ * development logger.
+ */
+const channel = createDiagnosticChannel('rn-local-db');
+
 export function logDiagnostic(event: DiagnosticEvent): void {
+	if (event.outcome !== undefined) {
+		channel.emit(event.outcome, 'warn', {
+			operation: event.operation,
+			...(event.collection === undefined ? {} : { collection: event.collection }),
+			...(event.adapter === undefined ? {} : { adapter: event.adapter }),
+		});
+	}
 	if (!logger || !isDevelopmentBuild()) {
 		return;
 	}
@@ -54,17 +73,22 @@ export function isLogging(): boolean {
  * installed and the build is a development build, so a production bundle pays
  * nothing and emits nothing (FR-081).
  */
-export function instrument<T extends Record<string, (...args: never[]) => unknown>>(
+export function instrument<T extends object>(
 	collection: string,
 	adapter: 'sqlite' | 'memory',
 	operations: T,
 ): T {
-	if (!isLogging()) {
+	// Unwrapped unless someone is listening: production pays nothing by default.
+	if (!isLogging() && !hasSdkSinks()) {
 		return operations;
 	}
 
 	const wrapped: Record<string, unknown> = {};
 	for (const [name, operation] of Object.entries(operations)) {
+		if (typeof operation !== 'function') {
+			wrapped[name] = operation;
+			continue;
+		}
 		wrapped[name] = async (...args: never[]): Promise<unknown> => {
 			const started = Date.now();
 			try {

package/src/diagnostics/errors.ts

@@ -6,6 +6,8 @@
  * error object at all.
  */
 
+import { SdkError } from '@chipmobilesdk/rn-core';
+
 import { DiagnosticCodes, RETRYABLE_CODES, type DiagnosticCode } from '../contract/errors';
 import type { MigrationFailureDetail } from '../contract/migration';
 import { redactCause, redactDetail, sanitizeAuthoredMessage } from './redact';
@@ -17,31 +19,30 @@ export type StorageErrorInit = {
 	 * identifier. `authored-messages.test.ts` checks every call site.
 	 */
 	message?: string;
-	detail?: Record<string, unknown>;
-	migration?: MigrationFailureDetail;
+	detail?: Record<string, unknown> | undefined;
+	migration?: MigrationFailureDetail | undefined;
 	cause?: unknown;
 };
 
-export class StorageError extends Error {
-	readonly code: DiagnosticCode;
-	readonly retryable: boolean;
-	readonly detail?: Record<string, string | number | boolean>;
-	readonly migration?: MigrationFailureDetail;
-	readonly redactedCause?: string;
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-local-db'`. */
+export class StorageError extends SdkError<DiagnosticCode> {
+	readonly detail?: Record<string, string | number | boolean> | undefined;
+	readonly migration?: MigrationFailureDetail | undefined;
 
 	constructor(code: DiagnosticCode, init: StorageErrorInit = {}) {
-		super(init.message ? sanitizeAuthoredMessage(init.message) : code);
+		// Call sites pass only authored literals (authored-messages.test.ts).
+		const message = init.message ? sanitizeAuthoredMessage(init.message) : code;
+		// `cause` is deliberately NOT kept: the native error it came from may
+		// quote the offending value. Only its redacted identifier survives.
+		super('rn-local-db', code, {
+			message,
+			retryable: RETRYABLE_CODES.has(code),
+			redactedCause: redactCause(init.cause),
+		});
 		this.name = 'StorageError';
-		this.code = code;
-		this.retryable = RETRYABLE_CODES.has(code);
 		this.detail = redactDetail(init.detail);
 		// Version numbers and an outcome enum — no payload can hide in these.
 		this.migration = init.migration;
-		this.redactedCause = redactCause(init.cause);
-		// `cause` is deliberately NOT assigned: the native error it came from
-		// may quote the offending value, and assigning it would reintroduce
-		// exactly the leak redaction exists to prevent.
-		Object.setPrototypeOf(this, StorageError.prototype);
 	}
 }
 

package/src/diagnostics/redact.ts

@@ -8,6 +8,8 @@
  * (FR-079, FR-099).
  */
 
+import { REDACTED, leadingIdentifier, pickAllowed } from '@chipmobilesdk/rn-core';
+
 /**
  * The allowlist IS the mechanism. Every key here has been reviewed as
  * incapable of carrying user data: identifiers the app already knows, sizes,
@@ -37,8 +39,6 @@ export const SAFE_DETAIL_KEYS = new Set([
 	'limit',
 ]);
 
-const REDACTED = '[redacted]';
-
 /**
  * Reduce foreign text to an identifier, or to nothing.
  *
@@ -60,15 +60,8 @@ const REDACTED = '[redacted]';
  * Everything else becomes `[redacted]`. A developer who needs more can
  * reproduce with the development logger; a crash report cannot.
  */
-const IDENTIFIER_TOKEN = /^([A-Z][A-Z0-9_]{2,})\b/;
-
 export function redactForeignText(text: string): string {
-	if (!text) {
-		return '';
-	}
-	const firstLine = text.split('\n')[0]!.trim();
-	const token = IDENTIFIER_TOKEN.exec(firstLine);
-	return token ? token[1]! : REDACTED;
+	return leadingIdentifier(text);
 }
 
 const MAX_AUTHORED_MESSAGE = 160;
@@ -107,19 +100,8 @@ export function sanitizeIdentifier(identifier: string): string {
 export function redactDetail(
 	detail: Record<string, unknown> | undefined,
 ): Record<string, string | number | boolean> | undefined {
-	if (!detail) {
-		return undefined;
-	}
-	const safe: Record<string, string | number | boolean> = {};
-	for (const [key, value] of Object.entries(detail)) {
-		if (!SAFE_DETAIL_KEYS.has(key)) {
-			continue;
-		}
-		if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-			safe[key] = value;
-		}
-	}
-	return Object.keys(safe).length > 0 ? safe : undefined;
+	const safe = pickAllowed(detail, SAFE_DETAIL_KEYS);
+	return safe && Object.keys(safe).length > 0 ? safe : undefined;
 }
 
 /** Reduce an unknown thrown value to a message-shaped string, redacted. */