chore: import upstream snapshot with attribution

tests/unit/memory-vectorstore-load.test.ts

@@ -0,0 +1,128 @@
+/**
+ * tests/unit/memory-vectorstore-load.test.ts
+ *
+ * Plan 21 — Memory Engine Redesign (F4)
+ * Tests for getVectorStore() singleton load behaviour:
+ *   - Returns instance when sqlite-vec loads successfully.
+ *   - Returns null when the db driver has no loadExtension (cloud/WASM backend).
+ *   - Singleton: two calls return the same instance.
+ *   - _resetVectorStoreSingleton allows re-initialization.
+ *
+ * NOTE: Testing the "sqlite-vec load failure" path requires a module-level seam.
+ * We expose VECTOR_STORE_DISABLE_VEC env var to force the null path in tests.
+ * The production code checks this env var to allow test isolation.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omr-vecstore-load-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.DISABLE_SQLITE_AUTO_BACKUP = "true";
+
+const core = await import("../../src/lib/db/core.ts");
+const vsModule = await import("../../src/lib/memory/vectorStore.ts");
+const { getVectorStore, _resetVectorStoreSingleton } = vsModule;
+
+function cleanup() {
+  _resetVectorStoreSingleton();
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.afterEach(() => {
+  cleanup();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+});
+
+// ──────────────── Singleton ────────────────
+
+test("getVectorStore() returns the same singleton on two consecutive calls", () => {
+  _resetVectorStoreSingleton();
+  const r1 = getVectorStore();
+  const r2 = getVectorStore();
+  assert.strictEqual(r1, r2, "two calls must return the exact same reference");
+});
+
+test("_resetVectorStoreSingleton() allows re-initialization", () => {
+  _resetVectorStoreSingleton();
+  const r1 = getVectorStore();
+  _resetVectorStoreSingleton();
+  const r2 = getVectorStore();
+  // Both are valid (either instance or null) but may be different objects on re-init.
+  // The key is that reset does not throw and returns a valid result.
+  assert.ok(r1 === null || r1 !== null); // trivially true — exercises code path
+  assert.ok(r2 === null || r2 !== null);
+});
+
+// ──────────────── Result shape ────────────────
+
+test("getVectorStore() returns null or a VectorStore instance (never throws)", () => {
+  _resetVectorStoreSingleton();
+
+  let result: unknown;
+  let threw = false;
+  try {
+    result = getVectorStore();
+  } catch {
+    threw = true;
+  }
+
+  assert.equal(threw, false, "getVectorStore() must never throw — must return null on failure");
+  assert.ok(
+    result === null || (typeof result === "object" && result !== null),
+    `getVectorStore() must return object or null, got ${typeof result}`,
+  );
+});
+
+test("getVectorStore() result has all required VectorStore methods when not null", () => {
+  _resetVectorStoreSingleton();
+  const store = getVectorStore();
+
+  if (store === null) {
+    // sqlite-vec is not available in this environment — skip method shape check.
+    return;
+  }
+
+  const requiredMethods = [
+    "ensureReady",
+    "upsertVector",
+    "deleteVector",
+    "searchVector",
+    "searchHybrid",
+    "stats",
+    "resetForSignature",
+  ] as const;
+
+  for (const method of requiredMethods) {
+    assert.ok(
+      typeof (store as Record<string, unknown>)[method] === "function",
+      `VectorStore must have method ${method}`,
+    );
+  }
+});
+
+// ──────────────── Null path ────────────────
+
+test("getVectorStore() returns null when VECTOR_STORE_DISABLE_VEC env var is set", () => {
+  // This test uses the VECTOR_STORE_DISABLE_VEC seam to force the null/degraded path.
+  // The env var simulates environments where sqlite-vec cannot be loaded (cloud/WASM).
+  process.env.VECTOR_STORE_DISABLE_VEC = "true";
+  _resetVectorStoreSingleton();
+  const result = getVectorStore();
+  delete process.env.VECTOR_STORE_DISABLE_VEC;
+
+  assert.equal(result, null, "VECTOR_STORE_DISABLE_VEC=true must force null result");
+});