@furongjun1999/dsh-memory 0.4.8 → 0.4.10

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

@@ -82,9 +82,11 @@ TRANSITIONS = frozenset({
 })
 
 
+# 生效条件：以 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
@@ -92,6 +94,7 @@ class TransitionError(ValueError):
 
 # ---------------------------------------------------------------- 纯函数裁决
 
+# 生效条件：fm 非 dict 直接返回 "active"；fm 为 dict 时取 fm.get(STATE_FIELD)，该值属于 STATES 则原样返回，缺键或值不在 STATES 均返回 "active"。
 def state_of(fm) -> str:
     """frontmatter → 状态；缺字段或未知值 → "active"（存量兼容，不猜测）。"""
     if not isinstance(fm, dict):
@@ -100,11 +103,13 @@ def state_of(fm) -> str:
     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"
@@ -115,6 +120,7 @@ def can_transition(src, dst) -> bool:
     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）。
 
@@ -138,6 +144,7 @@ def check(src, dst, protected: bool = False, override: bool = False):
     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)
@@ -146,6 +153,7 @@ def require_transition(src, dst, protected: bool = False, override: bool = False
     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)`。
@@ -170,6 +178,7 @@ def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
 
 # ---------------------------------------------------------------- 索引同步
 
+# 生效条件：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 同步进索引快照（免读文件可查）；无索引实现时静默跳过。
 
@@ -193,6 +202,7 @@ def _sync_index(cg, node_id, fm) -> None:
 
 # ---------------------------------------------------------------- 推进 / 回填
 
+# 生效条件：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:
     """推进一个节点的生命周期状态（**唯一推进入口**）。
@@ -226,6 +236,7 @@ def set_state(cg, node_id: str, dst: str, reason: str = None,
     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`（幂等）。
 
@@ -259,4 +270,4 @@ def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
         done.append(nid)
     return {"ok": True, "dry_run": False, "scanned": len(nodes),
             "missing": len(missing), "backfilled": len(done),
-            "planned": done[:50], "failed": failed[:20]}
+            "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

package/md_cg/links.py

@@ -59,10 +59,12 @@ class LinkError(Exception):
 # 存储
 # --------------------------------------------------------------------------
 
+# 生效条件：path 为真值（非 None/非空串）时直接返回 path；否则取 `os.environ.get(LINKS_FILE_ENV)`，其为真值时返回之；环境变量缺失或为空串（假值）时回落 DEFAULT_LINKS_FILE。
 def links_file(path: str = None) -> str:
     return path or os.environ.get(LINKS_FILE_ENV) or DEFAULT_LINKS_FILE
 
 
+# 生效条件：p=links_file(path)，仅当 `os.path.exists(p)` 为真且 json.load 得到 dict 且 `d.get("links")` 为 dict 时，`d.setdefault("schema", SCHEMA)`（已有 schema 键则保留原值）并返回 d；路径不存在、抛 OSError/ValueError、或 links 非 dict 时返回 `{"schema": SCHEMA, "links": {}, "updated_at": None}`。
 def load(path: str = None) -> dict:
     p = links_file(path)
     if os.path.exists(p):
@@ -77,6 +79,7 @@ def load(path: str = None) -> dict:
     return {"schema": SCHEMA, "links": {}, "updated_at": None}
 
 
+# 生效条件：传入 data（dict）与可选 path 时，p=links_file(path)，以 `dict(data)` 浅拷贝并强制覆盖 schema=SCHEMA、updated_at=time.time()，写入 p+".tmp"（目录名为空时 makedirs(".")），chmod 0o600 的 OSError 被吞，`os.replace(tmp, p)` 后返回 p。
 def save(data: dict, path: str = None) -> str:
     p = links_file(path)
     os.makedirs(os.path.dirname(p) or ".", exist_ok=True)
@@ -94,22 +97,26 @@ def save(data: dict, path: str = None) -> str:
     return p
 
 
+# 生效条件：传入 peer 时，对 f"{peer}|{time.time()}|{os.getpid()}" 做 utf-8 编码的 sha256，返回 "lk_" 拼接 `hexdigest()` 的前 12 个十六进制字符（peer 为 None 时按 "None" 参与哈希）。
 def _new_id(peer: str) -> str:
     h = hashlib.sha256(f"{peer}|{time.time()}|{os.getpid()}".encode("utf-8"))
     return "lk_" + h.hexdigest()[:12]
 
 
+# 生效条件：传入 link（dict）与 action，构造含 at/action 的 rec 并并入 kw 中值非 None 的项；link 缺 "audit" 键时由 setdefault 建空列表后 append，link 已有 "audit" 列表则直接 append 一条记录（已有值为 None 等非列表时 append 会失败，源码未兜）。
 def _audit(link: dict, action: str, **kw):
     rec = {"at": time.time(), "action": action}
     rec.update({k: v for k, v in kw.items() if v is not None})
     link.setdefault("audit", []).append(rec)
 
 
+# 生效条件：peer 为 None 或 strip 后为空串时返回空串 p；strip 后以 "agent:" 开头时原样返回 p；否则返回 "agent:" + p。
 def _norm_peer(peer: str) -> str:
     p = (peer or "").strip()
     return p if (not p or p.startswith("agent:")) else "agent:" + p
 
 
+# 生效条件：data.get("links") 为真 dict 时，peer 直接是键则返回 (peer, links[peer])；否则在 {peer, _norm_peer(peer)} 中匹配任一 link_id 或 link 的 peer_node_id 并返回首个 (lid, lk)；均不匹配返回 (None, None)。
 def _find(data: dict, peer: str):
     """按 link_id 或 peer_node_id 定位（容忍省略 `agent:` 前缀）。"""
     links = data.get("links") or {}
@@ -122,6 +129,7 @@ def _find(data: dict, peer: str):
     return None, None
 
 
+# 生效条件：调用方传入 data（须含 "links" 映射）、lid、link 时，执行 `data["links"][lid] = link` 并 save(data, path)，返回 link（data 无 "links" 键时该赋值抛 KeyError，源码未兜）。
 def _commit(data: dict, lid: str, link: dict, path: str = None):
     data["links"][lid] = link
     save(data, path)
@@ -132,6 +140,7 @@ def _commit(data: dict, lid: str, link: dict, path: str = None):
 # 版本对齐度 → 信任上限
 # --------------------------------------------------------------------------
 
+# 生效条件：以 `peer_theory or {}` 取 t，pv=`t.get("version") or t.get("theory_version")`；pv 为假值（None/空串）返回 aligned False、cap CAP_MISALIGNED、reason 为「对端未声明版本」；pv 在本地 theory.check() 的 accepted_versions（缺失时按 []）内返回 aligned True、cap CAP_ALIGNED；否则返回 aligned False、cap CAP_MISALIGNED 并附对端版本与本地集合。
 def version_alignment(peer_theory: dict = None) -> dict:
     """对端版本 vs 本地认可集合 → `{aligned, cap, reason}`。"""
     from .theory import check as _theory_check
@@ -151,6 +160,7 @@ def version_alignment(peer_theory: dict = None) -> dict:
             "local_accepted": accepted, "peer_version": pv}
 
 
+# 生效条件：cap 初始为 CAP_ALIGNED；`alignment.get("aligned")` 为假时 cap=min(cap, CAP_MISALIGNED)；position_map 为假值（None 或空 dict）时 cap=min(cap, CAP_INCOMPLETE)；返回该 cap（数值大小关系由常量定义，源码未在本段校验）。
 def _cap_for(alignment: dict, position_map: dict = None) -> float:
     cap = CAP_ALIGNED
     if not alignment.get("aligned"):
@@ -160,6 +170,7 @@ def _cap_for(alignment: dict, position_map: dict = None) -> float:
     return cap
 
 
+# 生效条件：传入 position 时返回含 position、委派 `md_cg.weights` 得到的 dominant/secondary/excluded/order，以及 class（`_w.is_viewpoint(position)` 真取 VIEWPOINT，否则取 FUNCTIONAL）的字典，不修改任何状态。
 def position_preference(position: str) -> dict:
     """该位置的分量偏好序（委派 `md_cg.weights`，纯结构、无数值）。
 
@@ -182,11 +193,13 @@ FUNCTIONAL = "functional"
 # 签名载荷（确定性：同参数必同字节）
 # --------------------------------------------------------------------------
 
+# 生效条件：传入 body 时返回 `json.dumps(body, ensure_ascii=False, sort_keys=True, separators=(",", ":"))` 的 utf-8 编码字节。
 def _canon(body: dict) -> bytes:
     return json.dumps(body, ensure_ascii=False, sort_keys=True,
                       separators=(",", ":")).encode("utf-8")
 
 
+# 生效条件：传入 peer_node_id 与可选 peer_theory/position_map 时，t=`peer_theory or {}`，返回 _canon 字节串，其中 theory_version 取 `t.get("version") or t.get("theory_version")`、theory_hash 取 `t.get("hash") or t.get("theory_hash")`、position_map 为 `(position_map or {})` 各项按 key 排序后值经 str() 的映射。
 def handshake_payload(peer_node_id: str, peer_theory: dict = None,
                       position_map: dict = None) -> bytes:
     t = peer_theory or {}
@@ -199,6 +212,7 @@ def handshake_payload(peer_node_id: str, peer_theory: dict = None,
     })
 
 
+# 生效条件：传入 peer_node_id、evidence、positive 时返回 _canon 字节串，evidence 经 str()（None 得 "None"）、positive 经 bool()（0/""/None 得 False）。
 def evidence_payload(peer_node_id: str, evidence: str, positive: bool) -> bytes:
     return _canon({"peer_node_id": peer_node_id, "evidence": str(evidence),
                    "positive": bool(positive)})
@@ -208,6 +222,7 @@ def evidence_payload(peer_node_id: str, evidence: str, positive: bool) -> bytes:
 # 握手（文档 §5.1 五步：① 声明 → ② 校验 → ③ 建档 → ④ 观察期；⑤ 转正见 promote）
 # --------------------------------------------------------------------------
 
+# 生效条件：peer_node_id 为假值（空串）时抛 LinkError，不以 agent: 开头的会被补前缀；ver.ok 为假时按 on_fail 取 reject 抛 LinkError、取 isolate 置 isolated、否则置 degraded，declared_charter 为假值时观察期按 PROBATION_SECONDS*2 计，未失败但版本不符仅记 version_misaligned 审计，正常路径返回 {'ok': True, 'link', 'alignment', 'signature'}；
 def handshake(peer_node_id: str, *, peer_theory: dict = None,
               position_map: dict = None, declared_charter: bool = True,
               subsystem: str = None, peer_signature: str = None,
@@ -306,6 +321,7 @@ def handshake(peer_node_id: str, *, peer_theory: dict = None,
 # 观测（P_trust 更新 / 反例击穿）
 # --------------------------------------------------------------------------
 
+# 生效条件：peer 经 load(path)/_find 命中连接（未命中或 status 为 "withdrawn" 时抛 LinkError）；`_signer.verify_for(...)` 返回值中 ok 非真时按 `ver.get("on_fail") or "degrade"` 处置——"reject" 抛 LinkError，其余置 isolated/degraded 后返回 ok False；验签通过则 delta=UP_STEP if positive else -DOWN_STEP，P_trust 置 `round(max(0.0, min(cap, before + delta)), 6)`（cap 取 `link.get("p_trust_cap") or 0.0`），负证据且新 P_trust<DEGRADE_BELOW 且原状态在 IN_TRUST 时降级，返回 ok True、link、delta。
 def observe(peer: str, *, evidence: str, positive: bool = True,
             subsystem: str = None, peer_signature: str = None,
             path: str = None, signers_file: str = None,
@@ -370,6 +386,7 @@ def observe(peer: str, *, evidence: str, positive: bool = True,
 # 状态迁移（宪章第二十二条响应阶梯）
 # --------------------------------------------------------------------------
 
+# 生效条件：status 不在 STATUS 中抛 LinkError；否则写入 link["status"]=status，status 为 "isolated" 时同时置 p_trust_cap=CAP_ISOLATED、p_trust=0.0，并写留痕（clause 为假值含 None/空串时回落「宪章第二十二条（响应阶梯）」），返回 link。
 def _set_status(link: dict, status: str, *, actor: str = "system",
                 clause: str = None, reason: str = None):
     if status not in STATUS:
@@ -384,6 +401,7 @@ def _set_status(link: dict, status: str, *, actor: str = "system",
     return link
 
 
+# 生效条件：传入 peer 与 status 时，先 load(path)/_find 定位（未命中抛 LinkError），再 `_set_status(link, status, actor=actor, reason=reason)` 并 `_commit(data, lid, link, path)`，返回 `{"ok": True, "link": link}`。
 def _transition(peer, status, *, reason=None, path=None, actor="system"):
     data = load(path)
     lid, link = _find(data, peer)
@@ -394,6 +412,7 @@ def _transition(peer, status, *, reason=None, path=None, actor="system"):
     return {"ok": True, "link": link}
 
 
+# 生效条件：连接存在且 link["status"]=="probation" 且 float(link.get("probation_until") or 0) - time.time() <= 0 时置 normal、promoted_at，提交并返回 {'ok': True, 'link'}；连接不存在、非 probation 或观察期未满均抛 LinkError。
 def promote(peer: str, *, path: str = None, actor: str = "system") -> dict:
     """观察期满且无异常 → normal。"""
     data = load(path)
@@ -412,16 +431,19 @@ def promote(peer: str, *, path: str = None, actor: str = "system") -> dict:
     return {"ok": True, "link": link}
 
 
+# 生效条件：传入 peer 时无条件返回 `_transition(peer, "degraded", reason=reason, path=path, actor=actor)`，reason/path/actor 原样透传。
 def degrade(peer: str, *, reason: str = None, path: str = None,
             actor: str = "system") -> dict:
     return _transition(peer, "degraded", reason=reason, path=path, actor=actor)
 
 
+# 生效条件：传入 peer 时无条件返回 `_transition(peer, "isolated", reason=reason, path=path, actor=actor)`，reason/path/actor 原样透传。
 def isolate(peer: str, *, reason: str = None, path: str = None,
             actor: str = "system") -> dict:
     return _transition(peer, "isolated", reason=reason, path=path, actor=actor)
 
 
+# 生效条件：传入 peer 时无条件返回 `_transition(peer, "withdrawn", reason=reason, path=path, actor=actor)`，reason/path/actor 原样透传（30 天冷静期不在本函数内校验）。
 def withdraw(peer: str, *, reason: str = None, path: str = None,
              actor: str = "system") -> dict:
     """声明退出（宪章第二十一条附 3：30 天冷静期由上层流程保证）。"""
@@ -432,6 +454,7 @@ def withdraw(peer: str, *, reason: str = None, path: str = None,
 # 衰减（无观测向初值回归）
 # --------------------------------------------------------------------------
 
+# 生效条件：now 为假值（None 或 0）时回落 time.time()；仅 status 属于 IN_TRUST 的链接参与，days=max(0, (now-last)/86400) 为 0 时跳过，否则按 DECAY_DAYS 算向 P_TRUST_INIT 回归后的 p_trust 与 decay，decay 绝对值 > 1e-9 才计入 changed 并 save，最终返回 {'ok': True, 'changed', 'count'}；
 def decay_all(*, path: str = None, now: float = None,
               actor: str = "system") -> dict:
     data = load(path)
@@ -465,6 +488,7 @@ def decay_all(*, path: str = None, now: float = None,
 # 查询 / 自描述 / CLI
 # --------------------------------------------------------------------------
 
+# 生效条件：`_find(load(path), peer)` 命中时返回该 link；未命中时抛 LinkError。
 def get(peer: str, *, path: str = None) -> dict:
     lid, link = _find(load(path), peer)
     if not link:
@@ -472,6 +496,7 @@ def get(peer: str, *, path: str = None) -> dict:
     return link
 
 
+# 生效条件：status 为真值时过滤掉 `link.get("status") != status` 的连接，subsystem 为真值时过滤掉 `link.get("subsystem") != subsystem` 的连接（两者为 None/空串则不过滤）；返回 `{"file": links_file(path), "count": len(out), "links": out}`，out 按 (status, peer_node_id) 排序。
 def ls(*, path: str = None, status: str = None, subsystem: str = None) -> dict:
     data = load(path)
     out = []
@@ -490,6 +515,7 @@ def ls(*, path: str = None, status: str = None, subsystem: str = None) -> dict:
     return {"file": links_file(path), "count": len(out), "links": out}
 
 
+# 生效条件：无 required 形参，调用即返回自描述 dict，其中 "file" 由无参 `links_file()` 决定（随 LINKS_FILE_ENV 环境变量与 DEFAULT_LINKS_FILE 回落变化），其余字段由 STATUS 列表与模块级常量（P_TRUST_INIT/UP_STEP/DOWN_STEP/DEGRADE_BELOW/DECAY_DAYS/PROBATION_SECONDS/CAP_*）拼成。
 def catalog() -> dict:
     return {
         "layer": "连接层（蜂群互联层1）",
@@ -518,10 +544,12 @@ def catalog() -> dict:
     }
 
 
+# 生效条件：传入 obj 时执行 `print(json.dumps(obj, ensure_ascii=False, indent=1, default=str))`，无返回值（不可序列化对象经 default=str 转字符串）。
 def _print(obj):
     print(json.dumps(obj, ensure_ascii=False, indent=1, default=str))
 
 
+# 生效条件：argv 为 None 时 argparse 取 sys.argv，子命令为 required；a.cmd 为 catalog/ls/handshake/observe/promote|degrade|isolate|withdraw/show/decay 时分别以 a.links_file（──links-file）、a.status、peer、a.evidence、`positive=not a.negative`、a.reason、a.signers_file 等分派执行；捕获 LinkError 打印到 stderr 并返回 2，否则返回 0（argparse 自身错误退出不在本段返回值内）。
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.links",
@@ -592,4 +620,4 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())