@furongjun1999/dsh-memory 0.6.0 → 0.6.1

package/md_cg/refindex.py

@@ -25,6 +25,18 @@
   「回读说没漂、巡检说有漂」。与 `region_hash` 的教训同源：区间哈希只允许一份实现，
   这里连「怎么判定 ok / stale / dangling」也只允许一份。
 
+**分工：节点判漂移，水位只判跳过**
+  漂移 / 悬空**只由节点自身 frontmatter ref 判**（`probe_ref` / `read_ref` 的唯一实现）；
+  水位（`_refindex.json`）**不进 probe**——它只判「这个节点能不能跳过、不读源」。
+  跳过的充分条件是三条同时成立：①节点 ref 与水位条目
+  `(hash, lineno, end, path, root)` **五项全等**；②源文件 size/mtime 未变；
+  ③该 node_id 本轮尚未判过（跨大域撞 id 时同一 id 会被多条水位条目列出，只判一次）。
+  五项里含 `path` / `root` 是必要的：不含时跨域撞 id 在稳态不可见（节点 ref 指向另一域
+  而水位条目取自本域），且不一致会重复报红（同一 node_id 两条 stale）。
+  不一致本身**不改判定**（不进 `ok`、不产生新红行），只记 `ledger_mismatch` 归因行，
+  用两侧 root 分辨两类成因：roots 相同＝`watermark_behind`（写序断裂 / 旧水位）、
+  roots 不同＝`collision_multi_root`（id 不含 root 的跨域撞 id 归属）。
+
 零第三方依赖。
 """
 from __future__ import annotations
@@ -240,14 +252,21 @@ class Ledger:
             files.pop(k, None)
         return len(dead)
 
-# 生效条件：当 kind、root、files、indexed、truncated 传入时，self.load()["last_index"] 被设为含 ts=_now()、kind、root、files、indexed、truncated=bool(truncated)、truncated_reason=reason or "" 的字典；reason 为假值（默认 ""/None）时 truncated_reason 回落 ""；
+# 生效条件：当 kind、root、files、indexed、truncated 传入时，self.load()["last_index"] 被设为含 ts=_now()、kind、root、files、indexed、truncated=bool(truncated)、truncated_reason=reason or ""、empty_scan=bool(empty_scan) 的字典；reason 为假值（默认 ""/None）时 truncated_reason 回落 ""；
     def note_index(self, *, kind: str, root: str, files: int, indexed: int,
-                   truncated: bool, reason: str = "") -> None:
-        """记「最近一次索引」结果——截断在这里留痕，供 diagnose 看见。"""
+                   truncated: bool, reason: str = "",
+                   empty_scan: bool = False) -> None:
+        """记「最近一次索引」结果——截断与空扫都在这里留痕，供 diagnose 看见。
+
+        `empty_scan=True` ⇒ 这一次**一个文件都没走过**（目录空/全被排除/全读不回）：
+        `files` 如实记 0，且这一次不做对账（见 `index_dir`），两个面因此对齐——
+        水位条目不被剪空，而 `last_index.files=0` 也不假装扫过。
+        """
         self.load()["last_index"] = {
             "ts": _now(), "kind": kind, "root": root, "files": files,
             "indexed": indexed, "truncated": bool(truncated),
             "truncated_reason": reason or "",
+            "empty_scan": bool(empty_scan),
         }
 
 # 生效条件：无参数调用即生效，取 self.load() 结果把 updated_at 置为 _now()，再以 atomic_write 把 json.dumps(..., ensure_ascii=False, indent=1, sort_keys=True) 写入 self.path，无返回值。
@@ -281,15 +300,26 @@ class Ledger:
 # 统一 index_dir：调度 + 水位 + 落盘（供 op=index_code / op=index_doc / heal 共用）
 # --------------------------------------------------------------------------
 
-# 生效条件：root 为源大域根、kind 为 'code_ref'/'doc_ref' 时经 _mod(kind) 调度底层 index_dir 并返回 (items, errors, stats)；ledger 非空时逐文件 record，incremental 为真时跳过 ledger.is_fresh 为真的文件，且 stats 未截断时执行 reconcile。
+# 生效条件：root 为源大域根、kind 为 'code_ref'/'doc_ref' 时经 _mod(kind) 调度底层 index_dir 并返回 (items, errors, stats)；ledger 非空时逐文件 record，incremental 为真时跳过 ledger.is_fresh 为真的文件，stats 未截断且 seen 非空时执行 reconcile，commit 为假时不 save（由调用方在节点写成功后 save）。
 def index_dir(root: str, *, kind: str, patterns=None, max_files: int = 500,
               max_items: int = 2000, incremental: bool = False,
-              ledger: "Ledger" = None, skip_dirs=None):
+              ledger: "Ledger" = None, skip_dirs=None, commit: bool = True):
     """按 kind 调度 codeindex / docindex 的全量（或增量）索引。
 
     incremental=True 且给了 ledger 时：未变文件跳过（`skipped_unchanged`）。
     返回 (items, errors, stats)，与底层 index_dir 的返回一致（多一个
-    `skipped_unchanged`）。
+    `skipped_unchanged`；给了 ledger 时另加 `empty_scan`）。
+
+    **零信息纪律（对账）**：`seen` 为空＝这次一个文件都没走过（目录空 / 全被排除 /
+    全读不回），此时「没见到」不等于「源已消失」——**不对账**。否则一次空扫就能把
+    该域的水位整片剪空（实测：目录仍在而零文件，prune 删 0、reconcile 删 2）。
+    `prune` 照旧执行：它的判据是「root 是否还是目录」，与本次扫到几个文件无关
+    （实测「目录仍在零文件」时 prune 删 0）。
+
+    **写序（`commit`）**：`commit=False` 时照做 prune / reconcile / note_index，
+    但不落盘——由调用方在**节点写成功之后**再 `ledger.save()`。这样进程在两步之间
+    被杀，残留方向是「节点新 + 水位旧」（下次增量重切该文件），而不是「水位新 +
+    节点旧」（节点被判成已索引、漂移静默）。
 
     `skip_dirs` 透传给底层：**追加**排除、只增不减（内置 `.git`/`.venv`/
     `node_modules` 等不可被关闭），见 `codeindex.skip_matcher`。实际排掉了哪些目录
@@ -321,14 +351,21 @@ def index_dir(root: str, *, kind: str, patterns=None, max_files: int = 500,
         fresh=fresh, on_file=on_file, skip_dirs=skip_dirs,
     )
     if ledger is not None:
+        # 空扫透出（stats 与 last_index 两面同值）：这不是「源全没了」，而是
+        # 「这一轮什么都没走到」——两个面都如实记，别互相打架。
+        stats["empty_scan"] = not seen
         ledger.prune()
-        if not stats.get("truncated"):
-            # 没扫完就不能对账：截断时「没见到」不等于「源已消失」。
+        if seen and not stats.get("truncated"):
+            # 对账的两个前提：①**这次真的走过文件**（空扫 ⇒ 「没见到」不代表
+            # 「源已消失」，否则一次空扫就把水位剪空）；②没被截断（没扫完 ≠
+            # 剩下的都消失了）。
             ledger.reconcile(root, kind, seen)
         ledger.note_index(kind=kind, root=root, files=stats.get("files", 0),
                           indexed=len(items), truncated=bool(stats.get("truncated")),
-                          reason=stats.get("truncated_reason") or "")
-        ledger.save()
+                          reason=stats.get("truncated_reason") or "",
+                          empty_scan=stats["empty_scan"])
+        if commit:
+            ledger.save()
     return items, errors, stats
 
 
@@ -348,13 +385,19 @@ def _domain_of(it: dict) -> str:
     return path.split("/")[0] or "orphan"
 
 
-# 生效条件：kind == 'code_ref' 时按 codeindex.node_id/render 写入 cg（tags 含 'code'、code_ref=_code_ref(it, root)），kind == 'doc_ref' 时按 docindex 写入（tags 含 'doc'、doc_ref=_doc_ref(it, root)、密级取自 docindex.sensitivity_for(it['path'], sensitivity)），其他 kind 抛 ValueError，返回 (ids, sens)。
+# 生效条件：kind == 'code_ref' 时按 codeindex.node_id/render 写入 cg（tags 含 'code'、code_ref=_code_ref(it, root)），kind == 'doc_ref' 时按 docindex 写入（tags 含 'doc'、doc_ref=_doc_ref(it, root, src_of(it))、密级取自 docindex.sensitivity_for(it['path'], sensitivity)），其他 kind 抛 ValueError，返回 (ids, sens)。
 def add_items(cg, items, *, kind: str, root: str, layer=None, sensitivity=None,
-              layer_of=None):
+              layer_of=None, src_of=None, extra_of=None):
     """把索引条目写进认知图（code / doc 的落盘细节收在这里，唯一实现）。
 
     - `layer=None` → 默认 `knowledge`（与代码节点同层，保证进默认召回）。
     - `layer_of(nid)` 可逐节点覆盖 layer（heal 重建时保留原层）。
+    - `src_of(it)` 为真时把返回值写进 `doc_ref["src"]`（真源身份层，见
+      `_doc_ref`）——不传时产物**逐字节不变**。
+    - `extra_of(it)` 返回 `{"tags": [...], "attrs": {...}}`：追加标签与
+      frontmatter 键（日志索引的 `dsh-log/logsrc/regenerable/ws:` 与
+      `session/workspace/dsh_session_uuid` 走这里，免得在 `logref` 里
+      复制一遍 doc 分支而与本函数漂移）。与既有 `layer_of` 同款逐条钩子。
     - doc 节点：密级走 `docindex.sensitivity_for`（只可能更严）；返回密级分布。
     - `condition_space` 走 `codeindex/docindex.condition_space`，与正文的
       `# 生效条件：` 行**同源**——改造前此处只写 `observation_position` 单槽，
@@ -380,15 +423,17 @@ def add_items(cg, items, *, kind: str, root: str, layer=None, sensitivity=None,
             level = it.get("level")
             s, _basis = docindex.sensitivity_for(it.get("path") or "", sensitivity)
             sens[s] = sens.get(s, 0) + 1
+            extra = (extra_of(it) or {}) if extra_of else {}
             cg.add(
                 nid, docindex.render(it),
                 layer=(layer_of(nid) if layer_of else None) or layer or "knowledge",
                 tags=["doc", "doc:md", f"level:{level}",
-                      "domain:" + _domain_of(it)],
+                      "domain:" + _domain_of(it)] + list(extra.get("tags") or []),
                 condition_space=docindex.condition_space(it),
                 verification_basis="data",
                 sensitivity=s,
-                doc_ref=_doc_ref(it, root),
+                doc_ref=_doc_ref(it, root, src_of(it) if src_of else None),
+                **(extra.get("attrs") or {}),
             )
         else:
             raise ValueError(f"未知 ref kind：{kind!r}")
@@ -410,15 +455,20 @@ def _code_ref(it: dict, root: str, render_version=None) -> dict:
     }
 
 
-# 生效条件：把入参 root 原样写入返回 dict 的 'root'，path/heading/heading_path/level/lineno/end/anchor/hash/lang 按 it.get 取值（缺省 None），precise 取 bool(it.get('precise', True))。
-def _doc_ref(it: dict, root: str) -> dict:
-    return {
+# 生效条件：把入参 root 原样写入返回 dict 的 'root'，path/heading/heading_path/level/lineno/end/anchor/hash/lang 按 it.get 取值（缺省 None），precise 取 bool(it.get('precise', True))；src 为真值时并入 'src' 键，假值（含 None/{}/""）时该键**不出现**（默认路径产物逐字不变——read_ref/probe_ref/check_refs/Ledger 都不认这个键）。
+def _doc_ref(it: dict, root: str, src: dict = None) -> dict:
+    ref = {
         "path": it.get("path"), "heading": it.get("heading"),
         "heading_path": it.get("heading_path"), "level": it.get("level"),
         "lineno": it.get("lineno"), "end": it.get("end"),
         "anchor": it.get("anchor"), "hash": it.get("hash"), "lang": it.get("lang"),
         "precise": bool(it.get("precise", True)), "root": root,
     }
+    if src:
+        # 真源身份层（日志一路）：区间落在转写上，身份落在 zstd 日志上。
+        # 只增不删：既有 11 键语义不动，回读侧（refindex.read_ref）对它无感。
+        ref["src"] = src
+    return ref
 
 
 # --------------------------------------------------------------------------
@@ -486,14 +536,68 @@ def read_ref(ref: dict, *, root: str = None, ref_kind: str = "ref") -> dict:
     }
 
 
-# 生效条件：cg 的 index['nodes'] 非空时汇总 stale/dangling/unresolved/errors 并返回 ok =（无 stale 且无 dangling）；only_tagged 为真时只探测 tags 含 'code'/'doc' 的节点，ledger 非空时先走 (size, mtime) 快路径。
+# 生效条件：n 为水位条目内的节点记录（id/lineno/end/hash）、e 为文件条目、rel/src_root 为源相对路径与源大域、unchanged 为源 size/mtime 未变时，按 cg.get(nid) 的 frontmatter ref 判该 node_id 的快路径结论并返回 {'node_id','kind','covered','probe','mismatch'}——取不回节点或节点无 ref 时 covered=False/probe=None（落回退路径、不记 mismatch）；五项全等且 unchanged 时 probe=None（跳过不读源）；否则 probe 为待探测 ref；不一致时 mismatch 带两侧 root/hash 与 kind_of_gap。
+def _fast_path_verdict(cg, n: dict, e: dict, rel: str, src_root: str,
+                       unchanged: bool) -> dict:
+    """单条水位记录 → 该 node_id 的快路径结论（**唯一实现**，也是定点变异锚点）。
+
+    探测数据**只**取节点自身 frontmatter ref（`ref_of(cg.get(nid))`）——水位条目
+    一律不进 probe，它只判「能不能跳过」。跳过的充分条件＝五项全等 + 源 size/mtime
+    未变 + 本轮未被判过（去重由调用方在 `covered` 上做，见 `check_refs`）。
+
+    `cg.get` 抛错 / 取空 / 节点无 ref 时**不认领也不记 mismatch**：那类节点落回
+    回退路径（同一份 `cg.get` + `ref_of` 口径），不新增行类。代价如实记：它们仍算
+    未覆盖、留在 todo 里，而 `truncated` 只看 todo 长度——大量读不回的节点可能把
+    `truncated` 推成 True，那是覆盖缺口被说出来了，不是被判成漂移。
+    """
+    nid = n.get("id")
+    out = {"node_id": nid, "kind": "", "covered": False, "probe": None,
+           "mismatch": None}
+    try:
+        node = cg.get(nid)
+    except Exception:                    # 读不回 ≠ 漂移：交回退路径同口径处理
+        return out
+    kind, ref = ref_of(node)
+    if not ref:
+        return out
+    out["kind"] = kind
+    out["covered"] = True
+    agree = (_norm_rel(ref.get("path")) == _norm_rel(rel)
+             and ref.get("lineno") == n.get("lineno")
+             and ref.get("end") == n.get("end")
+             and ref.get("hash") == n.get("hash")
+             and _same_root(ref.get("root"), src_root))
+    if not agree:
+        out["mismatch"] = {
+            "node_id": nid, "path": rel, "kind": kind,
+            "watermark_root": e.get("root") or src_root,
+            "node_root": ref.get("root"),
+            "watermark_hash": n.get("hash"), "node_hash": ref.get("hash"),
+            "kind_of_gap": ("watermark_behind"
+                            if _same_root(ref.get("root"), src_root)
+                            else "collision_multi_root"),
+        }
+    if agree and unchanged:
+        return out                       # 跳过：不读源
+    out["probe"] = {**ref, "path": ref.get("path") or rel,
+                    "root": ref.get("root") or src_root}
+    return out
+
+
+# 生效条件：cg 的 index['nodes'] 非空时汇总 stale/dangling/unresolved/errors/ledger_mismatch 并返回 ok =（无 stale 且无 dangling）；only_tagged 为真时只探测 tags 含 'code'/'doc' 的节点，ledger 非空时先经 _fast_path_verdict 走 (size, mtime) 快路径。
 def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
                only_tagged: bool = True) -> dict:
     """漂移 / 悬空巡检（只读、不抛）。
 
-    优先走 ledger 的 (size, mtime) 快路径：未变文件**不读盘**直接判 ok；
-    变了的文件读一次、按记录区间重算哈希判 stale。
-    ledger 覆盖不到的节点（早期索引 / 未开增量）再回退逐节点探测。
+    **分工：节点判漂移，水位只判跳过。** 探测数据只取**节点自身 frontmatter ref**
+    （`ref_of(cg.get(nid))`）——ledger 条目一律不进 probe；它只用来判「这个节点能不能
+    跳过、不读源」。跳过的充分条件（三条同时成立）：①节点 ref 与水位条目
+    `(hash, lineno, end, path, root)` **五项全等**；②源文件 size/mtime 未变；
+    ③该 node_id 本轮尚未判过（去重）。五项含 `path` / `root` 是必要的：不含时跨域
+    撞 id 在稳态不可见，且 node/水位不一致会重复报红。
+    不一致本身不改判定（不进 `ok`、不产生新红行），只记 `ledger_mismatch` 归因行
+    （带两侧 root：roots 相同＝写序断裂 / 旧水位，不同＝跨域撞 id）。
+    水位覆盖不到的节点（早期索引 / 未开增量 / `cg.get` 读不回）再回退逐节点探测。
 
     `only_tagged=True`（默认）只探测带 `code` / `doc` 标签的节点——ref 只由
     `index_code` / `index_doc` 产生，两者都会打这两个标签；这样巡检不必为每条
@@ -501,6 +605,7 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
     """
     nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
     stale, dangling, unresolved, errors = [], [], [], []
+    mismatch = []
     covered = set()
 
 # 生效条件：当 nid、ref、kind、rel 传入时，p = probe_ref(ref) 后按 p["status"] 分派：为 "dangling" 时把含 node_id/ref_kind/path/lineno/end/error 的 row 加入 dangling，为 "stale" 时补 hash_expected/hash 加入 stale，为 "unresolved" 时加入 unresolved，为 "error" 时加入 errors；其他状态不加入；
@@ -520,14 +625,14 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
         elif p["status"] == "error":
             errors.append(row)
 
-    # 快路径：ledger 记录的文件（键 = 源文件绝对路径，天然跨大域不撞名）
+    # 快路径：ledger 记录的文件（键 = 源文件绝对路径，天然跨大域不撞名）。
+    # 判据与探测数据收在 `_fast_path_verdict`（唯一实现，也是红基线的定点变异锚点）。
     if ledger is not None:
         for key, e in sorted((ledger.load().get("files") or {}).items()):
             rec_nodes = [n for n in (e.get("nodes") or [])
                          if n.get("id") in nodes]
             if not rec_nodes:
                 continue
-            covered.update(n.get("id") for n in rec_nodes)
             rel = e.get("path") or ""
             # 必须用**每个源文件自己的 root**（索引时的源大域），不能用 ledger.root：
             # 后者是认知图根，拿它拼路径会指向不存在的位置、把一切都误判成 dangling。
@@ -538,11 +643,23 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
                              and abs(float(e.get("mtime") or 0.0) - st.st_mtime) < 1e-6)
             except OSError:
                 unchanged = False
-            if not unchanged:
-                kind = e.get("kind") or kind_of_path(rel)
-                for n in rec_nodes:
-                    _probe_one(n.get("id"), {**n, "path": rel, "root": src_root},
-                               kind, rel)
+            for n in rec_nodes:
+                nid = n.get("id")
+                if nid in covered:
+                    # ①同一 node_id 只判一次：跨大域撞 id 时两条水位条目列同一 id，
+                    # 不去重就会把同一处漂移按「水位条目数」重复报（实测两域源都改：
+                    # 不去重 4 行 / dup=2，去重后 2 行 / dup=0——夹具每文件 2 节点）。
+                    continue
+                v = _fast_path_verdict(cg, n, e, rel, src_root, unchanged)
+                if v["mismatch"]:
+                    mismatch.append(v["mismatch"])
+                if not v["covered"]:
+                    # ②读不回节点 / 节点无 ref：不认领、不记 mismatch，落回退路径
+                    continue
+                covered.add(nid)
+                if v["probe"] is not None:
+                    _probe_one(nid, v["probe"],
+                               v["kind"] or e.get("kind") or kind_of_path(rel), rel)
 
     # 回退：ledger 未覆盖的索引节点
 # 生效条件：当 nid 传入时，若 only_tagged 为假值立即返回 True；否则取 (nodes.get(nid) or {}).get("tags") or []，仅当其中存在 "code" 或 "doc" 返回 True，否则返回 False；
@@ -552,7 +669,7 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
         tags = (nodes.get(nid) or {}).get("tags") or []
         return any(t in ("code", "doc") for t in tags)
 
-    todo = [nid for nid in nodes if nid not in covered and _candidate(nid)]
+    todo = [nid for nid in list(nodes) if nid not in covered and _candidate(nid)]
     truncated = len(todo) > max_nodes
     checked = 0
     for nid in todo[:max_nodes]:
@@ -578,6 +695,10 @@ def check_refs(cg, *, ledger: "Ledger" = None, max_nodes: int = MAX_CHECK,
         "ledger_files": len((ledger.load().get("files") or {})) if ledger else 0,
         "stale": stale, "dangling": dangling,
         "unresolved": unresolved, "errors": errors,
+        # 水位与节点不一致的**归因行**（带两侧 root）：不进 ok、不产生新红行，
+        # 但也不是静默——写序断裂 / 跨域撞 id 在这里可见（只增键，语义不动）。
+        "ledger_mismatch": mismatch[:20],
+        "ledger_mismatch_count": len(mismatch),
         "truncated": truncated, "max_nodes": max_nodes,
     }
 
@@ -691,7 +812,7 @@ def prune_orphans(cg, *, kind: str, root: str, items, dry_run: bool = False,
     # 免得为全库每条记忆都读一次盘。
     tag = "doc" if kind == "doc_ref" else "code"
     plan = []
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         if tag not in ((e or {}).get("tags") or []):
             continue
         try:
@@ -727,6 +848,13 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
     出口——已删脚本、被搬走的文档留下的残留节点一次清掉，而不是逐条手工
     `forget`。判定与巡检共用 `probe_ref` 的唯一实现，口径不会打架。
 
+    **可再生节点不列入**（计数 `regenerable_skipped` 透出）：判据两条取并——
+    标签含 `regenerable`，**或** ref 带真源身份层（`doc_ref.src.file_hash`）。
+    日志索引的转写落在系统临时目录、被清理后回读必然 dangling，而这类节点
+    **可再生**（真源仍在，重跑落库即恢复）——把它们软删会让再生无从下手。
+    第二条判据是必要的：标签会随 heal/rebuild 的重放面缺席（只重放 layer 与
+    src）而消失，只认标签等于让这条保护在重建后静默失效。
+
     另清**幽灵条目**（ghosts）：索引有条目、节点文件却不存在。它们是历史
     「删除只摘内存索引、不落盘」的遗留——`cg.get` 取不回 → 悬空清退够不着它，
     而 `check_refs` 走 ledger 会一直报 → dangling 永不归零。判据只用唯一真源
@@ -746,10 +874,17 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
     # 同 prune_orphans：ref 只在节点 frontmatter 里，索引条目里没有，
     # 必须 cg.get 取回节点再 ref_of（否则恒空、静默不删）。
     todo = []
-    for nid, e in nodes.items():
+    regenerable_skipped = []
+    for nid, e in list(nodes.items()):
         tags = (e or {}).get("tags") or []
         if not any(t in ("code", "doc") for t in tags):
             continue
+        if "regenerable" in tags:
+            # 可再生节点（转写落 %TEMP%、被系统清理后回读必然 dangling）**不进清退
+            # 计划**：软删它们与「可再生」的前提直接冲突——P2 的再生路径正是靠
+            # 这些节点找回真源。计数透出，不静默。
+            regenerable_skipped.append(nid)
+            continue
         try:
             node = cg.get(nid)
         except Exception:
@@ -759,6 +894,13 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
         _k, ref = ref_of(node)
         if not ref or not ref.get("root"):
             continue
+        if isinstance(ref.get("src"), dict) and ref["src"].get("file_hash"):
+            # 第二判据（**不依赖标签存活**）：ref 带真源身份层（`doc_ref.src`）即
+            # 「真源仍在 + 有文件哈希」⇒ 转写可再生。标签可能被 heal/rebuild 的
+            # 重放面丢掉（它只重放 layer 与 src，见 rebuild docstring），只认标签
+            # 会让「可再生」这个安全属性在重建后静默消失。
+            regenerable_skipped.append(nid)
+            continue
         if only_roots and not any(_same_root(ref.get("root"), r) for r in only_roots):
             continue
         todo.append((nid, ref))
@@ -777,7 +919,9 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
     base = {"scanned": len(nodes), "candidates": len(plan),
             "ghosts": len(ghost_plan),
             "dry_run": bool(dry_run), "truncated": truncated,
-            "max_nodes": max_nodes}
+            "max_nodes": max_nodes,
+            # 被排除的可再生节点数（原本会因转写被清理而列入 dangling）——不静默
+            "regenerable_skipped": len(regenerable_skipped)}
     if dry_run:
         return {**base, "ok": True, "count": len(plan), "pruned": sorted(plan)[:50],
                 "ghost_pruned": ghost_plan[:50],
@@ -786,20 +930,40 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
     dropped = _drop_ghosts(cg, ghost_plan)
     return {**base, "ok": True, "count": len(done), "pruned": done[:50],
             "ghost_pruned": dropped[:50],
-            "skipped_protected": blocked[:20], "reason": why}
+            "skipped_protected": blocked[:20],
+            "regenerable_skipped_ids": sorted(regenerable_skipped)[:20],
+            "reason": why}
 
 
-# 生效条件：cg 节点按 ref['root'] 与 kind 分组后逐组以 index_dir(incremental=False, ledger=ledger) 重切、再以 add_items(layer_of=原 layer) 重建，返回 {'ok','roots','groups','indexed','errors','truncated'}；only_roots 非 None 时只处理其中列出的 root。
+# 生效条件：cg 节点按 ref['root'] 与 kind 分组后逐组以 index_dir(incremental=False, ledger=ledger) 重切、再以 add_items(layer_of=原 layer) 重建，返回 {'ok','roots','groups','indexed','errors','truncated','roots_missing','rebuilt'}；root 已不是目录的组不调 index_dir（记 roots_missing 并置 ok=False）；本次 0 文件（stats.empty_scan）或 files 为 0 的组同样置 ok=False 并记错误；only_roots 非 None 时只处理其中列出的 root。
 def rebuild(cg, *, ledger: "Ledger" = None, only_roots=None, max_files: int = 500,
             max_items: int = 2000) -> dict:
     """按 ref 记录的 root 重建索引（sustain.heal 的修复动作）。
 
     只重跑出了问题的 root（`only_roots`），逐节点**保留原 layer**；
     doc 密级用默认策略重算（默认只可能更严，不会放松）。
+    `src_of` 逐条从**既有节点的 doc_ref** 取回 `src`（与 `layer_of` 同构）：
+    否则重切转写 root 时 `doc_ref.src` 会静默消失＝真源身份层丢失。
+
+    **悬空 root 不重建（H1b）**：root 已不是目录的组**不调 `index_dir`**——重切只会
+    扫到 0 个文件，而 `index_dir` 的 prune / reconcile 会把该域水位剪空（实测：
+    见 `index_dir` 的零信息纪律；这是「水位被写成空」的唯一入口，op 面在
+    `mcp_server` 侧已先按 isdir 拒）。该组记入 `roots_missing` 并置 `ok=False`
+    ——没修好就说没修好，悬空仍需人工处置（`op=ref action=prune`）。
+
+    **逐组如实回报（H2）**：`rebuilt` 逐组记 (root/kind/files/indexed/empty_scan/
+    truncated)；空扫组（`stats.empty_scan` 或 0 文件）置 `ok=False` 并 append 一条
+    errors。截断仍逐组传播到 `out["truncated"]`，异常路径仍置 `ok=False`。
+
+    **如实边界**：本函数只重放 `layer` 与 `src`，**不重放 `extra_of` 派生面**
+    （附加 tags / 附加 frontmatter 键）。日志索引节点（`dsh-log/logsrc/
+    regenerable` + `session/workspace/dsh_session_uuid`）因此不能靠 heal 重建，
+    要走专用入口 `scripts/_mdcg_reindex_dshlogs.py --repair 1`——该边界写在
+    返回值的 `note` 里，不静默。
     """
     nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
     groups = {}
-    for nid in nodes:
+    for nid in list(nodes):
         try:
             node = cg.get(nid)
         except Exception:
@@ -814,16 +978,61 @@ def rebuild(cg, *, ledger: "Ledger" = None, only_roots=None, max_files: int = 50
         groups[(r, kind)] += 1
 
     out = {"ok": True, "roots": sorted({r for r, _ in groups}),
-           "groups": len(groups), "indexed": 0, "errors": [], "truncated": False}
+           "groups": len(groups), "indexed": 0, "errors": [], "truncated": False,
+           "roots_missing": [], "rebuilt": []}
     for (root, kind) in sorted(groups):
+        if not os.path.isdir(root):
+            # H1b：悬空域（源大域已搬走/删除）**不进 index_dir**——它对不上任何文件，
+            # 而 index_dir 会把该域水位剪空（[C2] 实测）。这里如实记、置 ok=False。
+            out["roots_missing"].append(root)
+            out["ok"] = False
+            out["errors"].append(
+                f"{root} [{kind}]：root 已不是目录，未重建（悬空需人工处置）")
+            continue
         try:
             items, errors, stats = index_dir(
                 root, kind=kind, max_files=max_files, max_items=max_items,
                 incremental=False, ledger=ledger)
+            empty = stats.get("empty_scan")
+            if empty is None:                         # 无 ledger 时退一步：0 文件即空扫
+                empty = not stats.get("files")
+            out["rebuilt"].append({
+                "root": root, "kind": kind, "files": stats.get("files"),
+                "indexed": len(items), "empty_scan": bool(empty),
+                "truncated": bool(stats.get("truncated"))})
+            if empty:
+                # H2：这一组什么都没扫到 ⇒ 没修好，不许报成修好。
+                out["ok"] = False
+                out["errors"].append(
+                    f"{root} [{kind}]：本次 0 个文件被扫到（empty_scan），"
+                    f"该域水位未对账、索引未重建")
+            kept_src = []                             # 本次真的取回 src 的节点
+
+            def _src_of(it, _cg=cg, _kind=kind, _hit=kept_src):   # noqa: E306
+                nid = node_id_of(it, _kind)
+                try:
+                    node = _cg.get(nid)
+                except Exception:
+                    return None
+                if not node:
+                    return None
+                _k, ref = ref_of(node)
+                s = (ref or {}).get("src") or None
+                if s:
+                    _hit.append(nid)
+                return s
+
             ids, _sens = add_items(
                 cg, items, kind=kind, root=root,
-                layer_of=lambda nid: (nodes.get(nid) or {}).get("layer"))
+                layer_of=lambda nid: (nodes.get(nid) or {}).get("layer"),
+                src_of=_src_of)
             out["indexed"] += len(ids)
+            if kept_src:
+                # extra_of 派生面不重放（见 docstring）：命中 src 承载节点即如实提示
+                out["note"] = ("只重放 layer 与 doc_ref.src（%d 个）——extra_of "
+                               "派生面（附加 tags/frontmatter 键）不由 heal 重建；"
+                               "日志索引节点请走 scripts/_mdcg_reindex_dshlogs.py"
+                               " --repair 1" % len(kept_src))
             out["errors"].extend(errors)
             out["truncated"] = out["truncated"] or bool(stats.get("truncated"))
         except Exception as exc:                      # 自愈不抛

package/md_cg/refine.py

@@ -136,7 +136,7 @@ def _pool(cg, prefix) -> tuple:
     """抽检池：id 以 prefix 开头、非受保护节点（与 induce 的池口径一致）。"""
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
     ids, protected = [], 0
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         if not str(nid).startswith(prefix):
             continue
         if (e or {}).get("protected"):

package/md_cg/routing.py

@@ -269,27 +269,54 @@ def domain_similarity(a: str, b: str) -> float:
     return len(ga & gb) / len(ga | gb)
 
 
-# 生效条件：counts 各值之和为 0（含空 dict 与全 0 计数）时返回 {'ok': True, 'reason': 'empty', 'buckets': 0}；否则在最大桶占比 >30%、桶数 >1 且单例桶占比 >50%、期望扫描 >30% 中命中的项写入 problems，返回含 ok(=problems 为空)、buckets、nodes、max_bucket_share、singleton_ratio、expected_scan、problems 的 dict。
-def bucket_health(counts: dict) -> dict:
+# 生效条件：counts 各值之和为 0（含空 dict 与全 0 计数）时——total_nodes 为假值（缺省 None 或 <=0）返回 {'ok': True, 'reason': 'empty', 'buckets': 0}（与加 total_nodes 参数之前逐位一致），total_nodes > 0 返回 {'ok': False, 'reason': 'empty_buckets', 'buckets': 0, 'nodes': total_nodes, 'problems': [...]}；否则在「桶数 >1 且最大桶占比 >30%」、「桶数 >1 且单例桶占比 >50%」、「桶数 ==1（单桶，条件路由不可用）」、桶数 >1 时「期望扫描 >30%」中命中的项写入 problems，返回含 ok(=problems 为空)、buckets、nodes、max_bucket_share、singleton_ratio、expected_scan、problems 的 dict。
+def bucket_health(counts: dict, total_nodes: int = None) -> dict:
     """分区健康度自检。分桶键一旦退化（巨桶或碎片化），条件路由就是纸面收益，
     必须在写入侧就能发现，而不是等召回变差才回头查。
 
     counts: {bucket_dir: node_count}
+    total_nodes: 调用方（`MdCG.health`）持有的**库内节点总数**，唯一用途是把
+      「真空库（无节点、无桶）」与「有节点但分桶表为空（分区信息缺失）」分开。
+      **缺省 None ⇒ 不做该比对**：空 counts 的返回与加本参数之前逐位一致，
+      故既有调用方（test_p0 / bench_axis_domain / bench6_arms，只传 counts）
+      行为一字不变——M3③ 的向后兼容面。
+
+    单桶（nb == 1）是「从未分区」而不是「分区退化」：巨桶判据（top/n == 1.0）与
+    期望扫描判据（同样恒 1.0）在 nb==1 时必触发且互为同一事实，此前把这类库报成
+    「巨桶 / 分区失效」是假话（M3①②）。现只给一条如实读数——条件路由本就不可用；
+    ok 仍为 False（单桶库的一次查询确实是全量扫描，判据未放宽）。
     """
     n = sum(counts.values())
+    nb = len(counts)
     if not n:
+        # 库里有节点却零个桶 ⇒ 分桶表与节点面不一致（分区信息缺失），
+        # 不能报 ok=True 冒充健康（M3③）。total_nodes 缺省时不作此判断。
+        if total_nodes and total_nodes > 0:
+            return {
+                "ok": False,
+                "reason": "empty_buckets",
+                "buckets": 0,
+                "nodes": int(total_nodes),
+                "problems": [f"分桶表为空但库内有 {int(total_nodes)} 个节点："
+                             "分区信息缺失，条件路由不可用（非真空库）"],
+            }
         return {"ok": True, "reason": "empty", "buckets": 0}
-    nb = len(counts)
     top = max(counts.values())
     singles = sum(1 for v in counts.values() if v == 1)
     # 期望扫描占比：随机取一节点的情境去路由，命中桶的期望大小占全库比例
     expected_scan = sum(v * v for v in counts.values()) / n / n
     problems = []
-    if top / n > 0.30:
+    if nb > 1 and top / n > 0.30:
         problems.append(f"巨桶：最大桶占 {top / n:.1%}（>30% 视为分区失效）")
     if nb > 1 and singles / nb > 0.50:
         problems.append(f"碎片化：单例桶占 {singles / nb:.1%}（>50% 说明键含实例级字段）")
-    if expected_scan > 0.30:
+    if nb == 1:
+        # 巨桶/期望扫描两条在 nb==1 时只是同一事实的两种写法，合并为一条如实读数。
+        # expected_scan 的**数值**仍在返回 dict 里（下游读的是数：test_p0 :92、
+        # bench_axis_domain :159），只有文案不再把「未分区」说成「巨桶退化」。
+        problems.append(f"单桶：全库仅 1 个分桶（{n} 个节点同桶），"
+                        "条件路由本就不可用（从未分区，非分区退化）")
+    elif expected_scan > 0.30:
         problems.append(f"路由无效：期望扫描 {expected_scan:.1%}（接近全量）")
     return {
         "ok": not problems,

package/md_cg/run_tests.py

@@ -38,6 +38,23 @@ import sys
 import tempfile
 import time
 
+# ---------------------------------------------------------------- 入口自保证 UTF-8
+# 约束（工作纪律第 15 条）：本调用必须在**任何文件/库 I/O 之前**——utf8_boot.ensure_utf8
+# 在解释器未开 UTF-8 模式时以相同 argv 重启自身（-X utf8），早于它的任何 open/stdio
+# 读写都走 locale 编码（Windows 中文机 = cp936：裸 open 抛 UnicodeDecodeError、中文写
+# 落 GBK 字节）。本文件是包内全量入口（安装态下 README 的门禁命令），必须最先保证。
+# 仓库根入 sys.path 的形态照 hive/exec.py::_md_cg_import 的最小写法（助手在仓根，
+# 不是 md_cg 包目录）。
+# 被 import（本模块非 __main__）时助手只置子进程继承面、绝不重启/退出——F6：静默重启
+# 会吞掉调用方输入。
+_UTF8_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _UTF8_ROOT not in sys.path:
+    sys.path.insert(0, _UTF8_ROOT)
+from utf8_boot import ensure_utf8  # noqa: E402
+
+ensure_utf8(__file__)
+
+
 _REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 #: 逐用例日志目录（重定向目标；默认临时目录，避免污染仓）
 _LOG_DIR = os.environ.get("MDCG_TESTLOG_DIR") or os.path.join(