@chipmobilesdk/rn-core 0.0.0-stage → 0.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @chipmobilesdk/rn-core

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# @chipmobilesdk/rn-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared foundation of the `@chipmobilesdk/*` React Native packages: one error
+model and one redaction mechanism, so every package fails and redacts the same way.
+Pure TypeScript, no native code, no side effects on import.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: see [CHANGELOG](CHANGELOG.md)
+
+Apps rarely import it directly: every other package depends on it. Import it when
+you handle errors from several packages in one place, or when you write a package
+of your own in the same family.
+
+## Entrypoints
+
+| Import | What it holds |
+|---|---|
+| `@chipmobilesdk/rn-core` | Everything below except test helpers |
+| `@chipmobilesdk/rn-core/errors` | `SdkError`, `isSdkError`, `defineErrorCodes`, `createIssueCollector` |
+| `@chipmobilesdk/rn-core/redact` | `createRedactor` and the redaction primitives |
+| `@chipmobilesdk/rn-core/listeners` | `createListenerSet`, `createEmitter` |
+| `@chipmobilesdk/rn-core/diagnostics` | `installSdkSink`, `createDiagnosticChannel` |
+| `@chipmobilesdk/rn-core/scheduler` | timers, backoff, retry, single-flight, timeouts, bounds |
+| `@chipmobilesdk/rn-core/lazy` | `lazyPeer` |
+| `@chipmobilesdk/rn-core/kv` | `KeyValuePort`, `openDurable`, `fromMmkvLike`, `createMemoryKeyValue`, `namespaced` |
+| `@chipmobilesdk/rn-core/runtime` | `currentPlatform`, `byPlatform`, `isDevBuild` |
+| `@chipmobilesdk/rn-core/intl` | `getNumberFormat`, `getDateTimeFormat`, `isValidTimeZone` |
+| `@chipmobilesdk/rn-core/messages` | `defineMessages`, `formatMessage` |
+| `@chipmobilesdk/rn-core/store` | `createStore`, `shallowEqual` |
+| `@chipmobilesdk/rn-core/react` | `useExternalStore`, `useLatestCallback`, `createSdkContext` (needs React) |
+| `@chipmobilesdk/rn-core/testing` | `redactionConformance`, the conformance harness, `createManualScheduler` — for tests only |
+
+## Errors
+
+Every package's public error class (`AdsError`, `PaymentError`, `StorageError`...)
+extends `SdkError`, keeping its own name and code union. So one handler covers all
+of them:
+
+```ts
+import { isSdkError } from '@chipmobilesdk/rn-core';
+
+function report(error: unknown) {
+	if (isSdkError(error)) {
+		// error.pkg: 'rn-ads', 'rn-payment'...; error.code: that package's code
+		log({ pkg: error.pkg, code: error.code, retryable: error.retryable, cause: error.redactedCause });
+	}
+}
+```
+
+- `code` is the package's stable code; branch on it, never on `message`.
+- `retryable` says whether the same call can succeed if made again.
+- `redactedCause` is the underlying failure, already reduced to text that is safe to
+  log. The original error object is never kept, since it may quote user data.
+- `isSdkError` checks a brand, not `instanceof`, so it still works when an app ends up
+  with two copies of rn-core in `node_modules`.
+
+`defineErrorCodes(codes, { retryable })` declares a package's code set once and
+answers `is(value)` and `isRetryable(code)`. `createIssueCollector()` gathers every
+problem in a config so it can be thrown at once.
+
+## Redaction
+
+`createRedactor(policy)` returns `{ text, detail, context }`:
+
+- `text(value)` reduces anything to one safe string. An `SdkError` becomes its code.
+  - `text: 'identifier'` (the default) keeps only a leading engine constant such as
+    `SQLITE_BUSY` and drops all other prose: no pattern can tell prose about a
+    failure from prose about a person.
+  - `text: 'patterns'` keeps prose but replaces URLs, JWTs, e-mail addresses, UUIDs
+    and long base64 runs (`COMMON_PATTERNS`), plus the policy's own `patterns`.
+    `dropKeys` are replaced wholesale when an object is rendered.
+- `detail(record)` keeps only `allowDetailKeys`, and only primitive values.
+- `context(record)` replaces the values of `shapeKeys` by their shape
+  (`[string:12]`), drops `dropKeys`, and pattern-redacts every other string.
+
+The primitives are exported too: `redactPatterns`, `leadingIdentifier`,
+`describeShape`, `pickAllowed`, `REDACTED`, `COMMON_PATTERNS`, `PATH_PATTERN`.
+
+## Listeners
+
+`createListenerSet<Args>()` is how every package notifies subscribers:
+`add(listener)` returns an unsubscribe that is safe to call twice, and
+`notify(...args)` calls each listener present when it starts. A listener removed
+during a round is not called; one added waits for the next round. Each listener runs
+in isolation, so one that throws neither stops the others nor reaches the code that
+notified. Its error is reported to `onListenerError` when given, otherwise rethrown on
+a fresh task, where the app's global error handler sees it.
+
+`createEmitter<Event>({ dedupe })` adds dispose and an optional dedupe by key. The
+dedupe remembers at most `capacity` keys, oldest forgotten first, so memory stays
+bounded however long the emitter lives. `emit` returns whether the event was
+delivered.
+
+## Diagnostics
+
+Every package reports what it observes as an `SdkDiagnostic`: `pkg`, `code`,
+`severity` (`debug`, `info`, `warn`, `error`), `at`, and optionally a
+`correlationId` and an already-redacted `context`. One sink receives all of them:
+
+```ts
+import { installSdkSink } from '@chipmobilesdk/rn-core';
+
+const uninstall = installSdkSink(d => {
+	if (d.severity === 'error' || d.severity === 'warn') crashReporter.log(`${d.pkg}:${d.code}`, d.context);
+});
+```
+
+Install it at startup, before creating the packages' instances: rn-local-db only
+instruments its operations while someone listens. Sinks are shared through a
+`Symbol.for` registry, so one installed through any copy of rn-core receives
+every package's diagnostics. A sink that throws is reported on a fresh task and
+never affects the package. Packages create a `createDiagnosticChannel(pkg)` and
+`emit(code, severity, context?, correlationId?)`; the context is redacted before
+any sink sees it.
+
+## Scheduling and bounds
+
+- `Scheduler` (`setTimeout`/`clearTimeout`) is injectable everywhere time is used;
+  `realScheduler` is the default. `createTimerSet(scheduler)` tracks every timer an
+  owner started, so disposing can prove none is left (`size()`).
+- `computeBackoff(attempt, { initialDelayMs, maxDelayMs, factor = 2, jitter })`:
+  initial × factor^(attempt−1), capped; `jitter: 'full'` spreads it over [0, delay].
+- `runWithRetry({ spec: { ...backoff, maxAttempts }, attempt, onExhausted })` runs an
+  attempt now and then on that schedule; a throw is a failed attempt, exhaustion is
+  reported rather than thrown, and `cancel()` is idempotent.
+- `createSingleFlight()` joins concurrent callers onto one operation;
+  `createExclusive()` refuses a second caller instead; `createRateLimiter(ms)` drops
+  calls inside the interval; `withTimeout(promise, ms, onTimeout)` always clears its
+  timer.
+- `checkRange(label, value, range, fail, unit?)` and `checkInteger(...)` reject an
+  out-of-range value, never clamp it, and throw what `fail(message)` builds, so each
+  package raises its own error with its own code.
+
+`createManualScheduler()` (`@chipmobilesdk/rn-core/testing`) is a scheduler a test
+drives with `advance(ms)`.
+
+## Native peers, storage and runtime
+
+- `lazyPeer(name, () => require('peer'))` loads a native peer on first use and caches
+  the outcome. `get()` never throws: `{ ok: true, module }` or `{ ok: false, peer,
+  cause }`. `require(fail)` returns the module or throws the package's own error.
+  `override(fake | null | undefined)` is the test seam. Keep the literal `require`
+  in the package that depends on the peer, so Metro bundles it there, and put it
+  inside a `try` block: Metro fails the whole bundle on a module it cannot find
+  unless the `require` sits in one, so an app that leaves an optional peer out
+  would not build.
+
+  ```ts
+  const messaging = lazyPeer('@react-native-firebase/messaging', () => {
+    try {
+      return require('@react-native-firebase/messaging') as MessagingModule;
+    } catch (cause) {
+      throw cause;
+    }
+  });
+  ```
+- `KeyValuePort` is a synchronous store with a `durable` flag. `openDurable(open,
+  onDegraded)` opens MMKV (or anything `MmkvLike`), or falls back to memory and
+  reports why. `namespaced(port, prefix)` shares one store between owners.
+- `currentPlatform()` is the one platform source: `'android'`, `'ios'` or
+  `'unsupported'` (Node, web), read from React Native lazily. `setPlatformOverride`
+  pins it in a test. `isDevBuild()` reads `__DEV__`, or `NODE_ENV` where that global
+  does not exist. React Native is an optional peer, needed only for `runtime`.
+- `appLifecycle()` is the app's lifecycle, shared by every package: one
+  reference-counted `AppState` subscription that exists only while somebody listens.
+  `current()` is `'active'`, `'inactive'` or `'background'`; `subscribe((state,
+  previous) => …)` hears changes only, never a repeat of the same state; `listenerCount`
+  says who holds it. `onForeground(listener, port?)` fires on a return from the
+  background, not on a trip through `inactive` (Control Center, a call banner).
+  `createAppLifecycle(source?)` builds a port over another source, and
+  `createManualLifecycle(initial?)` (`./testing`) is one a test moves with `set(state)`.
+  Packages never subscribe to `AppState` themselves.
+
+## Messages
+
+`defineMessages({ user, developer? })` declares a package's copy once: `user` texts
+may reach an end user, `developer` texts describe a configuration fault and must not.
+The set exposes `defaults`, `user`, `developer`, the key lists, `resolve(overrides)`,
+`audienceOf(key)` and `format(key, vars)`. Variables are `{name}`; `formatMessage`
+fills them and leaves an unknown one as written. A catalog is plain data, so rn-i18n's
+`runtimeEntriesFromCatalog` registers it for translation.
+
+## Intl
+
+`getNumberFormat(locale, options)` and `getDateTimeFormat(locale, options)` return a
+shared formatter per locale and options (key order does not matter), from a small
+LRU cache: constructing one is expensive on Hermes, and formatters never change once
+built. They throw what the constructor throws, so the caller decides how a bad option
+is reported. `isValidTimeZone(zone)` is memoized; Hermes raises a hard error for an
+unknown zone, so check a stored zone before formatting with it.
+
+## React
+
+`createStore(initial, isEqual?)` holds state whose snapshot keeps its identity until
+it actually changes, and notifies only then; it needs no React, so a package's pure
+core can own one. From `@chipmobilesdk/rn-core/react`:
+
+- `useExternalStore(subscribe, getSnapshot, select?, isEqual?)` reads any external
+  store through `useSyncExternalStore`. With `select`, the component re-renders only
+  when the selected value changes, however often the store changes.
+- `useLatestCallback(fn)` keeps one identity while calling the latest `fn`, for
+  listeners passed inline.
+- `createSdkContext(name)` returns a `Provider` and a `use()` that throws a clear
+  error outside it.
+
+React is an optional peer, needed only for this entrypoint; the main entrypoint
+never imports it.
+
+## Testing
+
+`redactionConformance(redact, { stringsOnly? })` runs a fixed set of secrets (a JWT,
+a token in a URL, an e-mail address, a UUID, a base64 payload, an `Error` carrying a
+token, and objects carrying them) through a redaction function and returns a report
+listing every secret that survived. Every `@chipmobilesdk` package runs it against
+each of its redaction entrypoints. The report is plain data, so it runs in Jest and
+on a device alike.
+
+### Port conformance
+
+A package states what any implementation of one of its ports must do as a list of
+checks, and runs the same list against its fake and against its real adapter (native
+module mocked in Jest, or for real from a demo screen). That is what keeps a fake
+honest: if it drifts from the adapter it stands in for, a check fails.
+
+```ts
+import { ensure, expectConformance, runChecks, type Check } from '@chipmobilesdk/rn-core/testing';
+
+const checks: readonly Check<{ create(): KeyValuePort }>[] = [
+	{
+		name: 'reads back what it wrote',
+		run(harness) {
+			const store = harness.create();
+			store.set('k', 'v');
+			ensure(store.get('k') === 'v', 'value changed');
+		},
+	},
+];
+
+expectConformance(await runChecks(() => harness, checks), 'memory store');
+```
+
+- `runChecks(makeSubject, checks)` runs every check against a fresh subject and returns
+  a `ConformanceReport`; a throwing check is a failure with its message as `detail`.
+- `expectConformance(report, subject?)` throws one error naming every failed check,
+  for a test runner. On a device, render the report instead.
+- `ensure(condition, message)` is the assertion a check uses; it needs no test runner.
+- `createFaultRegistry<Point>()` is deterministic fault injection: a fake calls
+  `throwIfFaulted(point)` at its named points, a test `arm`s the ones that should fail
+  (`times` defaults to one), and `fired()` proves the fault was reached.
+
+The suites built on it ship from each package's `./testing` entrypoint:
+`runPermissionPortConformance` and `runCameraEngineConformance` (rn-camera),
+`runProviderPortConformance` (rn-payment), `runAdsEngineConformance` (rn-ads), and
+`runSecureTokenStoreConformance` and `runOidcAuthClientConformance` (rn-auth).

package/package.json

@@ -1,6 +1,108 @@
 {
-  "name": "@chipmobilesdk/rn-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@chipmobilesdk/rn-core",
+	"version": "0.0.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./errors": {
+			"types": "./src/errors/index.ts",
+			"react-native": "./src/errors/index.ts",
+			"default": "./src/errors/index.ts"
+		},
+		"./redact": {
+			"types": "./src/redact/index.ts",
+			"react-native": "./src/redact/index.ts",
+			"default": "./src/redact/index.ts"
+		},
+		"./listeners": {
+			"types": "./src/listeners/index.ts",
+			"react-native": "./src/listeners/index.ts",
+			"default": "./src/listeners/index.ts"
+		},
+		"./diagnostics": {
+			"types": "./src/diagnostics/index.ts",
+			"react-native": "./src/diagnostics/index.ts",
+			"default": "./src/diagnostics/index.ts"
+		},
+		"./scheduler": {
+			"types": "./src/scheduler/index.ts",
+			"react-native": "./src/scheduler/index.ts",
+			"default": "./src/scheduler/index.ts"
+		},
+		"./lazy": {
+			"types": "./src/lazy/index.ts",
+			"react-native": "./src/lazy/index.ts",
+			"default": "./src/lazy/index.ts"
+		},
+		"./kv": {
+			"types": "./src/kv/index.ts",
+			"react-native": "./src/kv/index.ts",
+			"default": "./src/kv/index.ts"
+		},
+		"./runtime": {
+			"types": "./src/runtime/index.ts",
+			"react-native": "./src/runtime/index.ts",
+			"default": "./src/runtime/index.ts"
+		},
+		"./intl": {
+			"types": "./src/intl/index.ts",
+			"react-native": "./src/intl/index.ts",
+			"default": "./src/intl/index.ts"
+		},
+		"./messages": {
+			"types": "./src/messages/index.ts",
+			"react-native": "./src/messages/index.ts",
+			"default": "./src/messages/index.ts"
+		},
+		"./store": {
+			"types": "./src/store/index.ts",
+			"react-native": "./src/store/index.ts",
+			"default": "./src/store/index.ts"
+		},
+		"./react": {
+			"types": "./src/react/index.ts",
+			"react-native": "./src/react/index.ts",
+			"default": "./src/react/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+		"pack:check": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-native": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

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

@@ -0,0 +1,115 @@
+---
+name: sdk-rn-core
+description: "Shared foundation of the @chipmobilesdk packages via @chipmobilesdk/rn-core: SdkError and isSdkError for every package's errors, createRedactor, createListenerSet and createEmitter, installSdkSink for one diagnostic stream from every package, redactionConformance. Use when handling or logging errors from several SDK packages, wiring crash reporting or analytics to the SDK packages, or writing redaction or listeners for a package in this family."
+metadata:
+  package: "@chipmobilesdk/rn-core"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-core
+
+One error model and one redaction mechanism for every `@chipmobilesdk` package.
+Pure TypeScript; every other package depends on it.
+
+## Use this when
+
+- Handling or logging errors from several SDK packages in one place
+- Deciding whether a failed SDK call is worth retrying
+- Writing the redaction for a package in this family, or testing it
+- Writing a conformance suite for a port, so a fake and the real adapter pass the same checks
+
+## Errors
+
+Every package's error class extends `SdkError`. Branch on `error.code` and
+`error.retryable`; log `error.pkg`, `error.code` and `error.redactedCause`, never
+the message of a foreign error. Use `isSdkError`, not `instanceof`: it works across
+two copies of the package. README: `## Errors`.
+
+## Redaction
+
+Default to `createRedactor()` (identifier-only). Use `text: 'patterns'` only for
+text that describes a failure, never for text that may describe a person. Every
+redaction entrypoint must pass `redactionConformance` from
+`@chipmobilesdk/rn-core/testing`. README: `## Redaction`, `## Testing`.
+
+## Listeners and diagnostics
+
+Notify subscribers with `createListenerSet`, never a hand-written `Set` loop: it
+isolates a throwing listener and reports it. To get every SDK package's
+diagnostics, call `installSdkSink` once at startup, before creating instances.
+README: `## Listeners`, `## Diagnostics`.
+
+## Time and retries
+
+Never call `setTimeout` directly in a package: take a `Scheduler` so tests can drive
+it (`createManualScheduler`), and track owned timers in `createTimerSet`. Validate
+config with `checkRange`/`checkInteger` and the package's own error code.
+README: `## Scheduling and bounds`.
+
+## Native peers and platform
+
+Load a native peer with `lazyPeer`, never a bare `require` at module level or in a
+factory. The loader keeps its literal `require` inside a `try` block, or Metro cannot
+bundle an app without that optional peer. Ask `currentPlatform()` instead of reading `Platform.OS`. Persist through a
+`KeyValuePort` from `openDurable` and report a non-durable fallback. Hear the app's
+lifecycle through `appLifecycle()` (or `onForeground`), never `AppState` directly, so
+every package shares one subscription.
+README: `## Native peers, storage and runtime`.
+
+## React hooks
+
+Read package state with `useExternalStore` and a selector, never `useState` plus a
+subscribing `useEffect`. Keep snapshots stable (`createStore`, structural sharing).
+README: `## React`.
+
+## Intl
+
+Never construct `Intl.NumberFormat` or `Intl.DateTimeFormat` in a hot path: use
+`getNumberFormat`/`getDateTimeFormat`, and catch what they throw for a bad option.
+README: `## Intl`.
+
+## Messages
+
+Declare user-facing copy with `defineMessages`, keeping developer copy separate; an
+app registers the `user` catalog with rn-i18n. README: `## Messages`.
+
+## Public API
+
+Runtime:
+
+- `SdkError`, `isSdkError`, `defineErrorCodes`, `createIssueCollector`
+- `createRedactor`, `redactPatterns`, `leadingIdentifier`, `describeShape`, `pickAllowed`
+- `REDACTED`, `COMMON_PATTERNS`, `PATH_PATTERN`
+- `createListenerSet`, `createEmitter`, `reportAsynchronously`
+- `installSdkSink`, `hasSdkSinks`, `createDiagnosticChannel`
+- `realScheduler`, `createTimerSet`, `computeBackoff`, `runWithRetry`, `withTimeout`
+- `createSingleFlight`, `createExclusive`, `createRateLimiter`, `checkRange`, `checkInteger`
+- `lazyPeer`, `openDurable`, `fromMmkvLike`, `createMemoryKeyValue`, `namespaced`
+- `currentPlatform`, `setPlatformOverride`, `byPlatform`, `isDevBuild`
+- `appLifecycle`, `onForeground`, `createAppLifecycle` (+ `AppLifecyclePort`,
+  `AppLifecycleState`, `AppStateSource`)
+- `createStore`, `shallowEqual`
+- `getNumberFormat`, `getDateTimeFormat`, `isValidTimeZone`, `clearIntlCaches`
+- `defineMessages`, `formatMessage`
+
+React (`@chipmobilesdk/rn-core/react`):
+
+- `useExternalStore`, `useLatestCallback`, `createSdkContext`
+
+Types:
+
+- `SdkErrorOptions`, `ErrorCodes`, `ConfigIssue`, `RedactPolicy`, `Redactor`
+- `ListenerSet`, `ListenerErrorOptions`, `Emitter`, `EmitterOptions`, `DedupeOptions`, `Unsubscribe`
+- `SdkDiagnostic`, `DiagnosticSink`, `DiagnosticSeverity`, `DiagnosticChannel`, `DiagnosticChannelOptions`
+- `Scheduler`, `TimerSet`, `BackoffSpec`, `RetryHandle`, `RetryOptions`, `ExclusiveOutcome`, `Range`
+- `LazyPeer`, `PeerResult`, `KeyValuePort`, `MmkvLike`, `RuntimePlatform`, `BuildEnvironment`
+
+Testing (`@chipmobilesdk/rn-core/testing`):
+
+- `redactionConformance`, `REDACTION_PROBES`, `createManualScheduler`
+- `createManualLifecycle` — a lifecycle a test moves by hand
+- `runChecks`, `expectConformance`, `ensure`, `createFaultRegistry` — run one list of
+  port checks against a fake and the real adapter (README `### Port conformance`)
+- `ConformanceReport`, `ConformanceFailure`, `RedactionProbe`, `ManualScheduler`, `Check`,
+  `FaultRegistry`

package/src/diagnostics/index.ts

@@ -0,0 +1,110 @@
+/**
+ * One diagnostic stream for every package (CORE-08).
+ *
+ * Each package keeps its own typed events (`AdEvent`, `PaymentEvent`...), and also
+ * reports what it observed as an `SdkDiagnostic` through a channel. An app installs
+ * one `DiagnosticSink` and receives every package's diagnostics in one shape, so
+ * wiring crash reporting or analytics is one adapter rather than ten.
+ *
+ * Sinks live in a registry anchored on `Symbol.for`, so a sink installed through
+ * one copy of rn-core also receives diagnostics from packages bundling another.
+ * Every context passes through a redactor before any sink sees it.
+ */
+import type { Unsubscribe } from '../listeners';
+import { reportAsynchronously } from '../listeners';
+import { createRedactor, type Redactor } from '../redact';
+
+export type DiagnosticSeverity = 'debug' | 'info' | 'warn' | 'error';
+
+export interface SdkDiagnostic<Code extends string = string> {
+	/** The package that reported it, e.g. `rn-payment`. */
+	readonly pkg: string;
+	/** That package's stable diagnostic or event code. */
+	readonly code: Code;
+	readonly severity: DiagnosticSeverity;
+	/** Epoch milliseconds. */
+	readonly at: number;
+	/** Ties together everything reported within one operation, when the package has one. */
+	readonly correlationId?: string;
+	/** Already redacted. */
+	readonly context?: Readonly<Record<string, unknown>>;
+}
+
+export type DiagnosticSink = (diagnostic: SdkDiagnostic) => void;
+
+const REGISTRY = Symbol.for('chipmobilesdk.diagnosticSinks');
+
+function sinks(): Set<DiagnosticSink> {
+	const host = globalThis as { [REGISTRY]?: Set<DiagnosticSink> };
+	host[REGISTRY] ??= new Set();
+	return host[REGISTRY];
+}
+
+/**
+ * Sends every package's diagnostics to `sink` until the returned function is
+ * called. A sink that throws is reported on a fresh task and never affects the
+ * package that emitted.
+ */
+export function installSdkSink(sink: DiagnosticSink): Unsubscribe {
+	const registry = sinks();
+	registry.add(sink);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		registry.delete(sink);
+	};
+}
+
+/** Whether any sink is installed, for a package that would do extra work only to feed one. */
+export function hasSdkSinks(): boolean {
+	return sinks().size > 0;
+}
+
+export interface DiagnosticChannelOptions {
+	/** A package-level sink, in addition to every installed one. */
+	readonly sink?: DiagnosticSink | undefined;
+	/** Defaults to rn-core's identifier-only redactor. */
+	readonly redactor?: Redactor | undefined;
+	readonly now?: (() => number) | undefined;
+}
+
+export interface DiagnosticChannel<Code extends string> {
+	emit(
+		code: Code,
+		severity: DiagnosticSeverity,
+		context?: Readonly<Record<string, unknown>>,
+		correlationId?: string,
+	): void;
+}
+
+export function createDiagnosticChannel<Code extends string = string>(
+	pkg: string,
+	options: DiagnosticChannelOptions = {},
+): DiagnosticChannel<Code> {
+	const redactor = options.redactor ?? createRedactor();
+	const now = options.now ?? Date.now;
+
+	return {
+		emit(code, severity, context, correlationId) {
+			const targets = options.sink ? [options.sink, ...sinks()] : [...sinks()];
+			if (targets.length === 0) return;
+			const redacted = redactor.context(context);
+			const diagnostic: SdkDiagnostic<Code> = {
+				pkg,
+				code,
+				severity,
+				at: now(),
+				...(correlationId === undefined ? {} : { correlationId }),
+				...(redacted === undefined ? {} : { context: redacted }),
+			};
+			for (const sink of targets) {
+				try {
+					sink(diagnostic);
+				} catch (error) {
+					reportAsynchronously(error);
+				}
+			}
+		},
+	};
+}