@grafema/rfdb 0.2.3-beta → 0.2.5-beta

package/README.md

@@ -1,6 +1,8 @@
 # @grafema/rfdb
 
-> High-performance disk-backed graph database server for Grafema
+> **RFDB** (Rega Flow Database) — high-performance disk-backed graph database server for Grafema
+
+*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 early alpha stage and is not recommended for production use.**
 
@@ -29,11 +31,14 @@ cargo build --release
 ### As a CLI
 
 ```bash
-# Start the server
-npx rfdb-server --socket /tmp/rfdb.sock --data-dir ./my-graph
+# Start the server (db-path is required, socket is optional)
+npx rfdb-server ./my-graph.rfdb --socket /tmp/rfdb.sock
 
 # Or if installed globally
-rfdb-server --socket /tmp/rfdb.sock --data-dir ./my-graph
+rfdb-server ./my-graph.rfdb --socket /tmp/rfdb.sock
+
+# Using default socket path (/tmp/rfdb.sock)
+rfdb-server ./my-graph.rfdb
 ```
 
 ### Programmatic usage
@@ -66,7 +71,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 (Rega Flow Database) is optional for Grafema. By default, Grafema uses an in-memory backend. To use RFDB for persistent storage:
 
 ```javascript
 const { Orchestrator, RFDBServerBackend } = require('@grafema/core');
@@ -102,9 +107,72 @@ cargo build --release
 
 # Run tests
 cargo test
+```
+
+## Performance Benchmarks
+
+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
+
+| 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 |
+
+### CI Regression Detection
+
+Benchmarks run on PRs with the `benchmark` label (comparing PR vs main branch).
+Regressions >20% will fail the workflow.
+
+To trigger on your PR: add the `benchmark` label.
+
+### What to Do If Benchmarks Regress
+
+If CI reports a regression on your PR:
+
+1. **Check if it's noise** — re-run the workflow. CI runners have variable load; spurious regressions happen.
+2. **Reproduce locally** — save baselines before/after your change and compare with `critcmp`:
+   ```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** — look at which operations regressed. A regression in `add_nodes` suggests storage overhead; `bfs`/`reachability` point to traversal changes.
+4. **Fix or justify** — if the regression is real, fix it. If it's an acceptable trade-off (e.g., +15% write latency for 10x better reads), document the trade-off in the PR description.
+
+### Comparing Before/After Changes
+
+```bash
+# Before making changes
+cargo bench --bench graph_operations -- --save-baseline before
 
-# Run benchmarks
-cargo bench
+# Make changes, then compare
+cargo bench --bench graph_operations -- --baseline before
 ```
 
 ## License

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.5-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",