Baradb/PLAN_old_1.md

План за подобряване на BaraDB

Цел

Превърне BaraDB от добър proof-of-concept в солиден, изпълним проект с реална дълбочина на критичните компоненти.

---

Фаза 1: Честност и стабилна основа (1–2 седмици) ✅ ЗАВЪРШЕНА

1.1 Поправи README.md да отразява реалното състояние

• ✅ Добавена секция "Current Status / Limitations" с конкретни бележки:
  • LSM-Tree SSTable четене е placeholder
  • HNSW search е линейно сканиране (O(N))
  • TCP сървърът връща само "OK", без execution
  • Raft няма мрежов транспорт
  • Graph/FTS/Columnar са in-memory само
• ✅ Променена сравнителната таблица с EdgeDB — маркиран като "в разработка / експериментален"

1.2 Поправи компилацията на benchmark-ите

• ✅ В benchmarks/bench_all.nim: заменено (getMonoTime() - start).ticks с (getMonoTime() - start).inNanoseconds
• ✅ Добавен import std/times
• ✅ Benchmark-ът се компилира и изпълнява успешно

1.3 Имплементирай реално SSTable четене в storage/lsm.nim

Беше: db.get() намираше ключа в sst.index, но връщаше (true, @[]) — празен масив.

Сега:

• ✅ Дефиниран бинарен SSTable формат (Header → Data Block → Index Block → Bloom Filter Block)
• ✅ Имплементиран writeSSTable() — сериализира MemTable към .sst файл
• ✅ Имплементиран loadSSTable() — зарежда съществуващ .sst файл чрез mmap
• ✅ Имплементиран readSSTableEntry() — чете конкретен ключ от mmap-нат файл
• ✅ flush() вече наистина пише SSTable файл
• ✅ newLSMTree() вече зарежда съществуващи SSTables при стартиране
• ✅ Добавени serialize/deserialize на BloomFilter за персистентност
• ✅ Поправен mmap.nim да използва posix.open вместо грешния system.open
• ✅ Всички 214 теста минават
• ✅ Persistence тест: write → flush → close → reopen → read работи коректно

---

Фаза 2: Дълбочина на core engine-ите (2–4 седмици)

2.1 Реализирай истински HNSW search в vector/engine.nim ✅ ЗАВЪРШЕНА

Беше: search() правеше линейно сканиране на всички нодове.

Резултат:

• ✅ Имплементиран randomLevel() с геометрично разпределение
• ✅ Имплементиран searchLayer() — жадно разширяване на кандидати с ef лъч
• ✅ Имплементиран selectNeighbors() + addBidirectionalLink() с degree pruning
• ✅ insert() изгражда йерархичен граф ниво по ниво
• ✅ search() слиза от maxLevel до 0, рефинирайки entry point
• ✅ searchWithFilter() с пост-филтриране на метаданни
• ✅ Тестовете за HNSW (insert/search/filter) минават; benchmark-ът с 10K вектора работи

2.2 Интегрирай wire protocol в TCP сървъра ✅ ЗАВЪРШЕНА

Беше: core/server.nim връщаше "OK\n" за всяка заявка.

Резултат:

• ✅ Сървърът чете 12-byte бинарен header (kind, length, requestId) и payload
• ✅ Имплементиран recvExact за надеждно message framing
• ✅ SELECT: point read (WHERE key = '...') и full memTable scan
• ✅ INSERT: парсва EdgeDB-style синтаксис и записва в LSM-Tree
• ✅ DELETE: извлича ключ от WHERE и извиква db.delete()
• ✅ Отговори чрез mkData, mkComplete, mkError, mkPong
• ✅ Добавен scanMemTable() в LSM-Tree за пълни сканирания
• ✅ Всички тестове минават (214+)

2.3 Добави персистентност на поне един от Graph/FTS/Columnar ✅ ЗАВЪРШЕНА

Изпълнено за Graph engine.

Резултат:

• ✅ Дефиниран бинарен формат с magic bytes (BGRF) и version
• ✅ saveToFile(path) сериализира nodes, edges, properties, weights, next IDs
• ✅ loadFromFile(path) реконструира графа и adjacency lists от edges
• ✅ Тест "Save and load graph": 3 nodes, 2 edges, properties, shortest path — round-trip успешен
• ✅ Всички тестове минават (215+)

---

Фаза 3: Production hardening (2–3 седмици)

3.1 Thread-safety и concurrency ✅ ЗАВЪРШЕНА

• ✅ LSM-Tree: конвертиран от object на ref object, добавен std/locks.Lock
  • Всички публични операции (put, delete, get, contains, flush, close, scanMemTable) са опаковани с acquire/release
  • Премахнато неизползваното readLocks: int поле
  • Поправени сигнатури в core/server.nim от var LSMTree на LSMTree
• ✅ Graph: добавен std/locks.Lock в Graph (вече беше ref object)
  • Всички публични операции (addNode, addEdge, removeNode, getNode, getEdge, neighbors, inNeighbors, bfs, dfs, shortestPath, dijkstra, pageRank, nodeCount, edgeCount, saveToFile) са опаковани с acquire/release
  • Поправени вътрешни deadlock-ове (напр. bfs/dfs/shortestPath вече не извикват neighbors, а директен достъп до adjacency)
• ✅ Stress тестът (tests/stress_test.nim) вече използва std/threadpool с spawn за паралелни worker-и
  • 10 worker-а × 1000 ops, 0 грешки, ~833K ops/sec

3.2 Raft мрежов транспорт ✅ ЗАВЪРШЕНА

• ✅ Добавен RaftNetwork тип в core/raft.nim с asyncdispatch + asyncnet:
  • run() — слуша за входящи Raft RPC връзки на raftPort
  • send(peerId, msg) — изпраща сериализирано съобщение към пиър с persistent TCP socket
  • broadcast(msgs) — изпраща на всички пиъри
  • receiveLoop(client) — framed read (4-byte big-endian length + payload), диспатчва към handleRequestVote/handleAppendEntries
  • heartbeatLoop() — лидер изпраща AppendEntries heartbeat на всеки heartbeatTimeout
  • stop() — graceful shutdown
• ✅ Бинарна сериализация на RaftMessage с magic bytes (RAFT) + version
  • serialize() / deserializeRaftMessage() чрез std/streams
  • Поддържа LogEntry, seq[LogEntry], всички reply полета
• ✅ Peer addressing: RaftNode.peerAddrs: Table[string, (host, port)] + raftPort
• ✅ Интеграция с ElectionTimer:
  • tick(timer, net) приема optional RaftNetwork
  • При follower/candidate timeout се изпращат реални RequestVote съобщения по TCP
• ✅ Тест "3-node election over TCP" — 3 нода на портове 19001/19002/19003, проверява че точно 1 става лидер

3.3 CI/CD и качество ✅ ЗАВЪРШЕНА

• ✅ Създаден .github/workflows/ci.yml:
  • Пуска nim c --path:src -r tests/test_all.nim на всеки push/PR
  • Компилира benchmarks/bench_all.nim в release режим
  • Компилира и пуска tests/stress_test.nim
  • Проверява за XDeclaredButNotUsed и UnusedImport като GitHub Actions annotations
• ✅ Създаден tests/stress_test.nim:
  • 10 worker-а, всеки прави 1000 произволни put/get/delete операции
  • Всеки worker използва собствена LSMTree инстанция (до Phase 3.1 за thread-safety)
  • Проверка за data corruption — 0 грешки при 10 000 ops (~143K ops/sec)

3.4 Изчисти проекта ✅ ЗАВЪРШЕНА

• ✅ Изтрити broken/unused файлове:
  • src/barabadb/protocol/http.nim (unused, 5 compile errors)
  • src/barabadb/protocol/tls.nim (unused, 25 errors, overlaps with ssl.nim)
  • src/barabadb/protocol/websocket.nim (unused, 14 errors)
  • src/barabadb.nim (6-line dead re-export stub)
• ✅ Премахнати ~20 unused imports от src/ модулите
• ✅ Добавени build artifacts в .gitignore (*.out, тест/бенчмарк бинарни файлове)

---

Приоритетна матрица

Задача	Влияние	Трудност	Приоритет
SSTable реално четене	Критично	Средна	P0 ✅
README честност	Високо	Ниска	P0 ✅
HNSW истински search	Високо	Висока	P1 ✅
Wire protocol в сървъра	Високо	Средна	P1 ✅
Benchmark fix	Ниско	Ниска	P2 ✅
Graph персистентност	Средно	Ниска	P2 ✅
Raft мрежа	Средно	Висока	P2 ✅
Thread-safety	Средно	Средна	P2 ✅
CI/CD	Средно	Ниска	P3 ✅
Изчистване на проекта	Ниско	Ниска	P3 ✅

---

Очакван резултат след изпълнение

• Фаза 1: Проектът е честен, стабилен и benchmark-ите работят. LSM-Tree е валиден key-value store. ✅
• Фаза 2: HNSW работи с реален approximate search. Сървърът изпълнява заявки. Има персистентност. ✅
• Фаза 3: Многонишкова безопасност, CI, по-чист код. ✅

Крайна оценка след плана: от 6.5/10 към 8.5/10.