@furongjun1999/dsh-memory 0.4.8 → 0.4.9

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

@@ -129,8 +129,12 @@ def _run(tmp):
                                  "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"]
-           == ["audit", "consistency", "gated"],
+           == ["linkref", "deps", "audit", "consistency", "gated"],
+           repr(singleton.names()))
+    _check("单例默认after链", singleton.names()["after"]
+           == ["linkref", "trust"],
            repr(singleton.names()))
 
     # ---------- 3 链序 / 短路 / REWRITE ----------

package/md_cg/theory.py

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

package/md_cg/tokens.py

@@ -79,7 +79,15 @@ ALL_OPS = ("help", "info", "route", "read", "write", "goal", "task", "recent", "
            #        —— 对话记录→六要素候选→**编外复核**→落库；裁定 A：编译者不得自证
            #        （E041 机械拒绝 verifier == compiled_by）。复核通道优先蜂巢
            #        reflect/verify 单元，不可用则提示配置或降级 harness 端子代理。
-           "ccg")
+           # P4 新增（可验证记忆单元，2026-09-19）：
+           #   status  验证态 / 依赖 / 双时间轴 / 履历查询（只读）
+           #        —— 「它还成不成立」的读面；真源 md_cg/trust.py
+           # P4 新增（三元组反查原语，阶段二 4.2，2026-09-20）：
+           #   edges  按任意端 / 谓词 / 时间 + 排序分页聚合反查派生边（只读）
+           #        —— 「这条记忆从哪来 / 谁由它派生」的读面；真源
+           #        md_cg/provenance.py（find_edges）。**只读 op**：不含任何
+           #        写入 path，故读面角色一律放行（与 status 同档）
+           "ccg", "status", "edges")
 
 
 class TokenError(Exception):
@@ -115,7 +123,8 @@ ROLE_SPECS = OrderedDict([
         # task=结构层任务台账（工程做到哪一步/结果是什么）——记录单元本职：
         #     保存过程与结果；「不得自证」由 done 时的结果必填闸承接
         "ops_allow": ["info", "route", "read", "write", "goal", "task", "recent",
-                      "session", "ingest", "maintain", "insight", "ccg"],
+                      "session", "ingest", "maintain", "insight", "ccg", "status",
+                      "edges"],
         "delegable": False,
         "forbidden": ["self/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -128,7 +137,7 @@ ROLE_SPECS = OrderedDict([
         # maintain=反思后的前馈/模式分离候选（apply 类改写走 require_admin）
         # insight=发现差异/新路径：开窗 window + 情景重构 reconstruct + 盲区学习 learn
         "ops_allow": ["info", "route", "read", "write", "recent", "metacognition",
-                      "session", "maintain", "insight"],
+                      "session", "maintain", "insight", "status", "edges"],
         "delegable": False,
         "forbidden": ["knowledge/self/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -137,7 +146,8 @@ ROLE_SPECS = OrderedDict([
         "duty": "判断规则、执行结果和结构是否有效；只写验证证据与负记忆",
         "can_write": True, "can_admin": False, "clearance_cap": "internal",
         "layers_allow": ["rejected", "contextual"],
-        "ops_allow": ["info", "route", "read", "write", "verify", "insight"],
+        "ops_allow": ["info", "route", "read", "write", "verify", "insight",
+                      "status", "edges"],
         "delegable": False,
         "forbidden": ["knowledge/self/anchor 层（不得改被验证内容）",
                       "private/secret 密级", "裁决与删除"],
@@ -150,7 +160,7 @@ ROLE_SPECS = OrderedDict([
         # session 仅开放只读 recall；note/compact 在分发层按 can_write 拦截
         # insight 仅开放只读呈现（list/report/outlook/reconstruct）；写入被 can_write 拦截
         "ops_allow": ["info", "route", "read", "recent", "whitebox", "session",
-                      "insight"],
+                      "insight", "status", "edges"],
         "delegable": False,
         "forbidden": ["全部写入", "private/secret 密级", "管理操作"],
     }),
@@ -164,7 +174,7 @@ ROLE_SPECS = OrderedDict([
         # insight=整体结构洞察 outlook（趋势/盲区/建议）+ 条件层报告 report
         "ops_allow": ["info", "read", "write", "sustain", "scrub", "evolution",
                       "self_state", "metacognition", "link", "session",
-                      "maintain", "insight"],
+                      "maintain", "insight", "status", "edges"],
         "delegable": False,
         "forbidden": ["knowledge/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -173,7 +183,8 @@ ROLE_SPECS = OrderedDict([
         "duty": "无令牌时的降级身份：只读、最低密级",
         "can_write": False, "can_admin": False, "clearance_cap": "internal",
         "layers_allow": [],
-        "ops_allow": ["info", "route", "read", "recent", "whitebox"],
+        "ops_allow": ["info", "route", "read", "recent", "whitebox", "status",
+                      "edges"],
         "delegable": False,
         "forbidden": ["全部写入", "private/secret 密级", "管理操作"],
     }),
@@ -216,11 +227,13 @@ ORCH_OPS_ALLOW = ("route", "read", "write", "review", "recent", "consistency")
 ORCH_LAYERS_ALLOW = tuple(l for l in ALL_LAYERS if l not in CORE_LAYERS)
 
 
+# 生效条件：role 为假值（None/空串）时按 "" 处理，经 strip().lower() 得 r，r 命中 ROLE_ALIASES 键时返回别名，否则返回 r 本身。
 def normalize_role(role: str) -> str:
     r = (role or "").strip().lower()
     return ROLE_ALIASES.get(r, r)
 
 
+# 生效条件：normalize_role(role) 得 r，r 不在 ROLE_SPECS 中即抛 TokenError，否则返回 dict(ROLE_SPECS[r]) 的浅拷贝。
 def role_spec(role: str):
     r = normalize_role(role)
     if r not in ROLE_SPECS:
@@ -228,6 +241,7 @@ def role_spec(role: str):
     return dict(ROLE_SPECS[r])
 
 
+# 生效条件：无 required 形参，调用即返回含 SCHEMA、token_file()、CORE_PRIVATE_SENSITIVITIES/CORE_LAYERS/ALL_LAYERS/POSITION_ROLES/DELEGABLE_ROLES/ROLE_ALIASES/ROLE_SPECS 各自 list/dict 拷贝的字典。
 def catalog():
     """角色职责矩阵（供 whoami / service_info / 文档自描述）。"""
     return {"schema": SCHEMA, "token_file": token_file(),
@@ -243,10 +257,12 @@ def catalog():
 # 存储（仓库外，0600）
 # --------------------------------------------------------------------------
 
+# 生效条件：path 为真值时返回 path，否则回落 os.environ.get(TOKEN_FILE_ENV)（取到空串同为假值），仍为假值时返回 DEFAULT_TOKEN_FILE。
 def token_file(path: str = None) -> str:
     return path or os.environ.get(TOKEN_FILE_ENV) or DEFAULT_TOKEN_FILE
 
 
+# 生效条件：p=token_file(path) 的 os.path.exists(p) 为真且 json.load 得到 dict 时，setdefault("tokens", {}) 后返回该 dict；路径不存在、解析结果非 dict 或抛 OSError/ValueError 时返回 {"schema": SCHEMA, "tokens": {}}。
 def _load(path: str = None) -> dict:
     p = token_file(path)
     if os.path.exists(p):
@@ -261,6 +277,7 @@ def _load(path: str = None) -> dict:
     return {"schema": SCHEMA, "tokens": {}}
 
 
+# 生效条件：以 data 为内容、p=token_file(path) 为目标，先对 os.path.dirname(p) or "." 做 makedirs(exist_ok=True)，写 p+".tmp" 后 os.replace 覆盖 p，再尝试 chmod 0600（仅吞 OSError）。
 def _save(data: dict, path: str = None):
     p = token_file(path)
     os.makedirs(os.path.dirname(p) or ".", exist_ok=True)
@@ -274,14 +291,17 @@ def _save(data: dict, path: str = None):
         pass
 
 
+# 生效条件：secret 经 encode("utf-8") 后取 sha256 的 hexdigest；secret 非 str 时按其 encode 失败抛出。
 def _hash(secret: str) -> str:
     return hashlib.sha256(secret.encode("utf-8")).hexdigest()
 
 
+# 生效条件：_rank(want) <= _rank(cap) 时返回 want，否则返回 cap。
 def _clamp_level(want: str, cap: str) -> str:
     return want if _rank(want) <= _rank(cap) else cap
 
 
+# 生效条件：allow 为 None 时按 parent_allow 是否为 None 返回 None 或 list(parent_allow)；否则 parent_allow 为 None 或含 "*" 时返回 list(allow)；否则 allow 含 "*" 时返回 list(parent_allow)；否则返回 [x for x in allow if x in parent_allow]。
 def _narrow(allow, parent_allow):
     """求交：子权限只能收窄。父为 None（不限制）时取子；子为 None 时取父。"""
     if allow is None:
@@ -293,10 +313,12 @@ def _narrow(allow, parent_allow):
     return [x for x in allow if x in parent_allow]
 
 
+# 生效条件：role/token_id/secret 即使为假值也照拼，返回 f"{PREFIX}.{role}.{token_id}.{secret}"。
 def make_token(role: str, token_id: str, secret: str) -> str:
     return f"{PREFIX}.{role}.{token_id}.{secret}"
 
 
+# 生效条件：token 为假值时按 "" 处理，split(".") 后长度不为 4 或 parts[0] != PREFIX 即抛 TokenError；长度与前缀合规后 role/token_id/secret 任一为空再抛 TokenError；否则返回 (role.lower(), token_id, secret)。
 def parse_token(token: str):
     parts = (token or "").strip().split(".")
     if len(parts) != 4 or parts[0] != PREFIX:
@@ -311,6 +333,7 @@ def parse_token(token: str):
 # 签发 / 校验 / 派生 / 吊销
 # --------------------------------------------------------------------------
 
+# 生效条件：role 经 normalize_role+role_spec（未知角色抛 TokenError），clearance 为假值时取 spec["clearance_cap"] 再经 _clamp_level 收窄到该 cap，layers_allow/ops_allow 经 _narrow 与 spec 默认求交，actor 为假值时取 role，delegable is None 时取 spec["delegable"]、否则按所传值取 bool，ttl 为真值时 expires_at=now+float(ttl)、为假值（None/0）时 None，记录写入 token_file(path) 后返回含明文 token 的字典。
 def issue(role: str, actor: str = None, clearance: str = None,
           tenant: str = "default", ttl: float = None, label: str = "",
           issued_by: str = "root", parent: str = None, delegable: bool = None,
@@ -345,6 +368,7 @@ def issue(role: str, actor: str = None, clearance: str = None,
             "expires_at": rec["expires_at"], "token_file": token_file(path)}
 
 
+# 生效条件：token 先经 parse_token（格式非法即抛 TokenError），其后 _load(path) 的 tokens 中该 token_id 无记录、rec 的 role 与解析出的 role 不等、revoked_at 为真、hash 与 _hash(secret) 经 hmac.compare_digest 不等、expires_at 为真且小于当前时间中任一成立即抛 TokenError；否则返回 Principal，tenant=tenant or rec.get("tenant") or "default"、actor=rec.get("actor") or role、clearance=rec.get("clearance") or "internal"、can_write/can_admin 取对应 rec 值的 bool。
 def verify_token(token: str, tenant: str = None, path: str = None) -> Principal:
     """校验令牌 → Principal。任何异常都抛 TokenError（fail-closed）。"""
     role, token_id, secret = parse_token(token)
@@ -371,6 +395,7 @@ def verify_token(token: str, tenant: str = None, path: str = None) -> Principal:
         ops_allow=rec.get("ops_allow"), auth_mode="token")
 
 
+# 生效条件：parent_token 经 verify_token(parent_token, path=path) 成功且父记录 delegable 为真才继续，否则抛 TokenError；role 经 normalize_role+role_spec，clearance 为假值时取 spec["clearance_cap"] 再 _clamp_level，若仍高于 parent.clearance 则降为 parent.clearance 并向 clamped 追加 "clearance"；layers/ops 先与 spec 求交再与父记录求交；can_write/can_admin 取 spec 与父对应值的与；ttl 为真值时 expires_at=now+float(ttl)、为假值（None/0）时沿用父记录 expires_at；新记录 delegable 恒 False、parent/issued_by 为 parent.token_id，返回含明文 token 与 clamped 的字典。
 def derive(parent_token: str, role: str, actor: str = None, ttl: float = None,
            label: str = "", path: str = None, clearance: str = None,
            layers_allow=None, ops_allow=None):
@@ -414,6 +439,7 @@ def derive(parent_token: str, role: str, actor: str = None, ttl: float = None,
             "expires_at": rec["expires_at"]}
 
 
+# 生效条件：normalize_role(unit) 结果不在 POSITION_ROLES 时抛 TokenError；否则返回 Principal：unit/role=u、can_admin 恒 False、clearance=_clamp_level(spec["clearance_cap"], p.clearance)、can_write=bool(spec["can_write"]) and bool(p.can_write)、layers_allow/ops_allow=_narrow(spec 对应值, p 对应值)，tenant/actor/session/harness/token_id/parent/expires_at/auth_mode/theory 等沿用 p。
 def narrowed_principal(p: Principal, unit: str) -> Principal:
     """按「单元」收窄 principal 权限（**请求级**身份，只能变小不能变大）。
 
@@ -450,6 +476,7 @@ def narrowed_principal(p: Principal, unit: str) -> Principal:
         theory_ok=p.theory_ok, theory_version=p.theory_version)
 
 
+# 生效条件：token_id 在 _load(path) 的 tokens 中无记录时抛 TokenError；有记录则将其 revoked_at 置为 time.time() 并 _save，再对 tokens 中 parent 等于 token_id 的每个子令牌递归 revoke(c, path)，返回 {"ok": True, "token_id": token_id, "revoked_children": children}。
 def revoke(token_id: str, path: str = None):
     data = _load(path)
     rec = (data.get("tokens") or {}).get(token_id)
@@ -464,6 +491,7 @@ def revoke(token_id: str, path: str = None):
     return {"ok": True, "token_id": token_id, "revoked_children": children}
 
 
+# 生效条件：从 _load(path)（path 为 None 时取默认令牌文件）的 tokens 取值；条目的 revoked_at 为真且 include_revoked 为假时跳过；返回不含密钥材料与摘要的清单；
 def list_tokens(path: str = None, include_revoked: bool = False):
     """令牌清单（不含密钥材料与摘要）。"""
     out = []
@@ -488,10 +516,12 @@ def list_tokens(path: str = None, include_revoked: bool = False):
 # CLI：签发 / 派生 / 清单 / 吊销 / 角色矩阵
 # --------------------------------------------------------------------------
 
+# 生效条件：obj 一律经 json.dumps(obj, ensure_ascii=False, indent=1) 加换行写入 sys.stdout；obj 不可 JSON 序列化时抛出 TypeError。
 def _print(obj):
     sys.stdout.write(json.dumps(obj, ensure_ascii=False, indent=1) + "\n")
 
 
+# 生效条件：v 为假值（None/空串）时返回 None；否则按 "," 切分、strip 后丢弃空项，结果为空列表时同样返回 None。
 def _csv_list(v):
     """CLI 的逗号分隔白名单 → list；空值返回 None（= 不额外收窄）。
 
@@ -502,6 +532,7 @@ def _csv_list(v):
     return [x.strip() for x in str(v).split(",") if x.strip()] or None
 
 
+# 生效条件：path 经 os.path.abspath 得 p，其 dirname 非空时 makedirs(exist_ok=True)，text 原样写入 p+".tmp" 后 os.replace 覆盖 p，再尝试 chmod 0600（仅吞 OSError）。
 def _write_secret(path: str, text: str) -> None:
     """把令牌明文写入文件（0600，原子替换）——供 HIVE_ORCH_TOKEN_FILE 读取。"""
     p = os.path.abspath(path)
@@ -518,6 +549,7 @@ def _write_secret(path: str, text: str) -> None:
         pass
 
 
+# 生效条件：argv 为 None 时取 sys.argv[1:]；经 argparse 解析（--token-file 与必填子命令 issue/verify/revoke/list/roles 等）；参数非法时经 argparse 退出，写盘失败抛 OSError；
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.tokens",
@@ -629,4 +661,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

package/md_cg/tool_face.py

@@ -38,7 +38,8 @@ FULL_ENV = "MDCG_TOOL_FACE"
 CG_HELP_HINT = '完整 op/参数语义：cg(op="help", query="<op 名 | 参数名 | 工具名>")'
 
 TOOL_BRIEFS = {
-    "cg": "灵枢认知图唯一入口（32 op：写/读/审/护/演化/元认知/预测/白箱…）。" + CG_HELP_HINT,
+    "cg": "灵枢认知图唯一入口（34 op：写/读/审/护/演化/元认知/预测/白箱/验证态 status/"
+          "三元组反查 edges…）。" + CG_HELP_HINT,
     "stg": "语义时空图 4 op：relation|timeline|anchors|consistency。" + CG_HELP_HINT,
     "mdcg_remember": "写入记忆节点（gated=true 走主动遗忘闸门；正文建议含 CCG 五要素）。",
     "mdcg_recall": "按 token 预算召回记忆包（RRF 多路融合，可开模糊/条件语义路与查询扩展）。",
@@ -93,6 +94,7 @@ GENERIC_PARAMS = frozenset({
 })
 
 
+# 生效条件：desc 为 None/空串等假值时按 `desc or ""` 回落空串、`_OP_SEC_RE.finditer` 无匹配而返回空 dict；否则以每个匹配的组 1 为键、组 2 去首尾空白并去掉结尾「；/;」后为值填入并返回。
 def op_sections(desc):
     """从工具 description 里切出 {op: 段落}（机械切分，无损）。"""
     out = {}
@@ -101,6 +103,7 @@ def op_sections(desc):
     return out
 
 
+# 生效条件：tools 为空时可迭代但无元素、返回空 set；否则遍历每个工具，并入其 `t.get("description") or ""` 经 op_sections 得到的键，以及其 `(t.get("inputSchema") or {}).get("properties") or {}` 中名为 op/action 的属性 description（缺省 ""）里 `_ENUM_RE` 匹配串按 "|" 拆出的词，返回并集 vocab。
 def op_vocab(tools):
     """全量 op 词汇表（用于判定「这是 op 专属参数的描述」）。"""
     vocab = set()
@@ -115,11 +118,13 @@ def op_vocab(tools):
     return vocab
 
 
+# 生效条件：head=(desc or "")[:prefix_len]（desc 假值即空串、prefix_len 默认 18），当 vocab 中存在长度 ≥3 且作为子串出现在 head 中的元素时返回 True，否则（含 vocab 为空）返回 False。
 def _is_op_specific(desc, vocab, prefix_len=18):
     head = (desc or "")[:prefix_len]
     return any(len(o) >= 3 and o in head for o in vocab)
 
 
+# 生效条件：desc 为假值返回 None；否则空白归一化后按 _ENUM_RE 结果分派——恰 1 组返回该组、多于 1 组返回 ENUM_PLACEHOLDER、0 组时若 op_specific 为真则 d 长度 ≤OP_SPECIFIC_LIMIT 原样返回否则 None，若 op_specific 为假则 d 长度 >GENERIC_LIMIT 时返回 d[:GENERIC_LIMIT].rstrip()+"…"、否则原样返回 d。
 def short_desc(desc, vocab, op_specific=False):
     """投影一条参数描述。
 
@@ -142,10 +147,12 @@ def short_desc(desc, vocab, op_specific=False):
     return d
 
 
+# 生效条件：tool 的 "inputSchema" 键存在且值为真时原样返回该值；键缺失或值为 None/{} 等假值时按 `or {}` 回落返回空 dict。
 def _schema_of(tool):
     return tool.get("inputSchema") or {}
 
 
+# 生效条件：tool 须含 "name" 键（缺失即 KeyError），desc=`tool.get("description") or ""`、isch=`_schema_of(tool)`；逐条属性去掉 "_req" 键后，若其 description 为真则按「key 在 GENERIC_PARAMS 或 `not _is_op_specific(d, vocab)`」判为 generic，再经 short_desc 投影——非空则替换 description、空则弹出该 description 键；返回 name 与 `TOOL_BRIEFS.get(name) or _first_sentence(desc,140)` 的 description，inputSchema 的 type 取 `isch.get("type") or "object"`，仅当 required 非空时才带 "required"。
 def slim_tool(tool, vocab):
     """投影单个工具（不修改入参）。"""
     name = tool["name"]
@@ -172,6 +179,7 @@ def slim_tool(tool, vocab):
             "inputSchema": out_schema}
 
 
+# 生效条件：d=折叠 (desc or "") 空白，按 "。"、"；"、";" 顺序取各字符在 d 中 `find` 的首次出现位置 i，遇到首个满足 0<i<=limit 者即返回 d[:i+1]；三个字符的首次位置均不满足时，len(d)>limit 返回 d[:limit].rstrip()+"…"，否则原样返回 d（limit=0 时无 i 满足，d 非空则返回 "…"）。
 def _first_sentence(desc, limit):
     d = " ".join((desc or "").split())
     for ch in ("。", "；", ";"):
@@ -181,6 +189,7 @@ def _first_sentence(desc, limit):
     return (d[:limit].rstrip() + "…") if len(d) > limit else d
 
 
+# 生效条件：环境变量 FULL_ENV 取值 `(os.environ.get(FULL_ENV) or "").strip().lower()=="full"`（未设或设为空串均不成立）时原样返回入参 tools；否则以 tools 算出 vocab 并返回 `[slim_tool(t, vocab) for t in tools]`（tools 为空则返回空列表）。
 def slim_tools(tools):
     """投影整个工具面。MDCG_TOOL_FACE=full 时原样返回（调试/兼容）。"""
     if (os.environ.get(FULL_ENV) or "").strip().lower() == "full":
@@ -192,6 +201,7 @@ def slim_tools(tools):
 # --------------------------------------------------------------------------
 # 按需披露：cg(op=help, query=…)
 # --------------------------------------------------------------------------
+# 生效条件：取 `_schema_of(tool)` 的 properties，仅保留 description（缺省 ""）满足 `_is_op_specific(desc, {op})` 的属性，每项记为 name/type/required(k in required)/desc，返回该列表的 `out[:limit]` 切片（limit 默认 40，limit=0 得空列表，负值从尾部削减）。
 def _params_for(tool, op, limit=40):
     isch = _schema_of(tool)
     props = isch.get("properties") or {}
@@ -204,6 +214,7 @@ def _params_for(tool, op, limit=40):
     return out[:limit]
 
 
+# 生效条件：tools 用于建 `by_name={t["name"]: t}`（某工具缺 "name" 即 KeyError），q=(query or "").strip()——q 为空串返回 {"ok":True,"tool_index":[每工具 name 与 `TOOL_BRIEFS.get(name) or _first_sentence(desc,120)`],"usage":...}；q 等于某工具名时返回该工具的 description/ops（op_sections 键排序）/params/required；否则逐工具收集「q 出现在 op 段落键中」与「pname==q 或 len(q)>=4 且 pname 以 q 开头」两类命中（不互斥、可同时追加），全部工具遍历后无命中返回 {"ok":False,"error",...,"hint",...}，有命中返回 {"ok":True,"query":q,"hits":hits[:max(1, limit)]}（limit≤1 时按 1 条截取）。
 def help_text(tools, query=None, limit=40):
     """从**完整真源**按需渲染说明——被投影掉的原文在此无损取回。"""
     q = (query or "").strip()
@@ -247,4 +258,4 @@ def help_text(tools, query=None, limit=40):
     if not hits:
         return {"ok": False, "error": f"未找到 op / 参数 / 工具：{q}",
                 "hint": "cg(op=help) 不带 query 可列出全部工具与一行职责"}
-    return {"ok": True, "query": q, "hits": hits[:max(1, limit)]}
+    return {"ok": True, "query": q, "hits": hits[:max(1, limit)]}