@furongjun1999/dsh-memory 0.6.0 → 0.7.0

package/md_cg/test_ccg_form_parity.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""CCG 六要素「形态口径一致性」验收（2026-09-28）。
+
+运行：python -m md_cg.test_ccg_form_parity
+
+为什么需要这一套（本套的由来，是一个真实的口径分叉）：
+六要素标题存在两种书写形态——带冒号 `# 生效条件：<值>` 与不带冒号
+`# 生效条件` 后换行接值。写入闸门 `data/policy.json` 的必需正则
+`(?m)^#\\s*生效条件` **不要求冒号**，而检索面判据 `nodefile.ccg_completeness`
+原先**要求冒号**才计入「已声明」。二者对同一条正文给出相反结论：归档过闸
+（ACCEPT）后到检索路由被判 BLINDSPOT「CCG 要素不全」——归档看着写成了，
+检索面却当它没声明。存量实测 6905 件含六要素节点中 88 件处于该状态。
+
+判据收敛在**单点** `nodefile.ccg_mark_present` / `nodefile.ccg_field_value`
+（冒号可有可无），`mdcos._ccg_field`、`ccgc._has_ccg_line`、
+`consolidate._has_ccg_line`、`tasks._field_line` 一律委托该单点。
+
+本套的六组断言：
+ ① 两形态都判齐（形态不改变「齐不齐」）
+ ② 缺要素仍判不全（放宽的是标点，不是要求——判别力自证，两种形态各测）
+ ③ 写入闸门与检索面**结论一致**（读真源 data/policy.json 复算，直接钉住分叉）
+ ④ 取值面同源：无冒号的「值」= 标题后首个非空非标题行
+ ⑤ 四个副本函数与单点结论一致（防未来再长出第五、第六套口径）
+ ⑥ 写读闭环：无冒号节点经 upsert 后取得到新值（不出现「写进去读不出」）
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import re
+import sys
+
+from . import ccgc, consolidate, nodefile, tasks
+from .mdcos import _ccg_field
+
+PASS = FAIL = 0
+FAILS = []
+
+
+def ok(cond, label):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print("  [PASS] %s" % label)
+    else:
+        FAIL += 1
+        FAILS.append(label)
+        print("  [FAIL] %s" % label)
+
+
+MARKS = ("功能名", "生效条件", "子功能", "执行", "验证方式", "不适用条件")
+
+# ① 带冒号形态（既有惯例形态）
+COLON = "".join("# %s：值_%s\n" % (m, m) for m in MARKS)
+# ① 不带冒号形态（policy 正则接受，标题行 + 换行接值）
+NONCOLON = "".join("# %s\n值_%s\n" % (m, m) for m in MARKS)
+# ① 混形态（一半带冒号一半不带）
+MIXED = "".join(("# %s：值_%s\n" if i % 2 == 0 else "# %s\n值_%s\n") % (m, m)
+                for i, m in enumerate(MARKS))
+
+
+def _drop(body: str, mark: str) -> str:
+    """删掉某要素的标题行（连带其值行）——用于②的判别力自证。"""
+    out = []
+    skip_next = False
+    for ln in body.splitlines(True):
+        if skip_next:
+            skip_next = False
+            continue
+        if re.match(r"^#\s*%s\s*[:：]?\s*$" % re.escape(mark), ln.rstrip("\n")):
+            skip_next = True
+            continue
+        if ln.startswith("# %s：" % mark) or ln.startswith("# %s:" % mark):
+            continue
+        out.append(ln)
+    return "".join(out)
+
+
+def _policy_required() -> list:
+    """读**真源**策略文件的必需正则（相对本模块定位，不依赖 cwd）。"""
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    path = os.path.join(root, "data", "policy.json")
+    with io.open(path, encoding="utf-8") as fh:
+        return [re.compile(p) for p in json.load(fh)["required"]]
+
+
+def main() -> int:
+    print("== ① 两形态都判齐 ==")
+    for name, body in (("带冒号", COLON), ("无冒号", NONCOLON), ("混形态", MIXED)):
+        comp = nodefile.ccg_completeness(body)
+        ok(comp["complete"] and sorted(comp["required_present"]) == sorted(MARKS),
+           "①%s：六要素判齐（present=%d/%d）" % (name, len(comp["required_present"]), len(MARKS)))
+        ok(abs(comp["ratio"] - 1.0) < 1e-9, "①%s：ratio=1.0（%s）" % (name, comp["ratio"]))
+
+    print("== ② 缺要素仍判不全（放宽的是标点，不是要求）==")
+    for name, body in (("带冒号", COLON), ("无冒号", NONCOLON)):
+        for mark in MARKS:
+            broken = _drop(body, mark)
+            comp = nodefile.ccg_completeness(broken)
+            ok(not comp["complete"] and mark not in comp["required_present"],
+               "②%s 缺「%s」→ 判不全" % (name, mark))
+    ok(not nodefile.ccg_completeness("")["complete"], "②空正文 → 判不全")
+    ok(not nodefile.ccg_completeness("# 生效条件\n只要这一条\n")["complete"],
+       "②只声明一条 → 判不全（不冒充齐全）")
+
+    print("== ③ 写入闸门与检索面结论一致（读真源 policy 复算）==")
+    pats = _policy_required()
+    for name, body in (("带冒号", COLON), ("无冒号", NONCOLON), ("混形态", MIXED),
+                       ("空正文", ""), ("只一条", "# 生效条件：x\n")):
+        gate = all(p.search(body) for p in pats)
+        retr = nodefile.ccg_completeness(body)["complete"]
+        ok(gate == retr, "③%s：闸门=%s 检索面=%s（必须相等）" % (name, gate, retr))
+    for mark in MARKS:
+        for name, body in (("带冒号", COLON), ("无冒号", NONCOLON)):
+            broken = _drop(body, mark)
+            gate = all(p.search(broken) for p in pats)
+            retr = nodefile.ccg_completeness(broken)["complete"]
+            ok(gate == retr and not retr,
+               "③%s 缺「%s」：两侧同判不全" % (name, mark))
+    # 边界形态：二级标题 / 缩进标题 / 无空格 —— 两侧必须同判（宽松方向也要一致）。
+    # 注意按**该要素自身**的那条必需正则比对（拿「全六条」的结论比「单条」判据
+    # 是错的口径——空正文与二级标题会因两侧同假而蒙对，暴露不出真差异）。
+    for name, line in (("二级标题", "## 生效条件：x\n"),
+                       ("缩进标题", "  # 生效条件：x\n"),
+                       ("无空格", "#生效条件：x\n"),
+                       ("制表符", "#\t生效条件：x\n")):
+        pat = next(p for p in pats if "生效条件" in p.pattern)
+        gate = bool(pat.search(line))
+        present = nodefile.ccg_mark_present(line, "生效条件")
+        ok(gate == present,
+           "③%s（%r）：闸门=%s 判据=%s（必须相等）" % (name, line.strip(), gate, present))
+    # 全形态 × 全要素的逐条一致性（比「整体 complete」更细，能定位到具体要素）
+    for name, body in (("带冒号", COLON), ("无冒号", NONCOLON), ("混形态", MIXED)):
+        for mark in MARKS:
+            pat = next(p for p in pats if mark in p.pattern)
+            ok(bool(pat.search(body)) == nodefile.ccg_mark_present(body, mark),
+               "③%s 逐要素一致：「%s」" % (name, mark))
+
+    print("== ④ 取值面：无冒号的值 = 标题后首个非空非标题行 ==")
+    ok(nodefile.ccg_field_value(COLON, "功能名") == "值_功能名",
+       "④带冒号：取行内值")
+    ok(nodefile.ccg_field_value(NONCOLON, "功能名") == "值_功能名",
+       "④无冒号：取下一行值")
+    ok(nodefile.ccg_field_value("# 执行\n\n真实值行\n后文\n", "执行") == "真实值行",
+       "④无冒号：跳过空行取首个非空行")
+    ok(nodefile.ccg_field_value("# 功能名\n# 生效条件：x\n", "功能名") == "",
+       "④无冒号且下一行又是标题：取空串而非吞掉下一个要素")
+    ok(nodefile.ccg_field_value(COLON, "不存在的字段") is None,
+       "④无该字段行 → None")
+
+    print("== ⑤ 四个副本与单点结论一致（防再长出口径分叉）==")
+    for name, body in (("带冒号", COLON), ("无冒号", NONCOLON)):
+        for mark in ("功能名", "生效条件", "执行"):
+            single = nodefile.ccg_mark_present(body, mark)
+            ok(ccgc._has_ccg_line(body, mark) == single,
+               "⑤ccgc._has_ccg_line(%s,%s) 与单点一致" % (name, mark))
+            ok(consolidate._has_ccg_line(body, mark) == single,
+               "⑤consolidate._has_ccg_line(%s,%s) 与单点一致" % (name, mark))
+            ok(bool(_ccg_field(body, mark)) == single or not single,
+               "⑤mdcos._ccg_field(%s,%s) 与单点一致" % (name, mark))
+            ok(tasks._field_line(body, mark) == (nodefile.ccg_field_value(body, mark) or ""),
+               "⑤tasks._field_line(%s,%s) 与单点同值" % (name, mark))
+
+    print("== ⑥ 写读闭环：无冒号节点 upsert 后取得到新值 ==")
+    for enc, upsert in (("ccgc", ccgc._upsert_ccg_line), ("consolidate", consolidate._upsert_ccg_line)):
+        after = upsert(NONCOLON, "生效条件", "新条件")
+        ok(_ccg_field(after, "生效条件") == "新条件",
+           "⑥%s：无冒号节点 upsert 后 mdcos 读出「新条件」" % enc)
+        ok(nodefile.ccg_field_value(after, "生效条件") == "新条件",
+           "⑥%s：同一次写单点读出「新条件」" % enc)
+        ok(nodefile.ccg_completeness(after)["complete"],
+           "⑥%s：upsert 后仍判齐" % enc)
+        try:
+            upsert(NONCOLON, "生效条件", "多行\n注入")
+            ok(False, "⑥%s：值含换行应被拒（N208）" % enc)
+        except ValueError:
+            ok(True, "⑥%s：值含换行被拒（N208 fail-closed）" % enc)
+
+    print()
+    print("ccg_form_parity: PASS=%d FAIL=%d" % (PASS, FAIL))
+    if FAILS:
+        print("FAILS: " + "; ".join(FAILS))
+    return 1 if FAIL else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/test_ccgc.py

@@ -23,7 +23,7 @@ import tempfile
 import threading
 import time
 
-from . import audit, backfill, ccgc, nodefile, units
+from . import audit, backfill, ccgc, nodefile, tokens, units
 from .mdcos import MdCGOS
 
 PASS = FAIL = 0
@@ -126,6 +126,13 @@ def _import_mcp():
 def main():
     global PASS, FAIL
     tmp = tempfile.mkdtemp(prefix="mdcg_ccgc_")
+    # N176 契约：落库准入须令牌验证方——本测试自备哑令牌环境（临时 MDCG_TOKEN_FILE）
+    _old_tf = os.environ.get(tokens.TOKEN_FILE_ENV)
+    os.environ[tokens.TOKEN_FILE_ENV] = os.path.join(tmp, "tokens.json")
+    tk_reviewer = tokens.issue("designer", actor="designer",
+                               path=os.environ[tokens.TOKEN_FILE_ENV])["token"]
+    tk_reviewer_ext = tokens.issue("verify", actor="external-reviewer",
+                                   path=os.environ[tokens.TOKEN_FILE_ENV])["token"]
     try:
         root = os.path.join(tmp, "root")
         os.makedirs(root, exist_ok=True)
@@ -192,8 +199,11 @@ def main():
         a_defer = ccgc.attest("tgt", ccgc.DEFER, "designer", "agent:a1", cg=cg)
         ok((not a_defer.ok) and "E042" in a_defer.error, "V7b DEFER 不构成签章")
         a_ok = ccgc.attest("tgt", ccgc.ACCEPT, "designer", "agent:a1",
-                           evidence="设计者核对原文一致", cg=cg)
+                           evidence="设计者核对原文一致", cg=cg,
+                           verifier_token=tk_reviewer)
         ok(a_ok.ok and bool(a_ok.token), "V7c 编外验证方 ACCEPT → 有效签章")
+        ok(a_ok.verifier_identity == "token", "V7d 令牌验证方 identity=token"
+           "（N176：self-reported 不再构成落库准入）")
 
         # ---------- V8 无章不写 ----------
         l0 = ccgc.link(r, None, cg=cg, apply=True)
@@ -283,7 +293,7 @@ def main():
         lz = ccgc.link_pending(cg, "tgt", apply=True, actor="agent:a1")
         ok(lz.ok and lz.written == 6, "V16f 读回原件+签章 → 落库成功")
         ok(not os.path.isfile(sv["path"]), "V16g 落库成功即清 pending（暂存非存档）")
-        ok(not any(ccgc.PENDING_DIR in str(k) for k in (cg.index.get("nodes") or {})),
+        ok(not any(ccgc.PENDING_DIR in str(k) for k in (list(cg.index.get("nodes") or {}))),
            "V16h pending 不进索引（冷区对检索隐身）")
 
         # ---------- V17 闸门：只认编外裁决，绝不假装通过 ----------
@@ -396,6 +406,17 @@ def main():
             ok(c5["state"] == units.HIVE and c5["verdict"] == "ACCEPT" and c5["passed"] is True,
                "V20g review 取回裁决：ok/verdict/passed 三者分离")
             ok(bool((c5.get("attest") or {}).get("ok")), "V20h 拿到裁决即自动签章")
+            c5b = mcp._ccg_call(cg, {"ccg": {"action": "link", "node_id": "tgt",
+                                             "apply": True}})
+            ok((not c5b["ok"]) and "E052" in str((c5b.get("link") or {}).get("errors")),
+               "V20n 无令牌自报签章 → link 拒绝（N176 E052，不落 knowledge 层）")
+            c5c = mcp._ccg_call(cg, {"ccg": {"action": "attest", "node_id": "tgt",
+                                             "verdict": "ACCEPT",
+                                             "verifier": "external-reviewer",
+                                             "verifier_token": tk_reviewer_ext,
+                                             "evidence": "令牌验证方复核"}})
+            ok(c5c["ok"] and (c5c.get("attest") or {}).get("verifier_identity") == "token",
+               "V20o 令牌验证方重签章 → identity=token（挂回 pending 待落库）")
             c7 = mcp._ccg_call(cg, {"ccg": {"action": "review", "node_id": "tgt",
                                             "jobs": jobs, "blocking": False}})
             ok(c7["state"] == units.HIVE and c7["verdict"] is None and c7["passed"] is False,
@@ -421,6 +442,10 @@ def main():
                 os.environ[units.ENV_EXE] = _old_exe
 
     finally:
+        if _old_tf is None:
+            os.environ.pop(tokens.TOKEN_FILE_ENV, None)
+        else:
+            os.environ[tokens.TOKEN_FILE_ENV] = _old_tf
         print()
         print("ccgc: PASS=%d FAIL=%d" % (PASS, FAIL))
         if FAILS:

package/md_cg/test_en_pipeline.py

@@ -13,13 +13,14 @@
   MDCG_EN_ATOMS=1 显式开启；纯中文 query 零触发；
   mdcos 四路 RRF 的 lexical 路同源复用 expand_query_terms，自动受益。
 
-⚠ 与**统一归一层**的关系（2026-09-24 澄清，曾造成本件红灯）：
-  `semantic/unify.py::unify_query` 是**另一个、且默认开启**的开关
-  （MDCG_UNIFY_QUERY，默认 "1"，2026-09-23 口径转正）：检索入口把任意语言的
-  query 先归一成标准中文原子序列——英文 query 因此在**词法路**上就能命中中文
-  节点（与 en_zh_terms 默认关并不矛盾：一个在 query 侧归一，一个在召回词扩展侧）。
-  故本件的「跨语词面零交集 ⇒ 召回必须归零」只在**两个开关都关**时成立；
-  默认态断言相应改为「命中」，两个态都钉住（改口径必红）。
+⚠ 与**统一归一层**的关系（2026-09-24 澄清，曾造成本件红灯；2026-09-30 缺省翻关）：
+  `semantic/unify.py::unify_query` 是**另一个**开关，缺省**关**（MDCG_UNIFY_QUERY，
+  2026-09-30 使用者裁定由「默认 "1"」翻为「未设即关、显式 "1" 才开」）：显式开启时
+  检索入口把任意语言的 query 先归一成标准中文原子序列——英文 query 因此在**词法路**
+  上就能命中中文节点（与 en_zh_terms 默认关并不矛盾：一个在 query 侧归一，一个在召回
+  词扩展侧）。故「跨语词面零交集 ⇒ 召回必须归零」在**缺省态**（两个开关都不设）与
+  「两个开关都关」两种形态下都成立；命中只在显式 `MDCG_UNIFY_QUERY=1` 时断言。
+  三态都钉住（改口径必红）。
 
 运行：python -m md_cg.test_en_pipeline
 """
@@ -143,14 +144,22 @@ try:
     ids = [r[0].get("id") for r in res]
     del os.environ["MDCG_EN_ATOMS"]
     ok(len(res) >= 1 and ids[0] == "n_beef", "开启：英文 query top1 召回中文牛肉节点 %s" % ids)
-    # 默认（两个开关都不设）：**统一归一层**（MDCG_UNIFY_QUERY 默认 "1"）把英文
-    # query 归一成中文原子序列 → 词法路直达中文节点。这是 2026-09-23 使用者拍板的
-    # 口径转正（semantic/unify.py），与旧的「跨语词面零交集」契约相反：
-    # 旧断言已按新口径改写——默认态断言「命中」，unify=0 才断言「归零」。
+    # 2026-09-30 使用者裁定：统一归一层缺省由开翻为关（semantic/unify.py）。
+    # 故「两个开关都不设」= **两个都关** → 词面零交集，召回必须归零；
+    # 命中只在**显式** MDCG_UNIFY_QUERY=1 时才成立（英文对照路要用）。
+    # （旧断言「缺省态命中」对应的是 2026-09-23 的「默认开」口径，已随缺省翻转改写。）
     res_u, _mu = cg.search("I ate beef yesterday", judge=False)
     ids_u = [r[0].get("id") for r in res_u]
-    ok(len(res_u) >= 1 and ids_u[0] == "n_beef",
-       "默认（unify 开）：英文 query 经统一归一后 top1 命中中文节点 %s" % ids_u)
+    ok(not res_u or all(r[1] <= 0 for r in res_u),
+       "缺省（unify 缺省关 + EN_ATOMS 关）：词面零重叠召回归零 %s" % ids_u)
+    os.environ["MDCG_UNIFY_QUERY"] = "1"
+    try:
+        res1, _m1 = cg.search("I ate beef yesterday", judge=False)
+        ids1 = [r[0].get("id") for r in res1]
+    finally:
+        os.environ.pop("MDCG_UNIFY_QUERY", None)
+    ok(len(res1) >= 1 and ids1[0] == "n_beef",
+       "显式 unify=1：英文 query 经统一归一后 top1 命中中文节点 %s" % ids1)
     os.environ["MDCG_UNIFY_QUERY"] = "0"
     try:
         res0, _m0 = cg.search("I ate beef yesterday", judge=False)   # 关归一+EN_ATOMS 关

package/md_cg/test_generation_guard.py

@@ -0,0 +1,352 @@
+# -*- coding: utf-8 -*-
+"""守卫：代校验单点（`md_cg/generation.py`）与它的两处接线
+
+用法（仓根直跑，退出码 0 ＝ 全绿）：
+
+    python -X utf8 -m md_cg.test_generation_guard
+
+守的是「长驻 MCP 进程跨代混合快照」这条已定因缺陷的处置（使用者裁定方案 b：
+把「升级后须重启长驻 MCP 进程」写成运维前提 + 加一道代校验）。五项：
+
+  一 全绿：`verify_delegations()` 对**当前树**（逐字节临时副本）必须通过，
+     并打印扫到的委托项数与目标模块数。
+  二 定点变异自证：在临时副本里把 `md_cg/mdcg.py` 的 `mint_auto_id` 定义改名，
+     `verify_delegations()` 必须抛 `GenerationError` 且消息**逐字点名**目标子模块
+     与名字（证明它不是「恒绿的摆设」）。
+  三 判别力自证：临时副本里改一个源文件后 `is_stale()` 必须 True，恢复后必须 False
+     （证明指纹认内容不认 mtime）。
+  四 AST 断言：`mcp_server.py` 里 `generation.verify_delegations(` 的调用**不在
+     模块顶层**——只在函数体内（顶层调用会与函数内延迟导入的避环设计冲突）。
+  五 键集对拍：对临时 root 上的 `cg(op=info)` 真调一次 MCP 服务，响应必须含
+     code_generation / disk_generation / stale_on_disk / restart_required / hint
+     五个新键，且**既有键集合**与改动前读码钉住的 18 键逐字一致。
+
+安全边界：一切在 `tempfile.mkdtemp()` 临时目录内进行（md_cg 树是复制出来的副本），
+绝不写工作区、绝不写任何在役记忆库、绝不起用真 root 的常驻服务、绝不重启/终止
+任何在跑的进程——本守卫只**新起**短命子进程（argv 列表 + shell=False + UTF-8）。
+"""
+from __future__ import annotations
+
+import ast
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if REPO not in sys.path:                # 保证 `import md_cg.*` 能定位到当前树的包
+    sys.path.insert(0, REPO)
+
+# 改动前读码钉住的 cg(op=info) 既有键集合（在临时 root 上实跑一次服务所读，
+# 2026-09-30 接线前）：本守卫要证明这 18 键一字未动。
+PINNED_INFO_KEYS = frozenset({
+    "action_source", "audit_kinds", "buckets", "ccg_by_layer", "ccg_contract",
+    "external_verifiers", "links", "neg_memory_counts", "ok", "os", "reason",
+    "security", "surface", "theory", "tools", "total_nodes", "whoami",
+    "write_policy",
+})
+
+NEW_INFO_KEYS = ("code_generation", "disk_generation", "stale_on_disk",
+                 "restart_required", "hint")
+
+_FAILED = []
+
+
+def _ok(tag, text):
+    print("[PASS] %s —— %s" % (tag, text))
+
+
+def _fail(tag, text):
+    _FAILED.append(tag)
+    print("[FAIL] %s —— %s" % (tag, text))
+
+
+def _child_env(root):
+    """子进程环境：显式 UTF-8 + 全临时 root（绝不碰在役库）。"""
+    env = dict(os.environ)
+    env["PYTHONUTF8"] = "1"
+    env["PYTHONIOENCODING"] = "utf-8"
+    env["PYTHONPATH"] = root
+    env["MDCG_ROOT"] = os.path.join(root, "_guard_mem")
+    env["MDCG_AUX_ROOT"] = os.path.join(root, "_guard_aux")
+    env["DSH_HOME"] = root
+    env.pop("MDCG_TOKEN", None)
+    return env
+
+
+def _run(args, cwd, env, timeout=600):
+    """argv 列表 + shell=False + capture_output 的显式 UTF-8 调用（第 15 条）。"""
+    return subprocess.run(args, cwd=cwd, env=env, capture_output=True, text=True,
+                          encoding="utf-8", errors="replace", shell=False,
+                          timeout=timeout)
+
+
+def _copy_tree(dst_root):
+    """把当前树的 md_cg 复制成临时副本，返回副本包目录。
+
+    连仓根一级模块（`utf8_boot.py`——md_cg 各入口在文件 I/O 前用它自保证 UTF-8）
+    一并复制：否则副本里 `import md_cg.mcp_server` 会因缺 utf8_boot 而失败，把
+    指向它的延迟导入统统降级成「非致命不可用」，副本就不再忠实于当前树。
+    """
+    shutil.copytree(os.path.join(REPO, "md_cg"),
+                    os.path.join(dst_root, "md_cg"),
+                    ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+    for name in os.listdir(REPO):
+        if name.endswith(".py"):
+            shutil.copy2(os.path.join(REPO, name), os.path.join(dst_root, name))
+    return os.path.join(dst_root, "md_cg")
+
+
+_VERIFY_SNIPPET = (
+    "import json\n"
+    "from md_cg import generation as g\n"
+    "r = g.verify_delegations()\n"
+    "print(json.dumps({'ok': r['ok'], 'delegations': r['delegations'],\n"
+    "                  'target_modules': r['target_modules'],\n"
+    "                  'resolved': r['resolved'],\n"
+    "                  'scanned_files': r['scanned_files'],\n"
+    "                  'unavailable': len(r['unavailable']),\n"
+    "                  'generation': g.STARTUP_FINGERPRINT[:12]}, ensure_ascii=False))\n"
+)
+
+_MUTATION_SNIPPET = (
+    "import json, sys\n"
+    "from md_cg import generation as g\n"
+    "try:\n"
+    "    g.verify_delegations()\n"
+    "except g.GenerationError as e:\n"
+    "    print(json.dumps({'raised': 'GenerationError', 'msg': str(e)},\n"
+    "                     ensure_ascii=False))\n"
+    "except Exception as e:\n"
+    "    print(json.dumps({'raised': type(e).__name__, 'msg': str(e)},\n"
+    "                     ensure_ascii=False))\n"
+    "else:\n"
+    "    print(json.dumps({'raised': None}, ensure_ascii=False))\n"
+)
+
+_STALE_SNIPPET = (
+    "import io, json, os\n"
+    "from md_cg import generation as g\n"
+    "target = os.path.join(os.path.dirname(g.__file__), 'fsutil.py')\n"
+    "raw = io.open(target, encoding='utf-8').read()\n"
+    "clean = g.is_stale()\n"
+    "io.open(target, 'w', encoding='utf-8', newline='').write(raw + '\\n# 守卫临时改动\\n')\n"
+    "modified = g.is_stale()\n"
+    "io.open(target, 'w', encoding='utf-8', newline='').write(raw)\n"
+    "restored = g.is_stale()\n"
+    "print(json.dumps({'clean': clean, 'modified': modified,\n"
+    "                  'restored': restored, 'fp': g.fingerprint()[:12]},\n"
+    "                 ensure_ascii=False))\n"
+)
+
+
+# 一 + 二 + 三：临时副本上的三项自证
+def check_verify_and_mutation(tmp):
+    print("\n== 一 全绿（当前树的临时副本）+ 二 定点变异 + 三 判别力 ==")
+    _copy_tree(tmp)
+    env = _child_env(tmp)
+
+    real = _run([sys.executable, "-X", "utf8", "-c", _VERIFY_SNIPPET], tmp, env)
+    if real.returncode != 0:
+        _fail("一·全绿", "子进程退出码 %s：%s" % (real.returncode,
+                                                (real.stderr or "")[-500:]))
+        return
+    data = json.loads(real.stdout.strip().splitlines()[-1])
+    print("     扫描文件 %d 个 / 委托项 %d 项 / 目标模块 %d 个 / 已解析 %d 项 / "
+          "可选缺失 %d 项 / 副本代 %s"
+          % (data["scanned_files"], data["delegations"], data["target_modules"],
+             data["resolved"], data["unavailable"], data["generation"]))
+    if not data["ok"]:
+        _fail("一·全绿", "verify_delegations() 在副本上未通过")
+        return
+
+    # 副本与当前树同形自证：现树的指纹（本进程内只读计算）必须等于副本自报的代
+    from md_cg import generation as _real_gen           # 只读：只算哈希
+    real_fp = _real_gen.fingerprint()[:12]
+    if real_fp != data["generation"]:
+        _fail("一·全绿", "副本代 %s 与当前树代 %s 不同——副本不忠实，结论不成立"
+              % (data["generation"], real_fp))
+        return
+    _ok("一·全绿", "verify_delegations() 通过，且副本与当前树同代 %s" % real_fp)
+
+    # 二：定点变异——改名 mdcg.py 里的 mint_auto_id 定义
+    mdcg_path = os.path.join(tmp, "md_cg", "mdcg.py")
+    with open(mdcg_path, encoding="utf-8") as fh:
+        original = fh.read()
+    mutated = original.replace("def mint_auto_id(", "def mint_auto_id_renamed(", 1)
+    if mutated == original:
+        _fail("二·定点变异", "定位不到 def mint_auto_id( ——变异未生效，本条不成立")
+        return
+    with open(mdcg_path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(mutated)
+    try:
+        mut = _run([sys.executable, "-X", "utf8", "-c", _MUTATION_SNIPPET], tmp, env)
+    finally:
+        with open(mdcg_path, "w", encoding="utf-8", newline="") as fh:
+            fh.write(original)
+    if mut.returncode != 0:
+        _fail("二·定点变异", "子进程退出码 %s：%s" % (mut.returncode,
+                                                    (mut.stderr or "")[-500:]))
+        return
+    got = json.loads(mut.stdout.strip().splitlines()[-1])
+    if got.get("raised") != "GenerationError":
+        _fail("二·定点变异", "期望 GenerationError，实得 %r" % (got.get("raised"),))
+        return
+    msg = got.get("msg") or ""
+    if "md_cg.mdcg" not in msg or "mint_auto_id" not in msg:
+        _fail("二·定点变异", "异常消息未逐字点名子模块/名字：%r" % msg[:400])
+        return
+    print("     异常消息首行：%s" % msg.splitlines()[0])
+    _ok("二·定点变异", "去掉 mint_auto_id 定义后抛出 GenerationError，消息点名 "
+                       "md_cg.mdcg + mint_auto_id")
+
+    # 三：判别力——同一进程内改盘 → is_stale True；恢复 → False
+    st = _run([sys.executable, "-X", "utf8", "-c", _STALE_SNIPPET], tmp, env)
+    if st.returncode != 0:
+        _fail("三·判别力", "子进程退出码 %s：%s" % (st.returncode,
+                                                  (st.stderr or "")[-500:]))
+        return
+    s = json.loads(st.stdout.strip().splitlines()[-1])
+    if (s["clean"], s["modified"], s["restored"]) != (False, True, False):
+        _fail("三·判别力", "期望 (False, True, False)，实得 %r"
+              % ((s["clean"], s["modified"], s["restored"]),))
+        return
+    if s["fp"] != real_fp:
+        _fail("三·判别力", "恢复后指纹 %s ≠ 原代 %s（恢复不彻底）" % (s["fp"], real_fp))
+        return
+    _ok("三·判别力", "改一个源文件后 is_stale()=True，恢复后 False（代 %s 复原）"
+        % s["fp"])
+
+
+# 四：AST 断言——verify_delegations 的调用不在 mcp_server.py 的模块顶层
+def check_call_site_not_toplevel():
+    print("\n== 四 AST 断言：调用点不在模块顶层 ==")
+    path = os.path.join(REPO, "md_cg", "mcp_server.py")
+    with open(path, encoding="utf-8") as fh:
+        tree = ast.parse(fh.read(), path)
+
+    found = []          # (lineno, depth, 是否在 main 内)
+
+    class _V(ast.NodeVisitor):
+        def __init__(self):
+            self.depth = 0
+            self.func = []
+
+        def _fn(self, node):
+            self.depth += 1
+            self.func.append(node.name)
+            self.generic_visit(node)
+            self.func.pop()
+            self.depth -= 1
+
+        visit_FunctionDef = _fn
+        visit_AsyncFunctionDef = _fn
+
+        def visit_Call(self, node):
+            f = node.func
+            if isinstance(f, ast.Attribute) and f.attr == "verify_delegations":
+                found.append((node.lineno, self.depth,
+                              self.func[-1] if self.func else None))
+            self.generic_visit(node)
+
+    _V().visit(tree)
+    if not found:
+        _fail("四·调用点", "mcp_server.py 里找不到 *.verify_delegations(...) 调用"
+                           "——接线缺失")
+        return
+    top = [f for f in found if f[1] == 0]
+    if top:
+        _fail("四·调用点", "存在模块顶层调用（第 %s 行）——会与函数内延迟导入的"
+                           "避环设计冲突" % ", ".join(str(t[0]) for t in top))
+        return
+    _ok("四·调用点", "%d 处调用全在函数体内：%s"
+        % (len(found), ", ".join("%s:%d" % (f[2], f[0]) for f in found)))
+
+
+# 五：键集对拍——对临时 root 上真起的 MCP 服务调 cg(op=info)
+def check_info_keys(tmp):
+    print("\n== 五 键集对拍：cg(op=info) 真调（临时 root） ==")
+    env = _child_env(tmp)
+    # 本条要验的是**工作区里这套接线**（不是副本），故包来源显式钉到当前树：
+    # 记忆 root / aux / DSH_HOME 仍是临时目录（隔离），只有代码取自当前树。
+    env["PYTHONPATH"] = REPO
+    lines = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+         "params": {"protocolVersion": "2024-11-05", "capabilities": {},
+                    "clientInfo": {"name": "generation-guard", "version": "0"}}},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/call",
+         "params": {"name": "cg", "arguments": {"op": "info"}}},
+        {"jsonrpc": "2.0", "id": 3, "method": "shutdown", "params": {}},
+    ]
+    payload = "\n".join(json.dumps(x, ensure_ascii=False) for x in lines) + "\n"
+    r = subprocess.run([sys.executable, "-X", "utf8", "-m", "md_cg.mcp_server"],
+                       cwd=REPO, env=env, input=payload, capture_output=True,
+                       text=True, encoding="utf-8", errors="replace",
+                       shell=False, timeout=600)
+    if r.returncode != 0:
+        _fail("五·键集", "mcp_server 退出码 %s（代校验接线可能把启动打死了）：%s"
+              % (r.returncode, (r.stderr or "")[-700:]))
+        return
+    info = None
+    for line in r.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            continue
+        if obj.get("id") == 2 and "result" in obj:
+            info = json.loads(obj["result"]["content"][0]["text"])
+    if info is None:
+        _fail("五·键集", "没取到 cg(op=info) 响应：stdout=%s" % (r.stdout or "")[:400])
+        return
+    keys = set(info)
+    missing = [k for k in NEW_INFO_KEYS if k not in keys]
+    if missing:
+        _fail("五·键集", "缺新键：%s" % missing)
+        return
+    extra = sorted(keys - PINNED_INFO_KEYS - set(NEW_INFO_KEYS))
+    lost = sorted(PINNED_INFO_KEYS - keys)
+    if extra or lost:
+        _fail("五·键集", "既有键集被改动：多出 %s / 丢失 %s" % (extra, lost))
+        return
+    if info["code_generation"] != info["disk_generation"]:
+        _fail("五·键集", "刚起的进程自报跨代：code=%s disk=%s"
+              % (info["code_generation"], info["disk_generation"]))
+        return
+    if info["stale_on_disk"] is not False or info["restart_required"] is not False:
+        _fail("五·键集", "刚起的进程 stale_on_disk/restart_required 应为 False，"
+                         "实得 %r/%r" % (info["stale_on_disk"],
+                                         info["restart_required"]))
+        return
+    if "重启常驻 MCP 进程" not in (info["hint"] or ""):
+        _fail("五·键集", "hint 未含处置指引：%r" % (info["hint"],))
+        return
+    _ok("五·键集", "五新键齐备、既有 18 键一字未动；代 %s（code==disk，"
+                   "restart_required=False）"
+        % info["code_generation"])
+
+
+def main():
+    print("代校验守卫（generation guard）——临时目录内进行，不碰工作区与在役库")
+    tmp = tempfile.mkdtemp(prefix="mdcg_gen_guard_")
+    print("临时 root：%s" % tmp)
+    try:
+        check_verify_and_mutation(tmp)
+        check_call_site_not_toplevel()
+        check_info_keys(tmp)
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    print("")
+    if _FAILED:
+        print("结果：%d 项红 —— %s" % (len(_FAILED), "、".join(_FAILED)))
+        return 1
+    print("结果：全绿（0 红）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())