feat(xmtp_db): disk-latency benchmark for fresh-DB creation

[mkysel]

What

Adds an on-demand benchmark that measures libxmtp's fresh-DB creation (the ~63 Diesel migrations run by EncryptedMessageStore::new → init()) as a function of injected per-op disk / fsync latency, to model network-attached storage (e.g. AWS EFS) and quantify how per-account client init scales with it.

Two pieces:

• crates/xmtp_db/src/latency_vfs.rs — a WAL-compatible SQLite VFS shim (in the style of SQLite's vfstrace.c). It wraps the platform default VFS, delegates every VFS/file method to it, and only adds a configurable thread::sleep on xSync/xWrite/xRead, plus per-op counters. Scoped by filename so only the target DB (and its -wal/-shm/-journal siblings) is slowed. Because SQLCipher is a codec layered above the pager, real I/O still flows through this VFS, so the numbers are representative of the encrypted store. Gated behind a new bench feature, native-only.
• crates/xmtp_db/benches/db_init_latency.rs — a Criterion bench sweeping injected latency {0,1,5,10} ms/op over a fresh persistent encrypted store, in two scenarios (fsync_latency = xSync only; write_sync_latency = xWrite+xSync).

Run

cargo bench -p xmtp_db --features bench --bench db_init_latency

Result / motivation

A fresh store does ~768 writes but only ~6 fsyncs, so write-op round-trips — not fsync — dominate on high-latency storage:

per-op delay	fsync_latency	write_sync_latency
0 ms	25 ms	26 ms
1 ms	37 ms	1.36 s
5 ms	77 ms	5.58 s
10 ms	141 ms	10.56 s

At ~5 ms/op this reproduces the ~4 s Fargate/EFS agent-init cost tracked in Linear CON-245. Takeaway for that work: the lever is getting the 768 migration writes off the per-account hot path (pre-migrated template DB), not reducing fsyncs.

Scope / notes

• No production code changed — the VFS is compiled and registered only under the bench feature.
• A full-client (Client::create) variant was intentionally left out: it needs a live local backend, and its DB portion is exactly what this DB-layer bench already isolates.
• Draft: adds criterion as an xmtp_db dev-dep, so cargo hakari generate / a full just lint pass may be needed before marking ready.

Note

Add disk-latency benchmark for EncryptedMessageStore initialization in xmtp_db

• Adds a Criterion benchmark target db_init_latency (gated by a new bench feature) that measures EncryptedMessageStore creation time across configurable per-op I/O delays (0, 1, 5, 10ms).
• Implements a custom SQLite VFS wrapper in latency_vfs.rs that intercepts xRead, xWrite, and xSync, injects nanosecond-level delays, counts ops, and scopes injection to files matching a configurable token.
• The benchmark runs two sweep scenarios (fsync-only and write+sync) and prints one-time I/O op counts as a diagnostic before timed measurements.
• Risk: calling register() replaces the process-wide default SQLite VFS; this is only reachable under the bench feature on native targets.

Changes since #3824 opened

• Instrumented latency_vfs module with per-operation timing tracking across all SQLite VFS operations [f4f7096]
• Added environment variable configuration for benchmark database file base directory [f4f7096]

^{Macroscope summarized bc55db9.}

[claude]

Claude encountered an error —— View job

---

PR Review in Progress

Review Date: 2026-07-07 18:00 UTC

Tasks

• Read and analyze new benchmark code
• Read and analyze VFS implementation
• Review for code quality and potential issues
• Post final review feedback

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.72%. Comparing base (b86545d) to head (170bc2c).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3824      +/-   ##
==========================================
+ Coverage   84.70%   84.72%   +0.01%     
==========================================
  Files         409      409              
  Lines       60901    60901              
==========================================
+ Hits        51588    51597       +9     
+ Misses       9313     9304       -9     

☔ 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]

Approvability

Verdict: Approved

This PR adds benchmark infrastructure behind a feature flag (bench) that is not compiled in production builds. The new latency_vfs module and benchmark are explicitly for testing purposes only, with no impact on runtime behavior.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate f4f7096