@furongjun1999/dsh-memory 0.4.7 → 0.4.8

package/md_cg/mdcos.py

@@ -23,17 +23,20 @@ import json
 import os
 import re
 import time
+import uuid
 
 from .mdcg import (MdCG, expand_query_terms, bigrams, normalize_en, STATE_ACCEPT,
                    STATE_REJECT, STATE_DEFER, STATE_BLINDSPOT, TIER_BUCKET_LIKE,
                    TIER_BUCKET_SCAN, TIER_GLOBAL_LIKE, TIER_GLOBAL_SCAN,
                    GLOBAL_CAP, expand_query_terms_weighted,
-                   expand_query_terms_llm, en_zh_bigrams, semantic_on)
+                   expand_query_terms_llm, en_zh_bigrams, semantic_on,
+                   cut_by_relevance)
 from . import (nodefile, routing, chain, subgraph, forgetting, protect,
                identity, consistency, metacognition, crypto, sustain,
                self_state, predict, evolution, weights, pooling,
                writelimit)
-from .fsutil import FileLock, atomic_write, append_jsonl, read_jsonl
+from .fsutil import (FileLock, atomic_write, append_jsonl, read_jsonl,
+                     count_jsonl)
 from .security import (Principal, TenantRegistry, AccessDenied,
                        SENSITIVITY_ORDER, DEFAULT_SENSITIVITY, _rank)
 
@@ -275,6 +278,7 @@ class MdCGOS(MdCG):
         super().__init__(root, autoflush=autoflush)
         self.actor = actor
         self.audit_log = os.path.join(self.root, "_audit.jsonl")
+        self.audit_archive = os.path.join(self.root, self.AUDIT_ARCHIVE)
         self.deletions_log = os.path.join(self.root, "_deletions.jsonl")
         self.hippocampus = os.path.join(self.root, self.HIPPOCAMPUS)
         self.inbox_log = os.path.join(self.hippocampus, "inbox.jsonl")
@@ -282,6 +286,8 @@ class MdCGOS(MdCG):
         self.trash_dir = os.path.join(self.root, self.TRASH)
         os.makedirs(self.hippocampus, exist_ok=True)
         os.makedirs(self.trash_dir, exist_ok=True)
+        self._audit_writes = 0        # 进程内写入计数（轮转探测节流，稳态零 stat）
+        self._audit_index = None      # 归档索引缓存（懒加载）
 
     # ================= 6. payload-free 审计 =================
 
@@ -291,12 +297,216 @@ class MdCGOS(MdCG):
                "session": getattr(self, "session", None)}
         rec.update(meta)
         try:
+            self._rotate_audit_if_needed()
             append_jsonl(self.audit_log, rec)
         except OSError:
             pass
 
-    def audit_records(self):
-        return list(read_jsonl(self.audit_log))
+    def audit_records(self, limit: int = None):
+        """审计记录读取——轮转后跨分片按时间序（旧片在前）合并。
+
+        默认保持全量语义（既有调用方零改动）；limit=N 取尾部 N 条，供巡检使用
+        ——有界日志不该被读成新的 O(n) 全量。
+        """
+        paths = [os.path.join(self.audit_archive, n) for n in self._audit_shards()]
+        paths.append(self.audit_log)
+        if limit is None:
+            out = []
+            for p in paths:
+                out.extend(read_jsonl(p))
+            return out
+        out = []
+        for p in reversed(paths):              # 从最新往回读，读满 limit 即停
+            if len(out) >= limit:
+                break
+            out = list(read_jsonl(p)) + out
+        return out[-limit:]
+
+    # ---------- 审计日志分片轮转（治本：给无上界增长装上界） ----------
+
+    def _audit_shards(self):
+        """归档分片名，序号零填充 ⇒ 字典序 == 时间序。"""
+        try:
+            names = os.listdir(self.audit_archive)
+        except OSError:
+            return []
+        return sorted(n for n in names
+                      if n.startswith("_audit.") and n.endswith(".jsonl"))
+
+    def _load_audit_index(self) -> dict:
+        if self._audit_index is None:
+            idx = {}
+            try:
+                with open(os.path.join(self.audit_archive, self.AUDIT_INDEX),
+                          "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if isinstance(data, dict):
+                    idx = {k: v for k, v in data.items() if isinstance(v, dict)}
+            except (OSError, ValueError):
+                idx = {}                       # 索引缺失/损坏 → 空起步，自愈补数
+            self._audit_index = idx
+        return self._audit_index
+
+    def _save_audit_index(self, idx: dict):
+        try:
+            os.makedirs(self.audit_archive, exist_ok=True)
+            atomic_write(os.path.join(self.audit_archive, self.AUDIT_INDEX),
+                         json.dumps(idx, ensure_ascii=False, indent=1, sort_keys=True))
+        except OSError:
+            pass
+        self._audit_index = idx
+
+    def _rotate_audit_if_needed(self):
+        """写前闸门：活动日志达阈值即切分（把 stat 摊到 1/AUDIT_PROBE_EVERY）。
+
+        为什么不逐条 stat：写路径要付的是「每次写入税」，而活动文件由本进程与同
+        root 其它进程共同增长，故按固定间隔读一次真实元数据校准——既不漏轮转，
+        也不把 O(1) 纪律反向变成 O(n) 写入开销。
+        """
+        limit = self.AUDIT_ROTATE_BYTES
+        if limit <= 0:
+            return
+        self._audit_writes = (self._audit_writes or 0) + 1
+        if self._audit_writes % self.AUDIT_PROBE_EVERY:
+            return
+        try:
+            if os.path.getsize(self.audit_log) < limit:
+                return
+        except OSError:
+            return
+        self.rotate_audit()
+
+    def rotate_audit(self, reason: str = "size"):
+        """把活动审计日志切分为归档分片（os.replace 原子，不重写一个字节）。
+
+        语义边界（诚实面）：
+        · 分片内容与轮转前**逐行一致**（rename 不动字节）；最新记录始终在活动文件
+          `_audit.jsonl` 中——读尾部取最新记录的调用方不受轮转影响；
+        · 并发由 FileLock + 「rename 前复检大小 / 失败即返回 None」兜住：抢输的
+          进程不重复切分，也不丢记录（记录要么在旧片、要么在活动文件）；
+        · 保留策略只淘汰**分片**，且淘汰名单写进审计（不静默丢证据）。
+        """
+        with FileLock(os.path.join(self.root, "_audit.rotate.lock"), timeout=5.0):
+            try:
+                size = os.path.getsize(self.audit_log)
+            except OSError:
+                return None
+            if size < self.AUDIT_ROTATE_BYTES:
+                return None                    # 已被并发写者轮转
+            os.makedirs(self.audit_archive, exist_ok=True)
+            name = "_audit.%06d.jsonl" % self._next_shard_seq()
+            dst = os.path.join(self.audit_archive, name)
+            try:
+                os.replace(self.audit_log, dst)
+            except OSError:
+                return None                    # 抢输（文件已被移走）→ 让位，不报错
+            scale = self._audit_count_shard(dst, size)   # 分档：有界扫描 / 只读量级
+            events = scale["events"]
+            idx = self._load_audit_index()
+            idx[name] = {"bytes": size, "events": events, "exact": scale["exact"],
+                         "t": round(time.time(), 3), "reason": reason}
+            self._save_audit_index(idx)
+            pruned = self._prune_audit_shards()
+            self._audit_writes = 0
+            try:                               # 自述留痕：轮转本身可审计
+                append_jsonl(self.audit_log,
+                             {"t": time.time(), "op": "audit_rotate", "id": name,
+                              "actor": self.actor, "bytes": size, "events": events,
+                              "pruned": pruned, "reason": reason,
+                              "session": getattr(self, "session", None)})
+            except OSError:
+                pass
+            return {"shard": name, "bytes": size, "events": events, "pruned": pruned}
+
+    def _audit_count_shard(self, path, size: int = None) -> dict:
+        """分片条数读数：有界分片给精确值，超大历史分片只给量级。
+
+        为什么分档：阈值内的分片扫描是**有界**代价（≤ AUDIT_COUNT_MAX_BYTES）；但
+        历史遗留的超大文件（本机首个分片即 4.0 GB）若在轮转/体检路径上全量解析，
+        就会把「一次调用堵死整条通道」原样复现——故超阈值退回 _log_scale 元数据
+        口径并如实标注 exact=False（要精确值走离线工具，不在写路径上付 O(n)）。
+        """
+        if size is None:
+            try:
+                size = os.path.getsize(path)
+            except OSError:
+                return {"bytes": 0, "events": 0, "exact": True}
+        if size <= self.AUDIT_COUNT_MAX_BYTES:
+            return {"bytes": size, "events": count_jsonl(path), "exact": True}
+        s = self._log_scale(path)
+        return {"bytes": size, "events": s["events"], "exact": False}
+
+    def _next_shard_seq(self) -> int:
+        top = 0
+        for n in self._audit_shards():
+            try:
+                top = max(top, int(n[len("_audit."):-len(".jsonl")]))
+            except ValueError:
+                continue
+        return top + 1
+
+    def _prune_audit_shards(self):
+        """保留最近 AUDIT_KEEP_SHARDS 个分片、淘汰更旧的（≤0 表示不淘汰）。"""
+        keep = self.AUDIT_KEEP_SHARDS
+        if keep <= 0:
+            return []
+        shards = self._audit_shards()
+        gone = shards[:-keep] if len(shards) > keep else []
+        if not gone:
+            return []
+        idx = self._load_audit_index()
+        for n in gone:
+            try:
+                os.remove(os.path.join(self.audit_archive, n))
+            except OSError:
+                continue                       # 删不掉就留着：不假装已淘汰
+            idx.pop(n, None)
+        self._save_audit_index(idx)
+        return gone
+
+    def audit_scale(self) -> dict:
+        """审计面量级读数（O(1) 稳态）：活动文件实时读数 + 归档分片索引缓存。
+
+        为什么不逐片重数（第 4 条：指标与代价匹配）：轮转后「总计」= 活动 + 各分片，
+        逐片全量数会把体检摊成 O(分片总字节)。分片是**封存文件**（内容不再变），故
+        封存时数一次、落索引缓存即得稳态 O(1)；目录里出现未登记分片（外部手工放入）
+        时自愈补数一次——绝不假装与磁盘一致。
+        """
+        active = self._log_scale(self.audit_log)
+        present = self._audit_shards()
+        idx = self._load_audit_index()
+        healed = False
+        for n in present:
+            if n in idx:
+                continue
+            p = os.path.join(self.audit_archive, n)
+            try:
+                sc = self._audit_count_shard(p)       # 分档：有界扫描 / 只读量级
+                idx[n] = {"bytes": sc["bytes"], "events": sc["events"],
+                          "exact": sc["exact"], "t": round(time.time(), 3),
+                          "reason": "adopted"}
+                healed = True
+            except OSError:
+                continue
+        if healed:
+            self._save_audit_index(idx)
+        shard_bytes = sum(int(v.get("bytes") or 0) for k, v in idx.items() if k in present)
+        shard_events = sum(int(v.get("events") or 0) for k, v in idx.items() if k in present)
+        oversized = sum(1 for n in present if not idx.get(n, {}).get("exact", True))
+        out = dict(active)
+        out.update({
+            "shards": len(present),
+            "shard_bytes": shard_bytes,
+            "shard_events": shard_events,
+            "oversized": oversized,       # 非精确分片数（历史遗留超大文件）
+            "total_bytes": active["bytes"] + shard_bytes,
+            "total_events": (active["events"] + shard_events
+                             if active["events"] is not None else None),
+            "total_exact": bool(active["exact"]) and oversized == 0,
+            "rotate_bytes": self.AUDIT_ROTATE_BYTES,
+            "keep_shards": self.AUDIT_KEEP_SHARDS,
+        })
+        return out
 
     # ================= 2. role 分层索引 =================
 
@@ -315,11 +525,14 @@ class MdCGOS(MdCG):
         return nid
 
     def _candidates(self, layer=None, roles=None, include_work=False,
-                    session=None):
+                    session=None, branch=None):
         """候选池：按层 + role 过滤。默认剔除工作角色（工具输出/命令/编辑）。
 
         session：会话归属过滤（frontmatter.session，写入时自动落盘）——
         多会话共用一个 root 时，按它区分「本会话记忆 / 其他会话记忆」。
+        branch：分支可见性（记忆演化分支④）——None（默认）时分支实验
+        节点全部隐身（实验不污染主支检索）；branch=<id> 时主支 + 该分支
+        可见、其他分支仍隐身。
         """
         out = []
         for e in self.index["nodes"].values():
@@ -327,6 +540,8 @@ class MdCGOS(MdCG):
                 continue  # 负记忆走覆盖标记；目标只做定向，都不进正排
             if session and e.get("session") != session:
                 continue
+            if e.get("branch_id") not in (None, branch):
+                continue
             if layer and e.get("layer") != layer:
                 continue
             r = e.get("role")
@@ -376,7 +591,7 @@ class MdCGOS(MdCG):
                context=None, min_results: int = 1, record: bool = True,
                include_neg: bool = True, judge: bool = True,
                roles=None, include_work: bool = False, pools=None,
-               session=None):
+               session=None, branch=None):
         """在父类语义之上加 role 过滤（默认剔除工具输出/命令/编辑）。
 
         返回 (results, meta)，与 MdCG.search 完全同构（T0–T3 阶梯 + 资格判定）。
@@ -387,7 +602,7 @@ class MdCGOS(MdCG):
             return [], {"tier": None, "reason": "empty_query", "scanned": 0}
         pool_cfg = pooling.resolve(pooling.from_env(pools))
         entries = self._candidates(layer=layer, roles=roles, include_work=include_work,
-                                   session=session)
+                                   session=session, branch=branch)
         if not entries:
             return [], {"tier": None, "reason": "no_candidates", "scanned": 0}
 
@@ -428,25 +643,27 @@ class MdCGOS(MdCG):
                 if out:
                     return out
 
+        # 截断依据=相关度（同 MdCG.search：cap 值不变，改的是拿什么排序）
         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
 
-        docs_all.sort(key=lambda d: (-float(d[1].get("importance") or 0),
-                                     -float(d[1].get("created_at") or 0)))
         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,
@@ -460,7 +677,9 @@ class MdCGOS(MdCG):
         LIKE 命中集沿 entries（目录枚举序）排列，插入序截断会让本路候选池
         随写入顺序漂移、不可复算，并可能把与查询最相关的节点随机丢弃。
         LIKE 全空时兜底池改用 importance/created_at 序（与 search 主路径同口径），
-        不再取插入序前 CAP。
+        不再取插入序前 CAP。返回序**恒为相关度降序**——原实现仅在超 cap 时
+        排序，≤cap 时直接返回 entries 枚举序，下游 seed/融合会拿到无语义依据
+        的顺序。
         """
         terms = expand_query_terms(query)
         # qb 与文档侧 normalize_en 口径对齐（同 MdCGOS.search，防大小写断裂）
@@ -472,16 +691,23 @@ class MdCGOS(MdCG):
         hits = [d for d in docs if self._like(d[2], d[1], terms)
                 or (semantic_on() and d[1].get("semantic"))]
         if not hits:
+            # 兜底池（LIKE 全空 = 无相关度信号）：截断依据=importance/created_at
+            # 序，确定可复算；此时 bigram 部分匹配不足以定序（共现噪声），
+            # 故本路不做「先全量打分再截断」。
             hits = sorted(
                 docs, key=lambda d: (-float(d[1].get("importance") or 0),
                                      -float(d[1].get("created_at") or 0))
             )[:GLOBAL_CAP]
+            stat["cut_order"] = "importance_fallback"
         scored = self._score(hits, query, qb)
+        # 恒按相关度排序（原实现仅超 cap 时排序 → ≤cap 时返回 entries 枚举序，
+        # 下游 seed/融合拿到无语义依据的顺序，不可复算）
+        scored.sort(key=lambda x: (-x[1],
+                    -float(x[0]["frontmatter"].get("importance") or 0)))
         if len(scored) > GLOBAL_CAP:
             stat["pre_cap"] = len(scored)
             stat["cap"] = GLOBAL_CAP
-            scored.sort(key=lambda x: (-x[1],
-                        -float(x[0]["frontmatter"].get("importance") or 0)))
+            stat["cut_order"] = "relevance"
             return scored[:GLOBAL_CAP]
         return scored
 
@@ -728,7 +954,7 @@ class MdCGOS(MdCG):
                    record: bool = True, query_expand=None,
                    path_weights=None, recall_only=None, fusion: str = "sum",
                    goal_text=None, judge_ranking: bool = False,
-                   session=None):
+                   session=None, branch=None):
         """并行多路召回 + RRF 融合。返回 (results, meta)。
 
         每路各自排序 → Reciprocal Rank Fusion：
@@ -763,7 +989,7 @@ class MdCGOS(MdCG):
         if not q:
             return [], {"tier": None, "reason": "empty_query", "paths": {}}
         entries = self._candidates(layer=layer, roles=roles, include_work=include_work,
-                                   session=session)
+                                   session=session, branch=branch)
         if not entries:
             return [], {"tier": None, "reason": "no_candidates", "paths": {}}
 
@@ -873,7 +1099,7 @@ class MdCGOS(MdCG):
                include_work: bool = False, judge: bool = True, use_rrf: bool = True,
                paths=None, query_expand=None, fusion=None,
                goal_text=None, include_recent=False, recent_limit: int = 10,
-               judge_ranking: bool = False, session=None,
+               judge_ranking: bool = False, session=None, branch=None,
                max_item_tokens: int = DEFAULT_MAX_ITEM_TOKENS):
         """按 token 预算装包：装到预算花完为止。
 
@@ -906,11 +1132,13 @@ class MdCGOS(MdCG):
             if goal_text is not None:
                 kw["goal_text"] = goal_text
             kw["judge_ranking"] = judge_ranking
+            if branch is not None:
+                kw["branch"] = branch
             results, meta = self.search_rrf(query, **kw)
             items = [(r[0], r[1], r[2], r[3]) for r in results]
         else:
             res, meta = self.search(query, layer=layer, k=k, context=context,
-                                    judge=judge, session=session)
+                                    judge=judge, session=session, branch=branch)
             items = [(r[0], r[1], r[2], []) for r in res]
 
         pack, skipped, used = [], [], 0
@@ -1033,24 +1261,67 @@ class MdCGOS(MdCG):
     # ================= 4. 审核队列（inbox → decisions） =================
 
     def propose(self, node_id: str, content: str, layer: str = "knowledge",
-                tags=None, condition_space=None, verify=None, **kw):
+                tags=None, condition_space=None, verify=None,
+                info: bool = False, **kw):
         """把一个候选记忆放入海马体 inbox，等待审核（不直接持久化）。
 
         verify —— 验收判据（内联声明，裁决阶段只读），形如：
             {"kind": "code", "assertions": ["pytest -k foo 通过"], "cmd": "..."}
         判据指纹随提案落盘，复核者只能按原判据裁决，不能放宽标准。
+
+        幂等对账（两段式）：入队动作在 strict 锁内「查重 → 入队」原子完成。
+        对账键 = payload_hash（内容签名 _sig(content)），同内容提案若已存在
+        （无论 pending 还是已裁决 accepted/rejected）→ 幂等返回既有 pid，
+        不再入队。语义：重试与崩溃恢复无害——入队落盘成功而响应丢失时
+        （MCP 客户端超时重试的真正机制），重试对账命中既有记录并返回原 pid。
+
+        返回值：info=False（默认）返回 pid 字符串（保形，存量调用零变化）；
+        info=True 返回 {"pid", "dedup", "dup_of", "dup_status"}。
         """
-        pid = "prop_" + _sig(node_id + str(time.time()))
-        _norm, vhash = _verify_norm(verify)
-        rec = {"t": time.time(), "pid": pid, "id": node_id, "content": content,
-               "layer": layer, "tags": list(tags or []),
-               "condition_space": condition_space or {},
-               "verify": verify or {}, "verify_hash": vhash,
-               "extra": kw, "actor": self.actor,
-               "session": getattr(self, "session", None)}
-        append_jsonl(self.inbox_log, rec)
+        phash = _sig(content)
+        with FileLock(self.inbox_log, strict=True):
+            st = self._pid_status()
+            dup = None
+            for r in read_jsonl(self.inbox_log):
+                # 存量记录无 payload_hash 字段 → 现算兼容（对账覆盖旧账）
+                rh = r.get("payload_hash") or _sig(r.get("content") or "")
+                if rh != phash:
+                    continue
+                s = st.get(r.get("pid")) or {}
+                dup = {"pid": r.get("pid"),
+                       "status": s.get("status") or "pending",
+                       "node_id": r.get("id")}
+                if dup["status"] in ("accepted", "rejected"):
+                    break          # 已裁决的最有信息量，优先返回
+            if dup:
+                self._audit("propose_dedup", node_id, dup_of=dup["pid"],
+                            dup_status=dup["status"], payload_hash=phash)
+                if info:
+                    return {"pid": dup["pid"], "dedup": True,
+                            "dup_of": dup["pid"], "dup_status": dup["status"]}
+                return dup["pid"]
+            # 唯一性取证（2026-09-16）：旧式 _sig(node_id + time.time()) 只带
+            # 「节点 id + 时间戳」，无进程熵——多 worker 在同一时刻用相同
+            # node_id 入队即产生 pid 碰撞（test_review_conformance【8】「pid
+            # 互不重复」偶发红，4 进程同用 w-node-K 时命中）。幂等由
+            # payload_hash 对账保证、与 pid 取值无关，故此处补熵是
+            # 只增不减契约（20 条互异由 test_review_conformance【8c】守卫）。
+            pid = "prop_" + _sig(node_id + str(time.time())
+                                 + uuid.uuid4().hex)
+            _norm, vhash = _verify_norm(verify)
+            rec = {"t": time.time(), "pid": pid, "id": node_id, "content": content,
+                   "layer": layer, "tags": list(tags or []),
+                   "condition_space": condition_space or {},
+                   "payload_hash": phash,
+                   "verify": verify or {}, "verify_hash": vhash,
+                   "extra": kw, "actor": self.actor,
+                   "session": getattr(self, "session", None)}
+            append_jsonl(self.inbox_log, rec)
         self._audit("propose", node_id, pid=pid, layer=layer,
-                    payload_hash=_sig(content), verify_hash=vhash)
+                    payload_hash=phash, verify_hash=vhash)
+        if info:
+            return {"pid": pid, "dedup": False,
+                    "dup_of": None, "dup_status": None}
         return pid
 
     def _pid_status(self):
@@ -1160,7 +1431,10 @@ class MdCGOS(MdCG):
         rec["record_hash"] = self._record_hash(rec)
         rec["result"] = {k: v for k, v in result.items()
                          if k in ("ok", "node_id", "error", "state")}
-        append_jsonl(self.decisions_log, rec)
+        # 裁决记录不能丢：strict 锁内追加（并发裁决不交错；
+        # 丢一条裁决会让提案回 pending → 重复落盘，比让裁决者等一下代价大）
+        with FileLock(self.decisions_log, strict=True):
+            append_jsonl(self.decisions_log, rec)
         # md 审计节点写失败不影响裁决（jsonl 仍是权威来源）
         try:
             self._write_review_record(rec)
@@ -1176,6 +1450,43 @@ class MdCGOS(MdCG):
                     record_node=rec["record_node_id"])
         return result
 
+    def _cascade_dedup(self, pid: str, phash: str, decision: str):
+        """主提案终态裁决后，同 payload_hash 的其余纯 pending 提案自动出清。
+
+        兄弟提案多为超时重试的重复入队产物（存量账本里已有实例）：主提案已
+        裁决后，兄弟再走一遍裁决只会重复落盘/重复入库。只在 decisions 锁内
+        「查兄弟最新状态 → 未有任何裁决记录才出清」，与并发裁决互斥，不会
+        覆盖兄弟自己的 accept。needs_reapproval 的兄弟有独立红队轮次历史，
+        不动（留人工处置）。级联裁决的权威源同为本文件（jsonl），
+        不写 md 审计节点（可能批量，self 层只留 jsonl + audit 簿记）。
+        """
+        if not phash:
+            return []
+        closed = []
+        with FileLock(self.decisions_log, strict=True):
+            st = self._pid_status()
+            for r in read_jsonl(self.inbox_log):
+                bpid = r.get("pid")
+                if not bpid or bpid == pid or bpid in st:
+                    continue     # 自己 / 已有裁决记录（含 needs_reapproval）跳过
+                rh = r.get("payload_hash") or _sig(r.get("content") or "")
+                if rh != phash:
+                    continue
+                rec = {"t": time.time(), "pid": bpid, "decision": "reject",
+                       "status": "rejected", "round": 1,
+                       "redteam_verdict": "absent", "issues": [],
+                       "verify_hash": r.get("verify_hash") or "",
+                       "reason": f"cascade_dedup: 同内容提案已由 {pid} "
+                                 f"{decision}（自动出清重复入队，无需再裁决）",
+                       "actor": self.actor, "target_id": r.get("id"),
+                       "record_node_id": self._audit_node_id(bpid, 1)}
+                rec["record_hash"] = self._record_hash(rec)
+                append_jsonl(self.decisions_log, rec)
+                closed.append(bpid)
+        for b in closed:
+            self._audit("review_cascade", b, cascade_of=pid, decision=decision)
+        return closed
+
     def review_records(self, pid: str = None):
         """列出裁决记录节点（self 层 / audit 标签），供外部来源审计。"""
         out = []
@@ -1299,6 +1610,12 @@ class MdCGOS(MdCG):
                 extra["verify_hash"] = expect
             nid = self.add(item["id"], content, layer=layer, tags=tags,
                            condition_space=item.get("condition_space"), **extra)
+            # 索引增量收尾（2026-09-16 取证）：add 只把条目放进本进程内存 _dirty，
+            # 未达 autoflush(64) 阈值时进程退出即永久丢失——裁决进程（review_cli /
+            # MCP op=review）通常只写 1~2 条，不 flush 则「节点在盘上但索引无条目」，
+            # 其他进程与重载后的长驻进程都检索不到，只能靠某次全量 rebuild 偶然救回。
+            # merge 分支绕开 add 直写节点文件，故其收尾同为索引重建（同因不同法）。
+            self.flush()
             result.update(ok=True, node_id=nid)
         else:  # merge
             target = merge_into or (item.get("extra") or {}).get("merge_into")
@@ -1319,10 +1636,23 @@ class MdCGOS(MdCG):
             self.rebuild_index()
             result.update(ok=True, node_id=target)
 
-        return self._record_decision(
+        result = self._record_decision(
             pid, item, decision,
             "rejected" if decision == "reject" else "accepted",
             reason, round_no, rt_v, rt_issues, expect, result)
+        # 级联出清：主提案已终态，同内容兄弟提案（重复入队产物）自动关闭
+        casc = self._cascade_dedup(
+            pid, item.get("payload_hash") or _sig(item.get("content") or ""),
+            decision)
+        if casc:
+            result["cascade_closed"] = casc
+        # 裁决链路统一收尾（2026-09-16 取证）：上面 accept/edit 分支的 flush 只覆盖
+        # 目标节点，而 `_record_decision → _write_review_record → add` 在这里又写了一个
+        # **审计记录节点**（self 层），reject 路径更是**只**写它——两者同样停留在内存
+        # `_dirty` 中。不在此收尾则「审计记录在盘上但索引无条目」，复核方与其它进程都
+        # 检索不到（与目标节点同因，只是漏点不同）。flush 幂等（`_dirty` 空即返回）。
+        self.flush()
+        return result
 
     def decisions(self):
         return list(read_jsonl(self.decisions_log))
@@ -1352,8 +1682,9 @@ class MdCGOS(MdCG):
                                           "actor": self.actor,
                                           "trash": os.path.relpath(dst, self.root)
                                                    .replace("\\", "/")})
-        self.index["nodes"].pop(node_id, None)
-        self._dirty.pop(node_id, None)
+        # 摘索引必须**落盘**（写删除记录）：只 pop 内存会让条目在下次启动
+        # 重放 _index_log 时复活成幽灵条目（索引有条目、文件已进 trash/）。
+        self._unstage(node_id)
         subgraph.invalidate_cache(self)
         chain.invalidate_cache(self)
         self._audit("forget", node_id, reason=reason, payload_hash=h)
@@ -1480,14 +1811,21 @@ class MdCGOS(MdCG):
                        budget_tokens=1200, include_state=True):
         """按需恢复：一次调用返回「可续接的上下文包」（替代 hook 自动注入）。
 
-        内容 = 最近会话要点 + 活跃目标 + 近期事件 + 未解问题 (+ 自我状态卡)。
-        纯只读、无副作用；返回体受 budget_tokens 约束（超出即裁剪并显式上报）。
-        无 hook 的载体应在会话开始时显式调用本 op 一次。
+        内容 = 最近会话要点 + 活跃目标 + **任务台账（进行中 + 近期完成）** + 近期事件
+        + 未解问题 (+ 自我状态卡)。纯只读、无副作用；返回体受 budget_tokens 约束
+        （超出即裁剪并显式上报）。无 hook 的载体应在会话开始时显式调用本 op 一次。
+
+        任务段（2026-09-16 新增）是「忘记已实现的工程」的直接解药：新会话开机即见
+        「还在做的」与「刚做完的」，不必先想到去查。任务属结构层、跨会话稳定，
+        故**不按 session 过滤**——工程台账跟着工程走，不跟着会话走。
         """
         limit = max(1, min(int(limit or 5), 50))
         budget = max(200, int(budget_tokens or 1200))
         pack = {"ok": True, "session": session, "source": "session_recall",
-                "notes": [], "goals": [], "recent": [], "unresolved": [],
+                "notes": [], "goals": [],
+                "tasks": {"active": [], "done": [], "active_total": 0,
+                          "done_total": 0},
+                "recent": [], "unresolved": [],
                 "degraded": []}
         # ① 会话要点
         try:
@@ -1501,6 +1839,22 @@ class MdCGOS(MdCG):
                              for g in self.active_goals(limit=5)]
         except Exception:                                  # noqa: BLE001
             pack["degraded"].append("goals")
+        # ②.5 任务台账（structural 层）——见 docstring：不按 session 过滤
+        try:
+            from . import tasks as _tasks
+            ts = _tasks.session_tasks(self, active_limit=5, done_limit=5)
+            pack["tasks"] = {
+                "active": [{"id": t["id"], "name": t["name"], "status": t["status"],
+                            "plan": (t.get("plan") or "")[:300],
+                            "updated_at": t.get("updated_at")}
+                           for t in ts["active"]],
+                "done": [{"id": t["id"], "name": t["name"], "status": t["status"],
+                          "result": (t.get("result") or "")[:300],
+                          "updated_at": t.get("updated_at")}
+                         for t in ts["done"]],
+                "active_total": ts["active_total"], "done_total": ts["done_total"]}
+        except Exception:                                  # noqa: BLE001
+            pack["degraded"].append("tasks")
         # ③ 近期事件（原始滚动窗口）
         try:
             evs = self.recent_events(limit=max(1, int(recent_limit or 10)))
@@ -1528,18 +1882,29 @@ class MdCGOS(MdCG):
                 pack["self_state"] = _ss.summary(self, session=session)
             except Exception:                              # noqa: BLE001
                 pack["degraded"].append("self_state")
-        # ⑥ 预算裁剪：交替丢 recent / notes 尾部，超出预算则显式上报
+        # ⑥ 预算裁剪：交替丢 recent / notes 尾部；任务段**最后才让位**
+        #    （任务台账是结构性结论，事件流水是易失过程——先丢过程），
+        #    被裁的事实在 tasks_truncated 里显式上报，不静默丢。
+        tasks_trimmed = False
         pack["tokens"] = est_tokens(json.dumps(pack, ensure_ascii=False))
-        while pack["tokens"] > budget and (pack["recent"] or pack["notes"]):
-            if len(pack["recent"]) >= len(pack["notes"]):
+        while pack["tokens"] > budget and (pack["recent"] or pack["notes"]
+                                           or pack["tasks"]["active"]
+                                           or pack["tasks"]["done"]):
+            if pack["recent"] and len(pack["recent"]) >= len(pack["notes"]):
                 pack["recent"].pop()
-            else:
+            elif pack["notes"]:
                 pack["notes"].pop()
+            elif pack["tasks"]["done"] or pack["tasks"]["active"]:
+                (pack["tasks"]["done"] or pack["tasks"]["active"]).pop()
+                tasks_trimmed = True
+            else:
+                pack["recent"].pop()
             pack["tokens"] = est_tokens(json.dumps(pack, ensure_ascii=False))
         pack["budget_tokens"] = budget
         pack["truncated"] = pack["tokens"] > budget
-        pack["note"] = ("只读上下文包：会话要点 + 目标 + 近期事件 + 未解问题"
-                        "（+自我状态卡）。库侧替代 hook 自动注入；"
+        pack["tasks_truncated"] = tasks_trimmed
+        pack["note"] = ("只读上下文包：会话要点 + 目标 + 任务台账（进行中/近期完成）"
+                        "+ 近期事件 + 未解问题（+自我状态卡）。库侧替代 hook 自动注入；"
                         "会话开始时显式调用本 op 一次即可续接。")
         return pack
 
@@ -1859,7 +2224,9 @@ class MdCGOS(MdCG):
     # 三者都不进默认召回热路径，只在显式调用时工作。
 
     INSIGHT_ACTIONS = ("window", "record", "verify", "list", "report",
-                       "reconstruct", "learn", "outlook", "catalog")
+                       "reconstruct", "learn", "outlook", "catalog",
+                       "fork", "branch_rewrite", "branch_search",
+                       "branch_merge", "branch_discard", "branches")
 
     def insight(self, action="outlook", **kw):
         """洞察条件层 + 情景重构 + 盲区学习 + 结构洞察（P2）。
@@ -1909,6 +2276,34 @@ class MdCGOS(MdCG):
                 max_nodes=(kw.get("max_nodes") or subgraph.RECON_MAX_NODES),
                 neighbors=(True if kw.get("neighbors") is None
                            else bool(kw.get("neighbors"))))
+        if act in ("fork", "branch_rewrite", "branch_search", "branch_merge",
+                   "branch_discard", "branches"):
+            # 记忆演化分支（Pi 移植④）：fork / 分支改写（唯一正路，归属强制
+            # 继承）/ 分支内检索 / 溯源合并 / 教训归档冷收 / 盘点。
+            # discard 属写操作（MCP 分发层 require_admin）。
+            from . import branches as _br
+            if act == "fork":
+                return _br.fork(self, kw.get("node_ids") or kw.get("ids"),
+                                branch_id=kw.get("branch_id"),
+                                note=kw.get("note"))
+            if act == "branch_rewrite":
+                return _br.rewrite(self,
+                                   kw.get("node_id") or kw.get("pid") or "",
+                                   kw.get("content") or "",
+                                   tags=kw.get("tags"),
+                                   importance=kw.get("importance"))
+            if act == "branch_search":
+                return _br.search(self,
+                                  kw.get("content") or kw.get("query") or "",
+                                  kw.get("branch_id") or "")
+            if act == "branch_merge":
+                return _br.merge(self, kw.get("branch_id"),
+                                 reason=kw.get("reason"))
+            if act == "branch_discard":
+                return _br.discard(self, kw.get("branch_id"),
+                                   summary=kw.get("content")
+                                   or kw.get("summary") or "")
+            return _br.list_branches(self)
         if act == "explore":
             # 信息差驱动自主探索（opt-in）：提案 → 五态验证 → 回写 gap_hint
             from . import autonomy
@@ -1947,14 +2342,81 @@ class MdCGOS(MdCG):
 
     # ================= 健康度（并入 OS 指标） =================
 
+    AUDIT_COUNT_MAX_BYTES = 64 << 20      # 超过此规模不再全量精确计数（O(1) 体检纪律）
+    # ---- 审计日志分片轮转（治本面，2026-09-16）----
+    # 元数据读数（_log_scale）只让「指标与代价错配」不再显形，**有界性的来源是轮转**：
+    # 单文件 ≤ AUDIT_ROTATE_BYTES、分片数 ≤ AUDIT_KEEP_SHARDS ⇒ 单片读取代价与总量
+    # 都有上界，体检/getsize 不再随运行时长线性劣化。
+    AUDIT_ROTATE_BYTES = 64 << 20     # 活动日志轮转阈值（≤0 关闭轮转，退回无上界）
+    AUDIT_KEEP_SHARDS = 8             # 归档分片保留数（≤0 不淘汰；淘汰必留审计痕）
+    AUDIT_ARCHIVE = "_audit_archive"  # 分片归档目录（不在 LAYERS 内，不参与节点索引）
+    AUDIT_INDEX = "_index.json"       # 归档索引：分片 bytes/events 缓存（稳态 O(1)）
+    AUDIT_PROBE_EVERY = 32            # 每 N 次写入探测一次大小（把写入税摊到 1/N）
+
+    def _log_scale(self, path, est_sample=256 << 10):
+        """日志量级读数（O(1)）：以元数据为主，条数只在与规模相称时才精确。
+
+        为什么不去全量数条数（2026-09-16 使用者裁定「python 审查 4GB 数据是个
+        不明智的选择」+ 第 4 条现场取证）：
+
+          信息需求 = 量级（这条日志多大、多久没动）→ O(1) 元数据即可满足；
+          实际代价 = 全量解析/扫描 → O(n) 磁盘 IO（本机 4.0 GB 实测数十秒）；
+          且日志**无上界增长**（实测 ~2 条/s 持续写入、累计 ~21.5 M 条 / 4.0 GB）。
+          指标与代价错配，而「无上界」使任何「每次体检全量扫」的实现随运行时长
+          线性劣化——4 GB 只是让错配显形，不是错配本身。
+
+        故：有界规模内给精确行数（count_jsonl 流式、内存恒定）；超阈值只读元数据
+        + 尾部采样估算，**显式标注 exact=False 不假装精确**。要精确值走离线
+        count_jsonl 或审计日志分片轮转（属方向性决策，待定夺）。
+        """
+        try:
+            st = os.stat(path)
+        except OSError:
+            return {"bytes": 0, "mtime": None, "events": 0, "exact": True}
+        size = st.st_size
+        out = {"bytes": size, "mtime": st.st_mtime}
+        if size <= self.AUDIT_COUNT_MAX_BYTES:
+            out.update({"events": count_jsonl(path), "exact": True})
+            return out
+        est = None
+        try:
+            with open(path, "rb") as f:
+                f.seek(max(0, size - est_sample))
+                tail = f.read()
+            lines = [ln for ln in tail.split(b"\n") if ln.strip()]
+            if lines:
+                est = int(size / (len(tail) / float(len(lines))))
+        except OSError:
+            pass
+        out.update({
+            "events": est, "exact": False,
+            "note": ("超过 %.0f MB 不给全量精确计数（O(n) 磁盘 IO 与量级体检不匹配）；"
+                     "events 为尾部 %d KB 采样的估算值"
+                     % (self.AUDIT_COUNT_MAX_BYTES / 1048576.0, est_sample >> 10))})
+        return out
+
     def health_os(self):
         h = self.health()
+        audit = self.audit_scale()
         h["os"] = {
             "roles": self._role_counts(),
             "review_pending": len(self.review_list()),
             "review_records": len(self.review_records()),
-            "tombstones": len(list(read_jsonl(self.deletions_log))),
-            "audit_events": len(list(read_jsonl(self.audit_log))),
+            # 审计/墓碑面走 _log_scale（O(1) 量级读数）而非 list(read_jsonl(...))
+            # 也不再全量流式数行：物化读让只读体检把整条通道拖死（实测 4.0 GB
+            # 日志 → RSS 5 GB+、数十分钟不返回），而全量流式扫仍要 O(n) 磁盘 IO
+            # 且日志无上界增长（~2 条/s）→ 随运行时长线性劣化。见 _log_scale。
+            "tombstones": self._log_scale(self.deletions_log)["events"],
+            "audit_events": audit["events"],            # 超阈值时为估算值
+            "audit_events_exact": audit["exact"],       # False = 上面是估算，非精确
+            "audit_bytes": audit["bytes"],              # 量级看这个（O(1) 精确）
+            "audit_events_note": audit.get("note"),
+            # 轮转面（有界性证据）：活动文件 ≤rotate_bytes、分片 ≤keep_shards
+            "audit_shards": audit["shards"],            # 归档分片数
+            "audit_total_bytes": audit["total_bytes"],  # 活动 + 全部分片
+            "audit_total_events": audit["total_events"],  # 全量条数（分片走索引缓存）
+            "audit_total_exact": audit["total_exact"],  # False = 含超大分片的估算
+            "audit_oversized": audit["oversized"],      # 超大历史分片数（待离线切分）
             "reflections": len(self.last_d_records()),
             # 七件套覆盖度（第 5 篇）：目标槽 + 近期事件窗口
             "goals": {"total": len(self.list_goals()),
@@ -2632,9 +3094,9 @@ class MdCGSecure(MdCGOS):
         return super().clear_recent()
 
     def _candidates(self, layer=None, roles=None, include_work=False,
-                    session=None):
+                    session=None, branch=None):
         out = super()._candidates(layer=layer, roles=roles, include_work=include_work,
-                                  session=session)
+                                  session=session, branch=branch)
         return [e for e in out if self._readable(e)]
 
     def _neg_coverage(self, terms):