From a462d21b258c94a266e7507c93c9579334a6a7dd Mon Sep 17 00:00:00 2001
From: dimgigov <gigov@gigov.org>
Date: Thu, 30 Jul 2026 21:07:14 +0300
Subject: [PATCH] docs: SQL writes through raft (C3b) done

Mark the C3b design done; document leader-only DML, env vars, and default-DB
apply limits in en/bg distributed docs; refresh the README raft status line.
---
 README.md                                            |  2 +-
 docs/bg/distributed.md                               | 12 +++++++++++-
 docs/en/distributed.md                               | 12 +++++++++++-
 .../specs/2026-07-30-raft-sql-writes-design.md       |  2 +-
 4 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 5d36e52..6b052a4 100644
--- a/README.md
+++ b/README.md
@@ -1559,7 +1559,7 @@ features are still being refined:
 | LSM-Tree SSTable reads | ✅ Implemented | Full disk I/O with compaction, WAL, and bloom filters. |
 | HNSW vector search | ✅ Implemented | Hierarchical graph navigation with SIMD-optimized distance metrics. |
 | TCP server execution | ✅ Implemented | Full binary wire protocol parsing and BaraQL query execution. |
-| Raft consensus | ✅ Core logic | Full Raft algorithm with log replication; network transport pluggable. |
+| Raft consensus | ✅ Core logic | Leader election + log replication over TCP; SQL DML commits through the raft log when `BARADB_RAFT_ENABLED=true` (followers reject writes). |
 | Graph / FTS / Columnar | ✅ Implemented | In-memory engines with serialization; FTS/vector/graph indexes persist across restarts. |
 | Query codegen | ✅ Implemented | IR plans compile to storage engine operations with optimization passes. |
 
diff --git a/docs/bg/distributed.md b/docs/bg/distributed.md
index b412ba7..80e6c50 100644
--- a/docs/bg/distributed.md
+++ b/docs/bg/distributed.md
@@ -7,7 +7,17 @@ BaraDB поддържа разпределено внедряване с Raft к
 
 ## Raft Консенсус
 
-Leader election и log репликация:
+Leader election и log репликация през TCP. Включване:
+
+| Env | Значение |
+|-----|----------|
+| `BARADB_RAFT_ENABLED=true` | Включва Raft |
+| `BARADB_RAFT_NODE_ID` | Id на този възел |
+| `BARADB_RAFT_PORT` | Raft TCP порт |
+| `BARADB_RAFT_PEERS` | Списък `id@host:port` (вкл. себе си) |
+| `BARADB_RAFT_WRITE_TIMEOUT_MS` | Макс. изчакване за majority commit при SQL записи (по подразбиране 5000) |
+
+Когато Raft е активен, SQL DML (`INSERT`/`UPDATE`/`DELETE`/`MERGE` и транзакционен `COMMIT`) се приема само от лидера: KV двойките се добавят в Raft лога и клиентът чака majority commit. Followers отказват записи с `not leader; leader is '…'`. Приложените записи отиват в **default** базата. DDL (напр. `CREATE TABLE`) още не се репликира — схемата трябва да се създаде на всеки възел.
 
 ```nim
 import barabadb/core/raft
diff --git a/docs/en/distributed.md b/docs/en/distributed.md
index a4767d2..167071e 100644
--- a/docs/en/distributed.md
+++ b/docs/en/distributed.md
@@ -7,7 +7,17 @@ BaraDB supports distributed deployment with Raft consensus, sharding, and replic
 
 ## Raft Consensus
 
-Leader election and log replication:
+Leader election and log replication over TCP. Enable with:
+
+| Env | Meaning |
+|-----|---------|
+| `BARADB_RAFT_ENABLED=true` | Turn on Raft |
+| `BARADB_RAFT_NODE_ID` | This node's id |
+| `BARADB_RAFT_PORT` | Raft TCP port |
+| `BARADB_RAFT_PEERS` | Comma-separated `id@host:port` (include self) |
+| `BARADB_RAFT_WRITE_TIMEOUT_MS` | Max wait for majority commit on SQL writes (default 5000) |
+
+When Raft is enabled, SQL DML (`INSERT`/`UPDATE`/`DELETE`/`MERGE` and transactional `COMMIT`) is accepted only on the leader: each write's KV pairs are appended to the Raft log and the client waits until the entry is majority-committed. Followers reject writes with `not leader; leader is '…'`. Followers apply committed entries via `applyCommand` into the **default** database. DDL (e.g. `CREATE TABLE`) is not replicated yet — apply schema on every node.
 
 ```nim
 import barabadb/core/raft
diff --git a/docs/superpowers/specs/2026-07-30-raft-sql-writes-design.md b/docs/superpowers/specs/2026-07-30-raft-sql-writes-design.md
index a357f8a..b2dedb1 100644
--- a/docs/superpowers/specs/2026-07-30-raft-sql-writes-design.md
+++ b/docs/superpowers/specs/2026-07-30-raft-sql-writes-design.md
@@ -1,7 +1,7 @@
 # SQL Writes Through Raft (C3b) — Design
 
 Date: 2026-07-30
-Status: Approved direction (user: "ок ... продължавай"); implementation follows.
+Status: Done (implemented on `feat/raft-sql-writes`).
 
 ## Problem