@modusensus/dsh-mneme 0.8.13 → 0.8.15

package/test/serve.test.js

@@ -0,0 +1,196 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createServeRuntime } from "../src/serve.js";
+
+// daemon 装配面锁(test/serve-bin.test.js 另有真子进程 + 多进程共存):
+// in-process 起真 HTTP(port 0,OS 分配),fetch 走 health / 401 / save / search /
+// token 持久化复用全链路。锁的是「daemon 数据面 = api-standalone 同一工厂」这一契约。
+// 基础用例一律 embed:"off"——不碰取件与模型 init,CI 确定性;向量走注入假 embedder。
+
+function tmpDir() {
+  return mkdtempSync(join(tmpdir(), "mneme-serve-"));
+}
+
+/** 确定性 4 维伪嵌入:同词相关、异词近正交,足以让向量路径产生非零命中。 */
+function fakeEmbedder() {
+  return {
+    ready: true,
+    modelHash: "fake-hash-1",
+    dimension: 4,
+    embedSingle: async (text) => {
+      const v = [0, 0, 0, 0];
+      for (let i = 0; i < text.length; i++) v[i % 4] += text.charCodeAt(i) % 7;
+      const n = Math.hypot(v[0], v[1], v[2], v[3]) || 1;
+      return v.map((x) => x / n);
+    }
+  };
+}
+
+async function waitFor(fn, timeoutMs, what) {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr;
+  while (Date.now() < deadline) {
+    try { return await fn(); } catch (err) { lastErr = err; }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error(`timeout waiting for ${what}: ${lastErr?.message ?? lastErr}`);
+}
+
+test("serve: /health 免鉴权,业务路由无 token 401", async () => {
+  const dir = tmpDir();
+  const rt = await createServeRuntime({ memoryDir: dir, port: 0, embed: "off" });
+  await rt.api.ready;
+  try {
+    const base = `http://127.0.0.1:${rt.api.port}`;
+    const health = await fetch(`${base}/health`);
+    assert.equal(health.status, 200);
+    assert.deepEqual(await health.json(), { ok: true });
+
+    const noAuth = await fetch(`${base}/search?q=x`);
+    assert.equal(noAuth.status, 401);
+    assert.deepEqual(await noAuth.json(), { error: "unauthorized" });
+  } finally {
+    rt.dispose();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* win 文件锁偶发 */ }
+  }
+});
+
+test("serve: save → search 走通;token 持久化 kv;二次启动复用同一 token;检索回执落 recall_runs", async () => {
+  const dir = tmpDir();
+  const rt = await createServeRuntime({ memoryDir: dir, port: 0, embed: "off" });
+  await rt.api.ready;
+  const base = `http://127.0.0.1:${rt.api.port}`;
+  const auth = { authorization: `Bearer ${rt.api.token}` };
+
+  // 全新目录:首次启动生成 token
+  assert.equal(rt.tokenExisted, false);
+
+  const save = await fetch(`${base}/memories`, {
+    method: "POST",
+    headers: { ...auth, "content-type": "application/json" },
+    body: JSON.stringify({ type: "preference", title: "serve 冒烟偏好", content: "回复保持简短", importance: 4 })
+  });
+  assert.equal(save.status, 201);
+
+  const search = await fetch(`${base}/search?q=${encodeURIComponent("简短")}`, { headers: auth });
+  assert.equal(search.status, 200);
+  const searchBody = await search.json();
+  assert.ok((searchBody.items ?? []).some((m) => m.title === "serve 冒烟偏好"));
+
+  // token 持久化在 kv external_api(与 DSH 面板/CLI 共用同一凭证通道)
+  assert.equal(rt.settings.getExternalApi().token, rt.api.token);
+
+  // 检索回执:recorder 已接(index.js:294-309 同款),recall_runs 不缺数 —— #363 回帖
+  // 向 bridge 承诺过「第三方检索的复用统计不受影响」,这条就是该承诺的回归锁。
+  const recallRows = rt.store.db.prepare("SELECT COUNT(*) AS n FROM recall_runs").get();
+  assert.ok(recallRows.n >= 1, "recall_runs should record the search above");
+
+  rt.dispose();
+
+  // 二次启动同目录:token 复用不重新生成(firstBoot 提示只在真正首次出现)
+  const rt2 = await createServeRuntime({ memoryDir: dir, port: 0, embed: "off" });
+  await rt2.api.ready;
+  try {
+    assert.equal(rt2.tokenExisted, true);
+    assert.equal(rt2.api.token, rt.api.token);
+  } finally {
+    rt2.dispose();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* 同上 */ }
+  }
+});
+
+test("serve: dispose 后端口可复用(同端口连起两轮不踩 strictPort)", async () => {
+  const dir = tmpDir();
+  const rt = await createServeRuntime({ memoryDir: dir, port: 0, embed: "off" });
+  await rt.api.ready;
+  const port = rt.api.port;
+  // dispose 现为 async:等 server.close 回调(在途请求排干)后再重绑
+  await rt.dispose();
+  // 端口释放可能有内核级迟滞,重试绑定而不是假设立即可用
+  let rebound = null;
+  for (let i = 0; i < 10 && !rebound; i++) {
+    try {
+      const rt2 = await createServeRuntime({ memoryDir: dir, port, embed: "off" });
+      await rt2.api.ready;
+      rebound = rt2;
+    } catch (err) {
+      if (err?.code !== "EADDRINUSE") throw err;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  try {
+    assert.ok(rebound, "port should be rebindable after dispose");
+    assert.equal(rebound.api.port, port);
+  } finally {
+    await rebound?.dispose();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* 同上 */ }
+  }
+});
+
+test("serve: 注入假 embedder → 写入即嵌入,vector 轴接管检索;auto 检索可用", async () => {
+  const dir = tmpDir();
+  const fake = fakeEmbedder();
+  const rt = await createServeRuntime({ memoryDir: dir, port: 0, embed: "off", embedder: fake });
+  await rt.api.ready;
+  try {
+    // 覆盖注入生效:semantic 被绕过,embedder 直接挂 service
+    assert.equal(rt.semantic, null);
+
+    const base = `http://127.0.0.1:${rt.api.port}`;
+    const auth = { authorization: `Bearer ${rt.api.token}` };
+    const save = await fetch(`${base}/memories`, {
+      method: "POST",
+      headers: { ...auth, "content-type": "application/json" },
+      body: JSON.stringify({ type: "project", title: "向量注入冒烟", content: "daemon 侧写入即嵌入", importance: 3 })
+    });
+    assert.equal(save.status, 201);
+
+    // 写入侧嵌入是异步排队的:轮询到 vector 轴命中为止。auto 模式不断言 mode 字段 ——
+    // 标题同词命中时融合合并对象是 keyword 行,上游 mneme 的 auto 报告语义如此
+    // (vector:true 标记只在纯向量来源上保留),那是上游行为,不是 daemon 契约。
+    await waitFor(async () => {
+      const res = await fetch(`${base}/search?q=${encodeURIComponent("向量注入冒烟")}&mode=vector`, { headers: auth });
+      assert.equal(res.status, 200);
+      const body = await res.json();
+      assert.equal(body.mode, "vector", "mode=vector must report the vector axis");
+      assert.ok((body.items ?? []).some((m) => m.title === "向量注入冒烟"));
+      return true;
+    }, 8000, "vector-axis search");
+
+    const autoRes = await fetch(`${base}/search?q=${encodeURIComponent("向量注入冒烟")}&mode=auto`, { headers: auth });
+    assert.equal(autoRes.status, 200);
+    assert.ok(((await autoRes.json()).items ?? []).some((m) => m.title === "向量注入冒烟"));
+
+    // /context 全链路（issue #370）：daemon 与宿主外部访问共用同一工厂，注入
+    // 候选端点一并带出——同一 embedder 句柄喂查询向量，injectCandidates 走通。
+    const ctxRes = await fetch(`${base}/context?q=${encodeURIComponent("向量注入冒烟")}`, { headers: auth });
+    assert.equal(ctxRes.status, 200);
+    const ctxBody = await ctxRes.json();
+    assert.ok((ctxBody.items ?? []).some((m) => m.title === "向量注入冒烟"));
+    // #217 注入分账：injectCandidates 的曝光型访问事件落 recall_runs
+    // （mode='inject'），第三方的注入统计与宿主注入同表同口径。
+    const injectRuns = rt.store.db.prepare("SELECT count(*) AS c FROM recall_runs WHERE mode = 'inject'").get().c;
+    assert.ok(injectRuns >= 1, "injection access must be receipted in recall_runs (#217)");
+  } finally {
+    rt.dispose();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* 同上 */ }
+  }
+});
+
+test("serve: 非法 embed provider 拒装配;embed=off 时 semantic 为 null", async () => {
+  const dir = tmpDir();
+  await assert.rejects(
+    createServeRuntime({ memoryDir: dir, port: 0, embed: "bogus" }),
+    /invalid embed provider/
+  );
+  const rt = await createServeRuntime({ memoryDir: dir, port: 0, embed: "off" });
+  try {
+    assert.equal(rt.semantic, null, "off path must not assemble a semantic pipeline");
+  } finally {
+    rt.dispose();
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* 同上 */ }
+  }
+});

package/test/service-search.test.js

@@ -1,174 +1,174 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { createStore } from "../src/store.js";
-import { createService } from "../src/service.js";
-import { createVectorIndex } from "../src/vector-index.js";
-
-// Mock embedder from the pipeline spec: every query maps to the fixed vector
-// [1,0,0], so vector recall surfaces any row embedded at [1,0,0] (cosine 1)
-// and ignores rows embedded elsewhere (cosine 0).
-const embedder = {
-  embedSingle: async () => [1, 0, 0],
-  embed: async () => [1, 0, 0],
-  schedule: () => {}, // legacy path: scheduleEmbed uses schedule when present, so saveWithDedupe never calls embedSingle here
-  modelHash: "mock#1",
-  dimension: 3
-};
-
-// Mock reranker: scores candidates by their merge order (0,1,2,...) then sorts
-// descending — i.e. it reverses the incoming order. Deterministic, so tests can
-// assert the on/off difference precisely.
-const reranker = {
-  rerank: async (q, cands) =>
-    cands.map((c, i) => ({ id: c.id, score: i })).sort((a, b) => b.score - a.score)
-};
-
-// Real store + service, wired with the mock embedder and a vector index over
-// the same store (the service's vector path prefers vectorIndex when set).
-// The v0.5.0 recall fusion extras (BM25 third path, search-time semantic
-// dedup) are disabled per-test when the assertion targets the legacy blend
-// mechanics — the toy embedder pins every vector hit to the same [1,0,0],
-// which semantic dedup would legitimately collapse.
-function setup({ withEmbedder = true, config = {} } = {}) {
-  const store = createStore(":memory:");
-  const service = createService({ store, mirror: null, config });
-  const vectorIndex = createVectorIndex({ store });
-  if (withEmbedder) {
-    service.setEmbedder(embedder);
-    service.setVectorIndex(vectorIndex);
-  }
-  return { store, service, vectorIndex };
-}
-
-test("hybrid merges vector + keyword recalls and dedups shared memories", async () => {
-  const { service, vectorIndex } = setup();
-  // keyword-only hit: literal query in the title, embedding far from [1,0,0].
-  const kw = service.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门", importance: 5 });
-  vectorIndex.saveEmbedding(kw.memory.id, [0, 1, 0]);
-  // vector-only hit: no literal match, but embedded exactly at the query vector.
-  const vec = service.saveWithDedupe({ type: "project", title: "猫", content: "喜欢猫" });
-  vectorIndex.saveEmbedding(vec.memory.id, [1, 0, 0]);
-  // both: literal match AND embedded at [1,0,0] -> must appear exactly once.
-  const both = service.saveWithDedupe({ type: "decision", title: "量子计算笔记", content: "量子计算实践" });
-  vectorIndex.saveEmbedding(both.memory.id, [1, 0, 0]);
-
-  const rows = await service.searchMemories("量子计算", { mode: "hybrid", topK: 10 });
-  const ids = rows.map((r) => r.id);
-  assert.ok(ids.includes(vec.memory.id), "vector recall surfaces the semantic-only hit");
-  assert.ok(ids.includes(kw.memory.id), "keyword recall surfaces the literal hit");
-  assert.equal(ids.filter((id) => id === both.memory.id).length, 1, "overlap row is deduped to a single entry");
-  assert.ok(rows.some((m) => m.id === both.memory.id && m.vector), "shared row is flagged as a vector hit");
-  assert.equal(ids[0], vec.memory.id, "vector leads the hybrid blend");
-});
-
-test("hybrid blend honors configured vector/keyword weights", async () => {
-  const { service, vectorIndex } = setup();
-  const both = service.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门" });
-  vectorIndex.saveEmbedding(both.memory.id, [1, 0, 0]);
-
-  // Title hit scores 1 * (0.5 + 3/10) = 0.8; vector cosine = 1.0.
-  // Default weights (0.6/0.4) -> 0.6 + 0.32 = 0.92.
-  const defaults = await service.searchMemories("量子计算", { mode: "hybrid", topK: 10 });
-  const d = defaults.find((m) => m.id === both.memory.id);
-  assert.ok(Math.abs(d.score - 0.92) < 1e-9, `default blend ${d.score}`);
-
-  // Even 0.5/0.5 -> 0.5 + 0.4 = 0.9.
-  const store = createStore(":memory:");
-  const tuned = createService({ store, mirror: null, config: { hybridSearchVectorWeight: 0.5, hybridSearchKeywordWeight: 0.5 } });
-  const vi = createVectorIndex({ store });
-  tuned.setEmbedder(embedder);
-  tuned.setVectorIndex(vi);
-  const m = tuned.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门" });
-  vi.saveEmbedding(m.memory.id, [1, 0, 0]);
-  const rows = await tuned.searchMemories("量子计算", { mode: "hybrid", topK: 10 });
-  const t = rows.find((r) => r.id === m.memory.id);
-  assert.ok(Math.abs(t.score - 0.9) < 1e-9, `tuned blend ${t.score}`);
-});
-
-test("auto = keyword leads, vector fills the remaining slots", async () => {
-  const { service, vectorIndex } = setup();
-  const kw = service.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门" });
-  vectorIndex.saveEmbedding(kw.memory.id, [0, 1, 0]);
-  const vec = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫" });
-  vectorIndex.saveEmbedding(vec.memory.id, [1, 0, 0]);
-
-  const rows = await service.searchMemories("量子计算", { mode: "auto", topK: 10 });
-  const ids = rows.map((r) => r.id);
-  assert.ok(ids.includes(kw.memory.id), "keyword hit present");
-  assert.ok(ids.includes(vec.memory.id), "vector fills a free slot");
-  assert.equal(ids[0], kw.memory.id, "keyword stays first in auto mode");
-});
-
-test("reranker on/off: rerank reorders by score, off keeps merge order", async () => {
-  const { service, vectorIndex } = setup();
-  const a = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫", importance: 5 });
-  vectorIndex.saveEmbedding(a.memory.id, [0, 1, 0]);
-  const b = service.saveWithDedupe({ type: "preference", title: "猫猫", content: "猫粮", importance: 3 });
-  vectorIndex.saveEmbedding(b.memory.id, [0, 1, 0]);
-
-  // No reranker: keyword order (importance desc) is preserved.
-  const off = await service.searchMemories("猫", { mode: "keyword", topK: 10 });
-  assert.equal(off[0].id, a.memory.id, "without a reranker merge order is kept");
-
-  // Mock reranker installed: it reverses the merge order by score.
-  service.setReranker(reranker);
-  const on = await service.searchMemories("猫", { mode: "keyword", topK: 10 });
-  assert.equal(on[0].id, b.memory.id, "rerank reorders to the highest score first");
-  assert.equal(typeof on[0].score, "number", "reranked rows carry a score");
-
-  // Clearing the reranker restores merge order.
-  service.setReranker(null);
-  const after = await service.searchMemories("猫", { mode: "keyword", topK: 10 });
-  assert.equal(after[0].id, a.memory.id, "clearing the reranker restores original order");
-});
-
-test("keyword mode never calls the embedder", async () => {
-  let calls = 0;
-  const counting = { ...embedder, embedSingle: async () => { calls++; return [1, 0, 0]; } };
-  const { service, vectorIndex } = setup();
-  service.setEmbedder(counting);
-  service.setVectorIndex(vectorIndex);
-  service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
-
-  const rows = await service.searchMemories("中文", { mode: "keyword", topK: 10 });
-  assert.equal(rows.length, 1);
-  assert.equal(rows[0].title, "语言");
-  assert.equal(calls, 0, "keyword mode must never embed the query");
-});
-
-test("embedder failure degrades to keyword results", async () => {
-  const broken = { ...embedder, embedSingle: async () => { throw new Error("model unavailable"); } };
-  const { service, vectorIndex } = setup();
-  service.setEmbedder(broken);
-  service.setVectorIndex(vectorIndex);
-  service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
-
-  const rows = await service.searchMemories("中文", { mode: "auto", topK: 10 });
-  assert.equal(rows.length, 1, "keyword fallback still returns matches");
-  assert.equal(rows[0].title, "语言");
-  assert.ok(!rows.some((m) => m.vector), "no rows claim the vector path after a failure");
-});
-
-test("vector mode returns semantic hits, and falls back to keyword without an embedder", async () => {
-  const { service, vectorIndex } = setup();
-  const hit = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫" });
-  vectorIndex.saveEmbedding(hit.memory.id, [1, 0, 0]);
-  const rows = await service.searchMemories("猫", { mode: "vector", topK: 10 });
-  assert.ok(rows.some((m) => m.id === hit.memory.id && m.vector), "vector-only recall surfaces the embedded hit");
-
-  // No embedder/vector index: vector mode falls back to literal keyword.
-  const bare = setup({ withEmbedder: false });
-  const m = bare.service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
-  const fallback = await bare.service.searchMemories("中文", { mode: "vector", topK: 10 });
-  assert.ok(fallback.some((x) => x.id === m.memory.id), "keyword fallback when vector is unavailable");
-});
-
-test("topK caps the merged result set", async () => {
-  const { service, vectorIndex } = setup();
-  for (let i = 0; i < 5; i++) {
-    const m = service.saveWithDedupe({ type: "preference", title: `猫${i}`, content: "猫" });
-    vectorIndex.saveEmbedding(m.memory.id, [1, 0, 0]);
-  }
-  const rows = await service.searchMemories("猫", { mode: "auto", topK: 3 });
-  assert.equal(rows.length, 3, "merged list is trimmed to topK");
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createVectorIndex } from "../src/vector-index.js";
+
+// Mock embedder from the pipeline spec: every query maps to the fixed vector
+// [1,0,0], so vector recall surfaces any row embedded at [1,0,0] (cosine 1)
+// and ignores rows embedded elsewhere (cosine 0).
+const embedder = {
+  embedSingle: async () => [1, 0, 0],
+  embed: async () => [1, 0, 0],
+  schedule: () => {}, // legacy path: scheduleEmbed uses schedule when present, so saveWithDedupe never calls embedSingle here
+  modelHash: "mock#1",
+  dimension: 3
+};
+
+// Mock reranker: scores candidates by their merge order (0,1,2,...) then sorts
+// descending — i.e. it reverses the incoming order. Deterministic, so tests can
+// assert the on/off difference precisely.
+const reranker = {
+  rerank: async (q, cands) =>
+    cands.map((c, i) => ({ id: c.id, score: i })).sort((a, b) => b.score - a.score)
+};
+
+// Real store + service, wired with the mock embedder and a vector index over
+// the same store (the service's vector path prefers vectorIndex when set).
+// The v0.5.0 recall fusion extras (BM25 third path, search-time semantic
+// dedup) are disabled per-test when the assertion targets the legacy blend
+// mechanics — the toy embedder pins every vector hit to the same [1,0,0],
+// which semantic dedup would legitimately collapse.
+function setup({ withEmbedder = true, config = {} } = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const vectorIndex = createVectorIndex({ store });
+  if (withEmbedder) {
+    service.setEmbedder(embedder);
+    service.setVectorIndex(vectorIndex);
+  }
+  return { store, service, vectorIndex };
+}
+
+test("hybrid merges vector + keyword recalls and dedups shared memories", async () => {
+  const { service, vectorIndex } = setup();
+  // keyword-only hit: literal query in the title, embedding far from [1,0,0].
+  const kw = service.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门", importance: 5 });
+  vectorIndex.saveEmbedding(kw.memory.id, [0, 1, 0]);
+  // vector-only hit: no literal match, but embedded exactly at the query vector.
+  const vec = service.saveWithDedupe({ type: "project", title: "猫", content: "喜欢猫" });
+  vectorIndex.saveEmbedding(vec.memory.id, [1, 0, 0]);
+  // both: literal match AND embedded at [1,0,0] -> must appear exactly once.
+  const both = service.saveWithDedupe({ type: "decision", title: "量子计算笔记", content: "量子计算实践" });
+  vectorIndex.saveEmbedding(both.memory.id, [1, 0, 0]);
+
+  const rows = await service.searchMemories("量子计算", { mode: "hybrid", topK: 10 });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(vec.memory.id), "vector recall surfaces the semantic-only hit");
+  assert.ok(ids.includes(kw.memory.id), "keyword recall surfaces the literal hit");
+  assert.equal(ids.filter((id) => id === both.memory.id).length, 1, "overlap row is deduped to a single entry");
+  assert.ok(rows.some((m) => m.id === both.memory.id && m.vector), "shared row is flagged as a vector hit");
+  assert.equal(ids[0], vec.memory.id, "vector leads the hybrid blend");
+});
+
+test("hybrid blend honors configured vector/keyword weights", async () => {
+  const { service, vectorIndex } = setup();
+  const both = service.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门" });
+  vectorIndex.saveEmbedding(both.memory.id, [1, 0, 0]);
+
+  // Title hit scores 1 * (0.5 + 3/10) = 0.8; vector cosine = 1.0.
+  // Default weights (0.6/0.4) -> 0.6 + 0.32 = 0.92.
+  const defaults = await service.searchMemories("量子计算", { mode: "hybrid", topK: 10 });
+  const d = defaults.find((m) => m.id === both.memory.id);
+  assert.ok(Math.abs(d.score - 0.92) < 1e-9, `default blend ${d.score}`);
+
+  // Even 0.5/0.5 -> 0.5 + 0.4 = 0.9.
+  const store = createStore(":memory:");
+  const tuned = createService({ store, mirror: null, config: { hybridSearchVectorWeight: 0.5, hybridSearchKeywordWeight: 0.5 } });
+  const vi = createVectorIndex({ store });
+  tuned.setEmbedder(embedder);
+  tuned.setVectorIndex(vi);
+  const m = tuned.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门" });
+  vi.saveEmbedding(m.memory.id, [1, 0, 0]);
+  const rows = await tuned.searchMemories("量子计算", { mode: "hybrid", topK: 10 });
+  const t = rows.find((r) => r.id === m.memory.id);
+  assert.ok(Math.abs(t.score - 0.9) < 1e-9, `tuned blend ${t.score}`);
+});
+
+test("auto = keyword leads, vector fills the remaining slots", async () => {
+  const { service, vectorIndex } = setup();
+  const kw = service.saveWithDedupe({ type: "preference", title: "量子计算", content: "量子计算入门" });
+  vectorIndex.saveEmbedding(kw.memory.id, [0, 1, 0]);
+  const vec = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫" });
+  vectorIndex.saveEmbedding(vec.memory.id, [1, 0, 0]);
+
+  const rows = await service.searchMemories("量子计算", { mode: "auto", topK: 10 });
+  const ids = rows.map((r) => r.id);
+  assert.ok(ids.includes(kw.memory.id), "keyword hit present");
+  assert.ok(ids.includes(vec.memory.id), "vector fills a free slot");
+  assert.equal(ids[0], kw.memory.id, "keyword stays first in auto mode");
+});
+
+test("reranker on/off: rerank reorders by score, off keeps merge order", async () => {
+  const { service, vectorIndex } = setup();
+  const a = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫", importance: 5 });
+  vectorIndex.saveEmbedding(a.memory.id, [0, 1, 0]);
+  const b = service.saveWithDedupe({ type: "preference", title: "猫猫", content: "猫粮", importance: 3 });
+  vectorIndex.saveEmbedding(b.memory.id, [0, 1, 0]);
+
+  // No reranker: keyword order (importance desc) is preserved.
+  const off = await service.searchMemories("猫", { mode: "keyword", topK: 10 });
+  assert.equal(off[0].id, a.memory.id, "without a reranker merge order is kept");
+
+  // Mock reranker installed: it reverses the merge order by score.
+  service.setReranker(reranker);
+  const on = await service.searchMemories("猫", { mode: "keyword", topK: 10 });
+  assert.equal(on[0].id, b.memory.id, "rerank reorders to the highest score first");
+  assert.equal(typeof on[0].score, "number", "reranked rows carry a score");
+
+  // Clearing the reranker restores merge order.
+  service.setReranker(null);
+  const after = await service.searchMemories("猫", { mode: "keyword", topK: 10 });
+  assert.equal(after[0].id, a.memory.id, "clearing the reranker restores original order");
+});
+
+test("keyword mode never calls the embedder", async () => {
+  let calls = 0;
+  const counting = { ...embedder, embedSingle: async () => { calls++; return [1, 0, 0]; } };
+  const { service, vectorIndex } = setup();
+  service.setEmbedder(counting);
+  service.setVectorIndex(vectorIndex);
+  service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
+
+  const rows = await service.searchMemories("中文", { mode: "keyword", topK: 10 });
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].title, "语言");
+  assert.equal(calls, 0, "keyword mode must never embed the query");
+});
+
+test("embedder failure degrades to keyword results", async () => {
+  const broken = { ...embedder, embedSingle: async () => { throw new Error("model unavailable"); } };
+  const { service, vectorIndex } = setup();
+  service.setEmbedder(broken);
+  service.setVectorIndex(vectorIndex);
+  service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
+
+  const rows = await service.searchMemories("中文", { mode: "auto", topK: 10 });
+  assert.equal(rows.length, 1, "keyword fallback still returns matches");
+  assert.equal(rows[0].title, "语言");
+  assert.ok(!rows.some((m) => m.vector), "no rows claim the vector path after a failure");
+});
+
+test("vector mode returns semantic hits, and falls back to keyword without an embedder", async () => {
+  const { service, vectorIndex } = setup();
+  const hit = service.saveWithDedupe({ type: "preference", title: "猫", content: "喜欢猫" });
+  vectorIndex.saveEmbedding(hit.memory.id, [1, 0, 0]);
+  const rows = await service.searchMemories("猫", { mode: "vector", topK: 10 });
+  assert.ok(rows.some((m) => m.id === hit.memory.id && m.vector), "vector-only recall surfaces the embedded hit");
+
+  // No embedder/vector index: vector mode falls back to literal keyword.
+  const bare = setup({ withEmbedder: false });
+  const m = bare.service.saveWithDedupe({ type: "preference", title: "语言", content: "中文交流" });
+  const fallback = await bare.service.searchMemories("中文", { mode: "vector", topK: 10 });
+  assert.ok(fallback.some((x) => x.id === m.memory.id), "keyword fallback when vector is unavailable");
+});
+
+test("topK caps the merged result set", async () => {
+  const { service, vectorIndex } = setup();
+  for (let i = 0; i < 5; i++) {
+    const m = service.saveWithDedupe({ type: "preference", title: `猫${i}`, content: "猫" });
+    vectorIndex.saveEmbedding(m.memory.id, [1, 0, 0]);
+  }
+  const rows = await service.searchMemories("猫", { mode: "auto", topK: 3 });
+  assert.equal(rows.length, 3, "merged list is trimmed to topK");
+});