@grafema/rfdb 0.2.3-beta → 0.2.6-beta

package/README.md

@@ -1,8 +1,10 @@
 # @grafema/rfdb
 
-> High-performance disk-backed graph database server for Grafema
+> **RFDB** (Rega Flow Database) — high-performance disk-backed graph database server for Grafema
 
-**Warning: This package is in early alpha stage and is not recommended for production use.**
+*Named after the author's wife Regina (Rega for short). The Hebrew word רגע (rega, "moment") conveniently fits the concept — a flow of discrete moments captured in the graph.*
+
+**Warning: This package is in beta stage and the API may change between minor versions.**
 
 ## Installation
 
@@ -12,9 +14,8 @@ npm install @grafema/rfdb
 
 Prebuilt binaries are included for:
 - macOS x64 (Intel)
-- macOS arm64 (Apple Silicon) - coming soon
-- Linux x64 - coming soon
-- Linux arm64 - coming soon
+- macOS arm64 (Apple Silicon)
+- Linux x64
 
 For other platforms, build from source (requires Rust):
 
@@ -30,10 +31,10 @@ cargo build --release
 
 ```bash
 # Start the server
-npx rfdb-server --socket /tmp/rfdb.sock --data-dir ./my-graph
+npx rfdb-server ./my-graph.rfdb --socket /tmp/rfdb.sock
 
-# Or if installed globally
-rfdb-server --socket /tmp/rfdb.sock --data-dir ./my-graph
+# Using default socket path (/tmp/rfdb.sock)
+rfdb-server ./my-graph.rfdb
 ```
 
 ### Programmatic usage
@@ -66,7 +67,7 @@ server.kill();
 
 ## With Grafema
 
-RFDB is optional for Grafema. By default, Grafema uses an in-memory backend. To use RFDB for persistent storage:
+RFDB is the default storage backend for Grafema. The MCP server and CLI auto-start RFDB when needed.
 
 ```javascript
 const { Orchestrator, RFDBServerBackend } = require('@grafema/core');
@@ -79,20 +80,22 @@ const orchestrator = new Orchestrator({
 
 ## Features
 
-- **Columnar storage**: Efficient storage for graph nodes and edges
-- **Deterministic IDs**: BLAKE3 hash-based node identification
-- **Zero-copy access**: Memory-mapped files for fast reads
-- **BFS/DFS traversal**: Fast graph traversal algorithms
-- **Version-aware**: Support for incremental analysis
+- **Adaptive tuning** — Auto-detects CPU cores, memory, and disk type; tunes write buffers, compaction parallelism, and prefetch strategy
+- **Columnar storage** — Efficient storage for graph nodes and edges
+- **Deterministic IDs** — BLAKE3 hash-based node identification
+- **Zero-copy access** — Memory-mapped files for fast reads
+- **BFS/DFS traversal** — Fast graph traversal algorithms
+- **Parallel compaction** — Multi-threaded background compaction
 
 ## Protocol
 
 RFDB server communicates via Unix socket using MessagePack-encoded messages. The protocol supports:
 
-- `add_nodes` / `add_edges` - Batch insert operations
-- `get_node` / `find_by_attr` - Query operations
-- `bfs` / `dfs` - Graph traversal
-- `flush` / `compact` - Persistence operations
+- `add_nodes` / `add_edges` — Batch insert operations
+- `get_node` / `find_by_attr` — Query operations
+- `bfs` / `dfs` — Graph traversal
+- `flush` / `compact` — Persistence operations
+- `compact_with_stats` — Compaction with statistics reporting
 
 ## Building from source
 
@@ -102,11 +105,71 @@ cargo build --release
 
 # Run tests
 cargo test
+```
+
+## Performance Benchmarks
 
-# Run benchmarks
-cargo bench
+RFDB includes Criterion-based benchmarks covering all core graph operations.
+
+### Running Locally
+
+```bash
+cd packages/rfdb-server
+
+# Run all benchmarks
+cargo bench --bench graph_operations
+
+# Run specific benchmark group
+cargo bench --bench graph_operations -- 'add_nodes'
+cargo bench --bench graph_operations -- 'get_node'
+
+# Save baseline for future comparison
+cargo bench --bench graph_operations -- --save-baseline my-baseline
+
+# Compare against saved baseline
+cargo bench --bench graph_operations -- --baseline my-baseline
 ```
 
+### Benchmark Coverage (16 groups)
+
+| Category | Operations |
+|----------|-----------|
+| **Node write** | add_nodes |
+| **Edge write** | add_edges |
+| **Node read** | get_node, find_by_type, find_by_type (wildcard), find_by_attr |
+| **Edge read** | get_outgoing_edges, get_incoming_edges, neighbors |
+| **Mutation** | delete_node, delete_edge |
+| **Traversal** | bfs, reachability (forward/backward) |
+| **Maintenance** | flush, compact |
+| **Analysis** | reanalysis_cost, compaction |
+
+### Additional Tools
+
+```bash
+# Memory profiling
+cargo run --bin memory_profile
+
+# Benchmark report generation
+cargo run --bin bench_report
+```
+
+### CI Regression Detection
+
+Benchmarks run on PRs with the `benchmark` label (comparing PR vs main branch).
+Regressions >20% will fail the workflow.
+
+### What to Do If Benchmarks Regress
+
+1. **Check if it's noise** — re-run the workflow
+2. **Reproduce locally** — save baselines before/after:
+   ```bash
+   git stash && cargo bench --bench graph_operations -- --save-baseline before
+   git stash pop && cargo bench --bench graph_operations -- --save-baseline after
+   cargo install critcmp && critcmp before after
+   ```
+3. **Identify the cause** — `add_nodes` regression = storage overhead; `bfs`/`reachability` = traversal changes
+4. **Fix or justify** — document trade-offs in PR description
+
 ## License
 
 Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grafema/rfdb",
-  "version": "0.2.3-beta",
-  "description": "High-performance disk-backed graph database server for Grafema",
+  "version": "0.2.6-beta",
+  "description": "RFDB (Rega Flow Database) — high-performance disk-backed graph database server for Grafema",
   "main": "index.js",
   "types": "index.d.ts",
   "bin": {
@@ -9,14 +9,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Disentinel/rfdb.git"
+    "url": "https://github.com/Disentinel/grafema.git",
+    "directory": "packages/rfdb-server"
   },
   "keywords": [
     "graph",
     "database",
     "semantic-analysis",
     "code-analysis",
-    "rust"
+    "rust",
+    "rega-flow",
+    "rfdb"
   ],
   "author": "Vadim Reshetnikov",
   "license": "Apache-2.0",