@furongjun1999/dsh-memory 0.5.0 → 0.6.0

package/md_cg/evidence.py

@@ -33,12 +33,14 @@ import time
 
 from . import identity as _identity
 from . import signer as _signer
+from .datapath import aux_root
+from .fsutil import publish
 
 NODE_ID_ENV = "MDCG_NODE_ID"
 SWARM_DIR_ENV = "MDCG_SWARM_DIR"
 ROOT_ENV = "MDCG_ROOT"
 
-DEFAULT_DIR = os.path.join(os.path.expanduser("~"), ".mdcg")
+DEFAULT_DIR = aux_root()
 DEFAULT_SWARM_DIR = os.path.join(DEFAULT_DIR, "swarm")
 
 SUBSYSTEM = "swarm"          # 子系统名：智能体可对它声明签名策略（D-4）
@@ -485,7 +487,7 @@ def _write_json(path: str, obj) -> str:
         os.chmod(tmp, 0o600)
     except OSError:
         pass
-    os.replace(tmp, path)
+    publish(tmp, path)
     return path
 
 
@@ -504,7 +506,10 @@ def _open_cg(root: str = None):
                   clearance="private", can_write=True, can_admin=True,
                   role="designer", layers_allow=spec["layers_allow"],
                   ops_allow=spec["ops_allow"], auth_mode="legacy_env")
-    return MdCGSecure(r, principal=p)
+    # autoflush=1（P1b，2026-09-26，与 mcp_server.py:3695-3702 / review_cli._cg
+    # 同款）：短命工具进程被 kill 时 close/atexit 兜底不执行，缺省 64 会让
+    # 写入停在内存 _dirty、分片日志从未落——逐条落日志保任意退出形态跨进程可见。
+    return MdCGSecure(r, principal=p, autoflush=1)
 
 
 # 生效条件：当传入 obj 时，打印 json.dumps(obj, ensure_ascii=False, indent=1, default=str)。

package/md_cg/export.py

@@ -18,6 +18,8 @@ import json
 import os
 import time
 
+from .fsutil import publish
+
 SCHEMA = 1
 EXPORT_ACTIONS = ("graph", "nodes", "slice", "stat")
 
@@ -117,7 +119,7 @@ def _write_jsonl(cg, out_path: str, entries, include_content: bool = True):
             by_layer[lay] = by_layer.get(lay, 0) + 1
             if written % 500 == 0:
                 f.flush()              # 定期刷盘，控制缓冲区
-    os.replace(tmp, out_path)          # 流式 + 原子：要么完整、要么无
+    publish(tmp, out_path)             # 流式 + 原子：要么完整、要么无
     return {"ok": True, "out": out_path, "written": written,
             "skipped_unreadable": skipped, "by_layer": by_layer,
             "bytes": os.path.getsize(out_path),

package/md_cg/forgetting.py

@@ -48,7 +48,7 @@ import os
 import time
 
 from . import lifecycle, nodefile
-from .fsutil import append_jsonl, atomic_write, read_jsonl
+from .fsutil import append_jsonl, atomic_write, publish, read_jsonl
 from .mdcg import bigrams
 
 # ---------------------------------------------------------------- 判据常量
@@ -435,7 +435,7 @@ def longterm_assess(cg, apply=False, out=None, layer=None, keep=LONGTERM_KEEP,
                        "content_hash": e.get("content_hash")}
                 f.write(json.dumps(row, ensure_ascii=False) + "\n")
                 written += 1
-        os.replace(tmp, path)
+        publish(tmp, path)
         atomic_write(current_path(cg), json.dumps(
             {"snapshot_id": snapshot_id, "ts": time.time(), "path": rel,
              "total": total, "tiers": tiers, "by_layer": by_layer,

package/md_cg/fsutil.py

@@ -41,6 +41,18 @@ def _publish(tmp: str, path: str):
             time.sleep(_RENAME_WAIT)
 
 
+# 生效条件：行为与 _publish 完全一致（直接委派并返回其结果）——公开名，供包内
+# 各「tmp + os.replace」原子写点位统一改走带 Windows 短重试的实现。
+def publish(tmp: str, path: str):
+    """`os.replace` 的公开安全版：目标被 Defender/索引器短暂持锁时短重试。
+
+    2026-09-25 全量回归实测：裸 `os.replace` 在 Windows 上随机抛
+    `PermissionError: [WinError 5]`（retr_s7 的 _postings_meta.json 改名中招，
+    失败者随机分布）——md_cg 内原子写一律经本函数，不再各写各的裸 replace。
+    """
+    return _publish(tmp, path)
+
+
 # 生效条件：path 与 data 给定时取 path 所在目录 d 建目录，用 tempfile.mkstemp 在 d 内建临时文件按 encoding 写入 data，durable 为真才 flush+os.fsync（假值不 fsync），再经 _publish(tmp, path) 替换；任一步失败时 finally 里若 tmp 仍非 None 且 os.path.exists(tmp) 为真则 os.remove（OSError 忽略）。
 def atomic_write(path: str, data: str, encoding: str = "utf-8", durable: bool = False):
     """整文件替换。临时文件与目标同目录（保证同一文件系统，rename 才原子），
@@ -212,6 +224,42 @@ def read_jsonl(path: str):
                 continue
 
 
+# 生效条件：os.path.exists(path) 为假时返回 ([], None)；否则以二进制只读打开并 seek 到 offset 后一次性读到 EOF，按 b"\n" 切行逐段 decode("utf-8","replace") 再 strip，空行跳过，json.loads 成功的收入列表，ValueError 跳过；返回 (对象列表, offset+读到的字节数)——EOF 偏移是真实消费位置（stat 与 read 之间并发 append 的字节已计入），供增量缓存作水位。
+def read_jsonl_tail(path: str, offset: int):
+    """从字节偏移 offset 起**增量**读 append-only jsonl → `(records, end_offset)`。
+
+    存在理由（issue #32）：propose 等高频对账每次全量重读 inbox/decisions
+    是 O(M+D)/条、批量 O(M²)；append-only 契约（写点全部经 append_jsonl，
+    无轮转/截断）下「上次扫描到的 size」必为行边界，从该偏移起只解析新增
+    字节即可。上一次写入中断在行中间（ends_mid_line 补 \\n 场景）时，残行
+    前半已在上一轮装载中被跳过、增量窗口读到的是补写的换行与新行——与
+    全量 read_jsonl 的容错结果一致。
+
+    返回值（水位口径，竞态修复）：end_offset 是**实际读到的 EOF 位置**。
+    调用方若把「读前 stat 的 size」当水位，stat→read 窗口内的跨进程
+    append 会在本轮被并入、而水位偏小——下一轮增量从旧水位重读，同一条
+    记录在列表型缓存里重复并入且永不自愈。存本函数返回的 end_offset
+    即可精确续读。**读后再 stat 不可取**：re-stat 可能大于已消费位置，
+    下轮会跳过未读记录（丢账比重复更糟）。文件不存在返回 (list, None)，
+    调用方自行回落。
+    """
+    if not os.path.exists(path):
+        return [], None
+    recs = []
+    with open(path, "rb") as f:
+        f.seek(offset)
+        data = f.read()
+    for b in data.split(b"\n"):
+        line = b.decode("utf-8", "replace").strip()
+        if not line:
+            continue
+        try:
+            recs.append(json.loads(line))
+        except ValueError:
+            continue
+    return recs, offset + len(data)
+
+
 _COUNT_CACHE = {}          # abspath -> (bytes_scanned, mtime_ns, lines)
 
 

package/md_cg/hotcache.py

@@ -1,238 +1,255 @@
-# -*- coding: utf-8 -*-
-"""md_cg · 热路径缓存（L0 节点缓存 + query 结果缓存）
-
-【为什么】检索链路每次都跑四路 RRF 融合（约 50ms），但同一 query
-短时间内反复调用是常态（agent 对话轮次间、batch 调用等）。热缓存
-让重复 query 毫秒级返回，同时 L0 高频节点（session=main）的
-frontmatter 读取也从磁盘降为内存命中。
-
-【设计】
-  - 节点缓存：LRU dict，key=node_id → value=(frontmatter, body_excerpt)
-  - query 缓存：LRU dict，key=(query, k, layer, session, branch, validity, view,
-    extra) → value=(results, meta)
-    **键必须覆盖全部影响结果的参数**（红线，v14 缺陷 C 的教训）：validity /
-    view 之外，`include_work` / `roles` / `paths` / `path_weights` /
-    `recall_only` / `fusion` / `judge` / `judge_ranking` / `goal_text` /
-    `context` / `early_stop_threshold` 同样改变候选资格与排序，经 `extra`
-    整体入键（`_KEYED_EXTRA` 为清单真源）。
-    不入键的后果不是「慢」而是**静默错答**：默认查询会返回工作角色节点
-    （资格泄漏）、`paths` 口径互相顶替等。
-  - 无法稳定规范化的参数（自定义可调用 `query_expand`，见 `_BYPASS_EXTRA`）：
-    **非默认值即绕行缓存**（读+写双侧），fail-closed——宁可不用缓存，不可串味。
-  - 失效策略：写入时 invalidate 受影响节点 + query 全清（保守策略，
-    因为 RRF 融合后一个节点的变动可能影响全局排序）
-  - TTL：query 缓存 300s（5 分钟），节点缓存无 TTL（写入即失效）
-
-【边界】
-  - 进程内缓存，不跨进程（每个 cg 实例独立）
-  - 不改 RRF 核心算法（bench6 600/600 rank 逐位一致是硬约束）
-  - 缓存命中时 meta 带 "cached": True 标记
-
-零第三方依赖（D-005）。
-"""
-from __future__ import annotations
-
-import os
-import time
-from collections import OrderedDict
-
-#: 节点缓存上限（env MDCG_HOTCACHE_MAX_NODES 可覆盖——公共评测池 locomo-zh-500
-#: 为 567 节点，缺省 256 会持续 LRU 淘汰，issue #28：容量应可配或自适应）
-MAX_NODES = 256
-#: query 缓存上限（env MDCG_HOTCACHE_MAX_QUERIES 可覆盖）
-MAX_QUERIES = 64
-#: query 缓存 TTL（秒）
-QUERY_TTL = 300.0
-
-#: 进键的「口径参数」清单（**单一真源**）：调用方（mdcos.search_rrf）按此
-#: 构造 extra。新增影响结果的检索参数必须同时登记到本清单——漏登即跨口径
-#: 串味（v14 缺陷 C：include_work/roles 致资格泄漏、paths 互相顶替）。
-_KEYED_EXTRA = ("include_work", "roles", "paths", "path_weights", "recall_only",
-                "fusion", "judge", "judge_ranking", "goal_text", "context",
-                "early_stop_threshold")
-#: 不可稳定规范化的参数（自定义可调用）：非默认即**绕行缓存**（fail-closed）。
-_BYPASS_EXTRA = ("query_expand",)
-
-
-class HotCache:
-    """进程内热路径缓存。
-
-    使用 OrderedDict 实现 LRU 语义：
-    - get 命中时 move_to_end（最近使用放尾）
-    - put 满时 popitem(last=False)（淘汰头=最久未用）
-    """
-
-    def __init__(self, *, max_nodes=MAX_NODES, max_queries=MAX_QUERIES,
-                 query_ttl=QUERY_TTL):
-        self._nodes: OrderedDict = OrderedDict()
-        self._queries: OrderedDict = OrderedDict()
-        self._max_nodes = max_nodes
-        self._max_queries = max_queries
-        self._query_ttl = query_ttl
-        # 统计
-        self._stats = {"node_hits": 0, "node_misses": 0,
-                       "query_hits": 0, "query_misses": 0,
-                       "invalidations": 0}
-
-    # ---------- 节点缓存 ----------
-
-    def get_node(self, node_id: str):
-        """返回 (frontmatter, body_excerpt) 或 None（未缓存）。"""
-        entry = self._nodes.get(node_id)
-        if entry is None:
-            self._stats["node_misses"] += 1
-            return None
-        self._stats["node_hits"] += 1
-        self._nodes.move_to_end(node_id)
-        return entry
-
-    def put_node(self, node_id: str, frontmatter: dict, body_excerpt: str = ""):
-        """写入/更新节点缓存。"""
-        self._nodes[node_id] = (dict(frontmatter), body_excerpt)
-        self._nodes.move_to_end(node_id)
-        while len(self._nodes) > self._max_nodes:
-            self._nodes.popitem(last=False)
-
-    def invalidate_node(self, node_id: str):
-        """失效单个节点。"""
-        self._nodes.pop(node_id, None)
-
-    # ---------- query 缓存 ----------
-
-    @staticmethod
-    def _canon(v):
-        """参数值 → 可哈希、稳定、跨调用一致的键片段（递归规范化容器）。"""
-        if v is None or isinstance(v, (bool, int, float, str, bytes)):
-            return v
-        if isinstance(v, (list, tuple)):
-            return tuple(HotCache._canon(x) for x in v)
-        if isinstance(v, (set, frozenset)):
-            return tuple(sorted((HotCache._canon(x) for x in v), key=repr))
-        if isinstance(v, dict):
-            return tuple(sorted((str(k), HotCache._canon(x))
-                                for k, x in v.items()))
-        # 其余（含自定义对象/可调用）：repr 含内存地址 → 每次不同 →
-        # 缓存永不命中（等价绕行），是**安全侧**失败（不串味）。
-        return ("repr", repr(v))
-
-    @staticmethod
-    def _query_key(query, k, layer, session, branch, validity=None,
-                   view=None, extra=None):
-        # 键必须覆盖全部影响结果的参数（正确性缺陷，非优化项）：
-        # validity（不过滤/排已过期）、view（角色视图）、extra（口径参数，
-        # 见 _KEYED_EXTRA）任一不入键都会串结果。
-        return (query, k, layer or None, session or None, branch or None,
-                bool(validity) or None, view or None,
-                HotCache._canon(extra) if extra else None)
-
-    def get_query(self, query, k=20, layer=None, session=None, branch=None,
-                  validity=None, view=None, extra=None):
-        """返回 (results, meta) 或 None（未缓存/过期）。"""
-        key = self._query_key(query, k, layer, session, branch, validity,
-                              view, extra)
-        entry = self._queries.get(key)
-        if entry is None:
-            self._stats["query_misses"] += 1
-            return None
-        ts, results, meta = entry
-        if time.time() - ts > self._query_ttl:
-            self._queries.pop(key, None)
-            self._stats["query_misses"] += 1
-            return None
-        self._stats["query_hits"] += 1
-        self._queries.move_to_end(key)
-        return results, dict(meta)
-
-    def put_query(self, query, results, meta, k=20, layer=None,
-                  session=None, branch=None, validity=None, view=None,
-                  extra=None):
-        """写入/更新 query 缓存。"""
-        key = self._query_key(query, k, layer, session, branch, validity,
-                              view, extra)
-        self._queries[key] = (time.time(), list(results), dict(meta))
-        self._queries.move_to_end(key)
-        while len(self._queries) > self._max_queries:
-            self._queries.popitem(last=False)
-
-    def invalidate_all_queries(self):
-        """清空全部 query 缓存（写入时保守全清）。"""
-        n = len(self._queries)
-        self._queries.clear()
-        if n:
-            self._stats["invalidations"] += 1
-
-    def invalidate_node_and_queries(self, node_id: str):
-        """失效节点 + 全清 query（节点变动可能影响全局排序）。"""
-        self.invalidate_node(node_id)
-        self.invalidate_all_queries()
-
-    # ---------- 全局 ----------
-
-    def clear(self):
-        """清空全部缓存。"""
-        self._nodes.clear()
-        self._queries.clear()
-
-    def stats(self):
-        """返回统计信息。"""
-        s = dict(self._stats)
-        s["node_cache_size"] = len(self._nodes)
-        s["query_cache_size"] = len(self._queries)
-        return s
-
-
-#: 进程级默认实例（每个 cg 实例可独立持有，也可共享此单例）
-_DEFAULT = None
-
-
-def default_cache():
-    """进程级默认热缓存单例。"""
-    global _DEFAULT
-    if _DEFAULT is None:
-        _DEFAULT = HotCache()
-    return _DEFAULT
-
-
-# 生效条件：cg 传入；已挂（_hotcache 非 None）时幂等返回现有实例；未挂时按 max_nodes/max_queries 显式值构造 HotCache，缺省回落 env MDCG_HOTCACHE_MAX_NODES / MDCG_HOTCACHE_MAX_QUERIES（非整数回落模块级默认），再回落模块级常量；返回挂载的 HotCache。
-def attach(cg, *, max_nodes: int = None, max_queries: int = None):
-    """给 cg 实例挂热缓存（幂等：已挂则不重复）。
-
-    容量解析优先级：显式入参 > env（MDCG_HOTCACHE_MAX_NODES /
-    MDCG_HOTCACHE_MAX_QUERIES）> 模块级常量（issue #28：容量可配，
-    大库须调大，否则 LRU 持续淘汰使热缓存形同虚设）。
-    """
-    if getattr(cg, "_hotcache", None) is not None:
-        return cg._hotcache
-
-    def _cap(explicit, env_key, default):
-        if explicit is not None:
-            return explicit
-        raw = os.environ.get(env_key, "").strip()
-        if raw:
-            try:
-                return int(raw)
-            except ValueError:
-                pass
-        return default
-
-    cg._hotcache = HotCache(
-        max_nodes=_cap(max_nodes, "MDCG_HOTCACHE_MAX_NODES", MAX_NODES),
-        max_queries=_cap(max_queries, "MDCG_HOTCACHE_MAX_QUERIES",
-                         MAX_QUERIES))
-    return cg._hotcache
-
-
-def get(cg):
-    """取 cg 实例的热缓存（未挂返回 None）。"""
-    return getattr(cg, "_hotcache", None)
-
-
-def invalidate(cg, node_id: str = None):
-    """写入后失效（节点 + query 全清）。node_id=None 时全清。"""
-    hc = get(cg)
-    if hc is None:
-        return
-    if node_id:
-        hc.invalidate_node_and_queries(node_id)
-    else:
-        hc.clear()
+# -*- coding: utf-8 -*-
+"""md_cg · 热路径缓存（L0 节点缓存 + query 结果缓存）
+
+【为什么】检索链路每次都跑四路 RRF 融合（约 50ms），但同一 query
+短时间内反复调用是常态（agent 对话轮次间、batch 调用等）。热缓存
+让重复 query 毫秒级返回，同时 L0 高频节点（session=main）的
+frontmatter 读取也从磁盘降为内存命中。
+
+【设计】
+  - 节点缓存：LRU dict，key=node_id → value=(frontmatter, body_excerpt)
+  - query 缓存：LRU dict，key=(query, k, layer, session, branch, validity, view,
+    extra) → value=(results, meta)
+    **键必须覆盖全部影响结果的参数**（红线，v14 缺陷 C 的教训）：validity /
+    view 之外，`include_work` / `roles` / `paths` / `path_weights` /
+    `recall_only` / `fusion` / `judge` / `judge_ranking` / `goal_text` /
+    `context` / `early_stop_threshold` 同样改变候选资格与排序，经 `extra`
+    整体入键（`_KEYED_EXTRA` 为清单真源）。
+    不入键的后果不是「慢」而是**静默错答**：默认查询会返回工作角色节点
+    （资格泄漏）、`paths` 口径互相顶替等。
+  - 无法稳定规范化的参数（自定义可调用 `query_expand`，见 `_BYPASS_EXTRA`）：
+    **非默认值即绕行缓存**（读+写双侧），fail-closed——宁可不用缓存，不可串味。
+  - 失效策略：写入时 invalidate 受影响节点 + query 全清（保守策略，
+    因为 RRF 融合后一个节点的变动可能影响全局排序）
+  - TTL：query 缓存 300s（5 分钟），节点缓存无 TTL（写入即失效）
+
+【边界】
+  - 进程内缓存，不跨进程（每个 cg 实例独立）
+  - 不改 RRF 核心算法（bench6 600/600 rank 逐位一致是硬约束）
+  - 缓存命中时 meta 带 "cached": True 标记
+
+零第三方依赖（D-005）。
+"""
+from __future__ import annotations
+
+import os
+import time
+from collections import OrderedDict
+
+#: 节点缓存上限（env MDCG_HOTCACHE_MAX_NODES 可覆盖——公共评测池 locomo-zh-500
+#: 为 567 节点，缺省 256 会持续 LRU 淘汰，issue #28：容量应可配或自适应）
+MAX_NODES = 256
+#: query 缓存上限（env MDCG_HOTCACHE_MAX_QUERIES 可覆盖）
+MAX_QUERIES = 64
+#: query 缓存 TTL（秒）
+QUERY_TTL = 300.0
+
+#: 进键的「口径参数」清单（**单一真源**）：调用方（mdcos.search_rrf）按此
+#: 构造 extra。新增影响结果的检索参数必须同时登记到本清单——漏登即跨口径
+#: 串味（v14 缺陷 C：include_work/roles 致资格泄漏、paths 互相顶替）。
+_KEYED_EXTRA = ("include_work", "roles", "paths", "path_weights", "recall_only",
+                "fusion", "judge", "judge_ranking", "goal_text", "context",
+                "early_stop_threshold",
+                # 进程级开关快照（见 env_switch_key）：参数面之外还有一类口径来自
+                # 环境变量（MDCG_SEMANTIC/MDCG_EN_ATOMS/MDCG_UNIFY_QUERY…），它们
+                # 同样改变候选资格与打分。v14 只补了参数面，故另立一键
+                # （2026-09-24 修复：同 query 下切开关会命中另一口径的缓存 → 静默错答）。
+                "env_switch")
+#: 不可稳定规范化的参数（自定义可调用）：非默认即**绕行缓存**（fail-closed）。
+_BYPASS_EXTRA = ("query_expand",)
+#: 影响检索结果的进程级开关（新增一个就登记一个——同 _KEYED_EXTRA 的纪律）。
+#: MDCG_CN_GRAMS（v9 N78）：mdcg.cn_recall_grams 每调用读 env（="0" 回退旧行为），
+#: 改变 expand_query_terms 召回词集——漏登即运行期翻转后同 query 命中另一口径缓存。
+_ENV_SWITCHES = ("MDCG_SEMANTIC", "MDCG_EN_ATOMS", "MDCG_UNIFY_QUERY",
+                 "MDCG_RETRIEVAL_PIPELINE", "MDCG_S7_FRESHNESS",
+                 "MDCG_CN_GRAMS")
+
+
+# 生效条件：无必需形参；返回 _ENV_SWITCHES 中每个变量名的 (名, 当前取值或 None) 元组（稳定、可哈希，随 query 缓存键一起参与比对）。
+def env_switch_key():
+    """当前进程级检索开关的快照（进 query 缓存键，防跨口径串味）。"""
+    return tuple((name, os.environ.get(name)) for name in _ENV_SWITCHES)
+
+
+class HotCache:
+    """进程内热路径缓存。
+
+    使用 OrderedDict 实现 LRU 语义：
+    - get 命中时 move_to_end（最近使用放尾）
+    - put 满时 popitem(last=False)（淘汰头=最久未用）
+    """
+
+    def __init__(self, *, max_nodes=MAX_NODES, max_queries=MAX_QUERIES,
+                 query_ttl=QUERY_TTL):
+        self._nodes: OrderedDict = OrderedDict()
+        self._queries: OrderedDict = OrderedDict()
+        self._max_nodes = max_nodes
+        self._max_queries = max_queries
+        self._query_ttl = query_ttl
+        # 统计
+        self._stats = {"node_hits": 0, "node_misses": 0,
+                       "query_hits": 0, "query_misses": 0,
+                       "invalidations": 0}
+
+    # ---------- 节点缓存 ----------
+
+    def get_node(self, node_id: str):
+        """返回 (frontmatter, body_excerpt) 或 None（未缓存）。"""
+        entry = self._nodes.get(node_id)
+        if entry is None:
+            self._stats["node_misses"] += 1
+            return None
+        self._stats["node_hits"] += 1
+        self._nodes.move_to_end(node_id)
+        return entry
+
+    def put_node(self, node_id: str, frontmatter: dict, body_excerpt: str = ""):
+        """写入/更新节点缓存。"""
+        self._nodes[node_id] = (dict(frontmatter), body_excerpt)
+        self._nodes.move_to_end(node_id)
+        while len(self._nodes) > self._max_nodes:
+            self._nodes.popitem(last=False)
+
+    def invalidate_node(self, node_id: str):
+        """失效单个节点。"""
+        self._nodes.pop(node_id, None)
+
+    # ---------- query 缓存 ----------
+
+    @staticmethod
+    def _canon(v):
+        """参数值 → 可哈希、稳定、跨调用一致的键片段（递归规范化容器）。"""
+        if v is None or isinstance(v, (bool, int, float, str, bytes)):
+            return v
+        if isinstance(v, (list, tuple)):
+            return tuple(HotCache._canon(x) for x in v)
+        if isinstance(v, (set, frozenset)):
+            return tuple(sorted((HotCache._canon(x) for x in v), key=repr))
+        if isinstance(v, dict):
+            return tuple(sorted((str(k), HotCache._canon(x))
+                                for k, x in v.items()))
+        # 其余（含自定义对象/可调用）：repr 含内存地址 → 每次不同 →
+        # 缓存永不命中（等价绕行），是**安全侧**失败（不串味）。
+        return ("repr", repr(v))
+
+    @staticmethod
+    def _query_key(query, k, layer, session, branch, validity=None,
+                   view=None, extra=None):
+        # 键必须覆盖全部影响结果的参数（正确性缺陷，非优化项）：
+        # validity（不过滤/排已过期）、view（角色视图）、extra（口径参数，
+        # 见 _KEYED_EXTRA）任一不入键都会串结果。
+        return (query, k, layer or None, session or None, branch or None,
+                bool(validity) or None, view or None,
+                HotCache._canon(extra) if extra else None)
+
+    def get_query(self, query, k=20, layer=None, session=None, branch=None,
+                  validity=None, view=None, extra=None):
+        """返回 (results, meta) 或 None（未缓存/过期）。"""
+        key = self._query_key(query, k, layer, session, branch, validity,
+                              view, extra)
+        entry = self._queries.get(key)
+        if entry is None:
+            self._stats["query_misses"] += 1
+            return None
+        ts, results, meta = entry
+        if time.time() - ts > self._query_ttl:
+            self._queries.pop(key, None)
+            self._stats["query_misses"] += 1
+            return None
+        self._stats["query_hits"] += 1
+        self._queries.move_to_end(key)
+        return results, dict(meta)
+
+    def put_query(self, query, results, meta, k=20, layer=None,
+                  session=None, branch=None, validity=None, view=None,
+                  extra=None):
+        """写入/更新 query 缓存。"""
+        key = self._query_key(query, k, layer, session, branch, validity,
+                              view, extra)
+        self._queries[key] = (time.time(), list(results), dict(meta))
+        self._queries.move_to_end(key)
+        while len(self._queries) > self._max_queries:
+            self._queries.popitem(last=False)
+
+    def invalidate_all_queries(self):
+        """清空全部 query 缓存（写入时保守全清）。"""
+        n = len(self._queries)
+        self._queries.clear()
+        if n:
+            self._stats["invalidations"] += 1
+
+    def invalidate_node_and_queries(self, node_id: str):
+        """失效节点 + 全清 query（节点变动可能影响全局排序）。"""
+        self.invalidate_node(node_id)
+        self.invalidate_all_queries()
+
+    # ---------- 全局 ----------
+
+    def clear(self):
+        """清空全部缓存。"""
+        self._nodes.clear()
+        self._queries.clear()
+
+    def stats(self):
+        """返回统计信息。"""
+        s = dict(self._stats)
+        s["node_cache_size"] = len(self._nodes)
+        s["query_cache_size"] = len(self._queries)
+        return s
+
+
+#: 进程级默认实例（每个 cg 实例可独立持有，也可共享此单例）
+_DEFAULT = None
+
+
+def default_cache():
+    """进程级默认热缓存单例。"""
+    global _DEFAULT
+    if _DEFAULT is None:
+        _DEFAULT = HotCache()
+    return _DEFAULT
+
+
+# 生效条件：cg 传入；已挂（_hotcache 非 None）时幂等返回现有实例；未挂时按 max_nodes/max_queries 显式值构造 HotCache，缺省回落 env MDCG_HOTCACHE_MAX_NODES / MDCG_HOTCACHE_MAX_QUERIES（非整数回落模块级默认），再回落模块级常量；返回挂载的 HotCache。
+def attach(cg, *, max_nodes: int = None, max_queries: int = None):
+    """给 cg 实例挂热缓存（幂等：已挂则不重复）。
+
+    容量解析优先级：显式入参 > env（MDCG_HOTCACHE_MAX_NODES /
+    MDCG_HOTCACHE_MAX_QUERIES）> 模块级常量（issue #28：容量可配，
+    大库须调大，否则 LRU 持续淘汰使热缓存形同虚设）。
+    """
+    if getattr(cg, "_hotcache", None) is not None:
+        return cg._hotcache
+
+    def _cap(explicit, env_key, default):
+        if explicit is not None:
+            return explicit
+        raw = os.environ.get(env_key, "").strip()
+        if raw:
+            try:
+                return int(raw)
+            except ValueError:
+                pass
+        return default
+
+    cg._hotcache = HotCache(
+        max_nodes=_cap(max_nodes, "MDCG_HOTCACHE_MAX_NODES", MAX_NODES),
+        max_queries=_cap(max_queries, "MDCG_HOTCACHE_MAX_QUERIES",
+                         MAX_QUERIES))
+    return cg._hotcache
+
+
+def get(cg):
+    """取 cg 实例的热缓存（未挂返回 None）。"""
+    return getattr(cg, "_hotcache", None)
+
+
+def invalidate(cg, node_id: str = None):
+    """写入后失效（节点 + query 全清）。node_id=None 时全清。"""
+    hc = get(cg)
+    if hc is None:
+        return
+    if node_id:
+        hc.invalidate_node_and_queries(node_id)
+    else:
+        hc.clear()