@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/routing.py

@@ -29,6 +29,7 @@ _SKELETON_TAIL = re.compile(r"(知识点)?内容\s*[（(]按骨架填充[)）]\s
 ORPHAN = "orphan"
 
 
+# 生效条件：raw 为真值时按 NFKC 归一化并 strip，最多 3 轮剥离 _INSTANCE_TAIL（无变化即停）、再剥 _SKELETON_TAIL、空白转下划线后返回；raw 为假值（None/空串）或处理后为空串时返回 ORPHAN。
 def normalize_domain(raw: str) -> str:
     """把自由文本的域描述归一化成稳定的短键。
 
@@ -50,6 +51,7 @@ def normalize_domain(raw: str) -> str:
     return s or ORPHAN
 
 
+# 生效条件：tags 为真值时取其中首个 str(t) 以 "domain:" 开头的项，返回其前缀后内容的 normalize_domain 结果；无此标签且 condition_space 为真值时返回 normalize_domain(condition_space.get("observation_position"))（缺键即 None 归一为 ORPHAN）；tags 为假值且 condition_space 为假值时返回 ORPHAN。
 def route_key(condition_space: dict = None, tags=None) -> str:
     """导出条件路由键。优先级：tags 的 domain: > observation_position 归一化 > orphan。
 
@@ -65,6 +67,7 @@ def route_key(condition_space: dict = None, tags=None) -> str:
     return ORPHAN
 
 
+# 生效条件：key 等于 ORPHAN 时原样返回 ORPHAN；否则返回 "cond_" + 把 key 中非[\w中文-]字符替换为下划线并截前 24 字符的串 + "_" + key 的 sha256（utf-8）前 8 位十六进制。
 def bucket_dir(key: str) -> str:
     """路由键 → 目录名。中文键保留可读前缀 + 短哈希，避免文件系统非法字符/超长。"""
     if key == ORPHAN:
@@ -115,6 +118,7 @@ BIG_DOMAINS = {
 }
 
 
+# 生效条件：terms 为真值时对 BIG_DOMAINS 每个大域统计命中词数，最高分为 0 或 terms 为假值（None/空）时返回 None，否则返回最高分大域名（并列取 BIG_DOMAINS 迭代序首个最高分）。
 def big_domain_classify(terms) -> str | None:
     """阶段 1：14 大域并行打分 → 收敛到 top-1。
 
@@ -137,6 +141,7 @@ def big_domain_classify(terms) -> str | None:
     return best[0]
 
 
+# 生效条件：terms 为假值（None/空）时返回 {每个 BIG_DOMAINS 域: 0}；terms 为真值时返回 {大域: 该域词表命中 terms 中词的个数}。
 def big_domain_score_breakdown(terms) -> dict:
     """暴露打分明细，便于审计与回归测试。"""
     if not terms:
@@ -156,6 +161,7 @@ def big_domain_score_breakdown(terms) -> dict:
 # 老函数保持不动 → P0/P1 基线可比性不受影响；新函数只供新路径（fuzzy）使用。
 # ---------------------------------------------------------------------------
 
+# 生效条件：term 或 word 为假值（None/空串）返回 0.0；相等返回 1.0；word 是 term 子串返回 len(word)/len(term)；term 是 word 子串返回 len(term)/len(word)；二者无包含关系返回 0.0。
 def membership(term: str, word: str) -> float:
     """词 term 对代表词 word 的隶属度（0.0~1.0，越接近 1 越隶属）。
 
@@ -175,6 +181,7 @@ def membership(term: str, word: str) -> float:
     return 0.0
 
 
+# 生效条件：无入参，恒遍历模块级常量 BIG_DOMAINS 的各域代表词表，返回 {代表词: 包含该词的域个数}。
 def _build_domain_df() -> dict:
     """代表词 → 覆盖它的大域数（IDF 的分母）。"""
     df = {}
@@ -187,6 +194,7 @@ def _build_domain_df() -> dict:
 _DOMAIN_DF = _build_domain_df()
 
 
+# 生效条件：恒返回 math.log(1.0 + len(BIG_DOMAINS) / _DOMAIN_DF.get(word, 1))，即 word 在 _DOMAIN_DF 中取其覆盖域数，缺键（含任何未登记值）时按 _DOMAIN_DF.get 的默认 1 代入。
 def domain_idf(word: str) -> float:
     """代表词的区分度权重：log(1 + 大域总数 / 覆盖它的大域数)。
 
@@ -196,6 +204,7 @@ def domain_idf(word: str) -> float:
     return math.log(1.0 + len(BIG_DOMAINS) / _DOMAIN_DF.get(word, 1))
 
 
+# 生效条件：terms 是 dict 时以其条目（键 str(t) 以 "__" 开头者剔除、值为 float）为词权重并忽略 weights，否则以 wmap.get(t, 1.0) 为权重（weights 为假值即 None/空 dict 时 wmap 为空、全部权重取 1.0，terms 为假值则词集为空）；逐域累加「词权重 × 该词在域词表内最大（membership × domain_idf）」，权重 <=0 的词跳过，返回 {大域: round(得分, 6)}。
 def big_domain_score_weighted(terms, weights=None) -> dict:
     """阶段 1（分级版）：14 大域并行打分，按「隶属度 × IDF」加权。
 
@@ -226,6 +235,7 @@ def big_domain_score_weighted(terms, weights=None) -> dict:
     return out
 
 
+# 生效条件：以 terms、weights 计算各域加权得分（terms 为假值时各域均为 0.0），得分为空或最高分 <= min_score（默认 0.0）时返回 None，否则返回最高分大域名。
 def big_domain_classify_weighted(terms, weights=None, min_score: float = 0.0):
     """阶段 1（分级版）收敛到 top-1；全部低于 min_score → None。"""
     scores = big_domain_score_weighted(terms, weights)
@@ -237,6 +247,7 @@ def big_domain_classify_weighted(terms, weights=None, min_score: float = 0.0):
     return best[0]
 
 
+# 生效条件：a 或 b 为假值（None/空串）返回 0.0；相等返回 1.0；a 是 b 子串返回 len(a)/len(b)；b 是 a 子串返回 len(b)/len(a)；否则按二者二元组字符集合的 Jaccard 返回 len(ga & gb)/len(ga | gb)，任一集合为空（如单字符键）时返回 0.0。
 def domain_similarity(a: str, b: str) -> float:
     """两个归一化域键的相似度（0~1）：相同 1.0；包含取长度比；否则二元组 Jaccard。
 
@@ -258,6 +269,7 @@ def domain_similarity(a: str, b: str) -> float:
     return len(ga & gb) / len(ga | gb)
 
 
+# 生效条件：counts 各值之和为 0（含空 dict 与全 0 计数）时返回 {'ok': True, 'reason': 'empty', 'buckets': 0}；否则在最大桶占比 >30%、桶数 >1 且单例桶占比 >50%、期望扫描 >30% 中命中的项写入 problems，返回含 ok(=problems 为空)、buckets、nodes、max_bucket_share、singleton_ratio、expected_scan、problems 的 dict。
 def bucket_health(counts: dict) -> dict:
     """分区健康度自检。分桶键一旦退化（巨桶或碎片化），条件路由就是纸面收益，
     必须在写入侧就能发现，而不是等召回变差才回头查。
@@ -288,3 +300,67 @@ def bucket_health(counts: dict) -> dict:
         "expected_scan": expected_scan,
         "problems": problems,
     }
+
+
+# ---------------------------------------------------------------------------
+# 节点侧大域标签（S1 大域先验收敛的前置元数据）
+#
+# 为何需要：`big_domain_classify` 一直只作用于 **query 侧**（terms），节点侧没有域字段，
+# 于是「14 大域并行打分」算完只能写进 meta（审计偏差 4：先验算出来却当成报告）。
+# 要让大域先验真正参与候选收敛，节点必须在写入时固化自己的域。
+# 口径：与查询侧同一个分类器（BIG_DOMAINS + big_domain_classify），保证两侧同构。
+# ---------------------------------------------------------------------------
+
+# 域词取词：中文（≥2 字）与拉丁词（≥2 字）。词表命中用「包含关系」判定，
+# 故 2 字以上的切口足以覆盖 1~4 字代表词（如「工程」命中「工程师」）。
+DOMAIN_TERM_RE = re.compile(r"[\u4e00-\u9fff]{2,}|[A-Za-z][A-Za-z0-9_]{1,}")
+
+
+# 生效条件：text 为假值（None/空串）时返回 []；否则以 DOMAIN_TERM_RE 取词、按出现顺序去重后返回，
+# 最多 limit 个（limit 为假值/负数时按空处理，返回 []）。
+def domain_terms(text, limit: int = 400) -> list:
+    """从节点正文/标题抽「域词」（供 big_domain_classify 使用）。
+
+    只做最小分词：中文按 ≥2 字连续片段、拉丁按 [A-Za-z][A-Za-z0-9_]+ 取词；
+    去重保序，最多 limit 个（默认 400，避免长文把分类器拖慢）。
+    """
+    if not text or not limit or limit < 1:
+        return []
+    out, seen = [], set()
+    for m in DOMAIN_TERM_RE.finditer(str(text)):
+        w = m.group(0)
+        if w in seen:
+            continue
+        seen.add(w)
+        out.append(w)
+        if len(out) >= limit:
+            break
+    return out
+
+
+# 生效条件：bucket 为假值或等于 ORPHAN 时返回空串；否则去掉 "cond_" 前缀、并当末段为 8 位十六进制哈希时剥掉该段，返回剩余的可读键。
+def bucket_key_readable(bucket: str) -> str:
+    """桶目录名 → 可读键（S1b query 侧桶推断用）：'cond_感知系统_d94e90d2' → '感知系统'。
+
+    与 `bucket_dir` 互逆（丢哈希段）；`orphan`/空值返回空串（S1b 不把 orphan 当键，orphan 恒作兜底）。
+    """
+    if not bucket or bucket == ORPHAN:
+        return ""
+    s = str(bucket)
+    if s.startswith("cond_"):
+        s = s[len("cond_"):]
+    head, sep, tail = s.rpartition("_")
+    if sep and len(tail) == 8 and all(c in "0123456789abcdef" for c in tail):
+        s = head
+    return s
+
+
+# 生效条件：text 为假值或取不到任何域词时返回 None；否则返回 big_domain_classify(domain_terms(text))
+# 的结果（无有效域信号时亦为 None，调用方据此决定是否落域字段）。
+def classify_text(text, limit: int = 400):
+    """正文 → 大域名（节点侧域标签真源）。与查询侧共用 big_domain_classify。
+
+    返回 None 表示「无有效域信号」——此时**不写** big_domain 字段，
+    该节点留在 ORPHAN/兜底池（S1 收敛时必须能被兜底召回，见契约 §3 S1 不变量）。
+    """
+    return big_domain_classify(domain_terms(text, limit))

package/md_cg/scrub.py

@@ -71,6 +71,9 @@ STRATUM_WEIGHTS = {"stale": 0.20, "low_conf": 0.20, "disputed": 0.15,
 CONTAMINATION = {
     "contradiction": ("high", ("weaken", "demote")),
     "expired": ("high", ("weaken", "demote")),
+    # 未生效（双时间轴另一侧，2026-09-19）：**不是错误**——只提示「此刻不适用」，
+    # 故 severity=info、处置仅 hint（不 weaken / 不 demote / 不删）。
+    "not_yet": ("info", ("hint",)),
     "duplicate": ("medium", ("hint",)),
     "orphan_noise": ("low", ("weaken", "demote")),
     "unverified": ("info", ("hint",)),
@@ -82,10 +85,12 @@ SEVERITY_ORDER = {"high": 3, "medium": 2, "low": 1, "info": 0}
 # 工具
 # --------------------------------------------------------------------------
 
+# 生效条件：当 cg 的 index 为真且其 "nodes" 为真时返回该值，否则（cg 无 index、index 为假值、缺 "nodes" 或 "nodes" 为假值）返回 {}；
 def _nodes(cg) -> dict:
     return (getattr(cg, "index", None) or {}).get("nodes") or {}
 
 
+# 生效条件：cg 与 nid 传入后，若 cache 非 None 且 nid 已在 cache 中则直接返回 cache[nid]（即使其值为假值）；否则尝试 cg.get(nid)，异常或返回假值时按空节点处理，再取其中的 "frontmatter" 真值，若为假值则用 {}；cache 非 None 时把结果写入 cache[nid] 后返回；
 def _fm_of(cg, nid, cache=None) -> dict:
     """取节点 frontmatter（带可选缓存）。不可读（缺密钥 / 已删）→ {}。"""
     if cache is not None and nid in cache:
@@ -101,6 +106,7 @@ def _fm_of(cg, nid, cache=None) -> dict:
     return fm
 
 
+# 生效条件：cg.access_counts() 调用成功时返回其结果（访问次数, 最后访问时间）；调用抛出任何 Exception 时返回 ({}, {})；
 def _access(cg):
     """(访问次数, 最后访问时间)：读访问日志，未 compact 的也算。"""
     try:
@@ -109,6 +115,7 @@ def _access(cg):
         return {}, {}
 
 
+# 生效条件：`from . import chain` 成功且 chain.adjacency(cg) 正常返回时返回该 dict，导入或调用抛任何异常时返回 {}。
 def _adjacency(cg) -> dict:
     try:
         from . import chain
@@ -117,6 +124,7 @@ def _adjacency(cg) -> dict:
         return {}
 
 
+# 生效条件：float(ts or 0) 抛 TypeError/ValueError 时返回 0.0，转换后为 0（含 ts 为 0/空串/None 等假值）时返回 0.0，否则返回 (now - ts)/86400.0。
 def _days(ts, now) -> float:
     try:
         ts = float(ts or 0)
@@ -125,6 +133,7 @@ def _days(ts, now) -> float:
     return (now - ts) / 86400.0 if ts else 0.0
 
 
+# 生效条件：调用即返回带 t 与 op 的 rec；写 append_jsonl(os.path.join(cg.root, SCRUB_LOG), rec) 抛任何异常都被吞掉，不影响返回值。
 def _log(cg, op: str, **rec) -> dict:
     rec = dict(rec, t=time.time(), op=op)
     try:
@@ -134,6 +143,7 @@ def _log(cg, op: str, **rec) -> dict:
     return rec
 
 
+# 生效条件：仅当 read_jsonl(cg.root 下 SCRUB_LOG) 的记录 op=="decontaminate" 且 ok 为真时，把 (rec.get("node_id"), rec.get("kind")) 收进返回集合；无此类记录返回空集。
 def _handled(cg) -> set:
     """已处置过的 (node_id, kind)：保证去污染幂等（审计即状态）。"""
     out = set()
@@ -147,6 +157,7 @@ def _handled(cg) -> set:
 # ① 记忆抽查
 # --------------------------------------------------------------------------
 
+# 生效条件：当 cg 的节点/访问/邻接数据可取时，对每个「layer 不在 SELF_LAYERS」的节点（源码仅以 `if layer in SELF_LAYERS: continue` 排除，未要求 layer 非空）按 now、stale_days、unverified_days 判定入池——last 访问时间距今≥stale_days 时入 stale，last 为假值且 created_at 距今≥stale_days 时入 stale，访问计数 acc≥3 入 hot，邻接度 deg==0 且 layer=="contextual" 入 orphan，evidence_count≤0 且 layer=="knowledge" 且 age_d≥unverified_days 入 unverified，evidence_count>0 且 reads<int(max_reads) 且 _fm_of 返回非空前台时按 negative_evidence>0 入 disputed、按 confidence<LOW_CONF（confidence 缺键回落 0.6）入 low_conf（max_reads 为 0 时 int(max_reads)=0，reads<0 恒假，故 disputed/low_conf 不产生），每个节点无条件入 random 池，最后按各池 key 排序返回 pools（片段仅见排序段，未展示抽样阶段）；多分支无法一句话覆盖全部分支。
 def _pool_candidates(cg, *, now, stale_days, unverified_days, max_reads=200):
     """构造各层候选池（不读文件的部分先用索引 + 访问日志）。"""
     nodes = _nodes(cg)
@@ -210,6 +221,7 @@ def _pool_candidates(cg, *, now, stale_days, unverified_days, max_reads=200):
     return pools
 
 
+# 生效条件：strategy=="random" 时直接返回 {"random": int(n)}；strategy=="risk" 时按剔除 hot/random 后的 STRATUM_WEIGHTS 权重分配；其它策略名走全权重分配，两者都把 int(n) 余量补进已存在的 random 键否则补进 stale。
 def _quota(n: int, strategy: str) -> dict:
     if strategy == "random":
         return {"random": int(n)}
@@ -231,6 +243,7 @@ def _quota(n: int, strategy: str) -> dict:
     return out
 
 
+# 生效条件：k<=0 或 pool 为假值（空池）时返回 []，否则取池前 k*3 项后用 random.Random(f"{seed}:{stratum}") 稳定洗牌并返回前 k 项（池长不足 k*3 时对全池洗牌）。
 def _pick(pool, k: int, seed, stratum: str):
     """从池中取 k 个：风险最高的 3k 个入池，再按 seed 稳定洗牌。"""
     if k <= 0 or not pool:
@@ -242,6 +255,7 @@ def _pick(pool, k: int, seed, stratum: str):
     return cand[:k]
 
 
+# 生效条件：strategy 经 str(strategy or "stratified").lower() 后属于 stratified/risk/random 时返回带分层标签的样本（seed 为 None 时取 0，n 为 0 时 picked 为空），否则抛 ValueError。
 def sample(cg, n: int = DEFAULT_SAMPLE, *, strategy: str = "stratified",
            seed=None, stale_days: float = STALE_DAYS,
            unverified_days: float = UNVERIFIED_DAYS,
@@ -284,12 +298,14 @@ def sample(cg, n: int = DEFAULT_SAMPLE, *, strategy: str = "stratified",
 # ② 联想
 # --------------------------------------------------------------------------
 
+# 生效条件：a 或 b 为假值（空集）时返回 0.0，否则返回 len(a & b)/len(a | b)。
 def _jaccard(a: set, b: set) -> float:
     if not a or not b:
         return 0.0
     return len(a & b) / len(a | b)
 
 
+# 生效条件：对 node_id 汇总关系链（chain.walk 出边与入边，max_depth=int(hops)）、子图层级（subgraph.expand 命中项与父索引逐级上溯 int(hops) 层）以及 lexical 为真时的词法近邻（只在 _nodes 前 int(max_scan) 个节点内比 bigram、sim≥min_sim 者），返回按 weight 降序的 items[:int(limit)]。
 def associate(cg, node_id: str, *, hops: int = DEFAULT_HOPS, limit: int = 30,
               lexical: bool = True, min_sim: float = 0.25,
               max_scan: int = MAX_ASSOC_SCAN) -> dict:
@@ -300,6 +316,7 @@ def associate(cg, node_id: str, *, hops: int = DEFAULT_HOPS, limit: int = 30,
     """
     related = {}
 
+# 生效条件：nid 为真且 nid != node_id 时，构造 rec={'node_id':nid,'via':via,'weight':round(float(weight),4),'depth':int(depth)} 并并入 extra；仅当 related 中 nid 不存在或 rec['weight'] 大于已有 weight 时更新 related[nid]；nid 为假或等于 node_id 时直接返回；
     def put(nid, via, weight, depth=1, **extra):
         if not nid or nid == node_id:
             return
@@ -385,13 +402,19 @@ def associate(cg, node_id: str, *, hops: int = DEFAULT_HOPS, limit: int = 30,
 # ③ 去污染：确定性判据
 # --------------------------------------------------------------------------
 
-_EXPIRY_KEYS = ("valid_until", "expires_at", "expire_at", "expiry", "deadline")
+# 已结束键族（2026-09-19 阶段一：补规范名 `effective_until` 与冗余时刻 `expired_at`）。
+# 纪律：`believed_at`（信念时间）**两族都不入**——它既不是「已结束」也不是「尚未开始」，
+# 而是「体系何时确认此条」的取代/审核锚。键族真源见 md_cg/trust.py（FROM_ALIASES/UNTIL_ALIASES），
+# 两侧新增键须同步（交叉守卫 test_validity_filter）。
+_EXPIRY_KEYS = ("effective_until", "valid_until", "expires_at", "expire_at",
+                "expiry", "deadline", "expired_at")
 _SKIP_KEYS = ("功能名", "执行", "条件", "来源", "标签", "状态", "备注", "标题",
               "描述", "name", "id", "title", "layer", "tags", "说明")
 _NEG_WORDS = ("禁止", "不得", "不要", "不能", "切勿", "避免", "不应", "不可")
 _POS_WORDS = ("应当", "建议", "必须", "需要", "可以", "允许", "推荐", "宜")
 
 
+# 生效条件：v 为 bool 返回 None；v 为 int/float 时仅 f>1e8 返回 f 否则 None；str(v or "").strip() 为空返回 None；否则按 "%Y-%m-%dT%H:%M:%S"/"%Y-%m-%d %H:%M:%S"/"%Y-%m-%d" 依次取前 19/19/10 字符尝试解析，全失败后再试 float(s)，>1e8 返回否则 None，float 亦失败返回 None。
 def _to_ts(v):
     """宽松时间解析：秒级时间戳 / ISO / `YYYY-MM-DD`。无法识别 → None。"""
     if isinstance(v, bool):
@@ -415,6 +438,7 @@ def _to_ts(v):
         return None
 
 
+# 生效条件：对 (content or "").splitlines() 的每行去 # 后，先试中文全角 "："、无则试 ":"，切出的键长度在 2–12、值非空且键不在 _SKIP_KEYS 时以 setdefault 记录（每键只留首次出现），无合格行返回 {}。
 def _kv_pairs(content) -> dict:
     """抽 `键：值` 对（中文/英文冒号），跳过结构字段。"""
     out = {}
@@ -432,12 +456,14 @@ def _kv_pairs(content) -> dict:
     return out
 
 
+# 生效条件：c 取 content or ""，含 _NEG_WORDS 任一返回 -1 分量、含 _POS_WORDS 任一返回 +1 分量，结果为两者之和（都不含时为 0）。
 def _polarity(content) -> int:
     c = content or ""
     return (-1 if any(w in c for w in _NEG_WORDS) else 0) + \
            (1 if any(w in c for w in _POS_WORDS) else 0)
 
 
+# 生效条件：按 _EXPIRY_KEYS 顺序遍历 fm，返回首个满足「键在 fm 中且 _to_ts 非 None 且 ts<now」的 (k, fm.get(k))；该键解析为 None 或 ts≥now 时继续检查后续键，全不满足返回 None。
 def _expired(fm, now):
     for k in _EXPIRY_KEYS:
         if k in fm:
@@ -447,6 +473,25 @@ def _expired(fm, now):
     return None
 
 
+# 未生效键（双时间轴的起点，2026-09-19 · 真源 md_cg/trust.py）。
+# 纪律一：`valid_from` **绝不并入 `_EXPIRY_KEYS`**——两者语义相反（「尚未开始」vs
+# 「已经结束」），并入会让「未来才生效」被误判为「已失效」并触发 weaken/demote。
+# 纪律二：`believed_at`（信念时间）同上，**两族都不入**——第三类语义（体系何时确认）。
+_NOT_YET_KEYS = ("valid_from", "valid_since", "effective_from", "starts_at")
+
+
+# 生效条件：按 _NOT_YET_KEYS 顺序遍历 fm，返回首个满足「键在 fm 中且 _to_ts 非 None 且 ts>now」的 (k, fm.get(k))；全不满足返回 None。
+def _not_yet(fm, now):
+    """宽松判定「尚未生效」（与 `_expired` 同口径，方向相反）。"""
+    for k in _NOT_YET_KEYS:
+        if k in fm:
+            ts = _to_ts(fm.get(k))
+            if ts is not None and ts > now:
+                return k, fm.get(k)
+    return None
+
+
+# 生效条件：对 content 取 kv_pairs、bigrams 和 polarity，遍历 related（若 related 为假值则视为空）的前 int(max_compare) 个 r，以 r["node_id"] 调 cg.get；若某 oid 节点可读非空，先在其 content 与 content 的共同键中找到值不同者并返回 {'with':oid,'via':r.get('via'),'why':'同键不同值：...'}；否则若极性乘积 <0 且双方 bigram 非空，且共享 bigram 数 >=3 且 ratio>=0.15，返回 {'with':oid,'via':r.get('via'),'why':'极性相反且共享内容：...'}；全部遍历完无命中则返回 None；
 def _contradiction(cg, content, related, max_compare=10):
     """与同族节点比对：同键不同值 / 极性相反且共享 bigram。"""
     kv_a = _kv_pairs(content)
@@ -476,6 +521,7 @@ def _contradiction(cg, content, related, max_compare=10):
     return None
 
 
+# 生效条件：ids 在 node_ids 为 None 时取索引全部键、为 str 时取单元素列表、否则取 list(node_ids)，limit 为真值时截断为前 int(limit) 个；跳过 layer 在 SELF_LAYERS 的节点和 cg.get 取不到正文的节点，对剩余每个节点按 min_severity 门限累加 expired/unverified/orphan_noise/duplicate/contradiction，返回 ok=无 high 且无 medium 的结果。
 def audit(cg, node_ids=None, *, hops: int = 1, min_severity: str = "info",
           limit=None, unverified_days: float = UNVERIFIED_DAYS,
           lexical: bool = True, min_sim: float = 0.15) -> dict:
@@ -512,6 +558,7 @@ def audit(cg, node_ids=None, *, hops: int = 1, min_severity: str = "info",
         content = node.get("content") or ""
         age_d = _days(fm.get("created_at") or e.get("created_at"), now)
 
+# 生效条件：kind 是 CONTAMINATION 的键（否则 KeyError）且 CONTAMINATION[kind] 取出的 sev 在 SEVERITY_ORDER 中的值（缺键按 0）不小于闭包变量 min_severity 在 SEVERITY_ORDER 中的值（缺键按 0）时，把 {node_id, layer, kind, severity, detail, fix} 用 **extra 覆盖更新后追加到闭包 issues；sev 的值更小则直接 return 不追加（该函数无返回值）。
         def add(kind, detail, **extra):
             sev, actions = CONTAMINATION[kind]
             if SEVERITY_ORDER.get(sev, 0) < SEVERITY_ORDER.get(min_severity, 0):
@@ -525,6 +572,12 @@ def audit(cg, node_ids=None, *, hops: int = 1, min_severity: str = "info",
         if hit:
             add("expired", f"时效已过：{hit[0]}={hit[1]}", evidence=hit[0])
 
+        # 双时间轴另一侧（2026-09-19）：尚未生效**不是错误**——只提示「此刻不适用」，
+        # 处置由 CONTAMINATION["not_yet"] 定为 info 级 + 仅 hint（不 weaken / 不 demote）。
+        ny = _not_yet(fm, now)
+        if ny:
+            add("not_yet", f"尚未生效：{ny[0]}={ny[1]}", evidence=ny[0])
+
         if (layer == "knowledge" and age_d >= unverified_days
                 and int(e.get("evidence_count") or 0) <= 0):
             add("unverified", f"knowledge 层 {age_d:.0f} 天零验证")
@@ -562,6 +615,7 @@ def audit(cg, node_ids=None, *, hops: int = 1, min_severity: str = "info",
             "t": now}
 
 
+# 生效条件：循环 max(1, int(times)) 次调用 cg.verify(nid, "scrub:"+kind+":"+str(detail)[:120], "weakened")，返回最后一次调用结果（times≤0 时按 1 次执行）。
 def _weaken(cg, nid, kind, detail, times=1):
     res = None
     for _ in range(max(1, int(times))):
@@ -569,6 +623,7 @@ def _weaken(cg, nid, kind, detail, times=1):
     return res
 
 
+# 生效条件：kinds 为真且 issue 的 kind 不在其中则跳过；kind 为 duplicate/unverified 记 hint，已出现在 _handled 记 skip，protect.is_protected 为真且 override 为假记 skip_protected，dry_run 为真记 planned；仅 dry_run 为假时对余下 issue 执行 _weaken，并在 demote 为真、severity 为 high 或 low 且当前层非 contextual 时降级到 contextual，返回计数与 actions。
 def decontaminate(cg, node_ids=None, *, kinds=None, dry_run: bool = True,
                   min_severity: str = "medium", hops: int = 1, actor=None,
                   override: bool = False, weaken_times: int = 1,
@@ -650,6 +705,7 @@ def decontaminate(cg, node_ids=None, *, kinds=None, dry_run: bool = True,
 # ④ 校准偏差
 # --------------------------------------------------------------------------
 
+# 生效条件：对 cg 中每个「layer 不在 SELF_LAYERS」且 evidence_count≥int(min_evidence)（min_evidence=0 时该比较恒假而不早退）的节点，若 protect.is_protected 为假或 override 为真，且 cg.get(nid) 未抛异常并返回真值节点，则取 fm.get("confidence", 0.6)（缺键才回落 0.6，键存在为 None/假值不回落）为 old，算出 round(max(0.0, min(0.99, old+float(offset))),4)，与 old 差<1e-9 时跳过，否则写 fm["confidence"] 与 fm["calibration"] 并调用 cg._write_node 成功时 adjusted+1（写回异常被吞掉不计数），返回 (adjusted, skipped)，其中 skipped 只累计「layer 属 SELF_LAYERS」或被 protect 拦下且非 override 的节点。
 def _apply_offset(cg, offset, *, override=False, min_evidence=1):
     nodes = _nodes(cg)
     adjusted = skipped = 0
@@ -686,6 +742,7 @@ def _apply_offset(cg, offset, *, override=False, min_evidence=1):
     return adjusted, skipped
 
 
+# 生效条件：cg 和 apply/override/actor/max_offset/min_evidence 传入后，若 metacognition.calibration(cg) 返回 ok 假，则返回 {'ok':False,'reason':cal.get('reason') or 'insufficient_data',...}；若 ok 真，则用 gap=float(cal.get('gap') or 0.0) 和 max_offset 计算 offset=round(max(-max_offset,min(max_offset,-gap)),4)，对 cal.get('bins') or [] 中 accuracy 非 None 的 bin 生成 bins_bias 并排序；仅当 apply 为真且 abs(offset)>1e-9 时调用 _apply_offset(cg,offset,override=override,min_evidence=min_evidence) 并写日志，最后返回 ok True 及 verdict/gap/建议 offset 等字段；
 def calibrate(cg, *, apply: bool = False, override: bool = False, actor=None,
               max_offset: float = MAX_OFFSET, min_evidence: int = 1) -> dict:
     """校准偏差：自报置信 vs 实测正确率 → 偏置建议（`apply=True` 才写回）。"""
@@ -734,6 +791,7 @@ def calibrate(cg, *, apply: bool = False, override: bool = False, actor=None,
 # 一轮完整自净 + 审计
 # --------------------------------------------------------------------------
 
+# 生效条件：cg 与 n/seed/dry_run/hops/strategy/apply_calibration/actor 传入后，按 n 与 strategy、seed 调 sample；对 sample 结果前 8 个 node_id 按 hops 调 associate；按 dry_run/hops/actor 调 decontaminate；按 apply_calibration/actor 调 calibrate；若 decontaminate 的 audit.issues 中存在 severity 为 high 或 medium 的项则 out.ok 为 False，否则为 True，并返回含 sample/associate/audit/decontaminate/calibration/t 的 out；
 def sweep(cg, *, n: int = DEFAULT_SAMPLE, seed=None, dry_run: bool = True,
           hops: int = DEFAULT_HOPS, strategy: str = "stratified",
           apply_calibration: bool = False, actor=None) -> dict:
@@ -758,11 +816,13 @@ def sweep(cg, *, n: int = DEFAULT_SAMPLE, seed=None, dry_run: bool = True,
     return out
 
 
+# 生效条件：返回 cg.root 下 SCRUB_LOG 的全部记录条数 n 与 recs[-int(limit):]（limit=0 时切片为 recs[0:] 即返回全部记录）。
 def history(cg, limit: int = 100) -> dict:
     recs = list(read_jsonl(os.path.join(cg.root, SCRUB_LOG)))
     return {"n": len(recs), "records": recs[-int(limit):]}
 
 
+# 生效条件：读取 cg.root 下 SCRUB_LOG 的 JSONL 记录，过滤 op=="sweep" 得 sweeps、op=="decontaminate" 且 ok 为真得 decs；last 为 sweeps 最后一项或 None；返回 {'sweeps':len(sweeps),'decontaminated':len(decs),'last_sweep':last 的 t/n_issues/n_high_medium/applied/dry_run/calibration 或 None}；
 def summary(cg) -> dict:
     """给 health_os / 自维持循环用的只读摘要。"""
     recs = list(read_jsonl(os.path.join(cg.root, SCRUB_LOG)))
@@ -779,6 +839,7 @@ def summary(cg) -> dict:
                            if last else None)}
 
 
+# 生效条件：无入参调用即返回固定的 actions 列表、STRATA 列表、CONTAMINATION 映射（每项取 severity 与 actions）与 STALE_DAYS/UNVERIFIED_DAYS/LOW_CONF/ORPHAN_IMPORTANCE/MAX_OFFSET 阈值字典。
 def catalog() -> dict:
     return {"actions": ["sample", "associate", "audit", "decontaminate",
                         "calibrate", "sweep", "history", "summary", "catalog"],
@@ -789,4 +850,4 @@ def catalog() -> dict:
                            "unverified_days": UNVERIFIED_DAYS,
                            "low_conf": LOW_CONF,
                            "orphan_importance": ORPHAN_IMPORTANCE,
-                           "max_offset": MAX_OFFSET}}
+                           "max_offset": MAX_OFFSET}}

package/md_cg/security.py

@@ -28,6 +28,7 @@ class AccessDenied(Exception):
     """权限拒绝（读/写/管理）。"""
 
 
+# 生效条件：形参 level 为模块级常量 SENSITIVITY_ORDER 中的元素时返回其下标，否则抛 AccessDenied。
 def _rank(level: str) -> int:
     try:
         return SENSITIVITY_ORDER.index(level)
@@ -35,6 +36,7 @@ def _rank(level: str) -> int:
         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:
     """调用方身份（一次会话一个）。
 
@@ -65,6 +67,7 @@ class Principal:
     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,
@@ -99,31 +102,38 @@ class Principal:
 
     # ---------- 基础判定 ----------
 
+# 生效条件：形参 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):
@@ -131,6 +141,7 @@ class Principal:
                 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:
@@ -143,6 +154,7 @@ class Principal:
             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)
@@ -152,6 +164,7 @@ class Principal:
                 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:
@@ -160,6 +173,7 @@ class Principal:
         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,
@@ -175,12 +189,14 @@ class Principal:
                 "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}。
 
@@ -188,12 +204,14 @@ class TenantRegistry:
     设计意图：私有租户的 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:
@@ -205,6 +223,7 @@ class TenantRegistry:
                 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"
@@ -212,6 +231,7 @@ class TenantRegistry:
             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)
@@ -224,20 +244,25 @@ class TenantRegistry:
         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:
@@ -247,4 +272,4 @@ 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)