@furongjun1999/dsh-memory 0.5.0 → 0.6.0

package/md_cg/test_session_isolation.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+"""test_session_isolation —— 会话隔离模型守卫（issue #35 设计定稿）
+
+设计定稿（2026-09-23 使用者拍板）：
+  · public / internal = 跨会话共享档——通过 clearance 即可见（含他人会话写入）；
+  · private / secret  = 会话绑定档——仅归属会话可见；
+    - 归属会话 = frontmatter.session（服务端身份不可伪造）；
+    - 绑定档无归属（存量）→ fail-closed 仅设计者可见；
+    - 查询侧 "*" 不再越过 private 绑定（非 admin 的 "*" 与不传等价）；
+  · can_admin（设计者）豁免——整体判断需要全景；错误/冲突信息（rejected/
+    unresolved）恒不进默认正排，设计者经显式通道获取；
+  · tenant 物理根接线（issue #35 本体）：已登记租户走登记根，冲突 fail-closed，
+    未登记回落 MDCG_ROOT（零变更）。
+
+运行：python -X utf8 -m md_cg.test_session_isolation
+"""
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from md_cg.mcp_server import _resolve_root                # noqa: E402
+from md_cg.mdcos import MdCGSecure                        # noqa: E402
+from md_cg.security import Principal, TenantRegistry      # noqa: E402
+
+passed = failed = 0
+
+
+def check(name, cond, detail=""):
+    global passed, failed
+    if cond:
+        passed += 1
+        print("  [PASS] " + name)
+    else:
+        failed += 1
+        print("  [FAIL] " + name + "  " + str(detail)[:200])
+
+
+def _principal(sess, **kw):
+    kw.setdefault("actor", "tester")
+    kw.setdefault("clearance", "private")
+    kw.setdefault("can_write", True)
+    kw.setdefault("role", "recorder")
+    return Principal(session=sess, **kw)
+
+
+def _search_ids(cg, q="共享 私有 标记", k=20, **kw):
+    res, _m = cg.search_rrf(q, k=k, judge=False, **kw)
+    return sorted(r[0]["id"] for r in res)
+
+
+def main():
+    root = tempfile.mkdtemp(prefix="sess_iso_")
+    pa = _principal("sessA")
+    a = MdCGSecure(os.path.join(root, "mem"), principal=pa)
+    a.add("pub1", "共享公开级记忆：发布窗口每周三", "knowledge",
+          sensitivity="public")
+    a.add("int1", "共享默认级记忆：接口约定时间戳毫秒", "knowledge",
+          sensitivity="internal")
+    a.add("priv1", "会话私有记忆：A 的个人偏好与口令提示", "knowledge",
+          sensitivity="private")
+    a.flush()
+
+    print("[1] 跨会话共享档：B 能看到 A 的 public/internal，看不到 private")
+    b = MdCGSecure(os.path.join(root, "mem"), principal=_principal("sessB"))
+    ids = _search_ids(b)
+    check("B（不传 session）见共享档", "pub1" in ids and "int1" in ids, ids)
+    check("B（不传 session）不见 A 的 private", "priv1" not in ids, ids)
+    check("B get(private) → None（不可见即不存在）",
+          b.get("priv1") is None)
+    check("B get(public) 可读", b.get("pub1") is not None)
+
+    print("[2] 查询侧 session 参数与收紧的 \"*\"")
+    ids2 = _search_ids(b, session="sessB")
+    check("B 传自己 session 仍见共享档（super 硬等值已上收）",
+          "pub1" in ids2 and "int1" in ids2 and "priv1" not in ids2, ids2)
+    ids3 = _search_ids(b, session="*")
+    check("B 传 \"*\" 不越过 private 绑定（收紧）", "priv1" not in ids3, ids3)
+
+    print("[3] 归属会话自身与设计者豁免")
+    a2 = MdCGSecure(os.path.join(root, "mem"), principal=_principal("sessA"))
+    ids4 = _search_ids(a2)
+    check("A（归属会话）见自己的全部三档",
+          {"pub1", "int1", "priv1"} <= set(ids4), ids4)
+    adm = MdCGSecure(os.path.join(root, "mem"),
+                     principal=_principal("sessAdmin", can_admin=True,
+                                          role="designer"))
+    ids5 = _search_ids(adm)
+    check("设计者（can_admin）跨会话见全部（含 private）",
+          {"pub1", "int1", "priv1"} <= set(ids5), ids5)
+
+    print("[4] 绑定档无归属（存量）fail-closed")
+    import json as _json
+    e = a.index["nodes"]["priv1"]
+    p = os.path.join(root, "mem", e["path"])
+    fm, content = a._read(e)
+    fm.pop("session", None)
+    a._write_node("priv1", p, fm, content)
+    a.index["nodes"]["priv1"]["session"] = None
+    a.rebuild_index()
+    b2 = MdCGSecure(os.path.join(root, "mem"), principal=_principal("sessB"))
+    check("无归属 private：普通会话不可见（fail-closed）",
+          "priv1" not in _search_ids(b2))
+    check("无归属 private：设计者可见",
+          "priv1" in _search_ids(adm))
+
+    print("[5] rejected（错误标记）不进默认正排")
+    rj = a.add_rejected("会话私有的错误假设", "守卫用", sensitivity="public")
+    a.flush()
+    check("rejected 不进任何会话的默认正排",
+          rj not in _search_ids(b2) and rj not in _search_ids(adm))
+
+    print("[6] 租户物理根解析（_resolve_root）")
+    reg_path = os.path.join(root, "_tenants.json")
+    reg = TenantRegistry(path=reg_path)
+    reg.register("tenantA", os.path.join(root, "A"))
+    reg.register("tenantB", os.path.join(root, "B"))
+
+    r, err = _resolve_root({"MDCG_ROOT": os.path.join(root, "A"),
+                            "MDCG_TENANT": "tenantA",
+                            "MDCG_TENANT_REGISTRY": reg_path})
+    check("已登记租户 + 一致 MDCG_ROOT → 登记根",
+          not err and os.path.abspath(r) == os.path.abspath(
+              os.path.join(root, "A")), (r, err))
+
+    r, err = _resolve_root({"MDCG_TENANT": "tenantB",
+                            "MDCG_TENANT_REGISTRY": reg_path})
+    check("已登记租户 + 无 MDCG_ROOT → 登记根（私库可零配置）",
+          not err and r == os.path.abspath(os.path.join(root, "B")), (r, err))
+
+    r, err = _resolve_root({"MDCG_ROOT": os.path.join(root, "A"),
+                            "MDCG_TENANT": "tenantB",
+                            "MDCG_TENANT_REGISTRY": reg_path})
+    check("登记根与 MDCG_ROOT 冲突 → fail-closed（root=None + 冲突说明）",
+          r is None and "fail-closed" in (err or ""), (r, err))
+
+    r, err = _resolve_root({"MDCG_ROOT": os.path.join(root, "X")})
+    check("未设租户 → 维持 MDCG_ROOT（零变更）",
+          not err and r == os.path.join(root, "X"), (r, err))
+
+    r, err = _resolve_root({"MDCG_ROOT": os.path.join(root, "X"),
+                            "MDCG_TENANT": "未登记租户"})
+    check("租户未登记 → 回落 MDCG_ROOT（不误伤）",
+          not err and r == os.path.join(root, "X"), (r, err))
+
+    r, err = _resolve_root({})
+    check("全空 → (None, None)（main 侧报缺 MDCG_ROOT）",
+          r is None and not err, (r, err))
+
+    print("[7] 双租户物理隔离端到端（各自根，互不可见）")
+    ta = MdCGSecure(os.path.join(root, "A"), principal=_principal("sessA"))
+    ta.add("only_a", "租户A的记忆", "knowledge", sensitivity="public")
+    ta.flush()
+    tb = MdCGSecure(os.path.join(root, "B"), principal=_principal("sessB"))
+    tb.add("only_b", "租户B的记忆", "knowledge", sensitivity="public")
+    tb.flush()
+    check("A 根检索只见 A（物理隔离）",
+          "only_a" in _search_ids(ta) and "only_b" not in _search_ids(ta))
+    check("B 根检索只见 B（物理隔离）",
+          "only_b" in _search_ids(tb) and "only_a" not in _search_ids(tb))
+
+    print(f"\nsession_isolation: {passed} 通过 / {failed} 失败")
+    return 0 if not failed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/test_snapshot_autoclose.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""索引快照自动落盘守卫（issue：add→close 永不写快照，重开付全库扫描+重放）。
+
+缺陷形态（缺陷报告实测）：flush 只 append 分片日志、compact_index 生产零
+调用、close/atexit 只 flush——「add→close」的库永远没有快照，每次重开
+_load_index 都 _scan_nodes 全库逐文件 open+frontmatter 解析（1500 池本机
+~104ms），随后无条件重放全部索引日志（在扫描基底上纯冗余）。
+
+本守卫断言（调用计数/存在性形态，非时间阈值）：
+  C1 close 落快照：add→close 后 _index.json 存在（旧代码恒不存在 → 红）；
+  C2 重开零全库扫描：close 后重开期间 _scan_nodes 调用 == 0（旧代码
+     每次重开 1 次全库扫描 → 红）；
+  C3 重开零日志重放：close 后重开期间 ShardedLog.read_all 产出条数 == 0
+     （旧代码重放全部增量日志 → 红）；
+  C4 节点集一致：close→重开后 index["nodes"] 的 id 集与关闭前一致；
+  C5 尾部写入不丢：未达 autoflush 阈值的尾部 add 在 close 后重开可见；
+  C6 快照损坏防御：_index.json 写坏后 close/compact 不产出空快照——
+     节点仍全量可见（旧 compact 拿空骨架+增量日志会写出清池快照 → 红）；
+  C7 空库不落快照：无节点时 close 不产生 _index.json（保持原行为）。
+"""
+import os
+import shutil
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import md_cg.mdcg as mdcg_mod               # noqa: E402
+from md_cg.fsutil import ShardedLog         # noqa: E402
+from md_cg.mdcos import MdCGOS              # noqa: E402
+
+PASS = 0
+FAIL = 0
+FAILS = []
+
+
+def check(name, cond, detail=""):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print(f"  OK   {name}")
+    else:
+        FAIL += 1
+        FAILS.append(name)
+        print(f"  FAIL {name}  {detail}")
+
+
+def count_reload_reads(fn):
+    """打桩 _scan_nodes 调用数与 ShardedLog.read_all 产出条数。"""
+    n_scan, n_replay = 0, 0
+    real_scan = mdcg_mod.MdCG._scan_nodes
+    real_read = ShardedLog.read_all
+
+    def _scan_spy(self):
+        nonlocal n_scan
+        n_scan += 1
+        return real_scan(self)
+
+    def _read_spy(path, *a, **kw):
+        nonlocal n_replay
+        out = list(real_read(path, *a, **kw))
+        n_replay += len(out)
+        return iter(out)
+
+    mdcg_mod.MdCG._scan_nodes = _scan_spy
+    ShardedLog.read_all = staticmethod(_read_spy)
+    mdcg_mod.ShardedLog.read_all = staticmethod(_read_spy)
+    try:
+        return fn(), n_scan, n_replay
+    finally:
+        mdcg_mod.MdCG._scan_nodes = real_scan
+        ShardedLog.read_all = real_read
+        mdcg_mod.ShardedLog.read_all = real_read
+
+
+def build(root, n=30):
+    cg = MdCGOS(root, autoflush=64)          # 高阈值：尾部写入留在 _dirty
+    for i in range(n):
+        cg.add("mem_%04d" % i,
+               "# 功能名：快照守卫 %d\n# 正文：蜂群调度 样本 %d" % (i, i),
+               layer="knowledge")
+    return cg
+
+
+def main():
+    root = tempfile.mkdtemp(prefix="mdcg_snap_guard_")
+    try:
+        # C1/C4/C5：close 落快照 + 尾部写入 + 节点集一致
+        print("== C1/C4/C5 close 落快照 ==")
+        cg = build(root)
+        ids_before = set(cg.index["nodes"])
+        check("C5pre 尾部写入在 _dirty（未 flush）", len(cg._dirty) > 0,
+              f"dirty={len(cg._dirty)}")
+        cg.close()
+        snap = os.path.join(root, "_index.json")
+        check("C1a add→close 后 _index.json 快照存在（旧代码恒不存在）",
+              os.path.exists(snap))
+
+        def _reopen():
+            return MdCGOS(root)
+
+        cg2, n_scan, n_replay = count_reload_reads(_reopen)
+        try:
+            ids_after = set(cg2.index["nodes"])
+            check("C4a 重开后节点集与关闭前一致",
+                  ids_after == ids_before and len(ids_after) == 30,
+                  f"before={len(ids_before)} after={len(ids_after)}")
+        finally:
+            cg2.close()
+        check("C2a 重开零全库扫描（_scan_nodes 调用==0，旧每次重开 1 次）",
+              n_scan == 0, f"scans={n_scan}")
+        check("C3a 重开零日志重放（read_all 条数==0，旧全量重放）",
+              n_replay == 0, f"replayed={n_replay}")
+
+        # C6 快照损坏防御：写坏快照 → 重开（scan 基底）→ close 不产空快照
+        print("== C6 快照损坏防御 ==")
+        with open(snap, "w", encoding="utf-8") as f:
+            f.write("{corrupted json !!!")
+        root6 = root                            # 同库继续
+        cg6 = MdCGOS(root6)                      # 损坏 → _scan_nodes 基底
+        n6 = len(cg6.index["nodes"])
+        check("C6a 损坏快照下重开走全库扫描（节点全量可见）",
+              n6 == 30, f"nodes={n6}")
+        cg6.close()
+        cg6b = MdCGOS(root6)
+        try:
+            n6b = len(cg6b.index["nodes"])
+            check("C6b 损坏后 close/compact 不产空快照（重开仍 30 节点）",
+                  n6b == 30, f"nodes={n6b}")
+        finally:
+            cg6b.close()
+
+        # C8 未 flush 写入兜底（issue #33 修复中发现的回归形态）：实例 A
+        # 写节点不收尾（dirty 未 flush、文件已落盘），实例 B close 落快照
+        # ——B 的账本不含 A 的节点。此后重开必须仍能看到 A 的节点
+        # （compact 计数对账 + 重开指纹校验双保险；任一缺失都会让节点
+        # 「在盘上但索引不可见」）。
+        print("== C8 未 flush 写入兜底 ==")
+        root8 = tempfile.mkdtemp(prefix="mdcg_snap_guard8_")
+        try:
+            a = MdCGOS(root8, autoflush=64)
+            a.add("a1", "# 功能名：甲\n# 正文：甲的节点 蜂群", layer="knowledge")
+            a.add("a2", "# 功能名：乙\n# 正文：乙的节点 星云", layer="knowledge")
+            b = MdCGOS(root8, autoflush=64)
+            b.add("b1", "# 功能名：丙\n# 正文：丙的节点 水位", layer="knowledge")
+            b.close()                       # B 落快照（账本不含 a1/a2）
+            c = MdCGOS(root8)
+            try:
+                ids_c = set(c.index["nodes"])
+                check("C8a A 未 flush 的节点在 B close 落快照后重开仍可见",
+                      {"a1", "a2", "b1"} <= ids_c, f"ids={sorted(ids_c)}")
+            finally:
+                c.close()
+            d = MdCGOS(root8)
+            try:
+                ids_d = set(d.index["nodes"])
+                check("C8b C close 后再次重开节点仍全量可见（快照已含全部）",
+                      {"a1", "a2", "b1"} <= ids_d, f"ids={sorted(ids_d)}")
+            finally:
+                d.close()
+        finally:
+            shutil.rmtree(root8, ignore_errors=True)
+
+        # C7 空库不落快照
+        print("== C7 空库不落快照 ==")
+        root7 = tempfile.mkdtemp(prefix="mdcg_snap_guard7_")
+        try:
+            cg7 = MdCGOS(root7)
+            cg7.close()
+            check("C7a 空库 close 不产生 _index.json（保持原行为）",
+                  not os.path.exists(os.path.join(root7, "_index.json")))
+        finally:
+            shutil.rmtree(root7, ignore_errors=True)
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+    print("\n" + "=" * 60)
+    print(f"结果：PASS {PASS} / FAIL {FAIL}")
+    if FAILS:
+        for f in FAILS:
+            print(f"  - {f}")
+    return 0 if FAIL == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/test_tail_watermark_race.py

@@ -0,0 +1,208 @@
+# -*- coding: utf-8 -*-
+"""四增量对账缓存水位守卫（缺陷：水位存 stat 时刻值，stat→read 窗口并发 append 重复并入）。
+
+缺陷形态（缺陷报告 2026-09-25 复现证实，medium）：_pid_status /
+_inbox_phash_index / _inbox_records / _decisions_records 四缓存（mdcos.py
+:1708/:1739/:1768/:1793）扫描水位存「读前 stat 的 size」，而
+fsutil.read_jsonl_tail（:228-249）seek(offset) 后**读到真实 EOF**——跨进程
+append 恰落在 stat 与 read 之间时，新记录本轮已并入但水位偏小，下一轮增量
+从旧水位重读：列表型缓存重复并入同一条记录（review_list 待审清单重复 pid、
+review_stats 计数虚高、_cascade_dedup 连写两条 reject），且进程内永不自愈
+（稳态 size 只增，不触发全量重建）。
+
+修复：read_jsonl_tail 返回 (记录列表, 真实读到的 EOF 偏移)，四处缓存把水位
+存为**实际消费位置**（含首装/回退全量路径统一走 tail(0) 取精确 EOF）；
+读后再 stat 不可取——re-stat 可能大于已消费位置，下轮会跳过未读记录（丢账）。
+
+红守卫 = 缺陷报告复现口径（monkeypatch mdcos.read_jsonl_tail / read_jsonl，
+在 stat 后、read 前注入并发 append，等价真实交错）：
+  A decisions：窗口 append 后 records 必须 == 盘上条数，且第三次调用仍相等
+    （旧代码：本轮对、下轮重读翻倍、永不自愈）；
+  B inbox：review_list 无重复 pid 且长度 == 盘上条数；
+  C _pid_status dict 覆盖免疫（proposals == 去重 pid 数，语义锁）；
+  D 首装全量路径同窗（旧代码全量重建同样把 stat size 当水位，一样翻倍）。
+运行：python -m md_cg.test_tail_watermark_race
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import tempfile
+import time
+
+from . import mdcos
+from .fsutil import append_jsonl, read_jsonl
+from .mdcos import MdCGOS
+
+PASS = FAIL = 0
+FAILS = []
+
+
+def ok(cond, label):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print(f"  OK   {label}")
+    else:
+        FAIL += 1
+        FAILS.append(label)
+        print(f"  FAIL {label}")
+
+
+class _WindowInjector:
+    """把一条 append 注入 stat→read 窗口：目标函数被调（=stat 已发生）时
+    先落盘注入记录再委托原函数——等价跨进程 append 恰落在窗口内的交错。"""
+
+    def __init__(self, mod, log_path, rec):
+        self.mod, self.path, self.rec = mod, log_path, rec
+        self.fired = False
+        self._orig_tail = mod.read_jsonl_tail
+        self._orig_full = mod.read_jsonl
+
+    def _maybe_inject(self, path):
+        if not self.fired and os.path.abspath(str(path)) == \
+                os.path.abspath(self.path):
+            self.fired = True
+            append_jsonl(self.path, self.rec)
+
+    def _tail(self, path, offset):
+        self._maybe_inject(path)
+        return self._orig_tail(path, offset)
+
+    def _full(self, path):
+        self._maybe_inject(path)
+        return self._orig_full(path)
+
+    def __enter__(self):
+        self.mod.read_jsonl_tail = self._tail
+        self.mod.read_jsonl = self._full
+        return self
+
+    def __exit__(self, *a):
+        self.mod.read_jsonl_tail = self._orig_tail
+        self.mod.read_jsonl = self._orig_full
+
+
+def _n_on_disk(path):
+    return len(list(read_jsonl(path)))
+
+
+def _dec(pid, decision="noop"):
+    return {"t": time.time(), "pid": pid, "decision": decision,
+            "status": decision, "round": 1, "actor": "race_guard"}
+
+
+def _inbox(pid):
+    return {"t": time.time(), "pid": pid, "id": "m_" + pid,
+            "content": "窗口竞态守卫正文 " + pid, "layer": "knowledge"}
+
+
+def _scenario_decisions(tmp):
+    """A：decisions 尾部窗口（review_stats 口径）。"""
+    print("== A decisions 窗口竞态（review_stats） ==")
+    root = os.path.join(tmp, "dec")
+    os.makedirs(root)
+    cg = MdCGOS(root)
+    append_jsonl(cg.decisions_log, _dec("p1"))
+    append_jsonl(cg.decisions_log, _dec("p2"))
+    st1 = cg.review_stats()
+    ok(st1["records"] == 2, f"A1 基线装载 records=2（实测 {st1['records']}）")
+
+    append_jsonl(cg.decisions_log, _dec("p3_ext"))      # stat 前并发 append
+    with _WindowInjector(mdcos, cg.decisions_log, _dec("p4_ext")):
+        st2 = cg.review_stats()                          # 读窗内并发 append
+    disk = _n_on_disk(cg.decisions_log)
+    ok(st2["records"] == disk,
+       f"A2 窗口轮 records==盘上（{st2['records']} vs 盘上 {disk}）")
+
+    st3 = cg.review_stats()
+    ok(st3["records"] == disk,
+       f"A3 下一轮不重读（records={st3['records']}，盘上 {disk}——"
+       f"旧代码重读 p4_ext 虚高为 {st3['records']}）")
+    st4 = cg.review_stats()
+    ok(st4["records"] == disk,
+       f"A4 永不自愈形态不得出现（第三次调用 records={st4['records']}，"
+       f"盘上 {disk}）")
+    disk_noop = sum(1 for r in read_jsonl(cg.decisions_log)
+                    if r.get("decision") == "noop")
+    ok(st4["by_decision"].get("noop", 0) == disk_noop,
+       f"A5 noop 计数与盘上一致（{st4['by_decision'].get('noop', 0)} vs "
+       f"{disk_noop}）")
+    # C：_pid_status 为 dict 后写覆盖——窗口竞态不得影响 pid 去重口径
+    pids_disk = {r.get("pid") for r in read_jsonl(cg.decisions_log)}
+    st5 = cg.review_stats()
+    ok(st5["proposals"] == len(pids_disk)
+       and set(cg._pid_status()) == pids_disk,
+       f"C1 proposals==盘上去重 pid 数（{st5['proposals']} vs "
+       f"{len(pids_disk)}）——dict 覆盖免疫不受影响")
+
+
+def _scenario_inbox(tmp):
+    """B：inbox 尾部窗口（review_list 待审清单）。"""
+    print("== B inbox 窗口竞态（review_list） ==")
+    root = os.path.join(tmp, "inbox")
+    os.makedirs(root)
+    cg = MdCGOS(root)
+    append_jsonl(cg.inbox_log, _inbox("q1"))
+    append_jsonl(cg.inbox_log, _inbox("q2"))
+    rl1 = cg.review_list()
+    ok(len(rl1) == 2, f"B1 基线装载待审 2（实测 {len(rl1)}）")
+
+    append_jsonl(cg.inbox_log, _inbox("q3_ext"))
+    with _WindowInjector(mdcos, cg.inbox_log, _inbox("q4_ext")):
+        rl2 = cg.review_list()
+    disk = _n_on_disk(cg.inbox_log)
+    ok(len(rl2) == disk,
+       f"B2 窗口轮待审数==盘上（{len(rl2)} vs {disk}）")
+
+    rl3 = cg.review_list()
+    pids = [r.get("pid") for r in rl3]
+    ok(len(rl3) == disk and len(set(pids)) == len(pids),
+       f"B3 下一轮无重复 pid（len={len(rl3)}，去重 {len(set(pids))}，"
+       f"盘上 {disk}——旧代码 q4_ext 重复并入）")
+    rl4 = cg.review_list()
+    pids4 = [r.get("pid") for r in rl4]
+    ok(len(rl4) == disk and len(set(pids4)) == len(pids4),
+       f"B4 第三次调用仍无重复（len={len(rl4)}，盘上 {disk}）")
+
+
+def _scenario_first_load(tmp):
+    """D：首装全量路径同窗（旧代码全量重建也把 stat size 当水位）。"""
+    print("== D 首装全量路径同窗 ==")
+    root = os.path.join(tmp, "first")
+    os.makedirs(root)
+    cg = MdCGOS(root)
+    append_jsonl(cg.decisions_log, _dec("d1"))
+    append_jsonl(cg.decisions_log, _dec("d2"))
+    with _WindowInjector(mdcos, cg.decisions_log, _dec("d3_ext")):
+        st1 = cg.review_stats()                     # 首装发生在窗口内
+    disk = _n_on_disk(cg.decisions_log)
+    ok(st1["records"] == disk,
+       f"D1 首装窗口轮 records==盘上（{st1['records']} vs {disk}）")
+    st2 = cg.review_stats()
+    ok(st2["records"] == disk,
+       f"D2 首装后下一轮不重读（records={st2['records']}，盘上 {disk}）")
+
+
+def main():
+    os.environ.pop("MDCG_READ_CACHE", None)
+    tmp = tempfile.mkdtemp(prefix="mdcg_tail_race_")
+    try:
+        _scenario_decisions(tmp)
+        _scenario_inbox(tmp)
+        _scenario_first_load(tmp)
+    finally:
+        os.environ.pop("MDCG_READ_CACHE", None)
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    print("\n" + "=" * 60)
+    print(f"结果：PASS {PASS} / FAIL {FAIL}")
+    if FAILS:
+        for f in FAILS:
+            print(f"  - {f}")
+    return 0 if FAIL == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())