observability-toolkit 2.0.0 → 2.1.0

package/dist/lib/observability/indexer.test.js

@@ -0,0 +1,713 @@
+import { describe, it, before, after, beforeEach } from 'node:test';
+import * as assert from 'node:assert';
+import * as fs from 'fs';
+import * as path from 'path';
+import { gzipSync } from 'zlib';
+import { buildIndex, readIndex, isIndexStale, getIndexPath, queryIndex, readLinesByNumber, buildAndWriteIndex, getOrBuildIndex, } from './indexer.js';
+import { getSharedTempDir, clearTempDir, removeSharedTempDir, writeJsonlFileAsync, resetCleanupFailureCount, assertNoCleanupFailures, } from '../../test-helpers/file-utils.js';
+import { COUNT_FIVE, COUNT_FOUR, COUNT_NINETY, COUNT_THREE, COUNT_TEN, COUNT_TWENTY_FIVE, COUNT_TWO, COUNT_FIFTY, EPOCH_PLUS_HALF_SECOND_MS, EPOCH_SEC, EPOCH_SEC_PLUS_ONE, EPOCH_SEC_PLUS_TWO, NANO_HALF_SECOND, NANO_ZERO, } from '../../test-helpers/test-constants.js';
+import { requireDefined } from '../../test-helpers/assertions.js';
+const FILE_TOUCH_DELAY_MS = COUNT_TEN;
+const INDEX_LINE_NUMBER_SEVENTY_FIVE = 75;
+describe('Indexer', () => {
+    let tempDir;
+    before(() => {
+        tempDir = getSharedTempDir('Indexer');
+    });
+    beforeEach(() => {
+        resetCleanupFailureCount();
+        clearTempDir(tempDir);
+    });
+    after(() => {
+        removeSharedTempDir('Indexer');
+        assertNoCleanupFailures();
+    });
+    describe('getIndexPath', () => {
+        it('should append .idx to the file path', () => {
+            assert.strictEqual(getIndexPath('/path/to/file.jsonl'), '/path/to/file.jsonl.idx');
+        });
+        it('should strip .gz before appending .idx for gzipped files', () => {
+            assert.strictEqual(getIndexPath('/path/to/file.jsonl.gz'), '/path/to/file.jsonl.idx');
+        });
+        it('should handle various gzip file paths', () => {
+            assert.strictEqual(getIndexPath('traces-2026-01-28.jsonl.gz'), 'traces-2026-01-28.jsonl.idx');
+            assert.strictEqual(getIndexPath('/home/user/.claude/telemetry/logs-2026-01-28.jsonl.gz'), '/home/user/.claude/telemetry/logs-2026-01-28.jsonl.idx');
+        });
+    });
+    describe('buildIndex for traces', () => {
+        it('should build an index with correct metadata', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'test-operation',
+                    startTime: [EPOCH_SEC, NANO_ZERO],
+                    resource: { serviceName: 'test-service' },
+                },
+                {
+                    traceId: 'trace2',
+                    spanId: 'span2',
+                    name: 'another-op',
+                    startTime: [EPOCH_SEC_PLUS_ONE, NANO_HALF_SECOND],
+                    resource: { serviceName: 'other-service' },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.version, 1);
+            assert.strictEqual(index.sourceFile, filePath);
+            assert.ok(index.sourceMtime > 0);
+            assert.strictEqual(index.entries.length, COUNT_TWO);
+        });
+        it('should extract trace fields correctly', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'test-operation',
+                    startTime: [EPOCH_SEC, NANO_HALF_SECOND], // 500ms
+                    resource: { serviceName: 'test-service' },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.entries.length, 1);
+            const entry = index.entries[0];
+            assert.strictEqual(entry.lineNumber, 1);
+            assert.strictEqual(entry.traceId, 'trace1');
+            assert.strictEqual(entry.spanName, 'test-operation');
+            assert.strictEqual(entry.serviceName, 'test-service');
+            assert.strictEqual(entry.timestamp, EPOCH_PLUS_HALF_SECOND_MS); // ms
+        });
+        it('should skip malformed lines but track line numbers', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const content = [
+                JSON.stringify({ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }),
+                'not valid json',
+                JSON.stringify({ traceId: 'trace3', spanId: 'span3', name: 'op3', startTime: [EPOCH_SEC_PLUS_TWO, NANO_ZERO] }),
+            ].join('\n');
+            fs.writeFileSync(filePath, content, 'utf-8');
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.entries.length, COUNT_TWO);
+            assert.strictEqual(index.entries[0].lineNumber, 1);
+            assert.strictEqual(index.entries[1].lineNumber, COUNT_THREE);
+        });
+        it('should build index from gzipped file', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl.gz');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'test-operation',
+                    startTime: [EPOCH_SEC, NANO_ZERO],
+                    resource: { serviceName: 'test-service' },
+                },
+                {
+                    traceId: 'trace2',
+                    spanId: 'span2',
+                    name: 'another-op',
+                    startTime: [EPOCH_SEC_PLUS_ONE, NANO_HALF_SECOND],
+                    resource: { serviceName: 'other-service' },
+                },
+            ];
+            const content = mockSpans.map(s => JSON.stringify(s)).join('\n');
+            fs.writeFileSync(filePath, gzipSync(content));
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.version, 1);
+            assert.strictEqual(index.sourceFile, filePath);
+            assert.strictEqual(index.entries.length, COUNT_TWO);
+            assert.strictEqual(index.entries[0].traceId, 'trace1');
+            assert.strictEqual(index.entries[0].spanName, 'test-operation');
+            assert.strictEqual(index.entries[1].traceId, 'trace2');
+        });
+    });
+    describe('buildIndex for logs', () => {
+        it('should extract log fields correctly', async () => {
+            const filePath = path.join(tempDir, 'logs.jsonl');
+            const mockLogs = [
+                {
+                    timestamp: '2024-01-15T10:00:00.000Z',
+                    severityText: 'ERROR',
+                    body: 'Something went wrong',
+                    traceId: 'trace1',
+                    resource: { serviceName: 'log-service' },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockLogs);
+            const index = await buildIndex(filePath, 'logs');
+            assert.strictEqual(index.entries.length, 1);
+            const entry = index.entries[0];
+            assert.strictEqual(entry.severity, 'ERROR');
+            assert.strictEqual(entry.traceId, 'trace1');
+            assert.strictEqual(entry.serviceName, 'log-service');
+        });
+        it('should handle timestamp as array', async () => {
+            const filePath = path.join(tempDir, 'logs.jsonl');
+            const mockLogs = [
+                {
+                    timestamp: [EPOCH_SEC, NANO_HALF_SECOND],
+                    severity: 'INFO',
+                    body: 'Test message',
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockLogs);
+            const index = await buildIndex(filePath, 'logs');
+            assert.strictEqual(index.entries.length, 1);
+            assert.strictEqual(index.entries[0].timestamp, EPOCH_PLUS_HALF_SECOND_MS);
+        });
+    });
+    describe('buildIndex for metrics', () => {
+        it('should extract metric fields correctly', async () => {
+            const filePath = path.join(tempDir, 'metrics.jsonl');
+            const mockMetrics = [
+                {
+                    timestamp: '2024-01-15T10:00:00.000Z',
+                    name: 'http.request.duration',
+                    value: 100,
+                    resource: { serviceName: 'metric-service' },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockMetrics);
+            const index = await buildIndex(filePath, 'metrics');
+            assert.strictEqual(index.entries.length, 1);
+            const entry = index.entries[0];
+            assert.strictEqual(entry.metricName, 'http.request.duration');
+            assert.strictEqual(entry.serviceName, 'metric-service');
+        });
+    });
+    describe('buildIndex for llm-events', () => {
+        it('should extract llm event fields correctly', async () => {
+            const filePath = path.join(tempDir, 'llm-events.jsonl');
+            const mockEvents = [
+                {
+                    timestamp: '2024-01-15T10:00:00.000Z',
+                    name: 'gen_ai.chat.completion',
+                    attributes: { model: 'claude-3' },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockEvents);
+            const index = await buildIndex(filePath, 'llm-events');
+            assert.strictEqual(index.entries.length, 1);
+            const entry = index.entries[0];
+            assert.strictEqual(entry.spanName, 'gen_ai.chat.completion');
+        });
+    });
+    describe('OTel GenAI agent/tool index fields', () => {
+        it('should extract agentId from trace span attributes', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'invoke_agent',
+                    startTime: [EPOCH_SEC, NANO_ZERO],
+                    attributes: {
+                        'gen_ai.agent.id': 'agent-001',
+                        'gen_ai.agent.name': 'Explore',
+                    },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.entries.length, 1);
+            assert.strictEqual(index.entries[0].agentId, 'agent-001');
+        });
+        it('should extract toolName from trace span attributes', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'execute_tool',
+                    startTime: [EPOCH_SEC, NANO_ZERO],
+                    attributes: {
+                        'gen_ai.tool.name': 'Read',
+                        'gen_ai.tool.call.id': 'toolu_123',
+                    },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.entries.length, 1);
+            assert.strictEqual(index.entries[0].toolName, 'Read');
+        });
+        it('should extract operationName from trace span attributes', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'llm-call',
+                    startTime: [EPOCH_SEC, NANO_ZERO],
+                    attributes: {
+                        'gen_ai.operation.name': 'chat',
+                    },
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.entries.length, 1);
+            assert.strictEqual(index.entries[0].operationName, 'chat');
+        });
+        it('should handle missing agent/tool attributes gracefully', async () => {
+            const filePath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [
+                {
+                    traceId: 'trace1',
+                    spanId: 'span1',
+                    name: 'basic-operation',
+                    startTime: [EPOCH_SEC, NANO_ZERO],
+                },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            const index = await buildIndex(filePath, 'traces');
+            assert.strictEqual(index.entries.length, 1);
+            assert.strictEqual(index.entries[0].agentId, undefined);
+            assert.strictEqual(index.entries[0].toolName, undefined);
+            assert.strictEqual(index.entries[0].operationName, undefined);
+        });
+    });
+    describe('queryIndex OTel GenAI filters', () => {
+        it('should filter by agentId', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, agentId: 'agent-001' },
+                    { lineNumber: 2, timestamp: 0, agentId: 'agent-002' },
+                    { lineNumber: 3, timestamp: 0, agentId: 'agent-001' },
+                ],
+            };
+            const result = queryIndex(index, { agentId: 'agent-001' });
+            assert.deepStrictEqual(result, [1, COUNT_THREE]);
+        });
+        it('should filter by toolName', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, toolName: 'Read' },
+                    { lineNumber: 2, timestamp: 0, toolName: 'Write' },
+                    { lineNumber: 3, timestamp: 0, toolName: 'Read' },
+                ],
+            };
+            const result = queryIndex(index, { toolName: 'Read' });
+            assert.deepStrictEqual(result, [1, COUNT_THREE]);
+        });
+        it('should filter by operationName', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, operationName: 'chat' },
+                    { lineNumber: 2, timestamp: 0, operationName: 'execute_tool' },
+                    { lineNumber: 3, timestamp: 0, operationName: 'chat' },
+                ],
+            };
+            const result = queryIndex(index, { operationName: 'chat' });
+            assert.deepStrictEqual(result, [1, COUNT_THREE]);
+        });
+        it('should combine agentId and toolName filters with AND logic', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, agentId: 'agent-001', toolName: 'Read' },
+                    { lineNumber: 2, timestamp: 0, agentId: 'agent-001', toolName: 'Write' },
+                    { lineNumber: 3, timestamp: 0, agentId: 'agent-002', toolName: 'Read' },
+                ],
+            };
+            const result = queryIndex(index, { agentId: 'agent-001', toolName: 'Read' });
+            assert.deepStrictEqual(result, [1]);
+        });
+    });
+    describe('readIndex', () => {
+        it('should return null for non-existent file', () => {
+            const result = readIndex('/non/existent/path.idx');
+            assert.strictEqual(result, null);
+        });
+        it('should read valid index file', async () => {
+            const jsonlPath = path.join(tempDir, 'traces.jsonl');
+            const idxPath = getIndexPath(jsonlPath);
+            const mockSpans = [{ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }];
+            await writeJsonlFileAsync(jsonlPath, mockSpans);
+            await buildAndWriteIndex(jsonlPath, 'traces');
+            const index = readIndex(idxPath);
+            assert.ok(index !== null);
+            assert.strictEqual(index.version, 1);
+            assert.strictEqual(index.entries.length, 1);
+        });
+        it('should return null for invalid version', () => {
+            const idxPath = path.join(tempDir, 'test.idx');
+            const invalidIndex = { version: 2, sourceFile: 'test', sourceMtime: 0, entries: [] };
+            fs.writeFileSync(idxPath, JSON.stringify(invalidIndex), 'utf-8');
+            const result = readIndex(idxPath);
+            assert.strictEqual(result, null);
+        });
+        it('should return null for malformed JSON', () => {
+            const idxPath = path.join(tempDir, 'test.idx');
+            fs.writeFileSync(idxPath, 'not valid json', 'utf-8');
+            const result = readIndex(idxPath);
+            assert.strictEqual(result, null);
+        });
+    });
+    describe('isIndexStale', () => {
+        it('should return false for fresh index', async () => {
+            const jsonlPath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [{ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }];
+            await writeJsonlFileAsync(jsonlPath, mockSpans);
+            const index = await buildIndex(jsonlPath, 'traces');
+            const stale = isIndexStale(index, jsonlPath);
+            assert.strictEqual(stale, false);
+        });
+        it('should return true when source file is modified', async () => {
+            const jsonlPath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [{ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }];
+            await writeJsonlFileAsync(jsonlPath, mockSpans);
+            const index = await buildIndex(jsonlPath, 'traces');
+            // Wait a bit and modify the file
+            await new Promise(resolve => setTimeout(resolve, FILE_TOUCH_DELAY_MS));
+            fs.appendFileSync(jsonlPath, '\n' + JSON.stringify({ traceId: 'trace2', spanId: 'span2', name: 'op2', startTime: [EPOCH_SEC_PLUS_ONE, NANO_ZERO] }));
+            const stale = isIndexStale(index, jsonlPath);
+            assert.strictEqual(stale, true);
+        });
+        it('should return true when source file does not exist', () => {
+            const fakeIndex = {
+                version: 1,
+                sourceFile: '/non/existent/file.jsonl',
+                sourceMtime: 12345,
+                entries: [],
+            };
+            const stale = isIndexStale(fakeIndex, '/non/existent/file.jsonl');
+            assert.strictEqual(stale, true);
+        });
+    });
+    describe('queryIndex', () => {
+        it('should return null when no indexable filters', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [{ lineNumber: 1, timestamp: 0 }],
+            };
+            const result = queryIndex(index, {});
+            assert.strictEqual(result, null);
+        });
+        it('should filter by traceId', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, traceId: 'trace1' },
+                    { lineNumber: 2, timestamp: 0, traceId: 'trace2' },
+                    { lineNumber: 3, timestamp: 0, traceId: 'trace1' },
+                ],
+            };
+            const result = queryIndex(index, { traceId: 'trace1' });
+            assert.deepStrictEqual(result, [1, COUNT_THREE]);
+        });
+        it('should filter by spanName with substring match', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, spanName: 'user-create' },
+                    { lineNumber: 2, timestamp: 0, spanName: 'user-update' },
+                    { lineNumber: 3, timestamp: 0, spanName: 'db-query' },
+                ],
+            };
+            const result = queryIndex(index, { spanName: 'user' });
+            assert.deepStrictEqual(result, [1, COUNT_TWO]);
+        });
+        it('should filter by severity case-insensitively', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, severity: 'ERROR' },
+                    { lineNumber: 2, timestamp: 0, severity: 'error' },
+                    { lineNumber: 3, timestamp: 0, severity: 'INFO' },
+                ],
+            };
+            const result = queryIndex(index, { severity: 'error' });
+            assert.deepStrictEqual(result, [1, COUNT_TWO]);
+        });
+        it('should filter by metricName with substring match', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, metricName: 'http.request.duration' },
+                    { lineNumber: 2, timestamp: 0, metricName: 'http.response.size' },
+                    { lineNumber: 3, timestamp: 0, metricName: 'db.query.count' },
+                ],
+            };
+            const result = queryIndex(index, { metricName: 'http' });
+            assert.deepStrictEqual(result, [1, COUNT_TWO]);
+        });
+        it('should apply multiple filters with AND logic', () => {
+            const index = {
+                version: 1,
+                sourceFile: 'test.jsonl',
+                sourceMtime: 0,
+                entries: [
+                    { lineNumber: 1, timestamp: 0, traceId: 'trace1', severity: 'ERROR' },
+                    { lineNumber: 2, timestamp: 0, traceId: 'trace1', severity: 'INFO' },
+                    { lineNumber: 3, timestamp: 0, traceId: 'trace2', severity: 'ERROR' },
+                ],
+            };
+            const result = queryIndex(index, { traceId: 'trace1', severity: 'ERROR' });
+            assert.deepStrictEqual(result, [1]);
+        });
+    });
+    describe('readLinesByNumber', () => {
+        it('should read specific lines from file', async () => {
+            const filePath = path.join(tempDir, 'test.jsonl');
+            const data = [
+                { id: 1, name: 'first' },
+                { id: 2, name: 'second' },
+                { id: 3, name: 'third' },
+                { id: 4, name: 'fourth' },
+            ];
+            await writeJsonlFileAsync(filePath, data);
+            const results = await readLinesByNumber(filePath, [COUNT_TWO, COUNT_FOUR]);
+            assert.strictEqual(results.length, COUNT_TWO);
+            assert.strictEqual(results[0].id, COUNT_TWO);
+            assert.strictEqual(results[1].id, COUNT_FOUR);
+        });
+        it('should return empty array for empty line list', async () => {
+            const filePath = path.join(tempDir, 'test.jsonl');
+            await writeJsonlFileAsync(filePath, [{ id: 1 }]);
+            const results = await readLinesByNumber(filePath, []);
+            assert.strictEqual(results.length, 0);
+        });
+        it('should maintain order based on line numbers', async () => {
+            const filePath = path.join(tempDir, 'test.jsonl');
+            const data = [
+                { id: 1 },
+                { id: 2 },
+                { id: 3 },
+            ];
+            await writeJsonlFileAsync(filePath, data);
+            // Request lines out of order
+            const results = await readLinesByNumber(filePath, [COUNT_THREE, 1, COUNT_TWO]);
+            // Should be sorted by line number
+            assert.strictEqual(results.length, COUNT_THREE);
+            assert.strictEqual(results[0].id, 1);
+            assert.strictEqual(results[1].id, COUNT_TWO);
+            assert.strictEqual(results[2].id, COUNT_THREE);
+        });
+        it('should read specific lines from gzipped file', async () => {
+            const filePath = path.join(tempDir, 'test.jsonl.gz');
+            const data = [
+                { id: 1, name: 'first' },
+                { id: 2, name: 'second' },
+                { id: 3, name: 'third' },
+                { id: 4, name: 'fourth' },
+            ];
+            const content = data.map(d => JSON.stringify(d)).join('\n');
+            fs.writeFileSync(filePath, gzipSync(content));
+            const results = await readLinesByNumber(filePath, [COUNT_TWO, COUNT_FOUR]);
+            assert.strictEqual(results.length, COUNT_TWO);
+            assert.strictEqual(results[0].id, COUNT_TWO);
+            assert.strictEqual(results[0].name, 'second');
+            assert.strictEqual(results[1].id, COUNT_FOUR);
+            assert.strictEqual(results[1].name, 'fourth');
+        });
+    });
+    describe('getOrBuildIndex', () => {
+        it('should build index for file without existing index', async () => {
+            const jsonlPath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [{ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }];
+            await writeJsonlFileAsync(jsonlPath, mockSpans);
+            const index = await getOrBuildIndex(jsonlPath, 'traces');
+            assert.ok(index !== null);
+            assert.strictEqual(index.entries.length, 1);
+            // Should have written the index file
+            assert.ok(fs.existsSync(getIndexPath(jsonlPath)));
+        });
+        it('should return cached index when not stale', async () => {
+            const jsonlPath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [{ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }];
+            await writeJsonlFileAsync(jsonlPath, mockSpans);
+            // Build and write index
+            const index1 = await getOrBuildIndex(jsonlPath, 'traces');
+            // Get again - should return from disk (not stale)
+            const index2 = await getOrBuildIndex(jsonlPath, 'traces');
+            // Compare key properties (JSON round-trip strips undefined values)
+            const firstIndex = requireDefined(index1, 'Expected first index');
+            const secondIndex = requireDefined(index2, 'Expected second index');
+            const firstEntry = requireDefined(firstIndex.entries[0], 'Expected first index entry');
+            const secondEntry = requireDefined(secondIndex.entries[0], 'Expected second index entry');
+            assert.strictEqual(firstIndex.version, secondIndex.version);
+            assert.strictEqual(firstIndex.sourceFile, secondIndex.sourceFile);
+            assert.strictEqual(firstIndex.sourceMtime, secondIndex.sourceMtime);
+            assert.strictEqual(firstIndex.entries.length, secondIndex.entries.length);
+            assert.strictEqual(firstEntry.traceId, secondEntry.traceId);
+        });
+        it('should rebuild index when stale', async () => {
+            const jsonlPath = path.join(tempDir, 'traces.jsonl');
+            const mockSpans = [{ traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] }];
+            await writeJsonlFileAsync(jsonlPath, mockSpans);
+            const index1 = await getOrBuildIndex(jsonlPath, 'traces');
+            assert.strictEqual(requireDefined(index1, 'Expected first index').entries.length, 1);
+            // Modify file
+            await new Promise(resolve => setTimeout(resolve, FILE_TOUCH_DELAY_MS));
+            fs.appendFileSync(jsonlPath, '\n' + JSON.stringify({ traceId: 'trace2', spanId: 'span2', name: 'op2', startTime: [EPOCH_SEC_PLUS_ONE, NANO_ZERO] }));
+            const index2 = await getOrBuildIndex(jsonlPath, 'traces');
+            assert.strictEqual(requireDefined(index2, 'Expected rebuilt index').entries.length, COUNT_TWO);
+        });
+        it('should return null for non-existent file', async () => {
+            const result = await getOrBuildIndex('/non/existent/file.jsonl', 'traces');
+            assert.strictEqual(result, null);
+        });
+    });
+    describe('concurrent operations', () => {
+        it('should handle concurrent index builds safely', async () => {
+            const filePath = path.join(tempDir, 'concurrent-traces.jsonl');
+            const mockSpans = [
+                { traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] },
+                { traceId: 'trace2', spanId: 'span2', name: 'op2', startTime: [EPOCH_SEC_PLUS_ONE, NANO_ZERO] },
+                { traceId: 'trace3', spanId: 'span3', name: 'op3', startTime: [EPOCH_SEC_PLUS_TWO, NANO_ZERO] },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            // Trigger multiple index builds simultaneously
+            const results = await Promise.all([
+                buildAndWriteIndex(filePath, 'traces'),
+                buildAndWriteIndex(filePath, 'traces'),
+                buildAndWriteIndex(filePath, 'traces'),
+            ]);
+            // All should succeed with same entry count
+            results.forEach(result => {
+                assert.ok(result !== null);
+                assert.strictEqual(result.entries.length, COUNT_THREE);
+                assert.strictEqual(result.version, 1);
+            });
+            // Index file should exist and be valid
+            const indexPath = getIndexPath(filePath);
+            assert.ok(fs.existsSync(indexPath));
+            const finalIndex = readIndex(indexPath);
+            assert.ok(finalIndex !== null);
+            assert.strictEqual(finalIndex.entries.length, COUNT_THREE);
+        });
+        it('should handle concurrent getOrBuildIndex calls', async () => {
+            const filePath = path.join(tempDir, 'concurrent-get.jsonl');
+            const mockSpans = [
+                { traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] },
+                { traceId: 'trace2', spanId: 'span2', name: 'op2', startTime: [EPOCH_SEC_PLUS_ONE, NANO_ZERO] },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            // Multiple concurrent calls should all succeed
+            const results = await Promise.all([
+                getOrBuildIndex(filePath, 'traces'),
+                getOrBuildIndex(filePath, 'traces'),
+                getOrBuildIndex(filePath, 'traces'),
+                getOrBuildIndex(filePath, 'traces'),
+                getOrBuildIndex(filePath, 'traces'),
+            ]);
+            // All should return valid indexes
+            results.forEach(result => {
+                assert.ok(result !== null);
+                assert.strictEqual(result.entries.length, COUNT_TWO);
+            });
+        });
+        it('should handle concurrent queries during index rebuild', async () => {
+            const filePath = path.join(tempDir, 'concurrent-query.jsonl');
+            const mockSpans = [
+                { traceId: 'target-trace', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] },
+                { traceId: 'other-trace', spanId: 'span2', name: 'op2', startTime: [EPOCH_SEC_PLUS_ONE, NANO_ZERO] },
+                { traceId: 'target-trace', spanId: 'span3', name: 'op3', startTime: [EPOCH_SEC_PLUS_TWO, NANO_ZERO] },
+            ];
+            await writeJsonlFileAsync(filePath, mockSpans);
+            // Build initial index
+            const initialIndex = await buildAndWriteIndex(filePath, 'traces');
+            assert.ok(initialIndex !== null);
+            // Run queries and rebuilds concurrently
+            const queryResults = await Promise.all([
+                Promise.resolve(queryIndex(initialIndex, { traceId: 'target-trace' })),
+                buildAndWriteIndex(filePath, 'traces'),
+                Promise.resolve(queryIndex(initialIndex, { traceId: 'target-trace' })),
+                buildAndWriteIndex(filePath, 'traces'),
+            ]);
+            // Query results should be consistent
+            const queries = [queryResults[0], queryResults[2]];
+            queries.forEach(result => {
+                assert.ok(result !== null);
+                assert.deepStrictEqual(result, [1, COUNT_THREE]);
+            });
+        });
+        it('should handle concurrent reads of same JSONL lines', async () => {
+            const filePath = path.join(tempDir, 'concurrent-read.jsonl');
+            const mockSpans = Array.from({ length: 100 }, (_, i) => ({
+                traceId: `trace-${i}`,
+                spanId: `span-${i}`,
+                name: `op-${i}`,
+                startTime: [EPOCH_SEC + i, NANO_ZERO],
+            }));
+            await writeJsonlFileAsync(filePath, mockSpans);
+            // Request same lines from multiple concurrent calls
+            const linesToRead = [
+                COUNT_TEN,
+                COUNT_TWENTY_FIVE,
+                COUNT_FIFTY,
+                INDEX_LINE_NUMBER_SEVENTY_FIVE,
+                COUNT_NINETY,
+            ];
+            const results = await Promise.all([
+                readLinesByNumber(filePath, linesToRead),
+                readLinesByNumber(filePath, linesToRead),
+                readLinesByNumber(filePath, linesToRead),
+            ]);
+            // All results should be identical
+            results.forEach(result => {
+                assert.strictEqual(result.length, COUNT_FIVE);
+                assert.strictEqual(result[0].traceId, 'trace-9'); // line 10 = index 9
+                assert.strictEqual(result[4].traceId, 'trace-89'); // line 90 = index 89
+            });
+            // Results should match each other
+            assert.deepStrictEqual(results[0], results[1]);
+            assert.deepStrictEqual(results[1], results[2]);
+        });
+        it('should handle concurrent index builds for different telemetry types', async () => {
+            const tracesPath = path.join(tempDir, 'traces.jsonl');
+            const logsPath = path.join(tempDir, 'logs.jsonl');
+            const metricsPath = path.join(tempDir, 'metrics.jsonl');
+            await writeJsonlFileAsync(tracesPath, [
+                { traceId: 'trace1', spanId: 'span1', name: 'op1', startTime: [EPOCH_SEC, NANO_ZERO] },
+            ]);
+            await writeJsonlFileAsync(logsPath, [
+                { timestamp: '2024-01-15T10:00:00Z', severityText: 'INFO', body: 'test' },
+            ]);
+            await writeJsonlFileAsync(metricsPath, [
+                { timestamp: '2024-01-15T10:00:00Z', name: 'test.metric', value: 42 },
+            ]);
+            // Build indexes for different types concurrently
+            const results = await Promise.all([
+                buildAndWriteIndex(tracesPath, 'traces'),
+                buildAndWriteIndex(logsPath, 'logs'),
+                buildAndWriteIndex(metricsPath, 'metrics'),
+            ]);
+            // All should succeed with correct entries
+            const tracesIndex = requireDefined(results[0], 'Expected traces index');
+            const logsIndex = requireDefined(results[1], 'Expected logs index');
+            const metricsIndex = requireDefined(results[2], 'Expected metrics index');
+            assert.strictEqual(tracesIndex.entries.length, 1);
+            assert.strictEqual(requireDefined(tracesIndex.entries[0], 'Expected trace entry').traceId, 'trace1');
+            assert.strictEqual(logsIndex.entries.length, 1);
+            assert.strictEqual(requireDefined(logsIndex.entries[0], 'Expected log entry').severity, 'INFO');
+            assert.strictEqual(metricsIndex.entries.length, 1);
+            assert.strictEqual(requireDefined(metricsIndex.entries[0], 'Expected metric entry').metricName, 'test.metric');
+        });
+    });
+});
+//# sourceMappingURL=indexer.test.js.map