@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/evolution.py

@@ -84,18 +84,22 @@ _STATE_RE = re.compile(r"```json state\s*\n(.*?)\n```", re.S)
 # 路径 / 追加
 # --------------------------------------------------------------------------
 
+# 生效条件：cg 可解析出 root 时，返回 os.path.join(cg.root, 模块常量 EVOLUTION_DIR)，无守卫分支。
 def evolution_dir(cg) -> str:
     return os.path.join(cg.root, EVOLUTION_DIR)
 
 
+# 生效条件：cg 可解析出 root 时，返回 evolution_dir(cg) 与模块常量 LEDGER_NAME 的 os.path.join 结果。
 def ledger_path(cg) -> str:
     return os.path.join(evolution_dir(cg), LEDGER_NAME)
 
 
+# 生效条件：无入参，任何一次调用都返回 "evo-" + time.strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex 的前 4 位。
 def new_entry_id() -> str:
     return "evo-" + time.strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex[:4]
 
 
+# 生效条件：cg 与 text 给定时，在 FileLock(ledger_path(cg)) 内取旧内容（读不到或空则回退 _HEADER，不以换行结尾则补一个换行）并 atomic_write 写入 old + text，无需 text 非空。
 def _append(cg, text: str):
     """向账本追加一条（读-改-写 + 跨进程锁，崩溃不留半截文件）。"""
     p = ledger_path(cg)
@@ -112,6 +116,7 @@ def _append(cg, text: str):
         atomic_write(p, old + text)
 
 
+# 生效条件：ledger_path(cg) 对应路径不存在时返回 ""，否则以 encoding="utf-8"、errors="replace" 打开并返回 f.read() 的全部内容。
 def read_ledger(cg) -> str:
     p = ledger_path(cg)
     if not os.path.exists(p):
@@ -124,7 +129,9 @@ def read_ledger(cg) -> str:
 # 渲染 / 解析
 # --------------------------------------------------------------------------
 
+# 生效条件：field、before、after 任意取值下都返回 f"{field} {_short(before)}→{_short(after)}"。
 def _fmt_change(field, before, after) -> str:
+# 生效条件：v 为 list/tuple 返回 f"{len(v)}条"，为 dict 返回 f"{len(v)}键"，为 None 返回 "—"，为 float 返回 f"{v:g}"，其余类型返回 str(v)。
     def _short(v):
         if isinstance(v, (list, tuple)):
             return f"{len(v)}条"
@@ -138,6 +145,7 @@ def _fmt_change(field, before, after) -> str:
     return f"{field} {_short(before)}→{_short(after)}"
 
 
+# 生效条件：before 与 after 中任一为假值（None、{} 等）时该侧按 {} 参与比较，返回 STATE_FIELDS 中 b.get(k) != a.get(k) 的字段对应的 _fmt_change(k, b.get(k), a.get(k)) 列表。
 def diff(before, after):
     """状态差异 → 人类可读列表（只比认知状态字段）。"""
     b, a = before or {}, after or {}
@@ -145,6 +153,7 @@ def diff(before, after):
             for k in STATE_FIELDS if b.get(k) != a.get(k)]
 
 
+# 生效条件：entry 含键 'entry_id'（缺失即 KeyError）时，按 _BULLET_ORDER 输出值不属 None/""/[]/{} 的字段行（node_id 假值显示 '—'），并在 entry.get("state") 为真值时追加 json 状态块，返回以 "\n" 连接的文本。
 def _fmt(entry: dict) -> str:
     lines = [f"## {entry['entry_id']} · `{entry.get('node_id') or '—'}`", ""]
     for k in _BULLET_ORDER:
@@ -162,6 +171,7 @@ def _fmt(entry: dict) -> str:
     return "\n".join(lines)
 
 
+# 生效条件：text 中 _ENTRY_RE 匹配到 0 个条目时返回 []，匹配到则按各匹配区间解析为字典列表（node 为空或 "—" 时 node_id 置 None，state 段 json.loads 抛 ValueError 时 state 置 None，kind 缺省回落模块常量 KIND_CONDITION_GAP）。
 def _parse(text: str):
     out = []
     marks = list(_ENTRY_RE.finditer(text))
@@ -190,6 +200,7 @@ def _parse(text: str):
 # 认知状态
 # --------------------------------------------------------------------------
 
+# 生效条件：cg.get(node_id) 为假值（含 None）时返回 None，否则返回 frontmatter 中属于 STATE_FIELDS 且值不为 None 的字段（"layer" 缺失时用 node.get("path") 首段补上），保留 []/{}/"" 等显式空值。
 def state_of(cg, node_id):
     """抽取节点的认知状态（可回滚字段），节点不存在返回 None。
 
@@ -209,6 +220,7 @@ def state_of(cg, node_id):
 # 记录
 # --------------------------------------------------------------------------
 
+# 生效条件：pattern.strip() 非空且 kind 属于模块常量 KINDS 时追加并返回条目 e（pattern 为空白或 kind 未知抛 ValueError；action 去空白后为空且 extra 为真时取 extra.pop("change", "") 作 action；before/after 任一 non-None 时 state 记入二者 or {}；extra 中值不属 None/""/[]/{} 的键并入 e）。
 def record(cg, node_id=None, pattern="", missing="", action="", evidence="",
            source="", kind=KIND_CONDITION_GAP, before=None, after=None,
            extra=None):
@@ -249,6 +261,7 @@ def record(cg, node_id=None, pattern="", missing="", action="", evidence="",
 # 查询
 # --------------------------------------------------------------------------
 
+# 生效条件：cg 给定时返回 _parse(read_ledger(cg)) 的列表——node_id 为真值则只留该节点记录、kind 为真值则只留该类型记录、newest_first 为真值则 reverse、limit 为真值时截断为前 int(limit) 条（limit 为 0/None 等假值时不截断）。
 def entries(cg, limit=None, node_id=None, kind=None, newest_first=True):
     recs = _parse(read_ledger(cg))
     if node_id:
@@ -262,6 +275,7 @@ def entries(cg, limit=None, node_id=None, kind=None, newest_first=True):
     return recs
 
 
+# 生效条件：遍历 entries(cg, limit=0)（limit=0 为假值故不截断，覆盖全部记录），命中 r.get("entry_id") == entry_id 时返回该记录，否则返回 None。
 def show(cg, entry_id):
     for r in entries(cg, limit=0):
         if r.get("entry_id") == entry_id:
@@ -269,10 +283,12 @@ def show(cg, entry_id):
     return None
 
 
+# 生效条件：cg 与 node_id 给定时返回 {"node_id": node_id, "entries": entries(cg, limit=limit, node_id=node_id)}——node_id 为假值时 entries 不按节点过滤，limit 默认 50 为真值故截断，传 0 等假值则不截断。
 def history(cg, node_id, limit=50):
     return {"node_id": node_id, "entries": entries(cg, limit=limit, node_id=node_id)}
 
 
+# 生效条件：cg 给定时返回统计字典，其中 recs 取 entries(cg, limit=0) 全量、real 剔除 kind == 模块常量 KIND_ROLLBACK（missing 为空的条目不计入 by_missing、kind 缺省回落 KIND_CONDITION_GAP、source 缺省回落 "unknown"），top_patterns 取按 count 降序 pattern 升序排序后的前 int(limit) 项（limit 为 0 时切片为空列表）。
 def patterns(cg, limit=10):
     """规律统计：哪一维条件反复缺失、由谁触发、哪些规律重复出现。
 
@@ -301,6 +317,7 @@ def patterns(cg, limit=10):
             "by_source": by_source, "top_patterns": top[:int(limit)]}
 
 
+# 生效条件：cg 给定时返回固定结构字典——missing_top 取 patterns(cg) 的 by_missing 中计数最大项的键（by_missing 为空则 "（暂无）"），top_pattern 取 top_patterns[0]["pattern"]（为空则 "（暂无）"），recent 取 entries(cg, limit=5)。
 def summary(cg):
     p = patterns(cg)
     missing_top = (max(p["by_missing"].items(), key=lambda kv: kv[1])[0]
@@ -322,6 +339,7 @@ def summary(cg):
 # 回滚
 # --------------------------------------------------------------------------
 
+# 生效条件：cg.get(node_id) 为假时返回 ([], [{"field": "*", "reason": "节点不存在"}])，否则先处理 target 中的 "layer"（为真且不同于当前 path 首段时经 cg._move_layer 迁移并 appended "layer"，抛异常则记入 skipped，相同/为假时直接 appended "layer"），再按 STATE_FIELDS 处理：k 在 remove 中且存在于 frontmatter 则 pop 并 appended "-k"，k 在 target 中且值相同则 appended k、不同则改写并在 changed 时经 cg._write_node 回写，最终返回 (applied, skipped)（若层迁移后 node 取不回则提前返回）。
 def _apply_state(cg, node_id, target, remove=()):
     """把目标状态写回节点。返回 (applied, skipped)。
 
@@ -375,6 +393,7 @@ def _apply_state(cg, node_id, target, remove=()):
     return applied, skipped
 
 
+# 生效条件：cg 与 entry_id 定位 show(cg, entry_id) 后逐项判定——条目不存在返回未找到错误、kind == 模块常量 KIND_ROLLBACK 返回拒回滚错误、state 的 before 为假值返回无回滚状态错误、node_id 为假值返回未绑定节点错误、state_of 为 None 返回节点不可读错误；dry_run 为真值时返回含 current/target/would_remove/would_change 的预览；否则经 _apply_state(target, remove=after 中不属 before 且非 "layer" 的字段) 回写、尝试 cg.rebuild_index()（异常静默）并 record 一条 KIND_ROLLBACK 条目后返回 ok=True 结果。
 def rollback(cg, entry_id, dry_run=False, note=""):
     """把某条演化撤回其 before 状态，并记一条 rollback 条目（撤销不可静默）。"""
     src = show(cg, entry_id)
@@ -423,6 +442,7 @@ def rollback(cg, entry_id, dry_run=False, note=""):
 # 自描述
 # --------------------------------------------------------------------------
 
+# 生效条件：无入参，任何调用都返回含 module/schema/ledger/carrier/principles/fields/kinds/state_fields/condition_dims/rollback/actions 的固定字典（kinds、state_fields、condition_dims 分别来自模块常量 KINDS、STATE_FIELDS、CONDITION_DIMS）。
 def catalog():
     return {
         "module": "evolution",
@@ -455,4 +475,4 @@ def catalog():
         },
         "actions": ["record", "entries", "show", "history", "patterns",
                     "summary", "rollback", "catalog"],
-    }
+    }

package/md_cg/export.py

@@ -27,12 +27,14 @@ _ROW_KEYS = ("id", "layer", "path", "tags", "importance", "confidence",
              "created_at", "edges", "protected", "sensitivity", "content")
 
 
+# 生效条件：给定 cg 与 kind 即返回 os.path.join(cg.root, f"export_{kind}_{当前 %Y%m%d_%H%M%S 时间戳}.jsonl")，无任何前置校验或分支。
 def _default_out(cg, kind: str) -> str:
     """默认导出路径：`<root>/export_<kind>_<ts>.jsonl`（可搬运、可灾备）。"""
     ts = time.strftime("%Y%m%d_%H%M%S")
     return os.path.join(cg.root, f"export_{kind}_{ts}.jsonl")
 
 
+# 生效条件：cg.get(nid) 为 None 时返回 None；否则以 fm = node.get("frontmatter") or {}（缺键或假值回落空 dict）与 entry 组装行，layer 取 fm 的 layer、为假值时回落 entry.get("layer")，include_content 为真值时追加 content = node.get("content") or ""，最终只保留 _ROW_KEYS 中实际存在的键。
 def _row(cg, nid: str, entry: dict, include_content: bool = True):
     """索引条目 → 导出行（回读节点拿到 frontmatter + 正文）。
 
@@ -62,6 +64,7 @@ def _row(cg, nid: str, entry: dict, include_content: bool = True):
     return {k: row[k] for k in _ROW_KEYS if k in row}
 
 
+# 生效条件：源为 cg.index 的 nodes（缺 "nodes" 键或假值回落空 dict）——ids 为真值时只取其中确实在 nodes 里的 id，否则取全部——按 (float(created_at or 0), id) 排序后逐个产出同时满足 layer（为真时须 (e.layer or "") == layer）、tag（为真时须在 e.tags or [] 中）、since/until（非 None 时按 float 比较 created_at）的条目，limit 为真值且已产出 n 条并 n >= int(limit) 时停止（limit 为 0 或 None 不设上限）。
 def _iter_entries(cg, layer=None, since=None, until=None, tag=None,
                   ids=None, limit=None):
     """按条件遍历索引条目（不读文件，保证筛选阶段零 IO）。
@@ -91,6 +94,7 @@ def _iter_entries(cg, layer=None, since=None, until=None, tag=None,
             return
 
 
+# 生效条件：将 entries 逐条经 _row 转换后写入 out_path（先 makedirs 其父目录、写 out_path + ".tmp"、结束后 os.replace 为 out_path），_row 返回 None 的条目只累加 skipped_unreadable 而不写入，其余写入并累加 written 及 by_layer（row 的 layer 缺键或假值记为 "?"）；include_content 透传给 _row 决定行是否含正文；返回含 ok/out/written/skipped_unreadable/by_layer/bytes/elapsed_ms 的统计 dict。
 def _write_jsonl(cg, out_path: str, entries, include_content: bool = True):
     """流式写 JSONL（tmp + 原子改名）。返回统计 dict。"""
     out_path = os.path.abspath(out_path)
@@ -120,6 +124,7 @@ def _write_jsonl(cg, out_path: str, entries, include_content: bool = True):
             "elapsed_ms": round((time.time() - t0) * 1000, 1)}
 
 
+# 生效条件：out 为假值（None/空串）时回落为 _default_out(cg, "graph")，以 _iter_entries(cg, layer=layer, limit=limit) 为条目流调用 _write_jsonl(include_content=include_content)，再补 action="graph" 与 note 后返回该结果 dict。
 def export_graph(cg, out: str = None, layer=None, limit=None,
                  include_content: bool = True):
     """全库导出（默认含正文）。"""
@@ -133,6 +138,7 @@ def export_graph(cg, out: str = None, layer=None, limit=None,
     return res
 
 
+# 生效条件：ids 先按 [str(i) for i in (ids or []) if str(i).strip()] 规整，规整结果为空（ids 为 None/空容器/全空白项）时返回 {'ok': False, 'error': 'ids 不能为空'}；否则 out 为假值时回落为 _default_out(cg, "nodes")，以 _iter_entries(cg, ids=ids) 为条目流调用 _write_jsonl(include_content=include_content)，再补 action="nodes"、requested=len(ids)、missing=索引 keys 与 ids 的差集排序后返回。
 def export_nodes(cg, ids, out: str = None, include_content: bool = True):
     """按 id 列表导出（顺序 = 传入顺序）。"""
     ids = [str(i) for i in (ids or []) if str(i).strip()]
@@ -147,6 +153,7 @@ def export_nodes(cg, ids, out: str = None, include_content: bool = True):
     return res
 
 
+# 生效条件：out 为假值（None/空串）时回落为 _default_out(cg, "slice")，以 _iter_entries(cg, layer=layer, since=since, until=until, tag=tag, limit=limit) 为条目流调用 _write_jsonl(include_content=include_content)，再补 action="slice" 与记录 layer/since/until/tag 的 filter 后返回。
 def export_slice(cg, out: str = None, layer=None, since=None, until=None,
                  tag=None, limit=None, include_content: bool = True):
     """按层 / 时间窗 / 标签切片导出（有界，便于增量搬运）。"""
@@ -159,6 +166,7 @@ def export_slice(cg, out: str = None, layer=None, since=None, until=None,
     return res
 
 
+# 生效条件：只读 cg.index 的 nodes（缺 "nodes" 键或假值回落空 dict），逐条统计 layer（缺键或假值记 "?"）、verification_basis（缺键或假值记 "(未声明)"）、tags 计数（按计数降序取前 15）、protected 与 has_neg_conditions 为真值的条目数，以及 created_at 为真值时的 min/max（全为 0 或缺键时二者均为 None），返回含 total/by_layer/by_verification_basis/protected/with_non_applicable/top_tags/time_range/note 的 dict。
 def export_stat(cg):
     """导出前体检：层分布 / 验证基底 / 标签 Top / 时间范围。**只读索引，零 IO**。"""
     nodes = (cg.index.get("nodes") or {})
@@ -180,7 +188,8 @@ def export_stat(cg):
         if ca:
             t_min = ca if t_min is None else min(t_min, ca)
             t_max = ca if t_max is None else max(t_max, ca)
-    top_tags = sorted(by_tag.items(), key=lambda kv: -kv[1])[:15]
+    top_tags = sorted(by_tag.items(),
+                      key=lambda kv: (-kv[1], str(kv[0])))[:15]
     return {"ok": True, "action": "stat", "total": len(nodes),
             "by_layer": by_layer, "by_verification_basis": by_basis,
             "protected": protected, "with_non_applicable": with_neg,
@@ -190,6 +199,7 @@ def export_stat(cg):
                      "如需密级分布请用 graph 导出后统计。")}
 
 
+# 生效条件：act = (action or "graph").strip().lower()（action 为 None/空串等假值时取 "graph"）——act 为 "graph"/"nodes"/"slice"/"stat" 时分别转调 export_graph/export_nodes/export_slice/export_stat（out、layer、limit、since、until、tag、ids 取自 kw 对应键，include_content 取 kw.get("include_content", True)），其它 act 值抛 ValueError。
 def run(cg, action: str = "graph", **kw):
     """export op 唯一入口。"""
     act = (action or "graph").strip().lower()

package/md_cg/forgetting.py

@@ -80,6 +80,7 @@ LOG_FILE = "_forgetting.jsonl"
 
 # ---------------------------------------------------------------- 三问
 
+# 生效条件：role 与 verification_basis 各自经 str(x or "").strip().lower() 后按序判——role 命中模块常量 EXTERNAL_ROLES 返回 "external_surprising"；否则 role 命中 INTERNAL_ROLES、或两者都不命中前者时 verification_basis 命中 DETERMINISTIC_BASIS，返回 "internal_deterministic"；否则 role 为 "assistant"/"agent" 返回 "self_generated"；全不命中返回 "unknown"。
 def source_kind(role=None, verification_basis=None):
     """Q3 的来源面：内部确定性产生 vs 外部惊奇来源。"""
     r = str(role or "").strip().lower()
@@ -95,6 +96,7 @@ def source_kind(role=None, verification_basis=None):
     return "unknown"
 
 
+# 生效条件：new_grams 为空集（假值）时返回 0.0；非空时返回 len(new_grams & body_grams)/len(new_grams)。
 def _coverage(new_grams, body_grams):
     if not new_grams:
         return 0.0
@@ -107,6 +109,7 @@ def _coverage(new_grams, body_grams):
 _TEMPLATE_LABELS = ("功能名", "生效条件", "子功能", "执行", "验证方式", "不适用条件")
 
 
+# 生效条件：content 为 None 或假值时按 "" 处理，结果为空串；否则逐行剥离 "#" 与 _TEMPLATE_LABELS 标签后以 "" 直接拼接。
 def payload(content):
     """剥离 CCG 固定标签后的**内容骨架**（保留字段值，丢弃字段名与标记）。"""
     out = []
@@ -123,6 +126,7 @@ def payload(content):
     return "".join(out)
 
 
+# 生效条件：content 经 payload/bigrams 得空集合时直接返回零值 best（max=0.0、with=None、compared=0）；否则遍历 cg.index 的 nodes，跳过 nid==exclude，layer 为真值时只比较 str(layer 字段 or "")==layer 的节点，cg.get(nid) 抛异常/返回假值、或该节点 content 的 bigrams 为空则跳过，每计入一个节点后若 n>=limit 立即 break（故 limit 为 0 或负数时只比较首项即停），返回覆盖度最大者 best（无覆盖度提升时不更新 with/jaccard，compared 为实际计入数）。
 def redundancy(cg, content, layer="contextual", exclude=None, limit=MAX_COMPARE):
     """Q1 重复？——新内容被既有同层节点覆盖的最大比例。"""
     new = bigrams(payload(content))
@@ -157,6 +161,7 @@ def redundancy(cg, content, layer="contextual", exclude=None, limit=MAX_COMPARE)
     return best
 
 
+# 生效条件：dup 必填并转 float；dup=0 时 p 取 EPS，返回 -log2(EPS) 这一有限大值；dup>=1 时返回 0.0。
 def self_information(dup):
     """Q3 的自信息代理：I = -log2(min(1, dup + ε))，单位 bit。
 
@@ -167,6 +172,7 @@ def self_information(dup):
     return -math.log(p, 2.0)
 
 
+# 生效条件：hint 非 None 且可转 float（含 hint=0）时返回 from="hint" 的裁剪分数；否则用 novelty、SOURCE_WEIGHT.get(kind, SOURCE_WEIGHT["unknown"])、len(content)/200 三因子启发式。
 def importance_score(hint, novelty, kind, content):
     """Q2 重要？——显式 hint 优先，否则启发式（对齐 longterm_snapshot 四因子简化版）。"""
     if hint is not None:
@@ -182,6 +188,7 @@ def importance_score(hint, novelty, kind, content):
     return {"score": round(max(0.0, min(1.0, s)), 4), "from": "heuristic"}
 
 
+# 生效条件：以 source_kind(role,verification_basis) 的 kind 与 redundancy(cg,content,layer=layer,exclude=node_id) 的 red["max"] 为输入，按 if/elif 顺序取首个命中分支——imp["score"]≥PROTECT_IMPORTANCE→"ACCEPT"；否则 kind=="internal_deterministic" 且 red["max"]≥DUP_DROP→"DROP"；否则 red["max"]≥DUP_MERGE→"MERGE"；否则 red["max"]≥DUP_DROP 且 imp["score"]<IMPORTANCE_MIN→"DEFER"；否则 imp["score"]≥IMPORTANCE_MIN→"ACCEPT"；否则 novelty≥NOVELTY_MIN→"ACCEPT"；否则→"DEFER"。
 def assess(cg, content, layer="contextual", role=None, verification_basis=None,
            importance_hint=None, node_id=None):
     """三问 → 四态裁决。返回完整判据（可审计，不只给结论）。"""
@@ -226,6 +233,7 @@ def assess(cg, content, layer="contextual", role=None, verification_basis=None,
 
 # ---------------------------------------------------------------- 落库动作
 
+# 生效条件：cg 与 rec 必填；append_jsonl 写 cg.root/LOG_FILE 抛任意异常时被吞掉，仍返回 rec。
 def log(cg, rec):
     """裁决留痕（append-only）。DROP/DEFER 也留痕——否则遗忘变黑箱。"""
     try:
@@ -235,6 +243,7 @@ def log(cg, rec):
     return rec
 
 
+# 生效条件：cg 与 node_id 必填，delta 默认 0.05；cg.get(node_id) 抛异常或返回假值时返回 None；imp 跨过 PROTECT_IMPORTANCE 即写 protected。
 def reinforce(cg, node_id, delta=0.05):
     """MERGE 的落库动作：不新增节点，把「又一次见到」折算成既有节点的强化。
 
@@ -276,6 +285,7 @@ def reinforce(cg, node_id, delta=0.05):
             "merge_count": fm["merge_count"], "protected": bool(fm.get("protected"))}
 
 
+# 生效条件：cg 必填，limit 默认 100；日志路径不存在时返回 []；否则返回 out[-limit:]，limit=0 时 -0 退化为 out[0:] 即全量。
 def history(cg, limit=100):
     """读取遗忘留痕（最近 limit 条）。"""
     p = os.path.join(cg.root, LOG_FILE)
@@ -296,6 +306,7 @@ def history(cg, limit=100):
     return out[-limit:]
 
 
+# 生效条件：cg 必填；日志路径不存在返回 {"total": 0, "by_verdict": {}}；否则流式累计行数与 verdict 分布。
 def summary(cg):
     """遗忘留痕聚合（流式，不把全量日志读进内存）：总数 + 四态分布。"""
     p = os.path.join(cg.root, LOG_FILE)
@@ -339,6 +350,7 @@ VERIFIED_BASES = ("formal_proof", "compiler", "test", "textbook", "public_kb")
 TIER_WORKING = 0.40
 
 
+# 生效条件：e 必填；protected 为真、importance>=PROTECT_IMPORTANCE、或 evidence_count>=3 且 verification_basis 在 VERIFIED_BASES → "longterm"；importance>=TIER_WORKING 或 vb 在 VERIFIED_BASES → "working"；否则 "candidate"。
 def _tier_of(e: dict) -> str:
     """索引快照 → 分层：longterm（长期）/ working（工作）/ candidate（候选待评估）。"""
     imp = float(e.get("importance", 0.5) or 0.5)
@@ -351,19 +363,23 @@ def _tier_of(e: dict) -> str:
     return "candidate"
 
 
+# 生效条件：e 必填；e["edges"] 为假值（缺失/空列表）且 e["subgraph"] 为假值时返回 True，否则 False。
 def _is_island(e: dict) -> bool:
     """无边孤岛：既无出边也无子图声明（夜间整理的首要候选）。"""
     return (not (e.get("edges") or [])) and (not e.get("subgraph"))
 
 
+# 生效条件：cg 必填且提供 cg.root，恒返回 os.path.join(cg.root, LONGTERM_DIR)。
 def longterm_dir(cg) -> str:
     return os.path.join(cg.root, LONGTERM_DIR)
 
 
+# 生效条件：cg 必填，恒返回 longterm_dir(cg) 下的 "current.json" 路径。
 def current_path(cg) -> str:
     return os.path.join(longterm_dir(cg), "current.json")
 
 
+# 生效条件：apply 为真且由 cg.index 的 nodes（layer 为假值时不过滤、为真时仅取 layer 字段相等者，max_rows 为真值时先取 ids[:int(max_rows)]）算出的 snapshot_id 与 current.json 所记 snapshot_id 不同或其记录的 path 文件不存在（same 为假）时，才写断面文件、原子更新 current 指针、执行 _prune 并追加维护日志；apply 为假时只返回 dry_run=True 的统计（out 与 force 在源码中未被引用）。
 def longterm_assess(cg, apply=False, out=None, layer=None, keep=LONGTERM_KEEP,
                     max_rows=None, force=False, actor="maintain"):
     """评估后分层落盘：生成一个可回溯的长期记忆断面。
@@ -440,6 +456,7 @@ def longterm_assess(cg, apply=False, out=None, layer=None, keep=LONGTERM_KEEP,
     }
 
 
+# 生效条件：cg 与 keep 必填；keep<=0 时不删除任何断面返回 []；否则删除除最近 keep 个 .jsonl 外的旧断面。
 def _prune(cg, keep):
     """只保留最近 keep 个断面文件（按文件名时间前缀排序）。"""
     d = longterm_dir(cg)
@@ -457,6 +474,7 @@ def _prune(cg, keep):
     return removed
 
 
+# 生效条件：cg 必填，limit 默认 20；目录不可读返回 []；否则新的在前逐个 append，因先 append 后判 len(out)>=limit，limit=0 时仍返回 1 条快照。
 def longterm_list(cg, limit=20):
     """列出历史断面（新的在前）：{snapshot_id, path, ts, total, tiers}。"""
     d = longterm_dir(cg)
@@ -481,6 +499,7 @@ def longterm_list(cg, limit=20):
     return {"current": cur, "snapshots": out}
 
 
+# 生效条件：longterm_dir(cg) 不可列出（OSError）时返回 {"ok":False,"error":"no_snapshot"}；否则在倒序文件名中取首个满足 snapshot_id 为 None 或为其子串的 .jsonl（snapshot_id="" 与任意文件名匹配），无匹配返回 {"ok":False,"error":"snapshot_not_found"}；命中则逐行聚合该文件（空行与 json.loads 抛 ValueError 的行跳过），返回 file/total/tiers/by_layer/islands。
 def longterm_show(cg, snapshot_id=None):
     """读取某个断面的分层统计（不载全量行，只聚合）。"""
     d = longterm_dir(cg)
@@ -524,6 +543,7 @@ def longterm_show(cg, snapshot_id=None):
 # 写入**之前**的新奇检测：重复项并入既有（MERGE），而非新增；无关噪音丢弃；
 # 有歧义的半重复留痕待复核。这是「写入侧前置」的落库动作，比夜间整理更早一步。
 
+# 生效条件：cg 与 content 必填；恒经 assess 得四态并映射 decision（ACCEPT→write 等），落留痕后返回 ok=True，不写任何节点。
 def prefeed(cg, content, layer="contextual", role=None, verification_basis=None,
             importance_hint=None, node_id=None):
     """前馈裁决（不写盘）：返回四态 + 判据，并留痕 `_forgetting.jsonl`。
@@ -548,13 +568,15 @@ def prefeed(cg, content, layer="contextual", role=None, verification_basis=None,
     return {"ok": True, "action": "prefeed", **rec}
 
 
+# 生效条件：content 为 None 或假值时按 "" 计算，恒返回 "pre_"+sha1(content).hexdigest()[:12]。
 def _prefeed_id(content):
     return "pre_" + hashlib.sha1((content or "").encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：cg 必填，limit 默认 100；action 为假值（None/空串）时不过滤，真值只留该 action；返回 recs[-int(limit):]，limit=0 时退化为全量。
 def maintain_history(cg, limit=100, action=None):
     """维护留痕（`_maintain.jsonl` 最近 limit 条），可按 action 过滤。"""
     recs = list(read_jsonl(os.path.join(cg.root, MAINTAIN_LOG)))
     if action:
         recs = [r for r in recs if r.get("action") == action]
-    return recs[-int(limit):]
+    return recs[-int(limit):]

package/md_cg/fsutil.py

@@ -28,6 +28,7 @@ _RENAME_TRIES = 20
 _RENAME_WAIT = 0.005
 
 
+# 生效条件：tmp 与 path 给定后循环至多 _RENAME_TRIES 次调用 os.replace(tmp, path)，成功即返回；仅捕获 PermissionError，非最后一次则 time.sleep(_RENAME_WAIT) 重试，最后一次仍 PermissionError 则抛出。
 def _publish(tmp: str, path: str):
     """把临时文件 rename 到位，Windows 上短重试。"""
     for i in range(_RENAME_TRIES):
@@ -40,6 +41,7 @@ def _publish(tmp: str, path: str):
             time.sleep(_RENAME_WAIT)
 
 
+# 生效条件：path 与 data 给定时取 path 所在目录 d 建目录，用 tempfile.mkstemp 在 d 内建临时文件按 encoding 写入 data，durable 为真才 flush+os.fsync（假值不 fsync），再经 _publish(tmp, path) 替换；任一步失败时 finally 里若 tmp 仍非 None 且 os.path.exists(tmp) 为真则 os.remove（OSError 忽略）。
 def atomic_write(path: str, data: str, encoding: str = "utf-8", durable: bool = False):
     """整文件替换。临时文件与目标同目录（保证同一文件系统，rename 才原子），
     临时名唯一（并发写者不共享），失败即清理而不是留在可能刚写满的磁盘上。
@@ -71,6 +73,7 @@ def atomic_write(path: str, data: str, encoding: str = "utf-8", durable: bool =
                 pass
 
 
+# 生效条件：os.path.isdir(d) 为假时直接返回；否则对 d 下名字以 "." 开头且含 ".tmp-" 的条目，当 now - os.path.getmtime(p) > older_than 时 os.remove(p)（OSError 忽略），其余条目不动。
 def sweep_stale_temps(d: str, older_than: float = 3600):
     """清理被杀死的进程留下的唯一命名临时文件（它们不会被下一个写者复用清掉）。"""
     if not os.path.isdir(d):
@@ -87,6 +90,7 @@ def sweep_stale_temps(d: str, older_than: float = 3600):
             pass
 
 
+# 生效条件：path 加 ".lock" 后缀作为锁文件，进入时按 timeout 秒内以 poll 间隔轮询获取 OS 级排它锁（IS_WIN 用 msvcrt.locking 锁首字节，否则 fcntl.flock），超时仍未获锁时 strict 为真抛 TimeoutError、否则返回自身放行。
 class FileLock:
     """跨进程排它锁（OS 级）。
 
@@ -102,6 +106,7 @@ class FileLock:
     好过静默放行后退化为无锁并发（丢一条提案/裁决比让写入者等一下代价大）。
     """
 
+# 生效条件：path 加 ".lock" 后缀存入 self.path，timeout、poll、strict 原样保存，并置 self._f = None、self.acquired = False。
     def __init__(self, path: str, timeout: float = 10.0, poll: float = 0.01,
                  strict: bool = False):
         self.path = path + ".lock"
@@ -111,6 +116,7 @@ class FileLock:
         self._f = None
         self.acquired = False
 
+# 生效条件：先按 self.path 建父目录并 open(self.path, "a+b")，再在 self.timeout 到期前每 self.poll 秒尝试加锁（IS_WIN 用 msvcrt.locking(LK_NBLCK)，否则 fcntl.flock(LOCK_EX|LOCK_NB)）；成功即置 self.acquired=True 并返回 self；OSError 的 errno 不在 (EACCES, EAGAIN, EDEADLK) 时直接 raise，超时后 self.strict 为真抛 TimeoutError、否则返回 self 放行。
     def __enter__(self):
         os.makedirs(os.path.dirname(os.path.abspath(self.path)) or ".", exist_ok=True)
         self._f = open(self.path, "a+b")
@@ -134,6 +140,7 @@ class FileLock:
                     return self          # 放行，不阻断写路径
                 time.sleep(self.poll)
 
+# 生效条件：self.acquired 为真时按 IS_WIN 用 msvcrt.locking(LK_UNLCK) 或 fcntl.flock(LOCK_UN) 解锁（OSError 被吞掉）；finally 中只要 self._f 为真就 close，随后 self._f=None、self.acquired=False。
     def __exit__(self, *exc):
         try:
             if self.acquired:
@@ -151,6 +158,7 @@ class FileLock:
             self.acquired = False
 
 
+# 生效条件：os.path.getsize(path) 为 0 时返回 False；否则二进制打开 path 并从 size-1 处读 1 字节，返回 f.read(1) != b"\n"；getsize/open/seek/read 抛 OSError 时返回 False。
 def ends_mid_line(path: str) -> bool:
     """行式日志的最后一字节是否不是换行——即上一个写者被杀死留下的半截记录。
     追加者若不先补一个换行，新记录会粘在这行上，两条都解析不出来。"""
@@ -165,6 +173,7 @@ def ends_mid_line(path: str) -> bool:
         return False
 
 
+# 生效条件：record 序列化为 json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"；若 ends_mid_line(path) 为真则在行首再补一个 "\n"；随后建父目录并以 O_CREAT|O_WRONLY|O_APPEND、权限 0o600 打开 path 写入该行 UTF-8 字节后关闭。
 def append_jsonl(path: str, record: dict):
     """向 append-only 日志追加一条记录（best-effort 语义）。
 
@@ -187,6 +196,7 @@ def append_jsonl(path: str, record: dict):
         os.close(fd)
 
 
+# 生效条件：os.path.exists(path) 为假时生成器直接结束不产出；否则逐行 strip，空行跳过，json.loads 成功则 yield 该对象，抛 ValueError 的行跳过，其余异常不捕获。
 def read_jsonl(path: str):
     """读 append-only 日志，跳过被截断/粘连的坏行（不因自身簿记而失败）。"""
     if not os.path.exists(path):
@@ -205,6 +215,7 @@ def read_jsonl(path: str):
 _COUNT_CACHE = {}          # abspath -> (bytes_scanned, mtime_ns, lines)
 
 
+# 生效条件：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)）。
 
@@ -255,6 +266,7 @@ 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 时各写者只写自己这一分片，从而不共享写入点。
 class ShardedLog:
     """每写者独占一个分片的 append-only 日志——不能丢记录时用它。
 
@@ -263,6 +275,7 @@ 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。
     def __init__(self, directory: str):
         self.dir = os.path.abspath(directory)
         os.makedirs(self.dir, exist_ok=True)
@@ -271,6 +284,7 @@ class ShardedLog:
         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。
     def append(self, record: dict):
         self._seq += 1
         record = dict(record, _t=time.time(), _s=self._seq)
@@ -280,12 +294,14 @@ class ShardedLog:
                                   separators=(",", ":")) + "\n")
         self._fh.flush()
 
+# 生效条件：幂等；self._fh 为真值时 flush 并关闭句柄、再把 self._fh 置 None，为 None 时直接返回不报错；
     def close(self):
         if self._fh:
             self._fh.close()
             self._fh = None
 
     @staticmethod
+# 生效条件：directory 是目录时，按 sorted(os.listdir(directory)) 顺序对每个以 ".log" 结尾的文件调用 read_jsonl 汇总记录，再按每条记录 r.get("_t", 0)、r.get("_s", 0)（缺键取 0）排序后返回全部记录；directory 不是目录时直接返回 []。
     def read_all(directory: str):
         """按全局写入顺序回放所有分片。"""
         if not os.path.isdir(directory):
@@ -299,6 +315,7 @@ class ShardedLog:
         return recs
 
     @staticmethod
+# 生效条件：directory 是目录时，遍历 os.listdir(directory)，对以 ".log" 结尾且不满足「keep 为真值且 os.path.abspath(p) == keep」的条目调用 os.remove（keep 为 None/空串等假值时该排除条件恒不成立，所有 ".log" 条目都会被删），删除时的 OSError 被忽略；directory 不是目录时直接返回。
     def clear(directory: str, keep: str = None):
         """合并进快照后清理分片。keep 用于保留当前进程正在写的那个。"""
         if not os.path.isdir(directory):
@@ -310,4 +327,4 @@ class ShardedLog:
             try:
                 os.remove(p)
             except OSError:
-                pass
+                pass