@a9i5k4/dsh-auto-memory 3.0.0 → 3.0.1

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,6 +104,23 @@ 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
+  }
+
   // ---- 段追加(会话进行中实时累积) ----
   function append(seg) {
     if (disposed) return { ok: false, reason: 'disposed' }
@@ -280,6 +297,39 @@ export function createEpisodicStorePre(opts = {}) {
       } : 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,7 +339,7 @@ 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() {
@@ -309,7 +359,7 @@ export function createEpisodicStorePre(opts = {}) {
 
   return {
     append, consolidate, flush, query, recent, get, statsFor,
-    snapshot, restore, clear, dispose,
+    snapshot, restore, importEpisodes, clear, dispose,
     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) {

package/lib/fact-store.js

@@ -181,10 +181,17 @@ export function createFactStorePre(opts = {}) {
       // conflictId 必须唯一:同一候选值反复出现时,每次冲突都是独立待决事件。
       // 用 subject+predicate+object+序号+detectedAt 派生,保证可被逐个 resolve。
       conflictSeq++
+      // ★ 登记**检测时快照**而非活引用（2026-09-19 上游 PR #80 第 3 项 / issue #67 同步落地）：
+      //   旧实现 `left: existing` 持 store 内活对象引用 ⇒ 后续 merge 会**原地改写** existing.confidence
+      //   并对 existing.provenance **数组原地 push** ⇒ 已展示/已落盘（facts.json）的冲突左侧
+      //   ≠ 检测时的值 ⇒ 审计面失真（"当时判定冲突的两个值"被事后改写）。
+      //   故此处取快照，provenance 额外做数组副本。
       conflicts.push({
         conflictId: defaultFactId(c.scope, c.subject, c.predicate, c.object) + '_conflict_' + conflictSeq + '_' + String(now),
         scope: c.scope, subject: c.subject, predicate: c.predicate,
-        left: existing, right: c, detectedAt: now, resolved: false,
+        left: { ...existing, provenance: Array.isArray(existing.provenance) ? [...existing.provenance] : existing.provenance },
+        right: { ...c, provenance: Array.isArray(c.provenance) ? [...c.provenance] : c.provenance },
+        detectedAt: now, resolved: false,
       })
       void persist() // 冲突集是重要状态,必须落盘(不持久化会丢失待决冲突)
       return { ok: true, outcome: 'conflict-added', conflict: conflicts[conflicts.length - 1], existing }
@@ -384,7 +391,12 @@ export function createFactStorePre(opts = {}) {
   function clear() {
     facts = []; conflicts = []
     try { io.clear() } catch (_) {}
-    stats.created = 0; stats.merged = 0; stats.superseded = 0
+    // ★ issue #76-6c 修复（2026-09-19）：统计字段**全量归零**。
+    //   旧实现只写 `stats.created = 0; stats.merged = 0; stats.superseded = 0`，
+    //   漏掉 `upserts / conflictAdded / inferenceBlocked / expiredIgnored / revoked`
+    //   ⇒ clear() 后这些计数残留（实测），诊断读数与实际不符。
+    //   改为**按现有键遍历归零**，将来新增 stats 字段也不会再漏。
+    for (const k of Object.keys(stats)) stats[k] = 0
     return { ok: true }
   }
   function dispose(reason) {
@@ -396,6 +408,13 @@ export function createFactStorePre(opts = {}) {
   return {
     upsert, supersede, get, query, conflictsList, pendingConflicts, resolveConflict,
     evidenceFor, revokeBySource, snapshot, restore, clear, dispose,
+    // ★ issue #76-5 修复（2026-09-19）：把**模块级**的 judgement-row 消费器挂进实例。
+    //   旧实现 `memory-hub.js:81-84` 检查 `typeof stores.facts.factCandidateFromJudgementRow === 'function'`
+    //   以决定是否委托——但该函数此前**只是模块级导出**（见上方 `export function`），
+    //   不在 `createFactStorePre()` 的返回对象上 ⇒ **该分支恒假** ⇒ hub 恒走自己的本地副本
+    //   `factCandidateFromRow`（丢掉 `ttl` 字段，实测同输入下 store 版 ttl=60000、hub 版无 ttl）
+    //   ⇒ 两适配器从此各自演化。挂进实例后委托分支变为恒真，语义统一到 store 实现。
+    factCandidateFromJudgementRow,
     getStats: () => ({ ...stats }),
     get size() { return facts.length },
     get conflictCount() { return conflicts.length },

package/lib/index-sync.js

@@ -16,7 +16,19 @@ import {
   M7_INDEX_POLICY_VERSION_V1,
 } from './m7-wire.js'
 
-export const INDEX_SYNC_PAGE_BUDGET_V1 = Object.freeze({ maxRecordsPerPage: 64, maxPageBytes: 256 * 1024 })
+/**
+ * ★ 页字节预算（2026-09-19 上游 PR #78 / issue #64 同步落地）。
+ *
+ * **为什么是 252KiB 而不是 256KiB**：`maxPageBytes` 只约束**页 payload**，
+ * 而 m7-wire 的 `MAX_LINE_BYTES` 是 **256KiB**，约束的是**整条线帧**（payload + 帧信封 + 换行）。
+ * 两者同为 256KiB ⇒ payload 落入约 231B 临界窗口的页 **builder 接受、线上必超限**
+ * ⇒ worker 判 `line-oversize` fail-closed 退出。
+ * 更糟的是叠加了死锁：① 熔断阈值 3，但每段 `index_sync_begin` 的成功帧把计数清零 ⇒ 峰值 2 永不熔断；
+ * ② `syncId` 由 recordCount **确定性派生** ⇒ 重试恒重建同一坏页 ⇒ 每 Segment 重生 worker、索引永不 ready。
+ *
+ * 故留 **4KiB 余量**（≈ 实测信封 202–230B 的 18 倍）。
+ */
+export const INDEX_SYNC_PAGE_BUDGET_V1 = Object.freeze({ maxRecordsPerPage: 64, maxPageBytes: 252 * 1024 })
 const SCOPE_ORDER_PRE = ['Workspace', 'User']
 
 function pagePayloadBytes(syncId, pageNo, pageCount, records) {