@modusensus/dsh-mneme 0.7.31 → 0.8.0

package/test/runtime-verify.test.js

@@ -0,0 +1,214 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_PROBE_TEXTS, defaultEngine, verifyFunctional, verifyPayload } from "../src/runtime/verify.js";
+import { TRANSFORMERS_ENTRY } from "../src/runtime/layout.js";
+import { pathToFileURL } from "node:url";
+
+// 验证三件套（issue #131 / PR-A）。重点不是「能跑通」，而是「坏的那几种能被抓住」：
+// 结构对但原生二进制与本机不匹配、返回非归一化向量、向量退化、加载直接抛——
+// 这些都必须变成一条可读的失败结论，而不是让调用方拿到一个假的 ok。
+
+/** 造一个结构上合法的 payload（只有形状，没有真东西）。 */
+function makePayload({ platform = "win32", arch = "x64", withEntry = true } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "mneme-verify-"));
+  const write = (rel, body) => {
+    const full = join(dir, rel);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, body);
+  };
+  for (const name of ["@huggingface/transformers", "onnxruntime-node", "sharp"]) {
+    write(join("node_modules", name, "package.json"), JSON.stringify({ name, version: name === "@huggingface/transformers" ? "4.2.0" : "1.0.0" }));
+  }
+  if (withEntry) write(TRANSFORMERS_ENTRY, "export const x = 1;\n");
+  mkdirSync(join(dir, "node_modules", "onnxruntime-node", "bin", "napi-v6", platform, arch), { recursive: true });
+  return dir;
+}
+
+/** 归一化的假向量：`rows` 行，每行 dim 维，方向由 seed 决定。 */
+function fakeRows(rows, dim, seed = 0) {
+  return Array.from({ length: rows }, (_, r) => {
+    const v = Array.from({ length: dim }, (_, i) => Math.sin((i + 1) * (r + 1 + seed)));
+    const length = Math.hypot(...v);
+    return v.map((x) => x / length);
+  });
+}
+
+/** 注入一个「什么都能返回」的 engine。 */
+function engineReturning(value) {
+  return async () => async () => value;
+}
+
+test("功能验证：正常的向量通过，并报出维度与耗时", async () => {
+  const result = await verifyFunctional("/whatever", { engine: engineReturning(fakeRows(2, 512)) });
+  assert.equal(result.ok, true, result.reason);
+  assert.equal(result.dim, 512);
+  assert.equal(result.rows, 2);
+  assert.ok(result.elapsedMs >= 0);
+});
+
+test("功能验证：行数不符要报出来（而不是只取第一行当作通过）", async () => {
+  const result = await verifyFunctional("/whatever", { engine: engineReturning(fakeRows(1, 512)) });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /返回行数不符/);
+});
+
+test("功能验证：非归一化向量要报出来（说明 normalize 没生效）", async () => {
+  const rows = fakeRows(2, 8).map((row) => row.map((x) => x * 3));
+  const result = await verifyFunctional("/whatever", { engine: engineReturning(rows) });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /不是 L2 归一化/);
+});
+
+test("功能验证：向量退化成同一方向要报出来", async () => {
+  const one = fakeRows(1, 16)[0];
+  const result = await verifyFunctional("/whatever", { engine: engineReturning([one, one]) });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /嵌入退化/);
+});
+
+test("功能验证：加载失败与推理失败分别给出不同措辞", async () => {
+  const loadFail = await verifyFunctional("/whatever", {
+    engine: async () => {
+      throw new Error("Cannot find package 'onnxruntime-node'");
+    }
+  });
+  assert.equal(loadFail.ok, false);
+  assert.match(loadFail.reason, /加载运行时失败/);
+  assert.match(loadFail.reason, /onnxruntime-node/);
+
+  const embedFail = await verifyFunctional("/whatever", {
+    engine: async () => async () => {
+      throw new Error("boom");
+    }
+  });
+  assert.equal(embedFail.ok, false);
+  assert.match(embedFail.reason, /推理失败/);
+});
+
+test("功能验证：返回空向量要报出来，而不是当成 dim=0 通过", async () => {
+  const result = await verifyFunctional("/whatever", { engine: engineReturning([[], []]) });
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /空向量/);
+});
+
+test("三件套：结构不过就不再做功能验证（省掉一次无谓的加载）", async () => {
+  const dir = makePayload({ withEntry: false });
+  let engineCalled = false;
+  const result = await verifyPayload(dir, {
+    platform: "win32",
+    arch: "x64",
+    engine: async () => {
+      engineCalled = true;
+      return async () => fakeRows(2, 8);
+    }
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.functional.ok, false);
+  assert.match(result.functional.reason, /跳过功能验证/);
+  assert.equal(engineCalled, false);
+});
+
+test("三件套：结构 + 功能都过、完整性缺失时如实标 unverified 且不判定失败", async () => {
+  const dir = makePayload();
+  const result = await verifyPayload(dir, {
+    platform: "win32",
+    arch: "x64",
+    engine: engineReturning(fakeRows(2, 8))
+  });
+  assert.equal(result.ok, true);
+  assert.equal(result.integrity.status, "unverified");
+  assert.equal(result.integrity.ok, true);
+  assert.equal(result.version, "4.2.0");
+});
+
+test("三件套：--strict 场景下哈希不匹配即整体不通过", async () => {
+  const dir = makePayload();
+  const matched = await verifyPayload(dir, {
+    platform: "win32",
+    arch: "x64",
+    engine: engineReturning(fakeRows(2, 8)),
+    integrity: { status: "sha512-matched", detail: "tarball 比对通过" }
+  });
+  assert.equal(matched.ok, true);
+  assert.equal(matched.integrity.status, "sha512-matched");
+
+  const mismatch = await verifyPayload(dir, {
+    platform: "win32",
+    arch: "x64",
+    engine: engineReturning(fakeRows(2, 8)),
+    integrity: { status: "sha512-mismatch", detail: "与钉死的哈希不一致" }
+  });
+  assert.equal(mismatch.ok, false);
+  assert.equal(mismatch.structural.ok, true, "结构仍然是对的，失败来自完整性");
+  assert.equal(mismatch.functional.ok, true);
+});
+
+test("假通过防线 ①：行不是数组时返回失败，而不是抛异常", async () => {
+  // 契约是「任何失败都返回结果对象，不抛」；非数组行会让 .length/.some 直接抛。
+  const dir = makePayload();
+  const result = await verifyPayload(dir, {
+    platform: "win32",
+    arch: "x64",
+    engine: engineReturning([null, null])
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.functional.reason, /不是数组/);
+});
+
+test("假通过防线 ②：非有限数值必须判失败（NaN 的比较恒为 false，会静默通过）", async () => {
+  const dir = makePayload();
+  for (const bad of [[NaN, 0], [Infinity, 0], ["0.5", "0.5"]]) {
+    const result = await verifyPayload(dir, {
+      platform: "win32",
+      arch: "x64",
+      engine: engineReturning([bad, [0, 0]])
+    });
+    assert.equal(result.ok, false, `含 ${JSON.stringify(bad)} 的向量不该被判通过`);
+    assert.match(result.functional.reason, /非有限数值/);
+  }
+});
+
+test("默认 engine 是导出的函数，且探针文本固定（改它等于改验收标准）", () => {
+  assert.equal(typeof defaultEngine, "function");
+  assert.deepEqual(DEFAULT_PROBE_TEXTS, ["猫咪喜欢晒太阳", "the quick brown fox"]);
+});
+
+// ── defaultEngine：注入假 transformers 模块，钉住「真 import + 行切分」的契约 ──
+
+/** 造一个假 transformers 入口：export env + pipeline，把收到的参数记到 globalThis。 */
+function fakeEntry(dims) {
+  const dir = mkdtempSync(join(tmpdir(), "mneme-engine-"));
+  const entry = join(dir, "entry.mjs");
+  writeFileSync(entry, `
+export const env = {};
+export async function pipeline(kind, model, opts) {
+  globalThis.__engineSeen = { kind, model, opts, cacheDir: env.cacheDir, remote: env.allowRemoteModels };
+  const d = ${JSON.stringify(dims)};
+  const data = Float32Array.from({ length: d[0] * d[1] }, (_, i) => i + 1);
+  return async () => ({ dims: d, data });
+}
+`);
+  return pathToFileURL(entry).href;
+}
+
+test("defaultEngine: 假 transformers 入口可驱动嵌入，并按输出维度做行切分", async () => {
+  const entry = fakeEntry([2, 4]);
+  const embed = await defaultEngine(entry, { cacheDir: "/tmp/mneme-cache" });
+  const rows = await embed(["猫咪", "fox"]);
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows[0], [1, 2, 3, 4]);
+  assert.deepEqual(rows[1], [5, 6, 7, 8]);
+  // 缓存目录与离线开关必须落到 env：验证过程绝不能偷偷下载模型。
+  assert.equal(globalThis.__engineSeen.cacheDir, "/tmp/mneme-cache");
+  assert.equal(globalThis.__engineSeen.remote, false);
+  assert.equal(globalThis.__engineSeen.kind, "feature-extraction");
+});
+
+test("defaultEngine: 输出宽度为 0 时明确抛错（防止调用方死循环）", async () => {
+  const entry = fakeEntry([2, 0]);
+  const embed = await defaultEngine(entry, {});
+  await assert.rejects(() => embed(["x"]), /维度不可用/);
+});

package/test/scope-retrieval.test.js

@@ -0,0 +1,197 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createTools } from "../src/tools.js";
+
+// v0.8.0 A2（issue #17）：检索加权 + occurred_at 时间过滤。
+// 当前 scope 加成、他 scope 降权但保留可见；occurred 窗在 store.list/count 与
+// 搜索融合池两处同口径（COALESCE 回退 created_at）。
+
+test("store.list/count filter by occurred_at with created_at fallback", () => {
+  const store = createStore(":memory:");
+  store.save({ type: "project", title: "aug", content: "x", occurred_at: "2026-08-15T00:00:00Z" });
+  store.save({ type: "project", title: "sep", content: "x", occurred_at: "2026-09-01T00:00:00Z" });
+  // 未标注 occurred_at → 回退 created_at（今天，2026-09-13）参与比较。
+  store.save({ type: "project", title: "legacy", content: "x" });
+
+  const aug = store.list({ occurredFrom: "2026-08-01", occurredTo: "2026-08-31" });
+  assert.deepEqual(aug.map((m) => m.title), ["aug"]);
+  assert.equal(store.count("project", { occurredFrom: "2026-08-01", occurredTo: "2026-08-31" }), 1);
+
+  // 回退方向：窗口从「今天」起（日期从刚写入行的 created_at 推导，不依赖
+  // 测试机时钟/时区），未标注行靠 created_at 落入；sep 的 occurred 是月初，
+  // 在窗口外。
+  const legacyRow = store.list({}).find((m) => m.title === "legacy");
+  const today = legacyRow.created_at.slice(0, 10);
+  const sinceToday = store.list({ occurredFrom: today }).map((m) => m.title);
+  assert.deepEqual(sinceToday, ["legacy"]);
+
+  // 非法边界值被忽略（不进 WHERE），三行都在。
+  assert.equal(store.list({ occurredFrom: "garbage", occurredTo: 42 }).length, 3);
+});
+
+test("service.list/count pass the occurred window through", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  store.save({ type: "decision", title: "old", content: "x", occurred_at: "2026-01-10T00:00:00Z" });
+  store.save({ type: "decision", title: "new", content: "x", occurred_at: "2026-06-10T00:00:00Z" });
+  const rows = service.list({ occurredFrom: "2026-06-01" });
+  assert.deepEqual(rows.map((m) => m.title), ["new"]);
+  assert.equal(service.count("decision", { occurredFrom: "2026-06-01" }), 1);
+});
+
+test("searchMemories applies the occurred window to the fused pool", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  store.save({ type: "project", title: "needle aug", content: "hit", occurred_at: "2026-08-15T00:00:00Z" });
+  store.save({ type: "project", title: "needle legacy", content: "hit" });
+
+  const all = await service.searchMemories("needle", { mode: "keyword" });
+  assert.equal(all.length, 2);
+
+  const windowed = await service.searchMemories("needle", {
+    mode: "keyword",
+    occurredFrom: "2026-08-01",
+    occurredTo: "2026-08-31"
+  });
+  assert.deepEqual(windowed.map((m) => m.title), ["needle aug"]);
+});
+
+test("searchMemories scope weighting: current scope boosted, foreign demoted but visible", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: { scopeEnabled: true } });
+  // 打分构造（scoreKeyword：标题命中 1 × 0.8，正文命中 0.6 × 0.8）：
+  // 无加权时 alpha (0.8) 排在 beta (0.48) 前。
+  store.save({ type: "project", title: "alpha needle", content: "x", agent_scope: "coder" });
+  store.save({ type: "project", title: "beta", content: "needle", agent_scope: "novelist" });
+
+  // 当前会话是 novelist：beta 命中 ×1.25=0.6，alpha 他 scope ×0.5=0.4 → 翻转，
+  // 但 alpha 仍可见（降权不是过滤）。
+  const weighted = await service.searchMemories("needle", {
+    mode: "keyword",
+    scope: { agent_scope: "novelist", workspace_scope: null }
+  });
+  assert.deepEqual(weighted.map((m) => m.title), ["beta", "alpha needle"]);
+
+  // 无 scope 传参 → 不动分，保持基线排序。
+  const neutral = await service.searchMemories("needle", { mode: "keyword" });
+  assert.deepEqual(neutral.map((m) => m.title), ["alpha needle", "beta"]);
+
+  // scope 全 NULL（解析不出）→ 同样不动分。
+  const nullScope = await service.searchMemories("needle", {
+    mode: "keyword",
+    scope: { agent_scope: null, workspace_scope: null }
+  });
+  assert.deepEqual(nullScope.map((m) => m.title), ["alpha needle", "beta"]);
+});
+
+test("searchMemories weighting is off entirely when the flag is off", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  store.save({ type: "project", title: "alpha needle", content: "x", agent_scope: "coder" });
+  store.save({ type: "project", title: "beta", content: "needle", agent_scope: "novelist" });
+  const rows = await service.searchMemories("needle", {
+    mode: "keyword",
+    scope: { agent_scope: "novelist", workspace_scope: null }
+  });
+  assert.deepEqual(rows.map((m) => m.title), ["alpha needle", "beta"]);
+});
+
+test("unscoped rows rank with matched rows under weighting (never suppressed)", async () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: { scopeEnabled: true } });
+  store.save({ type: "project", title: "global needle", content: "x" });
+  store.save({ type: "project", title: "foreign", content: "needle", agent_scope: "someone-else" });
+  const rows = await service.searchMemories("needle", {
+    mode: "keyword",
+    scope: { agent_scope: "me", workspace_scope: null }
+  });
+  // 未标注行与命中行同列吃 BOOST（×1.25），foreign 行 ×0.5——不被任何会话压掉。
+  assert.deepEqual(rows.map((m) => m.title), ["global needle", "foreign"]);
+});
+
+function setupTools(config) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const registered = [];
+  createTools(
+    { tools: { register(def) { registered.push(def); return () => {}; } } },
+    service,
+    config
+  );
+  const pick = (name) => registered.find((def) => def.name === name);
+  return { store, service, pick };
+}
+
+async function runHandler(def, args, exec) {
+  const handler = def.execute.bind(def);
+  return handler(args, exec);
+}
+
+test("toApiList surfaces scope annotation and occurred_at", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  store.save({
+    type: "pitfall",
+    title: "stamped",
+    content: "x",
+    agent_scope: "coder",
+    workspace_scope: "D:\\proj",
+    sensitivity: "personal",
+    occurred_at: "2026-09-12T08:00:00Z"
+  });
+  const [row] = service.toApiList([store.getById(
+    service.list({}).find((m) => m.title === "stamped").id
+  )]);
+  assert.equal(row.agent_scope, "coder");
+  assert.equal(row.workspace_scope, "D:\\proj");
+  assert.equal(row.sensitivity, "personal");
+  assert.equal(row.occurred_at, "2026-09-12T08:00:00.000Z");
+  // 未标注行四字段为 undefined（JSON 序列化时省略）。
+  store.save({ type: "pitfall", title: "plain", content: "x" });
+  const [plain] = service.toApiList([service.list({}).find((m) => m.title === "plain")]);
+  assert.equal(plain.agent_scope, undefined);
+  assert.equal(plain.occurred_at, undefined);
+});
+
+test("memory_search passes the session scope and occurred window through", async () => {
+  const { store, pick } = setupTools({ scopeEnabled: true });
+  store.save({ type: "project", title: "alpha needle", content: "x", agent_scope: "coder" });
+  store.save({
+    type: "project", title: "beta", content: "needle", agent_scope: "novelist",
+    occurred_at: "2026-08-15T00:00:00Z"
+  });
+  const search = pick("memory_search");
+  const exec = { agent: { session: { id: "s1", header: { agentPreset: "novelist", cwd: "D:\\p" } } } };
+  const args = { query: "needle", occurred_from: "2026-08-01", occurred_to: "2026-08-31" };
+  const out = await runHandler(search, args, exec);
+  // 窗口内只剩 beta；其 agent_scope 命中当前会话（novelist），标注随行透出。
+  assert.equal(out.items.length, 1);
+  assert.equal(out.items[0].title, "beta");
+  assert.equal(out.items[0].agent_scope, "novelist");
+  assert.equal(out.items[0].occurred_at, "2026-08-15T00:00:00.000Z");
+});
+
+test("memory_list filters by the occurred window and keeps total consistent", async () => {
+  const { store, pick } = setupTools({});
+  store.save({ type: "decision", title: "old", content: "x", occurred_at: "2026-01-10T00:00:00Z" });
+  store.save({ type: "decision", title: "new", content: "x", occurred_at: "2026-06-10T00:00:00Z" });
+  const list = pick("memory_list");
+  const args = { type: "decision", occurred_from: "2026-06-01" };
+  const out = await runHandler(list, args, undefined);
+  assert.deepEqual(out.items.map((m) => m.title), ["new"]);
+  assert.equal(out.total, 1);
+});
+
+test("memory_get returns scope annotation and occurred_at", async () => {
+  const { store, pick } = setupTools({});
+  const saved = store.save({
+    type: "pitfall", title: "t", content: "c",
+    agent_scope: "coder", occurred_at: "2026-09-12T08:00:00Z"
+  });
+  const get = pick("memory_get");
+  const out = await runHandler(get, { id: saved.id }, undefined);
+  assert.equal(out.memory.agent_scope, "coder");
+  assert.equal(out.memory.occurred_at, "2026-09-12T08:00:00.000Z");
+});

package/test/scope-storage.test.js

@@ -0,0 +1,247 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createTools } from "../src/tools.js";
+import { createScopeResolver } from "../src/scope.js";
+
+// v0.8.0 A1（issue #17）：scope 隔离存储层。
+// 四列可空（agent_scope/workspace_scope/sensitivity/occurred_at）、迁移纯增量
+// 不带 DEFAULT；写入标注走 scopeEnabled 门控；去重键扩展 (type, title, scope…)。
+
+test("migration adds four nullable scope columns without defaults", () => {
+  const store = createStore(":memory:");
+  const cols = store.db.prepare("PRAGMA table_info(memories)").all();
+  for (const name of ["agent_scope", "workspace_scope", "sensitivity", "occurred_at"]) {
+    const col = cols.find((c) => c.name === name);
+    assert.ok(col, `column ${name} should exist`);
+    assert.equal(col.notnull, 0, `${name} must be nullable`);
+    assert.equal(col.dflt_value, null, `${name} must not carry a DEFAULT (存量零重写)`);
+  }
+});
+
+test("rows written without scope fields read back unscoped (legacy semantics)", () => {
+  const store = createStore(":memory:");
+  const row = store.save({ type: "project", title: "legacy shape", content: "body" });
+  assert.equal(row.agent_scope, undefined);
+  assert.equal(row.workspace_scope, undefined);
+  assert.equal(row.sensitivity, undefined);
+  assert.equal(row.occurred_at, undefined);
+});
+
+test("store.save persists and normalizes scope fields; dirty input lands as NULL", () => {
+  const store = createStore(":memory:");
+  const kept = store.save({
+    type: "project",
+    title: "scoped",
+    content: "c",
+    agent_scope: "  coder-agent  ",
+    workspace_scope: "D:\\proj",
+    sensitivity: "personal",
+    occurred_at: "2026-09-13T10:00:00+08:00"
+  });
+  assert.equal(kept.agent_scope, "coder-agent");
+  assert.equal(kept.workspace_scope, "D:\\proj");
+  assert.equal(kept.sensitivity, "personal");
+  // 时区归一：A2 的时间过滤按 ISO 字典序直接比较。
+  assert.equal(kept.occurred_at, "2026-09-13T02:00:00.000Z");
+
+  const dirty = store.save({
+    type: "project",
+    title: "dirty",
+    content: "c",
+    agent_scope: "   ",
+    workspace_scope: 42,
+    sensitivity: "",
+    occurred_at: "not-a-date"
+  });
+  assert.equal(dirty.agent_scope, undefined);
+  assert.equal(dirty.workspace_scope, undefined);
+  assert.equal(dirty.sensitivity, undefined);
+  assert.equal(dirty.occurred_at, undefined);
+});
+
+test("store.update keeps scope columns untouched (write-time annotation is immutable)", () => {
+  const store = createStore(":memory:");
+  const saved = store.save({ type: "decision", title: "t", content: "old", agent_scope: "a1", workspace_scope: "w1" });
+  store.update(saved.id, { content: "new", importance: 4 });
+  const row = store.getById(saved.id);
+  assert.equal(row.content, "new");
+  assert.equal(row.agent_scope, "a1");
+  assert.equal(row.workspace_scope, "w1");
+});
+
+test("scopeEnabled=false keeps legacy dedupe: cross-scope same-title still merges", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  store.save({ type: "project", title: "T", content: "scoped body", agent_scope: "agentA" });
+  const { action } = service.saveWithDedupe({ type: "project", title: "T", content: "new body" });
+  assert.equal(action, "merged");
+  assert.equal(store.count("project"), 1);
+});
+
+test("scopeEnabled=true: dedupe key extends with agent_scope/workspace_scope/sensitivity", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: { scopeEnabled: true } });
+  const save = (fields) => service.saveWithDedupe({ type: "project", title: "T", content: "body", ...fields });
+
+  assert.equal(save({ agent_scope: "agentA" }).action, "created");
+  // 同标题、不同 agent_scope → 独立行，绝不互相合并。
+  assert.equal(save({ agent_scope: "agentB" }).action, "created");
+  // 不同 workspace_scope → 独立行。
+  assert.equal(save({ agent_scope: "agentA", workspace_scope: "D:\\proj-a" }).action, "created");
+  // 不同 sensitivity → 独立行。
+  assert.equal(save({ agent_scope: "agentA", sensitivity: "personal" }).action, "created");
+  // 三元组全同 → 合并。
+  assert.equal(save({ agent_scope: "agentA" }).action, "merged");
+  assert.equal(store.count("project"), 4);
+});
+
+test("scopeEnabled=true: unscoped writes match legacy NULL rows but not stamped ones", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: { scopeEnabled: true } });
+  // 存量形状（NULL scope）。
+  store.save({ type: "preference", title: "P", content: "legacy" });
+  // 未标注新写入与存量 NULL 行互相匹配。
+  assert.equal(service.saveWithDedupe({ type: "preference", title: "P", content: "x" }).action, "merged");
+  // 已标注行与 NULL 行不匹配 → 独立新行。
+  assert.equal(service.saveWithDedupe({ type: "preference", title: "P", content: "x", agent_scope: "agentA" }).action, "created");
+  assert.equal(store.count("preference"), 2);
+});
+
+test("scopeEnabled=true: _mergeInto across scopes is rejected and falls back to a fresh row", () => {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: { scopeEnabled: true } });
+  const scoped = store.save({ type: "project", title: "S", content: "scoped", agent_scope: "agentA" });
+  const cross = service.saveWithDedupe({
+    type: "project", title: "S", content: "summary text", _mergeInto: scoped.id
+  });
+  assert.equal(cross.action, "created", "cross-scope semantic merge must not leak into the scoped row");
+  const same = service.saveWithDedupe({
+    type: "project", title: "S2", content: "more text", agent_scope: "agentA", _mergeInto: scoped.id
+  });
+  assert.equal(same.action, "merged", "same-scope explicit target still merges");
+  assert.equal(same.memory.id, scoped.id);
+});
+
+function setupTools(config) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config });
+  const registered = [];
+  createTools(
+    { tools: { register(def) { registered.push(def); return () => {}; } } },
+    service,
+    config
+  );
+  const memorySave = registered.find((def) => def.name === "memory_save");
+  assert.ok(memorySave, "memory_save registered");
+  return { store, memorySave };
+}
+
+async function runMemorySave(memorySave, args, exec) {
+  const handler = memorySave.execute.bind(memorySave);
+  return handler(args, exec);
+}
+
+test("memory_save stamps resolved scope onto the row when the flag is on", async () => {
+  const { store, memorySave } = setupTools({ scopeEnabled: true });
+  const exec = { agent: { session: { id: "s1", header: { agentPreset: "coder", cwd: "D:\\proj" } } } };
+  const args = { type: "pitfall", title: "T", content: "c", sensitivity: "personal", occurred_at: "2026-09-12T00:00:00Z" };
+  const out = await runMemorySave(memorySave, args, exec);
+  const row = store.getById(out.id);
+  assert.equal(row.agent_scope, "coder");
+  assert.equal(row.workspace_scope, "D:\\proj");
+  assert.equal(row.sensitivity, "personal");
+  assert.equal(row.occurred_at, "2026-09-12T00:00:00.000Z");
+});
+
+test("memory_save without exec context writes unscoped rows (flag on, nothing resolvable)", async () => {
+  const { store, memorySave } = setupTools({ scopeEnabled: true });
+  const out = await runMemorySave(memorySave, { type: "pitfall", title: "T", content: "c" }, undefined);
+  const row = store.getById(out.id);
+  assert.equal(row.agent_scope, undefined);
+  assert.equal(row.workspace_scope, undefined);
+});
+
+test("memory_save with the flag off writes rows without any scope annotation", async () => {
+  const { store, memorySave } = setupTools({});
+  const exec = { agent: { session: { id: "s1", header: { agentPreset: "coder", cwd: "D:\\proj" } } } };
+  const out = await runMemorySave(memorySave, { type: "pitfall", title: "T", content: "c" }, exec);
+  const row = store.getById(out.id);
+  assert.equal(row.agent_scope, undefined);
+  assert.equal(row.workspace_scope, undefined);
+});
+
+test("createScopeResolver returns null when scopeEnabled is off", () => {
+  const resolve = createScopeResolver({ ctx: {}, config: {} });
+  assert.equal(resolve({ agent: { session: { id: "s1" } } }), null);
+});
+
+test("resolver stamps agentPreset and header cwd; registry hit wins over header cwd", () => {
+  const resolve = createScopeResolver({
+    config: { scopeEnabled: true },
+    ctx: { workspaceRegistry: { list: () => [{ path: "C:\\canon", sessionIds: ["s1"] }] } }
+  });
+  const exec = { agent: { session: { id: "s1", header: { agentPreset: "coder", cwd: "D:\\raw" } } } };
+  assert.deepEqual(resolve(exec), { agent_scope: "coder", workspace_scope: "C:\\canon" });
+
+  const resolveNoHit = createScopeResolver({
+    config: { scopeEnabled: true },
+    ctx: { workspaceRegistry: { list: () => [{ path: "C:\\canon", sessionIds: ["other"] }] } }
+  });
+  assert.deepEqual(resolveNoHit(exec), { agent_scope: "coder", workspace_scope: "D:\\raw" });
+});
+
+test("resolver falls back to the static .header property on old hosts", () => {
+  const resolve = createScopeResolver({ config: { scopeEnabled: true }, ctx: {} });
+  const exec = { agent: { session: { id: "s1", header: { agentPreset: "novelist" } } } };
+  assert.deepEqual(resolve(exec), { agent_scope: "novelist", workspace_scope: null });
+});
+
+test("session.header wins over requestHeader() (EpochHeader must not shadow the durable header)", () => {
+  const resolve = createScopeResolver({ config: { scopeEnabled: true }, ctx: {} });
+  // 本地 web 复验（2026-09-13）实测踩中的形状：requestHeader() 返回请求级
+  // EpochHeader（模型路由头，无 agentPreset/cwd），曾在首个请求后遮蔽
+  // session.header，导致标注全空。
+  const exec = {
+    agent: {
+      session: {
+        id: "s1",
+        header: { agentPreset: "coder", cwd: "D:\\proj" },
+        requestHeader: () => ({ config: { provider: "deepseek-official", model: "deepseek-v4-flash" } })
+      }
+    }
+  };
+  assert.deepEqual(resolve(exec), { agent_scope: "coder", workspace_scope: "D:\\proj" });
+});
+
+test("hosts without .header fall back to requestHeader().config shape", () => {
+  const resolve = createScopeResolver({ config: { scopeEnabled: true }, ctx: {} });
+  const exec = {
+    agent: {
+      session: {
+        id: "s2",
+        requestHeader: () => ({ config: { agentPreset: "legacy", cwd: "E:\\old" } })
+      }
+    }
+  };
+  assert.deepEqual(resolve(exec), { agent_scope: "legacy", workspace_scope: "E:\\old" });
+});
+
+test("resolver never throws: registry explosion degrades to header cwd and warns once", () => {
+  const warnings = [];
+  const resolve = createScopeResolver({
+    config: { scopeEnabled: true },
+    ctx: { workspaceRegistry: { list: () => { throw new Error("boom"); } } },
+    logger: { warn: (m) => warnings.push(String(m)) }
+  });
+  const exec = { agent: { session: { id: "s1", header: { agentPreset: "coder", cwd: "D:\\raw" } } } };
+  assert.deepEqual(resolve(exec), { agent_scope: "coder", workspace_scope: "D:\\raw" });
+  assert.equal(warnings.length, 1, "warn exactly once, never block the write path");
+});
+
+test("resolver without a session or header lands all-NULL", () => {
+  const resolve = createScopeResolver({ config: { scopeEnabled: true }, ctx: {} });
+  assert.deepEqual(resolve(undefined), { agent_scope: null, workspace_scope: null });
+  assert.deepEqual(resolve({ agent: { session: { id: "s2" } } }), { agent_scope: null, workspace_scope: null });
+});