API Stability

TaiDB is still pre-1.0.0, so the public API can evolve. The project keeps changes additive when possible and documents any breaking change in the changelog.

Primary API

The primary supported API is the Rust crate:

• EngineConfig for readable application setup
• TaiDbEngine for string-friendly embedded usage
• TaiDb for byte-oriented lower-level usage
• Options and OptionsBuilder for durability, mmap, compression, encryption, and size limits
• EngineConfig::read_only, TaiDb::open_read_only, and TaiDbEngine::open_read_only for explicit read-only access
• KeyCursor and KeyInfo for sorted key metadata scans
• WriteBatch and BatchReport for bulk writes

Compatibility rules before 1.0

• Storage format changes must be versioned and documented.
• Existing readable database files should keep opening unless a documented migration step is required.
• New convenience APIs should not slow existing write/read/vector hot paths.
• Breaking API changes require changelog notes and migration guidance.
• Examples should compile in CI with cargo test --all-targets.

Scan semantics

Prefix and range scans return sorted key metadata, not values. This keeps scans small and lets callers fetch only the values they need.

for info in db.scan_prefix("doc:", 100) {
    println!("{}", String::from_utf8_lossy(&info.key));
}

for info in db.scan_range(Some("doc:1000"), Some("doc:2000"), 0) {
    println!("{}", String::from_utf8_lossy(&info.key));
}

scan_range uses inclusive start and exclusive end. A limit of 0 means no limit.

Path to 1.0

The remaining API work is to review exported types, stabilize error guidance, and document recovery recommendations for application authors.