@furongjun1999/dsh-memory 0.4.7 → 0.4.9

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

package/md_cg/test_wisdom_md_store.py

@@ -26,6 +26,7 @@ for _p in (_ROOT, _HERE, os.path.join(_HERE, "whitebox_kb"),
 from wisdom_book import (ConditionDex, DEFAULT_DB, DEFAULT_MD_ROOT,  # noqa: E402
                          BASE_ENTRIES, BASE_RELATIONS)
 from md_access import MdConn, read_conn  # noqa: E402
+from md_whitebox import corpus_ready  # noqa: E402
 from md_store import MdStore  # noqa: E402
 from aeis_core import ConditionSpace, MemoryLayer, STNode  # noqa: E402
 
@@ -44,8 +45,11 @@ def ok(cond, label):
 # ---------------------------------------------------------------------------
 
 def group_a(tmp):
-    if not (os.path.exists(DEFAULT_DB) and os.path.isdir(DEFAULT_MD_ROOT)):
-        print("组A SKIP：生产对拍数据不全（派生库或语料根缺失）")
+    # 语料就绪判据 = 「目录存在**且含 .md**」（2026-09-20 v14 缺陷 F）：空壳
+    # 目录（兄弟测试经 MdCGOS(root) 的 makedirs 留下）不算就绪，否则组A 会
+    # 以「md 语料行数 0 > 4000」的失败示人，而真实原因是真源根本不在位。
+    if not (os.path.exists(DEFAULT_DB) and corpus_ready(DEFAULT_MD_ROOT)):
+        print("组A SKIP：生产对拍数据不全（派生库缺失或语料根缺失/空壳）")
         return
     print("组A · 生产数据对拍（全量）")
     # sqlite 侧用副本隔离：search_content 的 increment_access 会落库，
@@ -258,7 +262,7 @@ def group_d(tmp):
     ok(not dex2._md_mode, "fresh=True → sqlite 形态（兼容 api.py 兜底）")
     dex2.close()
 
-    if os.path.isdir(DEFAULT_MD_ROOT):
+    if corpus_ready(DEFAULT_MD_ROOT):
         dex3 = ConditionDex(md_root=DEFAULT_MD_ROOT)
         try:
             conn = read_conn(dex3)           # duck：MdStore.conn → MdConn

package/md_cg/test_writepipe.py

@@ -0,0 +1,214 @@
+# -*- coding: utf-8 -*-
+"""写入路径拦截器链（writepipe）验收：Pi 钩子化移植（交接文档 §3⑥）。
+
+验收口径：
+- 默认链行为与重构前 _cg_dispatch write 分支逐字节一致
+  （ACCEPT 直写 / REJECT 负记忆 / DEFER 入队 + 幂等去重联动 / gated 闸 /
+  冲突 cvd 透传）；
+- 新增/移除一个拦截器不改核心文件（register/unregister 即插即拔）；
+- 角色/层权限校验结构上不可被拦截器绕过（反面清单：信任必须结构强制）；
+- REWRITE（拦截器改写 ctx["a"]["content"]）/ 链序 / 短路 / after 观测者。
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import traceback
+
+from . import writepipe
+from .mdcos import MdCGSecure
+from .security import AccessDenied, Principal
+
+_ok = 0
+_bad = []
+_seq = [0]
+
+
+def _check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("  ok   %s" % name)
+    else:
+        _bad.append("%s %s" % (name, detail))
+        print("  FAIL %s %s" % (name, detail))
+
+
+def _mk_cg(tmp, role="designer"):
+    _seq[0] += 1
+    root = os.path.join(tmp, "root_%02d_%s" % (_seq[0], role))
+    p = Principal(tenant="default", actor="t_" + role, role=role,
+                  can_write=(role != "guest"),
+                  can_admin=(role == "designer"))
+    return MdCGSecure(root, principal=p)
+
+
+def _policy(tmp, required=("PASSED",), forbidden=("FORBIDDEN_WORD",)):
+    path = os.path.join(tmp, "policy.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({"forbidden": list(forbidden),
+                   "required": list(required)}, f)
+    os.environ["MDCG_POLICY_FILE"] = path
+    return path
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="writepipe_")
+    old_policy = os.environ.pop("MDCG_POLICY_FILE", None)
+    try:
+        _run(tmp)
+    except Exception:
+        traceback.print_exc()
+        _bad.append("未捕获异常")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+        if old_policy is not None:
+            os.environ["MDCG_POLICY_FILE"] = old_policy
+        else:
+            os.environ.pop("MDCG_POLICY_FILE", None)
+    print("\nwritepipe 验收：%d 通过%s" % (
+        _ok, ("，%d 失败：%s" % (len(_bad), "; ".join(_bad))) if _bad else ""))
+    return 1 if _bad else 0
+
+
+def _run(tmp):
+    policy = _policy(tmp)
+
+    # ---------- 1 默认链：与重构前 write 分支行为一致 ----------
+    pipe = writepipe.install_default_gates(writepipe.WritePipeline())
+    cg = _mk_cg(tmp)
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "要素齐全 PASSED",
+                            "layer": "knowledge"})
+    _check("默认链ACCEPT直写", out.get("committed") is True and out.get("ok") is True,
+           repr(out))
+    _check("冲突闸cvd透传", isinstance(out.get("consistency"), dict), repr(out))
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "含 FORBIDDEN_WORD 的违禁内容",
+                            "layer": "knowledge"})
+    _check("REJECT负记忆", out.get("moved_to") == "rejected"
+           and out.get("committed") is False, repr(out))
+
+    # DEFER（无规则文件 → 无法判定 → 入审核队列）+ 幂等去重联动
+    os.environ.pop("MDCG_POLICY_FILE", None)
+    a = {"content_kind": "text", "content": "无规则可判的内容",
+         "layer": "knowledge"}
+    out1 = pipe.execute(cg, dict(a))
+    _check("DEFER入队", out1.get("moved_to") == "review_queue"
+           and bool(out1.get("pid")), repr(out1))
+    out2 = pipe.execute(cg, dict(a))
+    _check("幂等去重联动", out2.get("dedup") is True
+           and out2.get("dup_of") == out1.get("pid"), repr(out2))
+    os.environ["MDCG_POLICY_FILE"] = policy
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "PASSED 情境记忆", "gated": True,
+                            "layer": "contextual"})
+    _check("gated闸代执行", "gate" in out, repr(out))
+
+    # ---------- 2 注册/移除拦截器不改核心文件 ----------
+    singleton = writepipe.default_pipeline()
+
+    def _block_skipme(ctx):
+        if "SKIPME" in (ctx["a"].get("content") or ""):
+            return {"ok": False, "committed": False,
+                    "moved_to": "hook_blocked", "by": "test_block"}
+        return None
+
+    singleton.register_before("test_block", _block_skipme)
+    out = singleton.execute(cg, {"content_kind": "text",
+                                 "content": "PASSED SKIPME",
+                                 "layer": "knowledge"})
+    _check("注册即拦", out.get("moved_to") == "hook_blocked", repr(out))
+    singleton.unregister_before("test_block")
+    out = singleton.execute(cg, {"content_kind": "text",
+                                 "content": "PASSED SKIPME",
+                                 "layer": "knowledge"})
+    _check("移除即恢复(核心文件零改动)", out.get("committed") is True, repr(out))
+    # 默认 before 链含 linkref→deps→audit→consistency→gated（2026-09-19 deps 闸门新增）
+    _check("单例默认链", singleton.names()["before"]
+           == ["linkref", "deps", "audit", "consistency", "gated"],
+           repr(singleton.names()))
+    _check("单例默认after链", singleton.names()["after"]
+           == ["linkref", "trust"],
+           repr(singleton.names()))
+
+    # ---------- 3 链序 / 短路 / REWRITE ----------
+    p3 = writepipe.WritePipeline()
+    order = []
+    p3.register_before("g1", lambda ctx: order.append("g1") or None)
+    p3.register_before("g2", lambda ctx: order.append("g2") or None)
+    p3.register_before("g3", lambda ctx: order.append("g3")
+                       or {"ok": False, "moved_to": "halt"})
+    cg3 = _mk_cg(tmp)
+    out = p3.execute(cg3, {"content_kind": "text", "content": "PASSED",
+                           "layer": "knowledge"})
+    _check("链序按注册序", order == ["g1", "g2", "g3"], repr(order))
+    _check("终态短路不落盘", out.get("moved_to") == "halt"
+           and "id" not in out and "committed" not in out, repr(out))
+
+    p4 = writepipe.WritePipeline()
+    p4.register_before("rw", lambda ctx:
+                       ctx["a"].__setitem__("content",
+                                            ctx["a"].get("content") + " REWRITTEN")
+                       or None)
+    cg4 = _mk_cg(tmp)
+    out = p4.execute(cg4, {"content_kind": "text", "content": "PASSED",
+                           "layer": "knowledge"})
+    _check("REWRITE改写生效", out.get("committed") is True
+           and bool(cg4.search("REWRITTEN")), repr(out))
+
+    # ---------- 4 权限结构上不可被拦截器绕过 ----------
+    cg_guest = _mk_cg(tmp, role="guest")
+    p5 = writepipe.WritePipeline()
+    p5.register_before("always_pass", lambda ctx: None)
+    try:
+        p5.execute(cg_guest, {"content_kind": "text", "content": "PASSED",
+                              "consistency": False, "layer": "knowledge"})
+        _check("权限不可绕", False, "guest 写入未被拒")
+    except AccessDenied:
+        _check("权限不可绕", True)
+    except Exception as e:  # noqa: BLE001
+        _check("权限不可绕", False,
+               "异常类型=%s:%s" % (type(e).__name__, e))
+
+    # ---------- 5 after 观测者 ----------
+    p6 = writepipe.WritePipeline()
+    seen = []
+    p6.register_after("spy", lambda ctx, out: seen.append(out.get("committed")))
+    cg6 = _mk_cg(tmp)
+    p6.execute(cg6, {"content_kind": "text", "content": "PASSED",
+                     "layer": "knowledge"})
+    _check("after观测成功", seen == [True], repr(seen))
+
+    def _boom(ctx, out):
+        raise RuntimeError("after钩子故障")
+
+    p6.register_after("boom", _boom)
+    try:
+        p6.execute(cg6, {"content_kind": "text", "content": "PASSED 二次",
+                         "layer": "knowledge"})
+        _check("after故障不吞", False, "异常被静默")
+    except RuntimeError:
+        _check("after故障不吞", True)
+
+    # ---------- 6 注册表卫生 ----------
+    p7 = writepipe.WritePipeline()
+    p7.register_before("x", lambda ctx: None)
+    p7.register_before("x", lambda ctx: None)  # 同名幂等替换
+    _check("同名幂等注册", p7.names()["before"] == ["x"], repr(p7.names()))
+    try:
+        p7.register_before("y", 123)
+        _check("类型守卫", False, "非可调用未拒")
+    except TypeError:
+        _check("类型守卫", True)
+    _check("注销返回布尔", p7.unregister_before("x") is True
+           and p7.unregister_before("x") is False)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/theory.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """md_cg · 版本层（蜂群互联 · 层0）
 
-设计依据：`docs/蜂群互联_v0.1.md` §2.3 / §3.1 / §10。
+设计依据：`docs/swarm/蜂群互联_v0.1.md` §2.3 / §3.1 / §10。
 
 版本更新权 = 蜂群**唯一核心权限**（严格唯一，仅 designer）。本模块只做
 「声明 + 校验」两件事，不做跨节点证据交换（§9.1 属存在约束，留待 v0.3）：
@@ -52,24 +52,29 @@ class TheoryError(Exception):
 # 存储
 # --------------------------------------------------------------------------
 
+# 生效条件：path 为真值时返回 path，否则取 os.environ.get(THEORY_FILE_ENV)，该值为空串/未设置时回落模块常量 DEFAULT_THEORY_FILE。
 def theory_file(path: str = None) -> str:
     return path or os.environ.get(THEORY_FILE_ENV) or DEFAULT_THEORY_FILE
 
 
+# 生效条件：传入可被 json 序列化的 payload（dict）时返回 json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":"))。
 def _canon(payload: dict) -> str:
     """规范化 JSON：键排序 + 紧凑分隔符（哈希可复现的唯一前提）。"""
     return json.dumps(payload, sort_keys=True, ensure_ascii=False,
                       separators=(",", ":"))
 
 
+# 生效条件：payload 可被 _canon 序列化时返回 hashlib.sha256(_canon(payload).encode("utf-8")).hexdigest() 的十六进制摘要。
 def declaration_hash(payload: dict) -> str:
     return hashlib.sha256(_canon(payload).encode("utf-8")).hexdigest()
 
 
+# 生效条件：对 SEALED_FIELDS 中每个 k 用 decl.get(k) 取值（缺键即 None），返回同集合长度的 dict。
 def _payload(decl: dict) -> dict:
     return {k: decl.get(k) for k in SEALED_FIELDS}
 
 
+# 生效条件：以 dict(decl) 为副本 d，写入 d["declaration_hash"]=declaration_hash(_payload(d))，返回该副本（不改动入参 decl）。
 def seal(decl: dict) -> dict:
     """封缄：补上 declaration_hash。"""
     d = dict(decl)
@@ -77,6 +82,7 @@ def seal(decl: dict) -> dict:
     return d
 
 
+# 生效条件：p=theory_file(path) 后，os.path.exists(p) 为假返回 None；open/json.load 抛 OSError 或 ValueError 也返回 None；否则 d 是 dict 时返回 d，不是 dict 返回 None。
 def load(path: str = None):
     p = theory_file(path)
     if not os.path.exists(p):
@@ -89,6 +95,7 @@ def load(path: str = None):
     return d if isinstance(d, dict) else None
 
 
+# 生效条件：p=theory_file(path)，先 os.makedirs(os.path.dirname(p) or ".")，把 decl 以 ensure_ascii=False, indent=1 写入 p+".tmp" 再 os.replace 到 p，os.chmod(p, 0o600) 抛 OSError 时忽略，最终返回 p。
 def save(decl: dict, path: str = None) -> str:
     p = theory_file(path)
     os.makedirs(os.path.dirname(p) or ".", exist_ok=True)
@@ -107,6 +114,7 @@ def save(decl: dict, path: str = None) -> str:
 # 声明与校验
 # --------------------------------------------------------------------------
 
+# 生效条件：v=(version or PROTOCOL_VERSION).strip()，v 为空串时抛 TheoryError；accepted 为假值（None/空）时 acc=[v]，否则 list(accepted) 并剔除 strip 后为空的项，v 不在 acc 时 insert(0, v)；declared_by 假值回落 "designer"，declared_at=float(now if now is not None else time.time())，返回含 SCHEMA 的 dict。
 def make_declaration(version: str = None, accepted=None,
                      declared_by: str = "designer", now: float = None) -> dict:
     """构造（未封缄的）版本声明。accepted 默认只含自身版本。"""
@@ -122,6 +130,7 @@ def make_declaration(version: str = None, accepted=None,
             "declared_at": float(now if now is not None else time.time())}
 
 
+# 生效条件：d=decl if decl is not None else load(theory_file(path))；d 为假时返回 theory_ok=True、auto=True、version=PROTOCOL_VERSION 的状态；d.get("schema")!=SCHEMA、hmac.compare_digest(str(d.get("declaration_hash") or ""), declaration_hash(_payload(d))) 不通过、v=d.get("theory_version") 为假、或 v 不在 acc=[str(x) for x in (d.get("accepted_versions") or [])] 时各自返回同一个 base 且 theory_ok=False，其余情况 base 更新为 theory_ok=True、reason="ok"。
 def check(path: str = None, decl: dict = None) -> dict:
     """校验版本声明 → 状态字典（永不抛异常，供启动路径安全调用）。
 
@@ -164,6 +173,7 @@ def check(path: str = None, decl: dict = None) -> dict:
     return base
 
 
+# 生效条件：p=theory_file(path)，仅当 load(p) 为 None 时尝试 declare(PROTOCOL_VERSION, actor="system:autoinit", path=p, append_audit=False) 并吞掉 TheoryError/OSError，最终返回 check(p)。
 def ensure(path: str = None) -> dict:
     """启动路径：无声明则落盘默认声明（声明常态化），再返回校验状态。
 
@@ -179,6 +189,7 @@ def ensure(path: str = None) -> dict:
     return check(p)
 
 
+# 生效条件：version=None/空串时在 make_declaration 内回落 PROTOCOL_VERSION（仅回落结果 strip 后仍为空才抛 TheoryError），seal 后若 append_audit 为真值则把 (old or {}).get("audit") 或 [] 追加一条（仅 old 为真时追加）写入 decl["audit"]，save(decl, path) 后返回 {'ok': True, 'declaration': decl, 'status': check(path)}。
 def declare(version: str = None, accepted=None, actor: str = "designer",
             path: str = None, append_audit: bool = True) -> dict:
     """写入版本声明（版本更新权的唯一物理落点）。"""
@@ -195,11 +206,13 @@ def declare(version: str = None, accepted=None, actor: str = "designer",
     return {"ok": True, "declaration": decl, "status": check(path)}
 
 
+# 生效条件：以 path 调 load、check、theory_file，返回 {"declaration": load(path), "status": check(path), "theory_file": theory_file(path)}。
 def show(path: str = None) -> dict:
     return {"declaration": load(path), "status": check(path),
             "theory_file": theory_file(path)}
 
 
+# 生效条件：返回含模块常量 SCHEMA、PROTOCOL_VERSION、list(SEALED_FIELDS)、list(ESCAPE_OPS) 及 theory_file() 与 THEORY_ENV/THEORY_FILE_ENV 的自描述 dict。
 def catalog() -> dict:
     """版本层自描述（供 whoami / service_info 暴露）。"""
     return {"schema": SCHEMA, "theory_file": theory_file(),
@@ -213,10 +226,12 @@ def catalog() -> dict:
 # CLI
 # --------------------------------------------------------------------------
 
+# 生效条件：把 json.dumps(obj, ensure_ascii=False, indent=1)+"\n" 写入 sys.stdout，无返回值。
 def _print(obj):
     sys.stdout.write(json.dumps(obj, ensure_ascii=False, indent=1) + "\n")
 
 
+# 生效条件：argv 交给 ap.parse_args（argv 为 None 时 argparse 读 sys.argv），子解析器 required=True 缺 cmd 时由 argparse 报错退出；a.cmd 为 declare/check/ensure/show/catalog 之一且未抛 TheoryError 时打印并返回 0，抛出 TheoryError 时写 stderr 返回 2。
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.theory",
@@ -256,4 +271,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())