@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/test_reach.py

@@ -0,0 +1,378 @@
+# -*- coding: utf-8 -*-
+"""test_reach.py · 检索候选收敛层（reach）验收。
+
+覆盖（对应 A2/A3 判据的可证形式）：
+ (1) 包含性：收敛集 ⊇ 全量 LIKE 命中集，且 ⊇ 词法打分>0 集合（A2「不丢召回」的可证形式）
+ (2) 条件门控：收敛集 ⊆ 调用方候选集（层/角色/会话/分支由 _candidates 承载）；不可读节点不越权
+ (3) 图扩散：edges 邻居被吸收补召回；扩散受 DIFFUSE_MAX_FACTOR 上限约束
+ (4) 回退：MDCG_REACH=0 / 单字符 term / 索引不可用 → 不收敛（返回 None），旧行为不变
+ (5) 端到端：search 开关两态结果集为包含关系、meta 带 reach*、scanned 下降
+ (6) 缓存失效：新增节点后重建，新节点可被收敛召回（防陈旧缓存丢召回）
+
+运行：python -m md_cg.test_reach
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+
+from .mdcos import MdCGOS
+from .mdcg import bigrams, expand_query_terms, normalize_en
+from . import reach
+
+PASS = FAIL = 0
+FAILS = []
+
+
+def ok(cond, label, detail=""):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print(f"  [PASS] {label}" + (f"  · {detail}" if detail else ""))
+    else:
+        FAIL += 1
+        FAILS.append(label)
+        print(f"  [FAIL] {label}" + (f"  · {detail}" if detail else ""))
+
+
+QUERY = "召回截断 分池"
+BODY = "召回截断 索引 分池 内容"
+
+
+def _mk(root):
+    cg = MdCGOS(root, actor="test_reach")
+    for i in range(3):
+        cg.add(f"code_{i}", f"# 功能名：索引条目 {i}\n# 生效条件：条件 I\n\n{BODY} {i}\n",
+               layer="knowledge", tags=["index"])
+    for i in range(3):
+        cg.add(f"kp_{i}", f"# 功能名：知识 {i}\n# 生效条件：条件 K\n\n召回截断 索引 内容 {i}\n",
+               layer="knowledge")
+    cg.add("other_1", "# 功能名：无关\n# 生效条件：条件 O\n\n完全无关的另一段文本。\n",
+           layer="knowledge")
+    # 组扩散：other_2 不含查询词，但被 code_0 通过 edges 指向（图扩散应把它补进收敛集）
+    cg.add("other_2", "# 功能名：邻居\n# 生效条件：条件 N\n\n也不含查询词的邻居正文。\n",
+           layer="knowledge")
+    cg.add("code_0b", f"# 功能名：索引条目 0b\n# 生效条件：条件 I\n\n{BODY} 0b\n",
+           layer="knowledge", edges=[{"target": "other_2", "type": "similar", "confidence": 0.9}])
+    cg.add("n_rej", f"# 功能名：被否决\n# 生效条件：条件 R\n\n{BODY} 否\n", layer="rejected")
+    cg.flush()
+    return cg
+
+
+def _env(on):
+    os.environ["MDCG_REACH"] = "1" if on else "0"
+    reach._CACHE.clear()
+
+
+def _search_both(cg, query, k, on):
+    """在指定开关下跑一次 search（供两态对比）。"""
+    _env(on)
+    if on:
+        reach._CACHE.clear()
+    return cg.search(query, k=k)
+
+
+def _like_ids(cg, entries, terms):
+    stat = {"scanned": 0}
+    docs = cg._read_many(entries, stat)
+    return {e["path"] for e, fm, c in docs if cg._like(c, fm, terms)}, docs
+
+
+def main():
+    print("md_cg 收敛层 reach 验收 · 大域收敛 / 条件门控 / 图扩散 / 回退")
+    print("=" * 70)
+    root = tempfile.mkdtemp(prefix="mdcg_reach_")
+    try:
+        os.environ["MDCG_REACH_INDEX"] = os.path.join(root, "_idx_measure.json")
+        cg = _mk(root)
+        entries = cg._candidates()
+        terms = expand_query_terms(QUERY)
+        qb = bigrams(normalize_en(QUERY))
+
+        # ---------------- (1) 包含性 ----------------
+        print("\n(1) 大域收敛包含性（A2 可证形式）")
+        _env(True)
+        full_like, docs = _like_ids(cg, entries, terms)
+        narrow, meta = reach.narrow(cg, entries, terms, qb, None, q=QUERY)
+        nset = {e["path"] for e in (narrow or [])}
+        ok(full_like and full_like <= nset,
+           "(1) 收敛集 ⊇ 全量 LIKE 命中集", f"like={len(full_like)} narrow={len(nset)} miss={len(full_like - nset)}")
+        scored = cg._score(docs, QUERY, qb, None)
+        pos = {d[0]["path"] for d in scored if d[1] > 0}
+        ok(pos <= nset, "(1) 收敛集 ⊇ 词法打分>0 集合",
+           f"score>0={len(pos)} miss={len(pos - nset)}")
+        ok(meta.get("reach") == "converged" and meta.get("reach_seed", 0) > 0,
+           "(1) meta 如实报收敛状态", str(meta))
+
+        # ---------------- (2) 条件门控 ----------------
+        print("\n(2) 条件门控（收敛集 ⊆ 候选集）")
+        epaths = {e["path"] for e in entries}
+        ok(nset <= epaths, "(2) 收敛集不越出调用方候选集")
+        ok(all(e.get("layer") != "rejected" for e in narrow), "(2) 负记忆层不因收敛回流")
+
+        # ---------------- (3) 图扩散 ----------------
+        print("\n(3) 图扩散")
+        idx = reach._index(cg)
+        ids = {e["path"].split("/")[-1][:-3] for e in narrow}
+        os.environ["MDCG_REACH_DIFFUSE"] = "1"      # 扩散默认关（保 A2 精确），此处置开验证能力
+        narrow_d, meta_d = reach.narrow(cg, entries, terms, qb, None, q=QUERY)
+        os.environ["MDCG_REACH_DIFFUSE"] = "0"
+        ids_d = {e["path"].split("/")[-1][:-3] for e in (narrow_d or [])}
+        ok("other_2" in ids_d and meta_d.get("reach_diffused") == 1,
+           "(3) 扩散开关开启时 edges 邻居被吸收",
+           f"other_2 in narrow_d={'other_2' in ids_d} diffused={meta_d.get('reach_diffused')} (默认关时 ids={len(ids)})")
+        fake = reach.ReachIndex(root)
+        fake.adj = {"a": ["b", "c"], "b": ["d"], "d": ["e"]}
+        one = fake.diffuse({"a"}, hops=1)
+        two = fake.diffuse({"a"}, hops=2)
+        ok(one == {"a", "b", "c"}, "(3) 1 跳邻居集合正确", str(sorted(one)))
+        ok(two >= {"a", "b", "c", "d"}, "(3) 2 跳可达", str(sorted(two)))
+        big = {"s0"}
+        fake.adj = {"s0": [f"n{i}" for i in range(100)]}
+        lim = fake.diffuse({"s0"}, hops=1, limit=3)
+        ok(len(lim) <= 3, "(3) 扩散受上限约束", f"|out|={len(lim)}")
+
+        # ---------------- (4) 回退 ----------------
+        print("\n(4) 回退（不适用条件 → 不收敛）")
+        _env(False)
+        got, meta = reach.narrow(cg, entries, terms, qb, None, q=QUERY)
+        ok(got is None and meta.get("reach") == "off", "(4) MDCG_REACH=0 → 不收敛", str(meta))
+        _env(True)
+        got, meta = reach.narrow(cg, entries, ["白"], bigrams("白"), None, q="白")
+        ok(got is None and meta.get("reach") == "short_term", "(4) 单字符 term → 不收敛", str(meta))
+        saved = reach._index
+        reach._index = lambda *a, **k: None
+        try:
+            got, meta = reach.narrow(cg, entries, terms, qb, None, q=QUERY)
+            ok(got is None and meta.get("reach") == "index_unavailable",
+               "(4) 索引不可用 → 不收敛", str(meta))
+        finally:
+            reach._index = saved
+
+        # ---------------- (5) 端到端 ----------------
+        print("\n(5) 端到端（search 两态）")
+        _env(False)
+        res_off, m_off = cg.search(QUERY, k=10)
+        off_ids = [r[0]["id"] for r in res_off]
+        _env(True)
+        reach._CACHE.clear()
+        res_on, m_on = cg.search(QUERY, k=10)
+        on_ids = [r[0]["id"] for r in res_on]
+        ok(set(on_ids) >= set(off_ids), "(5) 开态结果集 ⊇ 关态（不丢召回）",
+           f"off={off_ids[:3]} on={on_ids[:3]}")
+        ok(m_on.get("reach") == "converged" and m_on.get("reach_seed"),
+           "(5) meta 透出 reach* 审计字段", f"reach={m_on.get('reach')} seed={m_on.get('reach_seed')}")
+        ok(m_on.get("scanned", 0) <= m_off.get("scanned", 0),
+           "(5) 开态读盘数不增（收敛生效）",
+           f"off={m_off.get('scanned')} on={m_on.get('scanned')}")
+        ok(m_on.get("pre_cap", 0) >= m_off.get("pre_cap", 0),
+           "(5) 截断前候选数不少于关态（图扩散可补召回）",
+           f"off={m_off.get('pre_cap')} on={m_on.get('pre_cap')}")
+        # 图扩散必须真的落到**结果层**（T3-r3 复核：只并入收敛集、随后被 _like 过滤掉等于没做）
+        os.environ["MDCG_REACH_DIFFUSE"] = "1"      # 结果层放行扩散节点需显式开关
+        res_big_off, _ = _search_both(cg, QUERY, 50, False)
+        res_big_on, _ = _search_both(cg, QUERY, 50, True)
+        os.environ["MDCG_REACH_DIFFUSE"] = "0"
+        ids_on = {r[0]["id"] for r in res_big_on}
+        ids_off = {r[0]["id"] for r in res_big_off}
+        ok("other_2" in ids_on and "other_2" not in ids_off,
+           "(5) 图扩散邻居进入 search 结果（补召回落地）",
+           f"other_2 on={'other_2' in ids_on} off={'other_2' in ids_off}")
+
+        # r14 复核：收敛集非空但 LIKE 命中为空 → 回退全量，且 meta.reach 必须改写为 reverted（不得谎报 converged）
+        _env(True)
+        _saved_like = cg._like
+        cg._like = staticmethod(lambda *a, **k: False)   # 模拟「bigram 有交集但无 LIKE 命中」
+        try:
+            res_rv, m_rv = cg.search(QUERY, k=5)
+        finally:
+            cg._like = _saved_like
+        ok(m_rv.get("reach") == "reverted",
+           "(5b) 回退全量时 reach 改写为 reverted（不谎报 converged）", str(m_rv.get("reach")))
+        ok(bool(res_rv), "(5b) 回退后仍能出结果（全量路径）", f"n={len(res_rv)}")
+        ok(m_rv.get("reach_reverted") is True, "(5b) 回退标记 reach_reverted=True")
+        ok(isinstance(m_rv.get("reach_reverted_docs"), int) and m_rv["reach_reverted_docs"] >= 0,
+           "(5b) 回退时暴露收敛阶段读盘量（A3 可扣减）", f"docs={m_rv.get('reach_reverted_docs')}")
+        # 让该次调用确实发生重建：清缓存并把磁盘缓存改旧，再令 _like 恒假 → 回退且首建成本必须保留
+        reach._CACHE.clear()
+        live2 = reach._index(cg)
+        live2.built_at = time.time() - 4000
+        try:
+            d4 = json.load(open(live2.path, encoding="utf-8"))
+            d4["built_at"] = time.time() - 4000
+            json.dump(d4, open(live2.path, "w", encoding="utf-8"))
+        except OSError:
+            pass
+        cg._like = staticmethod(lambda *a, **k: False)
+        try:
+            res_rv2, m_rv2 = cg.search(QUERY, k=5)
+        finally:
+            cg._like = _saved_like
+        ok(m_rv2.get("reach") == "reverted" and m_rv2.get("reach_build_docs") is not None,
+           "(5b) 回退时若发生重建，首建成本字段必须保留",
+           f"reach={m_rv2.get(chr(39)+chr(39)) if False else m_rv2.get('reach')} build={m_rv2.get('reach_build_docs')}")
+
+        # ---------------- (6) 缓存失效 ----------------
+        print("\n(6) 缓存失效（新增节点后仍可召回）")
+        cg.add("code_new", f"# 功能名：新增索引条目\n# 生效条件：条件 I\n\n{BODY} new\n",
+               layer="knowledge", tags=["index"])
+        cg.flush()
+        res2, m2 = cg.search(QUERY, k=20)
+        ok(any(r[0]["id"] == "code_new" for r in res2),
+           "(6) 新增节点进入收敛集（指纹失效触发重建）",
+           f"reach={m2.get('reach')} ids={[r[0]['id'] for r in res2][:4]}")
+        # 指纹必须含 path（r6 复核：路径交换/重命名而 content_hash 未变时不得复用缓存）
+        class _FakeCG:
+            def __init__(self, path):
+                self.root = root
+                self.index = {"nodes": {"n1": {"path": path, "content_hash": "H1"}}}
+        fp_a = reach._fingerprint(_FakeCG("knowledge/a.md"))
+        fp_b = reach._fingerprint(_FakeCG("knowledge/b.md"))
+        ok(fp_a != fp_b, "(7) 指纹含 path（路径变更即判不新鲜）", "%s vs %s" % (fp_a[:8], fp_b[:8]))
+        # r7 复核：仅改 edges 也必须判不新鲜（否则 MDCG_REACH_DIFFUSE=1 时扩散复用旧邻接表）
+        class _FakeCG2:
+            def __init__(self, edges):
+                self.root = root
+                self.index = {"nodes": {"n1": {"path": "knowledge/a.md",
+                                              "content_hash": "H1", "edges": edges}}}
+        e0 = _FakeCG2([])
+        e1 = _FakeCG2([{"target": "knowledge/b.md", "type": "similar"}])
+        ok(reach._fingerprint(e0) != reach._fingerprint(e1),
+           "(7) 指纹含 edges（仅改边即判不新鲜）")
+        ok(reach._node_key(e0.index["nodes"]["n1"]) != reach._node_key(e1.index["nodes"]["n1"]),
+           "(7) 新鲜度键含 edges 签名")
+        # r9 复核：tags 变更也必须判不新鲜（倒排含标签 bigram）
+        class _FakeCG3:
+            def __init__(self, tags):
+                self.root = root
+                self.index = {"nodes": {"n1": {"path": "knowledge/a.md",
+                                              "content_hash": "H1", "tags": tags, "edges": []}}}
+
+        ok(reach._node_key(_FakeCG3(["x"]).index["nodes"]["n1"])
+           != reach._node_key(_FakeCG3(["y"]).index["nodes"]["n1"]),
+           "(7) 新鲜度键含 tags（仅改标签即判不新鲜）")
+        # r10 复核：真实 cg.add 后的索引条目必须带 tags（否则 tags 新鲜度不可用）
+        cg.add("tag_probe", "# 功能名：标签探针\n# 生效条件：条件 T\n\n标签探针正文。\n",
+               layer="knowledge", tags=["alpha"])
+        cg.flush()
+        ent = cg.index["nodes"].get("tag_probe")
+        ok(bool(ent) and "alpha" in (ent.get("tags") or []),
+           "(7) 真实索引含 tags（新鲜度键可依赖）", str((ent or {}).get("tags"))[:60])
+        import copy as _copy
+        e_mod = _copy.deepcopy(ent or {})
+        e_mod["tags"] = ["beta"]
+        ok(reach._node_key(ent or {}) != reach._node_key(e_mod),
+           "(7) 真实条目改标签即改新鲜度键")
+        # r10 复核：hash_complete 必须看原始 content_hash（缺则判不完整 → 不复用）
+        class _FakeCG4:
+            def __init__(self, with_hash):
+                self.root = root
+                n = {"path": "knowledge/a.md", "tags": [], "edges": []}
+                if with_hash:
+                    n["content_hash"] = "H1"
+                self.index = {"nodes": {"n1": n}}
+            def _read(self, e):
+                return {}, ""
+            def _open_content(self, node_id, fm, content):
+                return content
+        idx_fresh = reach.ReachIndex(root)
+        idx_fresh.build(_FakeCG4(True))
+        idx_miss = reach.ReachIndex(root)
+        idx_miss.build(_FakeCG4(False))
+        ok(idx_fresh.hash_complete is True and idx_miss.hash_complete is False,
+           "(7) hash_complete 按原始 content_hash 判定",
+           "fresh=%s miss=%s" % (idx_fresh.hash_complete, idx_miss.hash_complete))
+        # ---------------- (7) 落盘/新鲜度/首建成本 ----------------
+        print(chr(10) + "(7) 落盘分隔符 / 新鲜度 / 首建成本")
+        cg.add("comma,node", f"# 功能名：含逗号\n# 生效条件：条件 C\n\n{BODY} 逗号\n",
+               layer="knowledge")
+        cg.flush()
+        saved = reach._index(cg)
+        saved.save()
+        reloaded = reach.ReachIndex(root); reloaded.load()
+        pth = [e["path"] for e in cg._candidates() if e["path"].endswith("comma,node.md")]
+        ok(bool(pth) and pth[0] in reloaded.post.get("召回", []) + reloaded.post.get("召", []),
+           "(7) 含逗号路径经落盘/重载仍在倒排中（_SEP 而非逗号）", f"path={pth}")
+        fake_cg = type("X", (), {"index": {"nodes": {"n1": {"path": "knowledge/n1.md"}}}})()
+        ok(reach._disk_fresh(saved, fake_cg) is False,
+           "(7) content_hash 缺失 → 判不新鲜（触发重建）")
+        os.environ["MDCG_REACH_TTL"] = "1"
+        d = json.load(open(saved.path, encoding="utf-8"))
+        d["built_at"] = time.time() - 30          # 让**磁盘缓存**过期（改内存对象无效）
+        json.dump(d, open(saved.path, "w", encoding="utf-8"))
+        reach._CACHE.clear()
+        again = reach._index(cg)
+        ok(getattr(again, "built_now", False) is True,
+           "(7) 磁盘缓存超 TTL → 重建")
+        os.environ["MDCG_REACH_TTL"] = "0"
+        # ---------------- (8) 新节点并入（陈旧索引不漏召回） ----------------
+        # 复用缓存时不得残留上一轮的首建标记
+        again.built_now = True
+        reach._CACHE[again.path] = (again, reach._fingerprint(cg))
+        _, m_reuse = reach.narrow(cg, cg._candidates(), terms, qb, None, q=QUERY)
+        ok("reach_build_docs" not in m_reuse, "(7) 复用缓存时不残留首建标记")
+
+        # 未索引节点并入（path 不在 idx.hashes）
+        cg.add("unindexed_node", "# 功能名：未索引\n# 生效条件：条件 U\n\n与查询无关。\n",
+               layer="knowledge")
+        cg.flush()
+        reach._CACHE.clear()
+        stale2 = reach.ReachIndex(root); stale2.load()
+        ok(not any(p.endswith("unindexed_node.md") for p in stale2.hashes),
+           "(8b) 前置：磁盘缓存里确无该节点")
+        reach._CACHE[stale2.path] = (stale2, reach._fingerprint(cg))
+        got3, meta3 = reach.narrow(cg, cg._candidates(), terms, qb, None, q=QUERY)
+        # r8 复核：未索引节点超过上限时必须整段回退（不得静默截断后仍提前返回）
+        saved_max = reach._FRESH_MAX
+        reach._FRESH_MAX = 1
+        cg.add("unindexed2", "# 功能名：未索引2\n# 生效条件：条件 U2\n\n与查询无关。\n", layer="knowledge")
+        cg.flush()
+        reach._CACHE.clear()
+        st3 = reach.ReachIndex(root); st3.load()
+        reach._CACHE[st3.path] = (st3, reach._fingerprint(cg))
+        got4, meta4 = reach.narrow(cg, cg._candidates(), terms, qb, None, q=QUERY)
+        reach._FRESH_MAX = saved_max
+        ok(got4 is None and meta4.get("reach") == "fresh_overflow",
+           "(8c) 未索引节点超过上限 → 整段回退（不静默截断）", str(meta4)[:80])
+
+        # r8 复核：进程内缓存 TTL 过期也要重建（不清 _CACHE，改内存实例的 built_at）
+        os.environ["MDCG_REACH_TTL"] = "1"
+        live = reach._index(cg)
+        live.built_at = time.time() - 30
+        try:
+            d2 = json.load(open(live.path, encoding="utf-8"))
+            d2["built_at"] = time.time() - 30          # 磁盘缓存也过期 → 必须真重建
+            json.dump(d2, open(live.path, "w", encoding="utf-8"))
+        except OSError:
+            pass
+        got5, meta5 = reach.narrow(cg, cg._candidates(), terms, qb, None, q=QUERY)
+        os.environ["MDCG_REACH_TTL"] = "0"
+        ok(meta5.get("reach_build_docs") is not None,
+           "(8d) 内存+磁盘缓存均超 TTL → 真重建（以 reach_build_docs 出现为准）", str(meta5)[:110])
+        ok(meta3.get("reach_fresh_nodes", 0) >= 1,
+           "(8b) 未索引节点被并入候选", f"fresh={meta3.get('reach_fresh_nodes')}")
+        print(chr(10) + "(8) 新节点并入")
+        cg.add("late_node", "# 功能名：后写节点\n# 生效条件：条件 L\n\n与查询无关的后写正文。\n",
+               layer="knowledge")
+        cg.flush()
+        _env(True)
+        # 强制「指纹比对通过但缓存里没有后写节点」的陈旧场景，验证并入机制
+        stale = reach.ReachIndex(root); stale.load()
+        reach._CACHE[stale.path] = (stale, reach._fingerprint(cg))
+        got2, meta2 = reach.narrow(cg, cg._candidates(), terms, qb, None, q=QUERY)
+        ids2 = {e["path"].split("/")[-1][:-3] for e in (got2 or [])}
+        ok("late_node" in ids2 or meta2.get("reach_fresh_nodes", 0) > 0,
+           "(8) 索引建成后写入的节点被并入候选", f"fresh={meta2.get('reach_fresh_nodes')}")
+        print(f"\n===== reach 验收：{PASS}/{PASS + FAIL} 通过 =====")
+        if FAILS:
+            print("失败项：" + "；".join(FAILS))
+        return 0 if FAIL == 0 else 1
+    finally:
+        _env(True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/md_cg/test_reach_keys.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+"""test_reach_keys.py · 新鲜度键与落盘的**编码无歧义**验收（r11 复核反例固化）。
+
+背景：_node_key 曾用 ';'/'|' 拼接 tags/edges，导致 ["a;b"] 与 ["a","b"] 生成同键；
+倒排曾用 ',' 与 chr(31) 拼接路径。本测试把编码层的不变性固化：
+  ① tags 含分隔符不碰撞   ② edges 含分隔符不碰撞
+  ③ 倒排落地/重载对含控制字符的路径原样保留   ④ TTL<=0 回落默认（不得静默关闭兜底）
+  ⑤ hash_complete 按原始 content_hash 判定
+
+运行：python -m md_cg.test_reach_keys
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+
+from . import reach
+
+PASS = FAIL = 0
+
+
+def ok(cond, label, detail=""):
+    global PASS, FAIL
+    PASS += int(bool(cond))
+    FAIL += int(not cond)
+    print(f'[{"✓" if cond else "✘"}] {label}' + (f"  · {detail}" if detail else ""))
+
+
+def _fake(root, **entry):
+    base = {"path": "knowledge/a.md", "content_hash": "H1", "tags": [], "edges": []}
+    base.update(entry)
+
+    class _CG:
+        def __init__(self):
+            self.root = root
+            self.index = {"nodes": {"n1": dict(base)}}
+        def _read(self, e):
+            return {}, ""
+        def _open_content(self, node_id, fm, content):
+            return content
+    return _CG()
+
+
+def main():
+    root = tempfile.mkdtemp(prefix="reach_keys_")
+    # reach 为显式 opt-in（契约 §7：不在默认路径上启用新行为），本测试须自行开启
+    os.environ["MDCG_REACH"] = "1"
+    os.environ["MDCG_REACH_INDEX"] = os.path.join(root, "idx.json")
+    # r12 复核：无 path 的条目不计入覆盖判定（与 build 口径一致）
+    class _CG3:
+        def __init__(self):
+            self.root = root
+            self.index = {"nodes": {"n1": {"path": "knowledge/a.md", "content_hash": "H1"},
+                                          "n2": {"content_hash": None}}}
+        def _read(self, e):
+            return {}, ""
+        def _open_content(self, node_id, fm, content):
+            return content
+    ok(reach._hash_complete(_CG3()) is True,
+       "⑤ 无 path 条目不计入 hash 覆盖（与 build 口径一致）")
+
+    print("md_cg reach 键编码验收 · 无歧义 / TTL 兜底 / 落盘往返")
+    print("=" * 66)
+    # ① tags 分隔符不碰撞
+    k1 = reach._node_key(_fake(root, tags=["a;b"]).index["nodes"]["n1"])
+    k2 = reach._node_key(_fake(root, tags=["a", "b"]).index["nodes"]["n1"])
+    ok(k1 != k2, "① tags 含分号不碰撞", f"{k1[:26]} vs {k2[:26]}")
+    k3 = reach._node_key(_fake(root, tags=["a|b"]).index["nodes"]["n1"])
+    k4 = reach._node_key(_fake(root, tags=["a", "b"]).index["nodes"]["n1"])
+    ok(k3 != k4, "① tags 含竖线不碰撞")
+    # ② edges 分隔符不碰撞
+    e1 = reach._node_key(_fake(root, edges=[{"target": "a|b", "type": ""}]).index["nodes"]["n1"])
+    e2 = reach._node_key(_fake(root, edges=[{"target": "a", "type": "b"}]).index["nodes"]["n1"])
+    ok(e1 != e2, "② edges 含竖线不碰撞")
+    e3 = reach._node_key(_fake(root, edges=[{"target": "a;b", "type": "c"}]).index["nodes"]["n1"])
+    e4 = reach._node_key(_fake(root, edges=[{"target": "a", "type": "b;c"}]).index["nodes"]["n1"])
+    ok(e3 != e4, "② edges 含分号不碰撞")
+    # ③ 倒排落盘对控制字符路径原样往返
+    idx = reach.ReachIndex(root)
+    weird = "knowledge/a" + chr(31) + "b.md"
+    idx.post = {"召": [weird]}
+    idx.adj = {}
+    idx.hashes = {}
+    idx.save()
+    back = reach.ReachIndex(root)
+    back.load()
+    ok(back.post.get("召") == [weird], "③ 含控制字符路径经落盘/重载原样保留",
+       str(back.post.get("召")))
+    # ④ TTL<=0 → 回落默认（不得静默关闭）
+    class _CG2:
+        def __init__(self):
+            self.root = root
+            self.index = {"nodes": {"n1": {"path": "knowledge/a.md", "content_hash": "H1",
+                                           "tags": [], "edges": []}}}
+    cg = _CG2()
+    os.environ["MDCG_REACH_TTL"] = "0"
+    idx2 = reach.ReachIndex(root)
+    idx2.built_at = time.time() - 4000
+    saved = reach._CACHE
+    reach._CACHE = {}
+    ok(reach._ttl() == 600.0, "④ TTL=0 经 _ttl() 回落 600s", str(reach._ttl()))
+    os.environ["MDCG_REACH_TTL"] = "-5"
+    ok(reach._ttl() == 600.0, "④ TTL 负值同样回落默认")
+    os.environ["MDCG_REACH_TTL"] = "abc"
+    ok(reach._ttl() == 600.0, "④ TTL 非法文本回落默认")
+    os.environ["MDCG_REACH_TTL"] = "30"
+    ok(reach._ttl() == 30.0, "④ 正数 TTL 原样生效")
+    os.environ["MDCG_REACH_TTL"] = "inf"
+    ok(reach._ttl() == 600.0, "④ TTL=inf 回落默认（否则过期判断永假）", str(reach._ttl()))
+    os.environ["MDCG_REACH_TTL"] = "1e999"
+    ok(reach._ttl() == 600.0, "④ TTL=1e999（溢出为 inf）回落默认")
+    os.environ["MDCG_REACH_TTL"] = "nan"
+    ok(reach._ttl() == 600.0, "④ TTL=nan 回落默认")
+    os.environ["MDCG_REACH_TTL"] = "0"
+    reach._CACHE = saved
+    # ⑤ hash_complete 按原始 content_hash 判定
+    a = reach.ReachIndex(root); a.hash_complete = None
+    b = reach.ReachIndex(root); b.hash_complete = None
+    a.build(_fake(root, content_hash="H1"))
+    b.build(_fake(root, content_hash=None))
+    ok(a.hash_complete is True and b.hash_complete is False,
+       "⑤ hash_complete 按原始 content_hash", f"a={a.hash_complete} b={b.hash_complete}")
+    # r13 复核：真实磁盘新鲜度路径（不手写 _CACHE）
+    os.environ["MDCG_REACH_TTL"] = "0"
+    cg2 = _CG3()
+    idx_a = reach.ReachIndex(root)
+    idx_a.build(cg2)
+    idx_a.save()
+    idx_b = reach.ReachIndex(root)
+    idx_b.load()
+    ok(reach._disk_fresh(idx_b, cg2) is True, "⑤ 真实磁盘缓存：同库判新鲜")
+    cg3 = _CG3()
+    cg3.index["nodes"]["n1"]["content_hash"] = "H2"
+    ok(reach._disk_fresh(idx_b, cg3) is False, "⑤ 真实磁盘缓存：content_hash 变即判不新鲜")
+    # r13 复核：落盘失败（只读根）时不得入进程缓存（类级替换 save 注入 OSError）
+    saved_save = reach.ReachIndex.save
+    def _boom(self):
+        raise OSError('readonly')
+    reach.ReachIndex.save = _boom
+    try:
+        reach._CACHE.clear()
+        reach._index(cg2, force=True)
+        ok(len(reach._CACHE) == 0, '⑤ 落盘失败时不入进程缓存（下次调用重建）', str(list(reach._CACHE)))
+    finally:
+        reach.ReachIndex.save = saved_save
+    # r15 复核：库内缺 content_hash 时，即使本次刚重建也必须回退（不得收敛）
+    class _CG5:
+        def __init__(self):
+            self.root = root
+            self.index = {"nodes": {"n1": {"path": "knowledge/a.md", "tags": [], "edges": []}}}
+        def _read(self, e):
+            return {}, ""
+        def _open_content(self, node_id, fm, content):
+            return content
+    os.environ["MDCG_REACH_INDEX"] = os.path.join(root, "idx2.json")
+    reach._CACHE.clear()
+    got_h, meta_h = reach.narrow(_CG5(), [{"path": "knowledge/a.md"}], ["abcd"], {"abcd"}, None, q="abcd")
+    ok(got_h is None and meta_h.get("reach") == "hash_incomplete",
+       "⑤ 缺 content_hash 时一律回退不收敛", str(meta_h)[:80])
+    # r17 复核：库内含不可读节点时，磁盘缓存仍须判新鲜（口径与 build 的剔除对齐）
+    class _CG6:
+        def __init__(self):
+            self.root = root
+            self.index = {"nodes": {"n1": {"path": "knowledge/a.md", "content_hash": "H1"},
+                                          "n2": {"path": "knowledge/locked.md", "content_hash": "H2"}}}
+        def _read(self, e):
+            if e.get("path", "").endswith("locked.md"):
+                return None, None          # 不可读（模拟解密失败）
+            return {}, ""
+        def _open_content(self, node_id, fm, content):
+            return content
+    os.environ["MDCG_REACH_INDEX"] = os.path.join(root, "idx3.json")
+    cg6 = _CG6()
+    i6 = reach.ReachIndex(root)
+    i6.build(cg6)
+    i6.save()
+    i6b = reach.ReachIndex(root)
+    i6b.load()
+    ok(reach._disk_fresh(i6b, cg6) is True,
+       "⑤ 含不可读节点时磁盘缓存仍判新鲜（跨进程可复用）",
+       "hashes=%d" % len(i6.hashes))
+    cg6.index["nodes"]["n1"]["content_hash"] = "H9"
+    ok(reach._disk_fresh(i6b, cg6) is False, "⑤ 已缓存节点 hash 变即判不新鲜")
+    # r18 复核：hash 不完整时——首次调用必须暴露首建成本；第二次调用不得再全库重建
+    os.environ["MDCG_REACH_INDEX"] = os.path.join(root, "idx4.json")
+    reach._CACHE.clear()
+    _cg7 = _CG5()
+    _g1, m1 = reach.narrow(_cg7, [{"path": "knowledge/a.md"}], ["abcd"], {"abcd"}, None, q="abcd")
+    ok(_g1 is None and m1.get("reach") == "hash_incomplete" and m1.get("reach_build_docs") is not None,
+       "⑤ hash 不完整：首次调用暴露首建成本", str(m1)[:90])
+    _g2, m2 = reach.narrow(_cg7, [{"path": "knowledge/a.md"}], ["abcd"], {"abcd"}, None, q="abcd")
+    ok(_g2 is None and m2.get("reach") == "hash_incomplete" and "reach_build_docs" not in m2,
+       "⑤ hash 不完整：第二次调用复用缓存（不再全库重建）", str(m2)[:90])
+    print(f"\n===== 键编码验收：{PASS}/{PASS + FAIL} 通过 =====")
+    return 0 if FAIL == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())