fix(core): isolate vector metadata and search results

.changeset/clean-vector-search-results.md

@@ -0,0 +1,10 @@
+---
+"@voltagent/core": patch
+"@voltagent/internal": patch
+---
+
+Copy embeddings in in-memory vector search results and deep-clone metadata at the store, get and search boundaries so caller mutations do not corrupt stored memories or change subsequent user-filtered searches. Only selected search results are cloned. Make the internal deep-clone fallback recursive, preserving cycles and shared references when metadata contains functions.
+
+Compatibility note: nested custom class instances in vector metadata are now copied as plain data objects, rather than returned by reference. Their prototypes and prototype methods are not retained, so `instanceof` checks against the original class no longer succeed. Store plain data records (for example, the result of an explicit serializer) and reconstruct application-specific classes after retrieval if needed. Functions retain their existing references in the fallback.
+
+The fallback copies binary storage using the built-in buffer slice methods and preserves own enumerable properties on buffers and views, including cyclic references.

packages/core/src/memory/adapters/vector/in-memory.spec.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import { InMemoryVectorAdapter } from "./in-memory";
+
+describe("InMemoryVectorAdapter search result isolation", () => {
+  it.each(["store", "get", "search"])(
+    "isolates metadata with an overridden buffer slice at the %s boundary",
+    async (operation) => {
+      const adapter = new InMemoryVectorAdapter();
+      const buffer = new ArrayBuffer(4);
+      Object.defineProperty(buffer, "slice", { value: () => buffer, enumerable: true });
+      new Uint8Array(buffer)[0] = 1;
+      await adapter.store("memory", [1, 0], { fn: () => "test", buffer });
+      if (operation === "store") {
+        new Uint8Array(buffer)[0] = 9;
+      } else {
+        const result =
+          operation === "search" ? (await adapter.search([1, 0]))[0] : await adapter.get("memory");
+        new Uint8Array(result?.metadata?.buffer as ArrayBuffer)[0] = 9;
+      }
+      const stored = (await adapter.get("memory"))?.metadata?.buffer as ArrayBuffer;
+      expect(new Uint8Array(stored)[0]).toBe(1);
+    },
+  );
+
+  it.each(["native", "fallback"])(
+    "copies custom class metadata as plain data using the %s clone path",
+    async (mode) => {
+      class CustomMetadata {
+        labels = ["original"];
+        label() {
+          return this.labels[0];
+        }
+      }
+      const adapter = new InMemoryVectorAdapter();
+      const item = new CustomMetadata();
+      await adapter.store("memory", [1, 0], {
+        item,
+        fn: mode === "fallback" ? () => "test" : undefined,
+      });
+      item.labels.push("changed");
+      const fetched = await adapter.get("memory");
+      const [searched] = await adapter.search([1, 0]);
+      for (const result of [fetched, searched]) {
+        const copied = result?.metadata?.item as CustomMetadata;
+        expect(Object.getPrototypeOf(copied)).toBe(Object.prototype);
+        expect(copied).not.toBeInstanceOf(CustomMetadata);
+        expect(copied.label).toBeUndefined();
+        expect(copied.labels).toEqual(["original"]);
+      }
+    },
+  );
+
+  it.each(["store", "get", "search"])(
+    "preserves and isolates binary metadata at the %s boundary",
+    async (operation) => {
+      const adapter = new InMemoryVectorAdapter();
+      const bytes = new Uint8Array([1, 2, 3]);
+      await adapter.store("memory", [1, 0], { fn: () => "test", bytes });
+      if (operation === "store") {
+        bytes[0] = 9;
+      } else {
+        const result =
+          operation === "search" ? (await adapter.search([1, 0]))[0] : await adapter.get("memory");
+        const resultBytes = result?.metadata?.bytes as Uint8Array;
+        expect(resultBytes.byteLength).toBe(3);
+        resultBytes[0] = 9;
+      }
+      const storedBytes = (await adapter.get("memory"))?.metadata?.bytes as Uint8Array;
+      expect(storedBytes.byteLength).toBe(3);
+      expect([...storedBytes]).toEqual([1, 2, 3]);
+    },
+  );
+
+  it.each(["search", "get", "store"])(
+    "isolates nested metadata containing functions at the %s boundary",
+    async (operation) => {
+      const adapter = new InMemoryVectorAdapter();
+      const fn = () => "label";
+      const metadata = { context: { labels: ["original"] }, fn };
+      await adapter.store("memory", [1, 0], metadata);
+
+      if (operation === "store") {
+        metadata.context.labels.push("changed");
+      } else {
+        const result =
+          operation === "search" ? (await adapter.search([1, 0]))[0] : await adapter.get("memory");
+        const context = result?.metadata?.context as typeof metadata.context;
+        context.labels.push("changed");
+      }
+
+      expect((await adapter.get("memory"))?.metadata).toEqual({
+        context: { labels: ["original"] },
+        fn,
+      });
+    },
+  );
+
+  it.each(["search", "get", "store"])(
+    "isolates nested metadata at the %s boundary",
+    async (operation) => {
+      const adapter = new InMemoryVectorAdapter();
+      const metadata = { context: { labels: ["original"] } };
+      await adapter.store("memory", [1, 0], metadata);
+
+      if (operation === "store") {
+        metadata.context.labels.push("changed");
+      } else {
+        const result =
+          operation === "search" ? (await adapter.search([1, 0]))[0] : await adapter.get("memory");
+        const context = result?.metadata?.context as typeof metadata.context;
+        context.labels.push("changed");
+      }
+
+      expect((await adapter.get("memory"))?.metadata).toEqual({
+        context: { labels: ["original"] },
+      });
+    },
+  );
+
+  it("does not let a returned embedding corrupt future similarity searches", async () => {
+    const adapter = new InMemoryVectorAdapter();
+    await adapter.store("matching", [1, 0], { userId: "alice" });
+    await adapter.store("other", [0, 1], { userId: "alice" });
+
+    const [result] = await adapter.search([1, 0]);
+    result.vector[0] = 0;
+    result.vector[1] = 1;
+
+    expect((await adapter.get("matching"))?.vector).toEqual([1, 0]);
+    const [nextResult] = await adapter.search([1, 0]);
+    expect(nextResult.id).toBe("matching");
+    expect(nextResult.score).toBe(1);
+  });
+
+  it("does not let returned metadata change user-scoped retrieval", async () => {
+    const adapter = new InMemoryVectorAdapter();
+    await adapter.store("memory", [1, 0], { userId: "alice" });
+
+    const [result] = await adapter.search([1, 0], { filter: { userId: "alice" } });
+    if (!result.metadata) throw new Error("Expected stored metadata");
+    result.metadata.userId = "bob";
+
+    expect(await adapter.search([1, 0], { filter: { userId: "bob" } })).toEqual([]);
+    expect(await adapter.search([1, 0], { filter: { userId: "alice" } })).toHaveLength(1);
+    expect((await adapter.get("memory"))?.metadata).toEqual({ userId: "alice" });
+  });
+
+  it("supports results without metadata and keeps stored input isolated", async () => {
+    const adapter = new InMemoryVectorAdapter();
+    const vector = [1, 0];
+    await adapter.store("memory", vector);
+    vector[0] = 0;
+
+    const [result] = await adapter.search([1, 0]);
+    expect(result.vector).toEqual([1, 0]);
+    expect(result.metadata).toBeUndefined();
+    expect(result.score).toBe(1);
+  });
+});

packages/core/src/memory/adapters/vector/in-memory.ts

@@ -1,9 +1,11 @@
+import { deepClone } from "@voltagent/internal/utils";
 import { cosineSimilarity } from "../../utils/vector-math";
 import type { SearchResult, VectorAdapter, VectorItem } from "./types";
 
 /**
  * Lightweight in-memory vector database adapter
  * Suitable for development, testing, and small datasets (< 10k vectors)
+ * Metadata is copied as data; custom class prototypes and prototype methods are not retained.
  */
 export class InMemoryVectorAdapter implements VectorAdapter {
   private vectors: Map<string, VectorItem>;
@@ -26,7 +28,7 @@ export class InMemoryVectorAdapter implements VectorAdapter {
     this.vectors.set(id, {
       id,
       vector: [...vector], // Clone to prevent external modifications
-      metadata: metadata ? { ...metadata } : undefined,
+      metadata: metadata ? deepClone(metadata) : undefined,
     });
   }
 
@@ -83,7 +85,11 @@ export class InMemoryVectorAdapter implements VectorAdapter {
     // Sort by score (descending) and limit results
     results.sort((a, b) => b.score - a.score);
 
-    return results.slice(0, limit);
+    return results.slice(0, limit).map((item) => ({
+      ...item,
+      vector: [...item.vector],
+      metadata: item.metadata ? deepClone(item.metadata) : undefined,
+    }));
   }
 
   async delete(id: string): Promise<void> {
@@ -115,7 +121,7 @@ export class InMemoryVectorAdapter implements VectorAdapter {
     return {
       ...item,
       vector: [...item.vector],
-      metadata: item.metadata ? { ...item.metadata } : undefined,
+      metadata: item.metadata ? deepClone(item.metadata) : undefined,
     };
   }
 

packages/internal/src/utils/objects.spec.ts

@@ -1,7 +1,161 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { deepClone, hasKey } from "./objects";
 
 describe("deepClone", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it.each([ArrayBuffer, SharedArrayBuffer])(
+    "ignores an overridden %s slice method in the fallback",
+    (BufferType) => {
+      const buffer = new BufferType(4);
+      Object.defineProperty(buffer, "slice", { value: () => buffer, enumerable: true });
+      new Uint8Array(buffer)[0] = 1;
+      const cloned = deepClone({ fn: () => "test", buffer });
+      expect(cloned.buffer).not.toBe(buffer);
+      new Uint8Array(buffer)[0] = 9;
+      expect(new Uint8Array(cloned.buffer)[0]).toBe(1);
+    },
+  );
+
+  it.each([
+    new ArrayBuffer(4),
+    new SharedArrayBuffer(4),
+    new Uint8Array([1, 2]),
+    new DataView(new ArrayBuffer(4)),
+  ])("preserves custom binary properties and cycles in the fallback (%s)", (binary) => {
+    const value = Object.assign(binary, { tag: { label: "original" }, self: binary });
+    const cloned = deepClone({ fn: () => "test", value });
+    expect(cloned.value.tag).toEqual(value.tag);
+    expect(cloned.value.tag).not.toBe(value.tag);
+    expect(cloned.value.self).toBe(cloned.value);
+    cloned.value.tag.label = "changed";
+    expect(value.tag.label).toBe("original");
+  });
+
+  it("preserves a view referenced by its own backing buffer's custom property", () => {
+    const bytes = new Uint8Array([1, 2]);
+    const buffer = Object.assign(bytes.buffer, { view: bytes });
+    const cloned = deepClone({ fn: () => "test", bytes, buffer });
+    expect(cloned.buffer.view).toBe(cloned.bytes);
+    expect(cloned.bytes.buffer).toBe(cloned.buffer);
+    expect([...cloned.bytes]).toEqual([1, 2]);
+    cloned.bytes[0] = 9;
+    expect(bytes[0]).toBe(1);
+  });
+
+  it("preserves binary data and shared backing buffers in the fallback", () => {
+    const buffer = new ArrayBuffer(8);
+    const bytes = new Uint8Array(buffer, 2, 4);
+    bytes.set([1, 2, 3, 4]);
+    const view = new DataView(buffer, 2, 4);
+    const original = { fn: () => "test", buffer, bytes, view, repeated: bytes };
+    const cloned = deepClone(original);
+    expect(cloned.buffer).toBeInstanceOf(ArrayBuffer);
+    expect(cloned.buffer).not.toBe(buffer);
+    expect(cloned.bytes).toBeInstanceOf(Uint8Array);
+    expect(cloned.bytes.byteLength).toBe(4);
+    expect(cloned.bytes.byteOffset).toBe(2);
+    expect([...cloned.bytes]).toEqual([1, 2, 3, 4]);
+    expect(cloned.bytes.buffer).toBe(cloned.buffer);
+    expect(cloned.view.buffer).toBe(cloned.buffer);
+    expect(cloned.view.byteOffset).toBe(2);
+    expect(cloned.view.getUint8(1)).toBe(2);
+    expect(cloned.repeated).toBe(cloned.bytes);
+    cloned.bytes[0] = 9;
+    expect(cloned.view.getUint8(0)).toBe(9);
+    expect(bytes[0]).toBe(1);
+  });
+
+  it("clones shared buffers and their views without sharing the original storage", () => {
+    const buffer = new SharedArrayBuffer(8);
+    const bytes = new Uint16Array(buffer, 2, 2);
+    bytes.set([123, 456]);
+    const cloned = deepClone({ fn: () => "test", bytes, buffer });
+    expect(cloned.buffer).toBeInstanceOf(SharedArrayBuffer);
+    expect(cloned.buffer).not.toBe(buffer);
+    expect(cloned.bytes.buffer).toBe(cloned.buffer);
+    expect(cloned.bytes.byteOffset).toBe(2);
+    expect([...cloned.bytes]).toEqual([123, 456]);
+    cloned.bytes[0] = 999;
+    expect(bytes[0]).toBe(123);
+  });
+
+  it("supports environments without SharedArrayBuffer during the fallback", () => {
+    vi.stubGlobal("SharedArrayBuffer", undefined);
+    const original = { fn: () => "test", nested: { value: 1 } };
+    const cloned = deepClone(original);
+    expect(cloned.nested).toEqual(original.nested);
+    expect(cloned.nested).not.toBe(original.nested);
+  });
+
+  it("isolates nested data when functions prevent structured cloning", () => {
+    const shared = { labels: ["original"] };
+    const original = { fn: () => "test", first: shared, second: shared };
+    const cloned = deepClone(original);
+    cloned.first.labels.push("changed");
+    expect(original.first.labels).toEqual(["original"]);
+    expect(cloned.second).toBe(cloned.first);
+    expect(cloned.fn).toBe(original.fn);
+  });
+
+  it("preserves cycles when functions prevent structured cloning", () => {
+    const original: { fn: () => string; self?: unknown } = { fn: () => "test" };
+    original.self = original;
+    const cloned = deepClone(original);
+    expect(cloned.self).toBe(cloned);
+    expect(cloned.fn).toBe(original.fn);
+  });
+
+  it("deep-clones arrays and primitives when structuredClone is unavailable", () => {
+    vi.stubGlobal("structuredClone", undefined);
+    const original = [{ nested: [1, null, undefined, false, "value"] }];
+    const cloned = deepClone(original);
+    expect(Array.isArray(cloned)).toBe(true);
+    expect(cloned).toEqual(original);
+    expect(cloned[0].nested).not.toBe(original[0].nested);
+    expect(deepClone(null)).toBeNull();
+    expect(deepClone(undefined)).toBeUndefined();
+    expect(deepClone(42)).toBe(42);
+  });
+
+  it("preserves collection types and shared references in the fallback", () => {
+    const shared = { label: "original" };
+    const original = {
+      fn: () => "test",
+      shared,
+      map: new Map([[shared, shared]]),
+      set: new Set([shared]),
+      date: new Date("2023-01-01"),
+      regex: /test/g,
+    };
+    const cloned = deepClone(original);
+    expect(cloned.map).toBeInstanceOf(Map);
+    expect(cloned.map.get(cloned.shared)).toBe(cloned.shared);
+    expect(cloned.set).toBeInstanceOf(Set);
+    expect(cloned.set.has(cloned.shared)).toBe(true);
+    expect(cloned.date).toEqual(original.date);
+    expect(cloned.date).not.toBe(original.date);
+    expect(cloned.regex).toEqual(original.regex);
+    expect(cloned.regex).not.toBe(original.regex);
+  });
+
+  it("copies an own __proto__ key without changing the fallback object's prototype", () => {
+    const original = { fn: () => "test" };
+    Object.defineProperty(original, "__proto__", {
+      value: { nested: "original" },
+      enumerable: true,
+    });
+    const cloned = deepClone(original);
+    expect(Object.getPrototypeOf(cloned)).toBe(Object.prototype);
+    expect(Object.hasOwn(cloned, "__proto__")).toBe(true);
+    expect(Object.getOwnPropertyDescriptor(cloned, "__proto__")?.value).toEqual({
+      nested: "original",
+    });
+    expect(Object.getOwnPropertyDescriptor(cloned, "__proto__")?.value).not.toBe(
+      Object.getOwnPropertyDescriptor(original, "__proto__")?.value,
+    );
+  });
+
   it("should deep clone a simple object", () => {
     const original = { a: 1, b: "test", c: true };
     const cloned = deepClone(original);
@@ -168,7 +322,7 @@ describe("deepClone", () => {
   });
 
   it("should handle Map objects", () => {
-    const map = new Map([
+    const map = new Map<string, string | { nested: string }>([
       ["key1", "value1"],
       ["key2", { nested: "value2" }],
     ]);