@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/test_protocol.py

@@ -0,0 +1,243 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 记忆动词协议 v1 形状钉死（静态对账 + 进程内真调形状）
+
+运行：python -m md_cg.test_protocol
+
+分工（三层，各自独立可裁）：
+  A 静态——协议声明 ↔ MCP 面实现：声明五动词 / live 有分支 / reserved 无分支 /
+    形状声明完备；`_ops_from_source` 的 AST 提取鲁棒性（单引号 · `op in` 元组 ·
+    `op.strip().lower()` 三写法 + 负例 `action ==` 不误取 + 语法错误不炸）。
+  B 动态——进程内真调 `_cg_call`，按协议声明的 required 子集校验**真实返回**：
+    route / read 三态（node · list · pack，含目标缺失返回 null）/ write 铁律三键 /
+    forget 两动作 + 失败形态 / op 推导兜底透出。
+  C 集成——`conformance.check()` 确实带上了 protocol.* 四条断言且全绿。
+
+边界（如实声明，不假装覆盖）：
+  · write 的 committed 形态在本环境不可达：未配置 MDCG_POLICY_FILE 时校验闸门恒
+    DEFER 入 review_queue（实测），故 B 段对 write 断言「铁律三键 + 未 committed
+    时去向可见（gate|moved_to）」，并按实际走的那一态校验对应形状；
+    committed 形态的字段依据是 writepipe 链尾执行器的源码事实。
+  · 本测试**不连真实库**：库根为 tempdir，断言面是形状（键集），不是数据正确性。
+"""
+import os
+import shutil
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from md_cg import conformance
+from md_cg import mcp_server as M
+from md_cg import protocol as P
+from md_cg.mdcos import MdCGSecure
+from md_cg.security import DEFAULT_SENSITIVITY, Principal
+
+_ok = 0
+_fail = []
+
+
+def check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("[PASS] " + name)
+    else:
+        _fail.append(name)
+        print("[FAIL] %s  · %s" % (name, str(detail)[:240]))
+
+
+def _p(actor="proto"):
+    return Principal(actor=actor, clearance=DEFAULT_SENSITIVITY,
+                     can_write=True, can_admin=True, role="designer")
+
+
+def _sub(shape, ret):
+    """required 子集判定——协议形状断言的原语。"""
+    return set(shape["required"]) <= set(ret or {})
+
+
+def _raises(exc, fn):
+    try:
+        fn()
+        return False
+    except exc:
+        return True
+    except Exception:                                       # noqa: BLE001
+        return False
+
+
+# ==================== A. 静态：协议声明 ↔ MCP 面实现 ====================
+print("-- A 静态对账 --")
+_a = P.audit()
+
+check("A1 audit ok（声明与实现一致）", _a["ok"] is True, _a["errors"])
+check("A2 协议 v1 且 draft 期未冻结（冻结是单向门）",
+      _a["protocol_version"] == 1 and _a["frozen"] is False,
+      (_a["protocol_version"], _a["frozen"]))
+check("A3 声明五动词且顺序固定",
+      tuple(_a["declared"]) == ("route", "read", "write", "supersede", "forget"),
+      _a["declared"])
+check("A4 live 四动词有实现分支",
+      set(_a["live"]) == {"route", "read", "write", "forget"}, _a["live"])
+check("A5 supersede 登记 reserved 且未泄漏实现（不冒充）",
+      _a["reserved"] == ["supersede"] and _a["reserved_leaked"] == [],
+      _a["reserved"])
+check("A6 无 live 动词缺实现分支", _a["missing_impl"] == [], _a["missing_impl"])
+check("A7 扩展能力面如实报告（属能力不属违例）",
+      bool(_a["extension_ops"]) and "write" not in _a["extension_ops"],
+      _a["extension_ops"])
+check("A8 每动词至少一形态、每形态带 when", all(
+    P.VERB_SPECS[v]["shapes"]
+    and all(s.get("when") for s in P.VERB_SPECS[v]["shapes"].values())
+    for v in _a["declared"]), "")
+check("A9 write 各形态 required 均含铁律三键",
+      all(set(P.WRITE_TRIO) <= set(s["required"])
+          for s in P.VERB_SPECS["write"]["shapes"].values()), "")
+check("A10 reserved 动词给出 map_to 现状映射证据",
+      bool(P.VERB_SPECS["supersede"].get("map_to")), "")
+check("A11 read 显式登记 null 形态（目标缺失 ≠ 错误）",
+      P.shape_of("read", "node_missing").get("returns_null") is True, "")
+check("A12 非法动词 fail-closed（shape_of 抛 KeyError）",
+      _raises(KeyError, lambda: P.shape_of("nosuch")), "")
+check("A13 summary 单行含 ok=True", "ok=True" in P.summary(), P.summary())
+
+_src = '''
+def _d(op, action):
+    if op == "double":
+        return 1
+    if op == 'single':
+        return 2
+    if op in ("in_a", "in_b"):
+        return 3
+    if op.strip().lower() == "stripped":
+        return 4
+    if action == "not_op":
+        return 5
+    return 0
+'''
+_ops = P._ops_from_source(_src)
+check("A14 AST 提取四写法齐（双引号/单引号/in 元组/strip().lower）",
+      set(_ops) == {"double", "single", "in_a", "in_b", "stripped"}, _ops)
+check("A15 负例：action == 分支不被误取为 op", "not_op" not in _ops, _ops)
+check("A16 语法错误返回空列表且不抛异常",
+      P._ops_from_source("if (op ==") == [], "")
+check("A17 dispatch_ops 与 audit 同源（同一次提取口径）",
+      P.dispatch_ops()["ops"] == _a["actual"], P.dispatch_ops()["ops"])
+
+# ==================== B. 动态：进程内真调形状 ====================
+print("-- B 进程内真调形状 --")
+_root = tempfile.mkdtemp(prefix="mdcg_proto_")
+_body = ("# 功能名：协议形状探针\n# 生效条件：协议形状测试\n# 子功能：无\n"
+         "# 执行：探针\n# 验证方式：test_protocol 断言\n"
+         "# 不适用条件：非形状测试场景\n\n正文 material_proto")
+try:
+    cg = MdCGSecure(_root, principal=_p())
+
+    _r = M._cg_call(cg, {"op": "route", "intent": "记忆动词协议形状"})
+    check("B1 route 形态 required 齐（knowledge/meta）",
+          _sub(P.shape_of("route"), _r), _r)
+
+    _w = M._cg_call(cg, {"op": "write", "content_kind": "text",
+                         "layer": "knowledge", "tags": ["proto"],
+                         "content": _body})
+    check("B2 write 铁律三键齐（ok/id/committed——落盘与否不靠猜）",
+          set(P.WRITE_TRIO) <= set(_w or {}), _w)
+    check("B3 write 未 committed 时去向可见（gate 或 moved_to）",
+          bool((_w or {}).get("committed"))
+          or ("gate" in (_w or {}) or "moved_to" in (_w or {})), _w)
+    if _w.get("committed"):
+        check("B3b write committed 形态 required 齐",
+              _sub(P.shape_of("write", "committed"), _w), _w)
+    else:
+        check("B3c write 闸门短路形态 required 齐（moved_to/verdict/hint）",
+              _sub(P.shape_of("write", "gate_short_circuit"), _w), _w)
+    check("B4 verdict 字段集与协议声明一致（写闸门短路态）",
+          set(P.VERDICT_FIELDS) <= set(_w.get("verdict") or {}), _w.get("verdict"))
+
+    _nid = "mem_proto1"
+    cg.add(_nid, _body, content_kind="text", layer="knowledge", tags=["proto"])
+    cg.flush()
+
+    _rn = M._cg_call(cg, {"op": "read", "node_id": _nid})
+    check("B5 read(node) 形态 required 齐（含 verification_state）",
+          _sub(P.shape_of("read", "node"), _rn),
+          list(_rn.keys()) if isinstance(_rn, dict) else _rn)
+
+    _rl = M._cg_call(cg, {"op": "read", "query": "协议形状探针"})
+    check("B6 read(list) 形态 required 齐（meta/results）",
+          _sub(P.shape_of("read", "list"), _rl), _rl)
+
+    _rp = M._cg_call(cg, {"op": "read", "query": "协议形状探针",
+                          "budget_tokens": 300})
+    check("B7 read(pack) 形态 required 齐（pack/tokens_used/budget/skipped/recent/meta）",
+          _sub(P.shape_of("read", "pack"), _rp),
+          list(_rp.keys()) if isinstance(_rp, dict) else _rp)
+
+    check("B8 read 目标缺失返回 null（协议登记形态，非错误对象）",
+          M._cg_call(cg, {"op": "read", "node_id": "mem_不存在"}) is None, "")
+
+    _f = M._cg_call(cg, {"op": "forget", "node_id": _nid, "reason": "协议测试"})
+    check("B9 forget 成功形态 required 齐（ok/id/tombstone）",
+          _sub(P.shape_of("forget", "forgotten"), _f), _f)
+    check("B10 forget 后 read(node_id) 立即返回 null（软删对读面生效）",
+          M._cg_call(cg, {"op": "read", "node_id": _nid}) is None, "")
+
+    _ff = M._cg_call(cg, {"op": "forget", "node_id": _nid, "action": "restore"})
+    check("B11 restore 返回属声明两形态之一（restored / failed）",
+          _sub(P.shape_of("forget", "restored"), _ff)
+          or _sub(P.shape_of("forget", "failed"), _ff), _ff)
+
+    _fm = M._cg_call(cg, {"op": "forget", "node_id": "mem_不存在"})
+    check("B12 forget 目标缺失失败形态 required 齐（ok/error）",
+          _sub(P.shape_of("forget", "failed"), _fm), _fm)
+
+    _d1 = M._cg_call(cg, {"content": "推导探针 derive_probe_content"})
+    check("B13 op 推导兜底：content → write 且透出 op_derived",
+          (_d1 or {}).get("op") == "write" and _d1.get("op_derived") is True, _d1)
+    check("B14 推导附加键不破坏 write 铁律三键",
+          set(P.WRITE_TRIO) <= set(_d1 or {}), _d1)
+    check("B15 推导附加键集与协议声明一致（op/op_derived/hint）",
+          set(P.DERIVE_EXTRA_KEYS) <= set(_d1 or {}), _d1)
+
+    _d2 = M._cg_call(cg, {"query": "协议形状探针"})
+    check("B16 op 推导兜底：query → read",
+          (_d2 or {}).get("op") == "read"
+          and _sub(P.shape_of("read", "list"), _d2), _d2)
+finally:
+    shutil.rmtree(_root, ignore_errors=True)
+
+# ==================== C. 集成：conformance 静态对账 ====================
+print("-- C conformance 集成 --")
+_croot = tempfile.mkdtemp(prefix="mdcg_proto_conf_")
+try:
+    # conformance.check 需要 `_index.json` 存在，而 flush() 只写分片日志
+    # （`_index_log/`）——只有 compact_index()/rebuild_index() 才落 `_index.json`。
+    _ccg = MdCGSecure(_croot, principal=_p("proto_conf"))
+    _ccg.add("mem_conf1", _body, content_kind="text", layer="knowledge",
+             tags=["proto"])
+    _ccg.rebuild_index()
+    _rep = conformance.check(_croot)
+    check("C1 报告含 protocol 段", bool(_rep.get("protocol")),
+          list(_rep.keys())[:12])
+    _ids = {c["id"]: c for c in _rep["checks"]}
+    for _cid in ("protocol.op.extension_surface", "protocol.verb.implemented",
+                 "protocol.verb.reserved_clean", "protocol.shape.declared"):
+        _c = _ids.get(_cid)
+        check("C2 已钉入 conformance 且 ok：%s" % _cid,
+              bool(_c) and _c["ok"] is True, _c)
+    check("C3 协议外 op 面为报告项 WARN（能力不是违例）",
+          _ids["protocol.op.extension_surface"]["level"] == "WARN",
+          _ids["protocol.op.extension_surface"]["level"])
+    check("C4 protocol.* 全绿（无 FAIL 残留）",
+          [c["id"] for c in _rep["checks"]
+           if c["id"].startswith("protocol.") and not c["ok"]] == [],
+          [c["id"] for c in _rep["checks"]
+           if c["id"].startswith("protocol.") and not c["ok"]])
+finally:
+    shutil.rmtree(_croot, ignore_errors=True)
+
+print("=" * 60)
+print("protocol：%d 通过 / %d 失败" % (_ok, len(_fail)))
+if _fail:
+    print("失败项：" + "; ".join(_fail))
+sys.exit(1 if _fail else 0)

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())