@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/test_v14_fixes.py

@@ -0,0 +1,397 @@
+# -*- coding: utf-8 -*-
+"""v14 第三方验证缺陷回归集（md_cg 侧：B / C / D / E / F / G / H）。
+
+来源：第三方独立验证报告 v14（基线 784e91f）§4 复现取证。本文件把该报告中
+**可复跑的观测**固化为机械断言——每条断言对应报告里的一条缺陷，修复前红、
+修复后绿；任一回归即红灯。
+
+覆盖（与报告编号一一对应）：
+  B  `trust.propagate` 多跳失效传播被 `doubted` 中间节点整体截断（下游永不降级）
+  C  `hotcache._query_key` 未覆盖 include_work/roles/paths/fusion/judge_ranking/
+     goal_text/query_expand/context/path_weights/recall_only/early_stop_threshold
+     → 跨口径串味（roles+include_work 可致资格泄漏）
+  D  `coldverify._process` 未检查 `trust.set_state` 返回值 → 迁移被拒却上报
+     ok=True（静默撒谎），且 stats.errors 掩盖
+  E  `md_cg/units.py` 自持一份 serve 判活口径（ts-only + 5s vs 权威三层 + 15s）
+  F  测试面非幂等：旁路执行造出 `_md_cg_wisdom_graph/` 空壳 → runner 由 SKIP 转 FAIL
+  G  超边幂等键 `node_id_for` 分隔符未转义/无长度前缀 → 相邻列搬移得同 id
+  H  `bench_en_atoms_public.py` 文件尾换行
+
+运行：python -m md_cg.test_v14_fixes
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+import tempfile
+import time
+
+try:
+    from . import coldverify, hotcache, hyperedge, trust, units
+    from .mdcos import MdCGOS
+except ImportError:                                   # 直接脚本运行
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from md_cg import coldverify, hotcache, hyperedge, trust, units
+    from md_cg.mdcos import MdCGOS
+
+_REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+PASS, FAIL = 0, []
+
+
+def ok(cond, label):
+    global PASS
+    if cond:
+        PASS += 1
+        print("  ok   " + label)
+    else:
+        FAIL.append(label)
+        print("  FAIL " + label)
+
+
+def phase(name):
+    print("--- " + name)
+
+
+def _ccg(name, deps=None, body=""):
+    sub = ("依赖 " + "、".join(deps)) if deps else "无"
+    return ("# 功能名：%s\n# 生效条件：无条件\n# 子功能：%s\n# 执行：无\n"
+            "# 验证方式：test\n# 不适用条件：无\n\n%s %s" % (name, sub, name, body))
+
+
+def _st(cg, nid):
+    return trust.state_of(cg.index["nodes"].get(nid) or {})
+
+
+def _load_run_tests():
+    """加载 scripts/run_tests.py（非包，按文件路径加载）。"""
+    p = os.path.join(_REPO, "scripts", "run_tests.py")
+    spec = importlib.util.spec_from_file_location("_v14_run_tests", p)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _hb(jd, pid, age_ms):
+    import json
+    with open(os.path.join(jd, "_serve.json"), "w", encoding="utf-8") as f:
+        json.dump({"ts": time.time() * 1000 - age_ms, "pid": pid, "workers": 1}, f)
+
+
+# ------------------------------------------------------------------ B
+def phase_b(tmp):
+    phase("B trust.propagate 多跳传播须穿过 doubted 中间节点")
+    ids = {"a": "mem_v14b_a", "b": "mem_v14b_b",
+           "c": "mem_v14b_c", "d": "mem_v14b_d"}
+
+    # B1 对照（中间节点非 doubted）：多跳正常
+    cg1 = MdCGOS(root=os.path.join(tmp, "b1"))
+    cg1.add(ids["a"], _ccg("上游甲"), layer="knowledge")
+    cg1.add(ids["b"], _ccg("中间乙", ["甲"]), layer="knowledge",
+           depends_on=[ids["a"]])
+    cg1.add(ids["c"], _ccg("下游丙", ["乙"]), layer="knowledge",
+           depends_on=[ids["b"]])
+    cg1.add(ids["d"], _ccg("末端丁", ["丙"]), layer="knowledge",
+           depends_on=[ids["c"]])
+    ok(ids["b"] in trust.dependents_index(cg1).get(ids["a"], []),
+       "B1 反查索引就位（甲 ← 乙）")
+    trust.set_state(cg1, ids["a"], "expired", reason="t", actor="t")
+    r1 = trust.propagate(cg1, apply=True)
+    ok([_st(cg1, ids[k]) for k in ("b", "c", "d")] == ["doubted"] * 3,
+       "B2 对照：中间节点非 doubted 时乙/丙/丁全被标 doubted（实得 %s）"
+       % [_st(cg1, ids[k]) for k in ("b", "c", "d")])
+    ok(r1.get("updated_count") == 3, "B2b updated_count=3（实得 %s）"
+       % r1.get("updated_count"))
+
+    # B3 初始 doubts 中间节点：下游仍须可达
+    cg2 = MdCGOS(root=os.path.join(tmp, "b2"))
+    for k, kw in (("a", {}), ("b", {"depends_on": [ids["a"]]}),
+                  ("c", {"depends_on": [ids["b"]]}),
+                  ("d", {"depends_on": [ids["c"]]})):
+        cg2.add(ids[k], _ccg("甲" + k), layer="knowledge", **kw)
+    trust.set_state(cg2, ids["a"], "expired", reason="t", actor="t")
+    trust.set_state(cg2, ids["b"], "doubted", reason="t", actor="t")
+    r2 = trust.propagate(cg2, apply=True)
+    ok([_st(cg2, ids[k]) for k in ("c", "d")] == ["doubted", "doubted"],
+       "B3 中间节点已 doubted 时下游丙/丁仍被标 doubted（实得 %s）"
+       % [_st(cg2, ids[k]) for k in ("c", "d")])
+    ok(r2.get("updated_count") == 2, "B3b updated_count=2（实得 %s）"
+       % r2.get("updated_count"))
+    ok(ids["b"] not in (r2.get("updated") or []),
+       "B3c doubted 中间节点不被重复标记（幂等）")
+
+    # B4 真实序列：先 mark_dependents（预演直接下游）再 propagate
+    cg3 = MdCGOS(root=os.path.join(tmp, "b3"))
+    for k, kw in (("a", {}), ("b", {"depends_on": [ids["a"]]}),
+                  ("c", {"depends_on": [ids["b"]]}),
+                  ("d", {"depends_on": [ids["c"]]})):
+        cg3.add(ids[k], _ccg("乙" + k), layer="knowledge", **kw)
+    trust.set_state(cg3, ids["a"], "expired", reason="t", actor="t")
+    trust.mark_dependents(cg3, ids["a"])
+    ok(_st(cg3, ids["b"]) == "doubted", "B4 一跳标记生效（乙=doubted）")
+    r3 = trust.propagate(cg3, apply=True)
+    ok([_st(cg3, ids[k]) for k in ("c", "d")] == ["doubted", "doubted"],
+       "B5 真实序列（先 mark_dependents 再 propagate）多跳不失效（实得 %s）"
+       % [_st(cg3, ids[k]) for k in ("c", "d")])
+    ok(r3.get("updated_count") == 2, "B5b updated_count=2（实得 %s）"
+       % r3.get("updated_count"))
+    for cg in (cg1, cg2, cg3):
+        cg.close()
+
+
+# ------------------------------------------------------------------ C
+def phase_c(tmp):
+    phase("C hotcache query 键覆盖全部影响结果的参数")
+    cg = MdCGOS(root=os.path.join(tmp, "c"))
+    hotcache.attach(cg)
+    kw = "v14cache口径"
+    good, work = "mem_v14c_good", "mem_v14c_work"
+    cg.add(good, _ccg("常规记忆", body=kw), layer="knowledge")
+    cg.add(work, _ccg("工具输出", body=kw), layer="knowledge",
+           role="tool-output")
+
+    q = kw
+    ids = lambda rs: [x[0]["id"] for x in rs]          # noqa: E731
+
+    # C1-C2：**先**以 include_work 口径查询（污染候选规则）
+    r1, m1 = cg.search_rrf(q, k=5, include_work=True)
+    ok(m1.get("cached") is not True, "C1 include_work 首次查询非缓存")
+    ok(work in ids(r1), "C2 include_work=True 时工作角色节点出现（该出的要出）")
+
+    # C3-C4：**随后的首次默认查询**不得复用该口径（报告 C10 资格泄漏）
+    r2, m2 = cg.search_rrf(q, k=5)
+    ok(work not in ids(r2), "C3 默认查询不得返回工作角色节点（无资格泄漏）")
+    ok(m2.get("cached") is not True,
+       "C4 默认查询不得复用 include_work 口径缓存（报告 C9/C10）")
+
+    # C5：默认口径自身缓存仍工作（修法不是「一律不缓存」）
+    r3, m3 = cg.search_rrf(q, k=5)
+    ok(work not in ids(r3) and m3.get("cached") is True,
+       "C5 默认口径重复查询命中缓存且结果不含工作角色")
+
+    r4, m4 = cg.search_rrf(q, k=5, paths=("bucket",))          # noqa: F841
+    r5, m5 = cg.search_rrf(q, k=5, paths=("lexical",))
+    ok(m5.get("cached") is not True, "C6 paths 不同口径不得互相命中（报告 C12）")
+    ok("bucket" not in (m5.get("paths") or {}),
+       "C7 paths=('lexical',) 的结果不含 bucket 路（实得 %s）"
+       % sorted((m5.get("paths") or {}).keys()))
+
+    r6, m6 = cg.search_rrf(q, k=5, fusion="max")                # noqa: F841
+    ok(m6.get("cached") is not True, "C8 fusion 不同口径不得互相命中")
+
+    r7, m7 = cg.search_rrf(q, k=5, judge_ranking=True)          # noqa: F841
+    ok(m7.get("cached") is not True, "C9 judge_ranking 不同口径不得互相命中")
+
+    r8, m8 = cg.search_rrf(q, k=5, roles=["tool-output"])       # noqa: F841
+    ok(m8.get("cached") is not True, "C10 roles 不同口径不得互相命中")
+
+    r9, m9 = cg.search_rrf(                                     # noqa: F841
+        q, k=5, paths=("fuzzy",),
+        query_expand=lambda _q: {"__source__": "test", kw: 1.0})
+    ok(m9.get("cached") is not True,
+       "C11 query_expand（自定义可调用）不写不读缓存（无法稳定进键即绕行）")
+    _, m9b = cg.search_rrf(
+        q, k=5, paths=("fuzzy",),
+        query_expand=lambda _q: {"__source__": "test", kw: 1.0})
+    ok(m9b.get("cached") is not True, "C11b 绕行为持续生效（非一次性）")
+
+    r10, m10 = cg.search_rrf(q, k=5, goal_text="完全不同目标向量",       # noqa: F841
+                             paths=("goal",))
+    ok(m10.get("cached") is not True, "C12 goal_text 不同口径不得互相命中")
+
+    # C13-C15 对照（报告 C13）：时间算子启用时读写双侧绕行缓存
+    cg.add("mem_v14c_time", _ccg("时间轴记忆", body=kw), layer="knowledge")
+    _, mt1 = cg.search_rrf(q, k=5, start_time=0.0, end_time=time.time() + 1e9)
+    ok(mt1.get("cached") is not True, "C13 时间算子启用时不写不读缓存（对照）")
+    _, mt2 = cg.search_rrf(q, k=5, start_time=0.0, end_time=time.time() + 1e9)
+    ok(mt2.get("cached") is not True, "C14 时间算子重复查询仍不命中缓存（对照）")
+    rt3, _mt3 = cg.search_rrf(q, k=5)
+    ok(work not in ids(rt3),
+       "C15 时间算子绕行后默认口径结果不变（无工作角色混入）")
+
+    # C16 同口径确实仍能命中（修法不是「一律不缓存」）
+    _, mh1 = cg.search_rrf(q, k=5)
+    _, mh2 = cg.search_rrf(q, k=5)
+    ok(mh2.get("cached") is True,
+       "C16 同口径重复查询仍命中缓存（保留热路径收益）")
+    cg.close()
+
+
+# ------------------------------------------------------------------ D
+def phase_d(tmp):
+    phase("D coldverify 非法迁移须如实报错（不得静默撒谎）")
+    cg = MdCGOS(root=os.path.join(tmp, "d"))
+    coldverify.attach(cg)
+    q = coldverify.get(cg)
+
+    # D1 doubted + 已过期 → doubted→expired 被 TRANSITIONS 拒绝
+    n1 = "mem_v14d_expired_doubted"
+    cg.add(n1, _ccg("存疑且过期"), layer="knowledge",
+           valid_from="2020-01-01", valid_until="2021-01-01")
+    trust.set_state(cg, n1, "doubted", reason="t", actor="t")
+    coldverify.enqueue(cg, n1, action="reverify")
+    r1 = q.drain(cg)
+    ok(r1 and r1[0].get("ok") is False,
+       "D1 非法迁移（doubted→expired）上报 ok=False（报告 V6）")
+    ok(_st(cg, n1) == "doubted", "D2 节点状态未被迁移（仍 doubted）")
+    ok((r1[0].get("error") or ""), "D3 失败原因如实透出（error 非空）")
+    ok(q.status()["stats"]["errors"] >= 1,
+       "D4 stats.errors 计入（不再掩盖，报告 V7b）")
+
+    # D5 verified + 未生效 → verified→unverified 被拒绝
+    n2 = "mem_v14d_notyet_verified"
+    cg.add(n2, _ccg("已验证但未生效"), layer="knowledge",
+           valid_from="2099-01-01")
+    trust.set_state(cg, n2, "verified", reason="t", actor="t")
+    coldverify.enqueue(cg, n2, action="reverify")
+    r2 = q.drain(cg)
+    ok(r2 and r2[0].get("ok") is False,
+       "D5 非法迁移（verified→unverified）上报 ok=False（报告 V7）")
+    ok(_st(cg, n2) == "verified", "D6 节点状态未被迁移（仍 verified）")
+
+    # D7 合法迁移仍正常（修法不是「一律报错」）
+    n3 = "mem_v14d_ok"
+    cg.add(n3, _ccg("已验证且过期"), layer="knowledge",
+           valid_from="2020-01-01", valid_until="2021-01-01")
+    trust.set_state(cg, n3, "verified", reason="t", actor="t")
+    coldverify.enqueue(cg, n3, action="reverify")
+    r3 = q.drain(cg)
+    ok(r3 and r3[0].get("ok") is True and _st(cg, n3) == "expired",
+       "D7 合法迁移（verified→expired）仍正常（实得 %s / %s）"
+       % (r3[0].get("ok") if r3 else None, _st(cg, n3)))
+    cg.close()
+
+
+# ------------------------------------------------------------------ E
+def phase_e(tmp):
+    phase("E units 判活口径须与权威三层同口径")
+    import hive.serve_start as serve_start
+
+    ok(float(units.FRESH_S) == float(serve_start.FRESH_S),
+       "E1 units.FRESH_S 与 serve_start.FRESH_S 同值（实得 %s vs %s）"
+       % (units.FRESH_S, serve_start.FRESH_S))
+    ok(float(units.FRESH_S) == 15.0, "E2 阈值为权威 15s（实得 %s）"
+       % units.FRESH_S)
+    src = open(units.__file__, encoding="utf-8").read()
+    ok('"pid_alive":' in src and '"pid_is_self_program":' in src,
+       "E3 units 透出三层判据明细（新鲜/pid 存活/pid 身份，可审计）")
+    ok("def pid_is_self_program" in src, "E4 units 有身份层判据")
+    ok("（同 _serve_alive）" not in src,
+       "E5 契约注释不再自称「同 _serve_alive」（该断言曾在 v13 后失效）")
+
+    jd = os.path.join(tmp, "hive_jobs")
+    os.makedirs(jd, exist_ok=True)
+    cases = [("新鲜+本进程+非 hive 映像", os.getpid(), 0),
+             ("同类心跳 age=8s", os.getpid(), 8000),
+             ("同类心跳 age=20s", os.getpid(), 20000),
+             ("pid 不存在", 999999, 0),
+             ("pid 不存在且陈旧", 999999, 60000)]
+    for label, pid, age in cases:
+        _hb(jd, pid, age)
+        a = bool(units.serve_state(jd)["alive"])
+        b = bool(serve_start.serve_alive(jd))
+        ok(a == b, "E6 %s：units=%s / serve_start=%s（须同结论）"
+           % (label, a, b))
+    with open(os.path.join(jd, "_serve.json"), "w", encoding="utf-8") as f:
+        f.write("{ 坏 json")
+    ok(bool(units.serve_state(jd)["alive"]) is False,
+       "E7 心跳损坏时不判活且不抛")
+    os.remove(os.path.join(jd, "_serve.json"))
+    ok(bool(units.serve_state(jd)["alive"]) is False, "E8 无心跳时不判活")
+
+
+# ------------------------------------------------------------------ F
+def phase_f(tmp):
+    phase("F 测试面幂等：空壳目录不算依赖就绪")
+    from . import md_whitebox
+
+    cr = getattr(md_whitebox, "corpus_ready", None)
+    if not callable(cr):
+        ok(False, "F1 corpus_ready 判据未提供（修复前：只判目录存在）")
+    else:
+        shell = os.path.join(tmp, "shell")
+        os.makedirs(shell)
+        ok(cr(shell) is False, "F1 空壳目录不算语料就绪")
+
+        real = os.path.join(tmp, "real", "knowledge")
+        os.makedirs(real)
+        with open(os.path.join(real, "n.md"), "w", encoding="utf-8") as f:
+            f.write("---\nid: x\n---\n正文\n")
+        ok(cr(os.path.join(tmp, "real")) is True, "F2 含 md 的目录算就绪")
+
+    missing = os.path.join(tmp, "missing_corpus")
+    try:
+        md_whitebox.build_db_from_md(root=missing, verbose=False)
+        ok(False, "F3 语料缺失须 fail-closed")
+    except FileNotFoundError:
+        ok(True, "F3 语料缺失 fail-closed（FileNotFoundError）")
+    except Exception as exc:                               # noqa: BLE001
+        ok(False, "F3 语料缺失 fail-closed（实得 %s: %s）"
+           % (type(exc).__name__, exc))
+    ok(not os.path.exists(missing), "F4 fail-closed 不产生空壳目录副作用")
+
+    rt = _load_run_tests()
+    old_repo = rt._REPO
+    try:
+        rt._REPO = tmp
+        sh = os.path.join(tmp, "_md_cg_wisdom_graph")
+        os.makedirs(sh)
+        ok(rt._dep_mdroot() is not None,
+           "F5 runner：空壳 _md_cg_wisdom_graph 不等于依赖就绪")
+        with open(os.path.join(sh, "n.md"), "w", encoding="utf-8") as f:
+            f.write("---\nid: x\n---\n")
+        ok(rt._dep_mdroot() is None, "F6 runner：含 md 时依赖就绪")
+    finally:
+        rt._REPO = old_repo
+
+    for rel in ("md_cg/test_md_access_parity.py",
+                "md_cg/test_p44_md_whitebox.py",
+                "md_cg/test_wisdom_md_store.py"):
+        txt = open(os.path.join(_REPO, rel), encoding="utf-8").read()
+        ok("SKIP" in txt,
+           "F7 %s 自带依赖缺失自辩（SKIP 出口）" % os.path.basename(rel))
+
+
+# ------------------------------------------------------------------ G / H
+def phase_g():
+    phase("G 超边幂等键无歧义（长度前缀）")
+    base = {"received_at": "t", "verify_id": "a", "commit": "b",
+            "verdict": "v", "receipt_job": "j", "iter_id": "i"}
+    row1 = dict(base, commit="b\x1fc")
+    row2 = dict(base, verify_id="a\x1fb", commit="c")
+    ok(hyperedge.node_id_for(row1) != hyperedge.node_id_for(row2),
+       "G1 相邻列搬移含 \\x1f 的文本得不同 id（报告 H17）")
+    ok(hyperedge.node_id_for(row1) == hyperedge.node_id_for(dict(row1)),
+       "G2 同一台账行恒同 id（幂等保持）")
+    ok(hyperedge.node_id_for(base).startswith("he_"), "G3 id 前缀不变")
+    bad = dict(base, commit="c")
+    ok(hyperedge.node_id_for(base) != hyperedge.node_id_for(bad),
+       "G4 无分隔符对照组 id 不同（问题是规范化而非哈希碰撞）")
+
+    phase("H 卫生：文件尾换行")
+    p = os.path.join(_REPO, "md_cg", "bench_en_atoms_public.py")
+    with open(p, "rb") as f:
+        ok(f.read().endswith(b"\n"), "H1 bench_en_atoms_public.py 尾换行在位")
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="mdcg_v14_")
+    try:
+        phase_b(tmp)
+        phase_c(tmp)
+        phase_d(tmp)
+        phase_e(tmp)
+        phase_f(tmp)
+        phase_g()
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    print("\nPASS=%d FAIL=%d" % (PASS, len(FAIL)))
+    if FAIL:
+        for f in FAIL:
+            print("  - " + f)
+        sys.exit(1)
+
+
+main()

package/md_cg/test_validity_filter.py

@@ -0,0 +1,280 @@
+# -*- coding: utf-8 -*-
+"""查询侧时效过滤（validity）验收 · GBrain 可借鉴点交接 §3②
+
+【裁决】使用者三处拍板，是本文件全部断言的判据来源：
+  ① 候选面**只排已过期**（valid_until 已过）；**未生效（valid_from 未到）保留**。
+     依据仓内既有纪律：`scrub` 模块「valid_from 绝不并入 _EXPIRY_KEYS」——
+     `not_yet`（尚未开始）与 `expired`（已经失效）语义相反；预约/计划类记忆
+     在生效前仍应可召回，故不得用「时间轴上不活跃」一刀切。
+  ② 启用默认值 = **opt-in 默认关**（缺省不过滤）：零 rust 镜像义务（保 py↔rust
+     零漂移硬承诺）、零 bench 漂移、完全可逆。
+  ③ 过滤落在**候选层**（一处过滤全链路生效：search / search_rrf / recall），
+     与 session / branch 过滤同构；MCP 面三入口透传。
+
+【覆盖】
+  ① `trust.is_expired` 布尔语义（四态→布尔；端点不可解析不猜测）+ scrub 纪律交叉守卫
+  ② 候选面：MdCG.search（裸核心）/ MdCGSecure.search（角色面）
+  ③ 默认关：缺省口径与启用口径逐条对照（opt-in 可逆性）
+  ④ search_rrf：融合面 + query 热缓存分键（validity 不入键会串口径）
+  ⑤ recall：RRF 分支 + 非 RRF 分支
+  ⑥ 图扩展：零词面交集节点经 edges 扩散可达时同样受 validity 约束
+  ⑦ MCP 面三入口透传（cg op=read / mdcg_search / mdcg_recall）
+
+【不适用】写入侧（add 落 valid_from/valid_until 是本项前提，非本项范围）；
+  库内真实数据面（当前 13514 节点零有效期，故本项为 opt-in 零漂移）。
+"""
+import os
+import shutil
+import sys
+import tempfile
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Windows cmd 默认 GBK：测试自带 UTF-8 兜底，不依赖调用方记得加 -X utf8。
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+from md_cg import hotcache, mcp_server as MS, scrub, trust
+from md_cg.mdcg import MdCG
+from md_cg.mdcos import MdCGSecure
+from md_cg.security import DEFAULT_SENSITIVITY, Principal
+
+_ok = 0
+_bad = []
+
+
+def check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("[PASS] " + name)
+    else:
+        _bad.append(name)
+        print("[FAIL] %s  · %s" % (name, str(detail)[:220]))
+
+
+Q = "量子咖啡机萃取压力曲线"          # 罕见词：测试库内确定性命中
+PAST, FUT = "2001-01-01", "2099-01-01"
+
+
+def _princ():
+    return Principal(actor="t_validity", clearance=DEFAULT_SENSITIVITY,
+                     can_write=True, can_admin=True, role="designer")
+
+
+def _ids(res):
+    """命中集 id 清单。
+
+    口径=**nid 是否在命中集**，而非「结果为空」——全扫兜底返回低分节点
+    是检索器既有行为，不属过滤失败。
+    """
+    out = []
+    for r in res or []:
+        n = r[0] if isinstance(r, tuple) else r
+        if isinstance(n, dict) and isinstance(n.get("node"), dict):
+            n = n["node"]        # _cg_call(op=read) 的 {"node": view} 包装
+        out.append((n or {}).get("id"))
+    return out
+
+
+def _seed(cg):
+    """三态语料：expired / not_yet / unknown + 一条图扩展专用的 expired。"""
+    cg.add("mem_now", Q + " 现行规格 9 巴", layer="knowledge",
+           verification_basis="test", consistency=False)
+    cg.add("mem_old", Q + " 旧版规格已被取代", layer="knowledge",
+           verification_basis="test", consistency=False, valid_until=PAST)
+    cg.add("mem_future", Q + " 下一代规格预告", layer="knowledge",
+           verification_basis="test", consistency=False, valid_from=FUT)
+    cg.add("mem_hub", Q + " 主档索引", layer="knowledge",
+           verification_basis="test", consistency=False,
+           edges=[{"target": "mem_ghost", "relation_type": "causal"}])
+    # 词面与 Q 零交集：只能经图扩展（edges）抵达 —— 图扩展绕过候选层时的靶子
+    cg.add("mem_ghost", "旁系条目与提问没有任何词面重合", layer="knowledge",
+           verification_basis="test", consistency=False, valid_until=PAST)
+
+
+# ---------------------------------------------------------------- ① 纯函数
+def _t1():
+    check("①expired → True", trust.is_expired({"valid_until": PAST}) is True)
+    check("①not_yet 不算过期（语义相反纪律）",
+          trust.is_expired({"valid_from": FUT}) is False)
+    check("①active → False",
+          trust.is_expired({"valid_from": "2020-01-01",
+                            "valid_until": "2030-01-01"}) is False)
+    check("①unknown（无时间轴）→ False", trust.is_expired({}) is False)
+    check("①None 入参 → False", trust.is_expired(None) is False)
+    check("①端点不可解析 → 不猜测（False，不误判为过期）",
+          trust.is_expired({"valid_until": "不是时间"}) is False)
+    check("①now 显式传入生效",
+          trust.is_expired({"valid_until": "2030-01-01"},
+                           now=trust.parse_time("2035-01-01")) is True)
+    check("①判定序：未来起点优先（not_yet 而非 expired）",
+          trust.validity({"valid_from": FUT, "valid_until": PAST})[0] == "not_yet")
+    check("①scrub 纪律交叉守卫：valid_from 绝不并入 _EXPIRY_KEYS",
+          "valid_from" not in scrub._EXPIRY_KEYS
+          and "valid_until" in scrub._EXPIRY_KEYS
+          and "valid_from" in scrub._NOT_YET_KEYS,
+          str(scrub._EXPIRY_KEYS))
+    # ---- 2026-09-19 阶段一：规范键族 + 第三类语义（信念时间）交叉守卫 ----
+    check("①阶段一：effective_from 属未生效族、绝不入已结束族",
+          "effective_from" in scrub._NOT_YET_KEYS
+          and "effective_from" not in scrub._EXPIRY_KEYS,
+          str(scrub._EXPIRY_KEYS))
+    check("①阶段一：effective_until/expired_at 属已结束族、不入未生效族",
+          "effective_until" in scrub._EXPIRY_KEYS
+          and "expired_at" in scrub._EXPIRY_KEYS
+          and "effective_until" not in scrub._NOT_YET_KEYS
+          and "expired_at" not in scrub._NOT_YET_KEYS,
+          str(scrub._EXPIRY_KEYS))
+    check("①阶段一：believed_at 两族都不入（第三类语义·物理隔离）",
+          trust.BELIEVED_FIELD not in scrub._EXPIRY_KEYS
+          and trust.BELIEVED_FIELD not in scrub._NOT_YET_KEYS,
+          str(scrub._EXPIRY_KEYS))
+    check("①键族同步守卫：trust 别名元组 ⊆ scrub 对应键族（两侧禁各自漂移）",
+          set(trust.FROM_ALIASES) <= set(scrub._NOT_YET_KEYS)
+          and set(trust.UNTIL_ALIASES) <= set(scrub._EXPIRY_KEYS),
+          str(trust.FROM_ALIASES) + " / " + str(scrub._NOT_YET_KEYS))
+    # ---- 规范键优先、别名回落（双轨读取）----
+    check("①规范键优先：effective_from 压过 valid_from",
+          trust.validity({"effective_from": FUT,
+                          "valid_from": "2020-01-01"})[0] == "not_yet")
+    check("①别名回落：仅历史键时照常判定（存量兼容）",
+          trust.validity({"valid_from": FUT})[0] == "not_yet")
+    check("①规范键不可解析 → 继续回落别名（不因写坏一键而漏判）",
+          trust.validity({"effective_until": "坏值",
+                          "valid_until": PAST})[0] == "expired")
+    check("①believed_at 不参与时效判定（物理隔离·绝不误判）",
+          trust.validity({"believed_at": PAST})[0] == "unknown"
+          and trust.is_expired({"believed_at": PAST}) is False)
+    check("①believed_at 读取器：epoch 值 / 缺字段 None",
+          trust.believed_at({"believed_at": PAST}) is not None
+          and trust.believed_at({}) is None)
+    check("①time_window_msg 点名实际命中键（规范名/历史名各归其位）",
+          "effective_from" in trust.time_window_msg({"effective_from": FUT})
+          and "valid_from" in trust.time_window_msg({"valid_from": FUT}))
+
+
+# ------------------------------------------------- ②③ 候选面 + 默认关
+def _t2(root_core, root_sec):
+    core = MdCG(root_core)
+    _seed(core)
+
+    off = _ids(core.search(Q, k=20)[0])
+    check("③MdCG.search 默认关：expired 可见（opt-in 可逆）",
+          "mem_old" in off, off)
+    check("③MdCG.search 默认关：not_yet 可见", "mem_future" in off, off)
+    on = _ids(core.search(Q, k=20, validity=True)[0])
+    check("②MdCG.search 启用后 expired 剔除", "mem_old" not in on, on)
+    check("②MdCG.search 启用后 not_yet 保留", "mem_future" in on, on)
+    check("②MdCG.search 启用后 unknown 保留", "mem_now" in on, on)
+
+    sec = MdCGSecure(root_sec, principal=_princ())
+    _seed(sec)
+    sec_off = _ids(sec.search(Q, k=20)[0])
+    check("③Secure.search 默认关：expired 可见", "mem_old" in sec_off, sec_off)
+    sec_on = _ids(sec.search(Q, k=20, validity=True)[0])
+    check("②Secure.search 启用后 expired 剔除", "mem_old" not in sec_on, sec_on)
+    check("②Secure.search 启用后 not_yet 保留",
+          "mem_future" in sec_on, sec_on)
+
+
+# --------------------------- ④ RRF + 缓存分键  ⑤ recall  ⑥ 图扩展
+def _t3(root):
+    cg = MdCGSecure(root, principal=_princ())
+    _seed(cg)
+    hotcache.attach(cg)
+
+    off, _ = cg.search_rrf(Q, k=20)
+    on, _ = cg.search_rrf(Q, k=20, validity=True)
+    check("④search_rrf 默认关：expired 可见", "mem_old" in _ids(off), _ids(off))
+    check("④search_rrf 启用后 expired 剔除", "mem_old" not in _ids(on), _ids(on))
+    check("④search_rrf 启用后 not_yet 保留", "mem_future" in _ids(on), _ids(on))
+
+    # 缓存分键：两口径必须各自成键，否则第二次调用命中第一次的缓存即串口径
+    hc = hotcache.get(cg)
+    on2, meta2 = cg.search_rrf(Q, k=20, validity=True)
+    off2, meta_off = cg.search_rrf(Q, k=20)
+    check("④缓存命中路径仍零 expired（meta.cached 可证命中）",
+          "mem_old" not in _ids(on2) and meta2.get("cached") is True,
+          "cached=%s ids=%s" % (meta2.get("cached"), _ids(on2)))
+    check("④两口径各自成键且互不顶替（默认口径仍见 expired 且命中自身缓存）",
+          "mem_old" in _ids(off2) and meta_off.get("cached") is True,
+          "off_cached=%s ids=%s" % (meta_off.get("cached"), _ids(off2)))
+    check("④缓存中两口径键并存（>=2 条）",
+          hc.stats()["query_cache_size"] >= 2, hc.stats())
+
+    # ⑥ 图扩展：零词面交集节点只能经 edges 抵达 —— 前置证据 + 过滤断言
+    check("⑥前置证据：不过滤时 ghost 经图扩展可达（零词面交集）",
+          "mem_ghost" in _ids(off), _ids(off))
+    check("⑥启用后 ghost 被剔除（图扩展不绕过时效过滤）",
+          "mem_ghost" not in _ids(on), _ids(on))
+
+    # ⑤ recall 两分支
+    p_off = [p.get("id") for p in cg.recall(Q, budget_tokens=6000, k=20)["pack"]]
+    check("⑤recall（RRF 分支）默认关：expired 可见", "mem_old" in p_off, p_off)
+    p_rrf = [p.get("id") for p in cg.recall(Q, budget_tokens=6000, k=20,
+                                            validity=True)["pack"]]
+    check("⑤recall（RRF 分支）启用后 expired 剔除", "mem_old" not in p_rrf, p_rrf)
+    check("⑤recall（RRF 分支）not_yet 保留", "mem_future" in p_rrf, p_rrf)
+    p_lin = [p.get("id") for p in cg.recall(Q, budget_tokens=6000, k=20,
+                                            use_rrf=False, validity=True)["pack"]]
+    check("⑤recall（非 RRF 分支）启用后 expired 剔除",
+          "mem_old" not in p_lin, p_lin)
+    check("⑤recall（非 RRF 分支）not_yet 保留", "mem_future" in p_lin, p_lin)
+
+
+# ------------------------------------------------------------- ⑦ MCP 面
+def _t4(root):
+    cg = MdCGSecure(root, principal=_princ())
+    _seed(cg)
+
+    s_on = MS.call_tool(cg, "mdcg_search",
+                        {"query": Q, "k": 20, "validity": True})
+    ids_on = [r["node"]["id"] for r in s_on["results"]]
+    check("⑦mdcg_search 透传 validity（expired 剔除）",
+          "mem_old" not in ids_on, ids_on)
+    check("⑦mdcg_search 透传后 not_yet 保留", "mem_future" in ids_on, ids_on)
+    s_off = MS.call_tool(cg, "mdcg_search", {"query": Q, "k": 20})
+    ids_off = [r["node"]["id"] for r in s_off["results"]]
+    check("⑦默认关：mdcg_search 缺省 expired 可见", "mem_old" in ids_off, ids_off)
+
+    rc = MS.call_tool(cg, "mdcg_recall",
+                      {"query": Q, "k": 20, "budget_tokens": 6000,
+                       "validity": True})
+    pids = [p.get("id") for p in rc["pack"]]
+    check("⑦mdcg_recall 透传 validity（expired 剔除）",
+          "mem_old" not in pids, pids)
+    rc_off = MS.call_tool(cg, "mdcg_recall",
+                          {"query": Q, "k": 20, "budget_tokens": 6000})
+    check("⑦默认关：mdcg_recall 缺省 expired 可见",
+          "mem_old" in [p.get("id") for p in rc_off["pack"]], rc_off.get("pack"))
+
+    out = MS._cg_call(cg, {"op": "read", "query": Q, "k": 20, "validity": True})
+    oids = _ids(out.get("results") or [])
+    check("⑦cg op=read 透传 validity（expired 剔除）", "mem_old" not in oids, oids)
+    out_off = MS._cg_call(cg, {"op": "read", "query": Q, "k": 20})
+    check("⑦默认关：cg op=read 缺省 expired 可见",
+          "mem_old" in _ids(out_off.get("results") or []),
+          _ids(out_off.get("results") or []))
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="mdcg_validity_")
+    try:
+        _t1()
+        _t2(os.path.join(tmp, "core"), os.path.join(tmp, "sec"))
+        _t3(os.path.join(tmp, "rrf"))
+        _t4(os.path.join(tmp, "mcp"))
+    except Exception:
+        traceback.print_exc()
+        _bad.append("未捕获异常")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    print("\nvalidity 验收：%d 通过%s" % (
+        _ok, ("，%d 失败：%s" % (len(_bad), "; ".join(_bad))) if _bad else ""))
+    return 1 if _bad else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())