@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,102 +1,191 @@
-# Changelog
-
-All notable changes to `@chipmobilesdk/rn-local-db` are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.2.0] — 2026-11-01
-
-Fixes a data-loss defect in transactions and attachment handling that failed on every
-Hermes device. **One behaviour change needs a code change** (see Changed).
-
-### Fixed
-
-- **A write from outside a transaction is no longer lost with its rollback.** The
-  connection routed every statement into whatever transaction was in flight, so a write
-  from another screen or a background sync while a transaction ran was rolled back with
-  it, and a reader outside saw uncommitted data. Each handle now queues work behind a
-  running transaction; only the executor the transaction hands out reaches it. The
-  memory adapter isolates the same way, so conformance now catches a regression. After
-  `tx.abort()` the body's remaining statements are refused instead of running in
-  autocommit.
-- **Attachments work on Hermes.** Writes and reads used Node's global `Buffer`, which
-  Hermes does not have. Byte handling is now `Uint8Array` with a self-contained base64
-  codec; the encrypted file format is unchanged.
-- **A batch upsert over a soft-deleted record restores it**, and a batch insert over one
-  conflicts — the collection API's rules. The batch used to issue an INSERT and fail the
-  whole batch on the primary key.
-- **Index names are scoped to their collection.** Two collections declaring an index of
-  the same name used to get only the first one, a UNIQUE constraint included. Existing
-  indexes are renamed on the next open; no data moves. `explain()` still reports the
-  declared name.
-- **Deleting an encrypted scope no longer needs its key.** A failing or destroyed key
-  failed the call after the scope was marked, leaving it stuck in `deleting`. The data is
-  deleted and the outcome sets `recordCountUnavailable`.
-- **Cascaded attachment removal is transaction-safe and reported.** Inside a
-  transaction, files are removed only after it commits, so a rollback no longer leaves a
-  reference to a deleted file. The reference is deleted before the file, a file that
-  could not be removed is reported in `failedRemovals`, batch deletes cascade, and the
-  memory adapter implements cascading.
-
-### Changed
-
-- **Needs a code change:** inside a transaction body, write attachments through
-  `tx.attachments()` (new) instead of `handle.attachments()`. The handle's call now waits
-  for the transaction; awaited from inside the body it is refused with
-  `TRANSACTION_STATE` after 10 seconds and the transaction rolls back, instead of
-  hanging. The same applies to `handle.collection()`, which inside a transaction was
-  already documented as a mistake.
-- `MigrationContext` no longer includes `attachments()`.
-
-### Added
-
-- `Transaction.attachments()`.
-- `WriteOutcome.cascade` on a delete when `cascadeAttachments` is on.
-- `DeletionOutcome.recordCountUnavailable`.
-
-## [0.1.0] — 2026-08-01
-
-First release. New package, no existing consumers, no migration burden.
-
-### Added
-
-- **Scope-isolated storage.** One SQLite database file per scope. Scope is bound to a handle at open and immutable for its lifetime; no read, write, or query operation accepts a scope argument, and there is no `switchScope`. Scope components are hashed — only the SHA-256 digest reaches disk, a log, or an error.
-- **Records.** `insert`, `update`, `upsert` (reporting created versus updated), `get`, `find`, `delete`, `softDelete`, `restore`. Payloads round-trip with zero coercions, and the four value conditions — record absent, field null, field absent, record soft-deleted — stay distinguishable.
-- **Queries.** Twelve operators plus `and`/`or`/`not`, multi-key sorting with a deterministic `id` tiebreaker, keyset pagination, and `count` that always agrees with the corresponding list. An invalid query is an error rather than an empty or complete result. Development-mode index-coverage reporting via `explain`.
-- **Transactions and batches.** Real ACID transactions with read-your-own-writes, explicit abort, and terminal-state rejection. Batches of up to 1,000 operations applied as one unit.
-- **Migrations.** Ascending, at most once per scope, one transaction each, with a per-scope ledger. A failing chain returns no handle and alters nothing; a downgrade is refused rather than truncating. `resetScope` is the separately named recovery path.
-- **Deletion lifecycle.** `deleteScopeData`, `deleteDatabase`, and `resetScope` as module-level functions that work with or without an open handle. Nothing is ever deleted unasked — no expiry, no eviction, no sweep on close or upgrade. Every deletion reports what it removed and what it could not.
-- **Attachments.** Package-owned artifacts with availability checks that never open the file, owner-scoped listing, opt-in cascade on record deletion, and app-triggered reconciliation for orphaned files and dangling references. Every filesystem operation is confined to the managed storage area.
-- **Encryption at rest.** Opt-in under an app-supplied key. SQLCipher for records; chunked AES-256-GCM with HKDF-derived per-artifact subkeys for files, one 256 KB chunk in flight so memory is flat in artifact size. The package never generates, persists, caches beyond the handle, returns, or logs key material, and depends on no keychain library.
-- **Backup posture.** Excluded by default. Enforced on iOS via `NSURLIsExcludedFromBackupKey`; verified and reported on Android, where participation is manifest-owned and unreachable from a library that authors no native code.
-- **Typed diagnostics.** Twenty-nine stable `DiagnosticCode` values with `isCode` so no consumer parses a message. Disk-full, filesystem-access, and corruption stay distinct. Redaction happens at construction, so no error carries a payload, query parameter, scope component, or key material in any build.
-- **`./testing` entrypoint.** In-memory adapter, the conformance suite both adapters must pass identically, deterministic reset, seeding through production write paths, and fault injection for every diagnostic code.
-
-### Documented
-
-- Six knowing divergences between the in-memory and on-device adapters, in the README.
-- The full diagnostic table with recommended recovery per condition.
-- The FR-088 budgets, and which four are hard limits.
-- The consumer data-behaviour note: what is stored, where, what leaves the device (nothing), the at-rest and backup postures, and what scope deletion does and does not guarantee.
-
-### Semver impact
-
-New package at `0.1.0`. Nothing to migrate from.
-
-| Surface | Status | Notes |
-|---|---|---|
-| Lifecycle, records, query, transaction, batch | **Stable** | Breaking changes need a major |
-| Scope deletion and reset | **Stable** | |
-| Attachments including reconciliation | **Stable** | |
-| Diagnostic codes | **Stable, additive** | A new code is a minor; renaming one is breaking |
-| Encryption and key provider | **Experimental** | Field-level encryption and posture conversion may extend it |
-| Backup posture reporting | **Experimental** | The Android `observed` / `enforcedBy` shape may change as verification improves |
-| `StorageAdapter` interface | **Experimental** | Exported so the conformance suite is usable; not yet a stable extension point |
-| Testing entrypoint | **Experimental** | |
-
-Reserved as additive minors: reactive query subscriptions, field-level encryption, in-place encryption-posture conversion, further filter operators, and further diagnostic codes. Any change to the physical layout, the artifact format, or the encryption format ships with an internal migration or is breaking.
-
-### Known limitations
-
-- **Android backup exclusion cannot be enforced by this package.** It ships the exact configuration, verifies coverage at runtime, and reports the observed posture; the manifest entry is the app's.
-- **Encryption posture cannot be converted in place.** Export, delete the scope, re-import.
-- **A transaction never spans two scopes.** One database file per scope makes this a type error rather than a runtime one.
-- **No reactive subscriptions.** Queries are pull-based in this version.
+# @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
+
+- Packaging only; no code change. The package no longer declares `engines.node`: a
+  React Native package does not run on Node, so the field only produced install
+  warnings in apps on another Node version. rn-i18n's command-line tooling does run
+  on Node; its README's compatibility table states the version it needs. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
+
+## [0.2.0] — 2026-11-01
+
+Fixes a data-loss defect in transactions and attachment handling that failed on every
+Hermes device. **One behaviour change needs a code change** (see Changed).
+
+### Fixed
+
+- **A write from outside a transaction is no longer lost with its rollback.** The
+  connection routed every statement into whatever transaction was in flight, so a write
+  from another screen or a background sync while a transaction ran was rolled back with
+  it, and a reader outside saw uncommitted data. Each handle now queues work behind a
+  running transaction; only the executor the transaction hands out reaches it. The
+  memory adapter isolates the same way, so conformance now catches a regression. After
+  `tx.abort()` the body's remaining statements are refused instead of running in
+  autocommit.
+- **Attachments work on Hermes.** Writes and reads used Node's global `Buffer`, which
+  Hermes does not have. Byte handling is now `Uint8Array` with a self-contained base64
+  codec; the encrypted file format is unchanged.
+- **A batch upsert over a soft-deleted record restores it**, and a batch insert over one
+  conflicts — the collection API's rules. The batch used to issue an INSERT and fail the
+  whole batch on the primary key.
+- **Index names are scoped to their collection.** Two collections declaring an index of
+  the same name used to get only the first one, a UNIQUE constraint included. Existing
+  indexes are renamed on the next open; no data moves. `explain()` still reports the
+  declared name.
+- **Deleting an encrypted scope no longer needs its key.** A failing or destroyed key
+  failed the call after the scope was marked, leaving it stuck in `deleting`. The data is
+  deleted and the outcome sets `recordCountUnavailable`.
+- **Cascaded attachment removal is transaction-safe and reported.** Inside a
+  transaction, files are removed only after it commits, so a rollback no longer leaves a
+  reference to a deleted file. The reference is deleted before the file, a file that
+  could not be removed is reported in `failedRemovals`, batch deletes cascade, and the
+  memory adapter implements cascading.
+
+### Changed
+
+- **Needs a code change:** inside a transaction body, write attachments through
+  `tx.attachments()` (new) instead of `handle.attachments()`. The handle's call now waits
+  for the transaction; awaited from inside the body it is refused with
+  `TRANSACTION_STATE` after 10 seconds and the transaction rolls back, instead of
+  hanging. The same applies to `handle.collection()`, which inside a transaction was
+  already documented as a mistake.
+- `MigrationContext` no longer includes `attachments()`.
+
+### Added
+
+- `Transaction.attachments()`.
+- `WriteOutcome.cascade` on a delete when `cascadeAttachments` is on.
+- `DeletionOutcome.recordCountUnavailable`.
+
+## [0.1.2] — 2026-09-12
+
+### Changed
+
+- The shipped agent skill and the README were clarified. No code change.
+
+## [0.1.1] — 2026-08-01
+
+### Changed
+
+- The package now ships its agent skill (`skills/`), which consuming apps
+  copy in with `scripts/sync-sdk-skills.mjs`. No code change.
+
+## [0.1.0] — 2026-08-01
+
+First release. New package, no existing consumers, no migration burden.
+
+### Added
+
+- **Scope-isolated storage.** One SQLite database file per scope. Scope is bound to a handle at open and immutable for its lifetime; no read, write, or query operation accepts a scope argument, and there is no `switchScope`. Scope components are hashed — only the SHA-256 digest reaches disk, a log, or an error.
+- **Records.** `insert`, `update`, `upsert` (reporting created versus updated), `get`, `find`, `delete`, `softDelete`, `restore`. Payloads round-trip with zero coercions, and the four value conditions — record absent, field null, field absent, record soft-deleted — stay distinguishable.
+- **Queries.** Twelve operators plus `and`/`or`/`not`, multi-key sorting with a deterministic `id` tiebreaker, keyset pagination, and `count` that always agrees with the corresponding list. An invalid query is an error rather than an empty or complete result. Development-mode index-coverage reporting via `explain`.
+- **Transactions and batches.** Real ACID transactions with read-your-own-writes, explicit abort, and terminal-state rejection. Batches of up to 1,000 operations applied as one unit.
+- **Migrations.** Ascending, at most once per scope, one transaction each, with a per-scope ledger. A failing chain returns no handle and alters nothing; a downgrade is refused rather than truncating. `resetScope` is the separately named recovery path.
+- **Deletion lifecycle.** `deleteScopeData`, `deleteDatabase`, and `resetScope` as module-level functions that work with or without an open handle. Nothing is ever deleted unasked — no expiry, no eviction, no sweep on close or upgrade. Every deletion reports what it removed and what it could not.
+- **Attachments.** Package-owned artifacts with availability checks that never open the file, owner-scoped listing, opt-in cascade on record deletion, and app-triggered reconciliation for orphaned files and dangling references. Every filesystem operation is confined to the managed storage area.
+- **Encryption at rest.** Opt-in under an app-supplied key. SQLCipher for records; chunked AES-256-GCM with HKDF-derived per-artifact subkeys for files, one 256 KB chunk in flight so memory is flat in artifact size. The package never generates, persists, caches beyond the handle, returns, or logs key material, and depends on no keychain library.
+- **Backup posture.** Excluded by default. Enforced on iOS via `NSURLIsExcludedFromBackupKey`; verified and reported on Android, where participation is manifest-owned and unreachable from a library that authors no native code.
+- **Typed diagnostics.** Twenty-nine stable `DiagnosticCode` values with `isCode` so no consumer parses a message. Disk-full, filesystem-access, and corruption stay distinct. Redaction happens at construction, so no error carries a payload, query parameter, scope component, or key material in any build.
+- **`./testing` entrypoint.** In-memory adapter, the conformance suite both adapters must pass identically, deterministic reset, seeding through production write paths, and fault injection for every diagnostic code.
+
+### Documented
+
+- Six knowing divergences between the in-memory and on-device adapters, in the README.
+- The full diagnostic table with recommended recovery per condition.
+- The FR-088 budgets, and which four are hard limits.
+- The consumer data-behaviour note: what is stored, where, what leaves the device (nothing), the at-rest and backup postures, and what scope deletion does and does not guarantee.
+
+### Semver impact
+
+New package at `0.1.0`. Nothing to migrate from.
+
+| Surface | Status | Notes |
+|---|---|---|
+| Lifecycle, records, query, transaction, batch | **Stable** | Breaking changes need a major |
+| Scope deletion and reset | **Stable** | |
+| Attachments including reconciliation | **Stable** | |
+| Diagnostic codes | **Stable, additive** | A new code is a minor; renaming one is breaking |
+| Encryption and key provider | **Experimental** | Field-level encryption and posture conversion may extend it |
+| Backup posture reporting | **Experimental** | The Android `observed` / `enforcedBy` shape may change as verification improves |
+| `StorageAdapter` interface | **Experimental** | Exported so the conformance suite is usable; not yet a stable extension point |
+| Testing entrypoint | **Experimental** | |
+
+Reserved as additive minors: reactive query subscriptions, field-level encryption, in-place encryption-posture conversion, further filter operators, and further diagnostic codes. Any change to the physical layout, the artifact format, or the encryption format ships with an internal migration or is breaking.
+
+### Known limitations
+
+- **Android backup exclusion cannot be enforced by this package.** It ships the exact configuration, verifies coverage at runtime, and reports the observed posture; the manifest entry is the app's.
+- **Encryption posture cannot be converted in place.** Export, delete the scope, re-import.
+- **A transaction never spans two scopes.** One database file per scope makes this a type error rather than a runtime one.
+- **No reactive subscriptions.** Queries are pull-based in this version.