@furongjun1999/dsh-memory 0.9.6 → 0.9.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (233) hide show
  1. package/README.md +150 -662
  2. package/codebuddy/CODEBUDDY.md +333 -204
  3. package/data/policy.json +38 -38
  4. package/docs/README.md +18 -0
  5. package/docs/discipline/harnesses.yaml +11 -3
  6. package/docs/discipline/templates/compact.txt.tmpl +20 -18
  7. package/docs/discipline/templates/full.md.tmpl +63 -61
  8. package/docs/discipline/templates/rules.mdc.tmpl +5 -3
  9. package/docs/discipline/templates/skill.md.tmpl +25 -23
  10. package/docs/discipline/templates/spec.txt.tmpl +2 -2
  11. package/docs/discipline/templates/zcode-user.md.tmpl +1 -1
  12. package/dsh/cordis.yml.example +139 -139
  13. package/lib/hooks.d.ts +19 -0
  14. package/lib/hooks.js +30 -7
  15. package/lib/index.js +18 -3
  16. package/lib/init.js +19 -4
  17. package/lib/lib/hook_audit.js +64 -2
  18. package/lib/lib/prompt_safety.js +14 -3
  19. package/lib/tools.d.ts +7 -0
  20. package/lib/tools.js +22 -1
  21. package/md_cg/_guard_kit.py +121 -121
  22. package/md_cg/anchor.py +114 -114
  23. package/md_cg/audit.py +15 -2
  24. package/md_cg/chain.py +3 -2
  25. package/md_cg/config_registry_guard.py +487 -487
  26. package/md_cg/conformance.py +747 -747
  27. package/md_cg/consolidate.py +1793 -1793
  28. package/md_cg/crypto.py +794 -794
  29. package/md_cg/hyperedge.py +262 -262
  30. package/md_cg/interface_schema.py +146 -146
  31. package/md_cg/lifecycle.py +426 -426
  32. package/md_cg/mdcos.py +12 -8
  33. package/md_cg/predict.py +1103 -1103
  34. package/md_cg/protect.py +654 -654
  35. package/md_cg/provenance.py +606 -606
  36. package/md_cg/queue_health.py +130 -130
  37. package/md_cg/refine.py +613 -613
  38. package/md_cg/retrieve.py +128 -128
  39. package/md_cg/revise.py +140 -140
  40. package/md_cg/rollback.py +657 -657
  41. package/md_cg/rollback_cli.py +124 -124
  42. package/md_cg/rotate.py +346 -346
  43. package/md_cg/routing.py +490 -490
  44. package/md_cg/self_surface.py +50 -50
  45. package/md_cg/semantic/canonical.py +144 -144
  46. package/md_cg/semantic/zh_en_atoms.py +141 -141
  47. package/md_cg/sources.py +1091 -1091
  48. package/md_cg/stg.py +3 -2
  49. package/md_cg/sustain.py +10 -1
  50. package/md_cg/test_audit_rotate_parity.py +279 -279
  51. package/md_cg/test_autonomy_modes.py +2013 -2013
  52. package/md_cg/test_cn_recall_grams.py +206 -206
  53. package/md_cg/test_code_kind_forbidden.py +101 -0
  54. package/md_cg/test_condaccept.py +156 -156
  55. package/md_cg/test_condgate.py +141 -141
  56. package/md_cg/test_heartbeat_ledger.py +9 -3
  57. package/md_cg/test_i50e_readside_protection.py +658 -658
  58. package/md_cg/test_issue111_gate_order.py +76 -76
  59. package/md_cg/test_issue111_scoring_contract.py +86 -86
  60. package/md_cg/test_issue121_calibration_bounds.py +293 -293
  61. package/md_cg/test_issue145_sleep_no_silent_rollback.py +167 -167
  62. package/md_cg/test_issue147_pack_id_escape.py +378 -378
  63. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -192
  64. package/md_cg/test_issue149_accel_default_face.py +248 -248
  65. package/md_cg/test_issue150_empty_query_terms.py +328 -328
  66. package/md_cg/test_issue151_153_157_write_cache_index.py +151 -151
  67. package/md_cg/test_issue152_sealed_postings.py +309 -309
  68. package/md_cg/test_issue153b_index_generation_invalidation.py +142 -142
  69. package/md_cg/test_issue157b_index_remainder.py +344 -344
  70. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -223
  71. package/md_cg/test_issue191_import_trust.py +382 -382
  72. package/md_cg/test_issue193_write_scope.py +378 -378
  73. package/md_cg/test_issue212_writeface_gaps.py +349 -349
  74. package/md_cg/test_issue214_reject_sensitivity.py +266 -266
  75. package/md_cg/test_issue215_condition_source_gap.py +272 -272
  76. package/md_cg/test_issue216_clash_routes.py +214 -214
  77. package/md_cg/test_issue217_slot_routes.py +248 -248
  78. package/md_cg/test_issue218_postcondition_value_blind.py +222 -222
  79. package/md_cg/test_issue258_pack_sensitivity.py +468 -468
  80. package/md_cg/test_issue265_coldverify_multiproc.py +438 -438
  81. package/md_cg/test_issue274_read_node_id_none.py +341 -341
  82. package/md_cg/test_issue275_layer_param.py +250 -250
  83. package/md_cg/test_issue277_node_id_traversal.py +384 -384
  84. package/md_cg/test_issue278_neg_separated_tension.py +271 -271
  85. package/md_cg/test_issue278_neg_window.py +294 -294
  86. package/md_cg/test_issue278_negative_layering.py +83 -83
  87. package/md_cg/test_issue284_skip_not_pass.py +291 -291
  88. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -573
  89. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -245
  90. package/md_cg/test_issue303_design_boundaries.py +262 -262
  91. package/md_cg/test_issue315_merge_branch_sensitivity.py +383 -383
  92. package/md_cg/test_issue319_tenant_unregistered_bypass.py +256 -256
  93. package/md_cg/test_issue321_mcp_deep_json.py +304 -304
  94. package/md_cg/test_issue322_node_write_lock.py +727 -727
  95. package/md_cg/test_issue324_write_size_fields.py +214 -214
  96. package/md_cg/test_issue325_audit_poison.py +229 -229
  97. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -331
  98. package/md_cg/test_issue326_key_perms.py +355 -355
  99. package/md_cg/test_issue326_twin_parser_parity.py +323 -323
  100. package/md_cg/test_issue326_vm_call_frame.py +569 -569
  101. package/md_cg/test_issue345_writelimit_effective_sens.py +233 -233
  102. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -424
  103. package/md_cg/test_issue348_insight_verify_op.py +199 -199
  104. package/md_cg/test_issue348_merge_rmw_lock.py +345 -345
  105. package/md_cg/test_issue350_casefold_collision.py +235 -235
  106. package/md_cg/test_issue351_ingest_root_fallback.py +201 -201
  107. package/md_cg/test_issue352_imgaudit.py +418 -418
  108. package/md_cg/test_issue352_pathsjson.py +537 -537
  109. package/md_cg/test_issue352_refindex.py +412 -412
  110. package/md_cg/test_issue352_rollback.py +604 -604
  111. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -327
  112. package/md_cg/test_issue354_rust_index_containment.py +571 -571
  113. package/md_cg/test_issue354_rust_wal_containment.py +606 -606
  114. package/md_cg/test_issue358_truncation_observable.py +247 -247
  115. package/md_cg/test_issue360_tidy_private_excerpt.py +195 -195
  116. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -494
  117. package/md_cg/test_issue362_neg_condition.py +468 -468
  118. package/md_cg/test_issue363_lexical_idf.py +275 -275
  119. package/md_cg/test_issue370_readcache_assembly.py +488 -488
  120. package/md_cg/test_issue376_heartbeat_failed.py +293 -293
  121. package/md_cg/test_issue377_layer_protect_stamp.py +324 -324
  122. package/md_cg/test_issue378_protected_floor.py +310 -310
  123. package/md_cg/test_issue383_state_event_write_gate.py +462 -462
  124. package/md_cg/test_issue397_sens_eff_wiring.py +435 -435
  125. package/md_cg/test_issue398_toolface_op_parity.py +511 -511
  126. package/md_cg/test_issue399_hive_json_shape.py +317 -317
  127. package/md_cg/test_issue401_wisdom_codegen.py +295 -295
  128. package/md_cg/test_issue404_heal_receipt.py +389 -389
  129. package/md_cg/test_issue409_compact_index_completeness.py +509 -509
  130. package/md_cg/test_issue410_verify_demote_write.py +366 -366
  131. package/md_cg/test_issue411_scrub_idempotence.py +575 -575
  132. package/md_cg/test_issue412_discipline_producer_parity.py +311 -311
  133. package/md_cg/test_issue413_preimage_failclosed.py +239 -239
  134. package/md_cg/test_issue413_preimage_twin.py +339 -339
  135. package/md_cg/test_issue415_deps_gate_probe.py +357 -357
  136. package/md_cg/test_issue416_entry_key_subset.py +525 -525
  137. package/md_cg/test_issue417_twophase_merge_landed.py +423 -423
  138. package/md_cg/test_issue425_ingest_library_path.py +331 -331
  139. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -346
  140. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -310
  141. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -301
  142. package/md_cg/test_issue427_serve_status_shape.py +191 -191
  143. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -322
  144. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -278
  145. package/md_cg/test_issue434_435_float_gate.py +90 -90
  146. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -448
  147. package/md_cg/test_issue43_default_policy.py +874 -874
  148. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -281
  149. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -454
  150. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -382
  151. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -51
  152. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -203
  153. package/md_cg/test_issue451_audit_actor.py +313 -313
  154. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -299
  155. package/md_cg/test_issue463_ghost_prune_guard.py +259 -259
  156. package/md_cg/test_issue466_basis_registry.py +469 -469
  157. package/md_cg/test_issue467_identity_sensitivity_parity.py +360 -360
  158. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -126
  159. package/md_cg/test_issue470_wal_event_durable.py +427 -427
  160. package/md_cg/test_issue471_identity_readable.py +136 -136
  161. package/md_cg/test_issue472_audit_chain.py +90 -90
  162. package/md_cg/test_issue472_prune_ledger.py +105 -105
  163. package/md_cg/test_issue472_rollback_degraded.py +81 -81
  164. package/md_cg/test_issue491_compose_sandbox.py +460 -460
  165. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -280
  166. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -256
  167. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -110
  168. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -88
  169. package/md_cg/test_issue525_read_null_semantics.py +52 -52
  170. package/md_cg/test_issue547_append_jsonl_whitelist.py +114 -114
  171. package/md_cg/test_issue547_audit_durable.py +96 -96
  172. package/md_cg/test_issue557_r2_write_entries_size_gate.py +83 -83
  173. package/md_cg/test_issue559_refine_prefix.py +69 -69
  174. package/md_cg/test_issue562_retired_faces.py +150 -0
  175. package/md_cg/test_issue71_queue_backlog.py +376 -376
  176. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -420
  177. package/md_cg/test_issue82_credential_rules.py +271 -271
  178. package/md_cg/test_issue91_verifier_sandbox.py +314 -314
  179. package/md_cg/test_issue93_remember_redaction.py +282 -282
  180. package/md_cg/test_logref.py +1141 -1141
  181. package/md_cg/test_md_access_parity.py +330 -330
  182. package/md_cg/test_md_cg_no_hive_dep.py +139 -139
  183. package/md_cg/test_mutation_residue.py +119 -119
  184. package/md_cg/test_mutation_rollback.py +835 -835
  185. package/md_cg/test_n123_derive_expiry_chain.py +210 -210
  186. package/md_cg/test_n184_keys_concurrent_provision.py +1 -1
  187. package/md_cg/test_n209_verify_write_face_gates.py +466 -466
  188. package/md_cg/test_n62_tenant_bind_failclosed.py +200 -200
  189. package/md_cg/test_neg_tail_honesty.py +733 -733
  190. package/md_cg/test_p21_tokens.py +294 -294
  191. package/md_cg/test_p27_docindex.py +792 -792
  192. package/md_cg/test_p28_refcheck.py +1053 -1053
  193. package/md_cg/test_p2_six_elements.py +476 -476
  194. package/md_cg/test_p33_ccg_wiring.py +300 -300
  195. package/md_cg/test_p3_legacy_closure.py +438 -438
  196. package/md_cg/test_p40_refine_worklist.py +244 -244
  197. package/md_cg/test_p4_freshness.py +781 -781
  198. package/md_cg/test_p9c_dedup_hints.py +288 -288
  199. package/md_cg/test_policy_required_ccg.py +444 -444
  200. package/md_cg/test_read_scope_b27.py +2 -2
  201. package/md_cg/test_retr_s5.py +312 -312
  202. package/md_cg/test_s1_ast_judge.py +109 -109
  203. package/md_cg/test_security_audit_v21.py +249 -249
  204. package/md_cg/test_state_event_op.py +521 -521
  205. package/md_cg/test_stgidx_index_parity.py +1024 -1024
  206. package/md_cg/test_sustain_bad_stamp.py +178 -0
  207. package/md_cg/test_sustain_bounded.py +652 -652
  208. package/md_cg/test_trust_edge_reachability.py +405 -405
  209. package/md_cg/test_w7_redlines.py +659 -659
  210. package/md_cg/test_write_return_shape.py +919 -919
  211. package/md_cg/test_writepipe.py +228 -228
  212. package/md_cg/trust.py +1114 -1114
  213. package/md_cg/twophase.py +303 -303
  214. package/md_cg/whitebox.py +536 -536
  215. package/md_cg/whitebox_kb/wisdom/compose_engine.py +1634 -1634
  216. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +318 -318
  217. package/md_cg/whitebox_kb/wisdom/core/parser.py +1082 -1082
  218. package/md_cg/whitebox_kb/wisdom/md_access.py +490 -490
  219. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +497 -497
  220. package/md_cg/whitebox_kb/wisdom/mini_python.py +995 -995
  221. package/md_cg/whitebox_kb/wisdom/net_units.py +2900 -2900
  222. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +4060 -4060
  223. package/md_cg/writepipe.py +1337 -1337
  224. package/package.json +3 -2
  225. package/scripts/workspace_index.py +328 -0
  226. package/src/hooks.ts +932 -908
  227. package/src/index.ts +21 -6
  228. package/src/init.ts +16 -4
  229. package/src/lib/hook_audit.ts +48 -2
  230. package/src/lib/mdcg_client.ts +469 -469
  231. package/src/lib/prompt_safety.ts +17 -3
  232. package/src/tools.ts +23 -1
  233. package/zcode/AGENTS.md +333 -204
package/md_cg/protect.py CHANGED
@@ -1,655 +1,655 @@
1
- # -*- coding: utf-8 -*-
2
- """md_cg · 自我层 / 锚点层写保护(不可遗忘)
3
-
4
- 理论出处(全部来自本仓已有文档,非外部发明):
5
-
6
- · `docs/mdcg/灵枢_自我层定义.md:6`
7
- SELF 层 = 身份 + 价值观 + 图接口,**不可遗忘**、跨会话自动加载。
8
- 任何实例都能改写自我层 = 自我认知可被任意覆写,与「自我」定义冲突。
9
- · `docs/mdcg/认知图_MD目录方案_v0.1.md:53`
10
- `anchor/ # 锚点层(不可遗忘,保护)`
11
- · `docs/mdcg/认知图_MD目录方案_v0.1.md:412-416`
12
- 「importance 提升(保护:不可遗忘记入 anchor/ 且**受保护标记**)」
13
- · `docs/mdcg/tool_table_v0.3.0.md:15`
14
- 「importance_hint 可显式提示重要性(**≥0.7 触发不可遗忘保护**)」
15
-
16
- 三层保护(任一命中即受保护):
17
-
18
- ┌ 1. 层保护 layer ∈ {self, anchor}
19
- ├ 2. 显式标记 frontmatter.protected == True
20
- └ 3. 重要性保护 importance ≥ 0.70(写入时自动打标)
21
-
22
- **关键区分:不可遗忘 ≠ 不可覆盖。**
23
- · 不可遗忘(forget / 降级搬迁):层保护 + protected 标记 + importance≥0.7 三者都拦。
24
- 文档原话是「不可遗忘」「触发不可遗忘保护」——重点是**别弄丢**。
25
- · 不可覆盖(覆写同一 id):只拦 层保护 + 显式 immutable 标记。
26
- 因为 goal_*/fix_*/kp_* 这类 id 是内容派生、由系统自身幂等更新,
27
- 若 importance≥0.7 就禁止覆写,会把正常的状态更新全部误伤。
28
- 自我认知之所以不可篡改,靠的是 **self/anchor 层**这个强信号,
29
- 而不是"重要性高"这个弱信号。
30
-
31
- 受保护节点的动作必须显式 `override=True`:动作前先把旧版本快照进
32
- `_protected_history/<id>/<时间戳>.md`,并把「谁、何时、为何」记进
33
- `_protected_audit.jsonl`——保护不等于黑箱。
34
-
35
- 注意:新建(索引中不存在的节点)不受限。保护的是「已有自我认知不被改/删」,
36
- 不是「禁止产生自我认知」,否则审计节点等正常写入会被误伤。
37
- """
38
- import os
39
- import time
40
-
41
- from . import nodefile
42
- from .fsutil import append_jsonl, atomic_write
43
- from .security import DEFAULT_SENSITIVITY, SENSITIVITY_ORDER
44
-
45
- PROTECTED_LAYERS = ("self", "anchor")
46
- AUTO_PROTECT_IMPORTANCE = 0.70
47
- HISTORY_DIR = "_protected_history"
48
- AUDIT_FILE = "_protected_audit.jsonl"
49
-
50
- # 索引条目里的**门控三键**(键集单点定义):`_node_entry`(mdcg.py:1294-1298)与
51
- # `_stage`(mdcg.py:1848-1851)恒落这三键,值可为 None ⇒「键不存在」不是
52
- # 「未标记」的可靠判据(N213 同根,2026-09-28)。None = **索引未记录该标记**。
53
- _GATE_UNKNOWN_KEYS = ("protected", "immutable", "self_state")
54
-
55
-
56
- class ProtectionError(PermissionError):
57
- """受保护节点的写动作被拒绝。"""
58
-
59
-
60
- # ---------------------------------------------------------------- 判定
61
-
62
- # 生效条件:cg 具备可调用的 _maybe_reload_index 时先经 _probe 调一次(索引代际探活,异常静默);随后对任意 cg、node_id 返回 `(cg.index 或其假值时的 {})["nodes"]`(该键缺失或假值时为 `{}`)中以 node_id 为键的值,索引无此键时返回 None。
63
- def _entry(cg, node_id):
64
- """索引条目读取单点(判定前**代际探活**)。
65
-
66
- N213 同根(2026-09-28):保护面的全部判据(_fm / is_protected / is_immutable
67
- / guard_write / guard_forget / guard_move / stats)都经由本函数直读**本进程
68
- 内存索引**,而写面只有 `MdCG.add`(mdcg.py:1508)接了探活——删除(forget)、
69
- 降级搬迁(_move_layer)、统计与角色视图等出口全都没有。他进程(serve 常驻、
70
- autoflush=1 只 flush 不 close)新盖的 immutable/protected 在陈旧条目上不存在
71
- → 判定「未标记」→ 受保护节点被静默覆写/删除/搬迁,无快照无审计。
72
- 探活放在这里 = 保护面一次接线、全部出口同闸(签名未变时只有一次 stat +
73
- 一次 listdir;重载是稀疏事件)。同理 `_resolve_target` 的探活在本函数外层
74
- 成了冗余的一次廉价检查,保留不动。
75
- """
76
- _probe(cg) # 探活实现在 _probe(唯一),本函数不再内联
77
- return ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
78
-
79
- # 为何 _probe / known_nodes 放在本判定单点**之后**(而不是之前):
80
- # 既有裁定 md_cg/test_n212_n213_n224_generation_gates.py 的 6f 是**源码窗口**断言——
81
- # 窗口从本单点起、到下一个判定函数(_fm)的定义前为止,窗口内必须出现探活入口
82
- # (判据名:protect._entry 判定前代际探活(写/删/搬迁三面同闸))。把探活实现留在该
83
- # 窗口内,既满足既有裁定,又**不把探活复制成两份**(#413「同语义两处实现、只加固一侧」
84
- # 正是要避免的形态)。
85
- # ⚠ 本注释**不得**出现窗口两个端点的字面量(前者会改起点、后者会把窗口截断在此——
86
- # 实测踩过:注释里写了端点字面量 ⇒ 窗口在注释处结束、探活实现落在窗口外,6f 仍红)。
87
- def _probe(cg):
88
- """索引代际探活(**唯一实现**):_entry(单条目形态)与 known_nodes(集合形态)共用。
89
-
90
- 为何抽成一处:探活纪律一旦分叉,就会出现「这面记得探活、那面忘了」的族(#415 正是
91
- 如此——writepipe._gate_deps 与该函数同宗判据却漏了探活)。
92
- """
93
- _reload = getattr(cg, "_maybe_reload_index", None)
94
- if callable(_reload):
95
- try:
96
- _reload()
97
- except Exception: # noqa: BLE001 —— 探活失败不得阻断判定本身
98
- pass
99
-
100
-
101
- # 生效条件:先经 _probe(cg) 探活,随后返回 (cg.index 或其假值时的 {})["nodes"](该键缺失或假值时为 {})**本身**(只读契约:调用方不得就地修改);读面异常时返回 {},恒不抛。
102
- def known_nodes(cg):
103
- """**集合形态**的索引判据单点(判定前代际探活)—— #415。
104
-
105
- #415 根因(2026-10-16):writepipe._gate_deps 判「依赖目标是否存在」时**裸读**
106
- set((getattr(cg, "index", None) or {}).get("nodes") or {}),判前无探活 ⇒ 他进程
107
- (serve 常驻 / 另一实例)刚建的依赖目标在**陈旧条目**里不存在 ⇒ **合法写入被硬拒**
108
- (E051 依赖目标不存在)。与 #403「陈旧 ⇒ 误放行覆写」同族、后果相反。
109
-
110
- 与 _entry 同形同实现:**一次探活 + 返回同一数据面**(单条目 vs 集合两种形态)。
111
- 为什么不返回 set:每次判定复制一份 id 集合是 O(N),而本函数在**写入热路径**上;
112
- 返回索引**同一映射对象**并约定只读即可——判定只需要 in。
113
- """
114
- _probe(cg)
115
- try:
116
- return (getattr(cg, "index", None) or {}).get("nodes") or {}
117
- except Exception: # noqa: BLE001 —— 读面异常不阻断判定
118
- return {}
119
-
120
-
121
- # 生效条件:cg 索引中无 node_id 条目时返回 None;有条目时先取 layer/importance(缺 importance 键回落 0.5)/protected/protection_reason/immutable/self_state/importance_source(issue50-e:缺键读 None),仅当条目缺 protected 或 immutable、或(缺 self_state 且条目 layer∈PROTECTED_LAYERS)、或(条目 layer∈PROTECTED_LAYERS 且 _GATE_UNKNOWN_KEYS 中任一键的值为 None)时再经 cg.get(node_id) 用 frontmatter 覆盖这些键(cg.get 抛异常或返回假值时保留索引值;layer 取 frontmatter.layer or 索引 layer,importance 缺键时回落索引 importance)。
122
- def _fm(cg, node_id):
123
- """取判定所需的 frontmatter 字段;索引快照门控字段**未知**时回退读文件。"""
124
- e = _entry(cg, node_id)
125
- if e is None:
126
- return None
127
- fm = {
128
- "layer": e.get("layer"),
129
- "importance": e.get("importance", 0.5),
130
- "protected": e.get("protected"),
131
- "protection_reason": e.get("protection_reason"),
132
- "immutable": e.get("immutable"),
133
- "self_state": e.get("self_state"),
134
- # issue50-e:重要度来源进判定面(_node_entry/_stage 恒落该键,值可为
135
- # None ⇒「缺省来源」;老索引条目缺键时 .get() 同样得 None,等价缺省)。
136
- "importance_source": e.get("importance_source"),
137
- }
138
- # 回退读文件:索引快照缺字段时。self_state 只在受保护层(self/anchor)
139
- # 需要,回退代价被限制在少量节点上,不影响全量统计性能。
140
- _layer = str(e.get("layer") or "")
141
- need_fallback = ("protected" not in e or "immutable" not in e
142
- or ("self_state" not in e
143
- and _layer in PROTECTED_LAYERS))
144
- # N213 同根(2026-09-28):`_node_entry`/`_stage` **恒落**这三键(值可为
145
- # None)⇒ 上面的「缺键」判据在本仓所有构造点恒假、第四个析取子句不可达,
146
- # `_fm` 100% 信任索引、**从不重读文件**;索引里的 None 被当「未标记」采信,
147
- # 而「只改文件、不进索引写日志」的门控写点(`protect.mark` 一类)在陈旧
148
- # 条目里正是 None → guard_write/guard_forget/guard_move 静默放行。
149
- # 值为 None 即「索引未记录该标记」,唯一权威是文件——但读盘有代价,
150
- # 只在**受保护层**(self/anchor,节点数极少;层保护本身已拦 不可覆盖/
151
- # 不可遗忘,None 决定的是 self_state 豁免与层间搬迁的细粒度判定)无条件
152
- # 回退;非受保护层由「门控写点必须进写日志」承担(`mark` 已随本批接线,
153
- # `add(immutable=True)` 本就经 _stage),故不付全池读盘代价。
154
- if not need_fallback and _layer in PROTECTED_LAYERS \
155
- and any(e.get(_k) is None for _k in _GATE_UNKNOWN_KEYS):
156
- need_fallback = True
157
- if need_fallback:
158
- try:
159
- node = cg.get(node_id)
160
- except Exception:
161
- node = None
162
- if node:
163
- f2 = node.get("frontmatter") or {}
164
- fm["protected"] = f2.get("protected")
165
- fm["protection_reason"] = f2.get("protection_reason")
166
- fm["immutable"] = f2.get("immutable")
167
- fm["self_state"] = f2.get("self_state")
168
- fm["layer"] = f2.get("layer") or fm["layer"]
169
- fm["importance"] = f2.get("importance", fm["importance"])
170
- fm["importance_source"] = f2.get("importance_source")
171
- return fm
172
-
173
-
174
- # 生效条件:cg 索引无 node_id 条目(_fm 直接返回 None,不走回退读文件)时返回 (False, '');有条目时按 layer∈PROTECTED_LAYERS 返回 (True, 层保护);否则 protected is True 时返回 (True, protection_reason 或 '显式保护标记');否则 importance(缺失/假值/float 转换异常一律按 0.0)≥AUTO_PROTECT_IMPORTANCE 且 importance_source 为 None(键缺省)或 'hint' 时返回 (True, 重要性保护)——issue50-e:'heuristic' 等显式非 hint 来源不得由分数触发;其余返回 (False, '')。
175
- def is_protected(cg, node_id):
176
- """**不可遗忘**判定 → (是否受保护, 原因)。节点不存在返回 (False, "")。
177
-
178
- issue50-e(2026-10-02,使用者裁定「读面也只认显式来源」):按分自动保护
179
- 只对**缺省来源或显式 hint** 的分数生效。issue50-d 落盘了启发式真分
180
- (importance=0.7x + importance_source="heuristic"、不打保护位),若本
181
- 判定不看来源,读面(遗忘/搬迁闸、protect.check、scrub 净化与 confidence
182
- 校准的 skip 判定、stats 盘点)会把机器推断的分数重新认回受保护——写侧
183
- 「只落分不打位」被读侧单方面推翻。边界:
184
- ① 键缺省(None)= 存量节点(既有 cg.add(importance=0.9) 直写、维护路径
185
- 调分等从未有过该键)⇒ 行为一字不变——按「缺省即不认」会大规模改变
186
- 既有保护面,禁止;
187
- ② "hint" = 显式声明(写侧对 hint 过线本就打位,按分分支只是其无位形态
188
- 的兜底,语义不变);
189
- ③ "heuristic" 及其它显式来源不得由分数触发——机器推断的重要度不构成
190
- 不可遗忘的依据。层保护(PROTECTED_LAYERS)、fm.protected 位、
191
- is_immutable 一律不动;MERGE 强化(forgetting.reinforce 跨 0.7 置
192
- protected=True)是「重复确认」的显式动作,不经本分支,不受影响。
193
- """
194
- return is_protected_entry(_fm(cg, node_id))
195
-
196
-
197
- # 生效条件:fm 为假值时返回 (False, "");否则按三条真源判定——layer∈PROTECTED_LAYERS ⇒ 层保护;protected is True ⇒ 显式位;importance≥AUTO_PROTECT_IMPORTANCE 且 importance_source 为 None 或 "hint" ⇒ 按分保护;其余返回 (False, "")。
198
- def is_protected_entry(fm):
199
- """**条目口径**的「不可遗忘」判定单点(#431/#432/#468 与 lifecycle/trust 共用)。
200
-
201
- 与 `is_protected` **同源**:后者现在就是「取 fm 再调本函数」——
202
- 两口径是**同一个函数**(构造上唯一),不是两份实现靠腿互证。
203
-
204
- 为什么需要条目口径:weights(fm 条目)、consolidate(索引条目)、forgetting._tier_of
205
- (索引快照)、lifecycle/trust.stamp(裸 fm)四类调用方手里都**没有** (cg, node_id);
206
- 此前各自读 `e.get("protected")` 位(**窄**:漏层保护与按分保护)或漏来源门(**宽**),
207
- 一窄一宽正是「同一语义两份实现」的指纹。
208
- """
209
- if fm is None:
210
- return False, ""
211
- layer = str(fm.get("layer") or "")
212
- if layer in PROTECTED_LAYERS:
213
- return True, f"层保护:{layer}(不可遗忘层)"
214
- if fm.get("protected") is True:
215
- return True, str(fm.get("protection_reason") or "显式保护标记")
216
- try:
217
- imp = float(fm.get("importance") or 0.0)
218
- except Exception:
219
- imp = 0.0
220
- _src = fm.get("importance_source")
221
- if imp >= AUTO_PROTECT_IMPORTANCE and (_src is None or _src == "hint"):
222
- return True, f"重要性保护:importance={imp:.2f}≥{AUTO_PROTECT_IMPORTANCE}"
223
- # issue50-e(2026-10-02):按分保护**只认缺省或显式 hint 来源**——
224
- # 语义与边界见 docstring ①②③;_fm 恒带 importance_source 键(缺省读
225
- # None),老索引条目缺键同样落 None ⇒ 存量按分保护一字不变。
226
- return False, ""
227
-
228
-
229
- # 生效条件:cg 索引无 node_id 条目时返回 (False, '');有条目时若 self_state is True 一律返回 (False, '')(自我状态豁免);否则 layer∈PROTECTED_LAYERS 返回 (True, 层保护);否则 immutable is True 返回 (True, protection_reason 或 '显式不可覆盖标记');其余返回 (False, '')。
230
- def is_immutable(cg, node_id):
231
- """**不可覆盖**判定 → (是否不可篡改, 原因)。比不可遗忘更窄,只认强信号。
232
-
233
- 例外:自我状态卡(frontmatter.self_state is True)**必须可覆盖**——
234
- 自我状态本来就要随认知演化而更新,冻结它等于自我认知停止生长。
235
- 但它仍然 is_protected(不可遗忘),这是「不可遗忘 ≠ 不可覆盖」的延伸。
236
- 身份锚点不设此豁免,依旧两者皆禁。
237
- """
238
- fm = _fm(cg, node_id)
239
- if fm is None:
240
- return False, ""
241
- if fm.get("self_state") is True:
242
- return False, ""
243
- layer = str(fm.get("layer") or "")
244
- if layer in PROTECTED_LAYERS:
245
- return True, f"层保护:{layer}(不可篡改层)"
246
- if fm.get("immutable") is True:
247
- return True, str(fm.get("protection_reason") or "显式不可覆盖标记")
248
- return False, ""
249
-
250
-
251
- # ---------------------------------------------------------------- 留痕
252
-
253
- # 生效条件:对任意 cg、action、node_id、reason(actor/snapshot 缺省为 None)都构造含 t/action/node_id/reason/actor/snapshot 的 rec 并返回(#451:actor 经 _actor_of 单点解析——显式优先、其次库实例身份、无身份载体仍 None),,同时尝试追加写入 cg.root 下的 AUDIT_FILE,该写入抛出的任何异常被吞掉且不影响返回值。
254
- def _audit(cg, action, node_id, reason, actor=None, snapshot=None):
255
- rec = {"t": time.time(), "action": action, "node_id": node_id,
256
- "reason": reason, "actor": _actor_of(cg, actor), "snapshot": snapshot}
257
- try:
258
- # issue #547:本模块的审计台账(`_protected_audit.jsonl`)此前走 append_jsonl
259
- # 缺省路(可静默丢行)。#549 已把同一类账本(`_audit.jsonl`)切到 durable=True,
260
- # 判据是「审计属不能丢面」而不是「必须与别的模块同一个文件」——各模块各有台账,
261
- # 但标准一致:丢一行审计会让「发生过」与「没发生过」不可区分(T0 ③)。
262
- append_jsonl(os.path.join(cg.root, AUDIT_FILE), rec, durable=True)
263
- except Exception:
264
- pass
265
- return rec
266
-
267
- # 生效条件:actor 显式传入(非 None)时原样返回,否则返回 getattr(cg, "actor", None)(库实例身份;载体无该属性时为 None)——**不凭空造身份**。
268
- def _actor_of(cg, actor=None):
269
- """审计 actor 单点(issue #451):显式优先,其次库实例身份,两者皆无 → None。
270
-
271
- #451 病象:`_allow` → `_audit` 把 actor **原样**透传,而三守卫经 mdcg 的写面
272
- 调用时都不传 actor ⇒ `override_write` / `override_forget` / `override_move`
273
- 三类审计行 `actor: null`;同一出口的 `snapshot`(:295)与 `preimage`(:342)
274
- 两行却都有 actor ——「同一出口两种口径」。本函数把三处同语义表达收成**一个
275
- 真源**(:295/:342 一并改走本函数,语义逐位不变)。
276
-
277
- 边界(不许改弱):本函数只保证「**不凭空造身份**」——载体无 `.actor` 属性时
278
- 仍返回 None;而「actor 值是否*是*真正的那一方」由更上层身份源决定,本层看不见
279
- (无独立身份源)。
280
- """
281
- return actor if actor is not None else getattr(cg, "actor", None)
282
-
283
-
284
- # 生效条件:cg.get(node_id) 抛异常或返回假值时返回 None;否则在 cg.root/HISTORY_DIR/node_id 下以时间戳命名写入当前 frontmatter 与 content,_write_node 抛异常时返回 None,成功则追加一条 action="snapshot" 的审计(_audit,actor 取 cg.actor)并返回相对 cg.root 且以 '/' 分隔的路径。
285
- #: 前像文件名的**唯一命名单点**(issue #413)。
286
- #: 两侧(`snapshot()`=裸守卫 `_allow` 路径;`snapshot_preimage()`=执行时点前像)都必须经此处
287
- #: ——「同语义两处实现、只加固了一侧」正是 #413 的病象(与 #326-③ 的 `condition_vm` 双链同形)。
288
- #: 加固=**同秒命名冲突规避**:基名仍是 `%Y%m%d-%H%M%S`(既有守卫钉的形态不变),同秒内再次
289
- #: 拍摄时追加 `-<N>` 序号(已存在即递增)⇒ 先那张前像不再被后来者踩掉。`suffix` 供执行时点
290
- #: 前像附加微秒(`snapshot_preimage` 的既有形态,另一条既有守卫钉死)。
291
- def _preimage_name(d, suffix=""):
292
- base = time.strftime("%Y%m%d-%H%M%S", time.localtime()) + suffix
293
- p = os.path.join(d, base + ".md")
294
- _n = 1
295
- while os.path.exists(p):
296
- p = os.path.join(d, "%s-%d.md" % (base, _n))
297
- _n += 1
298
- return p
299
-
300
-
301
- def snapshot(cg, node_id):
302
- """把节点当前版本快照进 `_protected_history/<id>/<ts>.md`,返回相对路径。
303
-
304
- N228(2026-09-28):本函数此前**全文零审计**——而它是**落盘写入**(写
305
- `_protected_history/`,且这些快照是后续 override 快照链的基线)。经工具面
306
- `mdcg_protect(action="snapshot")`(此前只要求粗粒度 write)任何 can_write
307
- 角色都能在自己可读的节点上制造未审计磁盘写入(实测 `_audit.jsonl` 条数
308
- 8→8 不变)。本批两条收口:① 工具面 op 要求对齐规范出口(protect 面在
309
- `cg(op="protect")` 上级为 designer 专属);② 快照成功即留痕(本函数内,
310
- 两条入口——工具面与 `guard_*` 的 `_allow`——都覆盖;`_allow` 路径会有
311
- 「snapshot + 具体守卫动作」两条审计,属如实记录而非重复计数)。
312
- """
313
- try:
314
- node = cg.get(node_id)
315
- except Exception:
316
- node = None
317
- if not node:
318
- return None
319
- d = os.path.join(cg.root, HISTORY_DIR, node_id)
320
- os.makedirs(d, exist_ok=True)
321
- p = _preimage_name(d) # issue #413:经**同一加固单点**(原为裸秒级名,同秒互踩)
322
- try:
323
- cg._write_node(node.get("id"), p, node.get("frontmatter") or {},
324
- node.get("content") or "")
325
- except Exception:
326
- return None
327
- rel = os.path.relpath(p, cg.root).replace("\\", "/")
328
- _audit(cg, "snapshot", node_id, "显式快照(%s)" % rel,
329
- actor=_actor_of(cg), snapshot=rel)
330
- return rel
331
-
332
-
333
- # 生效条件:cg.get(node_id) 抛异常或返回假值时返回 None(与 snapshot 同口径——目标不存在=动作不会发生,由调用方按既有错误路径处理);否则在 cg.root/HISTORY_DIR/node_id 下以「秒级时间戳-微秒后缀」命名写入当前 frontmatter 与 content(写盘形态与 snapshot 逐位一致:同目录、同 nodefile 序列化、同 _write_node 封装钩子),_write_node 抛异常时返回 None,成功则追加一条 action="preimage" 的审计(reason 交代动作类与 pid)并返回相对 cg.root 且以 '/' 分隔的路径;
334
- def snapshot_preimage(cg, node_id, action="", pid=None, reason="", actor=None):
335
- """执行时点前像(设计 §四「回滚原语通用化」:快照面推广为一切 C/D/B)。
336
-
337
- 与 `snapshot()` 的关系(**面复用、语义泛化**,既有行为一字不动):
338
- `_protected_history/<id>/` + `_protected_audit.jsonl` 这一对从「仅受保护节点」
339
- 推广为「一切 C/D/B 动作」的**前像面**——本函数是新入口,`snapshot()` /
340
- `guard_*` 的既有形态(文件名 `%Y%m%d-%H%M%S.md`、审计 action="snapshot"、
341
- reason「显式快照(rel)」、覆盖路径快照数)**不改一行**(守卫钉死)。
342
- 两条差别都是为「执行时点前像」的场景补强:
343
- · 文件名带微秒后缀——同一节点的多个变更单可能在**同一秒**内先后执行,
344
- 秒级名会互相覆盖(探针实测:同秒二次 snapshot 返回同一路径)——前像
345
- 被后来的前像踩掉,早先那张的回滚句柄就指向错误时点的内容;
346
- · 审计 action="preimage" 且 reason 交代动作类/pid——回滚与 §七 R3 读数
347
- (「存在实测回滚记录」)要能把「变更单前像」与既有显式快照区分开。
348
-
349
- 为什么前像必须在**执行时点**拍(设计 §四 明文):变更单在提议时点构造,
350
- 从提议到 accept 之间目标可能被第三方改动——回滚必须撤销**本变更本身**,
351
- 而不是一并抹掉第三方改动。故由执行桥(`mdcos._mutation_execute`)在动作
352
- 原语落盘**之前**拍摄,作为载荷 `before` 字段(执行时点快照引用)。
353
-
354
- 边界(如实):加密库(覆写了 `_seal_content` 的实例)里本文件的密文层
355
- 因每次封装熵不同**不保证逐字节可复现**——前像的语义是「明文内容 + 结构
356
- 的可恢复」,逐字节比对在非加密库(含一切守卫合成库)上成立(探针实测)。
357
- """
358
- try:
359
- node = cg.get(node_id)
360
- except Exception:
361
- node = None
362
- if not node:
363
- return None
364
- d = os.path.join(cg.root, HISTORY_DIR, node_id)
365
- os.makedirs(d, exist_ok=True)
366
- p = _preimage_name(d, "-%06d" % (time.time_ns() // 1000 % 1000000)) # issue #413:同一单点
367
- try:
368
- cg._write_node(node.get("id"), p, node.get("frontmatter") or {},
369
- node.get("content") or "")
370
- except Exception:
371
- return None
372
- rel = os.path.relpath(p, cg.root).replace("\\", "/")
373
- _audit(cg, "preimage", node_id,
374
- reason or ("执行时点前像(动作类 %s,pid=%s)"
375
- % (action or "?", pid or "?")),
376
- actor=_actor_of(cg, actor),
377
- snapshot=rel)
378
- return rel
379
-
380
-
381
- # 生效条件:cg.root/HISTORY_DIR/node_id 不是目录时返回 [];是目录时返回该目录下以 .md 结尾(不递归)的文件按名称排序后的 `HISTORY_DIR/node_id/文件名` 列表,无匹配文件则列表为空。
382
- def history(cg, node_id):
383
- """受保护节点的历史版本列表(按时间升序)。"""
384
- d = os.path.join(cg.root, HISTORY_DIR, node_id)
385
- if not os.path.isdir(d):
386
- return []
387
- out = [f for f in os.listdir(d) if f.endswith(".md")]
388
- out.sort()
389
- return [f"{HISTORY_DIR}/{node_id}/{f}" for f in out]
390
-
391
-
392
- # ---------------------------------------------------------------- 守卫
393
-
394
- # 生效条件:对任意 cg、node_id、why、action、override、actor——先拍前像(`snapshot`);**前像不可得**
395
- # (写者读不到该节点、或前像落盘失败 ⇒ `snapshot` 返回 None)时**fail-closed**:留一条
396
- # `<action>_denied` 审计行并抛 `ProtectionError`,不返回放行字典;前像可得时返回
397
- # {'override': True, 'reason': why, 'snapshot': snap, 'audit': _audit(...)}。
398
- def _allow(cg, node_id, why, action, override, actor):
399
- """受保护节点 override 的唯一放行点(前像不可得 ⇒ 拒)。
400
-
401
- issue #413 站点2(2026-10-16 实测,HEAD dd8a9640):此前 `snapshot()` 返回 None
402
- (该身份**读不到**这个节点,例如 self 层 private 节点 + internal 档写者、或跨会话)
403
- 时**照样返回 `override: True`** ⇒ 覆写静默落盘而 `_protected_history/<id>/` 一件不落、
404
- 审计行 `snapshot: null`:受保护节点的原内容**不可回滚地消失**(N228 逐字:「这些快照
405
- 是后续 override 快照链的基线」)。实测四写者变体里 `designer/internal/sessB` 走到该
406
- 分支:覆写后节点 `sensitivity` 由 private 变 internal、原文(AEAD 密文)无从恢复,
407
- internal 档读者随后可读。
408
- ⇒ 判据:**override 的价值来自「可回滚」,前像拍不出来就不该放行**(与 N228 快照留痕、
409
- 与 #413 站点1 的同秒不踩踏同一族)。需要放行的内部路径应改用能读到该节点的主语
410
- (或先 `cg.unlock`/换身份),而不是让不可回滚的覆写通过。
411
- """
412
- snap = snapshot(cg, node_id)
413
- if snap is None:
414
- rec = _audit(cg, action + "_denied", node_id,
415
- why + ";前像不可得 ⇒ fail-closed(issue #413 站点2)", actor, None)
416
- raise ProtectionError(
417
- f"节点 {node_id} 受保护({why});override 需要前像,但前像不可得"
418
- f"(该身份读不到此节点,或前像落盘失败)——本次覆写/搬迁/遗忘被拒(fail-closed)"
419
- f"(N228/#413-2:无前像的 override 不可回滚)")
420
- rec = _audit(cg, action, node_id, why, actor, snap)
421
- return {"override": True, "reason": why, "snapshot": snap, "audit": rec}
422
-
423
-
424
- # 生效条件:is_immutable(cg, node_id) 为假(含 self_state is True、layer 不在 PROTECTED_LAYERS 且 immutable 非 True 的情形)时返回 None;为真时 override 取真值则返回 _allow(..., 'override_write', override, actor),否则抛出 ProtectionError;layer 形参不参与该判定。
425
- def guard_write(cg, node_id, layer=None, override=False, actor=None):
426
- """覆盖既有节点前的守卫(只认**不可覆盖**信号)。
427
-
428
- 新节点 / 未标记 immutable 的节点直接放行(返回 None)。
429
- importance≥0.7 只保证「不可遗忘」,不阻断系统自身的幂等更新。
430
- """
431
- prot, why = is_immutable(cg, node_id)
432
- if not prot:
433
- return None
434
- if override:
435
- return _allow(cg, node_id, why, "override_write", override, actor)
436
- raise ProtectionError(
437
- f"节点 {node_id} 受写保护({why});覆盖需显式 override=True")
438
-
439
-
440
- # 生效条件:is_protected(cg, node_id) 为假时返回 None;为真时 override 取真值则返回 _allow(..., 'override_forget', override, actor),否则抛出 ProtectionError。
441
- def guard_forget(cg, node_id, override=False, actor=None):
442
- """删除前的守卫。受保护节点 = 不可遗忘。"""
443
- prot, why = is_protected(cg, node_id)
444
- if not prot:
445
- return None
446
- if override:
447
- return _allow(cg, node_id, why, "override_forget", override, actor)
448
- raise ProtectionError(
449
- f"节点 {node_id} 不可遗忘({why});删除需显式 override=True")
450
-
451
-
452
- # 生效条件:is_protected(cg, node_id) 为假时返回 None;为真且 to_layer∈PROTECTED_LAYERS(保护层间互搬)时也返回 None;为真且 to_layer 不在 PROTECTED_LAYERS 时,override 取真值则返回 _allow(..., 'override_move', override, actor),否则抛出 ProtectionError。
453
- def guard_move(cg, node_id, to_layer, override=False, actor=None):
454
- """降级/搬迁前的守卫:受保护节点不得被移出保护层。"""
455
- prot, why = is_protected(cg, node_id)
456
- if not prot:
457
- return None
458
- if to_layer in PROTECTED_LAYERS:
459
- return None # 保护层之间互搬仍受保护,放行
460
- if override:
461
- return _allow(cg, node_id, why, "override_move", override, actor)
462
- raise ProtectionError(
463
- f"节点 {node_id} 受写保护({why});降级移出保护层需显式 override=True")
464
-
465
-
466
- # 生效条件:cg.get(node_id) 抛异常时返回 None(读面失败不阻断判据本身),否则原样返回其读面结果(含 None=不可读/不存在)。
467
- def _safe_get(cg, node_id):
468
- """`cg.get` 的**不抛**包装(层闸判据用;读面失败不得把闸炸穿)。"""
469
- try:
470
- return cg.get(node_id)
471
- except Exception: # noqa: BLE001 —— 读面失败不阻断判据本身
472
- return None
473
-
474
-
475
- # 生效条件:cg 具备可调用的 _maybe_reload_index 时先调一次;层取形参 layer、索引条目 layer、节点 frontmatter layer 中首个真值(皆假值回落 "knowledge",与 require_layer_write 缺省同口径);敏感度取形参 sensitivity、索引条目 sensitivity、节点 frontmatter sensitivity 中首个真值;三来源皆无有效密级时回落 security.DEFAULT_SENSITIVITY(**已知 fail-open 代价,裁定与边界见函数内注释与 test_issue450_writegate_unknown_sens**);返回 (层, 敏感度) 二元组。
476
- def _resolve_target(cg, node_id, layer=None, sensitivity=None):
477
- """既有节点写面的「层 / 敏感度」解析**单点**(不设第二份口径)。
478
-
479
- 索引代际探活(N195 同族):写面直读本进程内存索引,他进程刚写入/搬迁的节点
480
- 在本进程索引中不存在、或层位陈旧 → 解析出的层不是真层,层闸会**静默失效**
481
- (「越权改 knowledge」被当成「同层正当写」放行)。故进入判定前先探活一次
482
- (签名未变时只有一次 stat)。
483
- """
484
- _reload = getattr(cg, "_maybe_reload_index", None)
485
- if callable(_reload):
486
- _reload()
487
- e = _entry(cg, node_id) or {}
488
- _layer = layer or e.get("layer")
489
- _sens = sensitivity or e.get("sensitivity")
490
- _node = None
491
- _node_read = False
492
- if not _layer or not _sens:
493
- _node = _safe_get(cg, node_id)
494
- _node_read = True
495
- if _node:
496
- f = _node.get("frontmatter") or {}
497
- _layer = _layer or f.get("layer")
498
- _sens = _sens or f.get("sensitivity")
499
- # ★ issue #450(fail-closed 版):**「缺 sensitivity 键」是 unknown,不是 internal。**
500
- # ① 为什么要查盘面:`MdCGSecure._scan_nodes` 用
501
- # `e["sensitivity"] = fm.get("sensitivity") or DEFAULT_SENSITIVITY`
502
- # 回填索引条目——回填把「未知」擦成 `internal`,层闸此后**再也看不到**
503
- # 缺键信号。故当生效值恰为 `DEFAULT_SENSITIVITY` 时回读一次 frontmatter,
504
- # 确认该键**是否真的声明过**(只读,不改盘、不写索引)。
505
- # ② 为什么不改 fail-closed(裁定 2026-10-18,实测后):真实密级可能是
506
- # restricted/private/secret ⇒ 回落 `internal` 确实会放行(fail-open,越权),
507
- # 方向与 `#447`/`_readable` 的「密级未知按 secret」一致。但本仓写面的**常态**
508
- # 是「不声明 sensitivity」(缺省即 internal),fail-closed 会把全库 legacy
509
- # 节点对非 secret 身份变成只读——全量链实测 3 个用例当场转红
510
- # (test_p31_insight / test_p30_maintain / test_p29_session_ingest_export)。
511
- # 功能代价 > 它堵的越权(后者需攻击者已持 internal clearance 且目标真实
512
- # 密级更高,即 #359 记的「private 已被记录」那类;#359 的裁定只绑定 merge
513
- # 场景,本处沿用其「unknown 视同缺省档」口径但不外推)。
514
- # 密级更高),故按「成本>收益取小」**保持 internal 回落**,把边界与代价
515
- # 钉在守卫 `md_cg/test_issue450_writegate_unknown_sens.py`。
516
- # ③ 何时改判:出现「缺键且真实密级应为高密级」的实例(届时按 fail-closed 改,
517
- # 并同批把 legacy 节点回填 sensitivity,否则就是上面的全库只读)。
518
- # 边界:节点**不存在** ⇒ 新写入面,沿用 `DEFAULT_SENSITIVITY`(保护的是
519
- # 「既有节点不被降档覆写」,不是「禁止新建」);节点存在但盘面读不出
520
- # (加密且无密钥/损坏)⇒ 无法确认缺键,保留索引值(不把「读不动」当成
521
- # 「缺键」而误锁全库)。
522
- # 已知缺口:读面·近期事件(`mdcos.py` 的 `recent_events`)= `#447`,本件不覆盖。
523
- if _sens == DEFAULT_SENSITIVITY:
524
- if not _node_read:
525
- _node = _safe_get(cg, node_id)
526
- if _node is not None:
527
- _fm = _node.get("frontmatter") or {}
528
- if not _fm.get("sensitivity"):
529
- _sens = None
530
- if not _sens:
531
- # 既有节点(索引有条目或节点可读)而密级不可判 ⇒ 最保守档;
532
- # 节点不存在(新写入面)⇒ 缺省档(保护面不拦新建)。
533
- # ★ 裁定(2026-10-18,全量链实测后):**保持 internal 回落**,不改 fail-closed。
534
- # 代价读数:本件首版曾按 fail-closed 返回 SENSITIVITY_ORDER[-1],全量链
535
- # md_cg 随即 3 个用例转红(test_p31_insight / test_p30_maintain /
536
- # test_p29_session_ingest_export,均因「既有节点未声明 sensitivity ⇒ 被
537
- # 判成 secret ⇒ internal 身份的同 id 改写被拒」)。实测 blast radius:
538
- # 本仓大多数节点**从不声明 sensitivity**(写面缺省即 internal),fail-closed
539
- # 等于把全库 legacy 节点对非 secret 身份变成只读——功能代价大于它堵的
540
- # fail-open(后者需要攻击者已持 internal clearance 且目标真实密级更高)。
541
- # 故按「成本>收益取小」维持原语义,并把边界钉在守卫
542
- # `md_cg/test_issue450_writegate_unknown_sens.py`(登记 + 代价 + 何时改判)。
543
- return _layer or "knowledge", DEFAULT_SENSITIVITY
544
- return _layer or "knowledge", _sens
545
-
546
-
547
- # 生效条件:经 _resolve_target 解析出节点真层与敏感度后,cg.principal 非 None 且具备 require_layer_write 时调 principal.require_layer_write(layer, sensitivity)(越权抛 AccessDenied),返回解析出的层;cg 无 principal(裸 MdCG)时不做任何判定。
548
- def require_layer(cg, node_id, layer=None, sensitivity=None, actor=None):
549
- """既有节点写面的 **principal 层闸**单点(不含引擎级保护闸)。
550
-
551
- N209(2026-09-28,同族未接线的相邻写面入口):「只有 `falsified` 一态接了
552
- 层闸」之外的三条写面全程只认管理位/保护位、**不认层白名单**——
553
- `MdCGSecure.verify` 的 confirmed/weakened 分支直写被验证节点本体
554
- (`md_cg/mdcg.py:3502`)、`trust.set_state`(验证态唯一推进入口 ⇒ 依赖者
555
- `mark_dependents` 与 `set_verification` 两条写路,`md_cg/trust.py:697-698`)、
556
- `MdCG._move_layer`(降级搬迁 = 源层一次删除写 + 目标层一次新增写,
557
- `md_cg/mdcg.py` 的 `MdCG._move_layer`)。后果:持 verify 令牌(`layers_allow` 仅
558
- rejected/contextual、forbidden 明列「knowledge/self/anchor 层」)即可改写
559
- knowledge 层节点本体、把 self 层依赖者置 doubted、把 knowledge 节点搬出层。
560
- 层闸口径与 `MdCGSecure.add`/`add_rejected` 一致(`md_cg/mdcos.py:3889`/`:3898`)。
561
- """
562
- _layer, _sens = _resolve_target(cg, node_id, layer=layer,
563
- sensitivity=sensitivity)
564
- p = getattr(cg, "principal", None)
565
- if p is not None and hasattr(p, "require_layer_write"):
566
- p.require_layer_write(_layer, _sens)
567
- return _layer
568
-
569
-
570
- # 生效条件:先经 require_layer(cg, node_id, layer, sensitivity) 做 principal 层闸(越权抛 AccessDenied),再委托 guard_write(cg, node_id, layer=解析层, override=override, actor=actor) 并返回其结果。
571
- def guard_overwrite(cg, node_id, layer=None, sensitivity=None,
572
- override=False, actor=None):
573
- """既有节点**覆写**前的统一双闸:principal 层写权限 + 引擎级写保护。
574
-
575
- N197/N208(2026-09-28):「同一身份对**同层**的 `add` 已被
576
- `require_layer_write` 拒绝,但直调 `cg._write_node` 的写面照样落盘」——
577
- 层闸被同一库的两条出口口径不一致地绕开。与 N131(review 队列 merge 面)
578
- 同序同错型:principal 层写闸在先(对照 `MdCGSecure.add` :3889),引擎级
579
- `guard_write` 在后(对照 `MdCG.add` :1509)。任何覆写**既有节点**的写面都
580
- 必须先过这里,否则 self/anchor 层与 immutable 节点被无痕覆写:不抛错、不落
581
- `_protected_history` 快照、不写 `_protected_audit.jsonl`。
582
-
583
- 索引代际探活(N195 同族):写面直读本进程内存索引,他进程刚置的保护位在本
584
- 进程索引中不存在 → `is_immutable` 的 `_entry` 得 None → 判 False,两道闸
585
- 会**同时静默失效**。故进入判定前先探活一次(签名未变时只有一次 stat);
586
- 解析与层闸由 `require_layer` 同一单点承担。
587
- """
588
- _layer = require_layer(cg, node_id, layer=layer, sensitivity=sensitivity)
589
- return guard_write(cg, node_id, layer=_layer, override=override, actor=actor)
590
-
591
-
592
- # 生效条件:cg.get(node_id) 抛异常或返回假值时返回 {'ok': False, 'error': 'node_not_found', 'node_id': node_id}(负路由,形态对齐 trust.set_state:692);否则把 protected=True 与 protection_reason=reason 写入 cg.root 下 node["path"](该键缺失即抛 KeyError)对应的 frontmatter 并保持原 content,随后门条目存在时同步其 protected/protection_reason 并把该条目并入索引写日志(_dirty 标脏 + flush,失败静默),返回 {'node_id': node_id, 'protected': True, 'reason': reason}。
593
- def mark(cg, node_id, reason):
594
- """给节点打上 `protected=True` 标记(写回 frontmatter,不动 content)。
595
-
596
- 节点不存在时返回**负路由** `{"ok": False, "error": "node_not_found",
597
- "node_id": node_id}`(与 `trust.set_state` 的不存在分支逐键同形),
598
- 不再裸返回 None(H9④ 前):None 与「成功」在调用方眼里都非 dict,
599
- `mcp_server._protect_call` 直接把它序列化成 `null` 回给 MCP 客户端
600
- ——不存在的 node_id 被读成「打标成功」,而 `_write_node` 从未发生。
601
- 调用方分流:失败看 `r.get("ok") is False` / `"error" in r`,
602
- 成功路径的返回键**不变**(node_id / protected / reason,无 ok 键)。
603
- """
604
- try:
605
- node = cg.get(node_id)
606
- except Exception:
607
- node = None
608
- if not node:
609
- return {"ok": False, "error": "node_not_found", "node_id": node_id}
610
- fm = node.get("frontmatter") or {}
611
- fm["protected"] = True
612
- fm["protection_reason"] = reason
613
- cg._write_node(node_id, os.path.join(cg.root, node["path"]),
614
- fm, node.get("content") or "")
615
- e = _entry(cg, node_id)
616
- if e is not None:
617
- e["protected"] = True
618
- e["protection_reason"] = reason
619
- # N213 同根(2026-09-28):保护位是**门控字段**,只改内存条目 + 文件而
620
- # 不进索引写日志 ⇒ 他进程(以及本进程 compact 前的重载)把该节点当
621
- # 「未标记」→ guard_forget / guard_move 静默放行。与 add 同口径:
622
- # `_dirty[nid] = e` 标脏(**不走 _stage**——它会重复累加该桶计数)
623
- # 并 flush,使日志成为跨进程可见的代际载体。日志化失败不阻断打标本身
624
- # (文件已改,下一次 compact/rebuild 的 _scan_nodes 会带上该标记)。
625
- _dirty = getattr(cg, "_dirty", None)
626
- if isinstance(_dirty, dict):
627
- _dirty[node_id] = e
628
- _flush = getattr(cg, "flush", None)
629
- if callable(_flush):
630
- try:
631
- _flush()
632
- except Exception: # noqa: BLE001 —— 落账失败不阻断打标
633
- pass
634
- return {"node_id": node_id, "protected": True, "reason": reason}
635
-
636
-
637
- # 生效条件:遍历 cg.index.nodes(或其假值时的空字典)的每个键,对 is_protected 为真的节点计入 ids 并按 layer(缺失/假值记为 '?')累加 by_layer,其中原因串含 "importance=" 或以 "重要性保护" 开头的计入 auto_by_importance,对 is_immutable 为真的计入 immutable_ids,返回含 protected_count/immutable_count/by_layer/auto_by_importance/ids/immutable_ids 的字典。
638
- def stats(cg):
639
- """保护面盘点:不可遗忘数 / 不可覆盖数 / 分层分布 / 自动保护命中数。"""
640
- nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
641
- by_layer, ids, auto, immutable = {}, [], 0, []
642
- for nid in list(nodes):
643
- prot, why = is_protected(cg, nid)
644
- if prot:
645
- ids.append(nid)
646
- layer = str(nodes[nid].get("layer") or "?")
647
- by_layer[layer] = by_layer.get(layer, 0) + 1
648
- if "importance=" in why or why.startswith("重要性保护"):
649
- auto += 1
650
- imm, _ = is_immutable(cg, nid)
651
- if imm:
652
- immutable.append(nid)
653
- return {"protected_count": len(ids), "immutable_count": len(immutable),
654
- "by_layer": by_layer, "auto_by_importance": auto, "ids": ids,
1
+ # -*- coding: utf-8 -*-
2
+ """md_cg · 自我层 / 锚点层写保护(不可遗忘)
3
+
4
+ 理论出处(全部来自本仓已有文档,非外部发明):
5
+
6
+ · `docs/mdcg/灵枢_自我层定义.md:6`
7
+ SELF 层 = 身份 + 价值观 + 图接口,**不可遗忘**、跨会话自动加载。
8
+ 任何实例都能改写自我层 = 自我认知可被任意覆写,与「自我」定义冲突。
9
+ · `docs/mdcg/认知图_MD目录方案_v0.1.md:53`
10
+ `anchor/ # 锚点层(不可遗忘,保护)`
11
+ · `docs/mdcg/认知图_MD目录方案_v0.1.md:412-416`
12
+ 「importance 提升(保护:不可遗忘记入 anchor/ 且**受保护标记**)」
13
+ · `docs/mdcg/tool_table_v0.3.0.md:15`
14
+ 「importance_hint 可显式提示重要性(**≥0.7 触发不可遗忘保护**)」
15
+
16
+ 三层保护(任一命中即受保护):
17
+
18
+ ┌ 1. 层保护 layer ∈ {self, anchor}
19
+ ├ 2. 显式标记 frontmatter.protected == True
20
+ └ 3. 重要性保护 importance ≥ 0.70(写入时自动打标)
21
+
22
+ **关键区分:不可遗忘 ≠ 不可覆盖。**
23
+ · 不可遗忘(forget / 降级搬迁):层保护 + protected 标记 + importance≥0.7 三者都拦。
24
+ 文档原话是「不可遗忘」「触发不可遗忘保护」——重点是**别弄丢**。
25
+ · 不可覆盖(覆写同一 id):只拦 层保护 + 显式 immutable 标记。
26
+ 因为 goal_*/fix_*/kp_* 这类 id 是内容派生、由系统自身幂等更新,
27
+ 若 importance≥0.7 就禁止覆写,会把正常的状态更新全部误伤。
28
+ 自我认知之所以不可篡改,靠的是 **self/anchor 层**这个强信号,
29
+ 而不是"重要性高"这个弱信号。
30
+
31
+ 受保护节点的动作必须显式 `override=True`:动作前先把旧版本快照进
32
+ `_protected_history/<id>/<时间戳>.md`,并把「谁、何时、为何」记进
33
+ `_protected_audit.jsonl`——保护不等于黑箱。
34
+
35
+ 注意:新建(索引中不存在的节点)不受限。保护的是「已有自我认知不被改/删」,
36
+ 不是「禁止产生自我认知」,否则审计节点等正常写入会被误伤。
37
+ """
38
+ import os
39
+ import time
40
+
41
+ from . import nodefile
42
+ from .fsutil import append_jsonl, atomic_write
43
+ from .security import DEFAULT_SENSITIVITY, SENSITIVITY_ORDER
44
+
45
+ PROTECTED_LAYERS = ("self", "anchor")
46
+ AUTO_PROTECT_IMPORTANCE = 0.70
47
+ HISTORY_DIR = "_protected_history"
48
+ AUDIT_FILE = "_protected_audit.jsonl"
49
+
50
+ # 索引条目里的**门控三键**(键集单点定义):`_node_entry`(mdcg.py:1294-1298)与
51
+ # `_stage`(mdcg.py:1848-1851)恒落这三键,值可为 None ⇒「键不存在」不是
52
+ # 「未标记」的可靠判据(N213 同根,2026-09-28)。None = **索引未记录该标记**。
53
+ _GATE_UNKNOWN_KEYS = ("protected", "immutable", "self_state")
54
+
55
+
56
+ class ProtectionError(PermissionError):
57
+ """受保护节点的写动作被拒绝。"""
58
+
59
+
60
+ # ---------------------------------------------------------------- 判定
61
+
62
+ # 生效条件:cg 具备可调用的 _maybe_reload_index 时先经 _probe 调一次(索引代际探活,异常静默);随后对任意 cg、node_id 返回 `(cg.index 或其假值时的 {})["nodes"]`(该键缺失或假值时为 `{}`)中以 node_id 为键的值,索引无此键时返回 None。
63
+ def _entry(cg, node_id):
64
+ """索引条目读取单点(判定前**代际探活**)。
65
+
66
+ N213 同根(2026-09-28):保护面的全部判据(_fm / is_protected / is_immutable
67
+ / guard_write / guard_forget / guard_move / stats)都经由本函数直读**本进程
68
+ 内存索引**,而写面只有 `MdCG.add`(mdcg.py:1508)接了探活——删除(forget)、
69
+ 降级搬迁(_move_layer)、统计与角色视图等出口全都没有。他进程(serve 常驻、
70
+ autoflush=1 只 flush 不 close)新盖的 immutable/protected 在陈旧条目上不存在
71
+ → 判定「未标记」→ 受保护节点被静默覆写/删除/搬迁,无快照无审计。
72
+ 探活放在这里 = 保护面一次接线、全部出口同闸(签名未变时只有一次 stat +
73
+ 一次 listdir;重载是稀疏事件)。同理 `_resolve_target` 的探活在本函数外层
74
+ 成了冗余的一次廉价检查,保留不动。
75
+ """
76
+ _probe(cg) # 探活实现在 _probe(唯一),本函数不再内联
77
+ return ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
78
+
79
+ # 为何 _probe / known_nodes 放在本判定单点**之后**(而不是之前):
80
+ # 既有裁定 md_cg/test_n212_n213_n224_generation_gates.py 的 6f 是**源码窗口**断言——
81
+ # 窗口从本单点起、到下一个判定函数(_fm)的定义前为止,窗口内必须出现探活入口
82
+ # (判据名:protect._entry 判定前代际探活(写/删/搬迁三面同闸))。把探活实现留在该
83
+ # 窗口内,既满足既有裁定,又**不把探活复制成两份**(#413「同语义两处实现、只加固一侧」
84
+ # 正是要避免的形态)。
85
+ # ⚠ 本注释**不得**出现窗口两个端点的字面量(前者会改起点、后者会把窗口截断在此——
86
+ # 实测踩过:注释里写了端点字面量 ⇒ 窗口在注释处结束、探活实现落在窗口外,6f 仍红)。
87
+ def _probe(cg):
88
+ """索引代际探活(**唯一实现**):_entry(单条目形态)与 known_nodes(集合形态)共用。
89
+
90
+ 为何抽成一处:探活纪律一旦分叉,就会出现「这面记得探活、那面忘了」的族(#415 正是
91
+ 如此——writepipe._gate_deps 与该函数同宗判据却漏了探活)。
92
+ """
93
+ _reload = getattr(cg, "_maybe_reload_index", None)
94
+ if callable(_reload):
95
+ try:
96
+ _reload()
97
+ except Exception: # noqa: BLE001 —— 探活失败不得阻断判定本身
98
+ pass
99
+
100
+
101
+ # 生效条件:先经 _probe(cg) 探活,随后返回 (cg.index 或其假值时的 {})["nodes"](该键缺失或假值时为 {})**本身**(只读契约:调用方不得就地修改);读面异常时返回 {},恒不抛。
102
+ def known_nodes(cg):
103
+ """**集合形态**的索引判据单点(判定前代际探活)—— #415。
104
+
105
+ #415 根因(2026-10-16):writepipe._gate_deps 判「依赖目标是否存在」时**裸读**
106
+ set((getattr(cg, "index", None) or {}).get("nodes") or {}),判前无探活 ⇒ 他进程
107
+ (serve 常驻 / 另一实例)刚建的依赖目标在**陈旧条目**里不存在 ⇒ **合法写入被硬拒**
108
+ (E051 依赖目标不存在)。与 #403「陈旧 ⇒ 误放行覆写」同族、后果相反。
109
+
110
+ 与 _entry 同形同实现:**一次探活 + 返回同一数据面**(单条目 vs 集合两种形态)。
111
+ 为什么不返回 set:每次判定复制一份 id 集合是 O(N),而本函数在**写入热路径**上;
112
+ 返回索引**同一映射对象**并约定只读即可——判定只需要 in。
113
+ """
114
+ _probe(cg)
115
+ try:
116
+ return (getattr(cg, "index", None) or {}).get("nodes") or {}
117
+ except Exception: # noqa: BLE001 —— 读面异常不阻断判定
118
+ return {}
119
+
120
+
121
+ # 生效条件:cg 索引中无 node_id 条目时返回 None;有条目时先取 layer/importance(缺 importance 键回落 0.5)/protected/protection_reason/immutable/self_state/importance_source(issue50-e:缺键读 None),仅当条目缺 protected 或 immutable、或(缺 self_state 且条目 layer∈PROTECTED_LAYERS)、或(条目 layer∈PROTECTED_LAYERS 且 _GATE_UNKNOWN_KEYS 中任一键的值为 None)时再经 cg.get(node_id) 用 frontmatter 覆盖这些键(cg.get 抛异常或返回假值时保留索引值;layer 取 frontmatter.layer or 索引 layer,importance 缺键时回落索引 importance)。
122
+ def _fm(cg, node_id):
123
+ """取判定所需的 frontmatter 字段;索引快照门控字段**未知**时回退读文件。"""
124
+ e = _entry(cg, node_id)
125
+ if e is None:
126
+ return None
127
+ fm = {
128
+ "layer": e.get("layer"),
129
+ "importance": e.get("importance", 0.5),
130
+ "protected": e.get("protected"),
131
+ "protection_reason": e.get("protection_reason"),
132
+ "immutable": e.get("immutable"),
133
+ "self_state": e.get("self_state"),
134
+ # issue50-e:重要度来源进判定面(_node_entry/_stage 恒落该键,值可为
135
+ # None ⇒「缺省来源」;老索引条目缺键时 .get() 同样得 None,等价缺省)。
136
+ "importance_source": e.get("importance_source"),
137
+ }
138
+ # 回退读文件:索引快照缺字段时。self_state 只在受保护层(self/anchor)
139
+ # 需要,回退代价被限制在少量节点上,不影响全量统计性能。
140
+ _layer = str(e.get("layer") or "")
141
+ need_fallback = ("protected" not in e or "immutable" not in e
142
+ or ("self_state" not in e
143
+ and _layer in PROTECTED_LAYERS))
144
+ # N213 同根(2026-09-28):`_node_entry`/`_stage` **恒落**这三键(值可为
145
+ # None)⇒ 上面的「缺键」判据在本仓所有构造点恒假、第四个析取子句不可达,
146
+ # `_fm` 100% 信任索引、**从不重读文件**;索引里的 None 被当「未标记」采信,
147
+ # 而「只改文件、不进索引写日志」的门控写点(`protect.mark` 一类)在陈旧
148
+ # 条目里正是 None → guard_write/guard_forget/guard_move 静默放行。
149
+ # 值为 None 即「索引未记录该标记」,唯一权威是文件——但读盘有代价,
150
+ # 只在**受保护层**(self/anchor,节点数极少;层保护本身已拦 不可覆盖/
151
+ # 不可遗忘,None 决定的是 self_state 豁免与层间搬迁的细粒度判定)无条件
152
+ # 回退;非受保护层由「门控写点必须进写日志」承担(`mark` 已随本批接线,
153
+ # `add(immutable=True)` 本就经 _stage),故不付全池读盘代价。
154
+ if not need_fallback and _layer in PROTECTED_LAYERS \
155
+ and any(e.get(_k) is None for _k in _GATE_UNKNOWN_KEYS):
156
+ need_fallback = True
157
+ if need_fallback:
158
+ try:
159
+ node = cg.get(node_id)
160
+ except Exception:
161
+ node = None
162
+ if node:
163
+ f2 = node.get("frontmatter") or {}
164
+ fm["protected"] = f2.get("protected")
165
+ fm["protection_reason"] = f2.get("protection_reason")
166
+ fm["immutable"] = f2.get("immutable")
167
+ fm["self_state"] = f2.get("self_state")
168
+ fm["layer"] = f2.get("layer") or fm["layer"]
169
+ fm["importance"] = f2.get("importance", fm["importance"])
170
+ fm["importance_source"] = f2.get("importance_source")
171
+ return fm
172
+
173
+
174
+ # 生效条件:cg 索引无 node_id 条目(_fm 直接返回 None,不走回退读文件)时返回 (False, '');有条目时按 layer∈PROTECTED_LAYERS 返回 (True, 层保护);否则 protected is True 时返回 (True, protection_reason 或 '显式保护标记');否则 importance(缺失/假值/float 转换异常一律按 0.0)≥AUTO_PROTECT_IMPORTANCE 且 importance_source 为 None(键缺省)或 'hint' 时返回 (True, 重要性保护)——issue50-e:'heuristic' 等显式非 hint 来源不得由分数触发;其余返回 (False, '')。
175
+ def is_protected(cg, node_id):
176
+ """**不可遗忘**判定 → (是否受保护, 原因)。节点不存在返回 (False, "")。
177
+
178
+ issue50-e(2026-10-02,使用者裁定「读面也只认显式来源」):按分自动保护
179
+ 只对**缺省来源或显式 hint** 的分数生效。issue50-d 落盘了启发式真分
180
+ (importance=0.7x + importance_source="heuristic"、不打保护位),若本
181
+ 判定不看来源,读面(遗忘/搬迁闸、protect.check、scrub 净化与 confidence
182
+ 校准的 skip 判定、stats 盘点)会把机器推断的分数重新认回受保护——写侧
183
+ 「只落分不打位」被读侧单方面推翻。边界:
184
+ ① 键缺省(None)= 存量节点(既有 cg.add(importance=0.9) 直写、维护路径
185
+ 调分等从未有过该键)⇒ 行为一字不变——按「缺省即不认」会大规模改变
186
+ 既有保护面,禁止;
187
+ ② "hint" = 显式声明(写侧对 hint 过线本就打位,按分分支只是其无位形态
188
+ 的兜底,语义不变);
189
+ ③ "heuristic" 及其它显式来源不得由分数触发——机器推断的重要度不构成
190
+ 不可遗忘的依据。层保护(PROTECTED_LAYERS)、fm.protected 位、
191
+ is_immutable 一律不动;MERGE 强化(forgetting.reinforce 跨 0.7 置
192
+ protected=True)是「重复确认」的显式动作,不经本分支,不受影响。
193
+ """
194
+ return is_protected_entry(_fm(cg, node_id))
195
+
196
+
197
+ # 生效条件:fm 为假值时返回 (False, "");否则按三条真源判定——layer∈PROTECTED_LAYERS ⇒ 层保护;protected is True ⇒ 显式位;importance≥AUTO_PROTECT_IMPORTANCE 且 importance_source 为 None 或 "hint" ⇒ 按分保护;其余返回 (False, "")。
198
+ def is_protected_entry(fm):
199
+ """**条目口径**的「不可遗忘」判定单点(#431/#432/#468 与 lifecycle/trust 共用)。
200
+
201
+ 与 `is_protected` **同源**:后者现在就是「取 fm 再调本函数」——
202
+ 两口径是**同一个函数**(构造上唯一),不是两份实现靠腿互证。
203
+
204
+ 为什么需要条目口径:weights(fm 条目)、consolidate(索引条目)、forgetting._tier_of
205
+ (索引快照)、lifecycle/trust.stamp(裸 fm)四类调用方手里都**没有** (cg, node_id);
206
+ 此前各自读 `e.get("protected")` 位(**窄**:漏层保护与按分保护)或漏来源门(**宽**),
207
+ 一窄一宽正是「同一语义两份实现」的指纹。
208
+ """
209
+ if fm is None:
210
+ return False, ""
211
+ layer = str(fm.get("layer") or "")
212
+ if layer in PROTECTED_LAYERS:
213
+ return True, f"层保护:{layer}(不可遗忘层)"
214
+ if fm.get("protected") is True:
215
+ return True, str(fm.get("protection_reason") or "显式保护标记")
216
+ try:
217
+ imp = float(fm.get("importance") or 0.0)
218
+ except Exception:
219
+ imp = 0.0
220
+ _src = fm.get("importance_source")
221
+ if imp >= AUTO_PROTECT_IMPORTANCE and (_src is None or _src == "hint"):
222
+ return True, f"重要性保护:importance={imp:.2f}≥{AUTO_PROTECT_IMPORTANCE}"
223
+ # issue50-e(2026-10-02):按分保护**只认缺省或显式 hint 来源**——
224
+ # 语义与边界见 docstring ①②③;_fm 恒带 importance_source 键(缺省读
225
+ # None),老索引条目缺键同样落 None ⇒ 存量按分保护一字不变。
226
+ return False, ""
227
+
228
+
229
+ # 生效条件:cg 索引无 node_id 条目时返回 (False, '');有条目时若 self_state is True 一律返回 (False, '')(自我状态豁免);否则 layer∈PROTECTED_LAYERS 返回 (True, 层保护);否则 immutable is True 返回 (True, protection_reason 或 '显式不可覆盖标记');其余返回 (False, '')。
230
+ def is_immutable(cg, node_id):
231
+ """**不可覆盖**判定 → (是否不可篡改, 原因)。比不可遗忘更窄,只认强信号。
232
+
233
+ 例外:自我状态卡(frontmatter.self_state is True)**必须可覆盖**——
234
+ 自我状态本来就要随认知演化而更新,冻结它等于自我认知停止生长。
235
+ 但它仍然 is_protected(不可遗忘),这是「不可遗忘 ≠ 不可覆盖」的延伸。
236
+ 身份锚点不设此豁免,依旧两者皆禁。
237
+ """
238
+ fm = _fm(cg, node_id)
239
+ if fm is None:
240
+ return False, ""
241
+ if fm.get("self_state") is True:
242
+ return False, ""
243
+ layer = str(fm.get("layer") or "")
244
+ if layer in PROTECTED_LAYERS:
245
+ return True, f"层保护:{layer}(不可篡改层)"
246
+ if fm.get("immutable") is True:
247
+ return True, str(fm.get("protection_reason") or "显式不可覆盖标记")
248
+ return False, ""
249
+
250
+
251
+ # ---------------------------------------------------------------- 留痕
252
+
253
+ # 生效条件:对任意 cg、action、node_id、reason(actor/snapshot 缺省为 None)都构造含 t/action/node_id/reason/actor/snapshot 的 rec 并返回(#451:actor 经 _actor_of 单点解析——显式优先、其次库实例身份、无身份载体仍 None),,同时尝试追加写入 cg.root 下的 AUDIT_FILE,该写入抛出的任何异常被吞掉且不影响返回值。
254
+ def _audit(cg, action, node_id, reason, actor=None, snapshot=None):
255
+ rec = {"t": time.time(), "action": action, "node_id": node_id,
256
+ "reason": reason, "actor": _actor_of(cg, actor), "snapshot": snapshot}
257
+ try:
258
+ # issue #547:本模块的审计台账(`_protected_audit.jsonl`)此前走 append_jsonl
259
+ # 缺省路(可静默丢行)。#549 已把同一类账本(`_audit.jsonl`)切到 durable=True,
260
+ # 判据是「审计属不能丢面」而不是「必须与别的模块同一个文件」——各模块各有台账,
261
+ # 但标准一致:丢一行审计会让「发生过」与「没发生过」不可区分(T0 ③)。
262
+ append_jsonl(os.path.join(cg.root, AUDIT_FILE), rec, durable=True)
263
+ except Exception:
264
+ pass
265
+ return rec
266
+
267
+ # 生效条件:actor 显式传入(非 None)时原样返回,否则返回 getattr(cg, "actor", None)(库实例身份;载体无该属性时为 None)——**不凭空造身份**。
268
+ def _actor_of(cg, actor=None):
269
+ """审计 actor 单点(issue #451):显式优先,其次库实例身份,两者皆无 → None。
270
+
271
+ #451 病象:`_allow` → `_audit` 把 actor **原样**透传,而三守卫经 mdcg 的写面
272
+ 调用时都不传 actor ⇒ `override_write` / `override_forget` / `override_move`
273
+ 三类审计行 `actor: null`;同一出口的 `snapshot`(:295)与 `preimage`(:342)
274
+ 两行却都有 actor ——「同一出口两种口径」。本函数把三处同语义表达收成**一个
275
+ 真源**(:295/:342 一并改走本函数,语义逐位不变)。
276
+
277
+ 边界(不许改弱):本函数只保证「**不凭空造身份**」——载体无 `.actor` 属性时
278
+ 仍返回 None;而「actor 值是否*是*真正的那一方」由更上层身份源决定,本层看不见
279
+ (无独立身份源)。
280
+ """
281
+ return actor if actor is not None else getattr(cg, "actor", None)
282
+
283
+
284
+ # 生效条件:cg.get(node_id) 抛异常或返回假值时返回 None;否则在 cg.root/HISTORY_DIR/node_id 下以时间戳命名写入当前 frontmatter 与 content,_write_node 抛异常时返回 None,成功则追加一条 action="snapshot" 的审计(_audit,actor 取 cg.actor)并返回相对 cg.root 且以 '/' 分隔的路径。
285
+ #: 前像文件名的**唯一命名单点**(issue #413)。
286
+ #: 两侧(`snapshot()`=裸守卫 `_allow` 路径;`snapshot_preimage()`=执行时点前像)都必须经此处
287
+ #: ——「同语义两处实现、只加固了一侧」正是 #413 的病象(与 #326-③ 的 `condition_vm` 双链同形)。
288
+ #: 加固=**同秒命名冲突规避**:基名仍是 `%Y%m%d-%H%M%S`(既有守卫钉的形态不变),同秒内再次
289
+ #: 拍摄时追加 `-<N>` 序号(已存在即递增)⇒ 先那张前像不再被后来者踩掉。`suffix` 供执行时点
290
+ #: 前像附加微秒(`snapshot_preimage` 的既有形态,另一条既有守卫钉死)。
291
+ def _preimage_name(d, suffix=""):
292
+ base = time.strftime("%Y%m%d-%H%M%S", time.localtime()) + suffix
293
+ p = os.path.join(d, base + ".md")
294
+ _n = 1
295
+ while os.path.exists(p):
296
+ p = os.path.join(d, "%s-%d.md" % (base, _n))
297
+ _n += 1
298
+ return p
299
+
300
+
301
+ def snapshot(cg, node_id):
302
+ """把节点当前版本快照进 `_protected_history/<id>/<ts>.md`,返回相对路径。
303
+
304
+ N228(2026-09-28):本函数此前**全文零审计**——而它是**落盘写入**(写
305
+ `_protected_history/`,且这些快照是后续 override 快照链的基线)。经工具面
306
+ `mdcg_protect(action="snapshot")`(此前只要求粗粒度 write)任何 can_write
307
+ 角色都能在自己可读的节点上制造未审计磁盘写入(实测 `_audit.jsonl` 条数
308
+ 8→8 不变)。本批两条收口:① 工具面 op 要求对齐规范出口(protect 面在
309
+ `cg(op="protect")` 上级为 designer 专属);② 快照成功即留痕(本函数内,
310
+ 两条入口——工具面与 `guard_*` 的 `_allow`——都覆盖;`_allow` 路径会有
311
+ 「snapshot + 具体守卫动作」两条审计,属如实记录而非重复计数)。
312
+ """
313
+ try:
314
+ node = cg.get(node_id)
315
+ except Exception:
316
+ node = None
317
+ if not node:
318
+ return None
319
+ d = os.path.join(cg.root, HISTORY_DIR, node_id)
320
+ os.makedirs(d, exist_ok=True)
321
+ p = _preimage_name(d) # issue #413:经**同一加固单点**(原为裸秒级名,同秒互踩)
322
+ try:
323
+ cg._write_node(node.get("id"), p, node.get("frontmatter") or {},
324
+ node.get("content") or "")
325
+ except Exception:
326
+ return None
327
+ rel = os.path.relpath(p, cg.root).replace("\\", "/")
328
+ _audit(cg, "snapshot", node_id, "显式快照(%s)" % rel,
329
+ actor=_actor_of(cg), snapshot=rel)
330
+ return rel
331
+
332
+
333
+ # 生效条件:cg.get(node_id) 抛异常或返回假值时返回 None(与 snapshot 同口径——目标不存在=动作不会发生,由调用方按既有错误路径处理);否则在 cg.root/HISTORY_DIR/node_id 下以「秒级时间戳-微秒后缀」命名写入当前 frontmatter 与 content(写盘形态与 snapshot 逐位一致:同目录、同 nodefile 序列化、同 _write_node 封装钩子),_write_node 抛异常时返回 None,成功则追加一条 action="preimage" 的审计(reason 交代动作类与 pid)并返回相对 cg.root 且以 '/' 分隔的路径;
334
+ def snapshot_preimage(cg, node_id, action="", pid=None, reason="", actor=None):
335
+ """执行时点前像(设计 §四「回滚原语通用化」:快照面推广为一切 C/D/B)。
336
+
337
+ 与 `snapshot()` 的关系(**面复用、语义泛化**,既有行为一字不动):
338
+ `_protected_history/<id>/` + `_protected_audit.jsonl` 这一对从「仅受保护节点」
339
+ 推广为「一切 C/D/B 动作」的**前像面**——本函数是新入口,`snapshot()` /
340
+ `guard_*` 的既有形态(文件名 `%Y%m%d-%H%M%S.md`、审计 action="snapshot"、
341
+ reason「显式快照(rel)」、覆盖路径快照数)**不改一行**(守卫钉死)。
342
+ 两条差别都是为「执行时点前像」的场景补强:
343
+ · 文件名带微秒后缀——同一节点的多个变更单可能在**同一秒**内先后执行,
344
+ 秒级名会互相覆盖(探针实测:同秒二次 snapshot 返回同一路径)——前像
345
+ 被后来的前像踩掉,早先那张的回滚句柄就指向错误时点的内容;
346
+ · 审计 action="preimage" 且 reason 交代动作类/pid——回滚与 §七 R3 读数
347
+ (「存在实测回滚记录」)要能把「变更单前像」与既有显式快照区分开。
348
+
349
+ 为什么前像必须在**执行时点**拍(设计 §四 明文):变更单在提议时点构造,
350
+ 从提议到 accept 之间目标可能被第三方改动——回滚必须撤销**本变更本身**,
351
+ 而不是一并抹掉第三方改动。故由执行桥(`mdcos._mutation_execute`)在动作
352
+ 原语落盘**之前**拍摄,作为载荷 `before` 字段(执行时点快照引用)。
353
+
354
+ 边界(如实):加密库(覆写了 `_seal_content` 的实例)里本文件的密文层
355
+ 因每次封装熵不同**不保证逐字节可复现**——前像的语义是「明文内容 + 结构
356
+ 的可恢复」,逐字节比对在非加密库(含一切守卫合成库)上成立(探针实测)。
357
+ """
358
+ try:
359
+ node = cg.get(node_id)
360
+ except Exception:
361
+ node = None
362
+ if not node:
363
+ return None
364
+ d = os.path.join(cg.root, HISTORY_DIR, node_id)
365
+ os.makedirs(d, exist_ok=True)
366
+ p = _preimage_name(d, "-%06d" % (time.time_ns() // 1000 % 1000000)) # issue #413:同一单点
367
+ try:
368
+ cg._write_node(node.get("id"), p, node.get("frontmatter") or {},
369
+ node.get("content") or "")
370
+ except Exception:
371
+ return None
372
+ rel = os.path.relpath(p, cg.root).replace("\\", "/")
373
+ _audit(cg, "preimage", node_id,
374
+ reason or ("执行时点前像(动作类 %s,pid=%s)"
375
+ % (action or "?", pid or "?")),
376
+ actor=_actor_of(cg, actor),
377
+ snapshot=rel)
378
+ return rel
379
+
380
+
381
+ # 生效条件:cg.root/HISTORY_DIR/node_id 不是目录时返回 [];是目录时返回该目录下以 .md 结尾(不递归)的文件按名称排序后的 `HISTORY_DIR/node_id/文件名` 列表,无匹配文件则列表为空。
382
+ def history(cg, node_id):
383
+ """受保护节点的历史版本列表(按时间升序)。"""
384
+ d = os.path.join(cg.root, HISTORY_DIR, node_id)
385
+ if not os.path.isdir(d):
386
+ return []
387
+ out = [f for f in os.listdir(d) if f.endswith(".md")]
388
+ out.sort()
389
+ return [f"{HISTORY_DIR}/{node_id}/{f}" for f in out]
390
+
391
+
392
+ # ---------------------------------------------------------------- 守卫
393
+
394
+ # 生效条件:对任意 cg、node_id、why、action、override、actor——先拍前像(`snapshot`);**前像不可得**
395
+ # (写者读不到该节点、或前像落盘失败 ⇒ `snapshot` 返回 None)时**fail-closed**:留一条
396
+ # `<action>_denied` 审计行并抛 `ProtectionError`,不返回放行字典;前像可得时返回
397
+ # {'override': True, 'reason': why, 'snapshot': snap, 'audit': _audit(...)}。
398
+ def _allow(cg, node_id, why, action, override, actor):
399
+ """受保护节点 override 的唯一放行点(前像不可得 ⇒ 拒)。
400
+
401
+ issue #413 站点2(2026-10-16 实测,HEAD dd8a9640):此前 `snapshot()` 返回 None
402
+ (该身份**读不到**这个节点,例如 self 层 private 节点 + internal 档写者、或跨会话)
403
+ 时**照样返回 `override: True`** ⇒ 覆写静默落盘而 `_protected_history/<id>/` 一件不落、
404
+ 审计行 `snapshot: null`:受保护节点的原内容**不可回滚地消失**(N228 逐字:「这些快照
405
+ 是后续 override 快照链的基线」)。实测四写者变体里 `designer/internal/sessB` 走到该
406
+ 分支:覆写后节点 `sensitivity` 由 private 变 internal、原文(AEAD 密文)无从恢复,
407
+ internal 档读者随后可读。
408
+ ⇒ 判据:**override 的价值来自「可回滚」,前像拍不出来就不该放行**(与 N228 快照留痕、
409
+ 与 #413 站点1 的同秒不踩踏同一族)。需要放行的内部路径应改用能读到该节点的主语
410
+ (或先 `cg.unlock`/换身份),而不是让不可回滚的覆写通过。
411
+ """
412
+ snap = snapshot(cg, node_id)
413
+ if snap is None:
414
+ rec = _audit(cg, action + "_denied", node_id,
415
+ why + ";前像不可得 ⇒ fail-closed(issue #413 站点2)", actor, None)
416
+ raise ProtectionError(
417
+ f"节点 {node_id} 受保护({why});override 需要前像,但前像不可得"
418
+ f"(该身份读不到此节点,或前像落盘失败)——本次覆写/搬迁/遗忘被拒(fail-closed)"
419
+ f"(N228/#413-2:无前像的 override 不可回滚)")
420
+ rec = _audit(cg, action, node_id, why, actor, snap)
421
+ return {"override": True, "reason": why, "snapshot": snap, "audit": rec}
422
+
423
+
424
+ # 生效条件:is_immutable(cg, node_id) 为假(含 self_state is True、layer 不在 PROTECTED_LAYERS 且 immutable 非 True 的情形)时返回 None;为真时 override 取真值则返回 _allow(..., 'override_write', override, actor),否则抛出 ProtectionError;layer 形参不参与该判定。
425
+ def guard_write(cg, node_id, layer=None, override=False, actor=None):
426
+ """覆盖既有节点前的守卫(只认**不可覆盖**信号)。
427
+
428
+ 新节点 / 未标记 immutable 的节点直接放行(返回 None)。
429
+ importance≥0.7 只保证「不可遗忘」,不阻断系统自身的幂等更新。
430
+ """
431
+ prot, why = is_immutable(cg, node_id)
432
+ if not prot:
433
+ return None
434
+ if override:
435
+ return _allow(cg, node_id, why, "override_write", override, actor)
436
+ raise ProtectionError(
437
+ f"节点 {node_id} 受写保护({why});覆盖需显式 override=True")
438
+
439
+
440
+ # 生效条件:is_protected(cg, node_id) 为假时返回 None;为真时 override 取真值则返回 _allow(..., 'override_forget', override, actor),否则抛出 ProtectionError。
441
+ def guard_forget(cg, node_id, override=False, actor=None):
442
+ """删除前的守卫。受保护节点 = 不可遗忘。"""
443
+ prot, why = is_protected(cg, node_id)
444
+ if not prot:
445
+ return None
446
+ if override:
447
+ return _allow(cg, node_id, why, "override_forget", override, actor)
448
+ raise ProtectionError(
449
+ f"节点 {node_id} 不可遗忘({why});删除需显式 override=True")
450
+
451
+
452
+ # 生效条件:is_protected(cg, node_id) 为假时返回 None;为真且 to_layer∈PROTECTED_LAYERS(保护层间互搬)时也返回 None;为真且 to_layer 不在 PROTECTED_LAYERS 时,override 取真值则返回 _allow(..., 'override_move', override, actor),否则抛出 ProtectionError。
453
+ def guard_move(cg, node_id, to_layer, override=False, actor=None):
454
+ """降级/搬迁前的守卫:受保护节点不得被移出保护层。"""
455
+ prot, why = is_protected(cg, node_id)
456
+ if not prot:
457
+ return None
458
+ if to_layer in PROTECTED_LAYERS:
459
+ return None # 保护层之间互搬仍受保护,放行
460
+ if override:
461
+ return _allow(cg, node_id, why, "override_move", override, actor)
462
+ raise ProtectionError(
463
+ f"节点 {node_id} 受写保护({why});降级移出保护层需显式 override=True")
464
+
465
+
466
+ # 生效条件:cg.get(node_id) 抛异常时返回 None(读面失败不阻断判据本身),否则原样返回其读面结果(含 None=不可读/不存在)。
467
+ def _safe_get(cg, node_id):
468
+ """`cg.get` 的**不抛**包装(层闸判据用;读面失败不得把闸炸穿)。"""
469
+ try:
470
+ return cg.get(node_id)
471
+ except Exception: # noqa: BLE001 —— 读面失败不阻断判据本身
472
+ return None
473
+
474
+
475
+ # 生效条件:cg 具备可调用的 _maybe_reload_index 时先调一次;层取形参 layer、索引条目 layer、节点 frontmatter layer 中首个真值(皆假值回落 "knowledge",与 require_layer_write 缺省同口径);敏感度取形参 sensitivity、索引条目 sensitivity、节点 frontmatter sensitivity 中首个真值;三来源皆无有效密级时回落 security.DEFAULT_SENSITIVITY(**已知 fail-open 代价,裁定与边界见函数内注释与 test_issue450_writegate_unknown_sens**);返回 (层, 敏感度) 二元组。
476
+ def _resolve_target(cg, node_id, layer=None, sensitivity=None):
477
+ """既有节点写面的「层 / 敏感度」解析**单点**(不设第二份口径)。
478
+
479
+ 索引代际探活(N195 同族):写面直读本进程内存索引,他进程刚写入/搬迁的节点
480
+ 在本进程索引中不存在、或层位陈旧 → 解析出的层不是真层,层闸会**静默失效**
481
+ (「越权改 knowledge」被当成「同层正当写」放行)。故进入判定前先探活一次
482
+ (签名未变时只有一次 stat)。
483
+ """
484
+ _reload = getattr(cg, "_maybe_reload_index", None)
485
+ if callable(_reload):
486
+ _reload()
487
+ e = _entry(cg, node_id) or {}
488
+ _layer = layer or e.get("layer")
489
+ _sens = sensitivity or e.get("sensitivity")
490
+ _node = None
491
+ _node_read = False
492
+ if not _layer or not _sens:
493
+ _node = _safe_get(cg, node_id)
494
+ _node_read = True
495
+ if _node:
496
+ f = _node.get("frontmatter") or {}
497
+ _layer = _layer or f.get("layer")
498
+ _sens = _sens or f.get("sensitivity")
499
+ # ★ issue #450(fail-closed 版):**「缺 sensitivity 键」是 unknown,不是 internal。**
500
+ # ① 为什么要查盘面:`MdCGSecure._scan_nodes` 用
501
+ # `e["sensitivity"] = fm.get("sensitivity") or DEFAULT_SENSITIVITY`
502
+ # 回填索引条目——回填把「未知」擦成 `internal`,层闸此后**再也看不到**
503
+ # 缺键信号。故当生效值恰为 `DEFAULT_SENSITIVITY` 时回读一次 frontmatter,
504
+ # 确认该键**是否真的声明过**(只读,不改盘、不写索引)。
505
+ # ② 为什么不改 fail-closed(裁定 2026-10-18,实测后):真实密级可能是
506
+ # restricted/private/secret ⇒ 回落 `internal` 确实会放行(fail-open,越权),
507
+ # 方向与 `#447`/`_readable` 的「密级未知按 secret」一致。但本仓写面的**常态**
508
+ # 是「不声明 sensitivity」(缺省即 internal),fail-closed 会把全库 legacy
509
+ # 节点对非 secret 身份变成只读——全量链实测 3 个用例当场转红
510
+ # (test_p31_insight / test_p30_maintain / test_p29_session_ingest_export)。
511
+ # 功能代价 > 它堵的越权(后者需攻击者已持 internal clearance 且目标真实
512
+ # 密级更高,即 #359 记的「private 已被记录」那类;#359 的裁定只绑定 merge
513
+ # 场景,本处沿用其「unknown 视同缺省档」口径但不外推)。
514
+ # 密级更高),故按「成本>收益取小」**保持 internal 回落**,把边界与代价
515
+ # 钉在守卫 `md_cg/test_issue450_writegate_unknown_sens.py`。
516
+ # ③ 何时改判:出现「缺键且真实密级应为高密级」的实例(届时按 fail-closed 改,
517
+ # 并同批把 legacy 节点回填 sensitivity,否则就是上面的全库只读)。
518
+ # 边界:节点**不存在** ⇒ 新写入面,沿用 `DEFAULT_SENSITIVITY`(保护的是
519
+ # 「既有节点不被降档覆写」,不是「禁止新建」);节点存在但盘面读不出
520
+ # (加密且无密钥/损坏)⇒ 无法确认缺键,保留索引值(不把「读不动」当成
521
+ # 「缺键」而误锁全库)。
522
+ # 已知缺口:读面·近期事件(`mdcos.py` 的 `recent_events`)= `#447`,本件不覆盖。
523
+ if _sens == DEFAULT_SENSITIVITY:
524
+ if not _node_read:
525
+ _node = _safe_get(cg, node_id)
526
+ if _node is not None:
527
+ _fm = _node.get("frontmatter") or {}
528
+ if not _fm.get("sensitivity"):
529
+ _sens = None
530
+ if not _sens:
531
+ # 既有节点(索引有条目或节点可读)而密级不可判 ⇒ 最保守档;
532
+ # 节点不存在(新写入面)⇒ 缺省档(保护面不拦新建)。
533
+ # ★ 裁定(2026-10-18,全量链实测后):**保持 internal 回落**,不改 fail-closed。
534
+ # 代价读数:本件首版曾按 fail-closed 返回 SENSITIVITY_ORDER[-1],全量链
535
+ # md_cg 随即 3 个用例转红(test_p31_insight / test_p30_maintain /
536
+ # test_p29_session_ingest_export,均因「既有节点未声明 sensitivity ⇒ 被
537
+ # 判成 secret ⇒ internal 身份的同 id 改写被拒」)。实测 blast radius:
538
+ # 本仓大多数节点**从不声明 sensitivity**(写面缺省即 internal),fail-closed
539
+ # 等于把全库 legacy 节点对非 secret 身份变成只读——功能代价大于它堵的
540
+ # fail-open(后者需要攻击者已持 internal clearance 且目标真实密级更高)。
541
+ # 故按「成本>收益取小」维持原语义,并把边界钉在守卫
542
+ # `md_cg/test_issue450_writegate_unknown_sens.py`(登记 + 代价 + 何时改判)。
543
+ return _layer or "knowledge", DEFAULT_SENSITIVITY
544
+ return _layer or "knowledge", _sens
545
+
546
+
547
+ # 生效条件:经 _resolve_target 解析出节点真层与敏感度后,cg.principal 非 None 且具备 require_layer_write 时调 principal.require_layer_write(layer, sensitivity)(越权抛 AccessDenied),返回解析出的层;cg 无 principal(裸 MdCG)时不做任何判定。
548
+ def require_layer(cg, node_id, layer=None, sensitivity=None, actor=None):
549
+ """既有节点写面的 **principal 层闸**单点(不含引擎级保护闸)。
550
+
551
+ N209(2026-09-28,同族未接线的相邻写面入口):「只有 `falsified` 一态接了
552
+ 层闸」之外的三条写面全程只认管理位/保护位、**不认层白名单**——
553
+ `MdCGSecure.verify` 的 confirmed/weakened 分支直写被验证节点本体
554
+ (`md_cg/mdcg.py:3502`)、`trust.set_state`(验证态唯一推进入口 ⇒ 依赖者
555
+ `mark_dependents` 与 `set_verification` 两条写路,`md_cg/trust.py:697-698`)、
556
+ `MdCG._move_layer`(降级搬迁 = 源层一次删除写 + 目标层一次新增写,
557
+ `md_cg/mdcg.py` 的 `MdCG._move_layer`)。后果:持 verify 令牌(`layers_allow` 仅
558
+ rejected/contextual、forbidden 明列「knowledge/self/anchor 层」)即可改写
559
+ knowledge 层节点本体、把 self 层依赖者置 doubted、把 knowledge 节点搬出层。
560
+ 层闸口径与 `MdCGSecure.add`/`add_rejected` 一致(`md_cg/mdcos.py:3889`/`:3898`)。
561
+ """
562
+ _layer, _sens = _resolve_target(cg, node_id, layer=layer,
563
+ sensitivity=sensitivity)
564
+ p = getattr(cg, "principal", None)
565
+ if p is not None and hasattr(p, "require_layer_write"):
566
+ p.require_layer_write(_layer, _sens)
567
+ return _layer
568
+
569
+
570
+ # 生效条件:先经 require_layer(cg, node_id, layer, sensitivity) 做 principal 层闸(越权抛 AccessDenied),再委托 guard_write(cg, node_id, layer=解析层, override=override, actor=actor) 并返回其结果。
571
+ def guard_overwrite(cg, node_id, layer=None, sensitivity=None,
572
+ override=False, actor=None):
573
+ """既有节点**覆写**前的统一双闸:principal 层写权限 + 引擎级写保护。
574
+
575
+ N197/N208(2026-09-28):「同一身份对**同层**的 `add` 已被
576
+ `require_layer_write` 拒绝,但直调 `cg._write_node` 的写面照样落盘」——
577
+ 层闸被同一库的两条出口口径不一致地绕开。与 N131(review 队列 merge 面)
578
+ 同序同错型:principal 层写闸在先(对照 `MdCGSecure.add` :3889),引擎级
579
+ `guard_write` 在后(对照 `MdCG.add` :1509)。任何覆写**既有节点**的写面都
580
+ 必须先过这里,否则 self/anchor 层与 immutable 节点被无痕覆写:不抛错、不落
581
+ `_protected_history` 快照、不写 `_protected_audit.jsonl`。
582
+
583
+ 索引代际探活(N195 同族):写面直读本进程内存索引,他进程刚置的保护位在本
584
+ 进程索引中不存在 → `is_immutable` 的 `_entry` 得 None → 判 False,两道闸
585
+ 会**同时静默失效**。故进入判定前先探活一次(签名未变时只有一次 stat);
586
+ 解析与层闸由 `require_layer` 同一单点承担。
587
+ """
588
+ _layer = require_layer(cg, node_id, layer=layer, sensitivity=sensitivity)
589
+ return guard_write(cg, node_id, layer=_layer, override=override, actor=actor)
590
+
591
+
592
+ # 生效条件:cg.get(node_id) 抛异常或返回假值时返回 {'ok': False, 'error': 'node_not_found', 'node_id': node_id}(负路由,形态对齐 trust.set_state:692);否则把 protected=True 与 protection_reason=reason 写入 cg.root 下 node["path"](该键缺失即抛 KeyError)对应的 frontmatter 并保持原 content,随后门条目存在时同步其 protected/protection_reason 并把该条目并入索引写日志(_dirty 标脏 + flush,失败静默),返回 {'node_id': node_id, 'protected': True, 'reason': reason}。
593
+ def mark(cg, node_id, reason):
594
+ """给节点打上 `protected=True` 标记(写回 frontmatter,不动 content)。
595
+
596
+ 节点不存在时返回**负路由** `{"ok": False, "error": "node_not_found",
597
+ "node_id": node_id}`(与 `trust.set_state` 的不存在分支逐键同形),
598
+ 不再裸返回 None(H9④ 前):None 与「成功」在调用方眼里都非 dict,
599
+ `mcp_server._protect_call` 直接把它序列化成 `null` 回给 MCP 客户端
600
+ ——不存在的 node_id 被读成「打标成功」,而 `_write_node` 从未发生。
601
+ 调用方分流:失败看 `r.get("ok") is False` / `"error" in r`,
602
+ 成功路径的返回键**不变**(node_id / protected / reason,无 ok 键)。
603
+ """
604
+ try:
605
+ node = cg.get(node_id)
606
+ except Exception:
607
+ node = None
608
+ if not node:
609
+ return {"ok": False, "error": "node_not_found", "node_id": node_id}
610
+ fm = node.get("frontmatter") or {}
611
+ fm["protected"] = True
612
+ fm["protection_reason"] = reason
613
+ cg._write_node(node_id, os.path.join(cg.root, node["path"]),
614
+ fm, node.get("content") or "")
615
+ e = _entry(cg, node_id)
616
+ if e is not None:
617
+ e["protected"] = True
618
+ e["protection_reason"] = reason
619
+ # N213 同根(2026-09-28):保护位是**门控字段**,只改内存条目 + 文件而
620
+ # 不进索引写日志 ⇒ 他进程(以及本进程 compact 前的重载)把该节点当
621
+ # 「未标记」→ guard_forget / guard_move 静默放行。与 add 同口径:
622
+ # `_dirty[nid] = e` 标脏(**不走 _stage**——它会重复累加该桶计数)
623
+ # 并 flush,使日志成为跨进程可见的代际载体。日志化失败不阻断打标本身
624
+ # (文件已改,下一次 compact/rebuild 的 _scan_nodes 会带上该标记)。
625
+ _dirty = getattr(cg, "_dirty", None)
626
+ if isinstance(_dirty, dict):
627
+ _dirty[node_id] = e
628
+ _flush = getattr(cg, "flush", None)
629
+ if callable(_flush):
630
+ try:
631
+ _flush()
632
+ except Exception: # noqa: BLE001 —— 落账失败不阻断打标
633
+ pass
634
+ return {"node_id": node_id, "protected": True, "reason": reason}
635
+
636
+
637
+ # 生效条件:遍历 cg.index.nodes(或其假值时的空字典)的每个键,对 is_protected 为真的节点计入 ids 并按 layer(缺失/假值记为 '?')累加 by_layer,其中原因串含 "importance=" 或以 "重要性保护" 开头的计入 auto_by_importance,对 is_immutable 为真的计入 immutable_ids,返回含 protected_count/immutable_count/by_layer/auto_by_importance/ids/immutable_ids 的字典。
638
+ def stats(cg):
639
+ """保护面盘点:不可遗忘数 / 不可覆盖数 / 分层分布 / 自动保护命中数。"""
640
+ nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
641
+ by_layer, ids, auto, immutable = {}, [], 0, []
642
+ for nid in list(nodes):
643
+ prot, why = is_protected(cg, nid)
644
+ if prot:
645
+ ids.append(nid)
646
+ layer = str(nodes[nid].get("layer") or "?")
647
+ by_layer[layer] = by_layer.get(layer, 0) + 1
648
+ if "importance=" in why or why.startswith("重要性保护"):
649
+ auto += 1
650
+ imm, _ = is_immutable(cg, nid)
651
+ if imm:
652
+ immutable.append(nid)
653
+ return {"protected_count": len(ids), "immutable_count": len(immutable),
654
+ "by_layer": by_layer, "auto_by_importance": auto, "ids": ids,
655
655
  "immutable_ids": immutable}