@chipmobilesdk/rn-local-db 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @chipmobilesdk/rn-local-db
 
+## 0.3.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+### Patch Changes
+
+- The `./testing` memory adapter and conformance suite no longer use Node's `Buffer`, so
+  they run on Hermes as well as under Jest; base64 goes through the same byte helpers the
+  SQLite adapter uses. Optional properties in the public types (`Query`, `PageRequest`,
+  `DatabaseConfig.encryption`, `AttachmentReference.owner`, `StorageError` and others)
+  now accept an explicit `undefined`, so apps compiling with
+  `exactOptionalPropertyTypes` can pass a value that may be missing. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -512,7 +512,7 @@ To opt in instead, set `backup: { includeInPlatformBackup: true }` and remove th
 
 ## Diagnostics
 
-Every failure is a `StorageError` with a stable `code`. **Never parse a message** — use `isCode`:
+Every failure is a `StorageError` with a stable `code`. `StorageError` extends `SdkError` from `@chipmobilesdk/rn-core`, so `isSdkError(error)` recognises it alongside every other package's errors, `error.pkg` names this package, and `error.redactedCause` (when present) is the underlying failure reduced to log-safe text. **Never parse a message** — use `isCode`:
 
 ```ts
 import { DiagnosticCodes, isCode, isStorageError } from '@chipmobilesdk/rn-local-db';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-local-db",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -37,9 +37,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"@dr.pogodin/react-native-fs": ">=2.39.2",
 		"@op-engineering/op-sqlite": ">=17.1.0",

package/src/contract/attachment.ts

@@ -14,7 +14,7 @@ export type AttachmentOwner = {
 export type AttachmentInput = {
 	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;
@@ -22,7 +22,7 @@ export type AttachmentInput = {
 
 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/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;
 	}
@@ -59,7 +78,8 @@ export function instrument<T extends Record<string, (...args: never[]) => unknow
 	adapter: 'sqlite' | 'memory',
 	operations: T,
 ): T {
-	if (!isLogging()) {
+	// Unwrapped unless someone is listening: production pays nothing by default.
+	if (!isLogging() && !hasSdkSinks()) {
 		return operations;
 	}
 

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. */

package/src/platform/backup-ios.ts

@@ -32,9 +32,10 @@ export async function ensureManagedRoot(
 	layout: StorageLayout,
 	includeInPlatformBackup: boolean,
 ): Promise<void> {
-	await fileSystem().mkdir(layout.root, {
-		NSURLIsExcludedFromBackupKey: isIos() ? !includeInPlatformBackup : undefined,
-	});
+	await fileSystem().mkdir(
+		layout.root,
+		isIos() ? { NSURLIsExcludedFromBackupKey: !includeInPlatformBackup } : {},
+	);
 }
 
 /** What the package can state about iOS, where it enforces rather than reports. */

package/src/platform/bytes.ts

@@ -21,16 +21,29 @@ const LOOKUP = (() => {
 	return table;
 })();
 
+/**
+ * Codecs Hermes and Node provide but React Native's type declarations omit.
+ * Read through this view so the package type-checks without DOM or Node types.
+ */
+interface HostCodecs {
+	atob?: (data: string) => string;
+	btoa?: (data: string) => string;
+	TextEncoder?: new () => { encode(input: string): Uint8Array };
+	TextDecoder?: new () => { decode(input: Uint8Array): string };
+}
+
+export const host = globalThis as unknown as HostCodecs;
+
 /* eslint-disable no-bitwise -- base64 is bit packing; there is no clearer way to write it. */
 
 /** Characters per `String.fromCharCode` call; large spreads overflow the stack. */
 const CHUNK = 0x8000;
 
 export function base64ToBytes(base64: string): Uint8Array {
-	if (typeof globalThis.atob === 'function') {
+	if (host.atob) {
 		let binary: string | undefined;
 		try {
-			binary = globalThis.atob(base64.replace(/-/g, '+').replace(/_/g, '/'));
+			binary = host.atob(base64.replace(/-/g, '+').replace(/_/g, '/'));
 		} catch {
 			// atob is strict where Buffer was lenient; fall through to the
 			// tolerant decoder rather than turn stray characters into a crash.
@@ -63,12 +76,12 @@ export function base64ToBytes(base64: string): Uint8Array {
 }
 
 export function bytesToBase64(bytes: Uint8Array): string {
-	if (typeof globalThis.btoa === 'function') {
+	if (host.btoa) {
 		const parts: string[] = [];
 		for (let index = 0; index < bytes.length; index += CHUNK) {
 			parts.push(String.fromCharCode(...bytes.subarray(index, index + CHUNK)));
 		}
-		return globalThis.btoa(parts.join(''));
+		return host.btoa(parts.join(''));
 	}
 	const parts: string[] = [];
 	for (let start = 0; start < bytes.length; start += CHUNK * 3) {
@@ -98,8 +111,8 @@ export function bytesToBase64(bytes: Uint8Array): string {
 
 /** UTF-8 encoding. `TextEncoder` is in Hermes and Node; the loop is the fallback. */
 export function utf8Bytes(value: string): Uint8Array {
-	if (typeof TextEncoder !== 'undefined') {
-		return new TextEncoder().encode(value);
+	if (host.TextEncoder) {
+		return new host.TextEncoder().encode(value);
 	}
 	const encoded = unescape(encodeURIComponent(value));
 	const bytes = new Uint8Array(encoded.length);
@@ -111,8 +124,8 @@ export function utf8Bytes(value: string): Uint8Array {
 
 /** UTF-8 decoding, the inverse of `utf8Bytes`. */
 export function utf8String(bytes: Uint8Array): string {
-	if (typeof TextDecoder !== 'undefined') {
-		return new TextDecoder().decode(bytes);
+	if (host.TextDecoder) {
+		return new host.TextDecoder().decode(bytes);
 	}
 	let binary = '';
 	for (const byte of bytes) {

package/src/platform/fs.ts

@@ -8,8 +8,10 @@
  * rule the ESLint config enforces.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
 import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
+import { StorageError } from '../diagnostics/errors';
 
 export type FileStat = {
 	path: string;
@@ -44,30 +46,29 @@ export type FileSystem = {
 	exists(path: string): Promise<boolean>;
 };
 
-let override: FileSystem | null = null;
-let cached: FileSystem | null = null;
+/** Loaded on first use (rn-core's lazy peer); a missing peer is `STORAGE_ACCESS`. */
+const fs = lazyPeer('@dr.pogodin/react-native-fs', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('@dr.pogodin/react-native-fs') as FileSystem;
+	} catch (cause) {
+		throw cause;
+	}
+});
 
-/** Swap the peer. Tests and the demo app's in-memory mode only. */
+/** Swap the peer. Tests and the demo app's in-memory mode only; `null` restores it. */
 export function setFileSystem(module: FileSystem | null): void {
-	override = module;
-	cached = null;
+	fs.override(module ?? undefined);
 }
 
 export function fileSystem(): FileSystem {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('@dr.pogodin/react-native-fs') as FileSystem;
-		} catch (error) {
-			raise(DiagnosticCodes.STORAGE_ACCESS, {
+	return fs.require(
+		(_peer, cause) =>
+			new StorageError(DiagnosticCodes.STORAGE_ACCESS, {
 				message: 'filesystem peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
+				cause,
+			}),
+	);
 }
 
 export async function pathExists(path: string): Promise<boolean> {

package/src/query/cursor.ts

@@ -14,7 +14,7 @@ import type { StoredRecord } from '../contract/record';
 import { raise } from '../diagnostics/errors';
 import { compareValues } from './compare';
 import { sortValueOf } from './sort';
-import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../platform/bytes';
+import { base64ToBytes, bytesToBase64, host, utf8Bytes, utf8String } from '../platform/bytes';
 
 export type CursorPayload = {
 	/** Sort key fields and directions, so a cursor cannot be reused across shapes. */
@@ -28,15 +28,15 @@ function shapeOf(sort: SortKey[]): string {
 }
 
 function toBase64(value: string): string {
-	if (typeof globalThis.btoa === 'function') {
-		return globalThis.btoa(unescape(encodeURIComponent(value)));
+	if (host.btoa) {
+		return host.btoa(unescape(encodeURIComponent(value)));
 	}
 	return bytesToBase64(utf8Bytes(value));
 }
 
 function fromBase64(value: string): string {
-	if (typeof globalThis.atob === 'function') {
-		return decodeURIComponent(escape(globalThis.atob(value)));
+	if (host.atob) {
+		return decodeURIComponent(escape(host.atob(value)));
 	}
 	return utf8String(base64ToBytes(value));
 }

package/src/sqlite/native.ts

@@ -8,8 +8,10 @@
  * express the synchronous call is a stronger guarantee than a review comment.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
 import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
+import { StorageError } from '../diagnostics/errors';
 
 export type SqlValue = string | number | boolean | null | undefined;
 
@@ -44,30 +46,29 @@ export type Engine = {
 	isSQLCipher?: () => boolean;
 };
 
-let override: Engine | null = null;
-let cached: Engine | null = null;
+/** Loaded on first use (rn-core's lazy peer); a missing peer is `OPEN_FAILED`. */
+const sqlite = lazyPeer('@op-engineering/op-sqlite', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('@op-engineering/op-sqlite') as Engine;
+	} catch (cause) {
+		throw cause;
+	}
+});
 
-/** Swap the engine. Tests only. */
+/** Swap the engine. Tests only; `null` goes back to the real one. */
 export function setEngine(next: Engine | null): void {
-	override = next;
-	cached = null;
+	sqlite.override(next ?? undefined);
 }
 
 export function engine(): Engine {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('@op-engineering/op-sqlite') as Engine;
-		} catch (error) {
-			raise(DiagnosticCodes.OPEN_FAILED, {
+	return sqlite.require(
+		(_peer, cause) =>
+			new StorageError(DiagnosticCodes.OPEN_FAILED, {
 				message: 'storage engine peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
+				cause,
+			}),
+	);
 }
 
 /**

package/src/testing/conformance/attachments.ts

@@ -1,5 +1,6 @@
 import { DiagnosticCodes } from '../../contract/errors';
 import { isCode } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../../platform/bytes';
 import type { ConformanceContext } from './index';
 
 /** US7: artifacts the package owns, and the reconciliation that keeps them honest. */
@@ -8,7 +9,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 		beforeEach(() => context.reset());
 
 		const scope = { kind: 'guest' } as const;
-		const content = Buffer.from('hello attachment', 'utf8').toString('base64');
+		const content = bytesToBase64(utf8Bytes('hello attachment'));
 
 		it('stores a reference alongside the artifact', async () => {
 			const handle = await context.adapter.open(context.configFor(scope));
@@ -20,7 +21,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 				content,
 			});
 
-			expect(reference.size).toBe(Buffer.from(content, 'base64').length);
+			expect(reference.size).toBe(base64ToBytes(content).length);
 			expect(await attachments.read('a1')).toBe(content);
 			expect((await attachments.availability('a1')).state).toBe('available');
 			await handle.close();
@@ -32,7 +33,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
 
 			const slice = await attachments.read('a1', { offset: 0, length: 5 });
-			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('hello');
+			expect(utf8String(base64ToBytes(slice))).toBe('hello');
 			await handle.close();
 		});
 
@@ -112,7 +113,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 
 		it('rejects an artifact over the size budget', async () => {
 			const handle = await context.adapter.open(context.configFor(scope));
-			const huge = Buffer.alloc(101 * 1024 * 1024).toString('base64');
+			const huge = bytesToBase64(new Uint8Array(101 * 1024 * 1024));
 
 			let thrown: unknown;
 			try {

package/src/testing/conformance/encryption.ts

@@ -1,6 +1,7 @@
 import { DiagnosticCodes } from '../../contract/errors';
 import type { KeyProvider } from '../../contract/encryption';
 import { isCode } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../../platform/bytes';
 import type { ConformanceContext } from './index';
 
 /** US10: opt-in encryption, and failures that stay apart from each other. */
@@ -47,12 +48,12 @@ export function registerEncryptionConformance(context: ConformanceContext): void
 			const handle = await context.adapter.open(
 				context.configFor(scope, { encryption: encrypted }),
 			);
-			const content = Buffer.from('hello encrypted attachment', 'utf8').toString('base64');
+			const content = bytesToBase64(utf8Bytes('hello encrypted attachment'));
 			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
 
 			expect(await handle.attachments().read('a1')).toBe(content);
 			const slice = await handle.attachments().read('a1', { offset: 6, length: 9 });
-			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('encrypted');
+			expect(utf8String(base64ToBytes(slice))).toBe('encrypted');
 			expect((await handle.attachments().availability('a1')).state).toBe('available');
 			await handle.close();
 		});

package/src/testing/conformance/index.ts

@@ -59,7 +59,7 @@ export type ConformanceOptions = {
 	 * — an encrypted database that quietly behaved differently would be a
 	 * second implementation nobody tested.
 	 */
-	encryption?: EncryptionConfig;
+	encryption?: EncryptionConfig | undefined;
 };
 
 export type ConformanceSection =

package/src/testing/memory-adapter/index.ts

@@ -6,6 +6,7 @@
  * (research.md R8). Documented divergences are listed in the package README.
  */
 
+import { base64ToBytes, bytesToBase64 } from '../../platform/bytes';
 import { createTransactionQueue } from '../../sqlite/transaction-queue';
 import type {
 	AttachmentInput,
@@ -219,7 +220,7 @@ export function createMemoryAdapter(options: MemoryAdapterOptions = {}): Storage
 				assertOpen();
 				throwIfFaulted('attachmentWrite');
 				assertValidAttachmentId(input.id);
-				const bytes = Buffer.from(input.content, 'base64');
+				const bytes = base64ToBytes(input.content);
 				assertArtifactWithinBudget(input.id, bytes.length);
 				const reference: AttachmentReference = {
 					id: input.id,
@@ -248,8 +249,8 @@ export function createMemoryAdapter(options: MemoryAdapterOptions = {}): Storage
 				if (!range) {
 					return content;
 				}
-				const bytes = Buffer.from(content, 'base64');
-				return bytes.subarray(range.offset, range.offset + range.length).toString('base64');
+				const bytes = base64ToBytes(content);
+				return bytesToBase64(bytes.subarray(range.offset, range.offset + range.length));
 			},
 			async availability(id) {
 				assertOpen();

package/src/testing/memory-adapter/store.ts

@@ -16,9 +16,9 @@ export type MemoryRow = {
 	/** Serialized on write, parsed on read — the same payload-as-truth rule
 	 * the SQLite adapter follows, so a mutation after write cannot leak in. */
 	payload: string;
-	createdAt?: number;
-	updatedAt?: number;
-	deletedAt?: number | null;
+	createdAt?: number | undefined;
+	updatedAt?: number | undefined;
+	deletedAt?: number | null | undefined;
 };
 
 export type MemoryScopeStore = {