@furongjun1999/dsh-memory 0.9.6 → 0.9.7

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 (216) hide show
  1. package/data/policy.json +38 -38
  2. package/docs/discipline/templates/spec.txt.tmpl +1 -1
  3. package/dsh/cordis.yml.example +139 -139
  4. package/lib/hooks.d.ts +19 -0
  5. package/lib/hooks.js +29 -6
  6. package/lib/index.js +11 -2
  7. package/lib/lib/hook_audit.js +38 -2
  8. package/lib/lib/prompt_safety.js +14 -3
  9. package/lib/tools.d.ts +7 -0
  10. package/lib/tools.js +22 -1
  11. package/md_cg/_guard_kit.py +121 -121
  12. package/md_cg/anchor.py +114 -114
  13. package/md_cg/audit.py +15 -2
  14. package/md_cg/chain.py +3 -2
  15. package/md_cg/config_registry_guard.py +487 -487
  16. package/md_cg/conformance.py +747 -747
  17. package/md_cg/consolidate.py +1793 -1793
  18. package/md_cg/crypto.py +794 -794
  19. package/md_cg/hyperedge.py +262 -262
  20. package/md_cg/interface_schema.py +146 -146
  21. package/md_cg/lifecycle.py +426 -426
  22. package/md_cg/mdcos.py +12 -8
  23. package/md_cg/predict.py +1103 -1103
  24. package/md_cg/protect.py +654 -654
  25. package/md_cg/provenance.py +606 -606
  26. package/md_cg/queue_health.py +130 -130
  27. package/md_cg/refine.py +613 -613
  28. package/md_cg/retrieve.py +128 -128
  29. package/md_cg/revise.py +140 -140
  30. package/md_cg/rollback.py +657 -657
  31. package/md_cg/rollback_cli.py +124 -124
  32. package/md_cg/rotate.py +346 -346
  33. package/md_cg/routing.py +490 -490
  34. package/md_cg/self_surface.py +50 -50
  35. package/md_cg/semantic/canonical.py +144 -144
  36. package/md_cg/semantic/zh_en_atoms.py +141 -141
  37. package/md_cg/sources.py +1091 -1091
  38. package/md_cg/stg.py +3 -2
  39. package/md_cg/test_audit_rotate_parity.py +279 -279
  40. package/md_cg/test_autonomy_modes.py +2013 -2013
  41. package/md_cg/test_cn_recall_grams.py +206 -206
  42. package/md_cg/test_code_kind_forbidden.py +101 -0
  43. package/md_cg/test_condaccept.py +156 -156
  44. package/md_cg/test_condgate.py +141 -141
  45. package/md_cg/test_heartbeat_ledger.py +557 -557
  46. package/md_cg/test_i50e_readside_protection.py +658 -658
  47. package/md_cg/test_issue111_gate_order.py +76 -76
  48. package/md_cg/test_issue111_scoring_contract.py +86 -86
  49. package/md_cg/test_issue121_calibration_bounds.py +293 -293
  50. package/md_cg/test_issue145_sleep_no_silent_rollback.py +167 -167
  51. package/md_cg/test_issue147_pack_id_escape.py +378 -378
  52. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -192
  53. package/md_cg/test_issue149_accel_default_face.py +248 -248
  54. package/md_cg/test_issue150_empty_query_terms.py +328 -328
  55. package/md_cg/test_issue151_153_157_write_cache_index.py +151 -151
  56. package/md_cg/test_issue152_sealed_postings.py +309 -309
  57. package/md_cg/test_issue153b_index_generation_invalidation.py +142 -142
  58. package/md_cg/test_issue157b_index_remainder.py +344 -344
  59. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -223
  60. package/md_cg/test_issue191_import_trust.py +382 -382
  61. package/md_cg/test_issue193_write_scope.py +378 -378
  62. package/md_cg/test_issue212_writeface_gaps.py +349 -349
  63. package/md_cg/test_issue214_reject_sensitivity.py +266 -266
  64. package/md_cg/test_issue215_condition_source_gap.py +272 -272
  65. package/md_cg/test_issue216_clash_routes.py +214 -214
  66. package/md_cg/test_issue217_slot_routes.py +248 -248
  67. package/md_cg/test_issue218_postcondition_value_blind.py +222 -222
  68. package/md_cg/test_issue258_pack_sensitivity.py +468 -468
  69. package/md_cg/test_issue265_coldverify_multiproc.py +438 -438
  70. package/md_cg/test_issue274_read_node_id_none.py +341 -341
  71. package/md_cg/test_issue275_layer_param.py +250 -250
  72. package/md_cg/test_issue277_node_id_traversal.py +384 -384
  73. package/md_cg/test_issue278_neg_separated_tension.py +271 -271
  74. package/md_cg/test_issue278_neg_window.py +294 -294
  75. package/md_cg/test_issue278_negative_layering.py +83 -83
  76. package/md_cg/test_issue284_skip_not_pass.py +291 -291
  77. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -573
  78. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -245
  79. package/md_cg/test_issue303_design_boundaries.py +262 -262
  80. package/md_cg/test_issue315_merge_branch_sensitivity.py +383 -383
  81. package/md_cg/test_issue319_tenant_unregistered_bypass.py +256 -256
  82. package/md_cg/test_issue321_mcp_deep_json.py +304 -304
  83. package/md_cg/test_issue322_node_write_lock.py +727 -727
  84. package/md_cg/test_issue324_write_size_fields.py +214 -214
  85. package/md_cg/test_issue325_audit_poison.py +229 -229
  86. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -331
  87. package/md_cg/test_issue326_key_perms.py +355 -355
  88. package/md_cg/test_issue326_twin_parser_parity.py +323 -323
  89. package/md_cg/test_issue326_vm_call_frame.py +569 -569
  90. package/md_cg/test_issue345_writelimit_effective_sens.py +233 -233
  91. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -424
  92. package/md_cg/test_issue348_insight_verify_op.py +199 -199
  93. package/md_cg/test_issue348_merge_rmw_lock.py +345 -345
  94. package/md_cg/test_issue350_casefold_collision.py +235 -235
  95. package/md_cg/test_issue351_ingest_root_fallback.py +201 -201
  96. package/md_cg/test_issue352_imgaudit.py +418 -418
  97. package/md_cg/test_issue352_pathsjson.py +537 -537
  98. package/md_cg/test_issue352_refindex.py +412 -412
  99. package/md_cg/test_issue352_rollback.py +604 -604
  100. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -327
  101. package/md_cg/test_issue354_rust_index_containment.py +571 -571
  102. package/md_cg/test_issue354_rust_wal_containment.py +606 -606
  103. package/md_cg/test_issue358_truncation_observable.py +247 -247
  104. package/md_cg/test_issue360_tidy_private_excerpt.py +195 -195
  105. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -494
  106. package/md_cg/test_issue362_neg_condition.py +468 -468
  107. package/md_cg/test_issue363_lexical_idf.py +275 -275
  108. package/md_cg/test_issue370_readcache_assembly.py +488 -488
  109. package/md_cg/test_issue376_heartbeat_failed.py +293 -293
  110. package/md_cg/test_issue377_layer_protect_stamp.py +324 -324
  111. package/md_cg/test_issue378_protected_floor.py +310 -310
  112. package/md_cg/test_issue383_state_event_write_gate.py +462 -462
  113. package/md_cg/test_issue397_sens_eff_wiring.py +435 -435
  114. package/md_cg/test_issue398_toolface_op_parity.py +511 -511
  115. package/md_cg/test_issue399_hive_json_shape.py +317 -317
  116. package/md_cg/test_issue401_wisdom_codegen.py +295 -295
  117. package/md_cg/test_issue404_heal_receipt.py +389 -389
  118. package/md_cg/test_issue409_compact_index_completeness.py +509 -509
  119. package/md_cg/test_issue410_verify_demote_write.py +366 -366
  120. package/md_cg/test_issue411_scrub_idempotence.py +575 -575
  121. package/md_cg/test_issue412_discipline_producer_parity.py +311 -311
  122. package/md_cg/test_issue413_preimage_failclosed.py +239 -239
  123. package/md_cg/test_issue413_preimage_twin.py +339 -339
  124. package/md_cg/test_issue415_deps_gate_probe.py +357 -357
  125. package/md_cg/test_issue416_entry_key_subset.py +525 -525
  126. package/md_cg/test_issue417_twophase_merge_landed.py +423 -423
  127. package/md_cg/test_issue425_ingest_library_path.py +331 -331
  128. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -346
  129. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -310
  130. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -301
  131. package/md_cg/test_issue427_serve_status_shape.py +191 -191
  132. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -322
  133. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -278
  134. package/md_cg/test_issue434_435_float_gate.py +90 -90
  135. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -448
  136. package/md_cg/test_issue43_default_policy.py +874 -874
  137. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -281
  138. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -454
  139. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -382
  140. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -51
  141. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -203
  142. package/md_cg/test_issue451_audit_actor.py +313 -313
  143. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -299
  144. package/md_cg/test_issue463_ghost_prune_guard.py +259 -259
  145. package/md_cg/test_issue466_basis_registry.py +469 -469
  146. package/md_cg/test_issue467_identity_sensitivity_parity.py +360 -360
  147. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -126
  148. package/md_cg/test_issue470_wal_event_durable.py +427 -427
  149. package/md_cg/test_issue471_identity_readable.py +136 -136
  150. package/md_cg/test_issue472_audit_chain.py +90 -90
  151. package/md_cg/test_issue472_prune_ledger.py +105 -105
  152. package/md_cg/test_issue472_rollback_degraded.py +81 -81
  153. package/md_cg/test_issue491_compose_sandbox.py +460 -460
  154. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -280
  155. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -256
  156. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -110
  157. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -88
  158. package/md_cg/test_issue525_read_null_semantics.py +52 -52
  159. package/md_cg/test_issue547_append_jsonl_whitelist.py +114 -114
  160. package/md_cg/test_issue547_audit_durable.py +96 -96
  161. package/md_cg/test_issue557_r2_write_entries_size_gate.py +83 -83
  162. package/md_cg/test_issue559_refine_prefix.py +69 -69
  163. package/md_cg/test_issue562_retired_faces.py +150 -0
  164. package/md_cg/test_issue71_queue_backlog.py +376 -376
  165. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -420
  166. package/md_cg/test_issue82_credential_rules.py +271 -271
  167. package/md_cg/test_issue91_verifier_sandbox.py +314 -314
  168. package/md_cg/test_issue93_remember_redaction.py +282 -282
  169. package/md_cg/test_logref.py +1141 -1141
  170. package/md_cg/test_md_access_parity.py +330 -330
  171. package/md_cg/test_md_cg_no_hive_dep.py +139 -139
  172. package/md_cg/test_mutation_residue.py +119 -119
  173. package/md_cg/test_mutation_rollback.py +835 -835
  174. package/md_cg/test_n123_derive_expiry_chain.py +210 -210
  175. package/md_cg/test_n209_verify_write_face_gates.py +466 -466
  176. package/md_cg/test_n62_tenant_bind_failclosed.py +200 -200
  177. package/md_cg/test_neg_tail_honesty.py +733 -733
  178. package/md_cg/test_p21_tokens.py +294 -294
  179. package/md_cg/test_p27_docindex.py +792 -792
  180. package/md_cg/test_p28_refcheck.py +1053 -1053
  181. package/md_cg/test_p2_six_elements.py +476 -476
  182. package/md_cg/test_p33_ccg_wiring.py +300 -300
  183. package/md_cg/test_p3_legacy_closure.py +438 -438
  184. package/md_cg/test_p40_refine_worklist.py +244 -244
  185. package/md_cg/test_p4_freshness.py +781 -781
  186. package/md_cg/test_p9c_dedup_hints.py +288 -288
  187. package/md_cg/test_policy_required_ccg.py +444 -444
  188. package/md_cg/test_retr_s5.py +312 -312
  189. package/md_cg/test_s1_ast_judge.py +109 -109
  190. package/md_cg/test_state_event_op.py +521 -521
  191. package/md_cg/test_stgidx_index_parity.py +1024 -1024
  192. package/md_cg/test_sustain_bounded.py +652 -652
  193. package/md_cg/test_trust_edge_reachability.py +405 -405
  194. package/md_cg/test_w7_redlines.py +659 -659
  195. package/md_cg/test_write_return_shape.py +919 -919
  196. package/md_cg/test_writepipe.py +228 -228
  197. package/md_cg/trust.py +1114 -1114
  198. package/md_cg/twophase.py +303 -303
  199. package/md_cg/whitebox.py +536 -536
  200. package/md_cg/whitebox_kb/wisdom/compose_engine.py +1634 -1634
  201. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +318 -318
  202. package/md_cg/whitebox_kb/wisdom/core/parser.py +1082 -1082
  203. package/md_cg/whitebox_kb/wisdom/md_access.py +490 -490
  204. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +497 -497
  205. package/md_cg/whitebox_kb/wisdom/mini_python.py +995 -995
  206. package/md_cg/whitebox_kb/wisdom/net_units.py +2900 -2900
  207. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +4060 -4060
  208. package/md_cg/writepipe.py +1337 -1337
  209. package/package.json +3 -2
  210. package/scripts/workspace_index.py +328 -0
  211. package/src/hooks.ts +30 -6
  212. package/src/index.ts +14 -5
  213. package/src/lib/hook_audit.ts +282 -256
  214. package/src/lib/mdcg_client.ts +469 -469
  215. package/src/lib/prompt_safety.ts +17 -3
  216. package/src/tools.ts +23 -1
package/md_cg/rollback.py CHANGED
@@ -1,657 +1,657 @@
1
- # -*- coding: utf-8 -*-
2
- """三档自治 · 回滚原语通用化(设计 v0.2 §四/§十一 · 批次③)。
3
-
4
- 设计 §四「回滚原语(已有,需通用化)」四条在本文档与实现中的落点:
5
-
6
- 1. **受保护快照面推广为一切 C/D/B 动作**:`_protected_history/<id>/<时间戳>.md`
7
- + `_protected_audit.jsonl`(protect.py 面)**面复用、语义泛化**——执行桥
8
- 经 `preimage()` 在**执行时点**调 `protect.snapshot_preimage()` 拍前像;
9
- `protect.py` 的既有 `snapshot()` / `guard_*` 行为**一字不改**(守卫钉死)。
10
- 2. **软删(D)**:`trash/` + 删除清单的既有 `restore` 接进统一口径——
11
- `rollback_mutation` 的 D 分支调 `cg.restore(force=True)`;restore 走 add
12
- 全量重建,探针实测与原件有字节差(多 `sensitivity: null` 键),故其后按
13
- 前像**校准**(`calibrated` 读数如实返回,不假装 restore 本身逐字节)。
14
- 3. **合并(B)**:聚合行 `- 【聚合 …】`(`forgetting.AGG_MARK`)**定向剥离**
15
- (`strip_aggregate_lines`)回退到合并前正文;fm 全量取前像——
16
- merge_count/last_merge_at/importance/merge_sources/protected 等**不可逆**
17
- (`-0.05` 会被 `min(1.0,…)` 截断、last_merge_at 旧值无从得知),前像快照
18
- 是唯一诚实来源。
19
- 4. **分数类(E)**:不属本批(设计 §四 明文「分数类:各模块既有 rollback」)。
20
-
21
- 统一回滚入口 `rollback_mutation(cg, mutation, ...)`:输入=变更单的**执行时点
22
- 载荷**(执行桥补全后的 `mutation_executed` 形态;CLI 从 decisions.jsonl 的
23
- `rec["mutation"]` 读回),按动作类分派 C/B/D 三条原语,回滚后做**残留核对**
24
- (边/索引条目/聚合行三面与前像时点影响面逐位对拍)与**逐字节比对前像**读数。
25
-
26
- 边界(如实登记):
27
- · 前像=执行时点快照——提议时点**不拍**(设计 §四:从提议到 accept 之间目标
28
- 可能被第三方改动,回滚必须撤销本变更本身);执行记录里的 `before` 引用由
29
- 执行桥补全,故对**未执行**(reject/fail-closed/pending)的变更单,本模块
30
- fail-closed 拒绝回滚(`rollback_gap`,不允许凭空猜一个前像)。
31
- · 加密库(覆写 `_seal_content` 的实例)密文层不保证逐字节可复现(每次封装
32
- 熵不同)——`bytes_equal_preimage` 在非加密库上成立(探针实测);
33
- 加密库语义为「明文内容 + 结构可恢复」,读数如实返回。
34
- · `restore` 的 tombstone 检查保留语义:回滚是「确认该删除属于本变更」的
35
- 处置,故显式 `force=True` 且 `reason` 写入返回体,不静默绕过。
36
- """
37
- from __future__ import annotations
38
- import sys
39
-
40
- import os
41
- import time
42
-
43
- from . import chain
44
- from . import forgetting as _forgetting
45
- from . import fsutil
46
- from . import nodefile
47
- from . import protect
48
- from . import subgraph as _subgraph
49
- from . import trust
50
-
51
- __all__ = [
52
- "RollbackError", "PreimageError",
53
- "command_for", "preimage", "collect_impact", "read_preimage",
54
- "strip_aggregate_lines", "rollback_mutation",
55
- "node_fingerprint", "preimage_fingerprint",
56
- ]
57
-
58
- #: 影响面「索引条目」对拍键(`collect_impact` 采集、残留核对比对,同一份口径)。
59
- _INDEX_KEYS = ("present", "path", "layer", "importance", "merge_count",
60
- "protected", "tags")
61
- #: 需要前像/可回滚的动作类(设计 §一:B 合并 / C 改写 / D 删除)。
62
- _ROLLBACK_ACTIONS = ("B", "C", "D")
63
- #: 盘面指纹取样的 frontmatter 键(**执行后像 / 前像 / 现盘面三侧同口径**)——
64
- #: 只取判据相关的稳定键:内容哈希之外,「执行之后又被标保护 / 换层 / 重判验证态」
65
- #: 同样属于「目标被动过」。刻意**不含** updated_at 之类每次落盘都变的键(否则
66
- #: 「内容没变、只重写了一遍」会大面积误判成漂移,把合法回滚一并拒掉)。
67
- _FINGERPRINT_FM_KEYS = ("immutable", "protection_reason", "layer", "sensitivity",
68
- "verification_state", "lifecycle_state", "self_state",
69
- "protected")
70
- #: 回滚留痕的审计 op(`_audit.jsonl` 一行)——常量单点,守卫按同名常量取用。
71
- ROLLBACK_AUDIT_OP = "rollback"
72
-
73
-
74
- # 生效条件:node 为 cg.get 返回形态(None/非 dict/假值=目标不在盘)时返回 {"present": False};否则返回 {"present": True, "content_hash": nodefile.content_hash(content), "fm": {k: fm.get(k) for k in _FINGERPRINT_FM_KEYS}}(正文与 frontmatter 都取不到时按空串/空 dict 计,不抛);
75
- def node_fingerprint(node):
76
- """盘面指纹(正文内容哈希 + 判据相关 fm 键)——**唯一实现**。
77
-
78
- 执行桥(`mdcos._mutation_execute`,执行落盘**之后**采「后像」)与回滚入口
79
- (回滚**之前**采「现盘面」)共用同一份口径——两侧各写一份哈希/键表,
80
- 漂移就会让闸门永远「匹配成功」而静默失效(同 `nodefile.content_hash`
81
- 的纪律:全仓唯一实现)。
82
- """
83
- if not isinstance(node, dict) or not node:
84
- return {"present": False}
85
- fm = node.get("frontmatter") or {}
86
- content = node.get("content") or ""
87
- return {"present": True,
88
- "content_hash": nodefile.content_hash(content),
89
- "fm": {k: fm.get(k) for k in _FINGERPRINT_FM_KEYS}}
90
-
91
-
92
- # 生效条件:fm/content 传入(缺省按空 dict/空串)时返回与 node_fingerprint 同形态的前像盘面指纹(present 恒 True、fm 只取 _FINGERPRINT_FM_KEYS 键);
93
- def preimage_fingerprint(fm, content):
94
- """前像盘面指纹——用于「现盘面是否**已经**等于前像」的幂等重放判定。"""
95
- fm = fm or {}
96
- return {"present": True,
97
- "content_hash": nodefile.content_hash(content or ""),
98
- "fm": {k: fm.get(k) for k in _FINGERPRINT_FM_KEYS}}
99
-
100
-
101
- class RollbackError(RuntimeError):
102
- """回滚无法执行(前像缺失/不可读、动作类未知等)——fail-closed。"""
103
-
104
- def __init__(self, code, message, **extra):
105
- super().__init__(message)
106
- self.code = code
107
- self.extra = extra
108
-
109
-
110
- class PreimageError(RuntimeError):
111
- """执行时点前像拍摄失败——执行桥据此 fail-closed(一切破坏性动作先留前像)。"""
112
-
113
-
114
- # 生效条件:pid 非空时返回 `python -X utf8 -m md_cg.rollback_cli --root "<root>" --pid <pid>` 形态的命令串(唯一构造点);pid 为空时抛 ValueError;
115
- def command_for(root, pid) -> str:
116
- """回滚命令串(**唯一构造点**,可执行——守卫实测演练同一条串)。
117
-
118
- 形态自定为 `md_cg.rollback_cli`:CLI 从 decisions.jsonl 读回该 pid 的
119
- 执行记录(`rec["mutation"]`,含执行时点前像/影响面/回滚命令),按动作类
120
- 分派统一回滚入口。root 用双引号包裹(路径可含空格)。
121
- """
122
- if not pid:
123
- raise ValueError("回滚命令缺 pid:无 pid 即无法定位执行记录——"
124
- "fail-closed 不构造命令串。")
125
- return ('python -X utf8 -m md_cg.rollback_cli --root "%s" --pid %s'
126
- % (root, pid))
127
-
128
-
129
- # 生效条件:action 归一后属 _ROLLBACK_ACTIONS 时——forgetting.prior_node 判目标不存在则返回 None(动作不会发生,由调用方走既有 target_missing/not_found 路径);目标在位于执行时点拍前像(protect.snapshot_preimage)并采集影响面与回滚命令,返回 {"before","impact","rollback"};拍摄失败(目标在位而快照未落)抛 PreimageError(fail-closed);action 不属 _ROLLBACK_ACTIONS 时返回 None;
130
- def preimage(cg, action, target, pid=None, reason=""):
131
- """执行时点前像(快照引用 + 影响面 + 回滚命令)——**唯一采集点**。
132
-
133
- 由执行桥(`mdcos._mutation_execute`)在动作原语落盘**之前**调用:
134
- 拍到的快照即「执行前一刻」的盘面(含提议之后、执行之前的第三方改动),
135
- 回滚据此撤销本变更本身(设计 §四:前像=执行时点,不是提议时点)。
136
-
137
- 返回 None 的两条路径(都=动作不会发生,无需留前像):
138
- · 动作类不属 B/C/D(未知动作类由执行桥的既有分支 fail-closed);
139
- · 目标节点不存在(既有原语会走 target_missing/not_found,执行桥的
140
- C 分支另有显式 target_missing 检查——本函数不抢它的错误形态)。
141
- """
142
- act = str(action or "").strip().upper()
143
- if act not in _ROLLBACK_ACTIONS:
144
- return None
145
- if _forgetting.prior_node(cg, target) is None:
146
- return None
147
- rel = protect.snapshot_preimage(cg, target, action=act, pid=pid,
148
- reason=reason)
149
- if rel is None:
150
- raise PreimageError(
151
- "执行时点前像拍摄失败(目标 %s 在位但快照未落盘)——"
152
- "一切破坏性动作先留前像(设计 §四/§六),本次 fail-closed 未执行。"
153
- % target)
154
- return {"before": rel,
155
- "impact": collect_impact(cg, target),
156
- "rollback": command_for(cg.root, pid)}
157
-
158
-
159
- # 生效条件:对任意 cg、node_id 均返回影响面读数 dict——{"edges": {"declared","children","parents"}, "index": {"present","path","layer","importance","merge_count","protected","tags"}, "agg_lines": [...]}(节点不可读时各面取空值/None,不抛);本函数只读,不产生副作用;
160
- def collect_impact(cg, node_id):
161
- """执行时点影响面读数(设计 §四:边 / 索引条目 / 聚合行)。
162
-
163
- 三个面都是**执行时点**(动作落盘前)的读数——回滚后由
164
- `rollback_mutation` 重采一次逐位对拍(残留核对:回滚后不得残留本变更
165
- 在任一面的痕迹)。采集走既有单点:`subgraph.children/parents_index`
166
- (声明式 ∪ 边式)、索引条目直读、聚合行按 `forgetting.AGG_MARK` 字面判。
167
- """
168
- try:
169
- node = cg.get(node_id)
170
- except Exception: # noqa: BLE001 —— 读面失败按空读数采
171
- node = None
172
- fm = (node or {}).get("frontmatter") or {}
173
- content = (node or {}).get("content") or ""
174
- entry = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id) \
175
- or {}
176
- return {
177
- "edges": {
178
- "declared": list(fm.get("edges") or []),
179
- "children": _subgraph.children(cg, node_id),
180
- "parents": list(_subgraph.parents_index(cg).get(node_id) or []),
181
- },
182
- "index": {
183
- "present": bool(entry),
184
- "path": entry.get("path"),
185
- "layer": entry.get("layer"),
186
- "importance": entry.get("importance"),
187
- "merge_count": entry.get("merge_count"),
188
- "protected": bool(entry.get("protected")),
189
- "tags": list(entry.get("tags") or []),
190
- },
191
- # 聚合行行号(1 起):正文里字面含 AGG_MARK 的行——forgetting.aggregate_line
192
- # 生成的形态是 `- 【聚合 月-日 时:分】…`;宽判据(含标记即计)与回滚核对同源。
193
- "agg_lines": [i + 1 for i, l in enumerate(content.splitlines())
194
- if _forgetting.AGG_MARK in l],
195
- }
196
-
197
-
198
- # 生效条件:rel 指向的文件不存在时抛 RollbackError(code="preimage_missing");存在则读取并以 cg._open_content(node_id, fm, raw) 对称解封,返回 (fm, content)——content 为 None(无密钥/身份不符)时抛 RollbackError(code="preimage_unreadable");文件含坏字节(非 UTF-8)无法解析时同样抛 RollbackError(code="preimage_unreadable")(fail-closed,不裸抛 UnicodeDecodeError);
199
- def read_preimage(cg, node_id, rel):
200
- """读执行时点前像文件(**与 snapshot_preimage 对称**:写走 _write_node 封装、
201
- 读走 _open_content 解封)——返回 (fm, content)。
202
-
203
- 注意:快照文件以节点文件同款 nodefile 序列化落盘;加密库中其内容为密封
204
- 形态,必须经解封钩子读,直接 nodefile.loads 会把密文当明文再次封装
205
- (双重封装)。非加密库两钩子恒等(探针实测逐字节一致)。
206
-
207
- 文件含坏字节(非 UTF-8)无法解析时抛 RollbackError(code="preimage_unreadable")
208
- ——fail-closed,不裸抛 UnicodeDecodeError。
209
- """
210
- p = os.path.join(cg.root, str(rel).replace("/", os.sep))
211
- if not os.path.isfile(p):
212
- raise RollbackError("preimage_missing",
213
- "前像文件不存在:%s——变更单可能未执行(无前像)"
214
- "或快照被移走;fail-closed 不猜一个前像。" % rel)
215
- try:
216
- with open(p, encoding="utf-8") as f:
217
- fm, raw = nodefile.loads(f.read())
218
- except UnicodeDecodeError as exc:
219
- # 坏字节/非 UTF-8:fail-closed——绝不让 UnicodeDecodeError 裸抛逃逸
220
- raise RollbackError("preimage_unreadable",
221
- "前像文件坏字节 / 非 UTF-8 无法解析:%s(%s)——"
222
- "fail-closed 不回滚。" % (rel, exc))
223
- content = cg._open_content(node_id, fm, raw)
224
- if content is None:
225
- raise RollbackError("preimage_unreadable",
226
- "前像不可解封(无密钥/身份不符):%s。" % rel)
227
- return fm, content
228
-
229
-
230
- # 生效条件:content 以 reference 为前缀且其后追加段逐段为「\n + 含 AGG_MARK 的非空行」时,逐段剥掉该追加段返回 (reference + 剩余段, 被剥行列表);不以 reference 为前缀、追加段形态不符、或 reference 为空时原样返回 (content, [])——不猜、不做字符串手术;
231
- def strip_aggregate_lines(content, reference):
232
- """定向剥离(设计 §四:合并回滚)——把**合并追加的聚合行**从正文里剥掉。
233
-
234
- 为什么是「前缀 + 追加段」判据而不是全局扫行:合并原语(`forgetting.
235
- reinforce` / `writelimit.converge_into`)对正文是**追加式**的
236
- (`aggregate_line`:`new_body = body + "\\n" + line`),回滚的目标是回到
237
- 前像正文——精确、可判、不误伤正文里历史遗留的聚合行(它们在前像里就已
238
- 存在,属「合并前正文」的一部分,不该动)。非追加式形态(第三方改写等)
239
- 一律不手术:返回原 content 与空剥离表,由调用方按读数决策。
240
-
241
- 返回 `(new_content, removed)`;追加段完全剥净时 `new_content == reference`
242
- (正常回滚场景,逐字节)。判据与 `forgetting.aggregate_line` 同款字面
243
- (`AGG_MARK` 常量单点在 forgetting.py,不另写第二份)。
244
- """
245
- text = content or ""
246
- ref = reference or ""
247
- if not ref or not text.startswith(ref):
248
- return text, []
249
- tail = text[len(ref):]
250
- removed = []
251
- while tail.startswith("\n"):
252
- nl = tail.find("\n", 1)
253
- line = tail[1:] if nl < 0 else tail[1:nl]
254
- if not line.strip() or _forgetting.AGG_MARK not in line:
255
- break # 空行/非聚合行:停止(不越界手术)
256
- removed.append(line)
257
- tail = "" if nl < 0 else tail[nl:]
258
- # 收尾:追加段的**纯换行尾**(`nodefile.dumps:313` 给不以换行结尾的正文
259
- # 补过一个尾换行,读回时即多出——探针实测:合并后读回形态为
260
- # `前像 + "\n" + 聚合行 + "\n"`)在已剥过行时一并剥净,使正常场景逐字节
261
- # 回到前像;未剥过行(removed 为空)不动分毫。
262
- if removed and not tail.strip("\n"):
263
- tail = ""
264
- return ref + tail, removed
265
-
266
-
267
- # 生效条件:落盘前先过保护闸——protect.is_immutable(cg, node_id) 为真且 preimage_fm 未带同一保护位(immutable is True 或 layer ∈ PROTECTED_LAYERS)时,force 为假即返回拒绝体 dict(不写盘);随后尝试 protect.snapshot(cg, node_id) 把将被覆盖的当前版本留档(失败不阻断),再经 cg._write_node 落盘、按 _node_entry 重算索引条目写入 index["nodes"] 与 _dirty 并失效 subgraph/chain/trust 三个反查缓存,返回 None(落盘完成);本函数只被本模块的回滚分支调用;
268
- def _land(cg, node_id, path, fm, content, preimage_fm=None, force=False,
269
- actor=None):
270
- """回滚的**唯一落盘口**:保护闸 + 前像快照 + 写盘 + 索引重算 + 缓存失效。
271
-
272
- 与 `mdcos.review_decide` merge 分支的定向 upsert 同款(`_node_entry`
273
- 与 `_scan_nodes` 同源,字段集零漂移);走 `_dirty`(**不走 `_stage`**
274
- ——它会虚增 bucket 计数,目标已在索引)。
275
-
276
- #352-A(2026-10-15):本口此前**三闸全无**——直接 `cg._write_node`,
277
- 不走 `protect.guard_overwrite` / `guard_write`,不留 `protect.snapshot`
278
- 前像副本,不写 `_audit`。后果:目标在执行之后被标 immutable 时,回滚
279
- 照样覆写并把 immutable 标记一并清掉,且事后无从知道被覆盖的是哪一版。
280
-
281
- 保护判据(**避免过度收紧**):只在「现盘面受保护 **而** 执行时点前像不带
282
- 同一保护位」时拒绝——保护位是本变更**之后**加的,覆写会把它抹掉。若前像
283
- 本身就带保护位(原节点本就 immutable / 在保护层),回滚只是把该保护位
284
- 如实还原,属正常回滚,**不拦**(否则 D 删除回滚永远回不来受保护节点)。
285
-
286
- 返回 None=落盘完成;返回 dict=拒绝体(`ok: False` + `error`),调用方
287
- 据此 fail-closed 返回,绝不静默覆写。
288
- """
289
- try:
290
- prot, why = protect.is_immutable(cg, node_id)
291
- except Exception: # noqa: BLE001 —— 判定失败按不拦(读面异常不升级成拒服务)
292
- prot, why = False, ""
293
- if prot and not force:
294
- _pre = preimage_fm or {}
295
- _pre_prot = (_pre.get("immutable") is True
296
- or str(_pre.get("layer") or "") in protect.PROTECTED_LAYERS)
297
- if not _pre_prot:
298
- return {"ok": False, "error": "protected_target",
299
- "protection": why,
300
- "detail": "回滚目标 %s 现受写保护(%s),而执行时点前像不带"
301
- "该保护位——保护位是本变更**之后**加的,覆写会把它"
302
- "一并清掉;fail-closed 未覆写(确认后加 --force)。"
303
- % (node_id, why),
304
- "hint": "如确需回滚:先解除保护(mdcg_protect 面)或对本单"
305
- "显式 --force;二者都会留痕。"}
306
- # 落盘前把**将被覆盖的当前版本**留档(protect 面既有单点,不另写第二套)。
307
- try:
308
- protect.snapshot(cg, node_id)
309
- except Exception: # noqa: BLE001 —— 留档失败不阻断回滚本身
310
- pass
311
- cg._write_node(node_id, path, fm, content)
312
- layer = str(fm.get("layer") or "knowledge")
313
- try:
314
- e = cg._node_entry(path, layer, fm, content)
315
- except Exception: # noqa: BLE001 —— 重算失败不阻断回滚落盘
316
- e = None
317
- if e is not None:
318
- cg.index["nodes"][node_id] = e
319
- cg._dirty[node_id] = e
320
- _subgraph.invalidate_cache(cg)
321
- chain.invalidate_cache(cg)
322
- trust.invalidate_cache(cg)
323
-
324
-
325
- # 生效条件:node_id 的索引条目存在时返回其盘面绝对路径;不存在或条目无 path 时返回 None;
326
- def _disk_path(cg, node_id):
327
- e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id) or {}
328
- p = e.get("path")
329
- return os.path.join(cg.root, p) if p else None
330
-
331
-
332
- # 生效条件:对任意路径返回 bytes(不存在/不可读时返回 None——比对判据按 None 处理,不抛);
333
- def _bytes_of(path):
334
- if not path:
335
- return None
336
- try:
337
- with open(path, "rb") as f:
338
- return f.read()
339
- except OSError:
340
- return None
341
-
342
-
343
- # 生效条件:path 与 rel 都取到字节时返回两者逐字节相等的布尔;任一侧字节取不到时返回 False(不可证即不认——比对判据 fail-closed);
344
- def _bytes_equal(path, rel_path):
345
- a, b = _bytes_of(path), _bytes_of(rel_path)
346
- return a is not None and b is not None and a == b
347
-
348
-
349
- # 生效条件:C 改写回滚——索引中节点在位(不在位返回 ok False error target_missing)时把前像 (fm0,c0) 落到节点盘面 path(_land;保护闸拒绝即原样返回该拒绝体)+ flush,返回读数 dict;
350
- def _rollback_rewrite(cg, tgt, fm0, c0, force=False, actor=None):
351
- path = _disk_path(cg, tgt)
352
- if path is None or _forgetting.prior_node(cg, tgt) is None:
353
- return {"ok": False, "error": "target_missing",
354
- "detail": "C 回滚:目标 %s 不在索引中——本变更之外还有变化,"
355
- "fail-closed 不猜落点(如属误删可先 restore)。" % tgt}
356
- refuse = _land(cg, tgt, path, fm0, c0, preimage_fm=fm0, force=force,
357
- actor=actor)
358
- if refuse is not None:
359
- return refuse
360
- cg.flush()
361
- return {"ok": True, "restored_path": os.path.relpath(path, cg.root)
362
- .replace("\\", "/"), "method": "preimage"}
363
-
364
-
365
- # 生效条件:B 合并回滚——目标在位(不在位返回 ok False error target_missing)时先按 strip_aggregate_lines 剥离追加的聚合行,剥离结果与前像正文逐字节相等则正文取剥离结果、否则取前像正文(stripped_ok 如实记录),fm 全量取前像 (fm0),经 _land 落盘 + flush;返回读数 dict(removed_lines/stripped_ok/method);
366
- def _rollback_merge(cg, tgt, fm0, c0, force=False, actor=None):
367
- cur = None
368
- try:
369
- cur = cg.get(tgt)
370
- except Exception: # noqa: BLE001
371
- cur = None
372
- if not cur:
373
- return {"ok": False, "error": "target_missing",
374
- "detail": "B 回滚:目标 %s 不可读——本变更之外还有变化,"
375
- "fail-closed 不猜落点。" % tgt}
376
- path = _disk_path(cg, tgt)
377
- if path is None:
378
- return {"ok": False, "error": "target_missing",
379
- "detail": "B 回滚:目标 %s 索引条目缺 path。" % tgt}
380
- c1 = cur.get("content") or ""
381
- stripped, removed = strip_aggregate_lines(c1, c0)
382
- stripped_ok = stripped == c0
383
- # 正文取剥离结果(正常场景逐字节==前像);剥离不精确(追加段含非聚合行等)
384
- # 时以快照正文为准——回滚的判据是「回到前像」,stripped_ok 如实记录。
385
- # fm 全量取前像:merge_count/last_merge_at/importance(+0.05 可被 1.0 截断)/
386
- # merge_sources/protected/lifecycle_state 等均不可逆,前像是唯一诚实来源。
387
- refuse = _land(cg, tgt, path, fm0, stripped if stripped_ok else c0,
388
- preimage_fm=fm0, force=force, actor=actor)
389
- if refuse is not None:
390
- return refuse
391
- cg.flush()
392
- return {"ok": True, "restored_path": os.path.relpath(path, cg.root)
393
- .replace("\\", "/"),
394
- "method": "strip_aggregate_lines" if stripped_ok else "preimage",
395
- "stripped_ok": stripped_ok, "removed_lines": removed}
396
-
397
-
398
- # 生效条件:D 删除回滚——先调既有 cg.restore(tgt, force=True)(trash + 删除清单口径);restore 失败且(错误非 not_in_trash 或节点仍不在库)时返回 ok False(detail 带 restore 原返回体);restore 成功、或 not_in_trash 而节点已在库(此前已回滚过=幂等重放)时继续:按前像做逐字节校准(盘面与快照字节不等时经 _land 以 (fm0,c0) 重写,calibrated=True 如实记录——探针实测 restore 重建会多 sensitivity:null 键),返回读数 dict(replayed 标注重放);
399
- def _rollback_delete(cg, tgt, fm0, c0, rel, force=False, actor=None):
400
- res = cg.restore(tgt, force=True)
401
- replayed = (not res.get("ok")) and res.get("error") == "not_in_trash" \
402
- and _forgetting.prior_node(cg, tgt) is not None
403
- if not res.get("ok") and not replayed:
404
- return {"ok": False, "error": res.get("error") or "restore_failed",
405
- "detail": {"restore": res},
406
- "hint": "D 回滚走既有 restore(trash + 删除清单)——失败即"
407
- "未恢复;如 trash 缺失可核对前像目录。"}
408
- path = _disk_path(cg, tgt)
409
- if path is None:
410
- return {"ok": False, "error": "target_missing",
411
- "detail": "D 回滚:restore 返回 ok 但索引无条目。"}
412
- pre_p = os.path.join(cg.root, str(rel).replace("/", os.sep))
413
- restore_bytes_equal = _bytes_equal(path, pre_p)
414
- calibrated = False
415
- if not restore_bytes_equal:
416
- # 校准(如实):restore 的 add 全量重建与快照存在字节差(实测 =
417
- # 多 `sensitivity: null` 键)——回滚的判据是「回到前像」,故以快照
418
- # 重写一次;`restore_bytes_equal=False` 读数保留,不假装 restore
419
- # 本身逐字节。
420
- refuse = _land(cg, tgt, path, fm0, c0, preimage_fm=fm0, force=force,
421
- actor=actor)
422
- if refuse is not None:
423
- return refuse
424
- calibrated = True
425
- cg.flush()
426
- return {"ok": True, "restored_path": os.path.relpath(path, cg.root)
427
- .replace("\\", "/"),
428
- "method": "restore+preimage_calibration" if calibrated
429
- else "restore",
430
- "replayed": replayed,
431
- "calibrated": calibrated,
432
- "restore_bytes_equal": restore_bytes_equal}
433
-
434
-
435
- # 生效条件:before_impact 与 after 两个影响面 dict(缺面按空 dict)逐面返回对拍布尔——{"agg_lines_restored","edges_restored","index_restored"};
436
- def _residual(before_impact, after):
437
- bi = before_impact if isinstance(before_impact, dict) else {}
438
- return {
439
- "agg_lines_restored": (after.get("agg_lines") or [])
440
- == (bi.get("agg_lines") or []),
441
- "edges_restored": (after.get("edges") or {}) == (bi.get("edges") or {}),
442
- "index_restored": {k: (after.get("index") or {}).get(k)
443
- for k in _INDEX_KEYS}
444
- == {k: (bi.get("index") or {}).get(k)
445
- for k in _INDEX_KEYS},
446
- }
447
-
448
-
449
- # 生效条件:cg 为 None 或 cg.get 抛异常/返回假值时返回 None,否则返回 cg.get(node_id) 的结果(读面失败一律按「目标不可读」计,不抛);
450
- def _node_of(cg, node_id):
451
- if cg is None:
452
- return None
453
- try:
454
- return cg.get(node_id)
455
- except Exception: # noqa: BLE001
456
- return None
457
-
458
-
459
- # 生效条件:pid 为真且 cg.decisions() 可读时,返回本 pid 最后一条 decision=="accept" 记录**之后**、decision=="accept" 且 rec["mutation"]["target"] 等于 tgt 的记录 pid 列表(顺序同盘面);**取不到顺序(pid 为空 / 无该 pid / decisions 不可读)时返回 None**(=判据不可用,调用方据此不拦——不把「取不到证据」升级成拒绝);
460
- def _later_executions(cg, tgt, pid):
461
- """本单执行之后、同目标的 accept 执行记录(旧执行记录无 after_hash 时的兜底判据)。
462
-
463
- decisions.jsonl 是 append-only,故「盘面顺序」即「时间顺序」——同一 pid 的
464
- 最后一条 accept 之后出现的、target 相同的 accept 执行记录,就是「本单之后
465
- 目标又被执行过一次」的证据面。
466
- """
467
- if not pid or cg is None:
468
- return None
469
- try:
470
- rows = list(cg.decisions())
471
- except Exception: # noqa: BLE001
472
- return None
473
- idx = None
474
- for i, r in enumerate(rows):
475
- if r.get("pid") == pid and r.get("decision") == "accept":
476
- idx = i
477
- if idx is None:
478
- return None
479
- out = []
480
- for r in rows[idx + 1:]:
481
- if r.get("decision") != "accept":
482
- continue
483
- mu = r.get("mutation")
484
- if isinstance(mu, dict) and str(mu.get("target") or "") == tgt:
485
- out.append(r.get("pid"))
486
- return out
487
-
488
-
489
- # 生效条件:对任意 cg/tgt/act/rel/res 都无条件返回布尔——先尝试 cg._audit("rollback", tgt, **meta)(MdCGOS 面,带 tenant/session/clearance 归因),失败或 cg 无 _audit 时退化为向 cg.root/_audit.jsonl 追加一行 {"t","op":"rollback","id","actor","action","pid","preimage","reason","method","bytes_equal_preimage"};两种情况都不抛(留痕失败不阻断已完成的回滚);
490
- def _audit_rollback(cg, tgt, act, rel, res, actor=None, pid=None, reason=""):
491
- """回滚留痕(`_audit.jsonl` 一行 op="rollback")——#352-A。
492
-
493
- 改前本模块的 docstring 写「审计由各分支的落盘 / restore 留痕承担」,而
494
- `_land` 这一支(C/B 以及 D 的校准路径)**一行审计都不写**:回滚是唯一
495
- 不写台账的破坏性写口(步骤④准入读数第 3 条即为「R3 破坏可逆读数缺失」)。
496
- 本函数是回滚留痕的**唯一落点**(op 常量集中在 `ROLLBACK_AUDIT_OP`)。
497
- """
498
- meta = {"action": act, "pid": pid, "preimage": rel,
499
- "reason": str(reason or ""), "method": res.get("method"),
500
- "bytes_equal_preimage": res.get("bytes_equal_preimage")}
501
- fn = getattr(cg, "_audit", None)
502
- if callable(fn):
503
- try:
504
- fn(ROLLBACK_AUDIT_OP, tgt, **meta)
505
- return True
506
- except Exception as e: # noqa: BLE001 —— 退化为直写
507
- # #472 站点 2:**退化不再静默**(原为 `pass`)——写 stderr 留痕,并把本行标记为
508
- # 「链外(已知退化)」,使 mdcos._audit_chain_verify 判为 known_degraded(**软信号**),
509
- # **而非** unknown_foreign(后者是「有人插入」,安全要报)——**两者不得同一信号**。
510
- try:
511
- from .mdcos import AUDIT_KNOWN_DEGRADED as _KD
512
- except Exception: # 循环导入等:退化为字面量
513
- # ⚠️ **已登记的已知偏差**(issue #472,Lead 裁定「允许但必须登记」):
514
- # 1) **这是回落副本、不是真源** —— 真源是 `mdcos.AUDIT_KNOWN_DEGRADED`;
515
- # 2) **回落触发条件**:`from .mdcos import ...` 失败(循环导入等);
516
- # 3) **已知漂移风险**:若有人只改 mdcos 侧的值,**回落到字面量的这条路径会静默
517
- # 地用旧值** —— 这是「两份副本必然漂」在语言机制层的又一次落地。
518
- # ⇒ 该偏差**已被腿钉住**:`md_cg/test_issue472_audit_chain.py` 的 C2 腿断言
519
- # 「本回落字面量 == mdcos.AUDIT_KNOWN_DEGRADED 的真值」(AST 静态比对,
520
- # 不需构造循环导入 ⇒ 可行)。
521
- _KD = "AUDIT_KNOWN_DEGRADED"
522
- sys.stderr.write("[rollback] cg._audit 不可用,退化直写(链外·已知退化):%s: %s"
523
- % (type(e).__name__, e) + chr(10))
524
- _degraded_mark = _KD
525
- else:
526
- _degraded_mark = None
527
- rec = {"t": time.time(), "op": ROLLBACK_AUDIT_OP, "id": tgt,
528
- "actor": actor}
529
- if _degraded_mark:
530
- rec["chain"] = _degraded_mark
531
- rec.update(meta)
532
- try:
533
- fsutil.append_jsonl(os.path.join(cg.root, "_audit.jsonl"), rec)
534
- return True
535
- except Exception: # noqa: BLE001
536
- return False
537
-
538
-
539
- # 生效条件:mutation 为 dict 且含非空 target 与 before(否则返回 ok False error mutation_missing/rollback_gap 带 hint);before 文件不可读按 RollbackError(code) 返回 ok False;现盘面与执行后像不等且未显式 force 时返回 ok False error drifted_since_execute(现盘面已等于前像=幂等重放,放行);dry_run 为真时只返回读数不落盘;动作类属 C/B/D 时按对应分支回滚,成功再重采影响面做残留对拍、做逐字节比对并向 _audit.jsonl 写一行 op="rollback",返回 {"ok": True, "action","target","preimage","restored_path","bytes_equal_preimage","residual","method",...};动作类不属 C/B/D 时返回 ok False error rollback_action_unknown;本函数不抛(可预期错误一律返回体);
540
- def rollback_mutation(cg, mutation, reason="", actor=None, force=False,
541
- pid=None, dry_run=False):
542
- """统一回滚入口(设计 §四 四条:C/B/D 分派 + 残留核对 + 逐字节比对)。
543
-
544
- 输入=**执行时点载荷**(`autonomy_modes.mutation_executed` 形态,含
545
- action/target/before/impact/rollback[/after_hash]);CLI 从 decisions.jsonl
546
- 的 `rec["mutation"]` 读回。`reason`/`actor`/`pid` 进返回体与回滚留痕。
547
-
548
- #352-A(2026-10-15)**漂移闸**(`drifted_since_execute`):回滚的语义是
549
- 「撤销**本变更本身**、不抹第三方改动」(`autonomy_modes.mutation_payload`
550
- :551-555 明文),而改前只处理了「提议→执行之间」的第三方改动(前像取执行
551
- 时点),**没处理「执行→回滚之间」的改动**——回滚用执行时点前像**整体覆写**,
552
- 执行之后写进去的正文(含另一张合并单追加的聚合行、删除后同 id 的重建、
553
- 新增的 immutable 标记)一并消失,回执还报 `ok:True`。本闸的比较面:
554
-
555
- · `after_hash`(执行桥在执行落盘**之后**采的「后像」指纹,
556
- `md_cg/mdcos.py` 的 `_mutation_execute` 处补全)与现盘面指纹不等 ⇒ 拒;
557
- · 旧执行记录(无 `after_hash`)⇒ 退化为扫 decisions.jsonl 同目标、本单
558
- **之后**的 accept 执行记录,有则拒;顺序取不到(pid 未知)时不拦
559
- (不把「取不到证据」升级成拒绝)。
560
-
561
- **幂等重放豁免**:现盘面**已经等于前像**时直接放行——回滚本身已做过(或
562
- 节点已处于前像状态),此时「覆写」是无操作,抹不掉任何东西。这条是既有
563
- 守卫 Q/R/S 组的「回滚命令串二次演练(幂等重放,rc=0)」得以保持的判据。
564
-
565
- `force=True` 跳过漂移闸与 `_land` 的保护闸(`rollback_cli --force`);
566
- `dry_run=True` 只回报将被覆写的差异、不落盘。
567
- """
568
- if not isinstance(mutation, dict):
569
- return {"ok": False, "error": "mutation_missing",
570
- "hint": "回滚入口需要变更单的执行时点载荷(dict)——"
571
- "decisions.jsonl 的 rec[\"mutation\"]。"}
572
- act = str(mutation.get("action") or "").strip().upper()
573
- tgt = str(mutation.get("target") or "").strip()
574
- rel = mutation.get("before")
575
- if not tgt:
576
- return {"ok": False, "error": "mutation_missing",
577
- "hint": "载荷缺 target——无法定位回滚对象。"}
578
- if not rel:
579
- return {"ok": False, "error": "rollback_gap",
580
- "hint": "载荷缺 before(执行时点前像引用):该变更单**未执行**"
581
- "(reject / fail-closed / pending)或执行记录不完整——"
582
- "fail-closed 不猜一个前像(前像必须来自执行时点)。"}
583
- if act not in _ROLLBACK_ACTIONS:
584
- return {"ok": False, "error": "rollback_action_unknown",
585
- "action": act or None,
586
- "hint": "回滚只覆盖 C 改写 / B 合并 / D 删除(设计 §四);"
587
- "动作类 %r 未定义回滚——fail-closed。" % (act or None)}
588
- try:
589
- fm0, c0 = read_preimage(cg, tgt, rel)
590
- except RollbackError as exc:
591
- return {"ok": False, "error": exc.code, "detail": str(exc),
592
- "action": act, "target": tgt, "preimage": rel}
593
- # ---- 漂移闸(#352-A):执行之后目标又被写过 ⇒ fail-closed,不整体覆写 ----
594
- cur_fp = node_fingerprint(_node_of(cg, tgt))
595
- pre_fp = preimage_fingerprint(fm0, c0)
596
- drift = None
597
- if cur_fp != pre_fp and not force: # 相等=幂等重放,放行(见 docstring)
598
- want = mutation.get("after_hash")
599
- if isinstance(want, dict):
600
- if cur_fp != want:
601
- drift = {"ok": False, "error": "drifted_since_execute",
602
- "action": act, "target": tgt, "preimage": rel,
603
- "current": cur_fp, "expected_after_execute": want,
604
- "hint": "本单**执行之后**目标又被写过——回滚会用执行时点"
605
- "前像整体覆写,把这些写入一并抹掉(设计 §四:"
606
- "回滚只撤销本变更本身、不抹第三方改动)。"
607
- "已 fail-closed 未覆写:先核对上面的 current / "
608
- "expected_after_execute 差异,确需回滚加 --force。",
609
- "reason": str(reason or ""), "actor": actor}
610
- else:
611
- later = _later_executions(cg, tgt, pid)
612
- if later:
613
- drift = {"ok": False, "error": "drifted_since_execute",
614
- "action": act, "target": tgt, "preimage": rel,
615
- "current": cur_fp, "later_executions": later,
616
- "hint": "该执行记录无 after_hash(改前落盘)——按"
617
- "decisions.jsonl 判据:本单之后同目标还有 accept "
618
- "执行记录 %s,回滚会抹掉它们的写入;fail-closed "
619
- "未覆写(确需回滚加 --force)。" % (later,),
620
- "reason": str(reason or ""), "actor": actor}
621
- if drift is not None:
622
- if dry_run:
623
- out = dict(drift, dry_run=True, would_apply=False)
624
- return out
625
- return drift
626
- if dry_run:
627
- return {"ok": True, "dry_run": True, "would_apply": True,
628
- "action": act, "target": tgt, "preimage": rel,
629
- "current": cur_fp, "preimage_state": pre_fp,
630
- "expected_after_execute": mutation.get("after_hash"),
631
- "reason": str(reason or ""), "actor": actor}
632
- if act == "C":
633
- res = _rollback_rewrite(cg, tgt, fm0, c0, force=force, actor=actor)
634
- elif act == "B":
635
- res = _rollback_merge(cg, tgt, fm0, c0, force=force, actor=actor)
636
- else: # "D"
637
- res = _rollback_delete(cg, tgt, fm0, c0, rel, force=force, actor=actor)
638
- if not res.get("ok"):
639
- out = dict(res)
640
- out.update({"action": act, "target": tgt, "preimage": rel})
641
- return out
642
- # 残留核对(设计 §十一 红项面):重采影响面,与前像时点记录逐面对拍。
643
- after = collect_impact(cg, tgt)
644
- residual = _residual(mutation.get("impact"), after)
645
- # 逐字节比对前像(设计 §十一):盘面 vs 快照文件。
646
- pre_p = os.path.join(cg.root, str(rel).replace("/", os.sep))
647
- disk_p = _disk_path(cg, tgt)
648
- out = {"ok": True, "action": act, "target": tgt, "preimage": rel,
649
- "rollback_command": mutation.get("rollback") or "",
650
- "reason": str(reason or ""), "actor": actor, "pid": pid,
651
- "bytes_equal_preimage": _bytes_equal(disk_p, pre_p),
652
- "residual": residual, "impact_after": after}
653
- out.update(res)
654
- # 回滚留痕(#352-A):唯一不变更 _audit 的破坏性写口就此收口。
655
- out["audited"] = _audit_rollback(cg, tgt, act, rel, out, actor=actor,
656
- pid=pid, reason=reason)
657
- return out
1
+ # -*- coding: utf-8 -*-
2
+ """三档自治 · 回滚原语通用化(设计 v0.2 §四/§十一 · 批次③)。
3
+
4
+ 设计 §四「回滚原语(已有,需通用化)」四条在本文档与实现中的落点:
5
+
6
+ 1. **受保护快照面推广为一切 C/D/B 动作**:`_protected_history/<id>/<时间戳>.md`
7
+ + `_protected_audit.jsonl`(protect.py 面)**面复用、语义泛化**——执行桥
8
+ 经 `preimage()` 在**执行时点**调 `protect.snapshot_preimage()` 拍前像;
9
+ `protect.py` 的既有 `snapshot()` / `guard_*` 行为**一字不改**(守卫钉死)。
10
+ 2. **软删(D)**:`trash/` + 删除清单的既有 `restore` 接进统一口径——
11
+ `rollback_mutation` 的 D 分支调 `cg.restore(force=True)`;restore 走 add
12
+ 全量重建,探针实测与原件有字节差(多 `sensitivity: null` 键),故其后按
13
+ 前像**校准**(`calibrated` 读数如实返回,不假装 restore 本身逐字节)。
14
+ 3. **合并(B)**:聚合行 `- 【聚合 …】`(`forgetting.AGG_MARK`)**定向剥离**
15
+ (`strip_aggregate_lines`)回退到合并前正文;fm 全量取前像——
16
+ merge_count/last_merge_at/importance/merge_sources/protected 等**不可逆**
17
+ (`-0.05` 会被 `min(1.0,…)` 截断、last_merge_at 旧值无从得知),前像快照
18
+ 是唯一诚实来源。
19
+ 4. **分数类(E)**:不属本批(设计 §四 明文「分数类:各模块既有 rollback」)。
20
+
21
+ 统一回滚入口 `rollback_mutation(cg, mutation, ...)`:输入=变更单的**执行时点
22
+ 载荷**(执行桥补全后的 `mutation_executed` 形态;CLI 从 decisions.jsonl 的
23
+ `rec["mutation"]` 读回),按动作类分派 C/B/D 三条原语,回滚后做**残留核对**
24
+ (边/索引条目/聚合行三面与前像时点影响面逐位对拍)与**逐字节比对前像**读数。
25
+
26
+ 边界(如实登记):
27
+ · 前像=执行时点快照——提议时点**不拍**(设计 §四:从提议到 accept 之间目标
28
+ 可能被第三方改动,回滚必须撤销本变更本身);执行记录里的 `before` 引用由
29
+ 执行桥补全,故对**未执行**(reject/fail-closed/pending)的变更单,本模块
30
+ fail-closed 拒绝回滚(`rollback_gap`,不允许凭空猜一个前像)。
31
+ · 加密库(覆写 `_seal_content` 的实例)密文层不保证逐字节可复现(每次封装
32
+ 熵不同)——`bytes_equal_preimage` 在非加密库上成立(探针实测);
33
+ 加密库语义为「明文内容 + 结构可恢复」,读数如实返回。
34
+ · `restore` 的 tombstone 检查保留语义:回滚是「确认该删除属于本变更」的
35
+ 处置,故显式 `force=True` 且 `reason` 写入返回体,不静默绕过。
36
+ """
37
+ from __future__ import annotations
38
+ import sys
39
+
40
+ import os
41
+ import time
42
+
43
+ from . import chain
44
+ from . import forgetting as _forgetting
45
+ from . import fsutil
46
+ from . import nodefile
47
+ from . import protect
48
+ from . import subgraph as _subgraph
49
+ from . import trust
50
+
51
+ __all__ = [
52
+ "RollbackError", "PreimageError",
53
+ "command_for", "preimage", "collect_impact", "read_preimage",
54
+ "strip_aggregate_lines", "rollback_mutation",
55
+ "node_fingerprint", "preimage_fingerprint",
56
+ ]
57
+
58
+ #: 影响面「索引条目」对拍键(`collect_impact` 采集、残留核对比对,同一份口径)。
59
+ _INDEX_KEYS = ("present", "path", "layer", "importance", "merge_count",
60
+ "protected", "tags")
61
+ #: 需要前像/可回滚的动作类(设计 §一:B 合并 / C 改写 / D 删除)。
62
+ _ROLLBACK_ACTIONS = ("B", "C", "D")
63
+ #: 盘面指纹取样的 frontmatter 键(**执行后像 / 前像 / 现盘面三侧同口径**)——
64
+ #: 只取判据相关的稳定键:内容哈希之外,「执行之后又被标保护 / 换层 / 重判验证态」
65
+ #: 同样属于「目标被动过」。刻意**不含** updated_at 之类每次落盘都变的键(否则
66
+ #: 「内容没变、只重写了一遍」会大面积误判成漂移,把合法回滚一并拒掉)。
67
+ _FINGERPRINT_FM_KEYS = ("immutable", "protection_reason", "layer", "sensitivity",
68
+ "verification_state", "lifecycle_state", "self_state",
69
+ "protected")
70
+ #: 回滚留痕的审计 op(`_audit.jsonl` 一行)——常量单点,守卫按同名常量取用。
71
+ ROLLBACK_AUDIT_OP = "rollback"
72
+
73
+
74
+ # 生效条件:node 为 cg.get 返回形态(None/非 dict/假值=目标不在盘)时返回 {"present": False};否则返回 {"present": True, "content_hash": nodefile.content_hash(content), "fm": {k: fm.get(k) for k in _FINGERPRINT_FM_KEYS}}(正文与 frontmatter 都取不到时按空串/空 dict 计,不抛);
75
+ def node_fingerprint(node):
76
+ """盘面指纹(正文内容哈希 + 判据相关 fm 键)——**唯一实现**。
77
+
78
+ 执行桥(`mdcos._mutation_execute`,执行落盘**之后**采「后像」)与回滚入口
79
+ (回滚**之前**采「现盘面」)共用同一份口径——两侧各写一份哈希/键表,
80
+ 漂移就会让闸门永远「匹配成功」而静默失效(同 `nodefile.content_hash`
81
+ 的纪律:全仓唯一实现)。
82
+ """
83
+ if not isinstance(node, dict) or not node:
84
+ return {"present": False}
85
+ fm = node.get("frontmatter") or {}
86
+ content = node.get("content") or ""
87
+ return {"present": True,
88
+ "content_hash": nodefile.content_hash(content),
89
+ "fm": {k: fm.get(k) for k in _FINGERPRINT_FM_KEYS}}
90
+
91
+
92
+ # 生效条件:fm/content 传入(缺省按空 dict/空串)时返回与 node_fingerprint 同形态的前像盘面指纹(present 恒 True、fm 只取 _FINGERPRINT_FM_KEYS 键);
93
+ def preimage_fingerprint(fm, content):
94
+ """前像盘面指纹——用于「现盘面是否**已经**等于前像」的幂等重放判定。"""
95
+ fm = fm or {}
96
+ return {"present": True,
97
+ "content_hash": nodefile.content_hash(content or ""),
98
+ "fm": {k: fm.get(k) for k in _FINGERPRINT_FM_KEYS}}
99
+
100
+
101
+ class RollbackError(RuntimeError):
102
+ """回滚无法执行(前像缺失/不可读、动作类未知等)——fail-closed。"""
103
+
104
+ def __init__(self, code, message, **extra):
105
+ super().__init__(message)
106
+ self.code = code
107
+ self.extra = extra
108
+
109
+
110
+ class PreimageError(RuntimeError):
111
+ """执行时点前像拍摄失败——执行桥据此 fail-closed(一切破坏性动作先留前像)。"""
112
+
113
+
114
+ # 生效条件:pid 非空时返回 `python -X utf8 -m md_cg.rollback_cli --root "<root>" --pid <pid>` 形态的命令串(唯一构造点);pid 为空时抛 ValueError;
115
+ def command_for(root, pid) -> str:
116
+ """回滚命令串(**唯一构造点**,可执行——守卫实测演练同一条串)。
117
+
118
+ 形态自定为 `md_cg.rollback_cli`:CLI 从 decisions.jsonl 读回该 pid 的
119
+ 执行记录(`rec["mutation"]`,含执行时点前像/影响面/回滚命令),按动作类
120
+ 分派统一回滚入口。root 用双引号包裹(路径可含空格)。
121
+ """
122
+ if not pid:
123
+ raise ValueError("回滚命令缺 pid:无 pid 即无法定位执行记录——"
124
+ "fail-closed 不构造命令串。")
125
+ return ('python -X utf8 -m md_cg.rollback_cli --root "%s" --pid %s'
126
+ % (root, pid))
127
+
128
+
129
+ # 生效条件:action 归一后属 _ROLLBACK_ACTIONS 时——forgetting.prior_node 判目标不存在则返回 None(动作不会发生,由调用方走既有 target_missing/not_found 路径);目标在位于执行时点拍前像(protect.snapshot_preimage)并采集影响面与回滚命令,返回 {"before","impact","rollback"};拍摄失败(目标在位而快照未落)抛 PreimageError(fail-closed);action 不属 _ROLLBACK_ACTIONS 时返回 None;
130
+ def preimage(cg, action, target, pid=None, reason=""):
131
+ """执行时点前像(快照引用 + 影响面 + 回滚命令)——**唯一采集点**。
132
+
133
+ 由执行桥(`mdcos._mutation_execute`)在动作原语落盘**之前**调用:
134
+ 拍到的快照即「执行前一刻」的盘面(含提议之后、执行之前的第三方改动),
135
+ 回滚据此撤销本变更本身(设计 §四:前像=执行时点,不是提议时点)。
136
+
137
+ 返回 None 的两条路径(都=动作不会发生,无需留前像):
138
+ · 动作类不属 B/C/D(未知动作类由执行桥的既有分支 fail-closed);
139
+ · 目标节点不存在(既有原语会走 target_missing/not_found,执行桥的
140
+ C 分支另有显式 target_missing 检查——本函数不抢它的错误形态)。
141
+ """
142
+ act = str(action or "").strip().upper()
143
+ if act not in _ROLLBACK_ACTIONS:
144
+ return None
145
+ if _forgetting.prior_node(cg, target) is None:
146
+ return None
147
+ rel = protect.snapshot_preimage(cg, target, action=act, pid=pid,
148
+ reason=reason)
149
+ if rel is None:
150
+ raise PreimageError(
151
+ "执行时点前像拍摄失败(目标 %s 在位但快照未落盘)——"
152
+ "一切破坏性动作先留前像(设计 §四/§六),本次 fail-closed 未执行。"
153
+ % target)
154
+ return {"before": rel,
155
+ "impact": collect_impact(cg, target),
156
+ "rollback": command_for(cg.root, pid)}
157
+
158
+
159
+ # 生效条件:对任意 cg、node_id 均返回影响面读数 dict——{"edges": {"declared","children","parents"}, "index": {"present","path","layer","importance","merge_count","protected","tags"}, "agg_lines": [...]}(节点不可读时各面取空值/None,不抛);本函数只读,不产生副作用;
160
+ def collect_impact(cg, node_id):
161
+ """执行时点影响面读数(设计 §四:边 / 索引条目 / 聚合行)。
162
+
163
+ 三个面都是**执行时点**(动作落盘前)的读数——回滚后由
164
+ `rollback_mutation` 重采一次逐位对拍(残留核对:回滚后不得残留本变更
165
+ 在任一面的痕迹)。采集走既有单点:`subgraph.children/parents_index`
166
+ (声明式 ∪ 边式)、索引条目直读、聚合行按 `forgetting.AGG_MARK` 字面判。
167
+ """
168
+ try:
169
+ node = cg.get(node_id)
170
+ except Exception: # noqa: BLE001 —— 读面失败按空读数采
171
+ node = None
172
+ fm = (node or {}).get("frontmatter") or {}
173
+ content = (node or {}).get("content") or ""
174
+ entry = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id) \
175
+ or {}
176
+ return {
177
+ "edges": {
178
+ "declared": list(fm.get("edges") or []),
179
+ "children": _subgraph.children(cg, node_id),
180
+ "parents": list(_subgraph.parents_index(cg).get(node_id) or []),
181
+ },
182
+ "index": {
183
+ "present": bool(entry),
184
+ "path": entry.get("path"),
185
+ "layer": entry.get("layer"),
186
+ "importance": entry.get("importance"),
187
+ "merge_count": entry.get("merge_count"),
188
+ "protected": bool(entry.get("protected")),
189
+ "tags": list(entry.get("tags") or []),
190
+ },
191
+ # 聚合行行号(1 起):正文里字面含 AGG_MARK 的行——forgetting.aggregate_line
192
+ # 生成的形态是 `- 【聚合 月-日 时:分】…`;宽判据(含标记即计)与回滚核对同源。
193
+ "agg_lines": [i + 1 for i, l in enumerate(content.splitlines())
194
+ if _forgetting.AGG_MARK in l],
195
+ }
196
+
197
+
198
+ # 生效条件:rel 指向的文件不存在时抛 RollbackError(code="preimage_missing");存在则读取并以 cg._open_content(node_id, fm, raw) 对称解封,返回 (fm, content)——content 为 None(无密钥/身份不符)时抛 RollbackError(code="preimage_unreadable");文件含坏字节(非 UTF-8)无法解析时同样抛 RollbackError(code="preimage_unreadable")(fail-closed,不裸抛 UnicodeDecodeError);
199
+ def read_preimage(cg, node_id, rel):
200
+ """读执行时点前像文件(**与 snapshot_preimage 对称**:写走 _write_node 封装、
201
+ 读走 _open_content 解封)——返回 (fm, content)。
202
+
203
+ 注意:快照文件以节点文件同款 nodefile 序列化落盘;加密库中其内容为密封
204
+ 形态,必须经解封钩子读,直接 nodefile.loads 会把密文当明文再次封装
205
+ (双重封装)。非加密库两钩子恒等(探针实测逐字节一致)。
206
+
207
+ 文件含坏字节(非 UTF-8)无法解析时抛 RollbackError(code="preimage_unreadable")
208
+ ——fail-closed,不裸抛 UnicodeDecodeError。
209
+ """
210
+ p = os.path.join(cg.root, str(rel).replace("/", os.sep))
211
+ if not os.path.isfile(p):
212
+ raise RollbackError("preimage_missing",
213
+ "前像文件不存在:%s——变更单可能未执行(无前像)"
214
+ "或快照被移走;fail-closed 不猜一个前像。" % rel)
215
+ try:
216
+ with open(p, encoding="utf-8") as f:
217
+ fm, raw = nodefile.loads(f.read())
218
+ except UnicodeDecodeError as exc:
219
+ # 坏字节/非 UTF-8:fail-closed——绝不让 UnicodeDecodeError 裸抛逃逸
220
+ raise RollbackError("preimage_unreadable",
221
+ "前像文件坏字节 / 非 UTF-8 无法解析:%s(%s)——"
222
+ "fail-closed 不回滚。" % (rel, exc))
223
+ content = cg._open_content(node_id, fm, raw)
224
+ if content is None:
225
+ raise RollbackError("preimage_unreadable",
226
+ "前像不可解封(无密钥/身份不符):%s。" % rel)
227
+ return fm, content
228
+
229
+
230
+ # 生效条件:content 以 reference 为前缀且其后追加段逐段为「\n + 含 AGG_MARK 的非空行」时,逐段剥掉该追加段返回 (reference + 剩余段, 被剥行列表);不以 reference 为前缀、追加段形态不符、或 reference 为空时原样返回 (content, [])——不猜、不做字符串手术;
231
+ def strip_aggregate_lines(content, reference):
232
+ """定向剥离(设计 §四:合并回滚)——把**合并追加的聚合行**从正文里剥掉。
233
+
234
+ 为什么是「前缀 + 追加段」判据而不是全局扫行:合并原语(`forgetting.
235
+ reinforce` / `writelimit.converge_into`)对正文是**追加式**的
236
+ (`aggregate_line`:`new_body = body + "\\n" + line`),回滚的目标是回到
237
+ 前像正文——精确、可判、不误伤正文里历史遗留的聚合行(它们在前像里就已
238
+ 存在,属「合并前正文」的一部分,不该动)。非追加式形态(第三方改写等)
239
+ 一律不手术:返回原 content 与空剥离表,由调用方按读数决策。
240
+
241
+ 返回 `(new_content, removed)`;追加段完全剥净时 `new_content == reference`
242
+ (正常回滚场景,逐字节)。判据与 `forgetting.aggregate_line` 同款字面
243
+ (`AGG_MARK` 常量单点在 forgetting.py,不另写第二份)。
244
+ """
245
+ text = content or ""
246
+ ref = reference or ""
247
+ if not ref or not text.startswith(ref):
248
+ return text, []
249
+ tail = text[len(ref):]
250
+ removed = []
251
+ while tail.startswith("\n"):
252
+ nl = tail.find("\n", 1)
253
+ line = tail[1:] if nl < 0 else tail[1:nl]
254
+ if not line.strip() or _forgetting.AGG_MARK not in line:
255
+ break # 空行/非聚合行:停止(不越界手术)
256
+ removed.append(line)
257
+ tail = "" if nl < 0 else tail[nl:]
258
+ # 收尾:追加段的**纯换行尾**(`nodefile.dumps:313` 给不以换行结尾的正文
259
+ # 补过一个尾换行,读回时即多出——探针实测:合并后读回形态为
260
+ # `前像 + "\n" + 聚合行 + "\n"`)在已剥过行时一并剥净,使正常场景逐字节
261
+ # 回到前像;未剥过行(removed 为空)不动分毫。
262
+ if removed and not tail.strip("\n"):
263
+ tail = ""
264
+ return ref + tail, removed
265
+
266
+
267
+ # 生效条件:落盘前先过保护闸——protect.is_immutable(cg, node_id) 为真且 preimage_fm 未带同一保护位(immutable is True 或 layer ∈ PROTECTED_LAYERS)时,force 为假即返回拒绝体 dict(不写盘);随后尝试 protect.snapshot(cg, node_id) 把将被覆盖的当前版本留档(失败不阻断),再经 cg._write_node 落盘、按 _node_entry 重算索引条目写入 index["nodes"] 与 _dirty 并失效 subgraph/chain/trust 三个反查缓存,返回 None(落盘完成);本函数只被本模块的回滚分支调用;
268
+ def _land(cg, node_id, path, fm, content, preimage_fm=None, force=False,
269
+ actor=None):
270
+ """回滚的**唯一落盘口**:保护闸 + 前像快照 + 写盘 + 索引重算 + 缓存失效。
271
+
272
+ 与 `mdcos.review_decide` merge 分支的定向 upsert 同款(`_node_entry`
273
+ 与 `_scan_nodes` 同源,字段集零漂移);走 `_dirty`(**不走 `_stage`**
274
+ ——它会虚增 bucket 计数,目标已在索引)。
275
+
276
+ #352-A(2026-10-15):本口此前**三闸全无**——直接 `cg._write_node`,
277
+ 不走 `protect.guard_overwrite` / `guard_write`,不留 `protect.snapshot`
278
+ 前像副本,不写 `_audit`。后果:目标在执行之后被标 immutable 时,回滚
279
+ 照样覆写并把 immutable 标记一并清掉,且事后无从知道被覆盖的是哪一版。
280
+
281
+ 保护判据(**避免过度收紧**):只在「现盘面受保护 **而** 执行时点前像不带
282
+ 同一保护位」时拒绝——保护位是本变更**之后**加的,覆写会把它抹掉。若前像
283
+ 本身就带保护位(原节点本就 immutable / 在保护层),回滚只是把该保护位
284
+ 如实还原,属正常回滚,**不拦**(否则 D 删除回滚永远回不来受保护节点)。
285
+
286
+ 返回 None=落盘完成;返回 dict=拒绝体(`ok: False` + `error`),调用方
287
+ 据此 fail-closed 返回,绝不静默覆写。
288
+ """
289
+ try:
290
+ prot, why = protect.is_immutable(cg, node_id)
291
+ except Exception: # noqa: BLE001 —— 判定失败按不拦(读面异常不升级成拒服务)
292
+ prot, why = False, ""
293
+ if prot and not force:
294
+ _pre = preimage_fm or {}
295
+ _pre_prot = (_pre.get("immutable") is True
296
+ or str(_pre.get("layer") or "") in protect.PROTECTED_LAYERS)
297
+ if not _pre_prot:
298
+ return {"ok": False, "error": "protected_target",
299
+ "protection": why,
300
+ "detail": "回滚目标 %s 现受写保护(%s),而执行时点前像不带"
301
+ "该保护位——保护位是本变更**之后**加的,覆写会把它"
302
+ "一并清掉;fail-closed 未覆写(确认后加 --force)。"
303
+ % (node_id, why),
304
+ "hint": "如确需回滚:先解除保护(mdcg_protect 面)或对本单"
305
+ "显式 --force;二者都会留痕。"}
306
+ # 落盘前把**将被覆盖的当前版本**留档(protect 面既有单点,不另写第二套)。
307
+ try:
308
+ protect.snapshot(cg, node_id)
309
+ except Exception: # noqa: BLE001 —— 留档失败不阻断回滚本身
310
+ pass
311
+ cg._write_node(node_id, path, fm, content)
312
+ layer = str(fm.get("layer") or "knowledge")
313
+ try:
314
+ e = cg._node_entry(path, layer, fm, content)
315
+ except Exception: # noqa: BLE001 —— 重算失败不阻断回滚落盘
316
+ e = None
317
+ if e is not None:
318
+ cg.index["nodes"][node_id] = e
319
+ cg._dirty[node_id] = e
320
+ _subgraph.invalidate_cache(cg)
321
+ chain.invalidate_cache(cg)
322
+ trust.invalidate_cache(cg)
323
+
324
+
325
+ # 生效条件:node_id 的索引条目存在时返回其盘面绝对路径;不存在或条目无 path 时返回 None;
326
+ def _disk_path(cg, node_id):
327
+ e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id) or {}
328
+ p = e.get("path")
329
+ return os.path.join(cg.root, p) if p else None
330
+
331
+
332
+ # 生效条件:对任意路径返回 bytes(不存在/不可读时返回 None——比对判据按 None 处理,不抛);
333
+ def _bytes_of(path):
334
+ if not path:
335
+ return None
336
+ try:
337
+ with open(path, "rb") as f:
338
+ return f.read()
339
+ except OSError:
340
+ return None
341
+
342
+
343
+ # 生效条件:path 与 rel 都取到字节时返回两者逐字节相等的布尔;任一侧字节取不到时返回 False(不可证即不认——比对判据 fail-closed);
344
+ def _bytes_equal(path, rel_path):
345
+ a, b = _bytes_of(path), _bytes_of(rel_path)
346
+ return a is not None and b is not None and a == b
347
+
348
+
349
+ # 生效条件:C 改写回滚——索引中节点在位(不在位返回 ok False error target_missing)时把前像 (fm0,c0) 落到节点盘面 path(_land;保护闸拒绝即原样返回该拒绝体)+ flush,返回读数 dict;
350
+ def _rollback_rewrite(cg, tgt, fm0, c0, force=False, actor=None):
351
+ path = _disk_path(cg, tgt)
352
+ if path is None or _forgetting.prior_node(cg, tgt) is None:
353
+ return {"ok": False, "error": "target_missing",
354
+ "detail": "C 回滚:目标 %s 不在索引中——本变更之外还有变化,"
355
+ "fail-closed 不猜落点(如属误删可先 restore)。" % tgt}
356
+ refuse = _land(cg, tgt, path, fm0, c0, preimage_fm=fm0, force=force,
357
+ actor=actor)
358
+ if refuse is not None:
359
+ return refuse
360
+ cg.flush()
361
+ return {"ok": True, "restored_path": os.path.relpath(path, cg.root)
362
+ .replace("\\", "/"), "method": "preimage"}
363
+
364
+
365
+ # 生效条件:B 合并回滚——目标在位(不在位返回 ok False error target_missing)时先按 strip_aggregate_lines 剥离追加的聚合行,剥离结果与前像正文逐字节相等则正文取剥离结果、否则取前像正文(stripped_ok 如实记录),fm 全量取前像 (fm0),经 _land 落盘 + flush;返回读数 dict(removed_lines/stripped_ok/method);
366
+ def _rollback_merge(cg, tgt, fm0, c0, force=False, actor=None):
367
+ cur = None
368
+ try:
369
+ cur = cg.get(tgt)
370
+ except Exception: # noqa: BLE001
371
+ cur = None
372
+ if not cur:
373
+ return {"ok": False, "error": "target_missing",
374
+ "detail": "B 回滚:目标 %s 不可读——本变更之外还有变化,"
375
+ "fail-closed 不猜落点。" % tgt}
376
+ path = _disk_path(cg, tgt)
377
+ if path is None:
378
+ return {"ok": False, "error": "target_missing",
379
+ "detail": "B 回滚:目标 %s 索引条目缺 path。" % tgt}
380
+ c1 = cur.get("content") or ""
381
+ stripped, removed = strip_aggregate_lines(c1, c0)
382
+ stripped_ok = stripped == c0
383
+ # 正文取剥离结果(正常场景逐字节==前像);剥离不精确(追加段含非聚合行等)
384
+ # 时以快照正文为准——回滚的判据是「回到前像」,stripped_ok 如实记录。
385
+ # fm 全量取前像:merge_count/last_merge_at/importance(+0.05 可被 1.0 截断)/
386
+ # merge_sources/protected/lifecycle_state 等均不可逆,前像是唯一诚实来源。
387
+ refuse = _land(cg, tgt, path, fm0, stripped if stripped_ok else c0,
388
+ preimage_fm=fm0, force=force, actor=actor)
389
+ if refuse is not None:
390
+ return refuse
391
+ cg.flush()
392
+ return {"ok": True, "restored_path": os.path.relpath(path, cg.root)
393
+ .replace("\\", "/"),
394
+ "method": "strip_aggregate_lines" if stripped_ok else "preimage",
395
+ "stripped_ok": stripped_ok, "removed_lines": removed}
396
+
397
+
398
+ # 生效条件:D 删除回滚——先调既有 cg.restore(tgt, force=True)(trash + 删除清单口径);restore 失败且(错误非 not_in_trash 或节点仍不在库)时返回 ok False(detail 带 restore 原返回体);restore 成功、或 not_in_trash 而节点已在库(此前已回滚过=幂等重放)时继续:按前像做逐字节校准(盘面与快照字节不等时经 _land 以 (fm0,c0) 重写,calibrated=True 如实记录——探针实测 restore 重建会多 sensitivity:null 键),返回读数 dict(replayed 标注重放);
399
+ def _rollback_delete(cg, tgt, fm0, c0, rel, force=False, actor=None):
400
+ res = cg.restore(tgt, force=True)
401
+ replayed = (not res.get("ok")) and res.get("error") == "not_in_trash" \
402
+ and _forgetting.prior_node(cg, tgt) is not None
403
+ if not res.get("ok") and not replayed:
404
+ return {"ok": False, "error": res.get("error") or "restore_failed",
405
+ "detail": {"restore": res},
406
+ "hint": "D 回滚走既有 restore(trash + 删除清单)——失败即"
407
+ "未恢复;如 trash 缺失可核对前像目录。"}
408
+ path = _disk_path(cg, tgt)
409
+ if path is None:
410
+ return {"ok": False, "error": "target_missing",
411
+ "detail": "D 回滚:restore 返回 ok 但索引无条目。"}
412
+ pre_p = os.path.join(cg.root, str(rel).replace("/", os.sep))
413
+ restore_bytes_equal = _bytes_equal(path, pre_p)
414
+ calibrated = False
415
+ if not restore_bytes_equal:
416
+ # 校准(如实):restore 的 add 全量重建与快照存在字节差(实测 =
417
+ # 多 `sensitivity: null` 键)——回滚的判据是「回到前像」,故以快照
418
+ # 重写一次;`restore_bytes_equal=False` 读数保留,不假装 restore
419
+ # 本身逐字节。
420
+ refuse = _land(cg, tgt, path, fm0, c0, preimage_fm=fm0, force=force,
421
+ actor=actor)
422
+ if refuse is not None:
423
+ return refuse
424
+ calibrated = True
425
+ cg.flush()
426
+ return {"ok": True, "restored_path": os.path.relpath(path, cg.root)
427
+ .replace("\\", "/"),
428
+ "method": "restore+preimage_calibration" if calibrated
429
+ else "restore",
430
+ "replayed": replayed,
431
+ "calibrated": calibrated,
432
+ "restore_bytes_equal": restore_bytes_equal}
433
+
434
+
435
+ # 生效条件:before_impact 与 after 两个影响面 dict(缺面按空 dict)逐面返回对拍布尔——{"agg_lines_restored","edges_restored","index_restored"};
436
+ def _residual(before_impact, after):
437
+ bi = before_impact if isinstance(before_impact, dict) else {}
438
+ return {
439
+ "agg_lines_restored": (after.get("agg_lines") or [])
440
+ == (bi.get("agg_lines") or []),
441
+ "edges_restored": (after.get("edges") or {}) == (bi.get("edges") or {}),
442
+ "index_restored": {k: (after.get("index") or {}).get(k)
443
+ for k in _INDEX_KEYS}
444
+ == {k: (bi.get("index") or {}).get(k)
445
+ for k in _INDEX_KEYS},
446
+ }
447
+
448
+
449
+ # 生效条件:cg 为 None 或 cg.get 抛异常/返回假值时返回 None,否则返回 cg.get(node_id) 的结果(读面失败一律按「目标不可读」计,不抛);
450
+ def _node_of(cg, node_id):
451
+ if cg is None:
452
+ return None
453
+ try:
454
+ return cg.get(node_id)
455
+ except Exception: # noqa: BLE001
456
+ return None
457
+
458
+
459
+ # 生效条件:pid 为真且 cg.decisions() 可读时,返回本 pid 最后一条 decision=="accept" 记录**之后**、decision=="accept" 且 rec["mutation"]["target"] 等于 tgt 的记录 pid 列表(顺序同盘面);**取不到顺序(pid 为空 / 无该 pid / decisions 不可读)时返回 None**(=判据不可用,调用方据此不拦——不把「取不到证据」升级成拒绝);
460
+ def _later_executions(cg, tgt, pid):
461
+ """本单执行之后、同目标的 accept 执行记录(旧执行记录无 after_hash 时的兜底判据)。
462
+
463
+ decisions.jsonl 是 append-only,故「盘面顺序」即「时间顺序」——同一 pid 的
464
+ 最后一条 accept 之后出现的、target 相同的 accept 执行记录,就是「本单之后
465
+ 目标又被执行过一次」的证据面。
466
+ """
467
+ if not pid or cg is None:
468
+ return None
469
+ try:
470
+ rows = list(cg.decisions())
471
+ except Exception: # noqa: BLE001
472
+ return None
473
+ idx = None
474
+ for i, r in enumerate(rows):
475
+ if r.get("pid") == pid and r.get("decision") == "accept":
476
+ idx = i
477
+ if idx is None:
478
+ return None
479
+ out = []
480
+ for r in rows[idx + 1:]:
481
+ if r.get("decision") != "accept":
482
+ continue
483
+ mu = r.get("mutation")
484
+ if isinstance(mu, dict) and str(mu.get("target") or "") == tgt:
485
+ out.append(r.get("pid"))
486
+ return out
487
+
488
+
489
+ # 生效条件:对任意 cg/tgt/act/rel/res 都无条件返回布尔——先尝试 cg._audit("rollback", tgt, **meta)(MdCGOS 面,带 tenant/session/clearance 归因),失败或 cg 无 _audit 时退化为向 cg.root/_audit.jsonl 追加一行 {"t","op":"rollback","id","actor","action","pid","preimage","reason","method","bytes_equal_preimage"};两种情况都不抛(留痕失败不阻断已完成的回滚);
490
+ def _audit_rollback(cg, tgt, act, rel, res, actor=None, pid=None, reason=""):
491
+ """回滚留痕(`_audit.jsonl` 一行 op="rollback")——#352-A。
492
+
493
+ 改前本模块的 docstring 写「审计由各分支的落盘 / restore 留痕承担」,而
494
+ `_land` 这一支(C/B 以及 D 的校准路径)**一行审计都不写**:回滚是唯一
495
+ 不写台账的破坏性写口(步骤④准入读数第 3 条即为「R3 破坏可逆读数缺失」)。
496
+ 本函数是回滚留痕的**唯一落点**(op 常量集中在 `ROLLBACK_AUDIT_OP`)。
497
+ """
498
+ meta = {"action": act, "pid": pid, "preimage": rel,
499
+ "reason": str(reason or ""), "method": res.get("method"),
500
+ "bytes_equal_preimage": res.get("bytes_equal_preimage")}
501
+ fn = getattr(cg, "_audit", None)
502
+ if callable(fn):
503
+ try:
504
+ fn(ROLLBACK_AUDIT_OP, tgt, **meta)
505
+ return True
506
+ except Exception as e: # noqa: BLE001 —— 退化为直写
507
+ # #472 站点 2:**退化不再静默**(原为 `pass`)——写 stderr 留痕,并把本行标记为
508
+ # 「链外(已知退化)」,使 mdcos._audit_chain_verify 判为 known_degraded(**软信号**),
509
+ # **而非** unknown_foreign(后者是「有人插入」,安全要报)——**两者不得同一信号**。
510
+ try:
511
+ from .mdcos import AUDIT_KNOWN_DEGRADED as _KD
512
+ except Exception: # 循环导入等:退化为字面量
513
+ # ⚠️ **已登记的已知偏差**(issue #472,Lead 裁定「允许但必须登记」):
514
+ # 1) **这是回落副本、不是真源** —— 真源是 `mdcos.AUDIT_KNOWN_DEGRADED`;
515
+ # 2) **回落触发条件**:`from .mdcos import ...` 失败(循环导入等);
516
+ # 3) **已知漂移风险**:若有人只改 mdcos 侧的值,**回落到字面量的这条路径会静默
517
+ # 地用旧值** —— 这是「两份副本必然漂」在语言机制层的又一次落地。
518
+ # ⇒ 该偏差**已被腿钉住**:`md_cg/test_issue472_audit_chain.py` 的 C2 腿断言
519
+ # 「本回落字面量 == mdcos.AUDIT_KNOWN_DEGRADED 的真值」(AST 静态比对,
520
+ # 不需构造循环导入 ⇒ 可行)。
521
+ _KD = "AUDIT_KNOWN_DEGRADED"
522
+ sys.stderr.write("[rollback] cg._audit 不可用,退化直写(链外·已知退化):%s: %s"
523
+ % (type(e).__name__, e) + chr(10))
524
+ _degraded_mark = _KD
525
+ else:
526
+ _degraded_mark = None
527
+ rec = {"t": time.time(), "op": ROLLBACK_AUDIT_OP, "id": tgt,
528
+ "actor": actor}
529
+ if _degraded_mark:
530
+ rec["chain"] = _degraded_mark
531
+ rec.update(meta)
532
+ try:
533
+ fsutil.append_jsonl(os.path.join(cg.root, "_audit.jsonl"), rec)
534
+ return True
535
+ except Exception: # noqa: BLE001
536
+ return False
537
+
538
+
539
+ # 生效条件:mutation 为 dict 且含非空 target 与 before(否则返回 ok False error mutation_missing/rollback_gap 带 hint);before 文件不可读按 RollbackError(code) 返回 ok False;现盘面与执行后像不等且未显式 force 时返回 ok False error drifted_since_execute(现盘面已等于前像=幂等重放,放行);dry_run 为真时只返回读数不落盘;动作类属 C/B/D 时按对应分支回滚,成功再重采影响面做残留对拍、做逐字节比对并向 _audit.jsonl 写一行 op="rollback",返回 {"ok": True, "action","target","preimage","restored_path","bytes_equal_preimage","residual","method",...};动作类不属 C/B/D 时返回 ok False error rollback_action_unknown;本函数不抛(可预期错误一律返回体);
540
+ def rollback_mutation(cg, mutation, reason="", actor=None, force=False,
541
+ pid=None, dry_run=False):
542
+ """统一回滚入口(设计 §四 四条:C/B/D 分派 + 残留核对 + 逐字节比对)。
543
+
544
+ 输入=**执行时点载荷**(`autonomy_modes.mutation_executed` 形态,含
545
+ action/target/before/impact/rollback[/after_hash]);CLI 从 decisions.jsonl
546
+ 的 `rec["mutation"]` 读回。`reason`/`actor`/`pid` 进返回体与回滚留痕。
547
+
548
+ #352-A(2026-10-15)**漂移闸**(`drifted_since_execute`):回滚的语义是
549
+ 「撤销**本变更本身**、不抹第三方改动」(`autonomy_modes.mutation_payload`
550
+ :551-555 明文),而改前只处理了「提议→执行之间」的第三方改动(前像取执行
551
+ 时点),**没处理「执行→回滚之间」的改动**——回滚用执行时点前像**整体覆写**,
552
+ 执行之后写进去的正文(含另一张合并单追加的聚合行、删除后同 id 的重建、
553
+ 新增的 immutable 标记)一并消失,回执还报 `ok:True`。本闸的比较面:
554
+
555
+ · `after_hash`(执行桥在执行落盘**之后**采的「后像」指纹,
556
+ `md_cg/mdcos.py` 的 `_mutation_execute` 处补全)与现盘面指纹不等 ⇒ 拒;
557
+ · 旧执行记录(无 `after_hash`)⇒ 退化为扫 decisions.jsonl 同目标、本单
558
+ **之后**的 accept 执行记录,有则拒;顺序取不到(pid 未知)时不拦
559
+ (不把「取不到证据」升级成拒绝)。
560
+
561
+ **幂等重放豁免**:现盘面**已经等于前像**时直接放行——回滚本身已做过(或
562
+ 节点已处于前像状态),此时「覆写」是无操作,抹不掉任何东西。这条是既有
563
+ 守卫 Q/R/S 组的「回滚命令串二次演练(幂等重放,rc=0)」得以保持的判据。
564
+
565
+ `force=True` 跳过漂移闸与 `_land` 的保护闸(`rollback_cli --force`);
566
+ `dry_run=True` 只回报将被覆写的差异、不落盘。
567
+ """
568
+ if not isinstance(mutation, dict):
569
+ return {"ok": False, "error": "mutation_missing",
570
+ "hint": "回滚入口需要变更单的执行时点载荷(dict)——"
571
+ "decisions.jsonl 的 rec[\"mutation\"]。"}
572
+ act = str(mutation.get("action") or "").strip().upper()
573
+ tgt = str(mutation.get("target") or "").strip()
574
+ rel = mutation.get("before")
575
+ if not tgt:
576
+ return {"ok": False, "error": "mutation_missing",
577
+ "hint": "载荷缺 target——无法定位回滚对象。"}
578
+ if not rel:
579
+ return {"ok": False, "error": "rollback_gap",
580
+ "hint": "载荷缺 before(执行时点前像引用):该变更单**未执行**"
581
+ "(reject / fail-closed / pending)或执行记录不完整——"
582
+ "fail-closed 不猜一个前像(前像必须来自执行时点)。"}
583
+ if act not in _ROLLBACK_ACTIONS:
584
+ return {"ok": False, "error": "rollback_action_unknown",
585
+ "action": act or None,
586
+ "hint": "回滚只覆盖 C 改写 / B 合并 / D 删除(设计 §四);"
587
+ "动作类 %r 未定义回滚——fail-closed。" % (act or None)}
588
+ try:
589
+ fm0, c0 = read_preimage(cg, tgt, rel)
590
+ except RollbackError as exc:
591
+ return {"ok": False, "error": exc.code, "detail": str(exc),
592
+ "action": act, "target": tgt, "preimage": rel}
593
+ # ---- 漂移闸(#352-A):执行之后目标又被写过 ⇒ fail-closed,不整体覆写 ----
594
+ cur_fp = node_fingerprint(_node_of(cg, tgt))
595
+ pre_fp = preimage_fingerprint(fm0, c0)
596
+ drift = None
597
+ if cur_fp != pre_fp and not force: # 相等=幂等重放,放行(见 docstring)
598
+ want = mutation.get("after_hash")
599
+ if isinstance(want, dict):
600
+ if cur_fp != want:
601
+ drift = {"ok": False, "error": "drifted_since_execute",
602
+ "action": act, "target": tgt, "preimage": rel,
603
+ "current": cur_fp, "expected_after_execute": want,
604
+ "hint": "本单**执行之后**目标又被写过——回滚会用执行时点"
605
+ "前像整体覆写,把这些写入一并抹掉(设计 §四:"
606
+ "回滚只撤销本变更本身、不抹第三方改动)。"
607
+ "已 fail-closed 未覆写:先核对上面的 current / "
608
+ "expected_after_execute 差异,确需回滚加 --force。",
609
+ "reason": str(reason or ""), "actor": actor}
610
+ else:
611
+ later = _later_executions(cg, tgt, pid)
612
+ if later:
613
+ drift = {"ok": False, "error": "drifted_since_execute",
614
+ "action": act, "target": tgt, "preimage": rel,
615
+ "current": cur_fp, "later_executions": later,
616
+ "hint": "该执行记录无 after_hash(改前落盘)——按"
617
+ "decisions.jsonl 判据:本单之后同目标还有 accept "
618
+ "执行记录 %s,回滚会抹掉它们的写入;fail-closed "
619
+ "未覆写(确需回滚加 --force)。" % (later,),
620
+ "reason": str(reason or ""), "actor": actor}
621
+ if drift is not None:
622
+ if dry_run:
623
+ out = dict(drift, dry_run=True, would_apply=False)
624
+ return out
625
+ return drift
626
+ if dry_run:
627
+ return {"ok": True, "dry_run": True, "would_apply": True,
628
+ "action": act, "target": tgt, "preimage": rel,
629
+ "current": cur_fp, "preimage_state": pre_fp,
630
+ "expected_after_execute": mutation.get("after_hash"),
631
+ "reason": str(reason or ""), "actor": actor}
632
+ if act == "C":
633
+ res = _rollback_rewrite(cg, tgt, fm0, c0, force=force, actor=actor)
634
+ elif act == "B":
635
+ res = _rollback_merge(cg, tgt, fm0, c0, force=force, actor=actor)
636
+ else: # "D"
637
+ res = _rollback_delete(cg, tgt, fm0, c0, rel, force=force, actor=actor)
638
+ if not res.get("ok"):
639
+ out = dict(res)
640
+ out.update({"action": act, "target": tgt, "preimage": rel})
641
+ return out
642
+ # 残留核对(设计 §十一 红项面):重采影响面,与前像时点记录逐面对拍。
643
+ after = collect_impact(cg, tgt)
644
+ residual = _residual(mutation.get("impact"), after)
645
+ # 逐字节比对前像(设计 §十一):盘面 vs 快照文件。
646
+ pre_p = os.path.join(cg.root, str(rel).replace("/", os.sep))
647
+ disk_p = _disk_path(cg, tgt)
648
+ out = {"ok": True, "action": act, "target": tgt, "preimage": rel,
649
+ "rollback_command": mutation.get("rollback") or "",
650
+ "reason": str(reason or ""), "actor": actor, "pid": pid,
651
+ "bytes_equal_preimage": _bytes_equal(disk_p, pre_p),
652
+ "residual": residual, "impact_after": after}
653
+ out.update(res)
654
+ # 回滚留痕(#352-A):唯一不变更 _audit 的破坏性写口就此收口。
655
+ out["audited"] = _audit_rollback(cg, tgt, act, rel, out, actor=actor,
656
+ pid=pid, reason=reason)
657
+ return out