@furongjun1999/dsh-memory 0.7.0 → 0.7.2

package/md_cg/mdcg.py

@@ -1451,6 +1451,12 @@ class MdCG:
         # （自身写入已由 _stage 落进内存索引，计入签名会让每次自身 flush 都被
         # 判成「他进程变化」→ 自身写入触发全量自重载）。flush() 里登记。
         self._own_shard = None
+        # 第 3 层结构索引（设计稿 §3.2）：装载期内存倒排，**首次 stg 访问时**才构建
+        # （惰性）；写路径经 `_set_index_entry`/`_remove_index_entry` 同钩增量维护，
+        # 整体换索引的路径（重载/compact/rebuild）经 `_invalidate_stg_index` 失效后
+        # 由下次访问重建。占用面：1.7 万节点 ≈ 三张小表 + 位序/分类两表（内存派生，
+        # 不改磁盘格式）。
+        self._stg_index = None
         self.index = self._load_index()
         # P1b-2（2026-09-26，DSH 在役复验）：索引只在本行装载一次，此后
         # read/get/search 全走内存态——其它进程（review_cli autoflush=1）
@@ -1671,6 +1677,10 @@ class MdCG:
         self._dirty_replay_superseded = superseded
         idx["buckets"] = self._count_buckets(idx["nodes"])
         self.index = idx
+        # 第 3 层结构索引随整体换索引一并失效：重载取回的是**另一份**快照
+        # （他进程写的新记录/新盘面），旧表按身份判代际必然不符——显式丢表，
+        # 下次 stg 访问按新快照重建（惰性失效重建，与 rebuild/compact 同路）。
+        self._invalidate_stg_index()
         self._index_sig = sig
         # 旧索引代里的派生缓存一并失效：query 结果缓存（hotcache，默认关）
         # 缓存的是旧候选池上的结果；解析读缓存（readcache，默认开）按 path
@@ -1785,13 +1795,20 @@ class MdCG:
             atomic_write(self.index_path, json.dumps(idx, ensure_ascii=False))
             ShardedLog.clear(self.index_log_dir)
         self.index = idx
+        # 第 3 层结构索引随快照替换失效（快照重建过，旧表与它的划分关系不再
+        # 有据可依）：下次 stg 访问重建；不在此处立即重算——compact 是收尾路
+        # 径，重建成本挪到真正需要索引的那次读（惰性失效重建，同一选）。
+        self._invalidate_stg_index()
         # P1b-2：自己写了快照 → 主动刷新签名，防止后续读路径把自己的
         # compact 误判为「他进程写入」而做一次无谓重载（自写自载循环）。
         self._index_sig = self._index_signature()
         return idx
 
-# 生效条件：self._dirty 非空时才在 FileLock(index_path) 下（必要时新建 ShardedLog）逐条 append、清空 _dirty 并关闭分片句柄；self._dirty 为空时立即返回、不写任何记录；
+# 生效条件：self._dirty 非空时才在 FileLock(index_path) 下（必要时新建 ShardedLog）逐条 append、清空 _dirty 并关闭分片句柄；self._dirty 为空时立即返回、不写任何记录；**不动 self.index、不失效第 3 层结构索引**——flush 只落索引派生物（分片日志），内存快照与其划分表本就不变（「flush 后表与快照一致」由守卫钉住）；
     def flush(self):
+        # 第 3 层结构索引（stgidx）：flush **不失效**——它不改内存索引（记录早在
+        # `_stage` 时就已同钩进表），若每次 flush 都丢表，惰性重建会在写读交替
+        # 负载下每轮重扫（与 readcache「写谁失效谁」同款纪律）。
         if not self._dirty:
             return
         # 世代/互斥防线（批次9，M3.3 落地）：append 必须与 compact/rebuild 的
@@ -1843,7 +1860,7 @@ class MdCG:
             self._log.close()
             self._log = None
 
-# 生效条件：以节点文件绝对路径 p、其所在层目录名 layer、解析出的 fm 与 content 为入参，构造含 path（相对 root 正斜杠）/layer（fm 回落 layer）/role/content_kind/session/tags/bucket（父目录名，等于层名时 None）/bucket_zh/importance/created_at/verification_basis/has_neg_conditions/content_hash/temporal/spatial/time_window/lifecycle 与 trust 状态字段/branch_id/branched_from/evidence_count/big_domain/observation_position/subgraph/edges/protected/protection_reason/immutable/self_state/derived_from/derived_relation 各键的条目，经 _strip_empty_gate_fields 清洗后返回；
+# 生效条件：以节点文件绝对路径 p、其所在层目录名 layer、解析出的 fm 与 content 为入参，构造含 path（相对 root 正斜杠）/layer（fm 回落 layer）/role/content_kind/session/tags/bucket（父目录名，等于层名时 None）/bucket_zh/importance/importance_source（issue50-d：fm 键缺省 None）/created_at/verification_basis/has_neg_conditions/content_hash/temporal/spatial/time_window/lifecycle 与 trust 状态字段/branch_id/branched_from/evidence_count/big_domain/observation_position/subgraph/edges/protected/protection_reason/immutable/self_state/derived_from/derived_relation 各键的条目，经 _strip_empty_gate_fields 清洗后返回；
     def _node_entry(self, p, layer, fm, content):
         """单节点索引条目——_scan_nodes 与定向 upsert 共用的**唯一真源**。
 
@@ -1875,6 +1892,10 @@ class MdCG:
             # S1b 跨语言收敛免读文件可判。
             "bucket_zh": fm.get("bucket_zh") or None,
             "importance": fm.get("importance", 0.5),
+            # issue50-d（2026-10-02）：重要度**来源**入快照（"hint"|"heuristic"，
+            # 旧库无此键 → None）——「这条 0.8 是显式声明还是启发式分」免读
+            # 文件可判（与既有扁平键同理由：检索期/审计期不读盘）。
+            "importance_source": fm.get("importance_source"),
             "created_at": fm.get("created_at", 0),
             "verification_basis": fm.get("verification_basis"),
             "has_neg_conditions": nodefile.has_non_applicable(content),
@@ -1979,6 +2000,10 @@ class MdCG:
             atomic_write(self.index_path, json.dumps(idx, ensure_ascii=False))
             ShardedLog.clear(self.index_log_dir)
         self.index = idx
+        # 第 3 层结构索引随全量重建失效（新快照 = 新盘面语义）：下次 stg 访问
+        # 重建——重建后的划分不变量由守卫钉住（写/删/rebuild/compact 后三表与
+        # 快照一致）。
+        self._invalidate_stg_index()
         # P1b-2：rebuild 同 compact——写完快照即刷新签名（自写不自载）。
         self._index_sig = self._index_signature()
         # broad=True：rebuild 以盘面扫描为准——ccgc/crosscheck/backfill 等
@@ -2046,7 +2071,8 @@ class MdCG:
             derived_from=None, relation: str = provenance.DEFAULT_RELATION,
             semantic: str = None, depends_on=None, valid_from=None,
             valid_until=None, effective_from=None, effective_until=None,
-            believed_at=None, verification_state: str = None, **extra) -> str:
+            believed_at=None, verification_state: str = None,
+            importance_source: str = None, **extra) -> str:
         """写入一个节点。
 
         verification_basis: 外部验证基底（白箱信任的硬门槛），
@@ -2236,6 +2262,11 @@ class MdCG:
             "evidence_count": 0, "positive_evidence": 0, "negative_evidence": 0,
         }
         fm.update(extra)
+        # issue50-d（2026-10-02）：重要度**来源**声明（"hint"|"heuristic"）落
+        # frontmatter——下游免读文件即可判「这条 0.8 是显式声明还是闸门启发式
+        # 分」。缺省 None 不落键（既有调用方 fm 形态逐位不变，零回归）。
+        if importance_source:
+            fm["importance_source"] = importance_source
         if bucket_zh:
             fm["bucket_zh"] = bucket_zh
         # S1 大域先验：写入时固化「内容 → 大域」（契约 §3 S1）。
@@ -2435,8 +2466,14 @@ class MdCG:
             fm["derived_from"] = parents
             fm["derived_relation"] = derived_rel
         # 重要性 ≥0.7 自动打保护标记（对齐 tool_table：≥0.7 触发不可遗忘保护）
+        # issue50-d（2026-10-02）：自动保护只认**显式声明**——调用方随 add
+        # 下传 importance_source 时，"heuristic"（闸门启发式分）过线**只落分、
+        # 不打位**（remember_gated 的裁决面文案已如实说「未落保护」）；
+        # importance_source 缺省 None（add 的全部既有调用方都不传）⇒ 本条件
+        # 恒真、既有行为逐位不变，零回归由构造保证。
         if (float(importance or 0.0) >= protect.AUTO_PROTECT_IMPORTANCE
-                and not fm.get("protected")):
+                and not fm.get("protected")
+                and importance_source != "heuristic"):
             fm["protected"] = True
             fm["protection_reason"] = (f"importance={float(importance):.2f}"
                                        f"≥{protect.AUTO_PROTECT_IMPORTANCE}")
@@ -2459,20 +2496,20 @@ class MdCG:
                     os.remove(_old_real)
             except OSError:
                 pass  # 删除失败不阻断主写路径（残留双文件退回旧行为，可重建兜底）
-            # 旧桶计数递减（与 _unstage 同口径），否则 buckets 计数漂移；
-            # 仅在桶变化时做——同桶覆写的 _stage 自增是既有口径，不在此对账。
-            _ob = prev_entry.get("bucket")
-            if _ob and _ob != bucket:
-                _left = self.index["buckets"].get(_ob, 1) - 1
-                if _left > 0:
-                    self.index["buckets"][_ob] = _left
-                else:
-                    self.index["buckets"].pop(_ob, None)
+            # 旧桶计数递减由 `_set_index_entry` 单点接管（issue #53-B）：本处
+            # 原先手写一份「仅桶变化时撤旧」——并有一句注释把「同桶覆写的
+            # _stage 自增」当成既有口径，而实测那正是计数虚高的病灶（覆写一次
+            # counts +1，{'orphan': 1} → 2）。撤旧/加新统一在单点按**归属
+            # 变化**判定；若此处再手写一份，换桶覆写会被撤两次、同桶覆写
+            # 仍虚高，两处口径必然分叉。本处不再动计数。
         self._stage(node_id, _strip_empty_gate_fields({
             "path": os.path.relpath(path, self.root).replace("\\", "/"),
             "layer": layer, "tags": tags, "bucket": bucket,
             "bucket_zh": bucket_zh or None,
             "importance": importance, "created_at": fm["created_at"],
+            # issue50-d：重要度来源入快照（与 _node_entry 同口径——写入后即可
+            # 免读文件判「0.8 是显式 hint 还是启发式」，不等全量重建）。
+            "importance_source": fm.get("importance_source"),
             "verification_basis": verification_basis,
             "has_neg_conditions": nodefile.has_non_applicable(sealed),
             # P2-1 / P4-2①：与 `_node_entry`（重建路径）**同口径**——写路径的
@@ -2973,17 +3010,71 @@ class MdCG:
             atomic_write(self.recent_log, "")
         return len(recs)
 
-# 生效条件：无条件把 entry 写入 _dirty[node_id] 与 index["nodes"][node_id]；entry.get("bucket") 为真值时该桶计数 +1；当 len(self._dirty) >= self.autoflush 时调 flush()（autoflush 为 0 时每次标脏都立即 flush）；
+# 生效条件：无条件把 entry 记进 _dirty[node_id] 并经 _set_index_entry 写进 index["nodes"][node_id]（桶计数与 stg 结构索引同钩，见该函数）；当 len(self._dirty) >= self.autoflush 时调 flush()（autoflush 为 0 时每次标脏都立即 flush）；
     def _stage(self, node_id, entry):
         self._dirty[node_id] = entry
-        self.index["nodes"][node_id] = entry
-        if entry.get("bucket"):
-            self.index["buckets"][entry["bucket"]] = \
-                self.index["buckets"].get(entry["bucket"], 0) + 1
+        self._set_index_entry(node_id, entry)
         if len(self._dirty) >= self.autoflush:
             self.flush()
 
-# 生效条件：无条件 pop index["nodes"][node_id]（不存在则无操作）；被 pop 的条目有真值 bucket 时该桶计数 -1，减后 <=0 则删除该桶键；随后无论是否命中都把 _dirty[node_id] 置 None（删除 tombstone）并立即调 flush() 持久化；
+# 生效条件：无条件把 entry 写入 index["nodes"][node_id]（同键覆写 = dict 原地更新，物理位序不变）；桶计数只在该 id 的桶归属**变化**时调整（经 _bucket_shift 撤旧加新，同归属零动作）；self._stg_index 非 None（第 3 层结构索引已构建）时同钩增量增/改该 id，为 None（未构建/已失效）时**不构建**——首次 stg 访问才构建，写路径零额外成本；返回 None。
+    def _set_index_entry(self, node_id, entry):
+        """索引条目写入的**单点**（桶计数 + stg 结构索引同钩）。
+
+        「同钩」是设计稿 §3.2 的字面要求：写路径的增量维护若与桶计数分家，
+        两处口径必然漂开（本仓既有教训：同一判据写两份 = 迟早各漏一次）。
+        无效化（rebuild/compact/重载）后 `_stg_index` 为 None ⇒ 这里退化为
+        无操作，读侧「首次需要时构建」的惰性路径接管。
+
+        issue #53-B：同 id 再装入（add 覆写 / backfill 等 _stage）此前对 entry
+        的桶**无条件 +1**——旧条目的计数从不撤下，覆写一次即虚高 1（实测
+        {'orphan': 1} → 覆写后 {'orphan': 2}），health 分桶读数随之失真。
+        改为「归属变化才动计数」：撤旧、加新，同桶覆写零动作。
+        """
+        _old = self.index["nodes"].get(node_id)
+        self.index["nodes"][node_id] = entry
+        _ob = _old.get("bucket") if _old is not None else None
+        _nb = entry.get("bucket")
+        if _ob != _nb:
+            self._bucket_shift(_ob, -1)
+            self._bucket_shift(_nb, +1)
+        ix = getattr(self, "_stg_index", None)
+        if ix is not None:
+            ix.add(node_id, entry)
+
+# 生效条件：无条件 pop index["nodes"][node_id]（不存在则无操作）；被 pop 的条目经 _bucket_shift 撤其桶一票；self._stg_index 非 None 时同钩摘除该 id（未构建即不动）；返回被摘除的条目（不存在返回 None）。
+    def _remove_index_entry(self, node_id):
+        """索引条目摘除的**单点**（与 `_set_index_entry` 对称：桶计数 + 结构索引同钩）。"""
+        e = self.index["nodes"].pop(node_id, None)
+        if e:
+            self._bucket_shift(e.get("bucket"), -1)
+        ix = getattr(self, "_stg_index", None)
+        if ix is not None:
+            ix.remove(node_id)
+        return e
+
+# 生效条件：bucket 为假值时直接返回；否则 index["buckets"][bucket] 计数 +delta，结果 >0 时写回、<=0 时删除该键；无返回值。
+    def _bucket_shift(self, bucket, delta):
+        """桶计数 ±1 的**唯一实现**（归零删键）——issue #53-B 的单点收口。
+
+        此前 `_set_index_entry` 只加不减、`_remove_index_entry` 与 `add()` 内
+        各手写一份递减——同一判据三份实现，旧条目归属变化时三处口径必然分叉
+        （本仓既有教训：「同一判据写两份 = 迟早各漏一次」）。
+        """
+        if not bucket:
+            return
+        left = self.index["buckets"].get(bucket, 0) + delta
+        if left > 0:
+            self.index["buckets"][bucket] = left
+        else:
+            self.index["buckets"].pop(bucket, None)
+
+# 生效条件：恒把 self._stg_index 置 None（丢弃已构建的第 3 层结构索引）——凡**整体替换 self.index** 的路径（重载/compact/rebuild）调它：表按身份判代际（`StgIndex.index_obj is self.index`），显式失效让下次 stg 访问重新按新快照构建（惰性失效重建，设计稿 §3.2 二选一之选）；恒返回 None、不抛。
+    def _invalidate_stg_index(self):
+        """第 3 层结构索引的失效单点（整体换索引的三处编排点都调它）。"""
+        self._stg_index = None
+
+# 生效条件：先经 _remove_index_entry 摘除 index["nodes"][node_id]（桶计数与 stg 结构索引同钩），随后无论是否命中都把 _dirty[node_id] 置 None（删除 tombstone）并立即调 flush() 持久化；
     def _unstage(self, node_id):
         """摘除索引条目并**持久化**——与 `_stage` 对称的删除原语。
 
@@ -2993,14 +3084,7 @@ class MdCG:
         幽灵条目的代价：检索白跑候选、`ref action=prune` 因 `cg.get` 取不回
         而够不着它，`check` 的 dangling 永不归零（本机实测累积数百条）。
         """
-        e = self.index["nodes"].pop(node_id, None)
-        if e and e.get("bucket"):
-            b = e["bucket"]
-            left = self.index["buckets"].get(b, 0) - 1
-            if left > 0:
-                self.index["buckets"][b] = left
-            else:
-                self.index["buckets"].pop(b, None)
+        self._remove_index_entry(node_id)
         self._dirty[node_id] = None      # None = 删除记录，随 flush 落分片日志
         self.flush()                     # 删除不可延迟到 autoflush 阈值
 
@@ -3031,6 +3115,17 @@ class MdCG:
             node_id, fm.get("sensitivity"), declared_sensitivity, sealed,
             has_sealer=(type(self)._seal_content is not MdCG._seal_content))
         atomic_write(path, nodefile.dumps(fm, sealed), durable=durable)
+        # issue #53-C：写盘口同步索引内容指纹——「所有写盘点都应走这里」的
+        # 同一收口面延伸。元数据更新族写点（update_tags / append_edge /
+        # append_subgraph_node / set_edge_condition / backfill_* …）走
+        # 「get() 解密 → 本方法重封」时密文每次变化（AEAD 随机 nonce），
+        # 而它们只同步自己关心的索引键——本键若不在此收口，索引 hash 会停在
+        # **旧密文**上 ⇒ 启动对账每次报 hash_drift 假阳性（实测可经 compact
+        # 快照与进程重开持久存活，直到某次全量重建；报告 issue #53-C）。
+        # 新节点首次写入时条目尚未装入（_stage 紧随其后，值同源）→ 取不到即跳过。
+        _entry = self.index["nodes"].get(node_id)
+        if _entry is not None:
+            _entry["content_hash"] = nodefile.content_hash(sealed)
         return sealed
 
     # ---------- S1 前置元数据：域标签回填 ----------
@@ -3045,7 +3140,8 @@ class MdCG:
         走 `get()`（解密）→ `_write_node()`（重新封装），保证加密库不会双重封装。
         """
         st = {"seen": 0, "already": 0, "written": 0, "no_signal": 0,
-              "unreadable": 0, "index_synced": 0, "dry_run": bool(dry_run)}
+              "unreadable": 0, "ciphertext": 0, "index_synced": 0,
+              "dry_run": bool(dry_run)}
         # 前置：功能未开启时**不做任何写入**——域标签是 S1 的元数据，默认口径不得被改变：
         # 否则「回填写索引」会与「_scan_nodes 默认关剥键」冲突，写/重建两条路口径不一致。
         if os.environ.get("MDCG_RETRIEVAL_PIPELINE") != "1":
@@ -3075,6 +3171,17 @@ class MdCG:
             if content is None:
                 st["unreadable"] += 1
                 continue
+            from . import crypto
+            if crypto.is_encrypted(content):
+                # issue #53-A：密文不可分类——无密钥实例（backfill CLI 以基类
+                # MdCG 打开库）的 get() 把密文**原样**交出，base64 噪声会碰巧
+                # 命中大域词表（实测唯一命中＝「经济」：词表唯一拉丁词 GDP 被
+                # 三连子串撞上），假标签再被 already 分支永久固化。此处**单列
+                # 计数**并跳过（不与 no_signal 叠加：各计数是互斥分区）；
+                # classify_text 单点也已同源设防（双层：此层给可观测计数，
+                # 单点层保证任何调用方都不会误分类密文）。
+                st["ciphertext"] += 1
+                continue
             try:
                 dom = routing.classify_text(content)
             except Exception:
@@ -3159,6 +3266,8 @@ class MdCG:
         try:
             with open(p, encoding="utf-8") as f:
                 fm, content = nodefile.loads(f.read())
+        except UnicodeDecodeError:
+            return None
         except OSError as exc:
             # C-3（FI-M02 / N134）：瞬时读失败**不得静默**——记账（真缺不记）。
             # 返回值语义不变（None = 不可读），本方法不入任何缓存，本处无负缓存
@@ -3199,6 +3308,8 @@ class MdCG:
         try:
             with open(p, encoding="utf-8") as f:
                 return nodefile.loads(f.read()) + (None,)
+        except UnicodeDecodeError:
+            return None, None, None
         except OSError as exc:
             if self._note_read_oserror(p, exc):
                 return None, None, fsutil.READ_FAIL_TRANSIENT
@@ -3611,7 +3722,7 @@ class MdCG:
                 try:
                     with open(full_path, encoding="utf-8") as f:
                         fm, content = nodefile.loads(f.read())
-                except OSError:
+                except (OSError, UnicodeDecodeError):
                     continue
                 if any(t in content for t in terms):
                     neg_coverage.append(e)
@@ -4664,15 +4775,29 @@ class MdCG:
         h = routing.bucket_health(self.index.get("buckets", {}),
                                   total_nodes=len(self.index["nodes"]))
         h["total_nodes"] = len(self.index["nodes"])
+        # issue #53-B③：分桶读数的**覆盖范围自述**——分桶物理上只存在于
+        # BUCKETED_LAYERS（只 knowledge），非分桶层节点不进 buckets 计数。
+        # 此前读数不带范围，报告方把「nodes=4 / total_nodes=505」读成
+        # 「统计建立在个位数样本上」（实为「knowledge 层 4 个带桶条目」）
+        # ——加一行的成本买断这个歧义。
+        h["bucket_scope"] = list(BUCKETED_LAYERS)
         # 5 要素完整度（全节点扫一遍，可能慢但只在 health() 调用）
         layer_stats = {}
         neg_stats = {}
+        # PR #54 的跳过是**静默**的：被跳过的节点不进 layer_stats，读数对
+        # 「少算了几个」无自述（跳过与不存在在统计上同形）。加显式计数：
+        # 纯增量、与既有键无冲突，与 bucket_scope 同构的扩键流程。
+        # skipped_unreadable=0 ⇔ 索引内每个节点本进程都读盘成功。
+        skipped_unreadable = 0
         for e in list(self.index["nodes"].values()):
             full_path = self._node_disk_path(e)
             try:
                 with open(full_path, encoding="utf-8") as f:
                     fm, content = nodefile.loads(f.read())
-            except OSError:
+            except (OSError, UnicodeDecodeError):
+                # 与索引重建同口径：损坏的非 UTF-8 节点不应让健康端点
+                # 整体崩溃；跳过该节点，保留其余盘面读数。
+                skipped_unreadable += 1
                 continue
             cpl = nodefile.ccg_completeness(content)
             layer = e["layer"]
@@ -4693,4 +4818,5 @@ class MdCG:
                 neg_stats[layer] += 1
         h["ccg_by_layer"] = layer_stats
         h["neg_memory_counts"] = neg_stats
-        return h
+        h["skipped_unreadable"] = skipped_unreadable
+        return h