@a9i5k4/dsh-auto-memory 3.0.0 → 3.1.0

package/lib/dsh-home.js

@@ -0,0 +1,143 @@
+/**
+ * dsh-home.js —— **DSH_HOME 的唯一解析口径**（上游 issue #86-3 修复）。
+ *
+ * ## 背景（#86-3；已在 pre 线实跑核验）
+ *
+ * 修复前，全仓有 **7 处独立解析** `process.env.DSH_HOME`，口径互不相同：
+ *
+ *   | 位置 | 环境变量缺失时的回落 |
+ *   |---|---|
+ *   | index.js:808（`dshHome()`） | `path.join(homedir(), '.dsh')` |
+ *   | index.js:9256（模型根） | `path.join(homedir(), '.dsh')` |
+ *   | index.js:9613（python-setup） | `path.join(homedir(), '.dsh')`，失败退 `homedir()` |
+ *   | index.js:9623（python-sidecar） | `path.join(homedir(), '.dsh')`，失败退 **空串** |
+ *   | semantic-js.js:73/176 | `path.join(homedir(), '.dsh')` |
+ *   | activation-host.js:72 | 退 `homedir()` 再拼 `.dsh`，全失败退 **'.'** |
+ *   | context-host.js:40 | 退 **`USERPROFILE || HOME`** 再拼（**前缀不同**） |
+ *   | shadow-host.js:129 | 同 activation（但注释说漏拼过 `.dsh`） |
+ *
+ * ⇒ 后果：**同一台机器上，不同子系统可能把数据写到不同根目录**。
+ *   最典型的是 `context-host` 用 `USERPROFILE` 作基准，而其余用 `os.homedir()`——
+ *   两者在 Windows 上通常一致，但在容器/CI/被改过环境变量的进程里会分叉。
+ *
+ * ## 本模块的职责
+ *
+ * 提供**一个**函数 `resolveDshHomePre(override)`，所有站点都调它。
+ * 解析顺序（逐级回落，**绝不抛**）：
+ *
+ *   1. `override`（显式传入，最高优先 —— 给测试注入与 engine 级配置留口）
+ *   2. `process.env.DSH_HOME`（trim 后非空）
+ *   3. `os.homedir()` + `/.dsh`
+ *   4. 环境变量 `USERPROFILE || HOME` + `/.dsh`（**保留 context-host 原有的兜底能力**，
+ *      只是把它从「基准」降级为「最后兜底」，从而与其余站点统一）
+ *   5. 全失败 ⇒ `'.dsh'`（相对路径，保证**永不返回空串**）
+ *
+ * ## 为什么把 `homedir()` 放在 `USERPROFILE` 之前
+ *
+ * `os.homedir()` 在 Windows 上**本身就是** `USERPROFILE`（Node 内部优先读它，
+ * 读不到才退 `HOMEDRIVE+HOMEPATH`）⇒ 两者绝大多数情况等价，
+ * 但 `homedir()` 还会正确处理 `HOME` 覆盖与权限异常 ⇒ **以它为准更稳**。
+ * 保留 `USERPROFILE||HOME` 仅作 `homedir()` 抛异常时的兜底。
+ *
+ * ## 纪律
+ *   - 零运行时依赖（只 `node:os` / `node:path`）。
+ *   - **永不抛、永不返回空串**（调用方大量直接 `path.join(dshHome(), ...)`）。
+ *   - 只读环境变量，**不缓存**（测试会中途改 `process.env.DSH_HOME`）。
+ *   - CRLF、无 BOM。
+ */
+import os from 'node:os'
+import path from 'node:path'
+
+/** 环境变量名（集中一处，便于将来改名）。 */
+export const DSH_HOME_ENV_V1 = 'DSH_HOME'
+
+/** 默认子目录名。 */
+export const DSH_HOME_DIRNAME_V1 = '.dsh'
+
+/** 全失败时的最后兜底（相对路径，保证返回非空）。 */
+export const DSH_HOME_FALLBACK_V1 = '.dsh'
+
+/**
+ * 取 home 基准目录（用于拼 `.dsh`）。**永不抛**。
+ * @returns {string} 非空字符串，或空串（表示取不到基准）
+ */
+function homeBasePre() {
+  // ① os.homedir() —— 首选：Windows 上等价于 USERPROFILE，且能处理 HOME 覆盖
+  try {
+    const h = os.homedir()
+    if (h && String(h).trim()) return String(h).trim()
+  } catch (_) {
+    // 落到 ②
+  }
+  // ② USERPROFILE / HOME —— 兼容 homedir() 抛异常的极端环境
+  try {
+    const e = process.env.USERPROFILE || process.env.HOME || ''
+    if (e && String(e).trim()) return String(e).trim()
+  } catch (_) {}
+  return ''
+}
+
+/**
+ * **唯一入口**：解析 DSH_HOME。
+ *
+ * @param {string} [override] 显式覆盖（测试注入 / engine 级配置）；空串视为未提供。
+ * @returns {string} 非空路径字符串（**永不抛、永不返回空串**）
+ */
+export function resolveDshHomePre(override) {
+  // ① 显式覆盖优先
+  try {
+    if (override != null && String(override).trim()) return String(override).trim()
+  } catch (_) {}
+  // ② 环境变量
+  try {
+    const env = process.env[DSH_HOME_ENV_V1]
+    if (env && String(env).trim()) return String(env).trim()
+  } catch (_) {}
+  // ③ / ④ 基准目录 + .dsh
+  const base = homeBasePre()
+  if (base) {
+    try {
+      return path.join(base, DSH_HOME_DIRNAME_V1)
+    } catch (_) {}
+  }
+  // ⑤ 最后兜底
+  return DSH_HOME_FALLBACK_V1
+}
+
+/**
+ * engine 级便捷包装：优先用 `engine.__dshHomeOverride`，其次环境变量，最后默认。
+ *
+ * 之所以要这一层：`activation-host` / `context-host` / `shadow-host` 都是
+ * 「engine + 可选 __homedirFn」的形态，统一改调本函数可让三者的口径完全一致，
+ * 同时**保留** `__homedirFn` 这个既有测试注入点（不再各自手写回落链）。
+ */
+export function resolveDshHomeForEnginePre(engine) {
+  const e = engine || {}
+  // ★★ 优先级必须与**原实现**一致：`env` 优先于 `__homedirFn`。
+  //    原写法是 `const env = process.env.DSH_HOME; if (env.trim()) return env.trim();
+  //    const base = engine.__homedirFn ? ... : ...` ⇒ env 先判。
+  //    ⚠️ 2026-09-20 首次实现把 __homedirFn 提到 env 之前，导致用 `process.env.DSH_HOME`
+  //       注入的测试（如 smoke-test-m53）被真实 homedir 覆盖，证据写到了**真实用户目录**
+  //       （症状：C4/C5/C6 evidence 落盘数为 0，离真因很远）。
+  // ① 显式 engine 级覆盖（新增能力，原实现没有，放最前不影响兼容）
+  try {
+    if (e.__dshHomeOverride != null && String(e.__dshHomeOverride).trim()) {
+      return String(e.__dshHomeOverride).trim()
+    }
+  } catch (_) {}
+  // ② 环境变量（与原实现同优先级）
+  try {
+    const env = process.env[DSH_HOME_ENV_V1]
+    if (env && String(env).trim()) return String(env).trim()
+  } catch (_) {}
+  // ③ 既有注入点 __homedirFn：返回的是「home 基准目录」，仍需拼 .dsh
+  try {
+    if (typeof e.__homedirFn === 'function') {
+      const base = e.__homedirFn()
+      if (base && String(base).trim()) return path.join(String(base).trim(), DSH_HOME_DIRNAME_V1)
+    }
+  } catch (_) {}
+  // ④ 默认链（homedir → USERPROFILE/HOME → '.dsh'）
+  return resolveDshHomePre()
+}
+

package/lib/episodic-store.js

@@ -104,15 +104,60 @@ export function createEpisodicStorePre(opts = {}) {
     return EPISODE_ID_PREFIX + h.slice(0, 32)
   }
 
+  /**
+   * issue#57 修复(2026-09-19):restore 时对 `data.current` 做**形状校验**。
+   * 旧实现 `current = data.current || null` 零校验(与 :222 的 validateEpisodePre 形成不对称):
+   * 磁盘上 `current:{}`(截断/手改/旧版本残留)会被原样采纳 ⇒ 之后 consolidate() 在
+   * `current.segments.length`(:202)抛 TypeError ⇒ **巩固链路静默停摆**,且因异常发生在
+   * 调用方 try 之外,统计与日志都不留痕。
+   * 纪律:**丢弃优于卡死** —— 形状不合格一律置 null(等效"本会话无未巩固缓冲"),
+   * 绝不把结构非法对象放进状态机。
+   */
+  function restoreCurrentPre(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+    if (typeof raw.sessionRef !== 'string' || !raw.sessionRef) return null
+    if (typeof raw.startedAt !== 'number' || !Number.isFinite(raw.startedAt)) return null
+    if (!Array.isArray(raw.segments) || !Array.isArray(raw.userTexts) || !Array.isArray(raw.assistantTexts)) return null
+    return raw
+  }
+
+  /**
+   * ★ P2-2 修复(2026-09-21)：查询返回**深一层副本**。
+   * 旧实现 `{ ...e }` 是浅拷贝 ⇒ `actions/entities/unresolved/provenance` 四个数组
+   * 与库内对象**同引用**，调用方 push 会直接改脏已巩固 episode(绕过 persist 与统计)。
+   */
+  function cloneEpisode(e) {
+    if (!e) return e
+    return {
+      ...e,
+      actions: Array.isArray(e.actions) ? [...e.actions] : e.actions,
+      entities: Array.isArray(e.entities) ? [...e.entities] : e.entities,
+      unresolved: Array.isArray(e.unresolved) ? [...e.unresolved] : e.unresolved,
+      provenance: Array.isArray(e.provenance) ? [...e.provenance] : e.provenance,
+    }
+  }
+
   // ---- 段追加(会话进行中实时累积) ----
   function append(seg) {
     if (disposed) return { ok: false, reason: 'disposed' }
     const v = validateEpisodeSegmentPre(seg)
     if (!v.ok) return { ok: false, reason: v.reason }
     const s = v.segment
+    const incomingRef = String(s.sessionRef || 'unknown')
+    // ★ A-7 修复(2026-09-21)：**按 sessionRef 隔离**。
+    //   旧实现只在 `!current` 时取一次 sessionRef ⇒ 后续不同会话的段被并进同一个 episode:
+    //   实测 sessionRef=session-A 但 intent 含 session-B 内容、provenance=["seg:1","seg:1"]。
+    //   后果:procedure 晋升依赖的 distinctSessions 被系统性低估 ⇒ 技能永远卡在
+    //   `diversity-below-3`(跨会话证据明明够,读数却恒为 1)。
+    //   现改为:检测到会话切换时,**先巩固当前缓冲**(把上一会话的段固化成一个独立 episode),
+    //   再为新的 sessionRef 开一个干净的 current。consolidate 失败(如 too-short)不阻断本段,
+    //   其内部已负责把 current 置 null,后续照常新建。
+    if (current && current.sessionRef !== incomingRef) {
+      consolidate()
+    }
     if (!current) {
       current = {
-        sessionRef: String(s.sessionRef || 'unknown'),
+        sessionRef: incomingRef,
         startedAt: nowFn(),
         segments: [],
         userTexts: [], assistantTexts: [],
@@ -139,7 +184,13 @@ export function createEpisodicStorePre(opts = {}) {
       if (current.assistantTexts.length) current.assistantTexts.shift()
     }
     stats.segmentsAppended++
-    return { ok: true, segments: current.segments.length }
+    // ★ P2-11 修复(2026-09-21)：append 此前**完全不落盘** —— 段只留在内存，
+    //   进程重启(崩溃/宿主重载)后未巩固的会话缓冲整段丢失，而调用方看到 ok:true。
+    //   现在按段落盘(与 fact-store 各写路径一致)。落盘结果一并透传(A-8 同款纪律)。
+    const pr = persist()
+    return pr.ok
+      ? { ok: true, segments: current.segments.length, persisted: true }
+      : { ok: true, segments: current.segments.length, persisted: false, persistError: pr.error }
   }
 
   /** 从累积文本提取 intent(2026-08-28 提纯;2026-09-16 issue#30 改为共享清洗器)。
@@ -215,13 +266,24 @@ export function createEpisodicStorePre(opts = {}) {
       unresolved: extractUnresolved(current),
       outcome,
       success: outcome === 'success',
-      provenance: current.segments.map((s) => 'seg:' + String(s.eventSeq)),
+      // ★ A-7 修复(2026-09-21)：provenance 改为 **`sessionRef:eventSeq`**。
+      //   旧实现只用 `'seg:' + eventSeq` ⇒ 不同会话里 eventSeq 从 1 重新计数时
+      //   会产出完全相同的串(实测 ["seg:1","seg:1"]),既无法溯源到会话,
+      //   也让"同一段被重复计入"与"两段恰好同号"在审计面上不可区分。
+      provenance: current.segments.map((s) => String(current.sessionRef) + ':' + String(s.eventSeq)),
       startedAt: current.startedAt,
       consolidatedAt: nowFn(),
     }
     const v = validateEpisodePre(ep)
     if (!v.ok) { current = null; return { ok: false, reason: 'invalid:' + v.reason } }
-    episodes.push(v.episode)
+    // ★ P2-11 修复(2026-09-21)：巩固入店前按 **episodeId 去重**。
+    //   episodeId = hash(sessionRef, startedAt) ⇒ 同一会话在同一时间戳被重复巩固
+    //   (或 restore/import 已带入同 id 记录)会产出**同一主键的第二条**，
+    //   下游 query/statsFor 会把一次会话数成两次 ⇒ distinctSessions/success 读数虚高。
+    //   去重策略:**后到者胜**(原地替换,不打乱既有顺序),与 fact-store restore 一致。
+    const dupAt = episodes.findIndex((x) => x.episodeId === v.episode.episodeId)
+    if (dupAt >= 0) episodes[dupAt] = v.episode
+    else episodes.push(v.episode)
     // 保留策略: 超 retention 淘汰最旧
     if (episodes.length > cfg.retention) {
       episodes = episodes.slice(-cfg.retention)
@@ -229,8 +291,10 @@ export function createEpisodicStorePre(opts = {}) {
     }
     current = null
     stats.consolidated++
-    void persist()
-    return { ok: true, episode: v.episode }
+    const pr = persist()
+    return pr.ok
+      ? { ok: true, episode: v.episode, persisted: true }
+      : { ok: true, episode: v.episode, persisted: false, persistError: pr.error }
   }
 
   /** 会话中途强制巩固(跨天续接/会话切换时调用)。 */
@@ -247,14 +311,14 @@ export function createEpisodicStorePre(opts = {}) {
         (q.sessionRef === undefined || e.sessionRef === q.sessionRef) &&
         (q.outcome === undefined || e.outcome === q.outcome) &&
         (q.success === undefined || e.success === q.success))
-      .map((e) => ({ ...e }))
+      .map(cloneEpisode)
   }
   function recent(n = 10) {
-    return episodes.slice(-n).map((e) => ({ ...e }))
+    return episodes.slice(-n).map(cloneEpisode)
   }
   function get(episodeId) {
     const e = episodes.find((x) => x.episodeId === episodeId)
-    return e ? { ...e } : null
+    return e ? cloneEpisode(e) : null
   }
 
   // ---- M-04 挂钩: 供 Procedure 晋升用的事故/成功统计 ----
@@ -273,13 +337,48 @@ export function createEpisodicStorePre(opts = {}) {
     return {
       schemaVersion: 1, namespace: 'dsh-auto-memory', policyVersion: EPISODIC_POLICY_VERSION,
       savedAt: nowFn(),
-      episodes: episodes.map((e) => ({ ...e })),
+      // ★ P2-2 修复：快照数组字段同样做副本(调用方改快照不得改脏库内 episode)
+      episodes: episodes.map(cloneEpisode),
       current: current ? {
         sessionRef: current.sessionRef, startedAt: current.startedAt,
-        segments: current.segments, userTexts: current.userTexts, assistantTexts: current.assistantTexts,
+        segments: current.segments.map((s) => ({ ...s })),
+        userTexts: [...current.userTexts], assistantTexts: [...current.assistantTexts],
       } : null,
     }
   }
+  /**
+   * ★ 增量导入（2026-09-19 上游 PR #77 / issue #63 同步落地，**P0 数据丢失**）。
+   *
+   * **为什么必须单独有这个函数**：hub 的 `ingestJudgement` 原本对每行 `episodic_candidate`
+   * 调 `restore({schemaVersion:1, episodes:[row]})`，而 `restore()` 是**快照整体替换**语义
+   * （先 `episodes = []`）。worker 产出的候选行普遍缺 `validateEpisodePre` 必填字段
+   * ⇒ 校验必拒（`restored:0`），**但 episodes 已被清空、current 已被置 null**，
+   * 且 `restore()` 仍返回 `{ok:true}` ⇒ hub 记 `consumedEpisodic++` / `outcome:'restored'`
+   * ⇒ 下次 consolidate/flush 把清空态落盘 ⇒ **一次 ingest 抹掉全部已巩固 episode，不可逆**。
+   *
+   * 契约（与 `restore` 严格区分）：
+   *  - **绝不清空既有状态**（不清 episodes、不动 current）；
+   *  - 逐条校验，**只追加合法项**，非法项计入 `rejected`（不静默）；
+   *  - 按 `episodeId` **幂等去重**（重复导入同一行不产生副本）；
+   *  - **不持久化**（由调用方决定何时 flush），与 `restore` 一致。
+   * @param {Array} rows - 候选 episode 行（原始形态，内部走 validateEpisodePre）
+   * @returns {{ok: boolean, imported: number, rejected: number, duplicates: number, reason?: string}}
+   */
+  function importEpisodes(rows) {
+    if (!Array.isArray(rows)) return { ok: false, imported: 0, rejected: 0, duplicates: 0, reason: 'bad-rows' }
+    let imported = 0, rejected = 0, duplicates = 0
+    const seen = new Set(episodes.map((e) => e.episodeId))
+    for (const raw of rows) {
+      const v = validateEpisodePre(raw)
+      if (!v.ok) { rejected++; continue }
+      if (seen.has(v.episode.episodeId)) { duplicates++; continue }
+      episodes.push(v.episode)
+      seen.add(v.episode.episodeId)
+      imported++
+    }
+    return { ok: true, imported, rejected, duplicates }
+  }
+
   function restore(data) {
     if (!data || data.schemaVersion !== 1) return { ok: false, reason: 'bad-schema' }
     if (!Array.isArray(data.episodes)) return { ok: false, reason: 'bad-episodes' }
@@ -289,27 +388,52 @@ export function createEpisodicStorePre(opts = {}) {
       if (!v.ok) continue
       episodes.push(v.episode)
     }
-    current = data.current || null
+    current = restoreCurrentPre(data.current)
     return { ok: true, restored: episodes.length }
   }
   function clear() {
     episodes = []; current = null
-    try { io.clear() } catch (_) {}
-    return { ok: true }
+    // ★ A-8：io.clear() 失败不得静默(残留快照会在下次 load 时"复活"已清空的 episode)
+    let cleared = true, clearError
+    try { io.clear() } catch (e) {
+      cleared = false
+      clearError = (e && e.message) ? String(e.message) : String(e)
+    }
+    return clearError !== undefined ? { ok: true, cleared, error: clearError } : { ok: true, cleared }
   }
   function dispose(reason) {
-    if (disposed) return
+    if (disposed) return { ok: true, persisted: true, alreadyDisposed: true }
     disposed = true
-    try { io.save(snapshot()) } catch (_) {}
+    // ★ A-8：dispose 是最后一次落盘机会，失败必须外显
+    const r = persist()
+    return { ok: r.ok, persisted: r.ok, ...(r.error ? { error: r.error } : {}) }
   }
 
+  /**
+   * ★ A-8 修复(2026-09-21)：旧实现 `try { io.save(snapshot()) } catch (_) {}` **吞掉落盘失败** ——
+   * 调用方看到 ok:true、宿主继续推进状态，但磁盘没写上，该状态**永不重写**(静默数据丢失)。
+   * 现改为:① 返回结构化结果 `{ok, persisted}`(失败时附 error 文案); ② 失败记进模块内可读状态
+   * `lastPersistError`(经 `getLastPersistError()` 暴露)。不引入任何新 import。
+   * @returns {{ok:boolean, persisted:boolean, error?:string}}
+   */
+  let lastPersistError = null
   function persist() {
-    try { io.save(snapshot()) } catch (_) {}
+    try {
+      io.save(snapshot())
+      lastPersistError = null
+      return { ok: true, persisted: true }
+    } catch (e) {
+      const msg = (e && e.message) ? String(e.message) : String(e)
+      lastPersistError = msg
+      return { ok: false, persisted: false, error: msg }
+    }
   }
 
   return {
     append, consolidate, flush, query, recent, get, statsFor,
-    snapshot, restore, clear, dispose,
+    snapshot, restore, importEpisodes, clear, dispose,
+    /** ★ A-8：最近一次落盘失败(字符串)或 null —— 供宿主诊断"写盘失败但流程继续"的静默缺口。 */
+    getLastPersistError: () => lastPersistError,
     getStats: () => ({ ...stats }),
     get size() { return episodes.length },
     get hasCurrent() { return !!current },

package/lib/evidence-store.js

@@ -118,7 +118,14 @@ export class EvidenceEventStore {
     }
     if (id) this._appended.add(id)
     this._chain = this._chain.then(() => this._writeLine(proj.line))
-    return this._chain.then((written) => ({ ok: written, reason: written ? 'ok' : 'write-failed', evidenceId: id, projected: proj.projected }))
+    return this._chain.then((written) => {
+      // issue#56 修复(2026-09-19):写盘失败必须**释放幂等登记**。
+      // 旧实现只 add 从不回退 ⇒ 一次瞬时写失败后,同 evidenceId 的重试恒被判
+      // duplicate-evidence 而拒绝 ⇒ 该条证据**静默永久丢失**。
+      // 登记保留在调用时(维持同步去重窗口),失败时撤销(允许重试)。
+      if (!written && id) this._appended.delete(id)
+      return { ok: written, reason: written ? 'ok' : 'write-failed', evidenceId: id, projected: proj.projected }
+    })
   }
 
   async _writeLine(line) {