@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/mreview/__main__.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+"""M1 机械层入口（零写入）：
+
+    python -m md_cg.mreview [--root R] [--out dump.json] [--full] [--limit N]
+
+默认只打印/落盘**摘要 + 包清单 + 机械聚合**；``--full`` 追加条目明细与逐条机械 issue
+（真源全量 dump 会很大，默认裁剪是为可审查性服务，不是隐藏内容）。
+"""
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import os
+
+from .. import conformance as CF
+from ..datapath import mdcg_root
+from . import bundle as BD
+from . import candidates as CD
+from . import ruleset as RS
+
+
+# 生效条件：root 为假值（None/空串）时回落 mdcg_root()，sources 缺省取模块常量 CD.SOURCES 并透传给 CD.generate，返回 dict out，且仅当 full 为真值时额外带上 candidates_full、bundles_full、packages_full 三键。
+def run(root=None, *, sources=CD.SOURCES, cold_limit=500, patrol_window=200,
+        max_per_bundle=50, limit=None, patrol_offset=None, rules_dir=None,
+        full=False) -> dict:
+    root = root or mdcg_root()
+    nodes = CF.load_index(root) or {}       # load_index 直接返回 nodes 字典
+    gen = CD.generate(root, sources=sources, nodes=nodes, limit=limit,
+                      cold_limit=cold_limit, patrol_window=patrol_window,
+                      patrol_offset=patrol_offset, with_report=True)
+    bd = BD.bundle(gen["candidates"], nodes=nodes, root=root,
+                   max_per_bundle=max_per_bundle)
+    asm = RS.assemble_all(bd, rules_dir=rules_dir)
+    by_rule = collections.Counter(i["rule_id"] for p in asm["packages"] for i in p["mechanical"])
+    out = {
+        "root": root,
+        "candidates": {"by_source": gen["by_source"], "total_raw": gen["total_raw"],
+                       "total": gen["total"], "skipped": gen["skipped"]},
+        "report": gen.get("report"),
+        "assertions": gen.get("assertions"),
+        "bundles": [{"bundle_id": b["bundle_id"], "group_kind": b["group_kind"],
+                     "group_key": b["group_key"], "size": b["size"], "refs": b["refs"]}
+                    for b in bd["bundles"]],
+        "bundle_stats": bd["stats"],
+        "content_missing": bd["content_missing"],
+        "assemble_stats": asm["stats"],
+        "mechanical_by_rule": dict(by_rule),
+        "llm_checks": sorted({(c["rule_id"], c["check"]) for p in asm["packages"]
+                              for c in p["llm"]}),
+    }
+    if full:
+        out["candidates_full"] = gen["candidates"]
+        out["bundles_full"] = bd["bundles"]
+        out["packages_full"] = asm["packages"]
+    return out
+
+
+# 生效条件：d 必须已含 candidates、bundle_stats、assemble_stats、root、content_missing、llm_checks 这些键（直接下标取值，缺键即 KeyError），且仅当 d.get("assertions") 为真值（非空映射）时才追加断言集一行，其 failed 空或缺失时回落显示「无」。
+def _fmt_summary(d: dict) -> str:
+    c, b, a = d["candidates"], d["bundle_stats"], d["assemble_stats"]
+    lines = ["", "== M1 机械层（候选 → 捆绑 → 规则装配） ==",
+             "真源：%s" % d["root"],
+             "候选：原始 %d 条 → 去重后 %d 条（按源：%s）"
+             % (c["total_raw"], c["total"],
+                ", ".join("%s=%d" % kv for kv in sorted(c["by_source"].items()))),
+             "跳过（未落盘/无节点）：%d 条" % len(c["skipped"]),
+             "捆绑：%d 包（最大 %d 条/包；分组类型 %s）"
+             % (b["bundles"], b["largest"], b["by_group_kind"]),
+             "正文缺失：%d 条（读盘失败计入，不冒充内容）" % d["content_missing"],
+             "规则：%d 条（%s）" % (len(a["rules"]), ", ".join(a["rules"])),
+             "机械检查：%d 条 issue（按类 %s）" % (a["mechanical_total"], a["mechanical_by_kind"]),
+             "待 LLM 检查项：%d 条（%s）"
+             % (a["llm_checks"], ", ".join("%s:%s" % t for t in d["llm_checks"]))]
+    asr = d.get("assertions") or {}
+    if asr:
+        lines.append("断言集交叉核对：verdict=%s，未达标项 %s"
+                     % (asr.get("verdict"), ", ".join(asr.get("failed") or []) or "无"))
+    return "\n".join(lines)
+
+
+# 生效条件：argv 为 None 时 argparse 改从 sys.argv[1:] 取参，--sources 按逗号切分并丢弃空串后组成元组传入 run，仅当 --out 为非空串时才以 UTF-8 落盘 JSON dump，各分支之后统一 return 0。
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m md_cg.mreview",
+                                 description="M1 机械层：候选生成→捆绑→规则装配（只读零写入）")
+    ap.add_argument("--root", default=None, help="认知图根（缺省 MDCG_ROOT/默认路径）")
+    ap.add_argument("--sources", default=",".join(CD.SOURCES))
+    ap.add_argument("--limit", type=int, default=None)
+    ap.add_argument("--cold-limit", type=int, default=500)
+    ap.add_argument("--patrol-window", type=int, default=200)
+    ap.add_argument("--patrol-offset", type=int, default=None)
+    ap.add_argument("--max-per-bundle", type=int, default=50)
+    ap.add_argument("--rules-dir", default=None)
+    ap.add_argument("--out", default=None, help="落盘 dump（JSON）")
+    ap.add_argument("--full", action="store_true", help="含条目明细与逐条 issue")
+    a = ap.parse_args(argv)
+    d = run(a.root, sources=tuple(s for s in a.sources.split(",") if s),
+            cold_limit=a.cold_limit, patrol_window=a.patrol_window, limit=a.limit,
+            patrol_offset=a.patrol_offset, max_per_bundle=a.max_per_bundle,
+            rules_dir=a.rules_dir, full=a.full)
+    print(_fmt_summary(d))
+    if a.out:
+        with open(os.path.abspath(a.out), "w", encoding="utf-8") as f:
+            json.dump(d, f, ensure_ascii=False, indent=1)
+        print("已落盘：%s" % os.path.abspath(a.out))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/md_cg/mreview/bundle.py

@@ -0,0 +1,178 @@
+# -*- coding: utf-8 -*-
+"""记忆评审流水线 · 级 2：捆绑（确定性，零写入）。
+
+真源：docs/记忆评审系统_立项设计与施工交接_20260915.md §3 第 2 级。
+
+**同模板组一包一评**：批次报告类节点（「批次N收官记忆」）正文各不相同但同模板，
+逐条评审＝重复劳动且立场漂移；成组评审＝一次裁决整组。分组键优先级：
+
+1. ``template`` 模板签名——复用 :func:`writelimit.template_signature`（强信号 ``t:``）；
+   长文（≥ MAX_CONTENT）无标题签名时回退**首行骨架**（弱信号 ``h:``）——真源知识节点
+   正文多为长文四要素，标题/首行才是同模板流水的载体（该回退只在评审分组内生效，
+   不改写侧聚合口径）。
+2. ``lineage``  血缘——branch_id / branched_from / derived_from[0]（同源迁移一起看）。
+3. ``topic``    标签前缀集合（无标签回退层）。
+4. ``batch``    无任何分组特征的孤立候选，按确定性顺序成批（不误聚、不丢弃）。
+
+组内条数 < ``min_group`` 的组降级并入 batch；组内超 ``max_per_bundle`` 切分多包。
+包号确定性：``b1_<kind>_<sha1(key)[:8]>_c<idx>``；同一输入两次运行逐字节一致。
+"""
+from __future__ import annotations
+
+import collections
+import hashlib
+import os
+
+from .. import conformance as CF
+from .. import writelimit as WL
+
+GROUP_TEMPLATE = "template"
+GROUP_LINEAGE = "lineage"
+GROUP_TOPIC = "topic"
+GROUP_BATCH = "batch"
+
+
+# 生效条件：content 为假值（如空串）时返回 (None, None)；content 为真且 WL.template_signature(content) 返回真值时返回 (s, 'strong')；否则遍历 content.splitlines() 中 strip 后非空的行，遇首个非空行时其 WL._skeleton 长度 ≥ WL.MIN_SKELETON 则返回 ('h:' + sk, 'head')，否则立即返回 (None, None)（不再看后续行），无任何非空行时也返回 (None, None)；
+def _sig_of(content: str):
+    """模板签名（强/弱）。返回 (sig, kind) 或 (None, None)。"""
+    if not content:
+        return None, None
+    s = WL.template_signature(content)
+    if s:
+        return s, "strong"
+    for line in content.splitlines():
+        t = line.strip()
+        if not t:
+            continue
+        sk = WL._skeleton(t)
+        if len(sk) >= WL.MIN_SKELETON:
+            return "h:" + sk, "head"
+        return None, None
+    return None, None
+
+
+# 生效条件：meta（dict）中按 ("branched_from", "branch_id") 顺序取到的首个 v 为真且 str(v) != 'None' 时返回 str(v)；否则 meta.get('derived_from') 为 list/tuple 且非空时返回 str(d[0])；否则其为非空 str 且不等于 '[]' 与 'None' 时返回该 str 本身；以上皆不成立时返回 None；
+def _lineage_key(meta: dict):
+    for f in ("branched_from", "branch_id"):
+        v = meta.get(f)
+        if v and str(v) != "None":
+            return str(v)
+    d = meta.get("derived_from")
+    if isinstance(d, (list, tuple)) and d:
+        return str(d[0])
+    if isinstance(d, str) and d and d not in ("[]", "None"):
+        return d
+    return None
+
+
+# 生效条件：meta 为真时先取 sorted(CF._tag_prefixes(meta)) 作为 pref，pref 为空且 tags 有真值元素时改用各 tag 的 str(t).split(':', 1)[0]（跳过假值 tag）集合排序；pref 非空返回 '+'.join(pref)；pref 为空时取 str((meta or {}).get('layer') or '')，该层名非空返回 'layer:' + layer，层名为假值（None/空串/0）则返回 None；
+def _topic_key(meta: dict, tags: list):
+    pref = sorted(CF._tag_prefixes(meta)) if meta else []
+    if not pref and tags:
+        pref = sorted({str(t).split(":", 1)[0] for t in tags if t})
+    if pref:
+        return "+".join(pref)
+    layer = str((meta or {}).get("layer") or "")
+    return ("layer:" + layer) if layer else None
+
+
+# 生效条件：content 经 _sig_of 得到的 sig 为真时返回 (GROUP_TEMPLATE, sig, kind)；否则 meta 经 _lineage_key 得到的值非空时返回 (GROUP_LINEAGE, lin, None)；否则 (meta, tags) 经 _topic_key 得到的值非空时返回 (GROUP_TOPIC, top, None)；三者皆不成立时返回 (GROUP_BATCH, 'misc', None)；
+def _group_of(meta: dict, tags: list, content: str):
+    sig, kind = _sig_of(content)
+    if sig:
+        return GROUP_TEMPLATE, sig, kind
+    lin = _lineage_key(meta)
+    if lin:
+        return GROUP_LINEAGE, lin, None
+    top = _topic_key(meta, tags)
+    if top:
+        return GROUP_TOPIC, top, None
+    return GROUP_BATCH, "misc", None
+
+
+# 生效条件：root 与 meta 均为真、且 meta.get('path') 经 or '' 再 str 后为非空路径时，把 rel 中的 '\\' 与 '/' 替换为 os.sep 并与 root 拼接，以 encoding='utf-8'、errors='replace' 打开并返回 f.read(int(limit))（limit 为 0 时读 0 字节）；root 或 meta 为假值、rel 为空、或该打开/读取抛 OSError 时返回 None；
+def _load_content(root: str, meta: dict, limit: int):
+    if not root or not meta:
+        return None
+    rel = str(meta.get("path") or "")
+    if not rel:
+        return None
+    p = os.path.join(root, rel.replace("\\", os.sep).replace("/", os.sep))
+    try:
+        with open(p, encoding="utf-8", errors="replace") as f:
+            return f.read(int(limit))
+    except OSError:
+        return None
+
+
+# 生效条件：恒返回构造 dict——ref/node_id/proposal_id/origin/layer/role/importance/evidence_count/verification_basis/lifecycle_state 均以 .get 取值（缺键得 None），content_hash 先取 cand.get('content_hash') 为空再取 (meta or {}).get('content_hash')，tags/issue_kinds/evidence 经 or [] 后 list 化，excerpt 取 (content or '')[:int(limit)] 为空时（含 content 为空串或 limit 为 0）为 None；
+def _entry(cand: dict, meta: dict, content: str, limit: int) -> dict:
+    return {"ref": cand.get("key"), "node_id": cand.get("node_id"),
+            "proposal_id": cand.get("proposal_id"), "origin": cand.get("origin"),
+            "layer": cand.get("layer"), "tags": list(cand.get("tags") or []),
+            "role": (meta or {}).get("role"),
+            "importance": (meta or {}).get("importance"),
+            "evidence_count": (meta or {}).get("evidence_count"),
+            "verification_basis": (meta or {}).get("verification_basis"),
+            "lifecycle_state": (meta or {}).get("lifecycle_state"),
+            "content_hash": cand.get("content_hash") or (meta or {}).get("content_hash"),
+            "issue_kinds": list(cand.get("issue_kinds") or []),
+            "evidence": list(cand.get("evidence") or []),
+            "excerpt": (content or "")[:int(limit)] or None}
+
+
+# 生效条件：ids 与 size 为必需形参，size 先经 max(1, int(size))（0、负值或 1 均按 1）作为步长，返回 [ids[i:i + size] for i in range(0, len(ids), size)]；ids 为空（如 [] 或空串）时返回 []；
+def _chunks(ids: list, size: int) -> list:
+    size = max(1, int(size))
+    return [ids[i:i + size] for i in range(0, len(ids), size)]
+
+
+# 生效条件：candidates（list）为必需输入，nodes 为假值时按 {} 取节点表；逐候选以 c.get('node_id') 查 meta（无 node_id 则 meta 为 {}）、以 c.get('content') or '' 取内容，内容为空且 read_content 为真且 nid 为真时改用 _load_content(root, meta, content_limit) 的结果（再 or ''），并按 int(content_limit) 截断；随后按 _group_of(meta, c.get('tags') or [], content) 分组，非 GROUP_BATCH 且组内 id 数 < int(min_group)（min_group 为 0 时该比较恒不成立，即无降级）的组与既有 GROUP_BATCH 组一并降级，降级集合非空时并入 (GROUP_BATCH, 'misc')、为空则不建该组；再对每组按 int(max_per_bundle) 经 _chunks 切块生成带 entries 的 bundles 与 stats，返回 content_missing 为 contents 中该候选键对应值为假值的候选数；
+def bundle(candidates: list, nodes=None, root=None, *, max_per_bundle=50,
+           min_group=2, read_content=True, content_limit=3000) -> dict:
+    """候选清单 → 待评包（含条目上下文与机械字段，供级 3 装配与级 4 spec）。"""
+    nodes = nodes or {}
+    bykey = {c.get("key"): c for c in candidates}
+    groups, contents = {}, {}
+    for c in candidates:
+        nid = c.get("node_id")
+        meta = (nodes.get(nid) or {}) if nid else {}
+        content = c.get("content") or ""
+        if not content and read_content and nid:
+            content = _load_content(root, meta, content_limit) or ""
+        content = (content or "")[:int(content_limit)]
+        kind, key, sig_kind = _group_of(meta, c.get("tags") or [], content)
+        g = groups.get((kind, key))
+        if g is None:
+            g = groups[(kind, key)] = {"ids": [], "sig_kind": sig_kind}
+        g["ids"].append(c.get("key"))
+        contents[c.get("key")] = content
+
+    # 小组降级并入 batch（不误聚、不丢弃）
+    demoted = []
+    for k in [k for k, g in groups.items()
+              if k[0] != GROUP_BATCH and len(g["ids"]) < int(min_group)]:
+        demoted += groups.pop(k)["ids"]
+    for k in [k for k in groups if k[0] == GROUP_BATCH]:
+        demoted += groups.pop(k)["ids"]
+    demoted = sorted(demoted)
+    if demoted:
+        groups[(GROUP_BATCH, "misc")] = {"ids": demoted, "sig_kind": None}
+
+    bundles = []
+    for (kind, key) in sorted(groups):
+        g = groups[(kind, key)]
+        for i, chunk in enumerate(_chunks(sorted(g["ids"]), int(max_per_bundle))):
+            bid = "b1_%s_%s_c%d" % (kind, hashlib.sha1(str(key).encode("utf-8")).hexdigest()[:8], i)
+            bundles.append({
+                "bundle_id": bid, "group_kind": kind, "group_key": str(key),
+                "group_sig_kind": g["sig_kind"], "size": len(chunk), "refs": chunk,
+                "entries": [_entry(bykey[r], nodes.get(bykey[r].get("node_id") or "") or {},
+                                   contents.get(r) or "", content_limit)
+                            for r in chunk]})
+    stats = {"candidates": len(candidates), "bundles": len(bundles),
+             "largest": max([b["size"] for b in bundles] or [0]),
+             "by_group_kind": dict(collections.Counter(b["group_kind"] for b in bundles))}
+    return {"bundles": bundles, "stats": stats,
+            "content_missing": sum(1 for c in candidates
+                                   if not contents.get(c.get("key")))}

package/md_cg/mreview/candidates.py

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+"""记忆评审流水线 · 级 1：候选生成（确定性，零写入）。
+
+真源：docs/记忆评审系统_立项设计与施工交接_20260915.md §3 第 1 级。
+
+四源（可单独关闭）：
+
+* ``assertion``   断言集超限项的**条目级展开**——复用 conformance 的**同一判据函数**
+  （`_coverage_metrics` / `unanalyzed` / `_dup_metrics` / `_edge_metrics`），
+  保证「报告聚合数」与「条目清单」两个入口同口径（见 test_mr_m1 T4）。
+* ``defer_queue`` 闸门待裁决提案（inbox 未被 decisions 覆盖）＋遗忘日志 DEFER 留痕；
+  未落盘的 node_id 计入 ``skipped``，**如实上报不冒充候选**。
+* ``cold``        access log 触达集合之外、且重要度不低的节点（久未触达者更值得评审）。
+* ``patrol``      sha1(node_id) 排序切片轮巡（offset 决定窗口位置），多轮不重不漏。
+
+纪律：零写入；输出顺序由 (优先级, node_id) 决定；每条候选必带证据。
+"""
+from __future__ import annotations
+
+import collections
+import hashlib
+import json
+import os
+import time
+
+from .. import conformance as CF
+from ..datapath import mdcg_root
+
+SOURCES = ("assertion", "defer_queue", "cold", "patrol")
+_PRIORITY = {"assertion": 0, "defer_queue": 1, "cold": 2, "patrol": 3}
+FORGET_LOG = "_forgetting.jsonl"
+PATROL_EPOCH = 3600.0          # 轮巡窗口推进周期（秒）：默认每窗口周期轮转一格
+COLD_IMPORTANCE_MIN = 0.6      # 冷节点抽样门槛（importance 解析失败按 0 计）
+
+
+# 生效条件：path 不满足 os.path.exists(path) 时返回 []；否则逐行 strip 后跳过空行与 json.JSONDecodeError 行，返回成功 json.loads 的每行结果列表。
+def _read_jsonl(path: str) -> list:
+    if not os.path.exists(path):
+        return []
+    out = []
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return out
+
+
+# 生效条件：os.path.join(root, CF.ACCESS_LOG) 不存在时返回空集；否则逐行解析，rec.get("ids") 为 list/tuple 时仅加入其中真值元素的 str 形式，nid 取 rec.get("id") or rec.get("node_id") or rec.get("nid") 的真值并加入 str(nid)，最终返回 seen & set(nodes)（仅保留 nodes 键内的 id）。
+def _touched(root: str, nodes: dict) -> set:
+    """access log 触达集（与 conformance._reach_metrics 同一解析口径：ids / id / node_id / nid）。"""
+    p = os.path.join(root, CF.ACCESS_LOG)
+    seen = set()
+    if not os.path.exists(p):
+        return seen
+    with open(p, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            got = rec.get("ids")
+            if isinstance(got, (list, tuple)):
+                seen.update(str(x) for x in got if x)
+            nid = rec.get("id") or rec.get("node_id") or rec.get("nid")
+            if nid:
+                seen.add(str(nid))
+    return seen & set(nodes)
+
+
+# 生效条件：str(layer)=="knowledge" 的节点在 role 为假值、CF._as_int(evidence_count)==0、或 {"doc","code"} 命中 CF._tag_prefixes(r) 时分别产出 missing_field/mixed_layer；任意节点在 CF._as_int(evidence_count)==0 且无 CF._basis_of(r) 且 lifecycle_state 为假值时产出 unanalyzed；str(content_hash) 既非 "None" 也非 "" 且同指纹计数 >1 时该组内每个节点产出 dup_content；edges 为 list/tuple 时逐条处理其中的 dict 边，当该边所有真值键（CF.CANONICAL_EDGE_KEYS 与 "type"）中不含任一规范键时产出 edge_non_canonical 并停止该节点后续边。
+def _assertion_items(nodes: dict) -> list:
+    """断言集超限项 → 条目级（判据函数与 conformance 同源，不另立口径）。"""
+    out = []
+    kn = {nid: r for nid, r in nodes.items() if str(r.get("layer")) == "knowledge"}
+    for nid, r in kn.items():
+        if not r.get("role"):
+            out.append({"node_id": nid, "issue_kind": "missing_field",
+                        "evidence": "role 为空（口径=conformance.stratum.role_coverage，knowledge 层分母）"})
+        if CF._as_int(r.get("evidence_count")) == 0:
+            out.append({"node_id": nid, "issue_kind": "missing_field",
+                        "evidence": "evidence_count=0（口径=conformance.stratum.evidence_coverage）"})
+        if {"doc", "code"} & CF._tag_prefixes(r):
+            out.append({"node_id": nid, "issue_kind": "mixed_layer",
+                        "evidence": "knowledge 层带 doc/code 标签（口径=conformance.stratum.mixed_ratio）"})
+    for nid, r in nodes.items():
+        if (CF._as_int(r.get("evidence_count")) == 0 and not CF._basis_of(r)
+                and not r.get("lifecycle_state")):
+            out.append({"node_id": nid, "issue_kind": "unanalyzed",
+                        "evidence": "无一维分析痕迹（口径=conformance.unanalyzed 派生判据）"})
+    ch = collections.Counter(str(r.get("content_hash")) for r in nodes.values())
+    dup = {h for h, c in ch.items() if c > 1 and h not in ("None", "")}
+    if dup:
+        for nid, r in nodes.items():
+            h = str(r.get("content_hash"))
+            if h in dup:
+                out.append({"node_id": nid, "issue_kind": "dup_content",
+                            "evidence": "content_hash 重复组 %s（%d 条同指纹；口径=conformance.dup.content)" % (h, ch[h])})
+    for nid, r in nodes.items():
+        es = r.get("edges") or []
+        if not isinstance(es, (list, tuple)):
+            continue
+        for e in es:
+            if not isinstance(e, dict):
+                continue
+            keys = [k for k in CF.CANONICAL_EDGE_KEYS + ("type",) if e.get(k)]
+            if not any(k in CF.CANONICAL_EDGE_KEYS for k in keys):
+                out.append({"node_id": nid, "issue_kind": "edge_non_canonical",
+                            "evidence": "边键非规范：%s（口径=conformance.edge.key.canonical）"
+                                        % ("+".join(keys) or "<无关系键>")})
+                break
+    return out
+
+
+# 生效条件：当 root、nodes 给定，对 _read_jsonl(root/CF.INBOX_LOG) 解析出的 inbox 记录中 pid（str(r.get("pid") or "")）非空且不在 decisions 中 x.get("pid") 真值 str 集合的记录，生成 origin=proposal、issue_kind=gate_defer 条目，其中 layer 直接取 r.get("layer") 不回落、content 取 r.get("content") or ""、tags 取 r.get("tags") or []、content_hash 取 r.get("payload_hash") or ""、node_id 取 str(r.get("id") or "") or None；再对 _read_jsonl(root/FORGET_LOG) 中 str(r.get("verdict"))=="DEFER" 的记录，若 str(r.get("node_id") or "") 非空且该 nid 是 nodes 的键则加入 out，否则加入 skipped（source=defer_queue、reason=node_not_landed、detail 为 nid 或 str(r.get("reason"))）；返回 (out, skipped)；
+def _defer_items(root: str, nodes: dict):
+    """闸门待裁决提案 + 遗忘日志 DEFER 留痕。返回 (items, skipped)。"""
+    ib = _read_jsonl(os.path.join(root, CF.INBOX_LOG))
+    dc = _read_jsonl(os.path.join(root, CF.DECISION_LOG))
+    done = {str(x.get("pid")) for x in dc if x.get("pid")}
+    out, skipped = [], []
+    for r in ib:
+        pid = str(r.get("pid") or "")
+        if not pid or pid in done:
+            continue
+        out.append({"node_id": str(r.get("id") or "") or None, "origin": "proposal",
+                    "proposal_id": pid, "issue_kind": "gate_defer",
+                    "layer": r.get("layer"), "content": r.get("content") or "",
+                    "tags": r.get("tags") or [], "content_hash": r.get("payload_hash") or "",
+                    "evidence": "闸门待裁决提案（inbox 中 %s 未被 decisions 覆盖）" % pid})
+    for r in _read_jsonl(os.path.join(root, FORGET_LOG)):
+        if str(r.get("verdict")) != "DEFER":
+            continue
+        nid = str(r.get("node_id") or "")
+        if nid and nid in nodes:
+            out.append({"node_id": nid, "issue_kind": "gate_defer",
+                        "evidence": "遗忘闸门 DEFER 留痕：%s" % str(r.get("reason"))})
+        else:
+            skipped.append({"source": "defer_queue", "reason": "node_not_landed",
+                            "detail": nid or str(r.get("reason"))})
+    return out, skipped
+
+
+# 生效条件：取 nodes 中不在 _touched(root, nodes) 触达集、且 importance 经 _imp 归一后 >= COLD_IMPORTANCE_MIN 的节点，按归一 importance 降序（同值按 node_id 升序）后取 [:int(limit)]；limit=0 得空列表，limit 为负则排除末尾 |limit| 条而非空返回（源码无 int(limit)<=0 早退）。
+def _cold_items(root: str, nodes: dict, limit: int) -> list:
+    seen = _touched(root, nodes)
+
+# 生效条件：r 的 importance 为真值且 float() 可转换时返回其 float 值；importance 为假值（None/0/""）时回落 0.0；转换抛 TypeError 或 ValueError 时返回 0.0。
+    def _imp(r):
+        try:
+            return float(r.get("importance") or 0.0)
+        except (TypeError, ValueError):
+            return 0.0
+
+    rows = [(nid, r) for nid, r in nodes.items() if nid not in seen]
+    rows.sort(key=lambda kv: (-_imp(kv[1]), kv[0]))
+    picked = [(nid, r) for nid, r in rows if _imp(r) >= COLD_IMPORTANCE_MIN][:int(limit)]
+    return [{"node_id": nid, "issue_kind": "cold",
+             "evidence": "access log 未触达（importance=%.2f，排名第 %d）" % (_imp(r), i + 1)}
+            for i, (nid, r) in enumerate(picked)]
+
+
+# 生效条件：int(window) <= 0 或 nodes 为假值时返回 []；否则按 sha1(nid.encode("utf-8")).hexdigest() 排序，从 (int(offset)*int(window)) % len(nodes) 起取 int(window) 条，不足时用头部元素环绕补足。
+def _patrol_items(nodes: dict, window: int, offset: int) -> list:
+    if int(window) <= 0 or not nodes:
+        return []
+    ordered = sorted(nodes, key=lambda nid: hashlib.sha1(nid.encode("utf-8")).hexdigest())
+    n = len(ordered)
+    start = (int(offset) * int(window)) % n
+    picked = ordered[start:start + int(window)]
+    if len(picked) < int(window):                       # 环绕补足：多轮不重不漏
+        picked = picked + ordered[:int(window) - len(picked)]
+    return [{"node_id": nid, "issue_kind": "patrol",
+             "evidence": "轮巡窗口 #%d（窗口 %d 条，按 sha1(node_id) 排序切片）" % (int(offset), int(window))}
+            for nid in picked]
+
+
+# 生效条件：items 逐条以 node_id 为真时 key=str(node_id)、否则 key="pid:"+str(proposal_id) 聚合；首次建房时 node_id 为真则取 nodes.get(node_id) or {} 作 meta，tags 取 it.get("tags") or meta.get("tags") or []，evidence 每聚合记录最多 8 条；结果 sources 去重后为空则置 ["-"]，priority 取 _PRIORITY.get(s, 9) 的最小值，按 (priority, str(key)) 排序返回。
+def _merge(items: list, nodes: dict) -> list:
+    """按条目（节点/提案）聚合：一条候选 = 一个待评条目，多个问题挂在 issue_kinds 上。"""
+    acc = {}
+    for it in items:
+        nid = it.get("node_id")
+        key = str(nid) if nid else "pid:" + str(it.get("proposal_id"))
+        rec = acc.get(key)
+        if rec is None:
+            meta = nodes.get(nid) or {} if nid else {}
+            rec = acc[key] = {
+                "key": key, "node_id": nid or None, "proposal_id": it.get("proposal_id") or None,
+                "origin": it.get("origin") or "node",
+                "layer": it.get("layer") or meta.get("layer"),
+                "sources": [], "issue_kinds": [], "evidence": [],
+                "content": it.get("content") or "",
+                "tags": list(it.get("tags") or meta.get("tags") or []),
+                "content_hash": it.get("content_hash") or str(meta.get("content_hash") or ""),
+            }
+        src = it.get("source")
+        if src and src not in rec["sources"]:
+            rec["sources"].append(src)
+        ik = it.get("issue_kind")
+        if ik and ik not in rec["issue_kinds"]:
+            rec["issue_kinds"].append(ik)
+        ev = it.get("evidence")
+        if ev and len(rec["evidence"]) < 8:
+            rec["evidence"].append(ev)
+    out = list(acc.values())
+    for r in out:
+        r["sources"] = sorted(set(r["sources"])) or ["-"]
+        r["priority"] = min(_PRIORITY.get(s, 9) for s in r["sources"])
+        r["issue_kinds"] = sorted(r["issue_kinds"])
+    out.sort(key=lambda r: (r["priority"], str(r["key"])))
+    return out
+
+
+# 生效条件：root 为假值（None/""）时回落 mdcg_root()；nodes 为 None 时用 CF.load_index(root) or {}；wanted 为 (sources or SOURCES) 与 SOURCES 的交集，按其中是否含 assertion/defer_queue/cold/patrol 分派取候选（cold 传 cold_limit，patrol 传 patrol_window 与偏移，patrol_offset 为 None 时偏移取 int((now if now is not None else time.time())//PATROL_EPOCH)）；limit 为真值时才把 merged 截到 int(limit)；with_report 为真值时补 CF.check(root, check_paths=False) 的指标与失败断言 id。
+def generate(root=None, *, sources=SOURCES, nodes=None, limit=None, cold_limit=500,
+             patrol_window=200, patrol_offset=None, with_report=False, now=None) -> dict:
+    """四源候选生成。nodes 可注入（测试用合成库，免读真源）。"""
+    root = root or mdcg_root()
+    if nodes is None:
+        nodes = CF.load_index(root) or {}   # load_index 直接返回 nodes 字典
+    wanted = [s for s in SOURCES if s in (sources or SOURCES)]
+    items, skipped, by_source = [], [], {}
+    if "assertion" in wanted:
+        got = _assertion_items(nodes)
+        by_source["assertion"] = len(got)
+        items += [dict(x, source="assertion") for x in got]
+    if "defer_queue" in wanted:
+        got, sk = _defer_items(root, nodes)
+        by_source["defer_queue"] = len(got)
+        items += [dict(x, source="defer_queue") for x in got]
+        skipped += sk
+    if "cold" in wanted:
+        got = _cold_items(root, nodes, cold_limit)
+        by_source["cold"] = len(got)
+        items += [dict(x, source="cold") for x in got]
+    if "patrol" in wanted:
+        off = int(patrol_offset) if patrol_offset is not None \
+            else int((now if now is not None else time.time()) // PATROL_EPOCH)
+        got = _patrol_items(nodes, patrol_window, off)
+        by_source["patrol"] = len(got)
+        items += [dict(x, source="patrol") for x in got]
+    merged = _merge(items, nodes)
+    if limit:
+        merged = merged[:int(limit)]
+    rep = {"root": root, "generated_at": float(now if now is not None else time.time()),
+           "sources": wanted, "by_source": by_source, "total_raw": len(items),
+           "total": len(merged), "candidates": merged, "skipped": skipped}
+    if with_report:
+        rep0 = CF.check(root, check_paths=False)
+        rep["report"] = CF.metrics_of(rep0)
+        rep["assertions"] = {"verdict": rep0.get("verdict"), "counts": rep0.get("counts"),
+                             "failed": [c.get("id") for c in rep0.get("checks") or []
+                                        if not c.get("ok")]}
+    return rep