Baradb/PLAN.md

# BaraDB — AI-Native Data Platform Roadmap

> **Визия**: BaraDB не е "релационна база + векторна добавка", а единна AI-native база данни, където релационни, векторни, граф и текстови данни живеят в един engine. Както MariaDB интегрира vectors в ядрото, така и BaraDB прави vector/graph/fts първокласни граждани в SQL execution layer-а.
>
> **Принцип**: Универсалност + Multi-Tenancy. Всяка AI функция работи с Row-Level Security (RLS) и session variables (`app.tenant_id`). Няма отделни "AI таблици" — всичко е SQL.

---

## Текущо състояние (май 2026)

| Компонент | Статус |
|-----------|--------|
| SQL:2023 Engine | ✅ Window, MERGE, LATERAL, GROUPING SETS, PIVOT, SQL/PGQ |
| Vector Engine | ✅ HNSW + IVF-PQ + SIMD (ядро) |
| Vector SQL | ✅ `VECTOR(n)` тип, `CREATE VECTOR INDEX`, distance функции, `<->` оператор |
| Graph Engine | ✅ BFS/DFS/PageRank/Dijkstra + SQL/PGQ `GRAPH_TABLE` |
| Full-Text Search | ✅ Inverted Index + BM25 + Hybrid Search |
| JSON/JSONB | ✅ Колони, оператори, функции |
| Multi-Tenant | ✅ Session vars, `current_setting()`, `current_user`, RLS Policies |
| Foreign Keys | ✅ CASCADE/SET NULL/RESTRICT за ON DELETE и ON UPDATE |
| Formal Verification | ✅ 10 TLA+ спецификации |
| MCP Server | ✅ STDIO JSON-RPC, 3 tools (query, vector_search, schema_inspect), multi-tenant |
| AI Pipeline | ✅ chunk(), embed_text(), auto-embed on INSERT, configurable embedder |
| RAG Pipeline | ✅ ChatMessageHistory, end-to-end Python RAG example |
| AI Agents & NL→SQL | ✅ nl_to_sql(), schema_prompt(), query validation, self-correction loop, multi-tenant |
| Graph Similarity & Embeddings | ✅ similarity_nodes(), node2vec_embed() |
| Cypher Layer | ✅ cypher() — MATCH (a)-[r]->(b) RETURN ... → GRAPH_TABLE |

---

## Сесия 10: Vector AI Native Integration

> **Цел**: Да превърнем vector search от "engine feature" в "AI-native SQL experience" — RAG-ready, LangChain-compatible, MCP-enabled.

### Фаза 10.1: Hybrid RAG Search

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 10.1.1 | `hybrid_search()` SQL функция | Комбинира vector similarity + BM25 FTS + релационни филтри в една заявка. Reranking с RRF. | 6-8ч | ✅ |
| 10.1.2 | `rerank()` SQL функция | Cross-encoder reranking — приема query text + резултати, връща преподредени по relevance. | 4ч | ✅ |
| 10.1.3 | Metadata filtering в vector search | `WHERE` клауза върху JSONB/релационни колони ДО vector index scan-а (pre-filtering). | 6ч | ✅ |
| 10.1.4 | Chunking + embedding pipeline | `INSERT INTO docs (text)` → автоматично chunk-ване + embedding generation чрез външен embedder. | 8ч | ✅ |

**Метрика**: `SELECT hybrid_search('AI query', embedding, content, k => 10)` връща релевантни резултати за under 50ms с 1M vectors.

### Фаза 10.2: LangChain Vector Store Interface

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 10.2.1 | `BaraDBStore` за Python LangChain | Имплементира `VectorStore` интерфейса — `add_texts()`, `similarity_search()`, `max_marginal_relevance_search()`. | 4ч | ✅ |
| 10.2.2 | `BaraDBStore` за JS LangChain | Същото за LangChain.js. | 4ч | ✅ |
| 10.2.3 | Conversation buffer в BaraDB | `ChatMessageHistory` имплементация — съхранява message threads в релационна таблица с RLS. | 3ч | ✅ |
| 10.2.4 | RAG pipeline example | End-to-end пример: ingest PDF → chunks → embeddings → hybrid search → LLM context. | 3ч | ✅ |

**Метрика**: LangChain RAG tutorial работи с BaraDB без промяна на кода (swap-in replacement за PostgreSQL/pgvector).

### Фаза 10.3: MCP Server (Model Context Protocol) ✅

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 10.3.1 | MCP Server scaffolding | STDIO/SSE transport, tool definitions, capability negotiation. | 4ч | ✅ |
| 10.3.2 | `query` tool — SQL execution | AI агент изпраща SQL, получава резултати. Parameterized queries за сигурност. | 3ч | ✅ |
| 10.3.3 | `vector_search` tool | Semantic search tool с tenant isolation чрез `app.tenant_id` session var. | 3ч | ✅ |
| 10.3.4 | `schema_inspect` tool | AI агент разглежда таблици, колони, индекси, RLS policies. | 2ч | ✅ |
| 10.3.5 | Multi-tenant MCP | Всяка MCP сесия носи `tenant_id` + `user_id` — RLS филтрира автоматично. | 2ч | ✅ |

**Метрика**: Claude/Cursor can connect to BaraDB via MCP и изпълнява `SELECT hybrid_search(...) WHERE tenant_id = current_setting('app.tenant_id')`.
✅ Проверено: `baramcp --data-dir ./data` стартира STDIO MCP сървър с 3 tools-a. Тествани с JSON-RPC 2.0 клиент: query, vector_search, schema_inspect — всички работят.

---

## Сесия 11: Graph Engine Deep Integration

> **Цел**: SQL/PGQ парсерът е готов, но execution-ът е table-based. Да го направим първокласен citizen с native graph storage и Cypher compatibility.

### Фаза 11.1: Native Graph Storage

| # | Задача | Описание | Оценка |
|---|--------|----------|--------|
| 11.1.1 | Property Graph DDL | `CREATE GRAPH g`, `CREATE NODE TABLE`, `CREATE EDGE TABLE` — native graph schema. | 4ч |
| 11.1.2 | Adjacency list storage | Ребрата се пазят като adjacency lists (не като отделни LSM редове) за O(1) neighbors access. | 6ч |
| 11.1.3 | Graph indexes | Index на `source→targets` и `target→sources` за bidirectional traversal. | 4ч |
| 11.1.4 | Graph + RLS integration | `CREATE POLICY` върху graph nodes/edges — tenant isolation за граф данни. | 3ч |

### Фаза 11.2: Advanced Graph Algorithms

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 11.2.1 | `shortest_path()` SQL функция | Dijkstra/A* между два node-а, връща path като JSON array. | 3ч | ✅ |
| 11.2.2 | `community_detection()` SQL функция | Louvain algorithm, връща community ID за всеки node. | 6ч | ✅ |
| 11.2.3 | `similarity_nodes()` SQL функция | Jaccard/Adamic-Adar similarity между neighbors. | 3ч | ✅ |
| 11.2.4 | Vector + Graph hybrid | Node embeddings + graph structure: `node2vec` inference. | 8ч | ✅ |

### Фаза 11.3: Cypher Compatibility Layer

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 11.3.1 | Cypher parser (subset) | `MATCH (a)-[r]->(b) WHERE a.name = 'X' RETURN b` → BaraQL AST. | 6ч | ✅ |
| 11.3.2 | Cypher → SQL/PGQ translation | `MATCH` → `GRAPH_TABLE(... MATCH ...)` за съвместимост със съществуващ executor. | 4ч | ✅ |
| 11.3.3 | APOC-style functions | `apoc.path.expand()`, `apoc.coll.*` — полезни utility функции. | 4ч | ✅ |

**Метрика**: Neo4j `movies` example работи с BaraDB Cypher layer без промяна.

---

## Сесия 12: AI Agents & Natural Language → SQL

> **Цел**: No-code / low-code AI агенти, които работят директно с BaraDB.

### Фаза 12.1: NL → SQL Agent

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 12.1.1 | Schema-aware prompt template | Prompt който вкарва `CREATE TABLE` дефиниции + sample data + RLS policies. | 2ч | ✅ |
| 12.1.2 | `nl_to_sql()` SQL функция | `SELECT nl_to_sql('Show me top 5 customers by revenue')` → generated SQL string. | 4ч | ✅ |
| 12.1.3 | Query validation layer | Генерираният SQL минава през sandbox execution с `LIMIT 1` + explain plan. | 3ч | ✅ |
| 12.1.4 | Self-correction loop | Ако SQL-ът фейлва, агентът получава error message и генерира fix. | 3ч | ✅ |

### Фаза 12.2: Multi-Tenant AI Agent ✅

| # | Задача | Описание | Оценка | Статус |
|---|--------|----------|--------|--------|
| 12.2.1 | Per-tenant schema views | AI агентът вижда само таблици/колони, достъпни за текущия tenant. | 2ч | ✅ |
| 12.2.2 | Tenant-aware NL → SQL | `app.tenant_id` се инжектира автоматично в генерирания SQL. | 2ч | ✅ |
| 12.2.3 | Agent memory per tenant | Conversation history се изолира по tenant_id + user_id. | 2ч | ✅ |

---

## Приоритети и зависимости

```
Сесия 10 (Vector AI) ──→ Сесия 12 (AI Agents)
       │                      │
       ↓                      ↓
Сесия 11 (Graph) ──────→ Hybrid Vector+Graph
```

**Препоръчителен ред:**
1. **Сесия 10.1** — Hybrid RAG Search (най-висок business value)
2. **Сесия 10.2** — LangChain интеграция (екосистемна съвместимост)
3. **Сесия 10.3** — MCP Server (AI агенти могат да работят веднага)
4. **Сесия 11.1** — Native Graph Storage (performance foundation)
5. **Сесия 11.2** — Advanced Graph Algorithms (feature completeness)
6. **Сесия 12** — NL → SQL (user-facing wow factor)

---

## Сесия 13: Stabilization & Deep Audit (август 2026)

> **Цел**: Подобряване на надеждността и коректността върху вече завършеното ядро — целеви поправки + системен паралелен одит по слоеве (Storage / Query / Core / Protocol).

### Целеви поправки (завършени)

| # | Поправка | Файлове | Статус |
|---|----------|---------|--------|
| 1 | **REP delete-from-empty** — legacy REP payload носи явен put/delete таг (`encodeRepPayload`/`decodeRepPayload`); PK-only редове вече не изчезват при репликация | `core/replication.nim`, `core/server.nim` | ✅ + тестове |
| 2 | **Snapshot stall (частична mitigation)** — gzip при leader snapshot send се изнася извън event loop-а през worker thread (`gzipFileAsync`); heartbeats текат по време на компресия | `core/backup.nim`, `core/raft.nim`, `baradadb.nim` | ✅ + e2e |
| 3 | **REP receiver индекси** — receiver-ът минава през `applyReplicatedPut/Delete` под storage gate; вторичните индекси (B-tree/FTS/HNSW/graph) се поддържат на репликата | `core/server.nim` | ✅ + тест |

### Deep Audit (2026-08)

4 паралелни одит-агента по слоеве; ~28 нови находки (без дублиране на 80-те вече оправени в `BUGS.md`/`BUG_AUDIT.md`). Пълен отчет: [`BUG_AUDIT_2026-08.md`](BUG_AUDIT_2026-08.md).

**Батч 1 — поправени (5):** MIGRATE auth bypass (CRITICAL), raft commit strict-majority за even-N (CRITICAL), pre-auth wire-length DoS (HIGH), `**`/`++` lowering към equality (HIGH), `!=` не е отрицание на `=` (HIGH).

**Батч 2 — поправени (12):** semi-sync partial-ack (H3), COUNT/SUM/AVG(DISTINCT) (H6), UNION/INTERSECT/EXCEPT (H7), MERGE THEN DELETE (H8), WAL torn-record recovery (H9), MVCC write iteration (M1), checkpoint lock leak (M3), flushUnsafe order (M4), compaction empty-key (M5), rewriteLive atomic replace (M6), mmap overflow (L3), stray `protocol/scram` ELF.

**Остават (~12):** вж. `BUG_AUDIT_2026-08.md` — TLS peer verify (H2), B-tree separator (H10, needs careful repro), disttxn SO_ERROR (M2), compaction catalog order (M7), OFFSET-без-LIMIT (M8), window агрегати (M9), WebSocket (M10–M12), SCRAM (L1–L2), NULL equality (L4).

---

## Какво остава от старите планове

| Стар план | Статус |
|-----------|--------|
| `PLAN_old_1.md` — Base SQL + MVCC + Raft | ✅ Завършен |
| `PLAN_old_2.md` — Production Roadmap | ✅ Завършен |
| `PLAN_old_3.md` — Stabilization Sprint (сесия 9) | ✅ Завършен |
| `PLAN_SQL_ADVANCED.md` — Window Functions, MERGE, etc. | ✅ Завършен |
| `PLAN_ID_GENERATORS.md` — AUTO_INCREMENT, Sequences, FK | ✅ Завършен |
| **Този план** — Сесии 10, 11, 12 | ✅ Завършен |
| Raft C3a/C3b + DDL/forward/compact/metrics (2026-07-30) | ✅ Завършен на `main` — `docs/superpowers/specs/2026-07-30-raft-cluster-status.md` |
| **Production GA v1.2.0** (single-node) | ✅ `docs/superpowers/plans/2026-07-30-production-ga.md` |
| **Сесия 13** — Stabilization & Deep Audit (2026-08) | 🔄 В процес — батч 1+2 (17 поправки); остават ~12; `BUG_AUDIT_2026-08.md` |

---

## Философия

> BaraDB не добавя "AI модули" — BaraDB става AI-native като вгради embeddings, similarity search, graph traversal и natural language интерфейси в съществуващия SQL engine. Всяка нова функция работи с:
> - **MVCC транзакции**
> - **RLS + Multi-tenancy**
> - **WAL + Replication**
> - **Nim performance**

---

*План версия: 2026-08-02*