@furongjun1999/dsh-memory 0.4.5 → 0.4.7

package/md_cg/predict.py

@@ -42,6 +42,11 @@ BASE_HIT_RATE = 0.40        # 基线阈值（工程初值，非协议承诺）
 HIT_HISTORY_MAX = 200       # 命中历史滚动窗口
 EDGE_BOOST = 0.05           # 命中 → 因果/时序边置信度增量
 
+# Beta-Bernoulli 先验强度（等效先验样本数 κ，P-T-73/74 通道贝叶斯）：
+# α0 = BASE_HIT_RATE·κ，β0 = (1−BASE_HIT_RATE)·κ。κ 越大小样本越向基线收缩。
+# 性质：先验均值 = BASE_HIT_RATE（与 hit_rate() 空历史兜底同值，口径无缝）。
+PRIOR_STRENGTH = 20
+
 CAUSAL_BRANCH_TYPES = ("causal", "sequential")
 SEMANTIC_TOP_K = 5
 SEMANTIC_MIN_SIM = 0.05
@@ -309,6 +314,67 @@ def hit_rate(cg):
     return round(sum(1 for x in h if x) / len(h), 4)
 
 
+# ---------------------------------------------------------------- P-T-73/74 通道贝叶斯
+
+def beta_posterior(hits, prior_k=PRIOR_STRENGTH, base=BASE_HIT_RATE):
+    """Beta-Bernoulli 后验（纯函数）：命中序列 → 后验参数与区间。
+
+    置信度≠可信度（P-T-73/74）：`hit_rate` 是滑动计数（小样本过度自信：
+    n=5 全命中 → 1.0）；后验均值 = (α0+k)/(α0+β0+n) 随样本量向基线收缩
+    （n=5 全命中 → 0.52），诚实反映「证据还很少」。置信度的动态死区
+    （dynamic_hit_threshold）不动——本函数只提供**更诚实的可信度估计面**，
+    默认链路零行为变更。
+
+    返回：{alpha, beta, mean, std, ci95, samples, hits}；
+    空序列 → 先验（mean=base，与 hit_rate 空历史兜底同值）。
+    ci95 用正态近似 mean±1.96σ（零依赖；样本大时近似良好，小样本区间
+    偏窄，故另带 samples 供阅读方自判权重）。
+    """
+    a0 = float(base) * float(prior_k)
+    b0 = (1.0 - float(base)) * float(prior_k)
+    xs = [bool(x) for x in (hits or [])]
+    k = sum(1 for x in xs if x)
+    n = len(xs)
+    a, b = a0 + k, b0 + (n - k)
+    mean = a / (a + b)
+    var = (a * b) / ((a + b) ** 2 * (a + b + 1.0))
+    std = var ** 0.5
+    return {"alpha": round(a, 4), "beta": round(b, 4),
+            "mean": round(mean, 4), "std": round(std, 4),
+            "ci95": [round(max(0.0, mean - 1.96 * std), 4),
+                     round(min(1.0, mean + 1.96 * std), 4)],
+            "samples": n, "hits": k}
+
+
+def channel_history(cg, limit=HIT_HISTORY_MAX):
+    """feedback 留痕按通道分组（P-T-74 通道级可信度）→ {channel: [hit...]}。
+
+    通道 = 预测发出的面（feedback 的 `channel` 参数，如 "causal"/"semantic"）。
+    早期留痕无 channel 字段 → 归 "unlabeled"（诚实标注，不冒充分通道）。
+    """
+    out = {}
+    for r in _read_log(cg, limit=limit):
+        if r.get("type") != "feedback":
+            continue
+        ch = str(r.get("channel") or "unlabeled")
+        out.setdefault(ch, []).append(bool(r.get("hit")))
+    return out
+
+
+def channel_posterior(cg, channel=None, limit=HIT_HISTORY_MAX):
+    """通道级后验查询：channel=None → 全量+分通道；channel=str → 单通道。"""
+    hist = channel_history(cg, limit=limit)
+    if channel is not None:
+        ch = str(channel)
+        post = beta_posterior(hist.get(ch) or [])
+        post["channel"] = ch
+        return post
+    all_hits = [x for hits in hist.values() for x in hits]
+    return {"all": beta_posterior(all_hits),
+            "channels": {ch: beta_posterior(hits)
+                         for ch, hits in sorted(hist.items())}}
+
+
 def score_route(cg, route, verification=None):
     """D-004 T_pred 四维评分（verification 跨路线共享，来自命中率）。"""
     trend = float(route.get("confidence") or 0.0)
@@ -610,10 +676,17 @@ def dynamic_hit_threshold(cg, limit=HIT_HISTORY_MAX):
 
 
 def feedback(cg, predicted_node_id, actual_node_id=None, hit=None, note="",
-             actor="predict"):
+             actor="predict", sync_self=True, channel=None):
     """预测反馈（D-006）：hit → 边置信度 +0.05；miss → 登记 rejected。
 
     `hit` 未显式给出时按 `predicted == actual` 判定。
+    `channel`（可选，P-T-74）：预测发出的面（如 "causal"/"semantic"），
+    供通道级 Beta-Bernoulli 后验（channel_posterior）按面分层估计可信度；
+    不传 → 留痕归 "unlabeled"，不改变任何既有行为。
+
+    `sync_self`（默认 True）：反馈后**回写自我模型**——刷新自我状态卡的
+    「预测校准」面，形成「预测 → 事实 → 误差 → 自我更新」闭环。
+    自我模型是二阶观测，其刷新失败不阻塞一阶反馈结果。
     """
     pred = str(predicted_node_id or "").strip()
     act = str(actual_node_id or "").strip() or pred
@@ -621,7 +694,8 @@ def feedback(cg, predicted_node_id, actual_node_id=None, hit=None, note="",
         hit = (pred == act)
     hit = bool(hit)
     _append(cg, {"type": "feedback", "t": time.time(), "predicted": pred,
-                 "actual": act, "hit": hit, "note": str(note or "")[:200]})
+                 "actual": act, "hit": hit, "note": str(note or "")[:200],
+                 "channel": (str(channel) if channel else None)})
     out = {"ok": True, "hit": hit, "predicted": pred, "actual": act}
     if hit:
         out["boosted"] = _boost_incoming(cg, act, EDGE_BOOST, actor=actor)
@@ -634,6 +708,14 @@ def feedback(cg, predicted_node_id, actual_node_id=None, hit=None, note="",
         except Exception as exc:                              # pragma: no cover
             out["rejected_error"] = str(exc)
     out.update(dynamic_hit_threshold(cg))
+    # 闭环：预测误差 → 自我模型更新。延迟导入避免与 self_state 的循环依赖，
+    # 且自我模型刷新属于二阶观测，失败不阻塞一阶反馈结果。
+    if sync_self:
+        try:
+            from . import self_state
+            out["self_state"] = self_state.refresh(cg, actor=actor)
+        except Exception as exc:                          # pragma: no cover
+            out["self_state_error"] = str(exc)
     return out
 
 
@@ -814,6 +896,7 @@ def stats(cg, limit=20):
             "feedback_samples": len(h), "hits": sum(1 for x in h if x),
             "hit_rate": (round(sum(1 for x in h if x) / len(h), 4) if h
                          else BASE_HIT_RATE),
+            "beta": channel_posterior(cg),
             "dynamic": dynamic_hit_threshold(cg),
             "recent": recs[-int(limit):] if limit else []}
 
@@ -894,6 +977,8 @@ def catalog():
             "D-004": "T_pred 四维评分 trend/boundary/verification/balance",
             "D-005": "AttentionPolicy 适配器 + 降级（边置信度排序）",
             "D-006": "命中率动态校准（样本 < 50 不触发反思）",
+            "P-T-73/74": "通道贝叶斯后验（Beta-Bernoulli，置信度≠可信度；"
+                         "feedback channel 参数 + channel_posterior 查询）",
         },
         "weights": {"trend": W_TREND, "boundary": W_BOUNDARY,
                     "verification": W_VERIFICATION, "balance": W_BALANCE},

package/md_cg/progressive.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""progressive.py · 渐进式语义检索控制器（Progressive Semantic Retrieval）
+
+理论定位（使用者与 GPT 定稿，2026-09-14）：
+    语义解析的完整性与检索的必要性不是同一个问题——一句话不必完成完整
+    语义解析，往往已含足够检索线索。查询不是固定语义结构，而是**不断
+    收紧的约束集合**；检索本身成为语义理解的一部分。
+
+    不要追求「一句话完成语义理解」，而要从**最小可靠语义**开始，
+    通过检索获得上下文，再逐步增加条件，使语义收敛。
+
+    架构：AI 翻译 → 中文 → 基础语义组合 → 宽检索（少条件）→ 候选集合
+          → 逐步增加条件 → 精确语义判断。
+
+与灵枢既有机制的对接（全部已存在，本模块只补控制器壳）：
+    - 宽检索可行性    = bench_en_atoms_public 臂⑤⑥⑦实证：归一残缺 20%
+                        时 hit@10 仍 99.2-99.8——宽检索不要求完整归一；
+    - 四态控制器      = judge_qualification / judge_ranking（证据防火墙）：
+                        DEFER ≠ 失败 =「当前语义分辨率不足，继续获取条件」；
+    - 主动条件获取    = autonomy.explore 信息差驱动（Active Semantic
+                        Retrieval 的写侧对应物，后续增量汇合点）。
+
+代码职责（纯函数、确定性、评分器注入式）：
+    - core_subset()      Stage-1 宽检索核心子集（保序截断）；
+    - discriminative()   候选间区分度最大的未用原子（覆盖差，None=无
+                         区分性条件可加——诚实停止，不硬选）；
+    - progressive_search()  宽检索 → 区分度引导加条件 → 重排 的循环，
+                         返回逐阶段轨迹（可审计）。
+
+诚实边界：
+    1) 区分性条件词池由调用方给定（bench 侧=归一原子全集；引擎侧真实
+       系统应由 atoms.json 标准词表驱动——手工池只是评测示教）；
+    2) 零干扰池（567 全 gold）上渐进预期 ≈ 一次性全原子——机制价值
+       在归一残缺场景与受控干扰池（见 bench_progressive.py）；
+    3) 本模块不接 AI、不写库——DEFER 驱动的主动问询（向用户/环境获取
+       条件）是后续增量。
+"""
+from __future__ import annotations
+
+#: 区分度阈值：覆盖差 gap = 1-|2cov-1| ∈ (0,1]，低于此值不选
+#: （0 = 全命中/全不命中，加了不产生任何排序差异）。取小正数即可——
+#: 「最大区分度」排序本身已保证质量，阈值只排除零区分的无效条件。
+MIN_DISCRIM = 0.1
+
+
+def core_subset(atoms, ratio=0.5):
+    """Stage-1 宽检索核心子集：归一序列前 int(len*ratio) 个（保序，确定性）。
+
+    「最小可靠语义」的确定性近似——归一产物的前段通常是事件核心
+    （主体/动作），尾段多为修饰限定。ratio=1.0 退化为一次性全原子。
+    """
+    toks = [a for a in (atoms or ()) if a]
+    if not toks:
+        return []
+    n = max(1, int(len(toks) * ratio))
+    return toks[:n]
+
+
+def discriminative(unused, cand_sets, min_gap=MIN_DISCRIM):
+    """候选间区分度最大的未用原子（确定性：同 gap 取归一序列原序靠前者）。
+
+    unused:     候选条件词序列（保序）；
+    cand_sets:  当前 top 候选的原子集序列（frozenset）；
+    返回 gap 最大且 > min_gap 的原子；无 → None（无区分性条件可加）。
+    """
+    n = len(cand_sets)
+    if n < 2 or not unused:
+        return None
+    best, best_gap = None, float(min_gap)
+    for a in unused:
+        cov = sum(1 for s in cand_sets if a in s) / n
+        gap = 1.0 - abs(2.0 * cov - 1.0)     # cov=0.5 → 1.0；0/1 → 0.0
+        if gap > best_gap:
+            best, best_gap = a, gap
+    return best
+
+
+def progressive_search(rank_fn, atoms, cand_atoms,
+                       ratio=0.5, k=10, max_stages=4,
+                       cond_pool=None, min_gap=MIN_DISCRIM):
+    """渐进式语义检索主循环（评分器注入式，纯函数）。
+
+    rank_fn(atoms_list) -> [(cid, score), ...]  分数降序（bench 侧=原子
+        Jaccard；引擎侧=search_rrf 的适配包装——四态终排在引擎内生效）；
+    atoms:      归一原子全集（Stage-1 取 core_subset，后续按区分度补）；
+    cand_atoms: {cid: frozenset} 候选原子集（区分度观测面）；
+    cond_pool:  引擎侧的候选条件词池（bench 原子面缺省=atoms 未用部分）；
+    max_stages: 检索预算（最多 rank 次数，每阶段都被测量，不空转）。
+
+    返回轨迹：
+        stages: [{used, top}]   每阶段使用的条件与 top-k 候选 id；
+        added:  [atom]          逐阶段新增的区分性条件（refinement steps）；
+        converged: bool         无区分性条件可加而提前停止（True）或
+                                预算耗尽（False）。
+    """
+    toks = [a for a in (atoms or ()) if a]
+    if not toks:
+        return {"stages": [], "added": [], "converged": False}
+    used = core_subset(toks, ratio)
+    stages, added = [], []
+    converged = False
+    pool = list(cond_pool) if cond_pool else toks
+    for stage in range(max_stages):
+        ranked = rank_fn(used)
+        top = ranked[:k]
+        stages.append({"used": list(used),
+                       "top": [cid for cid, _s in top]})
+        if stage == max_stages - 1:
+            break
+        nxt = discriminative([a for a in pool if a not in used],
+                             [cand_atoms.get(cid, frozenset())
+                              for cid, _s in top],
+                             min_gap=min_gap)
+        if nxt is None:
+            converged = True          # 无条件可加：当前分辨率下已收敛
+            break
+        used = used + [nxt]
+        added.append(nxt)
+    return {"stages": stages, "added": added, "converged": converged}

package/md_cg/protocol/md_cg_gate.proto

@@ -0,0 +1,33 @@
+// md_cg 判定层 · 可协议化闸门 v0.1
+// 来源：forgetting.py assess() 七步阶梯 · protect.py is_protected()/is_immutable()
+// 语言契约（实测，见 out/probe*.proto）：
+//   · 且/或/非 静默恒假 → 复合条件一律用嵌套 若（等效 AND）
+//   · ≥ 闭区间用「若 X 小于 t，则 <不满足>，否则 <满足>」保真
+//   · 裸赋值会被静默丢弃 → 赋值全包在 若 分支内，第 1 步顺带初始化 裁决
+//   · 变量名禁用数字后缀
+//   · 输入符号必须全部显式传入：未传=未声明（抛 NameError），而非默认为 0
+//   · check 的 statements 计数在 3 层嵌套上坍缩为 1（forgetting 单段 8 条也报 1 条），
+//     但编译指令数与运行终态均正确 —— 该计数不可用作正确性判据
+// 输入（Python 侧数值化）：重要度 冗余 新信息 来源内定 层保护 显式保护 显式不可变 自我状态
+// 输出：裁决 1=ACCEPT 2=MERGE 3=DROP 4=DEFER；保护 1/0；不可覆盖 1/0
+// 阈值：0.70 0.85 0.60 0.30 0.15（forgetting.py / protect.py 常量）
+// 语句 1-7 = 遗忘闸门（顺序即语义）；8-10 = 不可遗忘；11-14 = 不可覆盖（9=未命中哨兵）
+
+问曰：此条记忆当写否，既有自我认知可改否？
+答曰：依 forgetting 七步阶梯与 protect 三层保护裁决。
+术曰：
+1。若 重要度 小于 0.7，则 裁决 = 0，否则 裁决 = 1；
+2。若 裁决 等于 0，则 若 来源内定 大于 0.5，则 若 冗余 小于 0.6，则 裁决 = 0，否则 裁决 = 3；
+3。若 裁决 等于 0，则 若 冗余 小于 0.85，则 裁决 = 0，否则 裁决 = 2；
+4。若 裁决 等于 0，则 若 重要度 小于 0.3，则 若 冗余 小于 0.6，则 裁决 = 0，否则 裁决 = 4；
+5。若 裁决 等于 0，则 若 重要度 小于 0.3，则 裁决 = 0，否则 裁决 = 1；
+6。若 裁决 等于 0，则 若 新信息 小于 0.15，则 裁决 = 0，否则 裁决 = 1；
+7。若 裁决 等于 0，则 裁决 = 4；
+8。若 层保护 大于 0.5，则 保护 = 1，否则 保护 = 9；
+9。若 保护 等于 9，则 若 显式保护 大于 0.5，则 保护 = 1；
+10。若 保护 等于 9，则 若 重要度 小于 0.7，则 保护 = 0，否则 保护 = 1；
+11。若 自我状态 大于 0.5，则 不可覆盖 = 0，否则 不可覆盖 = 9；
+12。若 不可覆盖 等于 9，则 若 层保护 大于 0.5，则 不可覆盖 = 1；
+13。若 不可覆盖 等于 9，则 若 显式不可变 大于 0.5，则 不可覆盖 = 1；
+14。若 不可覆盖 等于 9，则 不可覆盖 = 0；
+15。止。

package/md_cg/refindex.py

@@ -262,12 +262,16 @@ class Ledger:
 
 def index_dir(root: str, *, kind: str, patterns=None, max_files: int = 500,
               max_items: int = 2000, incremental: bool = False,
-              ledger: "Ledger" = None):
+              ledger: "Ledger" = None, skip_dirs=None):
     """按 kind 调度 codeindex / docindex 的全量（或增量）索引。
 
     incremental=True 且给了 ledger 时：未变文件跳过（`skipped_unchanged`）。
     返回 (items, errors, stats)，与底层 index_dir 的返回一致（多一个
     `skipped_unchanged`）。
+
+    `skip_dirs` 透传给底层：**追加**排除、只增不减（内置 `.git`/`.venv`/
+    `node_modules` 等不可被关闭），见 `codeindex.skip_matcher`。实际排掉了哪些目录
+    由 `stats["skipped_dirs"]` 回报，仍不静默。
     """
     mod = _mod(kind)
     fresh = None
@@ -290,7 +294,7 @@ def index_dir(root: str, *, kind: str, patterns=None, max_files: int = 500,
 
     items, errors, stats = mod.index_dir(
         root, patterns=patterns, max_files=max_files, max_items=max_items,
-        fresh=fresh, on_file=on_file,
+        fresh=fresh, on_file=on_file, skip_dirs=skip_dirs,
     )
     if ledger is not None:
         ledger.prune()
@@ -541,6 +545,167 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
     }
 
 
+# --------------------------------------------------------------------------
+# 节点级对账：孤儿清退 + 悬空清退
+#
+# 水位层的 `Ledger.reconcile` 只剪**水位条目**、`prune` 只剪「源大域已消失」
+# 的条目，两者都不碰**节点**。于是节点层的两类残留无人处置：
+#   · 孤儿（同一文档的过期代）——标题路径一变 id 全量重算，旧代与新代并存；
+#   · 悬空（源文件已删）——回读必然失败，巡检永远报 dangling。
+# 本节的唯一实现同时供 `op=index_code / index_doc`（孤儿）与
+# `op=ref action=prune`（悬空）使用，避免两处各写一套口径。
+# --------------------------------------------------------------------------
+
+def _norm_root(p) -> str:
+    """root 归一：同一目录的大小写/分隔符差异不得影响「同一大域」判定。"""
+    return os.path.normcase(os.path.abspath(str(p or "")))
+
+
+def _same_root(a, b) -> bool:
+    try:
+        return bool(a) and bool(b) and _norm_root(a) == _norm_root(b)
+    except (TypeError, ValueError):
+        return False
+
+
+def _norm_rel(p) -> str:
+    return str(p or "").replace("\\", "/").lstrip("./")
+
+
+def _forget_many(cg, plan, why: str) -> tuple:
+    """逐条软删（进 trash/、写删除清单、可 restore）；受保护节点拦下不删。
+
+    `forget` 属 **MdCGOS 层**能力（保护裁决 + 回收站 + 删除清单），基础层
+    `MdCG` 没有任何删除原语。缺能力时**明确报错、不静默跳过**——否则
+    「清退了 N 条」看着成功、实际一条没删（P27 §10 实测过这个坑）。
+    """
+    fn = getattr(cg, "forget", None)
+    if not callable(fn):
+        err = (f"{type(cg).__name__} 无 forget 能力（对账须能删除节点）；"
+               f"生产路径是 MdCGOS，测试请用 MdCGOS")
+        return [], [{"node_id": nid, "error": err} for nid in sorted(plan)]
+    done, blocked = [], []
+    for nid in sorted(plan):
+        try:
+            res = fn(nid, why) or {}
+        except Exception as exc:            # ProtectionError 等 → 拦下，不越权
+            blocked.append({"node_id": nid, "error": str(exc)[:120]})
+            continue
+        if res.get("ok"):
+            done.append(nid)
+        else:
+            blocked.append({"node_id": nid, "error": str(res.get("error"))[:120]})
+    return done, blocked
+
+
+def prune_orphans(cg, *, kind: str, root: str, items, dry_run: bool = False,
+                  reason: str = "") -> dict:
+    """清退「同 root + 同 path，但已不在本次产出里」的**过期代**节点。
+
+    为什么必须有：`node_id = sha1(相对path + "#" + heading_path)`，而
+    `add_items` 只做**同 id 幂等 upsert**——文档标题结构一变，整篇 id 全量
+    重算，旧代节点无人清退，与新代并存（同一文档召回两份，且旧代引用的区间
+    已失效）。截断的索引由调用方负责不调用本函数（没扫完 ≠ 剩下的都过期）。
+
+    范围**只限本次真正重切过的文件**（`items` 的 path）：增量索引跳过的未变
+    文件不在 items 里，其节点不进判定——否则会把完好的节点整片误删。
+    """
+    nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
+    touched: dict = {}
+    for it in items or []:
+        rel = _norm_rel(it.get("path"))
+        if rel:
+            touched.setdefault(rel, set()).add(node_id_of(it, kind))
+    base = {"scanned": len(nodes), "touched_files": len(touched),
+            "dry_run": bool(dry_run)}
+    if not touched:
+        return {**base, "ok": True, "count": 0, "pruned": [],
+                "skipped_protected": []}
+
+    # ⚠ ref 只存在于**节点 frontmatter**里；`cg.index['nodes']` 是元数据快照
+    # （path/layer/tags/…，见 mdcg._scan_nodes），**不含 ref**。因此必须
+    # `cg.get(nid)` 取回节点再 ref_of —— 否则 ref_of 恒返回 ('', None)、
+    # 整个对账静默失效（P27 §10 实测过这个坑）。标签预筛与 check_refs 同口径，
+    # 免得为全库每条记忆都读一次盘。
+    tag = "doc" if kind == "doc_ref" else "code"
+    plan = []
+    for nid, e in nodes.items():
+        if tag not in ((e or {}).get("tags") or []):
+            continue
+        try:
+            node = cg.get(nid)
+        except Exception:
+            continue
+        if not node:
+            continue
+        k, ref = ref_of(node)
+        if k != kind or not isinstance(ref, dict):
+            continue
+        keep = touched.get(_norm_rel(ref.get("path")))
+        if keep is None or nid in keep or not _same_root(ref.get("root"), root):
+            continue
+        plan.append(nid)
+
+    why = reason or ("索引重建：本节点已不在同文档新代产出中（标题路径变更致 "
+                     "node_id 重算），清退过期代以消除重复召回")
+    if dry_run:
+        return {**base, "ok": True, "count": len(plan), "pruned": sorted(plan)[:50],
+                "skipped_protected": [], "reason": why}
+    done, blocked = _forget_many(cg, plan, why)
+    return {**base, "ok": True, "count": len(done), "pruned": done[:50],
+            "skipped_protected": blocked[:20], "reason": why}
+
+
+def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
+                   max_nodes: int = MAX_CHECK, reason: str = "") -> dict:
+    """清退**悬空**节点：ref 指向的源文件已删除，回读必然失败。
+
+    `check_refs` 只报告不处置（其原话是「悬空需人工处置」），本函数就是那个
+    出口——已删脚本、被搬走的文档留下的残留节点一次清掉，而不是逐条手工
+    `forget`。判定与巡检共用 `probe_ref` 的唯一实现，口径不会打架。
+    """
+    nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
+    # 同 prune_orphans：ref 只在节点 frontmatter 里，索引条目里没有，
+    # 必须 cg.get 取回节点再 ref_of（否则恒空、静默不删）。
+    todo = []
+    for nid, e in nodes.items():
+        tags = (e or {}).get("tags") or []
+        if not any(t in ("code", "doc") for t in tags):
+            continue
+        try:
+            node = cg.get(nid)
+        except Exception:
+            continue
+        if not node:
+            continue
+        _k, ref = ref_of(node)
+        if not ref or not ref.get("root"):
+            continue
+        if only_roots and not any(_same_root(ref.get("root"), r) for r in only_roots):
+            continue
+        todo.append((nid, ref))
+    truncated = len(todo) > max_nodes
+    plan = []
+    for nid, ref in todo[:max_nodes]:
+        try:
+            if probe_ref(ref).get("status") == "dangling":
+                plan.append(nid)
+        except Exception:                   # 探测失败不算悬空（宁可不删）
+            continue
+
+    why = reason or ("源文件已删除，索引节点悬空（回读必然失败），"
+                     "清退以消除永不消失的 dangling")
+    base = {"scanned": len(nodes), "candidates": len(plan),
+            "dry_run": bool(dry_run), "truncated": truncated,
+            "max_nodes": max_nodes}
+    if dry_run:
+        return {**base, "ok": True, "count": len(plan), "pruned": sorted(plan)[:50],
+                "skipped_protected": [], "reason": why}
+    done, blocked = _forget_many(cg, plan, why)
+    return {**base, "ok": True, "count": len(done), "pruned": done[:50],
+            "skipped_protected": blocked[:20], "reason": why}
+
+
 def rebuild(cg, *, ledger: "Ledger" = None, only_roots=None, max_files: int = 500,
             max_items: int = 2000) -> dict:
     """按 ref 记录的 root 重建索引（sustain.heal 的修复动作）。