@furongjun1999/dsh-memory 0.4.8 → 0.4.10

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,
@@ -806,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)
@@ -819,6 +858,7 @@ class SustainLoop:
 
     # ---- 生命周期 ----
 
+# 生效条件：不适用（无必需形参与模块级常量）
     def start(self):
         if self._th is not None and self._th.is_alive():
             return self
@@ -830,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:
@@ -838,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
@@ -878,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 流水治理·读侧）：同构组聚合 + 成员降权。
 
@@ -898,6 +941,7 @@ class SustainLoop:
             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 同节奏，**只取结论**。
 
@@ -912,6 +956,7 @@ class SustainLoop:
             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）：盘点固化/重要性候选 —— 让「有能力」变成「有驱动」。
 
@@ -938,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):
         """记忆自净：抽查 → 联想 → 去污染 → 校准偏差。
 
@@ -956,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"],
@@ -971,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,
@@ -1006,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)
@@ -1017,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:
@@ -1033,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)
@@ -1054,6 +1106,7 @@ def summary(cg, name: str = "md_cg") -> dict:
     }
 
 
+# 生效条件：cg 必填，可导入 provenance 且其 summary(cg) 调用成功时返回该摘要，异常时返回 {}。
 def provenance_summary(cg) -> dict:
     """派生溯源摘要（G8，只读；失败不抛，避免拖垮 health_os）。"""
     try:
@@ -1063,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:
@@ -1075,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 {}

package/md_cg/tasks.py

@@ -75,6 +75,7 @@ _ILLEGAL_RE = re.compile(r"[^0-9A-Za-z\u4e00-\u9fff_.-]+")
 
 # ---------------------------------------------------------------- 命名与解析
 
+# 生效条件：name 为 None/空串或 strip 后为空时返回空串，否则把 `/`、`\`、`..` 及 _ILLEGAL_RE 命中字符折叠为 `-`、压缩连续 `-` 并去首尾 `-.` 后取前 64 字符再去首尾 `-.` 返回；
 def slugify(name: str) -> str:
     """任务名 → 语义 slug（稳定标识；同 slug 即同任务）。
 
@@ -91,6 +92,7 @@ def slugify(name: str) -> str:
     return s[:64].strip("-.")
 
 
+# 生效条件：name（`name or ""` 后 strip）先剥掉已有的 TASK_PREFIX 再 slugify，结果非空且被 _SLUG_RE.match 命中时返回 TASK_PREFIX + slug；name 为假值或归一化后为空、不匹配时返回 ""。
 def task_node_id(name: str) -> str:
     """任务名或节点 id → 规范节点 id（`task_<slug>`）。非法名返回空串。"""
     s = (name or "").strip()
@@ -102,15 +104,18 @@ def task_node_id(name: str) -> str:
     return TASK_PREFIX + slug
 
 
+# 生效条件：v 为 None 或 str(v).strip() 为 "" 时返回 False，否则返回 True。
 def _has(v) -> bool:
     """「本次调用是否提供了该字段」——空串/None 一律视为未提供（不静默清空）。"""
     return v is not None and str(v).strip() != ""
 
 
+# 生效条件：无必需形参且无模块级常量约束，恒返回 time.strftime("%Y-%m-%d %H:%M") 的当前时间文本。
 def _today() -> str:
     return time.strftime("%Y-%m-%d %H:%M")
 
 
+# 生效条件：content（`content or ""` 后 splitlines）中有某行 strip 后以 `# ` + field + `：` 开头时，返回该行该前缀之后的去空白内容；content 为假值或无此匹配行时返回 ""。
 def _field_line(content: str, field: str) -> str:
     """从正文抽 `# <字段>：` 行的值（与 `mdcos._ccg_field` 同源口径，
     本模块不反向 import mdcos，避免包内循环依赖）。"""
@@ -122,6 +127,7 @@ def _field_line(content: str, field: str) -> str:
     return ""
 
 
+# 生效条件：(content or "") 的行中 strip 后以 "## " 开头者成为节名 s[3:].strip() 并切换当前节，其余行累入当前节，返回各节内容以 "\n" join 后 strip 的字典；无任何标题行时仅返回 {"__body__": 全篇 strip}；content 为 None/空串时返回 {"__body__": ""}。
 def sections(content: str) -> dict:
     """正文 → `{节名: 节内容}`；无标题部分归入 `__body__`。"""
     out: dict = {"__body__": []}
@@ -136,6 +142,7 @@ def sections(content: str) -> dict:
     return {k: "\n".join(v).strip() for k, v in out.items()}
 
 
+# 生效条件：t = (text or "").strip()，t 为 ""/"（无）"/"（未填）" 时返回 ""，否则 len(t) <= n（默认 200）时返回 t，超出时返回 t[:n].rstrip() + "…"。
 def _brief(text: str, n: int = 200) -> str:
     t = (text or "").strip()
     if t in ("", "（无）", "（未填）"):
@@ -143,6 +150,7 @@ def _brief(text: str, n: int = 200) -> str:
     return t if len(t) <= n else t[:n].rstrip() + "…"
 
 
+# 生效条件：以 (old_text or "").strip() 为 base（base 为「（无）」或「（未填）」时置空），_has(change) 判定为假时返回 base or "（无）"，为真时拼出 `- [今日] change.strip()`，base 非空返回 base+"\n"+该行再 strip，base 为空只返回该行；
 def _append_change(old_text: str, change: str) -> str:
     """「计划变更」节追加一行（累积式，不覆盖历史）。"""
     base = (old_text or "").strip()
@@ -154,6 +162,7 @@ def _append_change(old_text: str, change: str) -> str:
     return (base + "\n" + line).strip() if base else line
 
 
+# 生效条件：name 为必需形参（`name or ""` 后 strip 填 `# 功能名：` 行）；condition、goal、acceptance、boundary、plan、changes、result 各经 _has 判定，未提供时分别落「无条件」「（未填：任务目标待补）」「other」「任务转 done/dropped 终态后不再作为进行中任务参与装配」「（未填）」「（无）」与空串；status 经 STATUS_ZH.get(status, status) 映射、未命中时原样输出，note 经 _has 为真时以 `｜` 拼在执行行后。
 def render(name: str, *, condition: str = "", goal: str = "", status: str = "active",
            note: str = "", acceptance: str = "", boundary: str = "",
            plan: str = "", changes: str = "", result: str = "") -> str:
@@ -184,6 +193,7 @@ def render(name: str, *, condition: str = "", goal: str = "", status: str = "act
 
 # ---------------------------------------------------------------- 读写
 
+# 生效条件：nid 为假值（None/空串）时返回 None；否则 cg.get(nid) 命中且其 frontmatter.layer == "structural"、TASK_TAG 在 frontmatter.tags（`or []`）中时，返回 {id, fm, content, path, sec}（sec 为 sections(content)）；记录缺失或层/标签不符时返回 None。
 def _read_task(cg, nid: str):
     """读回任务卡；层或标签不符一律视为不存在（防串号：别的节点占用了同 id）。"""
     if not nid:
@@ -199,6 +209,7 @@ def _read_task(cg, nid: str):
             "path": rec.get("path"), "sec": sections(content)}
 
 
+# 生效条件：以 layer="structural"、tags=list(tags)、importance=float(importance)、override=True、task_name=name、task_status=status、task_updated_at=time.time()、actor=actor or "task" 等构成 kw，extra 为真值时经 kw.update(extra) 追加覆盖，随后调用 cg.add(nid, content, **kw) 并返回其结果；
 def _write(cg, nid: str, name: str, content: str, status: str, tags,
            importance: float, actor, extra: dict = None):
     """唯一写盘点——走 `cg.add`（权限闸 / 归属注入全部复用既有链路）。
@@ -217,6 +228,7 @@ def _write(cg, nid: str, name: str, content: str, status: str, tags,
     return cg.add(nid, content, **kw)
 
 
+# 生效条件：cg 具有 _audit 属性（getattr(cg, "_audit", None) 非 None）时以 (op, nid, **meta) 调用它，且其中抛出的任何异常被吞掉；cg 无该属性时不调用，两种路径均不返回内容。
 def _audit(cg, op: str, nid: str, **meta) -> None:
     """生命周期留痕；审计失败绝不阻断主流程（与 branches._audit 同哲学）。"""
     a = getattr(cg, "_audit", None)
@@ -228,6 +240,7 @@ def _audit(cg, op: str, nid: str, **meta) -> None:
         pass
 
 
+# 生效条件：_read_task(cg, nid) 命中任务卡时返回摘要条目——id 取 rec['id']，name 取 fm.task_name 或（缺失/假值时）rec['id']，status 取 fm.task_status 或 "active"，plan/changes/result 取对应节的 _brief 摘要（缺节回落 ""），并带 created_at/updated_at/path；未命中时返回 None。
 def _entry(cg, nid: str):
     """节点 id → 对外任务条目（摘要形态；全字段查 `get_task`）。"""
     rec = _read_task(cg, nid)
@@ -247,6 +260,7 @@ def _entry(cg, nid: str):
 
 # ---------------------------------------------------------------- 写操作
 
+# 生效条件：slugify(name) 为空串或不匹配 _SLUG_RE 时返回 {'ok': False, 含 slug 的非法名 error}；否则 st = str(status if _has(status) else (旧卡 task_status or "active")).strip().lower()，st 不在 TASK_STATUSES 时返回未知状态错误，st == "done" 且合并后结果节 _has(new_res) 为假时返回「转 done 必须填结果」拒收，其余情况渲染写入并返回按 old 是否为 None 区分新建/更新的 out。
 def upsert(cg, name: str, *, plan: str = None, status: str = None,
            result: str = None, condition: str = None, goal: str = None,
            acceptance: str = None, boundary: str = None, change: str = None,
@@ -313,12 +327,14 @@ def upsert(cg, name: str, *, plan: str = None, status: str = None,
     return out
 
 
+# 生效条件：content 中 `# 执行：` 行的值含 "｜" 时返回第一个 "｜" 之后去空白的内容；content 为假值、无该行或该行值不含 "｜" 时返回 ""。
 def _exec_note(content: str) -> str:
     """从 `# 执行：` 行取 `｜` 之后的进度说明。"""
     val = _field_line(content, "执行")
     return val.split("｜", 1)[1].strip() if "｜" in val else ""
 
 
+# 生效条件：node_id 经 task_node_id 得到非空 nid 且 _read_task 命中该卡时，以旧卡 task_name（缺失/假值回落 nid）、status、result、note、actor 转调 upsert 并返回其结果；node_id 非法时返回 ok=False「非法任务标识」，卡不存在时返回 ok=False「任务不存在」。
 def set_status(cg, node_id: str, status: str, *, result: str = None,
                note: str = None, actor: str = None) -> dict:
     """任务状态迁移（进行中/受阻/完成/放弃）。迁 done 且无结果 → 拒收。"""
@@ -332,6 +348,7 @@ def set_status(cg, node_id: str, status: str, *, result: str = None,
                   result=result, note=note, actor=actor)
 
 
+# 生效条件：change 经 _has 判定为已提供、且 node_id 经 task_node_id 非空、_read_task 命中该卡时，以旧卡 task_name（缺失/假值回落 nid）与 change、actor 转调 upsert；change 为 None/空串/纯空白时返回 ok=False「计划变更内容为空」，node_id 非法或卡不存在时返回 ok=False 对应错误。
 def plan_add(cg, node_id: str, change: str, *, actor: str = None) -> dict:
     """计划变更追加——执行中发现的错误/新问题/偏差，累积进「计划变更」节。"""
     if not _has(change):
@@ -347,6 +364,7 @@ def plan_add(cg, node_id: str, change: str, *, actor: str = None) -> dict:
 
 # ---------------------------------------------------------------- 读操作
 
+# 生效条件：node_id 经 task_node_id 得到的 nid 对应一张 _read_task 命中的任务卡时返回 ok=True 的全字段（condition/goal/acceptance/boundary 由 _field_line 抽取、note 由 _exec_note 抽取、plan/changes/result 取节原文不截断、tags 取 fm.tags 或 []）；否则返回 ok=False，error 中的标识取 nid 或原 node_id。
 def get_task(cg, node_id: str) -> dict:
     """单卡全字段读回（计划/变更/结果不截断）。"""
     nid = task_node_id(node_id)
@@ -370,6 +388,7 @@ def get_task(cg, node_id: str) -> dict:
             "path": rec["path"]}
 
 
+# 生效条件：status 经 `str(status or "").strip().lower()` 为非空且不在 TASK_STATUSES 时返回 ok=False 未知状态；否则收集 cg.index["nodes"] 中各 _entry 可读任务、按 updated_at 倒序，status 非空时再按该状态过滤，total 为过滤后截断前的条数，limit 为真值时取前 max(int(limit), 1) 条——limit 为 None、0 或空串（假值）时不截断而返回全量 filtered 列表。
 def list_tasks(cg, status: str = None, limit: int = None) -> dict:
     """任务清单（按 updated_at 倒序）；status 可选 active/blocked/done/dropped。"""
     st = str(status or "").strip().lower() or None
@@ -389,6 +408,7 @@ def list_tasks(cg, status: str = None, limit: int = None) -> dict:
     return {"ok": True, "count": len(items), "total": total, "tasks": items}
 
 
+# 生效条件：遍历 cg.index["nodes"]，把 _entry 可读且 status 为 active/blocked 的归入 active、status 为 done 的归入 done，各自按 updated_at 倒序；返回 active[:max(int(active_limit), 0)] 与 done[:max(int(done_limit), 0)]（active_limit/done_limit 传 0 或负数时对应列表为空）以及两组截断前的 active_total/done_total。
 def session_tasks(cg, active_limit: int = 5, done_limit: int = 5) -> dict:
     """会话装配用：进行中（active/blocked）+ 近期完成（done，按 updated_at 倒序）。
 
@@ -404,7 +424,10 @@ def session_tasks(cg, active_limit: int = 5, done_limit: int = 5) -> dict:
             active.append(t)
         elif t["status"] == "done":
             done.append(t)
-    key = lambda x: -(x.get("updated_at") or 0)          # noqa: E731
+    # 终键 id：同 updated_at 并列时定序，否则顺序回落到 cg.index["nodes"]
+    # 的物理序（增量路径=写入序，重建路径=nid 序）。
+    key = lambda x: (-(x.get("updated_at") or 0),         # noqa: E731
+                     str(x.get("id") or ""))
     active.sort(key=key)
     done.sort(key=key)
     return {"ok": True,
@@ -413,6 +436,7 @@ def session_tasks(cg, active_limit: int = 5, done_limit: int = 5) -> dict:
             "active_total": len(active), "done_total": len(done)}
 
 
+# 生效条件：name 经 task_node_id 得 nid，exists 为同 id 任务卡是否被 _read_task 命中；k 经 `int(k or 5)` 再 max(…, 1)（k 为 None/0/空串回落 5，负数取 1）得到 kk，cg.search 抛异常时按无结果处理，只保留元素长度 ≥3、frontmatter.tags 含 TASK_TAG 且 node.id != nid 的条目，返回 out[:kk] 与 note。
 def find_similar(cg, name: str, k: int = 5) -> dict:
     """同族任务提示（**只提示，不自动合并**——是否同一任务由调用方裁决）。
 
@@ -444,4 +468,4 @@ def find_similar(cg, name: str, k: int = 5) -> dict:
                     "score": round(float(score), 4),
                     "qualification": (qual or {}).get("state") if isinstance(qual, dict) else None})
     return {"ok": True, "node_id": nid, "exists": exact, "similar": out[:kk],
-            "note": "仅提示疑似同族任务，不自动合并——终裁权在调用方"}
+            "note": "仅提示疑似同族任务，不自动合并——终裁权在调用方"}

package/md_cg/test_autonomy.py

@@ -7,6 +7,8 @@
      提案携带证据明细
   ③ 全链路：提案 → learn_blindspots 五态终判 → 留痕 _explore.jsonl
   ④ 幂等：重复 explore 终态一致、gap 回写不重复（gap_<sha1(bid)> 幂等）
+  ⑤ D_meta 排序加分：只进 sort_score 与证据，不改 score、不改资格
+     （零信号查询仍不提案；加分每轮一次、循环内复用）
 
 运行：python -m md_cg.test_autonomy
 """
@@ -103,6 +105,30 @@ def main():
                "④b gap 回写幂等（第二次 written=None，节点已存在）")
         else:
             ok(True, "④b本终态无回写动作，幂等性由判定确定性保证")
+
+        # ---------- ⑤ D_meta 排序加分（只影响排序，不改资格） ----------
+        root5 = os.path.join(tmp, "root5")
+        os.makedirs(root5, exist_ok=True)
+        cg5 = MdCGOS(root5)
+        for i in range(50):
+            append_jsonl(cg5.recent_log, {"i": i})
+        _sig(cg5, 1.0, "零信号查询", 0.0, {})
+        _sig(cg5, 2.0, "反应堆冷却方案", 0.9, {"BLINDSPOT": 2})
+        pr5 = autonomy.proposals(cg5, limit=3)
+        ps5 = pr5["proposals"]
+        ok(len(ps5) == 1 and pr5["n_signals"] == 2,
+           "⑤零信号查询仍不提案、n_signals 按原始信号计（加分不改资格）")
+        p0 = ps5[0]
+        ok(p0["score"] == round(autonomy.W_D2 * p0["d2_abs"]
+                                + autonomy.W_BLINDSPOT * p0["blindspot"]
+                                + autonomy.W_DEFER * p0["defer"], 4),
+           "⑤bscore 仍是纯 ΔD 定价（口径零变更）")
+        ok(p0["sort_score"] == round(p0["score"] + p0["d_meta_bonus"], 4)
+           and p0["d_meta_bonus"] == pr5["d_meta"]["bonus"],
+           "⑤c排序键 = ΔD + D_meta 加分（每轮一次、循环内复用）")
+        ok(p0["d_meta_bonus"] > 0 and "D_meta" in p0["reason"]
+           and "不合成" in p0["reason"],
+           "⑤d加分生效且 reason 追加证据并声明不合成（可审计）")
     finally:
         shutil.rmtree(tmp, ignore_errors=True)