@a9i5k4/dsh-auto-memory 2.2.6 → 2.3.0

package/lib/l0-extract.js

@@ -0,0 +1,149 @@
+/**
+ * L0 抽取纯核心（l0_extract_v1）—— 分层语义唤回的地基。
+ *
+ * 2026-09-08 建立。目的：为每条记忆生成廉价摘要（L0），使检索可先在小空间
+ * 收敛候选，再按 id 下钻原文，从而把 token 开销与索引构建成本降约一个数量级
+ * （实测：条目平均 814 字符 → L0 约 118 字符，压缩比 6.9:1）。
+ *
+ * 组成：
+ *   1) parseMemoryItemsPre —— 按 `<!-- memory:mem_<32hex> -->` 锚点切分记忆条目
+ *   2) extractL0Pre        —— 单条记忆的 L0 抽取（三级 fallback，见下）
+ *   3) buildL0IndexPre     —— 文件级 L0 索引（确定性排序）
+ *
+ * L0 抽取优先级（零 LLM，纯解析）：
+ *   ① `## 主题块标题`   —— 已由写入侧概括，质量最好（去掉 `（HH:MM）` 后缀）
+ *   ② 首个 `- ` 条目首句 —— 去掉 `- HH:MM ` 时间戳前缀后取首句
+ *   ③ 截断兜底          —— 前 maxChars 字符
+ *   若首句过短（< minChars）则继续并接后续句子，直到达标或触顶。
+ *
+ * 边界：纯函数、零 IO、零依赖；对同输入逐字段确定；非法输入 fail closed（返回
+ * 空串/空数组），不抛异常。所有新增文本 UTF-8 无 BOM。
+ */
+
+export const L0_EXTRACT_VERSION = 'l0_extract_v1'
+
+/** 锚点：`<!-- memory:mem_<32hex> -->`（允许空白浮动）。 */
+const MEM_ANCHOR_RE = /<!--\s*memory:(mem_[0-9a-f]{32})\s*-->/g
+
+/** 行首时间戳：`12:01 ` / `14:5x ` 等（日志条目惯例）。 */
+const LEAD_TIME_RE = /^\s*\d{1,2}:\d{2}[a-z]?\s+/
+
+/** 句末/句读分隔符（含中文）。 */
+const SENTENCE_SPLIT_RE = /[。；;!！?？\n]/
+
+/** 主题块标题后缀：`（12:02）` 或 `(12:02)`。 */
+const HEADING_SUFFIX_RE = /\s*[（(]\s*\d{1,2}:\d{2}\s*[)）]\s*$/
+
+export const L0_DEFAULTS = Object.freeze({
+  maxChars: 160,
+  minChars: 15,
+  hardChars: 480,
+})
+
+const clean = (s) => String(s == null ? '' : s).replace(/\u0000/g, '').trim()
+
+/**
+ * 按锚点切分记忆条目。
+ *
+ * 约定：锚点标记**其后**的内容（实测文件结构为 `<!-- A -->内容A<!-- B -->内容B`），
+ * 因此第 i 个内容对应第 i 个锚点。锚点之前的游离内容（若有）归入 `preamble`。
+ *
+ * @param {string} text 文件内容
+ * @returns {{items: Array<{id:string, body:string}>, preamble: string, anchors: number}}
+ */
+export function parseMemoryItemsPre(text) {
+  const src = typeof text === 'string' ? text : ''
+  const items = []
+  if (!src) return { items, preamble: '', anchors: 0 }
+
+  MEM_ANCHOR_RE.lastIndex = 0
+  const marks = []
+  let m
+  while ((m = MEM_ANCHOR_RE.exec(src)) !== null) {
+    marks.push({ id: m[1], start: m.index, end: m.index + m[0].length })
+    if (m.index === MEM_ANCHOR_RE.lastIndex) MEM_ANCHOR_RE.lastIndex++
+  }
+  if (!marks.length) return { items, preamble: clean(src), anchors: 0 }
+
+  for (let i = 0; i < marks.length; i++) {
+    const from = marks[i].end
+    const to = i + 1 < marks.length ? marks[i + 1].start : src.length
+    const body = clean(src.slice(from, to))
+    if (body) items.push({ id: marks[i].id, body })
+  }
+  return { items, preamble: clean(src.slice(0, marks[0].start)), anchors: marks.length }
+}
+
+/**
+ * 抽取单条记忆的 L0。纯函数，永不抛异常。
+ *
+ * @param {string} body 条目正文
+ * @param {{maxChars?:number, minChars?:number}} opts
+ * @returns {{l0: string, source: 'heading'|'firstSentence'|'truncate'|'empty'}}
+ */
+export function extractL0Pre(body, opts = {}) {
+  const maxChars = Math.max(16, Number(opts.maxChars) || L0_DEFAULTS.maxChars)
+  const minChars = Math.max(0, Number(opts.minChars) || L0_DEFAULTS.minChars)
+  const text = clean(body)
+  if (!text) return { l0: '', source: 'empty' }
+
+  const lines = text.split(/\r?\n/)
+
+  // ① 主题块标题
+  for (const line of lines) {
+    const h = /^\s{0,3}#{1,6}\s+(.+?)\s*$/.exec(line)
+    if (h) {
+      const title = clean(h[1]).replace(HEADING_SUFFIX_RE, '')
+      if (title) return { l0: cut(title, maxChars), source: 'heading' }
+    }
+  }
+
+  // ② 首个 `- ` 条目：先取首句，过短再并接（并接时剥列表标记与时间戳）
+  for (const line of lines) {
+    const b = /^\s*[-*+]\s+(.+?)\s*$/.exec(line)
+    if (!b) continue
+    let s = clean(b[1]).replace(LEAD_TIME_RE, '')
+    if (!s) continue
+    const first = clean(s.split(SENTENCE_SPLIT_RE)[0])
+    s = growToMin(first || s, text, minChars, maxChars)
+    return { l0: cut(s, maxChars), source: 'firstSentence' }
+  }
+
+  // ③ 兜底：正文截断
+  const flat = clean(text.replace(/\s+/g, ' '))
+  return { l0: cut(flat, maxChars), source: 'truncate' }
+}
+
+/** 构建文件级 L0 索引（按 id 升序，确定性）。 */
+export function buildL0IndexPre(text, opts = {}) {
+  const { items } = parseMemoryItemsPre(text)
+  const out = items.map((it) => {
+    const r = extractL0Pre(it.body, opts)
+    return { id: it.id, l0: r.l0, source: r.source, chars: r.l0.length, bodyChars: it.body.length }
+  })
+  out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  return out
+}
+
+// ---------- 内部工具 ----------
+
+function cut(s, n) {
+  if (s.length <= n) return s
+  return s.slice(0, Math.max(1, n - 1)) + '…'
+}
+
+/** 首句过短时，并接后续句子直到 minChars 或 maxChars。每句先剥列表标记与时间戳前缀。 */
+function growToMin(first, full, minChars, maxChars) {
+  if (first.length >= minChars) return first
+  const flat = clean(full.replace(/\s+/g, ' '))
+  if (!flat || flat.length <= first.length) return first
+  const parts = flat.split(SENTENCE_SPLIT_RE)
+    .map((x) => clean(String(x).replace(/^\s*[-*+]\s+/, '').replace(LEAD_TIME_RE, '')))
+    .filter(Boolean)
+  let acc = ''
+  for (const p of parts) {
+    acc = acc ? acc + '。' + p : p
+    if (acc.length >= minChars || acc.length >= maxChars) break
+  }
+  return acc || first
+}

package/lib/l0-index.js

@@ -0,0 +1,239 @@
+/**
+ * L0 向量索引（l0_index_v1）—— 为 T1 产出的 L0 建立向量索引,供语义检索使用。
+ *
+ * 2026-09-09 建立(P1)。参照 OpenViking「Vector Index 只存 URI+向量+元数据,不含文件内容」:
+ * 每条目仅 {id, vector, l0, source, l0Hash, updatedAt},**绝不存记忆原文**。
+ *
+ * 组成(工厂 createL0IndexPre,IO 与 embedding 全注入,模块层零 fs/零模型):
+ *   1) buildFull  —— 全量建索引:buildL0IndexPre(text) × embedPassages(l0s),一次性写盘
+ *   2) update     —— 增量:逐条比 l0Hash,新增/重算/跳过/移除,仅重算变化条
+ *   3) remove     —— 显式按 ids 移除失效条目
+ *   4) load       —— fail-soft 读取:文件缺失/schema 不符/条目非法 → {ok:false, entries:[]},绝不抛
+ *   5) status     —— 索引概况(count/version/updatedAt)
+ *
+ * 身份与版本约定(沿用仓库惯例):
+ *   - l0Hash = sha256(l0),增量重算的唯一判据(l0 不变 → 跳过该条)
+ *   - l0IndexVersion = 'l0idx_' + first32hex(sha256(canonical sorted [id,l0Hash] tuples))
+ *     (前缀 l0idx_ 有意区别于 corpus 的 idx_ memoryIndexVersion,避免两套版本语义混淆)
+ *   - 向量维度由 embedder 决定(真实 C2 引擎为 384 维已归一化),本模块不硬编码维度
+ *   - 向量以纯 number 数组存盘(JSON 安全);embedder 返回 Float32Array 时经 Array.from 转换
+ *
+ * 边界:纯函数 + IO 注入、零 npm 依赖;所有 API 在边界处 fail-soft 返回 {ok:false,error},
+ * 不向调用方抛异常(不阻塞任何调用方);非法输入返回空结果。UTF-8 无 BOM。
+ */
+import { createHash } from 'node:crypto'
+import { buildL0IndexPre } from './l0-extract.js'
+
+export const L0_INDEX_VERSION = 'l0_index_v1'
+export const L0_INDEX_SCHEMA_VERSION = 1
+
+const sha256Hex = (s) => createHash('sha256').update(String(s == null ? '' : s), 'utf8').digest('hex')
+const HEX64_RE = /^[0-9a-f]{64}$/
+
+/** 规范化向量:Float32Array/number[] → 纯 number 数组;非法输入返回 null。 */
+function normalizeVector(vec) {
+  if (!(vec && (Array.isArray(vec) || vec instanceof Float32Array))) return null
+  const out = []
+  for (let i = 0; i < vec.length; i++) {
+    const n = Number(vec[i])
+    if (!Number.isFinite(n)) return null
+    out.push(n)
+  }
+  return out.length ? out : null
+}
+
+/**
+ * l0IndexVersion:canonical sorted [id,l0Hash] tuples → 'l0idx_' + first32hex(sha256)。
+ * 同内容同版本(确定性);任一条目 l0 变化或条目增删 → 版本变化。
+ */
+export function computeL0IndexVersionPre(entries) {
+  const canon = (Array.isArray(entries) ? entries : [])
+    .map((e) => [String(e && e.id) || '', String(e && e.l0Hash) || ''])
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+  return 'l0idx_' + sha256Hex(JSON.stringify(canon)).slice(0, 32)
+}
+
+/**
+ * 工厂:创建 L0 索引操作器。
+ * @param {object} opts
+ * @param {{readJson(path:any):any, writeJson(path:any, obj:any):void, exists?(path:any):boolean}} opts.io
+ *   磁盘 IO 全注入;readJson 对缺失文件应返回 null 或抛错(两种都被模块层容错)。
+ * @param {{embedPassages(texts:string[]):Promise<Float32Array[]|number[][]>}} opts.embedder
+ *   embedding 注入(真实 C2 引擎或测试假 embedder);前缀由引擎内部负责,调用方传裸文本。
+ * @param {()=>number} [opts.now] 时间注入(默认 Date.now;测试确定性用)。
+ */
+export function createL0IndexPre(opts = {}) {
+  const io = opts.io
+  const embedder = opts.embedder
+  const nowMs = () => (typeof opts.now === 'function' ? Number(opts.now()) || 0 : Date.now())
+  if (!io || typeof io.readJson !== 'function' || typeof io.writeJson !== 'function') {
+    // fail closed:工厂级配置错误直接抛(调用方组装错误,不属于运行期 fail-soft 范畴)
+    throw new Error('l0-index: io.readJson/io.writeJson required')
+  }
+
+  /** fail-soft 读取+整文件校验。任何异常/不符 → {ok:false, reason, entries:[]}。 */
+  function load({ path } = {}) {
+    try {
+      const obj = io.readJson(path)
+      if (!obj || typeof obj !== 'object') return { ok: false, reason: 'missing', entries: [] }
+      if (obj.schemaVersion !== L0_INDEX_SCHEMA_VERSION) return { ok: false, reason: 'schema', entries: [] }
+      if (typeof obj.l0IndexVersion !== 'string' || !obj.l0IndexVersion.startsWith('l0idx_')) {
+        return { ok: false, reason: 'version', entries: [] }
+      }
+      if (!Array.isArray(obj.entries)) return { ok: false, reason: 'entries', entries: [] }
+      const out = []
+      for (const e of obj.entries) {
+        if (!e || typeof e !== 'object') return { ok: false, reason: 'entry', entries: [] }
+        if (typeof e.id !== 'string' || !e.id) return { ok: false, reason: 'entry.id', entries: [] }
+        if (typeof e.l0 !== 'string') return { ok: false, reason: 'entry.l0', entries: [] }
+        if (typeof e.l0Hash !== 'string' || !HEX64_RE.test(e.l0Hash)) return { ok: false, reason: 'entry.l0Hash', entries: [] }
+        if (typeof e.source !== 'string') return { ok: false, reason: 'entry.source', entries: [] }
+        if (!Number.isFinite(Number(e.updatedAt))) return { ok: false, reason: 'entry.updatedAt', entries: [] }
+        const vec = normalizeVector(e.vector)
+        if (!vec) return { ok: false, reason: 'entry.vector', entries: [] }
+        out.push({ id: e.id, vector: vec, l0: e.l0, source: e.source, l0Hash: e.l0Hash, updatedAt: Number(e.updatedAt) })
+      }
+      return { ok: true, entries: out, l0IndexVersion: obj.l0IndexVersion, updatedAt: Number(obj.updatedAt) || 0 }
+    } catch (e) {
+      return { ok: false, reason: 'read-error', error: String(e && e.message ? e.message : e), entries: [] }
+    }
+  }
+
+  /** 由 buildL0IndexPre 的条目 + 批量 embedding 组装索引文件对象(不写盘)。 */
+  async function assemble(items, prevById) {
+    const texts = items.map((it) => it.l0)
+    const vecs = await embedder.embedPassages(texts)
+    if (!Array.isArray(vecs) || vecs.length !== items.length) {
+      throw new Error('l0-index: embedder returned ' + (Array.isArray(vecs) ? vecs.length : 'non-array') + ' vectors for ' + items.length + ' passages')
+    }
+    const ts = nowMs()
+    const entries = items.map((it, i) => {
+      const vector = normalizeVector(vecs[i])
+      if (!vector) throw new Error('l0-index: embedder produced invalid vector at index ' + i)
+      const l0Hash = sha256Hex(it.l0)
+      const prev = prevById ? prevById.get(it.id) : null
+      // 复用语义:prev 的 l0Hash 一致才整条复用(保留原 updatedAt);否则按新条处理
+      const reused = prev && prev.l0Hash === l0Hash
+      return {
+        id: it.id,
+        vector: reused ? prev.vector : vector,
+        l0: it.l0,
+        source: it.source,
+        l0Hash,
+        updatedAt: reused ? prev.updatedAt : ts,
+      }
+    })
+    entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    return {
+      schemaVersion: L0_INDEX_SCHEMA_VERSION,
+      l0IndexVersion: computeL0IndexVersionPre(entries),
+      updatedAt: ts,
+      entries,
+    }
+  }
+
+  async function writeIndex(path, fileObj) {
+    io.writeJson(path, fileObj)
+    return fileObj
+  }
+
+  return {
+    version: L0_INDEX_VERSION,
+
+    /** 全量建索引(整文件重建,所有条目重算)。返回 {ok, count, added, recomputed, removed, skipped, l0IndexVersion} 或 {ok:false, error}。 */
+    async buildFull({ path, text, maxChars, minChars } = {}) {
+      try {
+        if (!embedder || typeof embedder.embedPassages !== 'function') throw new Error('embedder.embedPassages required')
+        const items = buildL0IndexPre(typeof text === 'string' ? text : '', { maxChars, minChars })
+        const fileObj = await assemble(items, null)
+        await writeIndex(path, fileObj)
+        return {
+          ok: true, count: fileObj.entries.length, added: fileObj.entries.length,
+          recomputed: fileObj.entries.length, removed: 0, skipped: 0,
+          l0IndexVersion: fileObj.l0IndexVersion,
+        }
+      } catch (e) {
+        return { ok: false, error: String(e && e.message ? e.message : e) }
+      }
+    },
+
+    /**
+     * 增量更新:新 L0 与旧索引逐条比 l0Hash——
+     * 新增(旧无此 id)/变化(hash 不同)→ 仅这些条重算;不变 → 原样保留;消失(旧有新无)→ 移除。
+     * 旧索引损坏/非法 → fail-soft 退化为全量重建(recovered:true),不阻塞调用方。
+     */
+    async update({ path, text, maxChars, minChars } = {}) {
+      try {
+        if (!embedder || typeof embedder.embedPassages !== 'function') throw new Error('embedder.embedPassages required')
+        const prev = load({ path })
+        const recovered = !prev.ok
+        const prevById = new Map()
+        if (prev.ok) for (const e of prev.entries) prevById.set(e.id, e)
+        const items = buildL0IndexPre(typeof text === 'string' ? text : '', { maxChars, minChars })
+        // 先做哈希分类,只为计数;实际组装仍走 assemble(其内部同样按 hash 决定复用)
+        const nextById = new Map()
+        let unchanged = 0
+        let changed = 0
+        for (const it of items) {
+          const h = sha256Hex(it.l0)
+          nextById.set(it.id, h)
+          const p = prevById.get(it.id)
+          if (p && p.l0Hash === h) unchanged++
+          else changed++
+        }
+        let removed = 0
+        for (const id of prevById.keys()) if (!nextById.has(id)) removed++
+        const fileObj = await assemble(items, prevById)
+        await writeIndex(path, fileObj)
+        return {
+          ok: true,
+          count: fileObj.entries.length,
+          added: items.filter((it) => !prevById.has(it.id)).length,
+          recomputed: changed,
+          removed,
+          skipped: unchanged,
+          recovered: recovered || undefined,
+          l0IndexVersion: fileObj.l0IndexVersion,
+        }
+      } catch (e) {
+        return { ok: false, error: String(e && e.message ? e.message : e) }
+      }
+    },
+
+    /** 显式移除失效条目。ids 中不存在的自动忽略。 */
+    async remove({ path, ids } = {}) {
+      try {
+        const prev = load({ path })
+        if (!prev.ok) return { ok: false, error: 'index not loadable: ' + (prev.reason || '?'), removed: 0 }
+        const drop = new Set((Array.isArray(ids) ? ids : []).map(String))
+        const kept = prev.entries.filter((e) => !drop.has(e.id))
+        const ts = nowMs()
+        const fileObj = {
+          schemaVersion: L0_INDEX_SCHEMA_VERSION,
+          l0IndexVersion: computeL0IndexVersionPre(kept),
+          updatedAt: ts,
+          entries: kept,
+        }
+        await writeIndex(path, fileObj)
+        return {
+          ok: true,
+          removed: prev.entries.length - kept.length,
+          count: kept.length,
+          l0IndexVersion: fileObj.l0IndexVersion,
+        }
+      } catch (e) {
+        return { ok: false, error: String(e && e.message ? e.message : e), removed: 0 }
+      }
+    },
+
+    /** fail-soft 读取(见 load)。 */
+    load,
+
+    /** 索引概况(不修改任何状态)。 */
+    status({ path } = {}) {
+      const r = load({ path })
+      if (!r.ok) return { ok: false, count: 0, path, reason: r.reason }
+      return { ok: true, count: r.entries.length, path, l0IndexVersion: r.l0IndexVersion, updatedAt: r.updatedAt }
+    },
+  }
+}

package/lib/m7-wire.js

@@ -30,14 +30,14 @@ export const M7_TRANSPORT_BUDGET_V1 = Object.freeze({
   breakerCooldownMs: 30000,
 })
 
-/** JS→Python frame 类型(§7.2;index_sync_* 属 M7-1)。 */
+/** JS→Python frame 类型(§7.2;index_sync_* 属 M7-1;recall_rank 属 P13 recall C3 语义臂)。 */
 export const JS_FRAME_TYPES_V1 = Object.freeze([
   'health', 'context_push', 'index_sync_begin', 'index_sync_page', 'index_sync_commit',
-  'cancel', 'close_session',
+  'cancel', 'close_session', 'recall_rank',
 ])
 /** Python→JS frame 类型。 */
 export const PY_FRAME_TYPES_V1 = Object.freeze([
-  'health_result', 'context_ack', 'index_ack', 'activation_request', 'error',
+  'health_result', 'context_ack', 'index_ack', 'activation_request', 'error', 'recall_rank_result',
 ])
 const ALL_FRAME_TYPES = new Set([...JS_FRAME_TYPES_V1, ...PY_FRAME_TYPES_V1])
 /** 请求→响应 type 对应(cancel/close_session 刻意无响应帧)。 */
@@ -47,6 +47,7 @@ export const RESPONSE_TYPE_FOR_V1 = Object.freeze({
   index_sync_begin: 'index_ack',
   index_sync_page: 'index_ack',
   index_sync_commit: 'index_ack',
+  recall_rank: 'recall_rank_result',
 })
 
 // ========== canonical JSON(与 python/worker_v1.py 逐字节一致) ==========

package/lib/memory-importance.js

@@ -0,0 +1,70 @@
+/**
+ * memory-importance-pre —— evidence → importance 纯核心(M8-2, 2026-09-09; memory_importance_v1)。
+ *
+ * 背景(M8-2 任务书):六类证据 seen/read/cite/reuse/success/correction 已由 M5 写入
+ * (lib/context-bridge.js:45 枚举),消费侧聚合为 fact-store.js:341 evidenceFor(memoryId)
+ * → {memoryId, total, distinctSessions, seen, read, cite, reuse, success, correction},
+ * 但此前只用于 M-04 技能晋升(procedure-store.js promote),从未接入记忆检索排序。
+ *
+ * 口径纪律(禁止项):correctionRate **逐字复用** procedure-store.js:268-269 的口径——
+ *   total = seen+read+cite+reuse+success+correction
+ *   correctionRate = total > 0 ? correction / total : 0
+ * 不另立纠正口径。
+ *
+ * 公式(确定性,∈[0,1]):
+ *   neutral(无任何证据)        → importance = 0.5(中性,不置顶不垫底)
+ *   pos = 0.5×min(1, distinctSessions/3) + 0.5×min(1, (success+reuse)/4)   // 正向:跨会话多样性 + 成功/复用饱和
+ *   importance = clamp01(0.5 + 0.3×pos − 0.5×correctionRate)               // correction 负向,权重最大
+ *   值域:正向满格 → 0.8;correctionRate=1 → 0;cite/seen/read 仅稀释 correctionRate(与 promote 口径一致)。
+ *
+ * 边界:纯函数、零依赖、零 IO;非法输入 fail closed(按全零处理 → 中性);同输入逐字节确定。
+ * 本段(2026-09-09)只交付纯函数与测试,不接线——接线点检索结论:现役融合 fuseD6Pre 位于
+ * _jsDecide 的 fv2 决策 margin(非检索排序),P3 rankFusionRRFPre 未接线,shadow 管线 evidence
+ * 数据不可达;待 P3 RRF 实际接线时作为加权因子之一落点(importance 禁止作为唯一排序依据)。
+ */
+
+export const MEMORY_IMPORTANCE_VERSION = 'memory_importance_v1'
+
+/** 中性值:无 evidence 记录时返回,保证不因此置顶或垫底。 */
+export const IMPORTANCE_NEUTRAL_V1 = 0.5
+
+/** 权重常数(冻结;调整即新版本)。 */
+export const IMPORTANCE_WEIGHTS_V1 = Object.freeze({
+  diversityDivisor: 3, // distinctSessions 饱和点:≥3 个不同会话记满
+  successReuseDivisor: 4, // success+reuse 饱和点:合计 ≥4 次记满
+  posGain: 0.3, // 正向增益上限(0.5 + 0.3 = 0.8)
+  negGain: 0.5, // correctionRate 惩罚权重(负向,口径复用 promote)
+})
+
+const num0 = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0)
+const clamp01 = (x) => Math.min(1, Math.max(0, x))
+
+/**
+ * evidence 聚合 → importance ∈ [0,1]。
+ * @param {{distinctSessions?:number, seen?:number, read?:number, cite?:number,
+ *          reuse?:number, success?:number, correction?:number}} agg evidenceFor() 形状的聚合(缺字段按 0)。
+ * @returns {{importance:number, correctionRate:number, neutral:boolean, total:number}}
+ */
+export function computeImportancePre(agg) {
+  const a = agg && typeof agg === 'object' ? agg : {}
+  const seen = num0(a.seen)
+  const read = num0(a.read)
+  const cite = num0(a.cite)
+  const reuse = num0(a.reuse)
+  const success = num0(a.success)
+  const correction = num0(a.correction)
+  const distinctSessions = num0(a.distinctSessions)
+  const total = seen + read + cite + reuse + success + correction
+  // 无任何证据 → 中性(0.5):既不置顶也不垫底(验收 3)
+  if (total === 0 && distinctSessions === 0) {
+    return { importance: IMPORTANCE_NEUTRAL_V1, correctionRate: 0, neutral: true, total: 0 }
+  }
+  // correctionRate 口径与 procedure-store.js:268-269 逐字一致(禁止另立)
+  const correctionRate = total > 0 ? correction / total : 0
+  const w = IMPORTANCE_WEIGHTS_V1
+  const diversity = Math.min(1, distinctSessions / w.diversityDivisor)
+  const successReuse = Math.min(1, (success + reuse) / w.successReuseDivisor)
+  const pos = 0.5 * diversity + 0.5 * successReuse
+  const importance = clamp01(IMPORTANCE_NEUTRAL_V1 + w.posGain * pos - w.negGain * correctionRate)
+  return { importance, correctionRate, neutral: false, total }
+}

package/lib/python-setup.js

@@ -23,9 +23,11 @@ import { readFile, writeFile, rm } from 'node:fs/promises'
 
 const execFileP = promisify(execFile)
 
-/** BGE-M3 int8 单文件(与 bench 夹具同源;hf-mirror 为主源,HF 官方为备源)。 */
+/** BGE-M3 int8 单文件(与 bench 夹具同源;hf-mirror 为主源,HF 官方为备源)。
+ * 2026-09-09 修复(issue #27):repo 原为 'Xenova/bge-m3-int8'(仓库不存在→HF 恒 401),正确仓库名是 'Xenova/bge-m3';
+ * INT8 量化文件 = onnx/model_int8.onnx(568,456,694 字节,仓库清单已确认存在;fp16/q4/uint8 等非本档目标)。 */
 const MODEL_SPEC = {
-  repo: 'Xenova/bge-m3-int8',
+  repo: 'Xenova/bge-m3',
   file: 'onnx/model_int8.onnx',
   bytes: 568456694,
   sha256: '', // 见 MODEL_SHA256:远端 LFS 校验不可靠时以 size 下限+可执行性兜底;sha256 由首版发布冻结后填入
@@ -35,6 +37,10 @@ const MODEL_SPEC = {
   ],
 }
 
+/** issue #28:AutoTokenizer.from_pretrained(modelDir) 需要完整 tokenizer 套件,HF_HUB_OFFLINE=1 时 transformers
+ * 无法运行时补拉。5 文件均已确认存在于 Xenova/bge-m3 仓库根,与 model_int8.onnx 同目录下载。 */
+const TOKENIZER_FILES = ['config.json', 'tokenizer.json', 'tokenizer_config.json', 'special_tokens_map.json', 'sentencepiece.bpe.model']
+
 /** venv 内 pip 依赖:#19 实测(int8 档 encode_ids 全程 numpy+onnxruntime,tokenizer 走 Rust 快速路径)——基础集无 torch,venv 体积 ~400MB。GPU 推理开关追加 onnxruntime-gpu(CUDAExecutionProvider)。池化/精度契约冻结自 R@5 0.925 基线,fastembed 注册表无 BGE-M3 且池化契约不同,不可用。 */
 const PIP_DEPS_CPU = ['transformers', 'onnxruntime']
 const PIP_DEPS_GPU_EXTRA = ['onnxruntime-gpu']
@@ -101,7 +107,8 @@ export function createPythonSetupPre(opts = {}) {
     // 既有成果快照
     st.venvOk = existsSync(venvPython())
     st.depsOk = st.venvOk ? (await probe(venvPython(), ['-c', 'import transformers, onnxruntime, torch; print("deps-ok")'])).ok : false
-    st.modelReady = existsSync(modelPath())
+    // modelReady 判定(2026-09-09):onnx + tokenizer 5 件全齐才算就绪,避免 UI 显示 ✓ 但 sidecar 起不来
+    st.modelReady = existsSync(modelPath()) && TOKENIZER_FILES.every((f) => existsSync(path.join(modelsDir(), f)))
     st.pythons = out
     st.phase = 'idle'
     return snapshot()
@@ -188,8 +195,13 @@ export function createPythonSetupPre(opts = {}) {
         st.phase = 'verifying'
         const size = statSync(modelPath()).size
         if (size < 100 * 1024 * 1024) throw new Error('下载不完整(' + size + ' bytes)')
+        // issue #28:补下 tokenizer 套件到同目录(缺任一文件即失败,走 catch → 下一镜像)
+        for (const tf of TOKENIZER_FILES) {
+          const tu = mirror.url(MODEL_SPEC.repo + '/resolve/main/' + tf)
+          await downloadWithResume(tu, path.join(modelsDir(), tf), () => {}, () => st.cancelled)
+        }
         st.modelReady = true; st.phase = 'ready'
-        diagOf('python-setup: model ready at ' + modelPath() + ' (' + size + ' bytes, mirror=' + mirror.id + ')')
+        diagOf('python-setup: model+tokens ready at ' + modelsDir() + ' (model=' + size + ' bytes, mirror=' + mirror.id + ')')
         return snapshot()
       } catch (e) {
         if (st.cancelled) { st.phase = 'idle'; return snapshot() }

package/lib/recall-fusion.js

@@ -0,0 +1,99 @@
+/**
+ * recall-fusion-pre —— rank-space 融合(P3, 2026-09-09; rrf_fusion_v1)。
+ *
+ * 背景:旧 fuseD6Pre(semantic-js.js)为 minmax 加权融合,存在三宗罪:
+ *   ① 分数随候选集漂移(归一化域=当前候选集) ② 矮子里拔将军(零极差臂全员 0.5)
+ *   ③ 候选 ≤1 时退化为常数 0.5(排序失效)。
+ * 本模块提供 **rank-space RRF** 并存实现(不替换 fuseD6Pre,由调用方按需选用):
+ *   score = Σ_arms 1/(k + rank/divisor),k=60(Hindsight issue #3956 实测安全值)。
+ *
+ * 决策/排序解耦(验收 1):融合分数**只用于排序**;"是否注入"的决策必须使用
+ * 绝对分数(如 rank.scores 的稠密余弦)与校准阈值比较 —— rank-space 分数本身
+ * 仍是候选集内的相对量,不承担决策职责。
+ *
+ * 边界:纯函数、零依赖、零 IO;非法输入 fail closed 返回空数组;确定性
+ * (同输入同输出;同分按 memoryId 升序)。无 score-space 加权(禁止项);无父分数传播。
+ */
+
+/** RRF 常数 k(Hindsight issue #3956 实测: k=60 时动态范围安全,加权会退化排序)。 */
+export const FUSION_RRF_K_V1 = 60
+
+/** rank 尺度常数:rank/divisor 把秩归到 (0,1] 量级(默认与 k 同值)。 */
+export const FUSION_RRF_DIVISOR_V1 = 60
+
+/** 版本标识。 */
+export const RECALL_FUSION_VERSION = 'rrf_fusion_v1'
+
+/**
+ * rank-space RRF 融合。
+ *
+ * @param {Array<{memoryId:string, dense?:number|null, lex?:number|null}>} pairs
+ *   与 fuseD6Pre 同形:两臂分数可缺失(null/undefined/非有限数视为该臂缺席)。
+ * @param {{k?:number, divisor?:number}} [opts] 可覆盖 k 与 divisor(默认均 60)。
+ * @returns {Array<{memoryId:string, fused:number, rrfDense:number, rrfLex:number,
+ *   denseRaw:number|null, lexRaw:number|null, rankDense:number|null, rankLex:number|null}>}
+ *   按 fused 降序、平局 memoryId 升序(确定性)。原始分数逐条保留供审计。
+ *
+ * 性质:
+ *   - 候选 <3(含单候选)不退化:每条 fused = 1/(k + rank/divisor),良定义非常数
+ *   - 候选集增删只平移秩,不改既有条目的相对序(rank-space 关键性质,minmax 不具备)
+ *   - 缺失臂贡献 0(不是 minmax 的 0.5)
+ */
+export function rankFusionRRFPre(pairs, opts = {}) {
+  const k = Number.isFinite(opts.k) && opts.k >= 0 ? opts.k : FUSION_RRF_K_V1
+  const divisor = Number.isFinite(opts.divisor) && opts.divisor > 0 ? opts.divisor : FUSION_RRF_DIVISOR_V1
+  const list = Array.isArray(pairs) ? pairs.filter((p) => p && typeof p.memoryId === 'string') : []
+
+  // 每臂独立排名:非空有限值按分数降序(平局 memoryId 升序)取秩(1 起);缺席者无秩。
+  const rankArm = (key) => {
+    const entries = []
+    for (const p of list) {
+      const v = p[key]
+      if (typeof v === 'number' && Number.isFinite(v)) entries.push({ memoryId: p.memoryId, v })
+    }
+    entries.sort((a, b) => (b.v !== a.v ? b.v - a.v : (a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0)))
+    const ranks = new Map()
+    entries.forEach((e, i) => ranks.set(e.memoryId, i + 1))
+    return ranks
+  }
+  const denseRanks = rankArm('dense')
+  const lexRanks = rankArm('lex')
+
+  // 时间臂(P12 后新增,2026-09-09):可选第三臂。temp 为 1(命中时间范围)/0(未命中)/
+  // 缺失(无时间臂或非日期来源)。所有 pair 均缺 temp **或 temp 全相等**(全 0/全 1)→
+  // 不构建 temp 秩,行为与两臂版逐字节一致(fused 不加 0 项、输出对象不含新字段)——
+  // 全 0 = 查询有时间表达但无候选命中,必须零扰动。rank-space,禁止 score-space 加权(#3956)。
+  const temps = []
+  for (const p of list) { if (typeof p.temp === 'number' && Number.isFinite(p.temp)) temps.push(p.temp) }
+  const hasTemp = temps.length > 0 && temps.some((v) => v !== temps[0])
+  const tempRanks = hasTemp ? rankArm('temp') : null
+
+  return list
+    .map((p) => {
+      const rd = denseRanks.get(p.memoryId)
+      const rl = lexRanks.get(p.memoryId)
+      const rrfDense = rd === undefined ? 0 : 1 / (k + rd / divisor)
+      const rrfLex = rl === undefined ? 0 : 1 / (k + rl / divisor)
+      const base = {
+        memoryId: p.memoryId,
+        fused: rrfDense + rrfLex,
+        rrfDense,
+        rrfLex,
+        denseRaw: typeof p.dense === 'number' && Number.isFinite(p.dense) ? p.dense : null,
+        lexRaw: typeof p.lex === 'number' && Number.isFinite(p.lex) ? p.lex : null,
+        rankDense: rd === undefined ? null : rd,
+        rankLex: rl === undefined ? null : rl,
+      }
+      if (!hasTemp) return base
+      const rt = tempRanks.get(p.memoryId)
+      const rrfTemp = rt === undefined ? 0 : 1 / (k + rt / divisor)
+      return {
+        ...base,
+        fused: rrfDense + rrfLex + rrfTemp,
+        rrfTemp,
+        tempRaw: typeof p.temp === 'number' && Number.isFinite(p.temp) ? p.temp : null,
+        rankTemp: rt === undefined ? null : rt,
+      }
+    })
+    .sort((x, y) => (y.fused !== x.fused ? y.fused - x.fused : (x.memoryId < y.memoryId ? -1 : x.memoryId > y.memoryId ? 1 : 0)))
+}

package/lib/shadow-retrieval.js

@@ -242,8 +242,8 @@ export function buildQueryPlan(snapshot, opts = {}) {
       seenTerms.set(t, { term: t, weight: wgt, origin })
     }
   }
-  // 排序稳定:按 term 字典序
-  const terms = [...seenTerms.values()].sort((a, b) => (a.term < b.term ? -1 : a.term > b.term ? 1 : 0))
+  // P12 排序:weight 降序优先(截断保高权重词),term 字典序升序作稳定 tiebreak;截断逻辑与 truncated 标记不变
+  const terms = [...seenTerms.values()].sort((a, b) => (b.weight - a.weight) || (a.term < b.term ? -1 : a.term > b.term ? 1 : 0))
   let truncated = false
   if (terms.length > SHADOW_LEXICAL_BUDGET_V1.queryTerms) {
     terms.length = SHADOW_LEXICAL_BUDGET_V1.queryTerms