@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/docs/internal/R1-READABILITY-FORENSICS-20260919.md

@@ -0,0 +1,127 @@
+# R1 · 长期记忆可读性 · 取证报告（2026-09-19）
+
+> **本文件回答 R1 的待答问题一（取证）与问题三（归因）。**
+> 方法：`artifacts/_probe-r1-readability.mjs`（可重跑），对两份真实记忆文件做**无预设**的六类缺陷量化。
+> **不声称已解决**——修法属问题四，需用户拍板。
+
+---
+
+## 0. 结论先行（三句话）
+
+1. **可读性差的主因在「写入/整理侧」，不在「渲染侧」** —— 空行、重复标题、缺主语都是**文件本身**的属性。
+2. **但渲染侧确有一处独立的、结构性的可读性缺陷**：注入文本**保留了对人无意义的 `<!-- memory:mem_<32hex> -->` 锚点注释**，且**每条各自带一个 `## <日期>`**，导致同一天出现 N 个重复日期标题。
+3. **⇒ 修法是两个方向各自独立的改法**（写入侧结构模板 + 渲染侧呈现），**不是一个**。这正是 R1 问题三要分清的。
+
+---
+
+## 1. 取证数据（真实文件，可复跑）
+
+| 指标 | 用户级 `~/.dsh/memory/MEMORY.md` | 项目 `.../workspaces/--D--dsh-auto-memory--/MEMORY.md` |
+|---|---|---|
+| 体量 | 13,160 字符 / 290 行 | 23,693 字符 / 444 行 |
+| **开头连续空行** | 3 行 | **50 行** ← ★ **打开即空白** |
+| ≥5 行空行块 | 0 处 | 1 处（第 1–50 行） |
+| **空行占比** | 92/290 = **32%** | 165/444 = **37%** |
+| `## ` 段数 | 55 | 27 |
+| **纯日期标题重复** | **15 种**（`2026-08-19`×5、`2026-08-16`×4、`2026-08-17`×3…） | **2 种**（`2026-09-18`×**19**、`2026-09-19`×5） |
+| 缺主语（以标识符/文件名/编号开头） | 0/40 = 0% | **10/66 = 15%** |
+| 过短或无完整句 | 10/40 = 25% | 20/66 = **30%** |
+| 术语密度 ≥1.2/20 字 | 5/40 = 13% | 9/66 = 14% |
+| 单条含 ≥3 分号 | 1 条 | 1 条 |
+
+### 典型样本（逐字取自真机）
+
+**A. 缺主语**（读者不知「谁」）：
+```
+M1 契约行渲染设计定案：不新建独立文件（那会新增状态源，违反 S10.4「不建状态机」）…
+`lib/tier0-catalog-pre.js`：新增 `TIER0_ANCHOR_ID_RE = /^mem_[0-9a-f]…
+isRetrievablePre 只对**未知值** fail-closed（防未来新增枚举时静默放行）。
+```
+⇒ 这三条**都对**，但读者要先知道「M1 是什么」「这个文件在项目里干什么」才能读懂。
+**缺的不是信息，是入口**：一句话说明「这是什么、为什么有这条」。
+
+**B. 无背景**（只有结论）：
+```
+本轮无新增跨项目通用规则。
+无
+无
+```
+⇒ 这类**空转条目**在用户级笔记里占了相当比例（25% 过短），它们不承载信息却占版面。
+
+**C. 结构污染**：
+项目笔记**前 50 行纯空行**；两份文件空行都占三分之一 ⇒ 人工翻阅时大量「翻页无内容」。
+
+---
+
+## 2. 归因（R1 问题三）
+
+### 2.1 主因：写入/整理侧（占绝大多数症状）
+
+| 症状 | 归属 | 证据 |
+|---|---|---|
+| 开头 50 行空行 | **整理侧** | 归档/折叠后未回收空占位（体积从大变小，行号槽位留下） |
+| 同日 N 个重复日期标题 | **写入/整理侧** | 每次 append 都新起一个 `## <日期>`（见 §3 渲染样本） |
+| 空转条目「无」「本轮无新增」 | **写入侧** | 模型在无内容时仍写一条 |
+| 缺主语 / 堆术语 / 无完整句 | **写入侧** | 条目语体无约束（本仓记忆纪律已要求「客观陈述」，但**未要求「自解释」**） |
+
+### 2.2 次因：渲染侧（独立且真实，但症状不同）
+
+**从本会话系统提示逐字摘录**（这是模型实际收到的样子）：
+```
+[项目长期笔记 …\MEMORY.md]
+<!-- memory:mem_cbd99fb31f5045e29ccef19f2eb94615 -->
+## 2026-09-18
+- M1 契约行渲染设计定案：…
+<!-- memory:mem_c0e799eb1cfa4247949733b481a9bece -->
+## 2026-09-18
+- 本仓降级纪律（长期）：…
+```
+
+**三个可读性问题（渲染侧独有）**：
+1. **`<!-- memory:mem_<32hex> -->` 直接进正文** —— 这是给**系统**用的锚点 ID，**对人类读者零信息量**，却每两条占一行；
+2. **每条前各带一个 `## <日期>`** —— 同一天被切成 N 段（项目笔记 `2026-09-18` 出现 **19 次**）；
+3. **超长内容被截断**（本会话可见 `…(截断,完整内容用 memory_recall_pre 或 GUI 面板)`）—— 属**有意的预算控制**，不算缺陷，但用户读到的确实不是全貌。
+
+⇒ **渲染侧的修法是独立的**：锚点可改为不可见/尾注；日期可合并为「同日分组」。
+
+---
+
+## 3. 判据建议（R1 问题二，供拍板时参考）
+
+一条「好读的记忆」应满足（可验收）：
+1. **一句话可答「这是什么」** —— 条目首句必须是自解释的完整句（不是标识符开头）；
+2. **有适用范围** —— 说清「在哪个项目/哪一层用」；
+3. **结论与来源可分离** —— 来源（路径/行号/commit）可折叠或后置；
+4. **不依赖隐藏上下文** —— 不需要读者先知道 M1/R4/G3 是什么。
+
+**可自动化验收的候选探针**（本报告脚本已实现前三条）：
+- 开头空行 = 0、空行占比 < 15%
+- 同日重复 `## ` 标题 = 0（或渲染时合并）
+- 缺主语条目占比 < 5%
+- 空转条目（「无」「无新增」）占比 = 0
+
+---
+
+## 4. 待用户拍板（问题四 · 修法）
+
+| # | 方案 | 改哪里 | 成本 | 影响面 |
+|---|---|---|---|---|
+| **A** | **写入侧结构模板**：强制条目自解释（首句完整句 + 可选「适用范围」） | `index.js` 写侧提示 + 整理器 | 低 | 新条目变好；**旧条目不变**（除非批量重写） |
+| **B** | **渲染侧呈现**：隐藏锚点注释、同日合并标题、清理空行 | `tier0-catalog-pre.js` / 注入渲染 | 低 | 立刻改善**已存在的**条目观感 |
+| **C** | **整理侧清理**：压缩空行、合并同日段、删空转条目 | 整理器（`maintain`/折叠） | 中 | 一次性改善存量；需防误删 |
+| **D** | 检索侧逐条摘要句 | 检索侧 | 高 | 需模型调用，成本最高 |
+
+**Agent 倾向（供参考，不作结论）**：**B + C 先做**（立竿见影且不动写入语义），**A 随后**（防新增）。
+理由：B/C 不改变任何记忆**内容**，只改呈现与排版 ⇒ 风险最低、可回退；A 属写入语义变更，按本仓纪律**需用户拍板**。
+
+---
+
+## 5. 与 ⑪（skill 导出）的关系
+
+⑪ 的导出物是给人/给模型读的 `SKILL.md`。
+**若 ⑩ 的 A 方案落地，⑪ 的导出模板可直接复用同一套「自解释条目」判据** ⇒ 两项有复用价值，但**互不阻塞**。
+
+---
+
+**取证脚本**：`artifacts/_probe-r1-readability.mjs`（可重跑，零依赖）
+**本报告不修改任何代码或记忆内容**，仅取证。

package/docs/internal/R2-EVIDENCE-DEEP-AUDIT-20260918.md

@@ -0,0 +1,140 @@
+# R2 · 静默降级深查报告（evidence 读写不对称）
+
+> 2026-09-18 · 承接 `R1-DEGRADE-AUDIT-20260918.md`
+> 探针：`artifacts/_probe-r2-evidence.mjs`
+> 状态：**根因已定位到代码级**；用户侧触发条件**未复现**（本机无法重放），列明待确认项
+
+---
+
+## 0. 一句话结论
+
+**读侧无条件扫描 + 写侧有条件写入 ⇒ 对满足「写入条件永不成立」的用户，每次 recall 都必然 ENOENT 且静默降级。**
+
+**关键新发现**：**正确的守卫函数 `evidenceRootExists()` 已经存在，却没有用在读侧守卫上** ——
+它只被 `:785` 的**展示统计**（`durableEventsOnDisk`）使用。**这是「有正确工具但没接到该接的地方」。**
+
+---
+
+## 1. 读侧：确认无守卫（附行号）
+
+```js
+// index.js:5889-5897
+const evDir = path.join(dshHome(), 'memory', 'evidence-pre', 'events')   // :5891
+const agg = aggregateEvidenceEventsPre(scanEvidenceEventsPre({
+  listFiles: () => readdirSync(evDir).filter((x) => x.endsWith('.jsonl')),   // :5893 ← 无条件
+  readFile: (name) => readFileSync(path.join(evDir, name), 'utf8'),          // :5894
+}, {}))
+} catch (eImp) { try { diag('evidence-agg 降级为中性(impMap 空): ' + ...) } catch (_) {} }  // :5897
+```
+- **无 `existsSync` 前置**；目录不存在 ⇒ `readdirSync` 抛 ENOENT ⇒ catch ⇒ `impMap` 空
+- 后果：`computeImportancePre` 全体中性（0.5）⇒ dense 臂因子恒 0.75 ⇒ **importance 加权对该用户完全无效**
+
+**★ 同时存在的正确守卫（未被用于此处）**：
+```js
+// context-host-pre.js:167-170
+function evidenceRootExists() {
+  const p = path.join(dshHome(), 'memory', 'evidence-pre')
+  try { return existsSync(p) } catch (_) { return false }
+}
+// 唯一调用点 :785（展示用）
+//   durableEventsOnDisk: evidenceRootExists() ? storeFor().loadEvents().events.length : 0,
+```
+⇒ **同一文件里既有正确守卫、又知道要防目录不存在，却没把它用到读侧**。
+
+---
+
+## 2. 写侧：确认「有条件」（附行号）
+
+```js
+// context-host-pre.js:709-717
+async function persistEvidence(list) {
+  if (!list.length) return                    // ← 条件1：列表非空
+  const st = storeFor()
+  for (const ev of list) { const r = await st.append(ev) ... }
+```
+```js
+// evidence-store-pre.js:109-130
+async append(evidence, opts = {}) {
+  ...
+  mkdirSync(this.eventsDir, { recursive: true })   // :126 ← 懒建：只在首次成功 append 时创建
+  appendFileSync(path.join(this.eventsDir, fname), line + '\n', 'utf8')
+}
+```
+
+**两个调用点都带内容前置条件**：
+| 位置 | 函数 | 前置条件（读源码所得） |
+|---|---|---|
+| `:653` | `emitTextEvidence`（`:614`） | 需 `cites`/`corrections`/`attributed` 至少一类非空；`attributed` 还需 P9a 归因命中 |
+| `:699` | 覆盖观察（`observeToolResult` 链路） | 需 `ok=true` **且** `resultPreview` 含**完整 memoryId token** **且**该 token 在**当前授权 corpus** 中，且 coverage>0 |
+
+**接线本身完整**：`index.js:8531` 无条件 `createContextHost({ engine })`；
+`:9223` 每次工具结果都调 `observeToolResult`；`:1702` 每次 segment 都调 `onToolResult`。
+⇒ **不是"没接线"，而是"接了线但内容条件永不满足"**。
+
+---
+
+## 3. 本机 vs 用户侧（硬证据对照）
+
+| | 本机（开发机） | 用户侧（`C:\Users\Administrator\`） |
+|---|---|---|
+| `evidence-pre/events/` | **存在，21 个文件**，09-18 仍在写 | **不存在** ⇒ 从未成功 append |
+| 推测原因 | 长期有会话活动 ⇒ 内容条件被满足过 | 新装 / 用法未触发任一条件 |
+| 表现 | 无报错 | **每次 recall 都 ENOENT** + 用户可感知功能异常 |
+
+**★ 路径不是拼错**：`release.mjs:93` 有 `['memory/evidence-pre','memory/evidence']`（发布版重命名）
+⇒ 用户报的 `evidence\events` 是**发布版正确路径**。
+
+---
+
+## 4. 缺陷定性
+
+**不是「设计内降级」，是「读写不对称」**：
+
+| 侧 | 契约应是 | 实际是 |
+|---|---|---|
+| 写 | 有内容才写；目录**可不存在** | ✅ 懒建，符合预期 |
+| 读 | 目录可能不存在 ⇒ **必须先判存在** | ❌ **无条件扫描** |
+
+⇒ **两侧对"目录可能不存在"这一事实没有共识**。写侧把"不存在"当正常态（懒建），
+读侧把"不存在"当异常（抛 ENOENT）。**这是契约缺口，不是容错不足。**
+
+与 M8/M9 同族：**功能存在、代码在跑、输入永远为空**。
+
+---
+
+## 5. 修法（候选，待用户批准后实施）
+
+| 方案 | 内容 | 评价 |
+|---|---|---|
+| **E-1** | 读侧加守卫：`existsSync(evDir)` 为假 ⇒ **静默返回空**（不报错、不计降级） | ✅ 消除噪音与异常开销；**与写侧契约对齐** |
+| **E-2** | 写侧改为**注册期确定性建目录** | ⚠️ 需先确认是否该让所有用户都建（**未验证**） |
+| **E-3** | 走 R3 留痕：把「importance 恒中性（因无证据事件）」变成**可见状态** | ✅ 让"这条臂没在工作"可查 |
+
+**倾向 E-1 + E-3**：
+- E-1 是**契约对齐**（读侧承认"目录可不存在"），非补丁
+- E-3 满足 R3 判据（这属**预期外失败**还是**预期内分支**？
+  ⇒ 判定为**预期内分支**：无证据事件是合法状态，**不该报错**；但**"这条臂未生效"应当可见**）
+
+**E-2 暂缓**：为何该用户从未触发写入**未查清**（内容条件依赖真实用法，本机无法重放）。
+在未查清前改写入时机有风险（可能改变既有用户的数据行为）。
+
+---
+
+## 6. 待确认（未下结论，不得当结论用）
+
+1. **用户侧内容条件为何永不满足？** 三个候选，**均未验证**：
+   (a) 新装无历史 ⇒ `corpus` 为空 ⇒ memoryId token 匹配不上
+   (b) 用法不触发（纯对话、无工具结果引用记忆）
+   (c) 其他配置/版本差异
+   ⇒ 需用户侧配置或复现步骤；**本机无法重放**。
+2. `evidence` 与 `evidence-pre` 两套目录在发布版是否都存活？
+   ⇒ 本机只有 `evidence-pre`（无 `evidence`）；`release.mjs:169` 有文件重命名映射。
+   （**待查**：发布版是否也把目录名一并改掉，即用户侧应是 `evidence` 而非 `evidence-pre` —— 报障路径显示是 `evidence`，**与重命名一致**。）
+
+---
+
+## 7. 对后续的影响
+
+- **R3 留痕层的判据在此得到实例**：E-1 属「预期内分支」（静默、不留痕）；
+  但**"importance 臂整体未生效"应作为状态可见**（E-3）。
+- **优先级**：本项不阻塞 M2.5b（layer 臂）；但**建议与 R3 同批**，因为留痕层正好覆盖它。

package/docs/internal/R3-DEGRADE-LEDGER-DESIGN-20260918.md

@@ -0,0 +1,138 @@
+# R3 · 降级留痕层 设计定稿（待批准）
+
+> 2026-09-18 · 上游：`R1-DEGRADE-AUDIT-20260918.md`、`R2-EVIDENCE-DEEP-AUDIT-20260918.md`、`BATTLE-PLAN-20260917.md §3.6`
+> **状态：设计待用户批准，尚未写代码**
+
+---
+
+## 0. 一句话目标
+
+**让「某条臂静默失效」从"用户只感到检索不太对"变成"可查询的状态"。**
+不是消灭降级（fail-soft 是对的），而是**让降级可见**。
+
+---
+
+## 1. 核心判据（R1/R2 已得出，这里是设计前提）
+
+**必须区分两类，绝不能一律报：**
+
+| 类别 | 定义 | 实例 | 处置 |
+|---|---|---|---|
+| **预期内分支** | 该状态是**合法业务状态** | 无证据事件（R2-E1）、查询无时间表达（`tr=null`） | **静默，不报** |
+| **预期外失败** | 该状态**不该发生** | 引擎抛错、目录 ENOENT、worker 拒绝 | **留痕** |
+
+**若一律报** ⇒ 每次 recall 都会刷"无时间臂"（因为绝大多数查询不含时间表达）⇒ **噪音淹没信号**。
+
+---
+
+## 2. 形态选择（三选一，我推荐 A）
+
+| | 方案 | 评价 |
+|---|---|---|
+| **A** | **内存环形缓冲 + 状态文件**：`degrade()` 写内存（有界 N 条）+ **定时/按需 flush 到一个 JSON 状态文件**；面板读该文件 | ✅ **零新增常驻状态机**（符合 S10.4）；面板与宿主解耦，不要求宿主常驻 |
+| B | 纯内存 + debugView 暴露 | ❌ 宿主重启即丢；用户报障后无法回看 |
+| C | 每次降级直接写日志文件 | ❌ 高频写盘 + 与既有 diag 重复 |
+
+**推荐 A 的理由**：本项目已有同类先例 —— `.dsh/memory/` 下的状态文件（如 `evidence-pre/`、`l0-index-*.json`）
+都是**可查询的磁盘状态**。留痕层应复用这个范式，而不是新造一个状态机。
+
+---
+
+## 3. 接口设计
+
+```js
+// lib/degrade-pre.js（新文件，纯函数 + 一个有界收集器）
+export function createDegradeSinkPre({ now, cap = 200 })
+  → {
+      record(kind, reason, detail)   // kind: 'semantic-arm' | 'evidence-arm' | 'temporal-arm' | 'l0-sync' | ...
+      snapshot()                     // 返回当前缓冲（含 counts + 最近 N 条）
+      counts()                       // { kind: n } 便于断言
+      reset()
+    }
+```
+
+**纪律（写进代码注释与套件）**：
+1. **只记录、不阻断** —— `record()` 内部整体 try/catch，任何异常都被吞掉
+2. **不得因留痕失败而二次失败** —— 留痕自身 fail-soft 到静默（这是 R3 的元规则）
+3. **有界** —— cap=200 + 每 kind 计数（防内存增长）
+4. **不含原文** —— 只存 kind/reason/时间/计数，**隐私边界与既有 diag 一致**
+5. **不新增配置键用于开关** —— 默认开启（这是观测面，不是业务功能）
+
+---
+
+## 4. 接线点（最小集，先接 4 条臂）
+
+| 位置 | 现有代码 | 改为 |
+|---|---|---|
+| `index.js:5877` | `catch (eBest) { diag('recall 语义臂择优降级…') }` | `+ sink.record('semantic-arm', ...)` |
+| `index.js`(evidence 段) | `catch (eImp) { diag('evidence-agg 降级…') }` | `+ sink.record('evidence-arm', ...)` |
+| `index.js:5908` | `catch (eTr) { diag('temporal-parse 降级…') }` | **不动**（预期内分支） |
+| `index.js:8795` | `catch (e) { diag('l0-index sync 降级…') }` | `+ sink.record('l0-sync', ...)` |
+
+**注意 `:5908` 不动** —— 这是判据的实际应用：无时间表达是**正常路径**，记它只会制造噪音。
+**但**：若 `parseTemporalQueryPre` **本身抛错**（而非返回 null），那是预期外 ⇒ 应当记。
+⇒ 需在实现时**把"返回 null"与"抛错"分开**（当前两者混在同一个 catch 里，这本身也是个小缺陷）。
+
+---
+
+## 5. 可见性（面板/状态文件）
+
+**产出物**：`<dshHome>/memory/degrade-pre/latest.json`
+```json
+{
+  "schemaVersion": 1,
+  "updatedAt": "2026-09-18T20:10:00+08:00",
+  "counts": { "semantic-arm": 3, "evidence-arm": 0, "l0-sync": 1 },
+  "recent": [ { "kind": "semantic-arm", "reason": "...", "at": "..." } ]
+}
+```
+
+**E-3 落地方式**：额外记录一条**臂健康快照**（不是降级，是状态）：
+```json
+"arms": { "semantic": "active", "evidence": "no-input", "temporal": "on-demand", "l0Sync": "ok" }
+```
+⇒ 这样用户/面板能直接看到「**evidence 臂 = no-input**」，
+而不是靠"每次 recall 都 ENOENT"来推断。
+
+---
+
+## 6. 与既有机制的边界（防重复建设）
+
+| 已有 | 关系 |
+|---|---|
+| `diag()` | **保留**。diag 是**过程日志**（滚动、即时）；degrade 是**状态**（可查询、可聚合）。两者互补，不替代 |
+| `_lastIndexDegrade`（index.js:5015 提到） | **需先查清**它是否已是一个同类机制 ⇒ 若是，R3 应**并入**而非新建（避免第二个状态源） |
+| 白板 lint「只读+留痕」 | **同源纪律**：lint 只读不写盘但留痕；degrade 同理 |
+| S10.4「不建状态机」 | ✅ 本设计是**观测面**，不参与业务判断 |
+
+**★ 建前必做（已完成 2026-09-18 20:05）**：查 `_lastIndexDegrade` 与 `debugView()`，确认不重复造轮子。
+
+**前置检查结论（已证实无需并入，可新建）**：
+
+| 查什么 | 实证结果 | 判定 |
+|---|---|---|
+| `_lastIndexDegrade` | `context-host-pre.js:112` `let lastIndexDegrade = null` + `:373` 赋值 —— 是 **单值兼容投影**（供旧读取方），**非收集器** | ❌ 不是同类机制 |
+| `debugView()` | 存在于 7 个 host（shadow/context/activation/activation-inbox/index-sync/rerank/python-sink），各返回**本域局部状态** | ❌ 非跨臂统一台账 |
+| `createDegrade*` / `recordDegrade` 等 | 全仓 grep **零命中** | ✅ 无重复 |
+
+⇒ **R3 是新建，与既有机制互补**：
+- `diag()` = **过程日志**（滚动、即时、人读）
+- `debugView()` = **各域局部状态**（分散、按 host）
+- `degrade` = **跨臂统一台账**（聚合、可查询、面向"哪条臂失效了"）
+
+---
+
+## 7. 验收
+
+1. 新增套件 `smoke-test-r3-degrade-pre.mjs`：接口契约 / fail-soft / 有界 / 隐私 / 计数正确
+2. **变异演示**：故意在 `catch` 里抛错 ⇒ 断言**主流程不受影响**（留痕自身 fail-soft 生效）
+3. 断言 `:5908`（无时间表达）**不产生留痕**（判据的正确性）
+4. 全量回归维持 **PASS 115+ / FAIL 0**
+
+---
+
+## 8. 待用户拍板的三个点
+
+1. **形态 A（内存+状态文件）是否认可？** 还是希望纯面板内存（B）？
+2. **状态文件位置**：`<dshHome>/memory/degrade-pre/latest.json` 是否合适？
+3. **是否同意"**先查 `_lastIndexDegrade` 再动手**"作为硬前置**？

package/docs/internal/R4-RECALL-QUOTA-PLAN-20260918.md

@@ -0,0 +1,218 @@
+# R4 · 检索区分度与配额治理（2026-09-18 用户批准立项）
+
+> **来源**：用户 2026-09-18 对话中提出的三个真实痛点 + 一处实测 bug。
+> **用户原话**：
+> - 「现在其实还是区分度有点问题，更加有含金量的结论和每一次都有的日志会混在一起。在 memory recall（记忆唤起）的时候，有什么好的处理方式吗？」
+> - 「配合这个问题也困扰我很久。有的时候配额太少，效果完全没有，或者有些大条目可能就被过滤掉了，一点用都没有；有的时候配额多了，我又怕浪费 token」
+> - 「我尝试把其中一个固定额度加大成两倍的时候，还遇到了一个锁死的问题。所以现在确实需要整一整额度的问题了。不过，确实得基于长期的观察，科学的（测量），不能拍脑子。」
+> **归口**：本节独立于 L/M/S 执行顺序（不参与层级冻结），但**用户已批准纳入作战计划**。
+
+---
+
+## 0. 一句话
+
+**结论与流水在检索里区分度不足** —— 语义臂内部完全不分层，融合层的层次优势（≈0.001）被流水层的数量优势（本机 449 vs 16）淹没。同时，**配额系统存在一个已确认的「锁死」缺陷**（见 §3），必须一并治理。
+
+---
+
+## 1. 实测证据（本次勘查，附行号）
+
+### 1.1 语义臂内部完全不分层
+
+```js
+index.js:6048-6057  corpus 收集：所有来源**平铺**进一个数组（layer 字段存了但没用）
+index.js:6068       filter(sc >= minScore)       ← 只看分数
+index.js:6069       sort((a, b) => b[1] - a[1])  ← ★ 纯分数倒序，不看 layer
+index.js:6070       slice(0, max(2, limit))
+```
+
+### 1.2 检索输出**不显示 layer**
+
+```js
+index.js:6093  out.push('· ' + s.label + ' [' + s.id8 + '] ×' + s.score.toFixed(2) + ' ' + s.l0)
+index.js:5977  out.push('· [' + c.id + '] ×' + sc + fr + ' ' + reason + ' ' + label + ' — ' + l0)
+```
+⇒ 模型看到的两个 `MEMORY.md`（结论）与三个 `2026-09-xx.md`（流水）**视觉上完全同级**。
+
+### 1.3 层次优势被数量优势碾压
+
+| 层 | rank 1 时的 RRF 贡献 | 本机语料量 |
+|---|---|---|
+| project（结论） | `1/(60+1)` = 0.01639 | **16 条** |
+| log（流水） | `1/(60+5)` = 0.01538 | **449 条** |
+
+差距 **0.001**，而流水数量是结论的 **28 倍**。⇒ 结论在检索中几乎必然被淹没。
+
+### 1.4 ★ 但这个能力**注入侧早就有了**（可直接复用）
+
+```js
+tier0-catalog-pre.js:391  TIER0_QUOTA_DEFAULTS = {
+  projectRatio: 0.6,
+  floorRatio: 0.1,
+  projectLayer: 'project',
+  floorLayers: ['whiteboard', 'user'],
+}
+```
+其 docblock 原话点明了同一个问题：「语料实测 77 块把 800 token 全占，whiteboard/user/log 一条都进不来，**分层退化成单层**」。
+
+⇒ **注入侧已解决，检索侧没有。** 这是本项工作的核心不对称。
+
+---
+
+## 2. 三个方案（用户已批准"可以加进作战计划"）
+
+### ★ 方案 A：作废条目**返回但显式标记** + 指向最新结论
+
+**现状**：`index.js:5838` `if (!isCurrentPre(it)) continue` ⇒ 作废条目**被完全跳过**，模型不知道它存在过，也不知道有过"此路不通"的教训。
+
+**改为**：
+```
+✗ [已作废] MEMORY.md [a1b2c3d4] — 旧结论：方案用 A 实现
+            ↳ 已被取代，最新结论见 mem_x9y8z7w6
+```
+
+**关键前置**：需要 `supersededBy` 指针字段（记录"被谁取代"）。
+- 现状：`status` 只有三值，**没有指向后继的字段**
+- 建议：G3 写 `superseded` 时**顺便记下取代者 id**
+- ⚠️ **待确认**：这是否违反 S10.4「不新建状态源」？
+  （**倾向不算** —— 它是 `status` 的伴生属性，与 `status` 同级；但需用户/文档明确）
+
+### ★ 方案 B：检索结果**分层展示**（用户：「分层显示可以先做」）
+
+**不改排序**，只改**呈现**：
+```
+【结论层 · 项目笔记/用户级】
+· MEMORY.md [e5f6g7h8] ×0.79 项目铁律：写入前必须备份
+· MEMORY.md [m3n4o5p6] ×0.77 架构决策：语义臂可降级
+
+【流水层 · 每日日志】
+· 2026-09-18.md [a1b2c3d4] ×0.82 今天修了个 bug
+```
+**零排序风险** —— 直接解决"看不见层次"的问题。**建议先做这个。**
+
+### ★ 方案 C：检索侧**层次保底配额**（用户：「单独评估」）
+
+复用注入侧 `TIER0_QUOTA_DEFAULTS` 的思路：语义臂输出时给 project/whiteboard/user **保底条数**，即使分数低也保证露面。
+
+⚠️ **会改变排序结果** ⇒ 必须单独评估、单独验证。
+
+---
+
+## 3. ★ 「锁死」缺陷（用户实测踩到，本次定位到代码级）
+
+**用户原话**：「我尝试把其中一个固定额度加大成两倍的时候，还遇到了一个锁死的问题。」
+
+### 机制（附行号）
+
+```
+:4621 capacityLimit(layer)        读 userCapacityChars/noteCapacityChars，<500 视为脏值回落默认
+:4655 ensureBudget                 超限 → 进入整理循环（最多 3 轮）
+:4744 const allowFold = !(last && now - last < COMPACT_THROTTLE_MS)
+:227  COMPACT_THROTTLE_MS = 10 * 60 * 1000     ← ★ 10 分钟节流
+:4799 / :4917 return { ok: false, reason: 'no-removable' }
+:4832 this._lastCompactAt[layer] = Date.now()  ← 整理过一次就上锁 10 分钟
+```
+
+### ⛔ 本节的「节流锁死」推断已被实测证伪（2026-09-18 23:15 更正）
+
+> **下面从"锁死的三步成因"起的整段分析作废，保留仅为记录推断过程。**
+> 复现证据见 `artifacts/_probe-budget-lockup.mjs`（抽取生产方法体真实执行，10/0）与
+> `tests/smoke/smoke-test-r4-budget-lockup-pre.mjs`（25/25）。
+
+**证伪的三条硬证据**：
+
+1. **`reason:'throttled'` 是死分支** —— 全仓 grep 仅有 6 处命中，其中**没有任何生产者**，
+   只有 `budgetRefusalTextPre` 里的文案。既然没有代码路径返回它，"被 throttled 拒绝"不可能发生。
+2. **节流只挡 AI 折叠、不挡整条归档** —— `compactLayer` 的注释（`:4742` 附近）即如此声明；
+   实测「整理一次 → 10 分钟窗口内第二次写入」**成功**，不存在 10 分钟锁。
+3. **真缺陷在别处，且是 legacy 路径（出厂默认走这条）**，两处：
+   - **`keepBudget` 口径用错变量**：旧式 `Math.max(COMPACT_PROTECT_RECENT_CHARS, limit - deficit - 1)`
+     展开即 `2*limit − curChars − add − 1` ⇒ **保留目标随额度单调递增**（方向反了），
+     且把保护窗口从**软**下限变成**硬**下限 ⇒ 额度落进死亡区间时被拒、**更小和更大的额度却能写** = **非单调**。
+     修为 `Math.max(0, curChars - deficit - 1)`。
+   - **回写量护栏缺失**：「AI 不可用」分支把刚归档的老段落**原样写回**主文件
+     （实测 `[compacted] note: 1729 -> 1730 chars`，不降反升）⇒ **归档发生了、空间却没腾出来**
+     ⇒ 三轮后返回 `still-over-capacity`。补上锚点路径同款护栏。
+
+**为什么原推断看起来很合理**：`:4832` 确实在成功路径上无条件打 `_lastCompactAt` 时间戳，
+`compactLayer` 也真的读了 `allowFold` —— 但那个标志**只决定"要不要再跑一次昂贵的 AI 折叠"**，
+与"能不能写入"无关。**教训（可复用）：看到时间戳 + 节流常量，不等于看到拒绝路径；
+判断一个 reason 是否是活分支，grep 生产者而不是读消费者文案。**
+
+### （已作废）原推断：锁死的三步成因
+
+1. ~~用户调大配额 ⇒ 但文件里已有内容不变 ⇒ 本不该再拒绝~~
+2. ~~若仍超限 ⇒ 触发整理~~
+3. ~~整理成功一次后上锁 ⇒ 10 分钟内任何再写入都被 `throttled` 拒绝~~
+
+### （已作废）原推断：更隐蔽的一层
+
+~~`:4689` `still-over-capacity` 时 10 分钟锁同样生效 ⇒ "没腾出空间"与"节流中"叠加。~~
+**实际成因**：是回写护栏缺失（见上），与节流无关。
+
+### 待办 → 已全部完成（2026-09-18）
+
+- [x] **复现**：已写探针与套件，**推翻了原假设**（不是 throttled，是 keepBudget 口径 + 缺护栏）
+- [x] **判定**：判定为**缺陷**（非设计），且是**默认可达、用户可见**的缺陷
+- [x] **修复**：`keepBudget` 修为 `max(0, curChars - deficit - 1)` + 补回写护栏
+- [x] **验收**：套件 25/25 · 变异 5/5 真红 · SHA256 逐字节还原 · 全量回归 PASS 121
+
+---
+
+## 4. 配额调优：用户要的「科学测量」而非拍脑袋
+
+**用户原话**：「确实得基于长期的观察，科学的（测量），不能拍脑子。」
+
+### 现状：配额是**静态配置**，没有测量回路
+
+| 键 | 默认 | 作用 |
+|---|---|---|
+| `injectBudgetChars` | 8000 | 每轮注入总预算（**与容量上限是两回事**，见 `:296` docblock） |
+| `tier0MaxTokens` | 400 | Tier-0 目录 token 上限 |
+| `tier0BudgetShare` | 0.25 | 目录占总预算比例 |
+| `noteCapacityChars` / `userCapacityChars` | 24000 | **文件本体**容量（M9 刚调过） |
+
+### 已有的观测面（可复用，不新建状态源）
+
+```js
+index.js:6537  budgets: (() => { ... })      ← debugInfo 已暴露
+index.js:5099  state.tier0Meta = { tokens, items, candidates, dropped, perLayer }
+index.js:5040  const budgetChars = Math.max(Number(cfg.injectBudgetChars) || 1600, 400)
+```
+
+**`tier0Meta` 已含 `candidates / dropped / perLayer`** ⇒ **"因为配额被丢掉多少条"这个数据已经在采集了**，只是没被用来调参。
+
+### 建议的测量闭环（不新建状态源，复用 degrade 台账）
+
+1. **采集**：每轮把 `tier0Meta.dropped / perLayer` 追加到 degrade 台账（已有落盘通道）
+2. **观察**：面板展示「近 N 轮各层 dropped 趋势」
+3. **判定**：某层**长期 dropped > 0** ⇒ 配额偏小；**长期 dropped = 0 且远未用满** ⇒ 配额偏大、浪费 token
+4. **再调整**：按观察结果改默认值，**不拍脑袋**
+
+> **与 R3 降级台账同源**：degrade 台账本来就是「跨轮可查询的观测面」，配额测量是它的第二个消费者（第一个是降级事件）。**零新建状态源。**
+
+---
+
+## 5. 优先级与依赖
+
+| 项 | 风险 | 依赖 | 建议顺序 |
+|---|---|---|---|
+| **B 分层展示** | 极低（只改呈现） | 无 | **第 1** |
+| **降级留痕补齐**（py→C2→词法每一跳） | 低 | 无 | **第 1**（与 B 同批） |
+| **§3 锁死复现 + 修复** | 中 | 需先写复现套件 | **第 2** |
+| **§4 配额测量闭环** | 低（只采集） | 复用 degrade 台账 | **第 2** |
+| **A 作废标记 + supersededBy** | 中 | G3 实施后 | **第 3**（随 G3） |
+| **C 层次保底配额** | 高（改排序） | 需 A/B 先跑出数据 | **第 4**（单独评估） |
+
+---
+
+## 6. 与既有工作的关系
+
+- **G3**（结论层状态写入）：A 方案依赖 G3 写 `supersededBy` ⇒ **两者合并实施**
+- **R3 降级台账**：§4 配额测量复用其通道；降级留痕补齐也是 R3 的收尾
+- **M2.5b 层次臂**：本项是它的直接延续 —— 层次臂"只能放大已有优势"，而 **C 方案是"给结论保底露面"**，二者互补
+- **S10.4**：全项**不新建状态源**（A 的 `supersededBy` 需确认边界）
+
+---
+
+*本文档为专项立项，执行细节并入 BATTLE-PLAN 的 R 系列。*