@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/degrade.js

@@ -0,0 +1,385 @@
+/**
+ * degrade.js · 降级留痕层（R3，2026-09-18）
+ *
+ * ── 要解决的问题 ──────────────────────────────────────────────
+ * 全仓普查发现 70 处 `catch` 只写 diag 不抛出，其中 10 处自述为「降级/回退/中性」。
+ * 检索链上**四条臂各自独立降级、各自静默** ⇒ 可同时失效而使用者只感到「检索不太对」。
+ * 实证案例（R2）：evidence 读侧误判目录缺失 ⇒ importance 加权对某类用户**出厂即死**，
+ * 而表现只是每次 recall 写一行 diag。
+ *
+ * ── 定性 ─────────────────────────────────────────────────────
+ * fail-soft 本身是对的（记忆插件不得拖垮会话）。**缺陷在「降级不可见」**。
+ * 本模块不是要消灭降级，而是让「**哪条臂没在工作**」从推断变成**可查询的状态**。
+ *
+ * ── 与既有机制的边界（2026-09-18 前置检查已证实无重复）──────
+ *   · `diag()`        = 过程日志（滚动、即时、人读）—— **保留不变**
+ *   · `debugView()`   = 各 host 的**局部**状态投影（7 处，彼此分散）
+ *   · `degrade`（本模块）= **跨臂统一台账**（聚合、可查询、回答"哪条臂失效"）
+ *   · `_lastIndexDegrade`（context-host.js:112）= 单值兼容投影，非收集器
+ *
+ * ── 判据（R1/R2 得出，本模块的最高纪律）──────────────────────
+ * **必须区分两类，绝不能一律报，否则噪音淹没信号**：
+ *   · **预期内分支**：该状态是合法业务状态（无证据事件 / 查询无时间表达）⇒ **静默，不记**
+ *   · **预期外失败**：该状态不该发生（引擎抛错 / 目录异常 / worker 拒绝）⇒ **记**
+ * 例：`parseTemporalQueryPre` 返回 null（查询含无时间表达）是预期内 ⇒ 不记；
+ *     但它**抛错**是预期外 ⇒ 记。调用方须把"返回 null"与"抛错"分开。
+ *
+ * ── 元规则（本模块自身的 fail-soft）──────────────────────────
+ * **留痕失败绝不可导致二次失败**：`record()` 内部整体 try/catch 吞掉一切。
+ * 宁可丢掉一条留痕，也绝不能因为留痕而打断检索。
+ */
+
+/** 身份常量（枚举类常量须配断言兜底 —— 本仓纪律）。 */
+export const DEGRADE_SCHEMA_V1 = 'degrade_v1'
+
+/** 环形缓冲上限：防内存无界增长。 */
+export const DEGRADE_CAP_V1 = 200
+
+/** 单条 reason 截断长度：与既有 diag 同口径，且防长文本撑爆状态文件。 */
+export const DEGRADE_REASON_MAX_V1 = 200
+
+/**
+ * 臂状态枚举（fail-closed 校验）。
+ * - `active`    正常工作
+ * - `no-input`  无输入（**合法状态**，如尚无证据事件 / 查询无时间表达）
+ * - `degraded`  已降级（**预期外**，值应能在 counts 里找到对应 kind）
+ * - `disabled`  被配置关闭
+ * - `unknown`   无法判定（**不得**当作正常，面板应显式呈现）
+ */
+export const ARM_STATES_V1 = Object.freeze(['active', 'no-input', 'degraded', 'disabled', 'unknown'])
+
+/** 已知降级 kind（仅作文档/断言用，**不限制**调用方传入新 kind）。 */
+export const DEGRADE_KINDS_V1 = Object.freeze([
+  'semantic-arm',   // 语义臂择优失败 → 回退词法
+  'evidence-arm',   // evidence 聚合失败 → importance 中性
+  'l0-sync',        // L0 索引同步失败 → 索引陈旧
+])
+
+/**
+ * 创建降级台账。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.cap]  环形缓冲上限
+ * @param {Function} [opts.now] 取时函数（注入便于测试确定性）
+ */
+export function createDegradeSinkPre(opts = {}) {
+  const cap = Number.isFinite(opts.cap) && opts.cap > 0 ? Math.floor(opts.cap) : DEGRADE_CAP_V1
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now()
+
+  /** @type {Map<string, number>} kind → 累计次数（不受环形淘汰影响） */
+  const counts = new Map()
+  /** @type {Array<{kind:string,reason:string,at:number}>} 最近条目（有界） */
+  let recent = []
+  /** 因超出 cap 而被淘汰的条数（保证"有界"这件事本身可见，不静默丢数据） */
+  let evicted = 0
+
+  /**
+   * 记录一次降级。**只用于预期外失败**（预期内分支请勿调用，直接静默）。
+   * 内部整体 fail-soft：任何异常都被吞掉，调用方无需 try/catch。
+   */
+  function record(kind, reason) {
+    try {
+      const k = String(kind == null ? 'unknown' : kind)
+      counts.set(k, (counts.get(k) || 0) + 1)
+      if (recent.length >= cap) { recent.shift(); evicted += 1 }
+      recent.push({
+        kind: k,
+        reason: String(reason == null ? '' : reason).slice(0, DEGRADE_REASON_MAX_V1),
+        at: now(),
+      })
+    } catch (_) { /* 元规则：留痕失败不得影响主流程 */ }
+  }
+
+  /** 读快照（不可变副本，防外部改内部状态）。 */
+  function snapshot() {
+    let out
+    try {
+      out = {
+        schemaVersion: DEGRADE_SCHEMA_V1,
+        updatedAt: new Date(now()).toISOString(),
+        counts: Object.fromEntries(counts),
+        recent: recent.map((r) => ({ ...r, at: new Date(r.at).toISOString() })),
+        evicted,
+        cap,
+      }
+    } catch (_) {
+      // 快照失败也要给出**结构性合法**的最小对象，不能让读取方拿到 undefined
+      out = { schemaVersion: DEGRADE_SCHEMA_V1, updatedAt: null, counts: {}, recent: [], evicted, cap }
+    }
+    return out
+  }
+
+  /** 某 kind 的累计次数（断言友好）。 */
+  function countOf(kind) { try { return counts.get(String(kind)) || 0 } catch (_) { return 0 } }
+
+  /** 是否发生过任何降级。 */
+  function isEmpty() { return counts.size === 0 }
+
+  function reset() { counts.clear(); recent = []; evicted = 0 }
+
+  return { record, snapshot, countOf, isEmpty, reset, _capForTest: cap }
+}
+
+/**
+ * 派生**臂健康快照**（E-3 落地）。
+ *
+ * 这不是"降级记录"，而是**状态陈述** —— 目的是让「某条臂没在工作」可见，
+ * 而不必靠"每次 recall 都报错"来推断。例：`evidence: 'no-input'` 一眼可见。
+ *
+ * @param {Record<string, string>} states 臂名 → 状态（须属 ARM_STATES_V1；非法值归一为 'unknown'）
+ */
+export function deriveArmsHealthPre(states) {
+  const out = {}
+  try {
+    for (const [arm, st] of Object.entries(states || {})) {
+      const s = String(st == null ? '' : st)
+      out[String(arm)] = ARM_STATES_V1.includes(s) ? s : 'unknown'
+    }
+  } catch (_) { /* fail-soft */ }
+  return out
+}
+
+/**
+ * R3-②（2026-09-18）：把台账**落盘**为可查询状态文件。
+ *
+ * 形态选择：**读驱动写**（由 `debugInfo()` 调用），不引入定时器、不新增常驻任务。
+ * 理由：① 降级是低频事件，无需实时落盘；② 用户查看诊断时正是"想知道发生了什么"的时刻，
+ * 此刻把最新快照写到磁盘 —— 既满足"可查询"，又不增加空闲期 IO。
+ *
+ * ★ 与 record/snapshot 同一条元规则：**落盘失败绝不可影响调用方**
+ *   —— 全程 try/catch，返回布尔而非抛错（调用方无需自行兜底）。
+ *
+ * @param {object} p
+ * @param {string} p.file            目标 JSON 文件绝对路径
+ * @param {object} p.snapshot        已算好的快照（通常来自 sink.snapshot()）
+ * @param {Function} [p.mkdirSync]   注入的 fs.mkdirSync（便于测试与解耦）
+ * @param {Function} [p.writeFileSync] 注入的 fs.writeFileSync
+ * @returns {boolean} 是否成功写入（失败返回 false，**不抛**）
+ */
+export function persistDegradeLedgerPre(p) {
+  try {
+    const { file, snapshot, mkdirSync, writeFileSync } = p || {}
+    if (!file || typeof file !== 'string') return false
+    if (typeof mkdirSync !== 'function' || typeof writeFileSync !== 'function') return false
+    const dir = file.replace(/[\\/][^\\/]*$/, '')
+    if (dir) mkdirSync(dir, { recursive: true })
+    writeFileSync(file, JSON.stringify(snapshot, null, 2), 'utf8')
+    return true
+  } catch (_) {
+    // 元规则：留痕层自身的持久化失败，绝不可打断 debugInfo / 检索主流程。
+    return false
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════
+// R4（2026-09-18）· 配额测量闭环
+// ══════════════════════════════════════════════════════════════════════
+//
+// ── 要解决的问题（用户原话）──────────────────────────────────────────
+// 「配额这个问题也困扰我很久。有的时候配额太少，效果完全没有，或者有些大条目可能就被过滤掉了，
+//   一点用都没有；有的时候配额多了，我又怕浪费 token」
+// 「确实得基于长期的观察，科学的（测量），不能拍脑子。」
+//
+// ── 为什么放在本模块（而不是新建一个文件）──────────────────────────────
+// S10.4「不新建状态源」：配额观测与降级台账**同属"跨轮可查询的观测面"**，
+// 只是两个不同的消费者。故复用同一模块、同一落盘文件（多一个 `quota` 键），
+// **不新增文件、不新增配置键、不新增常驻任务**。
+//
+// ── 与降级台账的判据边界（务必不要混）──────────────────────────────────
+//   · `record(kind, reason)` = **预期外失败**（引擎抛错、目录异常…）—— 只记异常
+//   · `observe(meta)`（本函数）= **常规业务观测**（本轮各层进了多少、丢了多少）—— 每轮都记
+//   把常规观测塞进 `record` 会**污染降级判据**（"有没有降级"将永远为非空），
+//   故两者**并列而不混用**：各自的 counts/recent 互不干扰。
+
+/** 配额探针的身份常量（枚举类常量须配断言兜底 —— 本仓纪律）。 */
+export const QUOTA_PROBE_SCHEMA_V1 = 'quota_probe_v1'
+
+/** 采样环上限：与降级台账同口径（有界，防内存无界增长）。 */
+export const QUOTA_PROBE_CAP_V1 = 200
+
+/**
+ * 配额判定结论枚举（fail-closed 校验）。
+ * - `under-quota`        某层被反复丢弃 ⇒ 配额偏小，该层内容进不来
+ * - `over-quota`         各层都不丢且远未用满 ⇒ 配额偏大，白花 token
+ * - `balanced`           既有丢弃但未持续、占用也合理
+ * - `insufficient-data`  **样本不足，不猜**（这是默认值 —— 宁可说不知道）
+ */
+export const QUOTA_VERDICTS_V1 = Object.freeze(['under-quota', 'over-quota', 'balanced', 'insufficient-data'])
+
+/** 判定阈值（集中声明，便于断言锁定与后续按观测调参）。 */
+export const QUOTA_THRESHOLDS_V1 = Object.freeze({
+  /** 至少这么多轮采样才敢下结论（少于它一律 insufficient-data）。 */
+  minSamples: 8,
+  /** 某层"出现丢弃"的轮数占比 ≥ 此值 ⇒ under-quota。 */
+  dropRateForUnder: 0.5,
+  /** 各层都不丢时，token 占用率 < 此值 ⇒ over-quota（远未用满）。 */
+  usageForOver: 0.5,
+})
+
+/**
+ * 创建**配额探针**：有界收集每轮 `tier0Meta` 的配额相关切片。
+ *
+ * 与降级台账同一元规则：**观测失败绝不可影响主流程**（全程 try/catch，返回布尔不抛）。
+ * 只保留判据所需字段（不整份存 tier0Meta），隐私面与降级台账一致（无正文、无路径）。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.cap] 采样环上限
+ * @param {Function} [opts.now] 取时函数（注入便于测试确定性）
+ */
+export function createQuotaProbePre(opts = {}) {
+  const cap = Number.isFinite(opts.cap) && opts.cap > 0 ? Math.floor(opts.cap) : QUOTA_PROBE_CAP_V1
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now()
+  /** @type {Array<object>} 最近采样（有界） */
+  let samples = []
+  /** 因超上限被淘汰的条数（"有界"这件事本身可见，不静默丢数据） */
+  let evicted = 0
+
+  function observe(meta) {
+    try {
+      if (!meta || typeof meta !== 'object') return false
+      const perLayer = {}
+      const src = meta.perLayer
+      if (src && typeof src === 'object') {
+        for (const [layer, m] of Object.entries(src)) {
+          if (!m || typeof m !== 'object') continue
+          perLayer[String(layer)] = {
+            candidates: Number(m.candidates) || 0,
+            picked: Number(m.picked) || 0,
+            dropped: Number(m.dropped) || 0,
+            tokens: Number(m.tokens) || 0,
+            cap: m.cap == null ? null : Number(m.cap),
+          }
+        }
+      }
+      if (samples.length >= cap) { samples.shift(); evicted += 1 }
+      samples.push({
+        at: now(),
+        tokens: Number(meta.tokens) || 0,
+        maxTokens: Number(meta.maxTokens) || 0,
+        items: Number(meta.items) || 0,
+        candidates: Number(meta.candidates) || 0,
+        dropped: Number(meta.dropped) || 0,
+        perLayer,
+      })
+      return true
+    } catch (_) { return false }
+  }
+
+  function snapshot() {
+    let out
+    try {
+      out = {
+        schemaVersion: QUOTA_PROBE_SCHEMA_V1,
+        updatedAt: new Date(now()).toISOString(),
+        samples: samples.map((s) => ({ ...s, at: new Date(s.at).toISOString(), perLayer: { ...s.perLayer } })),
+        evicted,
+        cap,
+      }
+    } catch (_) {
+      // 快照失败也要给出**结构性合法**的最小对象，不能让读取方拿到 undefined
+      out = { schemaVersion: QUOTA_PROBE_SCHEMA_V1, updatedAt: null, samples: [], evicted, cap }
+    }
+    return out
+  }
+
+  function reset() { samples = []; evicted = 0 }
+
+  return { observe, snapshot, reset, _capForTest: cap }
+}
+
+/**
+ * 从配额探针快照**推导判定结论**（R4 · 纯函数、零 IO、永不抛）。
+ *
+ * 这是「科学测量」的判据落点 —— 用户要求**不能拍脑袋**，所以：
+ *   · 样本不足 ⇒ 一律 `insufficient-data`（**不猜**，这是默认值）；
+ *   · 某层**持续**被丢 ⇒ `under-quota`（该层内容长期进不来 ⇒ 配额偏小）；
+ *   · 各层都不丢、且 token **远未用满** ⇒ `over-quota`（配额偏大、白花 token）；
+ *   · 其余 ⇒ `balanced`。
+ *
+ * ★ 判据纪律（本仓）：**宁可漏判，不可误伤** —— 阈值取保守值，
+ *   且把"凭什么这么判"的原始数据（dropRate/perLayer/usage）一并返回，供人复核。
+ *
+ * @param {object} snap `createQuotaProbePre().snapshot()` 的产物
+ * @param {object} [opts] 覆盖阈值（默认取 QUOTA_THRESHOLDS_V1）
+ * @returns {{version:string, verdict:string, samples:number, dropRate:number,
+ *            usage:number, perLayer:object, reasons:string[]}}
+ */
+export function deriveQuotaVerdictPre(snap, opts = {}) {
+  const th = { ...QUOTA_THRESHOLDS_V1, ...(opts || {}) }
+  const base = {
+    version: 'quota_verdict_v1',
+    verdict: 'insufficient-data',
+    samples: 0,
+    dropRate: 0,
+    usage: 0,
+    perLayer: {},
+    reasons: [],
+  }
+  try {
+    const list = snap && Array.isArray(snap.samples) ? snap.samples : []
+    base.samples = list.length
+    if (!list.length) { base.reasons.push('无采样'); return base }
+
+    // 逐层聚合：出现丢弃的轮数 / token 占用 / 候选与命中
+    const agg = {}
+    let tokSum = 0, maxSum = 0
+    for (const s of list) {
+      tokSum += Number(s.tokens) || 0
+      maxSum += Number(s.maxTokens) || 0
+      const pl = s && s.perLayer && typeof s.perLayer === 'object' ? s.perLayer : {}
+      for (const [layer, m] of Object.entries(pl)) {
+        if (!agg[layer]) agg[layer] = { rounds: 0, dropRounds: 0, candidates: 0, picked: 0, dropped: 0, tokens: 0 }
+        const a = agg[layer]
+        a.rounds += 1
+        if ((Number(m.dropped) || 0) > 0) a.dropRounds += 1
+        a.candidates += Number(m.candidates) || 0
+        a.picked += Number(m.picked) || 0
+        a.dropped += Number(m.dropped) || 0
+        a.tokens += Number(m.tokens) || 0
+      }
+    }
+    for (const [layer, a] of Object.entries(agg)) {
+      base.perLayer[layer] = {
+        rounds: a.rounds,
+        dropRounds: a.dropRounds,
+        dropRate: a.rounds ? Number((a.dropRounds / a.rounds).toFixed(3)) : 0,
+        candidates: a.candidates,
+        picked: a.picked,
+        dropped: a.dropped,
+      }
+    }
+    base.usage = maxSum > 0 ? Number((tokSum / maxSum).toFixed(3)) : 0
+
+    // ★ 样本不足 ⇒ 不猜（用户要的是"基于长期观察"，不是几轮就下结论）
+    if (list.length < th.minSamples) {
+      base.reasons.push('样本不足（' + list.length + '/' + th.minSamples + '），不下结论')
+      return base
+    }
+
+    // 某层长期被丢 ⇒ 该层配额偏小
+    const underLayers = Object.entries(base.perLayer)
+      .filter(([, a]) => a.rounds > 0 && a.dropRate >= th.dropRateForUnder)
+      .map(([l]) => l)
+    if (underLayers.length) {
+      base.verdict = 'under-quota'
+      base.reasons.push('层 ' + underLayers.join('/') + ' 持续被丢（dropRate ≥ ' + th.dropRateForUnder + '）⇒ 配额偏小')
+      return base
+    }
+
+    // 各层都不丢 + token 远未用满 ⇒ 配额偏大（浪费）
+    if (base.usage < th.usageForOver) {
+      base.verdict = 'over-quota'
+      base.reasons.push('无任何层被丢，且 token 占用率 ' + base.usage + ' < ' + th.usageForOver + ' ⇒ 配额偏大、白花 token')
+      return base
+    }
+
+    base.verdict = 'balanced'
+    base.reasons.push('有丢弃但未持续，且占用率 ' + base.usage + ' 合理')
+    return base
+  } catch (_) {
+    // 判定失败也要给出**结构性合法**的对象（verdict 保持 insufficient-data，不猜）
+    base.reasons.push('判定异常，按样本不足处理')
+    return base
+  }
+}
+

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/engine-identity.js

@@ -0,0 +1,149 @@
+/**
+ * 引擎身份（engine_identity_v1）—— P2「引擎隔离」的地基（V2-P2 卡 / 评审 §3.5）。
+ *
+ * 为什么需要它（权威依据）：
+ *   V2-P2 卡明确指出：单个 `PROVIDER_ID_INT8`（`python-setup.js:55`）**不足以**标识
+ *   模型内容 / tokenizer / 预处理；两层缓存若只凭 `chunkId` 或**裸输入哈希**读取，
+ *   **仍会串用两套向量**（e5 384 维与 bge-m3 1024 维混进同一次排序 = T2-9 判失败）。
+ *   因此身份必须够宽，至少覆盖：
+ *     模型与权重摘要 · tokenizer 版本 · 精度格式 · 维度 · 池化 · 归一化 · 输入处理版本。
+ *
+ * 本模块只做三件事（纯函数、零 IO、零依赖，便于宿主与测试共用）：
+ *   1) `computeEngineIdentityPre(desc)` —— 宽身份描述 → 稳定身份串 `engid_<32hex>`
+ *      （canonical 排序 JSON + sha256，同输入逐字节同输出；任一字段变化 → 身份必变）。
+ *   2) `aliasKeyPre(engineIdentity, chunkId)` —— 两级引用的**第一级**：
+ *      `engineIdentity + chunkId → alias`。记录变化导致未改块重新编号（chunkId 变）时，
+ *      只更新 alias，**不重新编码相同输入**（不改现有 chunkId 公式）。
+ *   3) `vectorKeyPre(engineIdentity, exactEncoderInput)` —— **第二级**：
+ *      `alias → hash(exactEncoderInput) → 向量对象`。相同输入且相同引擎 ⇒ 同一向量对象，
+ *      可直接复用；引擎不同 ⇒ vectorKey 必不同 ⇒ 不可能跨引擎串用（T2-9 的零成本实现）。
+ *
+ * 成本口径（评审 §3.5 采纳的措辞，不得写「成本为零」）：
+ *   **身份比较开销小；全量重建成本由本机承担。**
+ *
+ * UTF-8 无 BOM。
+ */
+import { createHash } from 'node:crypto'
+
+export const ENGINE_IDENTITY_VERSION = 'engine_identity_v1'
+
+/** 身份串前缀：有意与 corpus 的 `idx_` / L0 的 `l0idx_` 区分，避免三套版本语义混淆。 */
+export const ENGINE_IDENTITY_PREFIX = 'engid_'
+
+/** 身份必须覆盖的字段（缺一即身份不完整；缺失字段按空串参与哈希，不给"省略=通过"的口子）。 */
+export const ENGINE_IDENTITY_FIELDS = Object.freeze([
+  'provider',        // 通道/提供方标识（如 bge-m3-onnx-int8-v1 / js-e5-small-q8-v1）
+  'model',           // 模型名（如 bge-m3 / multilingual-e5-small）
+  'weightsDigest',   // 权重摘要（sha256 或廉价指纹；见 weightsDigestOfFilePre 的口径说明）
+  'tokenizer',       // tokenizer 版本/来源（如 xenova-bge-m3-fast / e5-small-tokenizer-v1）
+  'precision',       // 精度格式（int8 / q8 / fp32）
+  'dim',             // 向量维度（384 / 1024）
+  'pooling',         // 池化方式（cls / mean）
+  'normalized',      // 是否已归一化（true/false）
+  'inputVersion',    // 输入处理版本（前缀、截断、清洗等预处理口径）
+])
+
+const sha256Hex = (s) => createHash('sha256').update(String(s == null ? '' : s), 'utf8').digest('hex')
+
+/**
+ * 规范化身份描述：只保留白名单字段，值统一为字符串（数字/布尔 canonical 化），
+ * 键按固定顺序（ENGINE_IDENTITY_FIELDS，而非字母序）序列化 —— 顺序固定 = 哈希稳定。
+ */
+export function canonicalEngineDescPre(desc) {
+  const d = desc && typeof desc === 'object' ? desc : {}
+  const out = {}
+  for (const k of ENGINE_IDENTITY_FIELDS) {
+    const v = d[k]
+    if (v === null || v === undefined) { out[k] = ''; continue }
+    if (typeof v === 'boolean') { out[k] = v ? 'true' : 'false'; continue }
+    if (typeof v === 'number') { out[k] = Number.isFinite(v) ? String(v) : ''; continue }
+    out[k] = String(v)
+  }
+  return out
+}
+
+/**
+ * 宽身份计算：canonical 描述 → `engid_<first32hex(sha256)>`。
+ * 任一字段（含维度、精度、tokenizer、输入版本）变化 → 身份必变；同输入确定性。
+ */
+export function computeEngineIdentityPre(desc) {
+  const canon = canonicalEngineDescPre(desc)
+  return ENGINE_IDENTITY_PREFIX + sha256Hex(JSON.stringify(canon)).slice(0, 32)
+}
+
+/** 身份合法性：必须是本模块产出的前缀形态（防把任意字符串当身份塞进缓存）。 */
+export function isEngineIdentityPre(x) {
+  return typeof x === 'string' && /^engid_[0-9a-f]{32}$/.test(x)
+}
+
+/** 两个身份是否同一引擎。非法的身份一律视为不匹配（fail closed：宁可重建，不冒串用风险）。 */
+export function engineIdentityMatchesPre(a, b) {
+  if (!isEngineIdentityPre(a) || !isEngineIdentityPre(b)) return false
+  return a === b
+}
+
+/**
+ * 第一级引用：`engineIdentity + chunkId → aliasKey`。
+ * 用途：记录内容变化 → memoryId/recordDigest 变化 → chunkId 变；此键随引擎与 chunkId 走，
+ * 是"记录 → 向量"的可更新指针（记录重编号时只改这一层）。
+ */
+export function aliasKeyPre(engineIdentity, chunkId) {
+  return String(engineIdentity || '') + '|' + String(chunkId == null ? '' : chunkId)
+}
+
+/**
+ * 第二级引用：`engineIdentity + exactEncoderInput → vectorKey`。
+ * exactEncoderInput = **真正送进编码器的文本**（含引擎内部前缀之后的形态；调用方负责给出
+ * 与编码器输入一致的字符串）。相同引擎 + 相同输入 ⇒ 相同 vectorKey ⇒ 复用向量对象。
+ * 该键不含 chunkId，因此**块重新编号不会导致重复编码**（T2-2 的核心）。
+ */
+export function vectorKeyPre(engineIdentity, exactEncoderInput) {
+  return String(engineIdentity || '') + '|' + sha256Hex(exactEncoderInput)
+}
+
+/**
+ * 权重摘要的**廉价指纹**（性能口径，必须如实标注）：
+ * 对 2GB 级 onnx 做全量 sha256 代价过高，这里用 `size:mtimeMs:文件名` 的 sha256 作为
+ * **权重变更指纹**（同一份权重稳定、文件被替换/重下必变）。
+ * 说明：这是**指纹（fingerprint）而非内容摘要（digest）**；要真摘要需在切换时一次性计算
+ * 并落盘缓存（P4 若需要再补），本阶段不引入 2GB 级读盘开销。
+ */
+export function weightsDigestOfFilePre(stat, name) {
+  const size = Number(stat && stat.size) || 0
+  const mtime = Number(stat && (stat.mtimeMs != null ? stat.mtimeMs : stat.mtime)) || 0
+  return 'fp_' + sha256Hex(size + ':' + mtime + ':' + String(name == null ? '' : name)).slice(0, 32)
+}
+
+/** 端侧 JS 引擎（e5-small q8，384 维已归一化）的规范身份描述。 */
+export const JS_E5_IDENTITY_DESC_V1 = Object.freeze({
+  provider: 'js-e5-small-q8-v1',
+  model: 'multilingual-e5-small',
+  weightsDigest: 'manifest-e5-small-q8-v1', // 端侧资产清单版本；模型文件摘要由下载清单锁定
+  tokenizer: 'e5-small-tokenizer-v1',
+  precision: 'q8',
+  dim: 384,
+  pooling: 'mean',
+  normalized: true,
+  inputVersion: 'e5-passage-prefix-v1', // 引擎内部加 `passage: ` 前缀（见 semantic-js.js:351 注释）
+})
+
+/** Python 引擎（bge-m3 onnx int8，1024 维）的身份描述构造器（weightsDigest 由调用方给指纹）。 */
+export function pyBgeM3IdentityDescPre(weightsDigest) {
+  return {
+    provider: 'bge-m3-onnx-int8-v1',
+    model: 'bge-m3',
+    weightsDigest: weightsDigest || '',
+    tokenizer: 'xenova-bge-m3-fast',
+    precision: 'int8',
+    dim: 1024,
+    pooling: 'cls',
+    normalized: true,
+    inputVersion: 'bge-m3-raw-v1',
+  }
+}
+
+/** 供诊断/测试的最小投影（不泄内容：只有身份串与字段读数）。 */
+export function describeEngineIdentityPre(desc) {
+  const canon = canonicalEngineDescPre(desc)
+  return { identity: computeEngineIdentityPre(desc), fields: canon, version: ENGINE_IDENTITY_VERSION }
+}