@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/docs/hive//345/244/232/347/253/257harness/351/200/232/344/277/241/345/245/221/347/272/246_v0.1.md

@@ -0,0 +1,42 @@
+# 多端 harness 通信契约 v0.1
+
+**目标**：验证不卡死在任何单一端。任何具备"读共享目录 + 回执"能力的端都可充当验证方；无端认领时由内部独立复核通道顶上，两者并账。
+
+## 1 投放（我方 → 任何验证端）
+- **位置**：`hive/interop/<iter_id>/request.json`（与 `note-unit-review.json` 并列）
+- **必填字段**：`kind=verify-request`、`iter_id`、`branch`、`candidate_commit`、`claim_signal`、`claim_min`、`created_ts`
+- **认领信号（二选一即可）**：
+  1. 写 `hive/interop/<iter_id>/picked.json`（`{"verify_id": "<iter_id>", "picked_ts": <unix>}`）；
+  2. 在 `hive/interop/_receipts_ledger.tsv` 追加一条引用该 `iter_id` 的回执（历史端走的就是这条）。
+
+## 2 认领时限与升级（机械执行）
+- 由 `_coord/multiport.py sweep` 每 300s 执行一次：
+  - 有认领信号 → `claimed`（记录 `claimed_via`）；
+  - 超 `claim_min`（默认 10 分钟）仍无 → `escalated`，**自动转入内部独立复核通道**（`md_cg.units` 自足式作业）；
+- 状态落在 `hive/interop/_dispatch_ledger.tsv`（列：ts/iter/branch/commit/status/claim_by/claimed_via/note）。
+
+## 3 双通道并账
+- 同一候选可同时对外投放、对内复核；两侧 verdict 都写入台账；
+- **外部回执到达即补验并追加记录**，不因内部通道已过而丢弃外部证据。
+
+## 4 水位与事实来源
+- 事实来源优先级：`note-receipt-*.json` → `_receipts_ledger.tsv` → 各端自报 state/heartbeat；
+- 水位推进以**台账 + 认领记录**为准，不以任一端的口头报告为准。
+
+## 5 硬约束
+- 验证方**不得**改写被验证仓的源码与测试；jobs 写入属通道例外；
+- 我方**不得**用内部通道伪装外部 PASS：内部通道结论在台账中标注 `via=internal`，与外部 `via=<provider>` 区分。
+
+## 6 结算与升级（机械执行）
+- **状态机**：`offered` →（窗口内认领）`claimed`；→（超 `claim_min`）`escalated` →（内部独立复核）`internal-verified`；被后继版本顶替的候选标 `superseded`。
+- **`_coord/multiport.py dispatch`**：结算 `offered`/`escalated` 条目，读该 iter 的 `note-unit-review.json` 口径：
+  - `verdict=ACCEPT` → `internal-verified`，`claimed_via=internal:ACCEPT`（**仅内部口径，不冒外部 PASS**）；
+  - `REJECT/DEFER/BLINDSPOT/未解析` → 保持待处理并提示重做候选；**不得**记为 verified。
+- **`supersede --iter <id> --note <原因>`**：内部复核判 REJECT 且已有后继版本时使用，并在该 iter 目录写 `note-supersede.json`（`verdict_of_record` / `reason` / `superseded_by` / `superseding_commit`）。
+- **纠正义务**：若 `request.json` 曾声明的 `unit_review.verdict` 与 note 实际不符，必须如实更正并把历史写入 `verdict_history`；隐瞒即等同伪造通过。
+- **实现要点（历史实例，2026-09-18）**：协作脚本里的仓库路径必须显式绝对——曾用 `dirname³(__file__)`，脚本位于 `_coord/` 时解析到用户主目录，导致 note 永远读不到、状态永远停在 `escalated`（表现为"对方没回执"）。凡"读不到 note"，先核对路径解析，再怀疑对方。
+
+## 7 一眼可见的投放索引
+- `_coord/multiport.py status --index hive/interop/_offers_index.md` 生成 `hive/interop/_offers_index.md`（**机生成，勿手改**）；
+- 任何验证端只读这一个文件即可知道：有哪些候选、分支/commit、状态、认领方式、备注；
+- 索引与账本同源（`_dispatch_ledger.tsv`）；**账本是唯一事实来源，索引只是视图**。

package/docs/hive//346/243/200/347/264/242/346/224/266/346/225/233/345/256/236/346/265/213/344/270/216S1b/350/256/276/350/256/241_v0.1.md

@@ -0,0 +1,43 @@
+# 检索收敛口径实测与 S1b 设计（真实库 12,149 节点，只读）
+
+> 目的：为「重接检索线路」的价值边界提供**实测**依据，并据此确定下一个核心任务（S1b）。
+> 全部为只读测量（`MdCG(真实库)` + 抽样分类），未对真实库做任何写入。
+
+## 1. 两条收敛口径的实测对比
+
+| 口径 | 键 | 覆盖率 | 收敛强度 | 证据 |
+| --- | --- | --- | --- | --- |
+| **粗：14 大域**（本轮 S1 已落地） | `big_domain_classify`（关键词表） | 已标注 **58.3%**；无域信号 41.7% | 域内 ∪ 未标注 ≈ **44%~52% kept（约 2 倍）** | 240 节点抽样：binary 140 / tier2 +6 / 仍无标签 94 |
+| **细：路由桶**（写入侧已建好） | `bucket_dir(route_key(...))` | **91.1% 节点有非 orphan 桶**（11,063 / 12,149） | **期望扫描 2.1%**（1,066 桶，最大桶 10.1%） | 全库统计 |
+
+细口径的桶形如 `cond_感知系统_d94e90d2`、`cond_letta-code_f5190c71`、`cond_graphrag_f0f8d2e7` —— 是
+**来源/项目级域**（来自 `domain:` 标签或 `observation_position`），比 14 大域精细得多。
+
+## 2. 现状（代码事实）
+
+`MdCG.search()` **已经有 T0/T1 桶路**：当调用方传入 `context` 时，
+`route_bucket = bucket_dir(route_key(ctx, ctx.get("tags")))`，优先只在同桶内 LIKE 检索（T0），
+不足再桶内全扫（T1），仍不足才落 T2/T3 全库。
+
+**缺的只有一环**：不传 `context` 的普通 `search(q)` 没有桶 → 直接全表扫描。
+（审计「偏差 5：桶路由依赖人工标签」在**自动沉淀的库**上成立；本真实库 91% 有桶，桶路是健康的。）
+
+## 3. S1b 设计（下一个核心任务）
+
+**目标**：让 `search(q)` 在**没有 context** 时也能吃到细口径收敛。
+
+1. **桶规模表**（索引内即可构建，缓存）：`bucket → 节点数`（本库 1,066 桶）。
+2. **query 侧键推断**：把 query 扩展词与每个桶的可读前缀做 `domain_similarity`（已有：包含取长度比 + bigram Jaccard），
+   取 top-k 个键（`MDCG_BUCKET_TOPK`，默认 3）且要求 `sim ≥ MDCG_BUCKET_MIN_SIM`。
+3. **收敛**：候选 = 命中桶内节点 ∪ **orphan/无桶节点**（召回安全，本库 orphan 仅 8.9%）∪ 未标桶节点。
+4. **兜底**：命中不足 `min_results` → 回退全库（与 S1 同款规则）。
+5. **开关**：`MDCG_GATE_S1B_BUCKET`（默认 0、显式 =1）；审计 `meta.gates.s1b = {keys, kept, dropped}`。
+
+**预期收益（按本库实测推算）**：query 命中具体桶时 kept ≈ 该桶(期望 2.1%) + orphan(8.9%) ≈ **11%**
+→ 约 **9 倍**；命中大桶时 ~19% → 5 倍；命中不到任何桶时自动回退（不劣化）。
+
+## 4. 边界
+
+- 不改写入侧（桶已由 `route_key` 在写入时建好）；
+- 不放松召回安全：orphan/无桶节点恒留兜底，命中不足即回退；
+- 与 S1（14 大域）可叠加：S1 先按大域收敛，S1b 再按桶收敛（两者都有兜底）。

package/docs/hive//346/243/200/347/264/242/350/267/257/345/276/204/344/270/216/350/256/244/347/237/245/347/273/223/346/236/204/345/245/221/347/272/246_v0.1.md

@@ -0,0 +1,102 @@
+# 检索路径与认知结构契约 v0.1
+
+> 立约动因：外部审计（2026-09-19）发现「认知结构全部入库，但检索路径不调用它们」——
+> 五条偏差经本侧逐行核对**全部成立**（证据见 §1）。缺的不是能力，是**「结构如何参与检索」的契约**。
+> 本文件就是把这份契约写下来，作为重接线路（retrieval rewire）的判据。
+
+## 1. 审计核对（本侧逐行验证，origin/main 口径）
+
+| # | 审计结论 | 核对证据 | 判定 |
+| --- | --- | --- | --- |
+| 1 | edges 图建了但检索不走图 | `md_cg/mdcg.py::search()` 候选 = `self.index["nodes"].values()` 全枚举（L1506-1511）→ `_read_many` 全读（L1574/L1601-1613）→ `_like` 子串 + bigram；全路径**零** edges 引用 | 成立 |
+| 2 | condition_space 是后置过滤 | `judge_qualification` 只在 `_emit` 内、且对 `scored[:k]` **排序后**逐条判定（L1670-1679）；扫描与打分已全部付出 | 成立 |
+| 3 | 五层只是分类标签 | `layer` 仅作候选构建时的等值过滤（L1507）；打分不含层级先验；负记忆只在结果尾部附加条目（L1681-1692），不抑制正候选 | 成立 |
+| 4 | 大域先验只进元数据 | `big_domain_classify` / `big_domain_score_breakdown` 算出后只传入 `_emit` 的 meta（L1542-1543 → L1711-1712），不参与候选收敛 | 成立 |
+| 5 | 桶路由依赖人工标签 | `routing.route_key`：tags 首个 `domain:` → 否则 `observation_position` 归一化 → 否则 `ORPHAN`（L55-67）；DSH 自动沉淀不打 `domain:` → 多落 orphan | 成立（observation_position 一档属降级回退） |
+
+共同主线：**认知结构被实现成「数据结构」而不是「计算路径」** —— 存进去、建起来，但检索时不用。
+
+## 2. 目标形态：检索 = 六阶段逐级收敛（而非全扫后过滤）
+
+```
+情境输入(query, context)
+  ↓ S1 大域先验收敛      terms → big_domain_classify → 域集合；候选 = 该域节点 ∪ ORPHAN 兜底
+  ↓ S2 条件空间前置门控  condition_space 硬槽（time_window/observation_position/存在约束）不匹配 → 不进候选
+  ↓ S3 图扩散激活        以 (S1∩S2) 命中为种子，沿 edges 双向扩散 N 跳、按跳数衰减；不走全表
+  ↓ S4 层级激活优先级    anchor/self 初始激活值加成（认知优先级，不是过滤）
+  ↓ S5 负记忆抑制        rejected/unresolved 命中 → 对相关正候选乘性降权（抑制信号）
+  ↓ S6 一致性交叉验证    对最终 top-k 做 crosscheck（复用 md_cg/crosscheck.py）
+输出: 激活子集 + 分阶段审计计数
+```
+
+**每一步都在缩小范围**：触碰节点数应从「N(全库)」降到「域内 ∩ 条件匹配 ∩ 邻域」。
+
+## 3. 各阶段契约（输入 / 输出 / 不变量 / 失败模式）
+
+### S1 大域先验收敛
+- 输入：`terms`（`expand_query_terms` 结果）、节点 frontmatter 的**域标签**
+- 输出：`domains`（top-1 或 top-m，由 `big_domain_score_breakdown` 阈值决定）
+- 依赖：**节点侧域标签**。现状只有 query 侧分类器，节点侧无域字段 → 需写入侧推断并持久化 `big_domain`（内容 → `big_domain_classify`），历史节点由回填器补齐
+- 不变量：域收敛**不得丢召回**——ORPHAN/未标域节点必须留在兜底池；域内候选 < `min_results` 时自动放行兜底
+- 失败模式：域分类错误 → 兜底路径必须能救回
+
+### S2 条件空间前置门控
+- 输入：`condition_space`（每节点已存）、`context`（调用方情境）
+- 输出：通过门控的候选（**不读正文**即可判定：只用 frontmatter）
+- 只前移**可判定的硬槽**：`time_window` / `observation_position` / 存在约束；语义类判定仍留 `judge_qualification`（后置，因需正文）
+- 不变量：只剔除「明确不匹配」；**信息不足一律放行**（宁多勿漏）
+
+### S3 图扩散激活
+- 输入：种子集合、`edges`（出边在 `fm.edges`；白箱 KB 的 `edges` 表按 source/target 双索引）
+- 输出：激活集合 + 激活值（种子 1.0，第 n 跳 × 衰减^n）
+- 不变量：扩散**不得引入未通过 S2 门控**的节点；边方向/关系类型权重可配
+- 失败模式：图稀疏（实测 142 节点 / 87 边）→ 覆盖不足，必须保留域内 LIKE 兜底
+
+### S4 层级激活优先级
+- 初始激活值加成：`anchor`/`self` > `structural` > `knowledge` > `contextual`（顺序可配）
+- 不变量：只影响初始值/排序，不把不合格节点拉回
+
+### S5 负记忆抑制
+- `rejected`/`unresolved` 命中查询 → 对与其 `edges` 相邻或词面高度重叠的正候选乘性降权（`w ← w × (1-λ)`）
+- 保留现有行为：负记忆仍作为结果条目返回（便于调用方感知），但不再与正候选同权
+
+### S6 一致性交叉验证
+- 复用 `md_cg/crosscheck.py`；对 top-k 输出 verdict 摘要，不进主排序
+
+## 4. 开关与回退（缺一不可）
+
+| 开关 | 默认 | 作用 |
+| --- | --- | --- |
+| `MDCG_RETRIEVAL_PIPELINE` | **0** | 总开关；关 = 与现状等价（回归必须全绿） |
+| `MDCG_GATE_S1_DOMAIN` | 0 | 大域收敛 |
+| `MDCG_GATE_S2_COND` | 0 | 条件前置门控 |
+| `MDCG_GATE_S3_SPREAD` | 0 | 图扩散（`MDCG_SPREAD_HOPS`、`MDCG_SPREAD_DECAY`） |
+| `MDCG_GATE_S4_LAYER` | 0 | 层级优先级（`MDCG_LAYER_BOOST`） |
+| `MDCG_GATE_S5_NEG` | 0 | 负记忆抑制（`MDCG_NEG_LAMBDA`） |
+
+规则：**默认关**；每阶段可单独开，便于逐项验证与归因；总开关关时 `search()` 走原路径。
+
+## 5. 验收判据（每阶段都要过）
+
+1. **等价性**：开关关 → `scripts/run_tests.py md_cg` 全绿，且返回与现状一致（快照对比）；
+2. **有效性**：开关开 → `meta.scanned` 显著下降（阶段目标：S1 ≤1/10，S2 再砍，S3 只碰邻域），既有召回用例不劣化；
+3. **可审计**：`meta` 增加分阶段计数（`domains/gate_in/gate_out/spread_hops/activated/suppressed`），供编外复核端逐项核对；
+4. **落地判据不变**：内部独立复核 ACCEPT ∧ 零删除 ∧ 干净树回归绿 ∧ 逐候选可回退提交。
+
+## 6. 里程碑与分支纪律
+
+- 每阶段独立分支、独立复核、独立落地；落地后在 `origin/main` 打 `core-*` 标签；
+- 探索分支随任务完结即回收（≤10 条，见 `hive/interop/note-branch-discipline.md`）。
+
+## 7. 边界（不做的事）
+
+- **不**用 FTS5/倒排表替代认知路径（那会让灵枢退化为普通搜索引擎，并掩盖机制失效）；倒排只可作 S1/S3 之后的**候选内**加速；
+- **不**改写入侧语义（只补 `big_domain` 域标签这类检索所需的最小元数据）；
+- **不**在默认路径上启用新行为（先 flag 化、逐项验证、再讨论默认开启）。
+
+## 8. 首期范围（S1 + S2）
+
+1. 写入侧：`add()` / `_write_node` 存 `big_domain`（内容 → `routing.big_domain_classify`）；新增幂等回填器 `md_cg/backfill_bigdomain.py`（支持 `--dry-run`）；
+2. 读路径：`search()` 增加 S1 收敛与 S2 门控（flag 控），输出分阶段审计计数；
+3. 测试：等价性快照 + 收敛率（`scanned` 下降）+ 召回不劣化；
+4. S3~S5 依次跟进（各自独立落地）。

package/docs/hive//347/234/237/345/256/236/345/272/223/347/253/257/345/210/260/347/253/257/345/256/236/346/265/213_S1b/344/270/216/345/217/254/345/233/236/346/235/203/350/241/241_v0.1.md

@@ -0,0 +1,57 @@
+# 真实库端到端实测：S1b 的收益与召回权衡（2026-09-19）
+
+> 方法：把真实库 **完整拷贝**到临时目录（12,249 文件 / 1,446 MB，源库零写入），在拷贝上做开关对照实测。
+> 库：`D:/Program Files/2_ai/AEIS/data/mdcg` → 拷贝 `C:/Users/FuRongJun/.mdcg/_store_copy`（12,149 节点）。
+
+## 1. 基线（全关）：每个查询都扫全库
+
+| 查询 | scanned | tier | 用时 |
+| --- | --- | --- | --- |
+| 感知系统 记忆 节点 | 12,149 | T2_global_like | 2.87s |
+| graphrag 图谱 检索 | 12,149 | T2_global_like | 2.14s |
+| whitebox 白箱 条件 | 12,149 | T2_global_like | 3.70s |
+| 贝塞尔 曲线 工程 应力 | 12,149 | T2_global_like | 2.05s |
+
+→ **外部审计的「全表扫描」在生产库上被实测复现**（每查询 2–3.7 秒、12,149 节点全读）。
+
+## 2. S1b 开启（无需回填、零写入）：5.5–10.4 倍更少节点、3–8 倍更快
+
+| 查询 | scanned | 减少 | S1b 用时 | 命中的桶 |
+| --- | --- | --- | --- | --- |
+| 感知系统 记忆 节点 | 2,217 | 5.5× | 0.86s | cond_感知系统 / cond_复杂系统 / cond_动力学系统 |
+| graphrag 图谱 检索 | 1,733 | 7.0× | 0.55s | cond_graphrag / cond_graphiti |
+| whitebox 白箱 条件 | 1,497 | 8.1× | 0.60s | cond_whitebox_kb / cond_whitebox_py / cond_条件论 |
+| 贝塞尔 曲线 工程 应力 | 1,170 | 10.4× | 0.25s | cond_工程学 |
+
+**这是 S1b 的核心价值，而且不需要任何写入/回填**（桶在写入侧已建好，91.1% 节点有桶）。
+
+## 3. 但：召回集合发生了变化（必须如实报告）
+
+以「全关的全表扫描 top-10」为参照，S1b 的 **召回一致率只有 1/4**：4 个查询里 3 个的 top-10 组成不同
+（条数相同，但成员不同）——**被丢弃的异桶节点里，确实有词法高分命中**。
+
+**速度/召回权衡曲线（在拷贝上实测）**：
+
+| topk / min_sim | 平均 scanned | 召回一致 | 平均用时 |
+| --- | --- | --- | --- |
+| 1 / 0.20 | 1,579 | 1/4 | 0.55s |
+| 1 / 0.50 | 1,579 | 1/4 | 0.55s |
+| 3 / 0.34（默认） | 1,654 | 1/4 | 0.56s |
+| 6 / 0.20 | 1,686 | 1/4 | 0.57s |
+| 10 / 0.20 | 1,687 | 1/4 | 0.57s |
+
+结论：**放宽 topk / 降低 min_sim 几乎不改善召回一致，也不明显增加扫描** —— 说明丢掉的命中不在「更大的桶集合」里，
+而在**桶键推断没匹配上的桶**里（`domain_similarity` 对「查询词 ↔ 桶键」的匹配能力有限），且 kept 集合被
+**orphan/无桶兜底池**主导（本库 orphan 约 1,086 节点）。
+
+## 4. 诚实结论与建议
+
+1. **S1b 是一个「快模式」**：约 **7–8 倍更少扫描、4–6 倍更快**，但**不保证与全表扫描同结果**。
+   因此它必须保持 flag 默认关（现状如此），且**不建议**作为唯一检索路径启用——
+   这正是「域收敛不得丢召回」这条不变量在真实库上的边界。
+2. **要同时拿到速度与等价召回**，缺的是一层**廉价高精度候选生成器**：即把「词 → 命中节点」做成
+   **倒排/发布表**（词项索引），这样不必读遍所有文件就能取出词法命中，再交给既有路径排序。
+   契约 §7 允许「倒排只作 S1/S3 之后的候选内加速」——这是该层的正确定位（不是用它替代认知路径）。
+3. 该倒排层的建设成本在**索引 schema + 写入/重建维护**，属下一个里程碑级别的工作；
+   在它落地前，建议 S1b 只作为**可选加速**（默认关），并在启用时把 `meta.gates.s1b` 与
+   `covered_neg` 一并暴露给调用方，让调用方知道「本次是加速模式」。

package/docs/hive//347/234/237/345/256/236/345/272/223/347/253/257/345/210/260/347/253/257/345/256/236/346/265/213_S7/345/200/222/346/216/222/345/200/231/351/200/211/345/261/202_v0.1.md

@@ -0,0 +1,126 @@
+# 真实库端到端实测：S7 倒排候选层（候选内加速 + 零召回损失）（2026-09-19）
+
+> 方法：**真实库直连** `D:/Program Files/2_ai/AEIS/data/mdcg`（12,150 节点 / 1,446 MB），
+> 只写派生索引 `_postings.json` + `_postings_meta.json`，**不改任何节点内容**。
+> 旧的全库拷贝 `_store_copy` 已删除（不再使用拷贝）。
+> 实测期间该库正被注释补全流水线**持续改写**（1 分钟内 1,395 个节点文件 mtime 变化），
+> 这恰好把「快照过期」语义一起测了。
+
+## 1 基线（全关）：每个查询都扫全库
+
+| 查询 | scanned | tier | 用时 |
+| --- | --- | --- | --- |
+| 感知系统 记忆 节点 | 12,150 | T2_global_like | 2.76s |
+| graphrag 图谱 检索 | 12,150 | T2_global_like | 2.10s |
+| whitebox 白箱 条件 | 12,150 | T2_global_like | 3.60s |
+| 贝塞尔 曲线 工程 应力 | 12,150 | T2_global_like | 2.00s |
+| 泽塔欧米伽轴不存在的词 | 12,150 | T2_global_like | 3.19s |
+| 阿 | 12,150 | T2_global_like | 1.74s |
+
+构建发布表：**12,150 节点 / 201,650 词项 / 3,125,856 倒排条目 / 75.7 MB JSON / 6.5s**（幂等）。
+快照指纹校验开销：**0.064s**（1,074 个节点目录 + 索引文件各一次 stat，不重读节点）。
+
+## 2 候选窄化（`MDCG_S7_FRESHNESS=skip`，离线对照：假设快照新鲜）
+
+| 查询 | scanned | 缩减 | 用时 | S7 审计 |
+| --- | --- | --- | --- | --- |
+| 感知系统 记忆 节点 | 12,150 | 1.0× | 2.70s | `single_char_term` 回退 |
+| graphrag 图谱 检索 | 933 | 13.0× | 1.49s | `cands=933` |
+| whitebox 白箱 条件 | 11,499 | 1.06× | 3.65s | `cands=11499` |
+| 贝塞尔 曲线 工程 应力 | 723 | 16.8× | **0.45s（4.4× 快）** | `cands=723` |
+| 泽塔欧米伽轴不存在的词 | 7,167 | 1.7× | 2.62s | `cands=7167` |
+| 阿 | 12,150 | 1.0× | 1.81s | `single_char_term` 回退 |
+
+## 3 等价证据（这是 S7 存在的理由）
+
+以「逐条 (id, 分数, 次序)」为判据：
+
+- **`RESULT_PARITY 6/6`**：`results` 与全表扫描**逐条相同，含次序**。
+- `pre_cap`（命中集规模）与 `cap/candidates/tier/cut_order` 亦一致。
+- 唯一允许的差异是 `scanned`（正是加速本身）。
+
+两个必须点名的**真实缺陷**（均已在本次落地中修掉，并有不通过即红的用例）：
+
+1. **并列同分的次序**：候选曾按`集合`迭代序取出，而集合迭代序随进程哈希随机化而变
+   → 同分同重要性的条目次序会与全表不一致、甚至**逐个进程不同**。
+   修法：窄化时**保持索引原序**（候选集是过滤，不是重排）。
+   *证据*：`test_retr_s7` 第 12 节（3 个同内容同重要性节点，断言次序一致）。
+2. **组合退化（S7×S3）**：S7 曾把`窄化后的 entries`当作 S3 扩散的 allowed 集，
+   而 S3 的目标恰恰是「词面无交集、只沿 edges 可达」的节点 → S7+S3 会把 S3 的扩散清空。
+   修法：S3 的 allowed 恒取「S1/S2 门控后的全量候选」；S7 只做 T2 的加速器。
+   *证据*：`test_retr_s7` 第 11 节（临时还原该行 → 用例立即红：`expanded 2→0`）。
+
+**独立复核（编外验证单元）REJECT 的三条，均已修并补直接证据：**
+
+3. **组合退化（S7×语义路）**：`MDCG_SEMANTIC=1` 时「frontmatter 有 semantic 的节点」在
+   `_like` 之外**无条件入池**，而该标志**只在节点文件里**（索引快照无此键）→
+   候选阶段无法识别 → 窄化会漏读语义节点、丢召回。
+   修法：语义路开启时 S7 一律不窄化（`reason=semantic_on`，审计可见）。
+   *证据*：`test_retr_s7` 第 13b 节（含"无词面交集的语义节点 s2 仍入池"断言）。
+4. **自证式断言**：第 7 节原有一句 `check(..., True)`（恒真，等于没断言）。
+   修法：改为真断言「全量有命中 ∧ 0 < 候选数 < 全量命中数」——
+   该用例必须真的走在"窄化后命中不足 → T3 恢复全量"的路径上。
+5. **根目录自污染（根级节点）**：`_postings*.json` 就写在库根目录；
+   若用"根目录 mtime"判过期，快照刚建就被自己的写入改旧。
+   修法：根级路径（path 无目录）改为**逐文件记 mtime**（`file_mtimes`），
+   `dir_mtimes` 不再含空目录键。*证据*：`test_retr_s7` 第 15 节
+   （自身派生文件写入后仍新鲜；改写根级节点 → `root_file_touched`）。
+   （注：现行 `_scan_nodes` 只扫 `<layer>/**.md`，根级节点本不会进索引；
+   此修复是**防御性**的，成本为零。）
+
+## 4 真实行为（`MDCG_S7_FRESHNESS=auto`，默认）：过期即回退，绝不丢召回
+
+| 查询 | scanned（基线→skip→auto） | auto 的 s7 审计 |
+| --- | --- | --- |
+| graphrag 图谱 检索 | 12,150 → 933 → **933** | 快照仍新鲜 → 窄化 |
+| whitebox 白箱 条件 | 12,150 → 11,499 → 12,150 | `stale_index:dir_touched` → 回退 |
+| 贝塞尔 曲线 工程 应力 | 12,150 → 723 → 12,150 | `stale_index:dir_touched` → 回退 |
+
+**auto 模式下逐条一致仍是 6/6。** 语义是「宁可慢，不可丢召回」：
+注释流水线正在批量改写节点时，发布表秒级过期，查询自动落回全量；
+库安静下来后立即恢复窄化。
+
+## 5 设计要点
+
+1. **候选 ⊇ 真命中**：每词取其**全部 bigram 的发布列表交集**，各词并集；
+   再交既有 `_like` 精确过滤 → 召回与全表一致（契约 §7「候选内加速」定位）。
+   实测反证：某查询 `cands=934`、真命中 873，`hits - cands = 0`。
+2. **快照指纹**（节点数 + 节点目录 mtime + 索引文件 mtime / 0.064s）：
+   节点写入走 `fsutil.atomic_write`（temp + `os.replace`），目录 mtime 必然变化，
+   故 O(目录数) 次 stat 即可判定过期。
+3. **T3 兜底还原**：T2 未达阈值时强制恢复全量候选，并把 `scanned` 口径还原为
+   「从未窄化」（弃读量另记 `attempted`，诚实计量）。
+4. **抽样构建不算新鲜**：`--limit` 只索引部分节点，故**不写**快照指纹
+   → 检索一律回退（防「静默漏召回」）。
+
+## 6 诚实结论与局限
+
+1. **收益与查询选择性成正比**：`贝塞尔 曲线 工程 应力` 4.4× 更快（0.45s vs 2.00s）、
+   `graphrag 图谱 检索` 1.4×；而 `whitebox 白箱 条件` 只降 6%（该查询含极常见 2-gram
+   「条件」，11,499 个节点确实含它——候选集**本来就是**真命中集，不是实现问题）。
+2. **无 IDF 加权**：候选是「各词并集」，任一常见词就会把候选推到接近全库。
+   下一步可加「按词稀有度分层 + 提前剪枝」，但**不得**改为交集（`_like` 是任一词命中）。
+3. **单字词会让整条查询回退**：如「感知系统 记忆 节点」经同义词组展开得到单字词「库」
+   → 无法用 bigram 表达 → 整查询回退全量（安全但不加速）。
+   要覆盖单字词，需要字符级索引（下一里程碑）。
+4. **持续写入的库上会频繁过期**：批量改写期间 S7 落回基线；这是**正确性优先**的取舍，
+   不是失效。要长期吃到加速，需要**写入路径的增量维护（dirty 集）**——v1 未接
+   （每次写都 load+save 75MB 不可接受），当前用 `--if-stale` 重建守候。
+
+## 7 开关与审计
+
+| 环境变量 | 默认 | 作用 |
+| --- | --- | --- |
+| `MDCG_RETRIEVAL_PIPELINE` | 关 | 父开关（不开则 S7 代码路径不进入） |
+| `MDCG_GATE_S7_POSTINGS` | 关 | S7 子开关，**必须显式 =1** |
+| `MDCG_S7_FRESHNESS` | `auto` | `skip` 仅供离线对照实测（跳过指纹校验） |
+| `MDCG_SEMANTIC` | 关 | =1 时 S7 自动让位（`reason=semantic_on`）：语义节点面无法在候选阶段识别 |
+
+审计：`meta.gates.s7`，键位 `cands`（窄化后候选数）/ `in`（门控后全量）/ `terms`（查询词数）
+/ `reason`（`single_char_term` / `no_index` / `no_module` / `no_snapshot` / `no_candidate`
+/ `semantic_on`（`MDCG_SEMANTIC=1` 时不窄化）
+/ `stale_index:<dir_touched|node_count_changed|dirs_changed|index_touched|no_meta|root_file_touched|root_files_changed>`）
+/ `fallback`（`full_scan` / `no_candidate` / `t3_full`）/ `attempted`（T3 兜底时被弃读量）。
+
+运维：`python -X utf8 -m md_cg.build_postings --root <库根> --if-stale`（过期才重建，供守候环调用）；
+`--stats` 打印规模与 `stale_reason`。发布表是**派生索引**，可随时删除/重建，不影响节点。