@grafema/util 0.3.0-beta

package/dist/storage/backends/RFDBServerBackend.js

@@ -0,0 +1,748 @@
+/**
+ * RFDBServerBackend - Graph backend using RFDB server via Unix socket
+ *
+ * Replaces ReginaFlowBackend's direct NAPI binding with socket-based
+ * communication to a shared RFDB server. This allows multiple processes
+ * (MCP server, analysis workers) to share the same graph database.
+ *
+ * Socket path defaults to `{dbPath}/../rfdb.sock` (e.g., .grafema/rfdb.sock),
+ * ensuring each project has its own socket and avoiding conflicts when
+ * multiple MCP instances run simultaneously.
+ *
+ * Usage:
+ *   const backend = new RFDBServerBackend({
+ *     dbPath: '/project/.grafema/graph.rfdb'  // socket will be /project/.grafema/rfdb.sock
+ *   });
+ *   await backend.connect();
+ *   await backend.addNodes([...]);
+ *   await backend.flush();
+ */
+import { RFDBClient } from '@grafema/rfdb-client';
+import { join, dirname } from 'path';
+import { startRfdbServer } from '../../utils/startRfdbServer.js';
+import { GRAFEMA_VERSION, getSchemaVersion } from '../../version.js';
+import { brandNodeInternal } from '../../core/brandNodeInternal.js';
+export class RFDBServerBackend {
+    socketPath;
+    dbPath;
+    autoStart;
+    silent;
+    _clientName;
+    client;
+    serverProcess;
+    connected; // Public for compatibility
+    protocolVersion = 2; // Negotiated protocol version
+    edgeTypes;
+    _cachedNodeCounts;
+    _cachedEdgeCounts;
+    constructor(options = {}) {
+        this.dbPath = options.dbPath;
+        this.autoStart = options.autoStart ?? true; // Default true for backwards compat
+        this.silent = options.silent ?? false;
+        this._clientName = options.clientName ?? 'core';
+        // Default socket path: next to the database in .grafema folder
+        // This ensures each project has its own socket, avoiding conflicts
+        if (options.socketPath) {
+            this.socketPath = options.socketPath;
+        }
+        else if (this.dbPath) {
+            this.socketPath = join(dirname(this.dbPath), 'rfdb.sock');
+        }
+        else {
+            this.socketPath = '/tmp/rfdb.sock'; // fallback, not recommended
+        }
+        this.client = null;
+        this.serverProcess = null;
+        this.connected = false;
+        this.edgeTypes = new Set();
+    }
+    /**
+     * Log message if not in silent mode.
+     */
+    log(message) {
+        if (!this.silent) {
+            console.error(message);
+        }
+    }
+    /**
+     * Log error (always shown, even in silent mode).
+     */
+    logError(message, error) {
+        console.error(message, error ?? '');
+    }
+    /**
+     * Connect to RFDB server.
+     * If autoStart is true (default), starts the server if not running.
+     * If autoStart is false, requires explicit `grafema server start`.
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        // Try to connect first
+        this.client = new RFDBClient(this.socketPath, this._clientName);
+        // Attach error handler to prevent unhandled 'error' events
+        // This is important for stale sockets (socket file exists but server is dead)
+        this.client.on('error', (err) => {
+            this.logError('[RFDBServerBackend] Client error:', err.message);
+        });
+        try {
+            await this.client.connect();
+            // Verify server is responsive
+            await this.client.ping();
+            this.connected = true;
+            await this._negotiateProtocol();
+            this.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath} (protocol v${this.protocolVersion})`);
+            return;
+        }
+        catch {
+            // Server not running or stale socket
+            if (!this.autoStart) {
+                throw new Error(`RFDB server not running at ${this.socketPath}\n` +
+                    `Start the server first: grafema server start`);
+            }
+            this.log(`[RFDBServerBackend] RFDB server not running, starting...`);
+        }
+        // Start the server (only if autoStart is true)
+        await this._startServer();
+        // Connect again with fresh client
+        this.client = new RFDBClient(this.socketPath, this._clientName);
+        this.client.on('error', (err) => {
+            this.logError('[RFDBServerBackend] Client error:', err.message);
+        });
+        await this.client.connect();
+        await this.client.ping();
+        this.connected = true;
+        await this._negotiateProtocol();
+        this.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath} (protocol v${this.protocolVersion})`);
+    }
+    /**
+     * Alias for connect()
+     */
+    async initialize() {
+        return this.connect();
+    }
+    /**
+     * Start RFDB server process using shared utility.
+     */
+    async _startServer() {
+        if (!this.dbPath) {
+            throw new Error('dbPath required to start RFDB server');
+        }
+        await startRfdbServer({
+            dbPath: this.dbPath,
+            socketPath: this.socketPath,
+            pidPath: join(dirname(this.socketPath), 'rfdb.pid'),
+            waitTimeoutMs: 5000,
+            logger: this.silent ? undefined : { debug: (m) => this.log(m) },
+        });
+    }
+    /**
+     * Negotiate protocol version with server.
+     * Requests v3 (semantic IDs), falls back to v2 if server doesn't support it.
+     * Called after ping() confirmed connectivity, so failures here indicate
+     * the server doesn't support hello/v3, not network issues.
+     */
+    async _negotiateProtocol() {
+        if (!this.client)
+            return;
+        try {
+            const hello = await this.client.hello(3);
+            this.protocolVersion = hello.protocolVersion;
+            this._checkServerVersion(hello.serverVersion);
+        }
+        catch {
+            // Server predates hello command or doesn't support v3 — safe v2 fallback
+            this.protocolVersion = 2;
+            this.log('[RFDBServerBackend] WARNING: Server does not support version negotiation. Consider updating rfdb-server.');
+        }
+    }
+    /**
+     * Validate server version against expected client version.
+     * Warns on mismatch but never fails — version differences are informational.
+     */
+    _checkServerVersion(serverVersion) {
+        if (!serverVersion)
+            return;
+        const expected = getSchemaVersion(GRAFEMA_VERSION);
+        const actual = getSchemaVersion(serverVersion);
+        if (actual !== expected) {
+            this.log(`[RFDBServerBackend] WARNING: rfdb-server version mismatch — ` +
+                `server v${serverVersion}, expected v${GRAFEMA_VERSION}. ` +
+                `Update with: grafema server restart`);
+        }
+    }
+    /**
+     * Close client connection. Server continues running to serve other clients.
+     */
+    async close() {
+        // Request server flush before disconnecting
+        if (this.client) {
+            try {
+                await this.client.flush();
+            }
+            catch {
+                // Ignore flush errors on close - best effort
+            }
+            await this.client.close();
+            this.client = null;
+        }
+        this.connected = false;
+        // NOTE: We intentionally do NOT kill the server process.
+        // The server continues running to serve other clients (MCP, other CLI invocations).
+        // This is by design for multi-client architecture.
+        // Server lifecycle is managed separately (system process, or manual grafema server stop).
+        this.serverProcess = null;
+    }
+    /**
+     * Clear the database
+     */
+    async clear() {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.clear();
+    }
+    /**
+     * Flush data to disk
+     */
+    async flush() {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.flush();
+    }
+    /**
+     * Declare metadata fields for server-side indexing.
+     * Persisted in metadata.json — survives database reopen.
+     */
+    async declareFields(fields) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.declareFields(fields);
+    }
+    // ===========================================================================
+    // Node Operations
+    // ===========================================================================
+    /**
+     * Add a single node
+     */
+    async addNode(node) {
+        return this.addNodes([node]);
+    }
+    /**
+     * Add multiple nodes
+     */
+    async addNodes(nodes) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (!nodes.length)
+            return;
+        const useV3 = this.protocolVersion >= 3;
+        const wireNodes = nodes.map(n => {
+            // Extract metadata from node
+            const { id, type, nodeType, node_type, name, file, exported, ...rest } = n;
+            const wire = {
+                id: String(id),
+                nodeType: (nodeType || node_type || type || 'UNKNOWN'),
+                name: name || '',
+                file: file || '',
+                exported: exported || false,
+                metadata: useV3
+                    ? JSON.stringify(rest)
+                    : JSON.stringify({ originalId: String(id), ...rest }),
+            };
+            if (useV3) {
+                wire.semanticId = String(id);
+            }
+            return wire;
+        });
+        await this.client.addNodes(wireNodes);
+    }
+    /**
+     * Add a single edge
+     */
+    async addEdge(edge) {
+        return this.addEdges([edge]);
+    }
+    /**
+     * Add multiple edges
+     */
+    async addEdges(edges, skipValidation = false) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (!edges.length)
+            return;
+        // Track edge types
+        for (const e of edges) {
+            const edgeType = e.edgeType || e.edge_type || e.etype || e.type;
+            if (typeof edgeType === 'string')
+                this.edgeTypes.add(edgeType);
+        }
+        const useV3 = this.protocolVersion >= 3;
+        const wireEdges = edges.map(e => {
+            const { src, dst, type, edgeType, edge_type, etype, metadata, ...rest } = e;
+            // Flatten metadata: spread both edge-level properties and nested metadata
+            const flatMetadata = useV3
+                ? { ...rest, ...(typeof metadata === 'object' && metadata !== null ? metadata : {}) }
+                : { _origSrc: String(src), _origDst: String(dst), ...rest, ...(typeof metadata === 'object' && metadata !== null ? metadata : {}) };
+            return {
+                src: String(src),
+                dst: String(dst),
+                edgeType: (edgeType || edge_type || etype || type || 'UNKNOWN'),
+                metadata: JSON.stringify(flatMetadata),
+            };
+        });
+        await this.client.addEdges(wireEdges, skipValidation);
+    }
+    /**
+     * Get a node by ID
+     */
+    async getNode(id) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const node = await this.client.getNode(String(id));
+        if (!node)
+            return null;
+        return this._parseNode(node);
+    }
+    /**
+     * Check if node exists
+     */
+    async nodeExists(id) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.nodeExists(id);
+    }
+    /**
+     * Delete a node
+     */
+    async deleteNode(id) {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.deleteNode(id);
+    }
+    /**
+     * Find nodes by attributes
+     */
+    async findByAttr(query) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.findByAttr(query);
+    }
+    /**
+     * Parse a node from wire format to JS format
+     */
+    _parseNode(wireNode) {
+        const metadata = wireNode.metadata ? JSON.parse(wireNode.metadata) : {};
+        // Parse nested JSON strings
+        for (const [key, value] of Object.entries(metadata)) {
+            if (typeof value === 'string' && (value.startsWith('[') || value.startsWith('{'))) {
+                try {
+                    metadata[key] = JSON.parse(value);
+                }
+                catch {
+                    // Not JSON, keep as string
+                }
+            }
+        }
+        // Prefer metadata.semanticId (original v1 format preserved by RFDB server),
+        // then v3 semanticId, then v2 originalId metadata hack, then raw id
+        const humanId = metadata.semanticId || wireNode.semanticId || metadata.originalId || wireNode.id;
+        // Exclude standard fields from metadata to prevent overwriting wireNode values
+        // REG-325: Metadata spread was overwriting name with LITERAL node data
+        const { id: _id, type: _type, name: _name, file: _file, exported: _exported, nodeType: _nodeType, originalId: _originalId, // Already extracted above
+        semanticId: _semanticId, // Exclude from safeMetadata (used for humanId above)
+        ...safeMetadata } = metadata;
+        const parsed = {
+            id: humanId,
+            type: wireNode.nodeType,
+            name: wireNode.name,
+            file: wireNode.file,
+            exported: wireNode.exported,
+            ...safeMetadata,
+        };
+        // Re-brand nodes coming from database
+        return brandNodeInternal(parsed);
+    }
+    /**
+     * Parse an edge from wire format to EdgeRecord
+     */
+    _parseEdge(wireEdge) {
+        const meta = wireEdge.metadata ? JSON.parse(wireEdge.metadata) : {};
+        // v3: server resolves src/dst to semantic IDs, use directly
+        // v2: fall back to _origSrc/_origDst metadata hack
+        const { _origSrc, _origDst, ...rest } = meta;
+        const src = this.protocolVersion >= 3
+            ? wireEdge.src
+            : _origSrc || wireEdge.src;
+        const dst = this.protocolVersion >= 3
+            ? wireEdge.dst
+            : _origDst || wireEdge.dst;
+        return {
+            src,
+            dst,
+            type: wireEdge.edgeType,
+            metadata: Object.keys(rest).length > 0 ? rest : undefined,
+        };
+    }
+    /**
+     * Async generator for querying nodes
+     */
+    async *queryNodes(query) {
+        if (!this.client)
+            throw new Error('Not connected');
+        // Build query for server
+        const serverQuery = {};
+        if (query.nodeType)
+            serverQuery.nodeType = query.nodeType;
+        if (query.type)
+            serverQuery.nodeType = query.type;
+        if (query.name)
+            serverQuery.name = query.name;
+        if (query.file)
+            serverQuery.file = query.file;
+        if (query.substringMatch)
+            serverQuery.substringMatch = query.substringMatch;
+        // Use findByType if only nodeType specified
+        if (serverQuery.nodeType && Object.keys(serverQuery).length === 1) {
+            const ids = await this.client.findByType(serverQuery.nodeType);
+            for (const id of ids) {
+                const node = await this.getNode(id);
+                if (node)
+                    yield node;
+            }
+            return;
+        }
+        // Otherwise use client's queryNodes
+        for await (const wireNode of this.client.queryNodes(serverQuery)) {
+            yield this._parseNode(wireNode);
+        }
+    }
+    /**
+     * Get ALL nodes matching query (collects from queryNodes into array)
+     */
+    async getAllNodes(query = {}) {
+        const nodes = [];
+        for await (const node of this.queryNodes(query)) {
+            nodes.push(node);
+        }
+        return nodes;
+    }
+    // ===========================================================================
+    // Edge Operations
+    // ===========================================================================
+    /**
+     * Delete an edge
+     */
+    async deleteEdge(src, dst, type) {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.deleteEdge(src, dst, type);
+    }
+    /**
+     * Get all edges
+     */
+    async getAllEdges() {
+        return this.getAllEdgesAsync();
+    }
+    /**
+     * Get all edges (async version)
+     */
+    async getAllEdgesAsync() {
+        if (!this.client)
+            throw new Error('Not connected');
+        const edges = await this.client.getAllEdges();
+        return edges.map(e => this._parseEdge(e));
+    }
+    /**
+     * Get outgoing edges from a node
+     */
+    async getOutgoingEdges(nodeId, edgeTypes = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const edges = await this.client.getOutgoingEdges(nodeId, edgeTypes || undefined);
+        return edges.map(e => this._parseEdge(e));
+    }
+    /**
+     * Get incoming edges to a node
+     */
+    async getIncomingEdges(nodeId, edgeTypes = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const edges = await this.client.getIncomingEdges(nodeId, edgeTypes || undefined);
+        return edges.map(e => this._parseEdge(e));
+    }
+    // ===========================================================================
+    // Graph Traversal
+    // ===========================================================================
+    /**
+     * BFS traversal
+     */
+    async bfs(startIds, maxDepth, edgeTypes) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.bfs(startIds, maxDepth, edgeTypes);
+    }
+    /**
+     * DFS traversal
+     */
+    async dfs(startIds, maxDepth, edgeTypes = []) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.dfs(startIds, maxDepth, edgeTypes);
+    }
+    /**
+     * Reachability query - find all nodes reachable from start nodes
+     */
+    async reachability(startIds, maxDepth, edgeTypes = [], backward = false) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.reachability(startIds, maxDepth, edgeTypes, backward);
+    }
+    // ===========================================================================
+    // Statistics
+    // ===========================================================================
+    /**
+     * Get node count
+     */
+    async nodeCount() {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.nodeCount();
+    }
+    /**
+     * Get edge count
+     */
+    async edgeCount() {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.edgeCount();
+    }
+    /**
+     * Get statistics
+     */
+    async getStats() {
+        if (!this.client)
+            throw new Error('Not connected');
+        const nodeCount = await this.client.nodeCount();
+        const edgeCount = await this.client.edgeCount();
+        const nodeCounts = await this.client.countNodesByType();
+        const edgeCounts = await this.client.countEdgesByType();
+        return {
+            nodeCount,
+            edgeCount,
+            nodesByType: nodeCounts,
+            edgesByType: edgeCounts,
+        };
+    }
+    /**
+     * Get full server stats including shard diagnostics.
+     * Uses the GetStats wire command which returns all metrics in one call.
+     */
+    async getServerStats() {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.getStats();
+    }
+    /**
+     * Count nodes by type (sync, returns cached value)
+     */
+    async countNodesByType(_types = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.countNodesByType();
+    }
+    /**
+     * Count edges by type
+     */
+    async countEdgesByType(_edgeTypes = null) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return this.client.countEdgesByType();
+    }
+    /**
+     * Refresh cached counts (call after analysis)
+     */
+    async refreshCounts() {
+        if (!this.client)
+            throw new Error('Not connected');
+        this._cachedNodeCounts = await this.client.countNodesByType();
+        this._cachedEdgeCounts = await this.client.countEdgesByType();
+    }
+    async checkGuarantee(ruleSource, explain) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (explain) {
+            return await this.client.checkGuarantee(ruleSource, true);
+        }
+        const violations = await this.client.checkGuarantee(ruleSource);
+        // Convert bindings from {X: "value"} to [{name: "X", value: "value"}]
+        return violations.map(v => ({
+            bindings: Object.entries(v.bindings).map(([name, value]) => ({ name, value }))
+        }));
+    }
+    /**
+     * Load Datalog rules
+     */
+    async datalogLoadRules(source) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return await this.client.datalogLoadRules(source);
+    }
+    /**
+     * Clear Datalog rules
+     */
+    async datalogClearRules() {
+        if (!this.client)
+            throw new Error('Not connected');
+        await this.client.datalogClearRules();
+    }
+    async datalogQuery(query, explain) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (explain) {
+            return await this.client.datalogQuery(query, true);
+        }
+        const results = await this.client.datalogQuery(query);
+        // Convert bindings from {X: "value"} to [{name: "X", value: "value"}]
+        return results.map(r => ({
+            bindings: Object.entries(r.bindings).map(([name, value]) => ({ name, value }))
+        }));
+    }
+    async executeDatalog(source, explain) {
+        if (!this.client)
+            throw new Error('Not connected');
+        if (explain) {
+            return await this.client.executeDatalog(source, true);
+        }
+        const results = await this.client.executeDatalog(source);
+        return results.map(r => ({
+            bindings: Object.entries(r.bindings).map(([name, value]) => ({ name, value }))
+        }));
+    }
+    /**
+     * Run a Cypher query.
+     */
+    async cypherQuery(query) {
+        if (!this.client)
+            throw new Error('Not connected');
+        return await this.client.cypherQuery(query);
+    }
+    // ===========================================================================
+    // Batch Operations (RFD-16: CommitBatch protocol)
+    // ===========================================================================
+    /**
+     * Begin a batch operation. While batching, addNodes/addEdges buffer locally.
+     * Call commitBatch() to send all buffered data atomically.
+     */
+    beginBatch() {
+        if (!this.client)
+            throw new Error('Not connected to RFDB server');
+        this.client.beginBatch();
+    }
+    /**
+     * Commit the current batch to the server atomically.
+     * Returns a CommitDelta describing what changed.
+     *
+     * @param tags - Optional tags for the commit
+     * @param deferIndex - When true, server writes data but skips index rebuild.
+     */
+    async commitBatch(tags, deferIndex, protectedTypes, changedFiles) {
+        if (!this.client)
+            throw new Error('Not connected to RFDB server');
+        return this.client.commitBatch(tags, deferIndex, protectedTypes, changedFiles);
+    }
+    /**
+     * Synchronously batch a node. Must be inside beginBatch/commitBatch.
+     * Bypasses async wrapper for direct batch insertion.
+     */
+    batchNode(node) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const { id, type, nodeType, node_type, name, file, exported, ...rest } = node;
+        const useV3 = this.protocolVersion >= 3;
+        const wire = {
+            id: String(id),
+            nodeType: (nodeType || node_type || type || 'UNKNOWN'),
+            name: name || '',
+            file: file || '',
+            exported: exported || false,
+            metadata: useV3 ? JSON.stringify(rest) : JSON.stringify({ originalId: String(id), ...rest }),
+        };
+        if (useV3) {
+            wire.semanticId = String(id);
+        }
+        this.client.batchNode(wire);
+    }
+    /**
+     * Synchronously batch an edge. Must be inside beginBatch/commitBatch.
+     */
+    batchEdge(edge) {
+        if (!this.client)
+            throw new Error('Not connected');
+        const { src, dst, type, edgeType, edge_type, etype, metadata, ...rest } = edge;
+        const edgeTypeStr = edgeType || edge_type || etype || type;
+        if (typeof edgeTypeStr === 'string')
+            this.edgeTypes.add(edgeTypeStr);
+        const flatMetadata = { ...rest, ...(typeof metadata === 'object' && metadata !== null ? metadata : {}) };
+        this.client.batchEdge({
+            src: String(src),
+            dst: String(dst),
+            edgeType: (edgeTypeStr || 'UNKNOWN'),
+            metadata: JSON.stringify(flatMetadata),
+        });
+    }
+    /**
+     * Abort the current batch, discarding all buffered data.
+     */
+    abortBatch() {
+        if (!this.client)
+            throw new Error('Not connected to RFDB server');
+        this.client.abortBatch();
+    }
+    /**
+     * Rebuild all secondary indexes after deferred-index commits (REG-487).
+     * Call this once after a series of commitBatch(tags, true) calls.
+     */
+    async rebuildIndexes() {
+        if (!this.client)
+            throw new Error('Not connected to RFDB server');
+        await this.client.rebuildIndexes();
+    }
+    /**
+     * Create an isolated batch handle for concurrent-safe batching (REG-487).
+     * Each handle has its own buffers — safe for parallel workers.
+     */
+    createBatch() {
+        if (!this.client)
+            throw new Error('Not connected to RFDB server');
+        return this.client.createBatch();
+    }
+    // ===========================================================================
+    // Export/Import
+    // ===========================================================================
+    /**
+     * Export graph (for tests)
+     */
+    async export() {
+        const nodes = await this.getAllNodes();
+        const edges = await this.getAllEdgesAsync();
+        return {
+            nodes: nodes,
+            edges: edges,
+        };
+    }
+    /**
+     * Find nodes by predicate (for compatibility)
+     */
+    async findNodes(predicate) {
+        const allNodes = await this.getAllNodes();
+        return allNodes.filter(predicate);
+    }
+    // ===========================================================================
+    // Graph property (for compatibility)
+    // ===========================================================================
+    get graph() {
+        return this;
+    }
+}
+export default RFDBServerBackend;
+//# sourceMappingURL=RFDBServerBackend.js.map