@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/lexicon/expand_en_zh.py

@@ -42,6 +42,7 @@ NORMALIZER = os.path.join(HERE, "md_cg", "semantic", "en_normalizer.py")
 AUTO_BEGIN, AUTO_END = "<<EN_ZH_AUTO>>", "<<END_EN_ZH_AUTO>>"
 
 
+# 生效条件：无需入参；逐行读取模块常量 QUESTIONS 指向的内容，仅在 line.strip() 为真的行上 json.loads 该行并追加到 qs，最终返回 qs（全为空白行时返回空列表）。
 def load_questions():
     qs = []
     with io.open(QUESTIONS, encoding="utf-8") as f:
@@ -51,6 +52,7 @@ def load_questions():
     return qs
 
 
+# 生效条件：入参 min_len 给定；逐条 lexicon 记录的 en_raw（假值时回落 en，两者皆假值则取空串）转小写、下划线转空格并剥离 to/a/an 前缀后，不在 STOPWORDS 且能 fullmatch [a-z]+ 者计入 wordlike 并仅当长度 ≥ min_len 时并入 en→zh 集合（< min_len 计 too_short 后排除，STOPWORDS 计 stopword 后排除），最终单一 zh 的入 cand、多 zh 的入 conflicts，返回 (cand, conflicts, stat)。
 def reverse_map(min_len):
     """char_atoms_clean → (候选 {en: zh}, 冲突 {en: [zh...]}, 统计 dict)"""
     with io.open(CHAR_ATOMS, encoding="utf-8") as f:
@@ -84,6 +86,7 @@ def reverse_map(min_len):
     return cand, conflicts, stat
 
 
+# 生效条件：required 为空（无入参）；对 QUESTIONS 经 load_questions 读入的题面按 normalize_en_query 的 detail 统计 unknown_keep/proper_noun_keep 词次后，对 min_len=2、3、4 各调一次 reverse_map 打印统计，再对 min_len=3 二次调 reverse_map 取 cand 算命中词次、打印 top15 一对多冲突、并以 extra_map=cand 复跑 normalize_en_query 统计扩表后英文保留词次，全程只打印、返回 None。
 def analyze():
     """扩表收益上界：500 题 OOV 词频 × 反查覆盖率（词次口径）。"""
     qs = load_questions()
@@ -135,6 +138,7 @@ def analyze():
           % (n_kept, n_after))
 
 
+# 生效条件：入参 min_len 给定；cand 取 reverse_map(min_len) 中键不在 EN_ZH 的部分，若 NORMALIZER 中匹配到 AUTO_BEGIN…AUTO_END 标记段则整段替换，否则要求锚点行存在（缺失即断言失败不写回）后插入，compile 校验通过则写回 NORMALIZER 并返回 0（conf 仅用于打印）。
 def build(min_len):
     """反查扩表 → 字面量写回 en_normalizer.py（幂等标记块，重跑即刷新）。"""
     cand, conf, stat = reverse_map(min_len)
@@ -169,6 +173,7 @@ def build(min_len):
     return 0
 
 
+# 生效条件：无入参；在模块常量 NORMALIZER 中匹配不到「# ---- 机械扩表 … AUTO_END」段时打印零改动并返回 0，匹配到时删除该段、compile 校验通过后写回并返回 0。
 def clean():
     """删除 en_normalizer.py 中的机械扩表段（幂等；段不存在则零改动）。"""
     with io.open(NORMALIZER, encoding="utf-8") as f:
@@ -185,6 +190,7 @@ def clean():
     return 0
 
 
+# 生效条件：无入参；按 sys.argv[1] 分派（长度不超 1 时回落为 "analyze"）——"analyze" 调 analyze() 返回 0；"build" 时 ml 初值 3，若 sys.argv 含 "--min-len" 则取其下一个元素 int() 后覆盖 ml，返回 build(ml)；"clean" 返回 clean()；其余取值（含空串等未知模式）打印 __doc__ 并返回 2。
 def main():
     mode = sys.argv[1] if len(sys.argv) > 1 else "analyze"
     if mode == "analyze":

package/md_cg/lifecycle.py

@@ -0,0 +1,273 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 节点显式生命周期状态机（可学习优点 ②·显式状态机）
+
+出处（pi）：
+    运行操作 = 13 个**叶子显式状态机**（`session/types.ts:315-329`），drive 循环按
+    `at` 分发；一轮无任何进展即抛 `SessionInvariantError`（`drive.ts:101-104`）
+    ——非法迁移在**结构上不可能**，而不是靠调用方自觉。
+
+灵枢现状（本模块要收口的四处散落状态）：
+    · `writelimit._demote`  用 **tag** `tidy:converged` 记「同构聚合已定型」
+    · `forgetting.reinforce` 用 **importance** 升降记「强化 / 弱化」
+    · `protect`             用 **fm.protected** 记「不可遗忘」
+    · `_evolution/ledger.md` 记账本
+    四种载体各说各话：谁都能把已定型节点再降一次权、把归档节点悄悄覆写成新的，
+    而**没有任何地方校验「这一步迁移合不合法」**。
+
+本模块是该问题的唯一真源：状态集 `STATES` + 合法迁移表 `TRANSITIONS` + 单点裁决
+`check()` + 单点推进 `set_state()`。口径：
+
+  · 状态落 **frontmatter.lifecycle_state**（节点 md 是唯一真源）；索引快照带同名字
+    段 →「免读文件可查」（`_index.json` 即可回答「这节点什么状态」）。
+    **为何不叫 `state`**（对交接文档建议集的偏离，取证理由）：`state` 在 md_cg 内
+    已被**裁决四态**（ACCEPT/REJECT/DEFER/BLINDSPOT）占用——`audit._verdict` 的返
+    回体、`judge_qualification()` 的返回、`mdcos.search` 结果项、检索结果条目的
+    `entry["state"]` 全都用它。若生命周期也叫 `state`，则同一外层结构里
+    `entry["state"]`（裁决）与 `entry["frontmatter"]["state"]`（生命周期）并存，
+    人类与 agent 读面必生歧义；本仓既有 `self_state` 即为同一动机的先例。
+    故取 `lifecycle_state`：语义自明、零歧义。
+  · 存量节点**缺 state 即视为 active**（`state_of` 的缺省），故不回填也能工作；
+    `backfill()` 提供一次性回填（幂等、可 dry-run）。
+  · **受保护节点豁免降级**：`protected`/`immutable` 节点不接受降级迁移，需
+    `override=True` 显式放行——「保护 = 不可遗忘」在状态层的落点。
+  · 非法迁移**拒绝**（负路由）：`check()` 返回 `(ok, code, reason)`，`set_state()`
+    返回 `ok=False` + 机器可读 `error` 而不抛；写路径要硬拒用 `require_transition()`。
+  · 永不删除：`archived` 只是状态，节点文件仍在（可逆、可审计）。
+  · 幂等：同状态迁移是 no-op（不写盘、不留痕）——重复发起不会把历史刷爆。
+
+状态语义（建议集，逐级降级 / 逐级回升）：
+    active    正常：参与检索与写入面
+    converged 已定型：同构聚合的成员（writelimit tidy 的落点）
+    demoted   已降权：importance 被下调（forgetting 弱化的落点）
+    archived  已归档：不再参与默认检索，但文件保留、可显式恢复
+"""
+from __future__ import annotations
+
+import os
+import time
+
+from .fsutil import append_jsonl
+
+#: 状态全集。顺序即「降级方向」：active → converged → demoted → archived。
+STATES = ("active", "converged", "demoted", "archived")
+#: frontmatter 字段名（索引快照同名透出）。刻意避开 `state`——见模块 docstring
+#: 「为何不叫 state」：该名已被裁决四态占用，同名会让读面产生歧义。
+STATE_FIELD = "lifecycle_state"
+#: 迁移留痕字段（frontmatter 侧历史，滚动保留最近 HISTORY_KEEP 条）
+HISTORY_FIELD = "state_history"
+HISTORY_KEEP = 20
+#: 状态迁移审计（append-only，与 _forgetting.jsonl / _maintain.jsonl 同风格）
+AUDIT_FILE = "_lifecycle.jsonl"
+
+#: 降级序位（用于「受保护豁免降级」的判定）
+_RANK = {"active": 0, "converged": 1, "demoted": 2, "archived": 3}
+
+#: 合法迁移表——**逐级降级、逐级回升**，不跳级：
+#:   active   ⇄ converged        定型 / 定型撤销
+#:   active    → demoted         直接弱化（forgetting 降权）
+#:   converged → demoted        定型后再弱化
+#:   demoted  ⇄ active           被强化回升 / 再弱化
+#:   demoted   → archived        归档
+#:   archived  → active          显式恢复
+#: 刻意不收录的（即拒绝的）：active→archived（跳级归档）、archived→converged /
+#: archived→demoted（跳级回落）、converged→archived（跳级归档）。
+TRANSITIONS = frozenset({
+    ("active", "converged"),
+    ("active", "demoted"),
+    ("converged", "active"),
+    ("converged", "demoted"),
+    ("demoted", "active"),
+    ("demoted", "archived"),
+    ("archived", "active"),
+})
+
+
+# 生效条件：以 src、dst、code、reason 四个实参构造时，父类 ValueError 消息由 f-string 拼成「非法状态迁移 src→dst（code）：reason」，并把四个值分别存为同名属性。
+class TransitionError(ValueError):
+    """非法生命周期迁移（写路径用 `require_transition` 直接抛这个）。"""
+
+# 生效条件：接收 src、dst、code、reason 四个实参，调用 super().__init__ 传入 f"非法状态迁移 {src}→{dst}（{code}）：{reason}"，并将四者依次赋给 self.src、self.dst、self.code、self.reason。
+    def __init__(self, src, dst, code, reason):
+        super().__init__(f"非法状态迁移 {src}→{dst}（{code}）：{reason}")
+        self.src, self.dst, self.code, self.reason = src, dst, code, reason
+
+
+# ---------------------------------------------------------------- 纯函数裁决
+
+# 生效条件：fm 非 dict 直接返回 "active"；fm 为 dict 时取 fm.get(STATE_FIELD)，该值属于 STATES 则原样返回，缺键或值不在 STATES 均返回 "active"。
+def state_of(fm) -> str:
+    """frontmatter → 状态；缺字段或未知值 → "active"（存量兼容，不猜测）。"""
+    if not isinstance(fm, dict):
+        return "active"
+    s = fm.get(STATE_FIELD)
+    return s if s in STATES else "active"
+
+
+# 生效条件：按 _RANK.get(dst, 0) > _RANK.get(src, 0) 判定，src 或 dst 不在 _RANK 键中时该侧按 0 参与比较。
+def is_downgrade(src: str, dst: str) -> bool:
+    """是否向「更低」的状态迁移（active < converged < demoted < archived）。"""
+    return _RANK.get(dst, 0) > _RANK.get(src, 0)
+
+
+# 生效条件：src 不在 STATES 时先替换为 "active"；dst 不在 STATES 返回 False；替换后 src == dst 返回 True；否则返回 (src, dst) in TRANSITIONS 的布尔值。
+def can_transition(src, dst) -> bool:
+    """迁移是否合法（含幂等；未知 src 按 active 处理）。"""
+    src = src if src in STATES else "active"
+    if dst not in STATES:
+        return False
+    if src == dst:
+        return True                     # 幂等：同状态是 no-op
+    return (src, dst) in TRANSITIONS
+
+
+# 生效条件：src 不在 STATES 时替换为 "active"；dst 不在 STATES 返回 (False, 'unknown_state', ...)；src == dst 返回 (True, 'noop', ...)；(src, dst) 不在 TRANSITIONS 返回 (False, 'illegal_transition', ...)；is_downgrade(src, dst) 且 protected 为真且 override 为假时返回 (False, 'protected', ...)；其余返回 (True, 'ok', f'{src}→{dst} 合法')。
+def check(src, dst, protected: bool = False, override: bool = False):
+    """迁移合法性裁决 → `(ok, code, reason)`。**唯一裁决点**（纯函数，无 IO）。
+
+    code 取值：`ok` / `noop`（同状态，不写盘）/ `unknown_state` /
+    `illegal_transition` / `protected`。
+    """
+    src = src if src in STATES else "active"
+    if dst not in STATES:
+        return False, "unknown_state", f"未知状态 {dst!r}（允许：{STATES}）"
+    if src == dst:
+        return True, "noop", "状态未变（幂等，不写盘）"
+    if (src, dst) not in TRANSITIONS:
+        legal = "、".join(f"{a}→{b}" for a, b in sorted(TRANSITIONS))
+        return False, "illegal_transition", (
+            f"{src}→{dst} 不在合法迁移表内（允许：{legal}）——"
+            "降级与回升都须逐级，跨级迁移一律拒绝")
+    if is_downgrade(src, dst) and protected and not override:
+        return False, "protected", (
+            f"受保护节点不接受降级迁移 {src}→{dst}（保护 = 不可遗忘）；"
+            "确需降级请显式 override=True")
+    return True, "ok", f"{src}→{dst} 合法"
+
+
+# 生效条件：以 src、dst、protected、override 调 check 后，ok 为真时返回其 code，ok 为假时抛 TransitionError，抛出时 src 参数在 STATES 中则原样、否则替换为 "active"，dst、code、why 按源码透传。
+def require_transition(src, dst, protected: bool = False, override: bool = False):
+    """合法则返回 code，非法则抛 `TransitionError`（写路径的硬拒入口）。"""
+    ok, code, why = check(src, dst, protected=protected, override=override)
+    if not ok:
+        raise TransitionError(src if src in STATES else "active", dst, code, why)
+    return code
+
+
+# 生效条件：src 取 state_of(fm)，prot 取 bool(fm.get("protected") or fm.get("immutable"))；check 返回 ok 假或 code == "noop" 时原样返回 (ok, code, why) 且不改 fm；否则把 dst 写入 fm[STATE_FIELD]，并把含 at/from/to/reason/actor 的新条目追加到由 fm.get(HISTORY_FIELD) or [] 复制的列表、截取末 HISTORY_KEEP 条写回 fm[HISTORY_FIELD]，返回 (True, code, why)。
+def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
+          override: bool = False):
+    """在给定 frontmatter 上**就地**推进状态（无 IO）→ `(ok, code, why)`。
+
+    与 `set_state()` 共用同一裁决点（`check`），供**需与其他字段同批落盘**的收
+    口点使用——`writelimit` 的降权要一次写盘改 tags/importance/状态，`forgetting`
+    的强化同理；否则状态得单独再写一次盘（同一节点两倍 IO）。
+    合法且非幂等时写入 `STATE_FIELD` 并追加 `HISTORY_FIELD`；失败/幂等不动 fm。
+    """
+    src = state_of(fm)
+    prot = bool(fm.get("protected") or fm.get("immutable"))
+    ok, code, why = check(src, dst, protected=prot, override=override)
+    if not ok or code == "noop":
+        return ok, code, why
+    fm[STATE_FIELD] = dst
+    hist = list(fm.get(HISTORY_FIELD) or [])
+    hist.append({"at": time.time(), "from": src, "to": dst,
+                 "reason": reason, "actor": actor})
+    fm[HISTORY_FIELD] = hist[-HISTORY_KEEP:]
+    return True, code, why
+
+
+# ---------------------------------------------------------------- 索引同步
+
+# 生效条件：cg.index 非 dict 时静默 return；index 的 "nodes" 中查不到 node_id 时 return；否则把 fm.get(STATE_FIELD)（缺键即 None）写入该条目，cg._dirty 为 dict 时记入该条目并调用可调用的 cg.flush。
+def _sync_index(cg, node_id, fm) -> None:
+    """把 state 同步进索引快照（免读文件可查）；无索引实现时静默跳过。
+
+    只同步 `state` 一个键：迁移历史已在 frontmatter 与 `_lifecycle.jsonl` 留痕，
+    放进索引会让快照无谓膨胀。
+    """
+    idx = getattr(cg, "index", None)
+    if not isinstance(idx, dict):
+        return
+    e = (idx.get("nodes") or {}).get(node_id)
+    if e is None:
+        return
+    e[STATE_FIELD] = fm.get(STATE_FIELD)
+    dirty = getattr(cg, "_dirty", None)
+    if isinstance(dirty, dict):
+        dirty[node_id] = e
+    flush = getattr(cg, "flush", None)
+    if callable(flush):
+        flush()
+
+
+# ---------------------------------------------------------------- 推进 / 回填
+
+# 生效条件：cg.get(node_id) 为假值返回 {'ok': False, 'error': 'node_not_found', ...}；否则以 state_of(fm) 作 src 调 stamp——stamp 不 ok 返回 ok=False + error=code，code == "noop" 返回 ok=True + changed=False；其余情况取 fm[HISTORY_FIELD][-1]["at"] 后写盘、_sync_index 并追加审计 JSONL（append_jsonl 抛异常被吞掉），返回 ok=True + changed=True。
+def set_state(cg, node_id: str, dst: str, reason: str = None,
+              actor: str = None, override: bool = False) -> dict:
+    """推进一个节点的生命周期状态（**唯一推进入口**）。
+
+    非法迁移不走异常而是返回 `{"ok": False, "error": <code>, ...}`（负路由：
+    调用方自行决定降级处理；要硬拒请用 `require_transition`）。幂等迁移返回
+    `changed=False` 且不写盘。返回体始终带 `from` / `to` / `code` 便于审计。
+    """
+    node = cg.get(node_id)
+    if not node:
+        return {"ok": False, "error": "node_not_found", "node_id": node_id}
+    fm = dict(node.get("frontmatter") or {})
+    src = state_of(fm)
+    ok, code, why = stamp(fm, dst, reason=reason, actor=actor, override=override)
+    base = {"node_id": node_id, "from": src, "to": dst, "code": code}
+    if not ok:
+        return {**base, "ok": False, "error": code, "reason": why}
+    if code == "noop":
+        return {**base, "ok": True, "changed": False, "reason": why}
+    at = fm[HISTORY_FIELD][-1]["at"]
+    cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
+                   node.get("content") or "")
+    _sync_index(cg, node_id, fm)
+    try:
+        append_jsonl(os.path.join(cg.root, AUDIT_FILE), {
+            "t": at, "action": "set_state", "node_id": node_id,
+            "from": src, "to": dst, "reason": reason, "actor": actor,
+            "override": bool(override)})
+    except Exception:                    # 审计失败不阻断状态推进
+        pass
+    return {**base, "ok": True, "changed": True, "reason": why, "at": at}
+
+
+# 生效条件：nodes 取 (cg.index or {}).get("nodes") or {}，遍历中缺 STATE_FIELD 或该值不在 STATES 的 nid 计入 missing（累计数达 limit 即 break，limit <= 0 时立即 break 使 missing 为空），apply 假值只返回 dry_run=True 的盘点结果，apply 为真时对每个 missing 中 cg.get 取不到的记入 failed、取到的把 state_of(fm) 显式写回 fm[STATE_FIELD] 并写盘与 _sync_index 后记入 done，返回 dry_run=False 的结果。
+def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
+    """存量回填：把缺 `state` 的节点显式补成 `active`（幂等）。
+
+    缺字段本就按 active 解释（`state_of`），故回填**不是让功能工作的前提**，
+    而是把「缺省」变成「显式」——索引/审计里从此可直接读到状态。
+    `apply=False`（默认）只盘点。写不动（文件取不回）的节点进 `failed` 如实上报。
+    """
+    nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
+    missing = []
+    for nid, e in list(nodes.items()):
+        if len(missing) >= limit:
+            break
+        if (e or {}).get(STATE_FIELD) in STATES:
+            continue
+        missing.append(nid)
+    missing.sort()
+    if not apply:
+        return {"ok": True, "dry_run": True, "scanned": len(nodes),
+                "missing": len(missing), "planned": missing[:50]}
+    done, failed = [], []
+    for nid in missing:
+        node = cg.get(nid)
+        if not node:
+            failed.append(nid)
+            continue
+        fm = dict(node.get("frontmatter") or {})
+        fm[STATE_FIELD] = state_of(fm)   # 缺省 active → 显式落盘
+        cg._write_node(nid, os.path.join(cg.root, node["path"]), fm,
+                       node.get("content") or "")
+        _sync_index(cg, nid, fm)
+        done.append(nid)
+    return {"ok": True, "dry_run": False, "scanned": len(nodes),
+            "missing": len(missing), "backfilled": len(done),
+            "planned": done[:50], "failed": failed[:20]}

package/md_cg/linkref.py

@@ -0,0 +1,281 @@
+# -*- coding: utf-8 -*-
+"""正文裸 id 引用 → reference 边（写入侧低摩擦建链，R-L1b，2026-09-17）。
+
+【为什么不是 `[[双链]]` 语法】（第 4 条取证——全库普查，非相似度判断）
+zcode 报告《Obsidian 是什么》建议照搬 Obsidian 的 `[[node_id|显示名]]` 语法。
+全库 11,883 节点实测：正文含 `[[...]]` 的仅 **8 节点 / 45 次**，且逐条核对
+**全部是误匹配**——`[[tool.uv.index]]`（TOML 数组表）、
+`[[ "opencode-deja", {...} ]]`（JSON/JS 嵌套数组）、代码块数组。
+**真实双链用例 = 0**；即 `[[...]]` 不是本库写侧的自然语法，且与正文里
+已大量存在的 TOML/JSON 语法**物理冲突**：照搬将产出 0 条真边 + N 条垃圾边。
+（判定单：R-L1a = REJECT，依据=条件证据「正文会自然写 [[..]]」不成立。）
+
+而**真实存在的自然写法是裸 id**：全库 64 节点 / 169 处正文引用了其他节点 id，
+其中 62 节点「已引用但 edges 为空」——本模块即以此为靶区，零语法成本。
+
+【落点选择】（第 4 条取证）
+`cg.add` 是**全量重建 fm**（mdcg.py `"edges": list(edges or [])`），故经
+`a["edges"]` 注入会在**覆写既有节点时清空其原有边**（破坏性副作用）。
+本模块因此只「解析」不「注入」；落盘由 after 钩子经 `append_edge`——边域
+窄原语、按 (target, relation_type) 幂等、不动正文与本体字段——完成。
+
+【边类型语义】
+`reference` 与 `similar`/`causal` 都不同：正文提及 ≠ 语义相似 ≠ 因果依赖。
+故在 `chain.EDGE_WEIGHTS` 单列一类、取弱权重 0.50；且**不入**
+`CHAIN_TYPES_DEFAULT`（因果链遍历仍只走 causal/sequential/applies_to），
+避免正文提及污染「前提→结论」条件序列。
+
+【判据：通用形态 + 库内存在（双保险），不设前缀白名单】
+初版用 8 前缀白名单（node/mem/concept/imgpart/doc/code/ev/gap）。
+**2026-09-17 全库普查证伪**：真实库 11,883 个索引键的前缀域有 **48 个**——
+doc 3788 / kp 2962 / code 2878 / node 1360 / mem 435 / rev 153 / note 135 /
+imgpart 60 / vpipe 32 / arc / unr / swarm / bench6 / self / rej / anchor /
+work / whitebox / arch / goal / …（另 40 个前缀）。白名单会**漏掉 kp_* 等
+40 个前缀的全部引用**（判据面远小于真源面）。
+故改为**通用形态**：`字母前缀_字母数字段`（段长 ≥3），
+并以「**必须存在于库内已知 id 集合**」二次拦截——误匹配由第二道滤网兜住，
+两道判据都不成立时不建边。形态边界按 **ASCII 字母数字下划线**判定
+（不用 `\b`：其中文词义会让「id 紧邻汉字」整条漏抽，见 `ID_RE` 注释）。
+
+【纪律】G8 常态化建链第 2 条：**建链失败不阻断写入**——after 钩子全兜异常。
+
+【不适用条件】（负路由，实测边界）
+- `gated=true`（主动遗忘闸）路径：该闸是**替代执行路径**，自己落盘并短路，
+  `writepipe.execute` 在短路时直接 return（不跑 after 链）→ 该路径落盘的
+  节点**不**自动建 reference 边。与 G8 `derived_from` 在 gated 路径下仍生效
+  （`_gate_gated` 显式透传 derived_from）**不同**，属已知非对称边界。
+- 引用**尚未入库**的 id：`extract_refs` 以库内已知 id 为白名单，未知 id
+  不建边（否则产生「指向不存在节点」的幽灵边，检索侧 `_path_graph` 会追空）。
+- **当前身份不可读的目标节点**：白名单口径与库读面一致（`_readable`，见
+  `known_ids`）——「不可见即不存在」，读隔离区（`private`/`secret`）的节点
+  不被建边。故链接面是**身份相关**的：同一段正文，高 clearance 身份建出的
+  边多于低 clearance 身份。这是读隔离的正确投影（且避免把高密级节点 id
+  的存在性经 `fm.edges` 泄漏给低 clearance 读者），不是缺陷。
+  读隔离有**两个面**、判据必须叠加（20260917 取证补第二面）：①**密级面** =
+  `known_ids` 经 `_readable` 看索引里的 `sensitivity` 字段（纯内存）；②**密钥面** =
+  `live_targets` 经 `get` 实读——`private`/`secret` 正文是密文，解封需
+  **(tenant, actor) 信封里的 DEK**，无 DEK 时 `_open_content` 返回 None。
+  只有①时白名单会混入「密级够、密钥不够」的死目标（真实库实测 459 条：
+  rev/note/node/imgpart/vpipe/kp/self 七前缀，secret clearance 下候选清单
+  因此含 15 个死目标 / 16 条悬空候选）。两面叠加后建边才与 `get` 同口径。
+- **源节点在审计留痕层（`layer="self"`）**：该层是灵枢自身运行留痕——
+  `rev_<pid尾>_r<N>` 裁决记录节点由 `mdcos._write_review_record` 落盘，
+  正文是**模板机械拼装**、必然含被裁决对象的 id。这是「记录指向记录对象」，
+  不是记忆之间的语义引用；且每次裁决都会新生一个该层节点，逐条建边会让
+  弱边随裁决次数线性增长、稀释检索面。
+  判据取**层语义**（`SOURCE_EXCLUDE_LAYERS`）而非 id 前缀 `rev_`——与
+  `mdcos.review_records()` 的 self 层口径一致，且不依赖命名约定。
+  （20260917 取证：回填后仍残留 gap 的节点实测正是 `rev_*`。）
+- **不合形态的脏键不作源、也不被识别为目标**：真实库索引里存在 11 个脏键
+  （`None`——历史 `add` 未传 node_id 被字符串化落盘，磁盘上确有
+  `knowledge/orphan/None.md`；3 个中文标题式键；`kp_GIL全局解_*` 等 6 个
+  含中文的混合 id）。判据不因脏数据松弛：含中文/无下划线的键一律不建边。
+  脏数据**源头**（`add` 的 node_id 未规范化）属另一问题，另案处理。
+- 身份/授权：本模块不做权限判断——`append_edge` 经 `MdCGSecure` 库层照常
+  受 `require_layer_write` 约束（拦截器改不了「谁能写」）。
+"""
+from __future__ import annotations
+
+import re
+import time
+
+__all__ = ["RELATION", "ID_SHAPE", "ID_RE", "ID_SHAPE_RE", "SOURCE_EXCLUDE_LAYERS",
+           "known_ids", "live_targets", "is_linkable_id", "is_linkable_source",
+           "extract_refs", "make_edge", "before_hook", "after_hook"]
+
+# 节点 id **通用形态**（不设前缀白名单，见模块 docstring 的普查依据）：
+#   字母前缀 + `_` + 字母数字段（段长 ≥3）。
+# 实例：mem_1789125080573 / concept_d8eee20f2f / doc_b56c18dbf164 /
+#       kp_GIL_1787752832598 / node_meta_427035320_1787018623216 / rev_xxx_r1
+# 边界用 **ASCII 字母数字下划线 lookaround**（不可用 `\b`）：Python `re` 的
+# `\b` 按 Unicode 词义判定、中文属词字符，故 `见 mem_xxx的说明` 这类
+# 「id 紧邻汉字」的常见写法会被 `\b` 判为无边界而**整体漏抽**（假阴性）。
+ID_SHAPE = r"[A-Za-z][A-Za-z0-9]*_[0-9A-Za-z][0-9A-Za-z_]{2,}"
+ID_RE = re.compile(r"(?<![0-9A-Za-z_])(" + ID_SHAPE + r")(?![0-9A-Za-z_])")
+ID_SHAPE_RE = re.compile(r"^" + ID_SHAPE + r"$")
+
+# 源节点排除层：self 层是灵枢**自身运行留痕**（`rev_*` 裁决记录节点，
+# 见 `mdcos._write_review_record`），其正文引用是模板机械拼装的
+# 「记录→记录对象」，不构成记忆之间的语义引用。取层语义而非 id 前缀。
+SOURCE_EXCLUDE_LAYERS = ("self",)
+
+RELATION = "reference"
+# 解释：正文提及是**确定性文本事实**（不是推断），故 confidence=1.0；
+# 弱语义由类型 base 承担（chain.EDGE_WEIGHTS["reference"] = 0.50）。
+# 有效传播权重 = base × confidence = 0.50 × 1.0。
+EDGE_CONFIDENCE = 1.0
+VERIFIED = False          # 未经人工/证据验证——白箱诚实标记
+
+
+# 生效条件：cg.index 的 "nodes" 取到条目且 cg._readable 可调用时，仅把 guard(条目) 为真的 id 纳入白名单（判定抛异常即跳过该条）；_readable 不可调用时直接返回 nodes 的全部键；cg.index 取值抛异常或 "nodes" 为假值回落空 dict 时返回空集。
+def known_ids(cg):
+    """库内**对当前身份可读**的节点 id 集合（白名单；读隔离一致性）。
+
+    与 `md_cg/backfill.py::_readable_guard` 同口径：`MdCGSecure` 的读面
+    （`get` / `_candidates` / `search_rrf`）一律「不可见即不存在」，链接面
+    必须一致——否则会对当前身份不可读的节点建边，产出检索侧追空的悬空边。
+    （20260917 取证：真实库 11885 键里 clearance=internal 仅 7212 可读、
+    须 secret 才全读；候选目标 94 个中 21 个落在读隔离区。）
+
+    判定为**纯内存**（索引条目带 sensitivity；缺该字段时 `_readable` 会按
+    盘上真相回填并缓存，仅首次有盘读）。异常一律 fail-closed 回退空集。
+
+    注意这是**密级面**过滤：「密级可读 ≠ 实读可得」（加密节点还需本身份的
+    DEK）。密钥面由 `live_targets` 补——两者叠加才是完整的「不可见即不存在」。
+    """
+    try:
+        nodes = cg.index.get("nodes") or {}
+    except Exception:                                  # noqa: BLE001
+        return set()
+    guard = getattr(cg, "_readable", None)
+    if not callable(guard):
+        return set(nodes)               # 非安全库（MdCG）无读隔离概念
+    out = set()
+    for nid, e in nodes.items():
+        try:
+            if guard(e):
+                out.add(nid)
+        except Exception:                              # noqa: BLE001
+            continue                    # fail-closed：判不了即不纳入白名单
+    return out
+
+
+# 生效条件：逐 tid∈ids，cache 非 None 且 tid 已在 cache 时用 cache[tid] 作判据，否则以 bool(cg.get(tid)) 为判据（cg.get 抛异常记 False）并在 cache 非 None 时回写 cache[tid]；判据为真才把 tid 追加进 out。
+def live_targets(cg, ids, cache=None):
+    """从 ids 中筛出**当前身份实读可得**的目标（读隔离的第二道：密钥面）。
+
+    为什么不能只靠 `known_ids`：它经 `_readable` 只看索引里的密级字段，而
+    `private`/`secret` 节点**正文是密文**，解封需 (tenant, actor) 信封里的
+    DEK；无 DEK 时 `get` 经 `_open_content` 返回 None（并落 `read_locked` 审计）。
+    （20260917 取证：真实库 11885 键里 459 条正是此类——文件在、frontmatter
+    明文、正文密文、扫描身份无 DEK；`secret` clearance 下混入白名单，使候选
+    清单产出 15 条指向死目标的悬空边。）
+
+    cache —— 可选 dict，批量场景复用判定（同一 id 多次出现只读一次盘）。
+    异常一律 fail-closed（判不了即不建边，与 `known_ids` 同纪律）。
+    """
+    out = []
+    for tid in ids:
+        if cache is not None and tid in cache:
+            ok = cache[tid]
+        else:
+            try:
+                ok = bool(cg.get(tid))
+            except Exception:                              # noqa: BLE001
+                ok = False
+            if cache is not None:
+                cache[tid] = ok
+        if ok:
+            out.append(tid)
+    return out
+
+
+# 生效条件：nid 是 str 且 ID_SHAPE_RE.match(nid) 命中时返回 True，否则返回 False。
+def is_linkable_id(nid):
+    """id 形态是否可作链接面端点（排除 `None`/中文标题键/含中文混合 id 等脏键）。"""
+    return bool(isinstance(nid, str) and ID_SHAPE_RE.match(nid))
+
+
+# 生效条件：is_linkable_id(nid) 为真且 (layer or "") 不属于 SOURCE_EXCLUDE_LAYERS 时返回 True，否则 False（layer 为假值时按空串判定）。
+def is_linkable_source(nid, layer):
+    """源节点是否可建 reference 边：形态合法 **且** 不在审计留痕层。"""
+    return is_linkable_id(nid) and (layer or "") not in SOURCE_EXCLUDE_LAYERS
+
+
+# 生效条件：text 为假值直接返回 []；否则对 text 中 ID_RE 的每个捕获组 tid，在 tid 不在 seen、不在 ex（exclude 为真时含 str(exclude)）且（known 为 None 或 tid in known）时按首次出现顺序加入 out 并去重。
+def extract_refs(text, known=None, exclude=None):
+    """抽取正文中指向节点 id 的裸引用。
+
+    参数：
+        text    —— 正文（不含 frontmatter）。
+        known   —— 库内已知 id 集合；**传集合时启用白名单过滤**（钩子路径
+                   必须传，防幽灵边与形态误匹配）；传 None 表示只按通用形态
+                   判定（供离线盘点/回填预览使用）。
+        exclude —— 需排除的 id（通常为节点自身 id：正文里写自己的 id 不是引用）。
+
+    返回：去重**保序**的 id 列表（保序让边顺序稳定，落盘可复现）。
+    """
+    if not text:
+        return []
+    ex = {str(exclude)} if exclude else set()
+    seen = set()
+    out = []
+    for m in ID_RE.finditer(text):
+        tid = m.group(1)
+        if tid in seen or tid in ex:
+            continue
+        if known is not None and tid not in known:
+            continue
+        seen.add(tid)
+        out.append(tid)
+    return out
+
+
+# 生效条件：总是返回以 str(target) 为 target、常量 RELATION/EDGE_CONFIDENCE/VERIFIED 为关系与置信字段的 dict，created_at 在 now 非 None 时取 float(now)（now=0 亦取 0.0）、now 为 None 时取 time.time()。
+def make_edge(target, now=None, source="auto:linkref"):
+    """构造一条 reference 边（形态对齐旁路语料：target/relation_type/...）。"""
+    return {
+        "target": str(target),
+        "relation_type": RELATION,
+        "confidence": EDGE_CONFIDENCE,
+        "verified": VERIFIED,
+        "source": source,
+        "created_at": float(now if now is not None else time.time()),
+        "reason": "正文引用（写入侧自动解析）",
+    }
+
+
+# 生效条件：无入参，调用即返回闭包 _before 本身，本调用不做任何引用解析或 ctx 写入。
+def before_hook():
+    """before 拦截器工厂：解析正文引用 → 存 ctx（不落盘、永不短路）。
+
+    写入方可用 `linkref=False` 显式关闭本次自动建链（opt-out）；
+    写入 self 层（审计留痕）或非规范 id 时自动跳过。
+    """
+# 生效条件：ctx 中 a=ctx["a"] 或 {} 的 "linkref" 不为 False、nid=a["node_id"] 或 ctx["nid"] 经 is_linkable_source(nid, a["layer"]) 为真、且 a["content"] 为真时，用 known_ids(ctx["cg"]) 对 content 抽取引用（排除 nid），结果非空则写入 ctx["linkref_targets"]；各条件不满足即提前返回 None，函数始终返回 None。
+    def _before(ctx):
+        a = ctx.get("a") or {}
+        if a.get("linkref") is False:
+            return None
+        nid = a.get("node_id") or ctx.get("nid")
+        if not is_linkable_source(nid, a.get("layer")):
+            return None
+        content = a.get("content")
+        if not content:
+            return None
+        refs = extract_refs(content, known=known_ids(ctx.get("cg")),
+                            exclude=nid)
+        if refs:
+            ctx["linkref_targets"] = refs
+        return None
+    return _before
+
+
+# 生效条件：返回 after 拦截器闭包 _after(ctx, out)——仅当 out 是 dict 且 out.get("committed") 为真、ctx["linkref_targets"] 非空、ctx["cg"] 非 None 且 nid 为真时才对 live 目标逐个 append_edge；任一不成立即提前返回、不建边（建边失败就地吞掉，不阻断写入主流程）；
+def after_hook():
+    """after 拦截器工厂：落盘成功后经 append_edge 建 reference 边（幂等）。
+
+    纪律（G8 第 2 条）：建链失败**不得**阻断写入——所有异常就地吞掉。
+    这同时满足 writepipe 的「after 故障不吞」契约（钩子自身不抛即不触发）。
+    """
+# 生效条件：out 是 dict 且 out.get("committed") 为真、ctx["linkref_targets"] 非空、ctx["cg"] 非 None 且 nid（out["id"] 或 ctx["nid"]）为真时，对 live_targets(cg, targets) 返回的每个 tid 调用 cg.append_edge(nid, make_edge(tid, now=now))，append_edge 抛异常即跳过该条；否则提前返回，函数无返回语句。
+    def _after(ctx, out):
+        if not isinstance(out, dict) or not out.get("committed"):
+            return
+        targets = ctx.get("linkref_targets")
+        if not targets:
+            return
+        cg = ctx.get("cg")
+        nid = out.get("id") or ctx.get("nid")
+        if cg is None or not nid:
+            return
+        now = time.time()
+        # 落边前再经一遍**实读**校验（密钥面读隔离）：`before` 时的白名单只看
+        # 索引密级，加密节点的 DEK 可得性只有实读才知道；此处与 `get` 同口径，
+        # 避免产出指向死目标的悬空边（20260917 取证：459 条此类节点）。
+        for tid in live_targets(cg, targets):
+            try:
+                cg.append_edge(nid, make_edge(tid, now=now))
+            except Exception:                      # noqa: BLE001
+                continue    # 建链降级为静默跳过：写入已成功，不回滚、不抛
+    return _after