@modusensus/dsh-mneme 0.8.0 → 0.8.2

package/lib/service.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { TYPE_FILE } from "./mirror.js";
 import { updatedAtBounds } from "./store.js";
+import { normalizeExplicitScope, scopeKeyOf } from "./scope.js";
 import { STR, langOf } from "./lang.js";
 import { computeHeat } from "./heat.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
@@ -40,12 +41,8 @@ const CONTENT_HISTORY_MAX = 20;
 // 清单必须与 quality-filter.js 的写入端对齐（6 个，含 type 自指的 self_referential）。
 const SIGNAL_TAGS = ["low_quality", "duplicate", "meta", "repetitive", "short_content", "self_referential"];
 
-// v0.8.0 A1（issue #17）去重键的 scope 归一：非空 trim 字符串原样比较，其余
-// （NULL/undefined/空串）统一为「未标注」。与 store.normalizeScopeText 的落库
-// 口径一致——两把钥匙只有都过这里再比较，NULL 与 'global' 才不会错配。
-function scopeKeyOf(v) {
-  return typeof v === "string" && v.trim() ? v.trim() : null;
-}
+// scopeKeyOf 已上提到 ./scope.js（v0.8.1，issue #170 第 2 步）：与 sleep 的跨
+// scope 配对共用同一把比较钥匙，避免两处定义漂移。
 
 // v0.8.0 A2（issue #17）scope 检索加权系数：两维都无法确立 foreign 的候选
 // （命中行、未标注行、当前侧维度解析不到的行）→ 加成；只有确立了 foreign
@@ -93,10 +90,18 @@ function inOccurredBounds(m, bounds) {
  * 留给后续批次）。store.list 的 SQL 过滤与此谓词同口径（见 store.js visibility）。
  */
 function isVisibleInScope(m, current) {
-  const agent = scopeKeyOf(m.agent_scope);
-  if (agent !== null && (current.agent_scope === null || agent !== current.agent_scope)) return false;
-  const ws = scopeKeyOf(m.workspace_scope);
-  if (ws !== null && (current.workspace_scope === null || ws !== current.workspace_scope)) return false;
+  // v0.8.1 第 3 步（issue #170 4.3，作者已确认）：硬过滤只认显式声明。某维
+  // 仅当「该维有标注且来源为 explicit」才构成硬墙；auto（含 v0.8.0 存量的
+  // NULL 来源行）只吃 A2 软加权（foreign ×0.5 保留可见），不进硬过滤。
+  // 显式全局（值 NULL + source explicit）与未标注同形，天然恒可见。
+  if (m.agent_scope_source === "explicit") {
+    const agent = scopeKeyOf(m.agent_scope);
+    if (agent !== null && (current.agent_scope === null || agent !== current.agent_scope)) return false;
+  }
+  if (m.workspace_scope_source === "explicit") {
+    const ws = scopeKeyOf(m.workspace_scope);
+    if (ws !== null && (current.workspace_scope === null || ws !== current.workspace_scope)) return false;
+  }
   return true;
 }
 
@@ -1064,17 +1069,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // 标题变化，若仍按 (type, title) 匹配会出现两个活跃的 summary 同时注入。
     // 其余类型维持 (type, title) 匹配不变。
     const candidates = store.list({ type: memory.type, limit: 100 });
-    // v0.8.0 A1（issue #17）：scopeEnabled 开启时去重键由 (type, title) 扩展为
+    // v0.8.0 A1（issue #17）：去重键由 (type, title) 扩展为
     // (type, title, agent_scope, workspace_scope, sensitivity)——不同作用域的同
     // 标题记忆绝不互相物理合并（旧逻辑跨 agent/workspace 并行，事后无法拆分）。
     // NULL 归一为「未标注」：未标注行之间互相匹配（含存量行），与已标注行不
-    // 匹配。flag 关闭时跳过比较，行为与 A1 前逐字节一致。
-    const scopeOn = config.scopeEnabled === true;
+    // 匹配。
+    // v0.8.1（issue #170 复核项 1）：比较不再受 scopeEnabled 门控——显式声明
+    // flag 关也生效（工具层明写「读了自动标注也生效」，去重必须同口径），否则
+    // 关自动标注后同标题不同 scope 的行会物理合并进第一行的归属。存量全 NULL
+    // 行互相匹配，A1 前行为不变。
     const scopeMatches = (m) =>
-      !scopeOn ||
-      (scopeKeyOf(m.agent_scope) === scopeKeyOf(memory.agent_scope) &&
-        scopeKeyOf(m.workspace_scope) === scopeKeyOf(memory.workspace_scope) &&
-        scopeKeyOf(m.sensitivity) === scopeKeyOf(memory.sensitivity));
+      scopeKeyOf(m.agent_scope) === scopeKeyOf(memory.agent_scope) &&
+      scopeKeyOf(m.workspace_scope) === scopeKeyOf(memory.workspace_scope) &&
+      scopeKeyOf(m.sensitivity) === scopeKeyOf(memory.sensitivity);
     // Issue #127：写入端语义去重命中时，调用方用 _mergeInto 指定并入目标——复用
     // 下面这段并入逻辑（appendContent + content_history + 质量处置），不另写第二份
     // 实现。目标已被并发删除时回落到常规匹配。显式目标同样过 scope 门：跨作用域
@@ -1097,6 +1104,17 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         ? newContent
         : appendContent(existing.content, newContent);
       const importance = Math.min(5, Math.max(existing.importance, memory.importance ?? existing.importance));
+      // v0.8.1 底座（issue #170）：去重命中=scope 值完全同键，此时显式写入把
+      // 被并入行的同维来源升级为 explicit（用户刚刚显式声明了同一归属），
+      // 并刷新 scope_decided_at。仅升级来源、不改值——值改变会走新行。
+      const scopeUpgrade = {};
+      if (memory.agent_scope_source === "explicit" && existing.agent_scope_source !== "explicit") {
+        scopeUpgrade.agent_scope_source = "explicit";
+      }
+      if (memory.workspace_scope_source === "explicit" && existing.workspace_scope_source !== "explicit") {
+        scopeUpgrade.workspace_scope_source = "explicit";
+      }
+      if (Object.keys(scopeUpgrade).length) scopeUpgrade.scope_decided_at = new Date().toISOString();
       const merged = store.update(existing.id, {
         content,
         importance,
@@ -1105,8 +1123,30 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         content_history: pushContentHistory(existing, direct
           ? (memory._humanEdited === true ? "human_override" : "overwrite")
           : "auto_merge"),
+        ...scopeUpgrade,
         ...(quality ? { quality_score: quality.score } : {})
       });
+      // v0.8.1（issue #170 review 3）：来源升级也是归属性质改变——与
+      // updateMemory 的显式修正同等待遇，落一行 scope_changes（actor=tool：
+      // 只有 memory_save 的显式参数会带 explicit 来源走到这里）。审计失败只
+      // warn 不反噬合并。升级只在来源首次变化时触发，不会每次并入都写。
+      if (Object.keys(scopeUpgrade).length) {
+        try {
+          store.saveScopeChange({
+            memory_id: existing.id,
+            actor: "tool",
+            prev_agent_scope: existing.agent_scope ?? null,
+            prev_workspace_scope: existing.workspace_scope ?? null,
+            next_agent_scope: merged.agent_scope ?? null,
+            next_workspace_scope: merged.workspace_scope ?? null,
+            agent_scope_source: merged.agent_scope_source ?? null,
+            workspace_scope_source: merged.workspace_scope_source ?? null,
+            decided_at: scopeUpgrade.scope_decided_at
+          });
+        } catch (e) {
+          try { logger?.warn?.(`[dsh-mneme] scope upgrade audit failed: ${String(e)}`); } catch { /* 不反噬 */ }
+        }
+      }
       // Bug7: a degraded/archived result is applied on top of the merged row.
       const result = applyQualityDisposition(merged, quality, qf);
       afterSync("write");
@@ -1122,8 +1162,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       importance: memory.importance ?? 3,
       source: memory.source ?? "manual",
       // v0.8.0 A1：scope 标注透传（store 端归一化，未标注落 NULL）。
+      // v0.8.1 底座：来源（auto/explicit）与决策时间随行透传。
       agent_scope: memory.agent_scope,
       workspace_scope: memory.workspace_scope,
+      agent_scope_source: memory.agent_scope_source,
+      workspace_scope_source: memory.workspace_scope_source,
+      scope_decided_at: memory.scope_decided_at,
       sensitivity: memory.sensitivity,
       occurred_at: memory.occurred_at,
       ...(quality ? { quality_score: quality.score } : {})
@@ -1248,6 +1292,22 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           if (m && !m.archived && INJECT_TYPES.has(m.type) && !m.forgotten && codingGate(m)) semanticItems.push(m);
         }
       }
+      // Issue #198：首轮（无向量、无缓存召回）的同步兜底——BM25 词法召回领位。
+      // 注入渲染是同步的（宿主 systemPrompt 的 contexts 不支持异步 text），
+      // 查询向量只能异步 prefetch 给下一轮，首轮必 miss；此时纯静态排序会让
+      // 老的高重要性 summary/preference 占满槽位，当前话题的 decision/project
+      // 进不来。查询文本本身就在手上，BM25 是纯进程内同步计算，词法相关性
+      // 足以把当前话题顶到前排；门控与向量路径一致（含 importance 阈值）。
+      // 语义向量命中时本分支不参与，行为不变。
+      if (!semanticItems.length) {
+        for (const hit of bm25Recall(q, maxItems * 2)) {
+          if (hit && !hit.archived && INJECT_TYPES.has(hit.type) && !hit.forgotten &&
+            codingGate(hit) &&
+            (hit.type === "summary" || hit.type === "preference" || hit.importance >= threshold)) {
+            semanticItems.push(hit);
+          }
+        }
+      }
       if (semanticItems.length) {
         const seen = new Set();
         const merged = [];
@@ -1441,8 +1501,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       // v0.8.0 A2：scope 标注与事件发生时间透出——条件展开（未标注行不带键，
       // DTO 与 A2 前逐字节同形；带 undefined 键会被 in-process schema 校验
       // 判违规，JSON 序列化虽会丢弃但形状不稳定）。
+      // v0.8.1 底座：scope 来源与决策时间随行透出（同样条件展开）。
       ...(m.agent_scope !== undefined ? { agent_scope: m.agent_scope } : {}),
       ...(m.workspace_scope !== undefined ? { workspace_scope: m.workspace_scope } : {}),
+      ...(m.agent_scope_source !== undefined ? { agent_scope_source: m.agent_scope_source } : {}),
+      ...(m.workspace_scope_source !== undefined ? { workspace_scope_source: m.workspace_scope_source } : {}),
+      ...(m.scope_decided_at !== undefined ? { scope_decided_at: m.scope_decided_at } : {}),
       ...(m.sensitivity !== undefined ? { sensitivity: m.sensitivity } : {}),
       ...(m.occurred_at !== undefined ? { occurred_at: m.occurred_at } : {})
     }));
@@ -1734,10 +1798,47 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     // tags——任何带 tags 的更新都会抹掉这条唯一的审计线索（报告实测 150 条低分
     // 记忆里恰好缺的 2 条就是被 update 过的，并因此误判过归档来源）。把 existing
     // 的系统信号标签并集保留；用户自传的标签照常生效。
-    const patch = (p && Array.isArray(p.tags) && old && Array.isArray(old.tags))
+    let patch = (p && Array.isArray(p.tags) && old && Array.isArray(old.tags))
       ? { ...p, tags: [...new Set([...p.tags, ...old.tags.filter((t) => SIGNAL_TAGS.includes(t))])] }
       : p;
+    // v0.8.1 底座（issue #170）：显式 scope 修正。patch 携带 agent_scope /
+    // workspace_scope 键（undefined=该维不动）时归一化并盖 explicit 章 +
+    // scope_decided_at，随后写 scope_changes 审计行（actor：tool=模型侧 /
+    // panel=人工侧）。审计失败只 warn，不反噬主写入。
+    const nextAgentScope = p && p.agent_scope !== undefined ? normalizeExplicitScope(p.agent_scope) : undefined;
+    const nextWorkspaceScope = p && p.workspace_scope !== undefined ? normalizeExplicitScope(p.workspace_scope) : undefined;
+    const scopeChanged = nextAgentScope !== undefined || nextWorkspaceScope !== undefined;
+    if (scopeChanged) {
+      const decidedAt = new Date().toISOString();
+      patch = { ...patch };
+      if (nextAgentScope !== undefined) {
+        patch.agent_scope = nextAgentScope;
+        patch.agent_scope_source = "explicit";
+      }
+      if (nextWorkspaceScope !== undefined) {
+        patch.workspace_scope = nextWorkspaceScope;
+        patch.workspace_scope_source = "explicit";
+      }
+      patch.scope_decided_at = decidedAt;
+    }
     const updated = store.update(id, patch);
+    if (scopeChanged && old && updated) {
+      try {
+        store.saveScopeChange({
+          memory_id: id,
+          actor: ctx.actor === "panel" ? "panel" : "tool",
+          prev_agent_scope: old.agent_scope ?? null,
+          prev_workspace_scope: old.workspace_scope ?? null,
+          next_agent_scope: updated.agent_scope ?? null,
+          next_workspace_scope: updated.workspace_scope ?? null,
+          agent_scope_source: updated.agent_scope_source ?? null,
+          workspace_scope_source: updated.workspace_scope_source ?? null,
+          decided_at: patch.scope_decided_at
+        });
+      } catch (e) {
+        try { ctx.logger?.warn?.(`[dsh-mneme] scope change audit failed: ${String(e)}`); } catch { /* 同样不反噬 */ }
+      }
+    }
     // Record a user correction when any meaningful field changed and the
     // reflection failure tracker is enabled. expected = what it became,
     // actual = what it was before; query (when provided) captures the
@@ -1843,6 +1944,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       notifyWrite();
     },
     update: updateMemory,
+    // v0.8.1 底座：scope 归属修正审计（单条记忆，新→旧）。
+    listScopeChanges: (memoryId, opts) => store.listScopeChanges(memoryId, opts),
     // Compare-and-set update: applies the patch only when the row still carries
     // `expectedUpdatedAt`. Returns undefined on a miss (no write) so the caller
     // can re-read and retry — the primitive that prevents lost updates across