@chipmobilesdk/rn-local-db 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,164 @@
 # @chipmobilesdk/rn-local-db
 
+## 0.5.0
+
+### Minor Changes
+
+- Every peer range has an upper bound, and no package declares a peer it does not use. ([#21](https://github.com/operationd8979/chip-mobile-sdk/pull/21))
+
+  A peer range is now a caret, a tilde or an explicit `<`, except for `react` and
+  `react-native`: an app brings exactly one of each, so a floor is the only useful thing
+  to say about them. Every other peer is a library the app installs beside us, and an
+  open `>=` was a promise about versions nobody had run — mmkv 3→4 lost entitlements and
+  pending purchases exactly that way.
+
+  **Four of the new ceilings exclude a version that is already published**, so an app
+  that took the open range at its word may now see a peer warning. The new bound is the
+  major this release is tested against, which is the thing the old range failed to say:
+
+  | Peer | Was | Now | Published above the ceiling |
+  |---|---|---|---|
+  | `react-native-app-auth` (rn-auth) | `>=8` | `^8.0.0` | 9.0.0 |
+  | `react-native-keychain` (rn-auth) | `>=10` | `^10.0.0` | 11.0.0 |
+  | `@op-engineering/op-sqlite` (rn-local-db) | `>=17.1.0` | `^17.1.0` | 18.x, 19.x |
+  | `@react-native-firebase/messaging` (rn-notification) | `>=26.0.0` | `^26.0.0` | 27.x |
+
+  The others — `react-native-vision-camera` `^5.1.1`, `react-native-svg` `^15.15.0`,
+  `react-native-unistyles` `^3.2.0`, `@dr.pogodin/react-native-fs` `^2.39.2`,
+  `react-native-quick-crypto` `^1.0.0`, `react-native-notify-kit` `^10.5.0`,
+  `react-native-localize` `^3.7.0`, `react-native-mmkv` `^4.0.0` — exclude nothing that
+  exists today. rn-payment's mmkv range was already bounded (`>=4.0.0 <5`) and is now
+  written as the caret that means the same thing.
+
+  Peers nothing imports are gone. `rn-theme`, `rn-local-db` and `rn-notification` asked
+  for `react` without having a component or a hook between them; `rn-auth`, `rn-ai` and
+  `rn-i18n` asked for `react-native` without touching a React Native API (rn-auth reaches
+  both native modules through `lazyPeer`, rn-i18n formats on `Intl`); `rn-notification`
+  asked for `@react-native-firebase/app`, which messaging declares itself. `rn-ai` no
+  longer peers on `@chipmobilesdk/rn-auth` at all — it asks for a `TokenProvider`, a
+  two-method interface rn-auth's `auth` satisfies, so an app with its own token source
+  installs nothing extra. An app that enables push or signs in through rn-auth installs
+  the same packages as before; it is the manifest that stopped overstating.
+
+  `react-native-localize` is declared optional, which is what the code already did: the
+  time-zone reader goes through `lazyPeer` and falls back to `Intl` without it. The
+  `peerDependenciesMeta` entries that said `optional: false` are gone — that is npm's
+  default, and writing it down only invited the question of which peers were undecided.
+
+  `npm run check:manifests` now fails on an unbounded peer range, a peer nothing in
+  `src/` imports, and a `peerDependenciesMeta` entry for either, so the policy holds
+  without anyone remembering it.
+
+- Every package now ships built JavaScript with declaration files, instead of asking the
+  app to compile its TypeScript. ([#22](https://github.com/operationd8979/chip-mobile-sdk/pull/22))
+
+  Each tarball carries `lib/commonjs`, `lib/module` and `lib/typescript` (built with
+  `react-native-builder-bob`), and `src/` alongside them. What that changes for a
+  consumer:
+
+  - **Nothing to add to `transformIgnorePatterns`.** `require` resolves to the CommonJS
+    build, so an app's Jest loads this package without being told to transform it. That
+    was the one thing every consuming app had to know about us (DEP-04).
+  - **Typechecking reads our `.d.ts`** rather than compiling our source under our
+    `tsconfig`. A consumer's stricter — or looser — settings no longer meet our code.
+  - **`import` resolves to ESM**, so a bundler can tree-shake what it does not use.
+
+  No exported name changed, and no subpath moved: `.`, `./testing`, `./push`,
+  `./advanced`, `./app-auth`, `./keychain` and rn-core's twelve subpaths resolve exactly
+  as before, each now with its own declarations for both module systems. publint and
+  `attw --profile node16` pass on all twelve packages, which they could not before.
+
+  Inside the monorepo nothing changed either, and that is deliberate: every subpath also
+  declares a private `chipmobilesdk-source` condition pointing at its TypeScript, and
+  Metro, Jest and `tsc` here ask for that condition first. The demo app bundles 371
+  modules straight from `packages/*/src`, so editing a package still changes the app with
+  no build step, and coverage is still measured on the source. The condition is named for
+  this organization rather than using the conventional `source` because third-party
+  packages declare that one too — `@dr.pogodin/react-native-fs` does — and asking for it
+  pulled their sources into our stricter compile.
+
+  `npm run build:packages` builds everything, `prepack` rebuilds before any `npm pack`,
+  and `lib/` is git-ignored: the published bytes are produced by the release, never
+  committed. `npm run check:manifests` now fails a package whose `main`, `module`,
+  `types`, `source` condition, `files`, build script or `prepack` do not match this shape.
+
+### Patch Changes
+
+- Each package's public API and its weight are now recorded in the repository, so a change
+  to either is reviewed rather than discovered. ([#23](https://github.com/operationd8979/chip-mobile-sdk/pull/23))
+
+  `packages/<pkg>/etc/*.api.md` is an api-extractor report per entrypoint — twenty-seven
+  of them, generated from the declarations the package publishes and committed. A renamed
+  type, a widened union, one more optional field: all of it shows up in a pull request's
+  diff. `npm run check:api` fails when a report is out of date and `npm run api:update`
+  rewrites them.
+
+  A report that moves now needs a **minor or major** changeset for that package.
+  `check:changesets` enforces it, because the report is generated from what the package
+  publishes, and a patch release that moves the public surface is how a consumer's build
+  breaks on `npm update`. A report added for the first time is a baseline, not a change.
+  `./testing` deliberately has no report: test doubles are not a surface a release is
+  gated on.
+
+  `npm run check:size` holds every entrypoint to a budget in `.size-limit.json`, measured
+  on the ESM build with peers and rn-core treated as external — they are what an app
+  installs beside us, not our weight. Each budget started at today's measurement plus five
+  per cent, so growth becomes a decision someone makes instead of a drift nobody sees. The
+  current figures run from 500 B (`rn-core/lazy`) to 19 kB (rn-notification).
+
+  No behaviour or API changed in this release; the entry is here so the changelog records
+  when the reports and the budgets began.
+
+- The crypto footprint is written down, and the device gate for encryption is a checklist
+  someone can run. ([#21](https://github.com/operationd8979/chip-mobile-sdk/pull/21))
+
+  `@noble/hashes` was considered for HKDF and SHA, and declined (DEP-10). It removes no
+  dependency — `react-native-quick-crypto` stays for AES-GCM either way, so moving HKDF
+  out of it buys nothing at install time — while adding it would give this package a
+  second runtime dependency, against the rule that rn-core is the only one. The hashing
+  that genuinely had to work without a native module, the scope digest, is already plain
+  TypeScript. The README now states which primitive lives where and why, and when to
+  revisit.
+
+  `CipherModule` no longer declares `createHash`. Nothing called it: the scope digest is
+  computed in TypeScript precisely so a scope can be resolved by an app that never
+  enables encryption and may have no crypto module installed. The port now asks for the
+  two things the package actually uses, AES-256-GCM and `hkdfSync`.
+
+  The README's "Demo and validation" section gained **Device checks for the encrypted
+  database**: the steps to run after every op-sqlite or quick-crypto upgrade, with the
+  diagnostic each one must produce. It also stops claiming the LocalDB demo screens run
+  on the memory adapter — nothing overrides the adapter, so they exercise op-sqlite on
+  the device, which is what makes them evidence. Every step was run on a Pixel 3a
+  emulator (API 36, release build) before being written down: the four key-provider modes
+  answer `opened successfully`, `KEY_INVALID`, `KEY_PROVIDER_FAILED` and `KEY_INVALID`,
+  the wrong posture answers `ENCRYPTION_MISMATCH` with the data still readable, and a
+  32 MB artifact writes in 128 chunks.
+- Updated dependencies ([#22](https://github.com/operationd8979/chip-mobile-sdk/pull/22), [#23](https://github.com/operationd8979/chip-mobile-sdk/pull/23)):
+  - @chipmobilesdk/rn-core@0.2.0
+
+## 0.4.0
+
+### Minor Changes
+
+- Opening a database whose declared schema has not changed now runs no DDL: the applied schema is recorded and compared, instead of re-running CREATE TABLE, PRAGMA table_info and CREATE INDEX for every collection on each start. Index changes take effect — adding `unique`, changing the fields of an index, or removing its declaration used to do nothing. A newly declared field is backfilled the way a write projects it, so an object or array value is NULL for old records as for new ones. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Writes make fewer round-trips. `insert` is one statement and reports `RECORD_CONFLICT` without writing, `upsert` on an existing record is one statement, and a batch reads the state of everything it touches once per collection rather than once per operation. A record is serialized once per write, and its size is measured without allocating a copy.
+
+- `deleteScopeData`, `resetScope` and `deleteDatabase` now close the connection of any handle still open on what they delete and give back its slot in the open-handle budget. The handle keeps reporting `SCOPE_DELETED`; the app no longer has to close a handle it cannot use, and eight sign-outs without a `close()` no longer end in `OPEN_FAILED`. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  A database file laid out by a newer release of the package is refused with `SCHEMA_DOWNGRADE` instead of being opened. `setStorageAdapter` is exported from `./testing`, so a test can point `openDatabase` at the in-memory adapter. `MigrationContext.execute` types its parameters as `SqlParameter[]` (string, number, boolean or null) rather than `unknown[]`.
+
+  Internal: one builder for INSERT and UPDATE statements shared by the collection API and batches, one definition of a valid migration chain, the handle split out of the open path, and unused code removed.
+
+- `attachments().write()` accepts `sourcePath` in place of `content`. The file is copied natively when the database is unencrypted, and read and encrypted 256 KB at a time when it is, so writing a large photo or recording no longer needs the whole file in JS memory as base64. `content` keeps working and is still decoded whole. The in-memory adapter takes a `readSourceFile` option for tests that write by path. The README, the changelog and the contract comment no longer claim that write memory was flat before this. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+### Patch Changes
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
 ## 0.3.0
 
 ### Minor Changes
@@ -154,7 +313,7 @@ First release. New package, no existing consumers, no migration burden.
 - **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.
+- **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. (Write memory was not in fact flat until `sourcePath` arrived in 0.4.0: a base64 `content` is decoded whole.) 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.

package/README.md

@@ -356,7 +356,7 @@ Every one returns a `DeletionOutcome` rather than a bare success — what was re
 
 If a deletion is interrupted — a force-quit, a battery death — the next open reports `SCOPE_DELETED` rather than presenting the scope as healthy. Call `deleteScopeData` again to finish it.
 
-A handle whose scope is deleted beneath it reports `SCOPE_DELETED` on its next use. The deletion does not wait for it, and nothing revives it: open a new handle and rebuild whatever was built on the old one. An app that retries through the dead handle gets the same error every time, which reaches the user as a screen that only relaunching can fix.
+A handle whose scope is deleted beneath it reports `SCOPE_DELETED` on its next use. The deletion does not wait for it: it closes that handle's connection and gives back its slot in the open-handle budget, so the app does not have to close a handle it can no longer use. Nothing revives it: open a new handle and rebuild whatever was built on the old one. An app that retries through the dead handle gets the same error every time, which reaches the user as a screen that only relaunching can fix.
 
 ---
 
@@ -381,10 +381,25 @@ await attachments.listFor({ collection: 'notes', id: 'n1' });
 await attachments.remove('photo-1');
 ```
 
-`AttachmentInput.content` is one complete base64 string. The current public
-write contract therefore requires the app to hold the encoded payload, and the
-native adapter decodes that full string before processing encrypted chunks.
-Use range reads to avoid loading an entire stored artifact when consuming it.
+For anything large, pass the file instead of its content:
+
+```ts
+await attachments.write({
+  id: 'video-1',
+  contentType: 'video/mp4',
+  sourcePath: recording.path, // absolute path; a file:// prefix is accepted
+});
+```
+
+With `sourcePath` the bytes never pass through JS as a whole: an unencrypted
+artifact is one native file copy, and an encrypted one is read and encrypted
+256 KB at a time, so write memory does not grow with the file. The source file
+is left where it is. `content` is one complete base64 string, held by the app
+and decoded in one piece — fine for a thumbnail, several times the file's size
+in memory for a video. Use range reads to avoid loading an entire stored
+artifact when consuming it; a read without a range returns the whole artifact
+as one string. The in-memory adapter has no filesystem: give it
+`createMemoryAdapter({ readSourceFile })` to test a write by path.
 
 **Availability** answers from `stat()` and, for an encrypted artifact, the 22-byte header — never a content byte and never a decryption. A gallery showing fifty thumbnails does not decrypt fifty files to ask whether they are there.
 
@@ -444,10 +459,28 @@ The provider receives the resolved scope so you can key per identity — which i
 
 **Records** are protected by SQLCipher. **Artifacts** use chunked AES-256-GCM:
 256 KB chunks, a per-artifact subkey derived with HKDF, and an authentication
-tag per chunk. Encryption and range decryption operate by chunk, but the
-current write API first decodes the complete base64 input. Peak write memory is
-therefore not flat in artifact size; size large media before passing it to this
-version.
+tag per chunk. Encryption and range decryption operate by chunk. A write from
+`sourcePath` holds one chunk at a time; a write from base64 `content` first
+decodes the complete input, so its memory grows with the artifact.
+
+### Crypto footprint: what is native and what is not
+
+| Primitive | Where | Why |
+|---|---|---|
+| SQLCipher (records) | `@op-engineering/op-sqlite`, built with the SQLCipher flag | Page-level encryption of the database file; nothing in JavaScript can do this |
+| AES-256-GCM (artifacts) | `react-native-quick-crypto` | 256 KB chunks of a photo or recording; this is where native speed is the whole point |
+| HKDF-SHA256 (per-artifact subkey) | `react-native-quick-crypto` | One hash per artifact write, in the module AES-GCM already requires |
+| SHA-256 (scope digest) | plain TypeScript, `src/scope/hash.ts` | Runs on **every** scope resolution, including apps that never enable encryption and so may not have a crypto module installed at all |
+
+**`@noble/hashes` was considered for HKDF and SHA, and declined** (DEP-10, WS4-08).
+It would not remove a dependency: `react-native-quick-crypto` stays for AES-GCM
+either way, so moving HKDF out of it buys nothing at install time, while adding
+`@noble/hashes` would give this package a second runtime dependency — against the rule
+that rn-core is the only one (`npm run check:manifests` enforces it) — or a vendored
+copy to maintain. The hashing that genuinely had to work without a native module, the
+scope digest, is already plain TypeScript and byte-for-byte equal to Node's
+`createHash('sha256')` under test. Revisit only if quick-crypto stops shipping an
+`hkdfSync`, or if AES-GCM moves out of it.
 
 A key-provider failure while the device is locked is an **expected condition**, not a bug:
 
@@ -601,7 +634,11 @@ private and unsupported.
 ## Testing against the in-memory adapter
 
 ```ts
-import { createMemoryAdapter, resetMemoryAdapter } from '@chipmobilesdk/rn-local-db/testing';
+import {
+  createMemoryAdapter,
+  resetMemoryAdapter,
+  setStorageAdapter,
+} from '@chipmobilesdk/rn-local-db/testing';
 
 const adapter = createMemoryAdapter();
 beforeEach(() => resetMemoryAdapter(adapter));
@@ -639,7 +676,7 @@ runConformanceSuite(() => myAdapter, reset, hooks);
 
 ### Documented divergences
 
-The in-memory adapter is faithful, not identical. These six differences are known, deliberate, and the complete list — anything else that differs is a bug:
+The in-memory adapter is faithful, not identical. These seven differences are known, deliberate, and the complete list — anything else that differs is a bug:
 
 | Divergence | Why |
 |---|---|
@@ -649,6 +686,7 @@ The in-memory adapter is faithful, not identical. These six differences are know
 | **Backup posture**: reports the requested value | There is no filesystem to set an attribute on and no manifest to verify. |
 | **Artifact chunking**: content is stored whole | Chunk boundaries, nonces, and authentication tags are exercised by the cipher's own tests. |
 | **Corruption and disk-full**: not spontaneously reachable | Both are device conditions. Use `injectFault` to reach the codes. |
+| **Attachments by `sourcePath`**: read through `readSourceFile`, an option of `createMemoryAdapter` | There is no filesystem to read the path from. Without the option the write is refused with `STORAGE_ACCESS`. |
 
 ---
 
@@ -680,9 +718,9 @@ Four are **hard limits** with a typed error. The rest are soft: exceeding them i
 | Node (tooling) | 22.11+ |
 | Android | `minSdkVersion` 24, `targetSdkVersion` 36 |
 | iOS | 15.1+ |
-| `@op-engineering/op-sqlite` | >= 17.1.0 |
-| `@dr.pogodin/react-native-fs` | >= 2.39.2 |
-| `react-native-quick-crypto` | >= 1.0.0 — **optional**, only for encryption. Its own peer `react-native-quick-base64` must also be in the **app's** `dependencies`: autolinking compiles only what the app declares, and without it the first encrypted attachment fails with `'QuickBase64' could not be found` |
+| `@op-engineering/op-sqlite` | `^17.1.0` |
+| `@dr.pogodin/react-native-fs` | `^2.39.2` |
+| `react-native-quick-crypto` | `^1.0.0` — **optional**, only for encryption. Its own peer `react-native-quick-base64` must also be in the **app's** `dependencies`: autolinking compiles only what the app declares, and without it the first encrypted attachment fails with `'QuickBase64' could not be found` |
 
 **Storage location**: app-private documents directory, under `chipmobilesdk-localdb/`.
 **Backup mechanism**: `NSURLIsExcludedFromBackupKey` on iOS; `dataExtractionRules` / `fullBackupContent` on Android.
@@ -714,9 +752,13 @@ Written for the privacy disclosure a consuming app has to make.
 
 ## Demo and validation
 
-The demo app exposes ten `src/screens/LocalDb*Screen.tsx` scenarios and uses
-the testing entrypoint's memory adapter so the UI can run without native
-database setup. Run from the repository root:
+The demo app exposes ten `src/screens/LocalDb*Screen.tsx` scenarios. They run on the
+**real** adapter — op-sqlite on the device — because nothing overrides it; only
+`LocalDbDiagnosticsScreen` reaches for the testing entrypoint, and only for fault
+injection. So the screens are evidence about native behaviour, which is the point of
+the checklist below.
+
+Node-side gates, from the repository root:
 
 ```bash
 npm run typecheck --workspace @chipmobilesdk/rn-local-db
@@ -724,5 +766,43 @@ npm run pack:check --workspace @chipmobilesdk/rn-local-db
 npm run validate
 ```
 
-Physical-device SQLCipher, backup, corruption, and large-artifact evidence are
-separate release gates; the memory demo does not prove those native behaviors.
+### Device checks for the encrypted database
+
+SQLCipher and AES-GCM live in two native modules this package does not control
+(`@op-engineering/op-sqlite`, `react-native-quick-crypto`), and neither is exercised by
+a Jest run. **Run this after every upgrade of either one, and before a release that
+touches encryption** (WS4-08). It takes a few minutes on one device.
+
+```bash
+# A release build: a debug bundle's timings say nothing about chunked AES-GCM.
+npx react-native run-android --mode release   # or: adb install -r <apk>
+```
+
+Then, in the app's sidebar:
+
+1. **LocalDB · Encryption** → *Write to both*. The two scopes must disagree: `Guest
+   scope encrypted: false` reading back `Stored in the clear`, `Tenant scope encrypted:
+   true` reading back `Stored under a key`. If both report `false`, the app is missing
+   the SQLCipher build flag — the package answers `ENCRYPTION_UNAVAILABLE` rather than
+   writing plaintext, so check the flag before suspecting this package.
+2. **Key provider** → each of the four modes, each followed by *Open with this key*.
+   The expected diagnostics are `opened successfully`, then `KEY_INVALID` (wrong key,
+   not retryable), `KEY_PROVIDER_FAILED` (device locked, **retryable**) and
+   `KEY_INVALID` again (no key returned — an empty key is an invalid one, not a
+   different condition). Then *Open with the wrong posture* → `ENCRYPTION_MISMATCH`,
+   and `Data still readable with the correct key: yes`. That last line is the one that
+   matters: none of these paths opens, truncates or recreates the database.
+3. **Large artifacts** → *Write 1 MB*, *8 MB*, *32 MB*. All three must complete. The
+   32 MB run reports `128 chunk(s)`, which is the 256 KB chunking doing its job
+   (FR-107a), followed by a 256 KB range read and a reconcile with `0 orphans, 0
+   dangling`. The panel reports durations, not memory: watch the device's memory graph
+   while it runs, and it must not scale with the file.
+4. **LocalDB · Attachments** → *Attach a file* (inventory shows `available · 16384
+   bytes`), *Read a byte range*, *Escape the managed area* (must be refused, not
+   served), then *Reconcile and reclaim* and read the counts.
+
+Record the device, the OS version and the two native module versions with the result.
+As of 2026-11, on a Pixel 3a emulator (API 36, release build, op-sqlite 17.1.3,
+quick-crypto 1.1.6): every expectation above held, with the 32 MB write at 4,200 ms and
+the 256 KB range read at 33 ms. Backup/restore and corruption recovery are not covered
+here — corruption needs a deliberately damaged file — and remain separate gates.

package/lib/commonjs/adapter/budgets.js

@@ -0,0 +1,79 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.acquireHandleSlot = acquireHandleSlot;
+Object.defineProperty(exports, "assertArtifactWithinBudget", {
+  enumerable: true,
+  get: function () {
+    return _budgets.assertArtifactWithinBudget;
+  }
+});
+Object.defineProperty(exports, "assertBatchWithinBudget", {
+  enumerable: true,
+  get: function () {
+    return _budgets.assertBatchWithinBudget;
+  }
+});
+Object.defineProperty(exports, "assertRecordWithinBudget", {
+  enumerable: true,
+  get: function () {
+    return _budgets.assertRecordWithinBudget;
+  }
+});
+exports.releaseHandleSlot = releaseHandleSlot;
+exports.resetHandleSlots = resetHandleSlots;
+Object.defineProperty(exports, "serializedSize", {
+  enumerable: true,
+  get: function () {
+    return _budgets.serializedSize;
+  }
+});
+var _config = require("../contract/config.js");
+var _errors = require("../contract/errors.js");
+var _errors2 = require("../diagnostics/errors.js");
+var _budgets = require("../query/budgets.js");
+/**
+ * Where the FR-088 budgets are actually enforced.
+ *
+ * The checks live in `query/budgets.ts` so both adapters share them; this
+ * module is the adapter-layer entry point, and exists so there is one place
+ * to answer "which budgets are hard?" — per-record size, batch size, page
+ * size, and artifact size, each with a typed error (FR-088a).
+ *
+ * The rest are soft by design. Exceeding 100,000 records in a collection is
+ * slow, not an error, and refusing the 100,001st write would destroy data an
+ * app already holds. Degraded behavior is documented in the README instead.
+ */
+
+/**
+ * Concurrently open handles.
+ *
+ * Each one holds a native connection and its write-ahead log, so an app that
+ * leaks handles runs out of file descriptors rather than slowing down. Eight
+ * is generous for the multi-identity case FR-008b describes and low enough
+ * that a leak surfaces during development instead of in the field.
+ */
+let openHandles = 0;
+function acquireHandleSlot() {
+  if (openHandles >= _config.Budgets.MAX_OPEN_HANDLES) {
+    (0, _errors2.raise)(_errors.DiagnosticCodes.OPEN_FAILED, {
+      message: 'too many database handles are open',
+      detail: {
+        count: openHandles,
+        limit: _config.Budgets.MAX_OPEN_HANDLES
+      }
+    });
+  }
+  openHandles += 1;
+}
+function releaseHandleSlot() {
+  openHandles = Math.max(0, openHandles - 1);
+}
+
+/** Between tests. */
+function resetHandleSlots() {
+  openHandles = 0;
+}
+//# sourceMappingURL=budgets.js.map

package/lib/commonjs/adapter/budgets.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_config","require","_errors","_errors2","_budgets","openHandles","acquireHandleSlot","Budgets","MAX_OPEN_HANDLES","raise","DiagnosticCodes","OPEN_FAILED","message","detail","count","limit","releaseHandleSlot","Math","max","resetHandleSlots"],"sourceRoot":"../../../src","sources":["adapter/budgets.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,QAAA,GAAAF,OAAA;AACA,IAAAG,QAAA,GAAAH,OAAA;AAhBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAII,WAAW,GAAG,CAAC;AAEZ,SAASC,iBAAiBA,CAAA,EAAS;EACzC,IAAID,WAAW,IAAIE,eAAO,CAACC,gBAAgB,EAAE;IAC5C,IAAAC,cAAK,EAACC,uBAAe,CAACC,WAAW,EAAE;MAClCC,OAAO,EAAE,oCAAoC;MAC7CC,MAAM,EAAE;QAAEC,KAAK,EAAET,WAAW;QAAEU,KAAK,EAAER,eAAO,CAACC;MAAiB;IAC/D,CAAC,CAAC;EACH;EACAH,WAAW,IAAI,CAAC;AACjB;AAEO,SAASW,iBAAiBA,CAAA,EAAS;EACzCX,WAAW,GAAGY,IAAI,CAACC,GAAG,CAAC,CAAC,EAAEb,WAAW,GAAG,CAAC,CAAC;AAC3C;;AAEA;AACO,SAASc,gBAAgBA,CAAA,EAAS;EACxCd,WAAW,GAAG,CAAC;AAChB","ignoreList":[]}