@furongjun1999/dsh-memory 0.6.0 → 0.6.1

package/md_cg/fsutil.py

@@ -263,6 +263,230 @@ def read_jsonl_tail(path: str, offset: int):
 _COUNT_CACHE = {}          # abspath -> (bytes_scanned, mtime_ns, lines)
 
 
+# ---------- N225（2026-09-29）：非对象记录行的可观测记账 ----------
+#
+# 分片日志的读面必须**容忍**非对象行（`null` / `[]` / `123` / `"abc"` 都是
+# 合法 JSON，`read_jsonl` 按「JSON 合法性」收行 ⇒ 它们会进调用方的记录
+# 列表），否则排序键 `r.get("_t", 0)` 抛 AttributeError，索引装载 / compact
+# 整链断裂（实测：MdCG 构造失败、常驻服务起不来）。但**容忍 ≠ 静默**：
+# 跳过必须留下机器可读的痕迹——否则「日志里混进了坏行」与「记录本就不
+# 存在」不可区分，索引静默少几条，运维与守卫都看不见。故此处是跳过面的
+# 唯一记账点：模块级累计计数 + 有界样本 + stderr 汇总告警（每条分片一行，
+# 不逐行刷屏）。
+#
+# N225 补强（2026-09-29，深度 2 同族面）：同一记账面再收两类**dict 行内**的坏型
+# （N225 v1.0 报告 §0「已知缺口」点名的深度 2 复发面，此前不在任何断言面内）：
+#   ① 载荷坏型：分片记录 `e` 非 dict 且非 None——判据在重放面（mdcg 的两条重放
+#      路径同一实现），经 note_bad_payload_rows 记账；
+#   ② 排序键坏型：`_t` / `_s` 非数值（或 NaN）——read_all 的排序键健壮化与记账
+#      必须同时发生，经 note_bad_sortkey_rows 记账。
+# 三类**合计**进 NONOBJECT_ROW_SKIPS（这就是「同一记账面」的字面口径），各子面
+# 另留独立计数与样本，运维据此区分「行根本不是对象」/「行是对象而载荷坏了」/
+# 「行的排序键坏了」——三者排查方向不同。kind 名：非对象行 / 载荷坏型 / 排序键坏型。
+NONOBJECT_ROW_SKIPS = 0        # 累计跳过的坏记录行数（三类合计，进程内）
+NONOBJECT_ROW_SAMPLES = []     # 非对象行样本：(分片路径, 行号, JSON 类型名)
+BAD_PAYLOAD_ROW_SKIPS = 0      # 载荷坏型子面：(e 非 dict 且非 None) 条数
+BAD_PAYLOAD_ROW_SAMPLES = []   # 载荷坏型样本：(来源标签, 记录 id, 载荷类型名)
+BAD_SORTKEY_ROW_SKIPS = 0      # 排序键坏型子面：(_t/_s 非数值或 NaN) 条数
+BAD_SORTKEY_ROW_SAMPLES = []   # 排序键坏型样本：(分片路径, 行号, (t 类型名, s 类型名))
+_NONOBJECT_SAMPLE_CAP = 32     # 样本上限：记账要有界，不随坏行线性涨
+
+
+# 生效条件：skips 为 (分片路径, 行号, 值) 三元组序列且非空时，把条数累加进 NONOBJECT_ROW_SKIPS、按 _NONOBJECT_SAMPLE_CAP 上限补样本，并向 sys.stderr 写一行汇总告警（含分片名、本次条数、首条行号与类型名、累计条数）；skips 为空序列或假值时立即返回、不写任何输出。
+def note_nonobject_rows(skips):
+    """登记一批被跳过的非对象记录行 + stderr 告警（N225 可观测面）。"""
+    if not skips:
+        return
+    global NONOBJECT_ROW_SKIPS
+    NONOBJECT_ROW_SKIPS += len(skips)
+    for item in skips:
+        if len(NONOBJECT_ROW_SAMPLES) >= _NONOBJECT_SAMPLE_CAP:
+            break
+        NONOBJECT_ROW_SAMPLES.append((item[0], item[1],
+                                      type(item[2]).__name__))
+    path, lineno, value = skips[0]
+    sys.stderr.write(
+        "[fsutil] ShardedLog.read_all 跳过 %d 条非对象记录行（分片 %s，"
+        "首条 行%d 类型=%s）——坏行不进索引重放；本次后进程内累计 %d 条。"
+        "排查方向：该分片被非本协议写入方污染，或发生过截断 / 粘连。\n"
+        % (len(skips), os.path.basename(path), lineno,
+           type(value).__name__, NONOBJECT_ROW_SKIPS))
+
+
+# 生效条件：无入参，返回二元组 (累计坏行条数, 非对象行样本元组副本)——累计数为三类合计（非对象行 + 载荷坏型 + 排序键坏型），样本元素为 (分片路径, 行号, JSON 类型名) 且只含非对象行一类，副本只读、调用方改动不影响记账面。
+def nonobject_row_stats():
+    """读坏行记账合计（只读）：(累计条数, 非对象行样本元组)。
+
+    累计数是**同一记账面**的合计（三类 kind 都计入）；按 kind 的分项见
+    bad_payload_row_stats / bad_sortkey_row_stats。
+    """
+    return NONOBJECT_ROW_SKIPS, tuple(NONOBJECT_ROW_SAMPLES)
+
+
+# 生效条件：skips 为 (来源标签, 记录 id, 载荷值) 三元组序列且非空时，把 len(skips) 同时累加进 NONOBJECT_ROW_SKIPS（同一记账面）与 BAD_PAYLOAD_ROW_SKIPS（子面），按 _NONOBJECT_SAMPLE_CAP 上限补 BAD_PAYLOAD_ROW_SAMPLES（元素为 (来源标签, str(记录 id), 载荷类型名)），并向 sys.stderr 写一行载荷坏型汇总告警（含来源基名、本次条数、首条 id 与类型名、进程内累计条数）；skips 为空序列或假值时立即返回——不写输出、不动任何计数。
+def note_bad_payload_rows(skips):
+    """登记一批被跳过的**载荷坏型**记录（`e` 非 dict 且非 None）+ stderr 告警。
+
+    与 note_nonobject_rows 同一个记账面（合计进 NONOBJECT_ROW_SKIPS），但样本
+    与告警文案分开：运维据此区分「行本身不是对象」与「行是对象而载荷坏了」。
+    记录**不落进索引**由调用方（重放路径）负责，本函数只记账。计数只在这里加，
+    调用方不得另立计数器（`_count_buckets` 那条下游不做类型检查，正是靠这里
+    把坏载荷挡在 `nodes` 之外）。
+    """
+    if not skips:
+        return
+    global NONOBJECT_ROW_SKIPS, BAD_PAYLOAD_ROW_SKIPS
+    NONOBJECT_ROW_SKIPS += len(skips)
+    BAD_PAYLOAD_ROW_SKIPS += len(skips)
+    for item in skips:
+        if len(BAD_PAYLOAD_ROW_SAMPLES) >= _NONOBJECT_SAMPLE_CAP:
+            break
+        BAD_PAYLOAD_ROW_SAMPLES.append((item[0], str(item[1]),
+                                        type(item[2]).__name__))
+    source, nid, value = skips[0]
+    sys.stderr.write(
+        "[fsutil] 分片重放跳过 %d 条载荷坏型记录（e 非 dict 且非 None，来源 %s，"
+        "首条 id=%s 载荷类型=%s）——坏载荷不进索引节点；本次后进程内累计 %d 条"
+        "（含非对象行）。排查方向：该分片被按别的协议写入，或载荷被外部改写。\n"
+        % (len(skips), os.path.basename(str(source)), nid,
+           type(value).__name__, NONOBJECT_ROW_SKIPS))
+
+
+# 生效条件：无入参，返回二元组 (载荷坏型累计条数, 样本元组副本)——样本元素为 (来源标签, 记录 id, 载荷类型名)，副本只读、调用方改动不影响记账面。
+def bad_payload_row_stats():
+    """读载荷坏型子面（只读）：(累计条数, 样本元组)。"""
+    return BAD_PAYLOAD_ROW_SKIPS, tuple(BAD_PAYLOAD_ROW_SAMPLES)
+
+
+# 生效条件：skips 为 (分片路径, 行号, (t 值, s 值)) 三元组序列且非空时，把 len(skips) 同时累加进 NONOBJECT_ROW_SKIPS（同一记账面）与 BAD_SORTKEY_ROW_SKIPS（子面），按 _NONOBJECT_SAMPLE_CAP 上限补 BAD_SORTKEY_ROW_SAMPLES（元素为 (分片路径, 行号, (t 类型名, s 类型名))），并向 sys.stderr 写一行排序键坏型汇总告警（含分片基名、本次条数、首条行号与两个类型名、进程内累计条数）；skips 为空序列或假值时立即返回——不写输出、不动任何计数。
+def note_bad_sortkey_rows(skips):
+    """登记一批**排序键坏型**记录（`_t` / `_s` 非数值或 NaN）+ stderr 告警。
+
+    与 note_nonobject_rows 同一记账面。**记录本身不丢**（仍是 dict，照常回放，
+    只在排序键上按「缺键取 0」的既有口径归一）——故本函数只记账、不改记录：
+    丢掉一条合法 dict 记录是比重排它更糟的事。
+    """
+    if not skips:
+        return
+    global NONOBJECT_ROW_SKIPS, BAD_SORTKEY_ROW_SKIPS
+    NONOBJECT_ROW_SKIPS += len(skips)
+    BAD_SORTKEY_ROW_SKIPS += len(skips)
+    for item in skips:
+        if len(BAD_SORTKEY_ROW_SAMPLES) >= _NONOBJECT_SAMPLE_CAP:
+            break
+        raw = item[2]
+        BAD_SORTKEY_ROW_SAMPLES.append(
+            (item[0], item[1], (type(raw[0]).__name__, type(raw[1]).__name__)))
+    path, lineno, raw = skips[0]
+    sys.stderr.write(
+        "[fsutil] ShardedLog.read_all 排序键坏型 %d 条（分片 %s，首条 行%d "
+        "_t=%s _s=%s）——坏型槽记 0 参与排序（记录不丢）；本次后进程内累计 %d 条"
+        "（含非对象行）。排查方向：该分片被非本协议写入方污染。\n"
+        % (len(skips), os.path.basename(path), lineno,
+           type(raw[0]).__name__, type(raw[1]).__name__, NONOBJECT_ROW_SKIPS))
+
+
+# 生效条件：无入参，返回二元组 (排序键坏型累计条数, 样本元组副本)——样本元素为 (分片路径, 行号, (t 类型名, s 类型名))，副本只读、调用方改动不影响记账面。
+def bad_sortkey_row_stats():
+    """读排序键坏型子面（只读）：(累计条数, 样本元组)。"""
+    return BAD_SORTKEY_ROW_SKIPS, tuple(BAD_SORTKEY_ROW_SAMPLES)
+
+
+# 生效条件：无入参，把三类累计条数（NONOBJECT_ROW_SKIPS / BAD_PAYLOAD_ROW_SKIPS / BAD_SORTKEY_ROW_SKIPS）全置 0 并把三个样本列表原地清空（del [:]，不换对象）；守卫与运维建立观测基线时用，生产读路径不调用。
+def reset_nonobject_row_stats():
+    """清空整个坏行记账面（含两类子面；守卫 / 运维的观测基线用）。"""
+    global NONOBJECT_ROW_SKIPS, BAD_PAYLOAD_ROW_SKIPS, BAD_SORTKEY_ROW_SKIPS
+    NONOBJECT_ROW_SKIPS = 0
+    BAD_PAYLOAD_ROW_SKIPS = 0
+    BAD_SORTKEY_ROW_SKIPS = 0
+    del NONOBJECT_ROW_SAMPLES[:]
+    del BAD_PAYLOAD_ROW_SAMPLES[:]
+    del BAD_SORTKEY_ROW_SAMPLES[:]
+
+
+# ---------- C-3（FI-M02 / N134，2026-09-29）：读失败的**瞬时/终态单点判别**与记账 ----------
+#
+# 缺陷（N134，docs/eval/缺陷挖掘_自主迭代_v16.md:86）：`MdCG._read` 把 OSError
+# （含**瞬态**失败：独占句柄 / 资源剥夺）与「文件不存在 / 越界」一律归成
+# `(None, None)`，readcache 又把任何返回值——包括 `(None, None)`——一律当正常值
+# 写入缓存 ⇒ 一次瞬态 OS 失败被固化成「该节点从检索面永久消失，直到进程重启或
+# 该 path 再写盘」（cache 条目字面 `(gen, (None, None))`）；而 `cg.get` 直读不走
+# 缓存照常可读 ⇒「get 能读、search 搜不到」撕裂（P1 fail-closed 缺席 + T4 静默损伤）。
+#
+# 修法要点：**判别只此一处**——读路径在唯一捕获 OSError 的点上调用本函数拿到
+# 「瞬时 / 终态」标签，缓存层按标签决定接纳与否，**不再自行回看异常类型**
+# （否则就是判据的第二份副本；本仓 N133 与 `_ccg_line` 的教训都是「副本自称同源」）。
+#   · 终态（READ_FAIL_ABSENT）：`FileNotFoundError`——`atomic_write` 是
+#     tmp + os.replace（见 `_publish`：读者只可能看到旧值或新值，不会看到
+#     「写一半的缺文件」），故 ENOENT 是**真缺**，可照旧入缓存（不构成重读风暴）。
+#     越界（`_node_disk_path` 抛 ValueError）与「有节点但无密钥」同属终态，
+#     且不经本函数——两条既有语义逐位不变。
+#   · 瞬时（READ_FAIL_TRANSIENT）：其余 OSError——Windows 上独占句柄
+#     （WinError 32 共享冲突）、权限剥夺、同名目录顶位、磁盘瞬时故障。
+#     **判据方向是 fail-closed 的**：判不准（非 FileNotFoundError 的一切）
+#     一律归「瞬时」——宁可多读一次，不可把可读节点判死。
+#
+# ③「不得静默」：与 N225 三类坏行记账同风格——模块级累计计数 + 有界样本 +
+# stderr 汇总告警；计数面经 `transient_read_stats()` 可被守卫/运维读取。
+READ_FAIL_ABSENT = "absent"          # 终态：真缺 / 越界 / 无密钥 → 可入缓存
+READ_FAIL_TRANSIENT = "transient"    # 瞬时：可重试 → **不得**以「新鲜」身份固化
+
+TRANSIENT_READ_FAILURES = 0          # 累计瞬时读失败次数（进程内）
+TRANSIENT_READ_SAMPLES = []          # 样本：(节点 path, 异常类型名, errno)
+_TRANSIENT_READ_SAMPLE_CAP = 32      # 样本上限：记账要有界，不随失败次数线性涨
+# stderr 告警上限：热路径（全池检索每查询逐条读）防刷屏；**计数面恒完整**，
+# 上限只压告警行数，不减信息可观测性（守卫读的是计数与样本，不是 stderr）。
+_TRANSIENT_READ_WARN_CAP = 32
+
+
+# 生效条件：exc 为读节点文件时捕获的异常对象；是 FileNotFoundError（含其子类）返回 READ_FAIL_ABSENT（终态：真缺，可入缓存），否则返回 READ_FAIL_TRANSIENT（瞬时：可重试，不得入缓存）；非 OSError 入参同样按瞬时返回（判不准即保守，绝不判死节点）。
+def classify_read_failure(exc) -> str:
+    """**单点**判别：读失败是瞬时的还是终态的（唯一真源，缓存层不得再猜一遍）。
+
+    调用面恒为读路径捕获 OSError 的那一处（`MdCG._note_read_oserror`）。
+    """
+    if isinstance(exc, FileNotFoundError):
+        return READ_FAIL_ABSENT
+    return READ_FAIL_TRANSIENT
+
+
+# 生效条件：path 为节点文件路径（任意值，str() 后取基名入样本）、exc 为捕获到的异常；无条件把 TRANSIENT_READ_FAILURES 累加 1、按 _TRANSIENT_READ_SAMPLE_CAP 上限补样本，并在累计次数不超过 _TRANSIENT_READ_WARN_CAP 时向 sys.stderr 写一行汇总告警；返回是否写了告警行（bool）。
+def note_transient_read_failure(path, exc) -> bool:
+    """登记一次**瞬时读失败** + stderr 告警（C-3 可观测面，N225 同风格）。
+
+    只记账，**不改任何调用方的控制流**——读不到仍是读不到，只是不再静默。
+    """
+    global TRANSIENT_READ_FAILURES
+    TRANSIENT_READ_FAILURES += 1
+    if len(TRANSIENT_READ_SAMPLES) < _TRANSIENT_READ_SAMPLE_CAP:
+        TRANSIENT_READ_SAMPLES.append(
+            (str(path), type(exc).__name__, getattr(exc, "errno", None)))
+    if TRANSIENT_READ_FAILURES > _TRANSIENT_READ_WARN_CAP:
+        return False
+    sys.stderr.write(
+        "[fsutil] 节点读失败（瞬时，可重试）%s：%s errno=%s——本次不计入检索面，"
+        "且**不当作「不存在」固化**（C-3：负结果不入读缓存）；进程内累计 %d 次。"
+        "排查方向：独占句柄（Windows 共享冲突）/ 权限剥夺 / 同名目录顶位 / "
+        "磁盘瞬时故障。\n"
+        % (os.path.basename(str(path)), type(exc).__name__,
+           getattr(exc, "errno", None), TRANSIENT_READ_FAILURES))
+    return True
+
+
+# 生效条件：无入参，返回二元组 (累计瞬时读失败次数, 样本元组副本)——样本元素为 (节点 path, 异常类型名, errno)，副本只读、调用方改动不影响记账面。
+def transient_read_stats():
+    """读瞬时读失败记账（只读）：(累计次数, 样本元组)。"""
+    return TRANSIENT_READ_FAILURES, tuple(TRANSIENT_READ_SAMPLES)
+
+
+# 生效条件：无入参，把 TRANSIENT_READ_FAILURES 置 0 并原地清空 TRANSIENT_READ_SAMPLES（del [:]，不换对象）；守卫/运维建立观测基线时用，生产读路径不调用。
+def reset_transient_read_stats():
+    """清空瞬时读失败记账面（守卫 / 运维的观测基线用）。"""
+    global TRANSIENT_READ_FAILURES
+    TRANSIENT_READ_FAILURES = 0
+    del TRANSIENT_READ_SAMPLES[:]
+
+
 # 生效条件：os.stat(os.path.abspath(path or "")) 抛 OSError 时返回 0；缓存命中且已扫字节数与 mtime_ns 均与 stat 一致时直接返回缓存计数；若缓存已扫字节 < 当前 size 且 mtime_ns 不同则从该偏移起按 chunk 分块累计 b"\n" 个数并加上缓存值；读文件抛 OSError 时返回 total or 0（已累计值为假则返回 0）。
 def count_jsonl(path: str, chunk: int = 1 << 20) -> int:
     """数 append-only 日志的行数——**流式计数、不物化**（内存 O(1)）。
@@ -314,7 +538,157 @@ def count_jsonl(path: str, chunk: int = 1 << 20) -> int:
     return total
 
 
-# 生效条件：directory 经 abspath 后作为分片目录并 makedirs(exist_ok=True)，实例分片文件名由 os.getpid() 与 uuid.uuid4().hex[:8] 拼成 "{pid}-{hex8}.log"，append 时各写者只写自己这一分片，从而不共享写入点。
+# ---------- B4（2026-09-30）：分片目录缺失自愈（容忍 ≠ 静默；失败结构化） ----------
+#
+# 病灶：`ShardedLog` 只在 `__init__` 里建目录，`append` 首次 `open(self.path, "a")`
+# 前不复查。**长驻进程**（生产形态 `MdCGSecure(root, principal, autoflush=1)`——
+# `MdCG.flush` 每批写完全部 `close()` 分片句柄，故下次 append 必经重开）持有过
+# `ShardedLog` 实例之后目录被删（外部清理脚本 / 误删 / 备份还原），此后每次
+# append 都在 open 处抛 `FileNotFoundError [Errno 2]`，**且永不恢复**：目录三次
+# 都不重建、`close()` 抛同异常、`_index.json` 从未落成，而正文 .md 已在盘上
+# （`MdCG.add` → `_write_node` 先写盘）——索引静默落后于盘面。不自愈的必要条件
+# 是「本进程已持有 ShardedLog 实例」：`MdCG.flush` 只在该属性为 None 时建实例
+# （`mdcg.py` 内 `ShardedLog(...)` 构造点全仓唯一），全新短命进程做同一操作时
+# `__init__` 的 makedirs 生效、目录会被重建
+# （2026-09-30 沙箱实测两侧，见 `test_b4_shard_dir_selfheal.py` 头注）。
+#
+# 收口口径（本块是**唯一**实现；第二处调用点一律委托 `ensure_shard_dir`）：
+#   ① 判据 = 「分片目录不存在就重建」——`isdir` 快路径 → `makedirs(exist_ok=True)`
+#      → 失败抛结构化错误；`__init__`（首建）与 `append`（打开前）都走它。
+#   ② **容忍 ≠ 静默**（本仓 N225 已确立的判据）：重建必须可观测——模块级累计
+#      计数 + 有界样本 + stderr 汇总告警（与 `note_nonobject_rows` 同一风格：
+#      计数只在这里加，调用方不得另立计数器）。**首建不记账**（`where="init"`：
+#      建库时目录本就不存在，那是正常路径，不是「被删后自愈」的病态事件——
+#      计入会让计数面变成噪声、真事件被淹没）。
+#   ③ 重建**失败**（父只读 / 权限不足 / 有文件占着该路径）：抛 `ShardDirError`
+#      —— 可机读 `code` + 可操作 `hint`，不让裸 `FileNotFoundError` 冒到 MCP
+#      出口（出口只渲染 `f"{type(exc).__name__}: {exc}"` + `getattr(exc,
+#      "hint")`，裸异常在那里既无 code 也无 hint）。失败**同样记账 + 告警**：
+#      异常可能被上层兜底吞掉（`MdCG.close` 的 `except (OSError, ValueError)`），
+#      痕迹不得只存在于异常里。
+#   ④ `read_all` 既有语义**一字不改**：directory 不是目录 → 返回 `[]`（那是读面
+#      的降级契约，与本块写面自愈无关）。
+SHARD_DIR_REBUILDS = 0          # 累计「目录缺失→重建成功」次数（进程内）
+SHARD_DIR_REBUILD_SAMPLES = []  # 重建样本：(目录绝对路径, 调用点标签)
+SHARD_DIR_HEAL_FAILURES = 0     # 累计「目录缺失且重建失败」次数（进程内）
+SHARD_DIR_HEAL_FAILURE_SAMPLES = []   # 失败样本：(目录绝对路径, 调用点, 异常类型名)
+_SHARD_DIR_SAMPLE_CAP = 8       # 样本上限：记账有界，不随事件线性涨
+
+# 结构化失败的稳定 code（进 message 首字段 ⇒ MCP 出口的 error 串里可机读；
+# 出口不改形状，与 AccessDenied 的 hint 同口径只透 `hint`）。
+SHARD_DIR_ERR_CODE = "E_SHARD_DIR_UNREBUILDABLE"
+
+
+# 生效条件：msg 为必填字符串（经 super().__init__ 原样成为 str(e)），code / hint / path 任选（缺省 None）；构造出的是 OSError 子类实例，三者分别存入 self.code / self.hint / self.path，不校验取值、不读盘、不抛异常。
+class ShardDirError(OSError):
+    """分片目录缺失且无法重建——结构化失败（可机读 code + 可操作 hint）。
+
+    为什么继承 `OSError`（而不是 RuntimeError）：既有调用面按 `except OSError`
+    收敛 I/O 失败（`MdCG.close` 的兜底、各处 `except (OSError, ValueError)`），
+    换基类会让这些既有的降级/兜底面行为漂移；本类要补的是**信息**（code /
+    hint），不是新的异常族。`.hint` 与 `security.AccessDenied` 同口径——MCP
+    出口的 `getattr(exc, "hint")` 会把它渲染进工具错误结果。
+    """
+
+# 生效条件：msg 为必填字符串（经 super().__init__ 原样成为 str(e)），code / hint / path 任选（缺省 None）；随后把三者分别存入 self.code / self.hint / self.path，不校验取值、不读盘。
+    def __init__(self, msg: str, code: str = None, hint: str = None,
+                 path: str = None):
+        super().__init__(msg)
+        self.code = code
+        self.hint = hint
+        self.path = path
+
+
+# 生效条件：where 非 "init" 时把 SHARD_DIR_REBUILDS 累加 1、按 _SHARD_DIR_SAMPLE_CAP 上限补 (目录绝对路径, where) 样本，并向 sys.stderr 写一行含目录名/调用点/累计次数与排查方向的重建告警；where == "init" 时立即返回（首建是正常路径，不记账不告警）；stderr 写失败被吞掉（告警面不得反向破坏写路径），计数与样本不受影响。
+def note_shard_dir_rebuild(directory, where: str = "append"):
+    """登记一次分片目录重建（成功）+ stderr 告警（B4 可观测面）。"""
+    if where == "init":
+        return
+    global SHARD_DIR_REBUILDS
+    SHARD_DIR_REBUILDS += 1
+    if len(SHARD_DIR_REBUILD_SAMPLES) < _SHARD_DIR_SAMPLE_CAP:
+        SHARD_DIR_REBUILD_SAMPLES.append((os.path.abspath(directory), where))
+    try:
+        sys.stderr.write(
+            "[fsutil] ShardedLog 分片目录缺失，已重建（目录 %s，调用点 %s）——"
+            "本进程持有的分片实例不自愈；本次后进程内累计重建 %d 次。"
+            "排查方向：库根 _index_log/ 被外部清理/还原删掉，或库根被换过；"
+            "正文 .md 未受影响，索引缺口由重放/全库扫描补齐。\n"
+            % (os.path.basename(os.path.abspath(directory)), where,
+               SHARD_DIR_REBUILDS))
+    except Exception:                     # noqa: BLE001 —— 告警面不反向破坏写路径
+        pass
+
+
+# 生效条件：无条件把 SHARD_DIR_HEAL_FAILURES 累加 1、按 _SHARD_DIR_SAMPLE_CAP 上限补 (目录绝对路径, where, 异常类型名) 样本，并向 sys.stderr 写一行含失败原因类型与 hint 指向的告警；exc 为 None 时原因类型按 "NoneType" 渲染；stderr 写失败被吞掉（计数与样本不受影响），本函数不抛异常（真正的失败由调用方抛 ShardDirError）。
+def note_shard_dir_heal_failure(directory, where, exc=None):
+    """登记一次「目录缺失且重建失败」+ stderr 告警（B4 可观测面）。"""
+    global SHARD_DIR_HEAL_FAILURES
+    SHARD_DIR_HEAL_FAILURES += 1
+    if len(SHARD_DIR_HEAL_FAILURE_SAMPLES) < _SHARD_DIR_SAMPLE_CAP:
+        SHARD_DIR_HEAL_FAILURE_SAMPLES.append(
+            (os.path.abspath(directory), where,
+             type(exc).__name__ if exc is not None else "NoneType"))
+    try:
+        sys.stderr.write(
+            "[fsutil] ShardedLog 分片目录缺失且**重建失败**（目录 %s，调用点 %s，"
+            "原因 %s: %s）——抛 %s(code=%s)，不降级为裸 FileNotFoundError；"
+            "本次后进程内累计失败 %d 次。\n"
+            % (os.path.basename(os.path.abspath(directory)), where,
+               type(exc).__name__ if exc is not None else "NoneType", exc,
+               ShardDirError.__name__, SHARD_DIR_ERR_CODE,
+               SHARD_DIR_HEAL_FAILURES))
+    except Exception:                     # noqa: BLE001 —— 告警面不反向破坏写路径
+        pass
+
+
+# 生效条件：无入参，返回四元组 (重建累计次数, 重建样本元组, 失败累计次数, 失败样本元组)——样本元素分别为 (目录绝对路径, 调用点标签) 与 (目录绝对路径, 调用点标签, 异常类型名)；元组为副本，调用方改动不影响记账面。
+def shard_dir_stats():
+    """读分片目录自愈记账（只读）：(重建数, 重建样本, 失败数, 失败样本)。"""
+    return (SHARD_DIR_REBUILDS, tuple(SHARD_DIR_REBUILD_SAMPLES),
+            SHARD_DIR_HEAL_FAILURES, tuple(SHARD_DIR_HEAL_FAILURE_SAMPLES))
+
+
+# 生效条件：无入参、无返回值；把 SHARD_DIR_REBUILDS / SHARD_DIR_HEAL_FAILURES 归零并清空两个样本列表（守卫与运维读面前的重置点），只动本进程计数面、不触盘面。
+def reset_shard_dir_stats():
+    """清零分片目录自愈记账（守卫/运维用；只影响本进程计数面）。"""
+    global SHARD_DIR_REBUILDS, SHARD_DIR_HEAL_FAILURES
+    SHARD_DIR_REBUILDS = 0
+    SHARD_DIR_HEAL_FAILURES = 0
+    del SHARD_DIR_REBUILD_SAMPLES[:]
+    del SHARD_DIR_HEAL_FAILURE_SAMPLES[:]
+
+
+# 生效条件：directory 为分片目录路径时，os.path.isdir(directory) 为真立即返回 False（零动作、零记账）；为假则 os.makedirs(directory, exist_ok=True)——成功时经 note_shard_dir_rebuild 按 where 记账（"init" 不记）+ stderr 告警并返回 True；makedirs 抛 OSError（权限不足 / 有文件占着该路径 / 路径不可达）时先 note_shard_dir_heal_failure 记账 + 告警，再抛 ShardDirError（code=SHARD_DIR_ERR_CODE、message 首字段为 [code]、hint 含目录与三步处置、path=directory），cause 链（raise ... from）保留原异常；本函数是分片目录存在性的唯一实现点。
+def ensure_shard_dir(directory: str, where: str = "append") -> bool:
+    """`ShardedLog` 分片目录的**唯一**存在性保证点（B4）。
+
+    返回 True 表示本次**建了目录**（缺失→重建），False 表示目录本来就在。
+    where 只影响记账口径（"init" = `ShardedLog.__init__` 首建，正常路径不记；
+    "append" = 打开分片前的病态自愈面，记账 + 告警）。
+    """
+    if os.path.isdir(directory):
+        return False
+    try:
+        os.makedirs(directory, exist_ok=True)
+    except OSError as exc:
+        note_shard_dir_heal_failure(directory, where, exc)
+        raise ShardDirError(
+            "[%s] 分片目录不存在且重建失败：%s（底层 %s: %s）"
+            % (SHARD_DIR_ERR_CODE, directory, type(exc).__name__, exc),
+            code=SHARD_DIR_ERR_CODE,
+            hint=("分片目录 %s 不存在且无法重建（父目录不可写 / 权限不足 / 有文件"
+                  "占着该路径）。处置：①确认库根可写（Windows：去掉只读属性或"
+                  "改用有写权限的账号；POSIX：chmod/所有权）；②查是否有进程或"
+                  "杀毒软件把该目录删掉或占住；③索引日志是派生面——正文 .md 未"
+                  "受影响，修好权限后重开进程即可由重放 / 全库扫描恢复索引，"
+                  "无需重写节点。" % directory),
+            path=directory) from exc
+    note_shard_dir_rebuild(directory, where)
+    return True
+
+
+# 生效条件：directory 经 abspath 存入 self.dir 后经 ensure_shard_dir(self.dir, "init") 保证目录存在（首建不记账；失败抛 ShardDirError 而非裸 OSError），实例分片文件名由 os.getpid() 与 uuid.uuid4().hex[:8] 拼成 "{pid}-{hex8}.log"，append 时各写者只写自己这一分片，从而不共享写入点。
 class ShardedLog:
     """每写者独占一个分片的 append-only 日志——不能丢记录时用它。
 
@@ -323,20 +697,31 @@ class ShardedLog:
     代价是读取要合并 N 个分片，靠记录里的单调序号 (t, seq) 恢复全局写入顺序。
     """
 
-# 生效条件：directory 经 abspath 存入 self.dir 并 makedirs(exist_ok=True)，self.path 为 self.dir 下 "{os.getpid()}-{uuid.uuid4().hex[:8]}.log"，并置 self._seq = 0、self._fh = None。
+# 生效条件：directory 经 abspath 存入 self.dir 并经 ensure_shard_dir(self.dir, "init") 保证存在（唯一实现点；首建不记账，失败抛 ShardDirError），self.path 为 self.dir 下 "{os.getpid()}-{uuid.uuid4().hex[:8]}.log"，并置 self._seq = 0、self._fh = None。
     def __init__(self, directory: str):
         self.dir = os.path.abspath(directory)
-        os.makedirs(self.dir, exist_ok=True)
+        # B4：建目录单点收口到 ensure_shard_dir（不再各写各的 makedirs）——
+        # where="init" 是首建（正常路径，不记账）；重建失败的记账 + 告警与
+        # 结构化错误由该单点负责（原来这里是裸 OSError 直冒调用方）。
+        ensure_shard_dir(self.dir, "init")
         self.path = os.path.join(
             self.dir, f"{os.getpid()}-{uuid.uuid4().hex[:8]}.log")
         self._seq = 0
         self._fh = None
 
-# 生效条件：self._seq 先自增 1，record 被 dict(record, _t=time.time(), _s=self._seq) 复制；self._fh 为 None 时以 "a"、encoding="utf-8"、newline="\n" 打开 self.path，随后写入 json.dumps(ensure_ascii=False, separators=(",", ":")) + "\n" 并 flush。
+# 生效条件：self._seq 先自增 1，record 被 dict(record, _t=time.time(), _s=self._seq) 复制；self._fh 为 None 时先经 ensure_shard_dir(self.dir, "append") 复查并（缺失即）重建分片目录——重建成功记账 + stderr 告警、失败抛 ShardDirError——再以 "a"、encoding="utf-8"、newline="\n" 打开 self.path（路径照常，不换分片名），随后写入 json.dumps(ensure_ascii=False, separators=(",", ":")) + "\n" 并 flush。
     def append(self, record: dict):
         self._seq += 1
         record = dict(record, _t=time.time(), _s=self._seq)
         if self._fh is None:
+            # B4（2026-09-30）：**每次重开分片前**复查目录。病灶：目录在进程
+            # 存活期间被删后，原实现在这里 `open` 抛 FileNotFoundError 且此后
+            # 永不恢复（实测三连抛、目录三次都不重建、close 抛同异常）。缺失
+            # 即重建，路径照常仍是 self.path（同一分片名，只补回目录这一层）。
+            # 边界（诚实声明）：本条只在**句柄为 None 的重开点**复查——已持有
+            # 打开句柄期间目录被删不在本守卫面内（Windows 上被打开的文件无法
+            # 删除，生产写点 `MdCG.flush` 每批写完即 close ⇒ 必经此重开点）。
+            ensure_shard_dir(self.dir, "append")
             self._fh = open(self.path, "a", encoding="utf-8", newline="\n")
         self._fh.write(json.dumps(record, ensure_ascii=False,
                                   separators=(",", ":")) + "\n")
@@ -349,17 +734,78 @@ class ShardedLog:
             self._fh = None
 
     @staticmethod
-# 生效条件：directory 是目录时，按 sorted(os.listdir(directory)) 顺序对每个以 ".log" 结尾的文件调用 read_jsonl 汇总记录，再按每条记录 r.get("_t", 0)、r.get("_s", 0)（缺键取 0）排序后返回全部记录；directory 不是目录时直接返回 []。
+# 生效条件：directory 是目录时，按 sorted(os.listdir(directory)) 顺序对每个以 ".log" 结尾的文件读取汇总（单分片 PermissionError 时以 5ms×8 短重试等 Windows delete-pending 窗口过去、窗口后 FileNotFoundError 视为已被 compact 并入快照清走而跳过、重试耗尽照常 raise），逐行只收 dict 记录——非对象行（null/[]/123/"abc" 等合法 JSON）跳过并经 note_nonobject_rows 记账 + stderr 告警（不得静默）；随后按排序键 (_norm(r.get("_t", 0)), _norm(r.get("_s", 0))) 排序，其中 _norm 只把「数值（int/float，含 bool）且非 NaN」原样透传、其余槽（str/list/dict/None/NaN）一律记 0——坏型槽经 note_bad_sortkey_rows 记账 + stderr 告警（不得静默），记录本身不丢；合法记录（_t/_s 均数值，缺键按默认值 0）的排序键逐位等于旧键 (r.get("_t", 0), r.get("_s", 0))，故其相对次序与改前逐位一致；directory 不是目录时直接返回 []。
     def read_all(directory: str):
-        """按全局写入顺序回放所有分片。"""
+        """按全局写入顺序回放所有分片。
+
+        N170（2026-09-27）：并发 compact 的 delete-pending 窗口容忍。他进程
+        close→compact_index 的 ShardedLog.clear（mdcg.py:1137，锁内「先并快照
+        再删分片」）与本读方的 listdir→open 交错时，Windows 上 open 命中
+        「已 remove、名未消」的 delete-pending 态 → PermissionError [Errno 13]
+        （test_review_conformance【9】4 decide worker 同根并发实测复现：
+        worker 在 MdCGOS.__init__ 崩溃、stdout 空，父进程 json.loads("")
+        二次崩成 JSONDecodeError）。短重试等窗口过去：窗口过后文件要么可读、
+        要么已真删。已真删（FileNotFoundError）跳过是**安全**的——clear 的
+        契约是分片记录先并入快照再删（mdcg.py:1136-1137 顺序），本读方的
+        快照基底的陈旧读界与既有「他进程未 flush 写入不可见」边界同格，
+        由 _index_signature 指纹机制在下次重载收敛；重试耗尽的 PermissionError
+        照常上抛，真权限问题不掩盖。
+
+        N225（2026-09-29）：**非对象行容忍 + 可观测**。`read_jsonl` 按 JSON
+        合法性收行，`null` / `[]` / `123` / `"abc"` 都会原样产出；直接进
+        `recs` 会让下面的 `r.get("_t", 0)` 抛 AttributeError（实测：MdCG
+        构造 + compact_index 双崩）。此处逐行分流：dict 进回放列表，非对象行
+        进记账面（note_nonobject_rows → 模块级计数 + 样本 + stderr 告警）。
+        分流必须在本层做——`read_jsonl` 的通用契约（其它消费面）不在本次
+        范围，不得改。整片读成功才记账：半途重试不重复计数。
+
+        N225 补强（2026-09-29，**排序键健壮化**）：行是 dict 不等于键可排序
+        ——`_t` / `_s` 被外部写成 `"abc"` / `[]` / `null` 时，旧键
+        `(r.get("_t", 0), r.get("_s", 0))` 在 sort 里抛 TypeError
+        （`'<' not supported between instances of 'str' and 'float'`），
+        而 except 面只有 ValueError/OSError ⇒ 与 N225 原始缺陷同一条断链，
+        只是深度 2（N225 v1.0 报告 §0 已点名的缺口）。现按**单槽归一**处理：
+        数值（int/float，含 bool）原样，其余槽记 0——与「缺键取 0」同一口径，
+        不新造第二套默认值。归一化真的发生时（归一结果 ≠ 原值对）进
+        note_bad_sortkey_rows 记账（**容忍 ≠ 静默**，记录不丢）。
+        次序不变性：合法记录的排序键逐位等于旧键 ⇒ 同一稳定排序算法在同一
+        输入序列上产出同一次序，故相对次序与改前逐位一致（守卫 F2 用真实
+        分片记录与旧键 oracle 逐条对照）。
+        """
         if not os.path.isdir(directory):
             return []
+
+        # 生效条件：v 为 int/float（含 bool）且 v == v（非 NaN）时原样返回 v，其余取值（str/list/dict/None/NaN）一律返回 0——排序键单槽归一，NaN 必须排除（`nan == nan` 为假、与任何数比较恒假：它不抛但让次序不确定）。
+        def _norm(v):
+            return v if (isinstance(v, (int, float)) and v == v) else 0
+
         recs = []
         for fn in sorted(os.listdir(directory)):
             if not fn.endswith(".log"):
                 continue
-            recs.extend(read_jsonl(os.path.join(directory, fn)))
-        recs.sort(key=lambda r: (r.get("_t", 0), r.get("_s", 0)))
+            p = os.path.join(directory, fn)
+            for _attempt in range(8):
+                try:
+                    batch, skips, badkeys = [], [], []
+                    for lineno, rec in enumerate(read_jsonl(p), 1):
+                        if not isinstance(rec, dict):
+                            skips.append((p, lineno, rec))
+                            continue
+                        batch.append(rec)
+                        raw = (rec.get("_t", 0), rec.get("_s", 0))
+                        if (_norm(raw[0]), _norm(raw[1])) != raw:
+                            badkeys.append((p, lineno, raw))
+                    recs.extend(batch)
+                    note_nonobject_rows(skips)
+                    note_bad_sortkey_rows(badkeys)
+                    break
+                except FileNotFoundError:
+                    break          # 已被 compact 清走（记录已并入快照）
+                except PermissionError:
+                    if _attempt == 7:
+                        raise
+                    time.sleep(0.005)
+        recs.sort(key=lambda r: (_norm(r.get("_t", 0)), _norm(r.get("_s", 0))))
         return recs
 
     @staticmethod

package/md_cg/identity.py

@@ -277,7 +277,7 @@ def infer_position(cg, subject_id):
     tag = f"subject:{subject_id}"
     nodes = cg.index.get("nodes") or {}
     votes, n = {}, 0
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         tg = set(e.get("tags") or [])
         if tag not in tg or (tg & {TAG_ANCHOR, TAG_TRAIT}):
             continue
@@ -313,7 +313,7 @@ def profile(cg, subject_id):
     tag = f"subject:{subject_id}"
     nodes = cg.index.get("nodes") or {}
     anchors, traits = [], []
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         tg = set(e.get("tags") or [])
         if tag not in tg:
             continue
@@ -342,7 +342,7 @@ def positions(cg, limit=0):
     """所有主体的位置效应分布（OS 视角：谁在记录/反思/验证/输出/维生）。"""
     nodes = cg.index.get("nodes") or {}
     counts = {}
-    for _nid_, e in nodes.items():
+    for _nid_, e in list(nodes.items()):
         for t in (e.get("tags") or []):
             if isinstance(t, str) and t.startswith("subject:"):
                 sid = t[len("subject:"):]

package/md_cg/insight.py

@@ -29,6 +29,7 @@ import math
 import os
 import time
 
+from . import protect
 from .fsutil import append_jsonl
 
 INSIGHT_LOG = "_insight.jsonl"
@@ -78,7 +79,7 @@ def _append(cg, rec):
 def _events(cg):
     """全部洞见事件节点 id（按 index 层标签粗筛，避免全量读盘）。"""
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
-    return [nid for nid, e in nodes.items()
+    return [nid for nid, e in list(nodes.items())
             if TAG_EVENT in ((e or {}).get("tags") or [])]
 
 
@@ -232,7 +233,7 @@ def _normalize_evidence(evidence=None, v_types=None):
     return out
 
 
-# 生效条件：_read_event(cg,node_id) 取不到事件节点、或 verdict 经 str(verdict or "").strip().lower() 后非空且不是 verified/falsified 时抛 ValueError；verdict 为 None 或空白时按 v3 → v2 → v1 条数 ≥ V1_MIN_EVIDENCE 的顺序定 verified，有证据但不达门槛或无证据则保持 STATE_PENDING 并附 reason；显式 verdict 直接采信，verified 分支重要度保底 IMPORTANCE_FLOOR 并置保护位，falsified 分支打 TAG_FALSIFIED。
+# 生效条件：_read_event(cg,node_id) 取不到事件节点、或 verdict 经 str(verdict or "").strip().lower() 后非空且不是 verified/falsified 时抛 ValueError；verdict 为 None 或空白时按 v3 → v2 → v1 条数 ≥ V1_MIN_EVIDENCE 的顺序定 verified，有证据但不达门槛或无证据则保持 STATE_PENDING 并附 reason；显式 verdict 直接采信，verified 分支重要度保底 IMPORTANCE_FLOOR 并置保护位，falsified 分支打 TAG_FALSIFIED；裁决分支落盘前经 protect.guard_overwrite（层闸 + 保护闸），写盘后同步内存索引条目并**标脏**（cg._dirty[node_id]=ent，推进读缓存代际与索引增量日志）。
 def verify(cg, node_id=None, evidence=None, v_types=None, verdict=None,
            actor=None, note=""):
     """用 V1/V2/V3 外部证据裁决洞见事件。
@@ -243,6 +244,9 @@ def verify(cg, node_id=None, evidence=None, v_types=None, verdict=None,
       · V1 可检索/被引用 需 **≥ V1_MIN_EVIDENCE 条** 才成立；
       · 其余（无证据 / V1 不足）→ **保持 pending 并给出原因**，不判定。
     verified 后：重要度保底 0.9（``IMPORTANCE_FLOOR``）并置保护位。
+    裁决分支落盘前过 ``protect.guard_overwrite``（层闸 + 保护闸），写盘后同步
+    内存索引条目并**标脏**（``cg._dirty[node_id]``，C-1）——否则读缓存默认开时
+    同进程「verify 后读」拿旧 insight_state/tags/importance。
     """
     node = _read_event(cg, node_id)
     if not node:
@@ -294,6 +298,14 @@ def verify(cg, node_id=None, evidence=None, v_types=None, verdict=None,
     else:
         tg.append(TAG_FALSIFIED)
     fm["tags"] = tg
+    # N197（2026-09-28）：本面是**既有节点的覆写**——原先直调 `cg._write_node`，
+    # 既无 `principal.require_layer_write` 亦无 `protect.guard_write`，与同一身份
+    # 对同层 `add` 的待遇相反（add 被 AccessDenied，这里照样落盘）：越层腿
+    # （sustain layers=('self',) verify 他人的 contextual 事件）+ 保护腿
+    # （self/anchor/immutable 节点被无痕覆写、无快照无审计）都由这一处补闸收口。
+    # 层与敏感度取**本节点已读到的 frontmatter 真值**（不靠索引缺字段时的回落）。
+    protect.guard_overwrite(cg, node_id, layer=fm.get("layer"),
+                            sensitivity=fm.get("sensitivity"), actor=actor)
     cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
                    node.get("content") or "")
     ent = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
@@ -301,6 +313,15 @@ def verify(cg, node_id=None, evidence=None, v_types=None, verdict=None,
         ent["importance"] = fm.get("importance")
         ent["tags"] = list(tg)
         ent["insight_state"] = final
+        # 标脏（N133 修复，对照先例 md_cg/mdcg.py 的 update_tags / verify 直写
+        # 分支 `self._dirty[node_id] = e`）：只改内存 entry 时读缓存（默认开）
+        # 的 path_gen 不推进 ⇒ `_fresh` 继续判旧 fm 新鲜，同进程「verify 后读」
+        # 拿到旧 insight_state/tags/importance；标脏同时让本写进
+        # `_dirty → flush → _index_log` 重放。**不下沉进 `_write_node`**（该口
+        # 另有「只对账索引不落盘」的调用方，下沉会凭空产生写入代际与自重载）。
+        _dirty = getattr(cg, "_dirty", None)
+        if isinstance(_dirty, dict):
+            _dirty[node_id] = ent
     _append(cg, {"action": "verify", "node_id": node_id, "state": final,
                  "decided": True, "reason": reason or "显式裁决",
                  "evidence": ev, "importance": fm.get("importance"),
@@ -417,7 +438,7 @@ def outlook(cg, window_days=None, sample_limit=8, recent_days=7, now=None):
     imps, protected, no_neg, recent = [], 0, 0, 0
     lo_recent = now - float(recent_days) * 86400.0
     hi_imp_unprotected = []
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         e = e or {}
         layers[_layer_of(e)] = layers.get(_layer_of(e), 0) + 1
         b = str(e.get("verification_basis") or "unset")

package/md_cg/linkref.py

@@ -131,7 +131,7 @@ def known_ids(cg):
     if not callable(guard):
         return set(nodes)               # 非安全库（MdCG）无读隔离概念
     out = set()
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         try:
             if guard(e):
                 out.add(nid)