[jaykv]

Stacked on #7. Adds the evidence track from the plan (§6), a production-shaped reference application with end-to-end tests, the documentation, and the core changes that the measurements and the end-to-end tests led to.

What it adds

• bench/ (unpublished): workloads B1–B6 and B8, an HTTP load test (LOAD), stress scenarios X1–X7, a Mongoose comparator, and a Sentry SDK → rustrak tracing check. All against real MongoDB.
• Storefront reference app: auth, admin guards, row scope, an order transaction that cannot oversell, soft-deleted revisioned products, reviews as a reverse relation, an exactly-once resumable change-stream projector, health check, graceful shutdown. Runs on every plug and model backend.
• End-to-end tests that boot it under uvicorn and drive it over HTTP: customer journey on all five plugs, 40 concurrent buyers for 10 units, all-or-nothing multi-item orders, projector resume across restarts, in-flight requests on shutdown, consistency across a primary step-down.
• Docs: guide pages whose examples are executed by the test suite, migration guide, Mongoose parity page, benchmarks page, API reference. mkdocs build --strict runs in CI.

What the measurements changed

• Tracked reads: 428 ms → 150 ms for 10,000 nested documents (4.3× → 1.6× the driver). A tracked document now keeps the raw BSON it was read from and builds the snapshot only when saved.
• Cursor reads are fetched in batches instead of one await per document.
• Removed the trusted read option: its pydantic fast path measured slower than validating.
• Web responses use each backend's native JSON serialiser; list and get requests read untracked documents.

What the end-to-end tests found

• Aggregation paths (aggregate, union, graph, backref counts) failed whenever a default time limit was configured.
• Ids given as strings to reference fields were stored as strings on msgspec and attrs.
• Unexpected server errors were not logged anywhere.
• Upserted documents lacked the model's defaults, so they differed in shape from inserted ones.

Headline results

Full detail and caveats are in docs/benchmarks.md.

Question	Result
Server CPU per request vs hand-written pymongo + Starlette	0.76 ms vs 0.63 ms (1.21×); 0.83× throughput at saturation
Change tracking vs lean reads	0–15% slower, about 1.2 KB per document
Tracked documents vs driver, mongospecs / Mongoose	1.6× (msgspec), 2.7× (pydantic) / 3.8×
$lookup vs batched include()	batched is the default; $lookup never clearly won and was 5–9× slower through mongos at small fan-outs
Cursor vs offset pagination at the last of 2,499 pages	0.67 ms vs 12.6 ms
Stress scenarios X1–X7	all pass

Decisions for you

• Rust: not warranted for 0.2. The one candidate is a BSON-to-model decoder for bulk reads, where decoding BSON to dicts is essentially all of the driver's time. For request-sized reads it would gain an estimated 10–20%. Worth doing only if bulk reads matter to you.
• include() default: batched queries, as measured. Say if you would rather $lookup be the default on unsharded deployments despite the shared-target case.

Things to know when reviewing

• Run-to-run variation on this setup is around ±30%; the write-up only draws conclusions from larger, repeated effects. Two replica-set runs of the $lookup comparison disagree at fan-out 100 and both are shown.
• The first load benchmark used httpx and reported both servers at about 330 requests/s. That was the client's ceiling. It was replaced with a minimal keep-alive client and server CPU per request is now the primary metric.
• Everything ran on one machine with MongoDB in Docker; the free-threaded build was not benchmarked.
• The end-to-end suite includes a test that steps the replica-set primary down. It is marked chaos and runs in CI with the rest.
• rustrak is GPL-3.0. It is only pulled as a Docker image for the tracing check; nothing links against it.

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @jaykv, your pull request is larger than the review limit of 150,000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: f82b59b3-e650-4e13-b108-b8faf0c222c3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}