feat: expose dbIntegrityCheck and checkDatabaseIntegrity across all SDKs

[insipx]

Top of the DB-integrity stack (on #4028). One combined PR bringing the integrity API to every remaining SDK surface, mirroring the node implementation:

• bindings/wasm: IntegrityCheckLevel / IntegrityCheckOutcome, async client.dbIntegrityCheck(level?), free checkDatabaseIntegrity(dbPath, level?) (no key — wasm DBs are unencrypted)
• browser-sdk: client method through the worker RPC; free fn via the OPFS worker (SAH pool lives in a worker context); barrel re-exports
• bindings/mobile (uniffi): FfiIntegrityCheckLevel/FfiIntegrityCheckOutcome, FfiXmtpClient.db_integrity_check, keyed free check_database_integrity — spawn_blocking around the sync core; key conversion mirrors create_client
• sdks/android: Kotlin wrappers + companion static; bindings regenerated + gradle build verified locally
• sdks/ios: Swift wrappers + XCTest; authored against verified uniffi naming conventions, compile gated by CI

Same six outcome strings everywhere (ok|corrupt|unreadable|saltMissing|locked|failed). Verified per-surface: just wasm check, real headless-chromium vitest runs (browser), 3 backend-connected uniffi tests, gradle build + spotless (android); iOS via CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01V1AXHNsnQmHW174i5rRUEb

[claude]

Claude finished @insipx's task —— View job

---

PR Review - Database Integrity Check API

Review Date: 2026-08-27 15:47 UTC

Reviewed the implementation of dbIntegrityCheck and checkDatabaseIntegrity across all SDK surfaces. The PR successfully brings the integrity API to WASM, browser, mobile/uniffi, Android, and iOS with consistent naming and behavior.

✅ Strengths

1. Consistent API across platforms - Same six outcome strings everywhere (ok|corrupt|unreadable|saltMissing|locked|failed)
2. Good test coverage - Tests present in uniffi (2 tests), Android (2 tests), iOS (1 combined test), and browser vitest
3. Proper async handling - Mobile bindings correctly use spawn_blocking for the sync check (bindings/mobile/src/mls.rs:853)
4. Documentation parity - QUICK vs FULL level docs now accurately describe limitations after addressing reviewer feedback

🔍 Code Quality Observations

1. Missing error test coverage (minor)

While the happy path is well tested, there's limited coverage of error scenarios across SDKs:

• uniffi has a "wrong key → unreadable" test (bindings/mobile/src/mls/tests/integrity.rs:55-86)
• Android and iOS tests only verify the ok outcome
• Consider adding tests for corrupt, locked, and failed outcomes to match the comprehensive uniffi coverage

2. Test isolation concern (Android)

The Android static test (testCheckDatabaseIntegrityStatic) releases the DB connection but doesn't fully shut down the client:

runBlocking { client.dropLocalDatabaseConnection() }
val outcome = runBlocking { Client.checkDatabaseIntegrity(client.dbPath, key) }

The comment says "read-only connection isn't opened against a live client" but the client object still exists. The uniffi test does this more cleanly by calling shutdown():

client.shutdown().await.unwrap();
let outcome = check_database_integrity(db_path, Some(key), None).await.unwrap();

Consider matching the uniffi pattern for cleaner test semantics.

3. Unresolved review thread

The macroscopeapp review comment about read-only database handling remains unresolved. The reviewer explicitly states (sdks/ios/Sources/XMTPiOS/Client.swift:814):

"I don't see that amended change in the current PR: native.rs still returns Failed immediately when mode=rw fails, and by_path_checks_read_only_files is not present."

This contradicts the author's claim that it was "addressed in the amended core commit." The PR should either:

• Include the fallback to mode=ro when mode=rw fails, or
• Update the API documentation to clarify that write permissions are required

4. WASM implementation difference (architectural)

WASM runs the check directly without spawn_blocking (bindings/wasm/src/integrity.rs:68-71):

let result = self.inner_client().db_integrity_check(level.into()).map_err(ErrorWrapper::js)?;

This is correctly documented ("single-threaded, so this runs the (sync) core check directly") but creates a platform difference where WASM can block the event loop during intensive FULL checks. This is acceptable but worth noting for consumer documentation.

🛡️ Security & Performance

• Encryption key handling: Proper validation in mobile bindings (32-byte check with clear error message) ✅
• Blocking operations: Correctly isolated via spawn_blocking on mobile ✅
• Connection management: WASM/browser uses SAH worker context appropriately ✅

📊 Test Coverage Gap

Codecov shows 9 lines missing coverage in bindings/mobile/src/mls.rs (78.57% patch coverage). The missing lines appear to be in the free function check_database_integrity error handling paths. The existing tests cover:

• Happy path (ok)
• Wrong key (unreadable)

Missing coverage likely includes:

• Empty/None encryption key path
• Level parameter variations (FULL vs QUICK)

Recommendations

1. Critical: Resolve the read-only database issue raised by macroscopeapp before merging
2. Add error scenario tests to Android/iOS to match uniffi coverage depth
3. Consider calling shutdown() in Android static test for cleaner semantics
4. Document the WASM event loop blocking consideration for FULL checks

---

Overall this is solid work with good cross-platform consistency. The main blocker is resolving the outstanding read-only database review comment.

---

[codecov]

Codecov Report

❌ Patch coverage is 78.57143% with 9 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (insipx/db-integrity-check@f4a43d0). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
bindings/mobile/src/mls.rs	78.57%	9 Missing ⚠️

Additional details and impacted files

@@                     Coverage Diff                      @@
##             insipx/db-integrity-check    #4038   +/-   ##
============================================================
  Coverage                             ?   85.97%           
============================================================
  Files                                ?      421           
  Lines                                ?    68924           
  Branches                             ?        0           
============================================================
  Hits                                 ?    59257           
  Misses                               ?     9667           
  Partials                             ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[macroscopeapp]

🟡 Medium XMTPiOS/Client.swift:814

Client.checkDatabaseIntegrity returns a failed outcome for a readable database that is not writable, such as a copied diagnostic DB on read-only media, instead of performing the advertised read-only check. The native checker reached at this call opens the supplied path with SQLite URI mode=rw before enabling query_only; open it read-only (or explicitly change the API contract) so read-only databases can be checked.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @sdks/ios/Sources/XMTPiOS/Client.swift around line 814:

`Client.checkDatabaseIntegrity` returns a `failed` outcome for a readable database that is not writable, such as a copied diagnostic DB on read-only media, instead of performing the advertised read-only check. The native checker reached at this call opens the supplied path with SQLite URI `mode=rw` before enabling `query_only`; open it read-only (or explicitly change the API contract) so read-only databases can be checked.

[insipx]

Addressed in the amended core commit: the native checker now falls back to mode=ro when the mode=rw open fails, so read-only diagnostic copies (the exact forensic use-case this API serves) can be checked; WAL recovery is impossible on read-only files anyway, making ro safe there. Regression test: by_path_checks_read_only_files (0444 db + sidecar → Ok).

[macroscopeapp]

I don’t see that amended change in the current PR: native.rs still returns Failed immediately when mode=rw fails, and by_path_checks_read_only_files is not present. Please update/rebase the core commit so the fallback and regression test are included.