@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/ccgc.py

@@ -60,6 +60,9 @@ E_CODES = {
     "E041": "自证拒绝：验证方标识 == 编译执行者（LLM 不得自己验证自己）",
     "E042": "验证未通过：签章判定 REJECT / BLINDSPOT",
     "E043": "修正非法：只允许修正 condition_space 四槽",
+    "E050": ("依赖声明缺失：正文以 `@<节点 id>` 声明了跨节点依赖（「# 子功能：」行），"
+             "但 depends_on 未给出可解析目标——依赖必须是可解析的字段，不能只是散文"),
+    "E051": "依赖目标不存在：depends_on 指向的节点不在库中（悬空依赖）",
 }
 
 # ---- 候选来源标识（写进留痕，可溯源到「谁说的」） ----
@@ -91,13 +94,16 @@ class CompileResult:
     verdict: Optional[Dict] = None                              # 验证单元终裁
 
     @property
+# 生效条件：BLINDSPOT：缺证据（无 required 形参与模块级常量，仅有未给出的 self.errors 来源）。
     def has_errors(self) -> bool:
         return len(self.errors) > 0
 
+# 生效条件：对任意 code，msg 取 E_CODES.get(code, code)（缺键回落 code 本身），向 self.errors 追加 "code 空格 msg"，extra 为真值时再追加 "（extra）"。
     def err(self, code: str, extra: str = "") -> None:
         msg = E_CODES.get(code, code)
         self.errors.append(code + " " + msg + (("（" + extra + "）") if extra else ""))
 
+# 生效条件：无入参，首行按 self.success 输出「编译成功」或「编译失败（len(self.errors) 个错误）」，要素行取 nodefile.CCG_MARKS 与 self.lines 的交集，errors 列前 10 条、warnings 列前 5 条，返回 "\n".join(out)。
     def summary(self) -> str:
         out = ["编译成功" if self.success else
                "编译失败（%d 个错误）" % len(self.errors)]
@@ -140,14 +146,17 @@ class LinkResult:
 # 工具（就地实现，避免跨模块 import 环——与 mdcg.py 复制 _ccg_line 的既有做法一致）
 # =============================================================================
 
+# 生效条件：对任意 s（含 None/空串，源码以 `(s or "")` 兜底为空串），返回 hashlib.sha1(该串 utf-8 编码).hexdigest()[:12]。
 def _sha(s: str) -> str:
     return hashlib.sha1((s or "").encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：对任意 cg，返回 os.path.join(cg.root, LOG_NAME)（即 cg.root 与模块级常量 LOG_NAME 的拼接）。
 def _log_path(cg) -> str:
     return os.path.join(cg.root, LOG_NAME)
 
 
+# 生效条件：x 为 None 或非 str 时原样返回 x；x 为 str 时返回 MdCGOS(x) 构造出的 cg 实例。
 def _as_cg(x):
     """接受 root 路径或已构造的 cg 实例——保持密级隔离与密钥上下文。"""
     if x is None or not isinstance(x, str):
@@ -156,11 +165,13 @@ def _as_cg(x):
     return MdCGOS(x)
 
 
+# 生效条件：content 为字符串（None 视作空串）时，若其中含 "# " + field_name + "：" 或 "# " + field_name + ":" 则返回 True，否则 False。
 def _has_ccg_line(content: str, field_name: str) -> bool:
     text = content or ""
     return ("# " + field_name + "：") in text or ("# " + field_name + ":") in text
 
 
+# 生效条件：在 `(content or "").split("\n")` 中命中首个 strip 后以 "#" 开头、含 field_name、且去 "#" 后按全角或半角冒号切出的名字等于 field_name 的行→替换为 "# field_name：value" 并返回；否则若有行 strip 后以 "# 功能名" 开头→在该行后插入新行并返回；否则返回 `"# field_name：value\n" + (content or "")`。
 def _upsert_ccg_line(content: str, field_name: str, value: str) -> str:
     """写入/替换 `# <字段>：<值>`，优先插在「# 功能名」之后。
 
@@ -183,6 +194,7 @@ def _upsert_ccg_line(content: str, field_name: str, value: str) -> str:
     return newline + "\n" + (content or "")
 
 
+# 生效条件：对任意 path 与 rec，以追加模式写入 json.dumps(rec, ensure_ascii=False) + "\n"，仅 OSError 被吞掉且无返回值。
 def _append_jsonl(path: str, rec: dict) -> None:
     try:
         with open(path, "a", encoding="utf-8") as f:
@@ -191,6 +203,7 @@ def _append_jsonl(path: str, rec: dict) -> None:
         pass
 
 
+# 生效条件：path 为假值或 os.path.exists(path) 为假→返回 []；否则逐行 strip、跳过空行、json.loads 成功者追加、单行 json.loads 抛 ValueError 者跳过，中途 open/读取抛 OSError 时返回 []；全部读完返回 out。
 def _read_jsonl(path: str) -> List[dict]:
     out: List[dict] = []
     if not path or not os.path.exists(path):
@@ -218,6 +231,7 @@ def _read_jsonl(path: str) -> List[dict]:
 _FRAG_SPLIT = re.compile(r"[；;、，,]+")
 
 
+# 生效条件：value 经 `str(value).strip()`（None 记 ""）后为空→False；否则按 _FRAG_SPLIT 切分并去掉空分片，若分片列表为空→False；否则返回全部分片都在 dialog 中的 all 判定结果。
 def _value_grounded(dialog: str, value) -> bool:
     """值是否 grounded：按分片切分后，每个分片都是对话记录的字面子串。
 
@@ -233,6 +247,7 @@ def _value_grounded(dialog: str, value) -> bool:
     return all(f in dialog for f in frags)
 
 
+# 生效条件：span 经 `str(span).strip()`（None 记 ""）后须非空且作为连续子串出现在 dialog 中，否则返回 False。
 def _span_grounded(dialog: str, span) -> bool:
     """引用 span 是否 grounded：必须是对话记录的**连续**字面子串。"""
     s = "" if span is None else str(span).strip()
@@ -264,10 +279,12 @@ _SENT_SPLIT = re.compile(r"[。！？!?；;\n]+")
 _TS_PAT = re.compile(r"(20\d{2})[-/年](\d{1,2})[-/月](\d{1,2})")
 
 
+# 生效条件：dialog 为假值时按 "" 处理，按模块级 _SENT_SPLIT 切分后 strip 并过滤空串，返回句子列表。
 def _sentences(dialog: str) -> List[str]:
     return [s.strip() for s in _SENT_SPLIT.split(dialog or "") if s.strip()]
 
 
+# 生效条件：对 sents 逐句判 `any(c in s for c in cues)`，命中即 append，命中后 `len(out) >= limit` 即 break——limit 为 0 或负数时首个命中项仍被 append 后立刻 break（多返 1 项）；cues 为空容器时 any 恒假、返回空列表。
 def _pick_by_cues(sents: List[str], cues, limit: int = 1) -> List[str]:
     """按线索词命中挑句（命中即整句作为候选——整句天然是原文子串，不会捏造）。"""
     out: List[str] = []
@@ -279,6 +296,7 @@ def _pick_by_cues(sents: List[str], cues, limit: int = 1) -> List[str]:
     return out
 
 
+# 生效条件：类无 __init__ 形参，实例化即成立，类属性 name 恒为模块级常量 SRC_RULE，候选能力经 candidates(dialog, ctx=None) 以 dialog 为必需入参调用；
 class RuleParser:
     """内生规则解析器：**诚实下界能力**，不是主路径。
 
@@ -290,6 +308,7 @@ class RuleParser:
 
     name = SRC_RULE
 
+# 生效条件：sents（来自 _sentences(dialog)）非空时「功能名」取首句（超 30 字符截前 30）；pos/tool/cons 仅在 _pick_by_cues 用 _CUES 对应线索命中时写入对应槽；time_window 先按 _TS_PAT 在 dialog 中匹配，命中且 mktime 未抛 ValueError/OverflowError/OSError 才填 [当日0点, +86399]，否则回落 [nodefile.FULL_TIME_WINDOW_MIN, nodefile.FULL_TIME_WINDOW_MAX] 并标 synthetic="full_time_window"；「不适用条件/执行/子功能」按 _NEG_CUES/_EXEC_CUES/_SUB_CUES 命中首句写入；「验证方式」取 _BASIS_CUES 中首个出现在 dialog 中的线索。
     def candidates(self, dialog: str, ctx: Optional[dict] = None) -> Dict[str, Any]:
         sents = _sentences(dialog)
         out: Dict[str, Any] = {"marks": {}, "slots": {}}
@@ -337,6 +356,7 @@ class RuleParser:
         return out
 
 
+# 生效条件：对给定 parser、dialog、ctx，getattr(parser,"candidates",parser) 得到的 fn 被调用为 fn(dialog, ctx or {})，若该调用抛 Exception 或返回非 dict 则返回 {"marks": {}, "slots": {}}，否则返回该 dict 并 setdefault("marks",{}) 与 setdefault("slots",{}) 后的结果。
 def _invoke_parser(parser, dialog: str, ctx: Optional[dict]) -> Dict[str, Any]:
     """调用外部/内生解析器，统一形态；异常不视作通过（返回空候选）。"""
     fn = getattr(parser, "candidates", parser)
@@ -355,6 +375,7 @@ def _invoke_parser(parser, dialog: str, ctx: Optional[dict]) -> Dict[str, Any]:
 # 核心：compile_dialog（对话记录 → 六要素候选；只编译，不入库）
 # =============================================================================
 
+# 生效条件：dialog 空记 E001、node_id 空记 E002、actor 空记 E003，且 cg 转换后非 None 而 node_id 非空时该节点不存在再记 E002，存在任一 errors 即以 verdict{passed:False, reason:errors[0], authority:VERIFICATION_UNIT} 提前返回 res；否则按「marks/slots 任一为非空 dict → SRC_EXPLICIT；二者皆空且 parser 为 None → SRC_RULE（附下界告警）；二者皆空且 parser 非 None → SRC_PARSER」收集候选，四槽逐个校验（key 不在 cand_slots 即跳过；time_window 非长度 2 的 list/tuple 记 E021；其余槽空值/占位记 E021；仅当非「src_kind==SRC_EXPLICIT 且 strict_spans=False」豁免时，值非 dialog 子串记 E011、span 非空而定位失败记 E010），clean_slots 缺必需槽或 condition_space_text 为空记 E020；五要素按同样规则过滤后入 res.lines（生效条件行只由四槽 env_text 合成），验证基底按「候选 basis → 验证方式命中 _BASIS_CUES → 默认 other 并附告警」取值、不在 nodefile.VERIFICATION_BASIS 中记 E030；最终 res.success 与 verdict.passed 同取「无 errors」，verdict 恒带 requires_attestation=True，通过时再按 nodefile.CCG_REQUIRED 缺失项补 warning；
 def compile_dialog(dialog: str, node_id: str, actor: str, *,
                    marks: Optional[Dict[str, Any]] = None,
                    slots: Optional[Dict[str, Any]] = None,
@@ -429,6 +450,7 @@ def compile_dialog(dialog: str, node_id: str, actor: str, *,
         res.warnings.append(
             "strict_spans=False：显式入参豁免名实门，含未经对话原文支撑的声明（已留痕）。")
 
+# 生效条件：item 为 dict 时返回 (item.get("value"), item.get("span"), item.get("basis"), item.get("synthetic"))（各键缺失即回落 None）；item 非 dict 时返回 (item, None, None, None)。
     def _field(item):
         """候选项 → (value, span, basis, synthetic)；容忍裸值与 dict 两种形态。"""
         if isinstance(item, dict):
@@ -550,6 +572,7 @@ def compile_dialog(dialog: str, node_id: str, actor: str, *,
 # attest：认知图**外**的验证方签章（裁定 A 的落点）
 # =============================================================================
 
+# 生效条件：依次判 strip 后的 node_id 为空→E002；verifier 为空→E003；verifier==compiled_by→E041；state（verdict.strip()）不在模块级 STATES→非法裁决；state 非 ACCEPT→E042；全部通过才 res.ok=True；随后恒算 token=_sha(...)，仅当 ledger 为真且 _as_cg(cg) 非 None 时追加一条 ccgc_attest 审计 jsonl。
 def attest(node_id: str, verdict: str, verifier: str, compiled_by: str, *,
            slot_corrections: Optional[Dict[str, Any]] = None,
            evidence: str = "", cg: Any = None, ledger: bool = True) -> AttestResult:
@@ -596,6 +619,37 @@ def attest(node_id: str, verdict: str, verifier: str, compiled_by: str, *,
 # link：签章通过才写入（缺签章恒不写入）
 # =============================================================================
 
+# 生效条件：依次判 compiled.success 为假→返回带错误；attestation 为 None→E040；attestation.node_id 不等于 compiled.node_id 的取值→目标不一致拒绝；attestation.verifier 为真值且 == `(actor or compiled.actor)`→E041；attestation.ok 为假→E042；_as_cg(cg) 为 None→E002；节点不在 cg.index 的 nodes 中→E002；apply 为假→ok=True 的 dry-run 返回；否则 apply 为真时写入（fm 为 None 或 content 加密→E004），basis 为假值则回落 compiled.sources.get("verification_basis") 或 "other"，成功后 out.written=len(compiled.lines)。
+def _check_deps(_cg, node_id: str) -> List[str]:
+    """依赖声明硬闸门 → 错误列表（E050 / E051）。**读面失败不误杀**（返回空即放行）。
+
+    契约口径：CCG「子功能」行的契约角色是**依赖 dependency**（nodefile 术语真源），
+    但该槽同时承载**自述子功能**（描述本单元内部构成）——判据以 `@<节点 id>` 显式
+    引用为界（`nodefile.declares_dependency`，收窄裁定 b）：**显式声称依赖**才要求在
+    `depends_on` 给出可解析目标——否则「依赖」只剩散文，被依赖单元一旦变动，下游
+    无处可传（失效传播从源头断链）。自然语言自述不算声明（依赖不是必填元数据）。
+    二者齐全时目标必须真实存在：悬空依赖 = 声称依赖一个并不存在的地基。
+    """
+    errs: List[str] = []
+    try:
+        node = _cg.get(node_id)
+    except Exception:                       # noqa: BLE001 —— 读面异常按「无声明」放行
+        return errs
+    if not node:
+        return errs
+    from . import trust as _trust
+    fm = node.get("frontmatter") or {}
+    deps = _trust.as_deps(fm.get(nodefile.DEPENDS_ON_FIELD))
+    if nodefile.declares_dependency(node.get("content") or "") and not deps:
+        errs.append("E050 " + E_CODES["E050"])
+    known = set((getattr(_cg, "index", None) or {}).get("nodes") or {})
+    missing = [d for d in deps if d not in known]
+    if missing:
+        errs.append("E051 " + E_CODES["E051"] + "：" + ",".join(missing[:5]))
+    return errs
+
+
+# 生效条件：依次判 compiled.success 为假→返回带错误；attestation 为 None→E040；attestation.node_id 不等于 compiled.node_id 的取值→目标不一致拒绝；attestation.verifier 为真值且 == `(actor or compiled.actor)`→E041；attestation.ok 为假→E042；_as_cg(cg) 为 None→E002；节点不在 cg.index 的 nodes 中→E002；依赖声明闸门（E050/E051）不通过→拒绝写入；apply 为假→ok=True 的 dry-run 返回；否则 apply 为真时写入（fm 为 None 或 content 加密→E004），basis 为假值则回落 compiled.sources.get("verification_basis") 或 "other"，成功后 out.written=len(compiled.lines)。
 def link(compiled: CompileResult, attestation: Optional[AttestResult], *,
          cg: Any = None, apply: bool = False, actor: str = "",
          basis: str = "") -> LinkResult:
@@ -633,6 +687,10 @@ def link(compiled: CompileResult, attestation: Optional[AttestResult], *,
     if not entry:
         out.errors.append("E002 节点不存在：" + node_id)
         return out
+    _dep_errs = _check_deps(_cg, node_id)
+    if _dep_errs:
+        out.errors.extend(_dep_errs)
+        return out
     if not apply:
         out.ok = True
         out.warnings.append("dry-run（apply=False）：未写入；签章 token=" + attestation.token)
@@ -686,6 +744,7 @@ def link(compiled: CompileResult, attestation: Optional[AttestResult], *,
 # recalibrate：用后续验证修正生效条件（裁定 A 的闭环）
 # =============================================================================
 
+# 生效条件：node_id 空→E002；verifier 为真值且==compiled_by→E041；corrections 为假值（空 dict/None）→E043；corrections 含不在模块级 nodefile.CONDITION_SLOTS 的键→E043；_as_cg(cg) 为 None→E002；节点不在 cg.index 的 nodes 中→E002；fm 为 None 或内容加密→E004；旧槽合并 corrections 后 condition_space_text 为空→E020；apply 为假→ok=True 的 dry-run 返回；否则写入并按 1 计 written。
 def recalibrate(node_id: str, corrections: Dict[str, Any], verifier: str,
                 compiled_by: str, *, evidence: str = "", cg: Any = None,
                 apply: bool = False) -> LinkResult:
@@ -772,11 +831,13 @@ def recalibrate(node_id: str, corrections: Dict[str, Any], verifier: str,
 PENDING_DIR = "_ccgc_pending"
 
 
+# 生效条件：node_id 为 None 或空串时按 "" 处理，非 [0-9A-Za-z_.\-] 字符一律替换为 "-"，取前 80 个字符；结果为空串时返回 "unnamed"。
 def _safe_name(node_id: str) -> str:
     """node_id → 文件名安全形态（分支节点形如 mem_x@br1，须剥掉非 [A-Za-z0-9_.-]）。"""
     return re.sub(r"[^0-9A-Za-z_.\-]", "-", str(node_id or ""))[:80] or "unnamed"
 
 
+# 生效条件：_as_cg(cg) 的 root 属性为假值→返回 ""；否则返回 os.path.join(str(root), PENDING_DIR, _safe_name(node_id) + ".json")。
 def pending_path(cg, node_id: str) -> str:
     _cg = _as_cg(cg)
     root = getattr(_cg, "root", None)
@@ -785,12 +846,14 @@ def pending_path(cg, node_id: str) -> str:
     return os.path.join(str(root), PENDING_DIR, _safe_name(node_id) + ".json")
 
 
+# 生效条件：lines、slots 为假值时按 {} 处理，返回 `_sha(json.dumps({"lines":..., "slots":...}, ensure_ascii=False, sort_keys=True))`。
 def _payload_hash(lines, slots) -> str:
     """候选内容摘要（六行 + 四槽，键序无关）——签章与产物的绑定依据。"""
     return _sha(json.dumps({"lines": lines or {}, "slots": slots or {}},
                            ensure_ascii=False, sort_keys=True))
 
 
+# 生效条件：_as_cg(cg) 为 None→返回 {'ok': False, 'error': '未提供 cg'}；pending_path 为空→返回 {'ok': False, 'error': '无法定位 pending 目录'}；否则写 json（OSError 时返回 ok=False 且带 path 与异常名），成功返回 {'ok': True, 'path': p, 'hash': rec['hash']}，其中 attest 按 `attestation is not None` 决定是否落盘。
 def save_pending(cg, compiled: CompileResult,
                  attestation: Optional[AttestResult] = None) -> dict:
     """候选（+ 可选签章）落 pending；返回 {ok, path, hash}。"""
@@ -813,6 +876,7 @@ def save_pending(cg, compiled: CompileResult,
     return {"ok": True, "path": p, "hash": rec["hash"]}
 
 
+# 生效条件：_as_cg(cg) 为 None→error='未提供 cg'；pending_path 为空或 os.path.isfile(p) 为假→error=未找到 pending；open/json.load 抛 OSError 或 ValueError→error=pending 不可读；否则按 dataclasses.fields 过滤重建 CompileResult 与（rec['attest'] 为真值时的）AttestResult，hash_ok = `rec.get("hash") == _payload_hash(c.lines, c.slots)`，ok=True。
 def load_pending(cg, node_id: str) -> dict:
     """读回候选与签章，并校验 hash（内容被改即 hash_ok=False，调用方须拒绝写入）。"""
     _cg = _as_cg(cg)
@@ -845,6 +909,7 @@ def load_pending(cg, node_id: str) -> dict:
     return out
 
 
+# 生效条件：pending_path(cg, node_id) 为空→返回 False；否则 os.remove 成功→True，抛 OSError→False。
 def drop_pending(cg, node_id: str) -> bool:
     """删除 pending（link 成功后调用；失败静默——待办件不是事实，无需强保证）。"""
     p = pending_path(cg, node_id)
@@ -857,6 +922,7 @@ def drop_pending(cg, node_id: str) -> bool:
         return False
 
 
+# 生效条件：load_pending(cg, node_id) 的 ok 为假→带其 error 返回 LinkResult；hash_ok 为假→以「hash 不符」错误返回；否则转调 link(got["compiled"], got.get("attest"), cg=cg, apply=apply, actor=actor, basis=basis) 并返回其结果，且仅当 res.ok 与 apply 同时为真时调用 drop_pending。
 def link_pending(cg, node_id: str, *, apply: bool = False, actor: str = "",
                  basis: str = "") -> LinkResult:
     """从 pending 读回候选与签章后 link：hash 校验 → 签章准入 → 写入 → 清理 pending。"""
@@ -880,5 +946,4 @@ __all__ = ["ACCEPT", "REJECT", "DEFER", "BLINDSPOT", "STATES", "CONTRACT_ROLES",
            "E_CODES", "CompileResult", "AttestResult", "LinkResult", "RuleParser",
            "compile_dialog", "attest", "link", "recalibrate",
            "PENDING_DIR", "pending_path", "save_pending", "load_pending",
-           "drop_pending", "link_pending"]
-
+           "drop_pending", "link_pending"]

package/md_cg/census.py

@@ -31,6 +31,7 @@ DEFAULT_ROOT = os.path.join(
 ARCHIVE_DIRS = ("trash", "_protected_history", "_protected", "_index_log", "hippocampus")
 
 
+# 生效条件：当 root 为记忆库根目录、其下 .md 能被 nodefile.loads 解析出 frontmatter 时，返回 [(node_id, layer, condition_space, tags)...]；ARCHIVE_DIRS 与 _protected_history_ 目录整棵剪枝，无 frontmatter 的 md 跳过。
 def load(root):
     """遍历 md 记忆库根，返回 [(node_id, layer, condition_space, tags), ...]。
 
@@ -62,6 +63,7 @@ def load(root):
     return out
 
 
+# 生效条件：rows 非空、每行可解包为 (_, _, d, t) 且 keyfn(d, t) 可调用时，打印桶数、最大桶占比、单例桶比与期望扫描占比，无返回值。
 def report(name, rows, keyfn):
     cnt = collections.Counter(keyfn(d, t) for _, _, d, t in rows)
     n = len(rows)
@@ -78,12 +80,14 @@ def report(name, rows, keyfn):
     print(f"  ★条件路由后期望扫描占比 = {exp * 100:.1f}%  (100%=退化成全量, 越低越有效)")
 
 
+# 生效条件：传入 keys（任意可迭代键序列，含空序列时对 json.dumps({}) 求哈希）即返回一个接收 (d, t) 的 lambda，该 lambda 按 keys 逐个取 d.get(k)（缺键得 None）并 sort_keys=True、ensure_ascii=False 序列化后取 sha256 十六进制前 10 位，形参 t 不参与计算。
 def by_keys(keys):
     return lambda d, t: hashlib.sha256(
         json.dumps({k: d.get(k) for k in keys}, sort_keys=True,
                    ensure_ascii=False).encode()).hexdigest()[:10]
 
 
+# 生效条件：以 root 调用 load(root) 得 rows，先打印「总节点: len(rows)」（空序列也会先打印该行），仅当 rows 为假值时才打印空库提示并 return 2，否则继续打印分层与各维度取值分布、并执行方案A/B/C/D 的 report 后 return 0。
 def main(root):
     rows = load(root)
     print(f"md 记忆库: {root}")
@@ -126,4 +130,4 @@ if __name__ == "__main__":
     # 会在解释器退出阶段丢缓冲（实测只落盘 444 字节），CI 里会看不到失败原因。
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")
-    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_ROOT))
+    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_ROOT))

package/md_cg/chain.py

@@ -39,11 +39,17 @@ EDGE_WEIGHTS = {
     "correlational": 0.45,
     "cyclic": 0.35,
     "opposite": 0.30,
+    # 正文引用边（linkref，写入侧自动解析，2026-09-17）：取弱权重——正文提及
+    # ≠ 语义相似 ≠ 因果依赖，故与 DEFAULT_EDGE_WEIGHT 同值；显式登记的意义在
+    # 「类型已知」（可审计、可按类型调参、可区分于未登记类型的兜底默认）。
+    "reference": 0.50,
 }
 DEFAULT_EDGE_WEIGHT = 0.50
 
 CAUSAL_TYPES = ("causal",)
 # 检索默认沿「有语义方向」的关系走：因果 / 时序 / 条件适用
+# 注：reference **刻意不入**——正文提及不应进入「前提→结论」条件序列遍历，
+# 否则 causal 链会被「提到过」这类无向弱关联稀释（模式分离）。
 CHAIN_TYPES_DEFAULT = ("causal", "sequential", "applies_to")
 
 MAX_DEPTH_DEFAULT = 5
@@ -51,6 +57,7 @@ MAX_DEPTH_HARD = 64
 MAX_NODES_DEFAULT = 500
 
 
+# 生效条件：edge 为 dict 时按 relation_type→relation→type 顺序取首个真值、非 dict 时 rel 记为 None，两者统一返回 str(rel or "").strip().lower()——键缺失或全为假值时得空串。
 def edge_rel(edge):
     """取边的 relation_type（兼容 dict / 字符串两种写法），统一小写。"""
     if isinstance(edge, dict):
@@ -60,6 +67,7 @@ def edge_rel(edge):
     return str(rel or "").strip().lower()
 
 
+# 生效条件：edge 为 dict 时取 target or target_id（前者假值回落后者），该值非 None 则返回其 str().strip()、为 None 返回 None；edge is None 返回 None；其余（裸字符串等）返回 str(edge).strip() 或空白串时 None。
 def edge_target(edge):
     """取边的目标节点 id（兼容 target / target_id / 裸字符串）。"""
     if isinstance(edge, dict):
@@ -70,6 +78,7 @@ def edge_target(edge):
     return str(edge).strip() or None
 
 
+# 生效条件：base 取 EDGE_WEIGHTS.get(edge_rel(edge), DEFAULT_EDGE_WEIGHT)；edge 为 dict 时 conf 为 float(edge.get("confidence", 1.0))（缺该键得 1.0，值不可转 float 如 None 触发 TypeError/ValueError 时也回落 1.0），非 dict 时 conf 恒为 1.0，返回 round(base * max(0.0, min(1.0, conf)), 6)；
 def edge_weight(edge):
     """边权重 = 类型 base × 边置信度（缺失置信度视为 1.0 的已声明边）。"""
     base = EDGE_WEIGHTS.get(edge_rel(edge), DEFAULT_EDGE_WEIGHT)
@@ -82,6 +91,7 @@ def edge_weight(edge):
     return round(base * max(0.0, min(1.0, conf)), 6)
 
 
+# 生效条件：edge 非 dict 时返回 ""；edge 为 dict 时按 ("condition","conditions","条件") 顺序取第一个真值（list/tuple 先以 "；" 连接其中 str(x).strip() 非空的项，连接结果为空则视为假值跳过该键）并返回 str(v).strip()；三键均无真值且 edge.get("condition_space") 为 dict 时返回 condition_space_text(cs, require_full=False)；否则返回 ""；
 def edge_condition(edge):
     """边的条件标注：条件链上「这一跳在什么条件下成立」。"""
     if not isinstance(edge, dict):
@@ -101,6 +111,7 @@ def edge_condition(edge):
     return ""
 
 
+# 生效条件：cg.get(nid) 为假值（该节点缺失或为空）时返回 []；否则以 node.get("frontmatter") or {} 与 node.get("content") or "" 调 _declared_conditions，返回其正向条件列表 pos；
 def node_conditions(cg, nid):
     """节点自己声明的生效条件（CCG `# 生效条件：` 等三处来源合并）。"""
     node = cg.get(nid)
@@ -112,6 +123,7 @@ def node_conditions(cg, nid):
     return pos
 
 
+# 生效条件：cg 已有 _chain_adj 且其 [0] 等于 bool(include_hierarchy) 时直接返回缓存的 [1]；否则以 cg.index["nodes"]（无 index 或无该键时视为无节点）逐节点收集 frontmatter.edges 中 edge_target 非空的出边，include_hierarchy 为真时再为 subgraph.nodes 各合成一条 relation_type="part_of"、confidence=1.0 的层级边，仅对有出边的 nid 建表，写回 cg._chain_adj=(bool(include_hierarchy), adj) 后返回 adj；
 def adjacency(cg, include_hierarchy=True):
     """出邻接表：nid → [(target_id, edge_dict)]。
 
@@ -146,6 +158,7 @@ def adjacency(cg, include_hierarchy=True):
     return adj
 
 
+# 生效条件：调用即把 cg._chain_adj 置为 None（赋值抛异常时静默忽略），无返回值；
 def invalidate_cache(cg):
     """写入/删除节点后丢弃邻接缓存（与 subgraph.invalidate_cache 成对调用）。"""
     try:
@@ -154,6 +167,7 @@ def invalidate_cache(cg):
         pass
 
 
+# 生效条件：对 adj 的每个 src→[(tgt, e)] 逐条把 (src, e) 追加到 rev[tgt]（同 tgt 多次追加保持出现顺序），adj 为空字典时 rev 为空字典并返回；
 def _reverse(adj):
     rev = {}
     for src, outs in adj.items():
@@ -162,6 +176,7 @@ def _reverse(adj):
     return rev
 
 
+# 生效条件：start_id 起步迭代 DFS——max_depth 非 None 时先钳为 max(0, min(int(max_depth), MAX_DEPTH_HARD))，rels 为 (relation_types or ()) 的小写元组（None 或空则不作类型过滤），direction=="in" 时邻接表改用 _reverse(adjacency(cg, include_hierarchy))，每跳要求 rel∈rels（rels 非空时）、tgt 不在 seen、weight*edge_weight(e) ≥ min_weight，链在 max_depth 为 None 或 len(hops+[hop]) ≤ max_depth 时收入、在 max_depth 为 None 或 len(hops+[hop]) < max_depth 时继续下探，首跳且边无显式条件时条件回退 start_id 的 node_conditions，扩展节点数受 max_nodes、收链数受 max_chains 限制，sort=="length" 时按 (depth, -avg_weight) 排序否则按 (-weight, -depth) 排序，返回 chains[:max_chains]；
 def walk(cg, start_id, relation_types=CAUSAL_TYPES, max_depth=MAX_DEPTH_DEFAULT,
          direction="out", max_nodes=MAX_NODES_DEFAULT, min_weight=0.0,
          max_chains=200, include_hierarchy=True, sort="strength"):
@@ -218,13 +233,18 @@ def walk(cg, start_id, relation_types=CAUSAL_TYPES, max_depth=MAX_DEPTH_DEFAULT,
                 stack.append((tgt, seen | {tgt}, nhop, nw))
         if not extended and not hops:
             continue
+    # 终键 tuple(nodes)：图遍历序取决于邻接结构的枚举序，并列（同 depth/
+    # weight/avg_weight）时若无终键，截断结果随索引构建路径漂移。
     if sort == "length":            # 对齐 AEIS infer_causal_paths 的 Occam 偏好
-        chains.sort(key=lambda c: (c["depth"], -c["avg_weight"]))
+        chains.sort(key=lambda c: (c["depth"], -c["avg_weight"],
+                                   tuple(c["nodes"])))
     else:
-        chains.sort(key=lambda c: (-c["weight"], -c["depth"]))
+        chains.sort(key=lambda c: (-c["weight"], -c["depth"],
+                                   tuple(c["nodes"])))
     return chains[:max_chains]
 
 
+# 生效条件：kw 未含 relation_types 时先注入 CAUSAL_TYPES，再以 walk(cg, start_id, **kw) 的每条链逐跳渲染（跳条件为空串则显示「（未声明条件）」），返回 {"start": start_id, "count": 渲染链数, "chains": rendered}；
 def explain(cg, start_id, **kw):
     """人类可读的链式解释：「什么条件下 → 发生什么」。"""
     kw.setdefault("relation_types", CAUSAL_TYPES)
@@ -242,6 +262,7 @@ def explain(cg, start_id, **kw):
     return {"start": start_id, "count": len(rendered), "chains": rendered}
 
 
+# 生效条件：seeds 为 dict 时取其 items、否则取 list(seeds or [])（假值 seeds 得空列表，返回空 best），逐 (sid, s0) 跳过 sid 为假值或 float(s0) 抛 TypeError/ValueError 的项，对 walk(cg, sid, relation_types, max_depth, max_nodes, max_chains, include_hierarchy) 每条链取 nodes[-1] 为 nid（nid==sid 则跳过）并按 s0*链 weight*decay^depth 对每个 nid 只保留最高分，返回 best；
 def expand_from_seeds(cg, seeds, relation_types=CHAIN_TYPES_DEFAULT,
                       max_depth=MAX_DEPTH_DEFAULT, decay=0.9,
                       max_nodes=MAX_NODES_DEFAULT, max_chains=500,
@@ -277,4 +298,4 @@ def expand_from_seeds(cg, seeds, relation_types=CHAIN_TYPES_DEFAULT,
             if cur is None or sc > cur["score"]:
                 best[nid] = {"score": round(sc, 6), "chain": c,
                              "depth": c["depth"], "conditions": c["conditions"]}
-    return best
+    return best