@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
@@ -1,427 +1,427 @@
1
- # -*- coding: utf-8 -*-
2
- """md_cg · 节点显式生命周期状态机(可学习优点 ②·显式状态机)
3
-
4
- 出处(pi):
5
- 运行操作 = 13 个**叶子显式状态机**(`session/types.ts:315-329`),drive 循环按
6
- `at` 分发;一轮无任何进展即抛 `SessionInvariantError`(`drive.ts:101-104`)
7
- ——非法迁移在**结构上不可能**,而不是靠调用方自觉。
8
-
9
- 灵枢现状(本模块要收口的四处散落状态):
10
- · `writelimit._demote` 用 **tag** `tidy:converged` 记「同构聚合已定型」
11
- · `forgetting.reinforce` 用 **importance** 升降记「强化 / 弱化」
12
- · `protect` 用 **fm.protected** 记「不可遗忘」
13
- · `_evolution/ledger.md` 记账本
14
- 四种载体各说各话:谁都能把已定型节点再降一次权、把归档节点悄悄覆写成新的,
15
- 而**没有任何地方校验「这一步迁移合不合法」**。
16
-
17
- 本模块是该问题的唯一真源:状态集 `STATES` + 合法迁移表 `TRANSITIONS` + 单点裁决
18
- `check()` + 单点推进 `set_state()`。口径:
19
-
20
- · 状态落 **frontmatter.lifecycle_state**(节点 md 是唯一真源);索引快照带同名字
21
- 段 →「免读文件可查」(`_index.json` 即可回答「这节点什么状态」)。
22
- **为何不叫 `state`**(对交接文档建议集的偏离,取证理由):`state` 在 md_cg 内
23
- 已被**裁决四态**(ACCEPT/REJECT/DEFER/BLINDSPOT)占用——`audit._verdict` 的返
24
- 回体、`judge_qualification()` 的返回、`mdcos.search` 结果项、检索结果条目的
25
- `entry["state"]` 全都用它。若生命周期也叫 `state`,则同一外层结构里
26
- `entry["state"]`(裁决)与 `entry["frontmatter"]["state"]`(生命周期)并存,
27
- 人类与 agent 读面必生歧义;本仓既有 `self_state` 即为同一动机的先例。
28
- 故取 `lifecycle_state`:语义自明、零歧义。
29
- · 存量节点**缺 state 即视为 active**(`state_of` 的缺省),故不回填也能工作;
30
- `backfill()` 提供一次性回填(幂等、可 dry-run)。
31
- · **受保护节点豁免降级**:`protected`/`immutable` 节点不接受降级迁移,需
32
- `override=True` 显式放行——「保护 = 不可遗忘」在状态层的落点。
33
- #377(2026-10-14):判据改为**共用** `protect.is_protected`(∪ 原显式两位)
34
- ——层保护(layer ∈ {self, anchor})与按分保护同样不受降级,`override=True`
35
- 与 immutable 位两条既有通路逐位不变。
36
- · 非法迁移**拒绝**(负路由):`check()` 返回 `(ok, code, reason)`,`set_state()`
37
- 返回 `ok=False` + 机器可读 `error` 而不抛;写路径要硬拒用 `require_transition()`。
38
- · 永不删除:`archived` 只是状态,节点文件仍在(可逆、可审计)。
39
- · 幂等:同状态迁移是 no-op(不写盘、不留痕)——重复发起不会把历史刷爆。
40
-
41
- 状态语义(建议集,逐级降级 / 逐级回升):
42
- active 正常:参与检索与写入面
43
- converged 已定型:同构聚合的成员(writelimit tidy 的落点)
44
- demoted 已降权:importance 被下调(forgetting 弱化的落点)
45
- archived 已归档:不再参与默认检索,但文件保留、可显式恢复
46
- """
47
- from __future__ import annotations
48
-
49
- import os
50
- import time
51
-
52
- from . import protect
53
- from .fsutil import append_jsonl
54
-
55
- #: 状态全集。顺序即「降级方向」:active → converged → demoted → superseded → archived。
56
- #:
57
- #: superseded(2026-10-18 新增,使用者裁定方案 A):**被新版本取代的旧版本**。
58
- #: 背景:revise 在内容寻址下必产新节点,旧版本若留 active 会污染检索面并撞 V4 同槽
59
- #: 冲突;直接 archived 又违反「禁止跳级」。故单列一档,语义是「有新版、旧版退出默认
60
- #: 检索面但保留可读可恢复」——与 archived(主动归档、不再需要)区分开。
61
- STATES = ("active", "converged", "demoted", "superseded", "archived")
62
- #: frontmatter 字段名(索引快照同名透出)。刻意避开 `state`——见模块 docstring
63
- #: 「为何不叫 state」:该名已被裁决四态占用,同名会让读面产生歧义。
64
- STATE_FIELD = "lifecycle_state"
65
- #: 迁移留痕字段(frontmatter 侧历史,滚动保留最近 HISTORY_KEEP 条)
66
- HISTORY_FIELD = "state_history"
67
- HISTORY_KEEP = 20
68
- #: 状态迁移审计(append-only,与 _forgetting.jsonl / _maintain.jsonl 同风格)
69
- AUDIT_FILE = "_lifecycle.jsonl"
70
-
71
- #: 降级序位(用于「受保护豁免降级」的判定)
72
- _RANK = {"active": 0, "converged": 1, "demoted": 2, "superseded": 3, "archived": 4}
73
-
74
- #: 合法迁移表——**逐级降级、逐级回升**,不跳级:
75
- #: active ⇄ converged 定型 / 定型撤销
76
- #: active → demoted 直接弱化(forgetting 降权)
77
- #: converged → demoted 定型后再弱化
78
- #: demoted ⇄ active 被强化回升 / 再弱化
79
- #: demoted → archived 归档
80
- #: archived → active 显式恢复
81
- #: 刻意不收录的(即拒绝的):active→archived(跳级归档)、archived→converged /
82
- #: archived→demoted(跳级回落)、converged→archived(跳级归档)。
83
- TRANSITIONS = frozenset({
84
- ("active", "converged"),
85
- ("active", "demoted"),
86
- ("converged", "active"),
87
- ("converged", "demoted"),
88
- ("demoted", "active"),
89
- ("demoted", "archived"),
90
- ("archived", "active"),
91
- # ---- superseded(2026-10-18):修订取代 ----
92
- # 任何在用状态都可被新版取代——取代不必先降权(与 active→demoted 同一先例)。
93
- ("active", "superseded"),
94
- ("converged", "superseded"),
95
- ("demoted", "superseded"),
96
- # 撤销取代(回滚到旧版本)/ 进一步归档
97
- ("superseded", "active"),
98
- ("superseded", "archived"),
99
- # 刻意不收录:superseded→converged / superseded→demoted(不应回到降权轴——
100
- # 被取代是「版本关系」,与「重要性弱化」是两个维度,混回降权轴会丢失取代语义)
101
- })
102
-
103
-
104
- # 生效条件:以 src、dst、code、reason 四个实参构造时,父类 ValueError 消息由 f-string 拼成「非法状态迁移 src→dst(code):reason」,并把四个值分别存为同名属性。
105
- class TransitionError(ValueError):
106
- """非法生命周期迁移(写路径用 `require_transition` 直接抛这个)。"""
107
-
108
- # 生效条件:接收 src、dst、code、reason 四个实参,调用 super().__init__ 传入 f"非法状态迁移 {src}→{dst}({code}):{reason}",并将四者依次赋给 self.src、self.dst、self.code、self.reason。
109
- def __init__(self, src, dst, code, reason):
110
- super().__init__(f"非法状态迁移 {src}→{dst}({code}):{reason}")
111
- self.src, self.dst, self.code, self.reason = src, dst, code, reason
112
-
113
-
114
- # ---------------------------------------------------------------- 纯函数裁决
115
-
116
- # 生效条件:fm 非 dict 直接返回 "active";fm 为 dict 时取 fm.get(STATE_FIELD),该值属于 STATES 则原样返回,缺键或值不在 STATES 均返回 "active"。
117
- def state_of(fm) -> str:
118
- """frontmatter → 状态;缺字段或未知值 → "active"(存量兼容,不猜测)。"""
119
- if not isinstance(fm, dict):
120
- return "active"
121
- s = fm.get(STATE_FIELD)
122
- return s if s in STATES else "active"
123
-
124
-
125
- # 生效条件:入参 e 为索引条目(或同形 frontmatter 副本)时返回 state_of(e) == "archived" 的布尔结果;缺 STATE_FIELD 或取值不在 STATES 时 state_of 回落 "active" ⇒ 返回 False。
126
- def is_archived(e) -> bool:
127
- """默认检索剔除面=本函数(判据单点)。
128
-
129
- `archived` 的语义(模块 docstring :42)是「不再参与**默认检索**」——本函数是该
130
- 宣称的**唯一判据**,全部消费点共同引用(判据单点,多个消费点):
131
-
132
- · cg 检索面:`MdCGOS._candidates`(mdcos.py)——`MdCGSecure._candidates` 经
133
- `super()` 覆盖叠加读可见性,故全部**检索类** cg 读 op(search / search_rrf /
134
- recall / route…)都经它;
135
- · stg 扫描面:`stg._scan_one`(stg.py,`_scan` 的逐条实现单点)——timeline /
136
- anchors / consistency 三 op 的候选面同点覆盖(`relation` 面是显式 id 直读,
137
- `state_chain` 走 append-only 台账,两者不经扫描面);
138
- · 会话续接注入面:`MdCGOS.session_recall`(mdcos.py)的四个取数段——会话要点
139
- `_session_notes`、活跃目标 `goals`、任务台账 `tasks`、未解问题 `unresolved`
140
- (`goals`/`tasks` 经 `_retired_by_id` 按 id 回查索引后交本判据)。该 op 是
141
- 「装配续接包注入上下文/回给调用方」的注入面,与检索面同属「退役即不再默认
142
- 回出」;它自持取数面(不经 `_candidates`),故单点接线(独立复核 2026-10-06
143
- 两轮实测:接线前 archived 要点摘要、未解问题正文、**活跃目标与任务卡**均经
144
- 该 op 照旧回出;`recent` 段是事件窗口、`self_state` 是只读快照卡,不含节点
145
- 条目,不涉退役)。
146
-
147
- **fail-open**(缺键/非法值 → active):存量节点不回填也照常参与检索
148
- (存量零迁移、不误剔);「不误剔」的另一半是**只剔 archived**——
149
- converged / demoted 是**降权轴**,仍参与默认检索。
150
-
151
- 不适用条件(**不**消费本函数,故 archived 期间照常可达):显式 id 直读
152
- (`cg.get`)、审计面(`op=audit`)、工程台账的**显式管理查询面**
153
- (`cg(op=goal, action=list)` / `cg(op=task, action=list)`;注意与消费面之别——
154
- 会话续接注入包内的对应段已按上表剔除,两者不冲突)、负记忆层
155
- (rejected / unresolved 的覆盖标记面)、统计面(health / whoami / conformance)
156
- ——「退役不删除、可显式恢复」的承诺要求它们在 archived 期间照常可达。
157
- 边界(已知未覆盖面,另立裁定):基类 `MdCG.search`、`chain.adjacency` 拓扑面、
158
- `subgraph.children_index/parents_index` 结构面、rust 检索内核。
159
- """
160
- return state_of(e) == "archived"
161
-
162
-
163
- # 生效条件:入参 e 为索引条目(或同形 frontmatter 副本)时,state_of(e) 为 archived 或 superseded 即返回 True;缺键/非法值回落 active ⇒ False。
164
- def is_retired(e) -> bool:
165
- """**已退出默认检索面**的判据单点(archived ∪ superseded)。
166
-
167
- 为什么单列而不改 is_archived(2026-10-18,方案 A 配套):
168
- · is_archived 的名字与语义是「归档」,被多个消费点按字面引用;把 superseded
169
- 塞进去会让「归档」与「被取代」两个不同理由共用一个名字,正是本仓反复吃过的
170
- 「同一语义两份实现 / 一名多义」形态。
171
- · 故保留 is_archived 原义(仅 archived),新增本函数表达「退役面」的并集;
172
- 检索面/续接注入面改用本函数,显式管理查询面仍按 archived 单独判。
173
-
174
- 边界:superseded 与 archived 一样——**退役不删除**,cg.get 照常可读、
175
- 可显式恢复到 active(见 TRANSITIONS)。
176
- """
177
- return state_of(e) in ("archived", "superseded")
178
-
179
-
180
- # 生效条件:按 _RANK.get(dst, 0) > _RANK.get(src, 0) 判定,src 或 dst 不在 _RANK 键中时该侧按 0 参与比较。
181
- def is_downgrade(src: str, dst: str) -> bool:
182
- """是否向「更低」的状态迁移(active < converged < demoted < archived)。"""
183
- return _RANK.get(dst, 0) > _RANK.get(src, 0)
184
-
185
-
186
- # 生效条件:src 不在 STATES 时先替换为 "active";dst 不在 STATES 返回 False;替换后 src == dst 返回 True;否则返回 (src, dst) in TRANSITIONS 的布尔值。
187
- def can_transition(src, dst) -> bool:
188
- """迁移是否合法(含幂等;未知 src 按 active 处理)。"""
189
- src = src if src in STATES else "active"
190
- if dst not in STATES:
191
- return False
192
- if src == dst:
193
- return True # 幂等:同状态是 no-op
194
- return (src, dst) in TRANSITIONS
195
-
196
-
197
- # 生效条件:src 不在 STATES 时替换为 "active";dst 不在 STATES 返回 (False, 'unknown_state', ...);src == dst 返回 (True, 'noop', ...);(src, dst) 不在 TRANSITIONS 返回 (False, 'illegal_transition', ...);is_downgrade(src, dst) 且 protected 为真且 override 为假时返回 (False, 'protected', ...);其余返回 (True, 'ok', f'{src}→{dst} 合法')。
198
- def check(src, dst, protected: bool = False, override: bool = False):
199
- """迁移合法性裁决 → `(ok, code, reason)`。**唯一裁决点**(纯函数,无 IO)。
200
-
201
- code 取值:`ok` / `noop`(同状态,不写盘)/ `unknown_state` /
202
- `illegal_transition` / `protected`。
203
- """
204
- src = src if src in STATES else "active"
205
- if dst not in STATES:
206
- return False, "unknown_state", f"未知状态 {dst!r}(允许:{STATES})"
207
- if src == dst:
208
- return True, "noop", "状态未变(幂等,不写盘)"
209
- if (src, dst) not in TRANSITIONS:
210
- legal = "、".join(f"{a}→{b}" for a, b in sorted(TRANSITIONS))
211
- return False, "illegal_transition", (
212
- f"{src}→{dst} 不在合法迁移表内(允许:{legal})——"
213
- "降级与回升都须逐级,跨级迁移一律拒绝")
214
- if is_downgrade(src, dst) and protected and not override:
215
- return False, "protected", (
216
- f"受保护节点不接受降级迁移 {src}→{dst}(保护 = 不可遗忘);"
217
- "确需降级请显式 override=True")
218
- return True, "ok", f"{src}→{dst} 合法"
219
-
220
-
221
- # 生效条件:以 src、dst、protected、override 调 check 后,ok 为真时返回其 code,ok 为假时抛 TransitionError,抛出时 src 参数在 STATES 中则原样、否则替换为 "active",dst、code、why 按源码透传。
222
- def require_transition(src, dst, protected: bool = False, override: bool = False):
223
- """合法则返回 code,非法则抛 `TransitionError`(写路径的硬拒入口)。"""
224
- ok, code, why = check(src, dst, protected=protected, override=override)
225
- if not ok:
226
- raise TransitionError(src if src in STATES else "active", dst, code, why)
227
- return code
228
-
229
-
230
- # 生效条件:src 取 state_of(fm),prot 取 bool(fm.get("protected") or fm.get("immutable"));check 返回 ok 假或 code == "noop" 时原样返回 (ok, code, why) 且不改 fm;否则把 dst 写入 fm[STATE_FIELD],并把含 at/from/to/reason/actor 的新条目追加到由 fm.get(HISTORY_FIELD) or [] 复制的列表、截取末 HISTORY_KEEP 条写回 fm[HISTORY_FIELD],返回 (True, code, why)。
231
- #: 裸 frontmatter 探针的假 node_id(`protect.is_protected` 的 `(cg, node_id)` 形态所需;
232
- #: 真实节点 id 来自文件名/显式声明,不含 NUL ⇒ 与既有索引键不可能相撞)。
233
- _FM_PROBE_ID = "\x00fm-probe"
234
-
235
-
236
- class _FmProbe:
237
- """裸 frontmatter → `protect.is_protected` 所需的 `(cg, node_id)` 形态(**零规则载体**)。
238
-
239
- #377(2026-10-14):本模块的降级判据此前只读 `fm["protected"]` / `fm["immutable"]`
240
- 两位,漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**
241
- ——anchor/self 层节点可被无痕降级。本类**不复制任何判据**——规则单点仍是
242
- `protect.is_protected`——只把调用方手里已有的 frontmatter 摆成该判据所需的
243
- 索引快照形态(唯一索引条目=该映射本身)。刻意**不提供** `_maybe_reload_index`
244
- (`protect._fm` 的探活分支取不到即跳过)且 `get()` 恒返回 None(门控字段回退
245
- 读文件的分支在此无文件可读、**不抛异常**)⇒ 判定 100% 基于传入映射:
246
- 零 IO、零副作用(`stamp` 是就地改 fm 的纯函数面)。
247
- """
248
-
249
- __slots__ = ("index",)
250
-
251
- def __init__(self, fm):
252
- self.index = {"nodes": {_FM_PROBE_ID: fm if isinstance(fm, dict) else {}}}
253
-
254
- def get(self, node_id=None): # protect._fm 的回退分支:探针无文件可读
255
- return None
256
-
257
-
258
- def _is_protected_fm(fm) -> tuple:
259
- """裸 frontmatter 的「不可遗忘」判定 → `(是否受保护, 原因)`。
260
-
261
- 判据单点=**`protect.is_protected`**(层保护 self/anchor ∪ 显式 protected 位 ∪
262
- 按分保护 ≥0.70 且来源缺省/hint);本函数只负责把它喂给判据,不自带任何规则。
263
- """
264
- return protect.is_protected_entry(fm) # #431 批:_FmProbe 副本收口到条目口径单点
265
-
266
-
267
- def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
268
- override: bool = False):
269
- """在给定 frontmatter 上**就地**推进状态(无 IO)→ `(ok, code, why)`。
270
-
271
- 与 `set_state()` 共用同一裁决点(`check`),供**需与其他字段同批落盘**的收
272
- 口点使用——`writelimit` 的降权要一次写盘改 tags/importance/状态,`forgetting`
273
- 的强化同理;否则状态得单独再写一次盘(同一节点两倍 IO)。
274
- 合法且非幂等时写入 `STATE_FIELD` 并追加 `HISTORY_FIELD`;失败/幂等不动 fm。
275
- """
276
- src = state_of(fm)
277
- # #377(2026-10-14):原判据只读 fm 的**显式两位**(protected / immutable),
278
- # 漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**
279
- # ——anchor/self 层节点可被无痕降级。改为「显式两位 ∪ is_protected」:
280
- # **超集**,原判据一字不减(immutable 位照旧、override=True 照旧短路到 check 的
281
- # override 分支)⇒ 既有判定与 override 通路逐位不变;判据本体仍是 protect 的单点,
282
- # 不在本模块复制一份。
283
- prot = bool(fm.get("protected") or fm.get("immutable")) \
284
- or _is_protected_fm(fm)[0]
285
- ok, code, why = check(src, dst, protected=prot, override=override)
286
- if not ok or code == "noop":
287
- return ok, code, why
288
- fm[STATE_FIELD] = dst
289
- hist = list(fm.get(HISTORY_FIELD) or [])
290
- hist.append({"at": time.time(), "from": src, "to": dst,
291
- "reason": reason, "actor": actor})
292
- fm[HISTORY_FIELD] = hist[-HISTORY_KEEP:]
293
- return True, code, why
294
-
295
-
296
- # ---------------------------------------------------------------- 索引同步
297
-
298
- # 生效条件:cg.index 非 dict 时静默 return;index 的 "nodes" 中查不到 node_id 时 return;否则把 fm.get(STATE_FIELD)(缺键即 None)写入该条目,cg._dirty 为 dict 时记入该条目并调用可调用的 cg.flush。
299
- def _sync_index(cg, node_id, fm) -> None:
300
- """把 state 同步进索引快照(免读文件可查);无索引实现时静默跳过。
301
-
302
- 只同步 `state` 一个键:迁移历史已在 frontmatter 与 `_lifecycle.jsonl` 留痕,
303
- 放进索引会让快照无谓膨胀。
304
- """
305
- idx = getattr(cg, "index", None)
306
- if not isinstance(idx, dict):
307
- return
308
- e = (idx.get("nodes") or {}).get(node_id)
309
- if e is None:
310
- return
311
- e[STATE_FIELD] = fm.get(STATE_FIELD)
312
- dirty = getattr(cg, "_dirty", None)
313
- if isinstance(dirty, dict):
314
- dirty[node_id] = e
315
- flush = getattr(cg, "flush", None)
316
- if callable(flush):
317
- flush()
318
-
319
-
320
- # ---------------------------------------------------------------- 推进 / 回填
321
-
322
- # 生效条件:cg.get(node_id) 为假值返回 {'ok': False, 'error': 'node_not_found', ...};否则以 state_of(fm) 作 src 调 stamp——stamp 不 ok 返回 ok=False + error=code,code == "noop" 返回 ok=True + changed=False;其余情况(合法且真迁移,即**资格面已过**)先经 autonomy_modes.e_gate() 档位判定(补强批次 v1.2·E 面接线,位置=写盘之前):非 ALLOW(plan 档无计划)即经 forbidden_result() fail-closed 早退(ok=False、error=autonomy_forbidden、零写盘、零审计行),ALLOW(confirm/full)才取 fm[HISTORY_FIELD][-1]["at"] 后写盘、_sync_index 并追加审计 JSONL(append_jsonl 抛异常被吞掉),返回 ok=True + changed=True。
323
- def set_state(cg, node_id: str, dst: str, reason: str = None,
324
- actor: str = None, override: bool = False) -> dict:
325
- """推进一个节点的生命周期状态(**唯一推进入口**)。
326
-
327
- 非法迁移不走异常而是返回 `{"ok": False, "error": <code>, ...}`(负路由:
328
- 调用方自行决定降级处理;要硬拒请用 `require_transition`)。幂等迁移返回
329
- `changed=False` 且不写盘。返回体始终带 `from` / `to` / `code` 便于审计。
330
-
331
- **档位闸(补强批次 v1.2·E 面接线)**:合法且真迁移(`stamp` 已过=资格面
332
- 已过)之后、写盘之前,先经 `autonomy_modes.e_gate()`(设计 §三 plan 档
333
- E「须命中计划步骤」)——plan 档无计划 ⇒ fail-closed 早退(
334
- `ok=False`/`error="autonomy_forbidden"`/带 hint、零写盘、零审计行);
335
- confirm/full ⇒ ALLOW、**原链原样**(逐位不变)。非法迁移与 noop 由
336
- `stamp` 先行裁决、各回各的 code(档位**不参与**资格判定)。
337
- """
338
- node = cg.get(node_id)
339
- if not node:
340
- return {"ok": False, "error": "node_not_found", "node_id": node_id}
341
- fm = dict(node.get("frontmatter") or {})
342
- src = state_of(fm)
343
- ok, code, why = stamp(fm, dst, reason=reason, actor=actor, override=override)
344
- base = {"node_id": node_id, "from": src, "to": dst, "code": code}
345
- if not ok:
346
- return {**base, "ok": False, "error": code, "reason": why}
347
- if code == "noop":
348
- return {**base, "ok": True, "changed": False, "reason": why}
349
- # 三档自治(补强批次 v1.2·E 面接线,设计 §三 plan 档 E「须命中计划步骤」):
350
- # 位置=资格面(`stamp` 的合法性/保护裁决)之后、写盘之前——非法迁移与 noop
351
- # 已在上方各回各的 code,档位不参与资格判定;confirm/full ⇒ ALLOW 原链原样。
352
- from . import autonomy_modes as _am
353
- _dec = _am.e_gate()
354
- if _dec["decision"] != _am.ALLOW:
355
- out = _am.forbidden_result(_dec, node_id=node_id, changed=False)
356
- out.update({"from": src, "to": dst, "code": "autonomy_forbidden"})
357
- return out
358
- at = fm[HISTORY_FIELD][-1]["at"]
359
- cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
360
- node.get("content") or "")
361
- _sync_index(cg, node_id, fm)
362
- # 退役接线(2026-10-06):状态迁移改变 `is_archived` 读数 ⇒ 依赖该判据的
363
- # 邻接缓存(`chain.adjacency` 的 skip_archived 过滤)必须**同点作废**——
364
- # 此前只有本地写路径(add/_stage 尾三连)清缓存,set_state 后旧缓存会让
365
- # 退役节点继续沿因果链/图面扩散(本批探针实证:归档后 causal_chain 仍含
366
- # 目标)。懒导入避免模块环;`invalidate_cache` 内部自吞异常,不阻断推进。
367
- from . import chain as _chain
368
- _chain.invalidate_cache(cg)
369
- try:
370
- # issue #547:`_lifecycle.jsonl` 是审计台账(状态迁移留痕),按 #549 的口径
371
- # 走 durable=True(原为缺省 + `except: pass`,丢行静默)。
372
- append_jsonl(os.path.join(cg.root, AUDIT_FILE), {
373
- "t": at, "action": "set_state", "node_id": node_id,
374
- "from": src, "to": dst, "reason": reason, "actor": actor,
375
- "override": bool(override)}, durable=True)
376
- except Exception: # 审计失败不阻断状态推进
377
- pass
378
- return {**base, "ok": True, "changed": True, "reason": why, "at": at}
379
-
380
-
381
- # 生效条件:nodes 取 (cg.index or {}).get("nodes") or {},遍历中缺 STATE_FIELD 或该值不在 STATES 的 nid 计入 missing(累计数达 limit 即 break,limit <= 0 时立即 break 使 missing 为空),apply 假值只返回 dry_run=True 的盘点结果(**不接档位闸**——零写盘面照旧),apply 为真时先经 autonomy_modes.e_gate() 档位判定(补强批次 v1.2·E 面接线,位置=盘点资格面之后、写盘之前):非 ALLOW(plan 档无计划)即经 forbidden_result() fail-closed 早退(零写盘、backfilled=0),ALLOW(confirm/full)才对每个 missing 中 cg.get 取不到的记入 failed、取到的把 state_of(fm) 显式写回 fm[STATE_FIELD] 并写盘与 _sync_index 后记入 done,返回 dry_run=False 的结果。
382
- def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
383
- """存量回填:把缺 `state` 的节点显式补成 `active`(幂等)。
384
-
385
- 缺字段本就按 active 解释(`state_of`),故回填**不是让功能工作的前提**,
386
- 而是把「缺省」变成「显式」——索引/审计里从此可直接读到状态。
387
- `apply=False`(默认)只盘点。写不动(文件取不回)的节点进 `failed` 如实上报。
388
-
389
- **档位闸(补强批次 v1.2·E 面接线)**:`apply=True` 的**写盘前**先经
390
- `autonomy_modes.e_gate()`(设计 §三 plan 档 E「须命中计划步骤」)——plan 档
391
- 无计划 ⇒ fail-closed 早退(零写盘、`backfilled=0`);confirm/full ⇒ ALLOW、
392
- 原链原样。`apply=False`(盘点)不接闸。
393
- """
394
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
395
- missing = []
396
- for nid, e in list(nodes.items()):
397
- if len(missing) >= limit:
398
- break
399
- if (e or {}).get(STATE_FIELD) in STATES:
400
- continue
401
- missing.append(nid)
402
- missing.sort()
403
- if not apply:
404
- return {"ok": True, "dry_run": True, "scanned": len(nodes),
405
- "missing": len(missing), "planned": missing[:50]}
406
- # 三档自治(补强批次 v1.2·E 面接线):E 类动作**写盘前**的档位判定单点
407
- # (同 `set_state` 口径)——盘点(资格面)已完成、任何盘面写入之前。
408
- from . import autonomy_modes as _am
409
- _dec = _am.e_gate()
410
- if _dec["decision"] != _am.ALLOW:
411
- return _am.forbidden_result(_dec, dry_run=False, scanned=len(nodes),
412
- missing=len(missing), backfilled=0)
413
- done, failed = [], []
414
- for nid in missing:
415
- node = cg.get(nid)
416
- if not node:
417
- failed.append(nid)
418
- continue
419
- fm = dict(node.get("frontmatter") or {})
420
- fm[STATE_FIELD] = state_of(fm) # 缺省 active → 显式落盘
421
- cg._write_node(nid, os.path.join(cg.root, node["path"]), fm,
422
- node.get("content") or "")
423
- _sync_index(cg, nid, fm)
424
- done.append(nid)
425
- return {"ok": True, "dry_run": False, "scanned": len(nodes),
426
- "missing": len(missing), "backfilled": len(done),
1
+ # -*- coding: utf-8 -*-
2
+ """md_cg · 节点显式生命周期状态机(可学习优点 ②·显式状态机)
3
+
4
+ 出处(pi):
5
+ 运行操作 = 13 个**叶子显式状态机**(`session/types.ts:315-329`),drive 循环按
6
+ `at` 分发;一轮无任何进展即抛 `SessionInvariantError`(`drive.ts:101-104`)
7
+ ——非法迁移在**结构上不可能**,而不是靠调用方自觉。
8
+
9
+ 灵枢现状(本模块要收口的四处散落状态):
10
+ · `writelimit._demote` 用 **tag** `tidy:converged` 记「同构聚合已定型」
11
+ · `forgetting.reinforce` 用 **importance** 升降记「强化 / 弱化」
12
+ · `protect` 用 **fm.protected** 记「不可遗忘」
13
+ · `_evolution/ledger.md` 记账本
14
+ 四种载体各说各话:谁都能把已定型节点再降一次权、把归档节点悄悄覆写成新的,
15
+ 而**没有任何地方校验「这一步迁移合不合法」**。
16
+
17
+ 本模块是该问题的唯一真源:状态集 `STATES` + 合法迁移表 `TRANSITIONS` + 单点裁决
18
+ `check()` + 单点推进 `set_state()`。口径:
19
+
20
+ · 状态落 **frontmatter.lifecycle_state**(节点 md 是唯一真源);索引快照带同名字
21
+ 段 →「免读文件可查」(`_index.json` 即可回答「这节点什么状态」)。
22
+ **为何不叫 `state`**(对交接文档建议集的偏离,取证理由):`state` 在 md_cg 内
23
+ 已被**裁决四态**(ACCEPT/REJECT/DEFER/BLINDSPOT)占用——`audit._verdict` 的返
24
+ 回体、`judge_qualification()` 的返回、`mdcos.search` 结果项、检索结果条目的
25
+ `entry["state"]` 全都用它。若生命周期也叫 `state`,则同一外层结构里
26
+ `entry["state"]`(裁决)与 `entry["frontmatter"]["state"]`(生命周期)并存,
27
+ 人类与 agent 读面必生歧义;本仓既有 `self_state` 即为同一动机的先例。
28
+ 故取 `lifecycle_state`:语义自明、零歧义。
29
+ · 存量节点**缺 state 即视为 active**(`state_of` 的缺省),故不回填也能工作;
30
+ `backfill()` 提供一次性回填(幂等、可 dry-run)。
31
+ · **受保护节点豁免降级**:`protected`/`immutable` 节点不接受降级迁移,需
32
+ `override=True` 显式放行——「保护 = 不可遗忘」在状态层的落点。
33
+ #377(2026-10-14):判据改为**共用** `protect.is_protected`(∪ 原显式两位)
34
+ ——层保护(layer ∈ {self, anchor})与按分保护同样不受降级,`override=True`
35
+ 与 immutable 位两条既有通路逐位不变。
36
+ · 非法迁移**拒绝**(负路由):`check()` 返回 `(ok, code, reason)`,`set_state()`
37
+ 返回 `ok=False` + 机器可读 `error` 而不抛;写路径要硬拒用 `require_transition()`。
38
+ · 永不删除:`archived` 只是状态,节点文件仍在(可逆、可审计)。
39
+ · 幂等:同状态迁移是 no-op(不写盘、不留痕)——重复发起不会把历史刷爆。
40
+
41
+ 状态语义(建议集,逐级降级 / 逐级回升):
42
+ active 正常:参与检索与写入面
43
+ converged 已定型:同构聚合的成员(writelimit tidy 的落点)
44
+ demoted 已降权:importance 被下调(forgetting 弱化的落点)
45
+ archived 已归档:不再参与默认检索,但文件保留、可显式恢复
46
+ """
47
+ from __future__ import annotations
48
+
49
+ import os
50
+ import time
51
+
52
+ from . import protect
53
+ from .fsutil import append_jsonl
54
+
55
+ #: 状态全集。顺序即「降级方向」:active → converged → demoted → superseded → archived。
56
+ #:
57
+ #: superseded(2026-10-18 新增,使用者裁定方案 A):**被新版本取代的旧版本**。
58
+ #: 背景:revise 在内容寻址下必产新节点,旧版本若留 active 会污染检索面并撞 V4 同槽
59
+ #: 冲突;直接 archived 又违反「禁止跳级」。故单列一档,语义是「有新版、旧版退出默认
60
+ #: 检索面但保留可读可恢复」——与 archived(主动归档、不再需要)区分开。
61
+ STATES = ("active", "converged", "demoted", "superseded", "archived")
62
+ #: frontmatter 字段名(索引快照同名透出)。刻意避开 `state`——见模块 docstring
63
+ #: 「为何不叫 state」:该名已被裁决四态占用,同名会让读面产生歧义。
64
+ STATE_FIELD = "lifecycle_state"
65
+ #: 迁移留痕字段(frontmatter 侧历史,滚动保留最近 HISTORY_KEEP 条)
66
+ HISTORY_FIELD = "state_history"
67
+ HISTORY_KEEP = 20
68
+ #: 状态迁移审计(append-only,与 _forgetting.jsonl / _maintain.jsonl 同风格)
69
+ AUDIT_FILE = "_lifecycle.jsonl"
70
+
71
+ #: 降级序位(用于「受保护豁免降级」的判定)
72
+ _RANK = {"active": 0, "converged": 1, "demoted": 2, "superseded": 3, "archived": 4}
73
+
74
+ #: 合法迁移表——**逐级降级、逐级回升**,不跳级:
75
+ #: active ⇄ converged 定型 / 定型撤销
76
+ #: active → demoted 直接弱化(forgetting 降权)
77
+ #: converged → demoted 定型后再弱化
78
+ #: demoted ⇄ active 被强化回升 / 再弱化
79
+ #: demoted → archived 归档
80
+ #: archived → active 显式恢复
81
+ #: 刻意不收录的(即拒绝的):active→archived(跳级归档)、archived→converged /
82
+ #: archived→demoted(跳级回落)、converged→archived(跳级归档)。
83
+ TRANSITIONS = frozenset({
84
+ ("active", "converged"),
85
+ ("active", "demoted"),
86
+ ("converged", "active"),
87
+ ("converged", "demoted"),
88
+ ("demoted", "active"),
89
+ ("demoted", "archived"),
90
+ ("archived", "active"),
91
+ # ---- superseded(2026-10-18):修订取代 ----
92
+ # 任何在用状态都可被新版取代——取代不必先降权(与 active→demoted 同一先例)。
93
+ ("active", "superseded"),
94
+ ("converged", "superseded"),
95
+ ("demoted", "superseded"),
96
+ # 撤销取代(回滚到旧版本)/ 进一步归档
97
+ ("superseded", "active"),
98
+ ("superseded", "archived"),
99
+ # 刻意不收录:superseded→converged / superseded→demoted(不应回到降权轴——
100
+ # 被取代是「版本关系」,与「重要性弱化」是两个维度,混回降权轴会丢失取代语义)
101
+ })
102
+
103
+
104
+ # 生效条件:以 src、dst、code、reason 四个实参构造时,父类 ValueError 消息由 f-string 拼成「非法状态迁移 src→dst(code):reason」,并把四个值分别存为同名属性。
105
+ class TransitionError(ValueError):
106
+ """非法生命周期迁移(写路径用 `require_transition` 直接抛这个)。"""
107
+
108
+ # 生效条件:接收 src、dst、code、reason 四个实参,调用 super().__init__ 传入 f"非法状态迁移 {src}→{dst}({code}):{reason}",并将四者依次赋给 self.src、self.dst、self.code、self.reason。
109
+ def __init__(self, src, dst, code, reason):
110
+ super().__init__(f"非法状态迁移 {src}→{dst}({code}):{reason}")
111
+ self.src, self.dst, self.code, self.reason = src, dst, code, reason
112
+
113
+
114
+ # ---------------------------------------------------------------- 纯函数裁决
115
+
116
+ # 生效条件:fm 非 dict 直接返回 "active";fm 为 dict 时取 fm.get(STATE_FIELD),该值属于 STATES 则原样返回,缺键或值不在 STATES 均返回 "active"。
117
+ def state_of(fm) -> str:
118
+ """frontmatter → 状态;缺字段或未知值 → "active"(存量兼容,不猜测)。"""
119
+ if not isinstance(fm, dict):
120
+ return "active"
121
+ s = fm.get(STATE_FIELD)
122
+ return s if s in STATES else "active"
123
+
124
+
125
+ # 生效条件:入参 e 为索引条目(或同形 frontmatter 副本)时返回 state_of(e) == "archived" 的布尔结果;缺 STATE_FIELD 或取值不在 STATES 时 state_of 回落 "active" ⇒ 返回 False。
126
+ def is_archived(e) -> bool:
127
+ """默认检索剔除面=本函数(判据单点)。
128
+
129
+ `archived` 的语义(模块 docstring :42)是「不再参与**默认检索**」——本函数是该
130
+ 宣称的**唯一判据**,全部消费点共同引用(判据单点,多个消费点):
131
+
132
+ · cg 检索面:`MdCGOS._candidates`(mdcos.py)——`MdCGSecure._candidates` 经
133
+ `super()` 覆盖叠加读可见性,故全部**检索类** cg 读 op(search / search_rrf /
134
+ recall / route…)都经它;
135
+ · stg 扫描面:`stg._scan_one`(stg.py,`_scan` 的逐条实现单点)——timeline /
136
+ anchors / consistency 三 op 的候选面同点覆盖(`relation` 面是显式 id 直读,
137
+ `state_chain` 走 append-only 台账,两者不经扫描面);
138
+ · 会话续接注入面:`MdCGOS.session_recall`(mdcos.py)的四个取数段——会话要点
139
+ `_session_notes`、活跃目标 `goals`、任务台账 `tasks`、未解问题 `unresolved`
140
+ (`goals`/`tasks` 经 `_retired_by_id` 按 id 回查索引后交本判据)。该 op 是
141
+ 「装配续接包注入上下文/回给调用方」的注入面,与检索面同属「退役即不再默认
142
+ 回出」;它自持取数面(不经 `_candidates`),故单点接线(独立复核 2026-10-06
143
+ 两轮实测:接线前 archived 要点摘要、未解问题正文、**活跃目标与任务卡**均经
144
+ 该 op 照旧回出;`recent` 段是事件窗口、`self_state` 是只读快照卡,不含节点
145
+ 条目,不涉退役)。
146
+
147
+ **fail-open**(缺键/非法值 → active):存量节点不回填也照常参与检索
148
+ (存量零迁移、不误剔);「不误剔」的另一半是**只剔 archived**——
149
+ converged / demoted 是**降权轴**,仍参与默认检索。
150
+
151
+ 不适用条件(**不**消费本函数,故 archived 期间照常可达):显式 id 直读
152
+ (`cg.get`)、审计面(`op=audit`)、工程台账的**显式管理查询面**
153
+ (`cg(op=goal, action=list)` / `cg(op=task, action=list)`;注意与消费面之别——
154
+ 会话续接注入包内的对应段已按上表剔除,两者不冲突)、负记忆层
155
+ (rejected / unresolved 的覆盖标记面)、统计面(health / whoami / conformance)
156
+ ——「退役不删除、可显式恢复」的承诺要求它们在 archived 期间照常可达。
157
+ 边界(已知未覆盖面,另立裁定):基类 `MdCG.search`、`chain.adjacency` 拓扑面、
158
+ `subgraph.children_index/parents_index` 结构面、rust 检索内核。
159
+ """
160
+ return state_of(e) == "archived"
161
+
162
+
163
+ # 生效条件:入参 e 为索引条目(或同形 frontmatter 副本)时,state_of(e) 为 archived 或 superseded 即返回 True;缺键/非法值回落 active ⇒ False。
164
+ def is_retired(e) -> bool:
165
+ """**已退出默认检索面**的判据单点(archived ∪ superseded)。
166
+
167
+ 为什么单列而不改 is_archived(2026-10-18,方案 A 配套):
168
+ · is_archived 的名字与语义是「归档」,被多个消费点按字面引用;把 superseded
169
+ 塞进去会让「归档」与「被取代」两个不同理由共用一个名字,正是本仓反复吃过的
170
+ 「同一语义两份实现 / 一名多义」形态。
171
+ · 故保留 is_archived 原义(仅 archived),新增本函数表达「退役面」的并集;
172
+ 检索面/续接注入面改用本函数,显式管理查询面仍按 archived 单独判。
173
+
174
+ 边界:superseded 与 archived 一样——**退役不删除**,cg.get 照常可读、
175
+ 可显式恢复到 active(见 TRANSITIONS)。
176
+ """
177
+ return state_of(e) in ("archived", "superseded")
178
+
179
+
180
+ # 生效条件:按 _RANK.get(dst, 0) > _RANK.get(src, 0) 判定,src 或 dst 不在 _RANK 键中时该侧按 0 参与比较。
181
+ def is_downgrade(src: str, dst: str) -> bool:
182
+ """是否向「更低」的状态迁移(active < converged < demoted < archived)。"""
183
+ return _RANK.get(dst, 0) > _RANK.get(src, 0)
184
+
185
+
186
+ # 生效条件:src 不在 STATES 时先替换为 "active";dst 不在 STATES 返回 False;替换后 src == dst 返回 True;否则返回 (src, dst) in TRANSITIONS 的布尔值。
187
+ def can_transition(src, dst) -> bool:
188
+ """迁移是否合法(含幂等;未知 src 按 active 处理)。"""
189
+ src = src if src in STATES else "active"
190
+ if dst not in STATES:
191
+ return False
192
+ if src == dst:
193
+ return True # 幂等:同状态是 no-op
194
+ return (src, dst) in TRANSITIONS
195
+
196
+
197
+ # 生效条件:src 不在 STATES 时替换为 "active";dst 不在 STATES 返回 (False, 'unknown_state', ...);src == dst 返回 (True, 'noop', ...);(src, dst) 不在 TRANSITIONS 返回 (False, 'illegal_transition', ...);is_downgrade(src, dst) 且 protected 为真且 override 为假时返回 (False, 'protected', ...);其余返回 (True, 'ok', f'{src}→{dst} 合法')。
198
+ def check(src, dst, protected: bool = False, override: bool = False):
199
+ """迁移合法性裁决 → `(ok, code, reason)`。**唯一裁决点**(纯函数,无 IO)。
200
+
201
+ code 取值:`ok` / `noop`(同状态,不写盘)/ `unknown_state` /
202
+ `illegal_transition` / `protected`。
203
+ """
204
+ src = src if src in STATES else "active"
205
+ if dst not in STATES:
206
+ return False, "unknown_state", f"未知状态 {dst!r}(允许:{STATES})"
207
+ if src == dst:
208
+ return True, "noop", "状态未变(幂等,不写盘)"
209
+ if (src, dst) not in TRANSITIONS:
210
+ legal = "、".join(f"{a}→{b}" for a, b in sorted(TRANSITIONS))
211
+ return False, "illegal_transition", (
212
+ f"{src}→{dst} 不在合法迁移表内(允许:{legal})——"
213
+ "降级与回升都须逐级,跨级迁移一律拒绝")
214
+ if is_downgrade(src, dst) and protected and not override:
215
+ return False, "protected", (
216
+ f"受保护节点不接受降级迁移 {src}→{dst}(保护 = 不可遗忘);"
217
+ "确需降级请显式 override=True")
218
+ return True, "ok", f"{src}→{dst} 合法"
219
+
220
+
221
+ # 生效条件:以 src、dst、protected、override 调 check 后,ok 为真时返回其 code,ok 为假时抛 TransitionError,抛出时 src 参数在 STATES 中则原样、否则替换为 "active",dst、code、why 按源码透传。
222
+ def require_transition(src, dst, protected: bool = False, override: bool = False):
223
+ """合法则返回 code,非法则抛 `TransitionError`(写路径的硬拒入口)。"""
224
+ ok, code, why = check(src, dst, protected=protected, override=override)
225
+ if not ok:
226
+ raise TransitionError(src if src in STATES else "active", dst, code, why)
227
+ return code
228
+
229
+
230
+ # 生效条件:src 取 state_of(fm),prot 取 bool(fm.get("protected") or fm.get("immutable"));check 返回 ok 假或 code == "noop" 时原样返回 (ok, code, why) 且不改 fm;否则把 dst 写入 fm[STATE_FIELD],并把含 at/from/to/reason/actor 的新条目追加到由 fm.get(HISTORY_FIELD) or [] 复制的列表、截取末 HISTORY_KEEP 条写回 fm[HISTORY_FIELD],返回 (True, code, why)。
231
+ #: 裸 frontmatter 探针的假 node_id(`protect.is_protected` 的 `(cg, node_id)` 形态所需;
232
+ #: 真实节点 id 来自文件名/显式声明,不含 NUL ⇒ 与既有索引键不可能相撞)。
233
+ _FM_PROBE_ID = "\x00fm-probe"
234
+
235
+
236
+ class _FmProbe:
237
+ """裸 frontmatter → `protect.is_protected` 所需的 `(cg, node_id)` 形态(**零规则载体**)。
238
+
239
+ #377(2026-10-14):本模块的降级判据此前只读 `fm["protected"]` / `fm["immutable"]`
240
+ 两位,漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**
241
+ ——anchor/self 层节点可被无痕降级。本类**不复制任何判据**——规则单点仍是
242
+ `protect.is_protected`——只把调用方手里已有的 frontmatter 摆成该判据所需的
243
+ 索引快照形态(唯一索引条目=该映射本身)。刻意**不提供** `_maybe_reload_index`
244
+ (`protect._fm` 的探活分支取不到即跳过)且 `get()` 恒返回 None(门控字段回退
245
+ 读文件的分支在此无文件可读、**不抛异常**)⇒ 判定 100% 基于传入映射:
246
+ 零 IO、零副作用(`stamp` 是就地改 fm 的纯函数面)。
247
+ """
248
+
249
+ __slots__ = ("index",)
250
+
251
+ def __init__(self, fm):
252
+ self.index = {"nodes": {_FM_PROBE_ID: fm if isinstance(fm, dict) else {}}}
253
+
254
+ def get(self, node_id=None): # protect._fm 的回退分支:探针无文件可读
255
+ return None
256
+
257
+
258
+ def _is_protected_fm(fm) -> tuple:
259
+ """裸 frontmatter 的「不可遗忘」判定 → `(是否受保护, 原因)`。
260
+
261
+ 判据单点=**`protect.is_protected`**(层保护 self/anchor ∪ 显式 protected 位 ∪
262
+ 按分保护 ≥0.70 且来源缺省/hint);本函数只负责把它喂给判据,不自带任何规则。
263
+ """
264
+ return protect.is_protected_entry(fm) # #431 批:_FmProbe 副本收口到条目口径单点
265
+
266
+
267
+ def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
268
+ override: bool = False):
269
+ """在给定 frontmatter 上**就地**推进状态(无 IO)→ `(ok, code, why)`。
270
+
271
+ 与 `set_state()` 共用同一裁决点(`check`),供**需与其他字段同批落盘**的收
272
+ 口点使用——`writelimit` 的降权要一次写盘改 tags/importance/状态,`forgetting`
273
+ 的强化同理;否则状态得单独再写一次盘(同一节点两倍 IO)。
274
+ 合法且非幂等时写入 `STATE_FIELD` 并追加 `HISTORY_FIELD`;失败/幂等不动 fm。
275
+ """
276
+ src = state_of(fm)
277
+ # #377(2026-10-14):原判据只读 fm 的**显式两位**(protected / immutable),
278
+ # 漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**
279
+ # ——anchor/self 层节点可被无痕降级。改为「显式两位 ∪ is_protected」:
280
+ # **超集**,原判据一字不减(immutable 位照旧、override=True 照旧短路到 check 的
281
+ # override 分支)⇒ 既有判定与 override 通路逐位不变;判据本体仍是 protect 的单点,
282
+ # 不在本模块复制一份。
283
+ prot = bool(fm.get("protected") or fm.get("immutable")) \
284
+ or _is_protected_fm(fm)[0]
285
+ ok, code, why = check(src, dst, protected=prot, override=override)
286
+ if not ok or code == "noop":
287
+ return ok, code, why
288
+ fm[STATE_FIELD] = dst
289
+ hist = list(fm.get(HISTORY_FIELD) or [])
290
+ hist.append({"at": time.time(), "from": src, "to": dst,
291
+ "reason": reason, "actor": actor})
292
+ fm[HISTORY_FIELD] = hist[-HISTORY_KEEP:]
293
+ return True, code, why
294
+
295
+
296
+ # ---------------------------------------------------------------- 索引同步
297
+
298
+ # 生效条件:cg.index 非 dict 时静默 return;index 的 "nodes" 中查不到 node_id 时 return;否则把 fm.get(STATE_FIELD)(缺键即 None)写入该条目,cg._dirty 为 dict 时记入该条目并调用可调用的 cg.flush。
299
+ def _sync_index(cg, node_id, fm) -> None:
300
+ """把 state 同步进索引快照(免读文件可查);无索引实现时静默跳过。
301
+
302
+ 只同步 `state` 一个键:迁移历史已在 frontmatter 与 `_lifecycle.jsonl` 留痕,
303
+ 放进索引会让快照无谓膨胀。
304
+ """
305
+ idx = getattr(cg, "index", None)
306
+ if not isinstance(idx, dict):
307
+ return
308
+ e = (idx.get("nodes") or {}).get(node_id)
309
+ if e is None:
310
+ return
311
+ e[STATE_FIELD] = fm.get(STATE_FIELD)
312
+ dirty = getattr(cg, "_dirty", None)
313
+ if isinstance(dirty, dict):
314
+ dirty[node_id] = e
315
+ flush = getattr(cg, "flush", None)
316
+ if callable(flush):
317
+ flush()
318
+
319
+
320
+ # ---------------------------------------------------------------- 推进 / 回填
321
+
322
+ # 生效条件:cg.get(node_id) 为假值返回 {'ok': False, 'error': 'node_not_found', ...};否则以 state_of(fm) 作 src 调 stamp——stamp 不 ok 返回 ok=False + error=code,code == "noop" 返回 ok=True + changed=False;其余情况(合法且真迁移,即**资格面已过**)先经 autonomy_modes.e_gate() 档位判定(补强批次 v1.2·E 面接线,位置=写盘之前):非 ALLOW(plan 档无计划)即经 forbidden_result() fail-closed 早退(ok=False、error=autonomy_forbidden、零写盘、零审计行),ALLOW(confirm/full)才取 fm[HISTORY_FIELD][-1]["at"] 后写盘、_sync_index 并追加审计 JSONL(append_jsonl 抛异常被吞掉),返回 ok=True + changed=True。
323
+ def set_state(cg, node_id: str, dst: str, reason: str = None,
324
+ actor: str = None, override: bool = False) -> dict:
325
+ """推进一个节点的生命周期状态(**唯一推进入口**)。
326
+
327
+ 非法迁移不走异常而是返回 `{"ok": False, "error": <code>, ...}`(负路由:
328
+ 调用方自行决定降级处理;要硬拒请用 `require_transition`)。幂等迁移返回
329
+ `changed=False` 且不写盘。返回体始终带 `from` / `to` / `code` 便于审计。
330
+
331
+ **档位闸(补强批次 v1.2·E 面接线)**:合法且真迁移(`stamp` 已过=资格面
332
+ 已过)之后、写盘之前,先经 `autonomy_modes.e_gate()`(设计 §三 plan 档
333
+ E「须命中计划步骤」)——plan 档无计划 ⇒ fail-closed 早退(
334
+ `ok=False`/`error="autonomy_forbidden"`/带 hint、零写盘、零审计行);
335
+ confirm/full ⇒ ALLOW、**原链原样**(逐位不变)。非法迁移与 noop 由
336
+ `stamp` 先行裁决、各回各的 code(档位**不参与**资格判定)。
337
+ """
338
+ node = cg.get(node_id)
339
+ if not node:
340
+ return {"ok": False, "error": "node_not_found", "node_id": node_id}
341
+ fm = dict(node.get("frontmatter") or {})
342
+ src = state_of(fm)
343
+ ok, code, why = stamp(fm, dst, reason=reason, actor=actor, override=override)
344
+ base = {"node_id": node_id, "from": src, "to": dst, "code": code}
345
+ if not ok:
346
+ return {**base, "ok": False, "error": code, "reason": why}
347
+ if code == "noop":
348
+ return {**base, "ok": True, "changed": False, "reason": why}
349
+ # 三档自治(补强批次 v1.2·E 面接线,设计 §三 plan 档 E「须命中计划步骤」):
350
+ # 位置=资格面(`stamp` 的合法性/保护裁决)之后、写盘之前——非法迁移与 noop
351
+ # 已在上方各回各的 code,档位不参与资格判定;confirm/full ⇒ ALLOW 原链原样。
352
+ from . import autonomy_modes as _am
353
+ _dec = _am.e_gate()
354
+ if _dec["decision"] != _am.ALLOW:
355
+ out = _am.forbidden_result(_dec, node_id=node_id, changed=False)
356
+ out.update({"from": src, "to": dst, "code": "autonomy_forbidden"})
357
+ return out
358
+ at = fm[HISTORY_FIELD][-1]["at"]
359
+ cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
360
+ node.get("content") or "")
361
+ _sync_index(cg, node_id, fm)
362
+ # 退役接线(2026-10-06):状态迁移改变 `is_archived` 读数 ⇒ 依赖该判据的
363
+ # 邻接缓存(`chain.adjacency` 的 skip_archived 过滤)必须**同点作废**——
364
+ # 此前只有本地写路径(add/_stage 尾三连)清缓存,set_state 后旧缓存会让
365
+ # 退役节点继续沿因果链/图面扩散(本批探针实证:归档后 causal_chain 仍含
366
+ # 目标)。懒导入避免模块环;`invalidate_cache` 内部自吞异常,不阻断推进。
367
+ from . import chain as _chain
368
+ _chain.invalidate_cache(cg)
369
+ try:
370
+ # issue #547:`_lifecycle.jsonl` 是审计台账(状态迁移留痕),按 #549 的口径
371
+ # 走 durable=True(原为缺省 + `except: pass`,丢行静默)。
372
+ append_jsonl(os.path.join(cg.root, AUDIT_FILE), {
373
+ "t": at, "action": "set_state", "node_id": node_id,
374
+ "from": src, "to": dst, "reason": reason, "actor": actor,
375
+ "override": bool(override)}, durable=True)
376
+ except Exception: # 审计失败不阻断状态推进
377
+ pass
378
+ return {**base, "ok": True, "changed": True, "reason": why, "at": at}
379
+
380
+
381
+ # 生效条件:nodes 取 (cg.index or {}).get("nodes") or {},遍历中缺 STATE_FIELD 或该值不在 STATES 的 nid 计入 missing(累计数达 limit 即 break,limit <= 0 时立即 break 使 missing 为空),apply 假值只返回 dry_run=True 的盘点结果(**不接档位闸**——零写盘面照旧),apply 为真时先经 autonomy_modes.e_gate() 档位判定(补强批次 v1.2·E 面接线,位置=盘点资格面之后、写盘之前):非 ALLOW(plan 档无计划)即经 forbidden_result() fail-closed 早退(零写盘、backfilled=0),ALLOW(confirm/full)才对每个 missing 中 cg.get 取不到的记入 failed、取到的把 state_of(fm) 显式写回 fm[STATE_FIELD] 并写盘与 _sync_index 后记入 done,返回 dry_run=False 的结果。
382
+ def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
383
+ """存量回填:把缺 `state` 的节点显式补成 `active`(幂等)。
384
+
385
+ 缺字段本就按 active 解释(`state_of`),故回填**不是让功能工作的前提**,
386
+ 而是把「缺省」变成「显式」——索引/审计里从此可直接读到状态。
387
+ `apply=False`(默认)只盘点。写不动(文件取不回)的节点进 `failed` 如实上报。
388
+
389
+ **档位闸(补强批次 v1.2·E 面接线)**:`apply=True` 的**写盘前**先经
390
+ `autonomy_modes.e_gate()`(设计 §三 plan 档 E「须命中计划步骤」)——plan 档
391
+ 无计划 ⇒ fail-closed 早退(零写盘、`backfilled=0`);confirm/full ⇒ ALLOW、
392
+ 原链原样。`apply=False`(盘点)不接闸。
393
+ """
394
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
395
+ missing = []
396
+ for nid, e in list(nodes.items()):
397
+ if len(missing) >= limit:
398
+ break
399
+ if (e or {}).get(STATE_FIELD) in STATES:
400
+ continue
401
+ missing.append(nid)
402
+ missing.sort()
403
+ if not apply:
404
+ return {"ok": True, "dry_run": True, "scanned": len(nodes),
405
+ "missing": len(missing), "planned": missing[:50]}
406
+ # 三档自治(补强批次 v1.2·E 面接线):E 类动作**写盘前**的档位判定单点
407
+ # (同 `set_state` 口径)——盘点(资格面)已完成、任何盘面写入之前。
408
+ from . import autonomy_modes as _am
409
+ _dec = _am.e_gate()
410
+ if _dec["decision"] != _am.ALLOW:
411
+ return _am.forbidden_result(_dec, dry_run=False, scanned=len(nodes),
412
+ missing=len(missing), backfilled=0)
413
+ done, failed = [], []
414
+ for nid in missing:
415
+ node = cg.get(nid)
416
+ if not node:
417
+ failed.append(nid)
418
+ continue
419
+ fm = dict(node.get("frontmatter") or {})
420
+ fm[STATE_FIELD] = state_of(fm) # 缺省 active → 显式落盘
421
+ cg._write_node(nid, os.path.join(cg.root, node["path"]), fm,
422
+ node.get("content") or "")
423
+ _sync_index(cg, nid, fm)
424
+ done.append(nid)
425
+ return {"ok": True, "dry_run": False, "scanned": len(nodes),
426
+ "missing": len(missing), "backfilled": len(done),
427
427
  "planned": done[:50], "failed": failed[:20]}