@grafema/rfdb-client 0.2.11 → 0.3.0-beta

package/ts/rfdb-client-locking.test.ts

@@ -0,0 +1,897 @@
+/**
+ * RFDBClient Locking Tests (REG-523 STEP 2.5)
+ *
+ * These tests lock the existing behavior of RFDBClient BEFORE the refactoring
+ * that extracts BaseRFDBClient. If any test breaks during refactoring, it means
+ * existing behavior was altered — the refactoring is wrong.
+ *
+ * Tested areas:
+ * - Constructor and initial state
+ * - _send() framing: length-prefix + msgpack encoding
+ * - All key methods call _send() with correct command names
+ * - Batch operations (client-side only, no server needed)
+ * - Error handling for disconnected state
+ * - _handleData() length-prefix parsing and msgpack decoding
+ * - _parseRequestId() parsing logic
+ * - Event emission patterns
+ *
+ * NOTE: Tests run against dist/ (build first with pnpm build).
+ * Uses node:test and node:assert (project standard).
+ */
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { EventEmitter } from 'node:events';
+import { encode, decode } from '@msgpack/msgpack';
+import { RFDBClient, BatchHandle } from '../dist/client.js';
+
+// =============================================================================
+// Part 1: Constructor and Initial State
+// =============================================================================
+
+describe('RFDBClient — Constructor and Initial State (Locking)', () => {
+  it('should create instance with default socket path', () => {
+    const client = new RFDBClient();
+    assert.strictEqual(client.socketPath, '/tmp/rfdb.sock');
+    assert.strictEqual(client.connected, false);
+  });
+
+  it('should create instance with custom socket path', () => {
+    const client = new RFDBClient('/custom/path.sock');
+    assert.strictEqual(client.socketPath, '/custom/path.sock');
+  });
+
+  it('should not be connected initially', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.strictEqual(client.connected, false);
+  });
+
+  it('should be an EventEmitter', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.ok(client instanceof EventEmitter);
+  });
+
+  it('should not be batching initially', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.strictEqual(client.isBatching(), false);
+  });
+
+  it('should not support streaming initially', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.strictEqual(client.supportsStreaming, false);
+  });
+});
+
+// =============================================================================
+// Part 2: _send() requires connection — all methods should throw when disconnected
+// =============================================================================
+
+describe('RFDBClient — Methods Throw When Not Connected (Locking)', () => {
+  let client: InstanceType<typeof RFDBClient>;
+
+  beforeEach(() => {
+    client = new RFDBClient('/tmp/nonexistent.sock');
+  });
+
+  it('ping() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.ping(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('hello() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.hello(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('addNodes() throws when not connected and not batching', async () => {
+    await assert.rejects(
+      () => client.addNodes([{ id: 'n1', type: 'FUNCTION', name: 'foo', file: 'a.js' }]),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('addEdges() throws when not connected and not batching', async () => {
+    await assert.rejects(
+      () => client.addEdges([{ src: 'n1', dst: 'n2', edgeType: 'CALLS' as any, metadata: '{}' }]),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('getNode() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.getNode('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('nodeExists() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.nodeExists('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('findByType() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.findByType('FUNCTION' as any),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('findByAttr() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.findByAttr({ file: 'test.js' }),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('neighbors() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.neighbors('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('bfs() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.bfs(['n1'], 3),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('dfs() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.dfs(['n1'], 3),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('reachability() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.reachability(['n1'], 3),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('getOutgoingEdges() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.getOutgoingEdges('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('getIncomingEdges() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.getIncomingEdges('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('nodeCount() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.nodeCount(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('edgeCount() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.edgeCount(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('countNodesByType() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.countNodesByType(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('countEdgesByType() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.countEdgesByType(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('flush() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.flush(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('compact() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.compact(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('clear() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.clear(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('deleteNode() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.deleteNode('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('deleteEdge() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.deleteEdge('n1', 'n2', 'CALLS' as any),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('createDatabase() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.createDatabase('test'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('openDatabase() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.openDatabase('test'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('closeDatabase() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.closeDatabase(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('dropDatabase() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.dropDatabase('test'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('listDatabases() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.listDatabases(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('currentDatabase() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.currentDatabase(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('datalogLoadRules() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.datalogLoadRules('violation(X) :- node(X, "FUNCTION").'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('datalogClearRules() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.datalogClearRules(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('datalogQuery() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.datalogQuery('?- node(X, "FUNCTION").'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('checkGuarantee() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.checkGuarantee('violation(X) :- node(X, "FUNCTION").'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('executeDatalog() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.executeDatalog('violation(X) :- node(X, "FUNCTION").'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('updateNodeVersion() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.updateNodeVersion('n1', 'v2'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('declareFields() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.declareFields([{ name: 'async' }]),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('isEndpoint() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.isEndpoint('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('getNodeIdentifier() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.getNodeIdentifier('n1'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('diffSnapshots() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.diffSnapshots(1, 2),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('tagSnapshot() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.tagSnapshot(1, { release: 'v1.0' }),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('findSnapshot() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.findSnapshot('release', 'v1.0'),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('listSnapshots() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.listSnapshots(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+
+  it('rebuildIndexes() throws when not connected', async () => {
+    await assert.rejects(
+      () => client.rebuildIndexes(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+});
+
+// =============================================================================
+// Part 3: Batch operations (client-side state only)
+// =============================================================================
+
+describe('RFDBClient — Batch Operations (Locking)', () => {
+  it('beginBatch enables batching state', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.strictEqual(client.isBatching(), false);
+    client.beginBatch();
+    assert.strictEqual(client.isBatching(), true);
+  });
+
+  it('double beginBatch throws', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+    assert.throws(
+      () => client.beginBatch(),
+      { message: 'Batch already in progress' }
+    );
+  });
+
+  it('abortBatch resets batching state', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+    client.abortBatch();
+    assert.strictEqual(client.isBatching(), false);
+  });
+
+  it('abortBatch when not batching is a no-op (no throw)', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.abortBatch(); // should not throw
+    assert.strictEqual(client.isBatching(), false);
+  });
+
+  it('commitBatch without beginBatch throws', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    await assert.rejects(
+      () => client.commitBatch(),
+      { message: 'No batch in progress' }
+    );
+  });
+
+  it('addNodes during batch returns { ok: true } without sending', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+    const result = await client.addNodes([
+      { id: 'n1', type: 'FUNCTION', name: 'foo', file: 'a.js' },
+    ]);
+    assert.deepStrictEqual(result, { ok: true });
+    assert.strictEqual(client.isBatching(), true);
+  });
+
+  it('addEdges during batch returns { ok: true } without sending', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+    const result = await client.addEdges([
+      { src: 'n1', dst: 'n2', edgeType: 'CALLS' as any, metadata: '{}' },
+    ]);
+    assert.deepStrictEqual(result, { ok: true });
+  });
+
+  it('batchNode pushes directly into batch buffer', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+    client.batchNode({ id: 'n1', type: 'FUNCTION', name: 'foo', file: 'a.js' });
+    // Verify still batching (node was buffered, not sent)
+    assert.strictEqual(client.isBatching(), true);
+  });
+
+  it('batchNode throws when not batching', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.throws(
+      () => client.batchNode({ id: 'n1', type: 'FUNCTION', name: 'foo', file: 'a.js' }),
+      { message: 'No batch in progress' }
+    );
+  });
+
+  it('batchEdge pushes directly into batch buffer', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+    client.batchEdge({ src: 'n1', dst: 'n2', edgeType: 'CALLS', metadata: '{}' });
+    assert.strictEqual(client.isBatching(), true);
+  });
+
+  it('batchEdge throws when not batching', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    assert.throws(
+      () => client.batchEdge({ src: 'n1', dst: 'n2', edgeType: 'CALLS', metadata: '{}' }),
+      { message: 'No batch in progress' }
+    );
+  });
+});
+
+// =============================================================================
+// Part 4: BatchHandle (isolated batch)
+// =============================================================================
+
+describe('RFDBClient — BatchHandle (Locking)', () => {
+  it('createBatch returns a BatchHandle', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const batch = client.createBatch();
+    assert.ok(batch instanceof BatchHandle);
+  });
+
+  it('BatchHandle addNode and addEdge buffer independently', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const batch = client.createBatch();
+    batch.addNode(
+      { id: 'n1', nodeType: 'FUNCTION' as any, name: 'foo', file: 'a.js', exported: false, metadata: '{}' },
+      'a.js'
+    );
+    batch.addEdge({ src: 'n1', dst: 'n2', edgeType: 'CALLS' as any, metadata: '{}' });
+    // BatchHandle does not affect client batching state
+    assert.strictEqual(client.isBatching(), false);
+  });
+
+  it('BatchHandle.abort clears buffers', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const batch = client.createBatch();
+    batch.addNode(
+      { id: 'n1', nodeType: 'FUNCTION' as any, name: 'foo', file: 'a.js', exported: false, metadata: '{}' },
+    );
+    batch.abort();
+    // After abort, commit should send empty batch (no nodes/edges)
+    // We can't fully test this without connection, but abort should not throw
+    assert.strictEqual(client.isBatching(), false);
+  });
+});
+
+// =============================================================================
+// Part 5: addNodes wire format (metadata merging)
+// =============================================================================
+
+describe('RFDBClient — addNodes Wire Format (Locking)', () => {
+  /**
+   * Lock: extra fields beyond id/type/name/file/exported/metadata are
+   * merged into the metadata JSON string. This behavior was added in REG-274.
+   */
+  it('addNodes during batch merges extra fields into metadata', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+
+    await client.addNodes([{
+      id: 'n1',
+      type: 'SCOPE',
+      name: 'if_branch',
+      file: 'test.js',
+      constraints: [{ variable: 'x', operator: '!==', value: 'null' }],
+      scopeType: 'if_statement',
+    } as any]);
+
+    // The node was buffered. We verify the format by checking that
+    // abortBatch doesn't crash (the node was successfully transformed).
+    // Full format verification requires commitBatch with a connected server.
+    client.abortBatch();
+    assert.strictEqual(client.isBatching(), false);
+  });
+
+  it('addNodes supports node_type, nodeType, and type aliases', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+
+    // Verify no crash with various type-field aliases
+    client.beginBatch();
+    await client.addNodes([
+      { id: 'n1', type: 'FUNCTION', name: 'foo', file: 'a.js' },
+      { id: 'n2', node_type: 'CLASS', name: 'Bar', file: 'b.js' } as any,
+      { id: 'n3', nodeType: 'MODULE', name: 'mod', file: 'c.js' } as any,
+    ]);
+    client.abortBatch();
+  });
+});
+
+// =============================================================================
+// Part 6: addEdges wire format
+// =============================================================================
+
+describe('RFDBClient — addEdges Wire Format (Locking)', () => {
+  it('addEdges during batch merges extra fields into metadata', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+
+    await client.addEdges([{
+      src: 'n1',
+      dst: 'n2',
+      edgeType: 'CALLS' as any,
+      callSite: 'line:42',
+      confidence: 0.95,
+    } as any]);
+
+    client.abortBatch();
+  });
+
+  it('addEdges supports type, edge_type, edgeType aliases', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.beginBatch();
+
+    await client.addEdges([
+      { src: 'n1', dst: 'n2', type: 'CALLS', metadata: '{}' } as any,
+      { src: 'n2', dst: 'n3', edge_type: 'CONTAINS', metadata: '{}' } as any,
+      { src: 'n3', dst: 'n4', edgeType: 'IMPORTS_FROM' as any, metadata: '{}' },
+    ]);
+
+    client.abortBatch();
+  });
+});
+
+// =============================================================================
+// Part 7: _handleData length-prefix framing
+// =============================================================================
+
+describe('RFDBClient — _handleData Framing (Locking)', () => {
+  /**
+   * To test _handleData, we need to simulate a connected client and inject
+   * data chunks. We do this by accessing the private _handleData method
+   * via a subclass trick.
+   */
+
+  it('should parse a single complete message', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    // Simulate connected state
+    (client as any).connected = true;
+    (client as any).socket = { write: () => {}, removeListener: () => {}, once: () => {} };
+
+    // Set up a pending request that the response will resolve
+    const promise = new Promise<any>((resolve, reject) => {
+      (client as any).pending.set(0, { resolve, reject });
+    });
+
+    // Build a framed message: 4-byte BE length + msgpack payload
+    const response = { requestId: 'r0', pong: true, version: '1.0.0' };
+    const msgBytes = encode(response);
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(msgBytes.length);
+    const frame = Buffer.concat([header, Buffer.from(msgBytes)]);
+
+    // Inject the data
+    (client as any)._handleData(frame);
+
+    const result = await promise;
+    assert.strictEqual(result.pong, true);
+    assert.strictEqual(result.version, '1.0.0');
+  });
+
+  it('should handle split delivery (partial frames)', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    (client as any).connected = true;
+    (client as any).socket = { write: () => {}, removeListener: () => {}, once: () => {} };
+
+    const promise = new Promise<any>((resolve, reject) => {
+      (client as any).pending.set(0, { resolve, reject });
+    });
+
+    const response = { requestId: 'r0', ok: true };
+    const msgBytes = encode(response);
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(msgBytes.length);
+    const frame = Buffer.concat([header, Buffer.from(msgBytes)]);
+
+    // Split the frame in half and deliver in two chunks
+    const mid = Math.floor(frame.length / 2);
+    (client as any)._handleData(frame.subarray(0, mid));
+    (client as any)._handleData(frame.subarray(mid));
+
+    const result = await promise;
+    assert.strictEqual(result.ok, true);
+  });
+
+  it('should handle multiple messages in a single chunk', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    (client as any).connected = true;
+    (client as any).socket = { write: () => {}, removeListener: () => {}, once: () => {} };
+
+    const promise0 = new Promise<any>((resolve, reject) => {
+      (client as any).pending.set(0, { resolve, reject });
+    });
+    const promise1 = new Promise<any>((resolve, reject) => {
+      (client as any).pending.set(1, { resolve, reject });
+    });
+
+    // Build two framed messages
+    const buildFrame = (resp: any) => {
+      const msgBytes = encode(resp);
+      const header = Buffer.alloc(4);
+      header.writeUInt32BE(msgBytes.length);
+      return Buffer.concat([header, Buffer.from(msgBytes)]);
+    };
+
+    const frame0 = buildFrame({ requestId: 'r0', count: 5 });
+    const frame1 = buildFrame({ requestId: 'r1', count: 10 });
+    const combined = Buffer.concat([frame0, frame1]);
+
+    // Deliver both in a single chunk
+    (client as any)._handleData(combined);
+
+    const result0 = await promise0;
+    const result1 = await promise1;
+    assert.strictEqual(result0.count, 5);
+    assert.strictEqual(result1.count, 10);
+  });
+
+  it('should reject pending request when response has error field', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    (client as any).connected = true;
+    (client as any).socket = { write: () => {}, removeListener: () => {}, once: () => {} };
+
+    const promise = new Promise<any>((resolve, reject) => {
+      (client as any).pending.set(0, { resolve, reject });
+    });
+
+    const response = { requestId: 'r0', error: 'No database selected' };
+    const msgBytes = encode(response);
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(msgBytes.length);
+    const frame = Buffer.concat([header, Buffer.from(msgBytes)]);
+
+    (client as any)._handleData(frame);
+
+    await assert.rejects(promise, { message: 'No database selected' });
+  });
+});
+
+// =============================================================================
+// Part 8: close() and shutdown() behavior
+// =============================================================================
+
+describe('RFDBClient — close() and shutdown() (Locking)', () => {
+  it('close() when not connected does not throw', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    await client.close(); // should not throw
+    assert.strictEqual(client.connected, false);
+  });
+
+  it('close() sets connected to false', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    // Simulate a connected state
+    (client as any).connected = true;
+    (client as any).socket = { destroy: () => {} };
+
+    await client.close();
+    assert.strictEqual(client.connected, false);
+  });
+
+  it('unref() when not connected does not throw', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    client.unref(); // should not throw
+  });
+});
+
+// =============================================================================
+// Part 9: _parseRequestId behavior
+// =============================================================================
+
+describe('RFDBClient — _parseRequestId (Locking)', () => {
+  /**
+   * We access the private method through the class prototype for testing.
+   */
+  it('should parse "r0" to 0', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._parseRequestId('r0');
+    assert.strictEqual(result, 0);
+  });
+
+  it('should parse "r123" to 123', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._parseRequestId('r123');
+    assert.strictEqual(result, 123);
+  });
+
+  it('should return null for string not starting with "r"', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._parseRequestId('x42');
+    assert.strictEqual(result, null);
+  });
+
+  it('should return null for empty string', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._parseRequestId('');
+    assert.strictEqual(result, null);
+  });
+
+  it('should return null for "r" without number', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._parseRequestId('r');
+    assert.strictEqual(result, null);
+  });
+
+  it('should return null for "rNaN"', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._parseRequestId('rNaN');
+    assert.strictEqual(result, null);
+  });
+});
+
+// =============================================================================
+// Part 10: Snapshot ref resolution (locking _resolveSnapshotRef)
+// =============================================================================
+
+describe('RFDBClient — _resolveSnapshotRef (Locking)', () => {
+  it('should resolve number ref to { version }', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._resolveSnapshotRef(42);
+    assert.deepStrictEqual(result, { version: 42 });
+  });
+
+  it('should resolve tag ref to { tagKey, tagValue }', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._resolveSnapshotRef({ tag: 'release', value: 'v1.0' });
+    assert.deepStrictEqual(result, { tagKey: 'release', tagValue: 'v1.0' });
+  });
+
+  it('should handle version 0', () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    const result = (client as any)._resolveSnapshotRef(0);
+    assert.deepStrictEqual(result, { version: 0 });
+  });
+});
+
+// =============================================================================
+// Part 11: queryNodes async generator behavior (non-streaming)
+// =============================================================================
+
+describe('RFDBClient — queryNodes non-streaming fallback (Locking)', () => {
+  it('queryNodesStream delegates to queryNodes when streaming not supported', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    // supportsStreaming is false by default
+    assert.strictEqual(client.supportsStreaming, false);
+
+    // queryNodesStream should throw "Not connected" (same path as queryNodes)
+    const gen = client.queryNodesStream({ nodeType: 'FUNCTION' });
+    await assert.rejects(
+      () => gen.next(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+});
+
+// =============================================================================
+// Part 12: getAllNodes delegates to queryNodes
+// =============================================================================
+
+describe('RFDBClient — getAllNodes (Locking)', () => {
+  it('getAllNodes throws when not connected', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    await assert.rejects(
+      () => client.getAllNodes(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+});
+
+// =============================================================================
+// Part 13: getAllEdges behavior
+// =============================================================================
+
+describe('RFDBClient — getAllEdges (Locking)', () => {
+  it('getAllEdges throws when not connected', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    await assert.rejects(
+      () => client.getAllEdges(),
+      { message: 'Not connected to RFDB server' }
+    );
+  });
+});
+
+// =============================================================================
+// Part 14: Edge metadata parsing on getOutgoingEdges/getIncomingEdges
+// =============================================================================
+
+describe('RFDBClient — Edge Metadata Parsing (Locking)', () => {
+  /**
+   * Lock: getOutgoingEdges and getIncomingEdges parse metadata JSON and
+   * spread it onto the edge object. This is client-side convenience logic.
+   */
+
+  it('getOutgoingEdges parses and spreads metadata', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    (client as any).connected = true;
+    (client as any).socket = { write: () => {}, removeListener: () => {}, once: () => {} };
+
+    // Intercept _send by resolving the pending request with a mock response
+    const originalReqId = (client as any).reqId;
+    const callPromise = client.getOutgoingEdges('n1');
+
+    // Simulate response
+    const response = {
+      requestId: `r${originalReqId}`,
+      edges: [
+        { src: 'n1', dst: 'n2', edgeType: 'CALLS', metadata: '{"callSite":"line:42","confidence":0.9}' },
+      ],
+    };
+    const msgBytes = encode(response);
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(msgBytes.length);
+    (client as any)._handleData(Buffer.concat([header, Buffer.from(msgBytes)]));
+
+    const result = await callPromise;
+    assert.strictEqual(result.length, 1);
+    assert.strictEqual(result[0].src, 'n1');
+    assert.strictEqual(result[0].dst, 'n2');
+    assert.strictEqual((result[0] as any).callSite, 'line:42');
+    assert.strictEqual((result[0] as any).confidence, 0.9);
+    // type alias is set from edgeType
+    assert.strictEqual((result[0] as any).type, 'CALLS');
+  });
+});
+
+// =============================================================================
+// Part 15: connect() returns immediately if already connected
+// =============================================================================
+
+describe('RFDBClient — connect() idempotency (Locking)', () => {
+  it('connect() returns immediately if already connected', async () => {
+    const client = new RFDBClient('/tmp/test.sock');
+    (client as any).connected = true;
+
+    // Should return immediately without attempting socket connection
+    await client.connect();
+    assert.strictEqual(client.connected, true);
+  });
+});