@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/codeindex.py

@@ -31,14 +31,37 @@ MAX_DOC = 400
 LANG_COMPILER = "compiler"
 LANG_WEAK = "other"
 
+# --------------------------------------------------------------------------
+# 渲染契约代际（版本戳）
+# --------------------------------------------------------------------------
+# 生效条件：`render` 的**产物形态**发生不兼容变化时 +1（形态不变的重构不 +1）；
+# 由 refindex 写入 frontmatter.code_ref.render_version（节点侧），由 selfreport
+# 随常驻进程自报（进程侧），两侧同取本常量——**同源，无第二处硬编码**。
+#
+# 用途（第③道防线，防「旧契约静默覆盖重建成果」）：
+#   ① 节点侧：`scripts/mdcg_verify_render_meta.py` 据 code_ref.render_version 机械
+#      判定「节点由哪一代 render 产出」，不再只靠形态启发式（正文含元条件行）；
+#   ② 进程侧：`scripts/mdcg_stale_servers.py` 据自报值判定活进程代际，堵住
+#      「进程启动时间晚于源码 mtime 故 stale=False、却持旧 render」的盲区
+#      （AGENTS.md §5 运维注记的活体实证：旧契约把全量重建成果刷回 old_synth）。
+#
+# 代际史：
+#   1 = 旧契约（npm 0.4.8 及以前）：合成区产出 `# 生效条件：载体/位置：…`，
+#       索引元条件冒用 CCG 字段名（合成即冒充）。
+#   2 = 三分区契约（2026-09-19）：源码 CCG 区置首 → 合成 CCG 区（不产出生效
+#       条件行）→ 索引元信息区（`# 索引元条件：…` 非 CCG 字段名 + 位置行）。
+RENDER_VERSION = 2
+
 
 # --------------------------------------------------------------------------
 # Python：AST 提取（精确）
 # --------------------------------------------------------------------------
+# 生效条件：node 传入后，取 ast.get_docstring(node, clean=True) 的返回值，若该返回值为假值则回落空串，返回 strip 后截断到模块级 MAX_DOC 的文本；
 def _doc_of(node):
     return (ast.get_docstring(node, clean=True) or "").strip()[:MAX_DOC]
 
 
+# 生效条件：lines 为源码行列表、lineno 为 1-based 定义行时，从 lines[lineno-2] 向上收集连续以 "#" 起始的行，遇空行且已收集到注释即停止，遇空行且未收集到注释则跳过继续，遇非注释非空行停止，返回按物理顺序排列的注释列表；lineno<=1 或初始无匹配时返回空列表；
 def _leading_comments(lines, lineno):
     """定义行前的连续注释（# ...）。"""
     out, i = [], lineno - 2
@@ -56,6 +79,55 @@ def _leading_comments(lines, lineno):
     return list(reversed(out))
 
 
+# 生效条件：node 具有真值 body 属性时返回 body[0].lineno；否则（body 为 None/假值/缺属性）返回 node.lineno；
+def _body_first_line(node):
+    """符号体首个语句的行号（1-based）；无体 → 定义行本身（窗口为空）。"""
+    body = getattr(node, "body", None) or []
+    return body[0].lineno if body else node.lineno
+
+
+# 生效条件：lines 为 source.split("\n") 得到的行列表、lineno 为 1-based 定义行、body_lineno 为 1-based 体首语句行时，在 end=max(lineno, body_lineno-1) 下扫描 lines[lineno:end]，收集 strip 后以 "#" 起始的行并返回；body_lineno-1 <= lineno 时返回空列表；
+def _body_comments(lines, lineno, body_lineno):
+    """符号**体内首个语句之前**的连续 `#` 注释（定义行紧下方，声明头区）。
+
+    这是与 `_leading_comments`（定义行**之上**）并列的**第二个窗口**：
+
+    · 既有白箱单元库 104+ 处把 CCG 注释块写在**这里**
+      （例：`md_cg/whitebox_kb/wisdom/python_code_units.py` 的模板
+      `def tokenize(src):` 下一行即 `    # 生效条件：参数 src 合法`）；
+    · 本函数是 body 窗口的**唯一真源**——`whitebox_kb/wisdom/verifier._ccg_block`
+      委托此处（历史文档里那句「与 `codeindex._body_comments` 同款语义」曾是
+      **悬空引用**：该名当时并不存在）。
+
+    参数：`lines`=源码行列表（`source.split("\\n")`）；`lineno`=定义行（1-based）；
+    `body_lineno`=体首个语句行（1-based）。窗口 = `lines[lineno : body_lineno-1]`
+    （0-based 切片：定义行之后 → 体首语句之前），只收 `#` 起始行。
+    语法上该窗口**结构性地只可能含注释/空行/docstring**——体首语句之前的区域。
+    """
+    start = lineno                      # 0-based 索引 → 定义行的下一行
+    end = max(start, body_lineno - 1)
+    out = []
+    for ln in lines[start:end]:
+        s = ln.strip()
+        if s.startswith("#"):
+            out.append(s)
+    return out
+
+
+# 生效条件：lines 为源码行列表且 node 含 lineno 时，返回 _leading_comments(lines, node.lineno) 与 _body_comments(lines, node.lineno, _body_first_line(node)) 的拼接结果（leading 在前、body 在后）；
+def _symbol_comments(lines, node):
+    """符号的「源码 CCG 区」= leading 窗口 + body 窗口，**按物理行序**合并。
+
+    不发明额外优先级：两个窗口在源文件里的物理先后天然确定（leading 在定义行
+    之上、body 在其下），而检索侧 `mdcos._ccg_field` 取**首个**匹配——于是
+    「靠前者胜出」与「物理序」是同一件事，确定性可复算。
+    单窗口文件的行为与改造前逐字一致（只多收 body 窗口）。
+    """
+    return (_leading_comments(lines, node.lineno)
+            + _body_comments(lines, node.lineno, _body_first_line(node)))
+
+
+# 生效条件：source 与 node 传入后，取 ast.get_source_segment(source, node) 的返回值，若抛 ValueError/TypeError 或返回假值则 seg 为空串，返回 seg.split("\n",1)[0].strip()[:200]；
 def _sig(source, node):
     try:
         seg = ast.get_source_segment(source, node) or ""
@@ -64,6 +136,7 @@ def _sig(source, node):
     return seg.split("\n", 1)[0].strip()[:200]
 
 
+# 生效条件：tree 为 AST 根节点时，调用嵌套 rec(tree, "") 按 ast.iter_child_nodes 源码顺序递归产出 (定义节点, 所属类名)；ClassDef 自身以当前 parent 产出并对其内部递归改用类名，FunctionDef/AsyncFunctionDef 以当前 parent 产出并保持 parent，其他节点递归保持 parent；
 def _walk_defs(tree):
     """按**源码顺序**产出 (定义节点, 所属类名)。
 
@@ -71,6 +144,7 @@ def _walk_defs(tree):
     父级归属是「子功能」与「不适用条件」两项的判定依据（同名方法必须能区分
     是哪个类的），不能省。
     """
+# 生效条件：node 为 AST 节点、parent 为当前所属类名字符串时，按 ast.iter_child_nodes(node) 顺序递归产出 (定义节点, 所属类名)：ClassDef 以 parent 产出并递归改用 child.name，FunctionDef/AsyncFunctionDef 以 parent 产出并递归保持 parent，其他节点递归保持 parent；
     def rec(node, parent):
         for child in ast.iter_child_nodes(node):
             if isinstance(child, ast.ClassDef):
@@ -84,6 +158,7 @@ def _walk_defs(tree):
     return rec(tree, "")
 
 
+# 生效条件：source 可被 ast.parse 成功解析时，返回首项为 module 条目（path、name=os.path.basename(path) or "<module>"、lineno=1、end=len(source.split("\n"))、doc=_doc_of(tree)）后接 _walk_defs(tree) 各定义条目的列表；source 触发 SyntaxError 时抛 ValueError(f"{path}:{exc.lineno}: {exc.msg}")；
 def _extract_python(source, path):
     try:
         tree = ast.parse(source)
@@ -101,7 +176,7 @@ def _extract_python(source, path):
             "path": path, "name": node.name, "kind": kind, "parent": parent,
             "lineno": node.lineno, "end": getattr(node, "end_lineno", node.lineno),
             "sig": _sig(source, node), "doc": _doc_of(node),
-            "comments": _leading_comments(lines, node.lineno)})
+            "comments": _symbol_comments(lines, node)})
     return items
 
 
@@ -118,6 +193,7 @@ _JS_DEF = re.compile(
 _JS_MODULE_SCOPE_ONLY = ("const", "type", "enum")
 
 
+# 生效条件：lines 为源码行列表、lineno 为 1-based 定义行时，从 lines[lineno-2] 向上收集连续以 "//" 开头的行注释，或遇到 strip 后以 "*/" 结尾的行时向上收集到首个 strip 后以 "/*" 开头的行（含该行）作为块注释；lookback 默认 25 限制收集行数，lookback=0 时循环不进入并返回空列表；遇空行且已有收集即停止，空行且未收集则跳过，其他行停止；
 def _leading_js_comments(lines, lineno, lookback=25):
     """定义行前的连续行注释块，或紧邻的 /** ... */ 块。"""
     out, i = [], lineno - 2
@@ -146,6 +222,7 @@ def _leading_js_comments(lines, lineno, lookback=25):
     return list(reversed(out))
 
 
+# 生效条件：对 source 用 _JS_DEF.finditer 命中项生成条目（首项模块条目 name 为 os.path.basename(path) or "<module>"），跳过 kind 属于 _JS_MODULE_SCOPE_ONLY 且 indent 组非空的命中；其余命中按出现顺序取 lineno、kind、name、sig，end 为下一命中行号减一或 len(source.split("\n")) 且不小于 lineno，comments 由 _leading_js_comments(lines, lineno) 生成。
 def _extract_weak(source, path):
     """正则弱提取：返回条目，`end` 为**上界**（到下一个定义之前），不保证精确。"""
     lines = source.split("\n")
@@ -182,6 +259,7 @@ EXTRACTORS = {
 SUFFIX = tuple(sorted(EXTRACTORS))
 
 
+# 生效条件：lines 为行列表、lineno 与 end 为 1-based 行号时，对 "\n".join(lines[max(0, lineno-1):max(0, end)]) 的 UTF-8 字节求 sha1，返回其十六进制前 12 位；
 def region_hash(lines, lineno, end):
     """被引用行的 sha1 前 12 位（变更探测用，非内容寻址）。
 
@@ -192,6 +270,7 @@ def region_hash(lines, lineno, end):
     return hashlib.sha1(seg.encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：source 与 path 传入后，ext=suffix or os.path.splitext(path)[1].lower()；当 ext 存在于模块级 EXTRACTORS 时，用对应 fn(source, path) 抽取并给每个条目补 lang/precise/basis/hash（hash 由 region_hash(lines, it["lineno"], it["end"]) 算）后返回；ext 不在 EXTRACTORS 时抛 ValueError(f"无提取器（suffix={ext or '<none>'}）")；
 def extract(source, path="", suffix=None):
     """抽取一个文件的条目；按后缀分派提取器。语法错误抛 ValueError。
 
@@ -213,15 +292,18 @@ def extract(source, path="", suffix=None):
     return items
 
 
+# 生效条件：item 为条目字典时，path=item.get("path") or ""、top=path.split("/")[0] or "."，按 item.get("precise", True)（缺键默认 True，键存在假值走弱提取）选择 LANG_COMPILER 或 LANG_WEAK 方法文本，返回 observation_position 用 top、time_window 用 nodefile.FULL_TIME_WINDOW_MIN 与 nodefile.FULL_TIME_WINDOW_MAX、observation_tool 用方法文本、existence_constraint 含 path 的四槽字典；
 def condition_space(item):
     """条目 → 条件空间四槽（纯函数，**唯一来源**）。
 
-    为什么必须与 `render` 同源：正文的 `# 生效条件：` 行与 frontmatter 的
+    为什么必须与 `render` 同源：正文的 `# 索引元条件：` 行与 frontmatter 的
     `condition_space` 一旦各写一套，就会出现「正文有声明、条件空间是空的」
     ——`nodefile.condition_space_text(require_full=True)` 只看 frontmatter，
     于是节点**存得进、判得了，条件空间却没声明**。改造前正是这样：正文写
     「大域=X；检索…时」（第三种方言），frontmatter 只写 `observation_position`
     **单槽**。单槽不是生效条件（见 nodefile.CONDITION_SLOTS_REQUIRED），
+    该四槽在正文里由「索引元条件」行承载（**不再**占用「生效条件」字段——
+    Phase 0 契约裁决，见 nodefile.INDEX_META_MARK），
     故本函数按四槽齐备产出，供 `render` 与 `refindex.add_items` 共用。
 
     时间槽用**全时窗哨兵**而非 `mdcg.add` 缺省补的「写入时刻锚定 1 小时窗」：
@@ -244,8 +326,9 @@ def condition_space(item):
     }
 
 
+# 生效条件：item 为含 "name"、"kind"、"path"、"lineno"、"end" 键的条目字典时（缺这些必需键会 KeyError），返回由 item.get("comments") 的源码 CCG 区、合成 CCG 区、索引元信息区依次拼接的正文；parent/doc/comments/sig 按 item.get 缺键或假值回落，precise 缺键默认 True、键存在假值走弱提取，item["lineno"]/item["end"] 用于 basis 与位置行；
 def render(item):
-    """条目 → CCG 6 行正文（可被 search 命中，不含实现）。
+    """条目 → 正文三分区：源码 CCG 区（人工优先）→ 合成 CCG 区 → 索引元信息区。
 
     **必须渲染成 CCG 格式**，这是本模块最容易踩的坑：
     `judge_qualification` 第一步就查 `ccg_completeness` 的 5 要素
@@ -255,6 +338,16 @@ def render(item):
     `# path::name` / `# sig` / `# doc:` 这类非 CCG 行，于是**所有代码节点
     恒定 BLINDSPOT**：存得进、判不了、检索不到（与「目标节点的 CCG 渲染」
     是同一策略，见 mdcg.py 的对应注释）。
+
+    Phase 0 修复（行序压制 + 字段语义分家；契约见
+    docs/mdcg/代码评审与条件化注释_契约_v0.1.md）：
+      ① **源码 CCG 区置首**——mdcos._ccg_field 取**首个**匹配，置首即
+         「人工优先」的确定性序：人工声明的生效条件不再被合成行压制；
+      ② 合成区**不再产出生效条件行**——索引元条件不是功能前置条件
+         （裁定见 nodefile.INDEX_META_MARK）。故源码未声明的条目会**诚实地
+         缺该要素（BLINDSPOT）**，而不是被元条件冒充成 DEFER；
+      ③ 索引元信息区改用非 CCG 字段名（索引元条件行 + 位置行），两个语义
+         不再挤同一个字段名（可机械判：nodefile.is_ccg_mark）。
     """
     name = item["name"]
     kind = item["kind"]
@@ -270,27 +363,37 @@ def render(item):
     else:
         basis = (f"{LANG_WEAK}（正则弱提取，未过编译器；区间为**上界**，"
                  f"以 op=ref 回读为准：{path} L{item['lineno']}-L{item['end']}）")
-    lines = [
+    # ---- 三分区组装（顺序即语义，不许随手改）------------------------------
+    #   ① 源码 CCG 区：人工/源码声明逐字保留，**置首**取得「首个匹配」优先权
+    #   ② 合成 CCG 区：机械补齐 5 要素，保证 ccg_completeness 不因缺行整体失效
+    #   ③ 索引元信息区：非 CCG 字段名 + 位置行（与 CCG_MARKS 零重名）
+    lines = ["# " + c for c in comments]
+    lines += [
         f"# 功能名：{name}（{kind}）",
-        f"# 生效条件：{nodefile.condition_space_text(condition_space(item))}",
         f"# 子功能：{parent + '.' if parent else ''}{sub[:MAX_DOC]}",
         f"# 执行：{sig}",
         f"# 验证方式：{basis}",
         "# 不适用条件：其它大域的**同名**符号（同名不同域时以 path 区分；"
         f"本条目属于 {path}）",
+        # 索引元条件**不占用**生效条件字段：它是「条目在何处/何时可被观测」，
+        # 不是「这段代码在何种输入下正确」。合成即冒充（nodefile.INDEX_META_MARK）。
+        f"# {nodefile.INDEX_META_MARK}："
+        + nodefile.condition_space_text(condition_space(item),
+                                        require_full=False),
         f"# 位置：{path}:{item['lineno']}-{item['end']}"
         f"（{item.get('lang')}，precise={bool(item.get('precise', True))}）",
     ]
-    lines.extend("# " + c for c in comments)
     return "\n".join(lines)
 
 
+# 生效条件：item 为含 "path" 与 "name" 键的字典时（缺任一键会 KeyError），返回 "code_" 加 (item["path"] + "::" + item["name"]).encode("utf-8") 的 sha1 十六进制前 12 位；
 def node_id(item):
     """稳定 id：path::name 的短哈希（重复索引幂等）。"""
     key = (item["path"] + "::" + item["name"]).encode("utf-8")
     return "code_" + hashlib.sha1(key).hexdigest()[:12]
 
 
+# 生效条件：skip_dirs 传入后，遍历 (skip_dirs or ()) 把每项 str(raw).strip().replace("\\","/").strip("/")，空串跳过；含 "/" 的加入 paths，不含 "/" 的加入 names；若归一化后无规则返回 (None, [])，否则返回 (hit, rules)，其中 hit(rel_dir, base) 在 base 命中 names 或 rel_dir 等于/前缀匹配 paths 中某条加 "/" 时为 True；
 def skip_matcher(skip_dirs):
     """把调用方的 `skip_dirs` 编译成「该子目录是否排除」的判定 `hit(rel_dir, base)`。
 
@@ -320,6 +423,7 @@ def skip_matcher(skip_dirs):
     if not rules:
         return None, []
 
+# 生效条件：在 skip_matcher 返回的闭包中，rel_dir 与 base 传入后，若 base 命中由 skip_dirs 归一化出的不含 "/" 的目录名集合 names 则返回 True；否则若 rel_dir 等于或以其某个含 "/" 的路径规则 paths 加 "/" 为前缀则返回 True；两者都不满足返回 False；
     def hit(rel_dir, base):
         if base in names:
             return True
@@ -328,6 +432,7 @@ def skip_matcher(skip_dirs):
     return hit, rules
 
 
+# 生效条件：当 root 为可 os.walk 的目录时返回 (items, errors, stats)；patterns 为 None 时按模块常量 SUFFIX 取后缀，命中 max_files 或 max_items 上限则在 stats['truncated'] 上报截断，fresh 为 None 时逐文件读盘。
 def index_dir(root, patterns=None, max_files=500, max_items=2000,
               fresh=None, on_file=None, skip_dirs=None):
     """按大域（目录）遍历代码，产出 `(items, errors, stats)`。零 LLM。
@@ -350,11 +455,25 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
     pats = tuple(patterns or SUFFIX)
     hit_skip, skip_rules = skip_matcher(skip_dirs)
     items, errors, files = [], [], 0
+    hit_files = 0
     seen_suffix = set()
     stats = {"root": root, "patterns": list(pats), "files": 0, "truncated": False,
              "truncated_reason": "", "max_files": max_files, "max_items": max_items,
              "skipped_suffixes": [], "skipped_unchanged": 0,
-             "skip_dirs": list(skip_rules), "skipped_dirs": []}
+             "skip_dirs": list(skip_rules), "skipped_dirs": [],
+             # 截断**可复算**：命中（后缀匹配）文件数与本轮已产出条目数。
+             # 与 truncated_reason 一起读，调用方才能核对「差多少」而不是只看到"被截断了"。
+             "hit_files": 0, "indexed_items": 0}
+
+# 生效条件：无参闭包，只在本次扫库作用域内可调用；把 files / hit_files / indexed_items / skipped_suffixes / skipped_dirs 一次性落进 stats，三处 return 共用同一口径；
+    def _snap():
+        """把「截断相关」计数一次性落进 stats（三处 return 共用，避免各处口径漂移）。"""
+        stats["files"] = files
+        stats["hit_files"] = hit_files
+        stats["indexed_items"] = len(items)
+        stats["skipped_suffixes"] = sorted(
+            s for s in seen_suffix if s and s not in pats)[:12]
+
     for dirpath, dirnames, filenames in os.walk(root):
         rel_dir = os.path.relpath(dirpath, root).replace("\\", "/")
         if rel_dir == ".":
@@ -369,21 +488,22 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
                 stats["skipped_dirs"].append(child)
                 continue
             keep.append(d)
-        dirnames[:] = keep
+        # 目录序**必须确定性**：os.walk 给出的 dirnames 顺序由文件系统决定，
+        # 同一次输入两次运行可能不同 → 索引结果不可复算。排序后 walk 顺序唯一。
+        dirnames[:] = sorted(keep)
         for fn in sorted(filenames):
             ext = os.path.splitext(fn)[1].lower()
             seen_suffix.add(ext)
             if not fn.lower().endswith(pats):
                 continue
+            hit_files += 1
             if files >= max_files or len(items) >= max_items:
                 stats["truncated"] = True
                 stats["truncated_reason"] = (
                     f"files={files}>=max_files={max_files}"
                     if files >= max_files else
                     f"items={len(items)}>=max_items={max_items}")
-                stats["files"] = files
-                stats["skipped_suffixes"] = sorted(
-                    s for s in seen_suffix if s and s not in pats)[:12]
+                _snap()
                 return items, errors, stats
             files += 1
             fp = os.path.join(dirpath, fn)
@@ -404,12 +524,9 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
                     stats["truncated"] = True
                     stats["truncated_reason"] = (
                         f"items={len(items)}>=max_items={max_items}")
-                    stats["files"] = files
-                    stats["skipped_suffixes"] = sorted(
-                        s for s in seen_suffix if s and s not in pats)[:12]
+                    _snap()
                     return items, errors, stats
             except (OSError, UnicodeDecodeError, ValueError) as exc:
                 errors.append(f"{rel}: {exc}")
-    stats["files"] = files
-    stats["skipped_suffixes"] = sorted(s for s in seen_suffix if s and s not in pats)[:12]
-    return items, errors, stats
+    _snap()
+    return items, errors, stats

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)