@modusensus/dsh-mneme 0.2.3 → 0.2.5

package/test/tools.test.js

@@ -0,0 +1,265 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { assertSupportedJsonSchema, validateJsonSchemaValue } from "@deepseek-ai/dsh-tools";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createTools } from "../src/tools.js";
+
+function setup(embedder) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const registered = [];
+  const ctx = {
+    tools: {
+      register(def) {
+        registered.push(def);
+        return () => {};
+      }
+    }
+  };
+  const tools = createTools(ctx, service, {}, embedder);
+  return { store, service, tools, registered };
+}
+
+// Collect authoring-DSL regressions in a compiled schema: property-level
+// `required: true` (must be projected to a top-level required array by
+// defineTool) and `minimum`/`maximum` (outside the enforced subset) are
+// rejected by the real harness, so they must never appear post-compilation.
+function walkSchema(node, path, problems) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) return;
+  if (typeof node.required === "boolean") {
+    problems.push(`${path}.required must be an array (property-level required leaks through)`);
+  }
+  if (Object.hasOwn(node, "minimum") || Object.hasOwn(node, "maximum")) {
+    problems.push(`${path} uses minimum/maximum, which the enforced JSON Schema subset rejects`);
+  }
+  if (node.properties && typeof node.properties === "object") {
+    for (const [key, value] of Object.entries(node.properties)) {
+      walkSchema(value, `${path}.properties.${key}`, problems);
+    }
+  }
+  if (node.items) walkSchema(node.items, `${path}.items`, problems);
+  if (Array.isArray(node.oneOf)) {
+    node.oneOf.forEach((branch, index) => walkSchema(branch, `${path}.oneOf[${index}]`, problems));
+  }
+}
+
+test("registers seven tools with correct names", () => {
+  const { registered } = setup();
+  const names = registered.map((t) => t.name).sort();
+  assert.deepEqual(names, ["memory_archive", "memory_delete", "memory_forget", "memory_list", "memory_save", "memory_search", "memory_update"]);
+});
+
+test("compiled schemas pass the enforced DSH subset (defineTool projection)", () => {
+  const { registered } = setup();
+  assert.equal(registered.length, 7);
+  for (const tool of registered) {
+    assertSupportedJsonSchema(tool.parameters);
+    assertSupportedJsonSchema(tool.output.schema);
+    const problems = [];
+    walkSchema(tool.parameters, `parameters(${tool.name})`, problems);
+    walkSchema(tool.output.schema, `output.schema(${tool.name})`, problems);
+    assert.deepEqual(problems, []);
+  }
+});
+
+test("memory_save executes and stores", async () => {
+  const { registered, store } = setup();
+  const save = registered.find((t) => t.name === "memory_save");
+  const result = await save.execute({ type: "preference", title: "语言", content: "中文", importance: 4 });
+  assert.equal(result.action, "created");
+  assert.equal(store.count(), 1);
+});
+
+test("memory_save merges on matching title within type", async () => {
+  const { registered, store } = setup();
+  const save = registered.find((t) => t.name === "memory_save");
+  const first = await save.execute({ type: "preference", title: "语言", content: "中文" });
+  const second = await save.execute({ type: "preference", title: "语言", content: "简体中文" });
+  assert.equal(first.action, "created");
+  assert.equal(second.action, "merged");
+  assert.equal(first.id, second.id);
+  assert.equal(store.count(), 1);
+});
+
+test("memory_search finds by CJK substring", async () => {
+  const { registered, store, service } = setup();
+  service.saveWithDedupe({ type: "project", title: "记忆插件", content: "SQLite 存储中文记忆", importance: 3 });
+  const search = registered.find((t) => t.name === "memory_search");
+  const result = await search.execute({ query: "中文" });
+  assert.ok(result.items.length >= 1);
+  assert.equal(result.items[0].title, "记忆插件");
+});
+
+test("memory_list filters by type", async () => {
+  const { registered, service } = setup();
+  service.saveWithDedupe({ type: "preference", title: "a", content: "x" });
+  service.saveWithDedupe({ type: "project", title: "b", content: "y" });
+  const list = registered.find((t) => t.name === "memory_list");
+  const result = await list.execute({ type: "project" });
+  assert.equal(result.items.length, 1);
+  assert.equal(result.items[0].title, "b");
+});
+
+test("memory_list total reflects the type filter", async () => {
+  const { registered, service } = setup();
+  service.saveWithDedupe({ type: "preference", title: "a", content: "x" });
+  service.saveWithDedupe({ type: "preference", title: "b", content: "y" });
+  service.saveWithDedupe({ type: "project", title: "c", content: "z" });
+  const list = registered.find((t) => t.name === "memory_list");
+  const projectRes = await list.execute({ type: "project" });
+  assert.equal(projectRes.total, 1);
+  const allRes = await list.execute({});
+  assert.equal(allRes.total, 3);
+});
+
+test("memory_update modifies an entry", async () => {
+  const { registered, service } = setup();
+  const { memory } = service.saveWithDedupe({ type: "decision", title: "t", content: "c" });
+  const update = registered.find((t) => t.name === "memory_update");
+  const result = await update.execute({ id: memory.id, content: "updated" });
+  assert.equal(result.memory.content, "updated");
+});
+
+test("memory_update on missing id rejects", async () => {
+  const { registered } = setup();
+  const update = registered.find((t) => t.name === "memory_update");
+  await assert.rejects(() => update.execute({ id: "missing", content: "x" }), /memory not found/);
+});
+
+test("memory_delete removes an entry", async () => {
+  const { registered, service, store } = setup();
+  const { memory } = service.saveWithDedupe({ type: "decision", title: "t", content: "c" });
+  const del = registered.find((t) => t.name === "memory_delete");
+  await del.execute({ id: memory.id });
+  assert.equal(store.count(), 0);
+});
+
+test("memory_delete on missing id returns deleted:false", async () => {
+  const { registered } = setup();
+  const del = registered.find((t) => t.name === "memory_delete");
+  const result = await del.execute({ id: "missing" });
+  assert.equal(result.deleted, false);
+});
+
+test("memory_forget suppresses injection without deleting", async () => {
+  const { registered, service, store } = setup();
+  const { memory } = service.saveWithDedupe({ type: "project", title: "t", content: "c", importance: 5 });
+  const forget = registered.find((t) => t.name === "memory_forget");
+  const result = await forget.execute({ id: memory.id });
+  assert.equal(result.memory.forgotten, true);
+  assert.equal(store.count(undefined, { includeForgotten: true }), 1, "still stored but suppressed");
+});
+
+test("memory_forget on missing id rejects", async () => {
+  const { registered } = setup();
+  const forget = registered.find((t) => t.name === "memory_forget");
+  await assert.rejects(() => forget.execute({ id: "missing" }), /memory not found/);
+});
+
+test("memory_forget restores with forgotten:false", async () => {
+  const { registered, service } = setup();
+  const { memory } = service.saveWithDedupe({ type: "project", title: "t", content: "c", importance: 5 });
+  const forget = registered.find((t) => t.name === "memory_forget");
+  await forget.execute({ id: memory.id });
+  const restored = await forget.execute({ id: memory.id, forgotten: false });
+  assert.equal(restored.memory.forgotten, false);
+});
+
+test("execution results validate against their declared output schemas", async () => {
+  const { registered, service } = setup();
+  const byName = (n) => registered.find((t) => t.name === n);
+
+  const saved = await byName("memory_save").execute({ type: "decision", title: "x", content: "y", tags: ["k"], source: "test" });
+  assert.deepEqual(validateJsonSchemaValue(byName("memory_save").output.schema, saved), []);
+
+  service.saveWithDedupe({ type: "project", title: "p", content: "q" });
+  const searchRes = await byName("memory_search").execute({ query: "q" });
+  assert.deepEqual(validateJsonSchemaValue(byName("memory_search").output.schema, searchRes), []);
+
+  const listRes = await byName("memory_list").execute({});
+  assert.deepEqual(validateJsonSchemaValue(byName("memory_list").output.schema, listRes), []);
+
+  const updRes = await byName("memory_update").execute({ id: saved.id, content: "z" });
+  assert.deepEqual(validateJsonSchemaValue(byName("memory_update").output.schema, updRes), []);
+
+  const forgetRes = await byName("memory_forget").execute({ id: saved.id });
+  assert.deepEqual(validateJsonSchemaValue(byName("memory_forget").output.schema, forgetRes), []);
+
+  const delRes = await byName("memory_delete").execute({ id: saved.id });
+  assert.deepEqual(validateJsonSchemaValue(byName("memory_delete").output.schema, delRes), []);
+});
+
+test("memory_search semantic mode merges vector recalls", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const registered = [];
+  const ctx = { tools: { register(def) { registered.push(def); return () => {}; } } };
+  const embedder = { embed: async () => [1, 0, 0] };
+  createTools(ctx, service, {}, embedder);
+
+  const v = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫" });
+  store.setEmbedding(v.memory.id, [1, 0, 0]);
+  service.saveWithDedupe({ type: "preference", title: "狗", content: "喜欢狗" });
+
+  const search = registered.find((t) => t.name === "memory_search");
+  // literal query matches only 猫; vector recall also surfaces it via embedding
+  const res = await search.execute({ query: "猫", semantic: true });
+  assert.ok(res.items.some((m) => m.title === "猫"), "vector + keyword merged result contains the hit");
+  // mode=vector keeps keyword items too (dedup merge)
+  const res2 = await search.execute({ query: "猫", mode: "vector" });
+  assert.ok(res2.items.some((m) => m.title === "猫"));
+});
+
+test("memory_search falls back to keyword when embedder unavailable or returns null", async () => {
+  // No embedder passed → plain keyword search still works.
+  const { registered, service } = setup();
+  service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
+  const search = registered.find((t) => t.name === "memory_search");
+  const res = await search.execute({ query: "中文", semantic: true });
+  assert.equal(res.items.length, 1);
+  assert.equal(res.items[0].title, "语言");
+
+  // Embedder that resolves null (provider disabled) → keyword fallback.
+  const store = createStore(":memory:");
+  const service2 = createService({ store, mirror: null, config: {} });
+  const registered2 = [];
+  const ctx = { tools: { register(def) { registered2.push(def); return () => {}; } } };
+  createTools(ctx, service2, {}, { embed: async () => null });
+  service2.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
+  const search2 = registered2.find((t) => t.name === "memory_search");
+  const res2 = await search2.execute({ query: "中文", semantic: true });
+  assert.equal(res2.items.length, 1);
+});
+
+// --- memory_archive (item ⑤: archive + verifiable recovery) ----------------
+
+test("memory_archive hides an entry and memory_unarchive restores it", async () => {
+  const { registered, service } = setup();
+  const { memory: m } = service.saveWithDedupe({ type: "project", title: "t", content: "c" });
+  const archive = registered.find((t) => t.name === "memory_archive");
+  const archived = await archive.execute({ id: m.id });
+  assert.equal(archived.memory.archived, true);
+  assert.ok(!service.list({ type: "project" }).some((x) => x.id === m.id), "archived hidden from default list");
+  const restored = await archive.execute({ id: m.id, archived: false });
+  assert.equal(restored.memory.archived, false);
+  assert.ok(service.list({ type: "project" }).some((x) => x.id === m.id), "restored entry visible again");
+});
+
+test("memory_list include_archived lists hidden entries so they can be restored", async () => {
+  const { registered, service } = setup();
+  const { memory: m } = service.saveWithDedupe({ type: "preference", title: "a", content: "x" });
+  service.setArchived(m.id, true);
+  const list = registered.find((t) => t.name === "memory_list");
+  const hidden = await list.execute({ type: "preference", include_archived: true });
+  assert.ok(hidden.items.some((x) => x.id === m.id), "archived entry discoverable");
+  assert.equal(hidden.total, 1, "total counts the archived entry");
+  const visible = await list.execute({ type: "preference" });
+  assert.ok(!visible.items.some((x) => x.id === m.id), "archived entry hidden by default");
+});
+
+test("memory_archive on missing id rejects", async () => {
+  const { registered } = setup();
+  const archive = registered.find((t) => t.name === "memory_archive");
+  await assert.rejects(() => archive.execute({ id: "missing" }), /memory not found/);
+});

package/test/vector-index.test.js

@@ -0,0 +1,205 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// Focused unit tests for the vector-index layer: model fingerprint (drift
+// detection), embedding save/search/delete, incremental rebuild, and stats.
+// The store is used directly (createStore(":memory:")) since vector-index is a
+// thin layer over the store's embedding column + vector_meta table.
+
+function setup() {
+  const store = createStore(":memory:");
+  const vectorIndex = createVectorIndex({ store });
+  return { store, vectorIndex };
+}
+
+// Add a memory via the store and (optionally) set its embedding vector.
+function addMemory(store, { title, content, type = "preference", vector }) {
+  const memory = store.save({ type, title, content, tags: [], importance: 3 });
+  if (vector) store.setEmbedding(memory.id, vector);
+  return memory;
+}
+
+// Embedder mock for rebuildIndex. NOTE: the rebuild guard checks
+// `typeof embedder.embed === "function"` while the inner loop calls
+// `embedder.embedSingle` — so a rebuild-ready mock must provide both.
+function rebuildEmbedder({ vector = [1, 0, 0], modelHash = "mock#rebuild", dimension = 3 } = {}) {
+  return {
+    embed: async (texts) => texts.map(() => vector),
+    embedSingle: async () => vector,
+    modelHash,
+    dimension
+  };
+}
+
+test("modelHash drift detection: markModel records and replaces the fingerprint", () => {
+  const { vectorIndex } = setup();
+
+  // No model recorded yet.
+  assert.equal(vectorIndex.modelHash(), undefined);
+  assert.equal(vectorIndex.dimension(), undefined);
+
+  vectorIndex.markModel("model#v1", 3);
+  assert.equal(vectorIndex.modelHash(), "model#v1");
+  assert.equal(vectorIndex.dimension(), 3);
+
+  // Switching to a different model updates the fingerprint (drift signal).
+  vectorIndex.markModel("model#v2", 5);
+  assert.equal(vectorIndex.modelHash(), "model#v2");
+  assert.equal(vectorIndex.dimension(), 5);
+});
+
+test("saveEmbedding + search recall with cosine ordering", () => {
+  const { store, vectorIndex } = setup();
+  // Three memories with distinct 3-d vectors.
+  const a = addMemory(store, { title: "猫", content: "喜欢猫", vector: [1, 0, 0] });
+  const b = addMemory(store, { title: "狗", content: "喜欢狗", vector: [0, 1, 0] });
+  const c = addMemory(store, { title: "虎", content: "喜欢老虎", vector: [0.5, 0.5, 0] });
+
+  const hits = vectorIndex.search([1, 0, 0], { limit: 10, threshold: 0 });
+  assert.equal(hits.length, 3, "all embedded rows participate");
+  assert.equal(hits[0].id, a.id, "exact vector match ranks first");
+  assert.ok(Math.abs(hits[0].score - 1) < 1e-9, "self cosine is 1");
+
+  // Cosine ordering: [1,0,0] vs c = 0.5/sqrt(0.5) ≈ 0.7071 > vs b = 0.
+  assert.equal(hits[1].id, c.id, "higher cosine ranks before orthogonal");
+  assert.ok(Math.abs(hits[1].score - 0.5 / Math.sqrt(0.5)) < 1e-9, "c score is dot/sqrt(nb)");
+  assert.equal(hits[2].id, b.id, "orthogonal vector ranks last");
+  assert.ok(Math.abs(hits[2].score) < 1e-9, "orthogonal cosine is 0");
+
+  // threshold filters low-similarity rows out.
+  const filtered = vectorIndex.search([1, 0, 0], { limit: 10, threshold: 0.9 });
+  assert.deepEqual(filtered.map((h) => h.id), [a.id], "only the 1.0 match passes threshold 0.9");
+});
+
+test("deleteEmbedding clears the cached vector; getEmbedding reflects it", () => {
+  const { store, vectorIndex } = setup();
+  const m = addMemory(store, { title: "备忘", content: "临时内容", vector: [1, 0, 0] });
+
+  assert.deepEqual(vectorIndex.getEmbedding(m.id), [1, 0, 0]);
+
+  vectorIndex.deleteEmbedding(m.id);
+  assert.equal(vectorIndex.getEmbedding(m.id), undefined, "deleted embedding reads as undefined");
+  assert.equal(vectorIndex.getStats().embeddedCount, 0, "count drops after delete");
+
+  // Save again restores it.
+  vectorIndex.saveEmbedding(m.id, [0, 0, 1]);
+  assert.deepEqual(vectorIndex.getEmbedding(m.id), [0, 0, 1]);
+});
+
+test("rebuildIndex embeds only rows missing an embedding and marks the model", async () => {
+  const { store, vectorIndex } = setup();
+  // One memory already embedded, two missing.
+  addMemory(store, { title: "已有向量", content: "A", vector: [0, 1, 0] });
+  addMemory(store, { title: "缺向量1", content: "B" });
+  addMemory(store, { title: "缺向量2", content: "C" });
+  assert.equal(vectorIndex.getStats().embeddedCount, 1);
+
+  const seen = [];
+  const embedder = rebuildEmbedder({ vector: [1, 0, 0], modelHash: "mock#rebuild", dimension: 3 });
+  embedder.embedSingle = async (text) => { seen.push(text); return [1, 0, 0]; };
+
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+  assert.equal(result.indexed, 2, "two missing embeddings written");
+  assert.equal(result.skipped, 0);
+  assert.equal(vectorIndex.getStats().embeddedCount, 3, "all rows embedded after rebuild");
+  assert.equal(seen.length, 2, "embedSingle called once per missing row");
+
+  // Rebuild is a no-op once everything is embedded.
+  const again = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+  assert.equal(again.indexed, 0);
+  assert.equal(again.skipped, 0);
+
+  // Model fingerprint marked from the rebuild embedder.
+  assert.equal(vectorIndex.modelHash(), "mock#rebuild");
+  assert.equal(vectorIndex.dimension(), 3);
+});
+
+test("rebuildIndex handles a throwing embedder without failing the batch", async () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "好行", content: "A" });
+  addMemory(store, { title: "坏行", content: "B" });
+  addMemory(store, { title: "空行", content: "C" });
+
+  let calls = 0;
+  const embedder = rebuildEmbedder({ modelHash: "mock#throwing" });
+  embedder.embedSingle = async () => {
+    calls++;
+    if (calls === 2) throw new Error("model unavailable");
+    if (calls === 3) return []; // empty vector → not counted
+    return [1, 0, 0];
+  };
+
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+  assert.equal(result.indexed, 1, "only the successful row is indexed");
+  assert.equal(result.skipped, 2, "thrown + empty rows count as skipped");
+  assert.equal(vectorIndex.getStats().embeddedCount, 1);
+});
+
+test("rebuildIndex guard: embedder without embedSingle() is ignored", async () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "缺向量", content: "A" });
+  const bare = { embed: async () => [1, 0, 0], modelHash: "mock#bare", dimension: 3 };
+  const result = await vectorIndex.rebuildIndex(bare, { limit: 100 });
+  assert.deepEqual(result, { indexed: 0, skipped: 0 }, "guard returns early when embedSingle() is missing");
+  assert.equal(vectorIndex.modelHash(), undefined, "no model marked");
+});
+
+test("rebuildIndex works with embedSingle-only embedder", async () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "缺向量", content: "A" });
+  const single = { embedSingle: async () => [1, 0, 0], modelHash: "mock#single", dimension: 3 };
+  const result = await vectorIndex.rebuildIndex(single, { limit: 100 });
+  assert.ok(result.indexed >= 1, "embedSingle-only embedder should rebuild");
+  assert.equal(vectorIndex.modelHash(), "mock#single", "model marked after successful rebuild");
+});
+
+test("getStats reports embedded/total counts and model metadata", () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "甲", content: "1", vector: [1, 0, 0] });
+  addMemory(store, { title: "乙", content: "2", vector: [0, 1, 0] });
+  addMemory(store, { title: "丙", content: "3" });
+
+  let stats = vectorIndex.getStats();
+  assert.equal(stats.embeddedCount, 2);
+  assert.equal(stats.totalCount, 3);
+  assert.equal(stats.modelHash, undefined);
+  assert.equal(stats.dimension, undefined);
+  assert.equal(stats.updatedAt, undefined);
+
+  vectorIndex.markModel("model#v3", 4);
+  stats = vectorIndex.getStats();
+  assert.equal(stats.modelHash, "model#v3");
+  assert.equal(stats.dimension, 4);
+  assert.ok(typeof stats.updatedAt === "string" && stats.updatedAt.length > 0, "updatedAt set");
+});
+
+test("incremental update: saveEmbedding overwrites the cached vector and search reflects it", () => {
+  const { store, vectorIndex } = setup();
+  const a = addMemory(store, { title: "主题", content: "A", vector: [1, 0, 0] });
+  const b = addMemory(store, { title: "对照", content: "B", vector: [0, 1, 0] });
+
+  // Before overwrite: query for B's vector ranks b first.
+  let hits = vectorIndex.search([0, 1, 0], { limit: 10, threshold: 0 });
+  assert.equal(hits[0].id, b.id);
+
+  // Overwrite a's vector so it now points at b's direction.
+  vectorIndex.saveEmbedding(a.id, [0, 1, 0]);
+  assert.deepEqual(vectorIndex.getEmbedding(a.id), [0, 1, 0]);
+  assert.equal(vectorIndex.getStats().embeddedCount, 2, "overwrite does not change the count");
+
+  hits = vectorIndex.search([0, 1, 0], { limit: 10, threshold: 0 });
+  assert.equal(hits.length, 2);
+  // Tie: identical vectors both score 1; ordering between them is stable by id — we
+  // only assert the overwritten row now participates with a full score.
+  const aHit = hits.find((h) => h.id === a.id);
+  assert.ok(Math.abs(aHit.score - 1) < 1e-9, "overwritten vector scores 1 against the query");
+});
+
+test("search returns empty when nothing is embedded", () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "无向量", content: "A" });
+  addMemory(store, { title: "也无向量", content: "B" });
+  assert.deepEqual(vectorIndex.search([1, 0, 0], { limit: 10 }), []);
+});