react-native-nitro-logger 0.1.0

package/docs/PARITY.md

@@ -0,0 +1,330 @@
+# Parity with SwiftLogger
+
+This package is a port of [SwiftLogger](https://github.com/amirshayegh/logger).
+Where the two can produce the same bytes, they do — `JsonLinesFormatter` is
+asserted byte-identical to `JSONLogFormatter` over a generated corpus in
+`__tests__/jsonLinesFormatter.test.ts`. Where they cannot, this file says why.
+
+Nothing here is aspirational. Every "identical" row is covered by a golden;
+every difference is either enforced by a test or unreachable through the
+public API, and the table says which.
+
+## JSON record
+
+Field order is fixed on both sides so output diffs cleanly.
+
+| Field         | SwiftLogger                          | This package                     | Status |
+| ------------- | ------------------------------------ | -------------------------------- | ------ |
+| `timestamp`   | ISO 8601 UTC ms, or epoch seconds    | same                             | identical |
+| `level`       | `VERBOSE`…`TODO`                     | same                             | identical |
+| `message`     | RFC 8259 escaped string              | same                             | identical |
+| `correlation` | omitted when absent                  | same                             | identical |
+| `subsystem`   | omitted when absent                  | same                             | identical |
+| `file`        | emitted when non-empty               | **never emitted**                | differs |
+| `function`    | emitted when non-empty               | **never emitted**                | differs |
+| `line`        | **always emitted**                   | **never emitted**                | differs |
+| `metadata`    | sorted keys, omitted when empty      | same                             | identical |
+| `truncated`   | —                                    | added by `formatWithin`          | extension |
+
+### Why no `file`, `function`, `line`
+
+Swift captures these for free with `#fileID`, `#function`, and `#line`. JavaScript
+has no equivalent, and the alternative — parsing a Hermes stack trace on every
+log call — is both expensive and unreliable across Hermes versions and release
+builds. Subsystems are the filtering mechanism instead.
+
+This is the only structural difference in the record, and the parity test
+encodes it exactly: it strips `,"line":N` from each golden and requires
+byte equality on everything that remains. `file` and `function` are absent
+from the goldens because the corpus leaves them empty, which is what a port
+with no call-site capture would produce anyway.
+
+### Escaping
+
+Identical, and not by coincidence: `JSON.stringify` on a string produces the
+same bytes as SwiftLogger's hand-rolled escaper for every input Swift can
+represent — the two mandatory escapes, the `\b \f \n \r \t` shorthands,
+lowercase `\u00XX` for the rest of C0, and everything else literal including
+non-ASCII. Goldens cover each class.
+
+One case exists only on this side. A JavaScript string can hold an unpaired
+surrogate; a Swift `String` cannot. Written raw it would make the log file
+invalid UTF-8, so it is escaped as `\udXXX`, which is also what `JSON.stringify`
+does. No golden covers it because Swift cannot produce one.
+
+### Metadata values
+
+| Value        | SwiftLogger                    | This package        | Status |
+| ------------ | ------------------------------ | ------------------- | ------ |
+| string       | quoted                         | quoted              | identical |
+| bool         | `true` / `false`               | same                | identical |
+| integer      | `LogValue.int` → `42`          | `42`                | identical |
+| fractional   | `LogValue.double` → `1.5`      | `1.5`               | identical |
+| whole double | `LogValue.double(3)` → `3.0`   | `3`                 | differs |
+| non-finite   | quoted `"nan"` / `"inf"`       | quoted `"NaN"` / `"Infinity"` | differs, unreachable |
+
+The last two rows are both consequences of JavaScript having one numeric type
+where Swift has two. `LogValue.double(3.0)` renders `3.0`; a JavaScript `3` is
+indistinguishable from `3.0` and renders `3`. The values are numerically
+identical and both are valid JSON — a consumer parsing the field gets the same
+number either way.
+
+Non-finite values differ only in spelling, and redaction rejects them before a
+formatter ever sees one (`__tests__/redaction.test.ts`). The branch exists so a
+hand-built entry produces a parseable record rather than a bare `NaN` token.
+
+### Timestamps
+
+`iso8601` is identical, including the pre-1970 case where flooring rather than
+truncating toward zero decides the date — `-1500 ms` renders
+`1969-12-31T23:59:58.500Z` on both sides, and there is a golden for it.
+
+`epochSeconds` differs textually for whole seconds: Swift's `Double` rendering
+gives `1769516130.0` where JavaScript gives `1769516130`. Numerically equal,
+and the JSON type is a number on both sides. `iso8601` is the default and the
+style the goldens are written against.
+
+Out-of-range instants have no Swift analogue to match — Swift falls back to a
+`DateFormatter`, and this package clamps to the epoch rather than letting
+`toISOString` throw inside a log call that was already reporting a problem.
+
+## Console record
+
+`DefaultFormatter` follows SwiftLogger's console layout minus the same
+call-site column:
+
+```
+LEVEL | HH:mm:ss.SSS | [correlation] [subsystem] message {key=value}
+```
+
+Level tags are the byte-identical five-character forms (`TRACE`, `DEBUG`,
+` INFO`, ` WARN`, `ERROR`, ` TODO`), and metadata renders as `key=value` sorted
+by key. The timestamp is local time on both sides.
+
+### Control characters in structured fields
+
+| Field                    | SwiftLogger | This package         |
+| ------------------------ | ----------- | -------------------- |
+| `correlation`            | escaped     | escaped              |
+| `subsystem`              | escaped     | escaped              |
+| metadata keys and values | escaped     | escaped              |
+| `message`                | **verbatim**| **line-break safe**  |
+
+Both sides render controls in the structured fields as `\n`, `\r`, `\t`, or
+`\u{HH}` with uppercase hex. SwiftLogger covers C0 and DEL; this package also
+covers **C1 (U+0080–U+009F)**, which is easy to overlook and worth the
+divergence: U+009B is a single-character CSI, so a terminal reads what follows
+it as a cursor-movement or erase sequence, and U+0085 is NEL, a line break to
+any Unicode-aware reader.
+
+This layout puts one entry per line, so a newline inside any field lets
+whoever supplied it forge whole entries — a correlation ID, a subsystem, a
+metadata key or value, or a message can each arrive from a request header, a
+username, a URL, or an error. `"a\nERROR | 00:00:00.000 | "` would otherwise
+write a fake line a reader cannot distinguish from a real one.
+
+**The message is where the two diverge, deliberately.** SwiftLogger leaves it
+verbatim so the crash handler can log multi-line stack traces. This package
+wanted the same thing without the forgery, so it keeps the lines and indents
+every one after the first under the message column:
+
+```
+ERROR | 12:15:30.842 | Unhandled TypeError
+      |              | at foo (bundle.js:1:2)
+```
+
+A real record always carries a known five-character level tag and a timestamp
+of digits, so a blank in either column cannot be read as a header. Five
+sequences count as line breaks — `\n`, `\r\n`, a bare `\r`, U+0085, and
+U+2028/U+2029 — and every other control character, C0 through C1, is escaped
+as in the structured fields.
+
+### The JSON record does not do this
+
+`JsonLinesFormatter` escapes exactly what RFC 8259 requires, byte-identically
+to SwiftLogger: C0 escaped, everything else literal, C1 included. That is not
+an oversight.
+
+Its `framing: 'line'` contract is defined over **`\n` bytes**, because that is
+what the native crash-tail trimmer scans for. A raw U+0085 or U+009B inside a
+JSON string encodes to `C2 85` / `C2 9B` — no `0x0A` byte anywhere — so record
+boundaries survive, and the record is still valid JSON that any parser reads
+back exactly as written. Escaping them would buy nothing and break byte parity
+with the goldens.
+
+The distinction is that a console line is read by a terminal, and a JSON line
+is read by a parser.
+
+This package escaped none of these fields until the parity matrix was written.
+The structured-field gap was found by comparing against the Swift
+implementation; the message gap was found in review of that fix, on the
+grounds that matching the reference is not the same as being safe. Both are
+the argument for keeping this document accurate.
+
+## Beyond the formatter
+
+| Area | SwiftLogger | This package |
+| ---- | ----------- | ------------ |
+| Privacy | `os_log`-style interpolation privacy | `pub()` / `priv()` markers plus `privacyDefault`, enforced at runtime and by an ESLint plugin |
+| Metadata keys | unconstrained | validated, optionally catalog-restricted |
+| Call-site capture | `#fileID` / `#function` / `#line` | none, by design |
+| Per-file level overrides | supported | dropped for v1 |
+| `highlight()` | supported | dropped for v1 |
+
+The privacy layer is the substantive divergence. Swift's model leans on
+`os_log` privacy interpolation, which has no equivalent in a JavaScript logger
+that also writes files; this package resolves visibility itself, before an
+entry is constructed. `eslint-plugin/README.md` covers what that does and does
+not protect.
+
+---
+
+# Parity between the two native writers
+
+The Android writer is a port of the iOS one. Structure, naming scheme, clamping
+rules, the two-lock split, generation fencing and the durable/rebound split are
+identical by intent — a rotation or a purge that behaves differently on the two
+platforms is a bug report nobody can reproduce.
+
+The rows below are the places where they genuinely differ, and why. Everything
+not listed here is the same on both platforms and covered by suites that assert
+the same invariants: 122 XCTest cases and 102 JUnit cases, neither of which needs
+a simulator or an emulator.
+
+| Concern | iOS | Android | Consequence |
+| ------- | --- | ------- | ----------- |
+| Open-and-check | `O_RDWR\|O_APPEND\|O_CREAT\|O_NOFOLLOW\|O_NONBLOCK` in one syscall, then `fstat` | check-then-open: `lstat` for a symlink, then `FileOutputStream` | a window on Android, over app-private storage no other app can write to |
+| Crash-tail trim | through the same descriptor it will append with | a separate `RandomAccessFile` opened before the append stream exists | the trim and the writes provably concern one inode on iOS; on Android that rests on there being no other descriptor yet |
+| File age across restarts | `creationDate` from the filesystem | `<base>.meta` sidecar, authoritative once written | see below |
+| At-rest protection | `NSFileProtectionCompleteUntilFirstUserAuthentication` and a backup-exclusion flag, per artifact | `noBackupFilesDir` plus owner-only modes | **not equivalent** — see below |
+| Link count / directory sync | `fstat` and `fsync` directly | behind `PlatformIo`, so the writer imports nothing from `android.*` | the Android writer is JVM-testable; `PlatformIo.Jvm` reports "cannot say" for link count, so that path is driven by a fake |
+| Deadlines | `DispatchTime` | injected monotonic clock (`System.nanoTime`) | same guarantee, reached differently |
+| Console chunk size | 900 bytes per `os_log` entry | 3800 bytes per logcat entry | the platform limits genuinely differ; the behaviour around them — `(i/n)` markers, 8-chunk ceiling, a truncation notice that fits inside its own entry — is identical |
+| Console split boundary | grapheme clusters (`Character`) | code points | iOS also keeps combining sequences whole; Android only guarantees surrogate pairs are not cut. Both prevent replacement characters, which is the corruption that matters — see below |
+
+## Why the console split boundary differs
+
+Both platforms drop the tail of an over-long console line in silence — no
+ellipsis, no diagnostic — so both writers split it themselves and mark the
+pieces. What they will not do is split *inside a character*, because that
+produces replacement characters in the console and suggests corruption that is
+not there.
+
+iOS splits on `Character`, which is an extended grapheme cluster, so a flag
+emoji and a combining sequence both stay whole. Android splits on code points,
+which keeps surrogate pairs — the emoji — together but can separate a combining
+mark from the letter it modifies.
+
+The gap is deliberate. Matching iOS exactly means `BreakIterator` and therefore
+ICU, whose version varies by device, in the one code path that runs on every
+console line of every app. The failure it would prevent is a combining mark
+rendering on its own at a chunk boundary: visually odd, still legible, and
+still valid UTF-8. The failure both platforms *do* prevent is a half-encoded
+character, which is neither.
+
+## At-rest protection is not equivalent
+
+The table says "not equivalent" rather than "different mechanism, same result",
+because that would be a claim neither platform supports.
+
+iOS applies a data-protection class, so between boot and the first unlock the
+file's contents are cryptographically unavailable even to code that can reach
+the path. Android's log directory is app-private and excluded from Auto Backup,
+and every artifact is chmod'd to its owner, but the writer requests no
+per-file protection class — there is no Android equivalent to ask for. Whatever
+protection the artifacts have at rest is whatever platform storage encryption
+provides for that device and that user state.
+
+So the difference is narrow and specific: **before first unlock**, iOS gives the
+log file a guarantee the Android one does not have. After first unlock the two
+are much closer, and neither is a defence against an attacker who already has
+privileged access to the device — that case is out of scope for both, and
+`docs/PRIVACY.md` says so.
+
+The platforms also differ in how much they have to *withhold*. On iOS all three
+protections — mode, protection class, backup exclusion — are applied only to a
+log directory the writer itself created; one that was already there is inspected
+and left alone, because each of them is directory-wide, outlives the sink, and
+the log path may well be a directory the host app owns and shares. Android has
+nothing to withhold at that level: `restrictToOwner` sets modes and nothing
+else, and the Auto Backup exclusion comes from living under `noBackupFilesDir`
+rather than from an attribute the writer sets. Android's Kotlin therefore still
+tightens a pre-existing log directory's mode where iOS now reports it instead.
+That is a deliberate difference and the one place the two writers' directory
+handling is not identical: the case iOS is protecting — a directory deliberately
+shared with an app group or an extension — has no Android counterpart. App
+storage there is uid-isolated with no cross-process sharing to strip, and a
+directory on external storage does not honour POSIX modes in the first place.
+Files are treated the same on both, and unlike directories they are treated as
+owned whether or not the writer created them — a log file already sitting at the
+log path is one this writer is about to append to, rotate, and purge, so it is
+its artifact by every meaning that matters, and a `0644` one full of patient
+data is worth tightening. Every writer-managed file gets everything its platform
+offers.
+
+Both platforms can also fall short of what they attempt: applying or verifying
+a mode can fail, and the writer records a `protection` degradation and keeps
+logging rather than refusing to log at all. So "owner-only modes on every
+artifact" describes what is applied and reported, not an invariant that always
+holds. Read the `degraded` bitmask if the distinction matters to you.
+
+## Why Android needs a sidecar
+
+`BasicFileAttributes.creationTime()` is API 26, and this library supports 24.
+Worse, where it does exist it is not reliably populated: several Android
+filesystems have no birth time and return the mtime instead, which advances on
+every write. A writer that trusted it would see a freshly created file at every
+restart and postpone age-based rotation forever.
+
+So `<base>.meta` holds the epoch millis the current file began, and it is
+authoritative once written — the filesystem is consulted only to seed a sidecar
+that does not exist yet, and only when its answer is positive and not in the
+future. The sidecar is part of the artifact naming scheme, so a purge takes it.
+Rotation overwrites it with the fresh timestamp and holds that value in memory
+until the write lands, so a failed write followed by a failed reopen cannot
+send the process back to the archived file's age.
+
+## `java.nio.file` is not available
+
+API 26 again, and it is worth stating separately because the failure is not a
+graceful one: an unresolvable class raises `NoClassDefFoundError`, which is an
+`Error` and passes straight through `catch (Exception)`.
+
+Every use of `java.nio.file` in the Android sources is confined to
+`PlatformIo.Jvm.Nio`, a private object nothing on Android ever calls. The
+enclosing `PlatformIo.Jvm` *is* reachable from Android — `AndroidPlatformIo`
+falls back to its `restrictToOwner`, which uses only `java.io` — which is
+exactly why `Nio` is held separately: resolving `Jvm` must not drag
+`java.nio.file` into an Android class load.
+
+Android answers symlink detection and tri-state existence with `Os.lstat`
+(API 21), and path normalisation is done textually. It does not answer creation
+time at all: `AndroidPlatformIo.creationTimeMillis` returns null unconditionally,
+because the API-26 call is both unavailable below 26 and unreliable above it,
+and the sidecar is the mechanism instead.
+
+`platform` is a required parameter on both `LogFileWriter.open` and
+`LogWriterRegistry.acquire` specifically so that falling back to the JVM
+implementation is not expressible.
+
+## Compatibility, per platform
+
+These claims are deliberately narrower than "React Native ≥ 0.78 on both
+platforms", because only one of them is verified against the bottom of the
+range.
+
+| Platform | Claim | How it is backed |
+| -------- | ----- | ---------------- |
+| iOS | React Native ≥ 0.78 | the `min-rn-ios` CI job packs a tarball into a pristine 0.78 app, builds it Release, launches it on a simulator and reads a run-ID-matched verdict out of the app container |
+| Android | verified at the example's React Native version; **0.78 experimental** | `test-android` runs the writer's JUnit suite and `build-android` builds the example, but no equivalent minimum-version consumer job exists yet |
+
+The Android gap is tracked for v1.1. Narrowing the claim was the deliberate
+alternative to asserting something no job checks.
+
+`min-rn-ios` is pinned to `macos-15` with Xcode 16.4. React Native 0.78 pins
+fmt 11.0.2 through RCT-Folly and clang from Xcode 26 rejects its
+`format-inl.h`; that is upstream and unrelated to this library, but it is also
+not a combination any consumer is in, since an app on 0.78 builds with the
+toolchain 0.78 shipped against. The cost of keeping the floor at 0.78 is that
+this job is pinned to a runner image GitHub will eventually retire — raising
+the floor is what would let it move.

package/docs/PRIVACY.md

@@ -0,0 +1,341 @@
+# The privacy contract
+
+This library was built for an app that must never write patient data to a log
+file. That requirement shaped every design decision below, and it is worth
+saying plainly what the library does and does not promise.
+
+**What it promises.** Values you pass as metadata are redacted or rendered
+according to a rule you choose once, at startup. Redaction happens before an
+entry is constructed, so a redacted value is never present in any object a
+destination can see. The reveal path — the code that renders a private value in
+the clear — is `__DEV__`-gated and provably absent from a release bundle.
+
+**What it cannot promise.** Three things, and none of them is a detail:
+
+- It cannot tell whether a string is a name. If you interpolate a medical record
+  number into a message, this library writes it to disk. The message field is
+  public by contract and constrained by lint, not at runtime.
+- That lint is **opt-in**. Installing this package does not enable it.
+- The redaction above is **release-build behaviour**. A debug build renders
+  private payloads in the clear, to every destination including the file.
+
+Each is expanded below. The short version is that this library makes the safe
+thing the default in the builds that ship, and cannot make it the only thing.
+
+---
+
+## Two profiles
+
+The default is the OSS-friendly one. Switching the *metadata* default to
+fail-closed is one method call; the rest of the telehealth profile is not.
+Regulated use also requires enabling the ESLint configuration in your own
+setup and running it in CI, and — where your key vocabulary can carry an
+identifier — registering an approved-key catalog. `privacyDefault('private')`
+does neither of those for you.
+
+```ts
+import { Log } from 'react-native-nitro-logger';
+
+// In the app's entry point, before anything logs.
+Log.privacyDefault('private');
+```
+
+**In a release build** (`__DEV__` false):
+
+| | `'public'` (default) | `'private'` |
+| --- | --- | --- |
+| A bare metadata value | rendered | redacted to `<private>` |
+| `pub(v)` | rendered | rendered |
+| `priv(v)` | redacted | redacted |
+| Forgetting a wrapper | leaks | hides |
+
+**In a debug build the redaction column does not apply.** The reveal branch is
+`__DEV__`-gated, so a development build renders private payloads in the clear —
+to *every* configured destination, not just the console, because visibility is
+resolved before the entry is constructed and the file sink receives whatever
+that produced. A debug build is therefore not suitable for real regulated data;
+see [The compliance boundary](#the-compliance-boundary).
+
+`'private'` is fail-closed, which is the entire reason it exists: in the builds
+that ship, the failure mode of a forgotten wrapper is a missing value in a log
+file, not a patient identifier in one.
+
+`privacyDefault` is **first-set-wins, then tighten-only**. The first call
+decides; later calls can move `'public'` → `'private'` but never back. A
+library you depend on cannot loosen your setting, and a second call in a
+different module cannot silently undo the one in your entry point.
+
+`redactAllMetadata()` is the same idea taken to the end: every value redacts,
+wrapped or not, permanently.
+
+---
+
+## What may be a metadata value
+
+Only exact primitives: `string`, finite `number`, `boolean`, and the
+`pub()`/`priv()` markers wrapping one of those.
+
+Everything else is dropped without being rendered — objects, arrays, proxies,
+`NaN`, `Infinity`, functions, symbols, `null`, `undefined`. Dropping is
+payload-free: the entry gains a `droppedMetadataCount` integer and nothing
+else. A rejected value never appears in output, not even as a type name, since
+`String(value)` on a hostile object runs `toString` and that is somebody else's
+code deciding what your log file contains.
+
+Wrapper payloads are validated **twice** — once when `pub()`/`priv()` is called
+and again when the value is unwrapped at emit. The second check is not
+redundant. `pub(patient as any)` type-checks fine, and only the unwrap sees
+what actually arrived.
+
+Markers are recognised by membership in a module-private `WeakMap`, never by a
+property or a `Symbol`. A foreign object shaped like a `PublicValue` is not
+one, and fails validation naturally rather than by a check somebody has to
+remember to write.
+
+The payload is held in that `WeakMap` too, so there is no enumerable field to
+find. `JSON.stringify`, spreading, `String()`, and `console.log` inspection all
+yield the placeholder.
+
+### Metadata keys
+
+Keys must match `^[A-Za-z0-9._-]{1,64}$` at runtime. That stops a key from
+carrying a payload, but it does not stop `patient123` from being a key — which
+is why the strict profile adds an **approved-key catalog**:
+
+```ts
+Log.metadataKeyCatalog(['requestId', 'statusCode', 'durationMs', 'retryCount']);
+```
+
+With a catalog set, an unrecognised key is dropped and counted, in both direct
+and scoped metadata. Fail-closed, and the only mechanism here that stops a
+literal PHI key.
+
+Under `privacyDefault('private')` the catalog is **mandatory, and enforced by
+the runtime rather than by convention**: with no catalog configured, no key is
+approved, so every metadata key drops and is counted. Choosing the strict
+profile and then forgetting the catalog leaves none of the metadata you
+supplied — only the injected `droppedMetadataCount`, which is exactly the
+signal that this is what happened. Loud, and in the safe direction; not a
+silent failure open.
+
+The practical consequence is that the strict profile takes two calls, not one:
+
+```ts
+Log.privacyDefault('private');
+Log.metadataKeyCatalog(['requestId', 'statusCode', 'durationMs', 'retryCount']);
+```
+
+This applies to metadata the library itself emits. The crash handler logs under
+`errorName`, `errorMessage`, `errorFrames`, `errorFrameCount`,
+`errorFramesTruncated` and `fatal` — under `'private'`, catalog those six or
+crash reports arrive with their metadata stripped. Their *values* are already
+`pub()`-marked at the call site, because this package generates every one of
+them and none can carry caller data; but a `pub()` value does not exempt a key
+from the catalog, since the catalog exists to police key *names*.
+
+`droppedMetadataCount` is the exception and needs no entry. It is added after
+filtering rather than passing through it, and is rejected as an incoming key,
+so the count of what was dropped can never itself be dropped.
+
+---
+
+## Public by contract
+
+Four things are **not** redacted at runtime, because redacting them would make
+the logger useless — a log of `<private>` lines is not a log. They are
+constrained at build time instead, by the bundled ESLint plugin.
+
+**This enforcement is opt-in and does nothing until you turn it on.** Installing
+the package ships the rules; it does not apply them. Until you extend one of the
+configs below in your own ESLint setup *and* run ESLint in CI, nothing stops a
+template literal in a message position, and the guarantees in this section do
+not hold for your codebase.
+
+| Field | Rule | Enforced by |
+| --- | --- | --- |
+| `message` | string literal or approved constant | `no-dynamic-message` |
+| metadata keys | no computed keys, no object spreads | `no-computed-metadata-key` |
+| `correlation` | must come from `Log.newCorrelationId()` | `no-derived-correlation` |
+| `subsystem` | literal constant | `literal-subsystem` |
+
+```js
+// eslint.config.mjs
+import nitroLogger from 'react-native-nitro-logger/eslint-plugin';
+
+export default [nitroLogger.configs.strict];
+```
+
+`recommended` enables the first two. `strict` enables all four and is what the
+telehealth profile means.
+
+The rules reject variables, concatenation, template interpolation, calls,
+conditionals and dynamic thunk bodies in the message position. There are
+fixture tests for the ways people get around that by accident — aliasing,
+destructuring, wrappers, `call`/`apply` — and the plugin is run over `.js`
+files in CI as well as `.ts`.
+
+**Correlation IDs must be random and short-lived.** `Log.newCorrelationId()`
+returns one — an opaque string, not a branded type, because the enforcement is
+in the lint rule rather than in the type system. Do not derive them from a
+record identifier, and do not hash one: a hash of a small identifier space is
+trivially reversible, and it joins across sessions exactly as well as the
+original did.
+
+`no-derived-correlation` checks *provenance*, not spelling. A local
+`function newCorrelationId() { return patient.mrn }` produces exactly the leak
+the rule exists to prevent, so the generator has to be traceable to an import
+of this package.
+
+---
+
+## The compliance boundary
+
+**A build where reveal is possible is a build for synthetic data only.**
+
+The reveal branch is `__DEV__`-gated, and there is no API to turn it on at
+runtime. That absence is asserted rather than assumed: a test sweeps every
+function the privacy module exports, calls each one with a `priv('SECRET')`,
+and fails if any of them hands the payload back. Adding a reveal path to that
+module breaks the test. Three CI jobs cover the rest:
+
+- **`build-library`** inventories every `__DEV__` in the built output. It fails
+  when a new gated module appears *and* when an allowlisted one disappears —
+  the second because a vanished gate would quietly make the next check vacuous.
+- **`privacy-release-bundle`** bundles with `--dev false` and requires both that
+  the reveal sentinels are absent and that a witness token from each gated
+  module is present. Without the witness, the check would pass just as happily
+  if the module were never bundled at all.
+- The TypeScript suite asserts the runtime absence: with `__DEV__` false, a
+  private value renders as `<private>`.
+
+What this does *not* cover: a debug build renders private payloads in the clear,
+and it does so to **every configured destination**. Redaction is resolved before
+an entry is constructed, so a revealed value reaches the file sink and the
+system console exactly as it reaches `console.log` — and the file sink writes it
+to disk, where it outlives the session that produced it.
+
+That is the point of a debug build, and it is why the boundary is stated as a
+rule about data rather than a rule about builds: the enforcement is that reveal
+cannot reach production, not that reveal cannot exist.
+
+If you run a debug build against real regulated data, understand what can and
+cannot be undone. `FileDestination.purge()` removes the file sink's artifacts —
+that is the recoverable part. Everything the same entry handed to `os_log` or
+`logcat` is **not** recoverable: those are the operating system's stores, this
+library has no delete API for them, and on iOS the unified log is readable from
+a connected Mac. There is no call in this package that clears them. The only
+reliable control over that copy is not producing it in the first place, which is
+what the boundary above is for.
+
+### Logs on disk
+
+The file sink writes to app-private storage — `noBackupFilesDir` on Android,
+`Library/Logs` on iOS. Owner-only modes (0700 directories, 0600 files) are
+applied to every artifact, and on iOS each artifact also gets
+`NSFileProtectionCompleteUntilFirstUserAuthentication` and a backup-exclusion
+flag.
+
+**A log directory the writer did not create is inspected, never changed.** The
+log path is yours to choose, and nothing stops it being a directory your app
+already owns and uses. Every protection here is a property of the *directory*
+and outlives the sink: the backup exclusion is persistent and directory-wide,
+the protection class is inherited by every file created there afterwards, and
+even `0700` strips access from a directory that may be deliberately shared with
+an app group or an extension. Point a sink at `<Documents>/app.log` and claiming
+those would silently take your whole document tree out of iCloud backup.
+
+So if the directory was already there, the writer leaves it exactly as it found
+it and reports a loose mode as a `protection` degradation for you to act on. If
+the writer created the directory, it is unambiguously the writer's and gets all
+three. *Files* are different and always get all three: a log file at the log
+path is one the writer is about to append to, rotate and purge, so it counts as
+its own even if it was already there — and a `0644` log file left by an earlier
+version is exactly the thing worth tightening. Android has nothing to scope —
+its equivalent is structural (`noBackupFilesDir`), and its `restrictToOwner`
+only sets modes.
+
+The practical consequence: **if you supply your own log directory, create it
+with the protections you want.** This applies to the iOS default too —
+`Library/Logs` is a standard system directory and may well already exist, in
+which case the writer inspects it like any other. That is not a gap: what the
+backup exclusion and the protection class are actually protecting is the log
+files, and those are the writer's own artifacts, so they get both regardless of
+who made the directory around them.
+
+Those are applied, not guaranteed. When the platform refuses, the writer records
+a `protection` bit in the `degraded` bitmask and keeps logging rather than
+failing shut — losing a mode is worth reporting, not worth dropping the app's
+logs over. Read `degradation()` if you need to know. The two platforms are also
+not equivalent here: iOS's protection class makes the file cryptographically
+inaccessible until first unlock, and Android has no per-file counterpart.
+
+**`FileDestination.purge(deadlineMs)` is the compliance primitive.** It is
+synchronous and returns a `PurgeOutcome`. It deletes every artifact the writer
+can produce — active file, age sidecar, archives, and interrupted gzip staging
+files — bumps a generation so nothing in flight can write into the fresh file,
+and `fsync`s the directory so the removals survive a crash.
+
+Its reach is the file sink. It does not and cannot clear what other
+destinations did with the same entry; see the paragraph above on `os_log` and
+`logcat`.
+
+`durable` means every *pre-purge* artifact is gone and the directory has been
+synced, so the removals hold across a crash. It is not a claim that the log
+directory is left empty: a purge that succeeds and rebinds immediately opens a
+fresh, empty active file, because the alternative is a destination that accepts
+records with nowhere to put them. `durable` describes the data that was there.
+
+`durable` is false on any survivor, any deadline overrun, and any path where
+deletion failed *or could not be proven to have succeeded*: a file the platform
+cannot make a statement about is reported as a failure, never as a deletion.
+`rebound` is reported separately, because a complete deletion can still be
+followed by a failed reopen, and the destination stays fenced until it comes
+back. `discardedEntries` and `discardedBytes` say what was thrown away from the
+JS buffer, which is deliberately discarded rather than flushed — flushing it
+would write pre-purge records into the file moments before or after deleting it.
+
+`getLogFilePaths()` exists so an app can implement its own consent-gated
+support-log upload. Collecting and transmitting logs is deliberately not in
+this library: that needs a consent flow and an encryption story that belong to
+the application, not to its logger.
+
+---
+
+## Threat model, briefly
+
+Assumed hostile: values arriving as metadata, thrown values reaching the
+uncaught-error handler, and configuration numbers arriving from JavaScript.
+Where each is checked differs, and it is worth being exact:
+
+| Input | Validated in TypeScript | Validated natively |
+| --- | --- | --- |
+| Metadata values and keys | yes — primitives only, twice for wrapper payloads | **no**: native receives the already-rendered string, never the original value |
+| Thrown values | yes — every read guarded, message and frames sanitised | **no**, same reason |
+| Rotation and retention numbers | yes | yes — re-clamped independently, since `NaN` and `Infinity` cross the bridge as ordinary numbers |
+| Batch payload and entry count | yes | partly — the count must be a finite integer in range, and an empty payload with a nonzero count (or the reverse) is rejected; a nonzero count is **not** re-derived from the payload |
+
+The last row is worth being blunt about, and worth naming the layer each check
+sits in. The count crosses the bridge as a `double`, and both platforms refuse
+it unless it converts to an integer exactly: `Int(exactly:)` on iOS,
+`BridgeNumber.exactLong` on Android. Neither rounds — `2.5` is rejected, not
+silently turned into `2` — and neither accepts a NaN or an infinity, both of
+which a bare cast would quietly turn into a plausible number. The writer then
+bounds the range and rejects an empty payload carrying a nonzero count, or the
+reverse.
+
+What no layer does is parse the batch to confirm the number. Native trusts a
+plausible count. It drives loss accounting rather than what gets written, so a
+wrong-but-plausible count skews a statistic rather than corrupting the file.
+
+So "validated on both sides" is true of the numbers and of the batch framing,
+and not of the content. The content is resolved to a string in JavaScript, and
+the native side's job is to write that string without corrupting it, not to
+second-guess it.
+
+Assumed trusted: the application's own string literals, the device's storage,
+and the developer's build configuration. A logger cannot defend against an app
+that decides to log a patient record on purpose, and pretending otherwise would
+be worse than saying so.
+
+Out of scope: cross-process access to the log directory (there is no extension
+use case), and an attacker with root on the device.