---

name: fdb-simulation-workloads description: Guide for writing FoundationDB simulation workloads in Rust. Use when designing chaos testing, simulation testing, deterministic testing, or workload implementations for FDB layers. Covers operation design, invariant checking, and determinism requirements. allowed-tools: Read, Grep, Edit, Write

FDB Simulation Workloads

Patterns for designing Rust workloads that find bugs through autonomous chaos testing.

Determinism Rules (Critical)

Breaking any rule destroys reproducibility. The simulator requires identical seeds to produce identical execution paths.

Operation Alphabet

Design operations across three categories:

Invariant Patterns

Verify correctness continuously during execution, not just at the end.

Three-Crate Architecture

Separate production frameworks from simulation-testable code:

Copymy-project/
├── my-fdb-service/      # Core FDB operations - NO tokio
├── my-grpc-server/      # Production layer (tokio + tonic)
└── my-fdb-workloads/    # Simulation tests

The service crate contains pure db.run() transaction logic. The server crate wraps it for production. The workloads crate tests actual service code under chaos.

Common Pitfalls

1. Initialization on all clients - Use if self.client_id == 0 to run setup once
2. Ignoring maybe_committed - Check the flag in db.run() closure for idempotency
3. Storing database references - Each phase receives fresh references; don't cache them
4. Wrapping FdbError - Keep errors unwrapped so retry mechanism detects retryable errors
5. Assuming setup is failure-free - FDB knobs randomize; always use db.run() with retry logic

Full Reference

For detailed examples, patterns, and rationale: https://pierrezemb.fr/posts/writing-rust-fdb-workloads-that-find-bugs/