# Implementation Plan: Raft Core Replication

**Branch**: `002-raft-features` | **Date**: 2025-12-01 | **Spec**: [specs/002-raft-features/spec.md](specs/002-raft-features/spec.md)  
**Input**: Feature specification from `/specs/002-raft-features/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

## Summary

Implement Raft core replication for FlareDB: single-node bootstrap with durable log/hard/conf state, majority replication across a fixed 3-node cluster, and follower recovery/catch-up. Build on the existing Rust workspace (raft-rs, RocksDB) with tonic-based transport already present in the repo.

## Technical Context

**Language/Version**: Rust (stable, via Nix flake)  
**Primary Dependencies**: `raft` (tikv/raft-rs 0.7, prost codec), `tokio`, `tonic`/`prost`, `rocksdb`, `slog`  
**Storage**: RocksDB column families (`raft_log`, `raft_state`) for log, hard state, and conf state  
**Testing**: `cargo test` (unit/integration), scripted multi-node harness to be added for replication scenarios  
**Target Platform**: Linux (x86_64), Nix dev shell  
**Project Type**: Rust workspace (multi-crate: rdb-proto, rdb-storage, rdb-server, rdb-pd, rdb-client, rdb-cli)  
**Performance Goals**: From spec SCs — single-node commit ≤2s; 3-node majority commit ≤3s; follower catch-up ≤5s after rejoin  
**Constraints**: Fixed 3-node membership for this phase; no dynamic add/remove; minority must not commit  
**Scale/Scope**: Cluster size 3; log volume moderate (dev/test scale) sufficient to validate recovery and catch-up

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Test-First: Plan includes unit/integration tests for Raft storage, proposal/commit, and recovery paths.  
- Reliability & Coverage: CI to run `cargo test`; integration harness to cover cross-node replication.  
- Simplicity & Readability: Use existing crates (raft-rs, rocksdb); avoid bespoke protocols.  
- Observability: Ensure structured logs on Raft events/errors; failures must be actionable.  
- Versioning & Compatibility: Proto changes, if any, must be called out; fixed membership avoids dynamic reconfig in this phase.  
No constitution violations identified; gate PASS.

## Project Structure

### Documentation (this feature)

```text
specs/002-raft-features/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
└── tasks.md             # Phase 2 output (via /speckit.tasks)
```

### Source Code (repository root)

```text
Cargo.toml              # workspace
rdb-proto/              # proto definitions
rdb-storage/            # RocksDB storage + Raft CFs
rdb-server/             # Raft peer, gRPC services
rdb-pd/                 # placement driver (not primary in this feature)
rdb-client/             # client SDK/CLI (control hooks if needed)
rdb-cli/                # auxiliary CLI
scripts/                # verification scripts
tests/                  # integration harness (to be added under rdb-server or workspace)
```

**Structure Decision**: Use existing Rust workspace layout; place Raft-focused tests/harness under `rdb-server/tests` or workspace `tests/` as appropriate; contracts under `specs/002-raft-features/contracts/`.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| N/A | | |