@furongjun1999/dsh-memory 0.4.11 → 0.5.0

package/md_cg/security.py

@@ -1,275 +1,275 @@
-# -*- coding: utf-8 -*-
-"""md_cg · 进程/权限模型（记忆 OS #2）
-
-关键动机：**灵枢是开源仓库，而记忆很大一部分是私有内容**。因此权限模型必须
-支持「公开知识」与「私有记忆」的物理与逻辑隔离：
-
-  ① 物理隔离：租户（tenant）各自一个根目录。public 租户的根可落在开源仓库内，
-     private 租户的根必须落在仓库外（如 ~/.mdcg/private/）。
-  ② 逻辑隔离：每个节点带 sensitivity（public < internal < private < secret）；
-     每个调用方（Principal）带 clearance，只能读写 ≤ clearance 的节点。
-  ③ 硬规则：secret 节点对 clearance < secret 的调用方**写入即拒**（对齐 noema
-     「secret 候选自动拒绝」）；写入高于自身 clearance 的敏感度 → 拒绝。
-
-零第三方依赖。
-"""
-from __future__ import annotations
-
-import json
-import os
-import time
-import uuid
-
-SENSITIVITY_ORDER = ("public", "internal", "private", "secret")
-DEFAULT_SENSITIVITY = "internal"
-
-
-class AccessDenied(Exception):
-    """权限拒绝（读/写/管理）。"""
-
-
-# 生效条件：形参 level 为模块级常量 SENSITIVITY_ORDER 中的元素时返回其下标，否则抛 AccessDenied。
-def _rank(level: str) -> int:
-    try:
-        return SENSITIVITY_ORDER.index(level)
-    except ValueError:
-        raise AccessDenied(f"未知敏感度/密级：{level}") from None
-
-
-# 生效条件：全部形参均可省略、clearance 默认取模块常量 DEFAULT_SENSITIVITY，构造时先经 _rank(clearance) 校验，随后 session 为假值（含空串）回落为 sess_+uuid 十二位、role 假值回落 "system"、expires_at 为假值（含 0）置 None、layers_allow/ops_allow 为 None 时保持 None 否则转 tuple、theory_ok 经 bool() 转换。
-class Principal:
-    """调用方身份（一次会话一个）。
-
-    tenant        —— 租户（决定根目录）
-    actor         —— 调用者标识（写入审计）
-    clearance     —— 最高可读/可写敏感度
-    can_write     —— 是否允许写
-    can_admin     —— 是否允许管理操作（forget/restore/review_decide）
-    session       —— 会话 id（进程/会话模型：每次连接一个）
-    harness       —— 承载端标识（dsh/zcode/codebuddy…；仅归因，不参与授权）
-    unit          —— 单元分工（record/reflect/verify/output/sustain；仅归因）
-                     注：MCP 请求级参数 `as_unit` 会经 `tokens.narrowed_principal`
-                     产出一次性 Principal——其 role/layers/ops 取自该单元 spec、unit
-                     记为执行单元。那是**单次调用的临时身份**，不改变本字段的归因
-                     定位（见 `mcp_server.call_tool`）。
-
-    令牌扩展（由 `tokens.verify_token` 填充；直接构造时为 None = 不限制）：
-    role          —— 角色（designer/reflection/verifier/recorder/output/sustain/guest）
-    token_id      —— 令牌 id（可追溯到签发记录）
-    parent        —— 派生来源令牌 id（权职分离的委派链）
-    expires_at    —— 过期时间戳（None = 不过期）
-    layers_allow  —— 可写层白名单（None = 不限制；"*" = 全部）
-    ops_allow     —— 可执行 op 白名单（同上）
-    auth_mode     —— direct（直接构造）/ token / legacy_env / anonymous
-
-    版本层扩展（蜂群互联层0，由 `theory.check` 填充）：
-    theory_ok      —— 版本声明是否合法；False 时**全部写/管理操作被拒**（只读降级）
-    theory_version —— 当前声明的协议版本（审计与 whoami 用）
-    """
-
-# 生效条件：clearance 须为模块级常量 SENSITIVITY_ORDER 成员（否则 _rank 抛 AccessDenied），session 为假值（含 None/空串）时生成 sess_ 随机串，expires_at 为假值（含 None/0）时存 None 否则 float(expires_at)，layers_allow/ops_allow 为 None 时存 None 否则 tuple 化。
-    def __init__(self, tenant: str = "default", actor: str = "system",
-                 clearance: str = DEFAULT_SENSITIVITY, can_write: bool = True,
-                 can_admin: bool = False, session: str = None,
-                 harness: str = None, unit: str = None,
-                 role: str = None, token_id: str = None, parent: str = None,
-                 expires_at: float = None, layers_allow=None, ops_allow=None,
-                 auth_mode: str = "direct", theory_ok: bool = True,
-                 theory_version: str = None):
-        _rank(clearance)                      # 校验
-        self.tenant = tenant
-        self.actor = actor
-        self.clearance = clearance
-        self.can_write = can_write
-        self.can_admin = can_admin
-        self.session = session or ("sess_" + uuid.uuid4().hex[:12])
-        # 归因维度（嵌套身份）：只入审计（_audit/_recent），不参与权限判定。
-        # 权限域仍由令牌记录决定（tokens.ROLE_SPECS），与 harness/unit 无关。
-        # 受控例外：MCP 请求级 `as_unit` 收窄（tokens.narrowed_principal）产出的是
-        # 一次性 Principal，其 role/allow 取自单元 spec——**只做减法**（与 owner
-        # 求交 + 管理权恒 False），故不构成本字段「参与授权」的先例。
-        self.harness = harness
-        self.unit = unit
-        self.role = (role or "system")
-        self.token_id = token_id
-        self.parent = parent
-        self.expires_at = float(expires_at) if expires_at else None
-        self.layers_allow = None if layers_allow is None else tuple(layers_allow)
-        self.ops_allow = None if ops_allow is None else tuple(ops_allow)
-        self.auth_mode = auth_mode
-        self.theory_ok = bool(theory_ok)
-        self.theory_version = theory_version
-
-    # ---------- 基础判定 ----------
-
-# 生效条件：形参 sensitivity 与 self.clearance 均可被 _rank 映射到模块级常量 SENSITIVITY_ORDER 中时，返回前者排名是否不高于后者；任一不在其中则 _rank 抛 AccessDenied。
-    def allows(self, sensitivity: str) -> bool:
-        """clearance 是否覆盖该敏感度（可读/可写）。"""
-        return _rank(sensitivity) <= _rank(self.clearance)
-
-# 生效条件：无 required 形参或模块级常量前置，仅当 self.expires_at（来自 __init__ 的 expires_at）不为 None 且 time.time() 大于它时返回 True，否则返回 False。
-    def expired(self) -> bool:
-        return self.expires_at is not None and time.time() > self.expires_at
-
-    @staticmethod
-# 生效条件：allow 为 None 时返回 True（未声明=不限制），allow 非 None 时返回 "'*' in allow 或 name in allow" 的布尔结果。
-    def _in_scope(allow, name: str) -> bool:
-        if allow is None:                     # 未声明 = 不限制（兼容直接构造）
-            return True
-        return "*" in allow or name in allow
-
-# 生效条件：layer 为假值（None/空串）时以 "knowledge" 参与判定，返回 self._in_scope(self.layers_allow, layer or "knowledge") 的结果。
-    def allows_layer(self, layer: str) -> bool:
-        return self._in_scope(self.layers_allow, layer or "knowledge")
-
-# 生效条件：op 为假值（None/空串）时以 "" 参与，先经 strip().lower() 归一化，返回 self._in_scope(self.ops_allow, (op or "").strip().lower()) 的结果。
-    def allows_op(self, op: str) -> bool:
-        return self._in_scope(self.ops_allow, (op or "").strip().lower())
-
-    # ---------- 强制校验（越权即 AccessDenied） ----------
-
-# 生效条件：无 required 形参或模块级常量前置，当 self.expired()（来自 __init__ 的 expires_at 与当前时间比较）为 True 时抛 AccessDenied，否则无操作返回 None。
-    def _require_live(self):
-        if self.expired():
-            raise AccessDenied(f"actor={self.actor} 令牌已过期")
-
-# 生效条件：先调用 self._require_live()（过期则抛 AccessDenied）；再要求 self.allows_op(op) 为 True，否则抛 AccessDenied。
-    def require_op(self, op: str):
-        self._require_live()
-        if not self.allows_op(op):
-            raise AccessDenied(
-                f"角色 {self.role} 无权执行 op={op}（作用域 "
-                f"{list(self.ops_allow) if self.ops_allow is not None else '不限'}）")
-
-# 生效条件：依次要求 self._require_live() 未抛异常、self.theory_ok 为 True、self.can_write 为 True、self.allows(sensitivity) 为 True；任一不满足则抛 AccessDenied。
-    def require_write(self, sensitivity: str):
-        self._require_live()
-        if not self.theory_ok:
-            raise AccessDenied(
-                "版本层校验未通过（theory_ok=False）：全部写操作被拒，"
-                "仅保留 theory 修复入口")
-        if not self.can_write:
-            raise AccessDenied(f"actor={self.actor} 无写权限")
-        if not self.allows(sensitivity):
-            raise AccessDenied(
-                f"写入敏感度 {sensitivity} 超出 clearance {self.clearance}")
-
-# 生效条件：先要求 self.require_write(sensitivity) 未抛异常；随后将形参 layer 为假值（None/空串）时按 "knowledge" 处理，并要求 self.allows_layer(layer) 为 True，否则抛 AccessDenied。
-    def require_layer_write(self, layer: str, sensitivity: str):
-        """写层校验：密级 + 层白名单双闸门（核心私有内容不可越权修改）。"""
-        self.require_write(sensitivity)
-        layer = layer or "knowledge"
-        if not self.allows_layer(layer):
-            raise AccessDenied(
-                f"角色 {self.role} 无权写入 {layer} 层"
-                f"（可写层 {list(self.layers_allow) if self.layers_allow is not None else '不限'}）")
-
-# 生效条件：要求 self._require_live() 未抛异常、self.theory_ok 为 True、self.can_admin 为 True 时通过；否则抛 AccessDenied（消息用形参 op 标记操作）。
-    def require_admin(self, op: str):
-        self._require_live()
-        if not self.theory_ok:
-            raise AccessDenied(
-                f"版本层校验未通过（theory_ok=False）：管理操作 {op} 被拒")
-        if not self.can_admin:
-            raise AccessDenied(f"actor={self.actor} 无管理权限（{op}）")
-
-# 生效条件：无 required 形参或模块级常量前置，返回包含 self 各属性（tenant/actor/clearance/can_write/can_admin/session/harness/unit/role/token_id/parent/auth_mode/expires_at/theory_ok/theory_version 及 layers_allow/ops_allow）的 dict；其中 layers_allow/ops_allow 为 None 时值为 None，否则 list 化。
-    def as_dict(self):
-        return {"tenant": self.tenant, "actor": self.actor,
-                "clearance": self.clearance, "can_write": self.can_write,
-                "can_admin": self.can_admin, "session": self.session,
-                "harness": self.harness, "unit": self.unit,
-                "role": self.role, "token_id": self.token_id,
-                "parent": self.parent, "auth_mode": self.auth_mode,
-                "expires_at": self.expires_at,
-                "theory_ok": self.theory_ok,
-                "theory_version": self.theory_version,
-                "layers_allow": (None if self.layers_allow is None
-                                 else list(self.layers_allow)),
-                "ops_allow": (None if self.ops_allow is None
-                              else list(self.ops_allow))}
-
-# 生效条件：无前置；仅返回 tenant/actor/role/clearance/write/admin 的短摘要用于日志与排障，不含 token、密钥材料与能力白名单明细；
-    def __repr__(self):
-        return (f"Principal(tenant={self.tenant!r}, actor={self.actor!r}, "
-                f"role={self.role!r}, clearance={self.clearance!r}, "
-                f"write={self.can_write}, admin={self.can_admin})")
-
-
-# 生效条件：path 为 None 时落至 os.path.expanduser("~") 下的 .mdcg/_tenants.json，path 非 None（含空串）时按传入值使用，并在构造内以 self._load() 的返回填充 self.data。
-class TenantRegistry:
-    """租户注册表：tenant → {root, clearance_cap, description}。
-
-    默认位置：<registry_dir>/_tenants.json（默认 ~/.mdcg/）。
-    设计意图：私有租户的 root 指向仓库外目录，开源仓库里只放 public 租户的根。
-    """
-
-# 生效条件：形参 path 为 None 时取 ~/.mdcg/_tenants.json，否则取 path；self.data 初始化为 _load() 结果（self.path 经 os.path.exists 为真且 JSON 解析为 dict 时取该 dict，否则回落 {"schema":1,"tenants":{}}）。
-    def __init__(self, path: str = None):
-        if path is None:
-            path = os.path.join(os.path.expanduser("~"), ".mdcg", "_tenants.json")
-        self.path = path
-        self.data = self._load()
-
-# 生效条件：当 self.path 经 os.path.exists 为真且内容可解析为 dict 时返回该 dict；否则（os.path.exists 为假、非 dict、JSON 解析失败或 OSError）返回 {"schema":1,"tenants":{}}。
-    def _load(self):
-        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
-        return {"schema": 1, "tenants": {}}
-
-# 生效条件：无 required 形参或模块级常量前置，将 self.data 以 JSON 写入 self.path + ".tmp"，随后 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)
-
-# 生效条件：形参 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,
-                 description: str = ""):
-        _rank(clearance_cap)
-        self.data["tenants"][tenant] = {
-            "root": os.path.abspath(root),
-            "clearance_cap": clearance_cap,
-            "description": description,
-            "registered_at": time.time(),
-        }
-        self._save()
-        return self.data["tenants"][tenant]
-
-# 生效条件：self.data 含 "tenants" 键（否则 KeyError），且该映射中存在形参 tenant 时返回其值，否则返回 None（.get 缺键回落 None，键存在值为 None 也返回 None）。
-    def get(self, tenant: str):
-        return self.data["tenants"].get(tenant)
-
-# 生效条件：self.get(tenant) 返回真值（非 None/空 dict 等）时返回 t["root"]（若 t 无 "root" 键则 KeyError）；返回假值时返回 None。
-    def root_of(self, tenant: str):
-        t = self.get(tenant)
-        return t["root"] if t else None
-
-# 生效条件：self.get(tenant) 返回真值时返回 t["clearance_cap"]（缺键则 KeyError）；返回假值时返回模块级常量 DEFAULT_SENSITIVITY。
-    def cap_of(self, tenant: str):
-        t = self.get(tenant)
-        return t["clearance_cap"] if t else DEFAULT_SENSITIVITY
-
-# 生效条件：self.data 含 "tenants" 键时返回其浅拷贝 dict(self.data["tenants"])；该键缺失时按 self.data["tenants"] 取值会 KeyError，无默认回落。
-    def all(self):
-        return dict(self.data["tenants"])
-
-# 生效条件：cap 由 cap_of(tenant) 决定（形参 tenant 未注册时取模块级常量 DEFAULT_SENSITIVITY）；clearance 为假值（含 None/空串）时 want 取 cap，否则先取 clearance，再在 _rank(want) > _rank(cap) 时夹紧为 cap；actor 为假值时取 tenant；返回 Principal(...)。
-    def principal_for(self, tenant: str, actor: str = None, clearance: str = None,
-                      can_write: bool = True, can_admin: bool = False,
-                      session: str = None) -> Principal:
-        """按租户上限夹紧 clearance（调用方不能超过租户上限）。"""
-        cap = self.cap_of(tenant)
-        want = clearance or cap
-        if _rank(want) > _rank(cap):
-            want = cap
-        return Principal(tenant=tenant, actor=actor or tenant, clearance=want,
+# -*- coding: utf-8 -*-
+"""md_cg · 进程/权限模型（记忆 OS #2）
+
+关键动机：**灵枢是开源仓库，而记忆很大一部分是私有内容**。因此权限模型必须
+支持「公开知识」与「私有记忆」的物理与逻辑隔离：
+
+  ① 物理隔离：租户（tenant）各自一个根目录。public 租户的根可落在开源仓库内，
+     private 租户的根必须落在仓库外（如 ~/.mdcg/private/）。
+  ② 逻辑隔离：每个节点带 sensitivity（public < internal < private < secret）；
+     每个调用方（Principal）带 clearance，只能读写 ≤ clearance 的节点。
+  ③ 硬规则：secret 节点对 clearance < secret 的调用方**写入即拒**（对齐 noema
+     「secret 候选自动拒绝」）；写入高于自身 clearance 的敏感度 → 拒绝。
+
+零第三方依赖。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+
+SENSITIVITY_ORDER = ("public", "internal", "private", "secret")
+DEFAULT_SENSITIVITY = "internal"
+
+
+class AccessDenied(Exception):
+    """权限拒绝（读/写/管理）。"""
+
+
+# 生效条件：形参 level 为模块级常量 SENSITIVITY_ORDER 中的元素时返回其下标，否则抛 AccessDenied。
+def _rank(level: str) -> int:
+    try:
+        return SENSITIVITY_ORDER.index(level)
+    except ValueError:
+        raise AccessDenied(f"未知敏感度/密级：{level}") from None
+
+
+# 生效条件：全部形参均可省略、clearance 默认取模块常量 DEFAULT_SENSITIVITY，构造时先经 _rank(clearance) 校验，随后 session 为假值（含空串）回落为 sess_+uuid 十二位、role 假值回落 "system"、expires_at 为假值（含 0）置 None、layers_allow/ops_allow 为 None 时保持 None 否则转 tuple、theory_ok 经 bool() 转换。
+class Principal:
+    """调用方身份（一次会话一个）。
+
+    tenant        —— 租户（决定根目录）
+    actor         —— 调用者标识（写入审计）
+    clearance     —— 最高可读/可写敏感度
+    can_write     —— 是否允许写
+    can_admin     —— 是否允许管理操作（forget/restore/review_decide）
+    session       —— 会话 id（进程/会话模型：每次连接一个）
+    harness       —— 承载端标识（dsh/zcode/codebuddy…；仅归因，不参与授权）
+    unit          —— 单元分工（record/reflect/verify/output/sustain；仅归因）
+                     注：MCP 请求级参数 `as_unit` 会经 `tokens.narrowed_principal`
+                     产出一次性 Principal——其 role/layers/ops 取自该单元 spec、unit
+                     记为执行单元。那是**单次调用的临时身份**，不改变本字段的归因
+                     定位（见 `mcp_server.call_tool`）。
+
+    令牌扩展（由 `tokens.verify_token` 填充；直接构造时为 None = 不限制）：
+    role          —— 角色（designer/reflection/verifier/recorder/output/sustain/guest）
+    token_id      —— 令牌 id（可追溯到签发记录）
+    parent        —— 派生来源令牌 id（权职分离的委派链）
+    expires_at    —— 过期时间戳（None = 不过期）
+    layers_allow  —— 可写层白名单（None = 不限制；"*" = 全部）
+    ops_allow     —— 可执行 op 白名单（同上）
+    auth_mode     —— direct（直接构造）/ token / legacy_env / anonymous
+
+    版本层扩展（蜂群互联层0，由 `theory.check` 填充）：
+    theory_ok      —— 版本声明是否合法；False 时**全部写/管理操作被拒**（只读降级）
+    theory_version —— 当前声明的协议版本（审计与 whoami 用）
+    """
+
+# 生效条件：clearance 须为模块级常量 SENSITIVITY_ORDER 成员（否则 _rank 抛 AccessDenied），session 为假值（含 None/空串）时生成 sess_ 随机串，expires_at 为假值（含 None/0）时存 None 否则 float(expires_at)，layers_allow/ops_allow 为 None 时存 None 否则 tuple 化。
+    def __init__(self, tenant: str = "default", actor: str = "system",
+                 clearance: str = DEFAULT_SENSITIVITY, can_write: bool = True,
+                 can_admin: bool = False, session: str = None,
+                 harness: str = None, unit: str = None,
+                 role: str = None, token_id: str = None, parent: str = None,
+                 expires_at: float = None, layers_allow=None, ops_allow=None,
+                 auth_mode: str = "direct", theory_ok: bool = True,
+                 theory_version: str = None):
+        _rank(clearance)                      # 校验
+        self.tenant = tenant
+        self.actor = actor
+        self.clearance = clearance
+        self.can_write = can_write
+        self.can_admin = can_admin
+        self.session = session or ("sess_" + uuid.uuid4().hex[:12])
+        # 归因维度（嵌套身份）：只入审计（_audit/_recent），不参与权限判定。
+        # 权限域仍由令牌记录决定（tokens.ROLE_SPECS），与 harness/unit 无关。
+        # 受控例外：MCP 请求级 `as_unit` 收窄（tokens.narrowed_principal）产出的是
+        # 一次性 Principal，其 role/allow 取自单元 spec——**只做减法**（与 owner
+        # 求交 + 管理权恒 False），故不构成本字段「参与授权」的先例。
+        self.harness = harness
+        self.unit = unit
+        self.role = (role or "system")
+        self.token_id = token_id
+        self.parent = parent
+        self.expires_at = float(expires_at) if expires_at else None
+        self.layers_allow = None if layers_allow is None else tuple(layers_allow)
+        self.ops_allow = None if ops_allow is None else tuple(ops_allow)
+        self.auth_mode = auth_mode
+        self.theory_ok = bool(theory_ok)
+        self.theory_version = theory_version
+
+    # ---------- 基础判定 ----------
+
+# 生效条件：形参 sensitivity 与 self.clearance 均可被 _rank 映射到模块级常量 SENSITIVITY_ORDER 中时，返回前者排名是否不高于后者；任一不在其中则 _rank 抛 AccessDenied。
+    def allows(self, sensitivity: str) -> bool:
+        """clearance 是否覆盖该敏感度（可读/可写）。"""
+        return _rank(sensitivity) <= _rank(self.clearance)
+
+# 生效条件：无 required 形参或模块级常量前置，仅当 self.expires_at（来自 __init__ 的 expires_at）不为 None 且 time.time() 大于它时返回 True，否则返回 False。
+    def expired(self) -> bool:
+        return self.expires_at is not None and time.time() > self.expires_at
+
+    @staticmethod
+# 生效条件：allow 为 None 时返回 True（未声明=不限制），allow 非 None 时返回 "'*' in allow 或 name in allow" 的布尔结果。
+    def _in_scope(allow, name: str) -> bool:
+        if allow is None:                     # 未声明 = 不限制（兼容直接构造）
+            return True
+        return "*" in allow or name in allow
+
+# 生效条件：layer 为假值（None/空串）时以 "knowledge" 参与判定，返回 self._in_scope(self.layers_allow, layer or "knowledge") 的结果。
+    def allows_layer(self, layer: str) -> bool:
+        return self._in_scope(self.layers_allow, layer or "knowledge")
+
+# 生效条件：op 为假值（None/空串）时以 "" 参与，先经 strip().lower() 归一化，返回 self._in_scope(self.ops_allow, (op or "").strip().lower()) 的结果。
+    def allows_op(self, op: str) -> bool:
+        return self._in_scope(self.ops_allow, (op or "").strip().lower())
+
+    # ---------- 强制校验（越权即 AccessDenied） ----------
+
+# 生效条件：无 required 形参或模块级常量前置，当 self.expired()（来自 __init__ 的 expires_at 与当前时间比较）为 True 时抛 AccessDenied，否则无操作返回 None。
+    def _require_live(self):
+        if self.expired():
+            raise AccessDenied(f"actor={self.actor} 令牌已过期")
+
+# 生效条件：先调用 self._require_live()（过期则抛 AccessDenied）；再要求 self.allows_op(op) 为 True，否则抛 AccessDenied。
+    def require_op(self, op: str):
+        self._require_live()
+        if not self.allows_op(op):
+            raise AccessDenied(
+                f"角色 {self.role} 无权执行 op={op}（作用域 "
+                f"{list(self.ops_allow) if self.ops_allow is not None else '不限'}）")
+
+# 生效条件：依次要求 self._require_live() 未抛异常、self.theory_ok 为 True、self.can_write 为 True、self.allows(sensitivity) 为 True；任一不满足则抛 AccessDenied。
+    def require_write(self, sensitivity: str):
+        self._require_live()
+        if not self.theory_ok:
+            raise AccessDenied(
+                "版本层校验未通过（theory_ok=False）：全部写操作被拒，"
+                "仅保留 theory 修复入口")
+        if not self.can_write:
+            raise AccessDenied(f"actor={self.actor} 无写权限")
+        if not self.allows(sensitivity):
+            raise AccessDenied(
+                f"写入敏感度 {sensitivity} 超出 clearance {self.clearance}")
+
+# 生效条件：先要求 self.require_write(sensitivity) 未抛异常；随后将形参 layer 为假值（None/空串）时按 "knowledge" 处理，并要求 self.allows_layer(layer) 为 True，否则抛 AccessDenied。
+    def require_layer_write(self, layer: str, sensitivity: str):
+        """写层校验：密级 + 层白名单双闸门（核心私有内容不可越权修改）。"""
+        self.require_write(sensitivity)
+        layer = layer or "knowledge"
+        if not self.allows_layer(layer):
+            raise AccessDenied(
+                f"角色 {self.role} 无权写入 {layer} 层"
+                f"（可写层 {list(self.layers_allow) if self.layers_allow is not None else '不限'}）")
+
+# 生效条件：要求 self._require_live() 未抛异常、self.theory_ok 为 True、self.can_admin 为 True 时通过；否则抛 AccessDenied（消息用形参 op 标记操作）。
+    def require_admin(self, op: str):
+        self._require_live()
+        if not self.theory_ok:
+            raise AccessDenied(
+                f"版本层校验未通过（theory_ok=False）：管理操作 {op} 被拒")
+        if not self.can_admin:
+            raise AccessDenied(f"actor={self.actor} 无管理权限（{op}）")
+
+# 生效条件：无 required 形参或模块级常量前置，返回包含 self 各属性（tenant/actor/clearance/can_write/can_admin/session/harness/unit/role/token_id/parent/auth_mode/expires_at/theory_ok/theory_version 及 layers_allow/ops_allow）的 dict；其中 layers_allow/ops_allow 为 None 时值为 None，否则 list 化。
+    def as_dict(self):
+        return {"tenant": self.tenant, "actor": self.actor,
+                "clearance": self.clearance, "can_write": self.can_write,
+                "can_admin": self.can_admin, "session": self.session,
+                "harness": self.harness, "unit": self.unit,
+                "role": self.role, "token_id": self.token_id,
+                "parent": self.parent, "auth_mode": self.auth_mode,
+                "expires_at": self.expires_at,
+                "theory_ok": self.theory_ok,
+                "theory_version": self.theory_version,
+                "layers_allow": (None if self.layers_allow is None
+                                 else list(self.layers_allow)),
+                "ops_allow": (None if self.ops_allow is None
+                              else list(self.ops_allow))}
+
+# 生效条件：无前置；仅返回 tenant/actor/role/clearance/write/admin 的短摘要用于日志与排障，不含 token、密钥材料与能力白名单明细；
+    def __repr__(self):
+        return (f"Principal(tenant={self.tenant!r}, actor={self.actor!r}, "
+                f"role={self.role!r}, clearance={self.clearance!r}, "
+                f"write={self.can_write}, admin={self.can_admin})")
+
+
+# 生效条件：path 为 None 时落至 os.path.expanduser("~") 下的 .mdcg/_tenants.json，path 非 None（含空串）时按传入值使用，并在构造内以 self._load() 的返回填充 self.data。
+class TenantRegistry:
+    """租户注册表：tenant → {root, clearance_cap, description}。
+
+    默认位置：<registry_dir>/_tenants.json（默认 ~/.mdcg/）。
+    设计意图：私有租户的 root 指向仓库外目录，开源仓库里只放 public 租户的根。
+    """
+
+# 生效条件：形参 path 为 None 时取 ~/.mdcg/_tenants.json，否则取 path；self.data 初始化为 _load() 结果（self.path 经 os.path.exists 为真且 JSON 解析为 dict 时取该 dict，否则回落 {"schema":1,"tenants":{}}）。
+    def __init__(self, path: str = None):
+        if path is None:
+            path = os.path.join(os.path.expanduser("~"), ".mdcg", "_tenants.json")
+        self.path = path
+        self.data = self._load()
+
+# 生效条件：当 self.path 经 os.path.exists 为真且内容可解析为 dict 时返回该 dict；否则（os.path.exists 为假、非 dict、JSON 解析失败或 OSError）返回 {"schema":1,"tenants":{}}。
+    def _load(self):
+        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
+        return {"schema": 1, "tenants": {}}
+
+# 生效条件：无 required 形参或模块级常量前置，将 self.data 以 JSON 写入 self.path + ".tmp"，随后 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)
+
+# 生效条件：形参 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,
+                 description: str = ""):
+        _rank(clearance_cap)
+        self.data["tenants"][tenant] = {
+            "root": os.path.abspath(root),
+            "clearance_cap": clearance_cap,
+            "description": description,
+            "registered_at": time.time(),
+        }
+        self._save()
+        return self.data["tenants"][tenant]
+
+# 生效条件：self.data 含 "tenants" 键（否则 KeyError），且该映射中存在形参 tenant 时返回其值，否则返回 None（.get 缺键回落 None，键存在值为 None 也返回 None）。
+    def get(self, tenant: str):
+        return self.data["tenants"].get(tenant)
+
+# 生效条件：self.get(tenant) 返回真值（非 None/空 dict 等）时返回 t["root"]（若 t 无 "root" 键则 KeyError）；返回假值时返回 None。
+    def root_of(self, tenant: str):
+        t = self.get(tenant)
+        return t["root"] if t else None
+
+# 生效条件：self.get(tenant) 返回真值时返回 t["clearance_cap"]（缺键则 KeyError）；返回假值时返回模块级常量 DEFAULT_SENSITIVITY。
+    def cap_of(self, tenant: str):
+        t = self.get(tenant)
+        return t["clearance_cap"] if t else DEFAULT_SENSITIVITY
+
+# 生效条件：self.data 含 "tenants" 键时返回其浅拷贝 dict(self.data["tenants"])；该键缺失时按 self.data["tenants"] 取值会 KeyError，无默认回落。
+    def all(self):
+        return dict(self.data["tenants"])
+
+# 生效条件：cap 由 cap_of(tenant) 决定（形参 tenant 未注册时取模块级常量 DEFAULT_SENSITIVITY）；clearance 为假值（含 None/空串）时 want 取 cap，否则先取 clearance，再在 _rank(want) > _rank(cap) 时夹紧为 cap；actor 为假值时取 tenant；返回 Principal(...)。
+    def principal_for(self, tenant: str, actor: str = None, clearance: str = None,
+                      can_write: bool = True, can_admin: bool = False,
+                      session: str = None) -> Principal:
+        """按租户上限夹紧 clearance（调用方不能超过租户上限）。"""
+        cap = self.cap_of(tenant)
+        want = clearance or cap
+        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)