@nomos-arc/arc 0.1.0

package/src/search/__tests__/query-engine.test.ts

@@ -0,0 +1,334 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { QueryEngine } from '../query-engine.js';
+import { NomosError } from '../../core/errors.js';
+import type { Logger } from 'winston';
+import type { IndexMetadata, NomosConfig, SearchResult } from '../../types/index.js';
+
+// ─── Mocks ────────────────────────────────────────────────────────────────────
+
+// Hoist mock references so vi.mock factories can close over them
+const {
+  mockEmbedderEmbedOne,
+  mockVectorStoreInit,
+  mockVectorStoreQuery,
+  mockGraphEnricherEnrich,
+} = vi.hoisted(() => ({
+  mockEmbedderEmbedOne: vi.fn(),
+  mockVectorStoreInit: vi.fn(),
+  mockVectorStoreQuery: vi.fn(),
+  mockGraphEnricherEnrich: vi.fn(),
+}));
+
+vi.mock('../embedder.js', () => {
+  const EmbedderMock = Object.assign(
+    vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+      this['embedOne'] = mockEmbedderEmbedOne;
+    }),
+    {
+      create: vi.fn().mockImplementation(async () => ({
+        embedOne: mockEmbedderEmbedOne,
+      })),
+    },
+  );
+  return { Embedder: EmbedderMock };
+});
+
+vi.mock('../vector-store.js', () => ({
+  VectorStore: vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+    this['init'] = mockVectorStoreInit;
+    this['query'] = mockVectorStoreQuery;
+  }),
+}));
+
+vi.mock('../graph-enricher.js', () => ({
+  GraphEnricher: vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+    this['enrich'] = mockGraphEnricherEnrich;
+  }),
+}));
+
+vi.mock('node:fs/promises', () => ({
+  default: { readFile: vi.fn() },
+}));
+
+import fs from 'node:fs/promises';
+const mockReadFile = vi.mocked(fs.readFile);
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+function makeConfig(overrides: Partial<NomosConfig['search']> = {}): NomosConfig {
+  return {
+    execution: {
+      default_mode: 'supervised',
+      shadow_branch_prefix: 'nomos/',
+      worktree_base: '.nomos/worktrees',
+      supervised_heartbeat_timeout_ms: 30_000,
+    },
+    binaries: {
+      planner: { cmd: 'claude', args: [], pty: true, total_timeout_ms: 60000, heartbeat_timeout_ms: 15000, max_output_bytes: 1048576, usage_pattern: null },
+      reviewer: { cmd: 'openai', args: [], pty: false, total_timeout_ms: 60000, heartbeat_timeout_ms: 15000, max_output_bytes: 1048576, usage_pattern: null },
+    },
+    convergence: { score_threshold: 8, max_iterations: 3 },
+    budget: { max_tokens_per_task: 100000, warn_at_percent: 80, cost_per_1k_tokens: {} },
+    security: { sanitize_patterns: [], entropy_threshold: 4.5, sanitize_on: [], safe_commands: [], redaction_label: '[REDACTED]' },
+    git: { auto_commit: false, include_logs: false, commit_prefix: 'nomos:', sign_commits: false },
+    review: { max_context_files: 5 },
+    graph: {
+      exclude_patterns: [],
+      ai_enrichment: false,
+      ai_model: 'claude-3-5-sonnet',
+      ai_concurrency: 2,
+      ai_requests_per_minute: 20,
+      max_file_chars: 10000,
+      core_modules_count: 10,
+      output_dir: '.nomos/graph',
+    },
+    logging: { level: 'info', retain_days: 7 },
+    search: {
+      embedding_model: 'gemini-embedding-001',
+      embedding_dimensions: 768,
+      vector_store_path: '.nomos/vectors',
+      default_top_k: 10,
+      default_threshold: 0.7,
+      batch_size: 50,
+      embedding_requests_per_minute: 60,
+      request_timeout_ms: 30_000,
+      ...overrides,
+    },
+    auth: {
+      credentials_path: '~/.nomos/credentials.json',
+      redirect_port: 3000,
+    },
+  };
+}
+
+function makeIndexMeta(overrides: Partial<IndexMetadata> = {}): IndexMetadata {
+  return {
+    status: 'complete',
+    last_full_index: '2026-04-01T00:00:00.000Z',
+    last_incremental_index: null,
+    total_files_indexed: 10,
+    total_symbols_indexed: 50,
+    total_chunks: 60,
+    embedding_model: 'gemini-embedding-001',
+    vector_dimensions: 768,
+    failed_files: [],
+    files: {},
+    ...overrides,
+  };
+}
+
+function makeSearchResult(overrides: Partial<SearchResult> = {}): SearchResult {
+  return {
+    id: 'src/foo.ts',
+    type: 'file',
+    file_path: 'src/foo.ts',
+    symbol_name: null,
+    symbol_type: null,
+    line_start: null,
+    line_end: null,
+    purpose: 'A module',
+    similarity_score: 0.9,
+    graph_depth: 2,
+    dependents_count: 3,
+    is_core_module: false,
+    is_stale: false,
+    ...overrides,
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('QueryEngine', () => {
+  let logger: Logger;
+  let engine: QueryEngine;
+  const QUERY_VECTOR = new Float32Array(768).fill(0.1);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    logger = makeLogger();
+    engine = new QueryEngine('/project', makeConfig(), logger);
+
+    // Default happy-path stubs
+    mockReadFile.mockResolvedValue(JSON.stringify(makeIndexMeta()) );
+    mockVectorStoreInit.mockResolvedValue(undefined);
+    mockEmbedderEmbedOne.mockResolvedValue(QUERY_VECTOR);
+    mockVectorStoreQuery.mockResolvedValue([]);
+    mockGraphEnricherEnrich.mockResolvedValue([]);
+  });
+
+  // ── Test 1: Happy path ─────────────────────────────────────────────────────
+
+  it('embeds query, queries store, enriches, and returns ranked results', async () => {
+    const result1 = makeSearchResult({ id: 'src/a.ts', file_path: 'src/a.ts', similarity_score: 0.85 });
+    const result2 = makeSearchResult({ id: 'src/b.ts', file_path: 'src/b.ts', similarity_score: 0.95 });
+    mockGraphEnricherEnrich.mockResolvedValueOnce([result1, result2]);
+
+    const results = await engine.search('find the auth module');
+
+    expect(mockEmbedderEmbedOne).toHaveBeenCalledWith('find the auth module');
+    expect(mockVectorStoreInit).toHaveBeenCalledOnce();
+    expect(mockVectorStoreQuery).toHaveBeenCalledWith(QUERY_VECTOR, 10, 0.7);
+    expect(mockGraphEnricherEnrich).toHaveBeenCalledOnce();
+
+    // Results must be sorted descending by similarity_score
+    expect(results[0]!.similarity_score).toBeGreaterThanOrEqual(results[1]!.similarity_score);
+  });
+
+  // ── Test 2: No index AND no project map ─────────────────────────────────
+
+  it('throws NomosError(search_index_not_found) when neither index nor project map exists', async () => {
+    // Both readFile calls fail: index-meta.json then project_map.json
+    mockReadFile
+      .mockRejectedValueOnce(new Error('ENOENT'))  // index-meta.json
+      .mockRejectedValueOnce(new Error('ENOENT')); // project_map.json
+
+    await expect(engine.search('something')).rejects.toMatchObject({
+      code: 'search_index_not_found',
+    });
+  });
+
+  it('returns lexical results when no vector index exists but project map is available', async () => {
+    const projectMap = {
+      schema_version: 1, generated_at: '2026-04-01T00:00:00.000Z', root: '/project',
+      files: {
+        'src/auth.ts': {
+          file: 'src/auth.ts', hash: 'h1', language: 'typescript',
+          symbols: [{ name: 'login', kind: 'function', line: 1, end_line: 10, signature: 'login()', exported: true }],
+          imports: [], dependents: [], dependencies: [], depth: 0,
+          last_parsed_at: null, semantic: null, enrichment_status: 'structural',
+        },
+      },
+      stats: { total_files: 1, total_symbols: 1, total_edges: 0, core_modules: [], structural_only: 1, semantically_enriched: 0, indexed: 0 },
+    };
+    mockReadFile
+      .mockRejectedValueOnce(new Error('ENOENT'))          // index-meta.json — not found
+      .mockResolvedValueOnce(JSON.stringify(projectMap));   // project_map.json
+
+    const results = await engine.search('login');
+    // Should get lexical results without error
+    expect(results.length).toBeGreaterThanOrEqual(0);
+  });
+
+  // ── Test 3: Empty query ────────────────────────────────────────────────────
+
+  it('throws NomosError(search_query_failed) on empty query string', async () => {
+    await expect(engine.search('')).rejects.toMatchObject({
+      code: 'search_query_failed',
+    });
+    await expect(engine.search('   ')).rejects.toMatchObject({
+      code: 'search_query_failed',
+    });
+  });
+
+  // ── Test 4: topK and threshold overrides ──────────────────────────────────
+
+  it('respects topK and threshold overrides', async () => {
+    await engine.search('test query', { topK: 5, threshold: 0.85 });
+    expect(mockVectorStoreQuery).toHaveBeenCalledWith(QUERY_VECTOR, 5, 0.85);
+  });
+
+  // ── Test 5: Stale index warning ───────────────────────────────────────────
+
+  it('logs stale index warning when index is older than project map', async () => {
+    const meta = makeIndexMeta({ last_full_index: '2026-01-01T00:00:00.000Z' });
+    const projectMap = {
+      schema_version: 1, generated_at: '2026-04-01T00:00:00.000Z', root: '/project',
+      files: {}, stats: { total_files: 0, total_symbols: 0, total_edges: 0, core_modules: [], structural_only: 0, semantically_enriched: 0, indexed: 0 },
+    };
+
+    // Call order: index-meta.json → project_map.json → project_map.json (stale check)
+    mockReadFile
+      .mockResolvedValueOnce(JSON.stringify(meta))
+      .mockResolvedValueOnce(JSON.stringify(projectMap))
+      .mockResolvedValueOnce(JSON.stringify(projectMap));
+
+    await engine.search('find module');
+
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Index is older than project map'),
+    );
+  });
+
+  // ── Test 6: De-duplication — symbol within 0.05, file removed [TRAP-3] ───
+
+  it('removes file-level result when symbol result is within 0.05 [TRAP-3]', async () => {
+    const fileResult = makeSearchResult({
+      id: 'src/auth.ts',
+      type: 'file',
+      file_path: 'src/auth.ts',
+      similarity_score: 0.90,
+    });
+    const symbolResult = makeSearchResult({
+      id: 'src/auth.ts::login',
+      type: 'symbol',
+      file_path: 'src/auth.ts',
+      symbol_name: 'login',
+      similarity_score: 0.88, // gap = 0.02 ≤ 0.05 → file result must be removed
+    });
+
+    mockGraphEnricherEnrich.mockResolvedValueOnce([fileResult, symbolResult]);
+
+    const results = await engine.search('login function');
+
+    const resultIds = results.map((r) => r.id);
+    expect(resultIds).not.toContain('src/auth.ts');      // file-level removed
+    expect(resultIds).toContain('src/auth.ts::login');   // symbol kept
+  });
+
+  // ── Test 7: De-duplication — gap > 0.05, both kept [TRAP-3] ─────────────
+
+  it('keeps both file and symbol results when gap > 0.05 [TRAP-3]', async () => {
+    const fileResult = makeSearchResult({
+      id: 'src/auth.ts',
+      type: 'file',
+      file_path: 'src/auth.ts',
+      similarity_score: 0.95,
+    });
+    const symbolResult = makeSearchResult({
+      id: 'src/auth.ts::logout',
+      type: 'symbol',
+      file_path: 'src/auth.ts',
+      symbol_name: 'logout',
+      similarity_score: 0.80, // gap = 0.15 > 0.05 → both kept
+    });
+
+    mockGraphEnricherEnrich.mockResolvedValueOnce([fileResult, symbolResult]);
+
+    const results = await engine.search('auth module');
+
+    const resultIds = results.map((r) => r.id);
+    expect(resultIds).toContain('src/auth.ts');
+    expect(resultIds).toContain('src/auth.ts::logout');
+  });
+
+  // ── Test 8: VectorStore.init() failure → falls back to lexical [GAP-2] ───
+
+  it('falls back to lexical search when VectorStore.init() fails [GAP-2]', async () => {
+    const projectMap = {
+      schema_version: 1, generated_at: '2026-04-01T00:00:00.000Z', root: '/project',
+      files: {}, stats: { total_files: 0, total_symbols: 0, total_edges: 0, core_modules: [], structural_only: 0, semantically_enriched: 0, indexed: 0 },
+    };
+    mockReadFile
+      .mockResolvedValueOnce(JSON.stringify(makeIndexMeta()))   // index-meta.json
+      .mockResolvedValueOnce(JSON.stringify(projectMap));        // project_map.json
+
+    mockVectorStoreInit.mockRejectedValueOnce(new Error('LanceDB corrupted'));
+
+    const results = await engine.search('anything');
+
+    // Should not throw — falls back to lexical
+    expect(results).toEqual([]);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('Vector search failed, falling back to lexical search'),
+    );
+  });
+});

package/src/search/__tests__/similarity.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Task 7.7.3 — Verify cosine similarity correctness.
+ *
+ * Guards: all tests require GEMINI_API_KEY. Skipped in CI without key.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { Logger } from 'winston';
+import { vi } from 'vitest';
+import { Embedder } from '../embedder.js';
+import type { NomosConfig } from '../../types/index.js';
+
+function makeLogger(): Logger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logger;
+}
+
+/** Pure cosine similarity between two Float32Arrays. */
+function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+const EMBEDDING_DIMS = 768;
+
+function makeSearchConfig(): NomosConfig['search'] {
+  return {
+    embedding_model: 'gemini-embedding-001',
+    embedding_dimensions: EMBEDDING_DIMS,
+    vector_store_path: '/tmp/nomos-similarity-test',
+    default_top_k: 10,
+    default_threshold: 0.7,
+    batch_size: 5,
+    embedding_requests_per_minute: 60,
+    request_timeout_ms: 30_000,
+  };
+}
+
+describe.skipIf(!process.env['GEMINI_API_KEY'])(
+  'cosine similarity correctness (requires GEMINI_API_KEY)',
+  () => {
+    it('similar texts produce similarity > 0.8', async () => {
+      const embedder = new Embedder(makeSearchConfig(), makeLogger());
+      const v1 = await embedder.embedOne('process payment refund');
+      const v2 = await embedder.embedOne('handle refund for customer payment');
+      const similarity = cosineSimilarity(v1, v2);
+      expect(similarity).toBeGreaterThan(0.8);
+    }, 30_000);
+
+    it('unrelated texts produce similarity < 0.5', async () => {
+      const embedder = new Embedder(makeSearchConfig(), makeLogger());
+      const v1 = await embedder.embedOne('process payment refund');
+      const v2 = await embedder.embedOne('configure webpack build optimization');
+      const similarity = cosineSimilarity(v1, v2);
+      expect(similarity).toBeLessThan(0.5);
+    }, 30_000);
+
+    it('similarity is always in [0, 1]', async () => {
+      const embedder = new Embedder(makeSearchConfig(), makeLogger());
+      const v1 = await embedder.embedOne('any arbitrary text');
+      const v2 = await embedder.embedOne('completely different content');
+      const similarity = cosineSimilarity(v1, v2);
+      expect(similarity).toBeGreaterThanOrEqual(0);
+      expect(similarity).toBeLessThanOrEqual(1);
+    }, 30_000);
+  },
+);

package/src/search/__tests__/vector-store.test.ts

@@ -0,0 +1,281 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as os from 'node:os';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { VectorStore } from '../vector-store.js';
+import { NomosError } from '../../core/errors.js';
+import type { VectorRecord } from '../../types/index.js';
+import type { Logger } from 'winston';
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+const VECTOR_DIMS = 3;
+
+function makeLogger(): Logger {
+  return {
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+    debug: () => undefined,
+  } as unknown as Logger;
+}
+
+let recordCounter = 0;
+
+function makeRecord(overrides: Partial<VectorRecord> = {}): VectorRecord {
+  recordCounter++;
+  const base = new Float32Array(VECTOR_DIMS);
+  for (let i = 0; i < VECTOR_DIMS; i++) {
+    base[i] = (0.1 * recordCounter * (i + 1)) % 1.0;
+  }
+  return {
+    id: `rec-${recordCounter}`,
+    type: 'file',
+    vector: base,
+    file_path: `src/foo${recordCounter}.ts`,
+    module: 'src',
+    purpose: `Purpose ${recordCounter}`,
+    symbol_name: null,
+    symbol_type: null,
+    line_start: null,
+    line_end: null,
+    parent_file_id: null,
+    graph_depth: 1,
+    dependents_count: 0,
+    last_indexed: new Date().toISOString(),
+    content_hash: `hash${recordCounter}`,
+    ...overrides,
+  };
+}
+
+/** Return an L2-normalized unit vector of given values. */
+function unitVec(values: number[]): Float32Array {
+  const len = Math.sqrt(values.reduce((s, v) => s + v * v, 0));
+  return new Float32Array(values.map((v) => v / len));
+}
+
+// ── Test setup ────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let store: VectorStore;
+
+beforeEach(async () => {
+  recordCounter = 0;
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nomos-vs-test-'));
+  store = new VectorStore(tmpDir, makeLogger(), VECTOR_DIMS);
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('VectorStore', () => {
+  // Test 1: init() creates the DB directory if it does not exist
+  it('init() creates the DB directory if it does not exist', async () => {
+    const nonExistentDir = path.join(tmpDir, 'new-subdir', 'vector_index');
+    const freshStore = new VectorStore(nonExistentDir, makeLogger(), VECTOR_DIMS);
+    await expect(freshStore.init()).resolves.toBeUndefined();
+    const stat = await fs.stat(nonExistentDir).catch(() => null);
+    expect(stat).not.toBeNull();
+  });
+
+  // Test 2: init() wraps connection failure in NomosError('search_index_corrupted')
+  // Trigger: create a read-only parent so LanceDB cannot create the database directory.
+  it('init() wraps connection failure in NomosError(search_index_corrupted)', async () => {
+    const roParent = path.join(tmpDir, 'readonly-parent');
+    await fs.mkdir(roParent, { mode: 0o555 }); // read + execute, no write
+    const blockedPath = path.join(roParent, 'vector_index');
+    const brokenStore = new VectorStore(blockedPath, makeLogger(), VECTOR_DIMS);
+
+    await expect(brokenStore.init()).rejects.toSatisfy(
+      (e: unknown) =>
+        e instanceof NomosError && (e as NomosError).code === 'search_index_corrupted',
+    );
+  });
+
+  // Test 3: upsert() inserts records; count() returns correct total
+  it('upsert() inserts records and count() returns the correct total', async () => {
+    await store.init();
+    const records = [makeRecord(), makeRecord(), makeRecord()];
+    await store.upsert(records);
+    expect(await store.count()).toBe(3);
+  });
+
+  // Test 4: upsert() with duplicate id overwrites the existing record
+  it('upsert() with duplicate id overwrites the existing record', async () => {
+    await store.init();
+    const original = makeRecord({ id: 'dup-id', purpose: 'original' });
+    await store.upsert([original]);
+    expect(await store.count()).toBe(1);
+
+    const updated = makeRecord({ id: 'dup-id', purpose: 'updated' });
+    await store.upsert([updated]);
+    expect(await store.count()).toBe(1); // still 1, not 2
+  });
+
+  // Test 5: query() returns results ranked by similarity (closest first)
+  // Uses unit vectors so dot distance ≡ cosine distance.
+  it('query() returns results ranked by similarity, closest first', async () => {
+    await store.init();
+    const recA = makeRecord({ id: 'a', vector: unitVec([1, 0, 0]), file_path: 'src/a.ts' });
+    const recB = makeRecord({ id: 'b', vector: unitVec([0, 1, 0]), file_path: 'src/b.ts' });
+    const recC = makeRecord({ id: 'c', vector: unitVec([0.9, 0.1, 0]), file_path: 'src/c.ts' });
+    await store.upsert([recA, recB, recC]);
+
+    const queryVec = unitVec([1, 0, 0]); // identical to recA
+    const results = await store.query(queryVec, 3, 0);
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].id).toBe('a'); // closest match first
+    // Scores must be non-increasing
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i - 1].similarity_score).toBeGreaterThanOrEqual(results[i].similarity_score);
+    }
+  });
+
+  // Test 6: query() with threshold filters out low-similarity results
+  it('query() with threshold filters out low-similarity results', async () => {
+    await store.init();
+    const recA = makeRecord({ id: 'a', vector: unitVec([1, 0, 0]), file_path: 'src/a.ts' });
+    const recB = makeRecord({ id: 'b', vector: unitVec([0, 0, 1]), file_path: 'src/b.ts' }); // orthogonal
+    await store.upsert([recA, recB]);
+
+    const queryVec = unitVec([1, 0, 0]);
+    const results = await store.query(queryVec, 5, 0.9); // high threshold
+
+    expect(results.every((r) => r.similarity_score >= 0.9)).toBe(true);
+  });
+
+  // Test 7: query() returns similarity_score ∈ [0, 1] [S-3]
+  it('query() similarity_score is always in [0, 1]', async () => {
+    await store.init();
+    const records = Array.from({ length: 5 }, (_, i) =>
+      makeRecord({
+        id: `r${i}`,
+        vector: unitVec([i + 1, i, 0.5]),
+        file_path: `src/r${i}.ts`,
+      }),
+    );
+    await store.upsert(records);
+
+    const results = await store.query(unitVec([1, 1, 1]), 10, 0);
+    expect(results.length).toBeGreaterThan(0);
+    for (const r of results) {
+      expect(r.similarity_score).toBeGreaterThanOrEqual(0);
+      expect(r.similarity_score).toBeLessThanOrEqual(1);
+    }
+  });
+
+  // Test 8: query() results do NOT contain vector field [S-5]
+  it('query() results do not contain the vector field', async () => {
+    await store.init();
+    const rec = makeRecord({
+      id: 'v-check',
+      vector: unitVec([1, 2, 3]),
+      file_path: 'src/v.ts',
+    });
+    await store.upsert([rec]);
+
+    const results = await store.query(unitVec([1, 2, 3]), 5, 0);
+    expect(results.length).toBeGreaterThan(0);
+    for (const r of results) {
+      expect(Object.prototype.hasOwnProperty.call(r, 'vector')).toBe(false);
+      // Also verify JSON serialization does not leak vector data
+      const json = JSON.parse(JSON.stringify(r)) as Record<string, unknown>;
+      expect(json).not.toHaveProperty('vector');
+    }
+  });
+
+  // Test 9: deleteByFilePaths() removes only matching records
+  it('deleteByFilePaths() removes only records matching given file paths', async () => {
+    await store.init();
+    const recA = makeRecord({ id: 'da', file_path: 'src/delete-me.ts' });
+    const recB = makeRecord({ id: 'db', file_path: 'src/keep-me.ts' });
+    const recC = makeRecord({ id: 'dc', file_path: 'src/delete-me.ts' }); // same path
+    await store.upsert([recA, recB, recC]);
+    expect(await store.count()).toBe(3);
+
+    await store.deleteByFilePaths(['src/delete-me.ts']);
+    expect(await store.count()).toBe(1);
+  });
+
+  // Test 10: Table-swap full cycle [BLOCKER-1]
+  describe('table-swap full cycle (BLOCKER-1)', () => {
+    it('upsertToStaging does not affect live; promoteStagingToLive swaps', async () => {
+      await store.init();
+
+      // Seed live table with "old" data
+      const oldRec = makeRecord({ id: 'old', purpose: 'old data', file_path: 'src/old.ts' });
+      await store.upsert([oldRec]);
+      expect(await store.count()).toBe(1);
+
+      // Write new data to staging — does NOT touch live
+      const newRec = makeRecord({ id: 'new', purpose: 'new data', file_path: 'src/new.ts' });
+      await store.upsertToStaging([newRec]);
+
+      // Live still has old data
+      expect(await store.count()).toBe(1);
+
+      // Promote staging → live
+      await store.promoteStagingToLive();
+
+      // After promotion, live contains new data only
+      expect(await store.count()).toBe(1);
+    });
+
+    it('promoteStagingToLive() throws search_index_failed if no staging table', async () => {
+      await store.init();
+      await expect(store.promoteStagingToLive()).rejects.toSatisfy(
+        (e: unknown) =>
+          e instanceof NomosError && (e as NomosError).code === 'search_index_failed',
+      );
+    });
+  });
+
+  // Test 11: cleanupStaging() removes orphaned staging without affecting live [GAP-3]
+  it('cleanupStaging() removes orphaned staging table without affecting live', async () => {
+    await store.init();
+
+    // Seed live table
+    const liveRec = makeRecord({ file_path: 'src/live.ts' });
+    await store.upsert([liveRec]);
+
+    // Create orphaned staging table
+    const stagingRec = makeRecord({ file_path: 'src/staging.ts' });
+    await store.upsertToStaging([stagingRec]);
+
+    await store.cleanupStaging();
+    expect(await store.count()).toBe(1); // live untouched
+
+    // Idempotent: calling again with no staging table is a no-op
+    await expect(store.cleanupStaging()).resolves.toBeUndefined();
+  });
+
+  // Test 12: Concurrent upsert() calls do not corrupt the store
+  // Pre-seed the table so concurrent upserts all use the mergeInsert path (not the
+  // initial-creation path which serializes on overwrite mode by design).
+  it('concurrent upsert() calls do not corrupt the store', async () => {
+    await store.init();
+
+    // Seed the table first so the live table exists before concurrent ops begin
+    const seed = makeRecord({ id: 'seed', file_path: 'src/seed.ts' });
+    await store.upsert([seed]);
+
+    const batches = Array.from({ length: 4 }, (_, i) =>
+      [0, 1, 2].map((j) =>
+        makeRecord({
+          id: `concurrent-${i}-${j}`,
+          file_path: `src/concurrent-${i}-${j}.ts`,
+        }),
+      ),
+    );
+
+    await Promise.all(batches.map((batch) => store.upsert(batch)));
+
+    // All 12 new records + 1 seed = 13, but seed has a unique id so no conflict
+    // With mergeInsert: all upserts are independent non-overlapping ids → 13 total
+    expect(await store.count()).toBe(13);
+  });
+});