@grafema/rfdb-client 0.2.11 → 0.3.0-beta

package/dist/client.js

@@ -6,27 +6,24 @@
  */
 import { createConnection } from 'net';
 import { encode, decode } from '@msgpack/msgpack';
-import { EventEmitter } from 'events';
 import { StreamQueue } from './stream-queue.js';
-export class RFDBClient extends EventEmitter {
+import { BaseRFDBClient } from './base-client.js';
+export class RFDBClient extends BaseRFDBClient {
     socketPath;
+    clientName;
     socket;
     connected;
     pending;
     reqId;
     buffer;
-    // Batch state
-    _batching = false;
-    _batchNodes = [];
-    _batchEdges = [];
-    _batchFiles = new Set();
     // Streaming state
     _supportsStreaming = false;
     _pendingStreams = new Map();
     _streamTimers = new Map();
-    constructor(socketPath = '/tmp/rfdb.sock') {
+    constructor(socketPath = '/tmp/rfdb.sock', clientName = 'unknown') {
         super();
         this.socketPath = socketPath;
+        this.clientName = clientName;
         this.socket = null;
         this.connected = false;
         this.pending = new Map();
@@ -134,7 +131,7 @@ export class RFDBClient extends EventEmitter {
         }
     }
     /**
-     * Handle decoded response — match by requestId, route streaming chunks
+     * Handle decoded response -- match by requestId, route streaming chunks
      * to StreamQueue or resolve single-response Promise.
      */
     _handleResponse(response) {
@@ -167,7 +164,7 @@ export class RFDBClient extends EventEmitter {
             this._handleStreamingResponse(id, response, streamQueue);
             return;
         }
-        // Non-streaming response — existing behavior
+        // Non-streaming response -- existing behavior
         if (!this.pending.has(id)) {
             this.emit('error', new Error(`Received response for unknown requestId: ${response.requestId}`));
             return;
@@ -183,17 +180,13 @@ export class RFDBClient extends EventEmitter {
     }
     /**
      * Handle a response for a streaming request.
-     * Routes chunk data to StreamQueue and manages stream lifecycle.
-     * Resets per-chunk timeout on each successful chunk arrival.
      */
     _handleStreamingResponse(id, response, streamQueue) {
-        // Error response — fail the stream
         if (response.error) {
             this._cleanupStream(id);
             streamQueue.fail(new Error(response.error));
             return;
         }
-        // Streaming chunk (has `done` field)
         if ('done' in response) {
             const chunk = response;
             const nodes = chunk.nodes || [];
@@ -205,13 +198,11 @@ export class RFDBClient extends EventEmitter {
                 streamQueue.end();
             }
             else {
-                // Reset per-chunk timeout
                 this._resetStreamTimer(id, streamQueue);
             }
             return;
         }
         // Auto-fallback: server sent a non-streaming Nodes response
-        // (server doesn't support streaming or result was below threshold)
         const nodesResponse = response;
         const nodes = nodesResponse.nodes || [];
         for (const node of nodes) {
@@ -220,9 +211,6 @@ export class RFDBClient extends EventEmitter {
         this._cleanupStream(id);
         streamQueue.end();
     }
-    /**
-     * Reset the per-chunk timeout for a streaming request.
-     */
     _resetStreamTimer(id, streamQueue) {
         const existing = this._streamTimers.get(id);
         if (existing)
@@ -233,9 +221,6 @@ export class RFDBClient extends EventEmitter {
         }, RFDBClient.DEFAULT_TIMEOUT_MS);
         this._streamTimers.set(id, timer);
     }
-    /**
-     * Clean up all state for a completed/failed streaming request.
-     */
     _cleanupStream(id) {
         this._pendingStreams.delete(id);
         this.pending.delete(id);
@@ -251,10 +236,6 @@ export class RFDBClient extends EventEmitter {
         const num = parseInt(requestId.slice(1), 10);
         return Number.isNaN(num) ? null : num;
     }
-    /**
-     * Default timeout for operations (60 seconds)
-     * Flush/compact may take time for large graphs, but should not hang indefinitely
-     */
     static DEFAULT_TIMEOUT_MS = 60_000;
     /**
      * Send a request and wait for response with timeout
@@ -267,12 +248,10 @@ export class RFDBClient extends EventEmitter {
             const id = this.reqId++;
             const request = { requestId: `r${id}`, cmd, ...payload };
             const msgBytes = encode(request);
-            // Setup timeout
             const timer = setTimeout(() => {
                 this.pending.delete(id);
                 reject(new Error(`RFDB ${cmd} timed out after ${timeoutMs}ms. Server may be unresponsive or dbPath may be invalid.`));
             }, timeoutMs);
-            // Handle socket errors during this request
             const errorHandler = (err) => {
                 this.pending.delete(id);
                 clearTimeout(timer);
@@ -289,7 +268,7 @@ export class RFDBClient extends EventEmitter {
                     clearTimeout(timer);
                     this.socket?.removeListener('error', errorHandler);
                     reject(error);
-                }
+                },
             });
             // Write length prefix + message
             const header = Buffer.alloc(4);
@@ -298,271 +277,23 @@ export class RFDBClient extends EventEmitter {
         });
     }
     // ===========================================================================
-    // Write Operations
-    // ===========================================================================
-    /**
-     * Add nodes to the graph
-     * Extra properties beyond id/type/name/file/exported/metadata are merged into metadata
-     */
-    async addNodes(nodes) {
-        const wireNodes = nodes.map(n => {
-            // Cast to Record to allow iteration over extra properties
-            const nodeRecord = n;
-            // Extract known wire format fields, rest goes to metadata
-            const { id, type, node_type, nodeType, name, file, exported, metadata, semanticId, semantic_id, ...rest } = nodeRecord;
-            // Merge explicit metadata with extra properties
-            const existingMeta = typeof metadata === 'string' ? JSON.parse(metadata) : (metadata || {});
-            const combinedMeta = { ...existingMeta, ...rest };
-            const wire = {
-                id: String(id),
-                nodeType: (node_type || nodeType || type || 'UNKNOWN'),
-                name: name || '',
-                file: file || '',
-                exported: exported || false,
-                metadata: JSON.stringify(combinedMeta),
-            };
-            // Preserve semanticId as top-level field for v3 protocol
-            const sid = semanticId || semantic_id;
-            if (sid) {
-                wire.semanticId = String(sid);
-            }
-            return wire;
-        });
-        if (this._batching) {
-            this._batchNodes.push(...wireNodes);
-            for (const node of wireNodes) {
-                if (node.file)
-                    this._batchFiles.add(node.file);
-            }
-            return { ok: true };
-        }
-        return this._send('addNodes', { nodes: wireNodes });
-    }
-    /**
-     * Add edges to the graph
-     * Extra properties beyond src/dst/type are merged into metadata
-     */
-    async addEdges(edges, skipValidation = false) {
-        const wireEdges = edges.map(e => {
-            // Cast to unknown first then to Record to allow extra properties
-            const edge = e;
-            // Extract known fields, rest goes to metadata
-            const { src, dst, type, edge_type, edgeType, metadata, ...rest } = edge;
-            // Merge explicit metadata with extra properties
-            const existingMeta = typeof metadata === 'string' ? JSON.parse(metadata) : (metadata || {});
-            const combinedMeta = { ...existingMeta, ...rest };
-            return {
-                src: String(src),
-                dst: String(dst),
-                edgeType: (edge_type || edgeType || type || e.edgeType || 'UNKNOWN'),
-                metadata: JSON.stringify(combinedMeta),
-            };
-        });
-        if (this._batching) {
-            this._batchEdges.push(...wireEdges);
-            return { ok: true };
-        }
-        return this._send('addEdges', { edges: wireEdges, skipValidation });
-    }
-    /**
-     * Delete a node
-     */
-    async deleteNode(id) {
-        return this._send('deleteNode', { id: String(id) });
-    }
-    /**
-     * Delete an edge
-     */
-    async deleteEdge(src, dst, edgeType) {
-        return this._send('deleteEdge', {
-            src: String(src),
-            dst: String(dst),
-            edgeType
-        });
-    }
-    // ===========================================================================
-    // Read Operations
-    // ===========================================================================
-    /**
-     * Get a node by ID
-     */
-    async getNode(id) {
-        const response = await this._send('getNode', { id: String(id) });
-        return response.node || null;
-    }
-    /**
-     * Check if node exists
-     */
-    async nodeExists(id) {
-        const response = await this._send('nodeExists', { id: String(id) });
-        return response.value;
-    }
-    /**
-     * Find nodes by type
-     */
-    async findByType(nodeType) {
-        const response = await this._send('findByType', { nodeType });
-        return response.ids || [];
-    }
-    /**
-     * Find nodes by attributes
-     */
-    async findByAttr(query) {
-        const response = await this._send('findByAttr', { query });
-        return response.ids || [];
-    }
-    // ===========================================================================
-    // Graph Traversal
+    // Streaming Overrides (Unix socket supports streaming)
     // ===========================================================================
     /**
-     * Get neighbors of a node
+     * Negotiate protocol version with server.
+     * Overrides base to set streaming flag.
      */
-    async neighbors(id, edgeTypes = []) {
-        const response = await this._send('neighbors', {
-            id: String(id),
-            edgeTypes
-        });
-        return response.ids || [];
-    }
-    /**
-     * Breadth-first search
-     */
-    async bfs(startIds, maxDepth, edgeTypes = []) {
-        const response = await this._send('bfs', {
-            startIds: startIds.map(String),
-            maxDepth,
-            edgeTypes
-        });
-        return response.ids || [];
-    }
-    /**
-     * Depth-first search
-     */
-    async dfs(startIds, maxDepth, edgeTypes = []) {
-        const response = await this._send('dfs', {
-            startIds: startIds.map(String),
-            maxDepth,
-            edgeTypes
-        });
-        return response.ids || [];
-    }
-    /**
-     * Reachability query - find all nodes reachable from start nodes
-     */
-    async reachability(startIds, maxDepth, edgeTypes = [], backward = false) {
-        const response = await this._send('reachability', {
-            startIds: startIds.map(String),
-            maxDepth,
-            edgeTypes,
-            backward
-        });
-        return response.ids || [];
-    }
-    /**
-     * Get outgoing edges from a node
-     * Parses metadata JSON and spreads it onto the edge object for convenience
-     */
-    async getOutgoingEdges(id, edgeTypes = null) {
-        const response = await this._send('getOutgoingEdges', {
-            id: String(id),
-            edgeTypes
-        });
-        const edges = response.edges || [];
-        // Parse metadata and spread onto edge for convenience
-        return edges.map(e => {
-            let meta = {};
-            try {
-                meta = e.metadata ? JSON.parse(e.metadata) : {};
-            }
-            catch {
-                // Keep empty metadata on parse error
-            }
-            return { ...e, type: e.edgeType, ...meta };
-        });
-    }
-    /**
-     * Get incoming edges to a node
-     * Parses metadata JSON and spreads it onto the edge object for convenience
-     */
-    async getIncomingEdges(id, edgeTypes = null) {
-        const response = await this._send('getIncomingEdges', {
-            id: String(id),
-            edgeTypes
-        });
-        const edges = response.edges || [];
-        // Parse metadata and spread onto edge for convenience
-        return edges.map(e => {
-            let meta = {};
-            try {
-                meta = e.metadata ? JSON.parse(e.metadata) : {};
-            }
-            catch {
-                // Keep empty metadata on parse error
-            }
-            return { ...e, type: e.edgeType, ...meta };
-        });
-    }
-    // ===========================================================================
-    // Stats
-    // ===========================================================================
-    /**
-     * Get node count
-     */
-    async nodeCount() {
-        const response = await this._send('nodeCount');
-        return response.count;
-    }
-    /**
-     * Get edge count
-     */
-    async edgeCount() {
-        const response = await this._send('edgeCount');
-        return response.count;
-    }
-    /**
-     * Count nodes by type
-     */
-    async countNodesByType(types = null) {
-        const response = await this._send('countNodesByType', { types });
-        return response.counts || {};
-    }
-    /**
-     * Count edges by type
-     */
-    async countEdgesByType(edgeTypes = null) {
-        const response = await this._send('countEdgesByType', { edgeTypes });
-        return response.counts || {};
-    }
-    // ===========================================================================
-    // Control
-    // ===========================================================================
-    /**
-     * Flush data to disk
-     */
-    async flush() {
-        return this._send('flush');
-    }
-    /**
-     * Compact the database
-     */
-    async compact() {
-        return this._send('compact');
+    async hello(protocolVersion = 3) {
+        const response = await this._send('hello', { protocolVersion });
+        const hello = response;
+        this._supportsStreaming = hello.features?.includes('streaming') ?? false;
+        return hello;
     }
     /**
-     * Clear the database
-     */
-    async clear() {
-        return this._send('clear');
-    }
-    // ===========================================================================
-    // Bulk Read Operations
-    // ===========================================================================
-    /**
-     * Query nodes (async generator)
+     * Query nodes (async generator).
+     * Overrides base to support streaming for protocol v3+.
      */
     async *queryNodes(query) {
-        // When server supports streaming (protocol v3+), delegate to streaming handler
-        // to correctly handle chunked NodesChunk responses for large result sets.
         if (this._supportsStreaming) {
             yield* this.queryNodesStream(query);
             return;
@@ -574,37 +305,13 @@ export class RFDBClient extends EventEmitter {
             yield node;
         }
     }
-    /**
-     * Build a server query object from an AttrQuery.
-     */
-    _buildServerQuery(query) {
-        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.exported !== undefined)
-            serverQuery.exported = query.exported;
-        return serverQuery;
-    }
     /**
      * Stream nodes matching query with true streaming support.
-     *
-     * Behavior depends on server capabilities:
-     * - Server supports streaming (protocol v3): receives chunked NodesChunk
-     *   responses via StreamQueue. Nodes are yielded as they arrive.
-     * - Server does NOT support streaming (fallback): delegates to queryNodes()
-     *   which yields nodes one by one from bulk response.
-     *
-     * The generator can be aborted by breaking out of the loop or calling .return().
+     * Overrides base to use StreamQueue for protocol v3+.
      */
     async *queryNodesStream(query) {
         if (!this._supportsStreaming) {
-            yield* this.queryNodes(query);
+            yield* super.queryNodes(query);
             return;
         }
         if (!this.connected || !this.socket) {
@@ -614,12 +321,10 @@ export class RFDBClient extends EventEmitter {
         const id = this.reqId++;
         const streamQueue = new StreamQueue();
         this._pendingStreams.set(id, streamQueue);
-        // Build and send request manually (can't use _send which expects single response)
         const request = { requestId: `r${id}`, cmd: 'queryNodes', query: serverQuery };
         const msgBytes = encode(request);
         const header = Buffer.alloc(4);
         header.writeUInt32BE(msgBytes.length);
-        // Register in pending map for error routing
         this.pending.set(id, {
             resolve: () => { this._cleanupStream(id); },
             reject: (error) => {
@@ -627,7 +332,6 @@ export class RFDBClient extends EventEmitter {
                 streamQueue.fail(error);
             },
         });
-        // Start per-chunk timeout (resets on each chunk in _handleStreamingResponse)
         this._resetStreamTimer(id, streamQueue);
         this.socket.write(Buffer.concat([header, Buffer.from(msgBytes)]));
         try {
@@ -640,389 +344,13 @@ export class RFDBClient extends EventEmitter {
         }
     }
     /**
-     * Get all nodes matching query
-     */
-    async getAllNodes(query = {}) {
-        const nodes = [];
-        for await (const node of this.queryNodes(query)) {
-            nodes.push(node);
-        }
-        return nodes;
-    }
-    /**
-     * Get all edges
-     * Parses metadata JSON and spreads it onto the edge object for convenience
+     * Create an isolated batch handle for concurrent-safe batching.
      */
-    async getAllEdges() {
-        const response = await this._send('getAllEdges');
-        const edges = response.edges || [];
-        // Parse metadata and spread onto edge for convenience
-        return edges.map(e => {
-            let meta = {};
-            try {
-                meta = e.metadata ? JSON.parse(e.metadata) : {};
-            }
-            catch {
-                // Keep empty metadata on parse error
-            }
-            return { ...e, type: e.edgeType, ...meta };
-        });
-    }
-    // ===========================================================================
-    // Node Utility Methods
-    // ===========================================================================
-    /**
-     * Check if node is an endpoint (has no outgoing edges)
-     */
-    async isEndpoint(id) {
-        const response = await this._send('isEndpoint', { id: String(id) });
-        return response.value;
-    }
-    /**
-     * Get node identifier string
-     */
-    async getNodeIdentifier(id) {
-        const response = await this._send('getNodeIdentifier', { id: String(id) });
-        return response.identifier || null;
-    }
-    /**
-     * Update node version
-     */
-    async updateNodeVersion(id, version) {
-        return this._send('updateNodeVersion', { id: String(id), version });
-    }
-    /**
-     * Declare metadata fields for server-side indexing.
-     * Call before adding nodes so the server builds indexes on flush.
-     * Returns the number of declared fields.
-     */
-    async declareFields(fields) {
-        const response = await this._send('declareFields', { fields });
-        return response.count || 0;
-    }
-    // ===========================================================================
-    // Datalog API
-    // ===========================================================================
-    /**
-     * Load Datalog rules
-     */
-    async datalogLoadRules(source) {
-        const response = await this._send('datalogLoadRules', { source });
-        return response.count;
-    }
-    /**
-     * Clear Datalog rules
-     */
-    async datalogClearRules() {
-        return this._send('datalogClearRules');
-    }
-    /**
-     * Execute Datalog query
-     */
-    async datalogQuery(query) {
-        const response = await this._send('datalogQuery', { query });
-        return response.results || [];
-    }
-    /**
-     * Check a guarantee (Datalog rule) and return violations
-     */
-    async checkGuarantee(ruleSource) {
-        const response = await this._send('checkGuarantee', { ruleSource });
-        return response.violations || [];
-    }
-    /**
-     * Execute unified Datalog — handles both direct queries and rule-based programs.
-     * Auto-detects the head predicate instead of hardcoding violation(X).
-     */
-    async executeDatalog(source) {
-        const response = await this._send('executeDatalog', { source });
-        return response.results || [];
-    }
-    /**
-     * Ping the server
-     */
-    async ping() {
-        const response = await this._send('ping');
-        return response.pong && response.version ? response.version : false;
-    }
-    // ===========================================================================
-    // Protocol v2 - Multi-Database Commands
-    // ===========================================================================
-    /**
-     * Negotiate protocol version with server
-     * @param protocolVersion - Protocol version to negotiate (default: 2)
-     * @returns Server capabilities including protocolVersion, serverVersion, features
-     */
-    async hello(protocolVersion = 3) {
-        const response = await this._send('hello', { protocolVersion });
-        const hello = response;
-        this._supportsStreaming = hello.features?.includes('streaming') ?? false;
-        return hello;
-    }
-    /**
-     * Create a new database
-     * @param name - Database name (alphanumeric, _, -)
-     * @param ephemeral - If true, database is in-memory and auto-cleaned on disconnect
-     */
-    async createDatabase(name, ephemeral = false) {
-        const response = await this._send('createDatabase', { name, ephemeral });
-        return response;
-    }
-    /**
-     * Open a database and set as current for this session
-     * @param name - Database name
-     * @param mode - 'rw' (read-write) or 'ro' (read-only)
-     */
-    async openDatabase(name, mode = 'rw') {
-        const response = await this._send('openDatabase', { name, mode });
-        return response;
-    }
-    /**
-     * Close current database
-     */
-    async closeDatabase() {
-        return this._send('closeDatabase');
-    }
-    /**
-     * Drop (delete) a database - must not be in use
-     * @param name - Database name
-     */
-    async dropDatabase(name) {
-        return this._send('dropDatabase', { name });
-    }
-    /**
-     * List all databases
-     */
-    async listDatabases() {
-        const response = await this._send('listDatabases');
-        return response;
-    }
-    /**
-     * Get current database for this session
-     */
-    async currentDatabase() {
-        const response = await this._send('currentDatabase');
-        return response;
-    }
-    // ===========================================================================
-    // Snapshot Operations
-    // ===========================================================================
-    /**
-     * Convert a SnapshotRef to wire format payload fields.
-     *
-     * - number -> { version: N }
-     * - { tag, value } -> { tagKey, tagValue }
-     */
-    _resolveSnapshotRef(ref) {
-        if (typeof ref === 'number')
-            return { version: ref };
-        return { tagKey: ref.tag, tagValue: ref.value };
-    }
-    /**
-     * Compute diff between two snapshots.
-     * @param from - Source snapshot (version number or tag reference)
-     * @param to - Target snapshot (version number or tag reference)
-     * @returns SnapshotDiff with added/removed segments and stats
-     */
-    async diffSnapshots(from, to) {
-        const response = await this._send('diffSnapshots', {
-            from: this._resolveSnapshotRef(from),
-            to: this._resolveSnapshotRef(to),
-        });
-        return response.diff;
-    }
-    /**
-     * Tag a snapshot with key-value metadata.
-     * @param version - Snapshot version to tag
-     * @param tags - Key-value pairs to apply (e.g. { "release": "v1.0" })
-     */
-    async tagSnapshot(version, tags) {
-        await this._send('tagSnapshot', { version, tags });
-    }
-    /**
-     * Find a snapshot by tag key/value pair.
-     * @param tagKey - Tag key to search for
-     * @param tagValue - Tag value to match
-     * @returns Snapshot version number, or null if not found
-     */
-    async findSnapshot(tagKey, tagValue) {
-        const response = await this._send('findSnapshot', { tagKey, tagValue });
-        return response.version;
-    }
-    /**
-     * List snapshots, optionally filtered by tag key.
-     * @param filterTag - Optional tag key to filter by (only snapshots with this tag)
-     * @returns Array of SnapshotInfo objects
-     */
-    async listSnapshots(filterTag) {
-        const payload = {};
-        if (filterTag !== undefined)
-            payload.filterTag = filterTag;
-        const response = await this._send('listSnapshots', payload);
-        return response.snapshots;
-    }
-    // ===========================================================================
-    // Batch Operations
-    // ===========================================================================
-    /**
-     * Begin a batch operation.
-     * While batching, addNodes/addEdges buffer locally instead of sending to server.
-     * Call commitBatch() to send all buffered data atomically.
-     */
-    beginBatch() {
-        if (this._batching)
-            throw new Error('Batch already in progress');
-        this._batching = true;
-        this._batchNodes = [];
-        this._batchEdges = [];
-        this._batchFiles = new Set();
-    }
-    /**
-     * Synchronously batch a single node. Must be inside beginBatch/commitBatch.
-     * Skips async wrapper — pushes directly to batch array.
-     */
-    batchNode(node) {
-        if (!this._batching)
-            throw new Error('No batch in progress');
-        const nodeRecord = node;
-        const { id, type, node_type, nodeType, name, file, exported, metadata, semanticId, semantic_id, ...rest } = nodeRecord;
-        const existingMeta = typeof metadata === 'string' ? JSON.parse(metadata) : (metadata || {});
-        const combinedMeta = { ...existingMeta, ...rest };
-        const wire = {
-            id: String(id),
-            nodeType: (node_type || nodeType || type || 'UNKNOWN'),
-            name: name || '',
-            file: file || '',
-            exported: exported || false,
-            metadata: JSON.stringify(combinedMeta),
-        };
-        const sid = semanticId || semantic_id;
-        if (sid) {
-            wire.semanticId = String(sid);
-        }
-        this._batchNodes.push(wire);
-        if (wire.file)
-            this._batchFiles.add(wire.file);
-    }
-    /**
-     * Synchronously batch a single edge. Must be inside beginBatch/commitBatch.
-     */
-    batchEdge(edge) {
-        if (!this._batching)
-            throw new Error('No batch in progress');
-        const edgeRecord = edge;
-        const { src, dst, type, edge_type, edgeType, metadata, ...rest } = edgeRecord;
-        const existingMeta = typeof metadata === 'string' ? JSON.parse(metadata) : (metadata || {});
-        const combinedMeta = { ...existingMeta, ...rest };
-        this._batchEdges.push({
-            src: String(src),
-            dst: String(dst),
-            edgeType: (edge_type || edgeType || type || edge.edgeType || 'UNKNOWN'),
-            metadata: JSON.stringify(combinedMeta),
-        });
-    }
-    /**
-     * Commit the current batch to the server.
-     * Sends all buffered nodes/edges with the list of changed files.
-     * Server atomically replaces old data for changed files with new data.
-     */
-    async commitBatch(tags) {
-        if (!this._batching)
-            throw new Error('No batch in progress');
-        const allNodes = this._batchNodes;
-        const allEdges = this._batchEdges;
-        const changedFiles = [...this._batchFiles];
-        this._batching = false;
-        this._batchNodes = [];
-        this._batchEdges = [];
-        this._batchFiles = new Set();
-        // Chunk large batches to stay under server's 100MB message limit.
-        // First chunk includes changedFiles (triggers old data deletion),
-        // subsequent chunks use empty changedFiles (additive only).
-        const CHUNK = 10_000;
-        if (allNodes.length <= CHUNK && allEdges.length <= CHUNK) {
-            const response = await this._send('commitBatch', {
-                changedFiles, nodes: allNodes, edges: allEdges, tags,
-            });
-            return response.delta;
-        }
-        const merged = {
-            changedFiles,
-            nodesAdded: 0, nodesRemoved: 0,
-            edgesAdded: 0, edgesRemoved: 0,
-            changedNodeTypes: [], changedEdgeTypes: [],
-        };
-        const nodeTypes = new Set();
-        const edgeTypes = new Set();
-        const maxI = Math.max(Math.ceil(allNodes.length / CHUNK), Math.ceil(allEdges.length / CHUNK), 1);
-        for (let i = 0; i < maxI; i++) {
-            const nodes = allNodes.slice(i * CHUNK, (i + 1) * CHUNK);
-            const edges = allEdges.slice(i * CHUNK, (i + 1) * CHUNK);
-            const response = await this._send('commitBatch', {
-                changedFiles: i === 0 ? changedFiles : [],
-                nodes, edges, tags,
-            });
-            const d = response.delta;
-            merged.nodesAdded += d.nodesAdded;
-            merged.nodesRemoved += d.nodesRemoved;
-            merged.edgesAdded += d.edgesAdded;
-            merged.edgesRemoved += d.edgesRemoved;
-            for (const t of d.changedNodeTypes)
-                nodeTypes.add(t);
-            for (const t of d.changedEdgeTypes)
-                edgeTypes.add(t);
-        }
-        merged.changedNodeTypes = [...nodeTypes];
-        merged.changedEdgeTypes = [...edgeTypes];
-        return merged;
-    }
-    /**
-     * Abort the current batch, discarding all buffered data.
-     */
-    abortBatch() {
-        this._batching = false;
-        this._batchNodes = [];
-        this._batchEdges = [];
-        this._batchFiles = new Set();
-    }
-    /**
-     * Check if a batch is currently in progress.
-     */
-    isBatching() {
-        return this._batching;
-    }
-    /**
-     * Find files that depend on the given changed files.
-     * Uses backward reachability to find dependent modules.
-     *
-     * Note: For large result sets, each reachable node requires a separate
-     * getNode RPC. A future server-side optimization could return file paths
-     * directly from the reachability query.
-     */
-    async findDependentFiles(changedFiles) {
-        const nodeIds = [];
-        for (const file of changedFiles) {
-            const ids = await this.findByAttr({ file });
-            nodeIds.push(...ids);
-        }
-        if (nodeIds.length === 0)
-            return [];
-        const reachable = await this.reachability(nodeIds, 2, ['IMPORTS_FROM', 'DEPENDS_ON', 'CALLS'], true);
-        const changedSet = new Set(changedFiles);
-        const files = new Set();
-        for (const id of reachable) {
-            const node = await this.getNode(id);
-            if (node?.file && !changedSet.has(node.file)) {
-                files.add(node.file);
-            }
-        }
-        return [...files];
+    createBatch() {
+        return new BatchHandle(this);
     }
     /**
      * Unref the socket so it doesn't keep the process alive.
-     *
-     * Call this in test environments to allow process to exit
-     * even if connections remain open.
      */
     unref() {
         if (this.socket) {
@@ -1039,17 +367,44 @@ export class RFDBClient extends EventEmitter {
             this.connected = false;
         }
     }
-    /**
-     * Shutdown the server
-     */
-    async shutdown() {
-        try {
-            await this._send('shutdown');
-        }
-        catch {
-            // Expected - server closes connection
-        }
-        await this.close();
+}
+/**
+ * Isolated batch handle for concurrent-safe batching (REG-487).
+ */
+export class BatchHandle {
+    client;
+    _nodes = [];
+    _edges = [];
+    _files = new Set();
+    constructor(client) {
+        this.client = client;
+    }
+    addNode(node, file) {
+        this._nodes.push(node);
+        if (file)
+            this._files.add(file);
+        else if (node.file)
+            this._files.add(node.file);
+    }
+    addEdge(edge) {
+        this._edges.push(edge);
+    }
+    addFile(file) {
+        this._files.add(file);
+    }
+    async commit(tags, deferIndex, protectedTypes) {
+        const nodes = this._nodes;
+        const edges = this._edges;
+        const changedFiles = [...this._files];
+        this._nodes = [];
+        this._edges = [];
+        this._files = new Set();
+        return this.client._sendCommitBatch(changedFiles, nodes, edges, tags, deferIndex, protectedTypes);
+    }
+    abort() {
+        this._nodes = [];
+        this._edges = [];
+        this._files = new Set();
     }
 }
 export default RFDBClient;