JoshuaChi · Feb 22, 2026 · Feb 21, 2026 · Feb 21, 2026 · Feb 21, 2026 · Feb 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ---
 
-## [Unreleased v0.2.3]
+## [v0.2.3] - 2026-02-21
 
 ### Added
 
@@ -19,6 +19,15 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- **⚠️ BREAKING: Protobuf Enum Value Shifts** (#279): All protobuf enums now follow buf lint standards with `UNSPECIFIED = 0`
+  - **NodeRole**: Old (Follower=0, Candidate=1, Leader=2, Learner=3) → New (UNSPECIFIED=0, Follower=1, Candidate=2, Leader=3, Learner=4)
+  - **NodeStatus**: Old (Promotable=0, ReadOnly=1, Active=2) → New (UNSPECIFIED=0, Promotable=1, ReadOnly=2, Active=3)
+  - **ErrorCode**: Old (None=0, NotLeader=1, ...) → New (UNSPECIFIED=0, NotLeader=1, ...)
+  - All enum values now have proper prefixes (`NODE_ROLE_*`, `NODE_STATUS_*`, `ERROR_CODE_*`)
+  - All fields now use snake_case naming (`leader_id`, `prev_log_index`, etc.)
+  - **⚠️ Wire protocol incompatibility**: v0.2.3 cannot communicate with v0.2.2 or earlier
+  - **Migration Required**: Update all TOML config files, upgrade all cluster nodes simultaneously (no rolling upgrade), upgrade client SDKs to v0.2.3
+
 - **Unified Client API** (#258): Merged KV and cluster operations into single `ClientApi` trait
   - **Breaking**: `KvClient` → `ClientApi`, `KvError` → `ClientApiError`
   - Simplifies developer experience (single trait for all operations)
@@ -50,6 +59,15 @@ All notable changes to this project will be documented in this file.
 
 ### Migration Notes
 
+#### Protobuf Breaking Changes
+
+- **⚠️ Wire protocol incompatible with v0.2.2**: All cluster nodes must upgrade simultaneously
+- Update configuration files: Change `role` and `status` enum values (e.g., `role = 0` → `role = 1` for Follower)
+- Upgrade all client SDKs to v0.2.3 before connecting to upgraded cluster
+- See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md#-for-v022-users-protobuf-enum-breaking-changes-in-v023) for detailed migration steps
+
+#### API Changes
+
 - Replace `KvClient` with `ClientApi` in trait bounds
 - Replace `KvError` with `ClientApiError` in error handling
 - Update imports: `use d_engine::client::ClientApi;`

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -25,7 +25,7 @@ exclude = [
 resolver = "2"
 
 [workspace.package]
-version = "0.2.2"
+version = "0.2.3"
 edition = "2024"
 authors = ["Joshua Chi <joshokn@gmail.com>"]
 homepage = "https://github.com/deventlab/d-engine"
@@ -34,10 +34,10 @@ license = "MIT OR Apache-2.0"
 rust-version = "1.88"
 
 [workspace.dependencies]
-d-engine-proto = { path = "./d-engine-proto", version = "0.2.2" }
-d-engine-core = { path = "./d-engine-core", version = "0.2.2" }
-d-engine-client = { path = "./d-engine-client", version = "0.2.2" }
-d-engine-server = { path = "./d-engine-server", version = "0.2.2" }
+d-engine-proto = { path = "./d-engine-proto", version = "0.2.3" }
+d-engine-core = { path = "./d-engine-core", version = "0.2.3" }
+d-engine-client = { path = "./d-engine-client", version = "0.2.3" }
+d-engine-server = { path = "./d-engine-server", version = "0.2.3" }
 
 tokio = { version = "1", features = [
     "macros",

diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
@@ -1,8 +1,8 @@
-# Migration Guide for d-engine v0.2.0
+# Migration Guide for d-engine
 
 ## 🎯 For New Users
 
-**Starting fresh with v0.2.0?** No migration needed - skip this guide and go to [Quick Start](./examples/quick-start/).
+**Starting fresh with the latest version?** No migration needed - skip this guide and go to [Quick Start](./examples/quick-start/).
 
 ---
 
@@ -128,12 +128,206 @@ grep "WAL" /var/log/d-engine.log
 
 ## Timeline
 
-| Version | WAL Format          | Migration Required |
-| ------- | ------------------- | ------------------ |
-| v0.1.x  | Relative TTL        | -                  |
-| v0.2.0+ | Absolute expiration | ✅ Yes (clear WAL) |
+| Version       | WAL Format          | Wire Protocol    | Migration Required                           |
+| ------------- | ------------------- | ---------------- | -------------------------------------------- |
+| v0.1.x        | Relative TTL        | Compatible       | -                                            |
+| v0.2.0–v0.2.2 | Absolute expiration | Compatible       | ✅ Yes (clear WAL from v0.1.x)               |
+| v0.2.3+       | Same as v0.2.0+     | **Incompatible** | ✅ Yes (protobuf enum changes + API changes) |
 
 ---
 
-**Version:** d-engine v0.2.0  
-**Last Updated:** December 2025
+## 🚨 For v0.2.2 Users: Protobuf Enum Breaking Changes in v0.2.3
+
+### What Changed
+
+v0.2.3 introduces **breaking wire protocol changes** due to protobuf enum value shifts to comply with buf lint standards.
+
+### ⚠️ Critical Impact
+
+**Wire Protocol Incompatibility:**
+
+- v0.2.3 nodes **CANNOT communicate** with v0.2.2 or earlier nodes
+- No rolling upgrade possible - all cluster nodes must upgrade simultaneously
+- Client SDKs must be upgraded to v0.2.3 to connect to upgraded clusters
+
+### Enum Value Changes
+
+#### NodeRole Enum
+
+| Role      | Old Value | New Value | New Constant            |
+| --------- | --------- | --------- | ----------------------- |
+| -         | -         | 0         | `NODE_ROLE_UNSPECIFIED` |
+| Follower  | 0         | 1         | `NODE_ROLE_FOLLOWER`    |
+| Candidate | 1         | 2         | `NODE_ROLE_CANDIDATE`   |
+| Leader    | 2         | 3         | `NODE_ROLE_LEADER`      |
+| Learner   | 3         | 4         | `NODE_ROLE_LEARNER`     |
+
+#### NodeStatus Enum
+
+| Status     | Old Value | New Value | New Constant              |
+| ---------- | --------- | --------- | ------------------------- |
+| -          | -         | 0         | `NODE_STATUS_UNSPECIFIED` |
+| Promotable | 0         | 1         | `NODE_STATUS_PROMOTABLE`  |
+| ReadOnly   | 1         | 2         | `NODE_STATUS_READ_ONLY`   |
+| Active     | 2         | 3         | `NODE_STATUS_ACTIVE`      |
+
+#### ErrorCode Enum
+
+| Error                  | Old Value | New Value | New Constant             |
+| ---------------------- | --------- | --------- | ------------------------ |
+| -                      | -         | 0         | `ERROR_CODE_UNSPECIFIED` |
+| NotLeader              | 1         | 1         | `ERROR_CODE_NOT_LEADER`  |
+| ... (others unchanged) |           |           |                          |
+
+### Additional Protobuf Changes
+
+- **Enum Prefixes**: All enum values now have proper prefixes (`NODE_ROLE_*`, `NODE_STATUS_*`, `ERROR_CODE_*`)
+- **Field Naming**: All fields now use snake_case naming (`leader_id`, `prev_log_index`, `last_log_index`, etc.)
+
+---
+
+## Migration Steps for v0.2.2 → v0.2.3 Protobuf Changes
+
+### Step 1: Update Configuration Files
+
+Update any TOML configuration files that reference enum values:
+
+**Old (v0.2.2):**
+
+```toml
+[cluster]
+node_id = 1
+role = 0        # Follower
+status = 0      # Promotable
+```
+
+**New (v0.2.3):**
+
+```toml
+[cluster]
+node_id = 1
+role = 1        # NODE_ROLE_FOLLOWER
+status = 1      # NODE_STATUS_PROMOTABLE
+```
+
+### Step 2: Upgrade All Cluster Nodes Simultaneously
+
+**⚠️ No Rolling Upgrade Possible**
+
+Since the wire protocol is incompatible, you must upgrade all nodes at once:
+
+1. **Schedule maintenance window** (cluster will be unavailable during upgrade)
+2. **Stop all nodes** in the cluster
+3. **Upgrade binaries** to v0.2.3 on all nodes
+4. **Update configuration files** (see Step 1)
+5. **Start all nodes** simultaneously
+6. **Verify cluster health** (check logs, run health checks)
+
+**For Production Clusters:**
+
+If you require high availability during upgrade:
+
+1. **Set up a parallel v0.2.3 cluster** (new hardware/instances)
+2. **Migrate data** to the new cluster (application-level migration)
+3. **Switch traffic** to new cluster
+4. **Decommission old cluster**
+
+### Step 3: Upgrade Client SDKs
+
+All client applications must upgrade their d-engine SDK to v0.2.3:
+
+**Cargo.toml:**
+
+```toml
+[dependencies]
+d-engine = { version = "0.2.3", features = ["client"] }
+```
+
+**Rebuild and redeploy** all client applications before connecting to upgraded cluster.
+
+### Step 4: Verification
+
+After upgrade, verify:
+
+```bash
+# Check all nodes started successfully
+journalctl -u d-engine -f
+
+# Verify cluster health
+curl http://localhost:8080/health
+
+# Test basic operations
+d-engine-cli put test-key test-value
+d-engine-cli get test-key
+```
+
+---
+
+## 🚨 For v0.2.2 Users: API Changes in v0.2.3
+
+### What Changed
+
+v0.2.3 introduces **breaking API changes** to unify client interfaces and improve developer experience.
+
+### Breaking Changes
+
+#### 1. Unified Client API Trait
+
+**Old (v0.2.2):**
+
+```rust
+use d_engine::client::KvClient;
+use d_engine::client::KvError;
+
+async fn example(client: impl KvClient) -> Result<(), KvError> {
+    // ...
+}
+```
+
+**New (v0.2.3):**
+
+```rust
+use d_engine::client::ClientApi;
+use d_engine::client::ClientApiError;
+
+async fn example(client: impl ClientApi) -> Result<(), ClientApiError> {
+    // ...
+}
+```
+
+**Migration Steps:**
+
+- Replace `KvClient` with `ClientApi` in trait bounds
+- Replace `KvError` with `ClientApiError` in error handling
+- Update imports: `use d_engine::client::{ClientApi, ClientApiError};`
+
+---
+
+#### 2. Default Persistence Strategy
+
+**Old (v0.2.2):** Default = `MemFirst` (write to memory, async flush to disk)
+
+**New (v0.2.3):** Default = `DiskFirst` (Raft protocol compliance)
+
+**Migration:**
+
+If you want to restore v0.2.2 behavior, add to config:
+
+```toml
+[raft.persistence]
+persistence_strategy = "MemFirst"
+```
+
+⚠️ **Warning:** `MemFirst` trades durability for performance. Only use in scenarios where data loss is acceptable.
+
+---
+
+### Non-Breaking Changes
+
+- **CompareAndSwap (CAS)**: New atomic operation added
+- **Drain-based batching**: Performance improvements (no API changes)
+- **Client::refresh()**: New method for leader rediscovery
+
+---
+
+**Last Updated:** February 2026
diff --git a/README.md b/README.md
@@ -24,7 +24,14 @@ and pluggable storage backends. Start with one node, scale to a cluster when nee
 
 ## Features
 
-### New in v0.2 🎉
+### New in v0.2.3 🎉
+
+- **CompareAndSwap (CAS)**: Atomic compare-and-swap for distributed locks, leader election, optimistic updates
+- **Drain-based Batching**: Linearizable read +92%, lease/eventual read +62% vs v0.2.2 (embedded mode)
+- **Client Auto-Recovery**: `Client::refresh()` rediscovers cluster after leader failover
+- **Unified Client API**: Single `ClientApi` trait for KV and cluster operations (replaces `KvClient`)
+
+### Core Features (v0.2+)
 
 - **EmbeddedEngine**: Single-node start, scale to 3-node cluster when needed
 - **EmbeddedClient**: Zero-overhead in-process access (<0.1ms latency)
@@ -87,7 +94,7 @@ d-engine = "0.2"
 **Use when**: Building Rust applications that need distributed coordination  
 **Why**: Zero-overhead (<0.1ms), single binary, zero network cost
 
-> **Performance note**: Embedded mode delivers exceptional performance - **4.6x higher write throughput** and **2x faster linearizable reads** vs etcd 3.5 (3-node cluster on M2 Mac localhost vs etcd on 3 GCE instances). Achieves 203K writes/sec and 279K linearizable reads/sec. See [benches/embedded-bench/reports/v0.2.2/](https://github.com/deventlab/d-engine/tree/main/benches/embedded-bench/reports/v0.2.2) for detailed benchmarks.
+> **Performance note**: Embedded mode on AWS EC2 3-node cluster achieves **64K writes/sec** and **181K linearizable reads/sec** under high concurrency, with sub-millisecond latency. See [benches/reports/v0.2.3/](https://github.com/deventlab/d-engine/tree/main/benches/reports/v0.2.3) for detailed benchmarks.
 
 **→ Examples:**
 
@@ -105,7 +112,7 @@ d-engine = { version = "0.2", features = ["client"], default-features = false }
 **Use when**: Application and d-engine run as separate processes  
 **Why**: Language-agnostic (Go/Python/Java/Rust), independent scaling, easier operations
 
-> **Performance note**: Standalone mode achieves 64K writes/sec and 12K linearizable reads/sec via gRPC, suitable for multi-language environments. For maximum performance, use embedded mode (3.1x faster writes, 23x faster reads). See [benches/standalone-bench/reports/v0.2.2/](https://github.com/deventlab/d-engine/tree/main/benches/standalone-bench/reports/v0.2.2) for benchmarks.
+> **Performance note**: Standalone mode achieves 36K writes/sec and 51K linearizable reads/sec via gRPC, suitable for multi-language environments. For maximum performance, use embedded mode (1.8x faster writes, 3.5x faster reads). See [benches/reports/v0.2.3/](https://github.com/deventlab/d-engine/tree/main/benches/reports/v0.2.3) for benchmarks.
 
 **Note**: Rust apps can use both modes - embedded for performance, standalone for operational flexibility
 
@@ -152,9 +159,9 @@ sequenceDiagram
 
 ---
 
-## Performance Comparison (d-engine v0.2.2 vs etcd 3.5)
+## Performance Comparison (d-engine v0.2.3 vs etcd)
 
-![d-engine vs etcd comparison](https://raw.githubusercontent.com/deventlab/d-engine/main/benches/reports/v0.2.2/dengine_comparison_v0.2.2.png)
+![d-engine vs etcd comparison](https://raw.githubusercontent.com/deventlab/d-engine/main/benches/reports/v0.2.3/d-engine_comparison_v0.2.3.png)
 
 ### View Benchmarks Detailed Reports
 

diff --git a/benches/embedded-bench/README.md b/benches/embedded-bench/README.md
@@ -24,7 +24,7 @@ make all-tests
 
 **Compare with Standalone mode:**
 
-- Standalone report: `../../benches/standalone-bench/reports/v0.2.2/report_v0.2.2.md`
+- Unified report: `../reports/v0.2.3/bench_report_v0.2.3.md`
 - Same test parameters (key-size=8, value-size=256, sequential-keys)
 - Direct performance comparison (Embedded vs Standalone)