@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/coldverify.py

@@ -0,0 +1,265 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 冷路径异步深度验证队列
+
+【为什么】写入路径中的一跳同步传播（_after_trust → mark_dependents）
+只做「标记存疑」——它不验证下游是否真的被影响。真正的深度验证
+需要：(1) 重跑 judge_qualification 看条件是否仍命中；
+(2) 检查依赖链上的验证态是否级联失效。
+
+这些操作可重可慢，不该阻塞写入路径。故异步入队，后台消费。
+
+【设计】
+  - enqueue(node_id, action, **kw)：入队异步验证任务
+  - 后台线程消费队列，调 trust.set_state + judge_ranking
+  - 队列落盘 _coldverify.jsonl（崩溃恢复）
+  - 默认不启动后台线程（opt-in：start_worker()）
+  - 也可同步消费（drain()，用于测试）
+
+【边界】
+  - 不阻塞写入路径（_after_trust 只 enqueue 不等结果）
+  - 后台线程异常只记日志不抛（永不拖垮主进程）
+  - 队列文件可选（无文件时纯内存，适合测试）
+
+零第三方依赖（D-005）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from collections import deque
+
+#: 队列文件名
+QUEUE_FILE = "_coldverify.jsonl"
+#: 后台线程轮询间隔（秒）
+POLL_INTERVAL = 2.0
+#: 单次批处理上限
+BATCH_LIMIT = 10
+
+_VALID_ACTIONS = {"reverify", "propagate_depth", "patrol_check"}
+
+
+class ColdVerifyQueue:
+    """冷路径异步深度验证队列。
+
+    线程安全：enqueue/drain/status 可跨线程调用。
+    """
+
+    def __init__(self, root=None):
+        self._root = root
+        self._queue: deque = deque()
+        self._lock = threading.Lock()
+        self._worker = None
+        self._stop = threading.Event()
+        self._stats = {"enqueued": 0, "processed": 0, "errors": 0,
+                       "skipped": 0}
+        self._queue_path = (os.path.join(root, QUEUE_FILE)
+                             if root else None)
+        self._load_persisted()
+
+    def _load_persisted(self):
+        """从队列文件恢复未处理任务（崩溃恢复）。"""
+        if not self._queue_path or not os.path.exists(self._queue_path):
+            return
+        try:
+            with open(self._queue_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    task = json.loads(line)
+                    if not task.get("_done"):
+                        self._queue.append(task)
+        except Exception:                              # noqa: BLE001
+            pass  # 崩溃恢复容错：文件损坏就不恢复
+
+    def _persist(self):
+        """持久化当前队列（全量覆写）。"""
+        if not self._queue_path:
+            return
+        try:
+            with open(self._queue_path, "w", encoding="utf-8") as f:
+                for task in self._queue:
+                    f.write(json.dumps(task, ensure_ascii=False) + "\n")
+        except Exception:                              # noqa: BLE001
+            pass  # 持久化失败不影响内存队列
+
+    def enqueue(self, node_id: str, action: str = "reverify", **kw):
+        """入队异步验证任务。返回 task dict。"""
+        if action not in _VALID_ACTIONS:
+            raise ValueError(f"未知 action: {action}，合法: {_VALID_ACTIONS}")
+        task = {
+            "node_id": node_id,
+            "action": action,
+            "enqueued_at": time.time(),
+            "kwargs": kw,
+        }
+        with self._lock:
+            self._queue.append(task)
+            self._stats["enqueued"] += 1
+            self._persist()
+        return task
+
+    def drain(self, cg, *, limit=BATCH_LIMIT):
+        """同步消费队列（用于测试/手动处理）。返回处理结果列表。"""
+        results = []
+        with self._lock:
+            batch = []
+            for _ in range(min(limit, len(self._queue))):
+                batch.append(self._queue.popleft())
+        for task in batch:
+            try:
+                r = self._process(cg, task)
+                results.append(r)
+                self._stats["processed"] += 1
+            except Exception as exc:                    # noqa: BLE001
+                self._stats["errors"] += 1
+                results.append({"node_id": task["node_id"],
+                                 "action": task["action"],
+                                 "error": str(exc),
+                                 "ok": False})
+        with self._lock:
+            self._persist()
+        return results
+
+    def _process(self, cg, task):
+        """执行单个验证任务。"""
+        from . import trust
+        nid = task["node_id"]
+        action = task["action"]
+        kw = task.get("kwargs", {})
+
+        if action == "reverify":
+            # 重新验证单节点：重跑 judge_qualification
+            node = cg.get(nid)
+            if not node:
+                self._stats["skipped"] += 1
+                return {"node_id": nid, "action": action, "ok": True,
+                        "skipped": "node_not_found"}
+            fm = node.get("frontmatter") or {}
+            old_state = trust.state_of(fm)
+            # 只对非 unverified 节点做深度验证
+            if old_state == "unverified":
+                self._stats["skipped"] += 1
+                return {"node_id": nid, "action": action, "ok": True,
+                        "skipped": "unverified_no_action"}
+            # 检查时效
+            kind, _, _ = trust.validity(fm)
+            want, why = None, ""
+            if kind == "expired" and old_state != "expired":
+                want, why = "expired", "冷路径：时效过期"
+            elif kind == "not_yet":
+                want, why = "unverified", "冷路径：尚未生效"
+            if want is None:
+                return {"node_id": nid, "action": action, "ok": True,
+                        "old_state": old_state, "new_state": old_state,
+                        "changed": False}
+            # 迁移结果**必须检查**（2026-09-20 v14 缺陷 D 修复）：`trust.set_state`
+            # 对非法迁移返回 ok=False（负路由不抛异常），旧实现丢弃返回值后一律
+            # 上报 `ok=True + new_state=<请求值>` —— 恰好在本队列最该说话的两条
+            # 迁移上（doubted→expired / verified→unverified，均为 TRANSITIONS
+            # 明令拒绝的跳级）**说了假话**，且 stats.errors 恒 0 把它盖住。
+            # trust 层做对了（拒绝非法迁移），队列层不得把它翻译成成功。
+            r = trust.set_state(cg, nid, want, reason=why,
+                                actor="coldverify", **kw)
+            if not r.get("ok"):
+                self._stats["errors"] += 1
+                return {"node_id": nid, "action": action, "ok": False,
+                        "old_state": old_state, "requested_state": want,
+                        "error": "transition_rejected:%s" % r.get("error"),
+                        "reason": r.get("reason") or "",
+                        "detail": "非法迁移被 trust.TRANSITIONS 拒绝，状态未变"}
+            return {"node_id": nid, "action": action, "ok": True,
+                    "old_state": old_state, "new_state": want,
+                    "changed": bool(r.get("changed"))}
+
+        elif action == "propagate_depth":
+            # 多跳深度传播
+            r = trust.propagate(cg, apply=True, actor="coldverify",
+                                **kw)
+            return {"node_id": nid, "action": action, "ok": True,
+                    "propagation": r}
+
+        elif action == "patrol_check":
+            # 巡检式检查
+            rep = trust.patrol(cg, **kw)
+            return {"node_id": nid, "action": action, "ok": True,
+                    "patrol": rep}
+
+        return {"node_id": nid, "action": action, "ok": False,
+                "error": "unknown_action"}
+
+    def start_worker(self, cg, *, poll_interval=POLL_INTERVAL):
+        """启动后台消费线程。"""
+        if self._worker and self._worker.is_alive():
+            return self._worker
+        self._stop.clear()
+
+        def _run():
+            while not self._stop.is_set():
+                try:
+                    if self._queue:
+                        self.drain(cg, limit=BATCH_LIMIT)
+                except Exception:                      # noqa: BLE001
+                    self._stats["errors"] += 1
+                self._stop.wait(poll_interval)
+
+        self._worker = threading.Thread(target=_run, daemon=True,
+                                        name="coldverify-worker")
+        self._worker.start()
+        return self._worker
+
+    def stop_worker(self, timeout=5.0):
+        """停止后台线程。"""
+        self._stop.set()
+        if self._worker and self._worker.is_alive():
+            self._worker.join(timeout=timeout)
+        self._worker = None
+
+    def status(self):
+        """返回队列状态。"""
+        with self._lock:
+            return {
+                "queue_size": len(self._queue),
+                "stats": dict(self._stats),
+                "worker_alive": (self._worker is not None
+                                  and self._worker.is_alive()),
+                "queue_file": self._queue_path,
+            }
+
+    def clear(self):
+        """清空队列（测试用）。"""
+        with self._lock:
+            self._queue.clear()
+            self._persist()
+
+
+#: 进程级默认实例
+_DEFAULT = None
+
+
+def default_queue(root=None):
+    """进程级默认冷路径队列单例。"""
+    global _DEFAULT
+    if _DEFAULT is None:
+        _DEFAULT = ColdVerifyQueue(root=root)
+    return _DEFAULT
+
+
+def attach(cg):
+    """给 cg 实例挂冷路径队列（幂等）。"""
+    if not hasattr(cg, "_coldverify") or cg._coldverify is None:
+        cg._coldverify = ColdVerifyQueue(root=cg.root)
+    return cg._coldverify
+
+
+def get(cg):
+    """取 cg 实例的冷路径队列（未挂返回 None）。"""
+    return getattr(cg, "_coldverify", None)
+
+
+def enqueue(cg, node_id: str, action: str = "reverify", **kw):
+    """快捷入口：挂队列 + 入队。"""
+    q = attach(cg)
+    return q.enqueue(node_id, action, **kw)

package/md_cg/comment_gate.py

@@ -0,0 +1,338 @@
+# -*- coding: utf-8 -*-
+"""comment_gate · 代码符号「条件化注释」抽样闸门（计划四环之环二入口）。
+
+**换对象不换机制**：复用 refine.py 的闸门范式（分层抽样 → 只读工单 → 人工裁决留痕 →
+通过率放行），把处理对象从「node_ 前缀的记忆节点 CCG 字段缺口」换成
+「code_ 前缀的代码符号注释缺口」。
+
+候选判据（唯一、机械、不做语义猜测）：**代码节点且正文缺『生效条件』**。
+依 Phase 0 契约，代码节点的生效条件只能来自源码人工声明——缺它即 BLINDSPOT
+（缺证据），正是本闸门要治理的对象。落点按使用者裁决 q-0：写进源码、定义行紧邻的
+井号注释（**两个窗口**，见 docs/mdcg/代码评审与条件化注释_契约_v0.1.md §三.2）。
+
+本模块只做**候选池 / 工单 / 留痕 / 闸门**：不生成注释、不改任何节点。
+生成与评审方式按 q-2（LLM 生成 + 人工抽检，复用 0.90 闸门）。
+
+诚实边界（honest_limits 已随 SPEC 一并输出）：
+· 分层抽样的**分配**沿用 refine.sample_ids 对 code_ 节点的口径（家族=大域），
+  而非对候选池重新分配——故 sample_adequacy 会如实报出样本里的候选产出率；
+  若产出率不足，应先扩大 n 或改用候选池重分配（已知待办，不在本片）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+from . import codeindex, nodefile, refine
+
+#: 放行阈值**唯一真源在 refine**（不在此处再定义一份，防口径漂移）
+GATE_MIN_PASS_RATE = refine.GATE_MIN_PASS_RATE
+SAMPLE_N = refine.SAMPLE_N
+#: 本闸门自己的抽样种子（与 refine 的 g6-sample-v1 分离，样本可各自复算）
+SAMPLE_SEED = "comment-gate-v1"
+#: 代码节点 id 前缀（见 codeindex.node_id = code_ + sha1 前 12 位）
+PREFIX = "code_"
+LOG_NAME = "_comment_gate.jsonl"
+
+#: 人工核对清单（与工单逐项对应；对照 refine.SPEC.review_items 的同构位置）
+REVIEW_ITEMS = (
+    "生效条件是否为**功能前置条件**（何种输入/状态下正确），而非索引元条件",
+    "条件可否被机械复核（有输入/状态判据；不是「常用条件默认省略」）",
+    "落点是否为源码定义行紧邻的井号注释（两窗口之一），且不覆盖既有实现说明",
+    "公开仓合规：过第 14 条「内容政策 + 隐私」双清单（补写内容随源码公开）",
+)
+
+SPEC = {
+    "goal": "为代码符号补写功能级生效条件注释，使其在检索侧可判（不再因缺证据恒 BLINDSPOT）",
+    "target": "code_ 前缀节点中正文缺『生效条件』者",
+    "landing": "源码定义行紧邻的井号注释（leading/body 两窗口，物理序合并）",
+    "review_items": list(REVIEW_ITEMS),
+    "gate": {"min_pass_rate": GATE_MIN_PASS_RATE, "basis": "人工核对忠实比例",
+             "rule": "低于阈值不得扩批"},
+    "honest_limits": [
+        "本闸门只覆盖已索引的代码节点；未索引的源码不在面内（先跑 index_code）",
+        "分层分配沿用 code_ 节点口径而非候选池，样本候选产出率由 sample_adequacy 如实上报",
+        "不生成注释、不改节点：生成与评审属另一环节（LLM 生成 + 人工抽检）",
+    ],
+}
+
+
+# 生效条件：cg 传入后返回 os.path.join(cg.root, LOG_NAME)，即以 cg.root 与模块级常量 LOG_NAME 拼接的日志路径（cg 缺 root 属性时抛 AttributeError）。
+def _log_path(cg) -> str:
+    return os.path.join(cg.root, LOG_NAME)
+
+
+# 生效条件：cg 与 nid 传入后，先看 str(nid) 是否以模块级常量 PREFIX 开头（不以则返回 False）；以 PREFIX 开头时取 cg.get(nid)（缺节点按空字典）的 content（假值按空串）经 nodefile.ccg_completeness 判断，若 "生效条件" 不在其 required_present 中则返回 True，否则 False。
+def is_candidate(cg, nid) -> bool:
+    """候选判据：代码节点且正文缺『生效条件』（机械判据，唯一）。"""
+    if not str(nid).startswith(PREFIX):
+        return False
+    node = cg.get(nid) or {}
+    comp = nodefile.ccg_completeness(node.get("content") or "")
+    return "生效条件" not in comp["required_present"]
+
+
+# 生效条件：cg 与 nid 传入后，从 cg.get(nid)（缺节点按空字典）的 frontmatter（假值按空字典）的 code_ref（假值按空字典）中按 path/name/kind/lineno/end/lang/precise 各键取 ref.get(k)（缺键为 None），返回含 code_ref 与固定 landing_rule、landing_note 字段的落点字典。
+def _landing(cg, nid) -> dict:
+    """工单条目 → 源码落点（坐标 + 落点规则），供补写者直接定位。"""
+    node = cg.get(nid) or {}
+    fm = node.get("frontmatter") or {}
+    ref = fm.get("code_ref") or {}
+    return {
+        "code_ref": {k: ref.get(k) for k in
+                     ("path", "name", "kind", "lineno", "end", "lang", "precise")},
+        "landing_rule": "定义行紧邻上方连续井号注释（leading）或定义行紧邻下方、体首语句之前（body）",
+        "landing_note": "两窗口按源码物理行序合并；靠前者胜出（契约 §三.2）",
+    }
+
+
+# 生效条件：cg 与 nid 传入后，取 cg.get(nid)（缺节点按空字典）的 content（假值按空串）算长度与 refine._sha(content)[:16] 作为 source_sha，并结合 refine._entry(cg, nid) 的 layer/tags（tags 假值按空列表）与 nodefile.CCG_MARKS 得出 ccg_missing，最后合并 _landing(cg, nid) 的返回构成工单条目字典。
+def _item(cg, nid) -> dict:
+    node = cg.get(nid) or {}
+    content = node.get("content") or ""
+    comp = nodefile.ccg_completeness(content)
+    e = refine._entry(cg, nid)
+    it = {
+        "id": nid, "family": refine._family(cg, nid),
+        "layer": e.get("layer"), "tags": list(e.get("tags") or []),
+        "ccg_present": comp["present"],
+        "ccg_missing": [m for m in nodefile.CCG_MARKS if m not in comp["present"]],
+        "body_len": len(content),
+        "source_sha": refine._sha(content)[:16],
+    }
+    it.update(_landing(cg, nid))
+    return it
+
+
+# 生效条件：ids 非空时返回经 is_candidate(cg, i) 过滤后的显式候选与 meta.source='explicit_ids'；ids 为空时经 refine._pool(cg, PREFIX) 扫描返回候选与 meta.source='scan'（含 skipped_protected）。
+def candidates(cg, ids=None):
+    """候选池（只读）→ (ids, meta)。"""
+    if ids:
+        pool = sorted({str(i) for i in ids if is_candidate(cg, i)})
+        return pool, {"source": "explicit_ids", "pool": len(pool),
+                      "requested": len(pool), "candidates": len(pool)}
+    all_ids, protected = refine._pool(cg, PREFIX)
+    cands = sorted(i for i in all_ids if is_candidate(cg, i))
+    return cands, {"source": "scan", "prefix": PREFIX, "pool": len(all_ids),
+                   "skipped_protected": protected, "candidates": len(cands)}
+
+
+# 生效条件：seed 为假值（None/空串）时回落模块常量 SAMPLE_SEED，n 仅当为 None 时取 SAMPLE_N、否则 int(n)（n=0 保留 0）；ids 为真值时样本取全部候选，为假值（含空列表）时经 refine.sample_ids 抽样后按 is_candidate 过滤。
+def plan(x, ids=None, n=None, seed=None) -> dict:
+    """抽检工单（只读）：确定性样本 + 源码落点 + 口径声明 + 样本充分性。"""
+    cg = refine._as_cg(x)
+    seed = seed or SAMPLE_SEED
+    n = SAMPLE_N if n is None else int(n)
+    cands, cmeta = candidates(cg, ids=ids)
+    if ids:
+        sample = sorted(cands)
+        smeta = {"pool": len(cands), "sampled": len(cands), "families": 0, "strata": {}}
+    else:
+        picked, smeta = refine.sample_ids(cg, n=n, seed=seed, prefix=PREFIX)
+        sample = sorted(i for i in picked if is_candidate(cg, i))
+    items = [_item(cg, nid) for nid in sample]
+    strata = {}
+    for it in items:
+        s = strata.setdefault(it["family"], {"picked": 0, "missing_fields": {}})
+        s["picked"] += 1
+        for m in it["ccg_missing"]:
+            s["missing_fields"][m] = s["missing_fields"].get(m, 0) + 1
+    adequacy = {
+        "sample_of_code_nodes": smeta.get("sampled", len(sample)),
+        "candidates_in_sample": len(sample),
+        "candidate_yield": round(len(sample) / float(smeta.get("sampled") or 1), 4),
+        "note": "分配沿用 code_ 节点口径；产出率不足时应扩大 n 或改候选池重分配",
+    }
+    return {
+        "root": cg.root, "dry_run": True, "readonly": True,
+        "action": "comment_gate", "op": "maintain",
+        "prefix": PREFIX, "seed": seed, "requested": n,
+        "pool": cmeta, "sampled": len(items), "families": len(strata),
+        "sample": sample, "sample_sha": refine._sha(*sample)[:16] if sample else "",
+        "strata": strata, "items": items, "worklist": items,
+        "spec": SPEC, "gate_rule": SPEC["gate"], "sample_adequacy": adequacy,
+        "note": ("代码注释补写工单（只读）：供人工核对补写口径；"
+                 "核对通过率未达阈值前不得扩批。本动作不改任何节点。"),
+    }
+
+
+# 生效条件：verdicts（None 按 []）中可哈希且属于 okv 字面集合（True/"1"/"true"/"True"/"pass"/"PASS"/"faithful"/"忠实"/"accept"/"ACCEPT"）的项计 passed，dict 项在 `v in okv` 处不可哈希先抛 TypeError，故源码里 v.get("verdict") 的计数分支不可达；reviewed 为 0 时 rate=0.0、expand_allowed=False、reason="no_review"，否则按 rate 与模块常量 GATE_MIN_PASS_RATE 比较给出 expand_allowed 与 reason。
+def _stats(verdicts) -> dict:
+    """通过率（只认忠实/pass/True），阈值取 refine 唯一真源。"""
+    vs = list(verdicts or [])
+    okv = {True, "1", "true", "True", "pass", "PASS", "faithful", "忠实",
+           "accept", "ACCEPT"}
+    passed = 0
+    for v in vs:
+        if v in okv:
+            passed += 1
+        elif isinstance(v, dict) and v.get("verdict") in okv:
+            passed += 1
+    reviewed = len(vs)
+    rate = (passed / float(reviewed)) if reviewed else 0.0
+    allowed = reviewed > 0 and rate >= GATE_MIN_PASS_RATE
+    return {"reviewed": reviewed, "passed": passed, "pass_rate": round(rate, 4),
+            "min_pass_rate": GATE_MIN_PASS_RATE, "expand_allowed": allowed,
+            "reason": ("" if allowed else
+                       ("no_review" if reviewed == 0 else
+                        "rate %.4f < %.2f" % (rate, GATE_MIN_PASS_RATE)))}
+
+
+# 生效条件：x 传入后经 refine._as_cg 得到 cg，若 cg.principal 非 None 则调用其 require_admin("maintain_comment_gate")；随后调用 plan(cg, ids=ids, n=n, seed=seed) 取工单、调用 _stats(verdicts) 取闸门统计，batch 假值回落 time.strftime("%Y%m%d-%H%M%S")，os.makedirs(cg.root, exist_ok=True) 后把含 batch/actor/seed/pool/sample/verdicts/gate 等字段的记录以追加方式写入 _log_path(cg)，并返回 ok=True 的留痕结果。
+def apply(x, ids=None, n=None, seed=None, verdicts=None, actor=None, note=None,
+          batch=None) -> dict:
+    """落抽检批次 + 人工裁决到 _comment_gate.jsonl。**不改写任何节点**。
+
+    权限**自持在模块内**（与 refine 同档）：apply 虽只落留痕，但它决定后续是否放行
+    **扩批**，故按管理面处理。放在此处而非分发层，是为避免「分发面漏挂一道闸」
+    这类易失同步的权限缺口。
+    """
+    cg = refine._as_cg(x)
+    _principal = getattr(cg, "principal", None)
+    if _principal is not None:
+        _principal.require_admin("maintain_comment_gate")
+    p = plan(cg, ids=ids, n=n, seed=seed)
+    batch = batch or time.strftime("%Y%m%d-%H%M%S")
+    stats = _stats(verdicts)
+    rec = {"t": time.time(), "action": "comment_gate", "batch": batch, "actor": actor,
+           "seed": p["seed"], "requested": p["requested"], "pool": p["pool"],
+           "sampled": p["sampled"], "sample": p["sample"], "sample_sha": p["sample_sha"],
+           "sample_adequacy": p["sample_adequacy"], "verdicts": list(verdicts or []),
+           "gate": stats, "note": note}
+    os.makedirs(cg.root, exist_ok=True)
+    with open(_log_path(cg), "a", encoding="utf-8") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + chr(10))
+    return {"ok": True, "action": "comment_gate", "op": "maintain", "batch": batch,
+            "root": cg.root, "sampled": p["sampled"], "gate": stats, "log": LOG_NAME,
+            "note": ("抽检留痕已落盘（未改任何节点）；" +
+                     ("闸门放行扩批" if stats["expand_allowed"] else
+                      "闸门未放行：" + stats["reason"]))}
+
+
+# 生效条件：x 传入后经 refine._as_cg 得到 cg，读取 _log_path(cg) 且仅当 os.path.exists 为真时逐行解析（空行跳过、json.loads 抛 ValueError 的行跳过），batch 为真时仅保留 batch 字段匹配的记录；recs 为空时返回 expand_allowed=False、reason="no_batch"，否则取 recs[-1] 的 verdicts 经 _stats 复算并返回。
+def gate(x, batch=None) -> dict:
+    """扩批闸门：读留痕复算通过率（不写盘）。"""
+    cg = refine._as_cg(x)
+    recs = []
+    path = _log_path(cg)
+    if os.path.exists(path):
+        with open(path, encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    recs.append(json.loads(line))
+                except ValueError:
+                    continue
+    if batch:
+        recs = [r for r in recs if r.get("batch") == batch]
+    if not recs:
+        return {"ok": True, "action": "comment_gate_gate", "op": "maintain",
+                "root": cg.root, "batch": batch, "batches": 0,
+                "expand_allowed": False, "reason": "no_batch"}
+    rec = recs[-1]
+    stats = _stats(rec.get("verdicts"))
+    return {"ok": True, "action": "comment_gate_gate", "op": "maintain",
+            "root": cg.root, "batch": rec.get("batch"),
+            "batches": len({r.get("batch") for r in recs}), **stats}
+
+
+# 生效条件：root 传入后调用 codeindex.index_dir 扫描（max_files 假值回落 500，max_items 假值回落 2000），对返回 items 的每条 comments（假值按空列表）逐条先 str(c).lstrip("#").strip() 再判断是否以 "生效条件" 开头，全部不以该串开头的项进入候选并返回含 items/errors/stats/examined/candidates 的字典。
+def candidates_from_sources(root, patterns=None, max_files=None, max_items=None,
+                            skip_dirs=None):
+    """**源级**候选枚举（不依赖认知图）：扫源码树，筛出注释里缺『生效条件』的符号。
+
+    为什么需要它（2026-09-17 实测）：真实库 2934 条 code_ 节点的生效条件 **100% 是旧 render
+    的合成值**，故**图内候选池为 0**；而「源码里哪些符号缺条件注释」是**源侧事实**，
+    无须先重索引（重索引会让 2934 条同时失去条件、判 BLINDSPOT）。本入口绕开该一次性代价。
+
+    判据唯一且机械：符号的 **井号注释窗口**（leading + body，见 codeindex）中不存在以
+    『生效条件』开头的行；只认井号注释、不认 docstring——落点按 q-0 裁决。
+    """
+    items, errors, stats = codeindex.index_dir(
+        root, patterns=patterns, max_files=int(max_files or 500),
+        max_items=int(max_items or 2000), skip_dirs=skip_dirs)
+    cands = []
+    for it in items:
+        has = any(str(c).lstrip("#").strip().startswith("生效条件")
+                  for c in (it.get("comments") or []))
+        if not has:
+            cands.append(it)
+    return {"root": root, "items": cands, "errors": errors, "stats": stats,
+            "examined": len(items), "candidates": len(cands),
+            "note": ("源级枚举：判据=井号注释窗口内无『生效条件』行；"
+                     "不含图内节点状态，故不受存量渲染影响")}
+
+
+# 生效条件：it 传入后取 it.get("path")（假值按空串）按 "/" 分割首段作为 family（首段为空则 family="."），并返回含 id=codeindex.node_id(it)、name/kind、code_ref（path/lineno/end/lang/precise 各缺省 None）、comments（假值按空列表逐项 str）、以及固定 landing_rule 与 landing_note 的字典。
+def _landing_src(it) -> dict:
+    return {"id": codeindex.node_id(it), "name": it.get("name"),
+            "kind": it.get("kind"),
+            "family": (it.get("path") or "").split("/")[0] or ".",
+            "code_ref": {"path": it.get("path"), "lineno": it.get("lineno"),
+                         "end": it.get("end"), "lang": it.get("lang"),
+                         "precise": it.get("precise")},
+            "comments": [str(c) for c in (it.get("comments") or [])],
+            "landing_rule": ("定义行紧邻上方连续井号注释（leading）或定义行紧邻下方、"
+                             "体首语句之前（body）"),
+            "landing_note": "两窗口按源码物理行序合并；靠前者胜出（契约 §三.2）"}
+
+
+# 生效条件：root 传入后调用 candidates_from_sources(root, patterns=patterns, skip_dirs=skip_dirs, max_files=max_files, max_items=max_items) 得候选，seed 假值回落 SAMPLE_SEED，n 为 None 时取 SAMPLE_N 否则 int(n)（0 保持 0），按 path 首段（空则 "."）分族与 sha(seed, node_id) 排序后做族间确定性轮转取至多 n 项，返回只读源级工单。
+def plan_sources(root, n=None, seed=None, patterns=None, skip_dirs=None,
+                 max_files=None, max_items=None) -> dict:
+    """**源级**工单（只读）：确定性抽样 + 源码落点；不依赖认知图、不改任何节点。
+
+    抽样口径：按大域（顶层目录）**确定性轮转**（族内按 sha(seed,id) 排序）。
+    刻意**不复制** refine 的浮点最大余数分配——那是第二份实现，会引入漂移；
+    源级候选列表是精确的（无「先抽样再过滤」的口径损失），轮转已给出跨族覆盖。
+    """
+    seed = seed or SAMPLE_SEED
+    n = SAMPLE_N if n is None else int(n)
+    got = candidates_from_sources(root, patterns=patterns, skip_dirs=skip_dirs,
+                                 max_files=max_files, max_items=max_items)
+    fams = {}
+    for it in got["items"]:
+        top = (it.get("path") or "").split("/")[0] or "."
+        fams.setdefault(top, []).append(it)
+    pools = {f: len(v) for f, v in fams.items()}
+    names = sorted(fams)
+    for f in names:
+        fams[f].sort(key=lambda it: refine._sha(seed, codeindex.node_id(it)))
+    picked = []
+    while len(picked) < n and any(fams[f] for f in names):
+        for f in names:
+            if fams[f] and len(picked) < n:
+                picked.append(fams[f].pop(0))
+    work = [_landing_src(it) for it in picked]
+    return {"root": root, "dry_run": True, "readonly": True, "mode": "source_level",
+            "action": "comment_gate_sources", "op": "maintain",
+            "seed": seed, "requested": n, "examined": got["examined"],
+            "candidates": got["candidates"], "sampled": len(work),
+            "families": len(pools), "strata": pools,
+            "items": work, "worklist": work, "spec": SPEC,
+            "scan_errors": list(got["errors"])[:10], "scan_stats": got["stats"],
+            "gate_rule": SPEC["gate"],
+            "note": ("源级工单（只读）：不依赖认知图、不改任何节点；"
+                     "抽样为按大域的确定性轮转。")}
+
+
+# 生效条件：x 与 action 传入后，action=="comment_gate" 时若 kw.get("apply") 为真则转 apply(x, ids,n,seed,verdicts,actor,note,batch)，否则转 plan(x, ids,n,seed)；action=="comment_gate_verdict" 时转 gate(x, batch)；action 为 "comment_gate_sources" 或 "comment_gate_source_plan" 时以 root=kw.get("root") or getattr(x,"root",None) or str(x) 转 plan_sources(...)；其余 action 抛 ValueError。
+def run(x, action, **kw) -> dict:
+    """maintain op 分派入口（与 backfill.run 同形，便于 mcp_server 侧并列分派）。"""
+    if action == "comment_gate":
+        if kw.get("apply"):
+            return apply(x, ids=kw.get("ids"), n=kw.get("n"), seed=kw.get("seed"),
+                         verdicts=kw.get("verdicts"), actor=kw.get("actor"),
+                         note=kw.get("note"), batch=kw.get("batch"))
+        return plan(x, ids=kw.get("ids"), n=kw.get("n"), seed=kw.get("seed"))
+    if action == "comment_gate_verdict":
+        return gate(x, batch=kw.get("batch"))
+    if action in ("comment_gate_sources", "comment_gate_source_plan"):
+        root = kw.get("root") or getattr(x, "root", None) or str(x)
+        return plan_sources(root, n=kw.get("n"), seed=kw.get("seed"),
+                            patterns=kw.get("patterns"), skip_dirs=kw.get("skip_dirs"))
+    raise ValueError("未知 comment_gate action：%s（允许 comment_gate / "
+                     "comment_gate_verdict）" % action)