@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/hotcache.py

@@ -0,0 +1,214 @@
+# -*- 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 time
+from collections import OrderedDict
+
+#: 节点缓存上限
+MAX_NODES = 256
+#: query 缓存上限
+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
+
+
+def attach(cg):
+    """给 cg 实例挂热缓存（幂等：已挂则不重复）。"""
+    if not hasattr(cg, "_hotcache") or cg._hotcache is None:
+        cg._hotcache = HotCache()
+    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()

package/md_cg/hyperedge.py

@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+"""超边（hyperedge）：跨端验证回执的认知图形式化投影。
+
+上游真源 = 互验协议运行时文件（hive/interop/_receipts_ledger.tsv，六列）；
+超边节点是历史回执在认知图中的**形式化镜像**（一行 = 一条超边，回执粒度），
+单向投影：超边不反向覆写台账，协议运行时逻辑零改动。
+
+六列 → fm + 正文完整自包含回执卡，机械映射零编造：
+    received_at / verify_id / commit / verdict / receipt_job / iter_id
+  - participants  定长二元 [verify_id, receipt_job]（六列机械可得的全部参与者
+                  信息；role/harness/unit/session 归因字段台账无载，不编造）
+  - evidence      [{verify_id, commit, verdict, received_at}]
+  - corrections   []（迁移期恒空；后续跨端修正经修正面回填）
+  - ledger_row    六列整行锚（与结构键互为回放校验）
+
+幂等键：he_<sha1(六列值 join)[:10]>——同一台账行重复迁移得到同一节点 id。
+
+验证器 verify_payload 做「结构键反解 ↔ ledger_row 锚」逐字段回放比对 + 正文
+四段标记检查，经 register_verifier("hyperedge", …) 注入（或 MDCG_VERIFIER_MODULES
+外部注入；未注入时 audit DEFER——诚实不假装通过）。
+
+本模块不含写库逻辑；写入由调用方走 cg(op=write, content_kind="hyperedge", …)
+经 writepipe 既有审核链（五动词纪律：不重复造写入通道）。
+"""
+from __future__ import annotations
+
+import hashlib
+
+CONTENT_KIND = "hyperedge"
+EDGE_TYPE = "cross_verify"          # 唯一类型，留扩展位
+SOURCE_NAME = "receipts_ledger"     # 溯源锚（协议真源 TSV）
+LEDGER_COLUMNS = ("received_at", "verify_id", "commit", "verdict",
+                  "receipt_job", "iter_id")
+
+# 写入面透传给 cg.add(**extra) 的 fm 键集合（writepipe._hyperedge_extra 按此
+# 收集非 None 键）。落盘面丢字段 = 上游声明静默失效（比报错更难发现）。
+EXTRA_FM_KEYS = ("content_kind", "edge_type", "participants", "evidence",
+                 "corrections", "iter_id", "source", "received_at",
+                 "verdict", "ledger_row")
+
+# 正文四段标记（build_content 段落标题词；验证器检查齐备——无 fm 解析能力
+# 的外部工具直读正文即可取数，这是「可被外部理解的正式结构」的最低保障）。
+CONTENT_MARKERS = ("参与者", "证据", "修正", "时间")
+
+_EMPTY_NOTE = "（台账原始行无此字段）"   # 空字段的事实陈述（非编造占位）
+
+
+# 生效条件：v 传入即归一为去空格字符串（None 得空串），无条件分支；
+def _clean(v):
+    return "" if v is None else str(v).strip()
+
+
+# 生效条件：row 为含六列键的 dict 时返回六列清洗副本；缺列或非 dict 即抛
+# ValueError（fail-closed，不猜测补值）；
+def _norm_row(row):
+    if not isinstance(row, dict):
+        raise ValueError("台账行须为 dict（六列键），得到 %s" % type(row).__name__)
+    missing = [c for c in LEDGER_COLUMNS if c not in row]
+    if missing:
+        raise ValueError("台账行缺列：%s（fail-closed，不猜测补值）" % missing)
+    return {c: _clean(row.get(c)) for c in LEDGER_COLUMNS}
+
+
+# 生效条件：row 经 _norm_row 校验即返回固定键集 fm（content_kind/edge_type/
+# participants/evidence/corrections/iter_id/source/received_at/verdict/ledger_row）；
+def fm_from_row(row):
+    """台账行 → 超边 fm（schema v0.1，协议冻结前允许破坏性调整）。"""
+    r = _norm_row(row)
+    return {
+        "content_kind": CONTENT_KIND,
+        "edge_type": EDGE_TYPE,
+        # 定长二元：空串占位保证反解对称（[0]→verify_id、[1]→receipt_job）。
+        "participants": [r["verify_id"], r["receipt_job"]],
+        "evidence": [{"verify_id": r["verify_id"], "commit": r["commit"],
+                      "verdict": r["verdict"], "received_at": r["received_at"]}],
+        "corrections": [],
+        "iter_id": r["iter_id"],
+        "source": SOURCE_NAME,
+        "received_at": r["received_at"],
+        "verdict": r["verdict"],
+        "ledger_row": dict(r),
+    }
+
+
+# 生效条件：fm 的 participants 为定长二元、evidence 为单项列表时返回六列重建
+# 行（回放方向 H1：反解六列）；形态不符即抛 ValueError；
+def rows_from_fm(fm):
+    """fm 结构键 → 台账行（反解方向，不依赖 ledger_row 锚）。"""
+    parts = fm.get("participants")
+    if not isinstance(parts, list) or len(parts) != 2:
+        raise ValueError("participants 须为定长二元 [verify_id, receipt_job]")
+    ev = fm.get("evidence")
+    if not isinstance(ev, list) or len(ev) != 1 or not isinstance(ev[0], dict):
+        raise ValueError("evidence 须为单项列表"
+                         "（{verify_id, commit, verdict, received_at}）")
+    e = ev[0]
+    return {
+        "received_at": _clean(e.get("received_at")),
+        "verify_id": _clean(parts[0]),
+        "commit": _clean(e.get("commit")),
+        "verdict": _clean(e.get("verdict")),
+        "receipt_job": _clean(parts[1]),
+        "iter_id": _clean(fm.get("iter_id")),
+    }
+
+
+# 生效条件：fm 含六列信息（ledger_row 锚优先，缺锚走结构键反解）时返回六列行；
+# 两者皆不可解析即抛 ValueError；
+def _row_of_fm(fm):
+    anchored = fm.get("ledger_row")
+    if isinstance(anchored, dict):
+        return {c: _clean(anchored.get(c)) for c in LEDGER_COLUMNS}
+    return rows_from_fm(fm)
+
+
+# 生效条件：fm 经 _row_of_fm 可解析即返回含四段标记（参与者/证据/修正/时间）
+# 的正文，空字段以「台账原始行无此字段」事实陈述呈现；
+def build_content(fm):
+    """超边 fm → 四段正文（参与者/证据/修正/时间）。"""
+    r = _row_of_fm(fm)
+
+    def v(col):
+        return r[col] if r[col] else _EMPTY_NOTE
+
+    corr = fm.get("corrections") or []
+    lines = [
+        "# 跨端验证超边（%s / %s）" % (CONTENT_KIND, EDGE_TYPE),
+        "",
+        "## 参与者",
+        "- verify_id: %s" % v("verify_id"),
+        "- receipt_job: %s" % v("receipt_job"),
+        "",
+        "## 证据",
+        "- commit: %s" % v("commit"),
+        "- verdict: %s" % v("verdict"),
+        "- received_at: %s" % v("received_at"),
+        "",
+        "## 修正",
+    ]
+    lines.extend(("- %s" % _clean(c) for c in corr if _clean(c)) if corr
+                 else ["无（迁移期恒空；后续跨端修正经修正面回填）"])
+    lines.extend([
+        "",
+        "## 时间",
+        "- received_at: %s" % v("received_at"),
+        "- iter_id: %s" % v("iter_id"),
+        "",
+        "溯源：%s（TSV 真源单向投影，超边不反向覆写台账）" % SOURCE_NAME,
+    ])
+    return "\n".join(lines)
+
+
+# 生效条件：row 经 _norm_row 校验即返回载荷 {ledger_row, frontmatter, content}
+# （写入面读向齐备，幂等 id 另经 node_id_for 取）；
+def row_from_ledger(row):
+    """台账行 → 超边载荷（{ledger_row, frontmatter, content}）。"""
+    r = _norm_row(row)
+    fm = fm_from_row(r)
+    return {"ledger_row": dict(r), "frontmatter": fm,
+            "content": build_content(fm)}
+
+
+# 生效条件：node 为 dict（frontmatter 嵌套或 fm 键平铺两形态）且结构键可反解
+# 时返回载荷（ledger_row 优先取节点锚，缺锚用结构重建行）；结构不可反解即抛
+# ValueError；
+def payload_from_node(node):
+    """节点 → 载荷（回放重建读向 H1）。"""
+    if not isinstance(node, dict):
+        raise ValueError("节点须为 dict")
+    fm = node.get("frontmatter") if isinstance(node.get("frontmatter"), dict) \
+        else node
+    anchored = fm.get("ledger_row")
+    rebuilt = rows_from_fm(fm)
+    row = ({c: _clean(anchored.get(c)) for c in LEDGER_COLUMNS}
+           if isinstance(anchored, dict) else rebuilt)
+    return {"ledger_row": row, "frontmatter": fm,
+            "content": node.get("content") or ""}
+
+
+# 生效条件：a（writepipe 写入请求，fm 键平铺顶层）传入即返回验证器三键载荷
+# {ledger_row, frontmatter, content}——frontmatter 收集 a 中非 None 的
+# EXTRA_FM_KEYS 键；ledger_row 非 dict 时为 None（由验证器 fail-closed 裁决）；
+def audit_payload(a):
+    """writepipe audit 闸的超边载荷装配（fm 键平铺 → 三键载荷）。"""
+    row = a.get("ledger_row")
+    return {"ledger_row": row if isinstance(row, dict) else None,
+            "frontmatter": {k: a.get(k) for k in EXTRA_FM_KEYS
+                            if a.get(k) is not None},
+            "content": a.get("content") or ""}
+
+
+# 生效条件：row 经 _norm_row 校验即返回 he_<sha1(逐列「len:val」拼接)[:10]>
+# （同一台账行恒同 id，重复迁移幂等；任意列内容不可伪造边界）；
+def node_id_for(row):
+    """幂等键：同一台账行重复迁移得到同一节点 id。
+
+    **无歧义规范化**（2026-09-20 v14 缺陷 G 修复）：逐列 `<len>:<val>` 前缀
+    拼接——长度前缀由本函数计算、不可被列内容伪造，故任意两列之间搬移含任意
+    字符的文本都得不同 canon。旧实现直接 `"\\x1f".join(...)`：`verify_id="a"`
+    + `commit="b\\x1fc"` 与 `verify_id="a\\x1fb"` + `commit="c"` 撞同一 id
+    （不是 SHA-1 碰撞，是规范化没做转义/长度前缀）。
+
+    id 口径变更说明：canon 输入形态改变 → id 取值随之改变。属 schema v0.1
+    内的破坏性调整（该 schema 明示允许）；实测库内 `he_` 节点为 0，无历史
+    迁移数据需兼容。
+    """
+    r = _norm_row(row)
+    canon = "".join("%d:%s" % (len(r[c]), r[c]) for c in LEDGER_COLUMNS)
+    return "he_" + hashlib.sha1(canon.encode("utf-8")).hexdigest()[:10]
+
+
+# 生效条件：payload 缺 ledger_row/frontmatter、结构键不可反解、反解与锚不一致
+# 或正文缺四段标记即 REJECT；逐字段一致且标记齐备即 ACCEPT（detail 带幂等 id）；
+# 其它异常照抛（由 audit 包为 DEFER）；
+def verify_payload(payload, ctx=None):
+    """audit 验证器签名：回放比对（fm/content 反解 ↔ ledger_row 锚）。"""
+    if not isinstance(payload, dict):
+        return {"state": "REJECT", "evidence": "payload 须为 dict，得到 %s"
+                                                % type(payload).__name__}
+    row = payload.get("ledger_row")
+    fm = payload.get("frontmatter")
+    if not isinstance(fm, dict):
+        fm = payload        # 平铺形态：载荷自身承载 fm 键（writepipe 闸外直调）
+    if not isinstance(row, dict):
+        return {"state": "REJECT",
+                "evidence": "payload 缺 ledger_row 锚（回执卡不自包含）"}
+    try:
+        anchored = {c: _clean(row.get(c)) for c in LEDGER_COLUMNS}
+        rebuilt = rows_from_fm(fm)          # 形态坏 → ValueError → REJECT
+    except ValueError as exc:
+        return {"state": "REJECT", "evidence": str(exc)}
+    diffs = ["%s: %r != %r" % (c, anchored[c], rebuilt[c])
+             for c in LEDGER_COLUMNS if anchored[c] != rebuilt[c]]
+    if diffs:
+        return {"state": "REJECT", "evidence": "回放比对不一致：%s" % "; ".join(diffs),
+                "detail": {"field_diffs": diffs}}
+    ctext = payload.get("content") if isinstance(payload.get("content"), str) else ""
+    miss = [m for m in CONTENT_MARKERS if m not in ctext]
+    if miss:
+        return {"state": "REJECT", "evidence": "正文缺四段标记：%s（不自包含）" % miss}
+    return {"state": "ACCEPT",
+            "evidence": "回放重建六列逐字段一致（verify_id=%r）"
+                        % anchored["verify_id"],
+            "detail": {"node_id": node_id_for(anchored)}}
+
+
+# 生效条件：audit_mod 提供 register_verifier 即把 verify_payload 以 override=True
+# 注入（重复加载幂等）；
+def register(audit_mod):
+    """MDCG_VERIFIER_MODULES 入口：把回放比对验证器注入 audit。"""
+    audit_mod.register_verifier(CONTENT_KIND, verify_payload, override=True)

package/md_cg/identity.py

@@ -92,6 +92,7 @@ _POSITION_TAGS = {
 }
 
 
+# 生效条件：subject_id 为假值（None/空串）时 s 为空串、无 ":" 可切，返回 ("user","")；否则 strip 后含 ":" 则按首个冒号切成 kind/name，kind 经 strip().lower() 后不在 SUBJECT_KIND 即改记 "user"，不含 ":" 时整串作为 name 归 "user"。
 def split_subject(subject_id):
     """`"self:lingshu"` → `("self", "lingshu")`；无前缀按 `user` 处理。"""
     s = (subject_id or "").strip()
@@ -104,21 +105,25 @@ def split_subject(subject_id):
     return "user", s
 
 
+# 生效条件：对 str(s) 的每个字符，isalnum() 为真或字符属于 "_-" 时原样保留，其余一律替换为 "_"（s 为 None/非字符串时按 str(s) 结果逐字符处理）。
 def _slug(s):
     return "".join(ch if (ch.isalnum() or ch in "_-") else "_" for ch in str(s))
 
 
+# 生效条件：subject_id 经 split_subject 与 _slug 处理后，按 PROFILE_PREFIX + kind + "_" + name 拼出档案节点 id。
 def subject_node_id(subject_id):
     """主体的档案节点 id（锚点载体）：`identity_<kind>_<name>`。"""
     kind, name = split_subject(subject_id)
     return f"{PROFILE_PREFIX}{_slug(kind)}_{_slug(name)}"
 
 
+# 生效条件：给定 prefix 与 subject_id（seed 缺省为空串且原样参与哈希，不做回落）即返回 f"{PROFILE_PREFIX}{prefix}_{_slug(subject_id)}_{sha256(f'{subject_id}|{seed}|{time.time()}')前10位}"——prefix 只参与结果拼接、不参与哈希，因哈希含 time.time() 故每次调用返回的后缀都不同。
 def _nid(prefix, subject_id, seed=""):
     h = hashlib.sha256(f"{subject_id}|{seed}|{time.time()}".encode("utf-8"))
     return f"{PROFILE_PREFIX}{prefix}_{_slug(subject_id)}_{h.hexdigest()[:10]}"
 
 
+# 生效条件：rec 先被 dict(rec) 拷贝，仅当拷贝中缺 "ts" 键时补 time.time()，随后写入 cg.root 下 AUDIT_FILE 指向的 jsonl；写盘抛 OSError 时静默跳过并返回 None。
 def log(cg, rec):
     rec = dict(rec)
     rec.setdefault("ts", time.time())
@@ -128,6 +133,7 @@ def log(cg, rec):
         pass
 
 
+# 生效条件：cg.root 下 AUDIT_FILE 路径缺失或打开即抛 OSError 时返回空列表；否则逐行解析非空 JSON（json.loads 抛 ValueError 的行跳过），读取中途抛 OSError 时返回已解析的部分 out，正常返回 out[-int(limit or 100):]，其中 limit 为 0/空串等假值时按 100 取值；
 def history(cg, limit=100):
     p = os.path.join(cg.root, AUDIT_FILE)
     out = []
@@ -152,6 +158,7 @@ def history(cg, limit=100):
 # 扮演论三接口：memory / anchor / values
 # --------------------------------------------------------------------------
 
+# 生效条件：subject_id 定 kind 默认值，kind 参数为真值时覆盖之；node_id 为假值时用 _nid("obs", subject_id, text[:32])（含 time.time()）生成；标签为 list(tags or []) 追加 subject:<subject_id>、TAG_OBS、kind:<k>，evidence 为真值时再追加一条 evidence:<evidence>；condition_space 以 dict(condition_space or {}) 为底并 setdefault subject/kind；落层用 layer 真值否则 "knowledge"，role 为真值时随 extra 传 role；返回 {"ok": True, "node_id", "subject_id", "kind"}。
 def observe(cg, subject_id, text, *, kind=None, role=None, layer=None, tags=None,
             condition_space=None, importance=0.5, verification_basis=None,
             evidence=None, node_id=None, override=False):
@@ -178,6 +185,7 @@ def observe(cg, subject_id, text, *, kind=None, role=None, layer=None, tags=None
     return {"ok": True, "node_id": nid, "subject_id": subject_id, "kind": k}
 
 
+# 生效条件：kind 参数为真值时覆盖 split_subject(subject_id) 得到的类型，k 不在 SUBJECT_KIND 时抛 ValueError；k 为 "self" 落 "self" 层、其余落 "anchor" 层，但 requested_layer 等于 "self" 且 k 不为 "self" 时抛 ValueError（不写盘）；节点 id 取自 subject_node_id(subject_id)，返回含 layer 与 protected True。
 def set_anchor(cg, subject_id, text, *, kind=None, condition_space=None,
                importance=0.9, override=False, requested_layer=None):
     """anchor 接口：写入身份锚点（不可遗忘）。
@@ -209,6 +217,7 @@ def set_anchor(cg, subject_id, text, *, kind=None, condition_space=None,
             "layer": layer, "protected": True}
 
 
+# 生效条件：kind 参数为真值时覆盖 split_subject(subject_id) 得到的类型；node_id 为假值时用 _nid("trait", subject_id, trait[:24]) 生成；落层硬编码为 "structural"；position 为真值时追加 position:<position> 标签；verification_basis 缺省为 "data"，importance 缺省 0.6；返回 layer 为 "structural" 与所用 condition_space。
 def add_trait(cg, subject_id, trait, *, condition_space=None, importance=0.6,
               position=None, kind=None, verification_basis="data",
               override=False, node_id=None):
@@ -238,6 +247,7 @@ def add_trait(cg, subject_id, trait, *, condition_space=None, importance=0.6,
 # 位置效应推断（智能论 v3.4 §十三）
 # --------------------------------------------------------------------------
 
+# 生效条件：tags 先转为 set(tags or []) 后并列判定——role 属于 ("command","tool-output") 或 layer 等于 "contextual" 则加 "record"；tags 与 _POSITION_TAGS 各项标记集有交集则加对应 pos；ev_pos 或 ev_neg 为真值则加 "verify"；role 属于 ("user","assistant") 或 tags 中任一字符串以 "cap:" 开头则加 "output"；layer 等于 "goals" 则加 "sustain"；返回该并集。
 def _votes(role, layer, tags, vb, ev_pos, ev_neg):
     """把一条行为证据映射到位置效应候选（可多面）。规则可审计、可扩展。"""
     tags = set(tags or [])
@@ -257,6 +267,7 @@ def _votes(role, layer, tags, vb, ev_pos, ev_neg):
     return v
 
 
+# 生效条件：遍历 cg.index.get("nodes")（缺键或值为假时取空 dict，此时必然返回 position=unknown、confidence=0.0、votes={}），仅统计标签含 "subject:<subject_id>" 且不含 TAG_ANCHOR/TAG_TRAIT 的节点，票由 _votes 得出；无任何票时返回 unknown/0.0/{}；有票时 winners 为 POSITION_ORDER 中票数等于最高票的位置，position 取 winners[0]，confidence=round(top/total, 3)，多赢家时以 tie 列出。
 def infer_position(cg, subject_id):
     """按该主体的行为证据投票推断位置效应（带 confidence / votes，可审计）。
 
@@ -288,12 +299,14 @@ def infer_position(cg, subject_id):
             "tie": winners if len(winners) > 1 else []}
 
 
+# 生效条件：pos 取自 POSITIONS，缺键时以空 dict 兜底，故未知 pos 返回 {"position": pos, "unit": None, "effect": None, "duty": None}。
 def _position_view(pos):
     meta = POSITIONS.get(pos) or {}
     return {"position": pos, "unit": meta.get("unit"),
             "effect": meta.get("effect"), "duty": meta.get("duty")}
 
 
+# 生效条件：仅遍历标签含 "subject:<subject_id>" 的节点，其中带 TAG_ANCHOR 者进 anchors，否则（elif）带 TAG_TRAIT 者进 traits——两标签同时存在时只进 anchors、不进 traits；anchor 取 anchors[0] 或 None；位置相关字段来自 infer_position(cg, subject_id)。
 def profile(cg, subject_id):
     """主体画像 = 身份锚点 + 位置效应 + 条件特征（取代单一「用户画像」）。"""
     k, name = split_subject(subject_id)
@@ -324,6 +337,7 @@ def profile(cg, subject_id):
     return out
 
 
+# 生效条件：counts 按每个以 "subject:" 开头的字符串标签出现次数累加（即标签次数，不是节点数），按 (-次数, sid) 排序后逐个 sid 调 infer_position；limit 为 0/None/空串等使 `limit and int(limit) > 0` 为假时返回全量 out，仅当 limit 为真值且 int(limit) > 0 时返回前 int(limit) 项。
 def positions(cg, limit=0):
     """所有主体的位置效应分布（OS 视角：谁在记录/反思/验证/输出/维生）。"""
     nodes = cg.index.get("nodes") or {}
@@ -342,6 +356,7 @@ def positions(cg, limit=0):
     return out[:int(limit)] if limit and int(limit) > 0 else out
 
 
+# 生效条件：cg.root/AUDIT_FILE 不存在时返回 0；否则逐行统计 strip() 后非空的行数，读取途中抛 OSError 时返回已累计的 n。
 def _audit_count(cg):
     p = os.path.join(cg.root, AUDIT_FILE)
     if not os.path.exists(p):
@@ -357,6 +372,7 @@ def _audit_count(cg):
     return n
 
 
+# 生效条件：以 positions(cg)（limit 缺省 0，返回全量）得主体列表并按各自 position 聚合计数，与 _audit_count(cg) 一并返回 subjects/by_position/audit_records。
 def summary(cg):
     """身份面汇总：主体数 + 位置分布（供 health / 运维审计，流式计数不载全量）。"""
     ps = positions(cg)
@@ -367,8 +383,9 @@ def summary(cg):
             "audit_records": _audit_count(cg)}
 
 
+# 生效条件：无入参，恒返回 POSITION_ORDER 中每个 p 的 POSITIONS[p] 副本、INTERFACES 各值副本以及 list(SUBJECT_KIND)。
 def catalog():
     """自描述：位置效应表 + 三接口（供 MCP / 文档对照协议验证）。"""
     return {"positions": {p: dict(POSITIONS[p]) for p in POSITION_ORDER},
             "interfaces": {k: dict(v) for k, v in INTERFACES.items()},
-            "kinds": list(SUBJECT_KIND)}
+            "kinds": list(SUBJECT_KIND)}