@grafema/rfdb 0.2.1-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.1-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",

package/scripts/postinstall.js

@@ -2,8 +2,10 @@
 /**
  * RFDB postinstall script
  *
- * Validates that a prebuilt binary exists for the current platform,
- * or provides instructions for building from source.
+ * Ensures the RFDB server binary is available:
+ * 1. Check for prebuilt binary (fastest)
+ * 2. Check ~/.local/bin/rfdb-server (user-installed)
+ * 3. Provide clear instructions for unsupported platforms
  */
 
 const path = require('path');
@@ -12,31 +14,58 @@ const fs = require('fs');
 const platform = process.platform;
 const arch = process.arch;
 
+// Determine platform directory name
 let platformDir;
 if (platform === 'darwin') {
   platformDir = arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
 } else if (platform === 'linux') {
   platformDir = arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
 } else {
-  console.warn(`\n⚠️  @grafema/rfdb: No prebuilt binary for ${platform}-${arch}`);
-  console.warn('   Build from source with: cargo build --release\n');
+  console.warn(`\n⚠️  @grafema/rfdb: Platform ${platform} is not supported yet.\n`);
   process.exit(0);
 }
 
-const binaryPath = path.join(__dirname, '..', 'prebuilt', platformDir, 'rfdb-server');
+const prebuiltDir = path.join(__dirname, '..', 'prebuilt', platformDir);
+const binaryPath = path.join(prebuiltDir, 'rfdb-server');
+const homeBinaryPath = path.join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
 
-if (!fs.existsSync(binaryPath)) {
-  console.warn(`\n⚠️  @grafema/rfdb: No prebuilt binary for ${platform}-${arch}`);
-  console.warn('   Build from source with: cargo build --release');
-  console.warn('   Or download from: https://github.com/Disentinel/rfdb/releases\n');
+// 1. Check for prebuilt binary
+if (fs.existsSync(binaryPath)) {
+  try {
+    fs.chmodSync(binaryPath, 0o755);
+  } catch (e) {
+    // Ignore chmod errors
+  }
+  console.log(`✓ @grafema/rfdb: Binary ready for ${platform}-${arch}`);
   process.exit(0);
 }
 
-// Make binary executable
-try {
-  fs.chmodSync(binaryPath, 0o755);
-} catch (e) {
-  // Ignore chmod errors on Windows
+// 2. Check if user already has binary in ~/.local/bin
+if (fs.existsSync(homeBinaryPath)) {
+  console.log(`✓ @grafema/rfdb: Found user binary at ${homeBinaryPath}`);
+  process.exit(0);
 }
 
-console.log(`✓ @grafema/rfdb: Binary ready for ${platform}-${arch}`);
+// 3. No binary available - provide instructions
+console.log(`
+⚠️  @grafema/rfdb: No prebuilt binary for ${platform}-${arch}
+
+To use Grafema, build the server binary from source:
+
+  # Clone and build
+  git clone https://github.com/Disentinel/grafema.git
+  cd grafema/packages/rfdb-server
+  cargo build --release
+
+  # Install to ~/.local/bin (Grafema will find it automatically)
+  mkdir -p ~/.local/bin
+  cp target/release/rfdb-server ~/.local/bin/
+
+  # Or specify in config.yaml:
+  # server:
+  #   binaryPath: /path/to/rfdb-server
+
+Requires Rust: https://rustup.rs
+`);
+
+process.exit(0);