@furongjun1999/dsh-memory 0.6.0 → 0.6.1

package/md_cg/protect.py

@@ -40,12 +40,18 @@ import time
 
 from . import nodefile
 from .fsutil import append_jsonl, atomic_write
+from .security import DEFAULT_SENSITIVITY
 
 PROTECTED_LAYERS = ("self", "anchor")
 AUTO_PROTECT_IMPORTANCE = 0.70
 HISTORY_DIR = "_protected_history"
 AUDIT_FILE = "_protected_audit.jsonl"
 
+# 索引条目里的**门控三键**（键集单点定义）：`_node_entry`（mdcg.py:1294-1298）与
+# `_stage`（mdcg.py:1848-1851）恒落这三键，值可为 None ⇒「键不存在」不是
+# 「未标记」的可靠判据（N213 同根，2026-09-28）。None = **索引未记录该标记**。
+_GATE_UNKNOWN_KEYS = ("protected", "immutable", "self_state")
+
 
 class ProtectionError(PermissionError):
     """受保护节点的写动作被拒绝。"""
@@ -53,14 +59,32 @@ class ProtectionError(PermissionError):
 
 # ---------------------------------------------------------------- 判定
 
-# 生效条件：对任意 cg、node_id 无条件返回 `(cg.index 或其假值时的 {})["nodes"]`（该键缺失或假值时为 `{}`）中以 node_id 为键的值，索引无此键时返回 None。
+# 生效条件：cg 具备可调用的 _maybe_reload_index 时先调一次（索引代际探活，异常静默）；随后对任意 cg、node_id 返回 `(cg.index 或其假值时的 {})["nodes"]`（该键缺失或假值时为 `{}`）中以 node_id 为键的值，索引无此键时返回 None。
 def _entry(cg, node_id):
+    """索引条目读取单点（判定前**代际探活**）。
+
+    N213 同根（2026-09-28）：保护面的全部判据（_fm / is_protected / is_immutable
+    / guard_write / guard_forget / guard_move / stats）都经由本函数直读**本进程
+    内存索引**，而写面只有 `MdCG.add`（mdcg.py:1508）接了探活——删除（forget）、
+    降级搬迁（_move_layer）、统计与角色视图等出口全都没有。他进程（serve 常驻、
+    autoflush=1 只 flush 不 close）新盖的 immutable/protected 在陈旧条目上不存在
+    → 判定「未标记」→ 受保护节点被静默覆写/删除/搬迁，无快照无审计。
+    探活放在这里 = 保护面一次接线、全部出口同闸（签名未变时只有一次 stat +
+    一次 listdir；重载是稀疏事件）。同理 `_resolve_target` 的探活在本函数外层
+    成了冗余的一次廉价检查，保留不动。
+    """
+    _reload = getattr(cg, "_maybe_reload_index", None)
+    if callable(_reload):
+        try:
+            _reload()
+        except Exception:                 # noqa: BLE001 —— 探活失败不得阻断判定本身
+            pass
     return ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
 
 
-# 生效条件：cg 索引中无 node_id 条目时返回 None；有条目时先取 layer/importance（缺 importance 键回落 0.5）/protected/protection_reason/immutable/self_state，仅当条目缺 protected 或 immutable、或（缺 self_state 且条目 layer∈PROTECTED_LAYERS）时再经 cg.get(node_id) 用 frontmatter 覆盖这四个键（cg.get 抛异常或返回假值时保留索引值；layer 取 frontmatter.layer or 索引 layer，importance 缺键时回落索引 importance）。
+# 生效条件：cg 索引中无 node_id 条目时返回 None；有条目时先取 layer/importance（缺 importance 键回落 0.5）/protected/protection_reason/immutable/self_state，仅当条目缺 protected 或 immutable、或（缺 self_state 且条目 layer∈PROTECTED_LAYERS）、或（条目 layer∈PROTECTED_LAYERS 且 _GATE_UNKNOWN_KEYS 中任一键的值为 None）时再经 cg.get(node_id) 用 frontmatter 覆盖这四个键（cg.get 抛异常或返回假值时保留索引值；layer 取 frontmatter.layer or 索引 layer，importance 缺键时回落索引 importance）。
 def _fm(cg, node_id):
-    """取判定所需的 frontmatter 字段；索引快照缺 protected 时回退读文件。"""
+    """取判定所需的 frontmatter 字段；索引快照门控字段**未知**时回退读文件。"""
     e = _entry(cg, node_id)
     if e is None:
         return None
@@ -74,9 +98,23 @@ def _fm(cg, node_id):
     }
     # 回退读文件：索引快照缺字段时。self_state 只在受保护层（self/anchor）
     # 需要，回退代价被限制在少量节点上，不影响全量统计性能。
+    _layer = str(e.get("layer") or "")
     need_fallback = ("protected" not in e or "immutable" not in e
                      or ("self_state" not in e
-                         and str(e.get("layer") or "") in PROTECTED_LAYERS))
+                         and _layer in PROTECTED_LAYERS))
+    # N213 同根（2026-09-28）：`_node_entry`/`_stage` **恒落**这三键（值可为
+    # None）⇒ 上面的「缺键」判据在本仓所有构造点恒假、第四个析取子句不可达，
+    # `_fm` 100% 信任索引、**从不重读文件**；索引里的 None 被当「未标记」采信，
+    # 而「只改文件、不进索引写日志」的门控写点（`protect.mark` 一类）在陈旧
+    # 条目里正是 None → guard_write/guard_forget/guard_move 静默放行。
+    # 值为 None 即「索引未记录该标记」，唯一权威是文件——但读盘有代价，
+    # 只在**受保护层**（self/anchor，节点数极少；层保护本身已拦 不可覆盖/
+    # 不可遗忘，None 决定的是 self_state 豁免与层间搬迁的细粒度判定）无条件
+    # 回退；非受保护层由「门控写点必须进写日志」承担（`mark` 已随本批接线，
+    # `add(immutable=True)` 本就经 _stage），故不付全池读盘代价。
+    if not need_fallback and _layer in PROTECTED_LAYERS \
+            and any(e.get(_k) is None for _k in _GATE_UNKNOWN_KEYS):
+        need_fallback = True
     if need_fallback:
         try:
             node = cg.get(node_id)
@@ -148,9 +186,19 @@ def _audit(cg, action, node_id, reason, actor=None, snapshot=None):
     return rec
 
 
-# 生效条件：cg.get(node_id) 抛异常或返回假值时返回 None；否则在 cg.root/HISTORY_DIR/node_id 下以时间戳命名写入当前 frontmatter 与 content，_write_node 抛异常时返回 None，成功则返回相对 cg.root 且以 '/' 分隔的路径。
+# 生效条件：cg.get(node_id) 抛异常或返回假值时返回 None；否则在 cg.root/HISTORY_DIR/node_id 下以时间戳命名写入当前 frontmatter 与 content，_write_node 抛异常时返回 None，成功则追加一条 action="snapshot" 的审计（_audit，actor 取 cg.actor）并返回相对 cg.root 且以 '/' 分隔的路径。
 def snapshot(cg, node_id):
-    """把节点当前版本快照进 `_protected_history/<id>/<ts>.md`，返回相对路径。"""
+    """把节点当前版本快照进 `_protected_history/<id>/<ts>.md`，返回相对路径。
+
+    N228（2026-09-28）：本函数此前**全文零审计**——而它是**落盘写入**（写
+    `_protected_history/`，且这些快照是后续 override 快照链的基线）。经工具面
+    `mdcg_protect(action="snapshot")`（此前只要求粗粒度 write）任何 can_write
+    角色都能在自己可读的节点上制造未审计磁盘写入（实测 `_audit.jsonl` 条数
+    8→8 不变）。本批两条收口：① 工具面 op 要求对齐规范出口（protect 面在
+    `cg(op="protect")` 上级为 designer 专属）；② 快照成功即留痕（本函数内，
+    两条入口——工具面与 `guard_*` 的 `_allow`——都覆盖；`_allow` 路径会有
+    「snapshot + 具体守卫动作」两条审计，属如实记录而非重复计数）。
+    """
     try:
         node = cg.get(node_id)
     except Exception:
@@ -166,7 +214,10 @@ def snapshot(cg, node_id):
                        node.get("content") or "")
     except Exception:
         return None
-    return os.path.relpath(p, cg.root).replace("\\", "/")
+    rel = os.path.relpath(p, cg.root).replace("\\", "/")
+    _audit(cg, "snapshot", node_id, "显式快照（%s）" % rel,
+           actor=getattr(cg, "actor", None), snapshot=rel)
+    return rel
 
 
 # 生效条件：cg.root/HISTORY_DIR/node_id 不是目录时返回 []；是目录时返回该目录下以 .md 结尾（不递归）的文件按名称排序后的 `HISTORY_DIR/node_id/文件名` 列表，无匹配文件则列表为空。
@@ -231,15 +282,96 @@ def guard_move(cg, node_id, to_layer, override=False, actor=None):
         f"节点 {node_id} 受写保护（{why}）；降级移出保护层需显式 override=True")
 
 
-# 生效条件：cg.get(node_id) 抛异常或返回假值时返回 None；否则把 protected=True 与 protection_reason=reason 写入 cg.root 下 node["path"]（该键缺失即抛 KeyError）对应的 frontmatter 并保持原 content，随后门条目存在时同步其 protected/protection_reason，返回 {'node_id': node_id, 'protected': True, 'reason': reason}。
+# 生效条件：cg 具备可调用的 _maybe_reload_index 时先调一次；层取形参 layer、索引条目 layer、节点 frontmatter layer 中首个真值（皆假值回落 "knowledge"，与 require_layer_write 缺省同口径）；敏感度取形参 sensitivity、索引条目 sensitivity、节点 frontmatter sensitivity 中首个真值（皆假值回落 security.DEFAULT_SENSITIVITY）；返回 (层, 敏感度) 二元组。
+def _resolve_target(cg, node_id, layer=None, sensitivity=None):
+    """既有节点写面的「层 / 敏感度」解析**单点**（不设第二份口径）。
+
+    索引代际探活（N195 同族）：写面直读本进程内存索引，他进程刚写入/搬迁的节点
+    在本进程索引中不存在、或层位陈旧 → 解析出的层不是真层，层闸会**静默失效**
+    （「越权改 knowledge」被当成「同层正当写」放行）。故进入判定前先探活一次
+    （签名未变时只有一次 stat）。
+    """
+    _reload = getattr(cg, "_maybe_reload_index", None)
+    if callable(_reload):
+        _reload()
+    e = _entry(cg, node_id) or {}
+    _layer = layer or e.get("layer")
+    _sens = sensitivity or e.get("sensitivity")
+    if not _layer or not _sens:
+        try:
+            node = cg.get(node_id)
+        except Exception:                     # noqa: BLE001 —— 读面失败不阻断判据本身
+            node = None
+        if node:
+            f = node.get("frontmatter") or {}
+            _layer = _layer or f.get("layer")
+            _sens = _sens or f.get("sensitivity")
+    return _layer or "knowledge", _sens or DEFAULT_SENSITIVITY
+
+
+# 生效条件：经 _resolve_target 解析出节点真层与敏感度后，cg.principal 非 None 且具备 require_layer_write 时调 principal.require_layer_write(layer, sensitivity)（越权抛 AccessDenied），返回解析出的层；cg 无 principal（裸 MdCG）时不做任何判定。
+def require_layer(cg, node_id, layer=None, sensitivity=None, actor=None):
+    """既有节点写面的 **principal 层闸**单点（不含引擎级保护闸）。
+
+    N209（2026-09-28，同族未接线的相邻写面入口）：「只有 `falsified` 一态接了
+    层闸」之外的三条写面全程只认管理位/保护位、**不认层白名单**——
+    `MdCGSecure.verify` 的 confirmed/weakened 分支直写被验证节点本体
+    （`md_cg/mdcg.py:3502`）、`trust.set_state`（验证态唯一推进入口 ⇒ 依赖者
+    `mark_dependents` 与 `set_verification` 两条写路，`md_cg/trust.py:697-698`）、
+    `MdCG._move_layer`（降级搬迁 = 源层一次删除写 + 目标层一次新增写，
+    `md_cg/mdcg.py:3405`）。后果：持 verify 令牌（`layers_allow` 仅
+    rejected/contextual、forbidden 明列「knowledge/self/anchor 层」）即可改写
+    knowledge 层节点本体、把 self 层依赖者置 doubted、把 knowledge 节点搬出层。
+    层闸口径与 `MdCGSecure.add`/`add_rejected` 一致（`md_cg/mdcos.py:3889`/`:3898`）。
+    """
+    _layer, _sens = _resolve_target(cg, node_id, layer=layer,
+                                    sensitivity=sensitivity)
+    p = getattr(cg, "principal", None)
+    if p is not None and hasattr(p, "require_layer_write"):
+        p.require_layer_write(_layer, _sens)
+    return _layer
+
+
+# 生效条件：先经 require_layer(cg, node_id, layer, sensitivity) 做 principal 层闸（越权抛 AccessDenied），再委托 guard_write(cg, node_id, layer=解析层, override=override, actor=actor) 并返回其结果。
+def guard_overwrite(cg, node_id, layer=None, sensitivity=None,
+                    override=False, actor=None):
+    """既有节点**覆写**前的统一双闸：principal 层写权限 + 引擎级写保护。
+
+    N197/N208（2026-09-28）：「同一身份对**同层**的 `add` 已被
+    `require_layer_write` 拒绝，但直调 `cg._write_node` 的写面照样落盘」——
+    层闸被同一库的两条出口口径不一致地绕开。与 N131（review 队列 merge 面）
+    同序同错型：principal 层写闸在先（对照 `MdCGSecure.add` :3889），引擎级
+    `guard_write` 在后（对照 `MdCG.add` :1509）。任何覆写**既有节点**的写面都
+    必须先过这里，否则 self/anchor 层与 immutable 节点被无痕覆写：不抛错、不落
+    `_protected_history` 快照、不写 `_protected_audit.jsonl`。
+
+    索引代际探活（N195 同族）：写面直读本进程内存索引，他进程刚置的保护位在本
+    进程索引中不存在 → `is_immutable` 的 `_entry` 得 None → 判 False，两道闸
+    会**同时静默失效**。故进入判定前先探活一次（签名未变时只有一次 stat）；
+    解析与层闸由 `require_layer` 同一单点承担。
+    """
+    _layer = require_layer(cg, node_id, layer=layer, sensitivity=sensitivity)
+    return guard_write(cg, node_id, layer=_layer, override=override, actor=actor)
+
+
+# 生效条件：cg.get(node_id) 抛异常或返回假值时返回 {'ok': False, 'error': 'node_not_found', 'node_id': node_id}（负路由，形态对齐 trust.set_state:692）；否则把 protected=True 与 protection_reason=reason 写入 cg.root 下 node["path"]（该键缺失即抛 KeyError）对应的 frontmatter 并保持原 content，随后门条目存在时同步其 protected/protection_reason 并把该条目并入索引写日志（_dirty 标脏 + flush，失败静默），返回 {'node_id': node_id, 'protected': True, 'reason': reason}。
 def mark(cg, node_id, reason):
-    """给节点打上 `protected=True` 标记（写回 frontmatter，不动 content）。"""
+    """给节点打上 `protected=True` 标记（写回 frontmatter，不动 content）。
+
+    节点不存在时返回**负路由** `{"ok": False, "error": "node_not_found",
+    "node_id": node_id}`（与 `trust.set_state` 的不存在分支逐键同形），
+    不再裸返回 None（H9④ 前）：None 与「成功」在调用方眼里都非 dict，
+    `mcp_server._protect_call` 直接把它序列化成 `null` 回给 MCP 客户端
+    ——不存在的 node_id 被读成「打标成功」，而 `_write_node` 从未发生。
+    调用方分流：失败看 `r.get("ok") is False` / `"error" in r`，
+    成功路径的返回键**不变**（node_id / protected / reason，无 ok 键）。
+    """
     try:
         node = cg.get(node_id)
     except Exception:
         node = None
     if not node:
-        return None
+        return {"ok": False, "error": "node_not_found", "node_id": node_id}
     fm = node.get("frontmatter") or {}
     fm["protected"] = True
     fm["protection_reason"] = reason
@@ -249,6 +381,21 @@ def mark(cg, node_id, reason):
     if e is not None:
         e["protected"] = True
         e["protection_reason"] = reason
+        # N213 同根（2026-09-28）：保护位是**门控字段**，只改内存条目 + 文件而
+        # 不进索引写日志 ⇒ 他进程（以及本进程 compact 前的重载）把该节点当
+        # 「未标记」→ guard_forget / guard_move 静默放行。与 add 同口径：
+        # `_dirty[nid] = e` 标脏（**不走 _stage**——它会重复累加该桶计数）
+        # 并 flush，使日志成为跨进程可见的代际载体。日志化失败不阻断打标本身
+        # （文件已改，下一次 compact/rebuild 的 _scan_nodes 会带上该标记）。
+        _dirty = getattr(cg, "_dirty", None)
+        if isinstance(_dirty, dict):
+            _dirty[node_id] = e
+            _flush = getattr(cg, "flush", None)
+            if callable(_flush):
+                try:
+                    _flush()
+                except Exception:         # noqa: BLE001 —— 落账失败不阻断打标
+                    pass
     return {"node_id": node_id, "protected": True, "reason": reason}
 
 
@@ -257,7 +404,7 @@ def stats(cg):
     """保护面盘点：不可遗忘数 / 不可覆盖数 / 分层分布 / 自动保护命中数。"""
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
     by_layer, ids, auto, immutable = {}, [], 0, []
-    for nid in nodes:
+    for nid in list(nodes):
         prot, why = is_protected(cg, nid)
         if prot:
             ids.append(nid)

package/md_cg/protocol.py

@@ -11,6 +11,13 @@
 
 范围（先行收窄）：route / read / write / supersede / forget 五动词。
 
+**扩展能力面的契约登记**（不并入五动词形状表，但同为本文件真源，2026-09-30）：
+① `ACTION_SOURCE_KEY / ACTION_SOURCE_VALUES`——wrapper 级恒定键 `action_source`
+（M4，四态 explicit/sig/default/none，任何 op 的 dict 返回恒在场）；
+② `PROTECT_MARK_NEG_ROUTE`——`protect.mark` 的负路由 error 形态（H9）。
+两者由 `audit()` 的 `action_source` / `protect_neg_route` 段透出，并由 `test_protocol`
+的**同源源码守卫**钉住 mcp_server / protect 的实现（防「声明了没做」）。
+
 **协议面 ≠ MCP 面全量**（2026-09-19 实测）：`_cg_dispatch` 现有 35 个 op 分支，
 其中 30 个（ccg / review / protect / verify / whitebox …）属**扩展能力面**——它们是能力，
 不是协议违例。把「协议覆盖范围」当成「MCP 面全量」会让协议每加一个 op 就永久红灯，
@@ -70,6 +77,31 @@ DERIVE_EXTRA_KEYS = ("op", "op_derived", "hint")
 #: state 取值 = ACCEPT / REJECT / DEFER / BLINDSPOT（四态资格裁决）。
 VERDICT_FIELDS = ("state", "kind", "basis", "evidence", "detail")
 
+#: M4（2026-09-30）· **wrapper 级恒定键**：**任何 op** 的 dict 返回都带此键
+#: （`_cg_call` 追加，实测 mcp_server.py:1849-1857 的 act_source 三元表达式 +
+#: 其后 `out.setdefault("action_source", act_source)`）。
+#: 取值四态（顺序即优先级）：explicit（调用方显式传了 action）> sig（漏传 action
+#: 但按参数签名推导出）> default（该 op 在默认动作表里有条目，走了默认）>
+#: none（该 op 无默认动作，不编造）。协议语义：客户端据此可判断本次 action 是
+#: **自己传的**还是**系统挑的**——旧行为只在「推导过」时透出 action_derived，
+#: 显式传 action 时返回里没有任何痕迹。
+#: 与 DERIVE_EXTRA_KEYS 的边界：那是「推导发生过才追加」（显式态下不出现），
+#: 本键**恒在场**；两套标记并存互补，见 test_read_face_input_gates 的 M4-C 组。
+ACTION_SOURCE_KEY = "action_source"
+ACTION_SOURCE_VALUES = ("explicit", "sig", "default", "none")
+
+#: H9（2026-09-30）· protect.mark 的**负路由形态**（实测 protect.py:374）。
+#: 目标不存在时该分支返回此 dict——不是裸 None：旧行为裸返 None 被
+#: `_protect_call` 序列化成 `null` 回客户端，「id 不存在」被读成「打标成功」，
+#: 而 `_write_node` 从未发生。与 read 的 `node_missing` 同为「缺失 ≠ 成功」，
+#: 但**形态不同、须分别处理**：read 返 `null`（returns_null=True），
+#: protect 返结构化 error（ok=False + error + node_id）。
+#: 调用方分流：失败看 `r.get("ok") is False` 或 `"error" in r`；成功路径的返回键
+#: **不变**（node_id / protected / reason，**无 ok 键**——不可用 `ok` 判成功）。
+PROTECT_MARK_NEG_ROUTE = {"ok": False, "error": "node_not_found",
+                          "node_id": "<目标 id>"}
+PROTECT_MARK_NEG_ROUTE_ERROR = "node_not_found"
+
 VERB_SPECS = {
     "route": {
         "status": "live",
@@ -157,7 +189,8 @@ VERB_SPECS = {
             },
         },
         "semantics": "写动词多形态：committed=已落盘；未 committed 时 moved_to/gate 说明去向，"
-                     "hint 说明「闸门正常行为、不是工具故障、重试同样结果」",
+                     "hint 说明下一步（闸门正常行为、不是工具故障；政策违规类 REJECT「重试同样结果」，"
+                     "缺必需要素类 REJECT 给出完整缺失清单与「补齐后重写」指引）",
     },
     "supersede": {
         "status": "reserved",
@@ -318,7 +351,13 @@ def audit(module: str = None, func: str = None) -> dict:
             "reserved": reserved, "actual": actual, "has_impl": has_impl,
             "missing_impl": missing_impl, "extension_ops": extension_ops,
             "reserved_leaked": reserved_leaked, "shape_errors": shape_errors,
-            "derive": list(OP_DERIVE), "errors": errors, "ok": not errors}
+            "derive": list(OP_DERIVE), "errors": errors, "ok": not errors,
+            # 扩展能力面的两条契约登记（2026-09-30）：wrapper 级恒定键 +
+            # protect.mark 负路由形态——都不属五动词形状表，故不并入 VERB_SPECS。
+            "action_source": {"key": ACTION_SOURCE_KEY,
+                              "values": list(ACTION_SOURCE_VALUES)},
+            "protect_neg_route": {"error": PROTECT_MARK_NEG_ROUTE_ERROR,
+                                  "shape": dict(PROTECT_MARK_NEG_ROUTE)}}
 
 
 # 生效条件：verb 为 VERBS 成员时返回其 VERB_SPECS 规格 dict，非成员（含 None/空串）抛 KeyError；

package/md_cg/provenance.py

@@ -28,6 +28,7 @@ import os
 import time
 
 from . import trust as _trust
+from . import security as _security
 from .fsutil import FileLock, append_jsonl, atomic_write, read_jsonl
 
 LEDGER_NAME = "_link.jsonl"
@@ -242,7 +243,7 @@ def index_edges(cg, *, prefix: str = None) -> list:
     """从**索引快照**恢复派生边（零读文件）——台账丢失/未重建时的只读兜底。"""
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
     out = []
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         if prefix and not str(nid).startswith(prefix):
             continue
         rel = coerce_relation((e or {}).get(FM_REL_FIELD))
@@ -423,12 +424,19 @@ def _mode_of(start_operator, end_operator) -> str:
         else "overlap"
 
 
-# 生效条件：nid 不在 (cg.index or {}).get("nodes") or {} 的 dict 条目中（含 cg.index 缺失、条目非 dict）时返回 {'id': nid, 'present': False}；否则返回 {'id','present':True} 并附 EXPAND_FIELDS 中值非 None 的字段。
+# 生效条件：nid 不在 (cg.index or {}).get("nodes") or {} 的 dict 条目中（含 cg.index 缺失、条目非 dict）时返回 {'id': nid, 'present': False}；条目在但对本身份不可见（security.node_visible 为假）时同样返回 {'id': nid, 'present': False}（不附任何字段）；否则返回 {'id','present':True} 并附 EXPAND_FIELDS 中值非 None 的字段。
 def _node_digest(cg, nid) -> dict:
-    """端点摘要（只读索引快照，**零读节点文件**）；端点缺失 → `present=False`。"""
+    """端点摘要（只读索引快照，**零读节点文件**）；端点缺失/不可见 → `present=False`。
+
+    N226（2026-09-28）：此前直读 `cg.index` 无可见性判定 ⇒ 端点摘要（layer/
+    tags/importance/writer/session/temporal）把读闸拒绝节点的元数据照返回
+    （实测 guest 经 `cg(op="edges", expand_nodes=true)` 拿到私密节点摘要）。
+    同库同身份的 `stg.timeline`（stg.py:133/172）早已接线 `_readable`——本处
+    是漏网的旁路出口，改为同一个跨层单点（`security.node_visible`）。
+    """
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
     e = nodes.get(nid)
-    if not isinstance(e, dict):
+    if not isinstance(e, dict) or not _security.node_visible(cg, nid):
         return {"id": nid, "present": False}
     d = {"id": nid, "present": True}
     for k in EXPAND_FIELDS:
@@ -494,6 +502,16 @@ def find_edges(cg, *, child=None, parent=None, relation=None, batch=None,
     q_e = _trust.parse_time(end_time) if enabled else None
 
     rows = all_edges(cg, path=path)
+    # N226（2026-09-28）：可见性前置过滤（在谓词过滤**之前**，故 `total` 与
+    # 审计不变式 `dropped + len(kept) == total` 的口径随之收敛为「本身份可见
+    # 候选数」，仍可复算）。判定用**两端都可见**才保留：边拓扑（child->parent
+    # + relation + t）本身就会泄露隐藏端点的 id 与关系（实测
+    # `aggregates.sample=['child_mark->priv_mark(derived_from)']` 即此形态），
+    # 「至少一端可见」不足以闭口；口径与 `linkref` 的目标白名单、
+    # `stg._scan` 同策略——可见集之外一律当不存在（不含半条边）。
+    rows = [e for e in rows
+            if _security.node_visible(cg, e.get("child"))
+            and _security.node_visible(cg, e.get("parent"))]
     cand = []
     for e in rows:
         if c_f and e.get("child") != c_f:

package/md_cg/reach.py

@@ -207,7 +207,7 @@ class ReachIndex:
 # 生效条件：当 cg 的 index 提供 nodes 时，对每个 path 非空、cg._read 返回内容非 None 且 cg._open_content 亦返回非 None 的节点写入 hashes/post（fm.semantic 为真时并入 sem），并只把两端均已入 hashes 的 edges 建成 adj，随后按原始 content_hash 是否齐全设置 hash_complete 并返回 self。
     def build(self, cg):
         nodes = cg.index.get("nodes") or {}
-        id2path = {k: (v.get("path") or "") for k, v in nodes.items()}
+        id2path = {k: (v.get("path") or "") for k, v in list(nodes.items())}
         hashes, post, adj, sem = {}, {}, {}, []
         for k in sorted(nodes):
             e = nodes[k]
@@ -229,7 +229,7 @@ class ReachIndex:
                 sem.append(p)                 # MDCG_SEMANTIC=1 时该节点无条件入池 → 必须进收敛集
             for b in _doc_tokens(c, (fm or {}).get("tags")):
                 post.setdefault(b, []).append(p)
-        for k, e in nodes.items():
+        for k, e in list(nodes.items()):
             p = e.get("path")
             if not p or p not in hashes:
                 continue
@@ -247,7 +247,7 @@ class ReachIndex:
         # 覆盖完整性必须看**原始 content_hash**（hashes 里存的是 _node_key，
         # 含分隔符恒为真 → 曾使 hash_complete 恒判 True，r10 复核取证）
         self.hash_complete = all(bool(v.get("content_hash"))
-                                 for v in nodes.values() if v.get("path"))
+                                 for v in list(nodes.values()) if v.get("path"))
         self.built_at = time.time()
         return self
 
@@ -357,7 +357,7 @@ def _hash_complete(cg) -> bool:
     # 口径与 build() 的覆盖集合一致：只按有 path 的条目判定（无 path 的条目 build 不收录，
     # 不应因此禁用缓存复用——r12 复核指出旧写法会让稳态每次全库重建）
     nodes = cg.index.get("nodes") or {}
-    return all(bool(v.get("content_hash")) for v in nodes.values() if v.get("path"))
+    return all(bool(v.get("content_hash")) for v in list(nodes.values()) if v.get("path"))
 
 
 # 生效条件：磁盘缓存 hashes 与库内节点 path/content_hash 一一对应（数量相同且逐条相等）时返回 True，否则返回 False（触发重建）。

package/md_cg/readcache.py

@@ -28,6 +28,15 @@
      Rust `load_docs` 预计算 stripped/db_len 同款理论）；
   3. 进程内一致性边界（与 MdStore 相同的诚实边界）：跨进程/外部直接改写
      md 文件不保证可见——认知图的多进程形态（每智能体一进程）各持快照。
+  4. **读失败不固化（C-3 / FI-M02 / N134，2026-09-29）**：只接纳「成功」与
+     「终态真缺（FileNotFoundError）」两种读结果，**瞬时读失败（独占句柄/
+     资源剥夺…）一律不入缓存**——修前任何返回值含 `(None, None)` 都被当正常
+     值固化且 `_fresh` 恒真，一次瞬态失败即「节点从检索面永久消失」（cache
+     条目字面 `(gen,(None,None))`），而 `cg.get` 直读照常可读 ⇒「get 能读、
+     search 搜不到」撕裂。判别是读路径的**单点**（`MdCG._read_status` 第三
+     元素，判据函数 `fsutil.classify_read_failure`），本层不看异常类型、不猜
+     一遍；失败侧另有模块级计数+有界样本记账（`fsutil.transient_read_stats`），
+     不再静默。**为什么不是「带失败标记 + TTL 入缓存」见 `install` 文档串。**
 
 开关：默认**开**（issue #31 后续——生产检索入口 MdCGOS.search 默认态每查询
 全池 open+realpath+parse，3300 池实测中位 ~602ms/查询、O(n) 线性；读缓存
@@ -58,7 +67,7 @@ def direct_read(cg, entry):
     return fn(entry)
 
 
-# 生效条件：cg._read 可调用时以 (path → (缓存时 write_gen, 解析产物)) 常驻字典包装之——_dirty 带 path_gen 簿记（_DirtyDict 形态）时命中条件为「该 path 最近标脏代际(path_gen)与 broad_gen 均 ≤ 缓存时 write_gen」（脏集精确失效：单节点写只失效该节点），否则回落整代际相等校验（旧口径，非 _DirtyDict 防御）；cg._doc_norm_bigrams 亦存在时同款包装其派生物（_score 热点：文档侧归一化 bigram 只依赖 content，随读缓存一并常驻）；包装后 cg._read/_doc_norm_bigrams 为包装函数、cg._read_cache/_norm_bigrams_cache 为缓存字典、cg._read_uncached 为未被包装的原始 _read（direct_read 的真源）；返回缓存字典。
+# 生效条件：cg 提供 _read_status（MdCG/MdCGSecure 恒有）时按其**三态标签**包装：第三元素为 None（成功 / 终态真缺）者照脏集精确失效口径入缓存，第三元素非 None（瞬时读失败，fsutil.READ_FAIL_TRANSIENT）者**一律不入缓存**（C-3：不得把可重试的读失败以「新鲜」身份固化）；cg 无 _read_status（非 MdCG 载体）时回落包装 cg._read，且空结果一律不接纳（无判别面时的保守侧：宁可重读，不可固化可能是瞬时的缺失）；cg._doc_norm_bigrams 存在时同款包装其派生物（_score 热点：文档侧归一化 bigram 只依赖 content，随读缓存一并常驻）；包装后 cg._read 与 cg._doc_norm_bigrams 走缓存、cg._read_cache/_norm_bigrams_cache 为缓存字典、cg._read_uncached 为**穿透缓存的原始二态 _read**（direct_read 的真源，返回形状与 install 前逐位一致）；返回缓存字典。
 def install(cg):
     """把 `cg._read`（与派生物钩子）包成**脏集精确失效**的常驻缓存。
 
@@ -71,11 +80,28 @@ def install(cg):
     据此按 path 判新鲜：**写谁失效谁**，其余条目原对象复用。写路径不必
     再改一处（标脏即 `_dirty[nid]=entry` 带 path，簿记在 _DirtyDict 钩子
     内自动完成）。
+
+    接纳口径（C-3 / FI-M02 / N134，2026-09-29）：缓存只接纳**成功**与
+    **终态真缺**两种读结果；**瞬时读失败不入缓存**。修前任何返回值（含
+    `(None, None)`）一律入缓存，且该 path 无写事件时 `_fresh` 判定恒真 ⇒
+    一次独占句柄/资源剥夺就被固化成「节点从检索面永久消失直到重启或再写盘」
+    （cache 条目字面 `(gen, (None, None))`），而 `cg.get` 直读照常可读 ⇒
+    「get 能读、search 搜不到」撕裂。判据是读路径给的**标签**（`_read_status`
+    第三元素），本层**不重新判别异常类型**（单点，见 fsutil.classify_read_failure）。
+
+    为什么是「不入缓存」而不是「带失败标记入缓存 + 失效条件」：失败标记要
+    生效必须引入时间窗（TTL / 单调钟代际），而本层的失效判据只有 `_fresh`
+    一维（write_gen 脏集）；给失败另开一维就是**第二份失效判据**，且 TTL 窗内
+    该节点仍处「get 能读、search 搜不到」的撕裂态（只是有界）——与本缺陷要
+    消灭的现象同型，仅缩窗。不入缓存则窗口为零：**释放即命中**（FI-M02 实测）。
+    代价侧不存在「每次查询都重试」的性能悬崖：
+      · 只有**失败的那几个 path** 每查询多一次 `open`（O(1)/path），成功节点
+        仍在缓存里（O(1)），不是整池重读——量级退化的最坏情形是「全池都读
+        不出来」，那正是修前（缓存恒关面）的既有开销，也不比它更差；
+      · 真缺（FileNotFoundError）仍照旧入缓存 ⇒ 缺文件的节点**不会**每查询重试；
+      · 失败可观测（fsutil.transient_read_stats 计数+样本），不再静默。
     """
     cache = {}
-    # 重复 install（如显式再调）不叠加包装层，_read_uncached 恒指真原始。
-    orig = getattr(cg, "_read_uncached", None) or cg._read
-    cg._read_uncached = orig
 
     def _fresh(p, hit):
         """hit=(缓存时 write_gen, val) 对 path p 是否仍新鲜（不陈旧）。"""
@@ -99,17 +125,52 @@ def install(cg):
         return (pg.get(p, 0) <= hit[0]
                 and dirty.broad_gen <= hit[0])
 
-    def _cached(entry):
-        p = entry["path"]
-        gen = getattr(cg._dirty, "write_gen", len(cg._dirty))
-        hit = cache.get(p)
-        if hit is not None and _fresh(p, hit):
-            return hit[1]
-        val = orig(entry)
-        cache[p] = (gen, val)
-        return val
-
-    cg._read = _cached
+    status_fn = getattr(cg, "_read_status", None)
+    if status_fn is not None:
+        # 三态面（C-3）：_read_status 是唯一判别点，本层只按标签决定接纳与否。
+        # 重复 install（如显式再调）不叠加：_read_status_uncached 恒指真原始。
+        orig_status = (getattr(cg, "_read_status_uncached", None)
+                       or status_fn)
+        cg._read_status_uncached = orig_status
+        if getattr(cg, "_read_uncached", None) is None:
+            # 穿透缓存的原始二态读（direct_read 真源）：形状同 install 前。
+            cg._read_uncached = (lambda entry: orig_status(entry)[:2])
+
+        def _cached_status(entry):
+            p = entry["path"]
+            gen = getattr(cg._dirty, "write_gen", len(cg._dirty))
+            hit = cache.get(p)
+            if hit is not None and _fresh(p, hit):
+                # 存储面恒为二态（成功/终态）；命中时补回「非失败」标签。
+                return hit[1] + (None,)
+            val = orig_status(entry)
+            if val[2] is not None:
+                # C-3：瞬时读失败**不入缓存**（本次即返回，下次查询重试该 path）。
+                return val
+            cache[p] = (gen, (val[0], val[1]))
+            return val
+
+        cg._read_status = _cached_status
+    else:
+        # 无判别面的载体（非 MdCG）：保守侧——空结果一律不接纳。
+        orig_read = getattr(cg, "_read_uncached", None) or cg._read
+        cg._read_uncached = orig_read
+
+        def _cached(entry):
+            p = entry["path"]
+            gen = getattr(cg._dirty, "write_gen", len(cg._dirty))
+            hit = cache.get(p)
+            if hit is not None and _fresh(p, hit):
+                return hit[1]
+            val = orig_read(entry)
+            if not val or val[0] is None or val[1] is None:
+                # 无三态面可判时不得固化空结果（可能是瞬时的缺失）。
+                return val
+            cache[p] = (gen, val)
+            return val
+
+        cg._read = _cached
+
     cg._read_cache = cache
 
     nb_cache = {}

package/md_cg/reconcile.py

@@ -156,7 +156,7 @@ def reconcile_state(cg, apply: bool = True) -> dict:
     kept_unreadable = []                    # 条目在、真源暂不可读——保留只告警
 
     # ①③ 以索引为基准走一遍：多索引条目 + 内容漂移
-    for nid, entry in index_nodes.items():
+    for nid, entry in list(index_nodes.items()):
         if nid not in by_nid:
             ep = entry.get("path") or ""
             if ep in problem_paths: