@furongjun1999/dsh-memory 0.4.11 → 0.5.1

package/md_cg/run_tests.py

@@ -0,0 +1,211 @@
+# -*- coding: utf-8 -*-
+"""run_tests.py · 测试一键入口（固化 `python -m` 运行约定）。
+
+背景（2026-09-13 全面分析报告建议 #3）：md_cg 包内测试普遍使用**相对导入**，
+必须以模块方式从仓库根运行——`python -m md_cg.test_xxx`；直接
+`python md_cg/test_xxx.py` 会因相对导入 ImportError（59/61 踩坑实测）。
+本脚本把该约定固化为唯一入口，杜绝逐文件手敲与跑法漂移。
+
+**本模块是包内入口**（2026-09-24 修复）：原入口只在 `scripts/run_tests.py`，
+而出货包 `files` 不含 `scripts/` —— README 写的门禁命令在安装态不存在。
+现在 `python -m md_cg.run_tests` 恒可用；源码树里 `scripts/run_tests.py`
+可继续作为薄封装（同一约定）。
+
+与 scripts/ 版的两点差异（都是为了在受限宿主里可跑）：
+  ① 子进程输出**重定向到文件**，不用 capture_output（管道）：DSH 文件沙箱
+     禁 CreatePipe（WinError 5），旧写法在受限环境里每个用例都 PermissionError
+     ——表现为「全部失败」，与代码无关。日志落在 `<testlogs>/` 便于事后查。
+  ② 组集合按**存在性**发现：compiler / swarm / scripts / hive 不在（安装态）
+     就自然没有目标，不报错。
+
+用法（任意 cwd 均可，内部以本包所在仓根为 subprocess cwd）：
+  python -m md_cg.run_tests                  # 全量（存在的组）
+  python -m md_cg.run_tests md_cg            # 只跑一组：md_cg | compiler | swarm | scripts | hive
+  python -m md_cg.run_tests -k p44           # 按关键字过滤模块名
+  python -m md_cg.run_tests --jobs 1         # 串行（默认并发 4）
+  python -m md_cg.run_tests --list           # 只列出目标不执行
+
+退出码：全部通过 0，存在失败 1（可直接接 CI / 提交前门禁）。
+"""
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import glob
+import os
+import subprocess
+import sys
+import tempfile
+import time
+
+_REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+#: 逐用例日志目录（重定向目标；默认临时目录，避免污染仓）
+_LOG_DIR = os.environ.get("MDCG_TESTLOG_DIR") or os.path.join(
+    tempfile.gettempdir(), "md_cg_testlogs")
+
+
+def _discover():
+    """返回 [(组名, 显示名, argv 候选列表)]；argv 依次尝试直到成功启动。"""
+    out = []
+    for f in sorted(glob.glob(os.path.join(_REPO, "md_cg", "test_*.py"))):
+        stem = os.path.splitext(os.path.basename(f))[0]
+        out.append(("md_cg", f"md_cg.{stem}",
+                    [[sys.executable, "-X", "utf8", "-m", f"md_cg.{stem}"]]))
+    for pkg in ("compiler", "swarm"):
+        for f in sorted(glob.glob(os.path.join(_REPO, pkg, "tests", "*.py"))):
+            if os.path.basename(f).startswith("_"):
+                continue
+            stem = os.path.splitext(os.path.basename(f))[0]
+            out.append((pkg, f"{pkg}.tests.{stem}",
+                        [[sys.executable, "-X", "utf8", "-m",
+                          f"{pkg}.tests.{stem}"],
+                         [sys.executable, "-X", "utf8", f]]))
+    # scripts/ 不是包（无 __init__.py）→ 只能直跑；脚本内自带 sys.path 注入
+    for f in sorted(glob.glob(os.path.join(_REPO, "scripts", "test_*.py"))):
+        stem = os.path.splitext(os.path.basename(f))[0]
+        out.append(("scripts", f"scripts.{stem}",
+                    [[sys.executable, "-X", "utf8", f]]))
+    # hive/ 是包 → -m 优先；测试内用 importlib 直载，故回退直跑同样可用。
+    for f in sorted(glob.glob(os.path.join(_REPO, "hive", "test_*.py"))):
+        stem = os.path.splitext(os.path.basename(f))[0]
+        out.append(("hive", f"hive.{stem}",
+                    [[sys.executable, "-X", "utf8", "-m", f"hive.{stem}"],
+                     [sys.executable, "-X", "utf8", f]]))
+    return out
+
+
+# 生效条件：name/argvs/timeout 就绪时逐个 argv 尝试运行（cwd=_REPO，stdout+stderr 重定向到 _LOG_DIR/<name>.log，无管道），返回 (name, 是否通过, 日志尾部最多 800 字符)；超时返回 (name, False, "超时(>Ns)")；首个成功启动（非「No module named」回退）的尝试决定结果。
+def _run_one(name, argvs, timeout):
+    """跑一个用例；输出**重定向到文件**（不用管道——沙箱禁 CreatePipe）。"""
+    os.makedirs(_LOG_DIR, exist_ok=True)
+    env = dict(os.environ, PYTHONUTF8="1", PYTHONIOENCODING="utf-8")
+    last = ""
+    for argv in argvs:                    # -m 优先；No module named 时回退直跑
+        log = os.path.join(_LOG_DIR, name.replace(".", "_") + ".log")
+        t0 = time.time()
+        try:
+            with open(log, "wb") as fh:
+                p = subprocess.run(argv, cwd=_REPO, stdout=fh,
+                                   stderr=subprocess.STDOUT,
+                                   stdin=subprocess.DEVNULL, env=env,
+                                   shell=False, timeout=timeout)
+            rc = p.returncode
+        except subprocess.TimeoutExpired:
+            return name, False, f"超时（>{timeout}s）—— 日志 {log}"
+        except OSError as exc:
+            return name, False, f"无法启动子进程：{exc!r}（日志 {log}）"
+        try:
+            with open(log, encoding="utf-8", errors="replace") as fh:
+                text = fh.read()
+        except OSError:
+            text = ""
+        if rc != 0 and "No module named" in text and len(argvs) > 1:
+            last = text[-300:]
+            continue
+        tail = text[-800:]
+        return name, rc == 0, f"[{time.time() - t0:.1f}s] " + tail
+    return name, False, last
+
+
+def _dep_db():
+    p = os.path.join(_REPO, "md_cg", "whitebox_kb", "wisdom",
+                     "wisdom-book-cloud.db")
+    return (None if os.path.exists(p)
+            else "依赖白箱库 whitebox_kb/wisdom/wisdom-book-cloud.db"
+                 "（.gitignore 忽略，需本地生成）")
+
+
+def _dep_mdroot():
+    """md 语料真源依赖：目录存在**且含 .md** 才算就绪。
+
+    空壳目录不算（v14 缺陷 F：旁路执行造出的空 `_md_cg_wisdom_graph/` 曾把
+    runner 从 SKIP 翻成 FAIL）——判据必须与 test_md_access_parity 同口径。
+    """
+    p = os.path.join(_REPO, "_md_cg_wisdom_graph")
+    if not os.path.isdir(p):
+        return ("依赖 md 语料真源 _md_cg_wisdom_graph/（.gitignore 忽略，"
+                "组 D 需本地真源）")
+    for _dirpath, _dirs, names in os.walk(p):
+        if any(n.endswith(".md") for n in names):
+            return None
+    return ("依赖 md 语料真源 _md_cg_wisdom_graph/（目录在但零 .md："
+            "空壳目录不算依赖就绪）")
+
+
+# 裸 clone 环境 SKIP 探测（2026-09-14 外部复核建议 #3）：
+# 依赖 gitignored 本地数据或特定平台的测试，依赖缺失时标 SKIP（附原因）
+# 不计入失败——避免裸 clone 用户第一眼看到虚假 FAIL（复核实测 83/87 根因）。
+_SKIPS = {
+    "md_cg.test_p44_md_whitebox": _dep_db,
+    "md_cg.test_md_access_parity": _dep_db,
+    "md_cg.test_wisdom_md_store": _dep_mdroot,
+    "swarm.tests.test_swarm_fault": (
+        lambda: None if os.name == "nt"
+        else "Windows 专用（powershell/taskkill）"),
+}
+
+
+# 生效条件：argv 就绪时解析组/-k/--jobs/--timeout/--list 参数，按 _discover() 与 _SKIPS 过滤后并发执行，打印 PASS/FAIL/SKIP 与汇总；全部通过返回 0、有失败返回 1、--list 恒返回 0。
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="python -m md_cg.run_tests",
+        description="灵枢测试入口（python -m 约定；输出重定向，沙箱安全）")
+    # 注：不用 argparse choices——部分 Python 版本对 nargs="*" 无值时
+    # 以空列表过 choices 校验会误报 invalid choice（bpo-27227 老行为）。
+    ap.add_argument("group", nargs="*", default=None,
+                    help="只跑指定组，可多选：md_cg compiler swarm scripts hive"
+                         "（缺省全量）")
+    ap.add_argument("-k", default="", help="按关键字过滤模块名")
+    ap.add_argument("--jobs", type=int, default=4, help="并发数（默认 4）")
+    ap.add_argument("--timeout", type=int, default=900, help="单测超时秒数")
+    ap.add_argument("--list", action="store_true", help="只列出目标不执行")
+    args = ap.parse_args(argv)
+
+    _known = ("md_cg", "compiler", "swarm", "scripts", "hive")
+    _bad = [g for g in (args.group or ()) if g not in _known]
+    if _bad:
+        ap.error(f"invalid group: {', '.join(_bad)}（可选：{'/'.join(_known)}）")
+    groups = set(args.group or ()) or set(_known)
+    targets = [(g, n, a) for g, n, a in _discover()
+               if g in groups and (not args.k or args.k in n)]
+    if args.list:
+        for g, n, _a in targets:
+            print(f"{g:<9}{n}")
+        print(f"共 {len(targets)} 个")
+        return 0
+
+    # SKIP 探测：依赖缺失/平台不符的测试不执行（外部复核建议 #3，裸 clone 友好）
+    skipped, runnable = [], []
+    for g, n, a in targets:
+        probe = _SKIPS.get(n)
+        reason = probe() if probe else None
+        if reason:
+            skipped.append((n, reason))
+            print(f"SKIP  {n}  （{reason}）", flush=True)
+        else:
+            runnable.append((g, n, a))
+
+    bad = []
+    with concurrent.futures.ThreadPoolExecutor(
+            max_workers=max(1, args.jobs)) as ex:
+        futs = {ex.submit(_run_one, n, a, args.timeout): (g, n)
+                for g, n, a in runnable}
+        for fu in concurrent.futures.as_completed(futs):
+            name, ok, tail = fu.result()
+            print(("PASS  " if ok else "FAIL  ") + name, flush=True)
+            if not ok:
+                bad.append(name)
+                for ln in tail.splitlines()[-6:]:
+                    print("      " + ln, flush=True)
+
+    print(f"\n===== SUMMARY {len(runnable) - len(bad)}/{len(runnable)} 通过，"
+          f"{len(skipped)} 跳过（依赖缺失/平台不符） =====")
+    print(f"逐用例日志：{_LOG_DIR}")
+    if bad:
+        print("失败：" + ", ".join(bad))
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/scrub.py

@@ -45,7 +45,7 @@ import os
 import random
 import time
 
-from . import forgetting, protect
+from . import forgetting, nodefile, protect
 from .fsutil import append_jsonl, read_jsonl
 from .mdcg import bigrams
 
@@ -450,7 +450,12 @@ def _kv_pairs(content) -> dict:
             if sep in line:
                 k, _, v = line.partition(sep)
                 k, v = k.strip(), v.strip()
-                if 2 <= len(k) <= 12 and v and k not in _SKIP_KEYS:
+                # CCG 六要素行（`# 功能名：` / `# 不适用条件：` …）是**逐节点声明**，
+                # 不是可跨节点比对的断言值。把「不适用条件」当键会让语义无关的节点
+                # 互为「同键不同值」矛盾（实测 12 抽样里 9 条 high 全是这类误报，
+                # 且 apply 会把好节点 weaken+demote 并跨层移动文件）。
+                if (2 <= len(k) <= 12 and v and k not in _SKIP_KEYS
+                        and not nodefile.is_ccg_mark(k)):
                     out.setdefault(k, v)
                 break
     return out
@@ -642,7 +647,12 @@ def decontaminate(cg, node_ids=None, *, kinds=None, dry_run: bool = True,
         nid, kind = issue["node_id"], issue["kind"]
         if kinds and kind not in kinds:
             continue
-        if kind in ("duplicate", "unverified"):
+        # 只给建议的动作必须按 CONTAMINATION 的**声明**判定，不能靠 kind 白名单：
+        # `not_yet` 声明 fix=("hint",)，原实现只排除 duplicate/unverified，
+        # 于是它会落到 _weaken 分支（实测 min_severity="info" 时 confidence
+        # 0.6→0.45、negative_evidence 0→1），声明与实修不一致。
+        _declared = CONTAMINATION.get(kind, (None, ()))[1]
+        if kind in ("duplicate", "unverified") or _declared == ("hint",):
             n_hint += 1
             actions.append({"node_id": nid, "kind": kind, "action": "hint",
                             "detail": issue["detail"], "applied": False})

package/md_cg/security.py

@@ -20,12 +20,44 @@ import os
 import time
 import uuid
 
-SENSITIVITY_ORDER = ("public", "internal", "private", "secret")
+from .datapath import aux_root
+from .fsutil import publish
+
+# 密级阶梯的体系语义（批次 27 表述正名，使用者 2026-09-24 澄清）：
+#   private ≠ 个人隐私保密，而是**错误处置标记**——工作区内容因错误相关、
+#   验证未过、待排查而被标记私有，目的是**限制向平级/下级扩散**（防止未
+#   证实或已知有误的内容被下游消费），不是对错误处置链路保密。
+#   可见性是**故意的冲突设计**：平级/下级限读，但错误处置链路必须可读——
+#   设计者（designer，secret 上限）、上级节点、验证单元（verify）三者
+#   必读。当前令牌矩阵中 record/reflect/verify/sustain/orchestr 的
+#   clearance_cap 均为 internal（forbidden 含 private）——验证单元读错误
+#   标记节点是本职却受限于 cap，属**已登记的分级缺口**（见安全审计实锚
+#   文档「读权限分级」节），未来专项：verify 面提 cap 或走设计者代查通道。
+# 密级阶梯的体系语义（批次 27 正名 / 批次 28 分型落地，使用者 2026-09-24）：
+#   **restricted = 错误处置标记（新增档）**——内容因错误相关、验证未过、
+#   待排查被标记，目的是限制向平级/下级扩散；可见性按**错误处置链路角色**
+#   判定（designer/orchestr/verify 必读，record/worker/output/guest 限读），
+#   不走纯密级 rank（链路角色与平级同为 internal，rank 无法区分）；
+#   **不加密**（不在 crypto.ENCRYPTED_LEVELS——链路要明文读）。
+#   private = 隐私/会话绑定档（语义不变：仅归属会话 + 设计者豁免可见，
+#   落盘加密）；secret = 最高密级。
+#   可见性的故意冲突设计就此消解：错误标记限扩散但处置链路必读，
+#   隐私内容写者私有——两种语义不再共用一个密级档。
+SENSITIVITY_ORDER = ("public", "internal", "restricted", "private", "secret")
 DEFAULT_SENSITIVITY = "internal"
 
 
 class AccessDenied(Exception):
-    """权限拒绝（读/写/管理）。"""
+    """权限拒绝（读/写/管理）。
+
+    hint（可选）：与本仓 70 处失败路径 hint 同口径的「为什么 + 怎么办」可操作
+    指引（issue #34：新用户首个错误无可操作指引——guest 只读写入被拒恰是
+    三步接入后必然撞上的第一条失败，不得只说「不行」不说「怎么办」）。
+    """
+
+    def __init__(self, msg: str, hint: str = None):
+        super().__init__(msg)
+        self.hint = hint
 
 
 # 生效条件：形参 level 为模块级常量 SENSITIVITY_ORDER 中的元素时返回其下标，否则抛 AccessDenied。
@@ -128,18 +160,40 @@ class Principal:
 
     # ---------- 强制校验（越权即 AccessDenied） ----------
 
-# 生效条件：无 required 形参或模块级常量前置，当 self.expired()（来自 __init__ 的 expires_at 与当前时间比较）为 True 时抛 AccessDenied，否则无操作返回 None。
+# 生效条件：无 required 形参或模块级常量前置，当 self.expired()（来自 __init__ 的 expires_at 与当前时间比较）为 True 时抛 AccessDenied（带重新签发 hint），否则无操作返回 None。
     def _require_live(self):
         if self.expired():
-            raise AccessDenied(f"actor={self.actor} 令牌已过期")
-
-# 生效条件：先调用 self._require_live()（过期则抛 AccessDenied）；再要求 self.allows_op(op) 为 True，否则抛 AccessDenied。
+            raise AccessDenied(
+                f"actor={self.actor} 令牌已过期",
+                hint="令牌过期不是故障：重新签发并更新 MDCG_TOKEN 后重启宿主"
+                     "（python -m md_cg.tokens issue …，README「写入凭据」一节）。")
+
+    # issue #34：op 拒绝按成因分指引——guest（无令牌只读访客）引导配凭据；
+    # 有令牌但白名单不含该 op 引导换角色/补授权。「不是故障」安抚语气与
+    # 本仓其它 70 处 hint 同口径。
+    _GUEST_OP_HINT = (
+        "当前为只读访客模式（未检测到写入凭据 MDCG_TOKEN）：读/召回/时间线可用，"
+        "写入与管理操作不落盘。这不是故障，配置凭据后即恢复。"
+        "要真正落盘请签发并配置写入凭据（README「写入凭据」一节）：\n"
+        "  python -m md_cg.tokens issue --role recorder --actor <名> "
+        "--clearance internal\n"
+        "  setx MDCG_TOKEN \"<token>\"   # 然后重启宿主（DSH/IDE）\n"
+        "最小权限可用 --role recorder；op 用法可查 cg(op=\"help\", query=\"write\")。")
+
+# 生效条件：先调用 self._require_live()（过期则抛 AccessDenied）；再要求 self.allows_op(op) 为 True，否则抛 AccessDenied（role=guest 带配凭据 hint，其它角色带补授权 hint）。
     def require_op(self, op: str):
         self._require_live()
         if not self.allows_op(op):
+            msg = (f"角色 {self.role} 无权执行 op={op}（作用域 "
+                   f"{list(self.ops_allow) if self.ops_allow is not None else '不限'}）")
+            if self.role == "guest":
+                raise AccessDenied(msg, hint=self._GUEST_OP_HINT)
             raise AccessDenied(
-                f"角色 {self.role} 无权执行 op={op}（作用域 "
-                f"{list(self.ops_allow) if self.ops_allow is not None else '不限'}）")
+                msg,
+                hint=f"当前令牌（actor={self.actor}，角色 {self.role}）的 ops "
+                     f"白名单不含 {op}，属正常闸门不是故障。可：①换用含该 op "
+                     f"的角色令牌；②由签发者以 --ops-allow 补授权后重新签发"
+                     f"（python -m md_cg.tokens issue …，README「写入凭据」一节）。")
 
 # 生效条件：依次要求 self._require_live() 未抛异常、self.theory_ok 为 True、self.can_write 为 True、self.allows(sensitivity) 为 True；任一不满足则抛 AccessDenied。
     def require_write(self, sensitivity: str):
@@ -149,7 +203,12 @@ class Principal:
                 "版本层校验未通过（theory_ok=False）：全部写操作被拒，"
                 "仅保留 theory 修复入口")
         if not self.can_write:
-            raise AccessDenied(f"actor={self.actor} 无写权限")
+            raise AccessDenied(
+                f"actor={self.actor} 无写权限",
+                hint=(self._GUEST_OP_HINT if self.role == "guest" else
+                      f"当前令牌（角色 {self.role}）未授予写权限（can_write="
+                      f"False），属正常闸门不是故障。请换用可写角色令牌或由"
+                      f"签发者重新签发（README「写入凭据」一节）。"))
         if not self.allows(sensitivity):
             raise AccessDenied(
                 f"写入敏感度 {sensitivity} 超出 clearance {self.clearance}")
@@ -196,40 +255,47 @@ class Principal:
                 f"write={self.can_write}, admin={self.can_admin})")
 
 
-# 生效条件：path 为 None 时落至 os.path.expanduser("~") 下的 .mdcg/_tenants.json，path 非 None（含空串）时按传入值使用，并在构造内以 self._load() 的返回填充 self.data。
+# 生效条件：path 为 None 时落至 datapath.aux_root()（默认 ~/.mdcg，可经 MDCG_AUX_ROOT 改）下的 _tenants.json，path 非 None（含空串）时按传入值使用，并在构造内以 self._load() 的返回填充 self.data、以 self.load_error 留存加载期损坏留痕（N124，2026-09-25：登记表损坏/不可读必须可被调用方感知，缺文件不算损坏）。
 class TenantRegistry:
     """租户注册表：tenant → {root, clearance_cap, description}。
 
     默认位置：<registry_dir>/_tenants.json（默认 ~/.mdcg/）。
     设计意图：私有租户的 root 指向仓库外目录，开源仓库里只放 public 租户的根。
+
+    load_error（N124，2026-09-25）：_load 遇「文件在但损坏/不可读」（JSON
+    解析失败、OSError、顶层非对象）时留存原因字符串，完好/缺文件为 None——
+    供 _resolve_root 等调用方把「静默回落空表」开口成 stderr 告警。
     """
 
-# 生效条件：形参 path 为 None 时取 ~/.mdcg/_tenants.json，否则取 path；self.data 初始化为 _load() 结果（self.path 经 os.path.exists 为真且 JSON 解析为 dict 时取该 dict，否则回落 {"schema":1,"tenants":{}}）。
+# 生效条件：形参 path 为 None 时取 ~/.mdcg/_tenants.json，否则取 path；self.load_error 置 None 后 self.data 初始化为 _load() 结果（self.path 经 os.path.exists 为真且 JSON 解析为 dict 时取该 dict，否则回落 {"schema":1,"tenants":{}}；文件在但解析失败/OSError/顶层非对象时先置 self.load_error 为原因串，缺文件不置）。
     def __init__(self, path: str = None):
         if path is None:
-            path = os.path.join(os.path.expanduser("~"), ".mdcg", "_tenants.json")
+            path = os.path.join(aux_root(), "_tenants.json")
         self.path = path
+        self.load_error = None
         self.data = self._load()
 
-# 生效条件：当 self.path 经 os.path.exists 为真且内容可解析为 dict 时返回该 dict；否则（os.path.exists 为假、非 dict、JSON 解析失败或 OSError）返回 {"schema":1,"tenants":{}}。
+# 生效条件：先置 self.load_error=None；当 self.path 经 os.path.exists 为真且内容可解析为 dict 时返回该 dict；解析失败或 OSError 时置 self.load_error=f"{类型名}: {e}"、顶层 JSON 非对象时置 self.load_error="登记表 JSON 顶层不是对象"；否则（os.path.exists 为假）不留痕；各回落分支均返回 {"schema":1,"tenants":{}}。
     def _load(self):
+        self.load_error = None
         if os.path.exists(self.path):
             try:
                 with open(self.path, encoding="utf-8") as f:
                     d = json.load(f)
                 if isinstance(d, dict):
                     return d
-            except (ValueError, OSError):
-                pass
+                self.load_error = "登记表 JSON 顶层不是对象"
+            except (ValueError, OSError) as e:
+                self.load_error = f"{type(e).__name__}: {e}"
         return {"schema": 1, "tenants": {}}
 
-# 生效条件：无 required 形参或模块级常量前置，将 self.data 以 JSON 写入 self.path + ".tmp"，随后 os.replace 到 self.path；目录名称为空时用 "." 创建。
+# 生效条件：无 required 形参或模块级常量前置，将 self.data 以 JSON 写入 self.path + ".tmp"，随后 publish（带 Windows 短重试的 os.replace）到 self.path；目录名称为空时用 "." 创建。
     def _save(self):
         os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)
         tmp = self.path + ".tmp"
         with open(tmp, "w", encoding="utf-8") as f:
             json.dump(self.data, f, ensure_ascii=False, indent=1)
-        os.replace(tmp, self.path)
+        publish(tmp, self.path)
 
 # 生效条件：形参 clearance_cap 须为模块级常量 SENSITIVITY_ORDER 成员（否则 _rank 抛 AccessDenied）；形参 tenant/root 提供后写入 self.data["tenants"]（要求 self.data 含 "tenants" 键，否则 KeyError），_save 成功则返回新登记项。
     def register(self, tenant: str, root: str, clearance_cap: str = DEFAULT_SENSITIVITY,
@@ -272,4 +338,48 @@ class TenantRegistry:
         if _rank(want) > _rank(cap):
             want = cap
         return Principal(tenant=tenant, actor=actor or tenant, clearance=want,
-                         can_write=can_write, can_admin=can_admin, session=session)
+                         can_write=can_write, can_admin=can_admin, session=session)
+
+
+# P1-4（批次 26，外部审查报告）：工具路径参数的根白名单——ingest/export/link
+# 的 path/out 是模型可控输入，原样透传 = 任意文件读（/etc/passwd 进图）与
+# 任意文件写（evidence export 的 out）。校验语义与 HIVE_READ_ROOTS 同构：
+# **env 未设置 = 放开**（默认部署零行为变更，与 2026-09-19 的读放开裁定
+# 精神一致）；**设置了 = realpath 落根内否则拒**（fail-closed），`..` 与
+# 绝对路径穿越在 realpath 归一后自然被涵盖。支持 os.pathsep 分隔多根。
+# 生效条件：env_var 环境变量去空白后为空、或 path 为 None/空串时直接返回（不约束）；否则取 realpath(expanduser(path))，与 env 值按 os.pathsep 切分的每个根做「相等或以根+os.sep 为前缀」判定，任一命中即返回；全部未命中抛 PermissionError（含 what/原 path/realpath/roots 的拒绝说明）。
+def check_path_root(path, env_var: str, what: str) -> None:
+    raw = (os.environ.get(env_var) or "").strip()
+    if not raw:
+        return                                   # 未配置 = 放开（部署开关）
+    if path is None or str(path).strip() == "":
+        return                                   # 无路径参数（如 stat/action）
+    roots = []
+    for p in raw.split(os.pathsep):
+        p = p.strip()
+        if p:
+            roots.append(os.path.realpath(os.path.expanduser(p)))
+    real = os.path.realpath(os.path.expanduser(str(path)))
+    for r in roots:
+        if real == r or real.startswith(r.rstrip(os.sep) + os.sep):
+            return
+    raise PermissionError(
+        f"{what} 路径超出 {env_var} 白名单，拒绝访问：{path} "
+        f"(realpath={real}, roots={roots})——路径类工具参数的根约束"
+        "（P1-4），部署用该环境变量声明可读写的根目录")
+
+
+# 错误处置链路角色集（批次 28 分型）：restricted（错误处置标记）的可见性
+# 不走密级 rank——链路角色与平级同为 internal，rank 无法区分「处置者」与
+# 「扩散面」。designer=全局观测本职；orchestr=上级节点（拆解派发/裁决
+# 收口）；verify=验证本职（错误标记节点是验证的对象）。
+_RESTRICTED_READER_ROLES = ("designer", "orchestr", "verify")
+
+
+# 生效条件：p 为 Principal 或 None；p 为 None 返回 False；p.can_admin 为真（设计者）或 p.role 属 _RESTRICTED_READER_ROLES 时返回 True，否则返回 False。
+def can_read_restricted(p) -> bool:
+    if p is None:
+        return False
+    if getattr(p, "can_admin", False):
+        return True
+    return getattr(p, "role", "") in _RESTRICTED_READER_ROLES