@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/sustain.py

@@ -80,16 +80,19 @@ _POLL = 0.2                       # 循环轮询步长（常驻进程 CPU 可忽
 # 心跳
 # --------------------------------------------------------------------------
 
+# 生效条件：d 为真值时返回 d，d 为 None/空串时回落 MDCG_SUSTAIN_DIR，该环境变量也未设或为空串时返回 os.path.join(os.path.expanduser("~"), ".mdcg", "sustain")；
 def net_dir(d: str = None) -> str:
     """心跳戳目录：显式 → MDCG_SUSTAIN_DIR → ~/.mdcg/sustain（仓库外）。"""
     return (d or os.environ.get("MDCG_SUSTAIN_DIR")
             or os.path.join(os.path.expanduser("~"), ".mdcg", "sustain"))
 
 
+# 生效条件：给定必填 name，返回 net_dir(d) 下 heartbeat.<name>.stamp 的拼接路径。
 def stamp_path(name: str, d: str = None) -> str:
     return os.path.join(net_dir(d), f"heartbeat.{name}.stamp")
 
 
+# 生效条件：name 必填，组装含模块常量 STAMP_VERSION 与 task_running 的戳记录、原子写入 stamp_path(name,d) 后返回该 rec。
 def write_stamp(name: str, d: str = None, **extra) -> dict:
     """写一次心跳（原子替换）。extra 会并入戳内容（None 值丢弃）。"""
     rec = {"v": STAMP_VERSION, "name": name, "ts": time.time(),
@@ -104,6 +107,7 @@ def write_stamp(name: str, d: str = None, **extra) -> dict:
     return rec
 
 
+# 生效条件：stamp_path(name, d) 所得路径上 os.path.exists 为真且 json.load 结果为 dict 时，返回该 rec 并附加 age=max(0.0, time.time() - float(rec.get("ts") or 0))；该路径不可读、json.load 抛 ValueError/OSError 或 rec 非 dict 时返回 None；
 def read_stamp(name: str, d: str = None):
     """读心跳戳并附 age（秒）；不存在 / 损坏 → None。"""
     p = stamp_path(name, d)
@@ -120,6 +124,7 @@ def read_stamp(name: str, d: str = None):
     return rec
 
 
+# 生效条件：对 stamp_path(name,d) 执行 os.remove，OSError 被静默忽略，无返回值。
 def clear_stamp(name: str, d: str = None):
     try:
         os.remove(stamp_path(name, d))
@@ -127,6 +132,7 @@ def clear_stamp(name: str, d: str = None):
         pass
 
 
+# 生效条件：age 为 None 返回 'absent'；否则以 factor=working if task_running else 1.0 比较 age 与 interval*warn*factor、interval*dead*factor，分别返回 'ok'/'warning'/'dead'。
 def judge(age, *, interval: float = DEFAULT_BEAT_INTERVAL,
           task_running: bool = False, warn: float = DEFAULT_WARN_FACTOR,
           dead: float = DEFAULT_DEAD_FACTOR,
@@ -146,6 +152,7 @@ def judge(age, *, interval: float = DEFAULT_BEAT_INTERVAL,
     return "dead"
 
 
+# 生效条件：net_dir(d) 可列为目录时遍历 heartbeat.*.stamp 并返回含 age 与 state 的记录列表，否则返回 []。
 def peers(d: str = None):
     """列出本机所有心跳戳（含状态）。"""
     base = net_dir(d)
@@ -171,6 +178,7 @@ DEFAULT_RESTART_COOLDOWN = 300.0   # 同一对端两次拉起的最小间隔（
 DEFAULT_FRESH_TIMEOUT = 60.0       # 拉起后等待对端戳变新鲜的窗口
 
 
+# 生效条件：pid 可转 int 且 >0 时按探活（os.name=='nt' 用 OpenProcess+WaitForSingleObject，否则 os.kill(pid,0)）返回 True，转 int 失败或 pid<=0 或探活失败返回 False。
 def pid_alive(pid) -> bool:
     """进程探活（零第三方依赖）：Windows=OpenProcess+WaitForSingleObject；
     posix=os.kill(pid,0)。pid 无效 / 已退出 / 权限外 → False（诚实）。"""
@@ -199,6 +207,7 @@ def pid_alive(pid) -> bool:
         return False
 
 
+# 生效条件：cmd 为 argv 列表时以 stdout/stderr=DEVNULL、不经 shell 的 subprocess.Popen 拉起（nt 附加 DETACHED|NEW_GROUP creationflags），返回该 Popen 对象。
 def _default_spawner(cmd):
     """分离式拉起：argv 列表、不经 shell、输出弃置（Windows 完全脱离父控制台）。"""
     import subprocess
@@ -209,6 +218,7 @@ def _default_spawner(cmd):
                             stderr=subprocess.DEVNULL, **kw)
 
 
+# 生效条件：root 与 peer 必填，扫描 root/SUSTAIN_LOG（模块常量）返回 op='mutual'、action='restart' 且 detail 以 peer 开头的记录中最大 t，无匹配返回 0.0。
 def _last_mutual_restart(root: str, peer: str) -> float:
     """_sustain.jsonl 里该对端最近一次互维拉起时间（无 → 0.0，审计即状态）。"""
     last = 0.0
@@ -227,6 +237,7 @@ def _last_mutual_restart(root: str, peer: str) -> float:
     return last
 
 
+# 生效条件：cg 与 peer 必填，读对端戳判状态：ok/warning 直接返回 action='none'；dead/absent 时依次按 pid_alive、restart_cooldown、restart_cmd 有无走 alive_but_stale/restart_cooldown/dead_unhandled/拉起并验戳，返回 out。
 def mutual_watch(cg, peer: str, *, restart_cmd=None, d: str = None,
                  interval: float = DEFAULT_BEAT_INTERVAL,
                  restart_cooldown: float = DEFAULT_RESTART_COOLDOWN,
@@ -294,6 +305,7 @@ def mutual_watch(cg, peer: str, *, restart_cmd=None, d: str = None,
     return out
 
 
+# 生效条件：cg 与 peer 必填，分别按 name 与 peer 读戳判状态，仅当自身与对端状态均属 ('dead','absent') 时返回 ok=False、both_dead=True。
 def mutual_status(cg, peer: str, *, d: str = None, name: str = "md_cg",
                   interval: float = DEFAULT_BEAT_INTERVAL) -> dict:
     """互维状态 + 双亡检测：自己也失联时互维不可信 → 显式外部告警语义。"""
@@ -316,6 +328,7 @@ def mutual_status(cg, peer: str, *, d: str = None, name: str = "md_cg",
 # 诊断（只读）
 # --------------------------------------------------------------------------
 
+# 生效条件：root 必填，对模块常量 LAYERS 各层 os.walk 统计以 .md 结尾的文件名个数并返回 n（不解析正文）。
 def _count_node_files(root: str) -> int:
     """轻量统计磁盘节点数（只数文件名，不解析正文）。"""
     n = 0
@@ -325,6 +338,7 @@ def _count_node_files(root: str) -> int:
     return n
 
 
+# 生效条件：root 与 older_than 必填，返回 root 及其 LAYERS 各层下以 '.' 开头、名含 '.tmp-' 且 mtime 早于 now-older_than 的路径列表。
 def _list_stale_temps(root: str, older_than: float):
     now, out = time.time(), []
     bases = [root] + [os.path.join(root, l) for l in LAYERS]
@@ -343,6 +357,7 @@ def _list_stale_temps(root: str, older_than: float):
     return out
 
 
+# 生效条件：root 必填，返回 root 顶层以 .jsonl/.log 结尾且 ends_mid_line 为真的路径列表；root 非目录返回 []。
 def _half_line_logs(root: str):
     """顶层行式日志里末尾不是换行的（写者被杀留下的半截记录）。"""
     out = []
@@ -357,6 +372,7 @@ def _half_line_logs(root: str):
     return out
 
 
+# 生效条件：root/_index_log 可列为目录时返回其中 .log 结尾的文件名列表，否则返回 []。
 def _index_log_shards(root: str):
     d = os.path.join(root, "_index_log")
     if not os.path.isdir(d):
@@ -364,6 +380,7 @@ def _index_log_shards(root: str):
     return [f for f in os.listdir(d) if f.endswith(".log")]
 
 
+# 生效条件：cg 具备 crypto_status 且其返回 unlocked 为假时，返回 cg.index['nodes'] 中 sensitivity 属 crypto.ENCRYPTED_LEVELS 的条目数；属性缺失、调用异常或已解锁时返回 0。
 def _locked_nodes(cg) -> int:
     """加密引擎在「未解锁」状态下被隔离的私有节点数（缺密钥 = 权限事实）。"""
     if not hasattr(cg, "crypto_status"):
@@ -388,6 +405,7 @@ EVOLVE_FIXES = {"ccg_backlog": "consolidate_run",
                 "importance_drift": "importance"}
 
 
+# 生效条件：nodes 与 top 必填，遍历索引条目统计缺 verification_basis 或 has_neg_conditions 的候补数 n、no_basis、no_neg 并取最多 top 个 sample，返回含 proxy=True 与 EVOLVE_FIXES['ccg_backlog'] 的字典。
 def _ccg_backlog(nodes: dict, top: int) -> dict:
     """固化候补量（**索引代理指标**：零读节点文件、确定性、O(N)）。
 
@@ -412,6 +430,7 @@ def _ccg_backlog(nodes: dict, top: int) -> dict:
             "proxy": True, "fix": EVOLVE_FIXES["ccg_backlog"]}
 
 
+# 生效条件：cg 必填，取 cg.index['nodes']（layer 非空时按 layer 过滤），经 weights.recalc(apply=False) 与 _ccg_backlog 汇总，返回 ok=True、readonly=True、dry_run=True 的候选盘点字典。
 def evolution_candidates(cg, *, layer: str = None, top: int = 8,
                          min_delta: float = None) -> dict:
     """演化候选盘点（G7）：**只读、零读节点文件、确定性、不写盘**。
@@ -446,6 +465,7 @@ def evolution_candidates(cg, *, layer: str = None, top: int = 8,
                      "重要性重算为确定性动作（有 rollback）")}
 
 
+# 生效条件：给定 cg 后只读汇总（nodes 取自 cg.index、disk 计数、refindex.check_refs），stale_temp_age 传入 _list_stale_temps；check_heartbeat / check_evolution(evolve_top) / check_provenance(provenance_top) 为真时分别追加对应 issue，返回 ok = 无 severity=="warning" 的 issue 连同 stats。
 def diagnose(cg, *, name: str = "md_cg", stale_temp_age: float = STALE_TEMP_AGE,
              check_heartbeat: bool = True, check_evolution: bool = True,
              evolve_top: int = 5, check_provenance: bool = True,
@@ -575,17 +595,20 @@ def diagnose(cg, *, name: str = "md_cg", stale_temp_age: float = STALE_TEMP_AGE,
 # 自愈
 # --------------------------------------------------------------------------
 
+# 生效条件：path 必填，以 'ab' 模式向该路径追加写入单个换行 b'\n'，无返回值。
 def _seal_half_line(path: str):
     with open(path, "ab") as f:
         f.write(b"\n")
 
 
+# 生效条件：root/op/action 必填，向 root/SUSTAIN_LOG（模块常量）追加一行含 t/op/action/detail(截断 200)/pid 的 JSONL，无返回值。
 def _audit(root: str, op: str, action: str, detail: str = ""):
     append_jsonl(os.path.join(root, SUSTAIN_LOG),
                  {"t": time.time(), "op": op, "action": action,
                   "detail": str(detail)[:200], "pid": os.getpid()})
 
 
+# 生效条件：按 diagnose(cg, name=name, stale_temp_age=stale_temp_age) 的 issues code 集合分派——命中 index_drift/index_orphan 重建索引、ref_stale/ref_dangling 按 ref 重建源索引、index_log_backlog 合并索引分片、stale_temps 清理陈旧临时文件、half_line_logs 修补半截日志；ccg_backlog 仅 allow_evolve=True 且 reflect_fn 非 None 时才 consolidate（否则记 needs_llm），importance_drift 仅 allow_evolve=True 时才重算重要性（否则记 evolve_disabled）；dry_run=True 时各动作只记入 actions 不落盘，返回含 after["ok"]、dry_run、actions、before/after 的 stats 与 t 的 dict；
 def heal(cg, *, name: str = "md_cg", dry_run: bool = False,
          stale_temp_age: float = STALE_TEMP_AGE,
          allow_evolve: bool = False, reflect_fn=None, verify_fn=None) -> dict:
@@ -599,6 +622,7 @@ def heal(cg, *, name: str = "md_cg", dry_run: bool = False,
     root = cg.root
     actions = []
 
+# 生效条件：闭包 dry_run 为真时向 actions 追加 {"code": code, "detail": detail, "applied": False} 并返回；否则调用 fn()，成功追加 applied=True/ok=True，抛异常时追加 applied=True/ok=False 与 error，最后执行 _audit(root, "heal", code, detail)；
     def act(code: str, detail: str, fn):
         if dry_run:
             actions.append({"code": code, "detail": detail, "applied": False})
@@ -624,6 +648,7 @@ def heal(cg, *, name: str = "md_cg", dry_run: bool = False,
     if "stale_temps" in codes:
         paths = _list_stale_temps(root, stale_temp_age)
 
+# 生效条件：对闭包变量 paths 中每个路径尝试 os.remove(p)，单个路径的 OSError 被吞掉后继续处理后续路径；
         def _sweep():
             for p in paths:
                 try:
@@ -643,6 +668,7 @@ def heal(cg, *, name: str = "md_cg", dry_run: bool = False,
         if allow_evolve and reflect_fn is not None:
             from . import consolidate as _cd
 
+# 生效条件：调用时返回 _cd.consolidate(cg.root, apply=True, reflect_fn=reflect_fn, verify_fn=verify_fn)；
             def _consolidate():
                 return _cd.consolidate(cg.root, apply=True,
                                        reflect_fn=reflect_fn,
@@ -655,6 +681,7 @@ def heal(cg, *, name: str = "md_cg", dry_run: bool = False,
         if allow_evolve:
             from . import weights
 
+# 生效条件：调用时返回 weights.recalc(cg, apply=True, actor="sustain_evolve")；
             def _importance():
                 return weights.recalc(cg, apply=True, actor="sustain_evolve")
             act("importance", "重算结构重要性（确定性；可 rollback）", _importance)
@@ -674,6 +701,7 @@ def heal(cg, *, name: str = "md_cg", dry_run: bool = False,
 # 会话水位（重启续接）
 # --------------------------------------------------------------------------
 
+# 生效条件：以 root 实例化后账本固定指向 os.path.join(root, LEDGER_FILE)，其 _load/_save/note/resume_point/sessions/summary 均以该路径为唯一读写对象；
 class SessionLedger:
     """会话水位账本：<root>/_sessions.json。
 
@@ -681,10 +709,12 @@ class SessionLedger:
     这里记「某个会话发生过什么」——重启后按会话给出续接点。
     """
 
+# 生效条件：传入 root 时置 self.root=root 且 self.path=os.path.join(root, LEDGER_FILE)，不做其他校验；
     def __init__(self, root: str):
         self.root = root
         self.path = os.path.join(root, LEDGER_FILE)
 
+# 生效条件：self.path（root/LEDGER_FILE）可读且 json 结果为 dict、且 d.get("sessions") 也是 dict 时返回该 d；self.path 不可读、json.load 抛 ValueError/OSError、或 d 非 dict / sessions 非 dict 时返回 {"schema": 1, "sessions": {}}；
     def _load(self):
         if os.path.exists(self.path):
             try:
@@ -696,9 +726,11 @@ class SessionLedger:
                 pass
         return {"schema": 1, "sessions": {}}
 
+# 生效条件：传入 d 时执行 atomic_write(self.path, json.dumps(d, ensure_ascii=False, indent=1))，自身无返回值；
     def _save(self, d):
         atomic_write(self.path, json.dumps(d, ensure_ascii=False, indent=1))
 
+# 生效条件：以 session 为键 setdefault 会话记录后写 events=int(s.get("events") or 0)+int(n)（n 默认 1，n=0 时计数不变），t 非 None 时写 last_t 且 first_t 为空时一并写入，seq 非 None 时写 last_seq，actor 为真值时写 actor，最后写 updated_at 并 _save，返回 dict(s, session=session)；
     def note(self, session: str, *, t=None, seq=None, n: int = 1,
              actor: str = None) -> dict:
         """记一笔会话活动（事件计数 + 最后 (t, seq) 水位）。"""
@@ -718,6 +750,7 @@ class SessionLedger:
         self._save(d)
         return dict(s, session=session)
 
+# 生效条件：_load()["sessions"].get(session) 为假值（键缺失或值为空 dict）时返回 {"session": session, "resume": None, "events": 0}；否则返回 {"session": session, "events": s.get("events", 0), "resume": {"t": s.get("last_t"), "seq": s.get("last_seq")}, "last_t": s.get("last_t"), "actor": s.get("actor")}；
     def resume_point(self, session: str) -> dict:
         """重启续接点：(t, seq) 之后的事件才是新的。"""
         s = self._load()["sessions"].get(session)
@@ -727,9 +760,11 @@ class SessionLedger:
                 "resume": {"t": s.get("last_t"), "seq": s.get("last_seq")},
                 "last_t": s.get("last_t"), "actor": s.get("actor")}
 
+# 生效条件：无参调用时返回 dict(self._load()["sessions"]) 的浅拷贝，账本缺失/损坏时 _load 回落默认值故此处为 {}；
     def sessions(self) -> dict:
         return dict(self._load()["sessions"])
 
+# 生效条件：取 d=_load()["sessions"] 后返回 {"sessions": len(d), "events": sum(int(v.get("events") or 0)), "latest": max(v.get("last_t") or 0) if d else None}，d 为空时 latest 为 None；
     def summary(self) -> dict:
         d = self._load()["sessions"]
         return {"sessions": len(d),
@@ -738,6 +773,7 @@ class SessionLedger:
                 if d else None}
 
 
+# 生效条件：os.path.exists(os.path.join(cg.root, "_sources.json")) 为真且 json.load 成功时返回 dict((d or {}).get("sources") or {})（d 或 sources 为假值即回落 {}）；该路径不可读或 json.load 抛 ValueError/OSError 时返回 {}；
 def watermarks(cg) -> dict:
     """源视角水位快照（读 sources.Ingestor 的 _sources.json）。"""
     p = os.path.join(cg.root, "_sources.json")
@@ -755,6 +791,7 @@ def watermarks(cg) -> dict:
 # 常驻循环
 # --------------------------------------------------------------------------
 
+# 生效条件：传入 cg 即构造实例并把 self.cg 指向它，name/beat_interval/heal_interval/auto_heal/scrub_interval/auto_scrub/evolve_interval/auto_evolve/tidy_interval/auto_tidy 用各默认值（DEFAULT_* 与 False/True）经 float()/bool() 落为 self 属性，ledger 为假值（默认 None）时回落 SessionLedger(cg.root)，d 经 net_dir(d) 赋值，其余运行态字段初始化为 False/None/空列表/空 Event/Lock
 class SustainLoop:
     """常驻自维持循环：后台线程周期心跳 + 周期巡检 + 必要时自愈。
 
@@ -762,6 +799,7 @@ class SustainLoop:
     让对端立刻看到「正常下线」而不是「失联」。
     """
 
+# 生效条件：传入 cg 时按 name 与各 DEFAULT_* 默认值初始化——self.d=net_dir(d)（d 假值时回落 MDCG_SUSTAIN_DIR/~/ .mdcg/sustain）、self.ledger=ledger or SessionLedger(cg.root)（ledger 假值时新建），beat/heal/scrub/evolve/tidy 间隔 float() 化、auto_heal/auto_scrub/auto_evolve/auto_tidy bool() 化后存为实例属性；
     def __init__(self, cg, name: str = "md_cg", *,
                  beat_interval: float = DEFAULT_BEAT_INTERVAL,
                  heal_interval: float = DEFAULT_HEAL_INTERVAL,
@@ -797,6 +835,8 @@ class SustainLoop:
         self.evolves = []
         self.last_tidy = None
         self.tidys = []
+        # 数据健康不变量断言集结论（Pi⑤）：与 tidy 同节奏，只取结论不落盘
+        self.last_conformance = None
         self._started_at = None
         self._th = None
         self._stop = threading.Event()
@@ -804,6 +844,7 @@ class SustainLoop:
 
     # ---- 心跳 ----
 
+# 生效条件：task_running 非 None 时先置 self.task_running=bool(task_running)，再 write_stamp(self.name, self.d, task_running=self.task_running, root=self.cg.root, uptime=... if self._started_at else 0.0)，beats 自增并记 last_beat=rec["ts"]，返回该 rec；
     def beat(self, task_running: bool = None) -> dict:
         if task_running is not None:
             self.task_running = bool(task_running)
@@ -817,6 +858,7 @@ class SustainLoop:
 
     # ---- 生命周期 ----
 
+# 生效条件：不适用（无必需形参与模块级常量）
     def start(self):
         if self._th is not None and self._th.is_alive():
             return self
@@ -828,6 +870,7 @@ class SustainLoop:
         self._th.start()
         return self
 
+# 生效条件：调用时置 _stop 事件，self._th 非 None 时 join(timeout)（默认 3.0）后置为 None，随后 clear_stamp(self.name, self.d)，返回 self；
     def stop(self, timeout: float = 3.0):
         self._stop.set()
         if self._th is not None:
@@ -836,6 +879,7 @@ class SustainLoop:
         clear_stamp(self.name, self.d)
         return self
 
+# 生效条件：self._stop 未置位期间轮询，按 beat_interval/heal_interval/scrub_interval/evolve_interval/tidy_interval 到期分别执行 beat 与 _tick_heal/_tick_scrub/_tick_evolve/_tick_tidy，各 tick 抛出的异常被吞掉不中断循环，末尾以 _stop.wait(_POLL) 休眠；
     def _run(self):
         next_beat = time.time() + self.beat_interval
         next_heal = time.time() + self.heal_interval
@@ -876,6 +920,7 @@ class SustainLoop:
                 next_tidy = now + self.tidy_interval
             self._stop.wait(_POLL)
 
+# 生效条件：以 apply=self.auto_tidy 调 writelimit.tidy_contextual(self.cg, actor="sustain_tidy")，把 t/scanned/groups/members/applied_count/auto_tidy 记入 self.last_tidy 与 tidys（仅保留最近 20 条），随后调 _tick_conformance()；auto_tidy=False（默认）时只盘点不落盘；
     def _tick_tidy(self):
         """整理巡检（contextual 流水治理·读侧）：同构组聚合 + 成员降权。
 
@@ -894,7 +939,24 @@ class SustainLoop:
         with self._lock:
             self.tidys.append(rec)
             self.tidys = self.tidys[-20:]
+        self._tick_conformance()
 
+# 生效条件：把 conformance.report_summary(self.cg) 的结论写入 self.last_conformance；该调用抛异常时写入 {"ok": False, "verdict": "BLINDSPOT", "error": "<类型名>: <消息>"}；
+    def _tick_conformance(self):
+        """数据健康不变量断言集（Pi⑤）——与 tidy 同节奏，**只取结论**。
+
+        复用 tidy 的 6h 节奏而不新开周期：两者都是「存量数据体检」，且都是
+        只读巡检。纪律：本断言集**只告警不改数据**，故 `auto_*` 在此无意义；
+        `check_paths=False` 跳过 1.1 万次 stat，`_audit.jsonl` 只读尾窗。
+        """
+        from . import conformance
+        try:
+            self.last_conformance = conformance.report_summary(self.cg)
+        except Exception as e:                              # noqa: BLE001
+            self.last_conformance = {"ok": False, "verdict": "BLINDSPOT",
+                                     "error": f"{type(e).__name__}: {e}"}
+
+# 生效条件：恒以 evolution_candidates(self.cg) 只读盘点并记入 last_evolve 与 evolves（保留最近 20 条）；仅当 self.auto_evolve 为真且 ev["importance_drift"]["n"] 为真时才额外执行 weights.recalc(self.cg, apply=True, actor="sustain_evolve")，其异常写入 rec["applied"]；
     def _tick_evolve(self):
         """演化巡检（G7）：盘点固化/重要性候选 —— 让「有能力」变成「有驱动」。
 
@@ -921,6 +983,7 @@ class SustainLoop:
             self.evolves.append(rec)
             self.evolves = self.evolves[-20:]
 
+# 生效条件：以 dry_run=not self.auto_scrub 调 scrub.sweep(self.cg)，把 t/ok/n_issues/n_high_medium/applied/dry_run 记入 last_scrub 与 scrubs（保留最近 20 条）；auto_scrub=False（默认）时 dry_run=True 只读巡检；
     def _tick_scrub(self):
         """记忆自净：抽查 → 联想 → 去污染 → 校准偏差。
 
@@ -939,6 +1002,7 @@ class SustainLoop:
             self.scrubs.append(rec)
             self.scrubs = self.scrubs[-20:]
 
+# 生效条件：先 diagnose(self.cg, name=self.name) 并将 ok 与 issues code 记入 last_diagnose；仅当 self.auto_heal 为真且 rep["ok"] 为假时才调 heal(self.cg, name=self.name)，其 actions 非空时把各 action 的 code 记入 heals（保留最近 20 条）；
     def _tick_heal(self):
         rep = diagnose(self.cg, name=self.name)
         self.last_diagnose = {"t": time.time(), "ok": rep["ok"],
@@ -954,6 +1018,7 @@ class SustainLoop:
 
     # ---- 状态 ----
 
+# 生效条件：以 read_stamp(self.name, self.d) 判定 state（有戳走 judge(age, interval=self.beat_interval, task_running=...)，无戳为 "stopped"），返回含 name/running/pid/uptime（无 _started_at 时为 0.0）/beats/last_beat/各 interval 与 auto_* 开关/heals[-5:]/evolves[-5:]/tidys[-5:]/peers(self.d)/ledger.summary() 的 dict；
     def status(self) -> dict:
         st = read_stamp(self.name, self.d)
         state = (judge(st["age"], interval=self.beat_interval,
@@ -980,6 +1045,7 @@ class SustainLoop:
                 "evolves": self.evolves[-5:],
                 "last_tidy": self.last_tidy,
                 "tidys": self.tidys[-5:],
+                "last_conformance": self.last_conformance,
                 "peers": peers(self.d),
                 "sessions": self.ledger.summary()}
 
@@ -988,6 +1054,7 @@ _LOOPS = {}
 _LOOPS_LOCK = threading.Lock()
 
 
+# 生效条件：cg 必填，以 (os.path.abspath(cg.root), name) 为键在模块级 _LOOPS 中复用已有实例或新建 SustainLoop 并返回该实例。
 def ensure_loop(cg, name: str = "md_cg", **kw) -> SustainLoop:
     """按 (root, name) 复用同一个常驻循环（避免重复线程 / 重复戳）。"""
     key = (os.path.abspath(cg.root), name)
@@ -999,10 +1066,12 @@ def ensure_loop(cg, name: str = "md_cg", **kw) -> SustainLoop:
         return lp
 
 
+# 生效条件：cg 必填，返回 _LOOPS[(os.path.abspath(cg.root), name)]，该键未登记时返回 None。
 def get_loop(cg, name: str = "md_cg"):
     return _LOOPS.get((os.path.abspath(cg.root), name))
 
 
+# 生效条件：模块级 _LOOPS 非空时清空该表并对每个循环调用 stop()（异常被吞），无返回值。
 def stop_all():
     """测试 / 进程退出用：停掉本进程创建的所有常驻循环。"""
     with _LOOPS_LOCK:
@@ -1015,6 +1084,7 @@ def stop_all():
             pass
 
 
+# 生效条件：以 read_stamp(name) 有戳时返回 heartbeat={'age': round(st["age"],1), 'state': judge(...), 'pid', 'task_running'}、无戳时 {'state':'absent'}，loop 取 get_loop(cg, name) 有值时给 running/beats/state、无值时 {'running': False}，并附带 SessionLedger(cg.root).summary()、scrub_summary(cg)、evolve_summary(cg)、provenance_summary(cg)；
 def summary(cg, name: str = "md_cg") -> dict:
     """并入 health_os 的轻量摘要（只读戳与计数，不做巡检）。"""
     st = read_stamp(name)
@@ -1036,6 +1106,7 @@ def summary(cg, name: str = "md_cg") -> dict:
     }
 
 
+# 生效条件：cg 必填，可导入 provenance 且其 summary(cg) 调用成功时返回该摘要，异常时返回 {}。
 def provenance_summary(cg) -> dict:
     """派生溯源摘要（G8，只读；失败不抛，避免拖垮 health_os）。"""
     try:
@@ -1045,6 +1116,7 @@ def provenance_summary(cg) -> dict:
         return {}
 
 
+# 生效条件：cg 必填，evolution_candidates(cg, top=3) 成功时返回 candidates/ccg_backlog/importance_drift 计数摘要，异常时返回 {}。
 def evolve_summary(cg) -> dict:
     """演化巡检摘要（只读；失败不抛，避免拖垮 health_os）。"""
     try:
@@ -1057,10 +1129,11 @@ def evolve_summary(cg) -> dict:
         return {}
 
 
+# 生效条件：cg 必填，可导入 scrub 且其 summary(cg) 调用成功时返回该摘要，异常时返回 {}。
 def scrub_summary(cg) -> dict:
     """记忆自净摘要（惰性导入，避免模块加载顺序耦合）。"""
     try:
         from . import scrub
         return scrub.summary(cg)
     except Exception:                     # noqa: BLE001
-        return {}
+        return {}