test(join): add test for duplicate columns in SELECT *

Verify that JOIN with overlapping column names preserves both left (bare) and right (qualified) values.
fix(query): preserve both sides of duplicate column names in JOIN
2026-05-21 09:44:32 +03:00 · 2026-05-21 09:44:31 +03:00 · 2026-05-21 09:44:28 +03:00 · 2026-05-21 09:44:25 +03:00 · 2026-05-21 09:44:17 +03:00
207 changed files with 215 additions and 20696 deletions
@@ -5,12 +5,12 @@
 **A multimodal database engine written in Nim — 100% native, zero dependencies.**
 [![Version](https://img.shields.io/badge/version-1.1.6-blue.svg)](baradadb.nimble)
-[![Documentation](https://img.shields.io/badge/docs-7_languages-blue.svg)](docs/index.md)
+[![Documentation](https://img.shields.io/badge/docs-2_languages-blue.svg)](docs/index.md)
 [![Stars](https://img.shields.io/github/stars/katehonz/barabaDB?style=social)](https://github.com/katehonz/barabaDB)
 ## Documentation
-📖 **[Read the documentation in your language](docs/index.md)** — English, Български, Русский, فارسی, 中文, Türkçe, العربية
+📖 **[Read the documentation in your language](docs/index.md)** — English, Български
 BaraDB combines document, graph, vector, columnar, and full-text search storage
 in a single engine with a unified query language (BaraQL). It compiles to a
@@ -112,7 +112,7 @@ nimble bench
 ## BaraQL — Query Language
-BaraQL is SQL-compatible with extensions for graph, vector, and document queries.
+BaraQL implements partial SQL:2023 coverage with extensions for graph, vector, and document queries.
 ### Basic Queries
@@ -1,62 +0,0 @@
 # API البروتوكول الثنائي
 بروتوكول سلكي منخفض المستوى لاتصالات العميل عالية الأداء.
 ## تنسيق الرسالة
 جميع الرسائل تستخدم ترتيب big-endian:
 ```
 ┌────────┬────────┬────────┬────────┬─────────────┐
 │ Length │  Type  │  Seq   │ Status │   Payload   │
 │ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │  N bytes    │
 └────────┴────────┴────────┴────────┴─────────────┘
 ```
 ## أنواع الرسائل
 ### Query (0x01)
 ```nim
 let msg = makeQueryMessage(seq, "SELECT * FROM users")
 ```
 ### Insert (0x02)
 ```nim
 let msg = makeInsertMessage(seq, "users", data)
 ```
 ### Update (0x03)
 ```nim
 let msg = makeUpdateMessage(seq, "users", updates, where)
 ```
 ### Delete (0x04)
 ```nim
 let msg = makeDeleteMessage(seq, "users", where)
 ```
 ### Ready (0x05)
 ```nim
 let msg = makeReadyMessage(seq)
 ```
 ### Error (0x06)
 ```nim
 let msg = makeErrorMessage(seq, code, message)
 ```
 ## رموز الاستجابة
 | الرمز | الاسم | الوصف |
 |-------|-------|-------|
 | 0x00 | OK | نجاح |
 | 0x01 | ERROR | خطأ عام |
 | 0x02 | AUTH_REQUIRED | مطلوب مصادقة |
 | 0x03 | INVALID_QUERY | خطأ في بناء الجملة |
 | 0x04 | NOT_FOUND | المورد غير موجود |
@@ -1,62 +0,0 @@
 # API HTTP/REST
 API REST مبني على JSON لتطبيقات الويب.
 ## Base URL
 ```
 http://localhost:9470/api
 ```
 ## نقاط النهاية
 ### GET /api/users
 قائمة جميع المستخدمين:
 ```bash
 curl http://localhost:9470/api/users
 ```
 ### GET /api/users/:id
 الحصول على المستخدم بالـ ID:
 ```bash
 curl http://localhost:9470/api/users/1
 ```
 ### POST /api/users
 إنشاء مستخدم:
 ```bash
 curl -X POST http://localhost:9470/api/users \
  -d '{"Name": "Charlie", "age": 35}'
 ```
 ### PUT /api/users/:id
 تحديث مستخدم:
 ```bash
 curl -X PUT http://localhost:9470/api/users/1 \
  -d '{"Name": "Alice", "age": 31}'
 ```
 ### DELETE /api/users/:id
 حذف مستخدم:
 ```bash
 curl -X DELETE http://localhost:9470/api/users/1
 ```
 ## نقطة نهاية الاستعلام
 تنفيذ استعلامات BaraQL عبر HTTP:
 ```bash
 curl -X POST http://localhost:9470/api/query \
  -d '{"sql": "SELECT * FROM users WHERE age > 18"}'
 ```
@@ -1,78 +0,0 @@
 # API WebSocket
 دفق كامل للاتجاهين لتغذية البيانات في الوقت الفعلي والإشعارات.
 ## الاتصال
 ```
 ws://localhost:9471/ws
 ```
 ## مثال العميل
 ```javascript
 const ws = new WebSocket('ws://localhost:9471/ws');
 ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'query',
    sql: 'SELECT * FROM users'
  }));
 };
 ws.onmessage = (event) => {
  console.log('Received:', JSON.parse(event.data));
 };
 ```
 ## تنسيق الرسالة
 ```json
 {
  "type": "query",
  "id": "uuid",
  "sql": "SELECT * FROM users"
 }
 ```
 ## أنواع الرسائل
 ### طلب الاستعلام
 ```json
 {
  "type": "query",
  "id": "123",
  "sql": "SELECT * FROM users"
 }
 ```
 ### استجابة الاستعلام
 ```json
 {
  "type": "result",
  "id": "123",
  "data": [{"id": 1, "name": "Alice"}]
 }
 ```
 ### الاشتراك
 ```json
 {
  "type": "subscribe",
  "table": "users"
 }
 ```
 ### إشعار
 ```json
 {
  "type": "push",
  "table": "users",
  "action": "insert",
  "data": {"id": 3, "name": "Charlie"}
 }
 ```
@@ -1,102 +0,0 @@
 # بنية BaraDB
 ## نظرة عامة
 BaraDB هو **محرك قاعدة بيانات متعدد الأنماط** مكتوب بـ Nim يجمع بين تخزين المستندات (KV) والرسم البياني والمتجهي والعمودي والبحث النصي الكامل في محرك واحد مع لغة استعلام موحدة **BaraQL**.
 ## البنية الطبقية
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ 1. طبقة العميل                                          │
 │    البروتوكول الثنائي │ HTTP/REST │ WebSocket │ مضمن    │
 ├─────────────────────────────────────────────────────────┤
 │ 2. طبقة الاستعلام (BaraQL)                              │
 │    المحلل اللغوي → المحلل → AST → IR → المحسن → توليد الكود│
 ├─────────────────────────────────────────────────────────┤
 │ 3. محركات التنفيذ                                       │
 │    المستندات │ الرسم البياني │ المتجه │ العمودي │ FTS     │
 ├─────────────────────────────────────────────────────────┤
 │ 4. التخزين                                              │
 │    LSM-Tree │ B-Tree │ WAL │ Bloom │ الضغط │ الذاكرة المؤقتة│
 ├─────────────────────────────────────────────────────────┤
 │ 5. الموزع                                               │
 │    توافق Raft │ التجزئة │ النسخ │ Gossip                 │
 └─────────────────────────────────────────────────────────┘
 ```
 ## الطبقة 1: طبقة العميل
 - **البروتوكول الثنائي**: بروتوكول ثنائي فعال big-endian
 - **HTTP/REST**: واجهة REST مبنية على JSON
 - **WebSocket**: دفق ثنائي الاتجاه كامل
 - **المدمج**: وصول مباشر داخل العملية
 ## الطبقة 2: طبقة الاستعلام (BaraQL)
 1. **المحلل اللغوي** (`query/lexer.nim`): أكثر من 80 نوع رمز
 2. **المحلل** (`query/parser.nim`): محلل تنازلي تكراري
 3. **AST** (`query/ast.nim`): أكثر من 25 نوع عقدة
 4. **IR** (`query/ir.nim`): تمثيل وسيط
 5. **المحسن** (`query/adaptive.nim`): تحسين عبر الأنماط
 6. **توليد الكود** (`query/codegen.nim`): ترجمة إلى عمليات التخزين
 7. **المنفذ** (`query/executor.nim`): تنفيذ متوازي
 ## الطبقة 3: محركات التنفيذ
 ### محرك المستندات/KV
 - **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTables
 ### المحرك المتجهي (`vector/`)
 - **فهرس HNSW** (`vector/engine.nim`): رسم بياني صغير قابل للملاحة هرمي
 - **فهرس IVF-PQ**: ملف مقلوب مع تكميم المنتج
 - **عمليات SIMD** (`vector/simd.nim`): محسّن بـ AVX2
 ### محرك الرسم البياني (`graph/`)
 - BFS، DFS، Dijkstra، PageRank
 - **Louvain**: كشف المجتمع
 ### البحث النصي الكامل (`fts/`)
 - الفهرس المقلوب، BM25، TF-IDF
 - **متعدد اللغات**: tokenizers لـ EN، BG، DE، FR، RU
 ## الطبقة 4: التخزين
 - **LSM-Tree**: MemTable، WAL، SSTable، Bloom Filter
 - **ذاكرة الصفحة**: ذاكرة مؤقتة LRU
 - **I/O المعينة**: وصول قائم على mmap
 - **الاستعادة**: إعادة تشغيل WAL
 ## الطبقة 5: الموزع
 - **توافق Raft** (`core/raft.nim`): انتخاب القائد، نسخ السجل
 - **التجزئة** (`core/sharding.nim`): hash، range، تجزئة متسقة
 - **النسخ** (`core/replication.nim`): متزامن، غير متزامن، شبه متزامن
 - **بروتوكول Gossip** (`core/gossip.nim`): مثل SWIM
 ## قرارات التصميم الرئيسية
 1. **Nim نقي**: بدون تبعيات Cython أو Python أو Rust
 2. **تخزين موحد**: محرك واحد لـ KV والرسم البياني والمتجة وFTS والعمودي
 3. **الوضع المدمج**: يمكن تشغيله كمكتبة أو خادم
 4. **البروتوكول الثنائي**: بروتوكول سلكي فعال مخصص
 5. **MVCC**: تحكم في التزامن متعدد الإصدارات
 6. **المخطط أولاً**: نظام مخطط مكتوب بشدة مع الوراثة
 7. **عبر الأنماط**: لغة استعلام واحدة عبر جميع نماذج البيانات
 8. **التحقق الرسمي**: الخوارزميات الموزعة الأساسية محددة في TLA+ ومتحقق منها مع TLC
 ## إحصائيات الوحدات
 | الفئة | الوحدات | أسطر الكود | الغرض |
 |-------|---------|------------|-------|
 | Core | 16 | ~4,200 | الخادم، البروتوكولات، المعاملات، الموزع |
 | Storage | 7 | ~3,100 | LSM، B-Tree، WAL، bloom، الضغط، mmap |
 | Query | 7 | ~2,800 | المحلل اللغوي، المحلل، AST، IR، المحسن، توليد الكود |
 | Vector | 3 | ~1,200 | HNSW، IVF-PQ، التكميم، SIMD |
 | Graph | 3 | ~1,000 | قائمة الجوار، الخوارزميات، كشف المجتمع |
 | FTS | 2 | ~900 | الفهرس المقلوب، BM25، غامض، متعدد اللغات |
 | Protocol | 7 | ~2,400 | Wire، HTTP، WebSocket، pool، auth، حد السعر، SSL |
 | Schema | 1 | ~600 | الأنواع، الروابط، الوراثة |
 | Client | 2 | ~800 | عميل Nim الثنائي |
 | CLI | 1 | ~400 | صدفة BaraQL التفاعلية |
 | **المجموع** | **49** | **~14,100** | |
@@ -1,82 +0,0 @@
 # النسخ الاحتياطي والاستعادة
 ## لقطات عبر الإنترنت
 تدعم BaraDB اللقطات عبر الإنترنت دون إيقاف الخادم.
 ### إنشاء لقطة
 ```nim
 import barabadb/core/backup
 var bm = newBackupManager()
 bm.createSnapshot("/backup/baradb_2025-01-15")
 ```
 ### عبر CLI
 ```bash
 ./build/baradadb --snapshot --output=/backup/snapshot.db
 ```
 ### عبر HTTP API
 ```bash
 curl -X POST http://localhost:9470/api/backup \
  -d '{"destination": "/backup/snapshot.db"}'
 ```
 ### النسخ الاحتياطي التلقائي
 ```bash
 0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
 find /backup -name "baradb_*.db" -mtime +7 -delete
 ```
 ## استعادة نقطة في الوقت (PITR)
 ### الاستعادة من اللقطة + WAL
 ```bash
 ./build/baradadb --recover \
  --checkpoint=/backup/snapshot.db \
  --wal-dir=/backup/wal
 ```
 ### الاستعادة عبر SQL
 ```sql
 RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
 ```
 ## سيناريوهات استعادة الكوارث
 ### السيناريو 1: تلف الملف
 ```bash
 cp /backup/sstables/000012.sst ./data/sstables/
 ./build/baradadb --rebuild-index
 ```
 ### السيناريو 2: فقدان البيانات الكامل
 ```bash
 cp /backup/snapshot.db ./data/
 ./build/baradadb --recover --wal-dir=/backup/wal
 ```
 ### السيناريو 3: فشل عقدة الكتلة
 ```bash
 BARADB_RAFT_NODE_ID=newnode \
 BARADB_RAFT_PEERS=node1:9001,node2:9001 \
 ./build/baradadb
 ```
 ## أفضل الممارسات
 1. اختبار الاستعادة بانتظام
 2. تخزين النسخ الاحتياطية خارج الموقع
 3. تشفير النسخ الاحتياطية
 4. مراقبة مهام النسخ الاحتياطي
 5. توثيق RTO/RPO
@@ -1,268 +0,0 @@
 # مرجع لغة استعلام BaraQL
 BaraQL هي لغة استعلام متوافقة مع SQL مع امتدادات لعمليات الرسم البياني والمتجة والمستندات.
 ## أنواع البيانات
 | النوع | الوصف | مثال |
 |-------|-------|------|
 | `null` | قيمة فارغة | `null` |
 | `bool` | منطقي | `true`, `false` |
 | `int8` | عدد صحيح 8 بت | `127` |
 | `int16` | عدد صحيح 16 بت | `32767` |
 | `int32` | عدد صحيح 32 بت | `2147483647` |
 | `int64` | عدد صحيح 64 بت | `9223372036854775807` |
 | `float32` | فاصلة عائمة 32 بت | `3.14` |
 | `float64` | فاصلة عائمة 64 بت | `3.14159265359` |
 | `str` | سلسلة UTF-8 | `'hello'` |
 | `vector` | متجه float32 | `[0.1, 0.2, 0.3]` |
 | `datetime` | طابع زمني ISO 8601 | `'2025-01-15T10:30:00Z'` |
 | `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` |
 ## الاستعلامات الأساسية
 ### SELECT
 ```sql
 SELECT * FROM users;
 SELECT name, age FROM users;
 SELECT name AS full_name FROM users;
 SELECT * FROM users LIMIT 10 OFFSET 20;
 ```
 ### WHERE
 ```sql
 SELECT * FROM users WHERE age > 18;
 SELECT * FROM users WHERE age BETWEEN 18 AND 65;
 SELECT * FROM users WHERE department IN ('Engineering', 'Sales');
 SELECT * FROM users WHERE name LIKE 'A%';
 ```
 ### INSERT
 ```sql
 INSERT users { name := 'Alice', age := 30 };
 ```
 ### UPDATE
 ```sql
 UPDATE users SET age = 31 WHERE name = 'Alice';
 ```
 ### DELETE
 ```sql
 DELETE FROM users WHERE name = 'Bob';
 ```
 ## JOIN
 ```sql
 SELECT u.name, o.total
 FROM users u
 INNER JOIN orders o ON u.id = o.user_id;
 ```
 ## CTE (تعبيرات الجدول المشترك)
 ```sql
 WITH active_users AS (
  SELECT * FROM users WHERE active = true
 )
 SELECT * FROM active_users;
 ```
 ## البحث المتجهي
 ```sql
 INSERT articles { title := 'Nim Programming', embedding := [0.1, 0.2, 0.3, 0.4] };
 SELECT title FROM articles
 ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
 LIMIT 5;
 ```
 ## أنماط الرسم البياني
 ```sql
 MATCH (p:Person)-[:KNOWS]->(friend:Person)
 WHERE p.name = 'Alice'
 RETURN friend.name;
 ```
 ## المعاملات
 ```sql
 BEGIN;
 INSERT users { name := 'Alice', age := 30 };
 INSERT orders { user_id := last_insert_id(), total := 100 };
 COMMIT;
 -- مع نقطة حفظ
 BEGIN;
 INSERT users { name := 'Bob', age := 25 };
 SAVEPOINT sp1;
 INSERT orders { user_id := last_insert_id(), total := 200 };
 -- خطأ، التراجع إلى نقطة الحفظ
 ROLLBACK TO sp1;
 COMMIT;
 ```
 ## البحث النصي الكامل
 ```sql
 -- بحث أساسي
 SELECT * FROM articles
 WHERE MATCH(title, body) AGAINST('database programming');
 -- مع درجة الصلة
 SELECT title, relevance()
 FROM articles
 WHERE MATCH(title, body) AGAINST('Nim language')
 ORDER BY relevance() DESC;
 -- الوضع المنطقي
 SELECT * FROM articles
 WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE);
 -- البحث الضبابي
 SELECT * FROM articles
 WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2);
 ```
 ## الدوال المحددة من المستخدم
 ```sql
 -- تسجيل UDF
 CREATE FUNCTION greet(name str) -> str {
  RETURN 'Hello, ' || name || '!';
 };
 -- استخدامها
 SELECT greet(name) FROM users;
 -- الدوال المدمجة
 SELECT abs(-5), sqrt(16), lower('HELLO'), len('test');
 ```
 ## تلميحات الاستعلام
 ```sql
 -- فرض استخدام الفهرس
 SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18;
 -- فرض البحث المتجهي التقريبي
 SELECT /*+ APPROXIMATE */ * FROM vectors
 ORDER BY cosine_distance(embedding, [...])
 LIMIT 10;
 -- التنفيذ المتوازي
 SELECT /*+ PARALLEL(4) */ * FROM large_table;
 ```
 ## دوال النوافذ
 ```sql
 -- دوال الترتيب
 SELECT
  name,
  department,
  ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn,
  RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r,
  DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr
 FROM employees;
 -- دوال القيمة
 SELECT
  name,
  salary,
  LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary,
  LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary,
  FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest,
  LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive
 FROM employees;
 -- دوال التوزيع
 SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees;
 ```
 ### مواصفات الإطار
 ```sql
 -- إطار ROWS
 SUM(salary) OVER (
  PARTITION BY department
  ORDER BY hire_date
  ROWS BETWEEN 1 PRECEDING AND CURRENT ROW
 )
 -- إطار RANGE
 SUM(salary) OVER (
  PARTITION BY department
  ORDER BY hire_date
  RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
 )
 ```
 ## ERP متعدد المستأجرين
 يدعم BaraDB تشغيل عدة شركات (مستأجرين) في مثيل قاعدة بيانات واحد، باستخدام **أمان مستوى الصف (RLS)** مع **متغيرات الجلسة**.
 ### متغيرات الجلسة
 ```sql
 SET app.tenant_id = 'company-123';
 SELECT current_setting('app.tenant_id') AS tenant;
 ```
 ### المستخدم / الدور الحالي
 ```sql
 SELECT current_user AS me, current_role AS my_role;
 ```
 ### عزل المستأجر عبر RLS
 ```sql
 -- تمكين RLS على جدول
 ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
 -- إنشاء سياسة تصفية حسب المستأجر
 CREATE POLICY tenant_isolation ON invoices
  FOR SELECT USING (tenant_id = current_setting('app.tenant_id'));
 -- كل جلسة ترى فقط بياناتها
 SET app.tenant_id = 'company-a';
 SELECT * FROM invoices;  -- صفوف company-a فقط
 ```
 ### لماذا متعدد المستأجرين؟
 - **مثيل واحد، مستأجرون كثيرون** — لا حاجة لتشغيل 100 قاعدة بيانات منفصلة
 - **مستندات JSONB** — تخزين مخطط مرن، سهل إضافة حقول لكل مستأجر
 - **RLS يضمن العزل** — قاعدة البيانات تفرض حدود المستأجر، وليس فقط التطبيق
 ## الكلمات المفتاحية المدعومة
 | الفئة | الكلمات المفتاحية |
 |----------|----------|
 | DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT |
 | DML | INSERT, UPDATE, DELETE, SET, VALUES |
 | DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE |
 | Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON |
 | Set | UNION, UNION ALL, INTERSECT, EXCEPT |
 | CTEs | WITH, RECURSIVE, AS |
 | Case | CASE, WHEN, THEN, ELSE, END |
 | Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT |
 | Graph | MATCH, RETURN, WHERE, shortestPath, type |
 | FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS |
 | Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> |
 | JSON | ->, ->> |
 | FTS | @@ (تطابق BM25) |
 | Recovery | RECOVER TO TIMESTAMP |
 | Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting |
 | Session | SET, current_setting, current_user, current_role |
 | Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING |
 | Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE |
@@ -1,26 +0,0 @@
 # فهرس B-Tree
 هيكل فهرس مرتب للبحث النطاقي والنقطة الفعال.
 ## الاستخدام
 ```nim
 import barabadb/storage/btree
 var btree = newBTreeIndex[string, string]()
 btree.insert("key1", "value1")
 btree.insert("key2", "value2")
 let values = btree.get("key1")
 let range = btree.scan("key_a", "key_z")
 btree.delete("key1")
 ```
 ## الميزات
 - تخزين مفاتي-قيم مرتب
 - استعلامات النطاق (BETWEEN, >, <, >=, <=)
 - المسح بالبادئة
 - حجم الصفحة القابل للتكوين
 - دعم المكرر
@@ -1,76 +0,0 @@
 # سجل التغييرات
 ## [0.1.0] — 2025-01-15
 ### المضاف
 - **محركات التخزين الأساسية**
  - LSM-Tree مع MemTable و WAL و SSTables و size-tiered compaction
  - فهرس B-Tree مرتب مع المسح النطاقي و MVCC copy-on-write
  - فلاتر Bloom
  - I/O المعينة بالذاكرة
  - ذاكرة صفحة LRU
 - **محرك الاستعلام (BaraQL)**
  - lexer متوافق مع SQL مع 80+ نوع رمز
  - parser تنازلي تكراري ينتج AST مع 25+ نوع عقدة
  - تمثيل وسيط (IR)
  - محسن استعلام تكيفي مع تخطيط عبر الأنماط
  - منفذ استعلام مع 병렬화
 - **ميزات لغة BaraQL**
  - SELECT و INSERT و UPDATE و DELETE
  - WHERE و ORDER BY و LIMIT و OFFSET
  - GROUP BY و HAVING ودوال التجميع
  - INNER JOIN و LEFT JOIN و RIGHT JOIN و FULL JOIN و CROSS JOIN
  - CTEs مع WITH
  - الاستعلامات الفرعية
  - تعبيرات CASE
  - UNION و INTERSECT و EXCEPT
 - **محرك المتجهات**
  - فهرس HNSW
  - فهرس IVF-PQ
  - دوال المسافة المحسنة بـ SIMD
  - التكميم: 8-bit/4-bit القياسي والمنتج والثنائي
 - **محرك الرسم البياني**
  - تخزين قائمة المجاورة
  - BFS و DFS للعبور
  - Dijkstra لأقصر مسار
  - PageRank
  - Louvain لكشف المجتمع
  - محلل استعلامات Cypher
 - **البحث النصي الكامل**
  - الفهرس المقلوب
  - ترتيب BM25
  - TF-IDF
  - البحث الغامض
  - tokenizers متعدد اللغات
 - **البروتوكولات**
  - بروتوكول Wire الثنائي مع 16 نوع رسالة
  - API HTTP/REST JSON
  - WebSocket للدفق
  - تجميع الاتصالات
  - مصادقة JWT
  - TLS/SSL
 - **الأنظمة الموزعة**
  - توافق Raft
  - تجزئة hash و range و consistent-hash
  - نسخ متزامن/غير متزامن/شبه متزامن
  - بروتوكول Gossip
  - commit على مرحلتين
 ### الأداء
 - LSM-Tree: 580K كتابة/ثانية، 720K قراءة/ثانية
 - B-Tree: 1.2M إدراج/ثانية، 1.5M بحث/ثانية
 - Vector SIMD: 850K مسافة جيب التمام/ثانية (dim=768)
 ### الاختبارات
 - 262 اختبار عبر 56 مجموعة اختبار
 - 100% معدل النجاح
@@ -1,66 +0,0 @@
 # حزم العملاء
 توفر BaraDB مكتبات العملاء الرسمية لـ JavaScript/TypeScript و Python و Nim و Rust.
 ## JavaScript / TypeScript
 ### التثبيت
 ```bash
 npm install baradb
 ```
 ### الاستخدام الأساسي
 ```typescript
 import { Client } from 'baradb';
 const client = new Client('localhost', 9472);
 await client.connect();
 const result = await client.query('SELECT name, age FROM users WHERE age > 18');
 ```
 ## Python
 ### التثبيت
 ```bash
 pip install baradb
 ```
 ### الاستخدام الأساسي
 ```python
 from baradb import Client
 client = Client("localhost", 9472)
 client.connect()
 result = client.query("SELECT name, age FROM users WHERE age > 18")
 ```
 ## Nim (الوضع المدمج)
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key", cast[seq[byte]]("value"))
 let (found, val) = db.get("key")
 db.close()
 ```
 ## Rust
 ```rust
 use baradb::Client;
 let mut client = Client::connect("localhost:9472").await?;
 ```
 ## HTTP/REST
 ```bash
 curl -X POST http://localhost:9470/api/query \
  -d '{"query": "SELECT * FROM users"}'
 ```
@@ -1,50 +0,0 @@
 # التخزين العمودي
 تخزين موجهة للأعمدة للاستعلامات التحليلية والتجميعات.
 ## الاستخدام
 ```nim
 import barabadb/core/columnar
 var batch = newColumnBatch()
 var ageCol = batch.addInt64Col("age")
 var nameCol = batch.addStringCol("name")
 ageCol.appendInt64(25)
 nameCol.appendString("Alice")
 ```
 ## التجميعات
 ```nim
 echo ageCol.sumInt64()
 echo ageCol.avgInt64()
 echo ageCol.minInt64()
 echo ageCol.maxInt64()
 ```
 ## الترميز
 ### RLE
 ```nim
 let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
 ```
 ### Dictionary
 ```nim
 let dict = dictEncode(@["apple", "banana", "apple"])
 ```
 ## أنواع الأعمدة
 | النوع | الوصف |
 |-------|-------|
 | `int32` | عدد صحيح 32 بت |
 | `int64` | عدد صحيح 64 بت |
 | `float32` | فاصلة عائمة 32 بت |
 | `float64` | فاصلة عائمة 64 بت |
 | `string` | سلسلة متغيرة الطول |
 | `bool` | منطقي |
@@ -1,96 +0,0 @@
 # مرجع التكوين
 يمكن تكوين BaraDB عبر **متغيرات البيئة** أو **ملف التكوين** أو **علامات سطر الأوامر**.
 ## ترتيب الأولوية
 1. علامات سطر الأوامر (الأعلى)
 2. متغيرات البيئة
 3. ملف التكوين (`baradb.conf` أو `baradb.json`)
 4. الإعدادات الافتراضية (الأدنى)
 ## متغيرات البيئة
 ### الشبكة
 | المتغير | الافتراضي | الوصف |
 |---------|-----------|-------|
 | `BARADB_ADDRESS` | `127.0.0.1` | عنوان الربط |
 | `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
 | `BARADB_HTTP_PORT` | `9470` | منفذ HTTP/REST API |
 | `BARADB_WS_PORT` | `9471` | منفذ WebSocket |
 ### التخزين
 | المتغير | الافتراضي | الوصف |
 |---------|-----------|-------|
 | `BARADB_DATA_DIR` | `./data` | مسار دليل البيانات |
 | `BARADB_MEMTABLE_SIZE_MB` | `64` | حجم MemTable (MB) |
 | `BARADB_CACHE_SIZE_MB` | `256` | حجم ذاكرة الصفحة (MB) |
 ### TLS/SSL
 | المتغير | الافتراضي | الوصف |
 |---------|-----------|-------|
 | `BARADB_TLS_ENABLED` | `false` | تمكين TLS |
 | `BARADB_CERT_FILE` | — | مسار شهادة TLS |
 | `BARADB_KEY_FILE` | — | مسار مفتاح TLS الخاص |
 ### الأمان
 | المتغير | الافتراضي | الوصف |
 |---------|-----------|-------|
 | `BARADB_AUTH_ENABLED` | `false` | تمكين المصادقة |
 | `BARADB_JWT_SECRET` | — | سر توقيع JWT |
 | `BARADB_RATE_LIMIT_GLOBAL` | `10000` | طلبات/ثانية عامة |
 | `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | طلبات/ثانية لكل عميل |
 ## ملف التكوين
 ### baradb.conf
 ```ini
 [server]
 address = "0.0.0.0"
 port = 9472
 http_port = 9470
 [storage]
 data_dir = "/var/lib/baradb"
 memtable_size_mb = 256
 cache_size_mb = 512
 [tls]
 enabled = true
 cert_file = "/etc/baradb/server.crt"
 key_file = "/etc/baradb/server.key"
 [auth]
 enabled = true
 jwt_secret = "change-me-in-production"
 ```
 ## علامات سطر الأوامر
 ```bash
 ./build/baradadb --help
 ```
 ## أمثلة التكوين
 ### التطوير
 ```bash
 ./build/baradadb --log-level debug --data-dir ./dev_data
 ```
 ### الإنتاج - عقدة واحدة
 ```bash
 BARADB_TLS_ENABLED=true \
 BARADB_AUTH_ENABLED=true \
 BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
 BARADB_MEMTABLE_SIZE_MB=256 \
 BARADB_CACHE_SIZE_MB=1024 \
 ./build/baradadb
 ```
@@ -1,48 +0,0 @@
 # الاستعلامات عبر الأنماط
 القدرة الفريدة لـ BaraDB هي تنفيذ استعلامات تمتد عبر محركات تخزين متعددة في بيان BaraQL موحد واحد.
 ## نظرة عامة
 - **مستند/KV** (LSM-Tree) — السجلات المهيكلة
 - **رسم بياني** (قائمة المجاورة) — العلاقات
 - **متجهي** (HNSW/IVF-PQ) — بحث التشابه
 - **نص كامل** (الفهرس المقلوب) — البحث النصي
 - **عمودي** — التجميعات التحليلية
 ## أنماط الاستعلام
 ### متجه + نص كامل
 ```sql
 SELECT title FROM articles
 WHERE MATCH(body) AGAINST('machine learning')
 ORDER BY cosine_distance(embedding, [...])
 LIMIT 10;
 ```
 ### رسم بياني + متجه
 ```sql
 MATCH (u:User)-[:KNOWS]->(friend:User)
 WHERE u.name = 'Alice'
 ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
 RETURN friend.name;
 ```
 ## التحسين
 ### مخطط استعلام عبر الأنماط
 1. العامل الأكثر انتقائية أولاً
 2. دفع المسندات إلى كل محرك
 3. استخدام فلاتر Bloom لعمليات KV
 4. 병렬화 الفروع المستقلة
 ## الأداء
 | نوع الاستعلام | التأخير (10K صف) |
 |---------------|------------------|
 | FTS + Vector | 15 ms |
 | Graph + Vector | 25 ms |
 | FTS + Aggregate | 12 ms |
@@ -1,68 +0,0 @@
 # دليل النشر
 ## Docker
 ### البداية السريعة
 ```bash
 docker build -t baradb:latest .
 docker compose up -d
 docker compose ps
 ```
 ### ملفات Docker Compose
 | الملف | الغرض |
 |-------|-------|
 | `docker-compose.yml` | التطوير |
 | `docker-compose.prod.yml` | الإنتاج |
 ## المنافذ
 | المنفذ | الوصف |
 |--------|-------|
 | `9472` | بروتوكول Wire الثنائي |
 | `9470` | HTTP/REST API |
 | `9471` | WebSocket |
 ## متغيرات البيئة
 | المتغير | الافتراضي | الوصف |
 |---------|-----------|-------|
 | `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع |
 | `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
 | `BARADB_HTTP_PORT` | `9470` | منفذ HTTP |
 | `BARADB_DATA_DIR` | `/data` | دليل البيانات |
 ## المجلدات
 | المسار | الوصف |
 |--------|-------|
 | `/data` | دليل البيانات الرئيسي |
 | `/data/server/wal` | سجل write-ahead |
 | `/data/server/sstables` | ملفات SSTable |
 ## قائمة التحقق للإنتاج
 - [ ] إنشاء شهادات TLS في `./certs/`
 - [ ] تعيين `BARADB_JWT_SECRET` قوي
 - [ ] تكوين قواعد جدار الحماية
 - [ ] تكوين النسخ الاحتياطي المنتظم
 - [ ] التحقق من حدود الموارد
 - [ ] تكوين المراقبة
 ## TLS في Docker
 ```bash
 mkdir -p certs
 openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/server.key -out certs/server.crt
 ```
 ## النسخ الاحتياطي في Docker
 ```bash
 docker exec baradb /app/backup backup --data-dir=/data
 docker exec baradb /app/backup list
 docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
 ```
@@ -1,73 +0,0 @@
 # الأنظمة الموزعة
 تدعم BaraDB النشر الموزع مع توافق Raft والتجزئة والنسخ.
 ## توافق Raft
 انتخاب القائد ونسخ السجل:
 ```nim
 import barabadb/core/raft
 var cluster = newRaftCluster()
 cluster.addNode("node1")
 cluster.addNode("node2")
 cluster.addNode("node3")
 let n1 = cluster.nodes["n1"]
 n1.becomeCandidate()
 n1.becomeLeader()
 ```
 ## التجزئة
 ```nim
 import barabadb/core/sharding
 var router = newShardRouter(ShardConfig(
  numShards: 4,
  replicas: 2,
  strategy: ssHash
 ))
 ```
 ### استراتيجيات التجزئة
 | الاستراتيجية | الوصف |
 |-------------|-------|
 | `ssHash` | تجزئة قائمة على hash |
 | `ssRange` | تجزئة قائمة على النطاق |
 | `ssConsistent` | تجزئة متسقة |
 ## النسخ
 ```nim
 import barabadb/core/replication
 var rm = newReplicationManager(rmSync)
 rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
 ```
 ### أوضاع النسخ
 | الوضع | الوصف |
 |-------|-------|
 | `rmSync` | نسخ متزامن |
 | `rmAsync` | نسخ غير متزامن |
 | `rmSemiSync` | نسخ شبه متزامن |
 ## المعاملات الموزعة
 الالتزام على مرحلتين:
 ```nim
 import barabadb/core/disttxn
 var dt = newDistributedTxn()
 dt.prepare(@["node1", "node2"])
 dt.commit()
 ```
 ## التحقق الرسمي
 تم تحديد الخوارزميات الموزعة الأساسية في TLA+ والتحقق منها.
@@ -1,78 +0,0 @@
 # دليل نشر Docker
 ## البداية السريعة
 ```bash
 git clone https://codeberg.org/baraba/baradb
 cd barabaDB
 docker build -t baradb:latest .
 docker compose up -d
 docker compose ps
 docker compose logs -f
 ```
 ## الملفات
 | الملف | الوصف |
 |-------|-------|
 | `Dockerfile` | بناء multi-stage للإنتاج |
 | `docker-compose.yml` | تكوين التطوير |
 | `docker-compose.prod.yml` | تكوين الإنتاج |
 ## بناء الصورة
 ```bash
 docker build -t baradb:latest .
 ```
 ## التشغيل
 ### التطوير
 ```bash
 docker compose up -d
 docker compose down
 ```
 ### الإنتاج
 ```bash
 docker compose -f docker-compose.prod.yml up -d
 ```
 ## المنافذ
 | المنفذ | الوصف |
 |--------|-------|
 | `9472` | بروتوكول Wire الثنائي |
 | `9470` | HTTP/REST API |
 | `9471` | WebSocket |
 ## متغيرات البيئة
 | المتغير | الافتراضي | الوصف |
 |---------|-----------|-------|
 | `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع |
 | `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي |
 | `BARADB_HTTP_PORT` | `9470` | منفذ HTTP |
 | `BARADB_DATA_DIR` | `/data` | دليل البيانات |
 ## المجلدات
 | المسار | الوصف |
 |--------|-------|
 | `/data` | دليل البيانات الرئيسي |
 | `/data/server/wal` | سجل write-ahead |
 | `/data/server/sstables` | ملفات SSTable |
 ## قائمة التحقق للإنتاج
 - [ ] إنشاء شهادات TLS في `./certs/`
 - [ ] تعيين `BARADB_JWT_SECRET` قوي
 - [ ] تكوين قواعد جدار الحماية
 - [ ] تكوين النسخ الاحتياطي المنتظم
 - [ ] التحقق من حدود الموارد
 - [ ] تكوين المراقبة
@@ -1,47 +0,0 @@
 # محرك البحث النصي الكامل
 فهرس مقلوب مع ترتيب BM25 و TF-IDF للبحث النصي.
 ## الاستخدام
 ```nim
 import barabadb/fts/engine
 var idx = newInvertedIndex()
 idx.addDocument(1, "Nim is a fast programming language")
 idx.addDocument(2, "Python is popular for data science")
 let results = idx.search("programming language")
 let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
 ```
 ## طرق الترتيب
 ### BM25
 ```nim
 let bm25 = idx.searchBM25("query terms")
 ```
 ### TF-IDF
 ```nim
 let tfidf = idx.searchTfidf("query terms")
 ```
 ## ميزات البحث
 | الميزة | الوصف |
 |---------|-------|
 | Fuzzy search | تساهل مسافة Levenshtein |
 | Wildcard | بادئة، لاحقة،wildcard中间 |
 | Regex | أنماط التعبير العادي |
 | Phrase search | تطابق عبارة تامة |
 | Boolean | عوامل AND, OR, NOT |
 ## واجهة SQL
 ```sql
 CREATE INDEX idx_fts ON articles(body) USING FTS;
 SELECT * FROM articles WHERE body @@ 'machine learning';
 ```
@@ -1,42 +0,0 @@
 # محرك الرسم البياني
 تخزين قائمة المجاورة مع خوارزميات مدمجة للعبور والتحليل.
 ## الاستخدام
 ```nim
 import barabadb/graph/engine
 var g = newGraph()
 let alice = g.addNode("Person", {"Name": "Alice"}.toTable)
 let bob = g.addNode("Person", {"Name": "Bob"}.toTable)
 discard g.addEdge(alice, bob, "knows")
 let bfs = g.bfs(alice)
 let path = g.shortestPath(alice, bob)
 let ranks = g.pageRank()
 ```
 ## الخوارزميات
 | الخوارزمية | الوصف |
 |------------|-------|
 | `bfs` | عبور بالعرض |
 | `dfs` | عبور بالعمق |
 | `dijkstra` | أقصر مسار موزون |
 | `pageRank` | ترتيب أهمية العقدة |
 | `louvain` | كشف المجتمع |
 | `patternMatch` | تماثل الرسم الفرعي |
 ## استعلام Cypher
 ```nim
 import barabadb/graph/cypher
 var engine = newCypherEngine(g)
 let results = engine.execute("""
  MATCH (p:Person)-[:KNOWS]->(friend:Person)
  WHERE p.name = 'Alice'
  RETURN friend.name
 """)
 ```
@@ -1,59 +0,0 @@
 # توثيق BaraDB (العربية)
 **محرك قاعدة بيانات متعدد الأنماط مكتوب بـ Nim — 100% أصلي، بدون تبعيات.**
 ## روابط سريعة
 > **ملاحظة:** التوثيق العربي قيد التطوير. يرجى الرجوع إلى [النسخة الإنجليزية](../en/) للمعلومات الكاملة.
 ### البدء
 - [التثبيت](../en/installation.md)
 - [البداية السريعة](../en/quickstart.md)
 - [نظرة عامة على البنية](../en/architecture.md)
 - [مرجع التكوين](../en/configuration.md)
 - [دليل النشر](../en/deployment.md)
 ### المفاهيم الأساسية
 - [لغة استعلام BaraQL](../en/baraql.md)
 - [محركات التخزين](../en/storage.md)
 - [نظام المخطط](../en/schema.md)
 - [الاستعلامات عبر الأنماط](../en/crossmodal.md)
 ### المحركات
 - [تخزين LSM-Tree](../en/lsm.md)
 - [فهرس B-Tree](../en/btree.md)
 - [البحث المتجهي](../en/vector.md)
 - [محرك الرسم البياني](../en/graph.md)
 - [البحث النصي الكامل](../en/fts.md)
 - [التخزين العمودي](../en/columnar.md)
 ### API والعملاء
 - [SDK للعملاء](../en/clients.md)
 - [البروتوكول الثنائي](../en/api-binary.md)
 - [HTTP/REST API](../en/api-http.md)
 - [WebSocket API](../en/api-websocket.md)
 - [مرجع البروتوكول](../en/protocol.md)
 ### العمليات
 - [الأداء والمعايير](../en/performance.md)
 - [دليل الأمان](../en/security.md)
 - [المراقبة](../en/monitoring.md)
 - [النسخ الاحتياطي والاستعادة](../en/backup.md)
 - [حل المشكلات](../en/troubleshooting.md)
 ### متقدم
 - [المعاملات و MVCC](../en/transactions.md)
 - [الأنظمة الموزعة](../en/distributed.md)
 - [الدوال المحددة من المستخدم](../en/udf.md)
 ---
 ## معلومات المشروع
 - [سجل التغييرات](../en/changelog.md)
 - [الترخيص](../../LICENSE)
 - [مستودع GitHub](https://github.com/katehonz/barabaDB)
 ---
 *التوثيق العربي قيد الترجمة.*
@@ -1,308 +0,0 @@
 # دليل تثبيت BaraDB
 ## المتطلبات
 - **مترجم Nim** >= 2.2.0
 - **ملفات رأس OpenSSL** (لدعم TLS)
 - **نظام التشغيل**: لينكس، macOS، ويندوز
 ### المنصات المدعومة
 | نظام التشغيل | البنية | الحالة |
 |-------------|--------|--------|
 | لينكس | x86_64 | ✅ دعم كامل |
 | لينكس | ARM64 | ✅ دعم كامل |
 | macOS | x86_64 | ✅ دعم كامل |
 | macOS | ARM64 | ✅ دعم كامل |
 | ويندوز | x86_64 | ✅ مدعوم |
 | FreeBSD | x86_64 | 🟡 اختبار المجتمع |
 ## تثبيت Nim
 ### لينكس
 ```bash
 # المثبت الرسمي
 curl https://nim-lang.org/choosenim/init.sh -sSf | sh
 # Ubuntu/Debian
 sudo apt-get update
 sudo apt-get install nim
 # Fedora
 sudo dnf install nim
 # Arch Linux
 sudo pacman -S nim
 ```
 ### macOS
 ```bash
 # Homebrew
 brew install nim
 # MacPorts
 sudo port install nim
 ```
 ### ويندوز
 ```powershell
 # باستخدام choosenim
 curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
 # باستخدام winget
 winget install nim
 # باستخدام scoop
 scoop install nim
 ```
 ### التحقق من التثبيت
 ```bash
 nim --version
 # المتوقع: Nim Compiler Version 2.2.0 أو أحدث
 ```
 ## تثبيت OpenSSL
 ### لينكس
 ```bash
 # Ubuntu/Debian
 sudo apt-get install libssl-dev
 # Fedora
 sudo dnf install openssl-devel
 # Arch Linux
 sudo pacman -S openssl
 ```
 ### macOS
 OpenSSL مضمن مع النظام. إذا لزم الأمر:
 ```bash
 brew install openssl
 ```
 ### ويندوز
 OpenSSL مضمن مع توزيع Nim ويندوز. للبناء اليدوي، قم بالتنزيل من [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html).
 ## بناء BaraDB
 ### استنساخ المستودع
 ```bash
 git clone https://codeberg.org/baraba/baradb
 cd barabaDB
 ```
 ### تثبيت التبعيات
 ```bash
 nimble install -d -y
 ```
 ### خيارات البناء
 #### بناء التصحيح
 ```bash
 nim c -d:ssl -o:build/baradadb src/baradadb.nim
 ```
 #### بناء الإصدار (موصى به)
 ```bash
 nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
 ```
 #### استخدام مهام Nimble
 ```bash
 # بناء التصحيح
 nimble build_debug
 # بناء الإصدار
 nimble build_release
 ```
 #### تقليل حجم الملف الثنائي
 ```bash
 nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
 strip build/baradadb
 ```
 ### التحقق من البناء
 ```bash
 ./build/baradadb --version
 # المتوقع: BaraDB v1.1.6 — Multimodal Database Engine
 ```
 ## تشغيل الاختبارات
 ### جميع الاختبارات
 ```bash
 nim c -d:ssl -r tests/test_all.nim
 ```
 ### مجموعات اختبارات محددة
 ```bash
 # اختبارات التخزين
 nim c -d:ssl -r tests/test_storage.nim
 # اختبارات محرك الاستعلام
 nim c -d:ssl -r tests/test_query.nim
 # اختبارات البروتوكول
 nim c -d:ssl -r tests/test_protocol.nim
 ```
 ### المعايير
 ```bash
 nim c -d:ssl -d:release -r benchmarks/bench_all.nim
 ```
 ## خيارات التثبيت
 ### التثبيت على مستوى النظام
 ```bash
 # بناء إصدار RELEASE
 nimble build_release
 # التثبيت في /usr/local/bin
 sudo cp build/baradadb /usr/local/bin/
 sudo chmod +x /usr/local/bin/baradadb
 # إنشاء دليل البيانات
 sudo mkdir -p /var/lib/baradb
 sudo chmod 755 /var/lib/baradb
 ```
 ### الملف الثنائي المبنى مسبقًا
 قم بتنزيل أحدث إصدار لمنصتك:
 ```bash
 # لينكس x86_64
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
 chmod +x baradadb-linux-amd64
 mv baradadb-linux-amd64 /usr/local/bin/baradadb
 # لينكس ARM64
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64
 chmod +x baradadb-linux-arm64
 mv baradadb-linux-arm64 /usr/local/bin/baradadb
 # macOS
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64
 chmod +x baradadb-darwin-amd64
 mv baradadb-darwin-amd64 /usr/local/bin/baradadb
 ```
 ### Docker
 ```bash
 # سحب الصورة الرسمية
 docker pull barabadb/barabadb:latest
 # التشغيل
 docker run -d \
  -p 9472:9472 \
  -p 9470:9470 \
  -p 9471:9471 \
  -v baradb_data:/data \
  barabadb/barabadb
 ```
 ### Docker Compose
 ```bash
 docker-compose up -d
 ```
 ### الاستخدام المدمج (مشاريع Nim)
 أضف إلى ملف `.nimble` الخاص بك:
 ```nim
 requires "barabadb >= 1.1.6"
 ```
 استخدم في الكود:
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key", cast[seq[byte]]("value"))
 let (found, val) = db.get("key")
 db.close()
 ```
 ## التشغيل الأول
 ```bash
 # بدء الخادم
 ./build/baradadb
 # المخرجات المتوقعة:
 # BaraDB v1.1.6 — Multimodal Database Engine
 # BaraDB TCP listening on 127.0.0.1:9472
 # الاختبار عبر HTTP API
 curl http://localhost:9470/health
 # الصدفة التفاعلية
 ./build/baradadb --shell
 ```
 ## حل مشكلات التثبيت
 ### "cannot open file: hunos"
 ```bash
 nimble install -d -y
 ```
 ### "BaraDB requires SSL support"
 قم دائمًا بالبناء باستخدام `-d:ssl`:
 ```bash
 nim c -d:ssl -o:build/baradadb src/baradadb.nim
 ```
 ### البناء البطيء
 استخدم البناء المتوازي:
 ```bash
 nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim
 ```
 ### حجم الملف الثنائي الكبير
 استخدم تحسين الحجم:
 ```bash
 nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim
 ```
 ## الخطوات التالية
 - [دليل البداية السريعة](quickstart.md)
 - [مرجع التكوين](configuration.md)
 - [نظرة عامة على البنية](architecture.md)
 - [لغة استعلام BaraQL](baraql.md)
@@ -1,48 +0,0 @@
 # محرك تخزين LSM-Tree
 محرك التخزين الأساسي في BaraDB باستخدام بنية Log-Structured Merge-Tree.
 ## البنية
 ```
 ┌─────────────────────────────────────────────┐
 │                   Writes                     │
 │         (append to WAL + MemTable)           │
 └─────────────────────────────────────────────┘
                      │
                      ▼
 ┌─────────────────────────────────────────────┐
 │                  MemTable                    │
 │         (in-memory sorted buffer)            │
 └─────────────────────────────────────────────┘
                      │
                      ▼
 ┌─────────────────────────────────────────────┐
 │                  SSTable                     │
 │          (sorted string table on disk)       │
 └─────────────────────────────────────────────┘
 ```
 ## الاستخدام
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.delete("key1")
 db.close()
 ```
 ## الميزات
 - **محسن للكتابة**: هيكل log-only إضافي
 - **الدائمة**: WAL يضمن استعادة بعد الانهيار
 - **Bloom Filter**: بحث سلبي سريع
 - **الضغط**: استراتيجية size-tiered
 - **ذاكرة الصفحة**: LRU للصفحاتaccessed بشكل متكرر
@@ -1,109 +0,0 @@
 # خادم MCP (Model Context Protocol)
 يتضمن BaraDB خادم MCP مدمج يمكّن وكلاء الذكاء الاصطناعي (Claude و Cursor وما إلى ذلك) من التفاعل مع قاعدة البيانات مباشرة.
 ## البداية السريعة
 ```bash
 ./build/baramcp --data-dir ./data
 ```
 يبدأ في وضع STDIO، يقبل رسائل JSON-RPC 2.0 على stdin.
 ## الأدوات المتاحة
 ### 1. `query` — تنفيذ SQL
 ```json
 {
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM users WHERE age > ?",
    "params": [25],
    "tenant_id": "company-a",
    "user_id": "alice"
  }
 }
 ```
 استعلامات معاملية باستخدام `?` placeholders. دعم multi-tenant عبر `tenant_id` و `user_id`.
 ### 2. `vector_search` — البحث الدلالي
 ```json
 {
  "name": "vector_search",
  "arguments": {
    "table": "docs",
    "column": "embedding",
    "query_vector": [0.1, 0.2, 0.3],
    "k": 5,
    "metric": "cosine",
    "filter_column": "category",
    "filter_value": "news",
    "tenant_id": "company-a"
  }
 }
 ```
 المقاييس: `cosine`، `euclidean`، `dot_product`، `manhattan`.
 ### 3. `schema_inspect` — استكشاف المخطط
 ```json
 {
  "name": "schema_inspect",
  "arguments": {
    "table": "users",
    "tenant_id": "company-a"
  }
 }
 ```
 إرجاع الجداول والأعمدة والأنواع والمفاتيح الأساسية والمفاتيح الخارجية والفهارس وسياسات RLS.
 ## تكوين Claude Desktop
 ```json
 {
  "mcpServers": {
    "baradb": {
      "command": "/path/to/build/baramcp",
      "args": ["--data-dir", "/path/to/data"]
    }
  }
 }
 ```
 ## تكوين Cursor
 ```json
 {
  "mcpServers": {
    "baradb": {
      "command": "/path/to/build/baramcp",
      "args": ["--data-dir", "~/.baradb/data"]
    }
  }
 }
 ```
 ## عزل Multi-Tenant
 يمكن أن يتضمن كل طلب MCP قيمة `tenant_id` و `user_id`، والتي يتم تعيينها كمتغيرات جلسة:
 - `app.tenant_id` — للترشيح RLS
 - `app.user_id` — لمراجع `current_user`
 تقوم سياسات RLS بتصفية البيانات تلقائياً بناءً على هذه المتغيرات.
 ## بروتوكول JSON-RPC 2.0
 يستخدم الخادم JSON-RPC 2.0 عبر STDIO:
 ```json
 // الطلب
 {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}}
 // الاستجابة
 {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}
 ```
@@ -1,84 +0,0 @@
 # المراقبة والقابلية للملاحظة
 ## فحوصات الصحة
 ### نقطة نهاية صحة HTTP
 ```bash
 curl http://localhost:9470/health
 ```
 الاستجابة:
 ```json
 {
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 86400,
  "checks": {
    "storage": "ok",
    "memory": "ok",
    "connections": "ok"
  }
 }
 ```
 ## المقاييس
 ### مقاييس متوافقة مع Prometheus
 ```bash
 curl http://localhost:9470/metrics
 ```
 مثال على المخرجات:
 ```
 baradb_queries_total 152340
 baradb_queries_duration_seconds_bucket{le="0.001"} 45000
 baradb_storage_lsm_size_bytes 2147483648
 baradb_cache_hit_rate 0.94
 baradb_active_connections 42
 ```
 ## التسجيل
 ### مستويات السجل
 | المستوى | الوصف |
 |---------|-------|
 | `debug` | عمليات داخلية مفصلة |
 | `info` | عمليات عادية |
 | `warn` | مشاكل قابلة للاسترداد |
 | `error` | فشل يستلزم الاهتمام |
 ### سجلات JSON المهيكلة
 ```bash
 BARADB_LOG_LEVEL=info \
 BARADB_LOG_FORMAT=json \
 BARADB_LOG_FILE=/var/log/baradb/baradb.log \
 ./build/baradadb
 ```
 ## لوحة Grafana
 استيراد معرف اللوحة `baradb-001` أو استخدام JSON في `monitoring/grafana-dashboard.json`.
 اللوحات الرئيسية:
 - الاستعلامات في الثانية
 - نسب مئوية لتأخير الاستعلام (p50, p95, p99)
 - حجم التخزين وعدد SSTable
 - معدل إصابة ذاكرة التخزين المؤقت
 - الاتصالات النشطة
 - معدل المعاملات
 - معدل الأخطاء
 ## حل المشكلات بالمقاييس
 | العَرَض | المقاييس | الإجراء |
 |---------|----------|---------|
 | استعلامات بطيئة | `baradb_queries_duration_seconds` | فحص معدل إصابة ذاكرة التخزين المؤقت، إضافة فهارس |
 | ذاكرة عالية | `process_resident_memory_bytes` | تقليل أحجام memtable/cache |
 | نمو التخزين | `baradb_storage_lsm_size_bytes` | تشغيل الضغط اليدوي |
 | أخطاء الاتصال | `baradb_active_connections` | زيادة تجمع الاتصالات أو إضافة العقد |
@@ -1,68 +0,0 @@
 # دليل الأداء
 ## منهجية المعايير
 جميع المعايير تعمل بـ:
 - **المترجم**: Nim 2.2.0 مع `-d:release --opt:speed`
 - **CPU**: AMD Ryzen 9 5900X (12 نواة / 24 خيط)
 - **الذاكرة**: 64 GB DDR4-3600
 - **التخزين**: Samsung 980 Pro NVMe SSD
 ```bash
 nim c -d:ssl -d:release -r benchmarks/bench_all.nim
 ```
 ## معايير محركات التخزين
 ### LSM-Tree
 | المقاييس | القيمة |
 |----------|--------|
 | إنتاجية الكتابة | ~580,000 ops/s |
 | إنتاجية القراءة | ~720,000 ops/s |
 | متوسط تأخير الكتابة | 1.7 µs |
 | متوسط تأخير القراءة | 1.4 µs |
 ### فهرس B-Tree
 | المقاييس | القيمة |
 |----------|--------|
 | إنتاجية الإدراج | ~1,200,000 ops/s |
 | إنتاجية البحث النقطي | ~1,500,000 ops/s |
 ## معايير المحرك المتجهي
 ### فهرس HNSW
 | المقاييس | القيمة |
 |----------|--------|
 | الإدراج (dim=128) | ~45,000 vectors/s |
 | البحث top-10 (n=100K) | ~8 ms |
 المعلمات: `M=16`, `efConstruction=200`, `efSearch=64`.
 ## دليل الضبط
 ### لأحمال الكتابة الثقيلة
 ```bash
 BARADB_MEMTABLE_SIZE_MB=256
 BARADB_WAL_SYNC_INTERVAL_MS=10
 BARADB_COMPACTION_INTERVAL_MS=30000
 ```
 ### لأحمال القراءة الثقيلة
 ```bash
 BARADB_CACHE_SIZE_MB=1024
 BARADB_BLOOM_BITS_PER_KEY=10
 BARADB_COMPACTION_INTERVAL_MS=120000
 ```
 ### للبحث المتجهي
 ```bash
 BARADB_VECTOR_EF_CONSTRUCTION=200
 BARADB_VECTOR_EF_SEARCH=128
 BARADB_VECTOR_M=32
 ```
@@ -1,67 +0,0 @@
 # مرجع البروتوكول
 يدعم BaraDB بروتوكولات متعددة للتواصل مع العملاء:
 - **Binary Wire Protocol** — عالي الأداء، منخفض التأخير
 - **HTTP/REST API** — لغةagnostic، سهل التصحيح
 - **WebSocket** — الدفق و pub/sub
 ## Binary Wire Protocol
 يستخدم ترميز big-endian لجميع القيم متعددة البايت.
 ### دورة الاتصال
 ```
 Client                          Server
  |                               |
  |─── TCP connect ──────────────>|
  |─── Auth message ─────────────>|
  |<── Auth_OK / Error ───────────|
  |─── Query message ────────────>|
  |<── Data / Complete / Error ───|
 ```
 ### تنسيق الرسالة
 ```
 ┌─────────────┬─────────────┬─────────────┬─────────────────────┐
 │  Length     │  Type       │  Sequence   │  Payload            │
 │  (4 bytes)  │  (1 byte)   │  (1 byte)   │  (Length - 6 bytes) │
 └─────────────┴─────────────┴─────────────┴─────────────────────┘
 ```
 ### أنواع الرسائل
 | النوع | ID | الوصف |
 |-------|----|-------|
 | Query | 0x01 | تنفيذ استعلام |
 | Insert | 0x02 | إدراج بيانات |
 | Update | 0x03 | تحديث بيانات |
 | Delete | 0x04 | حذف بيانات |
 | Ready | 0x05 | جاهز للامر التالي |
 | Error | 0x06 | استجابة خطأ |
 ## HTTP/REST API
 Base URL: `http://localhost:9470/api/v1`
 ### نقاط النهاية
 #### Health
 ```http
 GET /health
 ```
 #### استعلام
 ```http
 POST /query
 {
  "query": "SELECT * FROM users"
 }
 ```
 ## WebSocket Protocol
 URL: `ws://localhost:9471`
@@ -1,99 +0,0 @@
 # دليل البداية السريعة لـ BaraDB
 ## تشغيل الخادم
 ```bash
 ./build/baradadb
 ```
 الخادم يبدأ افتراضياً على `localhost:9470`.
 ## الاتصال عبر CLI
 ```bash
 ./build/baradadb --shell
 ```
 ## العمليات الأساسية
 ### إنشاء المخطط
 ```sql
 CREATE TYPE Person {
  name: str,
  age: int32
 };
 ```
 ### إدراج البيانات
 ```sql
 INSERT Person { name := 'Alice', age := 30 };
 ```
 ### استعلام البيانات
 ```sql
 SELECT name, age FROM Person WHERE age > 18;
 ```
 ### تحديث البيانات
 ```sql
 UPDATE Person SET age = 31 WHERE name = 'Alice';
 ```
 ### حذف البيانات
 ```sql
 DELETE FROM Person WHERE name = 'Bob';
 ```
 ## الاستعلامات المتقدمة
 ### JOIN
 ```sql
 SELECT u.name, o.total
 FROM users u
 INNER JOIN orders o ON u.id = o.user_id;
 ```
 ### CTE
 ```sql
 WITH active_users AS (
  SELECT * FROM users WHERE active = true
 )
 SELECT * FROM active_users;
 ```
 ## البحث المتجهي
 ```sql
 INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] };
 SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10;
 ```
 ## عمليات الرسم البياني
 ```sql
 MATCH (p:Person)-[:KNOWS]->(other:Person)
 WHERE p.name = 'Alice'
 RETURN other.name;
 ```
 ## HTTP/REST API
 ```bash
 curl http://localhost:9470/api/users
 curl -X POST http://localhost:9470/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "age": 30}'
 ```
 ## الخطوات التالية
 - [مرجع BaraQL](baraql.md)
 - [محركات التخزين](storage.md)
 - [نظرة عامة على البنية](architecture.md)
@@ -1,46 +0,0 @@
 # نظام المخطط
 يستخدم BaraDB تصميم schema-first مع وراثة النوع والهجرة التلقائية.
 ## تحديد الأنواع
 ```nim
 import barabadb/schema/schema
 var s = newSchema()
 let person = newType("Person")
 person.addProperty("name", "str", required = true)
 person.addProperty("age", "int32")
 s.addType("default", person)
 ```
 ## وراثة النوع
 ```nim
 let employee = newType("Employee")
 employee.setBases(@["Person"])
 employee.addProperty("department", "str")
 s.addType("default", employee)
 ```
 ## عمليات المخطط
 ### Diff
 ```nim
 let diff = s.diff(oldSchema, newSchema)
 ```
 ## أنواع الخصائص
 | النوع | الوصف |
 |-------|-------|
 | `str` | سلسلة |
 | `int32` | عدد صحيح 32 بت |
 | `int64` | عدد صحيح 64 بت |
 | `float32` | فاصلة عائمة 32 بت |
 | `float64` | فاصلة عائمة 64 بت |
 | `bool` | منطقي |
 | `datetime` | تاريخ/وقت |
 | `bytes` | بيانات ثنائية |
@@ -1,76 +0,0 @@
 # دليل الأمان
 ## تشفير TLS/SSL
 تدعم BaraDB TLS 1.3 لجميع البروتوكولات. إذا لم يتم توفير شهادة، ينشئ الخادم شهادة ذاتية التوقيع تلقائياً عند البدء.
 ### استخدام شهادات مخصصة
 ```bash
 BARADB_TLS_ENABLED=true \
 BARADB_CERT_FILE=/etc/baradb/server.crt \
 BARADB_KEY_FILE=/etc/baradb/server.key \
 ./build/baradadb
 ```
 ### إنشاء شهادة ذاتية التوقيع
 ```bash
 openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
  -days 365 -nodes -subj "/CN=localhost"
 ```
 ## المصادقة
 ### المصادقة المبنية على JWT
 تستخدم BaraDB JWT مع توقيع HMAC-SHA256.
 ### تمكين المصادقة
 ```bash
 BARADB_AUTH_ENABLED=true \
 BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
 ./build/baradadb
 ```
 ### التحكم في الوصول القائم على الأدوار
 | الدور | الأذونات |
 |-------|----------|
 | `admin` | وصول كامل |
 | `write` | قراءة + كتابة |
 | `read` | قراءة فقط |
 | `monitor` | المقاييس والصحة فقط |
 ## تحديد المعدل
 منع إساءة الاستخدام:
 ```nim
 var rl = newRateLimiter(
  rlaTokenBucket,
  globalRate = 10000,
  perClientRate = 1000,
  burstSize = 100
 )
 ```
 ## أمان الشبكة
 ### عنوان الربط
 ```bash
 BARADB_ADDRESS=0.0.0.0 ./build/baradadb
 ```
 ## قائمة التحقق الأمنية
 - [ ] تغيير سر JWT الافتراضي
 - [ ] تمكين TLS بشهادات صالحة
 - [ ] الربط بواجهات محددة
 - [ ] تمكين المصادقة في الإنتاج
 - [ ] تكوين تحديد المعدل
 - [ ] تمكين سجل التدقيق
 - [ ] تشفير البيانات في حالة السكون
 - [ ] تشغيل BaraDB كمستخدم غير root
@@ -1,67 +0,0 @@
 # محركات التخزين
 توفر BaraDB محركات تخزين متعددة محسنة لأنماط الوصول المختلفة.
 ## LSM-Tree (مفتاح-قيمة)
 محرك التخزين الأساسي المحسن للكتابة مع بنية log-only إلحاقية.
 ### الاستخدام
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.close()
 ```
 ### المكونات
 - **MemTable**: مخزن مؤقت مرتب في الذاكرة
 - **WAL**: سجل write-ahead للدائمة
 - **SSTable**: جداول السلاسل المرتبة على القرص
 - **Bloom Filter**: بنية احتمالية للبحث السلبي السريع
 - **الضغط**: استراتيجية ذات طبقات بحجم مع إدارة المستويات
 - **ذاكرة الصفحة**: ذاكرة مؤقتة LRU مع تتبع معدل الإصابة
 ## فهرس B-Tree
 فهرس مرتب للبحث بالنطاق والبحث النقطي.
 ### الاستخدام
 ```nim
 import barabadb/storage/btree
 var btree = newBTreeIndex[string, string]()
 btree.insert("key1", "value1")
 let values = btree.get("key1")
 let range = btree.scan("key_a", "key_z")
 ```
 ## Write-Ahead Log (WAL)
 يضمن دائمة عمليات الكتابة.
 ```nim
 import barabadb/storage/wal
 var wal = newWAL("./wal")
 wal.append("txn1", "SET key1 value1")
 wal.flush()
 ```
 ## Bloom Filter
 هيكل بيانات احتمالي للبحث السلبي السريع.
 ```nim
 import barabadb/storage/bloom
 var filter = newBloomFilter(10000, 0.01)
 filter.add("key1")
 if filter.mightContain("key1"):
  echo "ربما موجود"
 ```
@@ -1,47 +0,0 @@
 # المعاملات و MVCC
 MVCC (تحكم التزامن متعدد الإصدارات) مع عزل اللقطة واكتشاف الجمود.
 ## الاستخدام
 ```nim
 import barabadb/core/mvcc
 var tm = newTxnManager()
 let txn = tm.beginTxn()
 discard tm.write(txn, "key1", cast[seq[byte]]("value1"))
 discard tm.write(txn, "key2", cast[seq[byte]]("value2"))
 tm.savepoint(txn)
 discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
 discard tm.rollbackToSavepoint(txn)
 discard tm.commit(txn)
 ```
 ## عزل المعاملات
 تستخدم BaraDB **عزل اللقطة**:
 - القراء لا يحظرون الكتاب
 - الكتاب لا يحظرون القراء
 - كل معاملة ترى لقطة متسقة
 ## اكتشاف الجمود
 ```nim
 import barabadb/core/deadlock
 var detector = newDeadlockDetector()
 if detector.detectCycle(txn1, txn2):
  echo "تم اكتشاف الجمود!"
 ```
 ## التحقق الرسمي
 تم تحديد بروتوكول MVCC/Snapshot Isolation رسمياً في TLA+:
 ```bash
 cd formal-verification
 java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
 ```
@@ -1,81 +0,0 @@
 # دليل حل المشكلات
 ## مشاكل التثبيت
 ### Nim غير موجود
 ```bash
 curl https://nim-lang.org/choosenim/init.sh -sSf | sh
 ```
 ### خطأ تجميع SSL
 ```bash
 nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
 ```
 ### تبعيات مفقودة
 ```bash
 nimble install -d -y
 ```
 ## مشاكل وقت التشغيل
 ### المنفذ قيد الاستخدام
 ```bash
 BARADB_PORT=5433 ./build/baradadb
 ```
 ### تم رفض الإذن
 ```bash
 mkdir -p ./data
 chmod 755 ./data
 ```
 ### ذاكرة غير كافية
 ```bash
 BARADB_MEMTABLE_SIZE_MB=32 \
 BARADB_CACHE_SIZE_MB=128 \
 ./build/baradadb
 ```
 ## مشاكل الاستعلام
 ### خطأ في الصياغة
 ```sql
 SELECT name, age FROM users WHERE age > 18;
 ```
 ### الجدول غير موجود
 ```sql
 CREATE TYPE User { name: str, age: int32 };
 ```
 ## مشاكل الاتصال
 ### تم رفض الاتصال
 ```bash
 ./build/baradadb
 sudo ufw allow 9472
 ```
 ## مشاكل الأداء
 ### استعلامات بطيئة
 1. إضافة فهارس: `CREATE INDEX idx_users_name ON users(name);`
 2. استخدام LIMIT
 3. زيادة ذاكرة التخزين المؤقت: `BARADB_CACHE_SIZE_MB=1024`
 ## وضع التصحيح
 ```bash
 BARADB_LOG_LEVEL=debug ./build/baradadb
 ```
@@ -1,47 +0,0 @@
 # الدوال المحددة من المستخدم
 توسيع BaraQL بالدوال المخصصة.
 ## الاستخدام
 ```nim
 import barabadb/query/udf
 var reg = newUDFRegistry()
 reg.registerStdlib()
 reg.register("greet", @[UDFParam(name: "name", typeName: "str")],
  "str", proc(args: seq[Value]): Value =
    return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!"))
 ```
 ## دوال المكتبة القياسية
 | الدالة | الوصف | مثال |
 |--------|-------|------|
 | `abs(n)` | القيمة المطلقة | `abs(-5)` → 5 |
 | `sqrt(n)` | الجذر التربيعي | `sqrt(16)` → 4 |
 | `pow(n, e)` | الأس | `pow(2, 3)` → 8 |
 | `lower(s)` | حروف صغيرة | `lower('ABC')` → 'abc' |
 | `upper(s)` | حروف كبيرة | `upper('abc')` → 'ABC' |
 | `len(s)` | الطول | `len('hello')` → 5 |
 | `trim(s)` | إزالة المسافات | `trim(' hello ')` → 'hello' |
 ## تسجيل الدالة
 ```nim
 reg.register(
  name: "my_function",
  params: @[UDFParam(name: "arg1", typeName: "str")],
  returnType: "str",
  body: proc(args: seq[Value]): Value =
    result = Value(kind: vkString, strVal: "")
 )
 ```
 ## استخدام UDF في الاستعلامات
 ```sql
 SELECT greet(name) FROM users;
 ```
@@ -1,65 +0,0 @@
 # محرك البحث المتجهي
 فهارس HNSW و IVF-PQ للبحث عن التشابه.
 ## الاستخدام
 ```nim
 import barabadb/vector/engine
 var idx = newHNSWIndex(dimensions = 128)
 idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable)
 let results = idx.search(queryVector, k = 10)
 ```
 ## أنواع الفهارس
 ### HNSW
 رسم بياني Small World قابل للملاحة هرمي للبحث عن أقرب الجيران.
 ```nim
 var hnsw = newHNSWIndex(
  dimensions = 128,
  m = 16,
  efConstruction = 200,
  efSearch = 100
 )
 ```
 ### IVF-PQ
 فهرس ملف مقلوب مع تكميم المنتج.
 ```nim
 var ivfpq = newIVFPQIndex(
  dimensions = 128,
  numCentroids = 256,
  subQuantizers = 8
 )
 ```
 ## مقاييس المسافة
 | المقياس | الوصف |
 |---------|-------|
 | `cosine` | تشابه جيب التمام |
 | `euclidean` | مسافة L2 |
 | `dotproduct` | تشابه المنتج النقطي |
 | `manhattan` | مسافة L1 |
 ## التكميم
 ```nim
 let scalar = scalarQuantize(data, bits = 8)
 let pq = productQuantize(data, subVectors = 8, bits = 8)
 ```
 ## تسريع SIMD
 ```nim
 import barabadb/vector/simd
 let dist = simdCosineDistance(vec1, vec2)
 ```
@@ -2,6 +2,9 @@
 BaraDB предоставя няколко стратегии за backup — от пълни snapshot-ове до инкрементални и online consistent backups.
 > ⚠️ **Настройка с множество бази данни**
 > BaraDB поддържа множество бази данни (`CREATE DATABASE`). Всяка база има собствена изолирана data директория (напр. `data/databases/<име>/`). Командите за backup, repair, checkpoint и migration работят върху **една директория наведнъж**. Ако използвате множество бази, пускайте командите за всяка база отделно или архивирайте цялата `data/databases/` директория.
 ## Архитектура
 ```
@@ -17,6 +20,14 @@ BaraDB предоставя няколко стратегии за backup — о
 └─────────────────────────────────────────┘
 ```
 ## Backup Инструмент
 Backup инструментът е в `src/barabadb/core/backup.nim`. Компилирайте го преди употреба:
 ```bash
 nim c -o:build/backup src/barabadb/core/backup.nim
 ```
 ## SSTable Integrity (v3 CRC Footer)
 Всеки SSTable файл, записан от BaraDB, включва CRC32 footer:
@@ -37,24 +48,24 @@ BaraDB предоставя няколко стратегии за backup — о
 ```bash
 # Чрез Nim API
 import barabadb/storage/lsm
-let (ok, msg) = verifySSTable("data/sstables/1.sst")
+let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
 ```
-## Storage Repair (`baradb repair`)
+## Storage Repair (`baradadb repair`)
-При съмнение за повреда, пуснете repair инструмента:
+При съмнение за повреда, пуснете repair инструмента за конкретна база данни:
 ```bash
 # Dry run — само преглед
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 # Пълен ремонт — проверка, преместване на битите файлове, WAL replay
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 ```
 **Какво прави repair:**
 1. Сканира всички `sstables/*.sst` и проверява CRC
-2. Премества корумпираните SSTables в `data/corrupt/`
+2. Премества корумпираните SSTables в `<data-dir>/corrupt/`
 3. Пуска WAL replay за възстановяване на незаписани данни
 4. Докладва резултати
@@ -78,6 +89,8 @@ let (ok, msg) = verifySSTable("data/sstables/1.sst")
 - **Бързо стартиране** — зарежда от MANIFEST вместо scan на директория
 - **Откриване на orphans** — `checkStorageConsistency()` докладва излишни/липсващи файлове
 При настройка с множество бази данни, всяка база поддържа собствен независим MANIFEST в своята data директория.
 ## WAL Ротация
 Write-Ahead Log се ротира при достигане на 64MB:
@@ -99,7 +112,7 @@ wal/wal_archive/
 Checkpoint създава консистентна граница на storage без спиране на сървъра:
 ```bash
-./build/baradadb checkpoint --data-dir=./data
+./build/baradadb checkpoint --data-dir=./data/databases/default
 ```
 **Как работи:**
@@ -112,18 +125,20 @@ Freeze-ът отнема **< 1ms**; flush-ът продължава парале
 ## Backup Команди
 > Компилирайте backup инструмента първо: `nim c -o:build/backup src/barabadb/core/backup.nim`
 ### Пълен Backup (tar.gz)
 ```bash
-./build/backup backup --data-dir=./data --output=backup_$(date +%s).tar.gz
+./build/backup backup --data-dir=./data/databases/default --output=backup_$(date +%s).tar.gz
 ```
-Архивира цялата data директория.
+Архивира цялата data директория на посочената база данни.
 ### Инкрементален Backup
 ```bash
-./build/backup incremental --data-dir=./data --output=backup_inc_$(date +%s).tar.gz
+./build/backup incremental --data-dir=./data/databases/default --output=backup_inc_$(date +%s).tar.gz
 ```
 Включва само:
@@ -137,25 +152,25 @@ Freeze-ът отнема **< 1ms**; flush-ът продължава парале
 ### Online Consistent Backup
 ```bash
-./build/baradadb backup --online --output=backup_online_$(date +%s).tar.gz
+./build/backup backup --online --data-dir=./data/databases/default --output=backup_online_$(date +%s).tar.gz
 ```
 Еквивалентно на:
 1. `checkpoint`
 2. `incremental backup`
-**Безопасно за пускане, когато сървърът е спрян.** Ако сървърът работи, използвайте `backup incremental`.
+Безопасно за пускане докато сървърът работи. Checkpoint-ът създава консистентен snapshot, след което инкременталният backup го архивира.
 ## Миграция на SSTable Версии
-Ако имате legacy v1/v2 SSTables, мигрирайте ги към v3:
+Ако имате legacy v1/v2 SSTables, мигрирайте ги към v3 за всяка база данни:
 ```bash
 # Преглед
-./build/baradadb migrate --data-dir=./data --dry-run
+./build/baradadb migrate --data-dir=./data/databases/default --dry-run
 # Миграция
-./build/baradadb migrate --data-dir=./data
+./build/baradadb migrate --data-dir=./data/databases/default
 ```
 Миграцията пренаписва всеки legacy SSTable в текущия v3 формат (CRC footer) и обновява MANIFEST.
@@ -166,31 +181,35 @@ Freeze-ът отнема **< 1ms**; flush-ът продължава парале
 ```bash
 # Repair премества битите файлове и пуска WAL replay
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 # Проверка на консистентност
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 ```
-### Сценарий 2: Възстановяване от Backup
+### Сценарий 2: Възстановяване от Backup (Единична База)
 ```bash
 # Спиране на сървъра
-# Разархивиране на backup
+# Разархивиране на backup в директорията на базата
-tar -xzf backup_1234567890.tar.gz -C ./data
+tar -xzf backup_1234567890.tar.gz -C ./data/databases/default
 # Рестарт — LSMTree зарежда от MANIFEST
 ./build/baradadb
 ```
-### Сценарий 3: Пълна Загуба на Данни
+### Сценарий 3: Възстановяване на Всички Бази
 Ако сте архивирали цялото `data/databases/` дърво:
 ```bash
 # 1. Разархивиране на последния backup
 tar -xzf backup_latest.tar.gz -C ./data
-# 2. Repair за replay на наличния WAL
+# 2. Repair за всяка база за replay на наличния WAL
-./build/baradadb repair --data-dir=./data
+for db in ./data/databases/*/; do
  ./build/baradadb repair --data-dir="$db" --dry-run
 done
 # 3. Стартиране на сървъра
 ./build/baradadb
@@ -2,6 +2,9 @@
 BaraDB поддържа разпределено внедряване с Raft консенсус, шардиране, репликация и gossip протокол.
 > ⚠️ **Ограничение при множество бази данни**
 > Разпределените модули (Raft, шардиране и репликация) в момента работят само с **`default`** базата данни. Ако използвате множество бази (`CREATE DATABASE`, `USE DATABASE`), разпределените функции още не ги обхващат. Всяка база данни се нуждае от отделна кластър конфигурация.
 ## Raft Консенсус
 Leader election и log репликация:
@@ -6,12 +6,6 @@
 - [English](../en/)
 - [Български (Bulgarian)](../bg/)
 - [Deutsch (German)](../de/)
 - [Русский (Russian)](../ru/)
 - [فارسی (Farsi)](../fa/)
 - [中文 (Chinese)](../zh/)
 - [Türkçe (Turkish)](../tr/)
 - [العربية (Arabic)](../ar/)
 ---
@@ -61,4 +55,4 @@
 ---
-*За да добавите нов език, създайте нова папка в `docs/` с езиковия код (напр. `docs/de/`).*
+*За да добавите нов език, създайте нова папка в `docs/` с езиковия код.*
@@ -26,6 +26,32 @@ s.addType("default", employee)
 let resolved = s.resolveInheritance(employee)
 ```
 ## SQL Миграции
 BaraDB поддържа SQL миграции, изпълнявани чрез BaraQL:
 ```sql
 -- Създаване на миграционна таблица
 CREATE MIGRATION TABLE my_migration;
 -- Прилагане на чакащи миграции
 MIGRATION UP;
 -- Rollback на последната миграция
 MIGRATION DOWN;
 -- Прилагане на всички чакащи миграции наведнъж
 MIGRATION UP BATCH;
 -- Dry-run за преглед на промените
 MIGRATION DRYRUN;
 -- Проверка на статуса
 MIGRATION STATUS;
 ```
 Миграционните скриптове се съхраняват вътре в LSMTree на всяка база данни и са изолирани per database. При използване на множество бази, изпълнете `USE DATABASE <име>` преди миграционните команди.
 ## Типове Полета
 | Тип | Описание |
@@ -6,12 +6,15 @@ BaraDB предоставя множество storage двигатели, оп
 Основният storage engine с write-оптимизирана append-only лог структура.
 > **Бележка за множество бази данни**
 > Всяка база данни има собствена изолирана директория (напр. `data/databases/<име>/`). Примерите по-долу използват `./data` като placeholder — заменете с реалния път до вашата база.
 ### Употреба
 ```nim
 import barabadb/storage/lsm
-var db = newLSMTree("./data")
+var db = newLSMTree("./data/databases/default")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.close()
@@ -1,74 +0,0 @@
 # Binärprotokoll API
 Niedrigstufiges Wire-Protokoll für hochperformante Client-Verbindungen.
 ## Nachrichtenformat
 Alle Nachrichten verwenden Big-Endian-Byte-Reihenfolge:
 ```
 ┌────────┬────────┬────────┬────────┬─────────────┐
 │ Length │  Type  │  Seq   │ Status │   Payload   │
 │ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │  N bytes    │
 └────────┴────────┴────────┴────────┴─────────────┘
 ```
 ## Nachrichtentypen
 ### Query (0x01)
 ```nim
 let msg = makeQueryMessage(seq, "SELECT * FROM users")
 ```
 ### Insert (0x02)
 ```nim
 let msg = makeInsertMessage(seq, "users", data)
 ```
 ### Update (0x03)
 ```nim
 let msg = makeUpdateMessage(seq, "users", updates, where)
 ```
 ### Delete (0x04)
 ```nim
 let msg = makeDeleteMessage(seq, "users", where)
 ```
 ### Ready (0x05)
 ```nim
 let msg = makeReadyMessage(seq)
 ```
 ### Error (0x06)
 ```nim
 let msg = makeErrorMessage(seq, code, message)
 ```
 ## Antwortcodes
 | Code | Name | Beschreibung |
 |------|------|-------------|
 | 0x00 | OK | Erfolg |
 | 0x01 | ERROR | Allgemeiner Fehler |
 | 0x02 | AUTH_REQUIRED | Authentifizierung erforderlich |
 | 0x03 | INVALID_QUERY | Abfragesyntaxfehler |
 | 0x04 | NOT_FOUND | Ressource nicht gefunden |
 ## Serialisierung
 ```nim
 import barabadb/protocol/wire
 # Wert serialisieren
 let bytes = serializeValue(Value(kind: vkString, strVal: "test"))
 # Wert deserialisieren
 let value = deserializeValue(bytes)
 ```
@@ -1,91 +0,0 @@
 # HTTP/REST API
 JSON-basierte REST API für Web-Anwendungen.
 ## Basis-URL
 ```
 http://localhost:9470/api
 ```
 ## Endpoints
 ### GET /api/users
 Alle Benutzer auflisten:
 ```bash
 curl http://localhost:9470/api/users
 ```
 Antwort:
 ```json
 [
  {"id": 1, "name": "Alice", "age": 30},
  {"id": 2, "name": "Bob", "age": 25}
 ]
 ```
 ### GET /api/users/:id
 Benutzer nach ID abrufen:
 ```bash
 curl http://localhost:9470/api/users/1
 ```
 ### POST /api/users
 Benutzer erstellen:
 ```bash
 curl -X POST http://localhost:9470/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Charlie", "age": 35}'
 ```
 ### PUT /api/users/:id
 Benutzer aktualisieren:
 ```bash
 curl -X PUT http://localhost:9470/api/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "age": 31}'
 ```
 ### DELETE /api/users/:id
 Benutzer löschen:
 ```bash
 curl -X DELETE http://localhost:9470/api/users/1
 ```
 ## Query-Endpoint
 BaraQL-Abfragen über HTTP ausführen:
 ```bash
 curl -X POST http://localhost:9470/api/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users WHERE age > 18"}'
 ```
 ## Fehlerantwort
 ```json
 {
  "error": {
    "code": "INVALID_QUERY",
    "message": "Syntax error at line 1"
  }
 }
 ```
 ## Authentifizierung
 ```bash
 curl -H "Authorization: Bearer <token>" \
  http://localhost:9470/api/users
 ```
@@ -1,120 +0,0 @@
 # WebSocket API
 Vollduplex-Streaming für Echtzeit-Datenfeeds und Push-Benachrichtigungen.
 ## Verbindung
 ```
 ws://localhost:9471/ws
 ```
 ## Client-Beispiel
 ```javascript
 const ws = new WebSocket('ws://localhost:9471/ws');
 ws.onopen = () => {
  console.log('Connected');
  ws.send(JSON.stringify({
    type: 'query',
    sql: 'SELECT * FROM users'
  }));
 };
 ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
 };
 ```
 ## Nachrichtenformat
 ```json
 {
  "type": "query",
  "id": "uuid",
  "sql": "SELECT * FROM users"
 }
 ```
 ## Nachrichtentypen
 ### Query-Anfrage
 ```json
 {
  "type": "query",
  "id": "123",
  "sql": "SELECT * FROM users"
 }
 ```
 ### Query-Antwort
 ```json
 {
  "type": "result",
  "id": "123",
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
 }
 ```
 ### Fehlerantwort
 ```json
 {
  "type": "error",
  "id": "123",
  "error": {
    "code": "INVALID_QUERY",
    "message": "Syntax error"
  }
 }
 ```
 ### Subscription
 Änderungen abonnieren:
 ```json
 {
  "type": "subscribe",
  "id": "sub1",
  "table": "users"
 }
 ```
 ### Push-Benachrichtigung
 Server-Push:
 ```json
 {
  "type": "push",
  "table": "users",
  "action": "insert",
  "data": {"id": 3, "name": "Charlie"}
 }
 ```
 ## JavaScript-Client
 ```javascript
 class BaraDBClient {
  constructor(url) {
    this.ws = new WebSocket(url);
    this.pending = new Map();
  }
  query(sql) {
    return new Promise((resolve, reject) => {
      const id = crypto.randomUUID();
      this.pending.set(id, { resolve, reject });
      this.ws.send(JSON.stringify({ type: 'query', id, sql }));
    });
  }
 }
 ```
@@ -1,152 +0,0 @@
 # BaraDB Architektur
 ## Überblick
 BaraDB ist eine **multimodale Datenbank-Engine** in Nim, die Document (KV), Graph, Vector, Columnar und Full-Text Search Speicherung in einer einzigen Engine mit einer einheitlichen Abfragesprache namens **BaraQL** kombiniert.
 ## Schichten-Architektur
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ 1. CLIENT LAYER                                          │
 │    Binary Protocol │ HTTP/REST │ WebSocket │ Embedded    │
 ├─────────────────────────────────────────────────────────┤
 │ 2. QUERY LAYER (BaraQL)                                  │
 │    Lexer → Parser → AST → IR → Optimizer → Codegen      │
 ├─────────────────────────────────────────────────────────┤
 │ 3. EXECUTION ENGINE                                      │
 │    Document │ Graph │ Vector │ Columnar │ FTS            │
 ├─────────────────────────────────────────────────────────┤
 │ 4. STORAGE                                               │
 │    LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache  │
 ├─────────────────────────────────────────────────────────┤
 │ 5. DISTRIBUTED                                           │
 │    Raft Consensus │ Sharding │ Replication │ Gossip      │
 └─────────────────────────────────────────────────────────┘
 ```
 ## Schicht 1: Client-Layer
 Mehrere Kommunikationsprotokolle:
 - **Binärprotokoll** (`protocol/wire.nim`): Effizientes Big-Endian Binärprotokoll mit 16 Nachrichtentypen
 - **HTTP/REST** (`core/httpserver.nim`): JSON-basierte REST API mit Multi-Threading
 - **WebSocket** (`core/websocket.nim`): Vollduplex-Streaming
 - **Embedded** (`storage/lsm.nim`): Direkter In-Process-Zugriff
 ### Verbindungsmanagement
 - **Connection Pool** (`protocol/pool.nim`): Min/Max Verbindungslimits mit Idle-Timeout
 - **Rate Limiting** (`protocol/ratelimit.nim`): Token-Bucket globale und per-Client Limits
 - **Authentifizierung** (`protocol/auth.nim`): JWT mit HMAC-SHA256 und rollenbasierter Zugriff
 - **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 mit auto-generierten Zertifikaten
 ## Schicht 2: Query-Layer (BaraQL)
 Die BaraQL-Pipeline:
 1. **Lexer** (`query/lexer.nim`): Tokenisiert Eingabe in 80+ Tokentypen
 2. **Parser** (`query/parser.nim`): Rekursiver Descent-Parser produziert AST
 3. **AST** (`query/ast.nim`): 300+ Zeilen mit 25+ Knotenarten
 4. **IR** (`query/ir.nim`): Intermediate Representation für Ausführungspläne
 5. **Optimizer** (`query/adaptive.nim`): Adaptive Cross-Modal Query-Optimierung
 6. **Codegen** (`query/codegen.nim`): Übersetzt IR zu Speicheroperationen
 7. **Executor** (`query/executor.nim`): Führt Pläne mit Parallelisierung aus
 ### Cross-Modal Planning
 Der Optimizer (`query/adaptive.nim`) bestimmt die Ausführungsreihenfolge über Engines:
 ```
 1. Selektivität für jedes Prädikat schätzen
 2. Selektivstes Prädikat zuerst an seine Engine pushen
 3. Bloom-Filter für KV-Lookups verwenden
 4. Unabhängige Zweige parallelisieren
 5. Results streamen um Materialisierung zu vermeiden
 ```
 ## Schicht 3: Execution Engine
 ### Document/KV Engine
 - **LSM-Tree** (`storage/lsm.nim`): Write-optimierte Speicherung mit MemTable, WAL, SSTables
 - **B-Tree Index** (`storage/btree.nim`): Geordneter Index für Bereichsscans mit COW
 ### Vector Engine (`vector/`)
 - **HNSW Index** (`vector/engine.nim`): Hierarchical Navigable Small World Graph
 - **IVF-PQ Index** (`vector/engine.nim`): Inverted File Index mit Product Quantization
 - **SIMD Operations** (`vector/simd.nim`): AVX2-optimierte Distanzberechnungen
 - **Quantization** (`vector/quant.nim`): Scalar, Product und Binary Quantization
 ### Graph Engine (`graph/`)
 - **Adjacency List** (`graph/engine.nim`): Kanten-gewichteter gerichteter Graph
 - **Algorithmen** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
 - **Community Detection** (`graph/community.nim`): Louvain-Algorithmus
 - **Pattern Matching** (`graph/community.nim`): Subgraph-Isomorphie
 - **Cypher Parser** (`graph/cypher.nim`): Cypher-ähnliche Graph-Abfragen
 ### Full-Text Search (`fts/`)
 - **Inverted Index** (`fts/engine.nim`): Term-Document Index
 - **Ranking** (`fts/engine.nim`): BM25 und TF-IDF Scoring
 - **Fuzzy Search** (`fts/engine.nim`): Levenshtein-Distanz-Matching
 - **Multi-Language** (`fts/multilang.nim`): Tokenizer für EN, BG, DE, FR, RU
 ### Columnar Engine (`core/columnar.nim`)
 - Perspalten-Speicherung für analytische Abfragen
 - RLE und Dictionary-Kodierung
 - SIMD-beschleunigte Aggregatfunktionen
 ## Schicht 4: Storage
 - **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom-Filter, Compaction
 - **Page Cache** (`storage/compaction.nim`): LRU-Cache mit Trefferraten-Verfolgung
 - **Memory-mapped I/O** (`storage/mmap.nim`): mmap-basierter Dateizugriff
 - **Recovery** (`storage/recovery.nim`): WAL-Replay und Crash-Recovery
 ### Write Path
 ```
 Client → Protocol → Auth → Parser → AST → IR → Codegen
  → StorageOp → MVCC Txn → WAL Write → MemTable → Commit
 ```
 ### Read Path
 ```
 Client → Protocol → Auth → Parser → AST → IR → Codegen
  → StorageOp → MVCC Snapshot → MemTable → SSTable → Result
 ```
 ## Schicht 5: Distributed
 - **Raft Consensus** (`core/raft.nim`): Leader Election, Log-Replikation
 - **Sharding** (`core/sharding.nim`): Hash, Range und Consistent Hashing
 - **Replication** (`core/replication.nim`): Sync, Async, Semi-Sync Modi
 - **Gossip Protocol** (`core/gossip.nim`): SWIM-ähnliches Membership-Management
 - **Distributed Transactions** (`core/disttxn.nim`): Two-Phase Commit
 ## Wichtige Designentscheidungen
 1. **Reines Nim**: Keine Cython, Python oder Rust Abhängigkeiten
 2. **Unified Storage**: Eine Engine-handelt KV, Graph, Vector, FTS und Columnar
 3. **Embedded Mode**: Kann als Bibliothek oder Server laufen
 4. **Binärprotokoll**: Custom effizientes Wire-Protokoll
 5. **MVCC**: Multi-Version Concurrency Control
 6. **Schema-First**: Stark typisiertes Schema-System mit Vererbung
 7. **Cross-Modal**: Einheitliche Abfragesprache über alle Datenmodelle
 8. **Formally Verified**: Kern-Algorithmen in TLA+ spezifiziert und mit TLC model-gecheckt
 ## Modulstatistiken
 | Kategorie | Module | Codezeilen | Zweck |
 |----------|--------|------------|-------|
 | Core | 16 | ~4,200 | Server, Protokolle, Transaktionen, Distributed |
 | Storage | 7 | ~3,100 | LSM, B-Tree, WAL, Bloom, Compaction, mmap |
 | Query | 7 | ~2,800 | Lexer, Parser, AST, IR, Optimizer, Codegen, Executor |
 | Vector | 3 | ~1,200 | HNSW, IVF-PQ, Quantization, SIMD |
 | Graph | 3 | ~1,000 | Adjacency List, Algorithmen, Community Detection |
 | FTS | 2 | ~900 | Inverted Index, BM25, Fuzzy, Multi-Language |
 | Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, Pool, Auth, Rate Limit, SSL |
 | Schema | 1 | ~600 | Typen, Links, Vererbung, Migrationen |
 | Client | 2 | ~800 | Nim Binary Client, File Helpers |
 | CLI | 1 | ~400 | Interaktive BaraQL Shell |
 | **Total** | **49** | **~14,100** | |
@@ -1,199 +0,0 @@
 # Backup & Wiederherstellung
 ## Online Snapshots
 BaraDB unterstützt Online-Snapshots ohne Server-Stopp. Der Snapshot erfasst eine
 konsistente Point-in-Time-Ansicht mittels MVCC.
 ### Snapshot erstellen
 ```nim
 import barabadb/core/backup
 var bm = newBackupManager()
 bm.createSnapshot("/backup/baradb_2025-01-15")
 ```
 ### Via CLI
 ```bash
 ./build/baradadb --snapshot --output=/backup/snapshot.db
 ```
 ### Via HTTP API
 ```bash
 curl -X POST http://localhost:9470/api/backup \
  -H "Content-Type: application/json" \
  -d '{"destination": "/backup/snapshot.db"}'
 ```
 ### Automatisierte Backups
 Cron für geplante Backups verwenden:
 ```bash
 # Daily snapshot at 2 AM
 0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
 # Letzte 7 Tage behalten
 find /backup -name "baradb_*.db" -mtime +7 -delete
 ```
 ## Point-in-Time Recovery (PITR)
 BaraDB verwendet das Write-Ahead Log (WAL) für Point-in-Time Recovery.
 ### WAL-Archivierung
 Kontinuierliche WAL-Archivierung aktivieren:
 ```bash
 BARADB_WAL_ARCHIVE_DIR=/backup/wal \
 BARADB_WAL_ARCHIVE_INTERVAL_MS=60000 \
 ./build/baradadb
 ```
 ### Wiederherstellung von Checkpoint + WAL
 ```bash
 # Von Snapshot wiederherstellen
 ./build/baradadb --recover \
  --checkpoint=/backup/snapshot.db \
  --wal-dir=/backup/wal
 # Wiederherstellung zu spezifischem LSN
 ./build/baradadb --recover \
  --checkpoint=/backup/snapshot.db \
  --wal-dir=/backup/wal \
  --target-lsn=15420
 # Wiederherstellung zu spezifischer Zeit
 ./build/baradadb --recover \
  --checkpoint=/backup/snapshot.db \
  --wal-dir=/backup/wal \
  --target-time="2025-01-15T10:30:00Z"
 ```
 ### Wiederherstellung via SQL
 Sie können auch direkt via BaraQL wiederherstellen:
 ```sql
 RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
 ```
 ### Inkrementelle Backups
 Inkrementelle Backups kopieren nur geänderte SSTables:
 ```bash
 ./build/baradadb --backup-incremental \
  --last-backup=/backup/previous \
  --output=/backup/incremental_$(date +%Y%m%d)
 ```
 ## Replikation als Backup
 Für kontinuierlichen Schutz, Streaming-Replikation verwenden:
 ### Primary
 ```bash
 BARADB_REPLICATION_ENABLED=true \
 BARADB_REPLICATION_MODE=async \
 ./build/baradadb
 ```
 ### Replica
 ```bash
 BARADB_REPLICATION_ENABLED=true \
 BARADB_REPLICATION_PRIMARY=primary:9472 \
 ./build/baradadb
 ```
 ## Disaster Recovery
 ### Wiederherstellungsverfahren
 #### Szenario 1: Einzelne Dateikorruption
 ```bash
 # Korrupte SSTable aus Logs identifizieren
 # Spezifische SSTable aus Backup wiederherstellen
 cp /backup/sstables/000012.sst ./data/sstables/
 # Index neu aufbauen
 ./build/baradadb --rebuild-index
 ```
 #### Szenario 2: Kompletter Datenverlust
 ```bash
 # 1. Neuesten Snapshot wiederherstellen
 cp /backup/snapshot.db ./data/
 # 2. WAL replay
 ./build/baradadb --recover --wal-dir=/backup/wal
 # 3. Verifizieren
 curl http://localhost:9470/health
 ```
 #### Szenario 3: Cluster-Knoten-Ausfall
 ```bash
 # Für Raft-Cluster, einfach neuen Knoten starten
 BARADB_RAFT_NODE_ID=newnode \
 BARADB_RAFT_PEERS=node1:9001,node2:9001 \
 ./build/baradadb
 # Der neue Knoten wird über Raft-Log-Replikation aufholen
 ```
 ## Backup-Verifizierung
 Backups immer verifizieren:
 ```bash
 # In temporäres Verzeichnis wiederherstellen
 ./build/baradadb --recover \
  --checkpoint=/backup/snapshot.db \
  --data-dir=/tmp/verify_data
 # Konsistenzprüfung ausführen
 curl http://localhost:9470/api/admin/check
 ```
 ## Speicheranforderungen
 | Backup-Typ | Größe | Häufigkeit | Aufbewahrung |
 |-------------|------|-----------|--------------|
 | Full snapshot | ~1× Datengröße | Täglich | 7 Tage |
 | Inkrementell | ~0.1× Datengröße | Stündlich | 24 Stunden |
 | WAL-Archiv | ~0.05× Datengröße / Tag | Kontinuierlich | 30 Tage |
 ## Best Practices
 1. **Restores regelmäßig testen** — Ein Backup das Sie nicht wiederherstellen können ist wertlos
 2. **Backups außerhalb speichern** — S3, GCS oder Azure Blob verwenden
 3. **Backups verschlüsseln** — `gpg` oder OS-Level-Verschlüsselung verwenden
 4. **Backup-Jobs überwachen** — Bei fehlgeschlagenen Backups alarmieren
 5. **RTO/RPO dokumentieren** — Ihre Wiederherstellungszeit und Punktziele kennen
 ### Cloud-Backup-Upload
 ```bash
 # Zu S3 hochladen
 aws s3 cp /backup/snapshot.db s3://my-bucket/baradb/
 # Zu GCS hochladen
 gsutil cp /backup/snapshot.db gs://my-bucket/baradb/
 # Zu Azure hochladen
 az storage blob upload \
  --container-name backups \
  --file /backup/snapshot.db \
  --name baradb/snapshot.db
 ```
@@ -1,114 +0,0 @@
 # BaraQL — Abfragesprache-Referenz
 BaraQL ist eine SQL-kompatible Abfragesprache mit Erweiterungen für Graph-, Vektor- und Dokumentoperationen.
 ## Datentypen
 | Typ | Beschreibung | Beispiel |
 |------|-------------|---------|
 | `null` | Nullwert | `null` |
 | `bool` | Boolean | `true`, `false` |
 | `int64` | 64-bit Ganzzahl | `42` |
 | `float64` | 64-bit Fließkomma | `3.14` |
 | `str` | UTF-8 String | `'hello'` |
 | `vector(n)` | Float32 Vektor | `VECTOR(768)` |
 | `json` | JSON-Dokument | `{"key": "value"}` |
 ## Grundlegende Abfragen
 ```sql
 SELECT * FROM users;
 SELECT name, age FROM users WHERE age > 18;
 SELECT * FROM users ORDER BY age DESC LIMIT 10;
 ```
 ## Vektor-Operationen
 ```sql
 -- Distanzberechnungen
 SELECT cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
 SELECT embedding <-> '[0.1, 0.2, 0.3]' AS dist FROM items;
 -- Hybride Suche
 SELECT hybrid_search('query', embedding, content, 10) AS result;
 ```
 ## Graph-Operationen
 ```sql
 CREATE GRAPH social;
 DROP GRAPH social;
 -- Traversierung
 SELECT * FROM GRAPH_TABLE(social MATCH (n)-[r]->(m)
    ALGORITHM bfs START 1
    COLUMNS (id, node_label));
 -- PageRank
 SELECT * FROM GRAPH_TABLE(social ALGORITHM pagerank
    COLUMNS (id, node_label, rank));
 -- Community Detection
 SELECT * FROM GRAPH_TABLE(social ALGORITHM community
    COLUMNS (id, node_label, community));
 ```
 ## AI-Funktionen
 ```sql
 -- Text in Chunks zerlegen
 SELECT chunk('Langer Text...', 1024, 128) AS result;
 -- Embedding generieren
 SELECT embed_text('Suchtext') AS result;
 -- Natural Language → SQL
 SELECT nl_to_sql('Zeige alle Benutzer über 25', 'users') AS result;
 -- Schema-Prompt für LLM
 SELECT schema_prompt('users') AS result;
 -- Cypher-Übersetzung
 SELECT cypher('MATCH (a)-[r]->(b) RETURN a.node_label') AS result;
 -- Knotenähnlichkeit
 SELECT similarity_nodes('social', 'jaccard') AS result;
 -- Graph-Embeddings
 SELECT node2vec_embed('social', 64) AS result;
 ```
 ## Joins
 ```sql
 SELECT u.name, o.amount
 FROM users u
 INNER JOIN orders o ON u.id = o.user_id;
 ```
 ## Aggregation
 ```sql
 SELECT department, COUNT(*), AVG(salary)
 FROM employees
 GROUP BY department
 HAVING COUNT(*) > 5;
 ```
 ## Index-Erstellung
 ```sql
 CREATE INDEX idx_name ON users(name) USING btree;
 CREATE INDEX idx_vec ON docs(embedding) USING hnsw;
 CREATE INDEX idx_fts ON docs(content) USING fts;
 ```
 ## Multi-Tenant / RLS
 ```sql
 CREATE POLICY tenant_policy ON orders
 FOR ALL USING (tenant_id = current_setting('app.tenant_id'));
 SET app.tenant_id = 'company-a';
 SELECT * FROM orders;  -- Automatisch gefiltert
 ```
@@ -1,38 +0,0 @@
 # B-Tree Index
 Geordnete Indexstruktur für effiziente Bereichsabfragen und Point-Lookups.
 ## Verwendung
 ```nim
 import barabadb/storage/btree
 var btree = newBTreeIndex[string, string]()
 # Einfügen
 btree.insert("key1", "value1")
 btree.insert("key2", "value2")
 # Point-Lookup
 let values = btree.get("key1")
 # Bereichsabfrage
 let range = btree.scan("key_a", "key_z")
 # Löschen
 btree.delete("key1")
 ```
 ## Funktionen
 - Geordnete Schlüssel-Wert-Speicherung
 - Bereichsabfragen (BETWEEN, >, <, >=, <=)
 - Präfix-Scans
 - Konfigurierbare Seitengröße
 - Iterator-Unterstützung
 ## Anwendungsfälle
 - Primärschlüssel-Indizes
 - Sekundärindizes für häufig abgefragte Spalten
 - Bereichspartitionierte Daten
@@ -1,247 +0,0 @@
 # Changelog
 Alle bemerkenswerten Änderungen an BaraDB werden in dieser Datei dokumentiert.
 ## [Unreleased] — AI-Native Platform
 ### Hinzugefügt
 - **MCP Server (Model Context Protocol)** — STDIO JSON-RPC 2.0 Server mit 3 AI-Tools:
  - `query` — SQL-Ausführung mit parametrisierten Abfragen + Multi-Tenant Session-Variablen
  - `vector_search` — Semantische HNSW Vektor-suche mit Tenant-Isolation
  - `schema_inspect` — Tabellen-/Spalten-/Index-/RLS-Policy-Exploration
  - Standalone Binary: `build/baramcp`
 - **Graph Engine Tiefe Integration** — `CREATE GRAPH` / `DROP GRAPH` DDL mit nativer Adjacency-List-Speicherung
  - `GRAPH_TABLE()` SQL-Funktion mit 7 Algorithmen: BFS, DFS, PageRank, ShortestPath, Dijkstra, Louvain, Community
  - INSERT in `_nodes`/`_edges` Tabellen synchronisiert automatisch mit nativen Graph-Objekten
  - Optional `MATCH`, `ALGORITHM`, `START`, `END`, `MAXDEPTH` in GRAPH_TABLE Syntax
 - **Chunking + Embedding Pipeline** — Serverseitige AI-Datenverarbeitung:
  - `chunk()` SQL-Funktion — Text-Splitting mit konfigurierbarer Größe/Überlappung
  - `embed_text()` SQL-Funktion — ruft externe Embedding-API auf (OpenAI/Ollama kompatibel)
  - Auto-Embedding bei INSERT — wenn VECTOR-Spalte null ist, generiert aus TEXT-Spalte
  - Konfigurierbar via Env-Vars: `BARADB_EMBED_ENDPOINT`, `BARADB_EMBED_MODEL`, `BARADB_EMBED_API_KEY`
 - **LangChain ChatMessageHistory** — Python `BaraDBChatHistory` Klasse:
  - Speichert Konversations-Threads in relationaler Tabelle mit RLS
  - Multi-Tenant Isolation via `tenant_id` + `user_id`
 - **RAG Pipeline Beispiel** — End-to-End Python Script (`examples/rag_pipeline.py`):
  - PDF/text Ingestion → chunking → embedding → BaraDB Speicherung → hybrid search → LLM Generierung
  - Unterstützt OpenAI und Ollama APIs
 - **AI Agents & NL→SQL** — Serverseitige LLM-Integration:
  - `nl_to_sql()` SQL-Funktion — natürliche Sprache → SQL Generierung
  - `schema_prompt()` — generiert DDL + Beispieldaten für LLM-Kontext
  - Abfrage-Validierungsschicht — Sandbox-Ausführung mit LIMIT 0 + EXPLAIN
  - Selbst-Korrektur-Schleife — Fehlerfeedback an LLM zur Korrektur
  - Konfigurierbar via Env-Vars: `BARADB_LLM_ENDPOINT`, `BARADB_LLM_MODEL`, `BARADB_LLM_API_KEY`
 - **Graph Similarity & Embeddings**:
  - `similarity_nodes()` — Jaccard/Adamic-Adar Ähnlichkeit zwischen Knotenpaaren
  - `node2vec_embed()` — Random-walk basierte Graph Embeddings
 - **Cypher Compatibility Layer**:
  - `cypher()` SQL-Funktion — übersetzt `MATCH (a)-[r]->(b) RETURN ...` zu GRAPH_TABLE
  - Automatische Cypher → BaraQL Konvertierung
 - **German Documentation** — Vollständige Dokumentation auf Deutsch (`docs/de/`)
 ### Geändert
 - Graph Executor upgraded von Stub zu echtem BFS/DFS/PageRank/Dijkstra/Louvain
 - ExecutionContext erweitert mit `graphs`, `embedder`, `llmClient` Feldern
 - Graph Engine erweitert mit `addNodeWithId`, `addEdgeWithId`, Jaccard, Adamic-Adar, node2vec
 ## [1.1.0] — 2026-05-13
 ### Hinzugefügt
 - **Client SDKs v1.1.6** — Vollständige Clients für alle Sprachen:
  - JavaScript: TypeScript Definitionen, package.json, Beispiele, Unit & Integration Tests
  - Python: Umstrukturiert als proper Package (`baradb/` mit `__init__.py` und `core.py`), pyproject.toml, Beispiele, Tests
  - Nim: Beispiele, Integration Tests, README
  - Rust: Beispiele, Integration Tests, verbessertes Cargo.toml
 - **SCRAM-SHA-256 Authentifizierung** — RFC 7677 konforme Authentifizierung mit PBKDF2 + HMAC + SHA-256 + Nonce/Salt Generierung
 - **HTTP SCRAM Endpoints** — `/auth/scram/start` + `/auth/scram/finish` im HTTP Server
 - **Docker Compose Test Configuration** — `docker-compose.test.yml` für Test-Umgebungen
 - **CI/CD Clients Pipeline** — `.github/workflows/clients-ci.yml` für automatisierte Client-Tests
 ### Behoben
 - **Query Executor** — Unärer Minus (`irNeg`) funktioniert jetzt korrekt in SELECT und WHERE Klauseln
 - **Distributed Transactions** — Rollback nach Commit-Versuch verletzt nicht mehr Atomicity
 - **Sharding** — Datenmigrations-Protokoll mit TCP + `scanAll` auf LSM
 - **Raft** — Majority-Berechnung für gerade Knotenanzahl korrigiert
 - **MVCC** — Abgebrochene Transaktionen werden nicht mehr sichtbar
 - **LSM-Tree** — Datenverlust bei immutable memtable overwrite behoben; SSTable lookup sorting behoben
 - **Auth** — JWT-Signatur auf HMAC-SHA256 geändert (nicht mehr trivial fälschbar); Token-Ablauf (`exp`/`nbf`/`iat`) wird jetzt validiert; Signatur-Vergleich ist jetzt constant-time
 - **Recovery** — `summary()` mutiert die Datenbank nicht mehr
 - **Wire Protocol** — 64MB Limit + Bounds Checking + Max Depth um OOM/DoS zu verhindern
 - **SQL Injection** — `exprToSql` escaped jetzt Single Quotes
 - **ReDoS** — `irLike`/`irILike` escaped jetzt Regex Metacharacters
 - **Graph** — `addEdge` prüft jetzt Knotenexistenz
 - **Vector** — Dimension mismatch Validierung + HNSW Locking
 - **FTS** — UTF-8 Tokenisierung verwendet jetzt runes statt bytes
 - **Build** — `nim.cfg` fügt `-d:ssl` hinzu damit `nimble build` ohne Flags funktioniert; `--threads:on` zu allen CI Commands hinzugefügt
 ### Geändert
 - **Version auf 1.1.0 erhöht** über alle Komponenten
 - **README** — Version Badge aktualisiert; alle Feature-Tabellen referenzieren jetzt v1.1.6
 - **TLA+ Formal Verification** — `crossmodal.tla`, `backup.tla`, `recovery.tla` hinzugefügt; Symmetrie-Reduktion in allen 9 Specs
 - **Clean build** — 0 Compiler Warnings auf Nim 2.2.10
 ## [0.1.0] — 2025-01-15
 ### Hinzugefügt
 - **Core Storage Engines**
  - LSM-Tree mit MemTable, WAL, SSTables und size-tiered Compaction
  - B-Tree geordneter Index mit Range Scans und MVCC Copy-on-Write
  - Bloom Filter für effizientes SSTable Skip
  - Memory-mapped I/O für SSTable Reads
  - LRU Page Cache mit Hit-Rate Tracking
 - **Query Engine (BaraQL)**
  - SQL-kompatibler Lexer mit 80+ Tokentypen
  - Rekursiver Descent Parser produziert AST mit 25+ Knotenarten
  - Intermediate Representation (IR) für Ausführungspläne
  - Code Generator übersetzt IR zu Speicheroperationen
  - Adaptiver Query Optimizer mit Cross-Modal Planning
  - Query Executor mit Parallelisierung
 - **BaraQL Language Features**
  - SELECT, INSERT, UPDATE, DELETE
  - WHERE, ORDER BY, LIMIT, OFFSET
  - GROUP BY, HAVING, Aggregatfunktionen (count, sum, avg, min, max)
  - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN
  - CTEs (Common Table Expressions) mit WITH
  - Subqueries (EXISTS, IN, correlated)
  - CASE Expressions
  - UNION, INTERSECT, EXCEPT
  - Schema Definition: CREATE TYPE, DROP TYPE
 - **Vector Engine**
  - HNSW Index für Approximate Nearest Neighbor Search
  - IVF-PQ Index für Large-Scale Vector Search
  - SIMD-optimierte Distanzfunktionen (cosine, L2, dot product, Manhattan)
  - Quantization: scalar 8-bit/4-bit, product quantization, binary
  - Metadata Filtering während Vector Search
 - **Graph Engine**
  - Adjacency List Speicherung für gerichtete, kanten-gewichtete Graphen
  - BFS und DFS Traversierung
  - Dijkstra kürzester Pfad
  - PageRank Knotenwichtigkeit
  - Louvain Community Detection
  - Subgraph Pattern Matching
  - Cypher-ähnlicher Graph Query Parser
 - **Full-Text Search**
  - Inverted Index mit Term-Document Mapping
  - BM25 Ranking-Algorithmus
  - TF-IDF Scoring
  - Fuzzy Search mit Levenshtein Distanz
  - Wildcard/regex Search
  - Multi-Language Tokenizer (English, Bulgarian, German, French, Russian)
 - **Columnar Storage**
  - Perspalten-Speicherung für analytische Abfragen
  - RLE (Run-Length Encoding) Kompression
  - Dictionary Encoding für Low-Cardinality Spalten
  - SIMD-beschleunigte Aggregatfunktionen
 - **Transactions**
  - MVCC (Multi-Version Concurrency Control) mit Snapshot Isolation
  - Deadlock-Erkennung via Wait-for Graph
  - Write-Ahead Log für Dauerhaftigkeit
  - Savepoints und partielles Rollback
 - **Protocol Layer**
  - Binary Wire Protocol mit 16 Nachrichtentypen
  - HTTP/REST JSON API
  - WebSocket Streaming
  - Connection Pooling
  - JWT-basierte Authentifizierung
  - Token-bucket Rate Limiting
  - TLS/SSL mit auto-generierten Zertifikaten
 - **Schema System**
  - Starkes Typsystem mit 17 nativen Typen
  - Typvererbung mit Multi-Base Support
  - Property Links zwischen Typen
  - Schema Diffing und Migrationen
  - Computed Properties
 - **Distributed Systems**
  - Raft Consensus (Leader Election, Log Replikation)
  - Hash, Range und Consistent-Hash Sharding
  - Sync/async/semi-sync Replikation
  - Gossip Protocol für Membership Management
  - Two-Phase Commit für Distributed Transactions
 - **Cross-Modal Queries**
  - Vereinheitlichte Abfragesprache über alle Speicher-Engines
  - Cross-Engine Predicate Pushdown
  - Optimierte Ausführungspläne für Multi-Modal Abfragen
 - **Backup & Recovery**
  - Online Snapshots ohne Ausfallzeit
  - Point-in-Time Recovery via WAL Replay
  - Inkrementelle Backups
 - **Client SDKs**
  - JavaScript/TypeScript Client mit Binary Protocol
  - Python Client mit Sync und Async APIs
  - Nim Embedded Mode und Client Library
  - Rust Client (async)
 - **Operations**
  - Interaktive CLI Shell (BaraQL REPL)
  - Strukturiertes Logging (JSON und Text Formate)
  - Prometheus-kompatible Metrics Endpoint
  - Health und Readiness Probes
  - CPU/memory Profiling Endpoints
 - **Docker Support**
  - Multi-stage Dockerfile (Alpine Linux)
  - Docker Compose Konfiguration
  - Health Checks
 ### Performance
 - LSM-Tree: 580K writes/s, 720K reads/s
 - B-Tree: 1.2M inserts/s, 1.5M lookups/s
 - Vector SIMD: 850K cosine distances/s (dim=768)
 - FTS: 320K docs/s indexing, 28K queries/s BM25
 - Graph: 2.5M nodes/s insertion, 12K BFS traversals/s
 - Binary Protocol: 380K queries/s (100 concurrent connections)
 ### Tests
 - 262 Tests über 56 Test-Suiten
 - 100% Pass Rate
 ## [Unreleased]
 ### Hinzugefügt
 - **Vector SQL Integration** — Vollständige SQL-Level Vector Search Unterstützung:
  - `VECTOR(n)` Spaltentyp in `CREATE TABLE` mit Dimensionsvalidierung
  - `CREATE INDEX ... USING hnsw` / `USING ivfpq` für Approximate Nearest Neighbor Indizes
  - SQL Distanzfunktionen: `cosine_distance()`, `euclidean_distance()`, `inner_product()`, `l1_distance()`, `l2_distance()`
  - `<->` Nearest-Neighbor Operator (Euclidean Distanz)
  - `ORDER BY` Support für Vektor-Distanz-Ausdrücke, inklusive Spalten nicht in `SELECT`
  - Automatische HNSW Index-Wartung bei `INSERT` und `UPDATE`
 - **Advanced SQL Engine** — Window Functions, MERGE/UPSERT, LATERAL JOIN, PIVOT/UNPIVOT, SQL/PGQ Property Graph, Advanced Aggregates
 - **JavaScript Client — TCP Request Queue** — Interne `_requestQueue` + `_requestLock` für sichere konkurrierende Abfragen
 ### Behoben
 - **Query Executor — Row Value Escaping** — `execInsert` escaped jetzt korrekt Kommas und Equals-Zeichen
 - **Query Planner — ORDER BY Projection** — `irpkSort` ist jetzt vor `irpkProject` im IR Plan platziert
 - **Wire Protocol — Big-Endian Float Serialization** — `FLOAT32`/`FLOAT64` werden jetzt in Big-Endian Byte-Reihenfolge serialisiert
 - **Gossip Protocol — Async UDP Socket** — Synchrone `newSocket` + blocking `recvFrom` ersetzt durch `newAsyncSocket` + `await recvFrom`
 ### Geplant
 - Query Plan Caching
 - Materialized Views
 - Geospatial Index
 - Time-series Optimierungen
 - CDC (Change Data Capture) Streaming
 - Federated Queries über BaraDB Instances
@@ -1,285 +0,0 @@
 # Client SDKs
 BaraDB bietet offizielle Client-Bibliotheken für JavaScript/TypeScript, Python, Nim und Rust.
 ## JavaScript / TypeScript
 ### Installation
 ```bash
 npm install baradb
 # oder
 yarn add baradb
 ```
 ### Grundlegende Verwendung
 ```typescript
 import { Client } from 'baradb';
 const client = new Client('localhost', 9472);
 await client.connect();
 // Einfache Abfrage
 const result = await client.query('SELECT name, age FROM users WHERE age > 18');
 console.log(result.rows);
 // Parametrisierte Abfrage
 const result2 = await client.query(
  'SELECT * FROM users WHERE name = ?',
  ['Alice']
 );
 // Batch-Einfügung
 await client.batch([
  "INSERT users { name := 'Alice', age := 30 }",
  "INSERT users { name := 'Bob', age := 25 }",
 ]);
 // Transaktionen
 await client.begin();
 await client.query("INSERT orders { total := 100 }");
 await client.query("UPDATE users SET balance = balance - 100 WHERE name = 'Alice'");
 await client.commit();
 await client.close();
 ```
 ### Konkurrierende Abfragen
 Der JavaScript-Client serialisiert konkurrierende Anfragen über eine einzelne TCP-Verbindung automatisch via interner Request-Queue. Sie können sicher mehrere parallele Operationen starten — ihre Binärframes werden sich nicht auf dem Wire überlappen:
 ```typescript
 const [users, orders, stats] = await Promise.all([
  client.query('SELECT * FROM users'),
  client.query('SELECT * FROM orders'),
  client.query('SELECT count(*) FROM visits')
 ]);
 ```
 ### WebSocket-Streaming
 ```typescript
 import { WebSocketClient } from 'baradb/ws';
 const ws = new WebSocketClient('ws://localhost:9471');
 ws.onMessage = (data) => console.log(data);
 await ws.connect();
 await ws.send('SUBSCRIBE updates');
 ```
 ## Python
 ### Installation
 ```bash
 pip install baradb
 ```
 ### Grundlegende Verwendung
 ```python
 from baradb import Client
 client = Client("localhost", 9472)
 client.connect()
 # Einfache Abfrage
 result = client.query("SELECT name, age FROM users WHERE age > 18")
 for row in result:
    print(row["name"], row["age"])
 # Parametrisierte Abfrage
 result = client.query(
    "SELECT * FROM users WHERE name = ?",
    ["Alice"]
 )
 # Batch-Operationen
 client.batch([
    "INSERT users { name := 'Alice', age := 30 }",
    "INSERT users { name := 'Bob', age := 25 }",
 ])
 # Context Manager (auto-close)
 with Client("localhost", 9472) as c:
    result = c.query("SELECT count(*) FROM users")
    print(result[0]["count"])
 ```
 ### Async Client
 ```python
 import asyncio
 from baradb import AsyncClient
 async def main():
    client = AsyncClient("localhost", 9472)
    await client.connect()
    result = await client.query("SELECT * FROM users")
    print(result.rows)
    await client.close()
 asyncio.run(main())
 ```
 ## Nim (Embedded Mode)
 ### Abhängigkeit hinzufügen
 ```nim
 # In Ihrer .nimble Datei
 requires "barabadb >= 0.1.0"
 ```
 ### Embedded-Verwendung
 ```nim
 import barabadb/storage/lsm
 import barabadb/storage/btree
 import barabadb/vector/engine
 import barabadb/graph/engine
 # Key-Value Store
 var db = newLSMTree("./data")
 db.put("user:1", cast[seq[byte]]("Alice"))
 let (found, value) = db.get("user:1")
 db.close()
 # B-Tree Index
 var btree = newBTreeIndex[string, int]()
 btree.insert("Alice", 30)
 let ages = btree.get("Alice")
 # Vector Search
 var idx = newHNSWIndex(dimensions = 128)
 idx.insert(1, @[0.1'f32, 0.2, 0.3], {"category": "A"}.toTable)
 let results = idx.search(@[0.1'f32, 0.2, 0.3], k = 10)
 # Graph
 var g = newGraph()
 let alice = g.addNode("Person", {"name": "Alice"}.toTable)
 let bob = g.addNode("Person", {"name": "Bob"}.toTable)
 discard g.addEdge(alice, bob, "knows")
 let path = g.shortestPath(alice, bob)
 ```
 ### Client-Bibliothek
 ```nim
 import barabadb/client/client
 var c = newBaraClient("localhost", 9472)
 c.connect()
 let result = c.query("SELECT name FROM users")
 for row in result.rows:
  echo row["name"]
 c.close()
 ```
 ## Rust
 ### Abhängigkeit hinzufügen
 ```toml
 [dependencies]
 baradb = "0.1"
 tokio = { version = "1", features = ["full"] }
 ```
 ### Grundlegende Verwendung
 ```rust
 use baradb::Client;
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect("localhost:9472").await?;
    let result = client
        .query("SELECT name, age FROM users WHERE age > 18")
        .await?;
    for row in result.rows {
        println!("{} is {} years old", row["name"], row["age"]);
    }
    client.close().await?;
    Ok(())
 }
 ```
 ## HTTP/REST (Sprachunabhängig)
 Alle Sprachen können die HTTP/REST API direkt verwenden:
 ```bash
 # Abfrage
 curl -X POST http://localhost:9470/api/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "SELECT * FROM users WHERE age > 18"}'
 # Einfügen
 curl -X POST http://localhost:9470/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT users { name := \"Alice\", age := 30 }"}'
 # Schema
 curl http://localhost:9470/api/schema
 # Health
 curl http://localhost:9470/health
 # Metrics
 curl http://localhost:9470/metrics
 ```
 ## Connection Pooling
 Alle offiziellen Clients unterstützen Connection Pooling:
 ### JavaScript
 ```typescript
 import { Pool } from 'baradb';
 const pool = new Pool({
  host: 'localhost',
  port: 9472,
  min: 5,
  max: 50,
  idleTimeout: 30000,
 });
 const client = await pool.acquire();
 try {
  const result = await client.query('SELECT 1');
 } finally {
  pool.release(client);
 }
 ```
 ### Python
 ```python
 from baradb import Pool
 pool = Pool("localhost", 9472, min_size=5, max_size=50)
 with pool.connection() as conn:
    result = conn.query("SELECT 1")
 ```
 ## Datentyp-Mapping
 | BaraDB Type | JavaScript | Python | Nim | Rust |
 |-------------|------------|--------|-----|------|
 | `null` | `null` | `None` | `nil` | `Option::None` |
 | `bool` | `boolean` | `bool` | `bool` | `bool` |
 | `int8/16/32/64` | `number` | `int` | `int` | `i8/i16/i32/i64` |
 | `float32/64` | `number` | `float` | `float32/float64` | `f32/f64` |
 | `str` | `string` | `str` | `string` | `String` |
 | `bytes` | `Uint8Array` | `bytes` | `seq[byte]` | `Vec<u8>` |
 | `array` | `Array` | `list` | `seq` | `Vec` |
 | `object` | `Object` | `dict` | `Table` | `HashMap` |
 | `vector` | `Float32Array` | `list[float]` | `seq[float32]` | `Vec<f32>` |
@@ -1,58 +0,0 @@
 # Kolumnare Speicherung
 Spaltenorientierte Speicherung für analytische Abfragen und Aggregation.
 ## Verwendung
 ```nim
 import barabadb/core/columnar
 var batch = newColumnBatch()
 var ageCol = batch.addInt64Col("age")
 var nameCol = batch.addStringCol("name")
 ageCol.appendInt64(25)
 nameCol.appendString("Alice")
 ```
 ## Aggregation
 ```nim
 echo ageCol.sumInt64()
 echo ageCol.avgInt64()
 echo ageCol.minInt64()
 echo ageCol.maxInt64()
 echo ageCol.count()
 ```
 ## Kodierung
 ### RLE (Run-Length Encoding)
 ```nim
 let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
 ```
 ### Dictionary-Kodierung
 ```nim
 let dict = dictEncode(@["apple", "banana", "apple"])
 ```
 ## Spaltentypen
 | Typ | Beschreibung |
 |------|-------------|
 | `int32` | 32-Bit Integer |
 | `int64` | 64-Bit Integer |
 | `float32` | 32-Bit Float |
 | `float64` | 64-Bit Float |
 | `string` | Variable-length String |
 | `bool` | Boolean |
 ## Anwendungsfälle
 - OLAP-Workloads
 - Großflächige Aggregation
 - Data Warehousing
 - Zeitreihenanalyse
@@ -1,217 +0,0 @@
 # Konfigurationsreferenz
 BaraDB kann über **Environment-Variablen**, eine **Konfigurationsdatei** oder **Kommandozeilen-Flags** konfiguriert werden.
 ## Prioritätsreihenfolge
 1. Kommandozeilen-Flags (höchste Priorität)
 2. Environment-Variablen
 3. Konfigurationsdatei (`baradb.conf` oder `baradb.json`)
 4. Integrierte Standardwerte (niedrigste Priorität)
 ## Environment-Variablen
 ### Netzwerk
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_ADDRESS` | `127.0.0.1` | Bind-Adresse |
 | `BARADB_PORT` | `9472` | TCP Binary Protocol Port |
 | `BARADB_HTTP_PORT` | `9470` | HTTP/REST API Port |
 | `BARADB_WS_PORT` | `9471` | WebSocket Port |
 ### Speicher
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_DATA_DIR` | `./data` | Datenverzeichnis-Pfad |
 | `BARADB_MEMTABLE_SIZE_MB` | `64` | MemTable-Größe in MB |
 | `BARADB_CACHE_SIZE_MB` | `256` | Page-Cache-Größe in MB |
 | `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | WAL fsync Intervall (0 = bei jedem Write) |
 | `BARADB_COMPACTION_INTERVAL_MS` | `60000` | Background Compaction Intervall |
 | `BARADB_BLOOM_BITS_PER_KEY` | `10` | Bloom-Filter Bits pro Schlüssel |
 ### TLS/SSL
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_TLS_ENABLED` | `false` | TLS aktivieren |
 | `BARADB_CERT_FILE` | — | Pfad zum TLS-Zertifikat |
 | `BARADB_KEY_FILE` | — | Pfad zum TLS Private Key |
 ### Sicherheit
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_AUTH_ENABLED` | `false` | Authentifizierung aktivieren |
 | `BARADB_JWT_SECRET` | — | JWT Signatur-Geheimnis |
 | `BARADB_RATE_LIMIT_GLOBAL` | `10000` | Globale Requests pro Sekunde |
 | `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | Per-Client Requests pro Sekunde |
 ### Logging
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_LOG_LEVEL` | `info` | Log-Level: debug, info, warn, error |
 | `BARADB_LOG_FILE` | — | Log-Datei-Pfad (stdout wenn leer) |
 | `BARADB_LOG_FORMAT` | `json` | Log-Format: json, text |
 ### Vector Engine
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_VECTOR_M` | `16` | HNSW `M` Parameter |
 | `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` |
 | `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` |
 ### Graph Engine
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | PageRank Iterationsanzahl |
 | `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | PageRank Dämpfungsfaktor |
 | `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Louvain Resolution-Parameter |
 ### Distributed
 | Variable | Standard | Beschreibung |
 |----------|---------|-------------|
 | `BARADB_RAFT_NODE_ID` | — | Eindeutige Knoten-ID im Cluster |
 | `BARADB_RAFT_PEERS` | — | Komma-getrennte Liste von Peer-Adressen |
 | `BARADB_RAFT_PORT` | `9001` | Raft interne Kommunikation Port |
 | `BARADB_SHARD_COUNT` | `1` | Anzahl der Shards |
 | `BARADB_REPLICATION_FACTOR` | `1` | Replikationsfaktor |
 ## Konfigurationsdatei
 ### baradb.conf (INI-ähnlich)
 ```ini
 [server]
 address = "0.0.0.0"
 port = 9472
 http_port = 9470
 ws_port = 9471
 [storage]
 data_dir = "/var/lib/baradb"
 memtable_size_mb = 256
 cache_size_mb = 512
 wal_sync_interval_ms = 10
 compaction_interval_ms = 30000
 [tls]
 enabled = true
 cert_file = "/etc/baradb/server.crt"
 key_file = "/etc/baradb/server.key"
 [auth]
 enabled = true
 jwt_secret = "change-me-in-production"
 rate_limit_global = 10000
 rate_limit_per_client = 1000
 [logging]
 level = "info"
 format = "json"
 file = "/var/log/baradb/baradb.log"
 [vector]
 m = 16
 ef_construction = 200
 ef_search = 64
 [cluster]
 raft_node_id = "node1"
 raft_peers = "node2:9001,node3:9001"
 ```
 ### baradb.json
 ```json
 {
  "server": {
    "address": "0.0.0.0",
    "port": 9472,
    "http_port": 9470,
    "ws_port": 9471
  },
  "storage": {
    "data_dir": "/var/lib/baradb",
    "memtable_size_mb": 256,
    "cache_size_mb": 512
  },
  "tls": {
    "enabled": true,
    "cert_file": "/etc/baradb/server.crt",
    "key_file": "/etc/baradb/server.key"
  }
 }
 ```
 ## Kommandozeilen-Flags
 ```bash
 ./build/baradadb --help
 ```
 ```
 BaraDB v1.1.6 — Multimodal Database Engine
 Usage:
  baradadb [options]
 Options:
  -c, --config <file>       Config file path
  -p, --port <port>         TCP binary port (default: 9472)
  --http-port <port>        HTTP port (default: 9470)
  --ws-port <port>          WebSocket port (default: 9471)
  -d, --data-dir <dir>      Data directory (default: ./data)
  --tls-cert <file>         TLS certificate file
  --tls-key <file>          TLS private key file
  --log-level <level>       Log level: debug, info, warn, error
  --log-file <file>         Log file path
  --shell                   Start interactive shell
  --version                 Show version
  --recover                 Run WAL recovery
  --checkpoint <file>       Checkpoint for recovery
  -h, --help                Show this help
 ```
 ## Beispielkonfigurationen
 ### Entwicklung
 ```bash
 ./build/baradadb \
  --log-level debug \
  --data-dir ./dev_data
 ```
 ### Produktion Single Node
 ```bash
 BARADB_TLS_ENABLED=true \
 BARADB_CERT_FILE=/etc/baradb/server.crt \
 BARADB_KEY_FILE=/etc/baradb/server.key \
 BARADB_AUTH_ENABLED=true \
 BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
 BARADB_LOG_LEVEL=warn \
 BARADB_LOG_FILE=/var/log/baradb/baradb.log \
 BARADB_MEMTABLE_SIZE_MB=256 \
 BARADB_CACHE_SIZE_MB=1024 \
 ./build/baradadb
 ```
 ### Produktion Cluster (3 Knoten)
 ```bash
 # Knoten 1
 BARADB_ADDRESS=0.0.0.0 \
 BARADB_PORT=9472 \
 BARADB_RAFT_NODE_ID=node1 \
 BARADB_RAFT_PEERS=node2:9001,node3:9001 \
 BARADB_SHARD_COUNT=4 \
 BARADB_REPLICATION_FACTOR=2 \
 ./build/baradadb
 ```
@@ -1,218 +0,0 @@
 # Cross-Modal Abfragen
 BaraDB's einzigartige Fähigkeit ist die Ausführung von Abfragen, die mehrere
 Speicher-Engines in einer einzigen vereinheitlichten BaraQL-Anweisung umfassen.
 ## Überblick
 Traditionelle Datenbanken erfordern separate Abfragen und applikationsseitige Joins
 bei der Arbeit mit verschiedenen Datenmodellen. BaraDB's Cross-Modal Query Planner
 optimiert die Ausführung über:
 - **Document/KV** (LSM-Tree) — strukturierte Datensätze
 - **Graph** (Adjacency List) — Beziehungen
 - **Vector** (HNSW/IVF-PQ) — Ähnlichkeitssuche
 - **Full-Text** (Inverted Index) — Textsuche
 - **Columnar** — analytische Aggregatfunktionen
 ## Abfragemuster
 ### Vector + Full-Text (Semantisch + Schlüsselwortsuche)
 Finde Dokumente, die semantisch ähnlich zu einem Query-Vektor sind UND
 bestimmte Schlüsselwörter enthalten:
 ```sql
 SELECT title, score
 FROM articles
 WHERE MATCH(body) AGAINST('machine learning')
 ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, ...])
 LIMIT 10;
 ```
 Ausführungsplan:
 1. FTS-Engine filtert Artikel mit "machine learning"
 2. Vector-Engine rankt gefilterte Ergebnisse nach Embedding-Ähnlichkeit
 3. Top-K Ergebnisse zurückgegeben
 ### Graph + Vector (Soziale Empfehlungen)
 Finde Freunde eines Benutzers mit ähnlichen Geschmacksvektoren:
 ```sql
 MATCH (u:User)-[:KNOWS]->(friend:User)
 WHERE u.name = 'Alice'
 ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
 RETURN friend.name, friend.age;
 ```
 Ausführungsplan:
 1. Graph-Engine traversiert "KNOWS"-Kanten von Alice
 2. Vector-Engine berechnet Ähnlichkeit für jeden Freund
 3. Ergebnisse sortiert und projiziert
 ### Document + Graph (Entity-Anreicherung)
 Erhalte Bestelldetails mit Kunden-Beziehungsgraph:
 ```sql
 SELECT o.id, o.total, c.name,
       (SELECT count(*) FROM orders WHERE customer_id = c.id) as order_count
 FROM orders o
 JOIN customers c ON o.customer_id = c.id
 WHERE c.id IN (
  SELECT node_id FROM graph
  WHERE MATCH pattern (c:Customer)-[:REFERRED]->(:Customer)
 );
 ```
 ### Full-Text + Aggregate (Content-Analyse)
 Analysiere welche Abteilungen am meisten über ein Thema schreiben:
 ```sql
 SELECT department, count(*) as article_count,
       avg(length(content)) as avg_length
 FROM docs
 WHERE MATCH(content) AGAINST('Nim programming')
 GROUP BY department
 ORDER BY article_count DESC;
 ```
 ### Vector + Aggregate (Cluster-Analyse)
 Gruppiere ähnliche Vektoren und analysiere jedes Cluster:
 ```sql
 SELECT cluster_id, count(*) as size,
       centroid(embedding) as center,
       avg(created_at) as avg_date
 FROM products
 GROUP BY vector_cluster(embedding, k=10)
 ORDER BY size DESC;
 ```
 ### Alle Modalitäten kombiniert
 Eine komplexe Abfrage unter Verwendung aller Engines:
 ```sql
 WITH relevant_docs AS (
  SELECT id, title, embedding
  FROM articles
  WHERE MATCH(body) AGAINST('database optimization')
    AND created_at > '2024-01-01'
 ),
 author_graph AS (
  MATCH (a:Author)-[:COAUTHORED]->(b:Author)
  WHERE a.name = 'Dr. Smith'
  RETURN b.id as coauthor_id
 )
 SELECT rd.title, rd.score,
       a.name as author,
       cosine_distance(rd.embedding, query_vec) as similarity
 FROM relevant_docs rd
 JOIN authors a ON rd.author_id = a.id
 WHERE a.id IN (SELECT coauthor_id FROM author_graph)
 ORDER BY similarity ASC, rd.score DESC
 LIMIT 20;
 ```
 ## Optimierung
 ### Cross-Modal Query Planner
 BaraDB's adaptiver Query-Optimizer (`query/adaptive.nim`) wählt die Ausführungsreihenfolge basierend auf Selektivität:
 ```
 1. Selektivstes Filter zuerst (normalerweise FTS oder Vector)
 2. Prädikate zu jeder Engine pushen
 3. Bloom-Filter für KV-Lookups verwenden
 4. Unabhängige Zweige parallelisieren
 ```
 ### Index-Auswahl
 Der Optimizer wählt automatisch den besten Index:
 | Abfragemuster | Primäre Engine | Sekundäre Engine |
 |---------------|----------------|-----------------|
 | `MATCH ... ORDER BY cosine_distance` | Vector | FTS |
 | `MATCH ... WHERE graph condition` | Graph | FTS |
 | `WHERE id = ? AND vector_search` | KV | Vector |
 | `GROUP BY + MATCH` | FTS | Columnar |
 ### Hints
 Bestimmte Ausführungsreihenfolge erzwingen:
 ```sql
 SELECT /*+ USE_INDEX(vector) */ *
 FROM products
 WHERE category = 'electronics'
 ORDER BY cosine_distance(embedding, [...])
 LIMIT 10;
 ```
 ## Performance
 Cross-Modal Abfragen sind optimiert um Datenbewegung zu minimieren:
 | Abfragetyp | Latenz (10K Zeilen) | Latenz (100K Zeilen) |
 |------------|---------------------|----------------------|
 | FTS + Vector | 15 ms | 85 ms |
 | Graph + Vector | 25 ms | 120 ms |
 | FTS + Aggregate | 12 ms | 55 ms |
 | Alle Modalitäten | 45 ms | 220 ms |
 ## Anwendungsfälle
 ### E-Commerce Suche
 ```sql
 -- Finde Produkte passend zu einem Suchbegriff, ähnlich zu einem betrachteten Artikel,
 -- gekauft von ähnlichen Benutzern
 SELECT p.name, p.price
 FROM products p
 WHERE MATCH(p.description) AGAINST('wireless headphones')
  AND cosine_distance(p.embedding, viewed_embedding) < 0.3
  AND p.id IN (
    SELECT product_id FROM orders o
    JOIN graph ON o.customer_id = graph.node_id
    WHERE graph.similarity > 0.8
  )
 ORDER BY p.rating DESC
 LIMIT 20;
 ```
 ### Betrugserkennung
 ```sql
 -- Finde Transaktionen ähnlich zu bekannten Betrugsmustern,
 -- wo der Benutzer mit markierten Konten verbunden ist
 SELECT t.id, t.amount
 FROM transactions t
 WHERE cosine_distance(t.pattern_vector, fraud_vector) < 0.2
  AND t.user_id IN (
    MATCH (u:User)-[*1..3]->(f:FlaggedAccount)
    RETURN u.id
  );
 ```
 ### Knowledge Graph + RAG
 ```sql
 -- Relevante Dokumente für eine Query abrufen,
 -- dann den Knowledge Graph für verwandte Konzepte traversieren
 WITH docs AS (
  SELECT id, content, embedding
  FROM documents
  ORDER BY cosine_distance(embedding, query_embedding)
  LIMIT 5
 )
 SELECT d.content, c.name as related_concept
 FROM docs d
 JOIN graph ON d.id = graph.doc_id
 MATCH (d)-[:MENTIONS]->(c:Concept)
 RETURN d.content, c.name;
 ```
@@ -1,247 +0,0 @@
 # Deployment-Leitfaden
 ## Docker
 ### Schnellstart
 ```bash
 docker build -t baradb:latest .
 docker compose up -d
 ```
 ### Docker Compose Dateien
 | Datei | Zweck |
 |-------|-------|
 | `docker-compose.yml` | Entwicklung |
 | `docker-compose.prod.yml` | Produktion |
 | `docker-compose.override.yml` | Dev Override (automatisch) |
 ### Produktion
 ```bash
 docker compose -f docker-compose.prod.yml up -d
 ```
 ### Docker Swarm
 ```bash
 docker stack deploy -c docker-compose.prod.yml baradb
 ```
 ## systemd Service
 Erstelle `/etc/systemd/system/baradb.service`:
 ```ini
 [Unit]
 Description=BaraDB Multimodal Database
 After=network.target
 [Service]
 Type=simple
 User=baradb
 Group=baradb
 WorkingDirectory=/var/lib/baradb
 ExecStart=/usr/local/bin/baradadb
 Restart=always
 RestartSec=5
 Environment=BARADB_PORT=9472
 Environment=BARADB_HTTP_PORT=9470
 Environment=BARADB_DATA_DIR=/var/lib/baradb/data
 Environment=BARADB_LOG_LEVEL=info
 # Security hardening
 NoNewPrivileges=true
 ProtectSystem=strict
 ProtectHome=true
 ReadWritePaths=/var/lib/baradb/data
 ProtectKernelTunables=true
 ProtectKernelModules=true
 ProtectControlGroups=true
 [Install]
 WantedBy=multi-user.target
 ```
 Aktivieren und starten:
 ```bash
 sudo useradd -r -s /bin/false baradb
 sudo mkdir -p /var/lib/baradb/data
 sudo chown -R baradb:baradb /var/lib/baradb
 sudo cp build/baradadb /usr/local/bin/
 sudo systemctl daemon-reload
 sudo systemctl enable --now baradb
 ```
 ## Kubernetes
 ### StatefulSet
 ```yaml
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
  name: baradb
 spec:
  serviceName: baradb
  replicas: 3
  selector:
    matchLabels:
      app: baradb
  template:
    metadata:
      labels:
        app: baradb
    spec:
      containers:
      - name: baradb
        image: baradb:latest
        ports:
        - containerPort: 9472
          name: binary
        - containerPort: 9470
          name: http
        - containerPort: 9471
          name: websocket
        env:
        - name: BARADB_DATA_DIR
          value: /data
        - name: BARADB_RAFT_NODE_ID
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        volumeMounts:
        - name: data
          mountPath: /data
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 100Gi
 ---
 apiVersion: v1
 kind: Service
 metadata:
  name: baradb
 spec:
  selector:
    app: baradb
  ports:
  - port: 9472
    name: binary
  - port: 9470
    name: http
  - port: 9471
    name: websocket
  clusterIP: None
 ```
 ## Reverse Proxy (nginx)
 ```nginx
 upstream baradb_http {
    server 127.0.0.1:9470;
 }
 upstream baradb_ws {
    server 127.0.0.1:9471;
 }
 server {
    listen 80;
    server_name db.example.com;
    return 301 https://$server_name$request_uri;
 }
 server {
    listen 443 ssl http2;
    server_name db.example.com;
    ssl_certificate /etc/letsencrypt/live/db.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/db.example.com/privkey.pem;
    location /api/ {
        proxy_pass http://baradb_http/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    location /ws/ {
        proxy_pass http://baradb_ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
 }
 ```
 ## High Availability
 ### 3-Node Raft Cluster
 ```bash
 # Knoten 1
 BARADB_RAFT_NODE_ID=node1 \
 BARADB_RAFT_PEERS=node2:9001,node3:9001 \
 ./build/baradadb
 # Knoten 2
 BARADB_RAFT_NODE_ID=node2 \
 BARADB_RAFT_PEERS=node1:9001,node3:9001 \
 ./build/baradadb
 # Knoten 3
 BARADB_RAFT_NODE_ID=node3 \
 BARADB_RAFT_PEERS=node1:9001,node2:9001 \
 ./build/baradadb
 ```
 ## Cloud Deployment
 ### AWS EC2
 Empfohlene Instance: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
 ```bash
 # User data script
 #!/bin/bash
 apt-get update
 apt-get install -y nim
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
 chmod +x baradadb-linux-amd64
 mv baradadb-linux-amd64 /usr/local/bin/baradadb
 mkdir -p /data/baradb
 cat > /etc/systemd/system/baradb.service << 'EOF'
 [Unit]
 Description=BaraDB
 After=network.target
 [Service]
 ExecStart=/usr/local/bin/baradadb
 Environment=BARADB_DATA_DIR=/data/baradb
 Restart=always
 [Install]
 WantedBy=multi-user.target
 EOF
 systemctl daemon-reload
 systemctl enable --now baradb
 ```
 ### GCP Cloud Run (nur HTTP)
 ```bash
 gcloud run deploy baradb \
  --image gcr.io/PROJECT/baradb \
  --port 9470 \
  --memory 4Gi \
  --cpu 2 \
  --max-instances 10
 ```
@@ -1,110 +0,0 @@
 # Distributed Systems
 BaraDB unterstützt verteiltes Deployment mit Raft Consensus, Sharding und Replikation.
 ## Raft Consensus
 Leader Election und Log-Replikation:
 ```nim
 import barabadb/core/raft
 var cluster = newRaftCluster()
 cluster.addNode("node1")
 cluster.addNode("node2")
 cluster.addNode("node3")
 let n1 = cluster.nodes["n1"]
 n1.becomeCandidate()
 n1.becomeLeader()
 let entry = n1.appendLog("SET key1 value1")
 ```
 ## Sharding
 Daten über Knoten verteilen:
 ```nim
 import barabadb/core/sharding
 var router = newShardRouter(ShardConfig(
  numShards: 4,
  replicas: 2,
  strategy: ssHash
 ))
 router.rebalance(@["node1", "node2", "node3"])
 let shard = router.getShard("user_123")
 ```
 ### Sharding-Strategien
 | Strategie | Beschreibung |
 |----------|-------------|
 | `ssHash` | Hash-basiertes Sharding |
 | `ssRange` | Range-basiertes Sharding |
 | `ssConsistent` | Consistent Hashing |
 ## Replikation
 ```nim
 import barabadb/core/replication
 var rm = newReplicationManager(rmSync)
 rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
 rm.connectReplica("r1")
 let lsn = rm.writeLsn(@[1'u8, 2, 3])
 rm.ackLsn("r1", lsn)
 ```
 ### Replikationsmodi
 | Modus | Beschreibung |
 |-------|--------------|
 | `rmSync` | Synchronous Replikation |
 | `rmAsync` | Asynchrone Replikation |
 | `rmSemiSync` | Semi-synchrone Replikation |
 ## Gossip Protocol
 Membership und Failure-Erkennung:
 ```nim
 import barabadb/core/gossip
 var g = newGossipManager()
 g.addNode("node1")
 g.addNode("node2")
 g.tick()  # Membership-Info austauschen
 ```
 ## Distributed Transactions
 Two-Phase Commit über Knoten:
 ```nim
 import barabadb/core/disttxn
 var dt = newDistributedTxn()
 dt.prepare(@["node1", "node2"])
 dt.commit()
 ```
 ## Formale Verifikation
 Kern-Algorithmen für Distributed Systems sind formal in TLA+ spezifiziert und model-gecheckt:
 - **Raft Consensus** — `formal-verification/raft.tla`
  - Verifiziert: ElectionSafety, StateMachineSafety
 - **Two-Phase Commit** — `formal-verification/twopc.tla`
  - Verifiziert: Atomicity, NoOrphanBlocks
 - **Replication** — `formal-verification/replication.tla`
  - Verifiziert: MonotonicLsn, AcksRemovePending
 TLC lokal ausführen:
 ```bash
 cd formal-verification
 java -cp tla2tools.jar tlc2.TLC -config models/raft.cfg raft.tla
 java -cp tla2tools.jar tlc2.TLC -config models/twopc.cfg twopc.tla
 java -cp tla2tools.jar tlc2.TLC -config models/replication.cfg replication.tla
 ```
@@ -1,191 +0,0 @@
 # Docker Deployment-Leitfaden
 Dieser Leitfaden beschreibt, wie Sie BaraDB mit Docker und Docker Compose verwenden.
 ## Schnellstart
 ```bash
 # Repository klonen
 git clone https://codeberg.org/baraba/baradb
 cd barabaDB
 # Image bauen
 docker build -t baradb:latest .
 # Mit Docker Compose starten
 docker compose up -d
 # Status prüfen
 docker compose ps
 docker compose logs -f
 ```
 ## Dateien
 | Datei | Beschreibung |
 |-------|--------------|
 | `Dockerfile` | Multi-stage Production Build |
 | `docker-compose.yml` | Development Konfiguration |
 | `docker-compose.prod.yml` | Production Konfiguration |
 | `docker-compose.override.yml` | Development Override (wird automatisch geladen) |
 | `docker-entrypoint.sh` | Entrypoint-Skript für Initialisierung |
 | `.dockerignore` | Dateien, die nicht ins Image kopiert werden sollen |
 | `scripts/docker-build.sh` | Helper-Skript für Build |
 | `scripts/docker-run.sh` | Helper-Skript für manuelles Starten |
 ## Image erstellen
 ```bash
 # Standard Build
 docker build -t baradb:latest .
 # Mit Skript
 ./scripts/docker-build.sh
 # Mit bestimmter Version
 IMAGE_NAME=baradb VERSION=0.1.0 ./scripts/docker-build.sh
 ```
 ## Starten
 ### Development (docker compose)
 ```bash
 # Im Hintergrund starten
 docker compose up -d
 # Stoppen
 docker compose down
 # Stoppen und Volumes löschen (WARNUNG — löscht Daten!)
 docker compose down -v
 # Logs ansehen
 docker compose logs -f
 ```
 ### Production (docker compose)
 ```bash
 # Mit Production-Konfiguration starten
 docker compose -f docker-compose.prod.yml up -d
 # Healthcheck prüfen
 docker compose -f docker-compose.prod.yml ps
 ```
 ### Manuell (docker run)
 ```bash
 # Mit Skript
 ./scripts/docker-run.sh
 # Manuell
 docker run -d \
  --name baradb \
  -p 9472:9472 \
  -p 9470:9470 \
  -p 9471:9471 \
  -v baradb_data:/data \
  -e BARADB_LOG_LEVEL=info \
  baradb:latest
 ```
 ## Ports
 | Port | Beschreibung |
 |------|--------------|
 | `9472` | Binary Wire Protocol |
 | `9912` | HTTP/REST API (TCP port + 440) |
 | `9913` | WebSocket (TCP port + 441) |
 ## Environment Variables
 | Variable | Standardwert | Beschreibung |
 |----------|--------------|--------------|
 | `BARADB_ADDRESS` | `0.0.0.0` | Bind-Adresse |
 | `BARADB_PORT` | `9472` | Binary Protocol Port |
 | `BARADB_HTTP_PORT` | `9470` | HTTP Port |
 | `BARADB_WS_PORT` | `9471` | WebSocket Port |
 | `BARADB_DATA_DIR` | `/data` | Datenverzeichnis |
 | `BARADB_LOG_LEVEL` | `info` | Log-Level |
 ## Volumes
 | Pfad im Container | Beschreibung |
 |-------------------|--------------|
 | `/data` | Hauptdatenverzeichnis |
 | `/data/server/wal` | Write-Ahead Log |
 | `/data/server/sstables` | SSTable Dateien |
 ## Production Checklist
 - [ ] TLS-Zertifikate in `./certs/` erstellen
 - [ ] Starkes `BARADB_JWT_SECRET` setzen
 - [ ] Firewall-Regeln konfigurieren
 - [ ] Regelmäßige Backups konfigurieren
 - [ ] Resource Limits prüfen
 - [ ] Monitoring einrichten (Healthcheck, Logs)
 ## TLS in Docker
 1. Zertifikate erstellen:
 ```bash
 mkdir -p certs
 openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/server.key -out certs/server.crt
 ```
 2. In `docker-compose.prod.yml` aktivieren:
 ```yaml
 environment:
  - BARADB_TLS_ENABLED=true
  - BARADB_CERT_FILE=/certs/server.crt
  - BARADB_KEY_FILE=/certs/server.key
 volumes:
  - ./certs:/certs:ro
 ```
 ## Backup in Docker
 ```bash
 # Manueller Backup
 docker exec baradb /app/backup backup --data-dir=/data
 # Backup-Liste
 docker exec baradb /app/backup list
 # Wiederherstellung
 docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
 ```
 ## Troubleshooting
 ### Container startet nicht
 ```bash
 # Logs prüfen
 docker compose logs -f baradb
 # Status prüfen
 docker compose ps
 ```
 ### Keine Verbindung zur Datenbank
 ```bash
 # Prüfen ob Ports exponiert sind
 docker port baradb
 # Von innen prüfen
 docker exec baradb wget -qO- http://localhost:9470/health
 ```
 ### Permission denied auf /data
 Das Entrypoint-Skript erstellt automatisch Verzeichnisse und setzt korrekte Permissions. Bei Problemen:
 ```bash
 docker exec baradb ls -la /data
 docker exec baradb chown -R baradb:baradb /data
 ```
@@ -1,87 +0,0 @@
 # Volltextsuchmaschine
 Invertierter Index mit BM25 und TF-IDF-Ranking für Textsuche.
 ## Verwendung
 ```nim
 import barabadb/fts/engine
 var idx = newInvertedIndex()
 idx.addDocument(1, "Nim is a fast programming language")
 idx.addDocument(2, "Python is popular for data science")
 # BM25-Suche
 let results = idx.search("programming language")
 # TF-IDF-Suche
 let tfidf = idx.searchTfidf("programming language")
 # Fuzzy-Suche (Tippfehlertoleranz)
 let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
 # Platzhalter-Suche
 let wild = idx.regexSearch("prog*")
 ```
 ## Ranking-Methoden
 ### BM25
 Best-Matching-Ranking-Algorithmus:
 ```nim
 let bm25 = idx.searchBM25("query terms")
 ```
 ### TF-IDF
 Term Frequency-Inverse Document Frequency:
 ```nim
 let tfidf = idx.searchTfidf("query terms")
 ```
 ## Suchfunktionen
 | Funktion | Beschreibung |
 |---------|-------------|
 | Fuzzy-Suche | Levenshtein-Distanz-Toleranz |
 | Platzhalter | Präfix-, Suffix- und Infix-Platzhalter |
 | Regex | Reguläre Ausdrucksmuster |
 | Phrasensuche | Exakte Phrasenübereinstimmung |
 | Boolesch | AND, OR, NOT Operatoren |
 ## SQL-Schnittstelle
 Volltextsuche ist auch direkt in BaraQL verfügbar:
 ```sql
 -- Tabelle mit Textspalte erstellen
 CREATE TABLE articles (id INT PRIMARY KEY, title TEXT, body TEXT);
 -- FTS-Index erstellen
 CREATE INDEX idx_fts ON articles(body) USING FTS;
 -- Suche mit dem @@ Operator (BM25-Ranking)
 SELECT * FROM articles WHERE body @@ 'machine learning';
 -- Suche mit mehreren Begriffen
 SELECT * FROM articles WHERE body @@ 'quick brown fox';
 ```
 ## Mehrsprachige Unterstützung
 ```nim
 import barabadb/fts/multilang
 # Unterstützte Sprachen: EN, BG, DE, FR, RU
 var tokenizer = newTokenizer("de")  # Deutsch
 let tokens = tokenizer.tokenize("Volltextsuche")
 ```
 Funktionen pro Sprache:
 - Tokenisierung
 - Stoppwörter
 - Stemming
 - Spracherkennung
@@ -1,145 +0,0 @@
 # Graph Engine
 Adjazenzlisten-Speicher mit eingebauten Algorithmen für Graph-Traversierung und -Analyse.
 Vollständig integriert in den SQL-Executor via `GRAPH_TABLE()`.
 ## SQL — Graph DDL
 ### Graph erstellen
 ```sql
 CREATE GRAPH org_chart;
 ```
 Erstellt automatisch zwei Tabellen:
 - `org_chart_nodes (id INTEGER PRIMARY KEY, node_label TEXT, properties TEXT)`
 - `org_chart_edges (source_id INTEGER, dest_id INTEGER, edge_label TEXT, weight REAL)`
 ### Graph löschen
 ```sql
 DROP GRAPH org_chart;
 ```
 ## SQL — Daten einfügen
 ```sql
 -- Knoten
 INSERT INTO org_chart_nodes (id, node_label) VALUES (1, 'CEO');
 INSERT INTO org_chart_nodes (id, node_label) VALUES (2, 'VP');
 -- Kanten
 INSERT INTO org_chart_edges (source_id, dest_id, edge_label) VALUES (1, 2, 'manages');
 ```
 Alle INSERTs werden automatisch mit dem nativen Graph-Objekt synchronisiert.
 ## SQL — GRAPH_TABLE Abfragen
 ### BFS (Breitensuche)
 ```sql
 SELECT * FROM GRAPH_TABLE(org_chart MATCH (n)-[r]->(m)
    ALGORITHM bfs
    START 1 MAXDEPTH 2
    COLUMNS (id, node_label));
 ```
 ### DFS (Tiefensuche)
 ```sql
 SELECT * FROM GRAPH_TABLE(org_chart MATCH (n)-[r]->(m)
    ALGORITHM dfs START 1
    COLUMNS (id, node_label));
 ```
 ### PageRank
 ```sql
 SELECT id, node_label, rank FROM GRAPH_TABLE(org_chart
    ALGORITHM pagerank
    COLUMNS (id, node_label, rank))
 ORDER BY rank DESC;
 ```
 ### Community Detection (Louvain)
 ```sql
 SELECT id, node_label, community FROM GRAPH_TABLE(org_chart
    ALGORITHM community
    COLUMNS (id, node_label, community));
 ```
 ### Kürzester Pfad (Shortest Path)
 ```sql
 SELECT * FROM GRAPH_TABLE(org_chart
    ALGORITHM shortest_path
    START 1 END 3
    COLUMNS (id, node_label));
 ```
 ### Dijkstra (gewichtete kürzeste Pfade)
 ```sql
 SELECT * FROM GRAPH_TABLE(org_chart
    ALGORITHM dijkstra START 1
    COLUMNS (id, node_label, distance));
 ```
 ## SQL-Funktionen
 ### Knotenähnlichkeit
 ```sql
 -- Jaccard-Ähnlichkeit zwischen allen Knotenpaaren
 SELECT similarity_nodes('social', 'jaccard') AS result;
 -- Adamic-Adar-Ähnlichkeit
 SELECT similarity_nodes('social', 'adamic_adar') AS result;
 ```
 ### Node2Vec Embeddings
 ```sql
 -- Graphstruktur-Embeddings generieren (64 Dimensionen)
 SELECT node2vec_embed('social', 64) AS result;
 ```
 ## Cypher-Kompatibilität
 ```sql
 -- Cypher-Syntax automatisch nach GRAPH_TABLE übersetzen
 SELECT cypher('MATCH (a)-[r]->(b) WHERE a.node_label = ''CEO'' RETURN b.node_label') AS result;
 ```
 ## Algorithmen
 | Algorithmus | Beschreibung | SQL |
 |-------------|--------------|-----|
 | `bfs` | Breitensuche | `ALGORITHM bfs` |
 | `dfs` | Tiefensuche | `ALGORITHM dfs` |
 | `dijkstra` | Gewichtete kürzeste Pfade | `ALGORITHM dijkstra` |
 | `pageRank` | Knoten-Wichtigkeit | `ALGORITHM pagerank` |
 | `louvain` | Community Detection | `ALGORITHM community` |
 | `shortestPath` | Kürzester Pfad | `ALGORITHM shortest_path START X END Y` |
 | `similarityNodes` | Knotenähnlichkeit | `similarity_nodes()` |
 | `node2vec` | Graph Embeddings | `node2vec_embed()` |
 ## Native Nim API
 ```nim
 import barabadb/graph/engine
 var g = newGraph()
 let alice = g.addNode("Person", {"name": "Alice"}.toTable)
 let bob = g.addNode("Person", {"name": "Bob"}.toTable)
 discard g.addEdge(alice, bob, "knows")
 let bfs = g.bfs(alice)
 let path = g.shortestPath(alice, bob)
 let ranks = g.pageRank()
 let communities = louvain(g)
 let similarities = g.similarityNodes(smJaccard)
 let embeddings = g.node2vec(64, 10, 5)
 ```
@@ -1,64 +0,0 @@
 # BaraDB Dokumentation
 **Eine multimodale Datenbank-Engine — 100% Nim, null Abhängigkeiten.**
 ## Sprachen
 - [English](../en/)
 - [Български (Bulgarisch)](../bg/)
 - [Deutsch (German)](../de/)
 - [Русский (Russisch)](../ru/)
 - [فارسی (Farsi)](../fa/)
 - [中文 (Chinesisch)](../zh/)
 - [Türkçe (Türkisch)](../tr/)
 - [العربية (Arabisch)](../ar/)
 ---
 ## Schnellstart
 - [Installation](installation.md)
 - [Schnellstart](quickstart.md)
 - [Architektur](architecture.md)
 - [Konfiguration](configuration.md)
 ## Kernkonzepte
 - [BaraQL Abfragesprache](baraql.md)
 - [Speicher-Engines](storage.md)
 - [Schema System](schema.md)
 ## Engines
 - [LSM-Tree Speicher](lsm.md)
 - [B-Tree Index](btree.md)
 - [Vektor-Suche](vector.md)
 - [Graph Engine](graph.md)
 - [Volltext-Suche](fts.md)
 - [Spaltenbasierte Speicherung](columnar.md)
 ## API & Clients
 - [Client SDKs](clients.md)
 - [Binärprotokoll](api-binary.md)
 - [HTTP/REST API](api-http.md)
 - [MCP Server](mcp.md)
 ## Betrieb
 - [Performance](performance.md)
 - [Sicherheit](security.md)
 - [Monitoring](monitoring.md)
 - [Backup & Recovery](backup.md)
 - [Fehlerbehebung](troubleshooting.md)
 ## Erweitert
 - [Transaktionen & MVCC](transactions.md)
 - [Verteilte Systeme](distributed.md)
 - [Docker Deployment](docker.md)
 - [Änderungsprotokoll](changelog.md)
 ---
 *Um eine neue Sprache hinzuzufügen, erstellen Sie einen neuen Ordner in `docs/` mit dem Sprachcode (z.B. `docs/de/`).*
@@ -1,57 +0,0 @@
 # BaraDB — Installation
 ## Voraussetzungen
 - **Nim >= 2.2.0** (`curl https://nim-lang.org/choosenim/init.sh -sSf | sh`)
 - **Git**
 - **OpenSSL** (für TLS)
 ## Aus dem Quellcode bauen
 ```bash
 git clone https://github.com/katehonz/barabaDB.git
 cd barabadb
 nimble build_release
 ```
 Die Binärdateien werden im `build/` Verzeichnis erstellt:
 - `build/baradadb` — Datenbank-Server (TCP + HTTP)
 - `build/baramcp` — MCP Server für AI-Agenten
 ## Debug-Build
 ```bash
 nimble build_debug
 ```
 ## Tests ausführen
 ```bash
 nimble test
 ```
 ## Docker
 ```bash
 docker compose up -d
 ```
 ## Verifizierung
 ```bash
 ./build/baradadb --version
 # BaraDB v1.1.6 — Multimodal Database Engine
 ./build/baramcp --data-dir ./data &
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./build/baramcp
 ```
 ## Manuelle Kompilierung
 ```bash
 # Server
 nim c -d:release --opt:speed -o:build/baradadb src/baradadb.nim
 # MCP Server
 nim c -d:release --opt:speed -o:build/baramcp src/baramcp.nim
 ```
@@ -1,64 +0,0 @@
 # LSM-Tree Speicher-Engine
 Die primäre Speicher-Engine in BaraDB mit Log-Structured Merge-Tree Architektur.
 ## Architektur
 ```
 ┌─────────────────────────────────────────────┐
 │                   Writes                     │
 │         (append to WAL + MemTable)           │
 └─────────────────────────────────────────────┘
                       │
                       ▼
 ┌─────────────────────────────────────────────┐
 │                  MemTable                    │
 │         (in-memory sorted buffer)            │
 └─────────────────────────────────────────────┘
                       │
            (when full, flush to SSTable)
                       │
                       ▼
 ┌─────────────────────────────────────────────┐
 │                  SSTable                     │
 │          (sorted string table on disk)       │
 └─────────────────────────────────────────────┘
 ```
 ## Verwendung
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 # Schreiben
 db.put("key1", cast[seq[byte]]("value1"))
 # Lesen
 let (found, value) = db.get("key1")
 # Löschen
 db.delete("key1")
 db.close()
 ```
 ## Funktionen
 - **Write-optimiert**: Append-only Log-Struktur
 - **Dauerhaftigkeit**: Write-Ahead Log (WAL) sichert Crash-Wiederherstellung
 - **Bloom-Filter**: Schnelle negative Lookups
 - **Compaction**: Size-tiered Strategie mischt SSTables
 - **Page-Cache**: LRU-Cache für häufig zugegriffene Seiten
 ## Konfiguration
 ```nim
 var db = newLSMTree(
  path = "./data",
  memTableSize = 64 * 1024 * 1024,  # 64MB
  walEnabled = true,
  bloomFpRate = 0.01
 )
 ```
@@ -1,108 +0,0 @@
 # MCP Server (Model Context Protocol)
 BaraDB enthält einen eingebauten MCP-Server, der es AI-Agenten (Claude, Cursor, etc.) ermöglicht, direkt mit der Datenbank zu interagieren.
 ## Schnellstart
 ```bash
 ./build/baramcp --data-dir ./data
 ```
 Der Server startet im STDIO-Modus und akzeptiert JSON-RPC 2.0 Nachrichten.
 ## Verfügbare Tools
 ### 1. `query` — SQL ausführen
 ```json
 {
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM users WHERE age > ?",
    "params": [25],
    "tenant_id": "company-a",
    "user_id": "alice"
  }
 }
 ```
 Parameterisierte Abfragen mit `?`-Platzhaltern. Multi-Tenant-Support über `tenant_id` und `user_id`.
 ### 2. `vector_search` — Semantische Suche
 ```json
 {
  "name": "vector_search",
  "arguments": {
    "table": "docs",
    "column": "embedding",
    "query_vector": [0.1, 0.2, 0.3],
    "k": 5,
    "metric": "cosine",
    "tenant_id": "company-a"
  }
 }
 ```
 Unterstützte Metriken: `cosine`, `euclidean`, `dot_product`, `manhattan`.
 ### 3. `schema_inspect` — Schema erkunden
 ```json
 {
  "name": "schema_inspect",
  "arguments": {
    "table": "users",
    "tenant_id": "company-a"
  }
 }
 ```
 Gibt Tabellen, Spalten, Typen, Primärschlüssel, Fremdschlüssel, Indizes und RLS-Policies zurück.
 ## Konfiguration in Claude Desktop
 ```json
 {
  "mcpServers": {
    "baradb": {
      "command": "/pfad/zu/build/baramcp",
      "args": ["--data-dir", "/pfad/zu/daten"]
    }
  }
 }
 ```
 ## Konfiguration in Cursor
 ```json
 {
  "mcpServers": {
    "baradb": {
      "command": "/pfad/zu/build/baramcp",
      "args": ["--data-dir", "~/.baradb/data"]
    }
  }
 }
 ```
 ## Multi-Tenant Isolation
 Jede MCP-Anfrage kann `tenant_id` und `user_id` enthalten. Diese werden als Session-Variablen gesetzt:
 - `app.tenant_id` — für RLS-Filterung
 - `app.user_id` — für `current_user`-Referenzen
 RLS-Policies filtern die Daten automatisch basierend auf diesen Variablen.
 ## JSON-RPC 2.0 Protokoll
 Der Server verwendet JSON-RPC 2.0 über STDIO:
 ```json
 // Anfrage
 {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}}
 // Antwort
 {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}
 ```
@@ -1,258 +0,0 @@
 # Monitoring & Observability
 ## Health Checks
 ### HTTP Health Endpoint
 ```bash
 curl http://localhost:9470/health
 ```
 Antwort:
 ```json
 {
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 86400,
  "checks": {
    "storage": "ok",
    "memory": "ok",
    "connections": "ok"
  }
 }
 ```
 ### Readiness Probe
 ```bash
 curl http://localhost:9470/ready
 ```
 Gibt `200 OK` zurück wenn der Server bereit ist Traffic anzunehmen, `503` während des Starts.
 ## Metrics
 ### Prometheus-kompatible Metrics
 ```bash
 curl http://localhost:9470/metrics
 ```
 Beispielausgabe:
 ```
 # HELP baradb_queries_total Total number of queries executed
 # TYPE baradb_queries_total counter
 baradb_queries_total 152340
 # HELP baradb_queries_duration_seconds Query duration histogram
 # TYPE baradb_queries_duration_seconds histogram
 baradb_queries_duration_seconds_bucket{le="0.001"} 45000
 baradb_queries_duration_seconds_bucket{le="0.01"} 120000
 baradb_queries_duration_seconds_bucket{le="0.1"} 148000
 # HELP baradb_storage_lsm_size_bytes LSM-Tree total size
 # TYPE baradb_storage_lsm_size_bytes gauge
 baradb_storage_lsm_size_bytes 2147483648
 # HELP baradb_storage_sstables Number of SSTables
 # TYPE baradb_storage_sstables gauge
 baradb_storage_sstables 12
 # HELP baradb_cache_hit_rate Page cache hit rate
 # TYPE baradb_cache_hit_rate gauge
 baradb_cache_hit_rate 0.94
 # HELP baradb_active_connections Active client connections
 # TYPE baradb_active_connections gauge
 baradb_active_connections 42
 # HELP baradb_txns_active Active transactions
 # TYPE baradb_txns_active gauge
 baradb_txns_active 7
 # HELP baradb_txns_committed_total Total committed transactions
 # TYPE baradb_txns_committed_total counter
 baradb_txns_committed_total 89123
 ```
 ### JSON Metrics
 ```bash
 curl http://localhost:9470/metrics?format=json
 ```
 ## Logging
 ### Log-Level
 | Level | Beschreibung |
 |-------|--------------|
 | `debug` | Detaillierte interne Operationen |
 | `info` | Normale Operationen |
 | `warn` | Behebbare Probleme |
 | `error` | Fehler die Aufmerksamkeit erfordern |
 ### Strukturiertes JSON Logging
 ```bash
 BARADB_LOG_LEVEL=info \
 BARADB_LOG_FORMAT=json \
 BARADB_LOG_FILE=/var/log/baradb/baradb.log \
 ./build/baradadb
 ```
 Beispiel-Log-Eintrag:
 ```json
 {
  "timestamp": "2025-01-15T10:30:00.123Z",
  "level": "info",
  "component": "server",
  "message": "Query executed",
  "query": "SELECT * FROM users",
  "duration_ms": 12,
  "client_ip": "10.0.0.15"
 }
 ```
 ### Textformat
 ```bash
 BARADB_LOG_FORMAT=text ./build/baradadb
 ```
 Ausgabe:
 ```
 2025-01-15T10:30:00.123Z [INFO] server: Query executed | query="SELECT * FROM users" duration_ms=12
 ```
 ## Alerting-Regeln
 ### Prometheus AlertManager
 ```yaml
 groups:
  - name: baradb
    rules:
      - alert: BaraDBHighErrorRate
        expr: rate(baradb_errors_total[5m]) > 0.1
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "BaraDB error rate is high"
      - alert: BaraDBLowCacheHitRate
        expr: baradb_cache_hit_rate < 0.8
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "BaraDB cache hit rate below 80%"
      - alert: BaraDBHighConnections
        expr: baradb_active_connections > 800
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "BaraDB connection count is high"
      - alert: BaraDBDown
        expr: up{job="baradb"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "BaraDB instance is down"
 ```
 ## Grafana Dashboard
 Dashboard ID `baradb-001` importieren oder das bereitgestellte JSON in `monitoring/grafana-dashboard.json` verwenden.
 Wichtige Panels:
 - Queries pro Sekunde
 - Query-Latenz Perzentile (p50, p95, p99)
 - Speichergröße und SSTable-Anzahl
 - Cache Hit Rate
 - Aktive Verbindungen
 - Transaktionsrate
 - Fehlerrate
 ## Distributed Monitoring
 ### Cluster Metrics
 Für Raft-Cluster überwachen:
 ```bash
 curl http://node1:9470/metrics/cluster
 ```
 ```json
 {
  "cluster_id": "baradb-cluster-1",
  "nodes": [
    {"id": "node1", "role": "leader", "health": "healthy"},
    {"id": "node2", "role": "follower", "health": "healthy"},
    {"id": "node3", "role": "follower", "health": "healthy"}
  ],
  "raft_log_index": 15420,
  "raft_commit_index": 15420,
  "shards": 4,
  "replication_lag_ms": 5
 }
 ```
 ## Performance Profiling
 ### Eingebauter CPU Profiler
 ```bash
 curl -X POST http://localhost:9470/debug/pprof/cpu?seconds=30 > cpu.prof
 ```
 ### Memory Profiler
 ```bash
 curl http://localhost:9470/debug/pprof/heap > heap.prof
 ```
 ### Trace
 ```bash
 curl -X POST http://localhost:9470/debug/pprof/trace?seconds=5 > trace.out
 ```
 ## Log-Aggregation
 ### Fluent Bit Konfiguration
 ```ini
 [INPUT]
    Name tail
    Path /var/log/baradb/baradb.log
    Parser json
    Tag baradb
 [OUTPUT]
    Name elasticsearch
    Match baradb
    Host elasticsearch
    Port 9200
    Index baradb-logs
 ```
 ## Troubleshooting mit Metrics
 | Symptom | Metrik | Aktion |
 |---------|--------|--------|
 | Langsame Abfragen | `baradb_queries_duration_seconds` | Cache Hit Rate prüfen, Indizes in Betracht ziehen |
 | Hoher Speicherverbrauch | `process_resident_memory_bytes` | Memtable/Cache-Größen reduzieren |
 | Speicher wächst | `baradb_storage_lsm_size_bytes` | Manuelle Compaction ausführen |
 | Verbindungsfehler | `baradb_active_connections` | Connection Pool erhöhen oder Knoten hinzufügen |
 | Replikations-Lag | `baradb_replication_lag_ms` | Netzwerk prüfen, Ressourcen erhöhen |
@@ -1,174 +0,0 @@
 # BaraDB Performance-Leitfaden
 ## Benchmark-Methodik
 Alle Benchmarks wurden ausgeführt mit:
 - **Compiler**: Nim 2.2.0 mit `-d:release --opt:speed`
 - **CPU**: AMD Ryzen 9 5900X (12 Kerne / 24 Threads)
 - **Memory**: 64 GB DDR4-3600
 - **Storage**: Samsung 980 Pro NVMe SSD
 - **OS**: Ubuntu 24.04 LTS
 Die vollständige Benchmark-Suite ausführen:
 ```bash
 nim c -d:ssl -d:release -r benchmarks/bench_all.nim
 ```
 ## Storage Engine Benchmarks
 ### LSM-Tree Key-Value
 | Metrik | Wert |
 |--------|------|
 | Write Throughput | ~580,000 ops/s |
 | Read Throughput | ~720,000 ops/s |
 | Durchschnittliche Write-Latenz | 1.7 µs |
 | Durchschnittliche Read-Latenz | 1.4 µs |
 | Testdatensatz | 100,000 Keys (16-Byte Keys, 64-Byte Values) |
 Der LSM-Tree verwendet eine 64MB MemTable, WAL fsync bei jedem Write und size-tiered
 Compaction mit 6 Levels.
 ### B-Tree Index
 | Metrik | Wert |
 |--------|------|
 | Insert Throughput | ~1,200,000 ops/s |
 | Point Lookup Throughput | ~1,500,000 ops/s |
 | Range Scan (1000 Keys) | ~0.3 ms |
 | Baumhöhe (100K Keys) | 4 |
 B-Tree Knoten sind 4KB mit Copy-on-Write für MVCC-Kompatibilität.
 ## Vector Engine Benchmarks
 ### HNSW Index
 | Metrik | Wert |
 |--------|------|
 | Insert (dim=128) | ~45,000 vectors/s |
 | Search top-10 (dim=128, n=10K) | ~2 ms |
 | Search top-10 (dim=128, n=100K) | ~8 ms |
 | Speicher pro Vektor (dim=128) | ~580 bytes |
 Parameter: `M=16`, `efConstruction=200`, `efSearch=64`.
 ### SIMD Distanzfunktionen
 | Operation | dim=128 | dim=768 | dim=1536 |
 |-----------|---------|---------|----------|
 | Cosine Distance | 4.2M/s | 850K/s | 420K/s |
 | L2 (Euclidean) | 4.5M/s | 920K/s | 450K/s |
 | Dot Product | 4.8M/s | 980K/s | 480K/s |
 SIMD verwendet AVX2 256-Bit Vektoren mit Loop Unrolling.
 ### Quantization
 | Methode | Genauigkeitsverlust | Speicherreduzierung |
 |---------|--------------------|--------------------|
 | Scalar 8-bit | <1% | 4× |
 | Scalar 4-bit | ~3% | 8× |
 | Product Quantization (PQ16) | ~5% | 16× |
 | Binary | ~15% | 32× |
 ## Full-Text Search Benchmarks
 | Metrik | Wert |
 |--------|------|
 | Index Throughput | ~320,000 docs/s |
 | BM25 Search | ~28,000 queries/s |
 | Fuzzy Search (distance=2) | ~850 queries/s |
 | Wildcard Regex Search | ~4,200 queries/s |
 Testkorpus: 5 einzigartige Dokumente × 2,000 Wiederholungen (~50 Wörter/Dok).
 ## Graph Engine Benchmarks
 | Operation | Throughput | Latenz |
 |-----------|------------|--------|
 | Knoten hinzufügen | ~2.5M ops/s | 0.4 µs |
 | Kante hinzufügen | ~1.8M ops/s | 0.55 µs |
 | BFS (1K Knoten, 5K Kanten) | ~12K Traversierungen/s | 83 µs |
 | DFS (1K Knoten, 5K Kanten) | ~15K Traversierungen/s | 67 µs |
 | Dijkstra kürzester Pfad | — | ~120 µs |
 | PageRank (10 Iterationen) | ~450 Graphen/s | 2.2 ms |
 | Louvain Community Detection | — | ~45 ms |
 ## Protokoll-Benchmarks
 | Protokoll | Verbindungen | Queries/sec | Latenz p99 |
 |-----------|--------------|-------------|------------|
 | Binary (localhost) | 1 | 45,000 | 0.4 ms |
 | Binary (localhost) | 100 | 380,000 | 1.2 ms |
 | HTTP/REST | 1 | 12,000 | 2.1 ms |
 | HTTP/REST | 100 | 95,000 | 5.8 ms |
 | WebSocket | 1 | 18,000 | 1.8 ms |
 ## Query Engine Benchmarks
 | Abfragetyp | Zeilen | Zeit |
 |------------|--------|------|
 | Simple SELECT | 100K | 12 ms |
 | SELECT + WHERE | 100K | 18 ms |
 | SELECT + ORDER BY | 100K | 35 ms |
 | GROUP BY + Aggregates | 100K | 42 ms |
 | INNER JOIN (1K × 1K) | 1M Ergebnis | 85 ms |
 | CTE (2 Ebenen) | 100K | 28 ms |
 | Subquery (EXISTS) | 100K | 22 ms |
 ## Skalierungsverhalten
 ### Vertikale Skalierung
 | Kerne | LSM Write | LSM Read | Vector Search |
 |-------|-----------|----------|---------------|
 | 1 | 580K | 720K | 2.0 ms |
 | 4 | 1.9M | 2.6M | 1.1 ms |
 | 8 | 3.4M | 4.8M | 0.7 ms |
 | 16 | 5.8M | 7.2M | 0.5 ms |
 ### Speicherverbrauch
 | Komponente | Basis-Speicher | Pro-Entity Overhead |
 |------------|----------------|---------------------|
 | LSM MemTable | 64 MB (fest) | ~1.2× Rohdaten |
 | B-Tree | 8 MB (fest) | ~8 bytes/Key |
 | HNSW Index | — | ~580 bytes/Vektor (dim=128) |
 | Graph | — | ~32 bytes/Knoten, ~24 bytes/Kante |
 | FTS Index | — | ~40% von Rohtext |
 | Page Cache | 256 MB (konfigurierbar) | — |
 ## Tuning-Leitfaden
 ### Für Write-intensive Workloads
 ```bash
 export BARADB_MEMTABLE_SIZE_MB=256
 export BARADB_WAL_SYNC_INTERVAL_MS=10
 export BARADB_COMPACTION_INTERVAL_MS=30000
 ```
 ### Für Read-intensive Workloads
 ```bash
 export BARADB_CACHE_SIZE_MB=1024
 export BARADB_BLOOM_BITS_PER_KEY=10
 export BARADB_COMPACTION_INTERVAL_MS=120000
 ```
 ### Für Vector Search
 ```bash
 export BARADB_VECTOR_EF_CONSTRUCTION=200
 export BARADB_VECTOR_EF_SEARCH=128
 export BARADB_VECTOR_M=32
 ```
 ### Für Graph Analytics
 ```bash
 export BARADB_GRAPH_PAGE_RANK_ITERATIONS=20
 export BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0
 ```
@@ -1,240 +0,0 @@
 # Protokoll-Referenz
 BaraDB unterstützt mehrere Protokolle für Client-Kommunikation:
 - **Binär Wire Protokoll** — hochperformant, niedrige Latenz
 - **HTTP/REST API** — sprachunabhängig, einfach zu debuggen
 - **WebSocket** — Streaming und Pub/Sub
 ---
 ## Binär Wire Protokoll
 Das Binärprotokoll verwendet Big-Endian-Kodierung für alle Multi-Byte-Werte.
 ### Verbindungslebenszyklus
 ```
 Client                          Server
  |                               |
  |─── TCP connect ──────────────>|
  |<── TLS handshake (optional) ──|
  |─── Auth message ─────────────>|
  |<── Auth_OK / Error ───────────|
  |─── Query message ────────────>|
  |<── Data / Complete / Error ───|
  |─── Close message ────────────>|
  |<── TCP close ─────────────────|
 ```
 ### Nachrichtenformat
 Jede Nachricht beginnt mit einem 8-Byte-Header:
 ```
 ┌─────────────┬─────────────┬─────────────┬─────────────────────┐
 │  Length     │  Type       │  Sequence   │  Payload            │
 │  (4 bytes)  │  (1 byte)   │  (1 byte)   │  (Length - 6 bytes) │
 │  uint32 BE  │  uint8      │  uint8      │                     │
 └─────────────┴─────────────┴─────────────┴─────────────────────┘
 ```
 ### Nachrichtentypen
 | Typ | ID | Richtung | Beschreibung |
 |------|----|-----------|-------------|
 | Query | 0x01 | C→S | Abfrage ausführen |
 | Insert | 0x02 | C→S | Daten einfügen |
 | Update | 0x03 | C→S | Daten aktualisieren |
 | Delete | 0x04 | C→S | Daten löschen |
 | Ready | 0x05 | S→C | Bereit für nächsten Befehl |
 | Error | 0x06 | S→C | Fehlerantwort |
 | Auth | 0x07 | C→S | Authentifizierungsanfrage |
 | Batch | 0x08 | C→S | Batch-Operationen |
 | Ping | 0x09 | C→S | Keepalive Ping |
 | Data | 0x81 | S→C | Abfrageergebnis-Daten |
 | Complete | 0x82 | S→C | Abfrage abgeschlossen |
 | Auth_OK | 0x83 | S→C | Authentifizierung erfolgreich |
 | Pong | 0x84 | S→C | Keepalive-Antwort |
 ### Query-Nachrichten-Payload
 ```
 ┌──────────────┬──────────────┬────────────────────────────┐
 │ Result Format│ Query Length │ Query String               │
 │ (1 byte)     │ (4 bytes)    │ (Query Length bytes)       │
 │ 0x00=Binary │ uint32 BE    │ UTF-8                     │
 │ 0x01=JSON   │              │                            │
 │ 0x02=Text   │              │                            │
 └──────────────┴──────────────┴────────────────────────────┘
 ```
 ### Data-Nachrichten-Payload
 ```
 ┌──────────────┬─────────────────────────────────────────────┐
 │ Column Count │ Column Definitions + Row Data               │
 │ (2 bytes)    │                                             │
 │ uint16 BE    │                                             │
 └──────────────┴─────────────────────────────────────────────┘
 ```
 ### Spaltendefinition
 ```
 ┌──────────────┬──────────────┬────────────────────────────┐
 │ Name Length  │ Name         │ Type                       │
 │ (2 bytes)    │ (N bytes)    │ (1 byte)                   │
 │ uint16 BE    │ UTF-8        │ Siehe FieldKind-Tabelle    │
 └──────────────┴──────────────┴────────────────────────────┘
 ```
 ### Feldtypen
 | Typ | ID | Größe | Beschreibung |
 |------|----|------|-------------|
 | NULL | 0x00 | 0 | NULL-Wert |
 | BOOL | 0x01 | 1 | true/false |
 | INT8 | 0x02 | 1 | Signed 8-bit Integer |
 | INT16 | 0x03 | 2 | Signed 16-bit Integer |
 | INT32 | 0x04 | 4 | Signed 32-bit Integer |
 | INT64 | 0x05 | 8 | Signed 64-bit Integer |
 | FLOAT32 | 0x06 | 4 | IEEE 754 Single Precision (Big-Endian) |
 | FLOAT64 | 0x07 | 8 | IEEE 754 Double Precision (Big-Endian) |
 | STRING | 0x08 | variable | UTF-8 String (4-Byte Längenpräfix) |
 | BYTES | 0x09 | variable | Raw Bytes (4-Byte Längenpräfix) |
 | ARRAY | 0x0A | variable | Array von Werten |
 | OBJECT | 0x0B | variable | Key-Value Objekt |
 | VECTOR | 0x0C | variable | Float32 Array (4-Byte Längenpräfix, Big-Endian Floats) |
 ### Fehler-Nachrichten-Payload
 ```
 ┌──────────────┬──────────────┬────────────────────────────┐
 │ Error Code   │ Message Len  │ Error Message              │
 │ (4 bytes)    │ (4 bytes)    │ (Message Len bytes)        │
 │ uint32 BE    │ uint32 BE    │ UTF-8                     │
 └──────────────┴──────────────┴────────────────────────────┘
 ```
 ### Beispiel: Raw TCP-Session
 ```bash
 # Verbinden
 nc localhost 9472
 # Senden: Auth-Anfrage (Token "mytoken")
 # Header: length=15, type=0x07, seq=1
 # Payload: token length=7, token="mytoken"
 printf '\x00\x00\x00\x0f\x07\x01\x00\x00\x00\x07mytoken' > /dev/tcp/localhost/9472
 # Empfangen: Auth_OK
 # \x00\x00\x00\x06\x83\x01
 # Senden: Query "SELECT 1"
 printf '\x00\x00\x00\x12\x01\x02\x00\x00\x00\x00\x08SELECT 1' > /dev/tcp/localhost/9472
 # Empfangen: Data + Complete
 ```
 ---
 ## HTTP/REST API
 Basis-URL: `http://localhost:9470/api/v1`
 ### Endpoints
 #### Health
 ```http
 GET /health
 ```
 Antwort:
 ```json
 {
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 86400
 }
 ```
 #### Ready
 ```http
 GET /ready
 ```
 Gibt `200` zurück wenn bereit, `503` während des Starts.
 #### Query
 ```http
 POST /query
 Content-Type: application/json
 Authorization: Bearer <token>
 {
  "query": "SELECT name, age FROM users WHERE age > 18",
  "params": [],
  "format": "json"
 }
 ```
 #### Batch
 ```http
 POST /batch
 Content-Type: application/json
 {
  "queries": [
    "INSERT users { name := 'Alice', age := 30 }",
    "INSERT users { name := 'Bob', age := 25 }"
  ]
 }
 ```
 ### HTTP-Statuscodes
 | Code | Bedeutung |
 |------|----------|
 | 200 | Erfolg |
 | 400 | Bad request (Syntaxfehler) |
 | 401 | Unauthorized (Auth erforderlich) |
 | 403 | Forbidden (ungenügende Berechtigungen) |
 | 404 | Not found (Tabelle/Typ existiert nicht) |
 | 429 | Too many requests (Rate limitiert) |
 | 500 | Internal server error |
 | 503 | Service unavailable (wird gestartet) |
 ---
 ## WebSocket-Protokoll
 URL: `ws://localhost:9471`
 ### Frame-Format
 WebSocket Text-Frames enthalten JSON-Nachrichten:
 ```json
 {
  "id": 1,
  "type": "query",
  "query": "SELECT * FROM users"
 }
 ```
 ### Nachrichtentypen
 | Typ | Richtung | Beschreibung |
 |------|-----------|--------------|
 | `query` | C→S | Abfrage ausführen |
 | `subscribe` | C→S | Änderungen abonnieren |
 | `unsubscribe` | C→S | Abonnement beenden |
 | `ping` | C→S | Keepalive |
 | `result` | S→C | Abfrageergebnis |
 | `notification` | S→C | Änderungsbenachrichtigung |
 | `error` | S→C | Fehler |
 | `pong` | S→C | Keepalive-Antwort |
@@ -1,134 +0,0 @@
 # BaraDB — Schnellstart
 ## Server starten
 ```bash
 ./build/baradadb
 ```
 Der Server startet standardmäßig auf `localhost:9470`.
 ## Verbindung via CLI
 ```bash
 ./build/baradadb --shell
 ```
 ## MCP Server (AI Agenten)
 ```bash
 ./build/baramcp --data-dir ./data
 ```
 Der MCP Server startet im STDIO-Modus und stellt 3 Tools für AI-Agenten bereit: `query`, `vector_search`, `schema_inspect`.
 ## Grundlegende Operationen
 ### Tabelle erstellen
 ```sql
 CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT,
    email TEXT,
    age INTEGER
 );
 ```
 ### Daten einfügen
 ```sql
 INSERT INTO users (id, name, email, age) VALUES (1, 'Alice', 'alice@test.com', 30);
 INSERT INTO users (id, name, email, age) VALUES (2, 'Bob', 'bob@test.com', 25);
 ```
 ### Daten abfragen
 ```sql
 SELECT name, age FROM users WHERE age > 18;
 ```
 ### Indizes erstellen
 ```sql
 -- BTree Index
 CREATE INDEX idx_name ON users(name) USING btree;
 -- Volltext-Index
 CREATE INDEX idx_email_fts ON users(email) USING fts;
 -- Vektor-Index
 CREATE INDEX idx_vec ON items(embedding) USING hnsw;
 ```
 ## Vector Search
 ```sql
 CREATE TABLE docs (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(768));
 CREATE INDEX docs_vec ON docs(embedding) USING hnsw;
 -- Ähnlichkeitssuche
 SELECT id, cosine_distance(embedding, '[0.1, 0.2, ...]') AS dist
 FROM docs ORDER BY dist ASC LIMIT 10;
 ```
 ## Graph Engine
 ```sql
 CREATE GRAPH social;
 INSERT INTO social_nodes (id, node_label) VALUES (1, 'Alice'), (2, 'Bob');
 INSERT INTO social_edges (source_id, dest_id) VALUES (1, 2);
 -- BFS Traversal
 SELECT * FROM GRAPH_TABLE(social MATCH (n)-[r]->(m) ALGORITHM bfs COLUMNS (id, node_label));
 -- PageRank
 SELECT * FROM GRAPH_TABLE(social ALGORITHM pagerank COLUMNS (id, node_label, rank));
 -- Community Detection (Louvain)
 SELECT * FROM GRAPH_TABLE(social ALGORITHM community COLUMNS (id, node_label, community));
 -- Kürzester Pfad
 SELECT * FROM GRAPH_TABLE(social ALGORITHM shortest_path START 1 END 2 COLUMNS (id, node_label));
 -- Knoten-Ähnlichkeit (Jaccard)
 SELECT similarity_nodes('social', 'jaccard') AS result;
 ```
 ## AI Pipeline
 ```sql
 -- Text in Chunks zerlegen
 SELECT chunk('Langer Text hier...', 1024, 128) AS result;
 -- Embedding generieren (mit konfiguriertem externen Service)
 SELECT embed_text('Suchanfrage') AS result;
 -- Schema-Prompt für LLM generieren
 SELECT schema_prompt('users') AS result;
 -- Natural Language → SQL (mit konfiguriertem LLM)
 SELECT nl_to_sql('Zeige alle Benutzer über 25', 'users') AS result;
 -- Cypher zu BaraQL übersetzen
 SELECT cypher('MATCH (a)-[r]->(b) RETURN a.node_label, b.node_label') AS result;
 ```
 ## HTTP/REST API
 ```bash
 curl -X POST http://localhost:9470/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users"}'
 ```
 ## Konfiguration
 ```bash
 # Umgebungsvariablen
 export BARADB_DATA_DIR=./data
 export BARADB_EMBED_ENDPOINT=http://localhost:11434/api/embeddings
 export BARADB_EMBED_MODEL=nomic-embed-text
 export BARADB_LLM_ENDPOINT=http://localhost:11434/api/generate
 export BARADB_LLM_MODEL=llama3
 ```
@@ -1,55 +0,0 @@
 # Schema-System
 BaraDB verwendet ein Schema-first Design mit Typvererbung und automatischen Migrationen.
 ## Typen definieren
 ```nim
 import barabadb/schema/schema
 var s = newSchema()
 let person = newType("Person")
 person.addProperty("name", "str", required = true)
 person.addProperty("age", "int32")
 s.addType("default", person)
 ```
 ## Typvererbung
 ```nim
 let employee = newType("Employee")
 employee.setBases(@["Person"])
 employee.addProperty("department", "str")
 s.addType("default", employee)
 # Vererbung auflösen — Employee erhält name, age, department
 let resolved = s.resolveInheritance(employee)
 ```
 ## Schema-Operationen
 ### Diff
 Zwei Schemata vergleichen:
 ```nim
 let diff = s.diff(oldSchema, newSchema)
 ```
 ### Migrationen
 Schema-Änderungen werden verfolgt und können Migrationsskripte generieren.
 ## Eigenschaftstypen
 | Typ | Beschreibung |
 |------|-------------|
 | `str` | String |
 | `int32` | 32-Bit Integer |
 | `int64` | 64-Bit Integer |
 | `float32` | 32-Bit Float |
 | `float64` | 64-Bit Float |
 | `bool` | Boolean |
 | `datetime` | Datums-/Zeitwert |
 | `bytes` | Binärdaten |
@@ -1,184 +0,0 @@
 # Sicherheitsleitfaden
 ## TLS/SSL-Verschlüsselung
 BaraDB unterstützt TLS 1.3 für alle Protokolle (Binary, HTTP, WebSocket). Wenn kein
 Zertifikat bereitgestellt wird, generiert der Server automatisch ein selbstsigniertes Zertifikat
 beim Start für Zero-Configuration-Verschlüsselung.
 ### Eigene Zertifikate verwenden
 ```bash
 # Vorhandene Zertifikate bereitstellen
 BARADB_TLS_ENABLED=true \
 BARADB_CERT_FILE=/etc/baradb/server.crt \
 BARADB_KEY_FILE=/etc/baradb/server.key \
 ./build/baradadb
 ```
 ### Selbstsignierte Zertifikate generieren
 ```bash
 openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
  -days 365 -nodes -subj "/CN=localhost"
 ```
 ### Let's Encrypt (Production)
 Certbot verwenden und BaraDB auf die generierten Dateien zeigen:
 ```bash
 sudo certbot certonly --standalone -d db.example.com
 BARADB_CERT_FILE=/etc/letsencrypt/live/db.example.com/fullchain.pem \
 BARADB_KEY_FILE=/etc/letsencrypt/live/db.example.com/privkey.pem \
 ./build/baradadb
 ```
 ## Authentifizierung
 ### JWT-basierte Authentifizierung
 BaraDB verwendet JWT (JSON Web Tokens) mit HMAC-SHA256-Signatur.
 #### Authentifizierung aktivieren
 ```bash
 BARADB_AUTH_ENABLED=true \
 BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
 ./build/baradadb
 ```
 #### Tokens erstellen
 ```nim
 import barabadb/protocol/auth
 var am = newAuthManager("your-secret-key")
 let token = am.createToken(JWTClaims(
  sub: "user1",
  role: "admin",
  exp: getTime() + 24.hours
 ))
 ```
 #### Rollenbasierte Zugriffskontrolle
 | Rolle | Berechtigungen |
 |------|---------------|
 | `admin` | Voller Zugriff |
 | `write` | Lesen + Schreiben |
 | `read` | Nur Lesen |
 | `monitor` | Nur Metrics und Health |
 #### Tokens verwenden
 ```bash
 curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9470/api/query \
  -d '{"query": "SELECT * FROM users"}'
 ```
 ## Rate Limiting
 Token-Bucket Rate Limiting verhindert Missbrauch:
 ```nim
 import barabadb/protocol/ratelimit
 var rl = newRateLimiter(
  rlaTokenBucket,
  globalRate = 10000,      # 10K req/s global
  perClientRate = 1000,    # 1K req/s pro IP/Token
  burstSize = 100           # 100 req Burst erlauben
 )
 if not rl.allowRequest("client-ip"):
  return error("Rate limit exceeded")
 ```
 ## Netzwerksicherheit
 ### Bind-Adresse
 Standardmäßig bindet BaraDB an `127.0.0.1` (nur Localhost). Für Production:
 ```bash
 # An alle Interfaces binden (hinter Firewall oder Reverse Proxy)
 BARADB_ADDRESS=0.0.0.0 ./build/baradadb
 # An spezifisches internes Interface binden
 BARADB_ADDRESS=10.0.0.5 ./build/baradadb
 ```
 ### Firewall-Regeln
 ```bash
 # Nur Application-Server erlauben
 sudo ufw allow from 10.0.0.0/8 to any port 9472
 sudo ufw allow from 10.0.0.0/8 to any port 9470
 # Externen Zugriff auf Management-Ports blockieren
 sudo ufw deny 9471  # WebSocket (nur für internen Gebrauch)
 ```
 ## Datenverschlüsselung at Rest
 ### OS-Level-Verschlüsselung
 LUKS für Vollständige-Festplatten-Verschlüsselung verwenden:
 ```bash
 cryptsetup luksFormat /dev/nvme0n1p2
 cryptsetup open /dev/nvme0n1p2 baradb-crypt
 mkfs.ext4 /dev/mapper/baradb-crypt
 mount /dev/mapper/baradb-crypt /var/lib/baradb
 ```
 ### Applikations-Level-Verschlüsselung
 BaraDB unterstützt transparente Verschlüsselung von SSTable-Dateien:
 ```bash
 BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
 ./build/baradadb
 ```
 ## Audit Logging
 Alle Abfragen und administrativen Aktionen werden geloggt:
 ```json
 {
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "info",
  "event": "query_executed",
  "client_ip": "10.0.0.15",
  "user": "app_user",
  "query": "SELECT * FROM users WHERE id = ?",
  "duration_ms": 12,
  "rows_returned": 1
 }
 ```
 Audit Logging aktivieren:
 ```bash
 BARADB_LOG_LEVEL=info \
 BARADB_LOG_FORMAT=json \
 BARADB_LOG_FILE=/var/log/baradb/audit.log \
 ./build/baradadb
 ```
 ## Sicherheits-Checkliste
 - [ ] Standard-JWT-Geheimnis ändern
 - [ ] TLS mit gültigen Zertifikaten aktivieren
 - [ ] An spezifische Interfaces binden
 - [ ] Authentifizierung in Production aktivieren
 - [ ] Rate Limiting konfigurieren
 - [ ] Audit Logging aktivieren
 - [ ] Daten at Rest verschlüsseln (LUKS oder App-Level)
 - [ ] BaraDB als Non-Root-Benutzer ausführen
 - [ ] Firewall-Regeln restriktiv halten
 - [ ] JWT-Geheimnisse regelmäßig rotieren
@@ -1,78 +0,0 @@
 # Speicher-Engines
 BaraDB bietet mehrere Speicher-Engines, optimiert für verschiedene Zugriffsmuster.
 ## LSM-Tree (Key-Value)
 Die primäre Speicher-Engine mit write-optimierter Append-only Log-Struktur.
 ### Verwendung
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.close()
 ```
 ### Komponenten
 - **MemTable**: In-Memory sortierter Puffer
 - **WAL**: Write-Ahead Log für Dauerhaftigkeit
 - **SSTable**: Sortierte String-Tabellen auf Disk
 - **Bloom-Filter**: Probabilistische Mengenmitgliedschaft
 - **Compaction**: Size-tiered Strategie mit Level-Management
 - **Page-Cache**: LRU-Cache mit Trefferraten-Verfolgung
 ## B-Tree Index
 Geordneter Index für Bereichsabfragen und Point-Lookups.
 ### Verwendung
 ```nim
 import barabadb/storage/btree
 var btree = newBTreeIndex[string, string]()
 btree.insert("key1", "value1")
 let values = btree.get("key1")
 let range = btree.scan("key_a", "key_z")
 ```
 ## Write-Ahead Log (WAL)
 Sichert Dauerhaftigkeit von Schreiboperationen.
 ```nim
 import barabadb/storage/wal
 var wal = newWAL("./wal")
 wal.append("txn1", "SET key1 value1")
 wal.flush()
 ```
 ## Bloom-Filter
 Probabilistische Datenstruktur für schnelle negative Lookups.
 ```nim
 import barabadb/storage/bloom
 var filter = newBloomFilter(10000, 0.01)
 filter.add("key1")
 if filter.mightContain("key1"):
  echo "possibly exists"
 ```
 ## Memory-mapped I/O
 Effizienter Dateizugriff mittels mmap.
 ```nim
 import barabadb/storage/mmap
 var mapped = mmapFile("./data/file.dat")
 let data = mapped.read(0, 100)
 ```
@@ -1,78 +0,0 @@
 # Transaktionen & MVCC
 MVCC (Multi-Version Concurrency Control) mit Snapshot-Isolation und Deadlock-Erkennung.
 ## Verwendung
 ```nim
 import barabadb/core/mvcc
 var tm = newTxnManager()
 let txn = tm.beginTxn()
 # Schreiboperationen
 discard tm.write(txn, "key1", cast[seq[byte]]("value1"))
 discard tm.write(txn, "key2", cast[seq[byte]]("value2"))
 # Savepoint
 tm.savepoint(txn)
 discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
 discard tm.rollbackToSavepoint(txn)  # rückgängig machen key3
 # Commit
 discard tm.commit(txn)
 ```
 ## Transaktionsisolation
 BaraDB verwendet **Snapshot-Isolation**:
 - Leser blockieren keine Schreiber
 - Schreiber blockieren keine Leser
 - Jede Transaktion sieht einen konsistenten Snapshot
 ## Deadlock-Erkennung
 ```nim
 import barabadb/core/deadlock
 var detector = newDeadlockDetector()
 if detector.detectCycle(txn1, txn2):
  echo "Deadlock erkannt!"
 ```
 ## Write-Ahead Log
 ```nim
 import barabadb/storage/wal
 var wal = newWAL("./wal")
 wal.append(txnId, "SET key value")
 wal.flush()
 ```
 ## Savepoints
 Verschachtelte Transaktions-Savepoints:
 ```nim
 tm.savepoint(txn, "sp1")
 # ... Operationen ...
 tm.rollbackToSavepoint(txn, "sp1")
 ```
 ## Formale Verifikation
 Das MVCC / Snapshot-Isolation Protokoll ist formal in TLA+ spezifiziert:
 - **Spec:** `formal-verification/mvcc.tla`
 - **Verifizierte Eigenschaften:**
  - `NoDirtyReads` — Transaktionen lesen niemals nicht-committete Daten
  - `ReadOwnWrites` — Transaktionen sehen immer ihre eigenen Schreiboperationen
  - `WriteWriteConflict` — First-committer-wins (keine zwei committete Transaktionen schreiben denselben Schlüssel)
 Lokale TLC-Ausführung:
 ```bash
 cd formal-verification
 java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
 ```
@@ -1,335 +0,0 @@
 # Fehlerbehebungsleitfaden
 ## Installationsprobleme
 ### Nim nicht gefunden
 ```
 im: command not found
 ```
 **Lösung:**
 ```bash
 # Linux/macOS
 curl https://nim-lang.org/choosenim/init.sh -sSf | sh
 # Zu PATH hinzufügen
 echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc
 source ~/.bashrc
 ```
 ### SSL-Kompilierungsfehler
 ```
 Error: BaraDB requires SSL support. Compile with -d:ssl
 ```
 **Lösung:** Immer mit `-d:ssl` kompilieren:
 ```bash
 nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
 ```
 ### Fehlende Abhängigkeiten
 ```
 Error: cannot open file: hunos
 ```
 **Lösung:**
 ```bash
 nimble install -d -y
 ```
 ## Laufzeitprobleme
 ### Port bereits in Verwendung
 ```
 Error: unhandled exception: Address already in use [OSError]
 ```
 **Lösung 1:** Port ändern:
 ```bash
 BARADB_PORT=5433 ./build/baradadb
 ```
 **Lösung 2:** Bestehenden Prozess beenden:
 ```bash
 lsof -ti:9472 | xargs kill -9
 # oder
 fuser -k 9472/tcp
 ```
 ### Permission Denied auf Datenverzeichnis
 ```
 Error: cannot create directory: Permission denied
 ```
 **Lösung:**
 ```bash
 mkdir -p ./data
 chmod 755 ./data
 # Oder anderes Verzeichnis verwenden
 BARADB_DATA_DIR=/tmp/baradb_data ./build/baradadb
 ```
 ### Out of Memory
 ```
 Error: out of memory
 ```
 **Lösung:** Speicherverbrauch reduzieren:
 ```bash
 BARADB_MEMTABLE_SIZE_MB=32 \
 BARADB_CACHE_SIZE_MB=128 \
 BARADB_VECTOR_EF_CONSTRUCTION=100 \
 ./build/baradadb
 ```
 ### Disk Full
 ```
 Error: No space left on device
 ```
 **Lösung:**
 ```bash
 # Disk-Nutzung prüfen
 df -h
 # Compaction auslösen um Platz freizugeben
 curl -X POST http://localhost:9470/api/admin/compact
 # Oder manuell
 ./build/baradadb --compact
 ```
 ## Abfrageprobleme
 ### Syntaxfehler
 ```
 Error: Syntax error at position 15: unexpected token
 ```
 **Lösung:** Abfragesyntax prüfen:
 ```sql
 -- Korrekt
 SELECT name, age FROM users WHERE age > 18;
 -- Inkorrekt (fehlendes Komma)
 SELECT name age FROM users WHERE age > 18;
 ```
 ### Tabelle nicht gefunden
 ```
 Error: Table 'users' does not exist
 ```
 **Lösung:** Zuerst Schema erstellen:
 ```sql
 CREATE TYPE User {
  name: str,
  age: int32
 };
 ```
 ### Typ-Mismatch
 ```
 Error: Cannot compare int32 with str
 ```
 **Lösung:** Korrekte Typen verwenden:
 ```sql
 -- Korrekt
 SELECT * FROM users WHERE age > 18;
 -- Inkorrekt
 SELECT * FROM users WHERE age > '18';
 ```
 ### Timeout
 ```
 Error: Query execution timeout
 ```
 **Lösung:** LIMIT hinzufügen oder optimieren:
 ```sql
 -- Limit hinzufügen
 SELECT * FROM large_table LIMIT 1000;
 -- Index verwenden
 SELECT * FROM users WHERE id = 123;
 ```
 ## Verbindungsprobleme
 ### Connection Refused
 ```
 Connection refused: localhost:9472
 ```
 **Lösung:**
 ```bash
 # Prüfen ob Server läuft
 ps aux | grep baradadb
 # Server starten
 ./build/baradadb
 # Firewall prüfen
 sudo ufw status
 sudo ufw allow 9472
 ```
 ### Authentifizierung fehlgeschlagen
 ```
 Error: Authentication failed
 ```
 **Lösung:**
 ```bash
 # Prüfen ob JWT-Geheimnis übereinstimmt
 BARADB_AUTH_ENABLED=true \
 BARADB_JWT_SECRET="correct-secret" \
 ./build/baradadb
 ```
 ## Performance-Probleme
 ### Langsame Abfragen
 **Diagnose:**
 ```bash
 # Abfrageplan prüfen
 curl -X POST http://localhost:9470/api/explain \
  -d '{"query": "SELECT * FROM large_table"}'
 ```
 **Lösungen:**
 1. Indizes hinzufügen:
 ```sql
 CREATE INDEX idx_users_name ON users(name);
 ```
 2. LIMIT verwenden:
 ```sql
 SELECT * FROM users LIMIT 100;
 ```
 3. Cache erhöhen:
 ```bash
 BARADB_CACHE_SIZE_MB=1024 ./build/baradadb
 ```
 ### Hohe CPU-Nutzung
 **Ursachen:**
 - Compaction läuft
 - Große Vektor-Suche ohne HNSW
 - Komplexe Graph-Traversierung
 **Lösungen:**
 ```bash
 # Compaction-Intervall anpassen
 BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb
 # Approximative Vektor-Suche verwenden
 SELECT /*+ APPROXIMATE */ * FROM vectors
 ORDER BY cosine_distance(embedding, [...])
 LIMIT 10;
 ```
 ## Cluster-Probleme
 ### Raft Split-Brain
 ```
 Warning: Multiple leaders detected
 ```
 **Lösung:** Ungerade Anzahl von Knoten sicherstellen (3, 5, 7). Minority-Partition neu starten.
 ### Replikations-Lag
 ```
 Warning: Replication lag > 10s
 ```
 **Lösung:**
 ```bash
 # Netzwerk-Latenz prüfen
 ping replica-node
 # Replikations-Threads erhöhen
 BARADB_REPLICATION_THREADS=4 ./build/baradadb
 # Auf Async-Replikation umschalten
 BARADB_REPLICATION_MODE=async
 ```
 ## Datenkorruption
 ### Prüfsummen-Mismatch
 ```
 Error: SSTable checksum mismatch
 ```
 **Lösung:**
 ```bash
 # Korrupte SSTable entfernen (Daten werden aus WAL wiederhergestellt)
 rm ./data/sstables/corrupted.sst
 # Neustarten und wiederherstellen
 ./build/baradadb --recover
 ```
 ## Debug-Modus
 Debug-Logging für detaillierte Diagnostik aktivieren:
 ```bash
 BARADB_LOG_LEVEL=debug \
 BARADB_LOG_FILE=/tmp/baradb_debug.log \
 ./build/baradadb
 ```
 ## Hilfe erhalten
 Wenn das Problem weiterhin besteht:
 1. Logs prüfen: `tail -f /var/log/baradb/baradb.log`
 2. Metrics prüfen: `curl http://localhost:9470/metrics`
 3. Diagnostik ausführen: `./build/baradadb --diagnose`
 4. Issue öffnen mit:
   - BaraDB Version (`./build/baradadb --version`)
   - OS und Architektur
   - Relevante Log-Auszüge
   - Schritte zur Reproduktion
@@ -1,56 +0,0 @@
 # Benutzerdefinierte Funktionen
 BaraQL mit benutzerdefinierten Funktionen erweitern.
 ## Verwendung
 ```nim
 import barabadb/query/udf
 var reg = newUDFRegistry()
 # Standard-Bibliothek registrieren
 reg.registerStdlib()  # abs, sqrt, pow, lower, upper, len, trim, substr, toString, toInt
 # Benutzerdefinierte Funktion
 reg.register("greet", @[UDFParam(name: "name", typeName: "str")],
  "str", proc(args: seq[Value]): Value =
    return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!"))
 ```
 ## Standard-Bibliotheksfunktionen
 | Funktion | Beschreibung | Beispiel |
 |----------|-------------|---------|
 | `abs(n)` | Absoluter Wert | `abs(-5)` → 5 |
 | `sqrt(n)` | Quadratwurzel | `sqrt(16)` → 4 |
 | `pow(n, e)` | Potenz | `pow(2, 3)` → 8 |
 | `lower(s)` | Kleinbuchstaben | `lower('ABC')` → 'abc' |
 | `upper(s)` | Großbuchstaben | `upper('abc')` → 'ABC' |
 | `len(s)` | Länge | `len('hello')` → 5 |
 | `trim(s)` | Leerzeichen trimmen | `trim(' hello ')` → 'hello' |
 | `substr(s, start, len)` | Substring | `substr('hello', 0, 3)` → 'hel' |
 | `toString(n)` | In String konvertieren | `toString(123)` → '123' |
 | `toInt(s)` | In Integer konvertieren | `toInt('123')` → 123 |
 ## Funktionsregistrierung
 ```nim
 reg.register(
  name: "my_function",
  params: @[
    UDFParam(name: "arg1", typeName: "str"),
    UDFParam(name: "arg2", typeName: "int32")
  ],
  returnType: "str",
  body: proc(args: seq[Value]): Value =
    # Implementierung
    result = Value(kind: vkString, strVal: "")
 )
 ```
 ## UDFs in Abfragen verwenden
 ```sql
 SELECT greet(name) FROM users;
 ```
@@ -1,129 +0,0 @@
 # Vektor-Suche
 Native HNSW und IVF-PQ Indizes für Ähnlichkeitssuche mit vollständiger SQL-Integration.
 ## SQL — Vektor-Spalten
 ```sql
 CREATE TABLE items (
    id INT PRIMARY KEY,
    embedding VECTOR(768)
 );
 ```
 Der `VECTOR(n)`-Typ speichert float32-Arrays mit fester Dimension `n`.
 ## Vektoren einfügen
 ```sql
 INSERT INTO items (id, embedding) VALUES (1, '[0.1, 0.2, 0.3, ...]');
 ```
 ## Vektor-Distanzfunktionen
 ```sql
 -- Kosinus-Distanz (0 = identisch, 1 = orthogonal)
 SELECT id, cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
 -- Euklidische / L2 Distanz
 SELECT id, euclidean_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
 SELECT id, embedding <-> '[0.1, 0.2, 0.3]' AS dist FROM items;
 -- Inneres Produkt (negativ für Minimierung)
 SELECT id, inner_product(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
 -- Manhattan / L1 Distanz
 SELECT id, l1_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items;
 ```
 ## Vektor-Indizes
 ```sql
 -- HNSW-Index für approximative Nächste-Nachbarn-Suche
 CREATE INDEX idx_items_vec ON items(embedding) USING hnsw;
 -- Der Index wird bei INSERT und UPDATE automatisch aktualisiert
 ```
 ## Hybrid RAG Search
 ```sql
 -- Kombinierte Vektor- + Volltext-Suche mit RRF-Reranking
 SELECT hybrid_search('AI query', embedding, content, 10) AS result;
 -- Gefilterte hybride Suche
 SELECT hybrid_search_filtered('AI query', embedding, content, 10, 'category', 'news') AS result;
 ```
 ## AI Pipeline
 ### Text-Chunking
 ```sql
 -- Text in überlappende Chunks zerlegen
 SELECT chunk('Langer Text hier...', 1024, 128) AS result;
 -- Ergebnis: [{"index":0, "text":"...", "size":124}, ...]
 ```
 ### Embedding-Generierung
 ```sql
 -- Externen Embedding-Service aufrufen (konfiguriert via Umgebungsvariablen)
 SELECT embed_text('Suchtext hier') AS result;
 ```
 Umgebungsvariablen für den Embedder:
 ```bash
 export BARADB_EMBED_ENDPOINT=http://localhost:11434/api/embeddings
 export BARADB_EMBED_MODEL=nomic-embed-text
 ```
 ### Auto-Embedding bei INSERT
 Wenn eine VECTOR-Spalte NULL ist, aber eine TEXT-Spalte einen Wert hat, wird das Embedding automatisch generiert (falls ein Embedder konfiguriert ist).
 ```sql
 CREATE TABLE docs (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(768));
 CREATE INDEX docs_vec ON docs(embedding) USING hnsw;
 -- embedding wird automatisch gefüllt
 INSERT INTO docs (id, content) VALUES (1, 'Dieser Text wird automatisch embedded');
 ```
 ## Distanzmetriken
 | Metrik | SQL-Funktion | Beschreibung |
 |--------|-------------|-------------|
 | `cosine` | `cosine_distance(a, b)` | Kosinus-Distanz |
 | `euclidean` | `euclidean_distance(a, b)` / `<->` | L2-Distanz |
 | `dotproduct` | `inner_product(a, b)` | Negatives Skalarprodukt |
 | `manhattan` | `l1_distance(a, b)` | L1-Distanz |
 ## Index-Typen
 ### HNSW (Standard)
 ```nim
 import barabadb/vector/engine
 var hnsw = newHNSWIndex(dimensions = 128, m = 16, efConstruction = 200)
 ```
 ### IVF-PQ
 ```nim
 var ivfpq = newIVFPQIndex(dimensions = 128, numCentroids = 256, subQuantizers = 8)
 ```
 ## Native Nim API
 ```nim
 import barabadb/vector/engine
 var idx = newHNSWIndex(dimensions = 128)
 idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable)
 let results = idx.search(queryVector, k = 10)
 let filtered = idx.searchWithFilter(queryVector, k = 10,
  filter = proc(meta: Table[string, string]): bool = return "category" in meta)
 ```
@@ -2,6 +2,9 @@
 BaraDB provides multiple backup strategies ranging from full snapshots to incremental and online consistent backups.
 > ⚠️ **Multi-Database Setup**
 > BaraDB supports multiple databases (`CREATE DATABASE`). Each database has its own isolated data directory (e.g. `data/databases/<name>/`). Backup, repair, checkpoint, and migration commands operate on **one directory at a time**. If you use multiple databases, run the commands for each database separately or back up the entire `data/databases/` parent directory.
 ## Architecture
 ```
@@ -17,6 +20,14 @@ BaraDB provides multiple backup strategies ranging from full snapshots to increm
 └─────────────────────────────────────────┘
 ```
 ## Backup Tool
 The backup tool is shipped as `src/barabadb/core/backup.nim`. Build it before use:
 ```bash
 nim c -o:build/backup src/barabadb/core/backup.nim
 ```
 ## SSTable Integrity (v3 CRC Footer)
 Every SSTable file written by BaraDB includes a CRC32 footer:
@@ -37,24 +48,24 @@ This enables independent verification of each SSTable:
 ```bash
 # Via Nim API
 import barabadb/storage/lsm
-let (ok, msg) = verifySSTable("data/sstables/1.sst")
+let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
 ```
-## Storage Repair (`baradb repair`)
+## Storage Repair (`baradadb repair`)
-If corruption is suspected, run the repair tool:
+If corruption is suspected, run the repair tool against a specific database directory:
 ```bash
 # Dry run — preview only
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 # Full repair — verify, move corrupt files, replay WAL
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 ```
 **What repair does:**
 1. Scans all `sstables/*.sst` and verifies CRC
-2. Moves corrupt SSTables to `data/corrupt/`
+2. Moves corrupt SSTables to `<data-dir>/corrupt/`
 3. Replays WAL to recover unflushed committed data
 4. Reports results
@@ -78,6 +89,8 @@ Benefits:
 - **Fast startup** — load from MANIFEST instead of directory scan
 - **Orphan detection** — `checkStorageConsistency()` reports extra/missing files
 In a multi-database setup, each database maintains its own independent MANIFEST inside its data directory.
 ## WAL Rotation
 The Write-Ahead Log rotates when it reaches 64MB:
@@ -99,7 +112,7 @@ Rotation happens:
 A checkpoint creates a consistent storage boundary without stopping the server:
 ```bash
-./build/baradadb checkpoint --data-dir=./data
+./build/baradadb checkpoint --data-dir=./data/databases/default
 ```
 **How it works:**
@@ -112,18 +125,20 @@ The freeze takes **< 1ms**; the flush proceeds concurrently with writes.
 ## Backup Commands
 > Build the backup tool first: `nim c -o:build/backup src/barabadb/core/backup.nim`
 ### Full Backup (tar.gz)
 ```bash
-./build/backup backup --data-dir=./data --output=backup_$(date +%s).tar.gz
+./build/backup backup --data-dir=./data/databases/default --output=backup_$(date +%s).tar.gz
 ```
-Archives the entire data directory.
+Archives the entire data directory of the specified database.
 ### Incremental Backup
 ```bash
-./build/backup incremental --data-dir=./data --output=backup_inc_$(date +%s).tar.gz
+./build/backup incremental --data-dir=./data/databases/default --output=backup_inc_$(date +%s).tar.gz
 ```
 Includes only:
@@ -137,25 +152,25 @@ All SSTables are **CRC-verified** before archiving.
 ### Online Consistent Backup
 ```bash
-./build/baradadb backup --online --output=backup_online_$(date +%s).tar.gz
+./build/backup backup --online --data-dir=./data/databases/default --output=backup_online_$(date +%s).tar.gz
 ```
 Equivalent to:
 1. `checkpoint`
 2. `incremental backup`
-**Safe to run while the server is stopped.** If the server is running, use `backup incremental` instead.
+Safe to run while the server is running. The checkpoint creates a consistent snapshot, then the incremental backup archives it.
 ## SSTable Version Migration
-If you have legacy v1/v2 SSTables, migrate them to v3:
+If you have legacy v1/v2 SSTables, migrate them to v3 per database:
 ```bash
 # Preview
-./build/baradadb migrate --data-dir=./data --dry-run
+./build/baradadb migrate --data-dir=./data/databases/default --dry-run
 # Migrate
-./build/baradadb migrate --data-dir=./data
+./build/baradadb migrate --data-dir=./data/databases/default
 ```
 Migration rewrites each legacy SSTable with the current v3 format (CRC footer) and updates the MANIFEST.
@@ -166,31 +181,35 @@ Migration rewrites each legacy SSTable with the current v3 format (CRC footer) a
 ```bash
 # Repair moves corrupt files and replays WAL
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 # Verify consistency
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 ```
-### Scenario 2: Restore from Backup
+### Scenario 2: Restore from Backup (Single Database)
 ```bash
 # Stop the server
-# Extract backup
+# Extract backup into the database directory
-tar -xzf backup_1234567890.tar.gz -C ./data
+tar -xzf backup_1234567890.tar.gz -C ./data/databases/default
 # Restart — LSMTree loads from MANIFEST
 ./build/baradadb
 ```
-### Scenario 3: Complete Data Loss
+### Scenario 3: Restore All Databases
 If you back up the entire `data/databases/` tree:
 ```bash
 # 1. Extract latest backup
 tar -xzf backup_latest.tar.gz -C ./data
-# 2. Run repair to replay any available WAL
+# 2. Run repair for each database to replay any available WAL
-./build/baradadb repair --data-dir=./data
+for db in ./data/databases/*/; do
  ./build/baradadb repair --data-dir="$db" --dry-run
 done
 # 3. Start server
 ./build/baradadb
@@ -53,7 +53,7 @@ All notable changes to BaraDB are documented in this file.
 - **Cypher Compatibility Layer**:
  - `cypher()` SQL function — translates `MATCH (a)-[r]->(b) RETURN ...` to GRAPH_TABLE
  - Automatic Cypher → BaraQL conversion
- **German Documentation** — Full documentation set in German (`docs/de/`)
+- **Bulgarian Documentation** — Full documentation set in Bulgarian (`docs/bg/`) (replaces removed German, Russian, Arabic, Farsi, Turkish, and Chinese docs)
 ### Changed
@@ -2,6 +2,9 @@
 BaraDB supports distributed deployment with Raft consensus, sharding, and replication.
 > ⚠️ **Multi-Database Limitation**
 > The distributed modules (Raft, sharding, and replication) are currently wired to the **`default`** database only. If you use multiple databases (`CREATE DATABASE`, `USE DATABASE`), distributed features do not yet span across them. Each database would need its own cluster setup.
 ## Raft Consensus
 Leader election and log replication:
@@ -41,6 +41,32 @@ let diff = s.diff(oldSchema, newSchema)
 Schema changes are tracked and can generate migration scripts.
 ## SQL Migrations
 BaraDB supports SQL-level migrations executed through BaraQL:
 ```sql
 -- Create a migration table
 CREATE MIGRATION TABLE my_migration;
 -- Apply pending migrations
 MIGRATION UP;
 -- Rollback last migration
 MIGRATION DOWN;
 -- Apply all pending migrations in batch
 MIGRATION UP BATCH;
 -- Dry-run to preview changes
 MIGRATION DRYRUN;
 -- Check migration status
 MIGRATION STATUS;
 ```
 Migration scripts are stored inside each database's LSMTree and are isolated per database. When using multiple databases, run `USE DATABASE <name>` before executing migration commands.
 ## Property Types
 | Type | Description |
@@ -6,12 +6,15 @@ BaraDB provides multiple storage engines optimized for different access patterns
 The primary storage engine with write-optimized append-only log structure.
 > **Multi-Database Note**
 > Each database gets its own isolated data directory (e.g. `data/databases/<name>/`). The examples below use `./data` as a placeholder — substitute with your actual database path.
 ### Usage
 ```nim
 import barabadb/storage/lsm
-var db = newLSMTree("./data")
+var db = newLSMTree("./data/databases/default")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.close()
@@ -1,62 +0,0 @@
 # API پروتکل باینری
 پروتکل سطح پایین برای اتصالات با کارایی بالا.
 ## فرمت پیام
 همه پیام‌ها از ترتیب big-endian استفاده می‌کنند:
 ```
 ┌────────┬────────┬────────┬────────┬─────────────┐
 │ Length │  Type  │  Seq   │ Status │   Payload   │
 │ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │  N bytes    │
 └────────┴────────┴────────┴────────┴─────────────┘
 ```
 ## انواع پیام
 ### Query (0x01)
 ```nim
 let msg = makeQueryMessage(seq, "SELECT * FROM users")
 ```
 ### Insert (0x02)
 ```nim
 let msg = makeInsertMessage(seq, "users", data)
 ```
 ### Update (0x03)
 ```nim
 let msg = makeUpdateMessage(seq, "users", updates, where)
 ```
 ### Delete (0x04)
 ```nim
 let msg = makeDeleteMessage(seq, "users", where)
 ```
 ### Ready (0x05)
 ```nim
 let msg = makeReadyMessage(seq)
 ```
 ### Error (0x06)
 ```nim
 let msg = makeErrorMessage(seq, code, message)
 ```
 ## کدهای پاسخ
 | کد | نام | توضیح |
 |----|-----|--------|
 | 0x00 | OK | موفق |
 | 0x01 | ERROR | خطای عمومی |
 | 0x02 | AUTH_REQUIRED | نیاز به احراز هویت |
 | 0x03 | INVALID_QUERY | خطای نحوی |
 | 0x04 | NOT_FOUND | منبع یافت نشد |
@@ -1,62 +0,0 @@
 # HTTP/REST API
 API REST مبتنی بر JSON برای برنامه‌های وب.
 ## Base URL
 ```
 http://localhost:9470/api
 ```
 ## Endpoints
 ### GET /api/users
 لیست همه کاربران:
 ```bash
 curl http://localhost:9470/api/users
 ```
 ### GET /api/users/:id
 دریافت کاربر با ID:
 ```bash
 curl http://localhost:9470/api/users/1
 ```
 ### POST /api/users
 ایجاد کاربر:
 ```bash
 curl -X POST http://localhost:9470/api/users \
  -d '{"name": "Charlie", "age": 35}'
 ```
 ### PUT /api/users/:id
 به‌روزرسانی کاربر:
 ```bash
 curl -X PUT http://localhost:9470/api/users/1 \
  -d '{"name": "Alice", "age": 31}'
 ```
 ### DELETE /api/users/:id
 حذف کاربر:
 ```bash
 curl -X DELETE http://localhost:9470/api/users/1
 ```
 ## Query Endpoint
 اجرای کوئری BaraQL:
 ```bash
 curl -X POST http://localhost:9470/api/query \
  -d '{"sql": "SELECT * FROM users WHERE age > 18"}'
 ```
@@ -1,67 +0,0 @@
 # WebSocket API
 استریم تمام‌دوطرفه برای فیدهای داده real-time.
 ## اتصال
 ```
 ws://localhost:9471/ws
 ```
 ## مثال کلاینت
 ```javascript
 const ws = new WebSocket('ws://localhost:9471/ws');
 ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'query',
    sql: 'SELECT * FROM users'
  }));
 };
 ws.onmessage = (event) => {
  console.log('Received:', JSON.parse(event.data));
 };
 ```
 ## فرمت پیام
 ```json
 {
  "type": "query",
  "id": "uuid",
  "sql": "SELECT * FROM users"
 }
 ```
 ## انواع پیام
 ### درخواست
 ```json
 {
  "type": "query",
  "id": "123",
  "sql": "SELECT * FROM users"
 }
 ```
 ### پاسخ
 ```json
 {
  "type": "result",
  "id": "123",
  "data": [{"id": 1, "name": "Alice"}]
 }
 ```
 ### اشتراک
 ```json
 {
  "type": "subscribe",
  "table": "users"
 }
 ```
@@ -1,197 +0,0 @@
 # معماری BaraDB
 ## بررسی اجمالی
 BaraDB یک **موتور پایگاه داده چند حالته** است که با Nim نوشته شده و ذخیره‌سازی سندی (KV)، گرافی، برداری، ستونی و جستجوی تمام‌متن را در یک موتور واحد با زبان پرس‌وجوی واحد **BaraQL** ترکیب می‌کند.
 ## معماری لایه‌ای
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ 1. لایه کلاینت                                           │
 │    پروتکل باینری │ HTTP/REST │ WebSocket │ توکار          │
 ├─────────────────────────────────────────────────────────┤
 │ 2. لایه پرس‌وجو (BaraQL)                                │
 │    لکسر → پارسر → AST → IR → بهینه‌ساز → کد‌ژن          │
 ├─────────────────────────────────────────────────────────┤
 │ 3. موتور اجرا                                            │
 │    سند │ گراف │ بردار │ ستونی │ FTS                      │
 ├─────────────────────────────────────────────────────────┤
 │ 4. ذخیره‌سازی                                            │
 │    LSM-Tree │ B-Tree │ WAL │ Bloom │ فشردهسازی │ کش      │
 ├─────────────────────────────────────────────────────────┤
 │ 5. توزیع‌شده                                             │
 │    Raft │ شاردینگ │ ریپلیکیشن │ Gossip                   │
 └─────────────────────────────────────────────────────────┘
 ```
 ## لایه 1: لایه کلاینت
 چندین پروتکل ارتباطی:
 - **پروتکل باینری** (`protocol/wire.nim`): پروتکل باینری کارآمد big-endian با 16 نوع پیام
 - **HTTP/REST** (`core/httpserver.nim`): API REST مبتنی بر JSON با چند نخی
 - **WebSocket** (`core/websocket.nim`): استریم تمام‌دوطرفه
 - **حالت توکار** (`storage/lsm.nim`): دسترسی مستقیم درون‌پروسه‌ای
 ### مدیریت اتصال
 - **استخر اتصال** (`protocol/pool.nim`): محدودیت‌های کمینه/بیشینه اتصال با تایم‌اوت بیکاری
 - **محدودیت نرخ** (`protocol/ratelimit.nim`): Token-bucket سراسری و برای هر کلاینت
 - **احراز هویت** (`protocol/auth.nim`): JWT با HMAC-SHA256 و دسترسی مبتنی بر نقش
 - **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 با گواهینامه‌های خودتولید
 ## لایه 2: لایه پرس‌وجو (BaraQL)
 خط لوله BaraQL:
 1. **لکسر** (`query/lexer.nim`): توکن‌سازی ورودی به بیش از 80 نوع توکن
 2. **پارسر** (`query/parser.nim`): پارسر نزولی بازگشتی تولیدکننده AST
 3. **AST** (`query/ast.nim`): بیش از 300 خط，覆盖 بیش از 25 نوع گره
 4. **IR** (`query/ir.nim`): نمایش میانی برای نقشه‌های اجرا
 5. **بهینه‌ساز** (`query/adaptive.nim`): بهینه‌سازی تطبیقی کross-modal
 6. **کد‌ژن** (`query/codegen.nim`): ترجمه IR به عملیات ذخیره‌سازی
 7. **اجراکننده** (`query/executor.nim`): اجرای نقشه‌ها با موازی‌سازی
 ### برنامه‌ریزی کross-modal
 بهینه‌ساز (`query/adaptive.nim`) ترتیب اجرا را بین موتورها تعیین می‌کند:
 ```
 1. تخمین گزینش‌پذیری برای هر شرط
 2. ارسال گزینش‌پذیرترین شرط به موتور مربوطه اول
 3. استفاده از فیلترهای Bloom برای جستجوهای KV
 4. موازی‌سازی شاخه‌های مستقل
 5. استریم نتایج برای اجتناب از مادی‌سازی
 ```
 ## لایه 3: موتور اجرا
 ### موتور سند/KV
 - **LSM-Tree** (`storage/lsm.nim`): ذخیره‌سازی بهینه برای نوشتن با MemTable، WAL، SSTables
 - **اندیس B-Tree** (`storage/btree.nim`): اندیس مرتب برای اسکن بازه‌ای با COW
 ### موتور برداری (`vector/`)
 - **اندیس HNSW** (`vector/engine.nim`): گراف Navigable Small World سلسله‌مراتبی
 - **اندیس IVF-PQ** (`vector/engine.nim`): فایل معکوس با کوانتیزاسیون محصول
 - **عملیات SIMD** (`vector/simd.nim`): محاسبات فاصله بهینه‌شده با AVX2
 - **کوانتیزاسیون** (`vector/quant.nim`): اسکالر، محصول، و باینری
 ### موتور گراف (`graph/`)
 - **لیست مجاورت** (`graph/engine.nim`): گراف جهت‌دار با وزن یال
 - **الگوریتم‌ها** (`graph/engine.nim`): BFS، DFS، Dijkstra، PageRank
 - **تشخیص جامعه** (`graph/community.nim`): الگوریتم Louvain
 - **تطبیق الگو** (`graph/community.nim`): ایزومورفیسم زیرگراف
 - **پارسر Cypher** (`graph/cypher.nim`): پرس‌وجوهای گرافی Cypher-مانند
 ### جستجوی تمام‌متن (`fts/`)
 - **اندیس معکوس** (`fts/engine.nim`): اندیس سند-ترم
 - **رتبه‌بندی** (`fts/engine.nim`): امتیازدهی BM25 و TF-IDF
 - **جستجوی تقریبی** (`fts/engine.nim`): تطبیق با فاصله Levenshtein
 - **چندزبانه** (`fts/multilang.nim`): توکنایزرهایی برای EN، BG، DE، FR، RU
 ### موتور ستونی (`core/columnar.nim`)
 - ذخیره‌سازی هر-ستونی برای پرس‌وجوهای تحلیلی
 - کدگذاری RLE و دیکشنری
 - تجمیع‌های شتاب‌گرفته با SIMD
 ## لایه 4: ذخیره‌سازی
 - **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTable، Bloom Filter، فشرده‌سازی
 - **کش صفحه** (`storage/compaction.nim`): کش LRU با ردیابی نرخ hit
 - **I/O نگاشته‌شده به حافظه** (`storage/mmap.nim`): دسترسی فایل مبتنی بر mmap
 - **بازیابی** (`storage/recovery.nim`): بازپخش WAL و بازیابی پس از خرابی
 ### مسیر نوشتن
 ```
 کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن
  → StorageOp → MVCC Txn → WAL Write → MemTable → Commit
 ```
 ### مسیر خواندن
 ```
 کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن
  → StorageOp → MVCC Snapshot → MemTable → SSTable → Result
 ```
 ## لایه 5: توزیع‌شده
 - **Raft Consensus** (`core/raft.nim`): انتخاب رهبر، تکثیر لاگ
 - **شاردینگ** (`core/sharding.nim`): Hash، range، و consistent hashing
 - **ریپلیکیشن** (`core/replication.nim`): حالت‌های sync، async، semi-sync
 - **پروتکل Gossip** (`core/gossip.nim`): مدیریت عضویت SWIM-مانند
 - **تراکنش‌های توزیع‌شده** (`core/disttxn.nim`): commit دو مرحله‌ای
 ## تصمیمات کلیدی طراحی
 1. **Nim خالص**: بدون وابستگی به Cython، Python یا Rust
 2. **ذخیره‌سازی یکپارچه**: یک موتور برای KV، گراف، بردار، FTS و ستونی
 3. **حالت توکار**: می‌تواند به‌عنوان کتابخانه یا سرور اجرا شود
 4. **پروتکل باینری**: پروتکل سیمی کارآمد سفارشی
 5. **MVCC**: کنترل همزمانی چندنسخه‌ای
 6. **طرحواره-اول**: سیستم طرحواره با نوع قوی با وراثت
 7. **کross-modal**: زبان پرس‌وجوی واحد در تمام مدل‌های داده
 8. **تأیید رسمی**: الگوریتم‌های اصلی توزیع‌شده در TLA+ مشخص و با TLC بررسی شده
 ## آمار ماژول‌ها
 | دسته | ماژول‌ها | خطوط کد | هدف |
 |------|----------|----------|-----|
 | Core | 16 | ~4,200 | سرور، پروتکل‌ها، تراکنش‌ها، توزیع‌شده |
 | Storage | 7 | ~3,100 | LSM، B-Tree، WAL، bloom، فشرده‌سازی، mmap |
 | Query | 7 | ~2,800 | لکسر، پارسر، AST، IR، بهینه‌ساز، کد‌ژن، اجراکننده |
 | Vector | 3 | ~1,200 | HNSW، IVF-PQ، کوانتیزاسیون، SIMD |
 | Graph | 3 | ~1,000 | لیست مجاورت، الگوریتم‌ها، تشخیص جامعه |
 | FTS | 2 | ~900 | اندیس معکوس، BM25، تقریبی، چندزبانه |
 | Protocol | 7 | ~2,400 | Wire، HTTP، WebSocket، استخر، auth، محدودیت نرخ، SSL |
 | Schema | 1 | ~600 | انواع، لینک‌ها، وراثت، مهاجرت‌ها |
 | Client | 2 | ~800 | کلاینت باینری Nim، کمکی فایل |
 | CLI | 1 | ~400 | شل تعاملی BaraQL |
 | **مجموع** | **49** | **~14,100** | |
 ## نمودارهای جریان داده
 ### پرس‌وجوی ساده
 ```
 ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
 │ Client │───→│ Lexer  │───→│ Parser │───→│  IR    │───→│ Codegen│
 └────────┘    └────────┘    └────────┘    └────────┘    └───┬────┘
                                                             │
 ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐       │
 │ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘
 └────────┘    └────────┘    └────────┘    └────────┘
 ```
 ### پرس‌وجوی کross-modal
 ```
                     ┌─────────────┐
                     │   Parser    │
                     └──────┬──────┘
                            │
                     ┌──────▼──────┐
                     │   Adaptive  │
                     │   Optimizer │
                     └──────┬──────┘
                            │
            ┌───────────────┼───────────────┐
            │               │               │
     ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
     │    Vector   │ │    Graph    │ │     FTS     │
     │    Engine   │ │    Engine   │ │   Engine    │
     └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
            │               │               │
            └───────────────┼───────────────┘
                            │
                     ┌──────▼──────┐
                     │    Join     │
                     │   & Sort    │
                     └──────┬──────┘
                            │
                     ┌──────▼──────┐
                     │    Result   │
                     └─────────────┘
 ```
@@ -1,81 +0,0 @@
 # پشتیبان‌گیری و بازیابی
 ## Snapshot آنلاین
 BaraDB از snapshot آنلاین بدون توقف سرور پشتیبانی می‌کند.
 ### ایجاد snapshot
 ```nim
 import barabadb/core/backup
 var bm = newBackupManager()
 bm.createSnapshot("/backup/baradb_2025-01-15")
 ```
 ### از طریق CLI
 ```bash
 ./build/baradadb --snapshot --output=/backup/snapshot.db
 ```
 ### از طریق HTTP API
 ```bash
 curl -X POST http://localhost:9470/api/backup \
  -d '{"destination": "/backup/snapshot.db"}'
 ```
 ### پشتیبان‌گیری خودکار
 ```bash
 0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
 find /backup -name "baradb_*.db" -mtime +7 -delete
 ```
 ## بازیابی نقطه‌درزمان (PITR)
 ### بازیابی از snapshot + WAL
 ```bash
 ./build/baradadb --recover \
  --checkpoint=/backup/snapshot.db \
  --wal-dir=/backup/wal
 ```
 ### بازیابی از طریق SQL
 ```sql
 RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
 ```
 ## سناریوهای بازیابی
 ### سناریو 1: خرابی فایل
 ```bash
 cp /backup/sstables/000012.sst ./data/sstables/
 ./build/baradadb --rebuild-index
 ```
 ### سناریو 2: از دست دادن کامل داده
 ```bash
 cp /backup/snapshot.db ./data/
 ./build/baradadb --recover --wal-dir=/backup/wal
 ```
 ### سناریو 3: خرابی گره کلاستر
 ```bash
 BARADB_RAFT_NODE_ID=newnode \
 BARADB_RAFT_PEERS=node1:9001,node2:9001 \
 ./build/baradadb
 ```
 ## بهترین شیوه‌ها
 1. بازیابی را مرتب تست کنید
 2. پشتیبان‌ها را خارج از سایت ذخیره کنید
 3. پشتیبان‌ها را رمزنگاری کنید
 4. کارهای پشتیبان‌گیری را مانیتور کنید
@@ -1,597 +0,0 @@
 # مرجع زبان پرس‌وجو BaraQL
 BaraQL یک زبان پرس‌وجو سازگار با SQL با افزونه‌هایی برای عملیات گراف، بردار و سند است.
 ## انواع داده
 | نوع | توضیح | مثال |
 |------|--------|------|
 | `null` | مقدار تهی | `null` |
 | `bool` | بولی | `true`, `false` |
 | `int8` | عدد صحیح 8 بیتی علامت‌دار | `127` |
 | `int16` | عدد صحیح 16 بیتی علامت‌دار | `32767` |
 | `int32` | عدد صحیح 32 بیتی علامت‌دار | `2147483647` |
 | `int64` | عدد صحیح 64 بیتی علامت‌دار | `9223372036854775807` |
 | `float32` | عدد اعشاری 32 بیتی | `3.14` |
 | `float64` | عدد اعشاری 64 بیتی | `3.14159265359` |
 | `str` | رشته UTF-8 | `'hello'` |
 | `bytes` | بایت‌های خام | `0xDEADBEEF` |
 | `array<T>` | آرایه همگن | `[1, 2, 3]` |
 | `vector` | بردار float32 | `[0.1, 0.2, 0.3]` |
 | `object` | شیء کلید-مقدار | `{"a": 1}` |
 | `datetime` | timestamp ISO 8601 | `'2025-01-15T10:30:00Z'` |
 | `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` |
 | `json` | سند JSON | `{"key": "value"}` |
 | `jsonb` | JSON باینری (تأیید‌شده) | `{"key": "value"}` |
 ## پرس‌وجوهای پایه
 ### SELECT
 ```sql
 -- همه ستون‌ها
 SELECT * FROM users;
 -- ستون‌های خاص
 SELECT name, age FROM users;
 -- نام‌های مستعار
 SELECT name AS full_name, age AS years FROM users;
 -- DISTINCT
 SELECT DISTINCT department FROM employees;
 -- LIMIT و OFFSET
 SELECT * FROM users LIMIT 10 OFFSET 20;
 ```
 ### WHERE
 ```sql
 -- عملگرهای مقایسه‌ای
 SELECT * FROM users WHERE age > 18;
 SELECT * FROM users WHERE age >= 18 AND age <= 65;
 SELECT * FROM users WHERE name = 'Alice';
 SELECT * FROM users WHERE name != 'Bob';
 -- بازه
 SELECT * FROM users WHERE age BETWEEN 18 AND 65;
 -- عضویت مجموعه
 SELECT * FROM users WHERE department IN ('Engineering', 'Sales');
 -- تطبیق الگو
 SELECT * FROM users WHERE name LIKE 'A%';
 SELECT * FROM users WHERE name ILIKE 'alice';  -- بدون حساسیت به حروف
 -- بررسی NULL
 SELECT * FROM users WHERE email IS NOT NULL;
 -- عملگرهای منطقی
 SELECT * FROM users WHERE age > 18 AND (department = 'Engineering' OR department = 'Sales');
 ```
 ### ORDER BY
 ```sql
 -- صعودی (پیش‌فرض)
 SELECT * FROM users ORDER BY age;
 -- نزولی
 SELECT * FROM users ORDER BY age DESC;
 -- چند ستون
 SELECT * FROM users ORDER BY department ASC, age DESC;
 ```
 ### INSERT
 ```sql
 -- یک ردیف
 INSERT users { name := 'Alice', age := 30 };
 -- با نوع صریح
 INSERT User { name := 'Alice', age := 30 };
 -- چند ردیف
 INSERT users {
  { name := 'Alice', age := 30 },
  { name := 'Bob', age := 25 }
 };
 ```
 ### UPDATE
 ```sql
 -- به‌روزرسانی همه ردیف‌ها
 UPDATE users SET status = 'active';
 -- به‌روزرسانی شرطی
 UPDATE users SET age = 31 WHERE name = 'Alice';
 -- به‌روزرسانی چند ستون
 UPDATE users SET age = 32, status = 'premium' WHERE name = 'Alice';
 ```
 ### DELETE
 ```sql
 -- حذف همه ردیف‌ها
 DELETE FROM users;
 -- حذف شرطی
 DELETE FROM users WHERE age < 18;
 ```
 ## تجمیع و گروه‌بندی
 ### توابع تجمیعی
 | تابع | توضیح |
 |------|--------|
 | `count(*)` | شمارش همه ردیف‌ها |
 | `count(column)` | شمارش مقادیر غیر-NULL |
 | `sum(column)` | مجموع مقادیر |
 | `avg(column)` | میانگین |
 | `min(column)` | کمینه |
 | `max(column)` | بیشینه |
 | `stddev(column)` | انحراف معیار |
 | `variance(column)` | واریانس |
 ### GROUP BY
 ```sql
 SELECT department, count(*) as emp_count, avg(salary) as avg_salary
 FROM employees
 GROUP BY department;
 -- با HAVING
 SELECT department, count(*) as emp_count
 FROM employees
 GROUP BY department
 HAVING count(*) > 5;
 -- گروه‌بندی چندگانه
 SELECT department, role, count(*), avg(salary)
 FROM employees
 GROUP BY department, role;
 ```
 ## JOINها
 ```sql
 -- INNER JOIN
 SELECT u.name, o.total
 FROM users u
 INNER JOIN orders o ON u.id = o.user_id;
 -- LEFT JOIN
 SELECT u.name, o.total
 FROM users u
 LEFT JOIN orders o ON u.id = o.user_id;
 -- RIGHT JOIN
 SELECT u.name, o.total
 FROM users u
 RIGHT JOIN orders o ON u.id = o.user_id;
 -- FULL JOIN
 SELECT u.name, o.total
 FROM users u
 FULL JOIN orders o ON u.id = o.user_id;
 -- CROSS JOIN
 SELECT u.name, p.name
 FROM users u
 CROSS JOIN products p;
 -- JOINهای چندگانه
 SELECT u.name, o.id, p.name
 FROM orders o
 JOIN users u ON o.user_id = u.id
 JOIN products p ON o.product_id = p.id;
 -- Self JOIN
 SELECT e.name, m.name as manager
 FROM employees e
 JOIN employees m ON e.manager_id = m.id;
 ```
 ## CTEها (عبارات جدول مشترک)
 ```sql
 -- CTE واحد
 WITH active_users AS (
  SELECT * FROM users WHERE active = true
 )
 SELECT * FROM active_users;
 -- CTEهای چندگانه
 WITH
  recent AS (
    SELECT * FROM orders WHERE date > '2025-01-01'
  ),
  totals AS (
    SELECT user_id, sum(amount) as total FROM recent GROUP BY user_id
  )
 SELECT u.name, t.total
 FROM users u
 JOIN totals t ON u.id = t.user_id;
 -- CTE بازگشتی
 WITH RECURSIVE subordinates AS (
  SELECT id, name, manager_id FROM employees WHERE name = 'CEO'
  UNION ALL
  SELECT e.id, e.name, e.manager_id
  FROM employees e
  JOIN subordinates s ON e.manager_id = s.id
 )
 SELECT * FROM subordinates;
 ```
 ## زیرپرس‌وجوها
 ```sql
 -- زیرپرس‌وجو در SELECT
 SELECT name, (SELECT count(*) FROM orders WHERE user_id = u.id) as order_count
 FROM users u;
 -- زیرپرس‌وجو در FROM
 SELECT * FROM (SELECT id, name FROM users WHERE active = true) AS active;
 -- زیرپرس‌وجو در WHERE (IN)
 SELECT name FROM users WHERE id IN (SELECT user_id FROM orders);
 -- زیرپرس‌وجو در WHERE (EXISTS)
 SELECT name FROM users WHERE EXISTS (SELECT 1 FROM orders WHERE orders.user_id = users.id);
 -- زیرپرس‌وجوی همبسته
 SELECT name FROM users u
 WHERE age > (SELECT avg(age) FROM users WHERE department = u.department);
 ```
 ## عبارات CASE
 ```sql
 SELECT name,
  CASE
    WHEN age < 13 THEN 'child'
    WHEN age < 20 THEN 'teenager'
    WHEN age < 65 THEN 'adult'
    ELSE 'senior'
  END AS category
 FROM users;
 -- CASE ساده
 SELECT name,
  CASE department
    WHEN 'Engineering' THEN 'Tech'
    WHEN 'Sales' THEN 'Revenue'
    ELSE 'Other'
  END AS division
 FROM employees;
 ```
 ## عملیات مجموعه‌ای
 ```sql
 -- UNION (متفاوت)
 SELECT name FROM customers
 UNION
 SELECT name FROM suppliers;
 -- UNION ALL (با تکرار)
 SELECT name FROM customers
 UNION ALL
 SELECT name FROM suppliers;
 -- INTERSECT
 SELECT name FROM customers
 INTERSECT
 SELECT name FROM suppliers;
 -- EXCEPT
 SELECT name FROM customers
 EXCEPT
 SELECT name FROM suppliers;
 ```
 ## تعریف طرحواره
 ### CREATE TYPE
 ```sql
 CREATE TYPE Person {
  name: str,
  age: int32
 };
 -- با فیلدهای الزامی
 CREATE TYPE User {
  email: str REQUIRED,
  name: str,
  age: int32,
  created_at: datetime DEFAULT now()
 };
 -- با لینک‌ها
 CREATE TYPE Movie {
  title: str,
  year: int32,
  director: Person
 };
 -- با ویژگی‌های محاسباتی
 CREATE TYPE Employee {
  name: str,
  base_salary: float64,
  bonus: float64,
  total_compensation: float64 COMPUTED (base_salary + bonus)
 };
 ```
 ### وراثت
 ```sql
 CREATE TYPE Animal {
  name: str
 };
 CREATE TYPE Dog EXTENDING Animal {
  breed: str
 };
 CREATE TYPE Cat EXTENDING Animal {
  indoor: bool
 };
 ```
 ### اندیس‌ها
 ```sql
 CREATE INDEX idx_users_name ON users(name);
 CREATE UNIQUE INDEX idx_users_email ON users(email);
 CREATE INDEX idx_users_age ON users(age) USING btree;
 ```
 ### DROP
 ```sql
 DROP TYPE User;
 DROP INDEX idx_users_name;
 ```
 ## جستجوی برداری
 ```sql
 -- درج با بردار
 INSERT articles {
  title := 'Nim Programming',
  embedding := [0.1, 0.2, 0.3, 0.4]
 };
 -- جستجوی شباهت (فاصله کسینوسی)
 SELECT title FROM articles
 ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
 LIMIT 5;
 -- فاصله اقلیدسی
 SELECT title FROM articles
 ORDER BY l2_distance(embedding, [0.1, 0.2, 0.3, 0.4])
 LIMIT 5;
 -- ضرب نقطه‌ای
 SELECT title FROM articles
 ORDER BY dot_product(embedding, [0.1, 0.2, 0.3, 0.4]) DESC
 LIMIT 5;
 -- با فیلتر ابرداده
 SELECT title FROM articles
 WHERE category = 'tech'
 ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
 LIMIT 5;
 ```
 ## الگوهای گراف
 ```sql
 -- یافتن دوستان Alice
 MATCH (p:Person)-[:KNOWS]->(friend:Person)
 WHERE p.name = 'Alice'
 RETURN friend.name;
 -- یافتن کوتاه‌ترین مسیر
 MATCH path = shortestPath((a:Person)-[:KNOWS*1..5]->(b:Person))
 WHERE a.name = 'Alice' AND b.name = 'Bob'
 RETURN path;
 -- یافتن همه روابط
 MATCH (p:Person)-[r]->(other)
 WHERE p.name = 'Alice'
 RETURN type(r), other.name;
 -- جهش‌های چندگانه
 MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person)
 WHERE a.name = 'Alice'
 RETURN c.name;
 -- با تجمیع‌ها
 MATCH (p:Person)-[:KNOWS]->(friend)
 RETURN p.name, count(friend) as friend_count
 ORDER BY friend_count DESC;
 ```
 ## جستجوی تمام‌متن
 ```sql
 -- جستجوی پایه
 SELECT * FROM articles
 WHERE MATCH(title, body) AGAINST('database programming');
 -- با امتیاز ارتباط
 SELECT title, relevance()
 FROM articles
 WHERE MATCH(title, body) AGAINST('Nim language')
 ORDER BY relevance() DESC;
 -- حالت بولی
 SELECT * FROM articles
 WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE);
 -- جستجوی تقریبی
 SELECT * FROM articles
 WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2);
 ```
 ## تراکنش‌ها
 ```sql
 BEGIN;
 INSERT users { name := 'Alice', age := 30 };
 INSERT orders { user_id := last_insert_id(), total := 100 };
 COMMIT;
 -- با savepoint
 BEGIN;
 INSERT users { name := 'Bob', age := 25 };
 SAVEPOINT sp1;
 INSERT orders { user_id := last_insert_id(), total := 200 };
 -- اوپس، برگشت به savepoint
 ROLLBACK TO sp1;
 COMMIT;
 ```
 ## توابع تعریف‌شده کاربر
 ```sql
 -- ثبت یک UDF
 CREATE FUNCTION greet(name str) -> str {
  RETURN 'Hello, ' || name || '!';
 };
 -- استفاده
 SELECT greet(name) FROM users;
 -- توابع داخلی
 SELECT abs(-5), sqrt(16), lower('HELLO'), len('test');
 ```
 ## اشاره‌های پرس‌وجو
 ```sql
 -- اجبار استفاده از اندیس
 SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18;
 -- اجبار جستجوی برداری تقریبی
 SELECT /*+ APPROXIMATE */ * FROM vectors
 ORDER BY cosine_distance(embedding, [...])
 LIMIT 10;
 -- اجرای موازی
 SELECT /*+ PARALLEL(4) */ * FROM large_table;
 ```
 ## توابع پنجره‌ای
 ```sql
 -- توابع رتبه‌بندی
 SELECT
  name,
  department,
  ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn,
  RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r,
  DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr
 FROM employees;
 -- توابع مقدار
 SELECT
  name,
  salary,
  LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary,
  LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary,
  FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest,
  LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive
 FROM employees;
 -- توابع توزیع
 SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees;
 ```
 ### مشخصات فریم
 ```sql
 -- فریم ROWS
 SUM(salary) OVER (
  PARTITION BY department
  ORDER BY hire_date
  ROWS BETWEEN 1 PRECEDING AND CURRENT ROW
 )
 -- فریم RANGE
 SUM(salary) OVER (
  PARTITION BY department
  ORDER BY hire_date
  RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
 )
 ```
 ## ERP چند مستأجری
 BaraDB از اجرای چندین شرکت (tenant) در یک نمونه پایگاه داده پشتیبانی می‌کند، با استفاده از **امنیت سطح سطر (RLS)** همراه با **متغیرهای جلسه**.
 ### متغیرهای جلسه
 ```sql
 SET app.tenant_id = 'company-123';
 SELECT current_setting('app.tenant_id') AS tenant;
 ```
 ### کاربر / نقش فعلی
 ```sql
 SELECT current_user AS me, current_role AS my_role;
 ```
 ### جداسازی مستأجر با RLS
 ```sql
 -- فعال کردن RLS روی جدول
 ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
 -- ایجاد سیاست فیلترینگ بر اساس مستأجر
 CREATE POLICY tenant_isolation ON invoices
  FOR SELECT USING (tenant_id = current_setting('app.tenant_id'));
 -- هر جلسه فقط داده‌های خود را می‌بیند
 SET app.tenant_id = 'company-a';
 SELECT * FROM invoices;  -- فقط ردیف‌های company-a
 ```
 ### چرا چند مستأجری؟
 - **یک نمونه، مستأجران زیاد** — نیازی به اجرای ۱۰۰ پایگاه داده جداگانه نیست
 - **اسناد JSONB** — ذخیره‌سازی با طرح انعطاف‌پذیر، افزودن آسان فیلدها برای هر مستأجر
 - **RLS تضمین می‌کند** — پایگاه داده مرزهای مستأجر را اعمال می‌کند، نه فقط برنامه
 ## کلمات کلیدی پشتیبانی‌شده
 | دسته | کلمات کلیدی |
 |----------|----------|
 | DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT |
 | DML | INSERT, UPDATE, DELETE, SET, VALUES |
 | DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE |
 | Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON |
 | Set | UNION, UNION ALL, INTERSECT, EXCEPT |
 | CTEs | WITH, RECURSIVE, AS |
 | Case | CASE, WHEN, THEN, ELSE, END |
 | Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT |
 | Graph | MATCH, RETURN, WHERE, shortestPath, type |
 | FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS |
 | Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> |
 | JSON | ->, ->> |
 | FTS | @@ (BM25 match) |
 | Recovery | RECOVER TO TIMESTAMP |
 | Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting |
 | Session | SET, current_setting, current_user, current_role |
 | Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING |
 | Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE |
@@ -1,25 +0,0 @@
 # اندیس B-Tree
 ساختار اندیس مرتب برای اسکن بازه‌ای و جستجوی نقطه‌ای.
 ## استفاده
 ```nim
 import barabadb/storage/btree
 var btree = newBTreeIndex[string, string]()
 btree.insert("key1", "value1")
 btree.insert("key2", "value2")
 let values = btree.get("key1")
 let range = btree.scan("key_a", "key_z")
 btree.delete("key1")
 ```
 ## ویژگی‌ها
 - ذخیره‌سازی مرتب کلید-مقدار
 - جستجوهای بازه‌ای (BETWEEN, >, <, >=, <=)
 - اسکن پیشوندی
 - پشتیبانی از iterator
@@ -1,70 +0,0 @@
 # سیاهه تغییرات
 ## [0.1.0] — 2025-01-15
 ### افزوده شده
 - **موتورهای ذخیره‌سازی اصلی**
  - LSM-Tree با MemTable، WAL، SSTables و size-tiered compaction
  - B-Tree اندیس مرتب با اسکن بازه‌ای و MVCC copy-on-write
  - Bloom filterها
  - Memory-mapped I/O
  - LRU page cache
 - **موتور کوئری (BaraQL)**
  - لکسر SQL-سازگار با 80+ نوع توکن
  - پارسر تولیدکننده AST با 25+ نوع گره
  - نمایش میانی (IR)
  - بهینه‌ساز تطبیقی
  - اجراکننده موازی
 - **قابلیت‌های زبان BaraQL**
  - SELECT, INSERT, UPDATE, DELETE
  - WHERE, ORDER BY, LIMIT, OFFSET
  - GROUP BY, HAVING
  - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN
  - CTEs با WITH
  - زیرکوئری‌ها
  - CASE
  - UNION, INTERSECT, EXCEPT
 - **موتور برداری**
  - اندیس HNSW
  - IVF-PQ
  - SIMD-بهینه‌شده
 - **موتور گراف**
  - لیست مجاورت
  - BFS و DFS
  - Dijkstra
  - PageRank
  - Louvain
  - Cypher
 - **جستجوی تمام‌متن**
  - اندیس معکوس
  - BM25
  - TF-IDF
  - جستجوی فازی
  - چندزبانه
 - **پروتکل‌ها**
  - Binary wire protocol
  - HTTP/REST JSON API
  - WebSocket
  - Connection pooling
  - JWT auth
  - TLS/SSL
 - **سیستم توزیع‌شده**
  - Raft consensus
  - Sharding
  - Replication
  - Gossip
  - Two-phase commit
 ### عملکرد
 - LSM-Tree: 580K نوشتن/ثانیه، 720K خواندن/ثانیه
 - B-Tree: 1.2M درج/ثانیه
 - Vector SIMD: 850K فاصله کسینوسی/ثانیه
@@ -1,66 +0,0 @@
 # SDK های کلاینت
 BaraDB کتابخانه‌های کلاینت رسمی برای JavaScript/TypeScript، Python، Nim و Rust فراهم می‌کند.
 ## JavaScript / TypeScript
 ### نصب
 ```bash
 npm install baradb
 ```
 ### استفاده پایه
 ```typescript
 import { Client } from 'baradb';
 const client = new Client('localhost', 9472);
 await client.connect();
 const result = await client.query('SELECT name, age FROM users WHERE age > 18');
 ```
 ## Python
 ### نصب
 ```bash
 pip install baradb
 ```
 ### استفاده پایه
 ```python
 from baradb import Client
 client = Client("localhost", 9472)
 client.connect()
 result = client.query("SELECT name, age FROM users WHERE age > 18")
 ```
 ## Nim (حالت توکار)
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key", cast[seq[byte]]("value"))
 let (found, val) = db.get("key")
 db.close()
 ```
 ## Rust
 ```rust
 use baradb::Client;
 let mut client = Client::connect("localhost:9472").await?;
 ```
 ## HTTP/REST
 ```bash
 curl -X POST http://localhost:9470/api/query \
  -d '{"query": "SELECT * FROM users"}'
 ```
@@ -1,50 +0,0 @@
 # ذخیره‌سازی ستونی
 ذخیره‌سازی ستون-محور برای کوئری‌های تحلیلی و تجمیع‌ها.
 ## استفاده
 ```nim
 import barabadb/core/columnar
 var batch = newColumnBatch()
 var ageCol = batch.addInt64Col("age")
 var nameCol = batch.addStringCol("name")
 ageCol.appendInt64(25)
 nameCol.appendString("Alice")
 ```
 ## تجمیع‌ها
 ```nim
 echo ageCol.sumInt64()
 echo ageCol.avgInt64()
 echo ageCol.minInt64()
 echo ageCol.maxInt64()
 ```
 ## کدگذاری
 ### RLE
 ```nim
 let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
 ```
 ### Dictionary
 ```nim
 let dict = dictEncode(@["apple", "banana", "apple"])
 ```
 ## انواع ستون
 | نوع | توضیح |
 |-----|--------|
 | `int32` | عدد صحیح 32 بیتی |
 | `int64` | عدد صحیح 64 بیتی |
 | `float32` | عدد اعشاری 32 بیتی |
 | `float64` | عدد اعشاری 64 بیتی |
 | `string` | رشته با طول متغیر |
 | `bool` | بولی |
@@ -1,94 +0,0 @@
 # مرجع پیکربندی
 BaraDB از **متغیرهای محیطی**، **فایل پیکربندی** یا **پرچم‌های خط فرمان** پیکربندی می‌شود.
 ## اولویت
 1. پرچم‌های خط فرمان (بالاترین)
 2. متغیرهای محیطی
 3. فایل پیکربندی (`baradb.conf` یا `baradb.json`)
 4. مقادیر پیش‌فرض (پایین‌ترین)
 ## متغیرهای محیطی
 ### شبکه
 | متغیر | پیش‌فرض | توضیح |
 |--------|---------|--------|
 | `BARADB_ADDRESS` | `127.0.0.1` | آدرس اتصال |
 | `BARADB_PORT` | `9472` | پورت پروتکل باینری |
 | `BARADB_HTTP_PORT` | `9470` | پورت HTTP/REST API |
 | `BARADB_WS_PORT` | `9471` | پورت WebSocket |
 ### ذخیره‌سازی
 | متغیر | پیش‌فرض | توضیح |
 |--------|---------|--------|
 | `BARADB_DATA_DIR` | `./data` | مسیر پوشه داده |
 | `BARADB_MEMTABLE_SIZE_MB` | `64` | اندازه MemTable (MB) |
 | `BARADB_CACHE_SIZE_MB` | `256` | اندازه کش صفحه (MB) |
 ### TLS/SSL
 | متغیر | پیش‌فرض | توضیح |
 |--------|---------|--------|
 | `BARADB_TLS_ENABLED` | `false` | فعال‌سازی TLS |
 | `BARADB_CERT_FILE` | — | مسیر گواهی TLS |
 | `BARADB_KEY_FILE` | — | مسیر کلید TLS |
 ### امنیت
 | متغیر | پیش‌فرض | توضیح |
 |--------|---------|--------|
 | `BARADB_AUTH_ENABLED` | `false` | فعال‌سازی احراز هویت |
 | `BARADB_JWT_SECRET` | — | رمز امضای JWT |
 ## فایل پیکربندی
 ### baradb.conf
 ```ini
 [server]
 address = "0.0.0.0"
 port = 9472
 http_port = 9470
 [storage]
 data_dir = "/var/lib/baradb"
 memtable_size_mb = 256
 cache_size_mb = 512
 [tls]
 enabled = true
 cert_file = "/etc/baradb/server.crt"
 key_file = "/etc/baradb/server.key"
 [auth]
 enabled = true
 jwt_secret = "change-me-in-production"
 ```
 ## پرچم‌های خط فرمان
 ```bash
 ./build/baradadb --help
 ```
 ## نمونه پیکربندی‌ها
 ### توسعه
 ```bash
 ./build/baradadb --log-level debug --data-dir ./dev_data
 ```
 ### تولید - گره واحد
 ```bash
 BARADB_TLS_ENABLED=true \
 BARADB_AUTH_ENABLED=true \
 BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
 BARADB_MEMTABLE_SIZE_MB=256 \
 BARADB_CACHE_SIZE_MB=1024 \
 ./build/baradadb
 ```
@@ -1,40 +0,0 @@
 # پرس‌وجوهای بین‌حالتی
 توانایی منحصربه‌فرد BaraDB برای اجرای کوئری‌هایی که چندین موتور ذخیره‌سازی را در یک عبارت BaraQL واحد پوشش می‌دهند.
 ## نمای کلی
 - **سند/KV** (LSM-Tree) — رکوردهای ساختاریافته
 - **گراف** (لیست مجاورت) — روابط
 - **بردار** (HNSW/IVF-PQ) — جستجوی شباهت
 - **تمام‌متن** (اندیس معکوس) — جستجوی متنی
 - **ستونی** — تجمیع‌های تحلیلی
 ## پترن‌های کوئری
 ### بردار + تمام‌متن
 ```sql
 SELECT title FROM articles
 WHERE MATCH(body) AGAINST('machine learning')
 ORDER BY cosine_distance(embedding, [...])
 LIMIT 10;
 ```
 ### گراف + بردار
 ```sql
 MATCH (u:User)-[:KNOWS]->(friend:User)
 WHERE u.name = 'Alice'
 ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
 RETURN friend.name;
 ```
 ## بهینه‌سازی
 ### برنامه‌ریز پرس‌وجو
 1. فیلتر انتخابی‌ترین اول
 2. پوش‌داون پریدایکت‌ها به هر موتور
 3. فیلترهای Bloom برای جستجوهای KV
 4. موازی‌سازی شاخه‌های مستقل
@@ -1,249 +0,0 @@
 # راهنمای استقرار BaraDB
 ## Docker
 برای راهنمای کامل استقرار Docker به [راهنمای Docker](docker.md) مراجعه کنید.
 ### شروع سریع
 ```bash
 docker build -t baradb:latest .
 docker compose up -d
 ```
 ### فایل‌های Docker Compose
 | فایل | کاربرد |
 |------|--------|
 | `docker-compose.yml` | توسعه |
 | `docker-compose.prod.yml` | تولید |
 | `docker-compose.override.yml` | Override توسعه (خودکار) |
 ### تولید
 ```bash
 docker compose -f docker-compose.prod.yml up -d
 ```
 ### Docker Swarm
 ```bash
 docker stack deploy -c docker-compose.prod.yml baradb
 ```
 ## سرویس systemd
 فایل `/etc/systemd/system/baradb.service` را ایجاد کنید:
 ```ini
 [Unit]
 Description=BaraDB Multimodal Database
 After=network.target
 [Service]
 Type=simple
 User=baradb
 Group=baradb
 WorkingDirectory=/var/lib/baradb
 ExecStart=/usr/local/bin/baradadb
 Restart=always
 RestartSec=5
 Environment=BARADB_PORT=9472
 Environment=BARADB_HTTP_PORT=9470
 Environment=BARADB_DATA_DIR=/var/lib/baradb/data
 Environment=BARADB_LOG_LEVEL=info
 # Hardening امنیت
 NoNewPrivileges=true
 ProtectSystem=strict
 ProtectHome=true
 ReadWritePaths=/var/lib/baradb/data
 ProtectKernelTunables=true
 ProtectKernelModules=true
 ProtectControlGroups=true
 [Install]
 WantedBy=multi-user.target
 ```
 فعال‌سازی و شروع:
 ```bash
 sudo useradd -r -s /bin/false baradb
 sudo mkdir -p /var/lib/baradb/data
 sudo chown -R baradb:baradb /var/lib/baradb
 sudo cp build/baradadb /usr/local/bin/
 sudo systemctl daemon-reload
 sudo systemctl enable --now baradb
 ```
 ## Kubernetes
 ### StatefulSet
 ```yaml
 apiVersion: apps/v1
 kind: StatefulSet
 metadata:
  name: baradb
 spec:
  serviceName: baradb
  replicas: 3
  selector:
    matchLabels:
      app: baradb
  template:
    metadata:
      labels:
        app: baradb
    spec:
      containers:
      - name: baradb
        image: baradb:latest
        ports:
        - containerPort: 9472
          name: binary
        - containerPort: 9470
          name: http
        - containerPort: 9471
          name: websocket
        env:
        - name: BARADB_DATA_DIR
          value: /data
        - name: BARADB_RAFT_NODE_ID
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        volumeMounts:
        - name: data
          mountPath: /data
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 100Gi
 ---
 apiVersion: v1
 kind: Service
 metadata:
  name: baradb
 spec:
  selector:
    app: baradb
  ports:
  - port: 9472
    name: binary
  - port: 9470
    name: http
  - port: 9471
    name: websocket
  clusterIP: None
 ```
 ## Reverse Proxy (nginx)
 ```nginx
 upstream baradb_http {
    server 127.0.0.1:9470;
 }
 upstream baradb_ws {
    server 127.0.0.1:9471;
 }
 server {
    listen 80;
    server_name db.example.com;
    return 301 https://$server_name$request_uri;
 }
 server {
    listen 443 ssl http2;
    server_name db.example.com;
    ssl_certificate /etc/letsencrypt/live/db.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/db.example.com/privkey.pem;
    location /api/ {
        proxy_pass http://baradb_http/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    location /ws/ {
        proxy_pass http://baradb_ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
 }
 ```
 ## دسترس‌پذیری بالا
 ### خوشه Raft سه گره‌ای
 ```bash
 # گره 1
 BARADB_RAFT_NODE_ID=node1 \
 BARADB_RAFT_PEERS=node2:9001,node3:9001 \
 ./build/baradadb
 # گره 2
 BARADB_RAFT_NODE_ID=node2 \
 BARADB_RAFT_PEERS=node1:9001,node3:9001 \
 ./build/baradadb
 # گره 3
 BARADB_RAFT_NODE_ID=node3 \
 BARADB_RAFT_PEERS=node1:9001,node2:9001 \
 ./build/baradadb
 ```
 ## استقرار ابری
 ### AWS EC2
 نمونه توصیه‌شده: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
 ```bash
 # User data script
 #!/bin/bash
 apt-get update
 apt-get install -y nim
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
 chmod +x baradadb-linux-amd64
 mv baradadb-linux-amd64 /usr/local/bin/baradadb
 mkdir -p /data/baradb
 cat > /etc/systemd/system/baradb.service << 'EOF'
 [Unit]
 Description=BaraDB
 After=network.target
 [Service]
 ExecStart=/usr/local/bin/baradadb
 Environment=BARADB_DATA_DIR=/data/baradb
 Restart=always
 [Install]
 WantedBy=multi-user.target
 EOF
 systemctl daemon-reload
 systemctl enable --now baradb
 ```
 ### GCP Cloud Run (فقط HTTP)
 ```bash
 gcloud run deploy baradb \
  --image gcr.io/PROJECT/baradb \
  --port 9470 \
  --memory 4Gi \
  --cpu 2 \
  --max-instances 10
 ```
@@ -1,82 +0,0 @@
 # سیستم‌های توزیع‌شده
 BaraDB از استقرار توزیع‌شده با اجماع Raft، شاردینگ و تکثیر پشتیبانی می‌کند.
 ## اجماع Raft
 انتخاب رهبر و تکثیر لاگ:
 ```nim
 import barabadb/core/raft
 var cluster = newRaftCluster()
 cluster.addNode("node1")
 cluster.addNode("node2")
 cluster.addNode("node3")
 let n1 = cluster.nodes["n1"]
 n1.becomeCandidate()
 n1.becomeLeader()
 ```
 ## شاردینگ
 ```nim
 import barabadb/core/sharding
 var router = newShardRouter(ShardConfig(
  numShards: 4,
  replicas: 2,
  strategy: ssHash
 ))
 ```
 ### استراتژی‌های شاردینگ
 | استراتژی | توضیح |
 |-----------|--------|
 | `ssHash` | شاردینگ مبتنی بر hash |
 | `ssRange` | شاردینگ مبتنی بر بازه |
 | `ssConsistent` | هش سازگار |
 ## تکثیر
 ```nim
 import barabadb/core/replication
 var rm = newReplicationManager(rmSync)
 rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
 ```
 ### حالت‌های تکثیر
 | حالت | توضیح |
 |------|--------|
 | `rmSync` | تکثیر همگام |
 | `rmAsync` | تکثیر ناهمگام |
 | `rmSemiSync` | تکثیر نیمه‌همگام |
 ## پروتکل Gossip
 ```nim
 import barabadb/core/gossip
 var g = newGossipManager()
 g.addNode("node1")
 g.addNode("node2")
 g.tick()
 ```
 ## تراکنش‌های توزیع‌شده
 ```nim
 import barabadb/core/disttxn
 var dt = newDistributedTxn()
 dt.prepare(@["node1", "node2"])
 dt.commit()
 ```
 ## تأیید رسمی
 الگوریتم‌های اصلی توزیع‌شده در TLA+ مشخص و تأیید شده‌اند.
@@ -1,113 +0,0 @@
 # راهنمای استقرار Docker
 ## شروع سریع
 ```bash
 git clone https://codeberg.org/baraba/baradb
 cd barabaDB
 docker build -t baradb:latest .
 docker compose up -d
 docker compose ps
 docker compose logs -f
 ```
 ## فایل‌ها
 | فایل | توضیح |
 |------|--------|
 | `Dockerfile` | ساخت multi-stage production |
 | `docker-compose.yml` | پیکربندی توسعه |
 | `docker-compose.prod.yml` | پیکربندی تولید |
 | `docker-compose.override.yml` | Override توسعه |
 | `docker-entrypoint.sh` | اسکریپت entrypoint |
 | `.dockerignore` | فایل‌های مستثنی از کپی |
 | `scripts/docker-build.sh` | اسکریپت کمکی ساخت |
 | `scripts/docker-run.sh` | اسکریپت کمکی اجرا |
 ## ساخت تصویر
 ```bash
 docker build -t baradb:latest .
 ./scripts/docker-build.sh
 ```
 ## اجرا
 ### توسعه
 ```bash
 docker compose up -d
 docker compose down
 docker compose logs -f
 ```
 ### تولید
 ```bash
 docker compose -f docker-compose.prod.yml up -d
 ```
 ### دستی
 ```bash
 docker run -d \
  --name baradb \
  -p 9472:9472 \
  -p 9470:9470 \
  -p 9471:9471 \
  -v baradb_data:/data \
  baradb:latest
 ```
 ## پورت‌ها
 | پورت | توضیح |
 |------|--------|
 | `9472` | پروتکل باینری |
 | `9470` | HTTP/REST API |
 | `9471` | WebSocket |
 ## متغیرهای محیطی
 | متغیر | پیش‌فرض | توضیح |
 |--------|---------|--------|
 | `BARADB_ADDRESS` | `0.0.0.0` | آدرس اتصال |
 | `BARADB_PORT` | `9472` | پورت پروتکل باینری |
 | `BARADB_HTTP_PORT` | `9470` | پورت HTTP |
 | `BARADB_DATA_DIR` | `/data` | پوشه داده |
 ## Volumeها
 | مسیر | توضیح |
 |------|--------|
 | `/data` | پوشه اصلی داده |
 | `/data/server/wal` | Write-ahead log |
 | `/data/server/sstables` | فایل‌های SSTable |
 ## چک‌لیست تولید
 - [ ] ایجاد گواهی‌های TLS
 - [ ] تنظیم `BARADB_JWT_SECRET` قوی
 - [ ] پیکربندی قوانین فایروال
 - [ ] تنظیم پشتیبان‌گیری منظم
 - [ ] بررسی محدودیت منابع
 - [ ] تنظیم مانیتورینگ
 ## TLS در Docker
 ```bash
 mkdir -p certs
 openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/server.key -out certs/server.crt
 ```
 ## پشتیبان‌گیری
 ```bash
 docker exec baradb /app/backup backup --data-dir=/data
 docker exec baradb /app/backup list
 docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
 ```
@@ -1,47 +0,0 @@
 # موتور جستجوی تمام‌متن
 اندیس معکوس با رتبه‌بندی BM25 و TF-IDF.
 ## استفاده
 ```nim
 import barabadb/fts/engine
 var idx = newInvertedIndex()
 idx.addDocument(1, "Nim is a fast programming language")
 idx.addDocument(2, "Python is popular for data science")
 let results = idx.search("programming language")
 let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
 ```
 ## روش‌های رتبه‌بندی
 ### BM25
 ```nim
 let bm25 = idx.searchBM25("query terms")
 ```
 ### TF-IDF
 ```nim
 let tfidf = idx.searchTfidf("query terms")
 ```
 ## ویژگی‌های جستجو
 | ویژگی | توضیح |
 |--------|--------|
 | Fuzzy search | تساهل فاصله Levenshtein |
 | Wildcard | پیشوند، پسوند، میانوند |
 | Regex | الگوهای regular |
 | Phrase search | تطبیق عبارت دقیق |
 | Boolean | عملگرهای AND, OR, NOT |
 ## رابط SQL
 ```sql
 CREATE INDEX idx_fts ON articles(body) USING FTS;
 SELECT * FROM articles WHERE body @@ 'machine learning';
 ```
@@ -1,42 +0,0 @@
 # موتور گراف
 ذخیره‌سازی لیست مجاورت با الگوریتم‌های داخلی برای پیمایش و تحلیل گراف.
 ## استفاده
 ```nim
 import barabadb/graph/engine
 var g = newGraph()
 let alice = g.addNode("Person", {"Name": "Alice"}.toTable)
 let bob = g.addNode("Person", {"Name": "Bob"}.toTable)
 discard g.addEdge(alice, bob, "knows")
 let bfs = g.bfs(alice)
 let path = g.shortestPath(alice, bob)
 let ranks = g.pageRank()
 ```
 ## الگوریتم‌ها
 | الگوریتم | توضیح |
 |----------|--------|
 | `bfs` | پیمایش اول سطح |
 | `dfs` | پیمایش اول عمق |
 | `dijkstra` | کوتاه‌ترین مسیر وزن‌دار |
 | `pageRank` | رتبه‌بندی اهمیت گره |
 | `louvain` | تشخیص جامعه |
 | `patternMatch` | ایزومورفیسم زیرگراف |
 ## Cypher
 ```nim
 import barabadb/graph/cypher
 var engine = newCypherEngine(g)
 let results = engine.execute("""
  MATCH (p:Person)-[:KNOWS]->(friend:Person)
  WHERE p.name = 'Alice'
  RETURN friend.name
 """)
 ```
@@ -1,59 +0,0 @@
 # مستندات BaraDB (فارسی)
 **یک موتور پایگاه داده چند حالته به زبان Nim — کاملاً بومی، بدون وابستگی.**
 ## پیوندهای سریع
 > **توجه:** مستندات فارسی در حال توسعه است. لطفاً برای اطلاعات کامل به [نسخه انگلیسی](../en/) مراجعه کنید.
 ### شروع کار
 - [نصب](../en/installation.md)
 - [شروع سریع](../en/quickstart.md)
 - [بررسی معماری](../en/architecture.md)
 - [پیکربندی](../en/configuration.md)
 - [راهنمای استقرار](../en/deployment.md)
 ### مفاهیم اصلی
 - [BaraQL — زبان پرس‌وجو](../en/baraql.md)
 - [موتورهای ذخیره‌سازی](../en/storage.md)
 - [سیستم طرحواره](../en/schema.md)
 - [پرس‌وجوهای بین‌حالتی](../en/crossmodal.md)
 ### موتورها
 - [LSM-Tree](../en/lsm.md)
 - [اندیس B-Tree](../en/btree.md)
 - [جستجوی برداری](../en/vector.md)
 - [موتور گراف](../en/graph.md)
 - [جستجوی تمام‌متن](../en/fts.md)
 - [ذخیره‌سازی ستونی](../en/columnar.md)
 ### API و کلاینت‌ها
 - [SDK های کلاینت](../en/clients.md)
 - [پروتکل باینری](../en/api-binary.md)
 - [HTTP/REST API](../en/api-http.md)
 - [WebSocket API](../en/api-websocket.md)
 - [مرجع پروتکل](../en/protocol.md)
 ### عملیات
 - [عملکرد و معیارسنجی](../en/performance.md)
 - [امنیت](../en/security.md)
 - [نظارت](../en/monitoring.md)
 - [پشتیبان‌گیری و بازیابی](../en/backup.md)
 - [عیب‌یابی](../en/troubleshooting.md)
 ### مباحث پیشرفته
 - [تراکنش‌ها و MVCC](../en/transactions.md)
 - [سیستم‌های توزیع‌شده](../en/distributed.md)
 - [توابع تعریف‌شده کاربر](../en/udf.md)
 ---
 ## اطلاعات پروژه
 - [تاریخچه تغییرات](../en/changelog.md)
 - [مجوز](../../LICENSE)
 - [مخزن GitHub](https://github.com/katehonz/barabaDB)
 ---
 *مستندات فارسی در دست تهیه است.*
@@ -1,309 +0,0 @@
 # راهنمای نصب BaraDB
 ## الزامات
 - **کامپایلر Nim** >= 2.2.0
 - **فایل‌های هدر OpenSSL** (برای پشتیبانی TLS)
 - **سیستم‌عامل**: لینوکس، macOS، ویندوز
 ### پلتفرم‌های پشتیبانی‌شده
 | سیستم‌عامل | معماری | وضعیت |
 |------------|--------|--------|
 | لینوکس | x86_64 | ✅ پشتیبانی کامل |
 | لینوکس | ARM64 | ✅ پشتیبانی کامل |
 | macOS | x86_64 | ✅ پشتیبانی کامل |
 | macOS | ARM64 (Apple Silicon) | ✅ پشتیبانی کامل |
 | ویندوز | x86_64 | ✅ پشتیبانی‌شده |
 | FreeBSD | x86_64 | 🟡 تست‌شده توسط جامعه |
 ## نصب Nim
 ### لینوکس
 ```bash
 # نصب‌کننده رسمی
 curl https://nim-lang.org/choosenim/init.sh -sSf | sh
 # Ubuntu/Debian
 sudo apt-get update
 sudo apt-get install nim
 # Fedora
 sudo dnf install nim
 # Arch Linux
 sudo pacman -S nim
 ```
 ### macOS
 ```bash
 # Homebrew
 brew install nim
 # MacPorts
 sudo port install nim
 ```
 ### ویندوز
 ```powershell
 # Using choosenim
 curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
 # Using winget
 winget install nim
 # Using scoop
 scoop install nim
 ```
 ### تأیید نصب
 ```bash
 nim --version
 # انتظار: Nim Compiler Version 2.2.0 یا بالاتر
 ```
 ## نصب OpenSSL
 ### لینوکس
 ```bash
 # Ubuntu/Debian
 sudo apt-get install libssl-dev
 # Fedora
 sudo dnf install openssl-devel
 # Arch Linux
 sudo pacman -S openssl
 ```
 ### macOS
 OpenSSL همراه سیستم است. در صورت نیاز:
 ```bash
 brew install openssl
 ```
 ### ویندوز
 OpenSSL همراه توزیع ویندوز Nim است. برای ساخت دستی،
 از [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) دانلود کنید.
 ## ساخت BaraDB
 ### کلون کردن مخزن
 ```bash
 git clone https://codeberg.org/baraba/baradb
 cd barabaDB
 ```
 ### نصب وابستگی‌ها
 ```bash
 nimble install -d -y
 ```
 ### گزینه‌های ساخت
 #### ساخت دیباگ
 ```bash
 nim c -d:ssl -o:build/baradadb src/baradadb.nim
 ```
 #### ساخت ریلیز (توصیه‌شده)
 ```bash
 nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
 ```
 #### استفاده از Nimble Tasks
 ```bash
 # ساخت دیباگ
 nimble build_debug
 # ساخت ریلیز
 nimble build_release
 ```
 #### کاهش حجم باینری
 ```bash
 nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
 strip build/baradadb
 ```
 ### تأیید ساخت
 ```bash
 ./build/baradadb --version
 # انتظار: BaraDB v1.1.6 — Multimodal Database Engine
 ```
 ## اجرای تست‌ها
 ### همه تست‌ها
 ```bash
 nim c -d:ssl -r tests/test_all.nim
 ```
 ### مجموعه‌های تست خاص
 ```bash
 # تست‌های ذخیره‌سازی
 nim c -d:ssl -r tests/test_storage.nim
 # تست‌های موتور پرس‌وجو
 nim c -d:ssl -r tests/test_query.nim
 # تست‌های پروتکل
 nim c -d:ssl -r tests/test_protocol.nim
 ```
 ### بنچمارک‌ها
 ```bash
 nim c -d:ssl -d:release -r benchmarks/bench_all.nim
 ```
 ## گزینه‌های نصب
 ### نصب سیستمی
 ```bash
 # ساخت باینری ریلیز
 nimble build_release
 # نصب در /usr/local/bin
 sudo cp build/baradadb /usr/local/bin/
 sudo chmod +x /usr/local/bin/baradadb
 # ایجاد پوشه داده
 sudo mkdir -p /var/lib/baradb
 sudo chmod 755 /var/lib/baradb
 ```
 ### باینری از پیش ساخته‌شده
 آخرین ریلیز را برای پلتفرم خود دانلود کنید:
 ```bash
 # لینوکس x86_64
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
 chmod +x baradadb-linux-amd64
 mv baradadb-linux-amd64 /usr/local/bin/baradadb
 # لینوکس ARM64
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64
 chmod +x baradadb-linux-arm64
 mv baradadb-linux-arm64 /usr/local/bin/baradadb
 # macOS
 wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64
 chmod +x baradadb-darwin-amd64
 mv baradadb-darwin-amd64 /usr/local/bin/baradadb
 ```
 ### Docker
 ```bash
 # دریافت ایمیج رسمی
 docker pull barabadb/barabadb:latest
 # اجرا
 docker run -d \
  -p 9472:9472 \
  -p 9470:9470 \
  -p 9471:9471 \
  -v baradb_data:/data \
  barabadb/barabadb
 ```
 ### Docker Compose
 ```bash
 docker-compose up -d
 ```
 ### استفاده توکار (پروژه‌های Nim)
 به فایل `.nimble` خود اضافه کنید:
 ```nim
 requires "barabadb >= 0.1.0"
 ```
 در کد خود استفاده کنید:
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key", cast[seq[byte]]("value"))
 let (found, val) = db.get("key")
 db.close()
 ```
 ## اجرای اولیه
 ```bash
 # شروع سرور
 ./build/baradadb
 # خروجی مورد انتظار:
 # BaraDB v1.1.6 — Multimodal Database Engine
 # BaraDB TCP listening on 127.0.0.1:9472
 # تست با HTTP API
 curl http://localhost:9470/health
 # شل تعاملی
 ./build/baradadb --shell
 ```
 ## عیب‌یابی نصب
 ### "cannot open file: hunos"
 ```bash
 nimble install -d -y
 ```
 ### "BaraDB requires SSL support"
 همیشه با `-d:ssl` کامپایل کنید:
 ```bash
 nim c -d:ssl -o:build/baradadb src/baradadb.nim
 ```
 ### کامپایل کند
 از کامپایل موازی استفاده کنید:
 ```bash
 nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim
 ```
 ### حجم باینری زیاد
 از بهینه‌سازی اندازه استفاده کنید:
 ```bash
 nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim
 ```
 ## مراحل بعدی
 - [راهنمای شروع سریع](quickstart.md)
 - [مرجع پیکربندی](configuration.md)
 - [بررسی معماری](architecture.md)
 - [زبان پرس‌وجو BaraQL](baraql.md)
@@ -1,48 +0,0 @@
 # موتور ذخیره‌سازی LSM-Tree
 موتور ذخیره‌سازی اصلی BaraDB با معماری Log-Structured Merge-Tree.
 ## معماری
 ```
 ┌─────────────────────────────────────────────┐
 │                   Writes                     │
 │         (append to WAL + MemTable)           │
 └─────────────────────────────────────────────┘
                      │
                      ▼
 ┌─────────────────────────────────────────────┐
 │                  MemTable                    │
 │         (in-memory sorted buffer)            │
 └─────────────────────────────────────────────┘
                      │
                      ▼
 ┌─────────────────────────────────────────────┐
 │                  SSTable                     │
 │          (sorted string table on disk)       │
 └─────────────────────────────────────────────┘
 ```
 ## استفاده
 ```nim
 import barabadb/storage/lsm
 var db = newLSMTree("./data")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.delete("key1")
 db.close()
 ```
 ## ویژگی‌ها
 - **بهینه برای نوشتن**: ساختار log-only اضافه‌شونده
 - **دوام**: WAL تضمین‌کننده بازیابی پس از خرابی
 - **Bloom Filter**: جستجوهای منفی سریع
 - **Compaction**: استراتژی size-tiered
 - **Page Cache**: کش LRU
@@ -1,109 +0,0 @@
 # سرور MCP (Model Context Protocol)
 BaraDB شامل یک سرور MCP داخلی است که به عوامل هوش مصنوعی (Claude، Cursor و غیره) امکان تعامل مستقیم با پایگاه داده را می‌دهد.
 ## شروع سریع
 ```bash
 ./build/baramcp --data-dir ./data
 ```
 در حالت STDIO شروع می‌شود و پیام‌های JSON-RPC 2.0 را در stdin قبول می‌کند.
 ## ابزارهای موجود
 ### 1. `query` — اجرای SQL
 ```json
 {
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM users WHERE age > ?",
    "params": [25],
    "tenant_id": "company-a",
    "user_id": "alice"
  }
 }
 ```
 پرس‌وجوهای پارامتری با `?` placeholders. پشتیبانی multi-tenant از طریق `tenant_id` و `user_id`.
 ### 2. `vector_search` — جستجوی معنایی
 ```json
 {
  "name": "vector_search",
  "arguments": {
    "table": "docs",
    "column": "embedding",
    "query_vector": [0.1, 0.2, 0.3],
    "k": 5,
    "metric": "cosine",
    "filter_column": "category",
    "filter_value": "news",
    "tenant_id": "company-a"
  }
 }
 ```
 معیارها: `cosine`، `euclidean`، `dot_product`، `manhattan`.
 ### 3. `schema_inspect` — بررسی طرحواره
 ```json
 {
  "name": "schema_inspect",
  "arguments": {
    "table": "users",
    "tenant_id": "company-a"
  }
 }
 ```
 جداول، ستون‌ها، انواع، کلیدهای اصلی، کلیدهای خارجی، شاخص‌ها و سیاست‌های RLS را برمی‌گرداند.
 ## پیکربندی Claude Desktop
 ```json
 {
  "mcpServers": {
    "baradb": {
      "command": "/path/to/build/baramcp",
      "args": ["--data-dir", "/path/to/data"]
    }
  }
 }
 ```
 ## پیکربندی Cursor
 ```json
 {
  "mcpServers": {
    "baradb": {
      "command": "/path/to/build/baramcp",
      "args": ["--data-dir", "~/.baradb/data"]
    }
  }
 }
 ```
 ## جداسازی Multi-Tenant
 هر درخواست MCP می‌تواند شامل `tenant_id` و `user_id` باشد که به عنوان متغیرهای session تنظیم می‌شوند:
 - `app.tenant_id` — برای فیلتر RLS
 - `app.user_id` — برای referencهای `current_user`
 سیاست‌های RLS به طور خودکار داده‌ها را بر اساس این متغیرها فیلتر می‌کنند.
 ## پروتکل JSON-RPC 2.0
 سرور از JSON-RPC 2.0 از طریق STDIO استفاده می‌کند:
 ```json
 // درخواست
 {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}}
 // پاسخ
 {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}}
 ```
@@ -1,78 +0,0 @@
 # پایش و مشاهده‌پذیری
 ## بررسی‌های سلامت
 ### endpoint سلامت HTTP
 ```bash
 curl http://localhost:9470/health
 ```
 پاسخ:
 ```json
 {
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 86400,
  "checks": {
    "storage": "ok",
    "memory": "ok",
    "connections": "ok"
  }
 }
 ```
 ## معیارها
 ### معیارهای سازگار با Prometheus
 ```bash
 curl http://localhost:9470/metrics
 ```
 ### معیارهای JSON
 ```bash
 curl http://localhost:9470/metrics?format=json
 ```
 ## لاگ‌گذاری
 ### سطوح لاگ
 | سطح | توضیح |
 |------|--------|
 | `debug` | عملیات داخلی تفصیلی |
 | `info` | عملیات عادی |
 | `warn` | مشکلات قابل بازیابی |
 | `error` | خطاهای نیازمند توجه |
 ### لاگ‌های JSON ساختاریافته
 ```bash
 BARADB_LOG_LEVEL=info \
 BARADB_LOG_FORMAT=json \
 BARADB_LOG_FILE=/var/log/baradb/baradb.log \
 ./build/baradadb
 ```
 ## Grafana
 پنل‌های کلیدی:
 - Queries per second
 - Latency درصدها (p50, p95, p99)
 - اندازه ذخیره‌سازی
 - نرخ hit کش
 - اتصالات فعال
 - نرخ تراکنش
 - نرخ خطا
 ## عیب‌یابی با معیارها
 | علامت | معیار | عمل |
 |-------|-------|-----|
 | کوئری‌های کند | `baradb_queries_duration_seconds` | بررسی نرخ hit کش |
 | حافظه بالا | `process_resident_memory_bytes` | کاهش اندازه‌های memtable/cache |
 | رشد ذخیره‌سازی | `baradb_storage_lsm_size_bytes` | اجرای فشرده‌سازی دستی |
 | خطاهای اتصال | `baradb_active_connections` | افزایش استخر اتصال |
@@ -1,62 +0,0 @@
 # راهنمای عملکرد
 ## روش‌شناسی بنچمارک
 همه بنچمارک‌ها با Nim 2.2.0 و `-d:release --opt:speed` اجرا می‌شوند.
 ## بنچمارک‌های ذخیره‌سازی
 ### LSM-Tree
 | متریک | مقدار |
 |--------|-------|
 | توان عملیاتی نوشتن | ~580,000 ops/s |
 | توان عملیاتی خواندن | ~720,000 ops/s |
 ### B-Tree
 | متریک | مقدار |
 |--------|-------|
 | توان عملیاتی درج | ~1,200,000 ops/s |
 | جستجوی نقطه‌ای | ~1,500,000 ops/s |
 ## بنچمارک‌های موتور برداری
 ### HNSW
 | متریک | مقدار |
 |--------|-------|
 | درج (dim=128) | ~45,000 vectors/s |
 | جستجوی top-10 (n=100K) | ~8 ms |
 ## بنچمارک‌های پروتکل
 | پروتکل | اتصال | کوئری/ثانیه |
 |--------|-------|--------------|
 | Binary | 1 | 45,000 |
 | Binary | 100 | 380,000 |
 | HTTP/REST | 1 | 12,000 |
 ## راهنمای تنظیم
 ### برای بار کاری سنگین نوشتن
 ```bash
 BARADB_MEMTABLE_SIZE_MB=256
 BARADB_WAL_SYNC_INTERVAL_MS=10
 ```
 ### برای بار کاری سنگین خواندن
 ```bash
 BARADB_CACHE_SIZE_MB=1024
 BARADB_BLOOM_BITS_PER_KEY=10
 ```
 ### برای جستجوی برداری
 ```bash
 BARADB_VECTOR_EF_CONSTRUCTION=200
 BARADB_VECTOR_EF_SEARCH=128
 BARADB_VECTOR_M=32
 ```
@@ -1,67 +0,0 @@
 # مرجع پروتکل
 BaraDB چندین پروتکل پشتیبانی می‌کند:
 - **Binary Wire Protocol** — با کارایی بالا
 - **HTTP/REST API** — مستقل از زبان
 - **WebSocket** — استریمینگ و pub/sub
 ## Binary Wire Protocol
 از کدگذاری big-endian استفاده می‌کند.
 ### چرخه اتصال
 ```
 Client                          Server
  |                               |
  |─── TCP connect ──────────────>|
  |─── Auth message ─────────────>|
  |<── Auth_OK / Error ───────────|
  |─── Query message ────────────>|
  |<── Data / Complete / Error ───|
 ```
 ### فرمت پیام
 ```
 ┌─────────────┬─────────────┬─────────────┬─────────────────────┐
 │  Length     │  Type       │  Sequence   │  Payload            │
 │  (4 bytes)  │  (1 byte)   │  (1 byte)   │  (Length - 6 bytes) │
 └─────────────┴─────────────┴─────────────┴─────────────────────┘
 ```
 ### انواع پیام
 | نوع | ID | توضیح |
 |----|----|--------|
 | Query | 0x01 | اجرای کوئری |
 | Insert | 0x02 | درج داده |
 | Update | 0x03 | به‌روزرسانی |
 | Delete | 0x04 | حذف |
 | Ready | 0x05 | آماده |
 | Error | 0x06 | پاسخ خطا |
 ## HTTP/REST API
 Base URL: `http://localhost:9470/api/v1`
 ### Endpoints
 #### Health
 ```http
 GET /health
 ```
 #### Query
 ```http
 POST /query
 {
  "query": "SELECT * FROM users"
 }
 ```
 ## WebSocket Protocol
 URL: `ws://localhost:9471`
@@ -1,134 +0,0 @@
 # راهنمای شروع سریع BaraDB
 ## شروع سرور
 پس از ساخت BaraDB، سرور را_START کنید:
 ```bash
 ./build/baradadb
 ```
 سرور به‌صورت پیش‌فرض روی `localhost:9470` شروع می‌شود.
 ## اتصال از طریق CLI
 BaraDB شامل یک شل تعاملی است:
 ```bash
 ./build/baradadb --shell
 ```
 ## عملیات پایه
 ### ایجاد طرحواره
 ```sql
 CREATE TYPE Person {
  name: str,
  age: int32
 };
 CREATE TYPE Movie {
  title: str,
  year: int32,
  director: Person
 };
 ```
 ### درج داده
 ```sql
 INSERT Person { name := 'Alice', age := 30 };
 INSERT Person { name := 'Bob', age := 25 };
 ```
 ### پرس‌وجوی داده
 ```sql
 SELECT name, age FROM Person WHERE age > 18;
 ```
 ### به‌روزرسانی داده
 ```sql
 UPDATE Person SET age = 31 WHERE name = 'Alice';
 ```
 ### حذف داده
 ```sql
 DELETE FROM Person WHERE name = 'Bob';
 ```
 ## پرس‌وجوهای پیشرفته
 ### JOIN
 ```sql
 SELECT u.name, o.total
 FROM users u
 INNER JOIN orders o ON u.id = o.user_id;
 ```
 ### تجمیع‌ها
 ```sql
 SELECT department, count(*), avg(salary)
 FROM employees
 GROUP BY department
 HAVING count(*) > 5;
 ```
 ### CTEها
 ```sql
 WITH active_users AS (
  SELECT * FROM users WHERE active = true
 )
 SELECT * FROM active_users;
 ```
 ## جستجوی برداری
 ```sql
 -- درج بردار
 INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] };
 -- جستجوی مشابه
 SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10;
 ```
 ## عملیات گراف
 ```sql
 -- تطبیق الگوی گراف
 MATCH (p:Person)-[:KNOWS]->(other:Person)
 WHERE p.name = 'Alice'
 RETURN other.name;
 ```
 ## جستجوی تمام‌متن
 ```sql
 -- جستجوی اسناد
 SELECT * FROM articles WHERE MATCH(title, body) AGAINST('database');
 ```
 ## HTTP/REST API
 ```bash
 # درخواست GET
 curl http://localhost:9470/api/users
 # درخواست POST
 curl -X POST http://localhost:9470/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "age": 30}'
 ```
 ## مراحل بعدی
 - [مرجع BaraQL](baraql.md)
 - [موتورهای ذخیره‌سازی](storage.md)
 - [بررسی معماری](architecture.md)
 - [مرجع پروتکل](protocol.md)
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
dimgigov	072e7a5d13	test(join): add test for duplicate columns in SELECT * CI / test (push) Has been cancelled Details CI / verify (push) Has been cancelled Details Clients CI / build-server (push) Has been cancelled Details Clients CI / test-python (push) Has been cancelled Details Clients CI / test-javascript (push) Has been cancelled Details Clients CI / test-nim (push) Has been cancelled Details Clients CI / test-rust (push) Has been cancelled Details Verify that JOIN with overlapping column names preserves both left (bare) and right (qualified) values.	2026-05-21 09:44:32 +03:00
dimgigov	d4dc433e48	fix(query): preserve both sides of duplicate column names in JOIN When SELECT * joins tables with overlapping column names (e.g. 'id' in both users and orders), the right-side value was being dropped because irekStar filtered out dotted keys. - Add expandStarRow() that keeps bare columns and adds qualified aliases (u.id, o.id) only for duplicated names - Fix r.columns expansion to include all joined tables, qualifying duplicates from the right side	2026-05-21 09:44:31 +03:00
dimgigov	1ff6fabaff	fix(backup): resolve relative SSTable paths in incremental backup MANIFEST stores relative paths like 'sstables/1.sst'. The old code checked fileExists against CWD instead of dataDir, silently omitting SSTables when run from another directory. Now resolves paths relative to dataDir.	2026-05-21 09:44:28 +03:00
dimgigov	4a83eb6783	docs: update distributed/backup/schema/storage for multi-database - Add multi-database limitations to distributed docs - Fix backup commands and add multi-database backup guidance - Add SQL migration section to schema docs - Update storage examples to use per-database paths	2026-05-21 09:44:25 +03:00
dimgigov	a526a3aef9	docs: remove non-English/Bulgarian language docs, fix links Remove ar, de, fa, ru, tr, zh documentation folders. Update docs/index.md and docs/bg/index.md to only list en/bg. Update README badge from 7 to 2 languages. Update changelog entry for Bulgarian docs.	2026-05-21 09:44:17 +03:00