@furongjun1999/dsh-memory 0.7.2 → 0.7.3

package/md_cg/mdcos.py

@@ -977,7 +977,9 @@ class MdCGOS(MdCG):
                 # 语义资格（MDCG_SEMANTIC=1）：fm.semantic 节点无条件入池
                 hits = [d for d in docs
                         if self._like(d[2], d[1], terms,
-                                      index_key_hits(d[0], terms, q))
+                                      index_key_hits(d[0], terms, q),
+                                      entry=d[0],
+                                      positive_body=self._positive_body)
                         or (semantic_on() and d[1].get("semantic"))]
                 out = try_stage(hits, TIER_BUCKET_LIKE)
                 if out:
@@ -1004,7 +1006,9 @@ class MdCGOS(MdCG):
             _dif = set(_rstat.get("reach_diffused_paths") or ())
             hits_r = [d for d in docs_r
                       if self._like(d[2], d[1], terms,
-                                    index_key_hits(d[0], terms, q))
+                                    index_key_hits(d[0], terms, q),
+                                    entry=d[0],
+                                    positive_body=self._positive_body)
                       or (semantic_on() and d[1].get("semantic"))
                       or d[0].get("path") in _dif]     # 图扩散补召回：无词面命中也放行进打分
             stat["pre_cap"] = len(hits_r)     # 与 T2 同序：截断**前**的候选数
@@ -1038,7 +1042,9 @@ class MdCGOS(MdCG):
         # 语义资格（MDCG_SEMANTIC=1）：fm.semantic 节点无条件入池
         hits = [d for d in docs_all
                 if self._like(d[2], d[1], terms,
-                              index_key_hits(d[0], terms, q))
+                              index_key_hits(d[0], terms, q),
+                              entry=d[0],
+                              positive_body=self._positive_body)
                 or (semantic_on() and d[1].get("semantic"))]
         stat["pre_cap"] = len(hits)
         stat["cap"] = GLOBAL_CAP
@@ -1088,7 +1094,9 @@ class MdCGOS(MdCG):
         # 语义摘要=检索面（设想核心），否则摘要层只在 LIKE 全空时生效
         hits = [d for d in docs
                 if self._like(d[2], d[1], terms,
-                              index_key_hits(d[0], terms, query))
+                              index_key_hits(d[0], terms, query),
+                              entry=d[0],
+                              positive_body=self._positive_body)
                 or (semantic_on() and d[1].get("semantic"))]
         if not hits:
             # 兜底池（LIKE 全空 = 无相关度信号）：截断依据=importance/created_at
@@ -1346,8 +1354,10 @@ class MdCGOS(MdCG):
         out = []
         for e, fm, c in self._read_many(entries, stat):
             tags = " ".join(str(t) for t in (fm.get("tags") or []))
-            # 负条件行不作召回键（反例命中应由 judge 走 REJECT，不该召回节点）
-            cov = _weighted_coverage(tw, f"{nodefile.positive_body(c)} {tags}")
+            # 负条件行不作召回键（反例命中应由 judge 走 REJECT，不该召回节点）。
+            # N273：走 `_positive_body` 钩子（readcache 启用时 path 键控缓存
+            # 版）——与 `_like` 侧同一条派生物缓存口径，不再是第二处直调。
+            cov = _weighted_coverage(tw, f"{self._positive_body(e, c)} {tags}")
             if cov <= 0.0:
                 continue
             e_dom = routing.route_key(None, e.get("tags"))
@@ -4416,9 +4426,15 @@ class MdCGOS(MdCG):
     def check_consistency(self, content, layer=None, condition_space=None,
                           non_applicable_conditions=None, tags=None,
                           exclude=None, limit=consistency.MAX_SCAN,
-                          depth=consistency.MAX_DEPTH, auto_flywheel=False):
+                          depth=consistency.MAX_DEPTH, auto_flywheel=False,
+                          log_write=True):
         """不落盘地预检一条待写内容是否与既有节点/纪律冲突（三级决策）。
 
+        log_write（路线 C，2026-10-05，透传 consistency.check 同名参数）：
+        缺省 True＝原行为（落 `_consistency.jsonl` 台账）；**只读消费面**
+        （auditview 证据审计）传 False——判定照常返回、台账不写（「不落盘
+        预检」承诺的补全：既有 log 是无条件写，只读面消费会变成隐式写）。
+
         对齐《智能的公理化基石》§十一（情绪=信息差二阶变化，独立不参与信任）、
         条件论「反题」（预测与事实冲突）、:273（递归受深度/节点/循环/增益门槛约束）。
 
@@ -4436,7 +4452,7 @@ class MdCGOS(MdCG):
                                        if not _is_null_condition(x)],
             tags=tags,
             exclude=exclude, limit=limit, depth=depth,
-            auto_flywheel=auto_flywheel)
+            auto_flywheel=auto_flywheel, log_write=log_write)
 
 # 生效条件：当 limit 传入时，以 limit（默认 100）调用 consistency.history 并返回其结果；本函数不改变 limit；
     def consistency_history(self, limit=100):
@@ -5103,8 +5119,8 @@ class MdCGSecure(MdCGOS):
     def _neg_coverage(self, terms):
         return [e for e in super()._neg_coverage(terms) if self._readable(e)]
 
-# 生效条件：node_id 在 self.index["nodes"] 中存在且 self._readable(e) 为假时返回 None，否则转 super().get(node_id)；索引缺该条目时**先做代际探活重载再判可见性**（N196：索引缺条目 ≡ 本进程陈旧，不得据以跳过读隔离），重载后仍无条目才回落 super().get 的 not_found 语义；super().get 返回真值节点后用**同一次读取所得的 frontmatter**（sensitivity/session）再判一次可见性，为假即返回 None（N213：命中陈旧条目的路径不得以旧快照当判据、以新盘面当正文）；
-    def get(self, node_id: str):
+# 生效条件：probe 为真（缺省，行为与改动前逐位一致）时，索引缺该条目才做代际探活重载（N196）且 super().get 照旧探活；probe=False 时两处探活一并跳过（N276：调用方已在本批读之前探过一次，批量循环内的逐节点读不再各自重探）；其余判据与 probe 无关：node_id 在 self.index["nodes"] 中存在且 self._readable(e) 为假时返回 None，否则转 super().get(node_id, probe=probe)；索引缺该条目时**先做代际探活重载再判可见性**（N196：索引缺条目 ≡ 本进程陈旧，不得据以跳过读隔离），重载后仍无条目才回落 super().get 的 not_found 语义；super().get 返回真值节点后用**同一次读取所得的 frontmatter**（sensitivity/session）再判一次可见性，为假即返回 None（N213：命中陈旧条目的路径不得以旧快照当判据、以新盘面当正文）；
+    def get(self, node_id: str, probe: bool = True):
         e = self.index["nodes"].get(node_id)
         if e is None:
             # N196（2026-09-28）：索引缺条目**不**等于「节点不存在」——本进程
@@ -5114,11 +5130,14 @@ class MdCGSecure(MdCGOS):
             # 第二次读才归 None，因为那时条目已随重载进入索引）。先探活重载
             # 再判可见性；真不存在时 e 仍为 None，super().get 照旧返回 None。
             # 成本只在**未命中**路径（一次 stat），命中路径零变化。
-            self._maybe_reload_index()
+            # N276：probe=False（批内单探针）时本探活同跳——语义窗口见
+            # forgetting.redundancy 同注（本批读期间他进程写入不探知）。
+            if probe:
+                self._maybe_reload_index()
             e = self.index["nodes"].get(node_id)
         if e is not None and not self._readable(e):
             return None                     # 读隔离：不可见即不存在
-        node = super().get(node_id)
+        node = super().get(node_id, probe=probe)
         if node is None:
             return None
         # N213（2026-09-28）：命中陈旧条目的路径此前**零探活**——可见性判据取自

package/md_cg/nodefile.py

@@ -123,6 +123,22 @@ REPRODUCIBLE_BASIS = ("compiler", "test", "measurement", "formal_proof", "data")
 #: 来源一致性档：文科断言可用（来源表述一致即可）
 CONSISTENCY_BASIS = ("textbook", "public_kb")
 
+# ---- 多主体世界模型对齐（2026-10-05）：检验强度字段真源 ----------------------------
+# 「检验强度」分级（过程追踪过程 tracing 方法，见对齐评估 v0.1 §2 L1）：一条断言
+# 的**证据能带走多少裁决权重**——hoop（必要证据：不满足即证伪）/ smoking_gun
+# （决定性：单独即可确立）/ doubly_decisive（同时排除竞争假设）。与
+# `verification_basis`（来源**类型**）正交：一个说「凭什么类别的证据」，一个说
+# 「证据的裁决力有多强」。缺省 None＝未声明（**不落 fm 键**，存量零迁移、读取侧
+# `.get()` 回落）；显式传入时校验闭集（与 VERIFICATION_BASIS 同风格）。
+CHECK_STRENGTHS = ("hoop", "smoking_gun", "doubly_decisive")
+CHECK_STRENGTH_FIELD = "check_strength"
+
+#: 幽灵引用标记字段（A2，多主体世界模型对齐 v0.1 §2 L1「转引不得升级」）：
+#: 写入链检测到的**无可解析出处**的回指短语清单（短语层），落 fm 供后续
+#: 裁决/检索看见。**正文属性**：每次写入按当次检测重算、不继承（与
+#: check_strength 的声明继承语义相反——正文变了检测就该变）。
+UNCERTAIN_REFS_FIELD = "uncertain_refs"
+
 # ---- 裁定 D（2026-09-19）：可验证记忆单元的**字段名真源** --------------------------
 # 「子功能」的契约角色是**依赖 dependency**（见 CCG_CONTRACT_ROLES），其落字段即
 # `depends_on`——名字与角色对齐（不叫 sub_features，避免同一概念两种写法）。
@@ -386,6 +402,48 @@ def ccg_mark_present(content: str, mark: str) -> bool:
     return False
 
 
+# 生效条件：content 为真时逐行扫描——命中 marks 中任一要素的 CCG 标题行（判据单点 _ccg_heading_rest，`^#\s*<要素>` 冒号可有可无）即整段剥除：行内带值（`# 生效条件：v`／前缀式）只剥该行，裸标题连同其后首个非空、非标题行（该字段的值行，取值口径同 ccg_field_value）一并剥除；其余原行原样保留（含缩进）以 "\n" 连接返回；content 假值按空串返回。
+def _strip_ccg_segments(content, marks=CCG_MARKS):
+    """剥除 CCG 声明**整段字段**后的文本——剥除算法单点。
+
+    单点动因（N238 同族）：六要素允许无冒号形态（`# 不适用条件` + 换行 + 值行），
+    **值行才是内容本体**；只剥标题行会把该字段的正文留在正文里——同一条内容写成
+    带冒号时剥净、写成无冒号时残留，两种写法给出两种结论（该缺陷在
+    `consistency._body_text` 已按 N238 收口，本函数把**剥除算法本身**也收成一份，
+    防下游再各写一份循环而漂移）。调用方：`positive_body`（只剥不适用条件）与
+    `consistency._body_text`（剥全部六要素）。
+
+    判据一律走单点（`_ccg_heading_rest`，与写入闸门 data/policy.json 同一行语义）：
+    缩进标题与二级标题不构成「已声明」，与 `ccg_mark_present` 同边界。
+    """
+    lines = (content or "").split("\n")
+    out = []
+    i, n = 0, len(lines)
+    while i < n:
+        rest = None
+        for mark in marks:
+            rest = _ccg_heading_rest(lines[i], mark)
+            if rest is not None:
+                break
+        if rest is None:
+            out.append(lines[i])
+            i += 1
+            continue
+        i += 1
+        if rest.strip():
+            continue            # 行内已带值（冒号式 `# 字段：v` / 前缀式）→ 只剥该行
+        while i < n:            # 裸标题：其后首个非空、非标题行是值行，同剥
+            t = lines[i].strip()
+            if not t:
+                i += 1
+                continue
+            if t.startswith("#"):
+                break           # 下一个标题 ⇒ 本字段值为空，不消费
+            i += 1
+            break
+    return "\n".join(out)
+
+
 # 生效条件：content 中出现 "# {mark}：" 或 "# {mark}:"（中/英文冒号）或仅 "# {mark}" 标题行即把该 mark 计入 present 与 required_present；complete 为 required_present 覆盖全部 CCG_REQUIRED、all_present 为 present 覆盖全部 CCG_MARKS，ratio = len(required_present)/len(CCG_REQUIRED)，四键连同两个清单一起返回。
 def ccg_completeness(content: str) -> dict:
     """CCG 要素齐全度——白箱可审计性的量化指标。
@@ -441,39 +499,45 @@ def is_placeholder_text(value) -> bool:
     return any(m in s for m in PLACEHOLDER_MARKERS)
 
 
-# 生效条件：content 中含 "# 不适用条件："（全角冒号）或 "# 不适用条件:"（半角冒号）即返回 True，两者都不出现返回 False。
+# 生效条件：content 中存在 NEG_FIELD（"不适用条件"）的 CCG 标题行（判据单点 ccg_mark_present，`^#\s*不适用条件`，冒号可有可无，与写入闸门同一行语义）时返回 True，否则 False。
 def has_non_applicable(content: str) -> bool:
     """是否声明了不适用条件——REJECT 路径成立的必要条件。
 
     没有不适用条件的节点在白箱下不能 REJECT（无法证明「不适用」），
     只能 ACCEPT 或 BLINDSPOT。这是第 1 篇第 10 章从 28%→88% 的关键。
+
+    A3（N238 同族残面）：判据单点 = `ccg_mark_present`——本函数原先只认
+    「`# 不适用条件：`／`# 不适用条件:`」两种**带冒号**的字面量，无冒号形态
+    （`# 不适用条件` + 换行 + 值行）被判成「没声明」：同一条正文写不写冒号
+    给出两种结论，而「冒号可有可无」已由单点定案（test_ccg_form_parity ①-⑦）。
+    消费面：索引条目 `has_neg_conditions`（mdcg `_entry` / rebuild / `_stage`），
+    进而 `export`/`insight`/`sustain`/`predict` 的统计与边界读数。
     """
-    return "# 不适用条件：" in content or "# 不适用条件:" in content
+    return ccg_mark_present(content, NEG_FIELD)
 
 
 #: 负条件字段名——它是**反例声明**，不是召回键
 NEG_FIELD = "不适用条件"
 
 
-# 生效条件：content 为 None 时按 "" 处理；逐行 strip 后，仅当该行以 "#" 开头且 lstrip("#").strip() 又以 NEG_FIELD 开头时丢弃该行，其余行原样保留（保留原缩进），返回保留行的 "\n".join。
+# 生效条件：content 为 None 时按 "" 处理；逐行剥除 NEG_FIELD 的整段 CCG 声明（剥除算法单点 _strip_ccg_segments——行内带值只剥该行，裸标题连同其后首个非空、非标题的值行一并剥除），其余行原样保留（含原缩进），返回保留行的 "\n".join。
 def positive_body(content: str) -> str:
-    """剥离 `# 不适用条件：` 行后的正文——负条件不作召回键。
+    """剥离 `# 不适用条件` 声明段后的正文——负条件不作召回键。
 
     不适用条件声明的是「什么时候**不**适用」，其触发词是反例。一旦把它当召回
     键，查询命中反例时节点反而被召回——**恰好在它不该适用的地方被召回**，属实
     质性错误。反例的正确去向是 `judge_qualification` 的 REJECT 路径（读
     `frontmatter.non_applicable_conditions`），而不是召回。
 
-    只剥离真正的 CCG 行（以 `#` 开头且字段名匹配），避免误伤正文里恰好以
-    「不适用条件」开头的普通句子。
+    只剥离真正的 CCG 行（判据单点 `_ccg_heading_rest`：`# <字段>` 标题前缀、
+    冒号可有可无），避免误伤正文里恰好以「不适用条件」开头的普通句子。
+
+    A3（N238 同族残面）：剥的必须是**整段字段**——无冒号形态（`# 不适用条件` +
+    换行 + 值行）原先只剥标题行，值行（内容本体）残留 ⇒ 反例词面照样进召回键
+    （`MdCG._like` 实测命中），与带冒号写法的行为相反。剥除算法收在单点
+    `_strip_ccg_segments`（与 `consistency._body_text` 共用一份循环）。
     """
-    keep = []
-    for ln in (content or "").split("\n"):
-        s = ln.strip()
-        if s.startswith("#") and s.lstrip("#").strip().startswith(NEG_FIELD):
-            continue
-        keep.append(ln)
-    return "\n".join(keep)
+    return _strip_ccg_segments(content, (NEG_FIELD,))
 
 
 # ---- 条件空间 → 生效条件声明 -------------------------------------------------

package/md_cg/readcache.py

@@ -25,7 +25,9 @@
   2. 缓存**解析产物** `(fm, content)`（benchmark 版只缓存原文，parse 仍逐次），
      **并缓存文档侧检索派生物** `_doc_norm_bigrams`（归一化 bigram——批次 21
      实测本机热点 88% 在此而非 I/O：内容不变则派生物不变，随读缓存常驻；
-     Rust `load_docs` 预计算 stripped/db_len 同款理论）；
+     Rust `load_docs` 预计算 stripped/db_len 同款理论）与 `_positive_body`
+     （剥除不适用条件后的召回键正文——N273，8000 池实测 ~102ms/查询，
+     与 bigram 同一 path 键控 + 脏集失效口径，两者恒同步）；
   3. 进程内一致性边界（与 MdStore 相同的诚实边界）：跨进程/外部直接改写
      md 文件不保证可见——认知图的多进程形态（每智能体一进程）各持快照。
   4. **读失败不固化（C-3 / FI-M02 / N134，2026-09-29）**：只接纳「成功」与
@@ -67,7 +69,7 @@ def direct_read(cg, entry):
     return fn(entry)
 
 
-# 生效条件：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 前逐位一致）；返回缓存字典。
+# 生效条件：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._positive_body 存在时同款包装其派生物（_like 热点：剥除不适用条件后的正文只依赖 content，N273 与前者同一 path 键控 + 脏集失效口径）；包装后 cg._read 与 cg._doc_norm_bigrams/cg._positive_body 走缓存、cg._read_cache/_norm_bigrams_cache/_positive_body_cache 为缓存字典、cg._read_uncached 为**穿透缓存的原始二态 _read**（direct_read 的真源，返回形状与 install 前逐位一致）；返回缓存字典。
 def install(cg):
     """把 `cg._read`（与派生物钩子）包成**脏集精确失效**的常驻缓存。
 
@@ -189,14 +191,37 @@ def install(cg):
 
         cg._doc_norm_bigrams = _cached_nb
         cg._norm_bigrams_cache = nb_cache
+
+    # N273（第 32 轮性能面）：`_positive_body` 派生物同款缓存层——同 `entry`
+    # path 键、同 `_fresh` 脏集判据、同装载/失效时机（与 `_doc_norm_bigrams`
+    # 一字不差的同形结构，故两者命中率与失效行为恒同步）。修前 `_like` 每
+    # 查询对每个候选节点直调 `nodefile.positive_body`（逐行扫 CCG 声明段），
+    # 8000 池实测每次查询 ~102ms（占热态查询 ~47%）——它却是与 bigram 同
+    # 性质的纯函数（只依赖 content），缓存不对称在此收口。
+    pb_cache = {}
+    if hasattr(cg, "_positive_body"):
+        orig_pb = cg._positive_body
+
+        def _cached_pb(entry, content):
+            p = entry["path"]
+            gen = getattr(cg._dirty, "write_gen", len(cg._dirty))
+            hit = pb_cache.get(p)
+            if hit is not None and _fresh(p, hit):
+                return hit[1]
+            val = orig_pb(entry, content)
+            pb_cache[p] = (gen, val)
+            return val
+
+        cg._positive_body = _cached_pb
+        cg._positive_body_cache = pb_cache
     return cache
 
 
-# 生效条件：cg._read_cache 与 cg._norm_bigrams_cache 均清空（写侧显式兜底；哨兵之外的强制手段），返回清空的条目总数；无缓存时返回 0。
+# 生效条件：cg._read_cache、cg._norm_bigrams_cache 与 cg._positive_body_cache 均清空（写侧显式兜底；哨兵之外的强制手段），返回清空的条目总数；无缓存时返回 0。
 def clear(cg) -> int:
     """强制清空（外部批量改写文件后可手动调；正常写路径无需——哨兵自动失效）。"""
     n = 0
-    for attr in ("_read_cache", "_norm_bigrams_cache"):
+    for attr in ("_read_cache", "_norm_bigrams_cache", "_positive_body_cache"):
         c = getattr(cg, attr, None)
         if c:
             n += len(c)

package/md_cg/selfreport.py

@@ -126,10 +126,19 @@ def read_all() -> dict:
     return out
 
 
-# 生效条件：pids 为可迭代的 pid 集合（通常是「当前进程表中仍在的 md_cg 进程」）；删除自报目录中 pid 不在该集合内的 *.json 与遗留 *.tmp，返回删除条数；目录不存在或删除失败逐项吞掉，不抛。
-def purge(pids) -> int:
-    """清掉不属于「仍在的进程」的自报文件（防目录随重启次数膨胀）。"""
+# 生效条件：pids 为可迭代的 pid 集合（通常是「当前进程表中仍在的 md_cg 进程」），allow_empty 为破坏性动作的显式开关；keep 非空时删除自报目录中 pid 不在该集合内的 *.json 与遗留 *.tmp 并返回删除条数；keep 为**空集**且 allow_empty=False（默认）时一律不删并返回 0——空集既可能是「在役进程真的全部退出」也可能是「探测失败/未经校验」，两者不可分，故清空须显式开启；目录不存在或删除失败逐项吞掉，不抛。
+def purge(pids, *, allow_empty: bool = False) -> int:
+    """清掉不属于「仍在的进程」的自报文件（防目录随重启次数膨胀）。
+
+    N255（2026-10-05）：keep 为空集时**默认不删任何东西**（fail-closed）——空集既可能来自
+    「在役进程确已全部退出」，也可能来自**一次失败/未经校验的探测**。后者在本仓实证过：
+    `scripts/mdcg_stale_servers.py` 的 scan() 尾部曾无条件调用 `purge([])`（探测失败 →
+    pids 为空），把自报目录下全部 *.json 一次删光（沙盒 3 件预置全灭）。确要清空时，由
+    **探测已成功**的调用方显式传 `allow_empty=True`（见该脚本的 purge_reports()）。
+    """
     keep = {int(p) for p in (pids or ())}
+    if not keep and not allow_empty:
+        return 0
     n = 0
     try:
         names = os.listdir(SELF_REPORT_DIR)

package/md_cg/sleep.py

@@ -31,12 +31,18 @@
 
 四阶段（§4.4）里本模块的落点：
 
-    ① 物化   `materialize()`          —— 持根级锁；主库真源面逐字节不变
+    ① 物化   `materialize()`          —— 持根级锁；挂上影子即成功（`ok=True`）；
+                                       真源面在窗口内漂移只记 `face_stable=False`，
+                                       **不阻断迭代**（漂移交 ③ 的并发闸按「主库
+                                       优先」逐项处置——issue #60）
     ② 迭代   （P1；在影子上跑，本模块不管）
     ③ 对账+提交 `reconcile_and_commit()` —— 持根级锁；Δ 为空即零提交零写入
     ④ 合并   `merge()`                —— 持根级锁；写主库的正是「应写的那部分」
 
-脚本式用法（只读判读）：`python -X utf8 -m md_cg.sleep --status`
+脚本式用法：`python -X utf8 -m md_cg.sleep --status`（只读判读，含上一轮读数）｜
+            `--once`（立即跑一轮，不等常驻 tick，同样过四道门）｜
+            `--once --dry-run`（只预览：跑盘点与四道门，不物化、不记账）｜
+            `--audit`（只跑两条机械判据）
 """
 from __future__ import annotations
 
@@ -352,7 +358,7 @@ def _busy(phase: str, timeout: float) -> dict:
                        "只有一个能进）")}
 
 
-# 生效条件：root 为数据根（缺省取 mdcg_root()）；在 <state_root>/sleep/sleep 的根级锁内，建/复用独立 git 目录并（首次）把真源面入册为 main 基线，再 git worktree add -b sleep/<ts> <shadow> main（分支已存在则复用该分支重试一次）；返回含 ok/phase/busy/git_dir/shadow/branch/pathspecs/lock_acquired/source_face_delta/lock 的字典——ok 为真且 source_face_delta 三键全空 = 主库真源面逐字节未变。
+# 生效条件：root 为数据根（缺省取 mdcg_root()）；在 <state_root>/sleep/sleep 的根级锁内，建/复用独立 git 目录并（首次）把真源面入册为 main 基线，再 git worktree add -b sleep/<ts> <shadow> main（分支已存在则复用该分支重试一次）；返回含 ok/face_stable/phase/busy/lock_held/git_dir/shadow/branch/pathspecs/baseline/source_face_delta/lock 的字典——**ok = 物化动作是否成功**（正常挂上影子的成功路径恒真；取不到根级锁或影子未能挂上时保持假）；**face_stable = 主库真源面在物化窗口内逐字节未变**（原 ok 的真值；漂移不阻断物化，交 ③ 的并发闸按「主库优先」处置）。
 def materialize(root: str = None, *, git_dir_path: str = None,
                 shadow: str = None, ts: str = None,
                 timeout: float = DEFAULT_LOCK_TIMEOUT) -> dict:
@@ -360,6 +366,11 @@ def materialize(root: str = None, *, git_dir_path: str = None,
 
     幂等：影子已存在时先摘（`worktree remove --force`，非注册目录退化为 rmtree）
     再挂。分支已存在（同一秒重入）时退化为复用该分支。
+
+    `ok` 与 `face_stable` 是**两件事**（issue #60）：前者只说「影子挂上了没」，
+    后者才是「物化窗口内主库真源面有没有被别的写方动过」。窗口内漂移**不阻断**
+    迭代——活跃工作区（每轮都有新增 contextual/*.md）正是如此；同一 id 的改动
+    由 ③ 的并发闸（`baseline_face` 水位，主库优先）逐项裁决，那才是漂移的处置点。
     """
     root = os.path.abspath(root or mdcg_root())
     G = git_dir_path or git_dir()
@@ -391,7 +402,11 @@ def materialize(root: str = None, *, git_dir_path: str = None,
             reused = False
         after = source_face_hashes(root)
         delta = face_delta(before, after)
-        return {"ok": not (delta["added"] or delta["removed"] or delta["changed"]),
+        # ok = **物化动作成功**（影子已挂上）；真源面漂移与否是另一个读数
+        # （face_stable），不再拿来否决整轮迭代（issue #60）。
+        return {"ok": True,
+                "face_stable": not (delta["added"] or delta["removed"]
+                                    or delta["changed"]),
                 "busy": False, "lock_held": True, "phase": "materialize",
                 "git_dir": G, "shadow": S, "branch": branch,
                 "branch_reused": reused, "repo_created": rep["created"],
@@ -655,6 +670,34 @@ def batch_merged(batch: str) -> bool:
                for r in read_ledger())
 
 
+# 生效条件：无入参；返回台账里的**下一轮序号**（已有记录中最大的 round + 1；空台账/无有效 round 时为 1）——CLI `--once` 接着历史轮次编号，不另起一套计数。
+def next_round_index() -> int:
+    nums = [r.get("round") for r in read_ledger()]
+    nums = [n for n in nums if isinstance(n, int) and not isinstance(n, bool)]
+    return (max(nums) + 1) if nums else 1
+
+
+# 生效条件：rec 为 run_cycle 落台账的记录字典时，返回 ⑦记录步里的 phases 字典（缺该步或形态不符时返回 {}）。
+def _record_phases(rec: dict) -> dict:
+    for s in (rec.get("steps") or []):
+        if isinstance(s, dict) and s.get("step") == "record":
+            return s.get("phases") or {}
+    return {}
+
+
+# 生效条件：rec 为 run_cycle 落台账的记录字典时返回「本轮未迭代原因」文案或 None——先取门拦 `rec["skipped"]`，再取 ②③④ 的 skip 文案（物化未完成等）；已迭代的一轮返回 None。CLI `--once` 与 `--status` 的同一文案源（不另写第二份判据）。
+def cycle_not_iterated_reason(rec: dict):
+    if not isinstance(rec, dict):
+        return None
+    if rec.get("skipped"):
+        return rec["skipped"]
+    for s in (rec.get("steps") or []):
+        if isinstance(s, dict) and s.get("step") in ("induce", "promote", "scrub") \
+                and s.get("skipped"):
+            return s["skipped"]
+    return None
+
+
 # 生效条件：root 给定且 md_cg.mdcos 可导入时返回该 root 上的 MdCGOS 实例；导入失败抛原异常。
 def _open_cg(root: str):
     from .mdcos import MdCGOS
@@ -1151,13 +1194,19 @@ def ledger_steps(*, scan: dict, iterated: dict = None, delta_digest: dict = None
     return steps
 
 
-# 生效条件：给定 cg（主库）与各相位开关时，按 §3.2 的稳态判据与 §4.4 的四阶段跑一轮睡眠周期并返回台账记录；enabled=False / merge_mode="never" / 窗口外 / 候选数为 0 四种情形**只记账不动手**（②③④记 skipped）；batch 为已合并批次时直接返回 {"idempotent": True} 且零动作。
+# 生效条件：给定 cg（主库）与各相位开关时，按 §3.2 的稳态判据与 §4.4 的四阶段跑一轮睡眠周期并返回台账记录；enabled=False / merge_mode="never" / 窗口外 / 候选数为 0 四种情形**只记账不动手**（②③④记 gate_reason）；物化未完成（busy/error）时 ②③④ 记「物化未完成：…」（与门拦文案**区分**）；batch 为已合并批次时直接返回 {"idempotent": True} 且零动作；dry_run=True 时只跑感知盘点与四道门评估（**不物化、不记账**）。
 def run_cycle(cg=None, *, root: str = None, batch: str = None,
               enabled: bool = True, merge_mode: str = None,
               scrub_apply: bool = None, window: str = None,
               round_index: int = 1, now=None, git_dir_path: str = None,
-              shadow: str = None, timeout: float = DEFAULT_LOCK_TIMEOUT) -> dict:
-    """一轮睡眠周期（§3.1 九步 + §4.4 四阶段）。"""
+              shadow: str = None, dry_run: bool = False,
+              timeout: float = DEFAULT_LOCK_TIMEOUT) -> dict:
+    """一轮睡眠周期（§3.1 九步 + §4.4 四阶段）。
+
+    `dry_run=True` 是**预览档**（`--once --dry-run`）：只跑 ① 感知盘点与四道门
+    评估（总开关 / 合并策略 / 窗口 / 稳态），**不物化、不记账**——早退点刻意
+    置于 `materialize` 之前，也不触 `_append_ledger`。
+    """
     root = os.path.abspath(root or (cg.root if cg is not None else mdcg_root()))
     if cg is None:
         cg = _open_cg(root)
@@ -1179,7 +1228,10 @@ def run_cycle(cg=None, *, root: str = None, batch: str = None,
                    candidates=None, steps=ledger_steps(
                        scan={}, skip_reason="幂等：同批次已合并",
                        round_index=round_index, prev_candidates=prev))
-        _append_ledger(rec)
+        if dry_run:
+            rec["dry_run"] = True               # 预览档：**不记账**
+        else:
+            _append_ledger(rec)
         return rec
 
     # ① 感知盘点（主库，只读）——稳态判据的口径
@@ -1200,14 +1252,37 @@ def run_cycle(cg=None, *, root: str = None, batch: str = None,
     elif not scan["candidates"]:
         gate_reason = "稳态：盘点候选数为 0（只记账不动手）"
 
+    if dry_run:
+        # 预览档：四道门已评完即止——**不物化、不记账**（连影子都不建）。
+        rec.update(dry_run=True, skipped=gate_reason,
+                   planned=(None if gate_reason
+                            else "将执行物化→迭代→对账→合并"),
+                   steps=ledger_steps(scan=scan, round_index=round_index,
+                                      prev_candidates=prev,
+                                      skip_reason=gate_reason or ""))
+        return rec
+
     phases, iterated, delta, digest = {}, None, {}, {"n": 0, "ids": [], "kinds": {}}
+    mat_fail = None
     if gate_reason is None:
         m = materialize(root, git_dir_path=git_dir_path, shadow=shadow,
                         ts=b, timeout=timeout)
         phases["materialize"] = {k: m.get(k) for k in
-                                 ("ok", "busy", "branch", "shadow", "git_dir",
-                                  "baseline", "source_face_delta")}
+                                 ("ok", "face_stable", "busy", "branch", "shadow",
+                                  "git_dir", "baseline", "source_face_delta",
+                                  "reason", "error")}
+        if not m.get("ok"):
+            # 物化**未完成**（取不到根级锁 / 影子未能挂上）——与「门拦」区分记账：
+            # 门拦是「按设计不动手」，这里是「想动手却没做成」，用户要能一眼分开。
+            mat_fail = ("物化未完成：根级锁被占（另一进程在周期内）"
+                        if m.get("busy")
+                        else "物化未完成：%s" % (m.get("error") or "未知原因"))
         if m.get("ok"):
+            # **物化成功即迭代**（issue #60）：`ok` 现在只说「影子挂上了没」；
+            # 物化窗口内主库真源面的漂移另记 `face_stable`，**不阻断**迭代——
+            # 活跃工作区（每轮都有新写入）本就如此。迭代期间主库被改动/新增的
+            # 同一 id，由下面对账段的并发闸（`baseline_face` 水位）逐项裁
+            # 「主库优先」——那才是漂移的处置点，不是在这里自我否决。
             S = m["shadow"]
             iterated = iterate(S, scrub_apply=scrub)
             phases["iterate"] = iterated
@@ -1255,25 +1330,64 @@ def run_cycle(cg=None, *, root: str = None, batch: str = None,
     rec["steps"] = ledger_steps(scan=scan, iterated=iterated,
                                 delta_digest=digest, phases=phases,
                                 round_index=round_index, prev_candidates=prev,
-                                skip_reason=gate_reason or "")
+                                skip_reason=gate_reason or mat_fail or "")
     rec["skipped"] = gate_reason
     _append_ledger(rec)
     return rec
 
 
-# 生效条件：argv 含 --status 时打印当前解析结果（git_dir / shadow / lock / pathspecs / tracking / history 四读数）的 JSON 并返回 0；argv 含 --audit 时只打印两条机械判据结论（不合规返回 1）；无参数时打印解析结果。
+# 生效条件：recs 为 read_ledger(limit=1) 的返回（空列表或单条记录）时，返回该记录的 CLI 视图（t/batch/round/candidates/skipped / ②③④ skip 文案 / phases.materialize 摘要 / 未迭代原因）；无记录返回 None。
+def _last_cycle_view(recs):
+    if not recs:
+        return None
+    rec = recs[-1]
+    return {"t": rec.get("t"), "batch": rec.get("batch"),
+            "round": rec.get("round"), "candidates": rec.get("candidates"),
+            "skipped": rec.get("skipped"),
+            "steps_skip": {s.get("step"): s.get("skipped")
+                           for s in (rec.get("steps") or [])
+                           if isinstance(s, dict)
+                           and s.get("step") in ("induce", "promote", "scrub")},
+            "materialize": _record_phases(rec).get("materialize"),
+            "not_iterated_reason": cycle_not_iterated_reason(rec)}
+
+
+# 生效条件：argv 含 --once 时以 env 读取器为参数跑一轮 run_cycle（round 取 next_round_index()；--dry-run 同用时只预览、不物化不记账）并打印整条记录与「本轮未迭代原因」（未迭代时，文案与台账同源）；argv 含 --audit 时只打印两条机械判据结论（不合规返回 1）；--dry-run **不与 --once 同用**时返回 2（报错，不执行任何动作）；其余情形打印当前解析结果（git_dir / shadow / lock / pathspecs / tracking / history / **last_cycle** 读数）的 JSON 并返回 0。
 def _main(argv=None) -> int:
-    ap = argparse.ArgumentParser(description="睡眠周期 git 机制（只读判读面）")
+    ap = argparse.ArgumentParser(description="睡眠周期 git 机制（只读判读 + 手动一轮）")
     ap.add_argument("--root", default=None, help="数据根（缺省 mdcg_root()）")
     ap.add_argument("--git-dir", dest="git_dir_path", default=None)
     ap.add_argument("--shadow", default=None)
     ap.add_argument("--status", action="store_true", help="打印当前解析与判据读数")
     ap.add_argument("--audit", action="store_true", help="只跑两条机械判据")
+    ap.add_argument("--once", action="store_true",
+                    help="立即跑一轮睡眠周期（不等常驻循环的 tick；同样过四道门）")
+    ap.add_argument("--dry-run", dest="dry_run", action="store_true",
+                    help="只预览（须与 --once 同用）：跑盘点与四道门，不物化、不记账")
     a = ap.parse_args(argv)
+    if a.dry_run and not a.once:
+        sys.stderr.write("--dry-run 须与 --once 同用："
+                         "单独使用不执行任何动作（预览一轮请用 --once --dry-run）\n")
+        return 2
     root = os.path.abspath(a.root or mdcg_root())
     G = a.git_dir_path or git_dir()
     shadow = a.shadow or shadow_dir()
     sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if a.once:
+        rec = run_cycle(None, root=root, enabled=sleep_enabled(),
+                        merge_mode=sleep_merge_mode(),
+                        scrub_apply=sleep_scrub_apply(), window=sleep_window(),
+                        round_index=next_round_index(), dry_run=a.dry_run,
+                        git_dir_path=a.git_dir_path, shadow=a.shadow)
+        print(json.dumps(rec, ensure_ascii=False, indent=2))
+        if rec.get("dry_run"):
+            print("预览：" + (rec.get("planned")
+                            or ("门拦：%s" % (rec.get("skipped") or ""))))
+        else:
+            why = cycle_not_iterated_reason(rec)
+            if why:
+                print("本轮未迭代原因：" + why)
+        return 0
     if a.audit:
         tr = audit_tracking(root, git_dir_path=G)
         hi = audit_history(root, git_dir_path=G)
@@ -1289,6 +1403,8 @@ def _main(argv=None) -> int:
     if os.path.isdir(G):
         out["tracking"] = audit_tracking(root, git_dir_path=G)
         out["history"] = audit_history(root, git_dir_path=G)
+    # 上一轮读数：从 CLI 就能看到「上次为何没迭代」（门拦 / 物化未完成 / 幂等）。
+    out["last_cycle"] = _last_cycle_view(read_ledger(limit=1))
     print(json.dumps(out, ensure_ascii=False, indent=2))
     return 0
 

package/md_cg/sources.py

@@ -258,7 +258,7 @@ class DSHSessionSource(Source):
 
 
 # --------------------------------------------------------------------------
-# 蜂巢任务事件源（M6：hive/jobs → contextual，D:\2_ai 蜂巢记忆架构设计.md §5）
+# 蜂巢任务事件源（M6：hive/jobs → contextual，外部设计稿 蜂巢记忆架构设计.md §5）
 # --------------------------------------------------------------------------
 
 class HiveJobsSource(Source):