@furongjun1999/dsh-memory 0.4.6 → 0.4.8

package/md_cg/mdcg.py

@@ -20,10 +20,13 @@ import os
 import re
 import json
 import time
+import atexit
+import weakref
 import hashlib
 import threading
 
-from . import nodefile, protect, routing, subgraph, chain, provenance, pooling
+from . import (nodefile, protect, routing, subgraph, chain, provenance, pooling,
+               lifecycle)
 from .fsutil import (FileLock, ShardedLog, atomic_write, append_jsonl,
                      read_jsonl, sweep_stale_temps)
 
@@ -57,6 +60,69 @@ DEFAULT_RECENT_WINDOW = 200
 # 全量回退的读取上限，对齐 sqlite 版 `ORDER BY importance DESC, created_at DESC LIMIT 500`
 GLOBAL_CAP = 500
 
+# ---------- 索引持久化 · 进程退出兜底（2026-09-16 取证） ----------
+# 脏索引（`_dirty`）靠调用方显式 flush()/close() 落分片日志。一次性脚本/CLI
+# （review_cli、backfill、migrate_* 等）写入 1~2 条后直接退出，未达 autoflush(64)
+# 阈值 → 日志无记录；而**已有 `_index.json` 的根重开时不重扫目录**，于是节点
+# 「在盘上但索引无条目」：其它进程与重载后的长驻进程都检索不到，只能靠某次全量
+# rebuild_index() 偶然救回（首例=审核裁决通路，见 mdcos.review_decide）。
+# 兜底语义（刻意收窄）：**正常进程退出时**对所有存活实例补一次 close()——
+# 幂等（`_dirty` 为空即 no-op）、不改变正常路径行为、不替代显式收尾
+# （异常退出 / 被 kill 仍须调用方自己保证）。WeakSet 不阻止实例回收。
+_LIVE_CGS = weakref.WeakSet()
+_ATEXIT_HOOK = None
+
+
+def _atexit_flush_all():
+    """进程退出兜底：把仍存活实例的脏索引落盘（异常吞掉——退出路径不该再抛）。"""
+    for cg in list(_LIVE_CGS):
+        try:
+            cg.close()
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def _register_atexit_hook():
+    global _ATEXIT_HOOK
+    if _ATEXIT_HOOK is None:
+        atexit.register(_atexit_flush_all)
+        _ATEXIT_HOOK = _atexit_flush_all
+    return _ATEXIT_HOOK
+
+
+def cut_by_relevance(docs, scored, total, pools=None, key_of=None, stat=None):
+    """候选截断：**先按相关度排序，再截断到 `total`**（截断依据=相关度）。
+
+    动机（真库实测 2026-09-16，11521 节点 / cap=500）：原实现是「LIKE 命中集
+    沿 `entries`（目录枚举序）取前 `total` 条 → 再打分」——命中集超上限时，
+    等价于用**写入顺序抽签**决定谁进候选池。实测 40 个抽样查询中 27 个命中数
+    超 cap（最差 10963/11073 ≈ 99%），被现状丢弃的候选平均分 0.650、被保留的
+    平均分 0.340，gold 进 top10 由 19/40 降至 29/40。
+
+    本函数把 cap 语义从「候选生成上限」降级为「输出上限」：候选质量责任交还
+    排序（与 `mdcos._lexical` 同源先例一致），**cap 值本身不变**。
+
+    `docs` 与 `scored` 必须同序同长（`MdCG._score` 输出序=输入序）。不一致时
+    不猜：退回原序截断，并在 `stat["cut_order"]` 标 `insert_fallback` 供审计。
+    分池生效时在**分数序**内按池额度截断（池内原序=分数序）。
+    返回 `(picked, report)`。
+    """
+    if len(scored) != len(docs):
+        if stat is not None:
+            stat["cut_order"] = "insert_fallback"
+        return pooling.cut_report(docs, total, pools=pools,
+                                  key_of=key_of or pooling.doc_key)
+    order = sorted(
+        range(len(docs)),
+        key=lambda i: (-float(scored[i][1]),
+                       -float(scored[i][0]["frontmatter"].get("importance") or 0),
+                       -float(scored[i][0]["frontmatter"].get("created_at") or 0)))
+    ranked = [docs[i] for i in order]
+    if stat is not None:
+        stat["cut_order"] = "relevance"
+    return pooling.cut_report(ranked, total, pools=pools,
+                              key_of=key_of or pooling.doc_key)
+
 # 条件论「观测时间」栏的默认观测窗口（秒）：调用方未提供 time_window 时，
 # 以写入时刻为锚开一个 1 小时窗口（与 AEIS 既有约定一致）。
 OBSERVATION_WINDOW_SEC = 3600.0
@@ -110,8 +176,96 @@ STATE_BLINDSPOT = "BLINDSPOT"     # 无法建立可靠归属，停止猜测
 VERIFICATION_BASIS = nodefile.VERIFICATION_BASIS
 
 
+# 英→中语素召回中的代词黑名单（超泛词，进召回词只添噪声）
+_EN_ZH_PRONOUNS = {"我", "你", "他", "她", "它", "我们", "你们", "他们"}
+
+
+def semantic_on() -> bool:
+    """语义摘要路开关（MDCG_SEMANTIC=1，默认关闭零回归）。
+
+    开启时两件事生效（设想「摘要作为检索面」的两层）：
+    1. 候选资格：fm.semantic 节点无条件进入 LIKE 候选池（否则摘要层只在
+       LIKE 全空时才生效，形同虚设——e2e 实证：干扰文档的弱词法 2-gram
+       碰撞会把 gold 挡在打分池外）；
+    2. 打分面：_score 组合窗口共现分与词法分 max 聚合。
+    老库（节点无 semantic 字段）行为逐位不变。
+    """
+    return os.environ.get("MDCG_SEMANTIC") == "1"
+
+
+def en_zh_terms(text: str) -> list:
+    """原子级中英归一 v1（2026-09-13 管线接入）：英文词 → 中文语素召回词。
+
+    依据：英文 query 词面与中文语料零重叠（bench6 实测英文 hit@1 41% vs 中文 95%
+    的主因），形态归一（normalize_en）救不了跨语——beef 与「牛肉」无任何共享字符。
+    语义.en_normalizer 词表映射（时态归零→停用词剔除→英→中语素/复合词映射→
+    专有词保留）产出中文检索键，直接命中中文正文。
+
+    约束（与 cn_recall_grams 同模式）：
+      - 本函数只扩召回（terms/LIKE 资格）；打分侧由 en_zh_bigrams 显式负责
+        （search/_lexical 三处 qb 均已补充），两者同受 MDCG_EN_ATOMS 开关控制；
+      - 默认关闭（MDCG_EN_ATOMS=1 显式开启）：md_cg 主链路英文检索走
+        独立归一化原子+Jaccard 路（REPRODUCE.md 双语双路裁定，md_cg
+        char-bigram 管线跑英文实测比独立方案差 25% vs 52%），本集成为
+        opt-in 实验能力与 soul hub 序列化出口，不在默认链路生效；
+      - 仅当 query 含英文字母时触发，纯中文 query 零开销零变化；
+      - 代词语素剔除（我/你/他…超泛词防污染），动词/名词单字语素保留
+        （「吃/雨」在中文正文检索价值高，_score 终排兜底精度）；
+      - semantic 模块缺失时静默降级（不阻断主链路）。
+    词表未覆盖词保留原名（unknown_keep），是词表边界而非错误。
+    """
+    if os.environ.get("MDCG_EN_ATOMS", "0") != "1":
+        return []
+    if not re.search(r"[A-Za-z]", text or ""):
+        return []
+    try:
+        from .semantic.en_normalizer import normalize_en_query
+        terms, _detail = normalize_en_query(text)
+    except Exception:
+        return []
+    # 专有词/未知词保留原名是序列化语义；作为检索键必须统一小写
+    # （与 normalize_en 口径一致，避免大小写敏感 LIKE 意外命中）
+    return [t.lower() for t in terms
+            if t and (len(t) >= 2 or t not in _EN_ZH_PRONOUNS)]
+
+
+def en_zh_bigrams(text: str) -> set:
+    """英→中语素的打分侧补充：中文语素进 query bigram 集合。
+
+    背景：en_zh_terms 只扩 LIKE 召回资格，而 _score/_lexical 的词法分
+    = lexical_sim(qb, doc_bigrams)——英文 bigram 与中文文档恒零交集
+    （跨语场景词法分全 0、排序退化到扫描序，2026-09-13 端到端实测）。
+    「牛肉/昨天」等中文语素本身是合法 bigram，补进 qb 后与中文正文
+    bigram（牛肉面→{牛肉,肉面}）正常相交，词法分恢复区分度。
+
+    拼接升级（2026-09-14 盲测实证）：单字语素（马/肉/油…）被 len>=2
+    过滤后打分侧仍空集→跨语词法分恒 0→top5 全为 0 分扫描序干扰
+    （bench_blind_comp：词表补齐后 hit@1 反而 36.4%→27.3%，证明基线
+    命中全靠小候选集扫描序运气而非排序能力）。现把相邻中文语素按
+    query 词序拼接成 char-bigram（[马,肉]→「马肉」），与本仓主链路
+    char-bigram 口径同构（英文 query 译中文串再取 bigram）。
+    噪声边界：跨语素拼接 bigram（吃牛肉→「吃牛」「肉昨」）可与语义
+    相邻文档假相交，由 Jaccard 分母稀释，_score 终排兜底精度。
+
+    纯中文 query 零变化（en_zh_terms 不触发）；与 en_zh_terms 同受
+    MDCG_EN_ATOMS 开关控制（默认关闭）。
+    """
+    terms = en_zh_terms(text)
+    grams = {t for t in terms if len(t) >= 2}
+    # 相邻中文语素拼接：query 词序即语素序（horse meat→马 肉→「马肉」）
+    zh_seq = [t for t in terms if t and all("\u4e00" <= ch <= "\u9fff" for ch in t)]
+    joined = "".join(zh_seq)
+    grams |= {joined[i:i + 2] for i in range(len(joined) - 1)}
+    return grams
+
+
 def expand_query_terms(query: str) -> list:
-    """与 aeis.core 同实现：整句 + 分词（≥2字符）+ 同义词组展开。"""
+    """与 aeis.core 同实现：整句 + 分词（≥2字符）+ 同义词组展开 + 英文归一化
+    + 英→中语素召回扩展（en_zh_terms，MDCG_EN_ATOMS=1 开启，默认关）。"""
+    # 原子级中英归一：在 normalize_en 之前取（专有词首字母大写判断依赖原始形态）
+    _en_zh = en_zh_terms(query)
+    # 英文归一化（中文不动；小写化+去停用词+去时态复数）
+    query = normalize_en(query)
     terms = [query]
     for w in re.split(r"[\s、，。；：,;.:/\\|]+", query):
         w = w.strip()
@@ -122,6 +276,14 @@ def expand_query_terms(query: str) -> list:
             if w in query:
                 terms.extend(g for g in group if g not in terms)
                 break
+    # 构词法 v1：中文连续串 2-gram 召回扩展（只增召回，不改打分口径）
+    for g in cn_recall_grams(query):
+        if g not in terms:
+            terms.append(g)
+    # 原子级中英归一 v1：英→中语素召回扩展（与 cn_recall_grams 同模式：只增召回）
+    for t in _en_zh:
+        if t not in terms:
+            terms.append(t)
     return list(dict.fromkeys(terms))
 
 
@@ -132,6 +294,115 @@ def bigrams(s: str) -> set:
     return {s[i:i + 2] for i in range(len(s) - 1)}
 
 
+# 中文高频功能 bigram（召回扩展时剔除：纯语法组合，召回价值低、噪音高）
+CN_STOP_GRAMS = {
+    "的了", "是一", "的在", "有个", "就是", "不是", "没有", "这个", "那个",
+    "我们", "你们", "可以", "一个", "的话", "来说", "关于", "对于", "还是",
+}
+
+
+def cn_recall_grams(query: str, min_run: int = 4, cap: int = 16) -> list:
+    """构词法 v1 · 中文召回扩展：把连续中文串切成 2-gram 作为额外召回键。
+
+    背景（2026-09-13 诊断）：expand_query_terms 对无标点中文查询只产出「整句」
+    一个召回词，而 _like 要求正文原样包含整句才给召回资格 —— 导致「抑制剂怎么选」
+    无法召回含「酪氨酸激酶抑制剂」的节点（部分中文无法词匹配的机制断点）。
+
+    约束：只扩召回，不改打分口径（bigrams(q) 的 _score 不变）；纯标准库，零依赖；
+    仅当中文连续串 ≥ min_run 字时触发（短词本身已是召回词，无需扩展）。
+    """
+    if os.environ.get("MDCG_CN_GRAMS") == "0":   # A/B 开关：关闭即回退旧行为
+        return []
+    out = []
+    for run in re.findall(r"[\u4e00-\u9fff]{%d,}" % max(min_run, 2), query or ""):
+        for i in range(len(run) - 1):
+            g = run[i:i + 2]
+            if g in CN_STOP_GRAMS or g in out:
+                continue
+            out.append(g)
+            if len(out) >= cap:
+                return out
+    return out
+
+
+# ---- 英文归一化（与中文 cn_recall_grams 对称的英文预处理）----
+# 设计者裁定：大小写统一转小写；停用词（the 等）不能拆成 bigram 参与匹配；
+# 时态/复数归零（walked→walk, pets→pet），与语义层原子化原则一致。
+EN_STOPWORDS = frozenset({
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "do", "does", "did", "have", "has", "had", "will", "would", "could",
+    "should", "may", "might", "of", "to", "in", "on", "at", "for", "with",
+    "by", "from", "up", "about", "into", "over", "after", "and", "or",
+    "but", "not", "no", "so", "if", "then", "than", "also", "very",
+    "what", "which", "who", "how", "why", "when", "where",
+    "this", "that", "these", "those", "it", "its", "as", "there",
+    "i", "me", "my", "we", "our", "you", "your", "he", "him", "his",
+    "she", "her", "they", "them", "their",
+})
+
+EN_IRREGULAR = {
+    "ate": "eat", "eaten": "eat", "went": "go", "gone": "go",
+    "saw": "see", "seen": "see", "wrote": "write", "written": "write",
+    "took": "take", "taken": "take", "made": "make", "ran": "run",
+    "bought": "buy", "brought": "bring", "thought": "think",
+    "taught": "teach", "caught": "catch", "sought": "seek",
+    "fought": "fight", "sold": "sell", "told": "tell", "felt": "feel",
+    "fell": "fall", "sent": "send", "spent": "spend", "built": "build",
+    "lost": "lose", "met": "meet", "paid": "pay", "led": "lead",
+    "won": "win", "sat": "sit", "stood": "stand",
+    "understood": "understand", "heard": "hear",
+    "spoke": "speak", "spoken": "speak", "broke": "break", "broken": "break",
+    "chose": "choose", "chosen": "choose", "drew": "draw", "drawn": "draw",
+    "drove": "drive", "driven": "drive", "grew": "grow", "grown": "grow",
+    "knew": "know", "known": "know", "gave": "give", "given": "give",
+    "was": "be", "were": "be", "been": "be", "had": "have", "has": "have",
+    "did": "do", "done": "do", "said": "say", "got": "get",
+    "left": "leave", "kept": "keep", "held": "hold",
+    "slept": "sleep", "swept": "sweep", "meant": "mean",
+    "dealt": "deal", "lent": "lend", "bent": "bend",
+}
+
+def strip_tense_en(w: str) -> str:
+    """英文时态/复数归零（保守策略：宁可少剥不可误剥）"""
+    if w in EN_IRREGULAR:
+        return EN_IRREGULAR[w]
+    # -ous 结尾 = 形容词不是复数（courageous/famous/various）
+    if w.endswith("ous") or w.endswith("us") or w.endswith("is"):
+        return w
+    if w.endswith("ing") and len(w) > 5:
+        return w[:-3]
+    if w.endswith("ed") and len(w) > 4:
+        return w[:-2]
+    if w.endswith("ies") and len(w) > 4:
+        return w[:-3] + "y"
+    # -es 只剥真复数（boxes→box, watches→watch），不剥 motivates→motivate
+    if re.search(r'(ch|sh|ss|x|z)o?es$', w) and len(w) > 4:
+        return w[:-2]
+    # -s 剥离（motivates→motivate, pets→pet）
+    if w.endswith("s") and not w.endswith("ss"):
+        return w[:-1]
+    return w
+
+def normalize_en(text: str) -> str:
+    """英文归一化：小写 + 去停用词 + 去时态复数。中文部分不动。
+
+    设计者裁定：
+      - 大小写统一转小写匹配
+      - 停用词（the 等）不能拆成 bigram 参与匹配（整词剔除）
+      - 时态/复数归零（walked→walk, pets→pet）
+    """
+    # 清标点（保留中文字符和空格和数字）
+    cleaned = re.sub(r'[^\u4e00-\u9fff a-zA-Z0-9]', ' ', text or "")
+    def _norm_word(m):
+        w = m.group(0).lower()
+        if w in EN_STOPWORDS:
+            return ""
+        return strip_tense_en(w)
+    result = re.sub(r'[a-zA-Z]{2,}', _norm_word, cleaned)
+    result = re.sub(r'\s+', ' ', result).strip()
+    return result
+
+
 # 词法相似度口径（二元组集合）：
 #   legacy  = |q ∩ d| / |q|      只归一化**查询侧** → 长文档天然占优（既有基线）。
 #                                 LongMemEval-S 长 turn 上把证据挤出 Top-5：
@@ -145,8 +416,10 @@ def bigrams(s: str) -> set:
 # **评测侧**改用 eval_common.use_jaccard() 显式注入——长 turn 语料上
 # precise 0%→8.97% / temporal 0%→6.77% / interference 1.28%→20.51% /
 # reference 0%→3.76%（与 Rust mdcg-eval --score jaccard 逐位一致）。
-# 主库不切：短条目语料上 jaccard 会退化（test_p17_predict G4——可预测锚点
-# 由因果起点 a 错配到语义邻居 x），收益随文档长度单调增长。
+# 主库不切：收益随文档长度单调增长，短条目语料上无增益（该语料本无长度偏置）。
+# 另注：test_p17_predict G4 曾出现的「可预测锚点由因果起点 a 错配到语义邻居 x」
+# 已由 predict.anchor_from_description 的**可起推资格**修复（2026-09-16，出边
+# 非空优先），锚点漂移不再是切换打分口径的理由；口径切换仍按上列数据收益决定。
 SCORE_MODES = ("legacy", "jaccard")
 SCORE_MODE = os.environ.get("MDCG_SCORE_MODE") or "legacy"
 
@@ -288,6 +561,9 @@ class MdCG:
         self._log = None
         self.index = self._load_index()
         sweep_stale_temps(self.root)
+        # 进程退出兜底登记（见模块级 _LIVE_CGS）：一次性脚本漏收尾时索引仍能落盘。
+        _LIVE_CGS.add(self)
+        _register_atexit_hook()
 
     # ---------- 索引（派生物，可重建） ----------
 
@@ -305,7 +581,13 @@ class MdCG:
             idx = {"schema": SCHEMA, "nodes": self._scan_nodes(), "buckets": {}}
         for rec in ShardedLog.read_all(self.index_log_dir):
             nid, e = rec.get("id"), rec.get("e")
-            if nid and e:
+            if not nid:
+                continue
+            if e is None:
+                # 删除记录（tombstone）：删除必须能重放，否则已删节点会在下次
+                # 启动时从旧记录里复活成**幽灵条目**（索引有条目、文件不存在）。
+                idx["nodes"].pop(nid, None)
+            else:
                 idx["nodes"][nid] = e
         idx["buckets"] = self._count_buckets(idx["nodes"])
         return idx
@@ -332,7 +614,11 @@ class MdCG:
                     pass
             for rec in ShardedLog.read_all(self.index_log_dir):
                 nid, e = rec.get("id"), rec.get("e")
-                if nid and e:
+                if not nid:
+                    continue
+                if e is None:              # 删除记录（tombstone），见 _load_index
+                    idx["nodes"].pop(nid, None)
+                else:
                     idx["nodes"][nid] = e
             idx["buckets"] = self._count_buckets(idx["nodes"])
             atomic_write(self.index_path, json.dumps(idx, ensure_ascii=False))
@@ -381,18 +667,29 @@ class MdCG:
                     parent = os.path.basename(dirpath)
                     nodes[nid] = {
                         "path": rel, "layer": fm.get("layer", layer),
+                        # role 必须回填：它写在节点 frontmatter 里（写入时 role or "user"），
+                        # 但索引重建时若不复制，os.roles 会全部退化为 (none)，
+                        # 来源归因打分随之失效（实测 48 条全丢）。
+                        "role": fm.get("role"),
                         "tags": fm.get("tags", []),
                         "bucket": parent if parent != layer else None,
                         "importance": fm.get("importance", 0.5),
                         "created_at": fm.get("created_at", 0),
                         "verification_basis": fm.get("verification_basis"),
                         "has_neg_conditions": nodefile.has_non_applicable(content),
-                        "content_hash": hashlib.sha256(
-                            content.encode("utf-8")).hexdigest()[:12],
+                        # 内容指纹走 nodefile 的唯一实现（两段式对账依赖同一算法）
+                        "content_hash": nodefile.content_hash(content),
                         # 时空字段入索引快照：STG 查询免读文件（大域/目录索引的延伸）
                         "temporal": fm.get("temporal"),
                         "spatial": fm.get("spatial"),
                         "time_window": (fm.get("condition_space") or {}).get("time_window"),
+                        # 生命周期状态（② 显式状态机）：索引入快照 → 免读文件可查，
+                        # 写入路径也因此无需读盘就能校验迁移合法性。重建口径与
+                        # _stage 一致（旧库无该字段 → None → state_of 视为 active）。
+                        lifecycle.STATE_FIELD: fm.get(lifecycle.STATE_FIELD),
+                        # 记忆演化分支（④）：重建口径与 _stage 一致
+                        "branch_id": fm.get("branch_id"),
+                        "branched_from": fm.get("branched_from"),
                         "evidence_count": fm.get("evidence_count", 0),
                         # 嵌套子图 / 关系边入索引快照：递归展开与链式遍历免读文件
                         "subgraph": fm.get("subgraph"),
@@ -427,7 +724,7 @@ class MdCG:
             non_applicable_conditions=None, override: bool = False,
             consistency: bool = False, on_conflict: str = "reject",
             derived_from=None, relation: str = provenance.DEFAULT_RELATION,
-            **extra) -> str:
+            semantic: str = None, **extra) -> str:
         """写入一个节点。
 
         verification_basis: 外部验证基底（白箱信任的硬门槛），
@@ -442,6 +739,12 @@ class MdCG:
                      frontmatter（单一真相源）并追加派生边到 <root>/_link.jsonl；
                      **建链失败不阻断本次写入**（降级为告警 + .fail 台账留痕）。
         relation: 派生关系名，默认 "derived_from"；允许值见 provenance.RELATIONS。
+        semantic: 标准语义摘要（空格分隔的标准原子序列，如「鱼 油」）——
+                  **AI 写入侧归一**的产物（使用者设想 2026-09-14：归一主体是
+                  AI，系统只供词表真源 atoms.json + OOV 审计）。落 fm.semantic
+                  衍生层，正文原文无损；OOV token 记 fm.semantic_oov 警告不拒绝
+                  （词表覆盖有限，拒绝会堵死合法写入）。检索面经
+                  MDCG_SEMANTIC=1 开启组合共现打分（mdcg._score）。
         """
         if layer not in LAYERS:
             raise ValueError(f"未知层：{layer}（允许：{LAYERS}）")
@@ -469,6 +772,17 @@ class MdCG:
                 "emotional": (vd.get("emotional") or {}).get("bias"),
                 "unresolved_id": vd.get("unresolved_id")}
         tags = list(tags or [])
+        # 标准语义摘要（semantic/canonical.py：词表真源 + OOV 审计，警告不拒绝）。
+        # 语义校验失败不阻断写入（与 derived_from 建链降级同风格）。
+        if semantic is not None:
+            extra["semantic"] = str(semantic)
+            try:
+                from .semantic import canonical as _canon
+                _oov = _canon.oov_of(str(semantic))
+                if _oov:
+                    extra["semantic_oov"] = _oov
+            except Exception:
+                pass
         bucket = None
         d = os.path.join(self.root, layer)
         if layer in BUCKETED_LAYERS:
@@ -496,6 +810,41 @@ class MdCG:
             "evidence_count": 0, "positive_evidence": 0, "negative_evidence": 0,
         }
         fm.update(extra)
+        # 生命周期状态（② 显式状态机，真源 `lifecycle.py`）：add 是**全量重建
+        # fm** 而非增量更新，故必须显式处理状态——否则已定型/已降权节点会被静默
+        # 打回 active（与 ④ rewrite 必须重传 branch_id 同构的坑）。口径：
+        #   · 新节点：显式落 active（不再依赖「缺省即 active」的隐式约定）；
+        #   · 覆写既有节点：**继承旧状态**；显式传入 state 时走迁移裁决，非法迁移
+        #     **拒绝**（负路由：抛 TransitionError，与非法层名同风格）。
+        # 取旧状态优先读**索引快照**（免读盘）；索引缺该键（升级前的旧库）才回读
+        # 节点文件兜底——不兜底会把存量 converged/demoted 节点误判成 active。
+        prev_entry = (self.index.get("nodes") or {}).get(node_id)
+        prev_state = lifecycle.state_of(prev_entry)
+        if prev_entry and lifecycle.STATE_FIELD not in prev_entry:
+            prev_state = lifecycle.state_of(
+                (self.get(node_id) or {}).get("frontmatter"))
+        # 显式入口兼容两种写法：`state=`（调用方直觉）与 `lifecycle_state=`。
+        # `state` 必须 **pop 掉**——该键名已属裁决四态（ACCEPT/REJECT/DEFER/
+        # BLINDSPOT），落进 frontmatter 只会在读面制造同名歧义；归一到真字段名后
+        # 再走同一裁决。两者同时给出时以 `lifecycle_state=` 为准（字段名更明确）。
+        _alias = fm.pop("state", None)
+        want_state = fm.get(lifecycle.STATE_FIELD)
+        if want_state is None:
+            want_state = _alias
+        if want_state is None:
+            fm[lifecycle.STATE_FIELD] = prev_state
+        else:
+            # 受保护判定取**索引快照**（兼具两层含义）：本次 fm 里的保护标记、以及
+            # 节点**既有**的保护（快照带 protected/immutable）。只看本次 fm 会漏掉
+            # 「既有受保护节点被覆写时降级」——保护 = 不可遗忘，不因一次 add 失守。
+            # 注：该参数只在降级迁移上生效（check 内按方向判定），回升不受限。
+            _pe = prev_entry or {}
+            lifecycle.require_transition(
+                prev_state, want_state,
+                protected=bool(fm.get("protected") or fm.get("immutable")
+                               or _pe.get("protected") or _pe.get("immutable")),
+                override=override)
+            fm[lifecycle.STATE_FIELD] = want_state
         # G8 派生溯源：把「来源声明」写进 frontmatter（单一真相源），台账为派生物。
         # 只声明事实、不做校验式拒绝——关系名非法仅回退默认值，不阻断写入。
         parents = provenance.as_list(derived_from)
@@ -530,6 +879,14 @@ class MdCG:
             "self_state": fm.get("self_state"),
             "derived_from": parents,
             "derived_relation": derived_rel,
+            "writer": fm.get("writer"),
+            "session": fm.get("session"),
+            "harness": fm.get("harness"),
+            # 记忆演化分支（④）：fork 副本带分支归属与溯源主支
+            "branch_id": fm.get("branch_id"),
+            "branched_from": fm.get("branched_from"),
+            # 生命周期状态（②）：索引快照透出 → 免读文件可查（与 _scan_nodes 同口径）
+            lifecycle.STATE_FIELD: fm.get(lifecycle.STATE_FIELD),
         })
         subgraph.invalidate_cache(self)
         chain.invalidate_cache(self)
@@ -542,6 +899,168 @@ class MdCG:
                               actor=extra.get("actor"))
         return node_id
 
+    def set_state(self, node_id: str, dst: str, reason: str = None,
+                  actor: str = None, override: bool = False) -> dict:
+        """节点生命周期状态推进（② 显式状态机：**唯一推进入口**，见 lifecycle.py）。
+
+        非法迁移**拒绝**（返回 `ok=False` + `error` 机器码，不抛异常——负路由）；
+        受保护节点（`protected`/`immutable`）不接受降级，需 `override=True`。
+        状态与迁移历史落 frontmatter，索引快照同步，审计追加 `_lifecycle.jsonl`。
+        """
+        return lifecycle.set_state(self, node_id, dst, reason=reason,
+                                   actor=actor, override=override)
+
+    def reconcile_writes(self, apply: bool = True, limit: int = 2000) -> dict:
+        """写入两段式对账（③ 两段式提交）：把崩溃遗留的半途写入**补账或标记**。
+
+        幂等（补出的 outcome 与正常 outcome 同形，二次扫描无未配对项）；
+        `apply=False` 为只读盘点。返回 `{"unpaired","committed","interrupted",
+        "applied","details"}`；账本为 root 下 `_write_2pc.jsonl`（append-only）。
+        """
+        from . import twophase       # 延迟导入：与写路径解耦，避免模块环
+        return twophase.reconcile(self, apply=apply, limit=limit)
+
+    def pending_writes(self, limit: int = 200) -> list:
+        """未结清的写入意图（有 intent 无 outcome）——只读，不改账本。"""
+        from . import twophase
+        return twophase.pending(self, limit=limit)
+
+    # ------------------------------------------------------------------
+    # 边域窄原语（写路径收口：白箱工具写 md 真源的唯一正路）。
+    #
+    # 三条纪律：
+    # 1. 一律经 `self.get()` 读 + `_write_node()` 写（加密形态下 get 解封、
+    #    _write_node 再封装——绕过即破坏加密）；
+    # 2. 只动边域（fm.edges / fm.subgraph.nodes），不改 content / importance /
+    #    tags 等本体字段，故不走 guard_write 写保护（保护语义=本体覆写），
+    #    但索引 entry 的 edges/subgraph 键同步更新并标 _dirty；
+    # 3. 幂等去重：append_edge 按 (target, relation_type)、append_subgraph_node
+    #    按 child_id 去重，重复追加返回 False 不落盘。
+    # ------------------------------------------------------------------
+
+    def _edge_node(self, node_id):
+        """取节点 (fm, content, full_path)；不存在返回 None。"""
+        node = self.get(node_id)
+        if not node:
+            return None
+        return (node.get("frontmatter") or {}, node.get("content") or "",
+                os.path.join(self.root, node.get("path") or f"{node_id}.md"))
+
+    def _sync_edge_entry(self, node_id, fm):
+        """边域变更后同步索引 entry（edges/subgraph 键）并标脏。"""
+        entry = self.index["nodes"].get(node_id)
+        if entry is not None:
+            entry["edges"] = fm.get("edges") or []
+            entry["subgraph"] = fm.get("subgraph")
+            self._dirty[node_id] = entry
+        try:
+            from . import subgraph as _sg
+            _sg.invalidate_cache(self)
+        except Exception:
+            pass
+
+    def append_edge(self, node_id: str, edge: dict) -> bool:
+        """向既有节点追加一条出边（fm.edges），幂等去重。
+
+        edge 形态对齐迁移语料：{"target", "relation_type", "confidence",
+        "verified", "condition_space", ...}。节点不存在返回 False。
+        """
+        got = self._edge_node(node_id)
+        if got is None:
+            return False
+        fm, content, path = got
+        edges = fm.setdefault("edges", [])
+        if not isinstance(edges, list):
+            edges = fm["edges"] = []
+        tgt = str(edge.get("target") or "")
+        rel = str(edge.get("relation_type") or "")
+        if any(str(e.get("target") or "") == tgt
+               and str(e.get("relation_type") or "") == rel
+               for e in edges if isinstance(e, dict)):
+            return False  # 幂等：同 target 同关系已存在
+        edges.append(dict(edge))
+        self._write_node(node_id, path, fm, content)
+        self._sync_edge_entry(node_id, fm)
+        return True
+
+    def append_subgraph_node(self, node_id: str, child_id: str) -> bool:
+        """向既有父节点追加层级子节点（fm.subgraph.nodes），幂等去重。
+
+        层级边（hierarchical）在 md 语料的落点即父节点 subgraph.nodes
+        （source=父，与 migrate_wisdom_graph 导出形态一致）。
+        """
+        got = self._edge_node(node_id)
+        if got is None:
+            return False
+        fm, content, path = got
+        sg = fm.get("subgraph")
+        if not isinstance(sg, dict):
+            sg = fm["subgraph"] = {"nodes": []}
+        subs = sg.setdefault("nodes", [])
+        if not isinstance(subs, list):
+            subs = sg["nodes"] = []
+        if child_id in subs:
+            return False  # 幂等
+        subs.append(str(child_id))
+        self._write_node(node_id, path, fm, content)
+        self._sync_edge_entry(node_id, fm)
+        return True
+
+    def update_tags(self, node_id: str, add=None, remove=None) -> bool:
+        """节点 tags 增删（节点状态更新窄原语——causal 候选状态迁移面）。
+
+        remove 先于 add（状态迁移语义：去旧标→加新标），去重保序；
+        无实质变更不落盘返回 False。节点不存在返回 False。
+        """
+        got = self._edge_node(node_id)
+        if got is None:
+            return False
+        fm, content, path = got
+        tags = fm.get("tags")
+        if not isinstance(tags, list):
+            tags = fm["tags"] = []
+        tags = [str(t) for t in tags]
+        rm = {str(t) for t in (remove or [])}
+        new_tags = [t for t in tags if t not in rm]
+        for t in (add or []):
+            t = str(t)
+            if t not in new_tags:
+                new_tags.append(t)
+        if new_tags == tags:
+            return False  # 幂等：无实质变更
+        fm["tags"] = new_tags
+        self._write_node(node_id, path, fm, content)
+        entry = self.index["nodes"].get(node_id)
+        if entry is not None:
+            entry["tags"] = list(new_tags)
+            self._dirty[node_id] = entry
+        return True
+
+    def set_edge_condition(self, node_id: str, target_id: str,
+                           relation_type: str, condition_space: dict) -> bool:
+        """改既有节点上指定出边的 condition_space（模式分离更新面）。
+
+        匹配 (target, relation_type) 唯一边；无匹配返回 False 不落盘。
+        """
+        got = self._edge_node(node_id)
+        if got is None:
+            return False
+        fm, content, path = got
+        edges = fm.get("edges") or []
+        hit = None
+        for e in edges:
+            if (isinstance(e, dict)
+                    and str(e.get("target") or "") == str(target_id)
+                    and str(e.get("relation_type") or "") == str(relation_type)):
+                hit = e
+                break
+        if hit is None:
+            return False
+        hit["condition_space"] = dict(condition_space or {})
+        self._write_node(node_id, path, fm, content)
+        self._sync_edge_entry(node_id, fm)
+        return True
+
     def add_rejected(self, hypothesis: str, reason: str, verification_basis: str = "test",
                      tags=None, **extra) -> str:
         """第 5 篇 L2：负记忆——失败/否决的假设库。重复证伪幂等。"""
@@ -557,14 +1076,19 @@ class MdCG:
 
     def add_unresolved(self, question: str, known_clues: str = "",
                        goal: str = "", verification_basis: str = "data",
-                       tags=None, **extra) -> str:
-        """第 5 篇 L5：未解问题清单——驱动主动探索。"""
+                       tags=None, context: str = "", **extra) -> str:
+        """第 5 篇 L5：未解问题清单——驱动主动探索。
+
+        context：结构化「现场」（如「同条件两条不同取值 vs mem_A」）。
+        缺此字段时「32 / 64 哪个对」这类缺口在裁决时看不到原始对照。
+        """
         nid = f"unr_{hashlib.sha1(question.encode()).hexdigest()[:10]}"
         if nid in self.index["nodes"]:
             return nid
         content = (f"# 问题：{question}\n"
                    f"# 已知线索：{known_clues or '（暂无）'}\n"
-                   f"# 目标：{goal or '（未设定）'}\n"
+                   + (f"# 现场：{context}\n" if context else "")
+                   + f"# 目标：{goal or '（未设定）'}\n"
                    f"# 验证：{verification_basis}\n")
         return self.add(nid, content, layer="unresolved",
                         tags=tags, verification_basis=verification_basis,
@@ -707,6 +1231,26 @@ class MdCG:
         if len(self._dirty) >= self.autoflush:
             self.flush()
 
+    def _unstage(self, node_id):
+        """摘除索引条目并**持久化**——与 `_stage` 对称的删除原语。
+
+        只 pop 内存索引是不够的：`close()` 注释里记过同构的坑（已有
+        `_index.json` 的根重开不重扫目录），于是「删掉的条目」会在
+        `_index_log` 重放时复活成**幽灵条目**（索引有条目、节点文件不存在）。
+        幽灵条目的代价：检索白跑候选、`ref action=prune` 因 `cg.get` 取不回
+        而够不着它，`check` 的 dangling 永不归零（本机实测累积数百条）。
+        """
+        e = self.index["nodes"].pop(node_id, None)
+        if e and e.get("bucket"):
+            b = e["bucket"]
+            left = self.index["buckets"].get(b, 0) - 1
+            if left > 0:
+                self.index["buckets"][b] = left
+            else:
+                self.index["buckets"].pop(b, None)
+        self._dirty[node_id] = None      # None = 删除记录，随 flush 落分片日志
+        self.flush()                     # 删除不可延迟到 autoflush 阈值
+
     # ---------- 内容封装钩子（默认恒等；MdCGSecure 覆盖为「私有内容加密」）----
 
     def _seal_content(self, node_id: str, content: str,
@@ -753,6 +1297,51 @@ class MdCG:
 
     # ---------- 资格判定（与性能 tier 正交）----------
 
+    @staticmethod
+    def _ccg_line(content: str, name: str) -> str:
+        """取 CCG 正文 `# <name>：` 行的值。
+
+        与 mdcos._ccg_field 同源实现——父类不得反向 import mdcos，
+        故在此落同款确定性扫描（无正则回溯风险）。
+        """
+        for line in (content or "").splitlines():
+            s = line.strip()
+            if not s.startswith("#") or name not in s:
+                continue
+            body = s.lstrip("#").strip()
+            for sep in ("：", ":"):
+                if sep in body:
+                    head, _, val = body.partition(sep)
+                    if head.strip() == name:
+                        return val.strip()
+        return ""
+
+    @staticmethod
+    def _cond_terms(cond_text: str):
+        """生效条件声明 → 匹配短语列表（确定性切分，无语义猜测）。
+
+        切分规则：按槽分隔「；/;」拆槽（condition_space_text 以「；」连四槽）
+        → 每槽剥「槽标签：」前缀（载体/位置、时间、方法、约束等标签是通用词，
+        参与命中必误判）→ 槽内按「，,、/（）」切短语 → 丢弃长度 <2、纯数字、
+        全时窗哨兵短语（全时窗 = 时间维无信息量，不因其未命中而降级）。
+        """
+        out, seen = [], set()
+        for slot in re.split(r"[；;]", str(cond_text or "")):
+            if "：" in slot:
+                slot = slot.split("：", 1)[1]
+            elif ":" in slot:
+                slot = slot.split(":", 1)[1]
+            for seg in re.split(r"[，,、/（）()]", slot):
+                seg = seg.strip()
+                if len(seg) < 2 or seg.isdigit():
+                    continue
+                if "全时窗" in seg or "任意时刻" in seg:
+                    continue
+                if seg not in seen:
+                    seen.add(seg)
+                    out.append(seg)
+        return out
+
     @staticmethod
     def judge_qualification(node_dict, query: str, context=None):
         """四态判定（白箱第 1/2 篇）。
@@ -764,8 +1353,10 @@ class MdCG:
         - BLINDSPOT：节点 MARKS 不完整（6 行缺一不可；生效条件不可隐含，
           必须由条件空间四槽合成显式声明）→ 无法建立可靠归属，停止
         - REJECT：不适用条件命中 → 明确不适用
-        - DEFER：条件不足但缺的不是不适用条件，是适用条件未声明 → 可继续寻找
-        - ACCEPT：条件满足（默认）
+        - DEFER：生效条件未在情境（query+context）词面确认，或未声明验证基底
+          → 可继续寻找/补证据
+        - ACCEPT：条件满足（生效条件已确认，或无情境可比——此时 reason 诚实
+          标注「未做正条件确认」，不冒充已确认）
         """
         fm = node_dict.get("frontmatter") or {}
         content = node_dict.get("content") or ""
@@ -776,27 +1367,61 @@ class MdCG:
             return {"state": STATE_BLINDSPOT,
                     "reason": f"CCG 要素不全：缺 {set(nodefile.CCG_REQUIRED) - set(cpl['required_present'])}"}
 
+        # 情境合成（query + context）：正/负条件共用同一情境口径。
+        # 负条件扩面依据（2026-09-12）：不适用条件的语义是「本节点明确不适用
+        # 于这类问句」，问句（query）是情境的一半——只看 context 时「我没喝水」
+        # 声明的负条件「刚才在干什么」在同类问句下永不命中，否定事件得以冒充
+        # 事件。扩面已过全量回归（test_p33 负条件断言保绿：其词面本就命中）。
+        scene = {"query": query or ""}
+        if isinstance(context, dict):
+            scene.update(context)
+        scene_str = json.dumps(scene, ensure_ascii=False)
+
         # 2) REJECT：不适用条件命中（需条件对比，简化版用关键词命中）
         neg = fm.get("non_applicable_conditions") or []
-        ctx_str = json.dumps(context or {}, ensure_ascii=False)
-        neg_hit = [n for n in neg if any(w in ctx_str for w in n.split())]
+        neg_hit = [n for n in neg if any(w in scene_str for w in n.split())]
         if neg_hit:
             return {"state": STATE_REJECT,
                     "reason": f"不适用条件命中：{neg_hit[:3]}"}
 
-        # 3) DEFER：节点无 verification_basis → 信任根基不足
+        # 3) 正条件确认：生效条件须在情境（query+context）中词面可确认——
+        #    「没发现拒绝理由」≠「确认适用」（相似度产生候选，条件授予资格）。
+        #    情境为空（无 query 且无 context）→ 无可判定依据，跳过本段不降级：
+        #    「无情境」不能被误判成「不适用」。
+        cond_hit = None
+        has_scene = bool((query or "").strip()) or bool(context)
+        if has_scene:
+            cond_text = MdCG._ccg_line(content, "生效条件")
+            if not cond_text and fm.get("condition_space"):
+                cond_text = nodefile.condition_space_text(fm["condition_space"])
+            if cond_text and cond_text.strip() != "无条件":
+                terms_ = MdCG._cond_terms(cond_text)
+                cond_hit = next((t for t in terms_ if t in scene_str), None)
+                if cond_hit is None and terms_:
+                    return {"state": STATE_DEFER,
+                            "reason": ("生效条件未在情境确认（未命中任何声明条件："
+                                       + "、".join(terms_[:3])
+                                       + "）；可补充情境或条件词面后重判")}
+
+        # 4) DEFER：节点无 verification_basis → 信任根基不足
         if not fm.get("verification_basis"):
             return {"state": STATE_DEFER,
                     "reason": "未声明验证基底，需补充才能继续判定"}
 
-        # 4) ACCEPT：默认
-        return {"state": STATE_ACCEPT, "reason": "5 要素齐全 + 不适用条件未命中 + 验证基底已声明"}
+        # 5) ACCEPT：默认——reason 诚实标注正条件是否经情境确认
+        acc = "5 要素齐全 + 不适用条件未命中 + 验证基底已声明"
+        if cond_hit:
+            acc = f"生效条件已确认（命中「{cond_hit}」）+ " + acc
+        elif not has_scene:
+            acc = "无情境可比（未做正条件确认）+ " + acc
+        return {"state": STATE_ACCEPT, "reason": acc}
 
     # ---------- 检索（性能阶梯 + 资格判定）----------
 
     def search(self, query: str, layer: str = None, k: int = 20,
                context=None, min_results: int = 1, record: bool = True,
-               include_neg: bool = True, judge: bool = True, pools=None):
+               include_neg: bool = True, judge: bool = True, pools=None,
+               session=None, branch=None):
         """返回 (results, meta)。results = [(node_dict, score, qualification)]。
 
         meta 含 tier（性能层级）、scanned（读取节点数）、bucket（路由桶）、candidates。
@@ -816,12 +1441,18 @@ class MdCG:
         pool_cfg = pooling.resolve(pooling.from_env(pools))
 
         terms = expand_query_terms(q)
-        qb = bigrams(q)
+        # 英文归一化后再取 bigram（小写+去停用词+去时态；中文不动）
+        # + 英→中语素 bigram 补充（跨语词法分：纯中文零变化，MDCG_EN_ATOMS 可关）
+        qb = bigrams(normalize_en(q)) | en_zh_bigrams(q)
         # 把 rejected/unresolved 视作可参与召回的特殊「候选池」
         # ——命中它们的结果会改变 meta 的 covered_neg（被负记忆覆盖的查询）
         # 默认排除掉负记忆层的节点进入正排打分，仅作为「覆盖标记」用
         entries = [e for e in self.index["nodes"].values()
-                   if not layer or e["layer"] == layer]
+                   if (not layer or e["layer"] == layer)
+                   and (not session or e.get("session") == session)
+                   # 分支实验场：默认（branch=None）分支节点全部隐身；
+                   # branch=<id> 时主支 + 本分支可见、其他分支仍隐身
+                   and e.get("branch_id") in (None, branch)]
         if not entries:
             return [], {"tier": None, "reason": "no_candidates", "scanned": 0}
 
@@ -844,7 +1475,7 @@ class MdCG:
                     if any(t in content for t in terms):
                         neg_coverage.append(e)
 
-        stat = {"scanned": 0}
+        stat = {"scanned": 0, "query": q}
         route_bucket = None
         if context is not None:
             ctx = context if isinstance(context, dict) else {}
@@ -869,7 +1500,9 @@ class MdCG:
             in_bucket = [e for e in entries if e.get("bucket") == route_bucket]
             if in_bucket:
                 docs = self._read_many(in_bucket, stat)
-                hits = [d for d in docs if self._like(d[2], d[1], terms)]
+                # 语义资格（MDCG_SEMANTIC=1）：fm.semantic 节点无条件入池
+                hits = [d for d in docs if self._like(d[2], d[1], terms)
+                        or (semantic_on() and d[1].get("semantic"))]
                 out = try_stage(hits, TIER_BUCKET_LIKE)
                 if out:
                     return out
@@ -878,24 +1511,30 @@ class MdCG:
                     return out
 
         # T2：跨桶 LIKE（§七 截断点：分池截断，索引类不再挤掉知识类）
+        # 截断依据=相关度（先全量打分再排序截断）：命中集沿 entries（目录枚举序）
+        # 排列，原来「取前 GLOBAL_CAP 条再打分」等价于用写入顺序抽签决定谁进
+        # 候选池。cap 值不变，变的只是拿什么排序（见 cut_by_relevance）。
         docs_all = self._read_many(entries, stat)
-        hits = [d for d in docs_all if self._like(d[2], d[1], terms)]
+        # 语义资格（MDCG_SEMANTIC=1）：fm.semantic 节点无条件入池
+        hits = [d for d in docs_all if self._like(d[2], d[1], terms)
+                or (semantic_on() and d[1].get("semantic"))]
         stat["pre_cap"] = len(hits)
         stat["cap"] = GLOBAL_CAP
-        hits, _rep = pooling.cut_report(hits, GLOBAL_CAP, pools=pool_cfg,
-                                        key_of=pooling.doc_key)
+        hits, _rep = cut_by_relevance(hits, self._score(hits, q, qb, pool_cfg),
+                                      GLOBAL_CAP, pools=pool_cfg,
+                                      key_of=pooling.doc_key, stat=stat)
         pooling.record_audit(stat, _rep)
         out = try_stage(hits, TIER_GLOBAL_LIKE)
         if out:
             return out
 
-        # T3：全量兜底（同为分池截断点）
-        docs_all.sort(key=lambda d: (-float(d[1].get("importance") or 0),
-                                     -float(d[1].get("created_at") or 0)))
+        # T3：全量兜底（同为分池截断点；截断依据同为相关度，importance 作次级键）
         stat["pre_cap"] = len(docs_all)
         stat["cap"] = GLOBAL_CAP
-        picked, _rep = pooling.cut_report(docs_all, GLOBAL_CAP, pools=pool_cfg,
-                                          key_of=pooling.doc_key)
+        picked, _rep = cut_by_relevance(docs_all,
+                                        self._score(docs_all, q, qb, pool_cfg),
+                                        GLOBAL_CAP, pools=pool_cfg,
+                                        key_of=pooling.doc_key, stat=stat)
         pooling.record_audit(stat, _rep)
         scored = self._score(picked, q, qb, pool_cfg)
         return self._emit(scored, k, TIER_GLOBAL_SCAN, stat, route_bucket,
@@ -921,16 +1560,39 @@ class MdCG:
         # judge_qualification 走 REJECT，不能把节点召回。tags 仍参与匹配。
         tags = " ".join(str(t) for t in (fm.get("tags") or []))
         body = nodefile.positive_body(content)
-        return any(t in body or t in tags for t in terms)
+        # 双边小写化：英文大小写统一（中文无大小写不受影响）
+        body_l = body.lower()
+        tags_l = tags.lower()
+        return any(t in body_l or t.lower() in tags_l for t in terms)
 
     def _score(self, docs, q, qb, pools=None, mode=None):
+        # 语义摘要路（MDCG_SEMANTIC=1 opt-in，默认关闭零回归）：
+        # doc 侧 fm.semantic 标准原子序列 × query 归一序列的组合窗口共现分
+        # （semantic/canonical.pair_hits），与词法分 **max 聚合**——语义路=
+        # 候选生成器/终排器（judge_ranking 同定位），词法强时不拖累、词法
+        # 零交集（L3 盲测靶区）时独立成臂。延迟导入+异常静默降级（与
+        # en_zh_terms 同风格：semantic 模块缺失不阻断主链路）。
+        sem_on = semantic_on()
+        _pair_hits = None
+        if sem_on:
+            try:
+                from .semantic import canonical as _canon
+                _pair_hits = _canon.pair_hits
+            except Exception:
+                sem_on = False
         scored = []
         for e, fm, c in docs:
-            nb = bigrams(c)
+            # 归一化 content 后取 bigram（与 query 侧 normalize_en 对称）
+            c_norm = normalize_en(c)
+            nb = bigrams(c_norm)
             sim = lexical_sim(qb, nb, mode)
             tag_bonus = 0.05 if any(str(t) in q or q in str(t)
                                     for t in (fm.get("tags") or [])) else 0.0
-            raw = min(1.0, sim + tag_bonus)
+            if sem_on and _pair_hits is not None and fm.get("semantic"):
+                raw = min(1.0, max(sim, _pair_hits(fm["semantic"], q))
+                          + tag_bonus)
+            else:
+                raw = min(1.0, sim + tag_bonus)
             if pools:                       # §七 降权：乘数只来自显式权重表（可复算）
                 raw = max(0.0, min(1.0, raw * pooling.weight_of(
                     fm.get("id") or e["path"], e, pools)))
@@ -949,7 +1611,8 @@ class MdCG:
         out = []
         for r in results:
             if judge:
-                qual = self.judge_qualification(r[0], "", context)
+                qual = self.judge_qualification(r[0], stat.get("query") or "",
+                                                context)
             else:
                 qual = {"state": None, "reason": "judge_disabled"}
             out.append((r[0], r[1], qual))
@@ -979,6 +1642,8 @@ class MdCG:
                      "candidates": candidates,
                      # §七 分池审计：截断前候选数 / 全局额度 / 生效分池计划
                      "pre_cap": stat.get("pre_cap"), "cap": stat.get("cap"),
+                     # 截断依据审计：relevance=先打分再排序截断（现行）
+                     "cut_order": stat.get("cut_order"),
                      "pools": pool_plan,
                      "covered_neg": [nc["path"] for nc in neg_coverage],
                      # 阶段 1 大域收敛结果 + 完整打分明细（白箱可审计）
@@ -1041,6 +1706,10 @@ class MdCG:
         D = 1 - 有效命中比例，0=信息差为零（完美），1=完全空白。
 
         简化模型：本次查询的「有效命中」= score>0 且 state=ACCEPT 的比例。
+
+        口径声明（智能论3.4 §2.7.0 DEV-002a）：本值是 D_task 的
+        「检索-资格链路工程化身」——对象同一、数值不与 wisdom 四分量
+        D_norm（验证链路化身）直接互换。
         """
         if not results:
             return 1.0
@@ -1113,8 +1782,7 @@ class MdCG:
                               verification_basis="test")
             # 从原位置删除（节点进入 rejected 层）
             os.remove(os.path.join(self.root, node["path"]))
-            self.index["nodes"].pop(node_id, None)
-            self._dirty.pop(node_id, None)
+            self._unstage(node_id)      # 同上：索引删除必须可重放（防幽灵条目）
             return {"action": "falsified", "new_id": None,
                     "evidence_count": None, "demoted": None}
         # confirmed/weakened：调整 confidence（白箱第 5 篇：
@@ -1136,6 +1804,12 @@ class MdCG:
             demoted = self._move_layer(
                 node_id, "contextual",
                 reason=f"confidence {fm['confidence']} < {DEMOTE_CONFIDENCE}")
+            # 层降级 = 生命周期降级（②）：knowledge→contextual 即 state→demoted。
+            # 受保护节点已被 `guard_move` 拦在上一层（走不到这里）；此处仍按负路由
+            # 柔和处理——ok=False 只说明状态不可降，不回滚已完成的层迁移。
+            self.set_state(node_id, "demoted",
+                           reason=f"confidence {fm['confidence']} < {DEMOTE_CONFIDENCE}",
+                           actor="verify:weakened")
         else:
             self._write_node(node_id, os.path.join(self.root, node["path"]),
                              fm, node["content"])
@@ -1163,8 +1837,27 @@ class MdCG:
         question = (f"为何 {try_data.get('query','?')} 出现 {try_data.get('actual_state','?')}"
                     f" 而期望 {try_data.get('expected_state','?')}？")
         clues = try_data.get("missing", "")
+        # detail：判定器的结构化缺口（[{type, with, same_condition, ...}]）。
+        # 原先整字段被忽略——上游产出了结构却送不到下游。这里提炼为「现场」，
+        # 使条目在人工/外部裁决时能看到原始对照（如「同条件两条不同取值」）。
+        detail = try_data.get("detail") or []
+        parts = []
+        if isinstance(detail, list):
+            for d in detail:
+                if not isinstance(d, dict):
+                    continue
+                if d.get("type") == "same_condition_divergence":
+                    parts.append("同条件取值分歧 vs %s（条件重合 %s / 槽位 %s / 结论差异 %s）"
+                                 % (d.get("with"), d.get("same_condition"),
+                                    d.get("slot_overlap"), d.get("conclusion_overlap")))
+                elif d.get("type") == "condition_clash":
+                    parts.append("条件互斥 vs %s（覆盖 %s）"
+                                 % (d.get("with"), d.get("score")))
+                elif d.get("type"):
+                    parts.append("%s vs %s" % (d.get("type"), d.get("with")))
         nid = self.add_unresolved(question=question, known_clues=clues,
-                                  goal="结构精化：补缺失条件分支")
+                                  goal="结构精化：补缺失条件分支（或裁决取值）",
+                                  context=" | ".join(parts))
         return {"unresolved_id": nid, "question": question}
 
     # ---------- 访问计数：append-only，检索路径不写节点文件 ----------