@furongjun1999/dsh-memory 0.4.7 → 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
@@ -350,8 +416,10 @@ def normalize_en(text: str) -> str:
 # **评测侧**改用 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"
 
@@ -493,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()
 
     # ---------- 索引（派生物，可重建） ----------
 
@@ -510,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
@@ -537,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))
@@ -596,12 +677,19 @@ class MdCG:
                         "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"),
@@ -722,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)
@@ -759,6 +882,11 @@ class MdCG:
             "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)
@@ -771,6 +899,32 @@ 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 真源的唯一正路）。
     #
@@ -1077,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,
@@ -1247,7 +1421,7 @@ class MdCG:
     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,
-               session=None):
+               session=None, branch=None):
         """返回 (results, meta)。results = [(node_dict, score, qualification)]。
 
         meta 含 tier（性能层级）、scanned（读取节点数）、bucket（路由桶）、candidates。
@@ -1275,7 +1449,10 @@ class MdCG:
         # 默认排除掉负记忆层的节点进入正排打分，仅作为「覆盖标记」用
         entries = [e for e in self.index["nodes"].values()
                    if (not layer or e["layer"] == layer)
-                   and (not session or e.get("session") == session)]
+                   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}
 
@@ -1334,26 +1511,30 @@ class MdCG:
                     return out
 
         # T2：跨桶 LIKE（§七 截断点：分池截断，索引类不再挤掉知识类）
+        # 截断依据=相关度（先全量打分再排序截断）：命中集沿 entries（目录枚举序）
+        # 排列，原来「取前 GLOBAL_CAP 条再打分」等价于用写入顺序抽签决定谁进
+        # 候选池。cap 值不变，变的只是拿什么排序（见 cut_by_relevance）。
         docs_all = self._read_many(entries, stat)
         # 语义资格（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,
@@ -1461,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 大域收敛结果 + 完整打分明细（白箱可审计）
@@ -1599,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 篇：
@@ -1622,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"])