@furongjun1999/dsh-memory 0.4.4 → 0.4.6

package/md_cg/protect.py

@@ -0,0 +1,260 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 自我层 / 锚点层写保护（不可遗忘）
+
+理论出处（全部来自本仓已有文档，非外部发明）：
+
+  · `docs/灵枢_自我层定义.md:6`
+      SELF 层 = 身份 + 价值观 + 图接口，**不可遗忘**、跨会话自动加载。
+      任何实例都能改写自我层 = 自我认知可被任意覆写，与「自我」定义冲突。
+  · `docs/认知图_MD目录方案_v0.1.md:53`
+      `anchor/  # 锚点层（不可遗忘，保护）`
+  · `docs/认知图_MD目录方案_v0.1.md:412-416`
+      「importance 提升（保护：不可遗忘记入 anchor/ 且**受保护标记**）」
+  · `docs/tool_table_v0.3.0.md:15`
+      「importance_hint 可显式提示重要性（**≥0.7 触发不可遗忘保护**）」
+
+三层保护（任一命中即受保护）：
+
+  ┌ 1. 层保护      layer ∈ {self, anchor}
+  ├ 2. 显式标记    frontmatter.protected == True
+  └ 3. 重要性保护  importance ≥ 0.70（写入时自动打标）
+
+**关键区分：不可遗忘 ≠ 不可覆盖。**
+  · 不可遗忘（forget / 降级搬迁）：层保护 + protected 标记 + importance≥0.7 三者都拦。
+    文档原话是「不可遗忘」「触发不可遗忘保护」——重点是**别弄丢**。
+  · 不可覆盖（覆写同一 id）：只拦 层保护 + 显式 immutable 标记。
+    因为 goal_*/fix_*/kp_* 这类 id 是内容派生、由系统自身幂等更新，
+    若 importance≥0.7 就禁止覆写，会把正常的状态更新全部误伤。
+    自我认知之所以不可篡改，靠的是 **self/anchor 层**这个强信号，
+    而不是"重要性高"这个弱信号。
+
+受保护节点的动作必须显式 `override=True`：动作前先把旧版本快照进
+`_protected_history/<id>/<时间戳>.md`，并把「谁、何时、为何」记进
+`_protected_audit.jsonl`——保护不等于黑箱。
+
+注意：新建（索引中不存在的节点）不受限。保护的是「已有自我认知不被改/删」，
+不是「禁止产生自我认知」，否则审计节点等正常写入会被误伤。
+"""
+import os
+import time
+
+from . import nodefile
+from .fsutil import append_jsonl, atomic_write
+
+PROTECTED_LAYERS = ("self", "anchor")
+AUTO_PROTECT_IMPORTANCE = 0.70
+HISTORY_DIR = "_protected_history"
+AUDIT_FILE = "_protected_audit.jsonl"
+
+
+class ProtectionError(PermissionError):
+    """受保护节点的写动作被拒绝。"""
+
+
+# ---------------------------------------------------------------- 判定
+
+def _entry(cg, node_id):
+    return ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
+
+
+def _fm(cg, node_id):
+    """取判定所需的 frontmatter 字段；索引快照缺 protected 时回退读文件。"""
+    e = _entry(cg, node_id)
+    if e is None:
+        return None
+    fm = {
+        "layer": e.get("layer"),
+        "importance": e.get("importance", 0.5),
+        "protected": e.get("protected"),
+        "protection_reason": e.get("protection_reason"),
+        "immutable": e.get("immutable"),
+        "self_state": e.get("self_state"),
+    }
+    # 回退读文件：索引快照缺字段时。self_state 只在受保护层（self/anchor）
+    # 需要，回退代价被限制在少量节点上，不影响全量统计性能。
+    need_fallback = ("protected" not in e or "immutable" not in e
+                     or ("self_state" not in e
+                         and str(e.get("layer") or "") in PROTECTED_LAYERS))
+    if need_fallback:
+        try:
+            node = cg.get(node_id)
+        except Exception:
+            node = None
+        if node:
+            f2 = node.get("frontmatter") or {}
+            fm["protected"] = f2.get("protected")
+            fm["protection_reason"] = f2.get("protection_reason")
+            fm["immutable"] = f2.get("immutable")
+            fm["self_state"] = f2.get("self_state")
+            fm["layer"] = f2.get("layer") or fm["layer"]
+            fm["importance"] = f2.get("importance", fm["importance"])
+    return fm
+
+
+def is_protected(cg, node_id):
+    """**不可遗忘**判定 → (是否受保护, 原因)。节点不存在返回 (False, "")。"""
+    fm = _fm(cg, node_id)
+    if fm is None:
+        return False, ""
+    layer = str(fm.get("layer") or "")
+    if layer in PROTECTED_LAYERS:
+        return True, f"层保护：{layer}（不可遗忘层）"
+    if fm.get("protected") is True:
+        return True, str(fm.get("protection_reason") or "显式保护标记")
+    try:
+        imp = float(fm.get("importance") or 0.0)
+    except Exception:
+        imp = 0.0
+    if imp >= AUTO_PROTECT_IMPORTANCE:
+        return True, f"重要性保护：importance={imp:.2f}≥{AUTO_PROTECT_IMPORTANCE}"
+    return False, ""
+
+
+def is_immutable(cg, node_id):
+    """**不可覆盖**判定 → (是否不可篡改, 原因)。比不可遗忘更窄，只认强信号。
+
+    例外：自我状态卡（frontmatter.self_state is True）**必须可覆盖**——
+    自我状态本来就要随认知演化而更新，冻结它等于自我认知停止生长。
+    但它仍然 is_protected（不可遗忘），这是「不可遗忘 ≠ 不可覆盖」的延伸。
+    身份锚点不设此豁免，依旧两者皆禁。
+    """
+    fm = _fm(cg, node_id)
+    if fm is None:
+        return False, ""
+    if fm.get("self_state") is True:
+        return False, ""
+    layer = str(fm.get("layer") or "")
+    if layer in PROTECTED_LAYERS:
+        return True, f"层保护：{layer}（不可篡改层）"
+    if fm.get("immutable") is True:
+        return True, str(fm.get("protection_reason") or "显式不可覆盖标记")
+    return False, ""
+
+
+# ---------------------------------------------------------------- 留痕
+
+def _audit(cg, action, node_id, reason, actor=None, snapshot=None):
+    rec = {"t": time.time(), "action": action, "node_id": node_id,
+           "reason": reason, "actor": actor, "snapshot": snapshot}
+    try:
+        append_jsonl(os.path.join(cg.root, AUDIT_FILE), rec)
+    except Exception:
+        pass
+    return rec
+
+
+def snapshot(cg, node_id):
+    """把节点当前版本快照进 `_protected_history/<id>/<ts>.md`，返回相对路径。"""
+    try:
+        node = cg.get(node_id)
+    except Exception:
+        node = None
+    if not node:
+        return None
+    d = os.path.join(cg.root, HISTORY_DIR, node_id)
+    os.makedirs(d, exist_ok=True)
+    ts = time.strftime("%Y%m%d-%H%M%S", time.localtime())
+    p = os.path.join(d, f"{ts}.md")
+    try:
+        cg._write_node(node.get("id"), p, node.get("frontmatter") or {},
+                       node.get("content") or "")
+    except Exception:
+        return None
+    return os.path.relpath(p, cg.root).replace("\\", "/")
+
+
+def history(cg, node_id):
+    """受保护节点的历史版本列表（按时间升序）。"""
+    d = os.path.join(cg.root, HISTORY_DIR, node_id)
+    if not os.path.isdir(d):
+        return []
+    out = [f for f in os.listdir(d) if f.endswith(".md")]
+    out.sort()
+    return [f"{HISTORY_DIR}/{node_id}/{f}" for f in out]
+
+
+# ---------------------------------------------------------------- 守卫
+
+def _allow(cg, node_id, why, action, override, actor):
+    snap = snapshot(cg, node_id)
+    rec = _audit(cg, action, node_id, why, actor, snap)
+    return {"override": True, "reason": why, "snapshot": snap, "audit": rec}
+
+
+def guard_write(cg, node_id, layer=None, override=False, actor=None):
+    """覆盖既有节点前的守卫（只认**不可覆盖**信号）。
+
+    新节点 / 未标记 immutable 的节点直接放行（返回 None）。
+    importance≥0.7 只保证「不可遗忘」，不阻断系统自身的幂等更新。
+    """
+    prot, why = is_immutable(cg, node_id)
+    if not prot:
+        return None
+    if override:
+        return _allow(cg, node_id, why, "override_write", override, actor)
+    raise ProtectionError(
+        f"节点 {node_id} 受写保护（{why}）；覆盖需显式 override=True")
+
+
+def guard_forget(cg, node_id, override=False, actor=None):
+    """删除前的守卫。受保护节点 = 不可遗忘。"""
+    prot, why = is_protected(cg, node_id)
+    if not prot:
+        return None
+    if override:
+        return _allow(cg, node_id, why, "override_forget", override, actor)
+    raise ProtectionError(
+        f"节点 {node_id} 不可遗忘（{why}）；删除需显式 override=True")
+
+
+def guard_move(cg, node_id, to_layer, override=False, actor=None):
+    """降级/搬迁前的守卫：受保护节点不得被移出保护层。"""
+    prot, why = is_protected(cg, node_id)
+    if not prot:
+        return None
+    if to_layer in PROTECTED_LAYERS:
+        return None                       # 保护层之间互搬仍受保护，放行
+    if override:
+        return _allow(cg, node_id, why, "override_move", override, actor)
+    raise ProtectionError(
+        f"节点 {node_id} 受写保护（{why}）；降级移出保护层需显式 override=True")
+
+
+def mark(cg, node_id, reason):
+    """给节点打上 `protected=True` 标记（写回 frontmatter，不动 content）。"""
+    try:
+        node = cg.get(node_id)
+    except Exception:
+        node = None
+    if not node:
+        return None
+    fm = node.get("frontmatter") or {}
+    fm["protected"] = True
+    fm["protection_reason"] = reason
+    cg._write_node(node_id, os.path.join(cg.root, node["path"]),
+                   fm, node.get("content") or "")
+    e = _entry(cg, node_id)
+    if e is not None:
+        e["protected"] = True
+        e["protection_reason"] = reason
+    return {"node_id": node_id, "protected": True, "reason": reason}
+
+
+def stats(cg):
+    """保护面盘点：不可遗忘数 / 不可覆盖数 / 分层分布 / 自动保护命中数。"""
+    nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
+    by_layer, ids, auto, immutable = {}, [], 0, []
+    for nid in nodes:
+        prot, why = is_protected(cg, nid)
+        if prot:
+            ids.append(nid)
+            layer = str(nodes[nid].get("layer") or "?")
+            by_layer[layer] = by_layer.get(layer, 0) + 1
+            if "importance=" in why or why.startswith("重要性保护"):
+                auto += 1
+        imm, _ = is_immutable(cg, nid)
+        if imm:
+            immutable.append(nid)
+    return {"protected_count": len(ids), "immutable_count": len(immutable),
+            "by_layer": by_layer, "auto_by_importance": auto, "ids": ids,
+            "immutable_ids": immutable}

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/provenance.py

@@ -0,0 +1,321 @@
+# -*- coding: utf-8 -*-
+"""派生溯源（G8）：新增节点常态化建链 + 悬空可检出。
+
+回答「这个节点**从哪来**」——与 `md_cg.links` 刻意分层：
+  · `links.py`   = 跨节点信任（「我信你多少」，P_trust，落 `~/.mdcg/_links.json`）；
+  · 本模块        = 节点派生关系（「它由谁派生」，落 `<root>/_link.jsonl`）。
+两者都叫「链接」，但一个管**信任状态**、一个管**演进血缘**，不可混用。
+
+存储形态（对齐「md 单一真相源 + 派生索引可重建」）：
+  · 权威声明在节点 frontmatter（`derived_from` / `derived_relation`）；
+  · `<root>/_link.jsonl` 是 **append-only 派生台账**（快查用，可由 frontmatter 重建）；
+  · 建链失败写 `<root>/_link.jsonl.fail`（降级留痕）。
+
+三条纪律（对齐 G8 裁定 §六）：
+  1. **只对新增节点常态化建链，历史不回填**——`rebuild_ledger` 只重放 frontmatter
+     里**已经声明**的关系，不为历史节点发明任何边（当前库历史声明为 0 → 重建为空）；
+  2. **建链失败不得阻断写入**——`record()` 永不抛（best-effort），失败降级为告警 +
+     失败台账留痕，节点写入照常提交；
+  3. **巡检只读**——`check()` 检出悬空边（目标/子节点不在索引内）但**不自动删边**，
+     关系事实去留由人处置。
+
+零第三方依赖。
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+from .fsutil import FileLock, append_jsonl, atomic_write, read_jsonl
+
+LEDGER_NAME = "_link.jsonl"
+FAIL_SUFFIX = ".fail"
+LEDGER_ENV = "MDCG_LINK_FILE"
+SCHEMA = 1
+
+#: 允许的派生关系（显式枚举，避免「自由字符串」把血缘写成噪声）
+RELATIONS = ("derived_from", "split_from", "extracted_from",
+             "merged_from", "refined_from", "source")
+DEFAULT_RELATION = "derived_from"
+
+#: frontmatter 里承载派生声明的字段（写路径只读这两处，不猜）
+FM_FIELD = "derived_from"
+FM_REL_FIELD = "derived_relation"
+
+_LOCK_TIMEOUT = 2.0
+
+
+class ProvenanceError(Exception):
+    """派生溯源错误。写路径侧一律由 `record()` 兜住，不向上抛。"""
+
+
+# --------------------------------------------------------------------------
+# 路径 / 规范化
+# --------------------------------------------------------------------------
+
+def ledger_file(root: str, path: str = None) -> str:
+    """台账路径：显式 → MDCG_LINK_FILE → <root>/_link.jsonl。"""
+    return path or os.environ.get(LEDGER_ENV) or os.path.join(root, LEDGER_NAME)
+
+
+def fail_log_file(root: str, path: str = None) -> str:
+    """降级留痕路径（台账写不进时的「本该建的边」）。"""
+    return ledger_file(root, path) + FAIL_SUFFIX
+
+
+def as_list(value) -> list:
+    """把单值 / 序列统一成去重、去空白的字符串列表。"""
+    if value is None:
+        return []
+    items = list(value) if isinstance(value, (list, tuple, set)) else [value]
+    out = []
+    for x in items:
+        s = str(x).strip()
+        if s and s not in out:
+            out.append(s)
+    return out
+
+
+def normalize_relation(rel, default: str = DEFAULT_RELATION) -> str:
+    """严格校验关系名；非法抛 `ProvenanceError`（显式 API 用）。"""
+    r = str(rel or "").strip().lower()
+    if not r:
+        r = default
+    if r not in RELATIONS:
+        raise ProvenanceError(f"未知派生关系：{rel}（允许：{RELATIONS}）")
+    return r
+
+
+def coerce_relation(rel, default: str = DEFAULT_RELATION) -> str:
+    """宽松兜底：非法关系名回退默认值（**写路径用，保证永不阻断写入**）。"""
+    try:
+        return normalize_relation(rel, default)
+    except ProvenanceError:
+        return default
+
+
+def make_edge(child, parent, *, relation=DEFAULT_RELATION, batch=None,
+              actor="system", note=None, t=None):
+    """构造一条派生边；自环 / 空端点返回 None（**不产生无意义边**）。"""
+    c, p = str(child or "").strip(), str(parent or "").strip()
+    if not c or not p or c == p:
+        return None
+    edge = {"schema": SCHEMA,
+            "t": float(t if t is not None else time.time()),
+            "child": c, "parent": p, "rel": coerce_relation(relation),
+            "batch": batch, "actor": actor}
+    if note:
+        edge["note"] = str(note)[:200]
+    return edge
+
+
+def edges_for(child, parents, **kw) -> list:
+    """`(child, [parents]) → [edge]`：空端点 / 自环自动丢弃。"""
+    out = []
+    for p in as_list(parents):
+        e = make_edge(child, p, **kw)
+        if e:
+            out.append(e)
+    return out
+
+
+# --------------------------------------------------------------------------
+# 写：台账追加（record 为写路径唯一入口，永不抛）
+# --------------------------------------------------------------------------
+
+def append(root: str, edges, *, path: str = None) -> int:
+    """台账追加（加锁串行，防 Windows 并发交错丢边）。IO 失败抛 `ProvenanceError`。"""
+    edges = [e for e in (edges or []) if e]
+    if not edges:
+        return 0
+    p = ledger_file(root, path)
+    try:
+        os.makedirs(os.path.dirname(os.path.abspath(p)) or ".", exist_ok=True)
+        with FileLock(p, timeout=_LOCK_TIMEOUT):
+            for e in edges:
+                append_jsonl(p, e)
+    except OSError as exc:
+        raise ProvenanceError(f"派生台账写入失败：{p}（{exc}）") from exc
+    return len(edges)
+
+
+def _degrade(root: str, path, child, parents, relation, reason,
+             code: str) -> dict:
+    """降级留痕：把「本该建的边」记进 .fail 台账（自身也 best-effort）。"""
+    rec = {"t": time.time(), "code": code, "child": str(child or ""),
+           "parents": as_list(parents), "rel": str(relation or ""),
+           "reason": str(reason)[:300]}
+    try:
+        append_jsonl(fail_log_file(root, path), rec)
+    except Exception:                                  # noqa: BLE001
+        pass
+    return {"ok": False, "added": 0, "edges": [], "degraded": True,
+            "degrade_code": code, "reason": reason}
+
+
+def record(root: str, child, parents, *, relation=DEFAULT_RELATION,
+           batch=None, actor="system", note=None, path: str = None) -> dict:
+    """写路径建链入口：**永不抛**（G8 硬约束：建链失败不得阻断节点写入）。
+
+    返回 `{ok, added, edges, ...}`；失败时 `ok=False` + `degraded=True` 且已写
+    `.fail` 留痕。调用方**不得**因本函数返回 False 而回滚节点。
+    """
+    try:
+        edges = edges_for(child, parents, relation=relation, batch=batch,
+                          actor=actor, note=note)
+    except Exception as exc:                           # noqa: BLE001
+        return _degrade(root, path, child, parents, relation,
+                        f"{type(exc).__name__}: {exc}", "bad_edge")
+    if not edges:
+        return {"ok": True, "added": 0, "edges": [], "reason": "no_parents"}
+    try:
+        n = append(root, edges, path=path)
+    except ProvenanceError as exc:
+        return _degrade(root, path, child, parents, relation, str(exc),
+                        "ledger_io")
+    except Exception as exc:                           # noqa: BLE001
+        return _degrade(root, path, child, parents, relation,
+                        f"{type(exc).__name__}: {exc}", "ledger_io")
+    return {"ok": True, "added": n, "edges": edges,
+            "ledger": ledger_file(root, path)}
+
+
+# --------------------------------------------------------------------------
+# 读：台账 / 索引 / 悬空巡检
+# --------------------------------------------------------------------------
+
+def load(root: str, *, path: str = None) -> list:
+    """读台账（跳过坏行；只取有端点的记录）。"""
+    out = []
+    for r in read_jsonl(ledger_file(root, path)):
+        if isinstance(r, dict) and r.get("child") and r.get("parent"):
+            out.append(r)
+    return out
+
+
+def _dedupe(rows):
+    out, seen = [], set()
+    for r in rows:
+        key = (r.get("child"), r.get("parent"), r.get("rel"))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(r)
+    return out
+
+
+def edges(root: str, *, child=None, parent=None, relation=None, batch=None,
+          limit: int = None, path: str = None) -> list:
+    """按端点 / 关系 / 批次过滤台账边（只读，去重，保持写入顺序）。"""
+    out = []
+    for r in load(root, path=path):
+        if child and r.get("child") != child:
+            continue
+        if parent and r.get("parent") != parent:
+            continue
+        if relation and r.get("rel") != relation:
+            continue
+        if batch and r.get("batch") != batch:
+            continue
+        out.append(r)
+    out = _dedupe(out)
+    return out[:int(limit)] if limit else out
+
+
+def index_edges(cg, *, prefix: str = None) -> list:
+    """从**索引快照**恢复派生边（零读文件）——台账丢失/未重建时的只读兜底。"""
+    nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
+    out = []
+    for nid, e in nodes.items():
+        if prefix and not str(nid).startswith(prefix):
+            continue
+        rel = coerce_relation((e or {}).get(FM_REL_FIELD))
+        for p in as_list((e or {}).get(FM_FIELD)):
+            out.append({"schema": SCHEMA, "child": nid, "parent": p, "rel": rel,
+                        "batch": (e or {}).get("derived_batch"), "actor": None,
+                        "origin": "index"})
+    return _dedupe(out)
+
+
+def all_edges(cg, *, path: str = None) -> list:
+    """台账 ∪ 索引声明（台账优先，按边去重）。"""
+    return _dedupe(load(cg.root, path=path) + index_edges(cg))
+
+
+def check(cg, *, path: str = None, limit: int = 20,
+          include_index: bool = True) -> dict:
+    """只读巡检：检出**悬空派生边**（端点不在索引内）。**不删边、不写盘**。
+
+    `ok=False` 仅表示「有悬空」，不代表巡检失败；`checked=True` 恒成立。
+    """
+    known = set((getattr(cg, "index", None) or {}).get("nodes") or {})
+    rows = all_edges(cg, path=path) if include_index else load(cg.root, path=path)
+    dangling = []
+    for e in rows:
+        missing = []
+        if e.get("child") not in known:
+            missing.append("child")
+        if e.get("parent") not in known:
+            missing.append("parent")
+        if missing:
+            dangling.append({"child": e.get("child"), "parent": e.get("parent"),
+                             "rel": e.get("rel"), "missing": missing,
+                             "batch": e.get("batch"), "t": e.get("t"),
+                             "origin": e.get("origin") or "ledger"})
+    dangling.sort(key=lambda r: (r.get("child") or "", r.get("parent") or ""))
+    ledger = ledger_file(cg.root, path)
+    return {"ok": not dangling, "checked": True, "root": cg.root,
+            "ledger": ledger, "ledger_exists": os.path.exists(ledger),
+            "edges": len(rows), "nodes": len(known),
+            "dangling": dangling[:int(limit)], "dangling_count": len(dangling),
+            "readonly": True,
+            "note": "只读巡检：悬空边仅检出并报告，不自动删除（关系事实由人处置）"}
+
+
+def rebuild_ledger(cg, *, apply: bool = False, path: str = None) -> dict:
+    """按 frontmatter 重建台账——**只重放已声明的边，不发明任何边**。
+
+    历史节点未声明派生关系 → 重建结果为空，正合「历史不回填」。
+    默认 dry_run（只出报表）。
+    """
+    es = index_edges(cg)
+    if not apply:
+        return {"ok": True, "dry_run": True, "edges": len(es),
+                "written": 0, "sample": es[:5],
+                "note": "预演：未写盘；只重放 frontmatter 已声明的关系"}
+    body = "".join(json.dumps(e, ensure_ascii=False, separators=(",", ":")) + "\n"
+                   for e in es)
+    p = ledger_file(cg.root, path)
+    atomic_write(p, body)
+    return {"ok": True, "dry_run": False, "edges": len(es),
+            "written": len(es), "ledger": p}
+
+
+def summary(cg, *, path: str = None) -> dict:
+    """轻量摘要（只读；失败不抛，避免拖垮 health_os / 常驻循环）。"""
+    try:
+        rep = check(cg, path=path, limit=3)
+        return {"edges": rep["edges"], "dangling": rep["dangling_count"],
+                "ledger": rep["ledger"], "exists": rep["ledger_exists"],
+                "sample": [f"{r['child']}->{r['parent']}"
+                           for r in rep["dangling"]]}
+    except Exception:                                  # noqa: BLE001
+        return {}
+
+
+def catalog(root: str = None) -> dict:
+    """自描述（供 MCP catalog / 人工核对）。"""
+    return {
+        "layer": "派生溯源（G8）",
+        "question": "这个节点从哪来（演进血缘）",
+        "ledger": ledger_file(root) if root else LEDGER_NAME,
+        "schema": SCHEMA,
+        "relations": list(RELATIONS),
+        "default_relation": DEFAULT_RELATION,
+        "fm_fields": [FM_FIELD, FM_REL_FIELD],
+        "discipline": {"incremental_only": True, "no_backfill": True,
+                       "never_block_write": True, "patrol_readonly": True},
+        "distinct_from": ("links.py = 跨节点信任 P_trust（_links.json）；"
+                          "本层 = 节点派生关系（_link.jsonl）"),
+    }