@furongjun1999/dsh-memory 0.7.2 → 0.7.4

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):

package/md_cg/state_events.py

@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""状态事件账本（append-only）——多主体世界模型 L0「事件必记账」的最小承载。
+
+背景（对齐评估 v0.1，§2 L0）：CD-WHALE-01（鲸娘语料 731 轮）的六类缺陷全部落在
+「迁移/撤回/启用/来源」四个**状态操作**上（属性记得住、状态记不住）；CTP-P5
+回放的敏感性边界一证明「现行侧若只有状态陈述（T2）而无事件记录（T1），设施回滚
+只能判 DEFER」——故「事件必记账」是状态链（基线→变更→后续引用）与退役/否定
+语义的前置（跨切纪律 1）。
+
+设计约束（对齐评估 v0.1 复核修订后的口径）：
+  · **append-only**：`_recent.jsonl` 为窗口滚动面（`DEFAULT_RECENT_WINDOW=200`，
+    `roll_recent` 超限即截断），不可作一等记录；本账本只追加、不读改写、不截断。
+  · **单一真源**：事件是源、槽位现值是投影（未来 L2 寄存器由本账本物化；
+    落盘位置与 `_evolution` 台账/审计同级：`<root>/_state_events.jsonl`）。
+  · **五元结构**：主体 subject ／ 槽位 slot ／ 旧值 old → 新值 new ／ 轮或序号
+    seq ／ 出处 evidence（＋ kind 五类变迁事件 ＋ actor 断言者 ＋ t 时间戳）。
+
+KINDS 五类对齐《角色扮演一致性锚调研 v0.1》§3.4「变迁事件」：
+迁移 migration ／ 撤回 retraction ／ 启用 enablement ／ 购买获得 acquisition ／
+替换 replacement。「撤回」语义：old 有值而 new 为空（值作废、无新值）；
+「启用」：old 空而 new 有值；「迁移/替换」：old 与 new 皆有值。
+分类本身不进判据（记账不判语义），只作检索面标签。
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+from .fsutil import FileLock
+
+#: 账本文件名（库根下，与 `_recent.jsonl`/`_write_2pc.jsonl` 同级）。
+STATE_EVENTS_NAME = "_state_events.jsonl"
+
+#: 五类变迁事件（角色扮演一致性锚调研 v0.1 §3.4）。
+KINDS = ("migration", "retraction", "enablement", "acquisition", "replacement")
+
+#: 坏行容忍记账（容忍 ≠ 静默——本仓 N225 已确立的判据：跳过要可观测）。
+BAD_ROWS = 0            # 累计**跳过动作次数**（同一坏行每次 read 均计一次；非按行去重）
+_BAD_ROW_SAMPLES = []   # 有界样本：(行号, 行首 80 字符, 异常类型名)
+_BAD_ROW_SAMPLE_CAP = 8
+
+
+def _note_bad_row(lineno: int, line: str, exc: Exception):
+    global BAD_ROWS
+    BAD_ROWS += 1
+    if len(_BAD_ROW_SAMPLES) < _BAD_ROW_SAMPLE_CAP:
+        _BAD_ROW_SAMPLES.append((lineno, line[:80], type(exc).__name__))
+    sys.stderr.write(
+        f"[state_events] 跳过坏行（第 {lineno} 行，累计 {BAD_ROWS}）："
+        f"{type(exc).__name__}: {exc}\n")
+
+
+# 生效条件：cg 可解析出 root 时，返回 os.path.join(cg.root, STATE_EVENTS_NAME)。
+def ledger_path(cg) -> str:
+    return os.path.join(cg.root, STATE_EVENTS_NAME)
+
+
+# 生效条件：subject 与 slot 去空白后必须非空（否则 ValueError）；kind 非 None 时必须属于
+# KINDS（否则 ValueError）；old 与 new 不得同时为 None（否则 ValueError）；通过后在
+# FileLock(ledger_path) 内以追加模式写一行 JSON（ensure_ascii=False，flush+fsync），
+# 返回落盘记录 dict（不改任何既有文件、不读改写、不截断）。
+def append(cg, subject, slot, old=None, new=None, kind=None, seq=None,
+           evidence="", actor="", extra=None) -> dict:
+    """追加一条状态事件（append-only；跨进程锁；崩溃不留半截文件）。"""
+    sub = str(subject or "").strip()
+    sl = str(slot or "").strip()
+    if not sub:
+        raise ValueError("状态事件必须声明主体（subject）")
+    if not sl:
+        raise ValueError("状态事件必须声明槽位（slot）")
+    if kind is not None and kind not in KINDS:
+        raise ValueError(f"未知变迁事件类型：{kind}（允许：{KINDS}）")
+    if old is None and new is None:
+        raise ValueError("状态事件 old 与 new 不能同时为空（空事件无意义）")
+    rec = {
+        "t": time.time(),
+        "subject": sub,
+        "slot": sl,
+        "old": old,
+        "new": new,
+        "kind": kind,
+        "seq": seq,
+        "evidence": str(evidence or ""),
+        "actor": str(actor or ""),
+    }
+    if extra:
+        rec.update(extra)
+    p = ledger_path(cg)
+    os.makedirs(os.path.dirname(p) or ".", exist_ok=True)
+    with FileLock(p):
+        with open(p, "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+            f.flush()
+            os.fsync(f.fileno())
+    return rec
+
+
+# 生效条件：ledger_path 不存在时返回 []；存在时逐行 json.loads（空行跳过；非对象载荷或
+# JSON 解析失败按坏行处置——计数+有界样本+stderr 告警后跳过，不中断读）；subject/slot/kind
+# **非 None** 时按对应字段过滤（空串亦为合法过滤值，2026-10-05 复核口径钉正）；limit 为
+# 真值时只保留最后 limit 条；返回记录列表（落盘序）。
+def read(cg, subject=None, slot=None, kind=None, limit=0) -> list:
+    """读回（可按 subject/slot/kind 过滤；limit=0 不截断）。坏行跳过并记账。"""
+    p = ledger_path(cg)
+    out = []
+    if not os.path.exists(p):
+        return out
+    with open(p, encoding="utf-8", errors="replace") as f:
+        for i, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+                if not isinstance(rec, dict):
+                    raise ValueError("行载荷非对象")
+            except Exception as e:  # noqa: BLE001 —— 容忍≠静默：记账后跳过
+                _note_bad_row(i, line, e)
+                continue
+            if subject is not None and rec.get("subject") != subject:
+                continue
+            if slot is not None and rec.get("slot") != slot:
+                continue
+            if kind is not None and rec.get("kind") != kind:
+                continue
+            out.append(rec)
+    if limit:
+        out = out[-int(limit):]
+    return out

package/md_cg/state_slots.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""状态槽位寄存器投影（L2「主体×谓词槽位」）——**事件是源、槽位是投影**。
+
+设计稿：`docs/plans/语义时空图补全_世界模型功能端_设计_v0.1.md` §2/§3（P2 批）。
+
+本模块是**投影，不是第二真源**：
+  · 源＝`md_cg/state_events.py` 的 append-only 台账 `<root>/_state_events.jsonl`；
+  · 查询时**现算**——不落盘、不建缓存、不写任何盘面文件；
+  · 台账追加一条，投影立刻随之变化（无缓存、无物化表 ⇒ 无第二真源、无漂移面）；
+  · 本模块**只读**台账（经 `state_events.read`；`append` 归 `state_events`）。
+
+投影单元字段（设计稿 §3 表逐字）：
+    subject / slot / value / state(active|retired) / t_from / t_to /
+    seq_from / seq_to / tier / alternatives / blindspots / history / event_count
+
+回放规则（分组键 `(subject, slot)`，组内按 `state_events.read()` 的**落盘序**）：
+  · `value` 自 None 起：事件 `new` 非空 → `value=new`；`new` 空（撤回）→ `value=None`
+    且 `state=retired`；其后带值事件自然复活（事件序自然处理，无特判分支）。
+  · `state`：**最后一个事件的形态**决定——`new` 空 → `'retired'`；否则 `'active'`。
+  · 区间（取值一律用事件行的 `t` 落账时间戳，不另算时间）：
+    `t_from`/`seq_from` ＝**最后产生当前值**的那条事件的 `t`/`seq`（retired 态＝
+    最后一个**有值**事件的）；`t_to`/`seq_to` ＝**覆盖它的下一条事件**的 `t`/`seq`
+    （不存在＝None，即「未闭合／仍有效」）；retired 态的覆盖者＝撤回事件（闭合点
+    ＝值作废时刻）。
+  · `tier` ＝最后有值事件的顶层 `tier` 透传（`append(extra=…)` 会把 extra 并入行
+    顶层，故「extra.tier」与「行顶层 tier」是同一处）；缺失（键不在或为 None）→
+    `TIER_UNSPECIFIED`——**不编造**。
+  · `alternatives` / `blindspots`：本批**结构在场、恒为空列表**——「同期未决值」与
+    「声明缺口」的判定口径**后置**（P1 事件行尚无该信号），**不得臆造填充**。
+  · `history` ＝该槽位全部事件原样（每条＝事件行的 `t/seq/old/new/kind/evidence/
+    actor` 七字段，值不改写；缺键取 None）；`history=False` 时**不带该键**。
+
+撤回判据取 **payload**（`new` 为空）而不是 `kind` 标签：台账口径是「撤回＝old 有值而
+new 为空」（`state_events` 模块头），且该模块明言「分类本身不进判据（记账不判语义）」
+——两者一致时等价；冲突时以 payload 为准（不按标签改写数据）。判据单点＝`_is_void`。
+
+过滤与排序：`subject`/`slot` 为 None 不加过滤（该过滤**委托** `state_events.read`，
+此处不写第二套条件解析）；`include_retired=False` 剔除 `state=='retired'` 的单元；
+结果按 `(subject, slot)` 字典序稳定排序。
+
+CLI（纯只读人工入口，**恒可用、无开关**）：
+    python -X utf8 -m md_cg.state_slots --status
+    python -X utf8 -m md_cg.state_slots --subject 鲸娘 [--slot 住所]
+数据根取 `MDCG_ROOT`（缺省走 `datapath.mdcg_root()`，与 `md_cg/sleep.py` 的
+`_main` 同形）。本面与 stg 的 `MDCG_STG_STATE` 开关**无关**：开关管的是 MCP 读面，
+CLI 是人工排查入口（只读、不改任何状态）。
+
+不适用条件：本模块**不判语义**——「不是事实」的言语（玩笑/元层/回忆转述）之消歧
+标记（`not_fact` 等）不在本批（P1 事件行无该信号）；`alternatives`/`blindspots` 的
+真值判定亦未落地（见上，恒空列表）。跨库/多租户合并不在此（单库＝单台账）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import state_events
+
+#: 缺档位占位（台账未带 `tier` 时如实标注，不编造档位）。
+TIER_UNSPECIFIED = "unspecified"
+
+#: `history` 条目**必在**字段（单元 schema 逐字；缺键取 None，不改写数据）。
+_HIST_FIELDS = ("t", "seq", "old", "new", "kind", "evidence", "actor")
+
+
+# 生效条件：rec 为台账记录 dict——`rec.get("new")` 为 None 时返回 True（撤回/值作废），非 None 时返回 False；入参非 dict 时按 `.get` 抛 AttributeError（台账读面保证为 dict，不吞错）。
+def _is_void(rec) -> bool:
+    """撤回判据（单点）：`new` 为空＝值作废、无新值（口径见模块头）。"""
+    return rec.get("new") is None
+
+
+# 生效条件：rec 为一条台账记录 dict 时，返回含 _HIST_FIELDS 七键（缺键取 None）的新 dict——字段集＝单元 schema 的 history 条目逐字（不并入行内其余顶层键：新增键即「发明字段」，故限定枚举）；值原样不改写、不改写入参。
+def _hist_item(rec) -> dict:
+    """变迁史单条：单元 schema 的七字段原样（值不改写）。"""
+    return {k: rec.get(k) for k in _HIST_FIELDS}
+
+
+# 生效条件：subject/slot 为分组键、recs 为同组记录（**非空**，落盘序）、history 为真值时——按模块头回放规则返回单元 dict（含 history 键）；history 为假值时同一单元但不带 history 键；recs 为空时抛 IndexError（组由记录现场建成，恒非空，不吞错）。
+def _replay(subject, slot, recs, *, history=True) -> dict:
+    """单组回放：现值 / 档位 / 区间 / 变迁史（规则逐条见模块头）。"""
+    value = None
+    last_valued = None              # 最后**产生当前值**的事件下标（无则 None）
+    for i, rec in enumerate(recs):
+        if _is_void(rec):
+            value = None            # 撤回：值作废、无新值
+        else:
+            value = rec.get("new")
+            last_valued = i
+    last = recs[-1]
+    retired = _is_void(last)        # state：最后一个事件的形态决定
+    if last_valued is None:
+        # 全程无有值事件（孤立撤回）：起端无可溯源 ⇒ None（不编造）。
+        t_from, seq_from = None, None
+        tier = TIER_UNSPECIFIED
+    else:
+        lv = recs[last_valued]
+        t_from, seq_from = lv.get("t"), lv.get("seq")
+        tier = lv.get("tier")
+        if tier is None:
+            tier = TIER_UNSPECIFIED
+    # 覆盖者：retired 态＝撤回事件（最后一条，闭合点＝值作废时刻）；否则＝有值事件的
+    # **下一条**事件（存在则闭合，不存在＝None＝未闭合）；两者共用同一取舍。
+    nxt = (len(recs) - 1) if retired else (
+        None if last_valued is None else last_valued + 1)
+    if nxt is not None and 0 <= nxt < len(recs):
+        t_to, seq_to = recs[nxt].get("t"), recs[nxt].get("seq")
+    else:
+        t_to, seq_to = None, None
+    unit = {"subject": subject, "slot": slot, "value": value,
+            "state": "retired" if retired else "active",
+            "t_from": t_from, "t_to": t_to,
+            "seq_from": seq_from, "seq_to": seq_to,
+            "tier": tier,
+            # 结构在场、恒空：判定口径后置（模块头，不得臆造填充）。
+            "alternatives": [], "blindspots": [],
+            "event_count": len(recs)}
+    if history:
+        unit["history"] = [_hist_item(r) for r in recs]
+    return unit
+
+
+# 生效条件：recs 为台账记录序列（落盘序，可空）时——按 (subject, slot) 分组（组序＝首现序）后按 (str(subject), str(slot)) 字典序稳定排序，逐组经 _replay；include_retired 为假时剔除 state=='retired' 的单元，为真时全留；返回单元列表（recs 为空返回 []）；history 透传 _replay（假时不带 history 键）。
+def _project(recs, *, include_retired=False, history=True) -> list:
+    """记录序列 → 单元列表（project 与 status 共用的回放单点）。"""
+    groups = {}
+    for rec in recs:
+        key = (rec.get("subject"), rec.get("slot"))
+        groups.setdefault(key, []).append(rec)
+    # 排序键经 str() 归一：台账是外部可写面（append-only），非字符串 subject/slot 会让
+    # 裸元组比较抛 TypeError；字符串形态（正常）下与裸元组字典序逐位一致。
+    out = []
+    for key in sorted(groups, key=lambda k: (str(k[0]), str(k[1]))):
+        unit = _replay(key[0], key[1], groups[key], history=history)
+        if unit["state"] == "retired" and not include_retired:
+            continue
+        out.append(unit)
+    return out
+
+
+# 生效条件：cg 可解析出 root（经 state_events.ledger_path）时——以 state_events.read(cg, subject=subject, slot=slot) 为源（subject/slot 非 None 才过滤，空串亦为合法过滤值）、现算回放，返回单元列表；include_retired=False 剔除 state=='retired' 的单元；history=False 时单元不带 history 键；台账缺失/为空返回 []（不报错）。**零落盘、零缓存**——同一调用序列中台账追加一条，下一次调用结果即变。
+def project(cg, subject=None, slot=None, include_retired=False,
+            history=True) -> list:
+    """槽位寄存器投影（查询时现算）：list[dict]（单元字段见模块头）。
+
+    纯读函数：不改台账、不写盘、不缓存；过滤委托 `state_events.read`（单点），
+    本模块不另写一套条件解析。
+    """
+    recs = state_events.read(cg, subject=subject, slot=slot)
+    return _project(recs, include_retired=include_retired, history=history)
+
+
+# 生效条件：cg 可解析出 root 时——一次 state_events.read(cg) 后返回只读统计 dict：events（台账记录总数）/ subjects（去重 subject 数）/ slots（去重 slot 数）/ retired（回放后 state=='retired' 的单元数）/ bad_rows（state_events.BAD_ROWS 累计值，坏行采样与告警由该模块负责）；台账缺失/为空时 events/subjects/slots/retired 皆 0。
+def status(cg) -> dict:
+    """台账与投影的只读读数（不计语义、不改任何状态）。
+
+    只读一次台账后回放：`bad_rows` 的口径是「累计**跳过动作次数**」（同一坏行每次
+    read 均计一次，见 `state_events`）——本函数每次调用只产生**一次** read。
+    `slots` 为去重**槽位名**数（同一槽位名挂在多个主体下只算一次）；
+    `retired` 为回放后退役单元数（值已作废、未复活）。
+    """
+    recs = state_events.read(cg)
+    units = _project(recs, include_retired=True, history=False)
+    return {"events": len(recs),
+            "subjects": len({r.get("subject") for r in recs}),
+            "slots": len({r.get("slot") for r in recs}),
+            "retired": sum(1 for u in units if u["state"] == "retired"),
+            "bad_rows": state_events.BAD_ROWS}
+
+
+# 生效条件：root 给定且 md_cg.mdcos 可导入时返回该 root 上的 MdCGOS 实例（形态同 md_cg/sleep.py:_open_cg）；导入失败抛原异常。
+def _open_cg(root: str):
+    from .mdcos import MdCGOS
+    return MdCGOS(root)
+
+
+# 生效条件：传入 argv（None 取 sys.argv）——--status 时打印 status(cg) 的 JSON 并返回 0；否则要求 --subject（可配 --slot）或 --slot 单用，打印 project(cg, subject, slot, include_retired, history) 的 JSON 并返回 0；两者皆缺时打印**全量投影**（含退役需显式 --include-retired）并返回 0；--root 缺省取 datapath.mdcg_root()（env MDCG_ROOT）；argparse 对未知参数照常以 SystemExit(2) 退出（不吞）。
+def _main(argv=None) -> int:
+    """只读人工入口：台账现状（--status）/ 槽位投影（--subject [--slot]）。
+
+    本入口**恒可用**（不受 `MDCG_STG_STATE` 开关约束——那把开关管的是 MCP 读面）；
+    全程只读：不 append、不落盘、不改任何状态。
+    """
+    ap = argparse.ArgumentParser(
+        description="状态槽位投影（只读）：台账现算，不落盘、不缓存")
+    ap.add_argument("--root", default=None, help="数据根（缺省 mdcg_root()）")
+    ap.add_argument("--status", action="store_true",
+                    help="只打印台账/投影统计（events/subjects/slots/retired/bad_rows）")
+    ap.add_argument("--subject", default=None, help="按主体过滤（省略＝不过滤）")
+    ap.add_argument("--slot", default=None, help="按槽位过滤（省略＝不过滤）")
+    ap.add_argument("--include-retired", dest="include_retired",
+                    action="store_true", help="含退役单元（缺省剔除）")
+    ap.add_argument("--no-history", dest="history", action="store_false",
+                    help="不带变迁史（history 键省略）")
+    a = ap.parse_args(argv)
+    try:
+        # 进程内调用（守卫/嵌入）会重定向 stdout：无 reconfigure 的流上跳过，
+        # 不改变任何输出内容。
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:                              # noqa: BLE001
+        pass
+    root = os.path.abspath(a.root or _default_root())
+    cg = _open_cg(root)
+    if a.status:
+        out = status(cg)
+    else:
+        out = project(cg, subject=a.subject, slot=a.slot,
+                      include_retired=a.include_retired, history=a.history)
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+# 生效条件：无入参；返回 datapath.mdcg_root()（env MDCG_ROOT 非空时取该值，否则 paths.json/缺省），失败时抛原异常（不吞）。
+def _default_root() -> str:
+    from .datapath import mdcg_root
+    return mdcg_root()
+
+
+if __name__ == "__main__":
+    sys.exit(_main())