@avantf/dsh-mem 0.6.2 → 0.6.4

package/README.md

@@ -1,7 +1,8 @@
 # @avantf/dsh-mem
 
-DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的**记忆**和一个**文档知识库**，
-以进程内 Cordis 插件的形式提供 8 个模型工具、三段用法提示和两个主窗口标签页。
+DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的**记忆**和一个**文档知识库**——
+它跨会话记得你说过的事，也能把文档收进库里按语义查回来。装上后提供 8 个模型工具、三段用法提示
+和两个主窗口标签页（记忆 / 知识）。
 
 ## 主要功能
 
@@ -13,216 +14,110 @@ DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的
   - `kb_add` / `kb_list` / `kb_remove` / `kb_reindex`：新增文档（文本 / 文件 / URL，或批量导入目录，
     同名拒绝）、列表（带出受管 `.md` 的绝对路径与切片详情）、删除、重建索引；
     **改一篇既有文档就是改那份 `.md`**（用文件工具改，索引自动跟随）
-  - `kb_query`：跨「记忆事实 + 文档切片」的统一检索，结果带来源标注
-- **混合检索 + 联合融合**：库内三路（语义 / FTS bm25 / 实体 Jaccard，另有 HRR 实体探查腿），
-  跨库在合并候选池上做联合归一化——记忆与文档切片因此处于同一分数刻度。
-- **记忆是活的**：活跃使用日时钟，结算 / TTL / 遗忘 / 闲置 / 清理五段生命周期，去重与修订链，
-  写入即做的矛盾检测；派生状态（实体 / 三元组 / HRR bundle）跟着规则版本走，可批量重抽。
-- **文档知识库**：Markdown 标题感知分块、摄入期抽实体（检索期零重扫）、可增量重建索引；
-  `domain` 受 `knowledge.domains` 清单约束（默认 `design/api/ops/research/notes`，显式 `[]` = 不限制），
-  `source` 可留空（缺省 `default`）。可直接摄入文本与 **PDF**（抽取文本层，中文 CID 字体可用；
-  扫描件会明确报错），并把 **pandoc 能读的格式**（`.docx`/`.odt`/`.epub`/`.html`/`.tex`/`.rst`/`.csv`
-  等）与 **`.xlsx`** 先转成 Markdown 再入库（用了哪条转换器随 `converter` 回报且带版本，如
-  `pandoc-3.11`；没能带过来的内容随 `warnings` 透出）。其他二进制（图片 / pptx / 旧版
-  `.doc`/`.xls`/`.ppt` / 可执行文件）会被拒绝并说明检测到的类型；GBK/GB18030 等中文旧编码会自动解码
-  并在结果里标出 `encoding`。
-- **知识可维护**：每篇文档在 `~/.avantf/knowledge/docs/<domain>/<source>/<title>.md` 留一份可编辑副本
-  （frontmatter 记着它属于哪篇文档）——用你自己的编辑器改，插件会在**其后任一工具调用结束时**自动把改动同步
-  回索引（先一次 `stat` 判漂移、再用正文哈希裁决，只重摄入真正改过的），「知识」页的「重新摄入」是手动兜底；
-  删除文档会连同这份副本一起删除，`source_uri` 指向的原文件始终不被改动。
-- **可插拔、可降级**：语义后端 / 向量库都走内部注册表；模型、hnswlib、分词器任一缺失都自动降级
-  （FTS + 实体 / numpy 向量库 / 正则抽取），不会因此退出。
-- **0.5.0 起不再有结果重排**：`Reranker` 接口、`rerank.*` 配置键、公开面的 `registerReranker` 与结果/统计里的
-  `rerank_*` 字段已整体移除（旧配置里的 `rerank:` 段会被当作未知键告警并忽略）；可注册的检索面只剩语义后端与向量库。
-- **两个主窗口标签页**（排在 对话 / 轨迹 之后）：**记忆**（浏览、编辑、归档恢复、反馈、矛盾裁决）与
-  **知识**（文档列表，每行可查看切片 / 编辑 / 打开目录 / 重新摄入 / 删除；另有跨库查询与入库——
+  - `kb_query`：跨「记忆事实 + 文档切片」的统一检索，结果带来源标注，可据此引用原文
+- **记忆与知识一起检索**：对记忆事实与文档切片做统一排序，两类结果处在同一分数刻度上，
+  所以"我之前定过的约定"和"文档里怎么写的"能一次问出来。
+- **记忆是活的**：按活跃使用结算，支持有效期、遗忘、去重与修订链；同一主题的改动会被识别成
+  对旧事实的**修订**而不是简单叠加，写入时顺带做矛盾检测。
+- **资料随手入库**：文本、本地文件、目录、URL 都能收；Markdown 按标题分块，PDF、`.docx`、`.xlsx`
+  等常见格式也能直接入库（转换过程有问题会明确回报，不静默丢内容）。
+- **知识可维护**：每篇文档在数据目录里留一份可编辑的 Markdown 副本，用你自己的编辑器改，
+  插件会在其后自动把改动同步回索引；删除文档只删这份副本，你原来的文件不动。
+- **两个主窗口标签页**（排在 对话 / 轨迹 之后）：**记忆**（浏览、编辑、归档恢复、反馈、矛盾裁决）
+  与**知识**（文档列表，每行可查看切片 / 编辑 / 打开目录 / 重新摄入 / 删除；另有跨库查询与入库——
   URL / 本地文件 / 本地目录 / 粘贴文本共用一个输入）。
 - 系统提示词里只加**三段**用法提示（何时该主动记忆、何时该先查记忆、何时该先查知识库 / 怎么改一篇
-  既有文档），不解释内部保留策略。
+  既有文档）。
 
 ## 接入 dsh
 
 ```bash
-# 1) 装这两个包：插件本身，以及家族底座。底座是插件的 peer；不开 autoInstallPeers 的包管理器
-#    （pnpm / yarn）不会跟着装上，所以要显式装。
-#    版本号建议写死：pnpm ≥ 10 的 minimumReleaseAge 会避开刚发布的版本，解析到的旧版本可能不认识
-#    当前宿主（它的 peer 区间不含这个 dsh），那一单会被宿主的安装门禁直接拒绝并把 profile 回滚。
-dsh plugin --profile <PROFILE> add @avantf/dsh-plugin-base@<version>
+# 把插件装进你要用的 profile（依赖会自动装好，不用管别的）
 dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 
-# 2) 原生依赖只剩**可选**的加速件（分词 / 向量索引 / 嵌入模型）。它们缺失只会降级检索质量，
-#    不影响记忆库本身——存储层用的是运行时自带的 node:sqlite，没有需要编译的数据库模块。
-cd ~/.dsh/profiles/<PROFILE>
-pnpm approve-builds --all     # 勾选 nodejieba / hnswlib-node / onnxruntime，可按需
+# 然后重启 dsh 生效
 ```
 
-```yaml
-# 3) 挂载插件：装完通常什么都不用做。
-#
-# 本包声明了组合包（dsh.bundle.patch → 随包的 cordis.patch.yml），所以 `dsh plugin add` 装它时会
-# 顺手把这个包选进 profile 的 dsh.profile.bundles（实测），挂载行由随包的 patch 插入；DSH Desktop
-# 的「插件」页走的也是这条。只有两种情况才需要自己写那一行：
-#   · 用 npm / yarn 装（它们不认识 dsh.profile.bundles）；
-#   · 手工编辑 profile 的包清单，而没有把本包选进 bundles。
-# 两条路都做也不会挂两次：当前 dsh（0.1.7 / 0.2.0 线）的 loader 按条目 id 去重，只挂载一次（实测）；
-# 但 0.1.5 线（仍在本包 peer 区间内）上重复的行 id 会让 profile 树加载失败——所以始终二选一。
-#   · 前提：自动选中只在 `dsh plugin add` **跑完**那一刻发生。若它中途被构建提示（pnpm 的
-#     approve-builds）拦下（ERR_PNPM_IGNORED_BUILDS、非零退出），依赖装上了但组合包**不会被选中**，
-#     事后再 add / install 也不会补选——先答完提示再装，或到 DSH Desktop 的「插件」页启用这个组合包。
-#
-# 手写的那一行，放在 ~/.dsh/profiles/<PROFILE>/cordis.patch.yml（不存在就新建）：
-- insert:
-    - id: avantf-mem
-      name: '@avantf/dsh-mem'
-      config:
-        mode: cordis          # 进程内插件
-        # dataHome 建议省略（默认 ~/.avantf）。它是配置值，会被 AVANTF_HOME 压过。
-```
-
-```bash
-# 4) 重启 dsh（宿主半边需重启，浏览器半边会热重载）
-dsh web
-```
-
-### DSH Desktop
+版本号可以不写，但建议指定一个明确版本。
 
-Desktop 用的是同一套 profile（profile 名 `desktop`），差别只有三点：
-
-- **界面上只能装组合包**。Desktop 的「插件」页与 `plugin_manager` 只接受声明了 `dsh.bundle.patch`
-  的包（本包已声明）：在页面上装它，它会把这个包选进 `dsh.profile.bundles`，并应用随包的
-  `cordis.patch.yml`——不用手写挂载行。
-- **用它自带的 dsh**：`<安装目录>/resources/runtime/cli/bin/dsh.cmd`（或在设置里把 `dsh` 装进 PATH）。
-- **重启应用**才生效：Desktop 的宿主半边与浏览器半边一起启动，不像 Web 那样热更。
-
-Desktop 的宿主进程是 **Electron**（`NODE_MODULE_VERSION` 与同版本 Node 不同）。这正是本插件不依赖任何
-SQLite 绑定的原因：存储层用运行时自带的 `node:sqlite`，它就在跑插件的那个进程里，没有预编译产物要匹配、
-也不需要用户装 C++ 工具链。启动日志里 `sqlite=node:sqlite <版本>` 就是它；两个宿主写的是同一个 SQLite
-文件格式，换宿主不需要迁移数据。
-
-- 插件的 `@deepseek-ai/*` peer 由宿主提供（profile 上层的运行时解析表），`dsh plugin add` 不会另装一份。
-  **不要在 profile 里再装** `cordis` / `schemastery` / `dsh-tools`——两份对象身份会让工具与 typert
-  注册表对不上。
-- `zod` 同样是**宿主提供的 required peer**（区间 `>=4.4.3 <5`，宿主的 dsh 自带）：工具的 wire 与参数
-  schema 都用**这一份**。**不要在 profile 里单独装一份 `zod`**——两个副本的 schema 类型身份不同，
-  跨副本传 schema 对象会在运行期对不上。
+**DSH Desktop**：在「插件」页里安装同一个包即可，装完重启应用；不用动命令行。
 
 ## 怎么用
 
-工具是给模型用的，通常不用你手写；这里是最常见的几种用法。
+工具是给模型用的，通常不用你手写；用日常说法提要求就行。最常见的几种：
 
 ```text
 记住这条：发布窗口是每周四 20:00；验收标准是灰度零回滚。
 ```
 
 ```text
-我之前定过的数据目录约定是什么？（→ mem_recall，返回命中事实与来源）
+我之前定过的数据目录约定是什么？（返回命中事实与来源）
 ```
 
 ```text
-把 ~/docs/cgroup-v2.pdf 收到知识库的 ops 域下。（→ kb_add source_uri，转换器与告警随结果回报）
+把 ~/docs/cgroup-v2.pdf 收到知识库的 ops 域下。
 ```
 
 ```text
-看看知识库里关于「内存保护」的原文。（→ kb_query，结果带 source_ref，可据此引用）
+看看知识库里关于「内存保护」的原文。
 ```
 
-改一篇已经入库的文档：先用 `kb_list` 拿到那份 `.md` 的路径，再用**任意文件工具**改它——改完不必手动回填，
-插件会在其后任一工具调用结束时自动同步（「重新摄入」是手动兜底）；或直接对模型说"更新这篇文档"。
+```text
+把「每周四发布」改成「每周三发布」，并说明依据。
+```
+
+改一篇已经入库的文档：让模型"更新这篇文档"即可；也可以用任意文件工具直接编辑那份受管
+`.md`（先用 `kb_list` 拿到路径），改完会自动同步，「知识」页的「重新摄入」是手动兜底。
 
 常见维护动作：
 
 ```text
-检查记忆库的检索与索引状态。（→ mem_admin trust_diagnose / vectors_diagnose / stats）
-把矛盾检测的积压扫一遍。（→ mem_admin contradict_check，再对每条判 true_positive / false_positive）
+检查记忆库的检索与索引状态。
+把矛盾检测的积压扫一遍，逐条裁决。
 ```
 
-### 相关性门槛（严格 / 宽松）
+### 相关性门槛：严格 / 宽松
 
-检索对每条腿都有一条**绝对**相关性门槛（打在每条腿的原始分上、融合之前）：语义余弦
-`min_semantic_similarity`（默认 `0.5`）、FTS 腿逐行命中的**不同查询词元数** `min_fts_terms`（默认 `2`）、
-实体 Jaccard `min_jaccard`（默认 `0.2`）——分数等于门槛保留，`0` = 关闭该腿（改在
-`~/.avantf/configs/common.yaml` 的 `retriever` 节）。
+「记忆」「知识」页的查询面板有**严格 / 宽松**选择（工具面的 `mem_recall` / `kb_query` 也接受
+`floors: 'strict' | 'loose'`）：
 
-- **两个档位（UI 选择器 / `floors` 参数）**：「知识」「记忆」页的查询面板有「严格 / 宽松」选择，`mem_recall.search`
-  与 `kb_query` 也接受 `floors: 'strict' | 'loose'`。`strict` = 用配置值、**不**自动放宽（面板默认它，好让空结果
-  有明确说法）；`loose` = 直接宽松档，换成一组仍有绝对底线的值（`0.40 / ⌈词元数/2⌉ / 0.15`）——所以宽松档
-  一样答得出"确实没有相关结果"，不是"无门槛"。
-- **不传 `floors` 时的默认策略：严格档为空就自动放宽一次**：先按严格档跑；**仅当**它一条都没命中、且确实有
-  条目被门槛丢掉时，才用宽松档补跑一遍。只有宽松档真的产出结果才替换答案，结果里置 `relaxed: true`，面板显示
-  「（已自动放宽门槛）」；放宽也救不回时**原样返回严格档结果**（含"被门槛丢掉 N 条"的报告）。跨库查询只对
-  **合并后**的结果做这个决定，免得一条空库把放宽后的尾部混进另一条库的严格命中。
-- **可解释性**：结果带生效门槛 `floors` 与每腿丢弃数 `dropped_by_floor`，所以「门槛挡掉的空」与「本来就没有」
-  能分开说——面板因此分别给出「严格门槛丢弃了 N 条，可切「宽松」重试」与「（宽松档下）确实没有相关结果」。
+- **严格**（面板默认）：只有明确够相关的才返回，所以"没有结果"是一个可信的答案。
+- **宽松**：门槛更低，用来找回边角相关的条目——仍有一条底线，不是无门槛。
+- **不选时**：先按严格跑；严格档一条都没命中、且确实有条目被门槛挡掉时，自动用宽松档补跑一次，
+  结果会标明「已自动放宽门槛」。门槛挡掉的空与真的没有，面板和结果里的数字能区分开。
 
 ## 配置、数据与提示词
 
-- **数据目录**：默认 `~/.avantf`。记忆库、知识库（含 `knowledge/docs` 下的受管文档副本）与模型缓存
-  都在其中。
+- **数据目录**：默认 `~/.avantf`。记忆库、知识库（含受管文档副本）与模型缓存都在其中；
+  环境变量 `AVANTF_HOME` 可以改变它。
 - **配置**：`~/.avantf/configs/` 下的三份 YAML —— `common.yaml`（公共项，缺失时按注释模板自动创建）、
-  `memory.yaml`、`knowledge.yaml`；只写你要改的项，其余取内置默认。`dataHome` 也可以写在 profile 的
-  config 里，但环境变量 `AVANTF_HOME` 会压过它。
-- **提示词文件**：`~/.avantf/prompts/mem-memory-usage.md`、`mem-knowledge-usage.md`、`mem-kb-edit.md`。
-  缺失或为空时插件写入默认内容，**只在启动时读一次**，改完重启生效。正文可以**按领域改写**——内置默认
-  刻意不出现任何领域名词（它同时服务开发、投研、日常等场景），只给判据与"事实型 / 规则型"两种形状：
+  `memory.yaml`、`knowledge.yaml`。只写你要改的项，其余取内置默认。
+- **提示词文件**：`~/.avantf/prompts/` 下的 `mem-memory-usage.md`、`mem-knowledge-usage.md`、
+  `mem-kb-edit.md`。缺失或为空时插件写入默认内容，**只在启动时读一次**，改完重启生效。
+  可以按自己的领域改写：内置默认刻意不出现任何领域名词，只给判据与两种形状——
   - 事实型：`用户不吃香菜；订餐默认备注不要香菜。`（谁 / 什么范围 / 偏好或要求或术语是什么）
-  - 规则型：`只有「注销式回购」减少总股本，库存股回购不减少——比较 EPS 影响时要区分。`（当……时，应……，附条件与例外）
-  - 反例（不该写成事实）：一次调查的过程叙述、数据表、命令与链接——依据属于知识库文档，记忆里只留**结论 + 位置**
-    （路径 / 来源 / 名称）；敏感信息同理，只记存放位置，不记明文。
-- **自定义过提示词文件的话，升级时需手动补**：提示词**文件优先于内置正文**（文件存在且非空时内置正文完全不参与渲染）。
-  0.6.0 起内置正文多了三条行为口径，若你改过 `mem-memory-usage.md`，请把下面三行追加到你的文件末尾；没改过则无需操作：
-  ```text
-  记忆是过去的记录、不是当下指令，无关时可完全忽略。
-  同一主题用 `update` 纠正并附核实依据，不同事实新增。
-  不要把 `recall` 结果原样回记。
-  ```
-- **可选：中文时间窗检索腿**（0.6.0 起，**默认关闭**）。它在查询含中文时间表达时，把**事件时间**（写入时用
-  `event_date` 给出）落在窗口内的活跃事实作为额外一条腿参与融合——只增加候选、不删已有命中，也不会回退到写入时间。
-  在 `~/.avantf/configs/common.yaml` 打开：
-  ```yaml
-  retriever:
-    time_window: true
-  ```
-  打开前先看 `mem_admin stats` 的 `validity.coverage`（带事件时间的事实占比）：覆盖率接近 0 时这条腿等于没开。
-
-- **语义模型**：默认从 `hf-mirror.com` 下载并缓存，也可指向本地模型目录离线运行。
-- **升级前先备份 `~/.avantf`**：数据库迁移是单向的，用旧版本打开新库会被明确拒绝。
-
-## 升级 / 卸载 / 换版本
+  - 规则型：`只有「注销式回购」减少总股本，库存股回购不减少——比较 EPS 影响时要区分。`
+  - 不适合写进记忆：一次调查的过程叙述、数据表、命令与链接——依据归知识库文档，记忆里只留
+    **结论 + 位置**（路径 / 来源 / 名称）；敏感信息同理，只记存放位置，不记明文。
+- **升级前建议先备份 `~/.avantf`**：数据库迁移是单向的，用旧版本打开新库会被明确拒绝。
+
+## 升级 / 卸载
 
 ```bash
-# 升级（或重装）到某个版本：同一条命令，换版本号即可
+# 升级：换版本号重装同一个包
 dsh plugin --profile <PROFILE> add @avantf/dsh-mem@<version>
 
-# 卸载：先删掉 profile 依赖（这一步同时会取消该组合包的选中）
+# 卸载
 dsh plugin --profile <PROFILE> remove @avantf/dsh-mem
-# 再清掉挂载项：用组合包装的，包名已随上一步从 profile 的 `dsh.profile.bundles` 里去掉，无需再动；
-# 自己手写过那一行的，删掉 ~/.dsh/profiles/<PROFILE>/cordis.patch.yml 里那段 `- id: avantf-mem`
-#（该文件顶层必须是 YAML 数组：删空就写 `[]`，否则 dsh 启动会拒绝加载）。
-# DSH Desktop 的「插件」页上卸载会连着取消选中与依赖一起做。
 ```
 
-两者都需要重启 dsh 才生效。卸载**不动 `~/.avantf`**：记忆库、知识库、模型缓存全部保留。
+两者都要重启 dsh 生效。卸载**不动 `~/.avantf`**：记忆库、知识库、模型缓存全部保留。DSH Desktop 在
+「插件」页上卸载。
 
 ## 环境要求
 
-- **Node `>=22.15.0 <23 || >=23.11.0`**、**pnpm**。记忆与知识两个库都建在运行时自带的 `node:sqlite`
-  上，这个区间是它的两个下限的交集：模块免 flag（22.13 / 23.4）与"忽略语句未用到的命名参数"
-  （22.15 / 23.11）。低于该下限（或该构建缺 FTS5）时插件照常挂载，但 8 个工具都回
-  `memory unavailable` 并给出原因，不会拖垮宿主启动
-- `nodejieba` / `hnswlib-node` / `@huggingface/transformers` 都可选：缺失时分别降级为正则抽取 /
-  numpy 向量库 / 纯词法检索
-- 插件自包含：检索与知识引擎在构建时已内联进产物，安装不需要额外的家族包。宿主提供的 peer 有两个：
-  底座 `@avantf/dsh-plugin-base`（安装时随插件一起装）与 `zod`（宿主的 dsh 自带那份）
-
-## 从源码构建
-
-构建只对着**已安装的全局 dsh**（`npm i -g @deepseek-ai/dsh`），不需要 harness 源码；在仓库根执行：
-
-```bash
-pnpm install
-pnpm build:dsh mem      # 插件两半（tsc + tsdown → lib/index.js + lib/client.js），随后自动跑挂载冒烟
-pnpm pack:plugin:mem    # 打包成"用户安装的那一个包"（断言引擎已内联、依赖版本已落成真实范围）
-```
+- **Node `>=22.15.0 <23 || >=23.11.0`**、**pnpm**
+- 可选的原生加速件（分词 / 向量索引 / 本地嵌入模型）缺失时只会降低检索质量，不影响使用
 
 ## 许可
 

package/lib/engine/mem/db/dao/chunks.d.ts

@@ -115,6 +115,12 @@ export declare class ChunksDao {
      * This is what lets the shared repair flow read "what is stale" cheaply per slice instead of
      * re-scanning and hashing the corpus (`corpusState` reads every text; a batched migration must
      * not).
+     *
+     * The JS rule itself is `store/vector_space.ts` (`classifyVectorSpace` / `countVectorSpace`), and
+     * this projection is bound to it by the cross assertions in
+     * `test/knowledge_vector_migration.spec.ts` (the startup warning's count, the health count and the
+     * migration's `remaining` all have to be the same number). NOTHING here changes when the JS rule
+     * changes: the mirror is checked, not shared.
      */
     vectorSpaceCounts(space: string, expectedBytes: number): {
         stale: number;

package/lib/engine/mem/db/dao/fact_sources.d.ts

@@ -8,10 +8,28 @@
  * The SQL lives here like every other aggregate. The store decides WHICH source a write carries
  * (and refuses to invent one when the caller gave none); the DAO only records and reads rows.
  */
+import type { FactSourceView } from '../../../mem-contract/index.js';
 import type { Db } from '../port.js';
-/** The closed `kind` vocabulary, spelled once so the store and the tests share it. */
+/**
+ * The kind axis is the CONTRACT's, not a second list: `FactSourceView['kind']` is what `admin detail`
+ * renders and what the writer below records, so deriving the type from it is what makes "the closed
+ * vocabulary" one thing. (Before, the array here and the union in `types.ts` were two independent
+ * spellings that happened to agree.)
+ */
+export type FactSourceKind = FactSourceView['kind'];
+/**
+ * The closed `kind` vocabulary, spelled once so the store and the tests share it.
+ *
+ * The `satisfies` pins every member to the contract's union; the `Exclude` below pins the other
+ * direction, so a kind the contract ADDS fails to compile here instead of silently never being
+ * recorded.
+ */
 export declare const FACT_SOURCE_KINDS: readonly ["session", "kb_doc", "tool", "manual"];
-export type FactSourceKind = (typeof FACT_SOURCE_KINDS)[number];
+/**
+ * The FALLBACK kind: a `source_ref` without a recognized `kind:` prefix is `manual` with the
+ * reference kept VERBATIM (the tool contract says so, and "no shape guessing" is the point).
+ */
+export declare const FACT_SOURCE_FALLBACK_KIND: "manual";
 /** One provenance row as the read surfaces render it. */
 export interface FactSource {
     kind: FactSourceKind;
@@ -21,10 +39,14 @@ export interface FactSource {
  * Derive `(kind, ref)` from the single `source_ref` the write face accepts.
  *
  * The tool takes ONE string (the plan adds no second parameter), so the kind axis is spelled by a
- * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else is `manual` with the
- * reference kept VERBATIM. No shape guessing: a bare `domain:source:title` becomes a `manual`
- * source whose ref is exactly what the caller wrote, which is strictly more honest than inventing
- * a category from how the string looks.
+ * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else, INCLUDING the fallback
+ * kind's own name, is `manual` with the reference kept VERBATIM. No shape guessing: a bare
+ * `domain:source:title` becomes a `manual` source whose ref is exactly what the caller wrote, which
+ * is strictly more honest than inventing a category from how the string looks.
+ *
+ * The prefix table comes from {@link FACT_SOURCE_KINDS} (see {@link FACT_SOURCE_PREFIX_KINDS}) rather
+ * than from a hand-written alternation, which is what keeps the recognized set and the recorded set
+ * from being two lists.
  */
 export declare function classifySourceRef(sourceRef: string): {
     kind: FactSourceKind;

package/lib/engine/mem/defaults.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two page/result defaults the engine falls back to when neither the caller nor the config says
+ * anything — spelled ONCE, because each of them used to be written in two or three places.
+ *
+ * They are the ENGINE's consumption points of numbers the CONTRACT documents:
+ *
+ *   - `DEFAULT_SEARCH_LIMIT` — `query`'s own input schema carries `.default(10)`
+ *     (`contract/src/tools.ts`), and the recall actions' descriptions say "默认 10"; the recall union
+ *     itself is `.optional()`, so the engine is what applies it. It reaches `hybridSearch` (a
+ *     non-finite limit) and the cross-store router.
+ *   - `DEFAULT_LIST_LIMIT` — the documented page for `admin list` and `kb_list` ("默认 50" /
+ *     "缺省 50", same file).
+ *
+ * The cross-layer equation is pinned by `test/hybrid.spec.ts` against the contract's parsed schema,
+ * so a contract default moving and this constant not moving is a red test rather than a silent
+ * off-by-page behaviour. (These live here rather than in the contract because `@avantf/mem-contract`
+ * is consumed as built output: a constant added there is only visible to this engine after the
+ * contract is rebuilt, which a source-only change may not assume.)
+ *
+ * @module defaults
+ */
+/** Page of a recall/query result when the caller gave no usable `limit`. */
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+/** Page of a listing surface (`admin list`, `kb_list`) when the caller gave no `limit`. */
+export declare const DEFAULT_LIST_LIMIT = 50;

package/lib/engine/mem/dispatch.d.ts

@@ -16,10 +16,12 @@
 import type { KbAddRequest, ToolEnvelope, ToolSpec } from '../mem-contract/index.js';
 import type { AvantfRuntime } from './runtime.js';
 /**
- * The default page for a model-facing `kb_list`.
+ * The default page for a model-facing `kb_list` — the SAME page the operator's `admin list` uses.
  *
  * Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
- * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full.
+ * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full. The
+ * two surfaces were separate literals; the contract documents both as 50, so they are one constant
+ * (`src/defaults.ts`).
  */
 export declare const KB_LIST_DEFAULT_LIMIT = 50;
 /**

package/lib/engine/mem/modelBootstrap.d.ts

@@ -55,22 +55,6 @@ export interface WarmOptions {
  *   path keeps it, because there the caller only sees this logger.
  */
 export declare function warmModels(rt: AvantfRuntime, options?: WarmOptions, reportFinal?: boolean): Promise<boolean>;
-/**
- * Warm ONLY the embedding model: load it from `semantic.cache_dir` and mark the engine ready.
- *
- * Split out of {@link warmModels} for the plugin's envinit path. There the framework fetches the
- * model in the BACKGROUND, so the warm has to wait for the item to settle instead of running at
- * mount — and the runtime's own constructor warm is deferred for exactly that reason
- * (`RuntimeOptions.managedRoots` → `deferWarm`), which is what stops it racing the install and
- * leaving a second copy behind. While the item is unsettled NOTHING warms; this function is the
- * explicit "files are there now, look" step, and it still runs when the item skipped/failed so
- * `semantic.auto_download` can decide between the runtime's own fetch and degradation.
- *
- * @param rt - the runtime whose memory store owns the semantic backend.
- * @param reportFinal - log the one-line verdict (default `true`).
- * @returns whether the semantic path is available.
- */
-export declare function warmSemantic(rt: AvantfRuntime, reportFinal?: boolean): Promise<boolean>;
 /**
  * Wait out the startup gate — the host readiness signal (bounded by {@link WAIT_FOR_HOST_MS}) and,
  * when asked, one quiet turn of the event loop.
@@ -88,18 +72,6 @@ export declare function warmSemantic(rt: AvantfRuntime, reportFinal?: boolean):
  * @returns how long the idle gate waited (ms), or `0` when it was not requested.
  */
 export declare function awaitStartupGate(options?: WarmOptions): Promise<number>;
-/**
- * Warm ONLY the tokenizer, after the host-readiness signal and (when asked) an idle event loop.
- *
- * nodejieba loads its dictionary lazily on the FIRST `tag()` (measured ~950 ms, after which a call
- * is 0.1 ms), so without this the first write/query of a session pays it while the user waits. Its
- * cost belongs to startup, and an unavailable jieba is worth saying out loud — entity extraction
- * silently degrades to the regex fallback (weaker entity/jaccard legs).
- *
- * @param rt - the runtime whose logger reports the outcome.
- * @param options - the host-readiness signal and the idle gate (see {@link WarmOptions}).
- */
-export declare function warmTokenizer(rt: AvantfRuntime, options?: WarmOptions): Promise<void>;
 /**
  * Non-blocking embedding warm, for a caller that knows the model files are already on disk.
  *
@@ -160,48 +132,7 @@ export interface ProvisionSweepResult {
  * @returns whether the sweep ran or was skipped for incompatibility.
  */
 export declare function provisionToolchainAsync(rt: AvantfRuntime, options?: ProvisionSweepOptions): Promise<ProvisionSweepResult>;
-/** The artifact id, used in the startup log and in the model artifact's errors. */
-export declare const MODEL_ARTIFACT_ID = "model";
 /** The environment a model-artifact call runs under: the runtime that owns the model cache. */
 export interface ModelArtifactEnv {
     runtime: AvantfRuntime;
 }
-/** The slice of an artifact call this module needs (`@avantf/mem-provision`'s InstallContext). */
-interface ModelInstallContext {
-    logger: {
-        info(message: string): void;
-        warn(message: string): void;
-        error(message: string): void;
-    };
-    artifactEnv?: unknown;
-    config: {
-        auto_install: boolean;
-    };
-}
-/**
- * The embedding model (plus the nodejieba tokenizer it shares its warm-up budget with) as an
- * ARTIFACT, so the startup sweep in `@avantf/mem-provision` is the only initialization path.
- *
- * It used to be a parallel model warm-up call beside the tools sweep, which meant two
- * startup mechanisms with two logging vocabularies and no single place that answered "is this host
- * fully provisioned?". The model has no pinned version and no managed directory of its own ON THIS
- * (the flat `<repo>/<file>` layout the transformers.js cache reads), so it
- * declares neither; its `isPresent` is `false` because "is the model warm?" is not a question that
- * can be answered without attempting the warm-up, and the warm-up is cheap when the cache is
- * already there (measured ~1.2 s, in the background). The DSH plugin uses this sweep only when the
- * family framework is unavailable — with the framework up, `mem:model` owns the model root instead
- * and this artifact is not registered.
- */
-export declare const modelArtifact: {
-    id: string;
-    title: string;
-    verb: string;
-    isPresent(): Promise<boolean>;
-    install(ctx: ModelInstallContext): Promise<void>;
-    verify(ctx: {
-        logger: ModelInstallContext["logger"];
-    }): Promise<void>;
-};
-/** Register the model artifact once per process (idempotent for a test that mounts twice). */
-export declare function registerModelArtifact(): void;
-export {};

package/lib/engine/mem/store/hybrid.d.ts

@@ -26,8 +26,6 @@
 import { type Config, type FloorProfile, type RecallResult, type RetrievalFloorDrops, type RetrievalFloors } from '../../mem-contract/index.js';
 import { type BudgetInput, type Hit, type SemanticBackend } from '../../mem-retrieval/index.js';
 import { type FloorLeg } from './floors.js';
-/** The `limit` a caller gets when it passes nothing usable. */
-export declare const DEFAULT_SEARCH_LIMIT = 10;
 /**
  * A retrieval input the CALLER got wrong, as opposed to a backend that failed at runtime.
  *
@@ -39,8 +37,6 @@ export declare const DEFAULT_SEARCH_LIMIT = 10;
  */
 export declare class RetrievalInputError extends Error {
 }
-/** …and the over-fetch factor when the config does not set one (matches the contract default). */
-export declare const DEFAULT_OVER_FETCH_FACTOR = 5;
 /** The three weights a `RecallResult` reports. */
 export type RetrievalWeights = RecallResult['weights'];
 /** One retrieval leg's contribution to the fusion. */

package/lib/engine/mem/store/vector_space.d.ts

@@ -0,0 +1,60 @@
+import type { StaleVectorCounts } from './common.js';
+/** What one persisted vector IS, in the current space. */
+export type VectorSpaceVerdict = 'current' | 'stale' | 'space_stale';
+/**
+ * A persisted vector's width, in whichever shape the CALLER already has it — the discriminant is the
+ * shape, never the truth:
+ *
+ *   - `blob` — the raw BLOB (`Uint8Array`), for a caller that has read the bytes;
+ *   - `byteLength` — a projected `length(semantic_vector)`, for a caller that must not read them;
+ *   - `decoded` — an already decoded `Float32Array`, for a caller that had to decode anyway.
+ *
+ * All three answer the same question (`width === dim`), which is the point: the caller with the
+ * cheapest possible evidence is not forced to re-read the row in another shape. A `null`/`undefined`
+ * width is "no usable bytes" and classifies as `stale`, like a wrong one.
+ */
+export type PersistedVectorWidth = {
+    readonly source: 'blob';
+    readonly vec: Uint8Array | null | undefined;
+} | {
+    readonly source: 'byteLength';
+    readonly byteLength: number | null | undefined;
+} | {
+    readonly source: 'decoded';
+    readonly vec: Float32Array | null | undefined;
+};
+/** One width probe plus the space RECORDED beside it (the second element of the rule). */
+export type VectorSpaceProbe = PersistedVectorWidth & {
+    /** `facts.embedding_model` / `doc_chunks.embedding_model` of the same row; `null` = unrecorded. */
+    readonly embeddingModel: string | null | undefined;
+};
+/** The space the store writes into RIGHT NOW. */
+export interface VectorSpaceIdentity {
+    /** The representation fingerprint (`vectorSpaceOf`). */
+    readonly space: string;
+    /** The width the store writes now, in floats. */
+    readonly dim: number;
+}
+/** One row's classification. */
+export interface VectorSpaceClassification {
+    readonly verdict: VectorSpaceVerdict;
+    /** Of a `space_stale` verdict: the recorded id predates the representation fingerprint. */
+    readonly legacy: boolean;
+}
+/**
+ * Classify ONE persisted vector. Pure: no store, no database, no logging — a caller that disagrees
+ * with the result has to disagree with the rule, not with a copy of it.
+ *
+ * A caller-supplied vector is trusted to come from this backend, but its DIMENSION is still checked
+ * — the same asymmetry `legs.ts` applies to a caller-supplied `queryVector`: provenance is the
+ * caller's to assert, width is cheap and decides whether the bytes can be compared at all.
+ */
+export declare function classifyVectorSpace(probe: VectorSpaceProbe, identity: VectorSpaceIdentity): VectorSpaceClassification;
+/**
+ * {@link classifyVectorSpace} over a corpus: the `{ stale, space_stale, legacy }` triple the warning
+ * and the `/mem` status surface report, counted by the same rule that classified each row.
+ *
+ * `legacy` counts only rows already counted in `space_stale` (`reportStaleVectors` clamps it there
+ * too) — it is a REASON split, never a fourth bucket.
+ */
+export declare function countVectorSpace(probes: readonly VectorSpaceProbe[], identity: VectorSpaceIdentity): StaleVectorCounts;

package/lib/index.js

@@ -3777,8 +3777,19 @@ const modelArtifact = {
 };
 /** Register the model artifact once per process (idempotent for a test that mounts twice). */
 function registerModelArtifact() {
-	if (!hasArtifact("model")) registerArtifact(modelArtifact);
+	if (!hasArtifact(MODEL_ARTIFACT_ID)) registerArtifact(modelArtifact);
 }
+//#endregion
+//#region ../core/lib/dispatch.js
+/**
+* The default page for a model-facing `kb_list` — the SAME page the operator's `admin list` uses.
+*
+* Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
+* needs the file's frontmatter to detect collisions) to answer a question nobody asked in full. The
+* two surfaces were separate literals; the contract documents both as 50, so they are one constant
+* (`src/defaults.ts`).
+*/
+const KB_LIST_DEFAULT_LIMIT = 50;
 /** A document view with the managed file's path — what makes "edit it yourself" actionable. */
 function withFilePath(rt, doc) {
 	return {
@@ -3821,7 +3832,7 @@ const DISPATCH = {
 			const detail = rt.knowledge.detail(data.doc_id);
 			return detail === null ? { error: `文档不存在：doc_id=${String(data.doc_id)}` } : withFilePath(rt, detail);
 		}
-		return rt.knowledge.list(data.domain, data.source, data.limit ?? 50, data.offset).map((doc) => withFilePath(rt, doc));
+		return rt.knowledge.list(data.domain, data.source, data.limit ?? KB_LIST_DEFAULT_LIMIT, data.offset).map((doc) => withFilePath(rt, doc));
 	}),
 	kb_remove: ((rt, data) => rt.kb({
 		action: "remove",
@@ -7428,6 +7439,33 @@ function mergeFloorDrops(...parts) {
 function totalFloorDrops(drops) {
 	return drops.semantic + drops.fts + drops.jaccard + drops.hrr;
 }
+//#endregion
+//#region ../core/lib/store/hybrid.js
+/**
+* The retrieval orchestration BOTH stores run.
+*
+* `MemoryStore.search` and `KnowledgeStore.search` used to carry parallel copies of this flow
+* (~80 lines each: limit normalization → weights → over-fetch → leg cap → fuse → live filter →
+* slice → output budget → health event). The legs themselves are legitimately store-specific —
+* different tables, different filters (`category` vs `domain`/`source`), and only memory has the
+* HRR probe — but the ORCHESTRATION is one algorithm, and two copies of it drifted:
+*
+*   - the `NaN` limit guard existed only in memory, so a non-finite limit reached knowledge's SQL
+*     `LIMIT` and took the whole cross-store query down with it (`Promise.all` has no per-leg catch);
+*   - `retriever.over_fetch_factor` was read only by memory, while knowledge hardcoded `limit * 3`,
+*     so one config knob silently meant two different things;
+*   - `recordLegCapped()` was called only by memory, so a capped knowledge leg was unobservable —
+*     exactly the blindness DESIGN §20.17 says the counter exists to remove.
+*
+* Fixing those one at a time would leave the next drift a matter of when. The stores now supply
+* their legs and their hit mapping; everything that can drift lives here once.
+*
+* A leg that THROWS is isolated: it contributes nothing, the query still answers from the others,
+* and the failure is logged. The read path used to have no per-leg catch at all (the write path
+* did), so an ONNX error at inference cost the caller the FTS and entity legs too.
+*
+* @module store/hybrid
+*/
 /**
 * A retrieval input the CALLER got wrong, as opposed to a backend that failed at runtime.
 *
@@ -7488,7 +7526,7 @@ async function hybridSearch(deps, plan) {
 		fts: retriever.weight_fts,
 		jaccard: retriever.weight_jaccard
 	} : DEGRADED_WEIGHTS;
-	const overFetch = Math.max(limit, plan.overFetch ?? limit * (retriever.over_fetch_factor || 5));
+	const overFetch = Math.max(limit, plan.overFetch ?? limit * (retriever.over_fetch_factor || defaultConfig.retriever.over_fetch_factor));
 	const legCap = legCapFor(deps.config, overFetch);
 	const termCount = gradedTerms(query).length;
 	/**
@@ -8251,37 +8289,82 @@ async function forEachYielding(items, visit, every = 200) {
 		if ((index + 1) % every === 0) await yieldToEventLoop();
 	}
 }
+//#endregion
+//#region ../core/lib/store/vector_space.js
 /**
-* Rebuild one store's live vstore from its persisted rows, count what is unusable in the current
-* space, and say so once — the shared "open for business" step both stores used to write twice.
+* The ONE rule that decides whether a persisted vector can serve the store's CURRENT embedding
+* space — and therefore the one place the three counts (`stale` / `space_stale` / `legacy`) mean
+* anything.
 *
-* The owning store's ONLY half is the row read (`facts.activeVectorRows()` /
-* `chunks.vectorRows()`); the reload, the count and the loud warning are one implementation, so a
-* change to what counts as stale cannot land on one store only (the incident this exists for: the
-* memory store checked the SPACE while knowledge checked only the WIDTH, so a model swap mixed two
-* spaces in one index until someone happened to run `kb_reindex`).
+* The rule used to be written out five times (the shared open-time reload, the memory store's cheap
+* blob-length scan, the memory store's decode pass, the knowledge store's SQL projection and its
+* encode-source predicate), each in a slightly different shape: one over `Uint8Array`, one over a
+* projected `length(blob)`, one over a decoded `Float32Array`. They happened to agree; nothing made
+* them. A change to "what counts as stale" landing on one of them is exactly the silent two-spaces-
+* in-one-index failure `reportStaleVectors` exists to announce.
+*
+* The rule, as three elements (and nothing else):
+*
+*   1. `vec == null || byteLength !== dim * 4` → `stale` (the bytes cannot even decode into the
+*      current store);
+*   2. `embedding_model !== space` → `space_stale` (same width, another model's coordinates);
+*   3. of those, `isPreFingerprintSpace(...)` → `legacy` (a one-time format upgrade, not a model
+*      swap).
+*
+* WHAT IS NOT HERE: the SQL mirror (`ChunksDao.vectorSpaceCounts`) stays in SQL — it is what makes a
+* per-slice migration cheap (no blob is read) — and the cross assertions in
+* `test/vector_migration.spec.ts` / `test/knowledge_vector_migration.spec.ts` bind its counts to the
+* counts this module produces and to the startup warning. That is the direction the mirror has to be
+* checked in; a JS port of the SQL query would just be a sixth copy.
+*
+* @module store/vector_space
 */
-function loadVectorIndex(opts) {
-	reloadVectorIndex(opts.vstore, opts.rows, opts.store);
-	const expectedBytes = opts.vstore.dim * 4;
+/** How many bytes one element of a persisted vector BLOB costs (`float32ToBytes` writes LE f32). */
+const BYTES_PER_FLOAT32 = 4;
+/**
+* Classify ONE persisted vector. Pure: no store, no database, no logging — a caller that disagrees
+* with the result has to disagree with the rule, not with a copy of it.
+*
+* A caller-supplied vector is trusted to come from this backend, but its DIMENSION is still checked
+* — the same asymmetry `legs.ts` applies to a caller-supplied `queryVector`: provenance is the
+* caller's to assert, width is cheap and decides whether the bytes can be compared at all.
+*/
+function classifyVectorSpace(probe, identity) {
+	if (!(probe.source === "blob" ? probe.vec !== null && probe.vec !== void 0 && probe.vec.byteLength === identity.dim * BYTES_PER_FLOAT32 : probe.source === "byteLength" ? probe.byteLength === identity.dim * BYTES_PER_FLOAT32 : probe.vec !== null && probe.vec !== void 0 && probe.vec.length === identity.dim)) return {
+		verdict: "stale",
+		legacy: false
+	};
+	if (probe.embeddingModel !== identity.space) return {
+		verdict: "space_stale",
+		legacy: isPreFingerprintSpace(probe.embeddingModel)
+	};
+	return {
+		verdict: "current",
+		legacy: false
+	};
+}
+/**
+* {@link classifyVectorSpace} over a corpus: the `{ stale, space_stale, legacy }` triple the warning
+* and the `/mem` status surface report, counted by the same rule that classified each row.
+*
+* `legacy` counts only rows already counted in `space_stale` (`reportStaleVectors` clamps it there
+* too) — it is a REASON split, never a fourth bucket.
+*/
+function countVectorSpace(probes, identity) {
 	let stale = 0;
 	let spaceStale = 0;
 	let legacy = 0;
-	for (const row of opts.rows) {
-		if (row.vec === null || row.vec.byteLength !== expectedBytes) {
+	for (const probe of probes) {
+		const classified = classifyVectorSpace(probe, identity);
+		if (classified.verdict === "stale") {
 			stale++;
 			continue;
 		}
-		if (row.embedding_model !== opts.space) {
+		if (classified.verdict === "space_stale") {
 			spaceStale++;
-			if (isPreFingerprintSpace(row.embedding_model)) legacy++;
+			if (classified.legacy) legacy++;
 		}
 	}
-	reportStaleVectors(opts.store, opts.space, {
-		stale,
-		space_stale: spaceStale,
-		legacy
-	}, opts.manualEntry);
 	return {
 		stale,
 		space_stale: spaceStale,
@@ -8289,6 +8372,29 @@ function loadVectorIndex(opts) {
 	};
 }
 /**
+* Rebuild one store's live vstore from its persisted rows, count what is unusable in the current
+* space, and say so once — the shared "open for business" step both stores used to write twice.
+*
+* The owning store's ONLY half is the row read (`facts.activeVectorRows()` /
+* `chunks.vectorRows()`); the reload, the count and the loud warning are one implementation, so a
+* change to what counts as stale cannot land on one store only (the incident this exists for: the
+* memory store checked the SPACE while knowledge checked only the WIDTH, so a model swap mixed two
+* spaces in one index until someone happened to run `kb_reindex`).
+*/
+function loadVectorIndex(opts) {
+	reloadVectorIndex(opts.vstore, opts.rows, opts.store);
+	const counts = countVectorSpace(opts.rows.map((row) => ({
+		source: "blob",
+		vec: row.vec,
+		embeddingModel: row.embedding_model
+	})), {
+		space: opts.space,
+		dim: opts.vstore.dim
+	});
+	reportStaleVectors(opts.store, opts.space, counts, opts.manualEntry);
+	return counts;
+}
+/**
 * Encode rows one at a time, add each to the live index, and persist them in groups.
 *
 * The shared skeleton: serial encode (a MEASURED decision for chunks — a padded batched forward pass
@@ -10479,22 +10585,53 @@ var FactsDao = class FactsDao {
 //#endregion
 //#region ../core/lib/db/dao/fact_sources.js
 /**
+* The closed `kind` vocabulary, spelled once so the store and the tests share it.
+*
+* The `satisfies` pins every member to the contract's union; the `Exclude` below pins the other
+* direction, so a kind the contract ADDS fails to compile here instead of silently never being
+* recorded.
+*/
+const FACT_SOURCE_KINDS = [
+	"session",
+	"kb_doc",
+	"tool",
+	"manual"
+];
+/**
+* The FALLBACK kind: a `source_ref` without a recognized `kind:` prefix is `manual` with the
+* reference kept VERBATIM (the tool contract says so, and "no shape guessing" is the point).
+*/
+const FACT_SOURCE_FALLBACK_KIND = "manual";
+/**
+* The kinds that act as a PREFIX — the vocabulary minus its own fallback, so a kind the contract adds
+* joins the prefix table by itself (via {@link FACT_SOURCE_KINDS}) and cannot be forgotten here.
+*/
+const FACT_SOURCE_PREFIX_KINDS = FACT_SOURCE_KINDS.filter((kind) => kind !== FACT_SOURCE_FALLBACK_KIND);
+/**
 * Derive `(kind, ref)` from the single `source_ref` the write face accepts.
 *
 * The tool takes ONE string (the plan adds no second parameter), so the kind axis is spelled by a
-* `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else is `manual` with the
-* reference kept VERBATIM. No shape guessing: a bare `domain:source:title` becomes a `manual`
-* source whose ref is exactly what the caller wrote, which is strictly more honest than inventing
-* a category from how the string looks.
+* `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else, INCLUDING the fallback
+* kind's own name, is `manual` with the reference kept VERBATIM. No shape guessing: a bare
+* `domain:source:title` becomes a `manual` source whose ref is exactly what the caller wrote, which
+* is strictly more honest than inventing a category from how the string looks.
+*
+* The prefix table comes from {@link FACT_SOURCE_KINDS} (see {@link FACT_SOURCE_PREFIX_KINDS}) rather
+* than from a hand-written alternation, which is what keeps the recognized set and the recorded set
+* from being two lists.
 */
 function classifySourceRef(sourceRef) {
-	const match = /^(session|kb_doc|tool):(.+)$/s.exec(sourceRef);
-	if (match !== null && match[2] !== void 0) return {
-		kind: match[1],
-		ref: match[2]
-	};
+	const separator = sourceRef.indexOf(":");
+	if (separator > 0) {
+		const prefix = sourceRef.slice(0, separator);
+		const ref = sourceRef.slice(separator + 1);
+		if (ref !== "" && FACT_SOURCE_PREFIX_KINDS.includes(prefix)) return {
+			kind: prefix,
+			ref
+		};
+	}
 	return {
-		kind: "manual",
+		kind: FACT_SOURCE_FALLBACK_KIND,
 		ref: sourceRef
 	};
 }
@@ -11551,26 +11688,14 @@ var MemoryStore = class {
 	* and every existing assertion on it — is unchanged; only the warning's wording uses it.
 	*/
 	vectorSpaceCounts() {
-		const space = this.vectorSpace();
-		const expectedBytes = this.vstore.dim * 4;
-		let stale = 0;
-		let spaceStale = 0;
-		let legacy = 0;
-		for (const row of this.facts.activeVectorSpaces()) {
-			if (row.bytes !== expectedBytes) {
-				stale++;
-				continue;
-			}
-			if (row.embedding_model !== space) {
-				spaceStale++;
-				if (isPreFingerprintSpace(row.embedding_model)) legacy++;
-			}
-		}
-		return {
-			stale,
-			space_stale: spaceStale,
-			legacy
-		};
+		return countVectorSpace(this.facts.activeVectorSpaces().map((row) => ({
+			source: "byteLength",
+			byteLength: row.bytes,
+			embeddingModel: row.embedding_model
+		})), {
+			space: this.vectorSpace(),
+			dim: this.vstore.dim
+		});
 	}
 	async add(content, category, ttlDays, opts) {
 		const normalized = normalizeWrite(content).trim();
@@ -12028,17 +12153,25 @@ var MemoryStore = class {
 		const counts = this.facts.vectorCounts();
 		const models = this.facts.embeddingModels();
 		const rows = this.facts.activeVectorRows();
-		const space = this.vectorSpace();
+		const identity = {
+			space: this.vectorSpace(),
+			dim: this.vstore.dim
+		};
 		const staleIds = [];
 		const spaceStaleIds = [];
 		const usable = [];
 		for (const r of rows) {
 			const vec = bytesToFloat32(r.semantic_vector);
-			if (!vec || vec.length !== this.vstore.dim) {
+			const classified = classifyVectorSpace({
+				source: "decoded",
+				vec,
+				embeddingModel: r.embedding_model
+			}, identity);
+			if (classified.verdict === "stale") {
 				staleIds.push(r.fact_id);
 				continue;
 			}
-			if (r.embedding_model !== space) spaceStaleIds.push(r.fact_id);
+			if (classified.verdict === "space_stale") spaceStaleIds.push(r.fact_id);
 			usable.push({
 				id: r.fact_id,
 				vec
@@ -13069,6 +13202,12 @@ var ChunksDao = class {
 	* This is what lets the shared repair flow read "what is stale" cheaply per slice instead of
 	* re-scanning and hashing the corpus (`corpusState` reads every text; a batched migration must
 	* not).
+	*
+	* The JS rule itself is `store/vector_space.ts` (`classifyVectorSpace` / `countVectorSpace`), and
+	* this projection is bound to it by the cross assertions in
+	* `test/knowledge_vector_migration.spec.ts` (the startup warning's count, the health count and the
+	* migration's `remaining` all have to be the same number). NOTHING here changes when the JS rule
+	* changes: the mirror is checked, not shared.
 	*/
 	vectorSpaceCounts(space, expectedBytes) {
 		const row = this.db.prepare(`SELECT
@@ -17078,7 +17217,10 @@ async function loadFramework(options) {
 }
 /**
 * Read the range a plugin declares in the nearest `package.json`: walk up from `from`,
-* preferring `peerDependencies` over `devDependencies`; `undefined` when none is found.
+* preferring `dependencies` over `peerDependencies` over `devDependencies`; `undefined` when none is
+* found. `dependencies` is the live declaration — the base ships as a normal dependency of the
+* plugins — while `peerDependencies` stays as the fallback for plugins built when the base was
+* declared a peer, and `devDependencies` covers a local checkout.
 */
 async function readDependencyRange(from = process.cwd()) {
 	let current = from;
@@ -17108,7 +17250,7 @@ async function readDependencyRange(from = process.cwd()) {
 			const parsed = JSON.parse(text);
 			if (typeof parsed !== "object" || parsed === null) return void 0;
 			const manifest = parsed;
-			return rangeOf(manifest["peerDependencies"]) ?? rangeOf(manifest["devDependencies"]);
+			return rangeOf(manifest["dependencies"]) ?? rangeOf(manifest["peerDependencies"]) ?? rangeOf(manifest["devDependencies"]);
 		} catch {
 			return;
 		}
@@ -18469,7 +18611,7 @@ async function apply(ctx, config) {
 	logger.info(wellFormed.text && wellFormed.deep ? "well-formed repair: the base kit's wellFormedText/wellFormedDeep (interface v2)" : "well-formed repair: the mem mirror (the base is absent, or predates the v2 helpers)");
 	const compat = env?.compat;
 	let verdict;
-	if (compat === void 0) logger.warn("plugin mount: the dsh compatibility gate is ABSENT (@avantf/dsh-plugin-base unavailable — see the WARNING above); mounting the full plugin anyway");
+	if (compat === void 0) logger.warn("plugin mount: the dsh compatibility gate is UNAVAILABLE (@avantf/dsh-plugin-base is absent, or it is another interface generation — see the WARNING above); mounting the full plugin anyway");
 	else {
 		const run = provision(ctx, logger, compat);
 		if (!run.verdict.load) {
@@ -18631,7 +18773,8 @@ async function apply(ctx, config) {
 	new AvantfMemGateway(ctx, rt);
 	logger.info("remote registered: avantfMem (client ctx.remote.avantfMem.*)");
 	const disposeTypert = ctx.typert.register(hostContribution);
-	logger.info("typert registered: avantfMem host face (5 tools + 5 UI-only)");
+	const toolBackedMethods = descriptors.filter((descriptor) => toolSpecs.some((spec) => spec.key === descriptor.method)).length;
+	logger.info(`typert registered: avantfMem host face (${String(toolBackedMethods)} tool-backed + ${String(descriptors.length - toolBackedMethods)} UI-only Remote methods)`);
 	if (compat !== void 0) verifyRegisteredFaces({
 		ctx,
 		toolNames: toolSpecs.map((spec) => spec.name),

package/lib/interface-version.json

@@ -1,4 +1,4 @@
 {
-  "baseVersion": "0.4.1",
-  "interfaceVersion": 3
+  "baseVersion": "0.5.2",
+  "interfaceVersion": 4
 }

package/lib/types/envinit-bootstrap.d.ts

@@ -3,18 +3,20 @@
  * @module bootstrap
  */
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.5.2";
 /**
  * The framework interval this bootstrap can launch.
  *
- * Kept equal to the plugins' peer range for the base: the plugin passes no override, so THIS is the
- * runtime gate. It is a plain comparator interval, NOT a caret: the package version is ordinary
- * semver again and no longer tracks the interface, so the interval stays as wide as the family's
- * compatibility promise — `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can
- * consume, and stops at the major that invented a new interface generation. The interface itself is
- * the separate, runtime axis: a base inside this interval whose `INTERFACE_VERSION` differs is judged
- * by the base's own gate (INTERFACE.md §1, §3) — an OLDER base degrades, a NEWER one is `ok` + a
- * warning (generations are additive), and neither ever refuses the mount.
+ * This is the PACKAGE-version window, and nothing else: the interval is byte-for-byte the range the
+ * plugins declare in their `dependencies` for the base (the install-time gate; the base is a plain
+ * dependency, not a peer) and the plugin passes no override, so THIS is the runtime gate too. It is
+ * a plain comparator interval, NOT a caret: the package version is ordinary semver and does not
+ * track the interface, so the interval stays as wide as the family's compatibility promise —
+ * `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can consume. Its upper bound
+ * marks no generation boundary. Generation is the separate, runtime axis, judged on its own: the
+ * base's `INTERFACE_VERSION` is compared by the base's gate (INTERFACE.md §1, §3) — an OLDER base
+ * degrades to `incompatible`, a NEWER one is `ok` + a WARNING (generations are additive), and
+ * neither ever refuses the mount.
  */
 export declare const supportedRange = ">=0.3.0 <1.0.0";
 /** Sink for the warnings that replace a throw. */
@@ -49,6 +51,9 @@ export declare function ensureFramework(options: EnsureFrameworkOptions): Promis
 export declare function loadFramework<T = unknown>(options: EnsureFrameworkOptions): Promise<T | undefined>;
 /**
  * Read the range a plugin declares in the nearest `package.json`: walk up from `from`,
- * preferring `peerDependencies` over `devDependencies`; `undefined` when none is found.
+ * preferring `dependencies` over `peerDependencies` over `devDependencies`; `undefined` when none is
+ * found. `dependencies` is the live declaration — the base ships as a normal dependency of the
+ * plugins — while `peerDependencies` stays as the fallback for plugins built when the base was
+ * declared a peer, and `devDependencies` covers a local checkout.
  */
 export declare function readDependencyRange(from?: string): Promise<string | undefined>;

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AASlD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,mBAAmB,EAAU,MAAM,kCAAkC,CAAA;AAE9E,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,EAaL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAA;AAqB7B,eAAO,MAAM,IAAI,eAAe,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAQ7E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AACD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AAkCF,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAOvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBACtB,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa;IAK3C;;;;;;;;;OASG;YACW,IAAI;IAclB;;;;OAIG;IAEH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAMlF,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAMnF,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAKhF;;;;;OAKG;IAEH,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAOpD,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAI5D;;;;OAIG;IAEG,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAUnF,qFAAqF;IAE/E,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAUvE;;;;OAIG;IAEG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAQvG;;;;OAIG;IAEG,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAUpG;;;;;OAKG;IAEG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;CAiBpE;AAmHD,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyYvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AASlD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,mBAAmB,EAAU,MAAM,kCAAkC,CAAA;AAE9E,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,EAaL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAA;AAqB7B,eAAO,MAAM,IAAI,eAAe,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAQ7E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AACD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AAkCF,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAOvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBACtB,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa;IAK3C;;;;;;;;;OASG;YACW,IAAI;IAclB;;;;OAIG;IAEH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAMlF,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAMnF,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAKhF;;;;;OAKG;IAEH,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAOpD,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAI5D;;;;OAIG;IAEG,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAUnF,qFAAqF;IAE/E,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAUvE;;;;OAIG;IAEG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAQvG;;;;OAIG;IAEG,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAUpG;;;;;OAKG;IAEG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;CAiBpE;AAmHD,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyZvE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avantf/dsh-mem",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "avantf-mem DSH native Cordis plugin: host service + tools + RPC + client tabs 记忆/知识",
   "type": "module",
   "main": "lib/index.js",
@@ -41,7 +41,6 @@
     "node": ">=22.15.0 <23 || >=23.11.0"
   },
   "peerDependencies": {
-    "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
     "@deepseek-ai/cordis": "^4.0.0",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2",
@@ -67,6 +66,7 @@
     }
   },
   "dependencies": {
+    "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
     "exceljs": "^4.4.0",
     "unpdf": "^1.8.1",
     "yaml": "^2.5.0"
@@ -78,10 +78,10 @@
   },
   "devDependencies": {
     "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
-    "@avantf/mem": "0.6.2",
-    "@avantf/mem-contract": "0.6.2",
-    "@avantf/mem-convert": "0.6.2",
-    "@avantf/mem-provision": "0.6.2",
+    "@avantf/mem": "0.6.4",
+    "@avantf/mem-contract": "0.6.4",
+    "@avantf/mem-convert": "0.6.4",
+    "@avantf/mem-provision": "0.6.4",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "lightningcss": "^1.32.0",