@furongjun1999/dsh-memory 0.4.7 → 0.4.8

package/md_cg/corpus.py

@@ -84,7 +84,7 @@ def seed(cg, marks=True, layer="knowledge", verification_basis="data"):
 def reset_root(root, clean=False):
     """确保测试根存在：保证「重跑 ≡ 首跑」，且上一轮残留节点不会被当成先验。
 
-    默认**不删目录**（对齐本仓已裁决的设计，见 docs/认知图_MD目录方案_v0.1.md
+    默认**不删目录**（对齐本仓已裁决的设计，见 docs/mdcg/认知图_MD目录方案_v0.1.md
     「幂等性：迁移按 node id 原子覆盖写，可反复执行，**不需要先清空目录**」）：
     `seed()` 用固定 node id 原子覆盖，同一套语料重跑落在同一批文件上，集合封闭。
 

package/md_cg/eval_common.py

@@ -61,11 +61,12 @@ PATHS_CAL = PATHS + ("semantic",)   # 口径 B：显式启用条件结构路（
 def unlock_global_cap():
     """评测口径：解除 GLOBAL_CAP 截断（bench_membench patch_lexical_full 同法）。
 
-    默认 GLOBAL_CAP=500 会把 LIKE 预筛命中按「插入序」截到前 500 条再打分；
-    大型英文语料（turn 高度互相似）预筛命中数千条 → 证据 turn 被插入序随机
-    截掉，检索质量混入插入序 lottery（sanity：证据原文自检索仅 10% hit@1）。
-    评测主口径解除之，只测排序质量。mdcg 与 mdcos 各持一份 from-import 值，
-    必须双改（test_p43_pooling 先例）。
+    【2026-09-16 后语义更新】截断依据已由「插入序」改为「相关度」（`mdcg
+    .cut_by_relevance` 与 `mdcos._lexical` 均先全量打分再排序截断，cap 值仍
+    500）——插入序 lottery 已消除。评测仍解除 cap 的理由只剩一条：避免
+    「按相关度截掉尾部」在长语料上压低召回天花板（相近似 turn 数千条时，
+    排 501 名之后仍可能是证据）——评测要测**排序质量**而非截断策略。
+    mdcg 与 mdcos 各持一份 from-import 值，必须双改（test_p43_pooling 先例）。
     """
     import md_cg.mdcg as m
     import md_cg.mdcos as mo

package/md_cg/forgetting.py

@@ -9,12 +9,12 @@
   · `docs/白箱智能系列·第五篇:174-180`
       「把经历兑换成结构…整理完之后记忆库变小了，但信息量反而更可用——
       噪音被扔掉了，骨架被留下。」
-  · AEIS 工具表 `docs/tool_table_v0.3.0.md:15-19`
+  · AEIS 工具表 `docs/mdcg/tool_table_v0.3.0.md:15-19`
       `prefeed`（H1 新奇检测 → 高新奇输入当场强化编码）、
       `pattern_separation`（H3 扫描相似节点对）、
       `nightly_cleanup`（知识层夜间整理、无边孤岛降级）。
       本模块 = 这三件事的**写入侧前置版**：不等夜间整理，写之前就裁决。
-  · `docs/智能的公理化基石.md:758-763` —— **诚实边界**
+  · `docs/theory/智能的公理化基石.md:758-763` —— **诚实边界**
       「信息差与热力学熵之间只能进行结构类比，不应宣称数学同构」。
       故本模块一律称「自信息代理 / 惊奇度」，**不称香农熵**，也不做熵的物理断言。
 
@@ -47,7 +47,7 @@ import math
 import os
 import time
 
-from . import nodefile
+from . import lifecycle, nodefile
 from .fsutil import append_jsonl, atomic_write, read_jsonl
 from .mdcg import bigrams
 
@@ -256,11 +256,19 @@ def reinforce(cg, node_id, delta=0.05):
         fm["protected"] = True
         fm["protection_reason"] = (f"importance={imp:.2f}≥{PROTECT_IMPORTANCE}"
                                    f"（重复强化）")
+    # ② 显式状态机收口（2026-09-16）：MERGE 的语义是「又一次见到」= **重新激活**
+    # 信号——已降权（demoted）/已定型（converged）的节点经状态机**逐级回升**到
+    # active（archived→active 亦合法，归档节点被再次见到即恢复参与）；active 为
+    # 幂等 no-op（不写字段、不留痕）。protected 只豁免**降级**，回升不受限。
+    lifecycle.stamp(fm, "active", reason="MERGE 重复强化（回升）",
+                    actor="forgetting:reinforce")
     cg._write_node(node_id, os.path.join(cg.root, node["path"]),
                    fm, node.get("content") or "")
     e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
     if e is not None:
         e["importance"] = imp
+        if fm.get(lifecycle.STATE_FIELD):
+            e[lifecycle.STATE_FIELD] = fm[lifecycle.STATE_FIELD]
         if fm.get("protected"):
             e["protected"] = True
             e["protection_reason"] = fm["protection_reason"]

package/md_cg/fsutil.py

@@ -96,12 +96,18 @@ class FileLock:
 
     超时后放弃并放行（best-effort）：写被拒绝的代价大于一次竞态——这与
     deja-vu 对 usage 日志锁的取舍一致（"a racing write beats a lost injection"）。
+
+    strict=True 反转该取舍：超时抛 TimeoutError 而非放行。适用于**不能丢的写**
+    （审核队列 inbox/decisions、裁决记录）——锁竞争失败时显式报错让调用方重试，
+    好过静默放行后退化为无锁并发（丢一条提案/裁决比让写入者等一下代价大）。
     """
 
-    def __init__(self, path: str, timeout: float = 10.0, poll: float = 0.01):
+    def __init__(self, path: str, timeout: float = 10.0, poll: float = 0.01,
+                 strict: bool = False):
         self.path = path + ".lock"
         self.timeout = timeout
         self.poll = poll
+        self.strict = strict
         self._f = None
         self.acquired = False
 
@@ -122,6 +128,9 @@ class FileLock:
                 if e.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
                     raise
                 if time.time() > deadline:
+                    if self.strict:
+                        raise TimeoutError(
+                            f"FileLock 超时未获锁（strict）：{self.path}")
                     return self          # 放行，不阻断写路径
                 time.sleep(self.poll)
 
@@ -193,6 +202,59 @@ def read_jsonl(path: str):
                 continue
 
 
+_COUNT_CACHE = {}          # abspath -> (bytes_scanned, mtime_ns, lines)
+
+
+def count_jsonl(path: str, chunk: int = 1 << 20) -> int:
+    """数 append-only 日志的行数——**流式计数、不物化**（内存 O(1)）。
+
+    存在的唯一理由：`len(list(read_jsonl(p)))` 是**危险的默认写法**。它把整份
+    日志解析成对象列表，日志一长就是灾难——本机实测（2026-09-16）：审计日志
+    4.3 GB，一次 health/盘点调用解析速率 ~1 MB/s、RSS 涨到 5 GB+ 仍在涨、
+    数十分钟不返回；调用方超时重试又在别的进程里再排一次队，最终把整条 MCP
+    通道堵死（一个只读的「体检」把服务打死，代价与收益完全不成比例）。
+    这里只数字节里的换行：不解析、不驻留，速度只受磁盘限制；进程内按
+    (已扫字节数, mtime) 缓存，文件只增长时只扫新增字节（O(增量)）。
+
+    语义边界（诚实声明）：数的是**换行符**，不是 JSON 记录——
+      ① 完整写入的日志（`append_jsonl` 每条尾带 `\\n`）换行数 == 记录数，与
+         `len(list(read_jsonl(p)))` 逐位相等（test_health_scale ⑦ 守卫）；
+      ② 末尾**未终止的半截行**不计入（下界，最多差 1 行；见 append_jsonl 的
+         ends_mid_line 修补分支——并发交错被杀的进程会留下这种尾巴）；
+      ③ 非法 JSON 行计入行数而 `read_jsonl` 会跳过——健康度是量级指标，不做
+         逐行校验，逐行解析正是上面那场事故的根因。
+    """
+    key = os.path.abspath(path or "")
+    try:
+        st = os.stat(key)
+    except OSError:
+        return 0
+    start, total = 0, 0
+    prev = _COUNT_CACHE.get(key)
+    if prev:
+        p_scan, p_mtime, p_count = prev
+        if p_scan == st.st_size and p_mtime == st.st_mtime_ns:
+            return p_count                      # 完全未变：零 IO
+        if p_scan < st.st_size and p_mtime != st.st_mtime_ns:
+            start, total = p_scan, p_count      # 只增长：扫增量
+    scanned, lines = start, 0
+    try:
+        with open(key, "rb") as f:
+            if start:
+                f.seek(start)
+            while True:
+                buf = f.read(chunk)
+                if not buf:
+                    break
+                scanned += len(buf)
+                lines += buf.count(b"\n")
+    except OSError:
+        return total or 0
+    total += lines
+    _COUNT_CACHE[key] = (scanned, st.st_mtime_ns, total)
+    return total
+
+
 class ShardedLog:
     """每写者独占一个分片的 append-only 日志——不能丢记录时用它。
 

package/md_cg/identity.py

@@ -3,7 +3,7 @@
 
 理论出处
 --------
-· 智能论 v3.4 §十三「五大单元」·位置效应（`docs/智能的公理化基石.md:540-556`）：
+· 智能论 v3.4 §十三「五大单元」·位置效应（`docs/theory/智能的公理化基石.md:540-556`）：
 
       单元        位置效应   核心职责
       记录单元     全        保存观测、过程、结果和误差
@@ -16,7 +16,7 @@
   所以「画像」不该只刻画用户，而应识别**每个主体的身份锚点 + 位置 + 特征**，
   其中也包括智能体自身（self）。
 
-· 扮演论 v3.3（`README.md:231-271`、`docs/tool_table_v0.3.0.md:86-92`）：
+· 扮演论 v3.3（`README.md:231-271`、`docs/mdcg/tool_table_v0.3.0.md:86-92`）：
   智能即扮演；角色卡 = 条件空间声明起点；三接口 =
       memory（历史 → 知识层）/
       anchor（自我锚点 → SELF 层，不可遗忘）/

package/md_cg/insight.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 """洞察条件层（P2 · insight）：洞见事件四件套。
 
-对齐 `docs/tool_table_v0.3.0.md`（insight_record / insight_verify /
-insight_report / insight_window）与 `docs/灵枢82工具_功能整理与迁移映射_v0.1.md`
+对齐 `docs/mdcg/tool_table_v0.3.0.md`（insight_record / insight_verify /
+insight_report / insight_window）与 `docs/mdcg/灵枢82工具_功能整理与迁移映射_v0.1.md`
 §五 P2 缺口。
 
 四件套

package/md_cg/lifecycle.py

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 节点显式生命周期状态机（可学习优点 ②·显式状态机）
+
+出处（pi）：
+    运行操作 = 13 个**叶子显式状态机**（`session/types.ts:315-329`），drive 循环按
+    `at` 分发；一轮无任何进展即抛 `SessionInvariantError`（`drive.ts:101-104`）
+    ——非法迁移在**结构上不可能**，而不是靠调用方自觉。
+
+灵枢现状（本模块要收口的四处散落状态）：
+    · `writelimit._demote`  用 **tag** `tidy:converged` 记「同构聚合已定型」
+    · `forgetting.reinforce` 用 **importance** 升降记「强化 / 弱化」
+    · `protect`             用 **fm.protected** 记「不可遗忘」
+    · `_evolution/ledger.md` 记账本
+    四种载体各说各话：谁都能把已定型节点再降一次权、把归档节点悄悄覆写成新的，
+    而**没有任何地方校验「这一步迁移合不合法」**。
+
+本模块是该问题的唯一真源：状态集 `STATES` + 合法迁移表 `TRANSITIONS` + 单点裁决
+`check()` + 单点推进 `set_state()`。口径：
+
+  · 状态落 **frontmatter.lifecycle_state**（节点 md 是唯一真源）；索引快照带同名字
+    段 →「免读文件可查」（`_index.json` 即可回答「这节点什么状态」）。
+    **为何不叫 `state`**（对交接文档建议集的偏离，取证理由）：`state` 在 md_cg 内
+    已被**裁决四态**（ACCEPT/REJECT/DEFER/BLINDSPOT）占用——`audit._verdict` 的返
+    回体、`judge_qualification()` 的返回、`mdcos.search` 结果项、检索结果条目的
+    `entry["state"]` 全都用它。若生命周期也叫 `state`，则同一外层结构里
+    `entry["state"]`（裁决）与 `entry["frontmatter"]["state"]`（生命周期）并存，
+    人类与 agent 读面必生歧义；本仓既有 `self_state` 即为同一动机的先例。
+    故取 `lifecycle_state`：语义自明、零歧义。
+  · 存量节点**缺 state 即视为 active**（`state_of` 的缺省），故不回填也能工作；
+    `backfill()` 提供一次性回填（幂等、可 dry-run）。
+  · **受保护节点豁免降级**：`protected`/`immutable` 节点不接受降级迁移，需
+    `override=True` 显式放行——「保护 = 不可遗忘」在状态层的落点。
+  · 非法迁移**拒绝**（负路由）：`check()` 返回 `(ok, code, reason)`，`set_state()`
+    返回 `ok=False` + 机器可读 `error` 而不抛；写路径要硬拒用 `require_transition()`。
+  · 永不删除：`archived` 只是状态，节点文件仍在（可逆、可审计）。
+  · 幂等：同状态迁移是 no-op（不写盘、不留痕）——重复发起不会把历史刷爆。
+
+状态语义（建议集，逐级降级 / 逐级回升）：
+    active    正常：参与检索与写入面
+    converged 已定型：同构聚合的成员（writelimit tidy 的落点）
+    demoted   已降权：importance 被下调（forgetting 弱化的落点）
+    archived  已归档：不再参与默认检索，但文件保留、可显式恢复
+"""
+from __future__ import annotations
+
+import os
+import time
+
+from .fsutil import append_jsonl
+
+#: 状态全集。顺序即「降级方向」：active → converged → demoted → archived。
+STATES = ("active", "converged", "demoted", "archived")
+#: frontmatter 字段名（索引快照同名透出）。刻意避开 `state`——见模块 docstring
+#: 「为何不叫 state」：该名已被裁决四态占用，同名会让读面产生歧义。
+STATE_FIELD = "lifecycle_state"
+#: 迁移留痕字段（frontmatter 侧历史，滚动保留最近 HISTORY_KEEP 条）
+HISTORY_FIELD = "state_history"
+HISTORY_KEEP = 20
+#: 状态迁移审计（append-only，与 _forgetting.jsonl / _maintain.jsonl 同风格）
+AUDIT_FILE = "_lifecycle.jsonl"
+
+#: 降级序位（用于「受保护豁免降级」的判定）
+_RANK = {"active": 0, "converged": 1, "demoted": 2, "archived": 3}
+
+#: 合法迁移表——**逐级降级、逐级回升**，不跳级：
+#:   active   ⇄ converged        定型 / 定型撤销
+#:   active    → demoted         直接弱化（forgetting 降权）
+#:   converged → demoted        定型后再弱化
+#:   demoted  ⇄ active           被强化回升 / 再弱化
+#:   demoted   → archived        归档
+#:   archived  → active          显式恢复
+#: 刻意不收录的（即拒绝的）：active→archived（跳级归档）、archived→converged /
+#: archived→demoted（跳级回落）、converged→archived（跳级归档）。
+TRANSITIONS = frozenset({
+    ("active", "converged"),
+    ("active", "demoted"),
+    ("converged", "active"),
+    ("converged", "demoted"),
+    ("demoted", "active"),
+    ("demoted", "archived"),
+    ("archived", "active"),
+})
+
+
+class TransitionError(ValueError):
+    """非法生命周期迁移（写路径用 `require_transition` 直接抛这个）。"""
+
+    def __init__(self, src, dst, code, reason):
+        super().__init__(f"非法状态迁移 {src}→{dst}（{code}）：{reason}")
+        self.src, self.dst, self.code, self.reason = src, dst, code, reason
+
+
+# ---------------------------------------------------------------- 纯函数裁决
+
+def state_of(fm) -> str:
+    """frontmatter → 状态；缺字段或未知值 → "active"（存量兼容，不猜测）。"""
+    if not isinstance(fm, dict):
+        return "active"
+    s = fm.get(STATE_FIELD)
+    return s if s in STATES else "active"
+
+
+def is_downgrade(src: str, dst: str) -> bool:
+    """是否向「更低」的状态迁移（active < converged < demoted < archived）。"""
+    return _RANK.get(dst, 0) > _RANK.get(src, 0)
+
+
+def can_transition(src, dst) -> bool:
+    """迁移是否合法（含幂等；未知 src 按 active 处理）。"""
+    src = src if src in STATES else "active"
+    if dst not in STATES:
+        return False
+    if src == dst:
+        return True                     # 幂等：同状态是 no-op
+    return (src, dst) in TRANSITIONS
+
+
+def check(src, dst, protected: bool = False, override: bool = False):
+    """迁移合法性裁决 → `(ok, code, reason)`。**唯一裁决点**（纯函数，无 IO）。
+
+    code 取值：`ok` / `noop`（同状态，不写盘）/ `unknown_state` /
+    `illegal_transition` / `protected`。
+    """
+    src = src if src in STATES else "active"
+    if dst not in STATES:
+        return False, "unknown_state", f"未知状态 {dst!r}（允许：{STATES}）"
+    if src == dst:
+        return True, "noop", "状态未变（幂等，不写盘）"
+    if (src, dst) not in TRANSITIONS:
+        legal = "、".join(f"{a}→{b}" for a, b in sorted(TRANSITIONS))
+        return False, "illegal_transition", (
+            f"{src}→{dst} 不在合法迁移表内（允许：{legal}）——"
+            "降级与回升都须逐级，跨级迁移一律拒绝")
+    if is_downgrade(src, dst) and protected and not override:
+        return False, "protected", (
+            f"受保护节点不接受降级迁移 {src}→{dst}（保护 = 不可遗忘）；"
+            "确需降级请显式 override=True")
+    return True, "ok", f"{src}→{dst} 合法"
+
+
+def require_transition(src, dst, protected: bool = False, override: bool = False):
+    """合法则返回 code，非法则抛 `TransitionError`（写路径的硬拒入口）。"""
+    ok, code, why = check(src, dst, protected=protected, override=override)
+    if not ok:
+        raise TransitionError(src if src in STATES else "active", dst, code, why)
+    return code
+
+
+def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
+          override: bool = False):
+    """在给定 frontmatter 上**就地**推进状态（无 IO）→ `(ok, code, why)`。
+
+    与 `set_state()` 共用同一裁决点（`check`），供**需与其他字段同批落盘**的收
+    口点使用——`writelimit` 的降权要一次写盘改 tags/importance/状态，`forgetting`
+    的强化同理；否则状态得单独再写一次盘（同一节点两倍 IO）。
+    合法且非幂等时写入 `STATE_FIELD` 并追加 `HISTORY_FIELD`；失败/幂等不动 fm。
+    """
+    src = state_of(fm)
+    prot = bool(fm.get("protected") or fm.get("immutable"))
+    ok, code, why = check(src, dst, protected=prot, override=override)
+    if not ok or code == "noop":
+        return ok, code, why
+    fm[STATE_FIELD] = dst
+    hist = list(fm.get(HISTORY_FIELD) or [])
+    hist.append({"at": time.time(), "from": src, "to": dst,
+                 "reason": reason, "actor": actor})
+    fm[HISTORY_FIELD] = hist[-HISTORY_KEEP:]
+    return True, code, why
+
+
+# ---------------------------------------------------------------- 索引同步
+
+def _sync_index(cg, node_id, fm) -> None:
+    """把 state 同步进索引快照（免读文件可查）；无索引实现时静默跳过。
+
+    只同步 `state` 一个键：迁移历史已在 frontmatter 与 `_lifecycle.jsonl` 留痕，
+    放进索引会让快照无谓膨胀。
+    """
+    idx = getattr(cg, "index", None)
+    if not isinstance(idx, dict):
+        return
+    e = (idx.get("nodes") or {}).get(node_id)
+    if e is None:
+        return
+    e[STATE_FIELD] = fm.get(STATE_FIELD)
+    dirty = getattr(cg, "_dirty", None)
+    if isinstance(dirty, dict):
+        dirty[node_id] = e
+    flush = getattr(cg, "flush", None)
+    if callable(flush):
+        flush()
+
+
+# ---------------------------------------------------------------- 推进 / 回填
+
+def set_state(cg, node_id: str, dst: str, reason: str = None,
+              actor: str = None, override: bool = False) -> dict:
+    """推进一个节点的生命周期状态（**唯一推进入口**）。
+
+    非法迁移不走异常而是返回 `{"ok": False, "error": <code>, ...}`（负路由：
+    调用方自行决定降级处理；要硬拒请用 `require_transition`）。幂等迁移返回
+    `changed=False` 且不写盘。返回体始终带 `from` / `to` / `code` 便于审计。
+    """
+    node = cg.get(node_id)
+    if not node:
+        return {"ok": False, "error": "node_not_found", "node_id": node_id}
+    fm = dict(node.get("frontmatter") or {})
+    src = state_of(fm)
+    ok, code, why = stamp(fm, dst, reason=reason, actor=actor, override=override)
+    base = {"node_id": node_id, "from": src, "to": dst, "code": code}
+    if not ok:
+        return {**base, "ok": False, "error": code, "reason": why}
+    if code == "noop":
+        return {**base, "ok": True, "changed": False, "reason": why}
+    at = fm[HISTORY_FIELD][-1]["at"]
+    cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
+                   node.get("content") or "")
+    _sync_index(cg, node_id, fm)
+    try:
+        append_jsonl(os.path.join(cg.root, AUDIT_FILE), {
+            "t": at, "action": "set_state", "node_id": node_id,
+            "from": src, "to": dst, "reason": reason, "actor": actor,
+            "override": bool(override)})
+    except Exception:                    # 审计失败不阻断状态推进
+        pass
+    return {**base, "ok": True, "changed": True, "reason": why, "at": at}
+
+
+def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
+    """存量回填：把缺 `state` 的节点显式补成 `active`（幂等）。
+
+    缺字段本就按 active 解释（`state_of`），故回填**不是让功能工作的前提**，
+    而是把「缺省」变成「显式」——索引/审计里从此可直接读到状态。
+    `apply=False`（默认）只盘点。写不动（文件取不回）的节点进 `failed` 如实上报。
+    """
+    nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
+    missing = []
+    for nid, e in list(nodes.items()):
+        if len(missing) >= limit:
+            break
+        if (e or {}).get(STATE_FIELD) in STATES:
+            continue
+        missing.append(nid)
+    missing.sort()
+    if not apply:
+        return {"ok": True, "dry_run": True, "scanned": len(nodes),
+                "missing": len(missing), "planned": missing[:50]}
+    done, failed = [], []
+    for nid in missing:
+        node = cg.get(nid)
+        if not node:
+            failed.append(nid)
+            continue
+        fm = dict(node.get("frontmatter") or {})
+        fm[STATE_FIELD] = state_of(fm)   # 缺省 active → 显式落盘
+        cg._write_node(nid, os.path.join(cg.root, node["path"]), fm,
+                       node.get("content") or "")
+        _sync_index(cg, nid, fm)
+        done.append(nid)
+    return {"ok": True, "dry_run": False, "scanned": len(nodes),
+            "missing": len(missing), "backfilled": len(done),
+            "planned": done[:50], "failed": failed[:20]}