Skip to content

armgit / mem0

Public Imported from GitHub
0

The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.

177 KB
Raw Blame
/// <reference types="jest" />
/**
 * Backward-compatibility tests for ALL vector store implementations.
 *
 * Verifies that:
 *  1. Every store implements the full VectorStore interface
 *  2. initialize() is idempotent (safe to call multiple times)
 *  3. Constructor + explicit initialize() doesn't break (the double-call pattern)
 *  4. All CRUD methods work correctly after initialization
 *  5. getUserId / setUserId work correctly
 *  6. The Memory class works with each store via mocked factories
 */

import * as fs from "fs";
import * as path from "path";
import * as os from "os";

jest.setTimeout(15000);

// ───────────────────────────────────────────────────────────────────────────
// 1. MemoryVectorStore — full CRUD, no external dependencies
// ───────────────────────────────────────────────────────────────────────────
describe("MemoryVectorStore – full backward compat", () => {
  const { MemoryVectorStore } = require("../src/vector_stores/memory");
  let tmpDir: string;

  beforeEach(() => {
    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-vs-compat-"));
  });

  afterEach(() => {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  });

  it("implements full VectorStore interface", () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dbPath: path.join(tmpDir, "vs.db"),
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dbPath: path.join(tmpDir, "vs.db"),
    });
    await store.initialize();
    await store.initialize();
    await store.initialize();
    // Insert should still work after multiple initializations
    const vec = new Array(1536).fill(0.1);
    await store.insert([vec], ["id-1"], [{ data: "test" }]);
    const result = await store.get("id-1");
    expect(result).not.toBeNull();
  });

  it("full CRUD cycle with default dimension 1536", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dbPath: path.join(tmpDir, "vs.db"),
    });

    const vec1 = new Array(1536).fill(0);
    vec1[0] = 1.0;
    const vec2 = new Array(1536).fill(0);
    vec2[1] = 1.0;

    // Insert
    await store.insert(
      [vec1, vec2],
      ["id-1", "id-2"],
      [
        { data: "alpha", userId: "u1" },
        { data: "beta", userId: "u1" },
      ],
    );

    // Get
    const item = await store.get("id-1");
    expect(item).not.toBeNull();
    expect(item!.payload.data).toBe("alpha");

    // Search
    const results = await store.search(vec1, 2);
    expect(results.length).toBe(2);
    expect(results[0].id).toBe("id-1");

    // Search with filters (camelCase in payload is normalized to snake_case)
    const filtered = await store.search(vec1, 2, { user_id: "u1" });
    expect(filtered.length).toBe(2);

    // Update
    const vec3 = new Array(1536).fill(0);
    vec3[2] = 1.0;
    await store.update("id-1", vec3, { data: "updated", user_id: "u1" });
    const updated = await store.get("id-1");
    expect(updated!.payload.data).toBe("updated");

    // List
    const [listed, count] = await store.list({ user_id: "u1" });
    expect(count).toBe(2);

    // List with limit
    const [limitedList] = await store.list(undefined, 1);
    expect(limitedList.length).toBe(1);

    // Delete
    await store.delete("id-2");
    const deleted = await store.get("id-2");
    expect(deleted).toBeNull();

    // DeleteCol + re-init
    await store.deleteCol();
    const [afterDelete] = await store.list();
    expect(afterDelete.length).toBe(0);
  });

  it("full CRUD cycle with custom dimension 768", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dimension: 768,
      dbPath: path.join(tmpDir, "vs.db"),
    });

    const vec = new Array(768).fill(0.1);
    await store.insert([vec], ["id-1"], [{ data: "test" }]);
    const result = await store.get("id-1");
    expect(result!.payload.data).toBe("test");

    const searchResults = await store.search(vec, 1);
    expect(searchResults.length).toBe(1);
  });

  it("rejects dimension mismatch on insert", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dimension: 1536,
      dbPath: path.join(tmpDir, "vs.db"),
    });
    await expect(
      store.insert([new Array(768).fill(0)], ["id-1"], [{}]),
    ).rejects.toThrow("Vector dimension mismatch");
  });

  it("rejects dimension mismatch on search", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dimension: 1536,
      dbPath: path.join(tmpDir, "vs.db"),
    });
    await expect(store.search(new Array(768).fill(0), 1)).rejects.toThrow(
      "Query dimension mismatch",
    );
  });

  it("rejects dimension mismatch on update", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dimension: 1536,
      dbPath: path.join(tmpDir, "vs.db"),
    });
    await expect(
      store.update("id-1", new Array(768).fill(0), {}),
    ).rejects.toThrow("Vector dimension mismatch");
  });

  it("getUserId and setUserId roundtrip", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dbPath: path.join(tmpDir, "vs.db"),
    });

    const auto = await store.getUserId();
    expect(typeof auto).toBe("string");
    expect(auto.length).toBeGreaterThan(0);

    await store.setUserId("custom-user");
    expect(await store.getUserId()).toBe("custom-user");

    // Overwrite
    await store.setUserId("another-user");
    expect(await store.getUserId()).toBe("another-user");
  });

  it("get returns null for non-existent ID", async () => {
    const store = new MemoryVectorStore({
      collectionName: "test",
      dbPath: path.join(tmpDir, "vs.db"),
    });
    const result = await store.get("non-existent");
    expect(result).toBeNull();
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 2. Qdrant — mock QdrantClient, test interface + idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("Qdrant – backward compat with mocked client", () => {
  function createMockQdrantClient() {
    const collections = new Map<string, number>();
    const points = new Map<
      string,
      { id: string; vector: number[]; payload: any }
    >();

    return {
      _collections: collections,
      _points: points,
      createCollection: jest
        .fn()
        .mockImplementation(async (name: string, opts: any) => {
          if (collections.has(name)) {
            const err: any = new Error("Collection already exists");
            err.status = 409;
            throw err;
          }
          collections.set(name, opts.vectors.size);
        }),
      getCollection: jest.fn().mockImplementation(async (name: string) => {
        if (!collections.has(name)) {
          const err: any = new Error("Not found");
          err.status = 404;
          throw err;
        }
        return {
          config: { params: { vectors: { size: collections.get(name) } } },
        };
      }),
      getCollections: jest.fn().mockResolvedValue({
        collections: [],
      }),
      upsert: jest
        .fn()
        .mockImplementation(async (collName: string, opts: any) => {
          for (const pt of opts.points) {
            points.set(`${collName}:${pt.id}`, {
              id: pt.id,
              vector: pt.vector,
              payload: pt.payload,
            });
          }
        }),
      retrieve: jest
        .fn()
        .mockImplementation(async (collName: string, opts: any) => {
          const results = [];
          for (const id of opts.ids) {
            const pt = points.get(`${collName}:${id}`);
            if (pt) results.push({ id: pt.id, payload: pt.payload });
          }
          return results;
        }),
      search: jest
        .fn()
        .mockImplementation(async (collName: string, opts: any) => {
          const results: any[] = [];
          points.forEach((pt, key) => {
            if (key.startsWith(`${collName}:`)) {
              results.push({ id: pt.id, payload: pt.payload, score: 0.9 });
            }
          });
          return results.slice(0, opts.limit);
        }),
      scroll: jest
        .fn()
        .mockImplementation(async (collName: string, opts: any) => {
          const results: any[] = [];
          points.forEach((pt, key) => {
            if (key.startsWith(`${collName}:`)) {
              results.push({ id: pt.id, payload: pt.payload });
            }
          });
          return { points: results.slice(0, opts.limit) };
        }),
      delete: jest
        .fn()
        .mockImplementation(async (collName: string, opts: any) => {
          for (const id of opts.points) {
            points.delete(`${collName}:${id}`);
          }
        }),
      deleteCollection: jest.fn().mockImplementation(async (name: string) => {
        collections.delete(name);
      }),
    };
  }

  it("implements full VectorStore interface", () => {
    const { Qdrant } = require("../src/vector_stores/qdrant");
    const store = new Qdrant({
      client: createMockQdrantClient(),
      collectionName: "test",
      embeddingModelDims: 768,
      dimension: 768,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const { Qdrant } = require("../src/vector_stores/qdrant");
    const mockClient = createMockQdrantClient();
    const store = new Qdrant({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 768,
      dimension: 768,
    });

    // Constructor already fires initialize()
    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();

    await Promise.all([p1, p2, p3]);

    // createCollection called only once per collection despite multiple initialize() calls
    expect(mockClient.createCollection).toHaveBeenCalledTimes(2); // test + memory_migrations
  });

  it("full CRUD cycle", async () => {
    const { Qdrant } = require("../src/vector_stores/qdrant");
    const mockClient = createMockQdrantClient();
    const store = new Qdrant({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 768,
      dimension: 768,
    });
    await store.initialize();

    // Insert
    await store.insert(
      [
        [1, 2, 3],
        [4, 5, 6],
      ],
      ["id-1", "id-2"],
      [{ data: "alpha" }, { data: "beta" }],
    );
    expect(mockClient.upsert).toHaveBeenCalled();

    // Get
    const item = await store.get("id-1");
    expect(item).not.toBeNull();
    expect(item!.payload.data).toBe("alpha");

    // Search
    const results = await store.search([1, 2, 3], 2);
    expect(results.length).toBeGreaterThan(0);

    // Update
    await store.update("id-1", [7, 8, 9], { data: "updated" });

    // List
    const [listed, count] = await store.list();
    expect(listed.length).toBeGreaterThan(0);

    // Delete
    await store.delete("id-2");

    // DeleteCol
    await store.deleteCol();
    expect(mockClient.deleteCollection).toHaveBeenCalledWith("test");
  });

  it("getUserId and setUserId roundtrip", async () => {
    const { Qdrant } = require("../src/vector_stores/qdrant");
    const mockClient = createMockQdrantClient();
    const store = new Qdrant({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 768,
      dimension: 768,
    });
    await store.initialize();

    const userId = await store.getUserId();
    expect(typeof userId).toBe("string");
    expect(userId.length).toBeGreaterThan(0);

    await store.setUserId("custom-user");
    const updated = await store.getUserId();
    expect(updated).toBe("custom-user");
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 3. Redis — mock redis client, test interface + idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("Redis – backward compat with mocked client", () => {
  let RedisDB: any;

  beforeEach(() => {
    jest.resetModules();

    // Mock redis createClient
    jest.doMock("redis", () => {
      const store = new Map<string, any>();
      const mockClient = {
        connect: jest.fn().mockResolvedValue(undefined),
        on: jest.fn(),
        isOpen: false,
        moduleList: jest
          .fn()
          .mockResolvedValue([["name", "search", "ver", 20000]]),
        ft: {
          dropIndex: jest.fn().mockResolvedValue(undefined),
          create: jest.fn().mockResolvedValue(undefined),
          search: jest.fn().mockResolvedValue({ total: 0, documents: [] }),
        },
        hSet: jest.fn().mockImplementation(async (key: string, obj: any) => {
          store.set(key, obj);
        }),
        hGetAll: jest.fn().mockImplementation(async (key: string) => {
          return store.get(key) || {};
        }),
        del: jest.fn().mockImplementation(async (key: string) => {
          store.delete(key);
        }),
        keys: jest.fn().mockResolvedValue([]),
        quit: jest.fn().mockResolvedValue(undefined),
      };

      // Track connect calls for assertion
      mockClient.connect.mockImplementation(async () => {
        mockClient.isOpen = true;
      });

      return {
        createClient: jest.fn().mockReturnValue(mockClient),
        SchemaFieldTypes: {
          VECTOR: "VECTOR",
          TAG: "TAG",
          TEXT: "TEXT",
          NUMERIC: "NUMERIC",
        },
        VectorAlgorithms: {
          FLAT: "FLAT",
          HNSW: "HNSW",
        },
        __mockClient: mockClient,
      };
    });

    RedisDB = require("../src/vector_stores/redis").RedisDB;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new RedisDB({
      collectionName: "test",
      embeddingModelDims: 768,
      redisUrl: "redis://localhost:6379",
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const redis = require("redis");
    const mockClient = redis.__mockClient;

    const store = new RedisDB({
      collectionName: "test",
      embeddingModelDims: 768,
      redisUrl: "redis://localhost:6379",
    });

    // Constructor already fires initialize()
    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();

    await Promise.all([p1, p2, p3]);

    // connect() called only once despite multiple initialize() calls
    expect(mockClient.connect).toHaveBeenCalledTimes(1);
  });

  it("constructor + explicit initialize() doesn't double-connect", async () => {
    const redis = require("redis");
    const mockClient = redis.__mockClient;

    const store = new RedisDB({
      collectionName: "test",
      embeddingModelDims: 768,
      redisUrl: "redis://localhost:6379",
    });

    // Explicitly awaiting initialize (what Memory._autoInitialize does)
    await store.initialize();

    // Should only have connected once
    expect(mockClient.connect).toHaveBeenCalledTimes(1);
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 4. Supabase — mock Supabase client, test idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("Supabase – backward compat with mocked client", () => {
  let SupabaseDB: any;
  let mockClient: any;
  let mockTableApi: any;
  let mockSelectBuilder: any;

  beforeEach(() => {
    jest.resetModules();

    mockSelectBuilder = {
      limit: jest.fn().mockResolvedValue({ data: [{}], error: null }),
      range: jest.fn().mockResolvedValue({ data: [], error: null, count: 0 }),
      maybeSingle: jest.fn().mockResolvedValue({ data: null, error: null }),
    };
    mockSelectBuilder.eq = jest.fn().mockReturnValue(mockSelectBuilder);
    mockSelectBuilder.order = jest.fn().mockReturnValue(mockSelectBuilder);

    mockTableApi = {
      select: jest.fn().mockReturnValue(mockSelectBuilder),
      insert: jest.fn().mockReturnValue({ error: null }),
      delete: jest.fn().mockReturnValue({
        eq: jest.fn().mockReturnValue({ error: null }),
        neq: jest.fn().mockReturnValue({ error: null }),
      }),
      update: jest.fn().mockReturnValue({
        eq: jest.fn().mockReturnValue({ error: null }),
      }),
      upsert: jest.fn().mockReturnValue({ error: null }),
    };

    mockClient = {
      from: jest.fn().mockReturnValue(mockTableApi),
      rpc: jest.fn().mockResolvedValue({ data: [], error: null }),
    };

    jest.doMock("@supabase/supabase-js", () => ({
      createClient: jest.fn().mockReturnValue(mockClient),
      __mockClient: mockClient,
    }));

    SupabaseDB = require("../src/vector_stores/supabase").SupabaseDB;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new SupabaseDB({
      supabaseUrl: "https://example.supabase.co",
      supabaseKey: "fake-key",
      tableName: "memories",
      collectionName: "test",
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const store = new SupabaseDB({
      supabaseUrl: "https://example.supabase.co",
      supabaseKey: "fake-key",
      tableName: "memories",
      collectionName: "test",
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    await Promise.all([p1, p2]);
    // No crash = idempotent (Supabase init runs a read-only probe query only once)
  });

  it("_doInitialize probes with a non-destructive select, not an insert", async () => {
    const store = new SupabaseDB({
      supabaseUrl: "https://example.supabase.co",
      supabaseKey: "fake-key",
      tableName: "memories",
      collectionName: "test",
    });

    await store.initialize();

    expect(mockTableApi.insert).not.toHaveBeenCalled();
    expect(mockTableApi.select).toHaveBeenCalledWith("embedding");
    expect(mockSelectBuilder.limit).toHaveBeenCalledWith(1);
  });

  it("list() paginates via .range() across multiple pages when count exceeds page size", async () => {
    const totalRows = 1500;
    const rangeMock = jest
      .fn()
      .mockImplementation((from: number, to: number) => {
        const remaining = totalRows - from;
        const rowCount = Math.max(0, Math.min(to - from + 1, remaining));
        const data = Array.from({ length: rowCount }, (_, i) => ({
          id: `id-${from + i}`,
          metadata: { index: from + i },
        }));
        return Promise.resolve({ data, error: null, count: totalRows });
      });

    const listBuilder: any = {
      limit: jest.fn().mockResolvedValue({ data: [{}], error: null }),
      range: rangeMock,
    };
    listBuilder.eq = jest.fn().mockReturnValue(listBuilder);
    listBuilder.order = jest.fn().mockReturnValue(listBuilder);
    mockTableApi.select.mockReturnValue(listBuilder);

    const store = new SupabaseDB({
      supabaseUrl: "https://example.supabase.co",
      supabaseKey: "fake-key",
      tableName: "memories",
      collectionName: "test",
    });

    const [results, count] = await store.list(undefined, totalRows);

    expect(count).toBe(totalRows);
    expect(results).toHaveLength(totalRows);
    expect(rangeMock.mock.calls.length).toBeGreaterThan(1);
    expect(listBuilder.order).toHaveBeenCalledWith("id", { ascending: true });
    expect(new Set(results.map((r) => r.id)).size).toBe(totalRows);
  });

  it("search() warns when results are truncated at the PostgREST row cap", async () => {
    const cappedResults = Array.from({ length: 1000 }, (_, i) => ({
      id: `id-${i}`,
      similarity: 0.9,
      metadata: {},
    }));

    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});

    const store = new SupabaseDB({
      supabaseUrl: "https://example.supabase.co",
      supabaseKey: "fake-key",
      tableName: "memories",
      collectionName: "test",
    });
    mockClient.rpc.mockResolvedValue({ data: cappedResults, error: null });

    const results = await store.search([0.1, 0.2, 0.3], 5000);

    expect(results).toHaveLength(1000);
    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("5000"));
    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("1000"));

    warnSpy.mockRestore();
  });

  it("constructor does not emit an unhandled rejection when init fails", async () => {
    jest.resetModules();
    jest.doMock("@supabase/supabase-js", () => {
      const failing = {
        from: jest.fn().mockReturnValue({
          select: jest.fn().mockReturnValue({
            limit: jest.fn().mockResolvedValue({
              data: null,
              error: {
                code: "42501",
                message: "permission denied for table memories",
              },
            }),
          }),
        }),
      };
      return { createClient: jest.fn().mockReturnValue(failing) };
    });
    const FailingSupabaseDB =
      require("../src/vector_stores/supabase").SupabaseDB;

    const rejections: unknown[] = [];
    const onUnhandled = (reason: unknown) => rejections.push(reason);
    process.on("unhandledRejection", onUnhandled);
    try {
      const store = new FailingSupabaseDB({
        supabaseUrl: "https://example.supabase.co",
        supabaseKey: "fake-key",
        tableName: "memories",
        collectionName: "test",
      });
      expect(store).toBeDefined();
      await new Promise((resolve) => setTimeout(resolve, 25));
    } finally {
      process.removeListener("unhandledRejection", onUnhandled);
    }

    expect(rejections).toEqual([]);
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 5. AzureAISearch — mock Azure clients, test idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("AzureAISearch – backward compat with mocked client", () => {
  let AzureAISearch: any;

  beforeEach(() => {
    jest.resetModules();

    jest.doMock("@azure/search-documents", () => ({
      SearchClient: jest.fn().mockImplementation(() => ({
        search: jest.fn().mockReturnValue({
          [Symbol.asyncIterator]: () => ({ next: () => ({ done: true }) }),
        }),
        getDocument: jest.fn().mockResolvedValue(null),
        mergeOrUploadDocuments: jest.fn().mockResolvedValue({}),
        deleteDocuments: jest.fn().mockResolvedValue({}),
      })),
      SearchIndexClient: jest.fn().mockImplementation(() => ({
        listIndexes: jest.fn().mockReturnValue({
          [Symbol.asyncIterator]: () => ({ next: () => ({ done: true }) }),
        }),
        createOrUpdateIndex: jest.fn().mockResolvedValue({}),
        deleteIndex: jest.fn().mockResolvedValue({}),
      })),
      AzureKeyCredential: jest
        .fn()
        .mockImplementation((key: string) => ({ key })),
    }));

    jest.doMock("@azure/identity", () => ({
      DefaultAzureCredential: jest.fn(),
    }));

    AzureAISearch =
      require("../src/vector_stores/azure_ai_search").AzureAISearch;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new AzureAISearch({
      serviceName: "test-service",
      collectionName: "test-index",
      apiKey: "fake-key",
      embeddingModelDims: 768,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const store = new AzureAISearch({
      serviceName: "test-service",
      collectionName: "test-index",
      apiKey: "fake-key",
      embeddingModelDims: 768,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();
    await Promise.all([p1, p2, p3]);
    // No crash = idempotent
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 6. Databricks — mock SQL + REST clients, test interface + idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("Databricks – backward compat with mocked clients", () => {
  let DatabricksVectorStore: any;

  beforeEach(() => {
    jest.resetModules();

    jest.doMock("@databricks/sql", () => {
      let migrationUserId: string | undefined;

      const executeStatement = jest
        .fn()
        .mockImplementation(async (sql: string) => {
          const normalized = sql.replace(/\s+/g, " ").trim();

          if (
            normalized.startsWith("CREATE SCHEMA IF NOT EXISTS") ||
            normalized.startsWith("CREATE TABLE IF NOT EXISTS") ||
            normalized.startsWith("ALTER TABLE main.default.memories")
          ) {
            return {
              fetchAll: jest.fn().mockResolvedValue([]),
              close: jest.fn().mockResolvedValue(undefined),
            };
          }

          if (
            normalized.startsWith(
              "SELECT user_id FROM main.default.memory_migrations LIMIT 1",
            )
          ) {
            return {
              fetchAll: jest
                .fn()
                .mockResolvedValue(
                  migrationUserId ? [{ user_id: migrationUserId }] : [],
                ),
              close: jest.fn().mockResolvedValue(undefined),
            };
          }

          if (
            normalized.startsWith("DELETE FROM main.default.memory_migrations")
          ) {
            migrationUserId = undefined;
            return {
              fetchAll: jest.fn().mockResolvedValue([]),
              close: jest.fn().mockResolvedValue(undefined),
            };
          }

          if (
            normalized.startsWith(
              "INSERT INTO main.default.memory_migrations (user_id)",
            )
          ) {
            const match = normalized.match(/VALUES \('([^']*)'\)/);
            migrationUserId = match ? match[1] : undefined;
            return {
              fetchAll: jest.fn().mockResolvedValue([]),
              close: jest.fn().mockResolvedValue(undefined),
            };
          }

          return {
            fetchAll: jest.fn().mockResolvedValue([]),
            close: jest.fn().mockResolvedValue(undefined),
          };
        });

      const session = {
        executeStatement,
        close: jest.fn().mockResolvedValue(undefined),
      };
      const client = {
        connect: jest.fn().mockResolvedValue(undefined),
        openSession: jest.fn().mockResolvedValue(session),
        close: jest.fn().mockResolvedValue(undefined),
      };

      client.connect.mockResolvedValue(client);

      return {
        DBSQLClient: jest.fn().mockImplementation(() => client),
        __mockClient: client,
        __mockSession: session,
      };
    });

    jest.doMock("axios", () => {
      let endpointExists = false;
      let endpointPendingReadyResponses = 0;
      let indexExists = false;
      let indexPendingReadyResponses = 0;
      let syncPendingReadyResponses = 0;
      let indexNeverReady = false;
      let pagedQueryResponses: any[] = [];

      const defaultQueryResponse = {
        result: {
          manifest: {
            columns: [{ name: "memory_id" }, { name: "payload" }],
          },
          data_array: [
            ["id-1", JSON.stringify({ user_id: "u1", topic: "alpha" }), 0.98],
            ["id-2", JSON.stringify({ user_id: "u2", topic: "beta" }), 0.75],
          ],
        },
      };

      const httpClient = {
        get: jest.fn().mockImplementation(async (url: string) => {
          if (url === "/endpoints/mem0_vector_search") {
            if (!endpointExists) {
              const error: any = new Error("missing endpoint");
              error.response = { status: 404 };
              throw error;
            }
            if (endpointPendingReadyResponses > 0) {
              endpointPendingReadyResponses -= 1;
              return {
                data: {
                  name: "mem0_vector_search",
                  endpoint_status: { state: "PROVISIONING" },
                },
              };
            }
            return {
              data: {
                name: "mem0_vector_search",
                endpoint_status: { state: "ONLINE" },
              },
            };
          }

          if (url === "/indexes/main.default.memories") {
            if (!indexExists) {
              const error: any = new Error("missing index");
              error.response = { status: 404 };
              throw error;
            }
            if (indexNeverReady) {
              return {
                data: {
                  name: "main.default.memories",
                  status: { ready: false },
                },
              };
            }
            if (indexPendingReadyResponses > 0) {
              indexPendingReadyResponses -= 1;
              return {
                data: {
                  name: "main.default.memories",
                  status: { ready: false },
                },
              };
            }
            if (syncPendingReadyResponses > 0) {
              syncPendingReadyResponses -= 1;
              return {
                data: {
                  name: "main.default.memories",
                  status: { ready: false },
                },
              };
            }
            return {
              data: {
                name: "main.default.memories",
                status: { ready: true },
              },
            };
          }

          throw new Error(`Unexpected Databricks GET ${url}`);
        }),
        post: jest.fn().mockImplementation(async (url: string, body: any) => {
          if (url === "/endpoints") {
            endpointExists = true;
            endpointPendingReadyResponses = 1;
            return { data: { endpoint: body.name } };
          }

          if (url === "/indexes") {
            indexExists = true;
            indexPendingReadyResponses = 1;
            return { data: { index: body.name } };
          }

          if (url === "/indexes/main.default.memories/sync") {
            syncPendingReadyResponses = 1;
            return { data: { status: "queued" } };
          }

          if (url === "/indexes/main.default.memories/query") {
            return {
              data:
                pagedQueryResponses.shift() ??
                JSON.parse(JSON.stringify(defaultQueryResponse)),
            };
          }

          if (url === "/indexes/main.default.memories/query-next-page") {
            return {
              data:
                pagedQueryResponses.shift() ??
                JSON.parse(JSON.stringify(defaultQueryResponse)),
            };
          }

          throw new Error(`Unexpected Databricks POST ${url}`);
        }),
        delete: jest.fn().mockImplementation(async (url: string) => {
          if (url === "/indexes/main.default.memories") {
            indexExists = false;
            return { data: {} };
          }
          throw new Error(`Unexpected Databricks DELETE ${url}`);
        }),
      };

      const create = jest.fn().mockReturnValue(httpClient);
      const authPost = jest.fn().mockResolvedValue({
        data: { access_token: "oauth-token", expires_in: 3600 },
      });

      return {
        __esModule: true,
        default: { create, post: authPost },
        create,
        post: authPost,
        __mockHttpClient: httpClient,
        __setPagedQueryResponses: (responses: any[]) => {
          pagedQueryResponses = responses.map((response) =>
            JSON.parse(JSON.stringify(response)),
          );
        },
        __setIndexNeverReady: (value: boolean) => {
          indexNeverReady = value;
        },
        __mockAuthPost: authPost,
      };
    });

    DatabricksVectorStore =
      require("../src/vector_stores/databricks").DatabricksVectorStore;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const databricksSql = require("@databricks/sql");
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();
    await Promise.all([p1, p2, p3]);

    const clientInstance = databricksSql.DBSQLClient.mock.results[0].value;
    const session = databricksSql.__mockSession;
    const httpClient = axiosModule.__mockHttpClient;
    expect(clientInstance.connect).toHaveBeenCalledTimes(1);
    expect(clientInstance.openSession).toHaveBeenCalledTimes(1);
    expect(
      httpClient.get.mock.calls.filter(
        ([url]: [string]) => url === "/endpoints/mem0_vector_search",
      ).length,
    ).toBeGreaterThan(1);
    expect(
      httpClient.get.mock.calls.filter(
        ([url]: [string]) => url === "/indexes/main.default.memories",
      ).length,
    ).toBeGreaterThan(1);
    expect(httpClient.post).toHaveBeenCalledWith("/endpoints", {
      name: "mem0_vector_search",
      endpoint_type: "STANDARD",
    });
    expect(httpClient.post).toHaveBeenCalledWith("/indexes", {
      name: "main.default.memories",
      endpoint_name: "mem0_vector_search",
      primary_key: "memory_id",
      index_type: "DELTA_SYNC",
      delta_sync_index_spec: {
        source_table: "main.default.memories",
        pipeline_type: "TRIGGERED",
        columns_to_sync: [
          "memory_id",
          "payload",
          "text_lemmatized",
          "user_id",
          "agent_id",
          "run_id",
        ],
        embedding_vector_columns: [
          {
            name: "embedding",
            embedding_dimension: 3,
          },
        ],
      },
    });
    expect(
      session.executeStatement.mock.calls.some(
        ([sql]: [string]) =>
          sql.includes("ALTER TABLE main.default.memories") &&
          sql.includes("delta.enableChangeDataFeed"),
      ),
    ).toBe(true);
  });

  it("retries loading @databricks/sql after a failed dynamic import instead of caching the rejection", async () => {
    let shouldFail = true;
    jest.doMock("@databricks/sql", () => {
      if (shouldFail) {
        throw new Error("Cannot find module '@databricks/sql'");
      }
      const session = {
        executeStatement: jest.fn().mockResolvedValue({
          fetchAll: jest.fn().mockResolvedValue([]),
          close: jest.fn().mockResolvedValue(undefined),
        }),
        close: jest.fn().mockResolvedValue(undefined),
      };
      const client = {
        connect: jest.fn().mockResolvedValue(undefined),
        openSession: jest.fn().mockResolvedValue(session),
        close: jest.fn().mockResolvedValue(undefined),
      };
      client.connect.mockResolvedValue(client);
      return { DBSQLClient: jest.fn().mockImplementation(() => client) };
    });

    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await expect((store as any).getSqlModule()).rejects.toThrow(
      "The '@databricks/sql' package is required to use the Databricks vector store. " +
        "Install it with: npm install @databricks/sql (original error: Cannot find module '@databricks/sql')",
    );

    shouldFail = false;
    const sqlModule = await (store as any).getSqlModule();
    expect(typeof sqlModule.DBSQLClient).toBe("function");
  });

  it("executeSql(): reconnects on the next call after a session failure instead of reusing a dead session", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;
    const openSessionSpy = jest.spyOn(store as any, "openSession");

    session.executeStatement.mockRejectedValueOnce(
      new Error("session expired"),
    );
    await expect((store as any).executeSql("SELECT 1")).rejects.toThrow(
      "session expired",
    );
    expect(openSessionSpy).not.toHaveBeenCalled();

    await (store as any).executeSql("SELECT 1");
    expect(openSessionSpy).toHaveBeenCalledTimes(1);
  });

  it("getSession(): retries after a failed connection attempt instead of caching the rejection", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    // Simulate the warehouse dropping so the next getSession() must reconnect from scratch
    // (this clears both the cached session and any in-flight session promise).
    (store as any).resetSession();

    let attempts = 0;
    jest.spyOn(store as any, "openSession").mockImplementation(async () => {
      attempts++;
      if (attempts === 1) {
        throw new Error("warehouse cold start");
      }
      return databricksSql.__mockSession;
    });

    // First connection attempt fails (e.g. a cold/auto-suspended warehouse at startup)...
    await expect((store as any).getSession()).rejects.toThrow(
      "warehouse cold start",
    );

    // ...the next call must open a fresh session rather than replay the rejected promise.
    // Without getSession()'s catch-and-reset, openSession would never be called a second time.
    const session = await (store as any).getSession();
    expect(session).toBe(databricksSql.__mockSession);
    expect(attempts).toBe(2);
  });

  it("supports service-principal credentials for REST and SQL setup", async () => {
    const axiosModule = require("axios");
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      clientId: "client-id",
      clientSecret: "client-secret",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    await store.insert([[1, 0, 0]], ["id-1"], [{ user_id: "u1" }]);
    await store.search([1, 0, 0], 1);

    expect(axiosModule.__mockAuthPost).toHaveBeenCalledWith(
      "https://workspace.databricks.com/oidc/v1/token",
      expect.any(URLSearchParams),
      expect.objectContaining({
        auth: {
          username: "client-id",
          password: "client-secret",
        },
      }),
    );
    const authDetails = axiosModule.__mockAuthPost.mock.calls.map(
      ([, params]: [string, URLSearchParams]) =>
        params.get("authorization_details"),
    );
    const readDetails = JSON.stringify([
      {
        type: "unity_catalog_permission",
        securable_type: "table",
        securable_object_name: "main.default.memories",
        operation: "ReadVectorIndex",
      },
    ]);
    const writeDetails = JSON.stringify([
      {
        type: "unity_catalog_permission",
        securable_type: "table",
        securable_object_name: "main.default.memories",
        operation: "WriteVectorIndex",
      },
    ]);

    expect(authDetails).toContain(null);
    expect(authDetails).toContain(readDetails);
    expect(authDetails).toContain(writeDetails);
    expect(databricksSql.__mockClient.connect).toHaveBeenCalledWith(
      expect.objectContaining({
        authType: "databricks-oauth",
        oauthClientId: "client-id",
        oauthClientSecret: "client-secret",
      }),
    );
  });

  it("shapes Databricks SQL writes, syncs triggered indexes, and normalizes search results", async () => {
    const databricksSql = require("@databricks/sql");
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      // Non-zero: a 0ms poll skips the sleep entirely, so a sync would drain within the
      // microtask queue and never overlap the next write. 1ms models a real readiness wait.
      syncPollIntervalMs: 1,
    });

    await store.initialize();
    await store.insert(
      [[1, 0, 0]],
      ["id-1"],
      [{ user_id: "u1", topic: "alpha" }],
    );

    const session = databricksSql.__mockSession;
    expect(session.executeStatement).toHaveBeenCalledWith(
      expect.stringContaining("INSERT INTO main.default.memories"),
    );
    expect(session.executeStatement).toHaveBeenCalledWith(
      expect.stringContaining("'id-1'"),
    );
    expect(session.executeStatement).toHaveBeenCalledWith(
      expect.stringContaining("array(1, 0, 0)"),
    );
    await store.update("id-1", [0, 1, 0], { user_id: "u1", topic: "beta" });
    await store.delete("id-1");

    const results = await store.search([1, 0, 0], 5, {
      user_id: "u1",
      topic: "alpha",
    });
    const httpClient = axiosModule.__mockHttpClient;
    const syncPosts = httpClient.post.mock.calls.filter(
      ([url]: [string]) => url === "/indexes/main.default.memories/sync",
    );
    // insert/update/delete each request a sync, but writes that land while one is already
    // in flight coalesce into it -- so three writes never cost three pipeline runs.
    expect(syncPosts.length).toBeGreaterThanOrEqual(1);
    expect(syncPosts.length).toBeLessThan(3);
    expect(
      httpClient.get.mock.calls.filter(
        ([url]: [string]) => url === "/indexes/main.default.memories",
      ).length,
    ).toBeGreaterThan(4);
    expect(httpClient.post).toHaveBeenCalledWith(
      "/indexes/main.default.memories/query",
      expect.objectContaining({
        columns: ["memory_id", "payload"],
        filters_json: JSON.stringify({ user_id: "u1" }),
        query_type: "ANN",
        query_vector: [1, 0, 0],
      }),
    );
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.98,
      },
    ]);
  });

  it("keeps metadata-only filters local for standard endpoints", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const results = await store.search([1, 0, 0], 5, { topic: "alpha" });
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).toEqual(
      expect.objectContaining({
        columns: ["memory_id", "payload"],
        query_type: "ANN",
        query_vector: [1, 0, 0],
      }),
    );
    expect(queryCall?.[1]).not.toHaveProperty("filters_json");
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.98,
      },
    ]);
  });

  it("applies multiple local metadata operators on the same field", async () => {
    const axiosModule = require("axios");
    axiosModule.__setPagedQueryResponses([
      {
        result: {
          manifest: {
            columns: [{ name: "memory_id" }, { name: "payload" }],
          },
          data_array: [
            [
              "id-1",
              JSON.stringify({ user_id: "u1", importance: 1.0, topic: "high" }),
              0.99,
            ],
            [
              "id-2",
              JSON.stringify({
                user_id: "u1",
                importance: 0.75,
                topic: "within-range",
              }),
              0.98,
            ],
          ],
        },
      },
    ]);

    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const results = await store.search([1, 0, 0], 5, {
      importance: { gte: 0.5, lte: 0.9 },
    });
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).not.toHaveProperty("filters_json");
    expect(results).toEqual([
      {
        id: "id-2",
        payload: { user_id: "u1", importance: 0.75, topic: "within-range" },
        score: 0.98,
      },
    ]);
  });

  it("paginates when local-only filters need matches beyond the first page", async () => {
    const axiosModule = require("axios");
    axiosModule.__setPagedQueryResponses([
      {
        result: {
          manifest: {
            columns: [{ name: "memory_id" }, { name: "payload" }],
          },
          data_array: [
            ["id-2", JSON.stringify({ user_id: "u2", topic: "beta" }), 0.99],
          ],
          next_page_token: "page-2",
        },
      },
      {
        result: {
          manifest: {
            columns: [{ name: "memory_id" }, { name: "payload" }],
          },
          data_array: [
            ["id-1", JSON.stringify({ user_id: "u1", topic: "alpha" }), 0.98],
          ],
        },
      },
    ]);

    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const results = await store.search([1, 0, 0], 1, { topic: "alpha" });
    expect(
      axiosModule.__mockHttpClient.post.mock.calls.some(
        ([url]: [string]) =>
          url === "/indexes/main.default.memories/query-next-page",
      ),
    ).toBe(true);
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.98,
      },
    ]);
  });

  it("paginates across Databricks result pages when topK exceeds the first page", async () => {
    const axiosModule = require("axios");
    axiosModule.__setPagedQueryResponses([
      {
        result: {
          manifest: {
            columns: [{ name: "memory_id" }, { name: "payload" }],
          },
          data_array: [
            ["id-1", JSON.stringify({ user_id: "u1", topic: "alpha" }), 0.99],
          ],
          next_page_token: "page-2",
        },
      },
      {
        result: {
          manifest: {
            columns: [{ name: "memory_id" }, { name: "payload" }],
          },
          data_array: [
            ["id-2", JSON.stringify({ user_id: "u2", topic: "beta" }), 0.98],
          ],
        },
      },
    ]);

    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const results = await store.search([1, 0, 0], 1001);
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).toEqual(
      expect.objectContaining({
        num_results: 1001,
      }),
    );
    expect(
      axiosModule.__mockHttpClient.post.mock.calls.some(
        ([url]: [string]) =>
          url === "/indexes/main.default.memories/query-next-page",
      ),
    ).toBe(true);
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.99,
      },
      {
        id: "id-2",
        payload: { user_id: "u2", topic: "beta" },
        score: 0.98,
      },
    ]);
  });

  it("caps full-text local-fallback requests at Databricks' 200-result limit", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const results = await store.keywordSearch("alpha", 5, { topic: "alpha" });
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).toEqual(
      expect.objectContaining({
        num_results: 200,
        query_type: "FULL_TEXT",
        query_text: "alpha",
      }),
    );
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.98,
      },
    ]);
  });

  it("uses SQL-like filters for storage-optimized endpoints", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 16,
      endpointType: "STORAGE_OPTIMIZED",
    });
    const query = new Array(16).fill(0);
    query[0] = 1;

    const results = await store.search(query, 5, {
      user_id: "u1",
      topic: "alpha",
    });
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).toEqual(
      expect.objectContaining({
        columns: ["memory_id", "payload"],
        filters: "user_id = 'u1'",
        query_type: "ANN",
        query_vector: query,
      }),
    );
    expect(queryCall?.[1]).not.toHaveProperty("filters_json");
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.98,
      },
    ]);
  });

  it("translates storage-optimized array shorthand filters into IN clauses", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 16,
      endpointType: "STORAGE_OPTIMIZED",
    });
    const query = new Array(16).fill(0);
    query[0] = 1;

    await store.search(query, 5, {
      user_id: ["u1", "u2"],
    });
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).toEqual(
      expect.objectContaining({
        filters: "user_id IN ('u1', 'u2')",
      }),
    );
    expect(queryCall?.[1]).not.toHaveProperty("filters_json");
  });

  it("falls back to local filtering for logical operators", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const orResults = await store.search([1, 0, 0], 5, {
      $or: [{ user_id: "u1" }, { topic: "beta" }],
    });
    const notResults = await store.search([1, 0, 0], 5, {
      $not: [{ user_id: "u2" }],
    });
    const queryCalls = axiosModule.__mockHttpClient.post.mock.calls.filter(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCalls).toHaveLength(2);
    expect(queryCalls[0][1]).not.toHaveProperty("filters_json");
    expect(queryCalls[1][1]).not.toHaveProperty("filters_json");
    expect(orResults.map((result: any) => result.id)).toEqual(["id-1", "id-2"]);
    expect(notResults.map((result: any) => result.id)).toEqual(["id-1"]);
  });

  it("keeps memory_id filters aligned between Databricks and local fallback", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    const results = await store.search([1, 0, 0], 5, { memory_id: "id-1" });
    const queryCall = axiosModule.__mockHttpClient.post.mock.calls.find(
      ([url]: [string]) => url === "/indexes/main.default.memories/query",
    );

    expect(queryCall?.[1]).toEqual(
      expect.objectContaining({
        filters_json: JSON.stringify({ memory_id: "id-1" }),
      }),
    );
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.98,
      },
    ]);
  });

  it("omits columns_to_sync for storage-optimized endpoints", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 16,
      endpointType: "STORAGE_OPTIMIZED",
    });

    await store.initialize();

    expect(axiosModule.__mockHttpClient.post).toHaveBeenCalledWith("/indexes", {
      name: "main.default.memories",
      endpoint_name: "mem0_vector_search",
      primary_key: "memory_id",
      index_type: "DELTA_SYNC",
      delta_sync_index_spec: {
        source_table: "main.default.memories",
        pipeline_type: "TRIGGERED",
        columns_to_sync: undefined,
        embedding_vector_columns: [
          {
            name: "embedding",
            embedding_dimension: 16,
          },
        ],
      },
    });
  });

  it("rejects invalid storage-optimized embedding dimensions", () => {
    expect(
      () =>
        new DatabricksVectorStore({
          workspaceUrl: "https://workspace.databricks.com",
          httpPath: "/sql/1.0/warehouses/test",
          accessToken: "dapi-test",
          catalog: "main",
          schema: "default",
          collectionName: "memories",
          dimension: 3,
          endpointType: "STORAGE_OPTIMIZED",
        }),
    ).toThrow("require dimensions divisible by 16");
  });

  it("rejects HYBRID vector search without query text", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      queryType: "HYBRID",
      syncPollIntervalMs: 0,
    });

    await expect(store.search([1, 0, 0], 5)).rejects.toThrow(
      "Databricks HYBRID search requires query_text",
    );
    expect(
      axiosModule.__mockHttpClient.post.mock.calls.find(
        ([url]: [string]) => url === "/indexes/main.default.memories/query",
      ),
    ).toBeUndefined();
  });

  it("roundtrips migration user ids", async () => {
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
    });

    await store.setUserId("custom-user");
    expect(await store.getUserId()).toBe("custom-user");
  });

  it("escapes backslashes and quotes in SQL string literals (injection-safe)", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    // The id/user_id carry a single quote and a backslash. Databricks SQL treats
    // "\" as an escape char, so without doubling it, "\'" would break out of the
    // literal (injection) and any backslash would be dropped on write.
    await store.insert([[1, 0, 0]], ["a'b\\c"], [{ user_id: "x'y\\z" }]);

    const session = databricksSql.__mockSession;
    const insertSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0])
      .find((sql: string) => sql.includes("INSERT INTO main.default.memories"));

    expect(insertSql).toBeDefined();
    // Backslash doubled AND quote doubled: 'a''b\\c'
    expect(insertSql).toContain("'a''b\\\\c'");
    // The un-escaped single-backslash form (the breakout vector) must be absent.
    expect(insertSql).not.toContain("'a''b\\c'");
  });

  it("pushes session filters into the SQL WHERE clause when listing", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;
    session.executeStatement.mockClear();

    await store.list({ user_id: "u1" }, 10);

    const listSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("SELECT memory_id, payload FROM main.default.memories"),
      );

    expect(listSql).toBeDefined();
    expect(listSql).toContain("WHERE user_id = 'u1'");
  });

  it("list(): pushes null-safe ne/nin predicates into the WHERE clause", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;

    session.executeStatement.mockClear();
    await store.list({ agent_id: { ne: "a2" } }, 10);
    const neSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("SELECT memory_id, payload FROM main.default.memories"),
      );
    expect(neSql).toBeDefined();
    expect(neSql).toContain("(agent_id IS NULL OR agent_id != 'a2')");
    expect(neSql).not.toContain("WHERE agent_id != 'a2'");

    session.executeStatement.mockClear();
    await store.list({ agent_id: { nin: ["a2", "a3"] } }, 10);
    const ninSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("SELECT memory_id, payload FROM main.default.memories"),
      );
    expect(ninSql).toBeDefined();
    expect(ninSql).toContain(
      "(agent_id IS NULL OR agent_id NOT IN ('a2', 'a3'))",
    );
    expect(ninSql).not.toContain("WHERE agent_id NOT IN ('a2', 'a3')");
  });

  it("list(): bounds the SQL scan with LIMIT topK when the filter fully pushes down", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;

    session.executeStatement.mockClear();
    await store.list({ user_id: "u1" });
    const defaultTopKSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("SELECT memory_id, payload FROM main.default.memories"),
      );
    expect(defaultTopKSql).toContain("LIMIT 100");

    session.executeStatement.mockClear();
    await store.list({ user_id: "u1" }, 7);
    const customTopKSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("SELECT memory_id, payload FROM main.default.memories"),
      );
    expect(customTopKSql).toContain("LIMIT 7");
  });

  it("list(): rejects a topK that isn't a positive integer before it reaches SQL", async () => {
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    for (const badTopK of [
      0,
      -1,
      2.5,
      NaN,
      "10; DROP TABLE t" as unknown as number,
    ]) {
      await expect(store.list({ user_id: "u1" }, badTopK)).rejects.toThrow(
        `Databricks vector store: topK must be a positive integer, got ${badTopK}`,
      );
    }
  });

  it("list(): falls back to the 10k scan ceiling (no WHERE) when $or can't be pushed down", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;
    session.executeStatement.mockClear();

    await store.list({ $or: [{ user_id: "u1" }, { topic: "beta" }] });

    const listSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("SELECT memory_id, payload FROM main.default.memories"),
      );

    expect(listSql).toBeDefined();
    expect(listSql).not.toContain("WHERE");
    expect(listSql).toContain("LIMIT 10000");
  });

  it("provisions a dedicated text_lemmatized column for BM25 keyword search", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();

    const session = databricksSql.__mockSession;
    const createSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) =>
        sql.startsWith("CREATE TABLE IF NOT EXISTS main.default.memories"),
      );

    expect(createSql).toBeDefined();
    expect(createSql).toContain("text_lemmatized STRING");
  });

  it("writes lemmatized text on insert and refreshes it on update", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;
    session.executeStatement.mockClear();

    await store.insert(
      [[1, 0, 0]],
      ["id-1"],
      [{ data: "running shoes", textLemmatized: "run shoe" }],
    );

    const insertSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) => sql.startsWith("INSERT INTO"));

    expect(insertSql).toContain(
      "(memory_id, embedding, payload, text_lemmatized, user_id, agent_id, run_id)",
    );
    expect(insertSql).toContain("'run shoe'");

    session.executeStatement.mockClear();
    await store.update("id-1", [0, 1, 0], {
      data: "walking boots",
      textLemmatized: "walk boot",
    });

    const updateSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) => sql.startsWith("UPDATE"));

    expect(updateSql).toContain("text_lemmatized = 'walk boot'");
  });

  it("falls back to payload.data when textLemmatized is absent", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    await store.initialize();
    const session = databricksSql.__mockSession;
    session.executeStatement.mockClear();

    await store.insert([[1, 0, 0]], ["id-1"], [{ data: "plain text" }]);

    const insertSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0].replace(/\s+/g, " ").trim())
      .find((sql: string) => sql.startsWith("INSERT INTO"));

    expect(insertSql).toContain("'plain text'");
  });

  it("coalesces triggered-index syncs across sequential deletes", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 1,
    });

    await store.initialize();
    const httpClient = axiosModule.__mockHttpClient;
    httpClient.post.mockClear();

    // deleteAll() awaits each deleteMemory in turn -- exactly this shape.
    for (let index = 0; index < 8; index += 1) {
      await store.delete(`id-${index}`);
    }
    await store.search([1, 0, 0], 5);

    const syncPosts = httpClient.post.mock.calls.filter(
      ([url]: [string]) => url === "/indexes/main.default.memories/sync",
    );

    expect(syncPosts.length).toBeGreaterThanOrEqual(1);
    expect(syncPosts.length).toBeLessThan(8);
  });

  it("starts one sync for concurrent writers, and still drains the second write", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 1,
    });

    await store.initialize();
    const httpClient = axiosModule.__mockHttpClient;
    httpClient.post.mockClear();

    const syncPosts = () =>
      httpClient.post.mock.calls.filter(
        ([url]: [string]) => url === "/indexes/main.default.memories/sync",
      ).length;

    await Promise.all([
      store.insert([[1, 0, 0]], ["id-a"], [{ data: "alpha" }]),
      store.insert([[0, 1, 0]], ["id-b"], [{ data: "beta" }]),
    ]);

    // Both writers ran before any sync settled. Exactly one drain may own the pipeline --
    // if both had raced past the guard they would each have POSTed their own sync.
    expect(syncPosts()).toBe(1);

    // The second writer's rows are not lost: the live drain re-checks the queue and syncs again.
    await store.search([1, 0, 0], 5);
    expect(syncPosts()).toBe(2);
  });

  it("does not block writes on index readiness, and surfaces sync failures on the next read", async () => {
    const axiosModule = require("axios");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 1,
      syncTimeoutMs: 10,
    });

    await store.initialize();
    // Every readiness poll from here on reports not-ready, so the sync can only time out.
    axiosModule.__setIndexNeverReady(true);

    // The write still resolves: it schedules the sync, it does not wait for it.
    await expect(
      store.insert([[1, 0, 0]], ["id-1"], [{ data: "alpha" }]),
    ).resolves.toBeUndefined();

    // The reader is what pays -- and inherits the deferred failure.
    await expect(store.search([1, 0, 0], 5)).rejects.toThrow();

    // The error is consumed once, not latched forever.
    axiosModule.__setIndexNeverReady(false);
    await expect(store.search([1, 0, 0], 5)).resolves.toBeDefined();
  });

  it("update() does not null out session columns on a partial payload", async () => {
    const databricksSql = require("@databricks/sql");
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 1,
    });

    await store.initialize();
    await store.insert(
      [[1, 0, 0]],
      ["id-1"],
      [{ user_id: "u1", topic: "alpha" }],
    );
    // Partial payload -- omits user_id/agent_id/run_id, the way a caller updating just one
    // field would. Mirrors Python's `excluded_keys`: these must survive untouched.
    await store.update("id-1", [0, 1, 0], { topic: "beta" });

    const session = databricksSql.__mockSession;
    const updateSql = session.executeStatement.mock.calls
      .map((call: [string]) => call[0])
      .find((sql: string) => sql.includes("UPDATE"));

    expect(updateSql).toBeDefined();
    expect(updateSql).not.toMatch(/\buser_id\s*=/);
    expect(updateSql).not.toMatch(/\bagent_id\s*=/);
    expect(updateSql).not.toMatch(/\brun_id\s*=/);
    expect(updateSql).toMatch(/embedding\s*=/);
    expect(updateSql).toMatch(/payload\s*=/);
  });

  it("list() rejects an unsafe-integer topK that would slip past Number.isInteger", async () => {
    const store = new DatabricksVectorStore({
      workspaceUrl: "https://workspace.databricks.com",
      httpPath: "/sql/1.0/warehouses/test",
      accessToken: "dapi-test",
      catalog: "main",
      schema: "default",
      collectionName: "memories",
      dimension: 3,
      syncPollIntervalMs: 0,
    });

    // 1e21 is Number.isInteger()-true but not representable exactly, and stringifies as
    // "1e+21" -- meaningless (and unguarded) as a SQL LIMIT.
    await expect(store.list({ user_id: "u1" }, 1e21)).rejects.toThrow(
      /topK must be a positive integer/,
    );
    // Sanity: a normal topK is still accepted (does not throw).
    await expect(store.list({ user_id: "u1" }, 10)).resolves.toBeDefined();
  });
});

// ───────────────────────────────────────────────────────────────────────────
// Cassandra — mock client, test interface + idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("Cassandra – backward compat with mocked client", () => {
  let CassandraDB: any;

  beforeEach(() => {
    jest.resetModules();

    jest.doMock("cassandra-driver", () => {
      const rows = new Map<
        string,
        { id: string; vector: number[]; payload: string }
      >();
      const memoryRows = () =>
        Array.from(rows.entries())
          .filter(([key]) => key.startsWith("memories:"))
          .map(([, row]) => row);

      class MockClient {
        connect = jest.fn().mockResolvedValue(undefined);

        execute = jest
          .fn()
          .mockImplementation(
            async (
              query: string,
              params: any[] = [],
              options: Record<string, any> = {},
            ) => {
              const normalized = query.replace(/\s+/g, " ").trim();

              if (normalized.startsWith("CREATE KEYSPACE IF NOT EXISTS")) {
                return { rows: [] };
              }

              if (normalized.startsWith("CREATE TABLE IF NOT EXISTS")) {
                return { rows: [] };
              }

              if (
                normalized.startsWith(
                  "INSERT INTO mem0.memories (id, vector, payload) VALUES (?, ?, ?)",
                )
              ) {
                rows.set(`memories:${params[0]}`, {
                  id: params[0],
                  vector: params[1],
                  payload: params[2],
                });
                return { rows: [] };
              }

              if (
                normalized.startsWith(
                  "SELECT id, payload FROM mem0.memories WHERE id = ?",
                )
              ) {
                const row = rows.get(`memories:${params[0]}`);
                return {
                  rows: row ? [{ id: row.id, payload: row.payload }] : [],
                };
              }

              if (
                normalized.startsWith(
                  "SELECT id, vector, payload FROM mem0.memories",
                )
              ) {
                return {
                  rows: memoryRows().map((row) => ({
                    ...row,
                  })),
                };
              }

              if (
                normalized.startsWith("SELECT id, payload FROM mem0.memories")
              ) {
                return {
                  rows: memoryRows().map((row) => ({
                    id: row.id,
                    payload: row.payload,
                  })),
                };
              }

              if (normalized.startsWith("DROP TABLE IF EXISTS mem0.memories")) {
                for (const key of Array.from(rows.keys())) {
                  if (key.startsWith("memories:")) {
                    rows.delete(key);
                  }
                }
                return { rows: [] };
              }

              if (
                normalized.startsWith("DELETE FROM mem0.memories WHERE id = ?")
              ) {
                rows.delete(`memories:${params[0]}`);
                return { rows: [] };
              }

              if (
                normalized.startsWith(
                  "INSERT INTO mem0.memory_migrations (id, user_id) VALUES (?, ?)",
                )
              ) {
                rows.set(`migrations:${params[0]}`, {
                  id: params[0],
                  vector: [0],
                  payload: JSON.stringify({ user_id: params[1] }),
                });
                return { rows: [] };
              }

              if (
                normalized.startsWith(
                  "SELECT user_id FROM mem0.memory_migrations WHERE id = ?",
                )
              ) {
                const row = rows.get(`migrations:${params[0]}`);
                if (!row) {
                  return { rows: [] };
                }
                return {
                  rows: [{ user_id: JSON.parse(row.payload).user_id }],
                };
              }

              throw new Error(
                `Unexpected Cassandra query: ${normalized} prepare=${options.prepare}`,
              );
            },
          );
      }

      return {
        __esModule: true,
        default: {
          Client: jest.fn().mockImplementation(() => new MockClient()),
          auth: {
            PlainTextAuthProvider: jest
              .fn()
              .mockImplementation((username: string, password: string) => ({
                username,
                password,
              })),
          },
        },
      };
    });

    CassandraDB = require("../src/vector_stores/cassandra").CassandraDB;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new CassandraDB({
      client: {
        execute: jest.fn().mockResolvedValue({ rows: [] }),
      },
      collectionName: "memories",
      dimension: 3,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const cassandraDriver = require("cassandra-driver");
    const store = new CassandraDB({
      contactPoints: ["127.0.0.1"],
      localDataCenter: "datacenter1",
      collectionName: "memories",
      dimension: 3,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();
    await Promise.all([p1, p2, p3]);

    const clientInstance = cassandraDriver.default.Client.mock.results[0].value;
    expect(clientInstance.connect).toHaveBeenCalledTimes(1);
  });

  it("shapes Cassandra writes and normalizes search results", async () => {
    const cassandraDriver = require("cassandra-driver");
    const store = new CassandraDB({
      contactPoints: ["127.0.0.1"],
      localDataCenter: "datacenter1",
      collectionName: "memories",
      dimension: 3,
    });

    await store.initialize();
    await store.insert(
      [[1, 0, 0]],
      ["id-1"],
      [{ user_id: "u1", topic: "alpha" }],
    );

    const clientInstance = cassandraDriver.default.Client.mock.results[0].value;
    expect(clientInstance.execute).toHaveBeenCalledWith(
      expect.stringContaining(
        "INSERT INTO mem0.memories (id, vector, payload)",
      ),
      ["id-1", [1, 0, 0], JSON.stringify({ user_id: "u1", topic: "alpha" })],
      { prepare: true },
    );

    const results = await store.search([1, 0, 0], 5, { user_id: "u1" });
    expect(results).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 1,
      },
    ]);
  });

  it("roundtrips migration user ids", async () => {
    const store = new CassandraDB({
      contactPoints: ["127.0.0.1"],
      localDataCenter: "datacenter1",
      collectionName: "memories",
      dimension: 3,
    });

    await store.setUserId("custom-user");
    expect(await store.getUserId()).toBe("custom-user");
  });

  it("supports get, update, delete, and list", async () => {
    const store = new CassandraDB({
      contactPoints: ["127.0.0.1"],
      localDataCenter: "datacenter1",
      collectionName: "memories",
      dimension: 3,
    });

    await store.insert(
      [
        [1, 0, 0],
        [0, 1, 0],
      ],
      ["id-1", "id-2"],
      [
        { user_id: "u1", topic: "alpha" },
        { user_id: "u2", topic: "beta" },
      ],
    );

    expect(await store.get("missing")).toBeNull();
    expect(await store.get("id-1")).toEqual({
      id: "id-1",
      payload: { user_id: "u1", topic: "alpha" },
    });

    await store.update("id-1", [0, 0, 1], {
      user_id: "u1",
      topic: "gamma",
    });
    expect(await store.get("id-1")).toEqual({
      id: "id-1",
      payload: { user_id: "u1", topic: "gamma" },
    });

    const [listed, count] = await store.list({ user_id: "u1" }, 10);
    expect(count).toBe(1);
    expect(listed).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "gamma" },
      },
    ]);

    await store.delete("id-2");
    expect(await store.get("id-2")).toBeNull();

    await store.deleteCol();
    const [afterDrop, afterDropCount] = await store.list(undefined, 10);
    expect(afterDrop).toEqual([]);
    expect(afterDropCount).toBe(0);
  });

  it("scans paged search and list results", async () => {
    const execute = jest
      .fn()
      .mockImplementation(
        async (
          query: string,
          _params: any[] = [],
          options: Record<string, any> = {},
        ) => {
          const normalized = query.replace(/\s+/g, " ").trim();

          if (normalized.startsWith("CREATE KEYSPACE IF NOT EXISTS")) {
            return { rows: [] };
          }

          if (normalized.startsWith("CREATE TABLE IF NOT EXISTS")) {
            return { rows: [] };
          }

          if (
            normalized.startsWith(
              "SELECT id, vector, payload FROM mem0.memories",
            )
          ) {
            if (!options.pageState) {
              return {
                rows: [
                  {
                    id: "id-1",
                    vector: [1, 0, 0],
                    payload: JSON.stringify({ user_id: "u1", topic: "alpha" }),
                  },
                ],
                pageState: "page-2",
              };
            }

            return {
              rows: [
                {
                  id: "id-2",
                  vector: [0, 1, 0],
                  payload: JSON.stringify({ user_id: "u2", topic: "beta" }),
                },
              ],
              pageState: null,
            };
          }

          if (normalized.startsWith("SELECT id, payload FROM mem0.memories")) {
            if (!options.pageState) {
              return {
                rows: [
                  {
                    id: "id-1",
                    payload: JSON.stringify({ user_id: "u1", topic: "alpha" }),
                  },
                ],
                pageState: "page-2",
              };
            }

            return {
              rows: [
                {
                  id: "id-2",
                  payload: JSON.stringify({ user_id: "u2", topic: "beta" }),
                },
              ],
              pageState: null,
            };
          }

          if (
            normalized.startsWith(
              "SELECT user_id FROM mem0.memory_migrations WHERE id = ?",
            )
          ) {
            return { rows: [] };
          }

          throw new Error(`Unexpected Cassandra query: ${normalized}`);
        },
      );
    const store = new CassandraDB({
      client: { execute },
      collectionName: "memories",
      dimension: 3,
    });

    const searchResults = await store.search([1, 0, 0], 5);
    expect(searchResults).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 1,
      },
      {
        id: "id-2",
        payload: { user_id: "u2", topic: "beta" },
        score: 0,
      },
    ]);

    const [listed, count] = await store.list(undefined, 10);
    expect(count).toBe(2);
    expect(listed).toEqual([
      {
        id: "id-1",
        payload: { user_id: "u1", topic: "alpha" },
      },
      {
        id: "id-2",
        payload: { user_id: "u2", topic: "beta" },
      },
    ]);

    expect(execute).toHaveBeenCalledWith(
      expect.stringContaining("SELECT id, vector, payload"),
      [],
      expect.objectContaining({
        autoPage: false,
        fetchSize: 500,
        pageState: undefined,
      }),
    );
    expect(execute).toHaveBeenCalledWith(
      expect.stringContaining("SELECT id, vector, payload"),
      [],
      expect.objectContaining({
        autoPage: false,
        fetchSize: 500,
        pageState: "page-2",
      }),
    );
    expect(execute).toHaveBeenCalledWith(
      expect.stringContaining("SELECT id, payload"),
      [],
      expect.objectContaining({
        autoPage: false,
        fetchSize: 500,
        pageState: "page-2",
      }),
    );
  });

  it("rejects unsafe identifiers", () => {
    expect(
      () =>
        new CassandraDB({
          client: {
            execute: jest.fn().mockResolvedValue({ rows: [] }),
          },
          keyspace: "bad-name",
          collectionName: "memories",
          dimension: 3,
        }),
    ).toThrow("Invalid keyspace");
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 6. S3 Vectors — mock AWS client, test interface + init
// ───────────────────────────────────────────────────────────────────────────
describe("S3 Vectors – backward compat with mocked client", () => {
  function createMockS3VectorsClient(options?: {
    queryDistance?: number;
    queryDistanceMetric?: "cosine" | "euclidean";
  }) {
    const buckets = new Set<string>();
    const indexes = new Map<
      string,
      {
        dimension: number;
        distanceMetric: string;
      }
    >();
    const vectors = new Map<
      string,
      {
        key: string;
        data: { float32: number[] };
        metadata: Record<string, any>;
      }
    >();

    const vectorMapKey = (indexName: string, key: string) =>
      `${indexName}:${key}`;

    return {
      send: jest.fn().mockImplementation(async (command: any) => {
        const name = command.constructor.name;
        const input = command.input;

        switch (name) {
          case "GetVectorBucketCommand":
            if (!buckets.has(input.vectorBucketName)) {
              const error: any = new Error("Bucket not found");
              error.name = "NotFoundException";
              throw error;
            }
            return {};
          case "CreateVectorBucketCommand":
            if (buckets.has(input.vectorBucketName)) {
              const error: any = new Error("Bucket exists");
              error.name = "ConflictException";
              throw error;
            }
            buckets.add(input.vectorBucketName);
            return {};
          case "GetIndexCommand":
            if (!indexes.has(input.indexName)) {
              const error: any = new Error("Index not found");
              error.name = "NotFoundException";
              throw error;
            }
            return {};
          case "CreateIndexCommand":
            if (indexes.has(input.indexName)) {
              const error: any = new Error("Index exists");
              error.name = "ConflictException";
              throw error;
            }
            indexes.set(input.indexName, {
              dimension: input.dimension,
              distanceMetric: input.distanceMetric,
            });
            return {};
          case "PutVectorsCommand":
            for (const vector of input.vectors || []) {
              vectors.set(vectorMapKey(input.indexName, vector.key), {
                key: vector.key,
                data: vector.data,
                metadata: vector.metadata || {},
              });
            }
            return {};
          case "QueryVectorsCommand":
            return {
              distanceMetric: options?.queryDistanceMetric ?? "cosine",
              vectors: [
                {
                  key: "doc-1",
                  metadata: { user_id: "u1", topic: "alpha" },
                  distance: options?.queryDistance ?? 0.25,
                },
              ],
            };
          case "GetVectorsCommand":
            return {
              vectors: (input.keys || [])
                .map((key: string) =>
                  vectors.get(vectorMapKey(input.indexName, key)),
                )
                .filter(Boolean),
            };
          case "DeleteVectorsCommand":
            for (const key of input.keys || []) {
              vectors.delete(vectorMapKey(input.indexName, key));
            }
            return {};
          case "DeleteIndexCommand":
            indexes.delete(input.indexName);
            for (const key of Array.from(vectors.keys())) {
              if (key.startsWith(`${input.indexName}:`)) {
                vectors.delete(key);
              }
            }
            return {};
          case "ListVectorsCommand":
            return {
              vectors: Array.from(vectors.values())
                .filter((entry) =>
                  vectorMapKey(input.indexName, entry.key).startsWith(
                    `${input.indexName}:`,
                  ),
                )
                .map((entry) => ({
                  key: entry.key,
                  metadata: entry.metadata,
                })),
            };
          default:
            throw new Error(`Unexpected S3Vectors command: ${name}`);
        }
      }),
    };
  }

  function findCommandInput(
    client: { send: jest.Mock },
    commandName: string,
  ): Record<string, any> | undefined {
    const match = client.send.mock.calls.find(
      ([command]) => command.constructor.name === commandName,
    );
    return match?.[0]?.input;
  }

  it("implements full VectorStore interface", () => {
    const { S3Vectors } = require("../src/vector_stores/s3_vectors");
    const store = new S3Vectors({
      client: createMockS3VectorsClient(),
      vectorBucketName: "test-bucket",
      collectionName: "test-index",
      embeddingModelDims: 3,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const { S3Vectors } = require("../src/vector_stores/s3_vectors");
    const mockClient = createMockS3VectorsClient();
    const store = new S3Vectors({
      client: mockClient,
      vectorBucketName: "test-bucket",
      collectionName: "test-index",
      embeddingModelDims: 3,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();

    await Promise.all([p1, p2, p3]);

    expect(
      mockClient.send.mock.calls.filter(
        ([command]) => command.constructor.name === "CreateVectorBucketCommand",
      ),
    ).toHaveLength(1);
    expect(
      mockClient.send.mock.calls.filter(
        ([command]) => command.constructor.name === "CreateIndexCommand",
      ),
    ).toHaveLength(1);
    expect(
      mockClient.send.mock.calls.filter(
        ([command]) => command.constructor.name === "GetVectorBucketCommand",
      ),
    ).toHaveLength(1);
    expect(
      mockClient.send.mock.calls.filter(
        ([command]) => command.constructor.name === "GetIndexCommand",
      ),
    ).toHaveLength(1);
  });

  it("shapes S3 write requests and normalizes search results", async () => {
    const { S3Vectors } = require("../src/vector_stores/s3_vectors");
    const mockClient = createMockS3VectorsClient();
    const store = new S3Vectors({
      client: mockClient,
      vectorBucketName: "test-bucket",
      collectionName: "test-index",
      embeddingModelDims: 3,
    });

    await store.initialize();
    await store.insert(
      [[0.1, 0.2, 0.3]],
      ["doc-1"],
      [{ user_id: "u1", topic: "alpha" }],
    );

    const putInput = findCommandInput(mockClient, "PutVectorsCommand");
    expect(putInput).toMatchObject({
      vectorBucketName: "test-bucket",
      indexName: "test-index",
      vectors: [
        {
          key: "doc-1",
          data: { float32: [0.1, 0.2, 0.3] },
          metadata: { user_id: "u1", topic: "alpha" },
        },
      ],
    });

    const results = await store.search([0.1, 0.2, 0.3], 5, { user_id: "u1" });

    const queryInput = findCommandInput(mockClient, "QueryVectorsCommand");
    expect(queryInput).toMatchObject({
      vectorBucketName: "test-bucket",
      indexName: "test-index",
      queryVector: { float32: [0.1, 0.2, 0.3] },
      topK: 5,
      filter: { user_id: { $eq: "u1" } },
      returnMetadata: true,
      returnDistance: true,
    });
    expect(results).toEqual([
      {
        id: "doc-1",
        payload: { user_id: "u1", topic: "alpha" },
        score: 0.75,
      },
    ]);
  });

  it("normalizes euclidean distances without collapsing scores to zero", async () => {
    const { S3Vectors } = require("../src/vector_stores/s3_vectors");
    const store = new S3Vectors({
      client: createMockS3VectorsClient({
        queryDistance: 1.5,
        queryDistanceMetric: "euclidean",
      }),
      vectorBucketName: "test-bucket",
      collectionName: "test-index",
      embeddingModelDims: 3,
      distanceMetric: "cosine",
    });

    const [result] = await store.search([0.1, 0.2, 0.3], 1);

    expect(result).toEqual({
      id: "doc-1",
      payload: { user_id: "u1", topic: "alpha" },
      score: 0.4,
    });
  });

  it("normalizes empty in and nin operands before search hits AWS", async () => {
    const { S3Vectors } = require("../src/vector_stores/s3_vectors");
    const mockClient = createMockS3VectorsClient();
    const store = new S3Vectors({
      client: mockClient,
      vectorBucketName: "test-bucket",
      collectionName: "test-index",
      embeddingModelDims: 3,
    });

    const baselineQueryCalls = mockClient.send.mock.calls.filter(
      ([command]) => command.constructor.name === "QueryVectorsCommand",
    ).length;
    const emptyInResults = await store.search([0.1, 0.2, 0.3], 5, {
      topic: { in: [] },
    });
    expect(emptyInResults).toEqual([]);
    expect(
      mockClient.send.mock.calls.filter(
        ([command]) => command.constructor.name === "QueryVectorsCommand",
      ),
    ).toHaveLength(baselineQueryCalls);

    await store.search([0.1, 0.2, 0.3], 5, {
      topic: { nin: [] },
    });

    const queryInput = findCommandInput(mockClient, "QueryVectorsCommand");
    expect(queryInput).toMatchObject({
      vectorBucketName: "test-bucket",
      indexName: "test-index",
      queryVector: { float32: [0.1, 0.2, 0.3] },
      topK: 5,
      returnMetadata: true,
      returnDistance: true,
    });
    expect(queryInput.filter).toBeUndefined();
  });
  it("applies client-side list filters, including empty $nin operands", async () => {
    const { S3Vectors } = require("../src/vector_stores/s3_vectors");
    const mockClient = createMockS3VectorsClient();
    const store = new S3Vectors({
      client: mockClient,
      vectorBucketName: "test-bucket",
      collectionName: "test-index",
      embeddingModelDims: 3,
    });

    await store.initialize();
    await store.insert(
      [
        [0.1, 0.2, 0.3],
        [0.3, 0.2, 0.1],
      ],
      ["doc-1", "doc-2"],
      [
        { user_id: "u1", topic: "alpha", tags: ["keep"] },
        { user_id: "u2", topic: "beta", tags: ["skip"] },
      ],
    );

    const [allRows, allCount] = await store.list({ topic: { nin: [] } }, 10);
    expect(allCount).toBe(2);
    expect(allRows.map((row) => row.id)).toEqual(["doc-1", "doc-2"]);

    const [filteredRows, filteredCount] = await store.list(
      {
        $and: [{ topic: { nin: ["beta"] } }, { tags: { in: ["keep"] } }],
      },
      10,
    );

    expect(filteredCount).toBe(1);
    expect(filteredRows).toEqual([
      {
        id: "doc-1",
        payload: { user_id: "u1", topic: "alpha", tags: ["keep"] },
      },
    ]);
  });
});

// 6. Neptune Analytics — mock NeptuneGraph client, test interface + init
// ───────────────────────────────────────────────────────────────────────────
describe("Neptune Analytics – backward compat with mocked client", () => {
  // `@aws-sdk/client-neptune-graph` is an optional peer loaded via dynamic `import()`
  // (see neptune_analytics.ts). Register a default virtual mock so every test that
  // exercises `executeQuery()` -- even ones that inject their own `config.client` --
  // can resolve `sdk.ExecuteQueryCommand` without the real package being installed.
  // Tests that care about the AWS client constructor itself override this locally
  // with their own `jest.doMock(..., { virtual: true })` before requiring the module.
  beforeEach(() => {
    jest.resetModules();
    jest.doMock(
      "@aws-sdk/client-neptune-graph",
      () => ({
        ExecuteQueryCommand: class ExecuteQueryCommand {
          input: any;

          constructor(input: any) {
            this.input = input;
          }
        },
        NeptuneGraphClient: class NeptuneGraphClient {
          constructor(public config: any) {}

          async send() {
            throw new Error(
              "Neptune Analytics tests must inject a mock `client`; the default virtual SDK has no server to talk to.",
            );
          }
        },
      }),
      { virtual: true },
    );
  });

  afterEach(() => {
    jest.resetModules();
  });

  function createMockResponse(body: Record<string, any>) {
    return {
      payload: {
        transformToString: jest.fn().mockResolvedValue(JSON.stringify(body)),
      },
    };
  }

  function createMockNeptuneClient(options?: {
    failInsertUpsert?: boolean;
    throwInsertUpsert?: boolean;
    failUpdateUpsert?: boolean;
    failPayloadWrite?: boolean;
  }) {
    const nodes = new Map<
      string,
      {
        embedding?: number[];
        labels: string[];
        properties: Record<string, any>;
      }
    >();
    let storedUserId: string | undefined;

    const getPropertyValue = (
      node: { labels: string[]; properties: Record<string, any> },
      property: string,
    ) => {
      if (property === "~label") {
        return node.labels;
      }

      return node.properties[property];
    };

    const matchesFilter = (
      node: { labels: string[]; properties: Record<string, any> },
      filter: any,
    ): boolean => {
      if (!filter) {
        return true;
      }

      if (Array.isArray(filter.andAll)) {
        return filter.andAll.every((entry: any) => matchesFilter(node, entry));
      }

      if (Array.isArray(filter.orAll)) {
        return filter.orAll.some((entry: any) => matchesFilter(node, entry));
      }

      const propertyMatcher = (
        property: string,
        predicate: (value: any) => boolean,
      ) => {
        const value = getPropertyValue(node, property);
        if (property === "~label") {
          return (
            Array.isArray(value) && value.some((label) => predicate(label))
          );
        }

        return predicate(value);
      };

      if (filter.equals) {
        return propertyMatcher(
          filter.equals.property,
          (value) => value === filter.equals.value,
        );
      }

      if (filter.notEquals) {
        return propertyMatcher(
          filter.notEquals.property,
          (value) => value !== filter.notEquals.value,
        );
      }

      if (filter.greaterThan) {
        return propertyMatcher(
          filter.greaterThan.property,
          (value) =>
            typeof value === "number" && value > filter.greaterThan.value,
        );
      }

      if (filter.greaterThanOrEquals) {
        return propertyMatcher(
          filter.greaterThanOrEquals.property,
          (value) =>
            typeof value === "number" &&
            value >= filter.greaterThanOrEquals.value,
        );
      }

      if (filter.lessThan) {
        return propertyMatcher(
          filter.lessThan.property,
          (value) => typeof value === "number" && value < filter.lessThan.value,
        );
      }

      if (filter.lessThanOrEquals) {
        return propertyMatcher(
          filter.lessThanOrEquals.property,
          (value) =>
            typeof value === "number" && value <= filter.lessThanOrEquals.value,
        );
      }

      if (filter.in) {
        return propertyMatcher(filter.in.property, (value) =>
          filter.in.value.includes(value),
        );
      }

      if (filter.notIn) {
        return propertyMatcher(
          filter.notIn.property,
          (value) => !filter.notIn.value.includes(value),
        );
      }

      if (filter.stringContains) {
        return propertyMatcher(
          filter.stringContains.property,
          (value) =>
            typeof value === "string" &&
            value.includes(filter.stringContains.value),
        );
      }

      if (filter.startsWith) {
        return propertyMatcher(
          filter.startsWith.property,
          (value) =>
            typeof value === "string" &&
            value.startsWith(filter.startsWith.value),
        );
      }

      return false;
    };

    const toNodeRecord = (
      id: string,
      node: { labels: string[]; properties: Record<string, any> },
    ): Record<string, any> => ({
      "~id": id,
      "~labels": [...node.labels],
      "~properties": { ...node.properties },
    });

    const matchesListParameters = (
      properties: Record<string, any>,
      parameters: Record<string, any>,
    ) =>
      Object.entries(parameters)
        .filter(([key]) => key.startsWith("filter_"))
        .every(([key, value]) => {
          const match = key.match(/^filter_(?:eq_)?(.+)_\d+$/);
          if (!match) {
            return true;
          }

          return properties[match[1]] === value;
        });

    const extractStructuredArgument = (
      queryString: string,
      key: string,
    ): any => {
      const keyIndex = queryString.indexOf(`${key}:`);
      if (keyIndex < 0) {
        return undefined;
      }

      const objectStart = queryString.indexOf("{", keyIndex);
      if (objectStart < 0) {
        return undefined;
      }

      let depth = 0;
      for (let index = objectStart; index < queryString.length; index += 1) {
        const char = queryString[index];
        if (char === "{") {
          depth += 1;
        } else if (char === "}") {
          depth -= 1;
          if (depth === 0) {
            const literal = queryString.slice(objectStart, index + 1);
            const jsonLiteral = literal.replace(
              /([{\[,]\s*)([A-Za-z_][A-Za-z0-9_]*)(\s*:)/g,
              '$1"$2"$3',
            );
            return JSON.parse(jsonLiteral);
          }
        }
      }

      return undefined;
    };

    return {
      send: jest.fn().mockImplementation(async (command: any) => {
        const queryString = String(command.input.queryString || "");
        const parameters = command.input.parameters || {};
        const collectionLabelMatch = queryString.match(/MERGE \(n:`([^`]+)`/);
        const collectionLabel = collectionLabelMatch?.[1] || "MEM0_VECTOR_test";

        if (
          queryString.includes("UNWIND $nodeIds AS nodeId") &&
          queryString.includes("RETURN nodeId")
        ) {
          return createMockResponse({
            results: (parameters.nodeIds || [])
              .filter((nodeId: string) => nodes.has(nodeId))
              .map((nodeId: string) => ({ nodeId })),
          });
        }

        if (
          queryString.includes("UNWIND $nodeIds AS nodeId") &&
          queryString.includes("DETACH DELETE n")
        ) {
          for (const nodeId of parameters.nodeIds || []) {
            nodes.delete(nodeId);
          }
          return createMockResponse({ results: [] });
        }

        if (
          queryString.includes("CALL neptune.algo.vectors.upsert") &&
          Array.isArray(parameters.rows) &&
          queryString.includes("RETURN success")
        ) {
          const createsNode = queryString.includes("MERGE");
          const processedRows: any[] = [];
          for (const row of parameters.rows) {
            const existing = nodes.get(row.node_id);
            if (!existing && !createsNode) {
              continue;
            }
            nodes.set(row.node_id, {
              embedding: row.embedding,
              labels: existing?.labels || [collectionLabel],
              properties: existing ? existing.properties : {},
            });
            processedRows.push(row);
          }

          if (options?.throwInsertUpsert) {
            throw new Error("Neptune upsert rejected");
          }

          return createMockResponse({
            results: processedRows.map(() => ({
              success: !options?.failInsertUpsert,
            })),
          });
        }

        if (
          queryString.includes("UNWIND $rows AS row") &&
          queryString.includes("SET n += row.properties")
        ) {
          if (!options?.failPayloadWrite) {
            for (const row of parameters.rows || []) {
              const existing = nodes.get(row.node_id);
              nodes.set(row.node_id, {
                embedding: existing?.embedding,
                labels: existing?.labels || [collectionLabel],
                properties: existing
                  ? { ...existing.properties, ...row.properties }
                  : { ...row.properties },
              });
            }
          }

          return createMockResponse({ results: [{ n: {} }] });
        }

        if (
          queryString.includes("CALL neptune.algo.vectors.upsert") &&
          parameters.vectorId
        ) {
          if (options?.failUpdateUpsert) {
            return createMockResponse({ results: [{ success: false }] });
          }

          const existing = nodes.get(parameters.vectorId);
          if (existing) {
            nodes.set(parameters.vectorId, {
              embedding: parameters.embedding,
              labels: existing.labels,
              properties: parameters.properties || existing.properties,
            });
          }
          return createMockResponse({ results: [{ success: true }] });
        }

        if (queryString.includes("topK.byEmbedding")) {
          const vertexFilter = extractStructuredArgument(
            queryString,
            "vertexFilter",
          );
          const match = [...nodes.entries()].find(([, node]) =>
            matchesFilter(node, vertexFilter),
          );

          return createMockResponse({
            results: match
              ? [
                  {
                    node: toNodeRecord(match[0], match[1]),
                    score: 0.25,
                  },
                ]
              : [],
          });
        }

        if (queryString.includes("pg_schema")) {
          const labels = new Set<string>();
          for (const node of nodes.values()) {
            for (const label of node.labels) {
              labels.add(label);
            }
          }
          if (storedUserId) {
            labels.add("MEM0_VECTOR_memory_migrations");
          }
          return createMockResponse({
            results: [{ result: [...labels] }],
          });
        }

        if (
          queryString.includes(
            "MATCH (n:`MEM0_VECTOR_test` {`~id`: $vectorId})",
          ) &&
          queryString.includes("RETURN n") &&
          queryString.includes("LIMIT 1")
        ) {
          const node = nodes.get(parameters.vectorId);
          return createMockResponse({
            results: node
              ? [{ n: toNodeRecord(parameters.vectorId, node) }]
              : [],
          });
        }

        if (
          queryString.includes("MATCH (n:`MEM0_VECTOR_test`)") &&
          queryString.includes("RETURN count(n) AS count")
        ) {
          const count = [...nodes.values()].filter((node) =>
            matchesListParameters(node.properties, parameters),
          ).length;

          return createMockResponse({ results: [{ count }] });
        }

        if (
          queryString.includes("MATCH (n:`MEM0_VECTOR_test`)") &&
          queryString.includes("RETURN n") &&
          queryString.includes("LIMIT $limit")
        ) {
          const results = [...nodes.entries()]
            .filter(([, node]) =>
              matchesListParameters(node.properties, parameters),
            )
            .slice(0, parameters.limit || 100)
            .map(([id, node]) => ({ n: toNodeRecord(id, node) }));

          return createMockResponse({ results });
        }

        if (
          queryString.includes(
            "MATCH (n:`MEM0_VECTOR_test` {`~id`: $vectorId})",
          ) &&
          queryString.includes("SET n = $properties")
        ) {
          if (options?.failPayloadWrite) {
            throw new Error("Neptune property write rejected");
          }

          const existing = nodes.get(parameters.vectorId);
          if (existing) {
            nodes.set(parameters.vectorId, {
              embedding: existing.embedding,
              labels: existing.labels,
              properties: { ...parameters.properties },
            });
          }
          return createMockResponse({ results: [] });
        }

        if (
          queryString.includes(
            "MATCH (n:`MEM0_VECTOR_test` {`~id`: $vectorId})",
          ) &&
          queryString.includes("DETACH DELETE n")
        ) {
          nodes.delete(parameters.vectorId);
          return createMockResponse({ results: [] });
        }

        if (
          queryString.includes("MATCH (n:`MEM0_VECTOR_test`)") &&
          queryString.includes("DETACH DELETE n")
        ) {
          nodes.clear();
          return createMockResponse({ results: [] });
        }

        if (
          queryString.includes("MATCH (n:`MEM0_VECTOR_memory_migrations`") &&
          queryString.includes("RETURN n")
        ) {
          return createMockResponse({
            results: storedUserId
              ? [
                  {
                    n: toNodeRecord(parameters.userNodeId, {
                      labels: ["MEM0_VECTOR_memory_migrations"],
                      properties: {
                        user_id: storedUserId,
                      },
                    }),
                  },
                ]
              : [],
          });
        }

        if (
          queryString.includes("MERGE (n:`MEM0_VECTOR_memory_migrations`") &&
          queryString.includes("SET n.user_id = $userId")
        ) {
          storedUserId = parameters.userId;
          return createMockResponse({ results: [] });
        }

        return createMockResponse({ results: [{ success: true }] });
      }),
    };
  }

  it("implements full VectorStore interface", () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient(),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();

    expect(p1).toBe(p2);
    expect(p2).toBe(p3);

    await Promise.all([p1, p2, p3]);
    expect(mockClient.send).not.toHaveBeenCalled();
  });

  it("passes custom HTTPS endpoints to the AWS client when graphIdentifier is provided", async () => {
    jest.resetModules();

    const send = jest
      .fn()
      .mockResolvedValue(createMockResponse({ results: [] }));
    const neptuneGraphClient = jest.fn().mockReturnValue({ send });

    jest.doMock(
      "@aws-sdk/client-neptune-graph",
      () => ({
        ExecuteQueryCommand: class ExecuteQueryCommand {
          input: any;

          constructor(input: any) {
            this.input = input;
          }
        },
        NeptuneGraphClient: neptuneGraphClient,
      }),
      { virtual: true },
    );

    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");

    const store = new NeptuneAnalyticsVectorStore({
      graphIdentifier: "g-1234567890",
      endpoint: "https://example.us-east-1.neptune-graph.amazonaws.com",
      collectionName: "test",
      dimension: 3,
      region: "us-east-1",
      profile: "dev-profile",
      maxAttempts: 3,
    });
    await store.initialize();

    // The client is now constructed lazily on first use, not in the constructor.
    await store.search([1, 2, 3], 1);

    expect(neptuneGraphClient).toHaveBeenCalledWith({
      endpoint: "https://example.us-east-1.neptune-graph.amazonaws.com",
      maxAttempts: 3,
      profile: "dev-profile",
      region: "us-east-1",
    });
  });

  it("rejects HTTPS endpoints without an explicit graphIdentifier", () => {
    jest.resetModules();

    jest.doMock(
      "@aws-sdk/client-neptune-graph",
      () => ({
        ExecuteQueryCommand: class ExecuteQueryCommand {
          input: any;

          constructor(input: any) {
            this.input = input;
          }
        },
        NeptuneGraphClient: jest.fn().mockReturnValue({
          send: jest.fn(),
        }),
      }),
      { virtual: true },
    );

    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");

    expect(
      () =>
        new NeptuneAnalyticsVectorStore({
          endpoint: "https://example.us-east-1.neptune-graph.amazonaws.com",
          collectionName: "test",
          dimension: 3,
        }),
    ).toThrow(
      "Neptune Analytics HTTPS endpoints require graphIdentifier; pass graphIdentifier separately or use neptune-graph://<graph-id>.",
    );
  });

  it("derives graphIdentifier from a neptune-graph endpoint URI", async () => {
    jest.resetModules();

    const send = jest
      .fn()
      .mockResolvedValue(createMockResponse({ results: [] }));
    const neptuneGraphClient = jest.fn().mockReturnValue({ send });

    jest.doMock(
      "@aws-sdk/client-neptune-graph",
      () => ({
        ExecuteQueryCommand: class ExecuteQueryCommand {
          input: any;

          constructor(input: any) {
            this.input = input;
          }
        },
        NeptuneGraphClient: neptuneGraphClient,
      }),
      { virtual: true },
    );

    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      endpoint: "neptune-graph://g-1234567890",
      collectionName: "test",
      dimension: 3,
      region: "us-east-1",
    });

    await store.search([1, 2, 3], 1);

    expect(neptuneGraphClient).toHaveBeenCalledWith({
      region: "us-east-1",
    });
    expect(send).toHaveBeenCalled();
    expect(send.mock.calls[0][0].input.graphIdentifier).toBe("g-1234567890");
  });

  it("does not construct the Neptune client or load the SDK until the first query", async () => {
    jest.resetModules();

    let clientConstructions = 0;
    let sdkLoads = 0;
    jest.doMock(
      "@aws-sdk/client-neptune-graph",
      () => {
        sdkLoads++;
        return {
          ExecuteQueryCommand: class ExecuteQueryCommand {
            input: any;

            constructor(input: any) {
              this.input = input;
            }
          },
          NeptuneGraphClient: class NeptuneGraphClient {
            constructor(public config: any) {
              clientConstructions++;
            }

            async send() {
              return createMockResponse({ results: [] });
            }
          },
        };
      },
      { virtual: true },
    );

    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");

    const store = new NeptuneAnalyticsVectorStore({
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    expect(clientConstructions).toBe(0);
    expect(sdkLoads).toBe(0);

    await store.search([1, 2, 3], 1);

    expect(sdkLoads).toBe(1);
    expect(clientConstructions).toBe(1);
  });

  it("retries constructing the Neptune client after a failed SDK load instead of caching the rejection", async () => {
    jest.resetModules();

    let shouldFail = true;
    jest.doMock(
      "@aws-sdk/client-neptune-graph",
      () => {
        if (shouldFail) {
          throw new Error("Cannot find module '@aws-sdk/client-neptune-graph'");
        }
        return {
          ExecuteQueryCommand: class ExecuteQueryCommand {
            input: any;

            constructor(input: any) {
              this.input = input;
            }
          },
          NeptuneGraphClient: class NeptuneGraphClient {
            constructor(public config: any) {}

            async send() {
              return createMockResponse({ results: [] });
            }
          },
        };
      },
      { virtual: true },
    );

    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");

    const store = new NeptuneAnalyticsVectorStore({
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    // First use fails because the optional SDK can't be loaded...
    await expect((store as any).getClient()).rejects.toThrow(
      "The '@aws-sdk/client-neptune-graph' package is required",
    );

    // ...but a later call must retry rather than replay the cached rejection. Without
    // getClient()'s catch-and-reset this second call would throw the same stale error.
    shouldFail = false;
    const client = await (store as any).getClient();
    expect(client).toBeDefined();
    expect(typeof client.send).toBe("function");
  });

  it("shapes Neptune write requests and normalizes search results", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [[1, 2, 3]],
      ["id-1"],
      [{ data: "alpha", label: "topic-a", priority: 7, user_id: "u1" }],
    );

    expect(mockClient.send).toHaveBeenCalled();
    const insertCall = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .find((command: any) =>
        String(command.input.queryString || "").includes("MERGE"),
      );
    const vectorCall = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .find((command: any) =>
        String(command.input.queryString || "").includes(
          "CALL neptune.algo.vectors.upsert",
        ),
      );
    expect(insertCall).toBeDefined();
    expect(insertCall.input.queryString).toContain("MERGE");
    expect(insertCall.input.queryString).not.toContain("FOREACH");
    expect(insertCall.input.parameters.rows[0].properties.label).toBe(
      "topic-a",
    );
    expect(insertCall.input.parameters.rows[0].embedding).toEqual([1, 2, 3]);

    expect(vectorCall).toBeDefined();
    expect(vectorCall.input.queryString).toContain(
      "CALL neptune.algo.vectors.upsert",
    );
    expect(vectorCall.input.queryString).toContain(
      "WITH n, row.embedding AS embedding",
    );
    expect(vectorCall.input.queryString).not.toContain("MERGE");

    const results = await store.search([1, 2, 3], 1, {
      $or: [{ user_id: "u2" }, { priority: { gte: 5 } }],
      data: { contains: "alp" },
    });
    expect(results).toHaveLength(1);
    expect(results[0]).toEqual({
      id: "id-1",
      payload: expect.objectContaining({
        data: "alpha",
        label: "topic-a",
        user_id: "u1",
      }),
      score: 0.8,
    });

    const searchCall =
      mockClient.send.mock.calls[mockClient.send.mock.calls.length - 1];
    const searchQuery = String(searchCall[0].input.queryString || "").replace(
      /\s+/g,
      " ",
    );
    expect(searchQuery).toContain("topK.byEmbedding");
    expect(searchCall[0].input.parameters).toBeUndefined();
    expect(searchQuery).toContain("topK: 1");
    expect(searchQuery).toContain("embedding: [1, 2, 3]");
    expect(searchQuery).toContain(
      'property: "~label", value: "MEM0_VECTOR_test"',
    );
    expect(searchQuery).toContain('property: "user_id", value: "u2"');
    expect(searchQuery).toContain('property: "priority", value: 5');
    expect(searchQuery).toContain(
      'stringContains: { property: "data", value: "alp" }',
    );
  });

  it("escapes adversarial Neptune collection and filter identifiers", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = {
      send: jest.fn().mockImplementation(async (command: any) => {
        const queryString = String(command.input.queryString || "");
        if (queryString.includes("RETURN count(n) AS count")) {
          return createMockResponse({ results: [{ count: 0 }] });
        }

        return createMockResponse({ results: [] });
      }),
    };
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient as any,
      graphIdentifier: "g-1234567890",
      collectionName: "memo`graph",
      dimension: 3,
    });

    await store.list({ "topic`name": ["alpha`1", "beta(2)"] }, 2);
    await store.search([1, 2, 3], 4, {
      "topic`name": { eq: "lookup`value" },
    });

    const listCall = mockClient.send.mock.calls.find(([command]: [any]) =>
      String(command.input.queryString || "").includes("LIMIT $limit"),
    )?.[0];
    const searchCall = mockClient.send.mock.calls.find(([command]: [any]) =>
      String(command.input.queryString || "").includes("topK.byEmbedding"),
    )?.[0];

    expect(listCall).toBeDefined();
    expect(searchCall).toBeDefined();

    const listQuery = String(listCall.input.queryString || "").replace(
      /\s+/g,
      " ",
    );
    const searchQuery = String(searchCall.input.queryString || "").replace(
      /\s+/g,
      " ",
    );

    expect(listQuery).toContain("MATCH (n:`MEM0_VECTOR_memo``graph`)");
    expect(listQuery).toContain("n.`topic``name` IN $filter_in_topic_name_1");
    expect(listCall.input.parameters.filter_in_topic_name_1).toEqual([
      "alpha`1",
      "beta(2)",
    ]);

    expect(searchQuery).toContain("topK.byEmbedding");
    expect(searchQuery).toContain("vertexFilter: {");
    expect(searchQuery).toContain('property: "topic`name"');
    expect(searchQuery).toContain('value: "lookup`value"');
  });

  it("serializes complex list filters into Cypher clauses and parameters", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.list(
      {
        $and: [
          {
            $or: [{ priority: { gte: 5 } }, { data: { startsWith: "alp" } }],
          },
          { $not: [{ archived: true }] },
          { label: { contains: "topic" } },
          { tag: ["a", "b"] },
          { optional: "*" },
        ],
      },
      7,
    );

    const listCall = mockClient.send.mock.calls.find(
      ([command]: [any]) =>
        String(command.input.queryString || "").includes("LIMIT $limit") &&
        String(command.input.queryString || "").includes("RETURN n"),
    )?.[0];
    const countCall = mockClient.send.mock.calls.find(([command]: [any]) =>
      String(command.input.queryString || "").includes(
        "RETURN count(n) AS count",
      ),
    )?.[0];

    expect(listCall).toBeDefined();
    expect(countCall).toBeDefined();

    const listQuery = String(listCall.input.queryString || "").replace(
      /\s+/g,
      " ",
    );
    const countQuery = String(countCall.input.queryString || "").replace(
      /\s+/g,
      " ",
    );

    expect(listQuery).toContain("WHERE (");
    expect(listQuery).toContain("n.`priority` >= $filter_gte_priority_1");
    expect(listQuery).toContain(
      "toString(n.`data`) STARTS WITH $filter_startsWith_data_2",
    );
    expect(listQuery).toContain("NOT (n.`archived` = $filter_archived_3)");
    expect(listQuery).toContain(
      "toString(n.`label`) CONTAINS $filter_contains_label_4",
    );
    expect(listQuery).toContain("n.`tag` IN $filter_in_tag_5");
    expect(listQuery).toContain("n.`optional` IS NOT NULL");
    expect(countQuery).toContain("RETURN count(n) AS count");
    expect(listCall.input.parameters).toEqual({
      filter_gte_priority_1: 5,
      filter_startsWith_data_2: "alp",
      filter_archived_3: true,
      filter_contains_label_4: "topic",
      filter_in_tag_5: ["a", "b"],
      limit: 7,
    });
    expect(countCall.input.parameters).toEqual({
      filter_gte_priority_1: 5,
      filter_startsWith_data_2: "alp",
      filter_archived_3: true,
      filter_contains_label_4: "topic",
      filter_in_tag_5: ["a", "b"],
    });
  });

  it("replaces payloads on update and supports user-id storage", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [[1, 2, 3]],
      ["id-1"],
      [{ data: "alpha", user_id: "u1", stale: "remove-me" }],
    );

    const created = await store.get("id-1");
    expect(created).not.toBeNull();
    expect(created!.payload).toEqual(
      expect.objectContaining({
        data: "alpha",
        user_id: "u1",
      }),
    );

    await store.update("id-1", [3, 2, 1], { data: "beta", user_id: "u1" });

    const updated = await store.get("id-1");
    expect(updated).not.toBeNull();
    expect(updated!.payload).toEqual(
      expect.objectContaining({
        data: "beta",
        user_id: "u1",
      }),
    );
    expect(updated!.payload.stale).toBeUndefined();

    const combinedUpdateCalls = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .filter((command: any) =>
        String(command.input.queryString || "").includes(
          "MATCH (n:`MEM0_VECTOR_test` {`~id`: $vectorId})",
        ),
      );
    expect(
      combinedUpdateCalls.some((command: any) =>
        String(command.input.queryString || "").includes(
          "CALL neptune.algo.vectors.upsert",
        ),
      ),
    ).toBe(true);
    expect(
      combinedUpdateCalls.some((command: any) =>
        String(command.input.queryString || "").includes("SET n = $properties"),
      ),
    ).toBe(true);
    expect(
      combinedUpdateCalls.some((command: any) =>
        String(command.input.queryString || "").includes("FOREACH"),
      ),
    ).toBe(false);

    const [listed, count] = await store.list({ user_id: "u1" });
    expect(count).toBe(1);
    expect(listed[0].id).toBe("id-1");

    const generatedUserId = await store.getUserId();
    expect(typeof generatedUserId).toBe("string");
    expect(generatedUserId.length).toBeGreaterThan(0);

    await store.setUserId("custom-user");
    expect(await store.getUserId()).toBe("custom-user");

    await store.delete("id-1");
    expect(await store.get("id-1")).toBeNull();
  });

  it("supports payload-only and vector-only Neptune updates", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [[1, 2, 3]],
      ["id-1"],
      [{ data: "alpha", user_id: "u1", stale: "remove-me" }],
    );

    await store.update("id-1", [], { data: "payload-only", user_id: "u1" });
    expect((await store.get("id-1"))!.payload).toEqual(
      expect.objectContaining({
        data: "payload-only",
        user_id: "u1",
      }),
    );

    await store.update("id-1", [3, 2, 1], {});
    expect((await store.get("id-1"))!.payload).toEqual(
      expect.objectContaining({
        data: "payload-only",
        user_id: "u1",
      }),
    );

    const updateCalls = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .filter((command: any) =>
        String(command.input.queryString || "").includes(
          "MATCH (n:`MEM0_VECTOR_test` {`~id`: $vectorId})",
        ),
      );
    expect(
      updateCalls.some((command: any) =>
        String(command.input.queryString || "").includes("SET n = $properties"),
      ),
    ).toBe(true);
    expect(
      updateCalls.some(
        (command: any) =>
          String(command.input.queryString || "").includes(
            "CALL neptune.algo.vectors.upsert",
          ) && !("properties" in (command.input.parameters || {})),
      ),
    ).toBe(true);
  });

  it("deletes the full Neptune collection with deleteCol()", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [
        [1, 2, 3],
        [3, 2, 1],
      ],
      ["id-1", "id-2"],
      [
        { data: "alpha", user_id: "u1" },
        { data: "beta", user_id: "u1" },
      ],
    );

    await store.deleteCol();

    const [listed, count] = await store.list({ user_id: "u1" });
    expect(listed).toEqual([]);
    expect(count).toBe(0);

    const deleteColCall = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .find((command: any) =>
        String(command.input.queryString || "").includes(
          "MATCH (n:`MEM0_VECTOR_test`)",
        ),
      );
    expect(deleteColCall).toBeDefined();
    expect(deleteColCall.input.queryString).toContain("DETACH DELETE n");
  });

  it("returns a real total count for list pagination", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient(),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [
        [1, 2, 3],
        [3, 2, 1],
      ],
      ["id-1", "id-2"],
      [
        { data: "alpha", user_id: "u1" },
        { data: "beta", user_id: "u1" },
      ],
    );

    const [listed, count] = await store.list({ user_id: "u1" }, 1);
    expect(listed).toHaveLength(1);
    expect(count).toBe(2);
  });

  it("reads a persisted user id on a fresh store instance", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.setUserId("persisted-user");

    const freshStore = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    expect(await freshStore.getUserId()).toBe("persisted-user");
  });

  it("rolls back the payload when Neptune rejects an update upsert", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient({ failUpdateUpsert: true }),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [[1, 2, 3]],
      ["id-1"],
      [{ data: "alpha", user_id: "u1" }],
    );

    await expect(
      store.update("id-1", [3, 2, 1], { data: "beta", user_id: "u1" }),
    ).rejects.toThrow("Update failed in Neptune Analytics");

    // Neptune's vector index isn't transactional: the payload write already lands by the
    // time the vector step rejects. Without compensation the new metadata would be stuck
    // pointing at the stale embedding, so a failed update rolls the payload back to what
    // it was before the call instead of leaving the two desynced.
    const afterFailedUpsert = await store.get("id-1");
    expect(afterFailedUpsert).not.toBeNull();
    expect(afterFailedUpsert!.payload).toEqual(
      expect.objectContaining({
        data: "alpha",
        user_id: "u1",
      }),
    );
  });

  it("does not leave a phantom record when Neptune rejects an insert upsert", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient({ failInsertUpsert: true }),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await expect(
      store.insert([[1, 2, 3]], ["id-1"], [{ data: "alpha", user_id: "u1" }]),
    ).rejects.toThrow("Insert failed in Neptune Analytics");

    expect(await store.get("id-1")).toBeNull();
  });

  it("does not leave a phantom record when Neptune throws during insert upsert", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient({ throwInsertUpsert: true }),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await expect(
      store.insert([[1, 2, 3]], ["id-1"], [{ data: "alpha", user_id: "u1" }]),
    ).rejects.toThrow("Neptune upsert rejected");

    expect(await store.get("id-1")).toBeNull();
  });

  it("does not leave a phantom record when the property write fails", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient({ failPayloadWrite: true }),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [[1, 2, 3]],
      ["id-1"],
      [{ data: "alpha", user_id: "u1" }],
    );

    const results = await store.search([1, 2, 3], 1);
    expect(results).toEqual([]);
  });

  it("does not make the embedding durable when the update payload write fails", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient({ failPayloadWrite: true });
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await expect(
      store.update("id-1", [3, 2, 1], { data: "beta", user_id: "u1" }),
    ).rejects.toThrow();

    const upsertCalls = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .filter((command: any) =>
        String(command.input.queryString || "").includes(
          "neptune.algo.vectors.upsert",
        ),
      );
    expect(upsertCalls).toHaveLength(0);
  });

  it("writes the Neptune payload before the vector on a combined update", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const mockClient = createMockNeptuneClient();
    const store = new NeptuneAnalyticsVectorStore({
      client: mockClient,
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await store.insert(
      [[1, 2, 3]],
      ["id-1"],
      [{ data: "alpha", user_id: "u1" }],
    );

    await store.update("id-1", [3, 2, 1], { data: "beta", user_id: "u1" });

    const updateQueries = mockClient.send.mock.calls
      .map(([command]: [any]) => command)
      .filter((command: any) =>
        String(command.input.queryString || "").includes(
          "MATCH (n:`MEM0_VECTOR_test` {`~id`: $vectorId})",
        ),
      )
      .map((command: any) => String(command.input.queryString || ""));

    const payloadIndex = updateQueries.findIndex((queryString: string) =>
      queryString.includes("SET n = $properties"),
    );
    const vectorIndex = updateQueries.findIndex((queryString: string) =>
      queryString.includes("CALL neptune.algo.vectors.upsert"),
    );

    expect(payloadIndex).toBeGreaterThanOrEqual(0);
    expect(vectorIndex).toBeGreaterThan(payloadIndex);
  });

  it("throws for unsupported Neptune search and list filter shapes", async () => {
    const {
      NeptuneAnalyticsVectorStore,
    } = require("../src/vector_stores/neptune_analytics");
    const store = new NeptuneAnalyticsVectorStore({
      client: createMockNeptuneClient(),
      graphIdentifier: "g-1234567890",
      collectionName: "test",
      dimension: 3,
    });

    await expect(store.search([1, 2, 3], 1, { optional: "*" })).rejects.toThrow(
      "Neptune Analytics vector search does not support property-existence filters.",
    );
    await expect(
      store.search([1, 2, 3], 1, { data: { icontains: "alp" } }),
    ).rejects.toThrow(
      "Neptune Analytics vector search does not support case-insensitive contains filters.",
    );
    await expect(
      store.search([1, 2, 3], 1, { data: { regex: "alp" } }),
    ).rejects.toThrow("Unsupported Neptune Analytics filter operator: regex");
    await expect(
      store.search([1, 2, 3], 1, {
        $not: [{ data: { contains: "alp" } }],
      }),
    ).rejects.toThrow(
      "Neptune Analytics cannot negate this filter shape for vector search.",
    );
    await expect(
      store.search([1, 2, 3], 1, { data: { eq: () => "alp" } }),
    ).rejects.toThrow(
      "Unsupported Neptune Analytics algorithm value type: function",
    );
    await expect(store.list({ data: { icontains: "alp" } })).rejects.toThrow(
      "Neptune Analytics list filters do not support case-insensitive contains filters.",
    );
    await expect(store.list({ data: { regex: "alp" } })).rejects.toThrow(
      "Unsupported Neptune Analytics filter operator: regex",
    );
  });
});

// ───────────────────────────────────────────────────────────────────────────
// ───────────────────────────────────────────────────────────────────────────
// 7. Vectorize — mock Cloudflare client, test idempotent init
// ───────────────────────────────────────────────────────────────────────────
describe("Vectorize – backward compat with mocked client", () => {
  let VectorizeDB: any;

  beforeEach(() => {
    jest.resetModules();

    jest.doMock("cloudflare", () => {
      const mockIndexes = {
        list: jest.fn().mockReturnValue({
          [Symbol.asyncIterator]: () => ({
            next: async () => ({ done: true }),
          }),
        }),
        create: jest.fn().mockResolvedValue({}),
        delete: jest.fn().mockResolvedValue({}),
        query: jest.fn().mockResolvedValue({ matches: [] }),
        getByIds: jest.fn().mockResolvedValue([]),
        metadataIndex: {
          list: jest.fn().mockResolvedValue({ metadataIndexes: [] }),
          create: jest.fn().mockResolvedValue({}),
        },
      };

      return {
        __esModule: true,
        default: jest.fn().mockImplementation(() => ({
          apiToken: "fake-token",
          vectorize: { indexes: mockIndexes },
          __mockIndexes: mockIndexes,
        })),
      };
    });

    VectorizeDB = require("../src/vector_stores/vectorize").VectorizeDB;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new VectorizeDB({
      apiKey: "fake-token",
      indexName: "test-index",
      accountId: "test-account",
      dimension: 768,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const store = new VectorizeDB({
      apiKey: "fake-token",
      indexName: "test-index",
      accountId: "test-account",
      dimension: 768,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    await Promise.all([p1, p2]);
    // No crash = idempotent
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 8. LangchainVectorStore — mock Langchain client, verify no-op init
// ───────────────────────────────────────────────────────────────────────────
describe("LangchainVectorStore – backward compat", () => {
  it("implements full VectorStore interface", () => {
    const { LangchainVectorStore } = require("../src/vector_stores/langchain");
    const mockLcStore = {
      addVectors: jest.fn().mockResolvedValue(undefined),
      similaritySearchVectorWithScore: jest.fn().mockResolvedValue([]),
      delete: jest.fn().mockResolvedValue(undefined),
    };
    const store = new LangchainVectorStore({
      client: mockLcStore,
      collectionName: "test",
      dimension: 768,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is a no-op and safe to call multiple times", async () => {
    const { LangchainVectorStore } = require("../src/vector_stores/langchain");
    const mockLcStore = {
      addVectors: jest.fn().mockResolvedValue(undefined),
      similaritySearchVectorWithScore: jest.fn().mockResolvedValue([]),
    };
    const store = new LangchainVectorStore({
      client: mockLcStore,
      collectionName: "test",
    });
    await store.initialize();
    await store.initialize();
    await store.initialize();
  });

  it("insert and search work with mock Langchain client", async () => {
    const { LangchainVectorStore } = require("../src/vector_stores/langchain");
    const mockLcStore = {
      addVectors: jest.fn().mockResolvedValue(undefined),
      similaritySearchVectorWithScore: jest
        .fn()
        .mockResolvedValue([
          [
            { metadata: { _mem0_id: "id-1", data: "test" }, pageContent: "" },
            0.95,
          ],
        ]),
    };
    const store = new LangchainVectorStore({
      client: mockLcStore,
      collectionName: "test",
      dimension: 4,
    });

    await store.insert([[1, 2, 3, 4]], ["id-1"], [{ data: "test" }]);
    expect(mockLcStore.addVectors).toHaveBeenCalled();

    const results = await store.search([1, 2, 3, 4], 1);
    expect(results.length).toBe(1);
    expect(results[0].id).toBe("id-1");
    expect(results[0].score).toBe(0.95);
  });

  it("getUserId and setUserId work (in-memory)", async () => {
    const { LangchainVectorStore } = require("../src/vector_stores/langchain");
    const mockLcStore = {
      addVectors: jest.fn(),
      similaritySearchVectorWithScore: jest.fn(),
    };
    const store = new LangchainVectorStore({
      client: mockLcStore,
      collectionName: "test",
    });

    const defaultId = await store.getUserId();
    expect(defaultId).toBe("anonymous-langchain-user");

    await store.setUserId("custom-user");
    expect(await store.getUserId()).toBe("custom-user");
  });

  it("rejects vector dimension mismatch on insert", async () => {
    const { LangchainVectorStore } = require("../src/vector_stores/langchain");
    const mockLcStore = {
      addVectors: jest.fn(),
      similaritySearchVectorWithScore: jest.fn(),
    };
    const store = new LangchainVectorStore({
      client: mockLcStore,
      collectionName: "test",
      dimension: 4,
    });

    await expect(store.insert([[1, 2, 3]], ["id-1"], [{}])).rejects.toThrow(
      "Vector dimension mismatch",
    );
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 8. AzureMySQL — mock mysql2 pool, test interface + idempotent init + CRUD
// ───────────────────────────────────────────────────────────────────────────
describe("AzureMySQL – backward compat with mocked client", () => {
  let AzureMySQLDB: any;
  let mockPool: any;

  beforeEach(() => {
    jest.resetModules();

    const rows = new Map<
      string,
      { id: string; vector: string; payload: string }
    >();
    let userId: string | null = null;

    mockPool = {
      execute: jest
        .fn()
        .mockImplementation(async (sql: string, params?: any[]) => {
          const q = sql.trim().toUpperCase();

          if (
            q.startsWith("CREATE TABLE") ||
            q.startsWith("CREATE FULLTEXT") ||
            q.startsWith("DROP TABLE")
          ) {
            return [{ affectedRows: 0 }, []];
          }

          // INSERT into main table (ON DUPLICATE KEY)
          if (q.startsWith("INSERT INTO `") && q.includes("ON DUPLICATE KEY")) {
            const [id, vector, payload] = params!;
            rows.set(id, { id, vector, payload });
            return [{ affectedRows: 1 }, []];
          }

          // INSERT into memory_migrations
          if (q.startsWith("INSERT INTO MEMORY_MIGRATIONS")) {
            userId = params![0];
            return [{ affectedRows: 1 }, []];
          }

          // SELECT id, payload FROM table WHERE id = ? (single-row get by PK)
          if (
            q.startsWith("SELECT ID, PAYLOAD FROM") &&
            q.includes("WHERE ID = ?")
          ) {
            const row = rows.get(params![0]);
            return [row ? [row] : [], []];
          }

          // SELECT id, vector, payload FROM table (search with optional filters)
          if (q.startsWith("SELECT ID, VECTOR, PAYLOAD FROM")) {
            return [[...rows.values()], []];
          }

          if (q.includes("MATCH(TEXT_LEMMATIZED) AGAINST")) {
            const term = String(params?.[0] ?? "").toLowerCase();
            const limit = Number(params?.[params!.length - 1] ?? rows.size);
            const matched = [...rows.values()]
              .filter((row) => {
                const payload = JSON.parse(row.payload);
                return String(payload.textLemmatized ?? "")
                  .toLowerCase()
                  .includes(term);
              })
              .slice(0, limit)
              .map((row) => ({ ...row, score: 1 }));
            return [matched, []];
          }

          // SELECT id, payload FROM table (list with LIMIT)
          if (q.startsWith("SELECT ID, PAYLOAD FROM")) {
            return [
              [...rows.values()].slice(0, params![params!.length - 1]),
              [],
            ];
          }

          // SELECT COUNT(*)
          if (q.startsWith("SELECT COUNT(*)")) {
            return [[{ cnt: rows.size }], []];
          }

          // UPDATE
          if (q.startsWith("UPDATE `")) {
            const [vector, payload, id] = params!;
            if (rows.has(id)) {
              rows.set(id, { id, vector, payload });
            }
            return [{ affectedRows: 1 }, []];
          }

          // DELETE
          if (q.startsWith("DELETE FROM `")) {
            rows.delete(params![0]);
            return [{ affectedRows: 1 }, []];
          }

          // SELECT user_id FROM memory_migrations
          if (q.startsWith("SELECT USER_ID FROM MEMORY_MIGRATIONS")) {
            return [userId ? [{ user_id: userId }] : [], []];
          }

          return [[], []];
        }),
      getConnection: jest.fn().mockImplementation(async () => ({
        beginTransaction: jest.fn().mockResolvedValue(undefined),
        execute: jest
          .fn()
          .mockImplementation(async (sql: string, params?: any[]) => {
            return mockPool.execute(sql, params);
          }),
        commit: jest.fn().mockResolvedValue(undefined),
        rollback: jest.fn().mockResolvedValue(undefined),
        release: jest.fn(),
      })),
      end: jest.fn().mockResolvedValue(undefined),
    };

    jest.doMock("mysql2/promise", () => ({
      createPool: jest.fn().mockReturnValue(mockPool),
    }));

    AzureMySQLDB = require("../src/vector_stores/azure_mysql").AzureMySQLDB;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new AzureMySQLDB({
      host: "localhost",
      user: "test",
      database: "testdb",
      collectionName: "memories",
      embeddingModelDims: 4,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.keywordSearch).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent", async () => {
    const mysql2 = require("mysql2/promise");
    const store = new AzureMySQLDB({
      host: "localhost",
      user: "test",
      database: "testdb",
      collectionName: "memories",
      embeddingModelDims: 4,
    });

    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();
    await Promise.all([p1, p2, p3]);

    // createPool called only once despite 3 initialize() calls
    expect(mysql2.createPool).toHaveBeenCalledTimes(1);
  });

  it("full CRUD cycle", async () => {
    const store = new AzureMySQLDB({
      host: "localhost",
      user: "test",
      database: "testdb",
      collectionName: "memories",
      embeddingModelDims: 4,
    });
    await store.initialize();

    const vec1 = [1, 0, 0, 0];
    const vec2 = [0, 1, 0, 0];

    // Insert
    await store.insert(
      [vec1, vec2],
      ["id-1", "id-2"],
      [{ data: "alpha" }, { data: "beta" }],
    );

    // Get
    const item = await store.get("id-1");
    expect(item).not.toBeNull();
    expect(item!.id).toBe("id-1");

    // Search — vec1 should rank first
    const results = await store.search(vec1, 2);
    expect(results.length).toBeGreaterThan(0);

    // Update
    await store.update("id-1", [0, 0, 1, 0], { data: "updated" });

    // List
    const [listed, count] = await store.list();
    expect(listed.length).toBeGreaterThan(0);
    expect(count).toBeGreaterThan(0);

    // Delete
    await store.delete("id-2");

    // DeleteCol
    await store.deleteCol();
  });

  it("keywordSearch matches textLemmatized payloads", async () => {
    const store = new AzureMySQLDB({
      host: "localhost",
      user: "test",
      database: "testdb",
      collectionName: "memories",
      embeddingModelDims: 4,
    });
    await store.initialize();

    await store.insert(
      [[1, 0, 0, 0]],
      ["id-1"],
      [
        {
          data: "alpha",
          textLemmatized: "alpha normalized",
        },
      ],
    );

    const results = await store.keywordSearch("normalized", 5);
    expect(results).not.toBeNull();
    expect(results![0].id).toBe("id-1");
  });

  it("getUserId and setUserId roundtrip", async () => {
    const store = new AzureMySQLDB({
      host: "localhost",
      user: "test",
      database: "testdb",
      collectionName: "memories",
      embeddingModelDims: 4,
    });
    await store.initialize();

    await store.setUserId("custom-user");
    const retrieved = await store.getUserId();
    expect(retrieved).toBe("custom-user");
  });

  it("uses mysql_clear_password semantics for Azure tokens", async () => {
    jest.doMock("@azure/identity", () => ({
      DefaultAzureCredential: jest.fn().mockImplementation(() => ({
        getToken: jest.fn().mockResolvedValue({ token: "aad-token" }),
      })),
    }));

    const mysql2 = require("mysql2/promise");
    const store = new AzureMySQLDB({
      host: "localhost",
      user: "test",
      database: "testdb",
      collectionName: "memories",
      embeddingModelDims: 4,
      useAzureCredential: true,
    });
    await store.initialize();

    const poolConfig = mysql2.createPool.mock.calls[0][0];
    const plugin = poolConfig.authPlugins.mysql_clear_password();
    expect(plugin()).toEqual(Buffer.from("aad-token\0"));
  });

  it("rejects invalid collectionName at construction", () => {
    expect(
      () =>
        new AzureMySQLDB({
          host: "localhost",
          user: "test",
          database: "testdb",
          collectionName: "drop--table",
          embeddingModelDims: 4,
        }),
    ).toThrow("Invalid collectionName");
  });
});

// ───────────────────────────────────────────────────────────────────────────
// 9. Memory class — ensure it works with each provider via mocked factories
// ───────────────────────────────────────────────────────────────────────────
describe("Memory class – backward compat with all providers", () => {
  function createMockEmbedder(dims: number) {
    return {
      embed: jest.fn().mockResolvedValue(new Array(dims).fill(0)),
      embedBatch: jest.fn().mockResolvedValue([new Array(dims).fill(0)]),
    };
  }

  function createMockVectorStore() {
    return {
      insert: jest.fn().mockResolvedValue(undefined),
      search: jest.fn().mockResolvedValue([]),
      get: jest.fn().mockResolvedValue(null),
      update: jest.fn().mockResolvedValue(undefined),
      delete: jest.fn().mockResolvedValue(undefined),
      deleteCol: jest.fn().mockResolvedValue(undefined),
      list: jest.fn().mockResolvedValue([[], 0]),
      getUserId: jest.fn().mockResolvedValue("test-user-id"),
      setUserId: jest.fn().mockResolvedValue(undefined),
      initialize: jest.fn().mockResolvedValue(undefined),
    };
  }

  let MemoryClass: any;
  let mockEmbedderFactory: any;
  let mockVectorStoreFactory: any;

  beforeEach(() => {
    jest.resetModules();

    const mockEmbedder = createMockEmbedder(1536);
    const mockVStore = createMockVectorStore();

    mockEmbedderFactory = { create: jest.fn().mockReturnValue(mockEmbedder) };
    mockVectorStoreFactory = { create: jest.fn().mockReturnValue(mockVStore) };

    jest.doMock("../src/utils/factory", () => ({
      EmbedderFactory: mockEmbedderFactory,
      VectorStoreFactory: mockVectorStoreFactory,
      LLMFactory: {
        create: jest.fn().mockReturnValue({
          generateResponse: jest.fn().mockResolvedValue('{"facts":[]}'),
        }),
      },
      HistoryManagerFactory: {
        create: jest.fn().mockReturnValue({
          addHistory: jest.fn().mockResolvedValue(undefined),
          getHistory: jest.fn().mockResolvedValue([]),
          reset: jest.fn().mockResolvedValue(undefined),
        }),
      },
    }));

    jest.doMock("../src/utils/telemetry", () => ({
      captureClientEvent: jest.fn().mockResolvedValue(undefined),
      isTelemetryEnabled: jest.fn(() => false),
    }));

    MemoryClass = require("../src/memory").Memory;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("works with explicit dimension (no probe)", async () => {
    const mem = new MemoryClass({
      embedder: { provider: "openai", config: { apiKey: "k" } },
      vectorStore: {
        provider: "memory",
        config: { collectionName: "test", dimension: 1536 },
      },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await mem.getAll({ filters: { user_id: "u1" } });

    const embedder = mockEmbedderFactory.create.mock.results[0].value;
    expect(embedder.embed).not.toHaveBeenCalledWith("dimension probe");

    const vsCreateCall = mockVectorStoreFactory.create.mock.calls[0];
    expect(vsCreateCall[1].dimension).toBe(1536);
  });

  it("works with embeddingDims (no probe)", async () => {
    const mem = new MemoryClass({
      embedder: {
        provider: "ollama",
        config: { model: "nomic-embed-text", embeddingDims: 768 },
      },
      vectorStore: { provider: "qdrant", config: { collectionName: "test" } },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    const mockEmbedder768 = createMockEmbedder(768);
    mockEmbedderFactory.create.mockReturnValue(mockEmbedder768);

    await mem.getAll({ filters: { user_id: "u1" } });
    expect(mockEmbedder768.embed).not.toHaveBeenCalledWith("dimension probe");
  });

  it("probes when no dimension provided", async () => {
    const mockEmbedder768 = createMockEmbedder(768);
    mockEmbedderFactory.create.mockReturnValue(mockEmbedder768);

    const mem = new MemoryClass({
      embedder: { provider: "ollama", config: { model: "nomic-embed-text" } },
      vectorStore: { provider: "qdrant", config: { collectionName: "test" } },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await mem.getAll({ filters: { user_id: "u1" } });
    expect(mockEmbedder768.embed).toHaveBeenCalledWith("dimension probe");

    const vsCreateCall = mockVectorStoreFactory.create.mock.calls[0];
    expect(vsCreateCall[1].dimension).toBe(768);
  });

  it("calls vectorStore.initialize() after creation", async () => {
    const mockVStore = createMockVectorStore();
    mockVectorStoreFactory.create.mockReturnValue(mockVStore);

    const mem = new MemoryClass({
      embedder: { provider: "openai", config: { apiKey: "k" } },
      vectorStore: {
        provider: "memory",
        config: { collectionName: "test", dimension: 1536 },
      },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await mem.getAll({ filters: { user_id: "u1" } });
    expect(mockVStore.initialize).toHaveBeenCalled();
  });

  it("all public methods work after initialization", async () => {
    const memoryId = "3f0d5b6a-9c1e-4a2b-8d7f-1e2c3a4b5c6d";
    const mockVStore = createMockVectorStore();
    mockVStore.search.mockResolvedValue([
      { id: memoryId, payload: { memory: "test", hash: "h" }, score: 0.9 },
    ]);
    mockVStore.get.mockResolvedValue({
      id: memoryId,
      payload: {
        memory: "test",
        hash: "h",
        created_at: new Date().toISOString(),
        updated_at: new Date().toISOString(),
      },
    });
    mockVStore.list
      .mockResolvedValueOnce([
        [
          {
            id: memoryId,
            payload: {
              memory: "test",
              hash: "h",
              created_at: new Date().toISOString(),
              updated_at: new Date().toISOString(),
            },
          },
        ],
        1,
      ])
      .mockResolvedValue([[], 0]);
    mockVectorStoreFactory.create.mockReturnValue(mockVStore);

    const mem = new MemoryClass({
      embedder: { provider: "openai", config: { apiKey: "k" } },
      vectorStore: {
        provider: "memory",
        config: { collectionName: "test", dimension: 1536 },
      },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    // getAll
    const all = await mem.getAll({ filters: { user_id: "u1" } });
    expect(all).toBeDefined();

    // search
    const searchResult = await mem.search("query", {
      filters: { user_id: "u1" },
    });
    expect(searchResult).toBeDefined();

    // get
    const item = await mem.get(memoryId);
    expect(item).toBeDefined();

    // update
    const updateResult = await mem.update(memoryId, { text: "new data" });
    expect(updateResult.message).toBe("Memory updated successfully!");

    // delete
    const deleteResult = await mem.delete(memoryId);
    expect(deleteResult.message).toBe("Memory deleted successfully!");

    // deleteAll
    const deleteAllResult = await mem.deleteAll({ userId: "u1" });
    expect(deleteAllResult.message).toBe("Memories deleted successfully!");

    // history
    const history = await mem.history(memoryId);
    expect(Array.isArray(history)).toBe(true);
  });

  it("reset re-creates vector store correctly", async () => {
    const mockVStore1 = createMockVectorStore();
    const mockVStore2 = createMockVectorStore();
    mockVectorStoreFactory.create
      .mockReturnValueOnce(mockVStore1)
      .mockReturnValueOnce(mockVStore2);

    const mem = new MemoryClass({
      embedder: { provider: "openai", config: { apiKey: "k" } },
      vectorStore: {
        provider: "memory",
        config: { collectionName: "test", dimension: 1536 },
      },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await mem.getAll({ filters: { user_id: "u1" } });
    expect(mockVectorStoreFactory.create).toHaveBeenCalledTimes(1);

    await mem.reset();
    expect(mockVectorStoreFactory.create).toHaveBeenCalledTimes(2);
    // Second store should also have initialize called
    expect(mockVStore2.initialize).toHaveBeenCalled();
  });

  it("derives a separate Databricks entity table when provider casing differs", async () => {
    const primaryStore = createMockVectorStore();
    const entityStore = createMockVectorStore();
    mockVectorStoreFactory.create
      .mockReturnValueOnce(primaryStore)
      .mockReturnValueOnce(entityStore);

    const mem = new MemoryClass({
      embedder: { provider: "openai", config: { apiKey: "k" } },
      vectorStore: {
        provider: "Databricks",
        config: {
          workspaceUrl: "https://workspace.databricks.com",
          httpPath: "/sql/1.0/warehouses/test",
          accessToken: "dapi-test",
          collectionName: "memories",
          tableName: "memory_rows",
          dimension: 1536,
        },
      },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await mem.getAll({ filters: { user_id: "u1" } });
    await (mem as any).getEntityStore();

    expect(mockVectorStoreFactory.create).toHaveBeenNthCalledWith(
      2,
      "databricks",
      expect.objectContaining({
        collectionName: "memories_entities",
        tableName: "memory_rows_entities",
      }),
    );
    expect(entityStore.initialize).toHaveBeenCalled();
  });

  // optional-peers.test.ts proves no optional peer is imported at module scope. This asserts the
  // other half for Databricks: the driver is still loaded lazily (memoized dynamic import, with
  // retry-on-failure via getSqlModule()) rather than dropped entirely or made static/eager.
  it("still loads the optional @databricks/sql driver lazily", () => {
    const source = fs.readFileSync(
      path.join(__dirname, "../src/vector_stores/databricks.ts"),
      "utf8",
    );
    expect(source).toContain('import("@databricks/sql")');
  });

  it("sends file-based entities to their own DB when provider casing differs", async () => {
    const primaryStore = createMockVectorStore();
    const entityStore = createMockVectorStore();
    mockVectorStoreFactory.create
      .mockReturnValueOnce(primaryStore)
      .mockReturnValueOnce(entityStore);

    const mem = new MemoryClass({
      embedder: { provider: "openai", config: { apiKey: "k" } },
      vectorStore: {
        provider: "Memory",
        config: {
          collectionName: "memories",
          dbPath: "/tmp/mem0-casing.db",
          dimension: 1536,
        },
      },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await mem.getAll({ filters: { user_id: "u1" } });
    await (mem as any).getEntityStore();

    // Un-normalized, the `=== "memory"` check misses, dbPath is left alone, and entities land
    // in the very file they are supposed to be split out of.
    expect(mockVectorStoreFactory.create).toHaveBeenNthCalledWith(
      2,
      "memory",
      expect.objectContaining({
        collectionName: "memories_entities",
        dbPath: "/tmp/mem0-casing_entities.db",
      }),
    );
    expect(entityStore.initialize).toHaveBeenCalled();
  });

  it("propagates init error to public methods", async () => {
    const failingEmbedder = {
      embed: jest.fn().mockRejectedValue(new Error("Embedder unreachable")),
      embedBatch: jest.fn(),
    };
    mockEmbedderFactory.create.mockReturnValue(failingEmbedder);

    const consoleSpy = jest
      .spyOn(console, "error")
      .mockImplementation(() => {});

    const mem = new MemoryClass({
      embedder: { provider: "ollama", config: { model: "test" } },
      vectorStore: { provider: "qdrant", config: { collectionName: "t" } },
      llm: { provider: "openai", config: { apiKey: "k" } },
      disableHistory: true,
    });

    await expect(mem.getAll({ filters: { user_id: "u1" } })).rejects.toThrow(
      "auto-detect embedding dimension",
    );
    await expect(
      mem.search("q", { filters: { user_id: "u1" } }),
    ).rejects.toThrow("auto-detect embedding dimension");
    await expect(mem.get("id")).rejects.toThrow(
      "auto-detect embedding dimension",
    );

    consoleSpy.mockRestore();
  });
});

// ───────────────────────────────────────────────────────────────────────────
// WeaviateDB — mock client, behavioral surface checks
// ───────────────────────────────────────────────────────────────────────────
describe("WeaviateDB – backward compat with mocked client", () => {
  let WeaviateDB: any;
  let mockClient: any;
  let mockCol: any;

  beforeEach(() => {
    jest.resetModules();

    mockCol = {
      data: {
        insertMany: jest.fn().mockResolvedValue({}),
        deleteById: jest.fn().mockResolvedValue({}),
        update: jest.fn().mockResolvedValue({}),
      },
      query: {
        nearVector: jest.fn().mockResolvedValue({ objects: [] }),
        bm25: jest.fn().mockResolvedValue({ objects: [] }),
        fetchObjectById: jest.fn().mockResolvedValue(null),
        fetchObjects: jest.fn().mockResolvedValue({ objects: [] }),
      },
      filter: {
        byProperty: jest
          .fn()
          .mockReturnValue({ equal: jest.fn().mockReturnValue({}) }),
      },
    };

    mockClient = {
      collections: {
        exists: jest.fn().mockResolvedValue(false),
        create: jest.fn().mockResolvedValue({}),
        get: jest.fn().mockReturnValue(mockCol),
        delete: jest.fn().mockResolvedValue({}),
      },
    };

    jest.doMock("weaviate-client", () => ({
      default: {
        connectToLocal: jest.fn().mockResolvedValue(mockClient),
        connectToWeaviateCloud: jest.fn().mockResolvedValue(mockClient),
        connectToCustom: jest.fn().mockResolvedValue(mockClient),
        ApiKey: jest.fn().mockReturnValue({}),
        configure: {
          vectorizer: { none: jest.fn().mockReturnValue({}) },
          vectorIndex: { hnsw: jest.fn().mockReturnValue({}) },
        },
      },
      Filters: { and: jest.fn().mockReturnValue({ __mock: "filter" }) },
      __esModule: true,
    }));

    WeaviateDB = require("../src/vector_stores/weaviate").WeaviateDB;
  });

  afterEach(() => {
    jest.restoreAllMocks();
    jest.resetModules();
  });

  it("implements full VectorStore interface", () => {
    const store = new WeaviateDB({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 768,
    });
    expect(typeof store.insert).toBe("function");
    expect(typeof store.search).toBe("function");
    expect(typeof store.keywordSearch).toBe("function");
    expect(typeof store.get).toBe("function");
    expect(typeof store.update).toBe("function");
    expect(typeof store.delete).toBe("function");
    expect(typeof store.deleteCol).toBe("function");
    expect(typeof store.list).toBe("function");
    expect(typeof store.getUserId).toBe("function");
    expect(typeof store.setUserId).toBe("function");
    expect(typeof store.initialize).toBe("function");
  });

  it("initialize() is idempotent (same promise returned)", async () => {
    const store = new WeaviateDB({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 768,
    });
    const p1 = store.initialize();
    const p2 = store.initialize();
    const p3 = store.initialize();
    await Promise.all([p1, p2, p3]);
    expect(mockClient.collections.create).toHaveBeenCalledTimes(1);
  });

  it("insert shapes insertMany request correctly", async () => {
    const store = new WeaviateDB({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 3,
    });
    await store.initialize();
    await store.insert([[0.1, 0.2, 0.3]], ["id-1"], [{ data: "hello" }]);
    expect(mockCol.data.insertMany).toHaveBeenCalledWith(
      expect.arrayContaining([
        expect.objectContaining({
          id: "id-1",
          properties: { data: "hello" },
          vectors: [0.1, 0.2, 0.3],
        }),
      ]),
    );
  });

  it("search normalizes nearVector result to id/payload/score", async () => {
    mockCol.query.nearVector.mockResolvedValue({
      objects: [
        {
          uuid: "id-1",
          properties: { data: "x" },
          metadata: { distance: 0.2 },
        },
      ],
    });
    const store = new WeaviateDB({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 3,
    });
    await store.initialize();
    const results = await store.search([0.1, 0.2, 0.3], 1);
    expect(results).toHaveLength(1);
    expect(results[0]).toMatchObject({
      id: "id-1",
      payload: { data: "x" },
      score: 0.8,
    });
  });

  it("getUserId / setUserId roundtrip", async () => {
    const store = new WeaviateDB({
      client: mockClient,
      collectionName: "test",
      embeddingModelDims: 768,
    });
    await store.setUserId("custom-user");
    expect(await store.getUserId()).toBe("custom-user");
  });
});