@furongjun1999/dsh-memory 0.5.0 → 0.6.0

package/md_cg/mreview/govern.py

@@ -51,6 +51,7 @@ from ..backfill import _as_cg, _entry_id, _readable_guard, _sha
 from ..fsutil import append_jsonl, read_jsonl
 from ..mdcos import ALL_ROLES, WORK_ROLES
 from .ruleset import _as_rules, _blank
+from ..readcache import direct_read
 
 #: 留痕文件名（与 `backfill._backfill.jsonl` 分立：治理动作须能独立审计）
 GOVERN_LOG = "_govern.jsonl"
@@ -198,12 +199,12 @@ def _candidate_role(e, fm, *, sources, role_map) -> tuple:
                               else REASON_NO_SOURCE)
 
 
-# 生效条件：按序判定——_readable_guard(cg, e) 为假返回 ("denied", None)；cg._read(e) 的 fm 为 None 返回 ("unreadable", None)；crypto.is_encrypted(content) 为真返回 ("locked", None)；fm.get("role") 非空白返回 ("present", None)；否则 _candidate_role(e, fm, sources=sources, role_map=role_map) 的 role 为假返回 ("unfillable", {id,layer,reason,writer})，role 为真返回 ("", {id,layer,role,source,basis,before,had_key,writer})。
+# 生效条件：按序判定——_readable_guard(cg, e) 为假返回 ("denied", None)；direct_read(cg, e) 的 fm 为 None 返回 ("unreadable", None)；crypto.is_encrypted(content) 为真返回 ("locked", None)；fm.get("role") 非空白返回 ("present", None)；否则 _candidate_role(e, fm, sources=sources, role_map=role_map) 的 role 为假返回 ("unfillable", {id,layer,reason,writer})，role 为真返回 ("", {id,layer,role,source,basis,before,had_key,writer})。
 def _classify(cg, e, nid, *, sources, role_map) -> tuple:
     """单条裁决 → `(skip_reason, item|gap)`；skip_reason 为空串表示可回填。"""
     if not _readable_guard(cg, e):
         return "denied", None
-    fm, content = cg._read(e)
+    fm, content = direct_read(cg, e)
     if fm is None:
         return "unreadable", None
     if crypto.is_encrypted(content):
@@ -344,7 +345,7 @@ def role_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
         if not _readable_guard(cg, e):
             rep["skipped_denied"] += 1
             continue
-        fm, content = cg._read(e)
+        fm, content = direct_read(cg, e)
         if fm is None:
             rep["skipped_missing"] += 1
             continue
@@ -407,7 +408,7 @@ def role_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
         if e is None:
             rep["missing"] += 1
             continue
-        fm, content = cg._read(e)
+        fm, content = direct_read(cg, e)
         if fm is None or crypto.is_encrypted(content):
             rep["missing"] += 1
             continue

package/md_cg/postings.py

@@ -25,6 +25,8 @@ import json
 import os
 import time
 
+from .fsutil import publish
+
 SCHEMA = "mdcg-postings-2"
 
 
@@ -167,12 +169,12 @@ def load_meta(root: str) -> dict:
         return {}
 
 
-# 生效条件：无条件以 utf-8 原子写 path（tmp + os.replace），写入的字符串为 obj 的 JSON 序列化。
+# 生效条件：无条件以 utf-8 原子写 path（tmp + publish，即带 Windows 短重试的 os.replace），写入的字符串为 obj 的 JSON 序列化。
 def _atomic_json(path: str, obj, indent=None) -> None:
     tmp = path + ".tmp"
     with io.open(tmp, "w", encoding="utf-8", newline=chr(10)) as f:
         json.dump(obj, f, ensure_ascii=False, indent=indent, separators=None if indent else (",", ":"))
-    os.replace(tmp, path)
+    publish(tmp, path)
 
 
 # 生效条件：无条件读 root/_postings.json 并返回 dict（缺文件/解析失败返回 {}；内容非 dict 亦返回 {}）。

package/md_cg/readcache.py

@@ -10,13 +10,18 @@
 耗时，~230µs/节点线性退化）——「理论没有落地」。本模块即落地。
 
 与 `install_read_cache`（eval_common.py，benchmark 专用）的差异：
-  1. **写失效哨兵**：缓存条目携带 `len(cg._dirty)` 代际——所有写路径必然
-     标脏（flush 依赖 `_dirty`，add/_sync_edge_entry/负记忆化……无一例外），
-     dirty 代际变化即视为「有写入发生」，该 path 重读一次。对 path-only
-     无失效的朴素实现能红（外部报告实测的陈旧读场景）。
+  1. **写失效哨兵（脏集精确失效，缺陷迭代第 14 轮）**：缓存条目携带
+     缓存时的 `write_gen`，新鲜度按 `_DirtyDict.path_gen[path]`（该 path
+     最近标脏代际）与 `broad_gen`（tombstone/无 path 可辨变更的整池兜底）
+     判定——**写谁失效谁**，单节点写不再使全部条目同时 miss（此前整池
+     共用一个全局代际，10k 池写读交替 38.4× 退化、线性于 N）。所有写路径
+     必然标脏（flush 依赖 `_dirty`，add/_sync_edge_entry/负记忆化……无一
+     例外），标脏即 `_dirty[nid]=entry`（带 path）——簿记在 _DirtyDict
+     钩子内自动完成，写面零挂载点，天然覆盖未来新增写路径（不会有
+     「漏挂失效」型陈旧读）。对 path-only 无失效的朴素实现能红（外部报告
+     实测的陈旧读场景）。
      语义与 MdStore 的「写方落盘后 reload」同构，但**懒清**：检索高频写少，
-     写后首次检索全量重装一次即再稳定，不必写时同步清（写面零挂载点，
-     天然覆盖未来新增写路径——不会有「漏挂失效」型陈旧读）。
+     写后首次检索只重装被写节点，不必写时同步清。
   2. 缓存**解析产物** `(fm, content)`（benchmark 版只缓存原文，parse 仍逐次），
      **并缓存文档侧检索派生物** `_doc_norm_bigrams`（归一化 bigram——批次 21
      实测本机热点 88% 在此而非 I/O：内容不变则派生物不变，随读缓存常驻；
@@ -24,28 +29,81 @@
   3. 进程内一致性边界（与 MdStore 相同的诚实边界）：跨进程/外部直接改写
      md 文件不保证可见——认知图的多进程形态（每智能体一进程）各持快照。
 
-开关：`MDCG_READ_CACHE=1` 显式启用（默认关，零变更纪律，与 #28 hotcache
-同款装配）；不设或非 "1" 时 `install` 不被调用，行为与改动前逐位一致。
+开关：默认**开**（issue #31 后续——生产检索入口 MdCGOS.search 默认态每查询
+全池 open+realpath+parse，3300 池实测中位 ~602ms/查询、O(n) 线性；读缓存
+早已实现却默认关，生产恒不装配，故默认翻转）；`MDCG_READ_CACHE=0` 显式
+关闭（opt-out 零变更退出阀——跨进程改写 md 文件须本进程立即可见的部署，
+或内存受限场景，可一关回到逐次读盘的旧行为）。
 """
 import os
 
-# 生效条件：无 required 形参，锚定环境变量名 MDCG_READ_CACHE；当 os.environ.get("MDCG_READ_CACHE") == "1" 时返回 True，否则返回 False。
+# 生效条件：无 required 形参，锚定环境变量名 MDCG_READ_CACHE；未设或值为 "1" 时返回 True（默认开，issue #31 生产 O(n) 全池扫描修复），显式设为其它值（含 "0"）时返回 False。
 def enabled() -> bool:
-    """读缓存开关（默认关；=1 显式启用——零变更纪律）。"""
-    return os.environ.get("MDCG_READ_CACHE") == "1"
+    """读缓存开关（默认开；=0 显式关闭——opt-out 退出阀）。"""
+    return os.environ.get("MDCG_READ_CACHE", "1") == "1"
 
 
-# 生效条件：cg._read 可调用时以 (path → (dirty 代际, 解析产物)) 常驻字典包装之——命中条件为 path 存在且代际等于当前 len(cg._dirty)；cg._doc_norm_bigrams 亦存在时同款包装其派生物（_score 热点：文档侧归一化 bigram 只依赖 content，随读缓存一并常驻）；包装后 cg._read/_doc_norm_bigrams 为包装函数、cg._read_cache/_norm_bigrams_cache 为缓存字典；返回缓存字典。
+# 生效条件：cg._read_uncached 属性存在时返回其以 entry 调用的结果（穿透读缓存的盘上真值直读），否则返回 cg._read(entry)（未装缓存时两者等价，零变更）。
+def direct_read(cg, entry):
+    """治理/写前重查专用直读——穿透读缓存，读盘上当前真值。
+
+    读缓存默认开（issue #31 后续）后 `cg._read` 是进程内快照；治理面的
+    「写前重查」「回滚比对」语义上要求盘上真值——预演与执行之间节点
+    可能被他人/外部进程改写（test_mr_m4 D12「被人改动→不覆盖」形态：
+    path-only 命中会让重查读到预演时装入的旧值，漏判 drift）。
+    """
+    fn = getattr(cg, "_read_uncached", None)
+    if fn is None:
+        return cg._read(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 的真源）；返回缓存字典。
 def install(cg):
-    """把 `cg._read`（与派生物钩子）包成脏代际校验的常驻缓存。"""
+    """把 `cg._read`（与派生物钩子）包成**脏集精确失效**的常驻缓存。
+
+    失效口径（缺陷迭代第 14 轮，high）：此前哨兵取全局单调 write_gen——
+    整池共用一个代际值，任意一次单节点写使**全部**条目同时 miss，下一条
+    查询全池重装（10k 池写读交替 3rep 中位 1677.6ms vs 稳态 43.7ms，
+    38.4× 退化、线性于 N；生产暴露面：mcp_server 读 op=read 与写 op=write
+    同一常驻实例）。`_DirtyDict` 现簿记 `path_gen`（path → 最近标脏时的
+    write_gen）与 `broad_gen`（无 path 可辨变更的整池兜底代际），本包装
+    据此按 path 判新鲜：**写谁失效谁**，其余条目原对象复用。写路径不必
+    再改一处（标脏即 `_dirty[nid]=entry` 带 path，簿记在 _DirtyDict 钩子
+    内自动完成）。
+    """
     cache = {}
-    orig = cg._read
+    # 重复 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 是否仍新鲜（不陈旧）。"""
+        dirty = cg._dirty
+        pg = getattr(dirty, "path_gen", None)
+        if pg is None:
+            # D-4 修复（批次 23 / v20）：代际改读 _DirtyDict.write_gen（单调、
+            # 永不回退）——len(_dirty) 在 flush 清零后可被新写入凑回旧值，代际
+            # 巧合回退 → 陈旧读（v20_d4_repro stale=True 实测）。防御回落兼容
+            # 非 _DirtyDict 形态（整代际相等，旧口径）。
+            return hit[0] == getattr(dirty, "write_gen", len(dirty))
+        # 脏集精确失效（第 14 轮）：该 path 最近标脏代际 ≤ 缓存代际即新鲜
+        # ——单节点写只失效该节点；broad_gen（tombstone/无 path 可辨变更）
+        # 高于缓存代际时整池保守失效（与旧整代际口径等价的安全兜底）。
+        # flush 的 clear() 不推进 broad_gen：flush 只落索引派生物，节点
+        # 文件变更已在各写路径 _dirty[nid]=entry（带 path）时精确失效，
+        # 且生产写路径每次写后 flush（writepipe._commit_visibility）——
+        # 整池失效会让精确失效在生产恒不生效；rebuild_index 收尾走
+        # clear(broad=True) 推进 broad_gen（盘面重扫口径：直写文件 +
+        # rebuild 收尾的写方靠它对读缓存可见）。
+        return (pg.get(p, 0) <= hit[0]
+                and dirty.broad_gen <= hit[0])
 
     def _cached(entry):
         p = entry["path"]
-        gen = len(cg._dirty)
+        gen = getattr(cg._dirty, "write_gen", len(cg._dirty))
         hit = cache.get(p)
-        if hit is not None and hit[0] == gen:
+        if hit is not None and _fresh(p, hit):
             return hit[1]
         val = orig(entry)
         cache[p] = (gen, val)
@@ -60,9 +118,9 @@ def install(cg):
 
         def _cached_nb(entry, c):
             p = entry["path"]
-            gen = len(cg._dirty)
+            gen = getattr(cg._dirty, "write_gen", len(cg._dirty))
             hit = nb_cache.get(p)
-            if hit is not None and hit[0] == gen:
+            if hit is not None and _fresh(p, hit):
                 return hit[1]
             val = orig_nb(entry, c)
             nb_cache[p] = (gen, val)

package/md_cg/reconcile.py

@@ -0,0 +1,228 @@
+# -*- coding: utf-8 -*-
+"""启动对账 reconcile v0（v0.3 T9 自稳定定理落地，落地清单 P0-3）。
+
+**定位（与 twophase 的分工）**：`twophase.reconcile` 是**写账本清账**——只回答
+「有 intent 无 outcome 的那笔写入到底落盘没有」；本模块是它之上的**全量 diff
+对账**：索引（派生态）vs 盘面真源（节点 .md）逐条比对，把「索引与盘面背离」
+收敛回自稳定合法态（T9：任意瞬态扰动后仅凭真源与协议在有限步内回到合法态）。
+
+**三类 diff（v0 判据面）**：
+  1. **多索引条目**（幽灵）：索引有条目、盘面无其文件（或该文件已归属他 id）
+     → 摘除条目（tombstone，与 `_unstage` 同口径）；
+  2. **缺索引条目**：盘面有节点文件、索引无条目（非合作写者/日志丢失）
+     → 以 `_node_entry` 重建条目补入（与 rebuild_index 逐字段同源）；
+  3. **内容漂移**：条目 path 与盘面落点不符、或 content_hash 与盘面重算不符
+     → 以盘面为真源重建条目（**增量 upsert**，不触发全量 rebuild）。
+
+**T9 边界（结构合法 ≠ 内容正确）**：真源自身损坏——读失败（OSError，含
+Windows 上 Defender/索引器持句柄的瞬态形态）、解码失败（非 UTF-8 字节）、
+frontmatter 结构非法（`---` 无闭合）——**一律不自动改写**：既不据损坏文件
+建条目，也不因「读不出」摘除既有条目（瞬态读失败若被当「文件没了」就会把
+一次性抖动放大成索引面永久损伤，与 N134 同型——宁可漏修，不可误伤），只
+stderr 告警 + `_reconcile.jsonl` 留痕，是否处置交人工/上层裁决。
+
+**耗时可控**：清单 diff 是 O(n) 索引操作（os.walk 计数级）；哈希核验对每个
+盘面 .md 恰一次顺序读 + 轻量 frontmatter 切分（`nodefile.loads` 是纯字符串
+切分，无 YAML/全文解析、无检索打分/嵌入）——不是 `rebuild_index` 式全量重扫，
+修复只对漂移条目做定向 upsert。整体 O(n)；`MDCG_RECONCILE=0` 一键关闭
+（缺省开）。**告警口径**：diff 非空才写 stderr 与留痕，干净库零输出零写盘。
+
+**诚实边界（v0 不覆盖面）**：
+  · frontmatter **字段值**漂移（如盘上 importance 被直改、索引仍旧值）不在
+    v0 判据面——索引没有 fm 指纹可比（content_hash 刻意不含 frontmatter，见
+    nodefile.content_hash 文档串），该面仍由 rebuild_index 全量兜底（v1 候选）；
+  · 对账是**增益**不是服务前提：本模块任何异常都不得阻塞启动（调用方
+    mcp_server.main 以 try/except 包裹，与两段式对账同风格）。
+"""
+import os
+import time
+
+from . import nodefile
+from .fsutil import append_jsonl
+
+#: 关闭开关：仅当 `MDCG_RECONCILE` 的 strip 后取值**恰好为 "0"** 时关闭
+#: （缺省开；其它取值一律视为开——开关只回答「关没关」，不承担配置语义）。
+ENV_SWITCH = "MDCG_RECONCILE"
+
+#: 留痕文件（root 下，append-only，与 `_write_2pc.jsonl` / `_protected_audit.jsonl`
+#: 同一「独立审计文件」惯例；**仅在 diff 非空时写入**，干净库零写盘）。
+TRACE_FILE = "_reconcile.jsonl"
+
+#: 留痕/告警里每类异常的采样上限（防大库首轮修复把日志/告警撑成洪水）。
+SAMPLE_CAP = 20
+
+
+# 生效条件：读 MDCG_RECONCILE 环境变量（未设按空串），strip 后等于 "0" 返回 False，其余（含未设）返回 True。
+def enabled() -> bool:
+    """对账开关（缺省开；`MDCG_RECONCILE=0` 关闭）。"""
+    return os.environ.get(ENV_SWITCH, "").strip() != "0"
+
+
+# 生效条件：给定 cg 且其 root 属性可参与 os.path.join 时，恒返回 os.path.join(cg.root, TRACE_FILE)，无分支与早退。
+def trace_path(cg) -> str:
+    return os.path.join(cg.root, TRACE_FILE)
+
+
+# 生效条件：text 为假值（None/""）时按空串处理，返回去尾换行后的字符串（仅剥 "\n"）。
+def _norm(text: str) -> str:
+    return (text or "").rstrip("\n")
+
+
+# 生效条件：content（nodefile.loads 切出的盘面正文，含尾换行）非 None 时返回 (content_hash(content), content_hash(_norm(content))) 二元组——**双形态接受集**：add 写路径入索引的指纹按封存原文（mdcg.py `_stage` 面，正文不带尾换行时等于 norm 形态），rebuild 重建路径按 loads 读回原文（带尾换行）——两 producers 各自稳定，diff 两侧都认，否则无尾换行节点会在每次启动被误报漂移（假阳性洪水，twophase._norm 文档串同款教训）。
+def _disk_hashes(content: str) -> tuple:
+    raw = nodefile.content_hash(content or "")
+    return raw, nodefile.content_hash(_norm(content))
+
+
+# 生效条件：遍历 mdcg.LAYERS 各层目录树（os.walk，与 _scan_nodes 同序同口径），逐个 .md 读取并 nodefile.loads 切分；成功解析的以 nid（fm.get("id") 或文件名去 .md）登入 by_nid（同 nid 后到覆盖，与 _scan_nodes dict 覆盖语义一致）并登记 path_owner[relpath]=nid；读失败（OSError）/解码失败（UnicodeDecodeError）/frontmatter 无闭合（fm 为空且原文以 "---\n" 开头）的登入 problems（kind=read_error/decode_error/frontmatter_unterminated，附 relpath），不进 by_nid 与 path_owner；返回 (by_nid, path_owner, problems)。
+def _scan_disk(cg):
+    by_nid = {}
+    path_owner = {}
+    problems = []
+    for layer in _layers():
+        base = os.path.join(cg.root, layer)
+        for dirpath, _dirs, files in os.walk(base):
+            for fn in files:
+                if not fn.endswith(".md"):
+                    continue
+                p = os.path.join(dirpath, fn)
+                rel = os.path.relpath(p, cg.root).replace("\\", "/")
+                try:
+                    with open(p, encoding="utf-8") as f:
+                        text = f.read()
+                except OSError as exc:          # 瞬态/持久读失败：不猜测
+                    problems.append({"path": rel, "kind": "read_error",
+                                     "detail": str(exc)[:120]})
+                    continue
+                except UnicodeDecodeError as exc:   # 非 UTF-8 字节：真源损坏
+                    problems.append({"path": rel, "kind": "decode_error",
+                                     "detail": str(exc)[:120]})
+                    continue
+                fm, content = nodefile.loads(text)
+                if not fm and text.startswith("---\n"):
+                    # 结构非法：有 frontmatter 起始符但无闭合——loads 无法切出
+                    # 字段（正常节点必有 frontmatter；无 frontmatter 的裸文件
+                    # 按 _scan_nodes 旧例仍以文件名登入，不判损坏）。
+                    problems.append({"path": rel,
+                                     "kind": "frontmatter_unterminated",
+                                     "detail": "--- 无闭合"})
+                    continue
+                nid = fm.get("id") or fn[:-3]
+                by_nid[nid] = {"path": rel, "abs": p, "layer": layer,
+                               "fm": fm, "content": content}
+                path_owner[rel] = nid
+    return by_nid, path_owner, problems
+
+
+# 生效条件：延迟导入 mdcg 取模块级 LAYERS 并返回（与 _scan_nodes 的遍历集合同一真源；函数内导入避免 mdcg ↔ reconcile 模块环）。
+def _layers():
+    from .mdcg import LAYERS
+    return LAYERS
+
+
+# 生效条件：把单条异常以 JSONL 追加进 trace_path(cg)（best-effort：OSError 吞掉不抛——留痕是增益，不得反过来炸启动序列），无返回值。
+def _trace(cg, record: dict) -> None:
+    try:
+        append_jsonl(trace_path(cg), record)
+    except OSError:
+        pass
+
+
+# 生效条件：向 stderr 写一行告警（try/except 全包——stderr 为 None/closed/断管时静默放弃，N136 教训：告警通道失效不得伪装成新异常炸穿调用方），无返回值。
+def _warn(msg: str) -> None:
+    try:
+        import sys
+        sys.stderr.write("[mdcg-reconcile] %s\n" % msg)
+    except Exception:                       # noqa: BLE001 —— 告警失效不追责
+        pass
+
+
+# 生效条件：cg.index 须含 "nodes" 映射；enabled() 为 False 时直接返回 {"skipped": True, "applied": False} 不触盘；否则 _scan_disk 后做三类 diff：①nid 不在盘面且其 entry.path 既非问题文件也非无主——判幽灵（apply 时逐条 _unstage）；②盘面 nid 不在索引——判缺失（apply 时以 cg._node_entry 构条目 _stage）；③两上面向交的 nid 中 entry.path 与盘面落点不符或 content_hash 不在盘面双形态接受集——判漂移（apply 时以盘面重建条目 _stage）；apply 为真时收尾 cg.flush() 持久化；diff 非空时写 stderr 告警并 _trace 留痕（各类采样 ≤SAMPLE_CAP）；返回含 skipped/applied/scanned/entries/ghost_entries/missing_entries/hash_drift/unwritable_source/repaired 的报告 dict，applied=bool(apply)。
+def reconcile_state(cg, apply: bool = True) -> dict:
+    """索引（派生态）vs 盘面真源的三类 diff 对账（reconcile v0 主入口）。
+
+    `apply=False` 为 dry-run（只 diff 报告，不修复、不写盘）。返回报告：
+    `{"skipped","applied","scanned","entries","ghost_entries",
+      "missing_entries","hash_drift","unwritable_source","repaired"}`。
+    幂等：修复后的索引面与盘面一致，二次扫描 diff 为空、零输出零写盘。
+    """
+    if not enabled():
+        return {"skipped": True, "applied": False}
+    index_nodes = cg.index.get("nodes") or {}
+    by_nid, path_owner, problems = _scan_disk(cg)
+
+    problem_paths = {p["path"] for p in problems}
+    ghost, missing, drift = [], [], []
+    kept_unreadable = []                    # 条目在、真源暂不可读——保留只告警
+
+    # ①③ 以索引为基准走一遍：多索引条目 + 内容漂移
+    for nid, entry in index_nodes.items():
+        if nid not in by_nid:
+            ep = entry.get("path") or ""
+            if ep in problem_paths:
+                kept_unreadable.append(nid)     # 真源读不出 ≠ 文件没了：不摘条目
+            else:
+                ghost.append(nid)               # 盘面无其文件（或已归属他 id）
+            continue
+        d = by_nid[nid]
+        h_raw, h_norm = _disk_hashes(d["content"])
+        if entry.get("path") != d["path"] \
+                or entry.get("content_hash") not in (h_raw, h_norm):
+            drift.append(nid)
+
+    # ② 以盘面为基准走一遍：缺索引条目（仅成功解析的真源参与）
+    for nid in by_nid:
+        if nid not in index_nodes:
+            missing.append(nid)
+
+    repaired = {"unstaged": 0, "staged": 0}
+    if apply:
+        for nid in ghost:
+            cg._unstage(nid)                # tombstone + 立即持久化
+            repaired["unstaged"] += 1
+        for nid in missing + drift:
+            d = by_nid[nid]
+            cg._stage(nid, cg._node_entry(d["abs"], d["layer"],
+                                          d["fm"], d["content"]))
+            repaired["staged"] += 1
+        if repaired["unstaged"] or repaired["staged"]:
+            cg.flush()                      # 启动期一次收尾落账（不赖 autoflush）
+
+    rep = {
+        "skipped": False,
+        "applied": bool(apply),
+        "scanned": len(by_nid) + len(problems),
+        "entries": len(index_nodes),
+        "ghost_entries": ghost,
+        "missing_entries": missing,
+        "hash_drift": drift,
+        "unwritable_source": problems,
+        "repaired": repaired,
+    }
+    if kept_unreadable:
+        rep["kept_unreadable"] = kept_unreadable
+
+    # 告警 + 留痕（diff 非空才发声；干净库零输出零写盘）
+    if ghost or missing or drift or problems or kept_unreadable:
+        _warn("启动对账 v0: 幽灵条目=%s 缺失条目=%s 哈希漂移=%s "
+              "真源损坏/不可读=%s（%s）"
+              % (len(ghost), len(missing), len(drift), len(problems),
+                 "已按盘面增量修复索引面" if apply else "dry-run 未修复"))
+        for nid in ghost[:SAMPLE_CAP]:
+            _warn("  幽灵条目（盘面无文件→摘除）: %s" % (nid,))
+        for nid in kept_unreadable[:SAMPLE_CAP]:
+            _warn("  条目保留（真源暂不可读，不猜测不摘除）: %s" % (nid,))
+        for pr in problems[:SAMPLE_CAP]:
+            _warn("  真源损坏/不可读（只告警不改写——T9 边界）: %s [%s]"
+                  % (pr["path"], pr["kind"]))
+        _trace(cg, {
+            "t": time.time(), "op": "reconcile_v0", "apply": bool(apply),
+            "scanned": rep["scanned"], "entries": rep["entries"],
+            "ghost": ghost[:SAMPLE_CAP], "ghost_n": len(ghost),
+            "missing": missing[:SAMPLE_CAP], "missing_n": len(missing),
+            "drift": drift[:SAMPLE_CAP], "drift_n": len(drift),
+            "problems": problems[:SAMPLE_CAP], "problems_n": len(problems),
+            "kept_unreadable": kept_unreadable[:SAMPLE_CAP],
+            "repaired": repaired,
+        })
+    return rep

package/md_cg/review_cli.py

@@ -0,0 +1,215 @@
+# -*- coding: utf-8 -*-
+"""review_cli · 审核队列裁决命令行（设计者/管理权限专用）
+
+**包内入口**（2026-09-24 修复）：原实现只在 `scripts/review_cli.py`，而出货包
+`files` 不含 `scripts/` —— 于是包内所有给用户/智能体的提示（writepipe 的
+「已入审核队列 → 请裁决」）都指向一个安装态不存在的文件。本模块把同一实现
+搬进包内，统一入口 `python -m md_cg.review_cli`；`scripts/review_cli.py`
+在源码树内仍可用（同一代码路径：那里 _HERE 同为插件根）。
+
+背景：本机未配置外部验证器（MDCG_VERIFIER_MODULES）时，写入恒判 DEFER
+入审核队列——这是诚实行为（不假装通过）。裁决权专属 can_admin 角色
+（写入者不得自裁自决），agent 端被 AccessDenied 拒绝是设计行为；
+由设计者在本机直接运行本命令完成裁决。
+
+用法（root 须与待裁决部署一致：--root 或环境变量 MDCG_ROOT）：
+  python -m md_cg.review_cli list
+  python -m md_cg.review_cli accept  <pid> --session <会话id> --reason "实跑测试证据"
+  python -m md_cg.review_cli reject  <pid> --reason "内容有误"
+  python -m md_cg.review_cli edit    <pid> --content "修正后内容" --reason "..."
+  python -m md_cg.review_cli merge   <pid> --into <已有节点id> --reason "..."
+  python -m md_cg.review_cli noop    <pid> --reason "已评估，判定无需改动"
+  python -m md_cg.review_cli rounds  <pid>        # 某提案裁决轮次历史
+  python -m md_cg.review_cli stats                # 裁决动作统计（含 noop）
+
+noop 语义：**已评估、判定不改变任何现有记忆**——只留痕（decisions.jsonl +
+审计 md 节点）并关闭提案，不落业务节点、不进负记忆。它与 reject 的区别是
+「评估过了、无需改动」而非「否掉这条候选」，故不可借 noop 绕过 accept 门控。
+
+裁决留痕：decisions.jsonl + 审计 md 节点（由 review_decide 内部完成）。
+
+落盘归因（P1 修复，2026-09-26，DSH 端在役实测回告）：
+  · 会话：--session（各子命令通用）缺省取环境变量 MDCG_SESSION，仍无则维持
+    现状随机会话并 stderr 告警一行。同一批裁决传同一 session，落盘节点的
+    frontmatter.session 才稳定一致（此前每次随机 sess_<uuid12>，同批 5 节点
+    5 个会话 id）。
+  · 写入者：accept/edit 落盘节点的 frontmatter.writer 保留**提案原始写入者**
+    （propose 时库端快照的 actor，如 dsh-memory）；裁决者身份不丢失，记入
+    frontmatter.reviewer（designer-cli）。
+  · DSH 前置条件（环境侧自行核对，本 CLI 不校验）：MCP 写入面对 DSH 形态会话
+    id（session-<8>-<4>-<4>-<4>-<12>）有 `_normalize_session` 防编造校验
+    （md_cg/mcp_server.py）——会话目录须真存在于 MDCG_DSH_SESSIONS_ROOT 或
+    ~/.dsh/sessions 之下，否则该会话在 MCP 面降级为 anonymous。本 CLI 直构
+    Principal 不经该校验，但若裁决的会话 id 与 MCP 面共用，请先确认目录在位，
+    否则两侧归因对不上。
+"""
+import argparse
+import json
+import os
+import sys
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except AttributeError:
+    pass
+
+_HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+from md_cg.mdcos import MdCGSecure        # noqa: E402
+from md_cg.security import Principal      # noqa: E402
+
+
+# 生效条件：args 的 root 属性为真值（含 getattr 缺省 None 时回落）否则回落 os.environ.get("MDCG_ROOT", "")，两者皆空串或该值经 os.path.isdir 判定不是目录时 sys.exit 退出，否则返回该 root。
+def _root(args):
+    root = getattr(args, "root", None) or os.environ.get("MDCG_ROOT", "")
+    if not root:
+        sys.exit("错误：未指定存储根（--root 或环境变量 MDCG_ROOT）。\n"
+                 "root 必须与待裁决的部署一致——猜错会裁决到另一个空库。")
+    if not os.path.isdir(root):
+        sys.exit("错误：root 不存在：%s" % root)
+    return root
+
+
+# 生效条件：args 的 session 属性为真值（含 getattr 缺省 None 回落）或环境变量 MDCG_SESSION 去空白后非空时返回该值（前者优先），两者皆无返回 None。
+def _session_of(args):
+    """裁决会话归属：--session > 环境变量 MDCG_SESSION > None（随机 + 告警）。"""
+    s = str(getattr(args, "session", None)
+            or os.environ.get("MDCG_SESSION", "") or "").strip()
+    return s or None
+
+
+# 生效条件：args 就绪时先经 _session_of 取裁决会话归属，取到 None 时向 stderr 告警一行（缺省随机会话、同批裁决请传同一 --session）后维持现状；随后构造写死权限的 Principal(actor="designer-cli", clearance="secret", can_write=True, can_admin=True, role="designer", auth_mode="local-cli", session=<上述归属>)，再以 _root(args) 取到的存储根返回 MdCGSecure(root, principal=p, autoflush=1)。
+def _cg(args):
+    session = _session_of(args)
+    if session is None:
+        # P1 归因（2026-09-26，DSH 端在役实测）：缺省随机会话会让同一批裁决
+        # 得到互不相同的落盘归属（5 节点 5 个 sess_* 实录）。不拒绝、告警一行
+        # 后维持现状（向后兼容）；要稳定归属请显式传同一 --session。
+        sys.stderr.write("警告：未指定 --session / 环境变量 MDCG_SESSION，"
+                         "本次裁决落盘使用随机会话 id——同一批裁决请传同一 "
+                         "--session 以稳定归属。\n")
+    p = Principal(actor="designer-cli", clearance="secret",
+                  can_write=True, can_admin=True, role="designer",
+                  auth_mode="local-cli", session=session)
+    # 索引可见性（P1b，2026-09-26）：autoflush=1 —— 与 mcp_server.py:3695-3702
+    # 同款（server 级兜底 2026-09-16 已修），本处是同一兜底的**第二落点**，
+    # DSH 端在役实测 read null 后补齐。根因：缺省 autoflush=64 时写入先经
+    # _stage 入内存 _dirty，攒够阈值才 flush() 落分片日志 `_index_log/`；
+    # 本 CLI 正常退出有 main 的 finally cg.close() 与库层 atexit 双兜底
+    # （mdcg.py _LIVE_CGS），但兜底刻意只覆盖正常退出——被 kill / 崩溃时
+    # 两者都不执行，裁决节点停在内存索引、日志从未落，盘面文件在而索引
+    # 链路断，在役旧读面 `_load_index` 盲信既有快照即 read null。逐条落
+    # 日志后任意退出形态下写入对其它进程立即可见（review_decide 自身的
+    # 显式 flush 只覆盖其目标/审计节点，且与节点文件落盘之间仍有窗口）。
+    return MdCGSecure(_root(args), principal=p, autoflush=1)
+
+
+# 生效条件：rec 支持 .get 时，取 rec.get("content") 为假值则取 rec.get("statement")、再为假值则取空串，把其中的换行替换为空格，并按 width（缺省 66）切片后仅当 len(text) > width 才追加 "…"，返回该字符串。
+def _brief(rec, width=66):
+    text = (rec.get("content") or rec.get("statement") or "").replace("\n", " ")
+    return text[:width] + ("…" if len(text) > width else "")
+
+
+# 生效条件：cg 与 args 就绪时按 args.cmd 分派——"list" 时 cg.review_list() 为空则打印空队列并返回 0、非空则逐条打印（tags 取真值拼接、layer/round 为假值显示 "?"/0）后返回 0；"rounds" 时打印 cg.review_rounds(args.pid) 并返回 0；"stats" 时打印 cg.review_stats() 的记录数/提案数/待审数/已关闭数与动作分布（含 noop 计数）并返回 0；"edit" 时以 args.content 加真值 args.tags（按逗号分割并剔除空项）/args.layer 组成 edits 调 cg.review_decide；其余 cmd（含 noop）以 getattr(args, "into", None) 与 args.reason 调 cg.review_decide；后两类再按 out.get("ok") 为真返回 0，否则打印 out 并返回 1。
+def _execute(cg, args):
+    """按子命令执行裁决（cg 的生命周期由 main 统一收尾）。"""
+    if args.cmd == "list":
+        pend = cg.review_list()
+        if not pend:
+            print("审核队列为空（0 条待审）。")
+            return 0
+        print("待审 %d 条：" % len(pend))
+        for r in pend:
+            tags = (", tags=" + ",".join(r.get("tags") or [])) if r.get("tags") else ""
+            print("  [%s] %s · %s 层%s · round=%s\n      %s" % (
+                r.get("pid"), r.get("status"), r.get("layer") or "?",
+                tags, r.get("round") or 0, _brief(r)))
+        print('\n裁决示例：python -m md_cg.review_cli accept <pid> --reason "实跑测试证据"')
+        return 0
+
+    if args.cmd == "rounds":
+        print(json.dumps(cg.review_rounds(args.pid), ensure_ascii=False, indent=1))
+        return 0
+
+    if args.cmd == "stats":
+        st = cg.review_stats()
+        by = st.get("by_decision") or {}
+        print("裁决记录 %d 条 · 提案 %d 个 · 待审 %d 条 · 已关闭 %d 个" % (
+            st.get("records", 0), st.get("proposals", 0),
+            st.get("pending", 0), st.get("closed", 0)))
+        print("  动作分布：%s" % ("、".join(
+            "%s=%d" % (k, by[k]) for k in sorted(by)) or "（无记录）"))
+        print("  其中 noop（已评估、判定无需改动）= %d 条" % st.get("noop", 0))
+        return 0
+
+    if args.cmd == "edit":
+        edits = {"content": args.content}
+        if args.tags:
+            edits["tags"] = [t.strip() for t in args.tags.split(",") if t.strip()]
+        if args.layer:
+            edits["layer"] = args.layer
+        out = cg.review_decide(args.pid, "edit", edits=edits, reason=args.reason)
+    else:
+        out = cg.review_decide(args.pid, args.cmd,
+                               merge_into=getattr(args, "into", None),
+                               reason=args.reason)
+
+    if out.get("ok"):
+        print("已裁决：%s → %s%s" % (
+            args.pid, args.cmd,
+            ("，落盘节点 " + out["node_id"]) if out.get("node_id") else ""))
+        return 0
+    print("裁决未生效：%s" % json.dumps(out, ensure_ascii=False))
+    return 1
+
+
+# 生效条件：argv 为 None（默认）时由 argparse 解析 sys.argv、否则解析传入的 argv（子命令 dest="cmd" 为 required，已注册 list/accept/reject/edit/merge/rounds 并带 --root 等参数），解析成功后构造 cg=_cg(args) 并返回 _execute(cg, args)，finally 中执行 cg.close()。
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="python -m md_cg.review_cli",
+        description="灵枢审核队列裁决（designer 权限）")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--root", help="存储根目录（默认环境变量 MDCG_ROOT）")
+    common.add_argument("--session", default=None,
+                        help="裁决会话 id（落盘归属 frontmatter.session；缺省取"
+                             "环境变量 MDCG_SESSION，仍无则随机会话并 stderr 告警。"
+                             "同一批裁决传同一值即得同一归属）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("list", help="列出待审条目", parents=[common])
+    sub.add_parser("stats", help="裁决动作统计（含 noop）", parents=[common])
+    for name, help_ in (("accept", "按原样写入落盘"),
+                        ("reject", "丢弃（只记裁决）"),
+                        ("noop", "已评估、判定不改变现有记忆（只留痕）")):
+        s = sub.add_parser(name, help=help_, parents=[common])
+        s.add_argument("pid")
+        s.add_argument("--reason", default="", help="裁决理由（进留痕）")
+    s = sub.add_parser("edit", help="修订后写入", parents=[common])
+    s.add_argument("pid")
+    s.add_argument("--content", required=True)
+    s.add_argument("--tags", default=None, help="逗号分隔")
+    s.add_argument("--layer", default=None)
+    s.add_argument("--reason", default="")
+    s = sub.add_parser("merge", help="合并进已有节点", parents=[common])
+    s.add_argument("pid")
+    s.add_argument("--into", required=True, help="目标节点 id")
+    s.add_argument("--reason", default="")
+    s = sub.add_parser("rounds", help="某提案的裁决轮次历史", parents=[common])
+    s.add_argument("pid")
+    args = ap.parse_args(argv)
+
+    cg = _cg(args)
+    try:
+        return _execute(cg, args)
+    finally:
+        # 收尾（2026-09-16 取证）：裁决写入先进内存 _dirty，不落盘则「节点在盘上
+        # 但索引无条目」——已有 _index.json 的根重开不重扫目录，其它进程与重载后的
+        # 长驻进程都检索不到（只能靠某次全量 rebuild 偶然救回）。库层另有 atexit
+        # 兜底，但显式收尾才是正路：兜底只覆盖「正常退出」这一条路径。
+        cg.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())