@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/trust.py CHANGED
@@ -1,1114 +1,1114 @@
1
- # -*- coding: utf-8 -*-
2
- """md_cg · 可验证记忆单元(验证态状态机 + 依赖图 + 双时间轴)
3
-
4
- 把「可信度」从散文式描述,变成**显式、可查询、可传播、可输出**的结构化状态。
5
- 三件事:
6
-
7
- 1. **验证态持续化**——`verification_state` ∈ (unverified / verified /
8
- expired / doubted / rechecking),随验证动作与依赖变动**流转**,不是一次性
9
- 布尔开关;状态落 `frontmatter.verification_state`(节点 md 是唯一真源),
10
- 索引快照同名透出(免读文件可查)。
11
- 2. **依赖声明与失效传播**——单元显式声明它依赖谁(`depends_on`);被依赖单元
12
- 被修改/证伪时,**直接下游立即同步标为 doubted**(一跳,低成本);**多跳**
13
- 交由 `propagate()` 后台巡检重算,不阻塞写入与查询。
14
- 3. **双时间轴**——既有「何时不再成立」(`valid_until`)之外补「何时开始成立」
15
- (`valid_from`),使时效区间可判定:未生效 / 生效中 / 已过期。
16
-
17
- 与 `lifecycle.py` 刻意分层(同构实现、**正交语义**,禁跨套复用常量):
18
- · `lifecycle.py` = 节点**生命周期**(active/converged/demoted/archived);
19
- · 本模块 = 节点**验证态**(unverified/verified/expired/doubted/rechecking)。
20
- 两者都是「单点裁决 + 单点推进 + 硬拒入口」,但状态集不共享、`_RANK` 不共享。
21
-
22
- 与 `provenance.py` 刻意分层:
23
- · `provenance.py` = 节点**派生血缘**(「它由谁派生」,`_link.jsonl`);
24
- · 本模块 = 节点**依赖与证据强度**(「它靠谁成立、现在还成不成立」,
25
- `_trust.jsonl`)。血缘是既成事实,依赖是可失效假设——不可混用。
26
-
27
- 三条纪律(对齐 G8 裁定与 lifecycle 口径):
28
- 1. **台账失败降级不阻断写**——`mark_dependents()` 永不抛,写不进只留痕告警;
29
- 2. **历史不回填**——存量缺 `verification_state` 视为 `unverified`,`backfill()`
30
- 只在显式调用时把「缺省」变「显式」;
31
- 3. **巡检只读**——`patrol()` 检出悬空依赖/过期节点但**不自动改状态、不删节点**。
32
-
33
- 命名避让(既有先例):字段**不叫 `state`**——该名已被裁决四态
34
- (ACCEPT/REJECT/DEFER/BLINDSPOT)占用,`lifecycle_state` 的先例同此动机。
35
-
36
- 零第三方依赖(D-005)。
37
- """
38
- from __future__ import annotations
39
-
40
- import os
41
- import time
42
- import math
43
- from datetime import datetime
44
-
45
- from . import protect
46
- from . import security as _security
47
- from .fsutil import append_jsonl, read_jsonl
48
- from .security import AccessDenied
49
-
50
- #: 验证态全集。语义:
51
- #: unverified 未验证(默认;存量缺字段即视为它)
52
- #: verified 已验证(有验证方式与证据,且依赖未动)
53
- #: doubted 存疑(**依赖的地基动了**——异常的新定义)
54
- #: rechecking 重新验证中(复核进行态)
55
- #: expired 已过期(超出时效区间,或证据整体失效)
56
- STATES = ("unverified", "verified", "doubted", "rechecking", "expired")
57
-
58
- #: frontmatter 字段名(索引快照同名透出)。刻意避开 `state`——与 lifecycle 同动机。
59
- STATE_FIELD = "verification_state"
60
- #: 验证履历字段(frontmatter 侧历史,滚动保留最近 HISTORY_KEEP 条)
61
- HISTORY_FIELD = "verification_history"
62
- HISTORY_KEEP = 20
63
- #: 依赖声明字段(CCG「子功能」槽的落字段)
64
- DEPS_FIELD = "depends_on"
65
- #: 双时间轴(**效力时间**)字段。2026-09-19 阶段一:规范名迁移到
66
- #: `effective_from` / `effective_until`(**新写入落规范键**),历史名
67
- #: `valid_from` / `valid_until` 保留为**读取侧回落别名**(存量不迁移、零破坏)。
68
- FROM_FIELD = "valid_from"
69
- UNTIL_FIELD = "valid_until"
70
- #: 规范名(新写入落此;读取时优先于同名族旧键)
71
- EFFECTIVE_FROM_FIELD = "effective_from"
72
- EFFECTIVE_UNTIL_FIELD = "effective_until"
73
- #: 信念时间(体系**何时确认此条**):取代/审核的锚。
74
- #: **不是效力语义**——它既不是「已结束」也不是「尚未开始」,
75
- #: 故绝不并入 `scrub._EXPIRY_KEYS`(已结束族)或 `scrub._NOT_YET_KEYS`(未生效族)。
76
- BELIEVED_FIELD = "believed_at"
77
- #: 过期时刻(写盘冗余:由 `effective_until` 派生落盘,供审计/对账直读)。
78
- EXPIRED_FIELD = "expired_at"
79
-
80
- #: 端点取值优先级(**规范键优先、别名回落**,2026-09-19 阶段一)。
81
- #: 与 `scrub._NOT_YET_KEYS` / `scrub._EXPIRY_KEYS` 同键族——两处共用同一套别名,
82
- #: 任一侧新增键须同步另一侧(交叉守卫测试 test_validity_filter 守住)。
83
- FROM_ALIASES = (EFFECTIVE_FROM_FIELD, FROM_FIELD, "valid_since", "starts_at")
84
- UNTIL_ALIASES = (EFFECTIVE_UNTIL_FIELD, UNTIL_FIELD,
85
- "expires_at", "expire_at", "expiry", "deadline")
86
- #: 验证态迁移审计(append-only,与 _lifecycle.jsonl / _maintain.jsonl 同风格)
87
- AUDIT_FILE = "_trust.jsonl"
88
-
89
- #: 降级序位(用于「受保护豁免降级」判定)。verified 最高,doubted/expired 更低。
90
- _RANK = {"verified": 0, "rechecking": 1, "unverified": 1, "doubted": 2, "expired": 3}
91
-
92
- #: 合法迁移表。刻意不收录的(即拒绝的):
93
- #: verified → unverified(回落未验证:证据已存在,只应「存疑」而非「清零」)
94
- #: doubted → expired(跳级:存疑未经复核不得直接判过期)
95
- #: 注:`unverified → doubted` **收录**——两条路都真实到达这里:①上游变动波及一个
96
- #: 从未验证过的下游(「地基动了」对未验证者同样成立);②未验证节点收到**负证据**
97
- #: (证据削弱本身就是存疑的依据,比停在「未验证」更准确)。
98
- TRANSITIONS = frozenset({
99
- ("unverified", "verified"),
100
- ("unverified", "doubted"),
101
- ("unverified", "rechecking"),
102
- ("unverified", "expired"),
103
- ("verified", "doubted"),
104
- ("verified", "rechecking"),
105
- ("verified", "expired"),
106
- ("doubted", "rechecking"),
107
- ("doubted", "verified"),
108
- ("rechecking", "verified"),
109
- ("rechecking", "doubted"),
110
- ("rechecking", "unverified"),
111
- ("rechecking", "expired"),
112
- ("expired", "rechecking"),
113
- ("expired", "verified"),
114
- })
115
-
116
- #: 依赖边上限(单节点直接下游数);超出即拒收,防「依赖声明写成噪声」。
117
- MAX_DEPS = 32
118
- #: 多跳传播的节点上限(对齐 subgraph.MAX_NODES_DEFAULT 的量级)
119
- MAX_NODES_DEFAULT = 500
120
-
121
-
122
- class TrustError(Exception):
123
- """非法验证态迁移 / 依赖声明非法(写路径用 `require_transition` 直接抛)。"""
124
-
125
- def __init__(self, src, dst, code, reason):
126
- super().__init__(f"非法验证态迁移 {src}→{dst}({code}):{reason}")
127
- self.src, self.dst, self.code, self.reason = src, dst, code, reason
128
-
129
-
130
- # ---------------------------------------------------------------- 纯函数裁决
131
-
132
- def state_of(fm) -> str:
133
- """frontmatter → 验证态;缺字段或未知值 → "unverified"(存量兼容,不猜测)。"""
134
- if not isinstance(fm, dict):
135
- return "unverified"
136
- s = fm.get(STATE_FIELD)
137
- return s if s in STATES else "unverified"
138
-
139
-
140
- def is_downgrade(src: str, dst: str) -> bool:
141
- """是否向「更低可信度」迁移(verified < unverified/rechecking < doubted < expired)。"""
142
- return _RANK.get(dst, 0) > _RANK.get(src, 0)
143
-
144
-
145
- def can_transition(src, dst) -> bool:
146
- """迁移是否合法(含幂等;未知 src 按 unverified 处理)。"""
147
- src = src if src in STATES else "unverified"
148
- if dst not in STATES:
149
- return False
150
- if src == dst:
151
- return True # 幂等:同状态是 no-op
152
- return (src, dst) in TRANSITIONS
153
-
154
-
155
- def check(src, dst, protected: bool = False, override: bool = False):
156
- """迁移合法性裁决 → `(ok, code, reason)`。**唯一裁决点**(纯函数,无 IO)。
157
-
158
- code 取值:`ok` / `noop`(同状态,不写盘)/ `unknown_state` /
159
- `illegal_transition` / `protected`。
160
- """
161
- src = src if src in STATES else "unverified"
162
- if dst not in STATES:
163
- return False, "unknown_state", f"未知验证态 {dst!r}(允许:{STATES})"
164
- if src == dst:
165
- return True, "noop", "验证态未变(幂等,不写盘)"
166
- if (src, dst) not in TRANSITIONS:
167
- legal = "、".join(f"{a}→{b}" for a, b in sorted(TRANSITIONS))
168
- return False, "illegal_transition", (
169
- f"{src}→{dst} 不在合法迁移表内(允许:{legal})——"
170
- "验证态只沿「验证/存疑/复核/过期」四条路径流转,跨级迁移一律拒绝")
171
- if is_downgrade(src, dst) and protected and not override:
172
- return False, "protected", (
173
- f"受保护节点不接受降级迁移 {src}→{dst}(保护 = 不可轻弃);"
174
- "确需降级请显式 override=True")
175
- return True, "ok", f"{src}→{dst} 合法"
176
-
177
-
178
- def require_transition(src, dst, protected: bool = False, override: bool = False):
179
- """合法则返回 code,非法则抛 `TrustError`(写路径的硬拒入口)。"""
180
- ok, code, why = check(src, dst, protected=protected, override=override)
181
- if not ok:
182
- raise TrustError(src if src in STATES else "unverified", dst, code, why)
183
- return code
184
-
185
-
186
- #: 裸 frontmatter 探针的假 node_id(`protect.is_protected` 的 `(cg, node_id)` 形态所需;
187
- #: 真实节点 id 来自文件名/显式声明,不含 NUL ⇒ 与既有索引键不可能相撞)。
188
- _FM_PROBE_ID = "\x00fm-probe"
189
-
190
-
191
- class _FmProbe:
192
- """裸 frontmatter → `protect.is_protected` 所需的 `(cg, node_id)` 形态(**零规则载体**)。
193
-
194
- #377(2026-10-14):本模块的降级判据此前只读 `fm["protected"]` / `fm["immutable"]`
195
- 两位,漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**。
196
- 本类**不复制任何判据**——规则单点仍是 `protect.is_protected`——只把调用方手里
197
- 已有的 frontmatter 摆成该判据所需的索引快照形态(唯一索引条目=该映射本身)。
198
- 刻意**不提供** `_maybe_reload_index`(`protect._fm` 的探活分支取不到即跳过)且
199
- `get()` 恒返回 None(门控字段回退读文件的分支在此无文件可读、**不抛异常**)⇒
200
- 判定 100% 基于传入映射:零 IO、零副作用(`stamp` 是就地改 fm 的纯函数面)。
201
- """
202
-
203
- __slots__ = ("index",)
204
-
205
- def __init__(self, fm):
206
- self.index = {"nodes": {_FM_PROBE_ID: fm if isinstance(fm, dict) else {}}}
207
-
208
- def get(self, node_id=None): # protect._fm 的回退分支:探针无文件可读
209
- return None
210
-
211
-
212
- def _is_protected_fm(fm) -> tuple:
213
- """裸 frontmatter 的「不可遗忘」判定 → `(是否受保护, 原因)`。
214
-
215
- 判据单点=**`protect.is_protected`**(层保护 self/anchor ∪ 显式 protected 位 ∪
216
- 按分保护 ≥0.70 且来源缺省/hint);本函数只负责把它喂给判据,不自带任何规则。
217
- """
218
- return protect.is_protected_entry(fm) # #431 批:_FmProbe 副本收口到条目口径单点
219
-
220
-
221
- def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
222
- evidence: str = None, method: str = None, trigger: str = None,
223
- override: bool = False):
224
- """在给定 frontmatter 上**就地**推进验证态(无 IO)→ `(ok, code, why)`。
225
-
226
- 与 `set_state()` 共用同一裁决点(`check`),供**需与其他字段同批落盘**的
227
- 收口点使用(写入时一次写盘改依赖/时间轴/验证态)。
228
- """
229
- src = state_of(fm)
230
- # #377(2026-10-14):原判据只读 fm 的**显式两位**(protected / immutable),
231
- # 漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**
232
- # ——anchor/self 层节点可被无痕降级。改为「显式两位 ∪ is_protected」:
233
- # **超集**,原判据一字不减(immutable 位照旧、override=True 照旧短路到 check 的
234
- # override 分支)⇒ 既有判定与 override 通路逐位不变;判据本体仍是 protect 的单点,
235
- # 不在本模块复制一份。
236
- prot = bool(fm.get("protected") or fm.get("immutable")) \
237
- or _is_protected_fm(fm)[0]
238
- ok, code, why = check(src, dst, protected=prot, override=override)
239
- if not ok or code == "noop":
240
- return ok, code, why
241
- fm[STATE_FIELD] = dst
242
- rec = {"at": time.time(), "from": src, "to": dst, "reason": reason,
243
- "actor": actor, "trigger": trigger}
244
- if method:
245
- rec["method"] = str(method)[:120]
246
- if evidence:
247
- rec["evidence"] = str(evidence)[:300]
248
- hist = list(fm.get(HISTORY_FIELD) or [])
249
- hist.append(rec)
250
- fm[HISTORY_FIELD] = hist[-HISTORY_KEEP:]
251
- if method:
252
- fm["verification_method"] = str(method)[:120]
253
- if evidence:
254
- fm["verification_evidence"] = str(evidence)[:300]
255
- fm["verified_at"] = rec["at"]
256
- return True, code, why
257
-
258
-
259
- # ---------------------------------------------------------------- 双时间轴
260
-
261
- #: 单位归一判据:epoch **秒**到公元 5138 年仍 < 1e11,而 epoch **毫秒**自 1973-03
262
- #: 起已 > 1e11 —— 量级差 3 个数量级,故「>= 1e11」判为毫秒。
263
- #: 受保护的既有值:全时窗哨兵 `9999999999.0`(nodefile.FULL_TIME_WINDOW_MAX)
264
- #: 与秒级 `created_at` 一律**不受影响**(test_trust 的「数字直通」断言同此)。
265
- _MS_EPOCH_THRESHOLD = 1e11
266
-
267
-
268
- def epoch_seconds(value, *, _allow_nonfinite=False):
269
- """时间**数值** → epoch 秒(单位归一的**唯一实现点**);非数值 → None。
270
-
271
- 为什么需要它(issue #23 根因):图内规范单位是**秒**——`created_at`、
272
- `mdcg._write` 的默认观测窗、全时窗哨兵、`parse_time` 全是秒;但摄取链
273
- (`sources.DSHSessionSource` / `JsonlSource`)历史上产出**毫秒**。毫秒值一旦
274
- 进入 `condition_space.time_window`,`stg(op=timeline)` 的倒序排序被 1e3 倍放大
275
- 顶到最前,摄取节点**永久占据头部**(auto-recall 取到的「最新 N 条」全是它们);
276
- 同一根因还让 S2 时间门控把秒节点的区间判成不相交而误剔除。
277
-
278
- 口径(不猜测):有限数值 `>= _MS_EPOCH_THRESHOLD` → `/1000.0`;其余原样 float。
279
- NaN / Infinity / 超出 float 范围的数值返回 None,不得遮蔽合法别名。
280
- 于是「已落库的历史毫秒数据」**无需改盘**即可参与排序与区间比较
281
- (读取侧归一,零迁移)。
282
-
283
- 不适用条件:日期/日期时间**字符串**(走 `parse_time`);`spatial.bbox` 等
284
- 非时间的数值;全时窗哨兵判定(`nodefile.is_full_time_window` 按「两侧极值
285
- 恰好覆盖」判,不做单位换算)。
286
- """
287
- if not isinstance(value, (int, float)):
288
- return None
289
- try:
290
- v = float(value)
291
- except (ValueError, OverflowError):
292
- return None
293
- if not _allow_nonfinite and not math.isfinite(v):
294
- return None
295
- return v / 1000.0 if v >= _MS_EPOCH_THRESHOLD else v
296
-
297
-
298
- def parse_time(value, *, _allow_nonfinite=False):
299
- """时间值 → epoch 秒;不可解析返回 None(**不猜测**)。
300
-
301
- 接受:数字(epoch 秒;**毫秒自动归一**,见 `epoch_seconds`)/ 数字串
302
- (同左)/ 日期或日期时间字符串(ISO 8601,宽松:空格分隔、`Z` 后缀、
303
- 日期精度都容忍)。显式 Z / UTC offset 按绝对时刻解析;无时区日期保留
304
- 既有本地时间语义。纯标准库实现。
305
-
306
- 单位归一单点落在此处:它是全系统时间数值的**唯一读入口**
307
- (时间算子 / `validity` / `provenance` 边 / 效力轴端点 / `stg._interval`),
308
- 故历史毫秒数据在**所有**读取面上一次生效,不再逐调用点打补丁。
309
- """
310
- if value is None or value == "":
311
- return None
312
- if isinstance(value, (int, float)):
313
- return epoch_seconds(value, _allow_nonfinite=_allow_nonfinite)
314
- s = str(value).strip()
315
- if not s:
316
- return None
317
- try:
318
- return epoch_seconds(float(s), _allow_nonfinite=_allow_nonfinite)
319
- except ValueError:
320
- pass
321
- # Explicit offsets denote an instant, independent of the host timezone.
322
- # Naive dates below deliberately retain the existing local-time contract.
323
- t = s.replace("/", "-")
324
- try:
325
- aware = datetime.fromisoformat(t)
326
- if aware.tzinfo is not None:
327
- ts = aware.timestamp()
328
- return ts if math.isfinite(ts) else None
329
- except (ValueError, OverflowError, OSError):
330
- pass
331
- t = t.replace("T", " ")
332
- fmts = ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d")
333
- for f in fmts:
334
- try:
335
- return time.mktime(time.strptime(t, f))
336
- except ValueError:
337
- continue
338
- return None
339
-
340
-
341
- def first_endpoint(fm, keys):
342
- """按 `keys` 优先级取首个**可解析**端点 → `(epoch, key)`;全链无值 → `(None, None)`。
343
-
344
- 单点定义「规范键优先、别名回落」的取值口径:某键**存在但不可解析**时继续回落
345
- (而非按 None 定案)——「写坏了的时间值」不得遮蔽同族另一个合法键。
346
- """
347
- if not isinstance(fm, dict):
348
- return None, None
349
- for k in keys:
350
- if k in fm:
351
- ts = parse_time(fm.get(k))
352
- if ts is not None:
353
- return ts, k
354
- return None, None
355
-
356
-
357
- def validity(fm, now: float = None):
358
- """双时间轴判定 → `(kind, start, end)`。
359
-
360
- kind ∈ `unknown`(无时间轴约束)/ `not_yet`(未生效)/ `active`(生效中)/
361
- `expired`(已过期)。任一端点不可解析 → 该端点按 None 处理(不猜测、不误判)。
362
-
363
- 端点取值(2026-09-19 阶段一):**规范键优先、别名回落**——
364
- 起点 `effective_from` > `valid_from` > `valid_since` > `starts_at`;
365
- 终点 `effective_until` > `valid_until` > `expires_at` > `expire_at` > `expiry` > `deadline`。
366
- `believed_at`(信念时间)**不参与**本判定:它是「体系何时确认此条」(取代/审核的锚),
367
- 不是效力端点——并入任一方向都会把「已确认」误判成「已生效/已失效」。
368
- """
369
- if not isinstance(fm, dict):
370
- return "unknown", None, None
371
- start, _sk = first_endpoint(fm, FROM_ALIASES)
372
- end, _ek = first_endpoint(fm, UNTIL_ALIASES)
373
- if start is None and end is None:
374
- return "unknown", None, None
375
- t = time.time() if now is None else float(now)
376
- if start is not None and t < start:
377
- return "not_yet", start, end
378
- if end is not None and t > end:
379
- return "expired", start, end
380
- return "active", start, end
381
-
382
-
383
- def believed_at(fm) -> float:
384
- """信念时间(体系**何时确认此条**)→ epoch 秒;缺字段/不可解析 → None(不猜测)。
385
-
386
- 用途:取代(supersede)/ 审核的排序锚——「谁更晚被确认」是判定新旧的正路;
387
- **不得**拿 `valid_from`/`valid_until` 代替(那是事实在任务世界里何时有效,
388
- 与体系何时知道它无关)。
389
- """
390
- if not isinstance(fm, dict):
391
- return None
392
- return parse_time(fm.get(BELIEVED_FIELD))
393
-
394
-
395
- def is_expired(fm, now: float = None) -> bool:
396
- """`validity` 的布尔快捷:是否「**已过期**」。
397
-
398
- 只判 `expired`——`not_yet`(尚未生效)**不算**:两者语义相反
399
- (见 `scrub._NOT_YET_KEYS` 纪律「`valid_from` 绝不并入 `_EXPIRY_KEYS`」),
400
- 「尚未开始」不等于「已失效」。无时间轴 / 端点不可解析 → False(不猜测、不误杀)。
401
- """
402
- return validity(fm, now=now)[0] == "expired"
403
-
404
-
405
- def time_window_msg(fm, now: float = None) -> str:
406
- """时效判定的一句话(空串表示无时间轴约束)。**点名实际命中的键**(含别名)。"""
407
- kind, start, end = validity(fm, now=now)
408
- if kind == "unknown":
409
- return ""
410
- if kind == "not_yet":
411
- _ts, k = first_endpoint(fm, FROM_ALIASES)
412
- return f"未生效({k or FROM_FIELD} 未到)"
413
- if kind == "expired":
414
- _ts, k = first_endpoint(fm, UNTIL_ALIASES)
415
- return f"已过期({k or UNTIL_FIELD} 已过)"
416
- return "时效内"
417
-
418
-
419
- # ---------------------------------------------------------------- 时间算子(阶段二 4.1)
420
-
421
- #: 时间轴(**封闭枚举**)。两条轴物理隔离、语义不可互换(同 `believed_at` 的隔离纪律):
422
- #: effective 效力轴——这条事实**何时开始/不再成立**(`effective_from/until` 及别名)
423
- #: observed 观察轴——这条记忆**何时被观测/事件何时发生**(`temporal` / `time_window`)
424
- #: 不设**隐式**默认轴:入口在「启用时间算子但未指定轴」时回落 `effective`
425
- #: (与既有 `validity=` 语义连续),但轴本身永远由调用方显式决定。
426
- TIME_AXES = ("effective", "observed")
427
-
428
- #: 时间算子(**封闭枚举**,拒收未知名):候选轴端点 与 查询端点 的比较关系。
429
- #: 缺省(不给 operator)= **区间重叠**语义,见 `window_match`。
430
- TIME_OPERATORS = ("gt", "gte", "eq", "lte", "lt")
431
-
432
- #: 观察轴字段名(与 `stg._interval` 同源口径,**不新增第二套解析**)。
433
- OBSERVED_TIME_FIELD = "temporal"
434
- OBSERVED_WINDOW_FIELD = "time_window"
435
-
436
-
437
- def time_axis_of(axis) -> str:
438
- """轴名归一 → `"effective"` / `"observed"`;`None` → `"effective"`;
439
- 其余(含 `"believed"`)→ `ValueError`(**fail-closed,不静默降级**)。
440
-
441
- 与 `_stg_call`「不做签名推导——猜错会静默返回错误视图,比报错更贵」同风格:
442
- 轴写错时必须报错,因为静默按另一条轴过滤会产出**无法复算**的结果集。
443
- """
444
- if axis is None:
445
- return "effective"
446
- a = str(axis).strip().lower()
447
- if a in TIME_AXES:
448
- return a
449
- raise ValueError(f"未知 time_axis {axis!r}(允许:{TIME_AXES})")
450
-
451
-
452
- def time_window_of(fm, axis: str = "effective", *, _allow_nonfinite=False):
453
- """按轴取候选时间窗口 → `(start, end)`;不可判定 → `(None, None)`(不猜测)。
454
-
455
- · `effective`:效力轴,走 `first_endpoint(FROM_ALIASES/UNTIL_ALIASES)`
456
- (规范键优先、别名回落,与 `validity` **同源**);
457
- 缺字段/不可解析 → 该侧 `None`(= 无界,与 `validity` 的「不误判」口径一致)。
458
- · `observed`:观察轴,与 `stg._interval` **同源口径**——`temporal`(事件时刻)优先,
459
- 缺失才回退 `condition_space.time_window`(观测窗);任一端不可解析 → `(None, None)`
460
- (与 `_interval` 的「整体不可用」语义一致)。
461
-
462
- `believed_at` **永不参与**(`BELIEVED_FIELD` 不出现于任何轴)。
463
- 内部 `_allow_nonfinite=True` 仅供派生 STG 索引维持异常时间的保守候选桶;
464
- 查询入参、效力轴别名与正常消费者均使用有限端点规则。
465
- """
466
- if not isinstance(fm, dict):
467
- return None, None
468
- if time_axis_of(axis) == "observed":
469
- t = fm.get(OBSERVED_TIME_FIELD)
470
- if t is not None:
471
- ts = parse_time(t, _allow_nonfinite=_allow_nonfinite)
472
- if ts is not None:
473
- return ts, ts
474
- # 兼容两种载体形态:**fm**(`condition_space.time_window`)与**索引扁平快照**
475
- # (`time_window` 平铺在 entry 上,见 `mdcg._scan_nodes`/`_stage`)。
476
- # 只读嵌套会让「按 entry 过滤」的路径永不命中(同类坑:S2 时间门控,
477
- # mdcg.py L639 已记「直接读 cs 会让门控永不生效」)。
478
- cs = fm.get("condition_space") or {}
479
- tw = fm.get(OBSERVED_WINDOW_FIELD)
480
- if tw is None and isinstance(cs, dict):
481
- tw = cs.get(OBSERVED_WINDOW_FIELD)
482
- if isinstance(tw, (list, tuple)) and len(tw) == 2:
483
- s, e = (parse_time(v, _allow_nonfinite=_allow_nonfinite) for v in tw)
484
- if s is None or e is None:
485
- return None, None
486
- return s, e
487
- return None, None
488
- start, _sk = first_endpoint(fm, FROM_ALIASES)
489
- end, _ek = first_endpoint(fm, UNTIL_ALIASES)
490
- return start, end
491
-
492
-
493
- def _op_ok(cand, q, op) -> bool:
494
- """单个端点比较;任一端不可解析 → False(缺字段的处置归**轴策略**,此处不猜测)。"""
495
- if cand is None or q is None:
496
- return False
497
- if op == "gt":
498
- return cand > q
499
- if op == "gte":
500
- return cand >= q
501
- if op == "eq":
502
- return cand == q
503
- if op == "lte":
504
- return cand <= q
505
- if op == "lt":
506
- return cand < q
507
- return False # 未知算子:入口已 fail-closed,此处保守拒
508
-
509
-
510
- def window_match(cand_start, cand_end, q_start=None, q_end=None,
511
- start_op: str = None, end_op: str = None) -> bool:
512
- """候选窗口与查询窗口是否匹配(§1.2 B1/B2 的**唯一实现点**,纯函数)。
513
-
514
- 两种模式由「是否给 operator」**显式分叉**(不允许隐式混用——混用会产出
515
- 「无法复算」的过滤,违反白箱):
516
-
517
- · **重叠模式**(`start_op`/`end_op` 均为 `None`):候选窗口与查询窗口有交集
518
- 即命中(记忆窗口是**区间**不是点)。查询端点缺省 = 该侧**无界**(不隐含 now)。
519
- · **端点模式**(至少给一个 operator):对**显式启用的侧**做 `op(cand端, q端)`;
520
- 一侧未给 operator 但**给了该侧查询端点**时,用 B1 缺省(起点 `gte` / 终点 `lte`);
521
- 该侧查询端点也没有 → **不约束该侧**。
522
-
523
- 「未给 operator 且未给查询端点 → 不约束」是刻意的:若一律回落到 B1 缺省再比较,
524
- `_op_ok(cand, None, op)` 恒伪,于是 `start_operator="gte" + start_time=T`
525
- (单端算子,合法调用)会静默返回**空集**——把「只筛起点」误答成「没有匹配」。
526
- 端点模式下候选的该侧端点不可解析 → `False`(该侧无法比较,不猜)。
527
-
528
- 候选窗口两端皆不可解析 → `False`(该节点「无时间轴可判」)——是否因此剔除
529
- 由**轴的策略**决定(效力轴 fail-open / 观察轴 fail-closed,见候选过滤处)。
530
- """
531
- cs, ce = parse_time(cand_start), parse_time(cand_end)
532
- if cs is None and ce is None:
533
- return False
534
- qs, qe = parse_time(q_start), parse_time(q_end)
535
- if start_op is None and end_op is None:
536
- if qs is not None and ce is not None and ce < qs:
537
- return False
538
- if qe is not None and cs is not None and cs > qe:
539
- return False
540
- return True
541
- if start_op is not None or qs is not None:
542
- if not _op_ok(cs, qs, start_op or "gte"):
543
- return False
544
- if end_op is not None or qe is not None:
545
- if not _op_ok(ce, qe, end_op or "lte"):
546
- return False
547
- return True
548
-
549
-
550
- def check_time_args(start_time=None, end_time=None, start_operator=None,
551
- end_operator=None, time_axis=None):
552
- """时间算子入参 fail-closed 校验 → `(enabled, axis, why)`。
553
-
554
- **入口(`mdcg.search` / `entity_contexts`)与库层共用的唯一校验点**
555
- (避免两处各写一套、口径漂移)。三则误用一律拒(`why` 非空即应抛
556
- `ValueError`,不静默忽略——与 `_stg_call` 同风格):
557
-
558
- 1. 只给 operator 而不给对应的 `start_time`/`end_time`;
559
- 2. `time_axis` 非 `{"effective","observed"}`(含 `"believed"`);
560
- 3. `start_time > end_time`。
561
-
562
- 未启用(五参全 `None`)→ `(False, None, "")`(默认路径零变更)。
563
- """
564
- if time_axis is not None and str(time_axis).strip().lower() not in TIME_AXES:
565
- return False, None, (f"未知 time_axis {time_axis!r}(允许:{TIME_AXES})——"
566
- "轴必须显式且合法,静默按另一条轴过滤会产出无法复算的结果")
567
- for op, val, nm in ((start_operator, start_time, "start_operator/start_time"),
568
- (end_operator, end_time, "end_operator/end_time")):
569
- if op is None:
570
- continue
571
- if str(op).strip().lower() not in TIME_OPERATORS:
572
- return False, None, (f"未知算子 {op!r}(允许:{TIME_OPERATORS})")
573
- if val is None:
574
- return False, None, f"给了 {nm.split('/')[0]} 但缺 {nm.split('/')[1]}(不猜默认值)"
575
- s, e = parse_time(start_time), parse_time(end_time)
576
- if start_time is not None and s is None:
577
- return False, None, f"start_time 不可解析:{start_time!r}"
578
- if end_time is not None and e is None:
579
- return False, None, f"end_time 不可解析:{end_time!r}"
580
- if s is not None and e is not None and s > e:
581
- return False, None, f"start_time({s}) > end_time({e}):空窗口,拒绝"
582
- enabled = any(x is not None for x in (start_time, end_time,
583
- start_operator, end_operator))
584
- if not enabled:
585
- return False, None, ""
586
- return True, time_axis_of(time_axis), ""
587
-
588
-
589
- def window_matches_node(fm, axis, q_start, q_end, start_op=None, end_op=None):
590
- """候选节点按轴取窗后做 `window_match` → `(matched, missing)`。
591
-
592
- `missing=True` 表示该节点在**该轴上不可判定**(窗口两端皆 `None`)——
593
- 调用方据此执行轴策略:效力轴 fail-open(保留)、观察轴 fail-closed
594
- (剔除并计入 `axis_missing`)。策略按**保证强度**定,不按「一致好看」定:
595
- 效力轴字段是可选声明,观察轴字段由写入侧保证存在。
596
- """
597
- cs, ce = time_window_of(fm, axis)
598
- if cs is None and ce is None:
599
- return False, True
600
- return window_match(cs, ce, q_start, q_end, start_op, end_op), False
601
-
602
-
603
- def time_filter_meta(axis=None, mode="overlap", start=None, end=None,
604
- start_operator=None, end_operator=None, dropped=0,
605
- axis_missing=0, applied=False) -> dict:
606
- """`meta["time_filter"]` 审计块(**五键齐备**,可复算):
607
-
608
- `dropped + 存活数 == 候选数` 由调用方保证;`axis_missing` 单独记账,
609
- 使「观察轴缺字段被剔除」的条数可查(静默放行会把数据异常藏起来)。
610
- """
611
- return {"axis": axis, "mode": mode, "start": start, "end": end,
612
- "start_operator": start_operator, "end_operator": end_operator,
613
- "dropped": int(dropped), "axis_missing": int(axis_missing),
614
- "applied": bool(applied)}
615
-
616
-
617
- def filter_by_time(entries, axis, q_start, q_end, start_op=None, end_op=None):
618
- """按轴过滤候选 → `(kept, dropped, axis_missing)`。**候选层唯一过滤点**。
619
-
620
- 轴策略按**字段保证强度**定(不按「行为一致好看」定):
621
- · `effective` 效力轴:`effective_from/until` 是**可选声明**(多数节点没有)
622
- → 不可判定一律 fail-open(保留)——否则「没写时效 = 被过滤掉」,
623
- 会把沉默当否认;
624
- · `observed` 观察轴:`temporal` / `time_window` 由**写入侧保证**存在
625
- (add 缺省填观测窗)→ 不可判定一律 fail-closed(剔除并计入
626
- `axis_missing`,使数据异常可查而非静默放行)。
627
- """
628
- kept, dropped, missing = [], 0, 0
629
- for e in entries:
630
- m, miss = window_matches_node(e, axis, q_start, q_end, start_op, end_op)
631
- if miss:
632
- if axis == "observed":
633
- dropped += 1
634
- missing += 1
635
- else:
636
- kept.append(e)
637
- continue
638
- if m:
639
- kept.append(e)
640
- else:
641
- dropped += 1
642
- return kept, dropped, missing
643
-
644
-
645
- # ---------------------------------------------------------------- 依赖声明
646
-
647
- def as_deps(value) -> list:
648
- """把单值 / 序列 / 逗号串统一成**去重、排序**的节点 id 列表(上限 MAX_DEPS)。
649
-
650
- 容错口径(写路径的入参形态不由本模块决定,收窄会误伤):
651
- · `None` / 空串 / 纯空白项 → 丢弃(不是目标,也不是「声明了依赖」);
652
- · 半角/全角逗号串 → 切分(`"a, b"` 与 `["a", "b"]` 等价);
653
- · 排序的动机:依赖是**集合语义**(声明顺序不承载信息),排序让 fm 与
654
- 索引快照对同一组依赖恒等——比较/去重/审计不再依赖声明顺序。
655
- """
656
- if value is None:
657
- return []
658
- items = list(value) if isinstance(value, (list, tuple, set)) else [value]
659
- out = []
660
- for x in items:
661
- if x is None:
662
- continue
663
- for s in str(x).replace(",", ",").split(","):
664
- s = s.strip()
665
- if s and s not in out:
666
- out.append(s)
667
- out.sort()
668
- return out[:MAX_DEPS]
669
-
670
-
671
- def deps_of(cg, nid: str) -> list:
672
- """读某节点声明的依赖(**零读文件**:索引快照缺失才回读节点)。"""
673
- e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid) or {}
674
- deps = as_deps(e.get(DEPS_FIELD))
675
- if deps:
676
- return deps
677
- node = cg.get(nid)
678
- if not node:
679
- return []
680
- return as_deps((node.get("frontmatter") or {}).get(DEPS_FIELD))
681
-
682
-
683
- def invalidate_cache(cg) -> None:
684
- """作废反查缓存(写/删节点后调用;下次读时增量重建)。"""
685
- try:
686
- cg.__dict__.pop("_trust_dependents", None)
687
- except Exception: # noqa: BLE001
688
- pass
689
-
690
-
691
- def dependents_index(cg, refresh: bool = False) -> dict:
692
- """反查索引:`{被依赖节点: [依赖它的节点…]}`(「谁依赖我」)。
693
-
694
- 缓存挂在 cg 实例上(与 `subgraph` 的缓存化做法同构);`refresh=True` 强制重建。
695
- """
696
- generation = getattr(cg, "_cache_generation", None)
697
- generation = generation() if callable(generation) else None
698
- if not refresh and getattr(cg, "_trust_generation", None) == generation:
699
- cached = getattr(cg, "_trust_dependents", None)
700
- if isinstance(cached, dict):
701
- return cached
702
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
703
- idx = {}
704
- for nid, e in list(nodes.items()):
705
- for p in as_deps((e or {}).get(DEPS_FIELD)):
706
- idx.setdefault(p, []).append(nid)
707
- for k in idx:
708
- idx[k].sort()
709
- try:
710
- cg._trust_dependents = idx
711
- cg._trust_generation = generation
712
- except Exception: # noqa: BLE001
713
- pass
714
- return idx
715
-
716
-
717
- def _record(cg, rec: dict) -> None:
718
- """台账追加(best-effort:失败静默,**绝不阻断写路径**)。"""
719
- try:
720
- # issue #547:本模块的审计台账(`_trust.jsonl`)此前声明「失败静默」;按 #549
721
- # 对审计账本的口径(不能丢 ⇒ durable=True)统一,丢行不再静默。
722
- append_jsonl(os.path.join(cg.root, AUDIT_FILE), rec, durable=True)
723
- except Exception: # noqa: BLE001
724
- pass
725
-
726
-
727
- # ---------------------------------------------------------------- 推进
728
-
729
- def _sync_index(cg, node_id, fm) -> None:
730
- """把验证态同步进索引快照(免读文件可查);无索引实现时静默跳过。"""
731
- idx = getattr(cg, "index", None)
732
- if not isinstance(idx, dict):
733
- return
734
- e = (idx.get("nodes") or {}).get(node_id)
735
- if e is None:
736
- return
737
- e[STATE_FIELD] = fm.get(STATE_FIELD)
738
- dirty = getattr(cg, "_dirty", None)
739
- if isinstance(dirty, dict):
740
- dirty[node_id] = e
741
- flush = getattr(cg, "flush", None)
742
- if callable(flush):
743
- flush()
744
-
745
-
746
- # 生效条件:cg.get(node_id) 为假值(节点不存在)时返回 {"ok": False, "error": "node_not_found", "node_id": node_id};否则先过层写闸 protect.require_layer(cg, node_id, layer=fm.layer, sensitivity=fm.sensitivity)(N209:越权身份抛 AccessDenied → 转成 {"ok": False, "error": "layer_denied", "changed": False} 负路由,记 set_state_denied 台账,**不写盘**),再经 stamp 裁决:code 为 noop 或非法迁移时返回 ok=False 或 changed=False 不写盘,成功时把 fm 经 cg._write_node 落盘、_sync_index 同步验证态快照、_record 追加台账,fm 含 depends_on 时再 invalidate_cache,返回 {node_id, from, to, code, ok, changed, reason, at}。
747
- def set_state(cg, node_id: str, dst: str, reason: str = None, actor: str = None,
748
- evidence: str = None, method: str = None, trigger: str = None,
749
- override: bool = False) -> dict:
750
- """推进一个节点的验证态(**唯一推进入口**)。
751
-
752
- 非法迁移不走异常而是返回 `{"ok": False, "error": <code>, ...}`(负路由)。
753
- 幂等迁移返回 `changed=False` 且不写盘。**写盘前另过 principal 层写闸**
754
- (N209:无权写该层 → `error="layer_denied"` 负路由,零写盘 + 台账留痕)。
755
- """
756
- node = cg.get(node_id)
757
- if not node:
758
- return {"ok": False, "error": "node_not_found", "node_id": node_id}
759
- fm = dict(node.get("frontmatter") or {})
760
- src = state_of(fm)
761
- # N209(同族未接线的相邻写面):验证态推进 = 对节点本体 frontmatter 的一次
762
- # **覆写**(`cg._write_node` 全量重写 fm + 正文),与 add / 覆写写面同一层闸。
763
- # 此前该路径零层闸(MdCGSecure 对 set_state/set_verification/mark_dependents
764
- # 无任何覆盖)⇒ 持 verify 令牌者经 verify→mark_dependents → 把**任意层**
765
- # 依赖者(实测 self 层)置 doubted。拒绝走**负路由**而非 raise:本函数契约是
766
- # 「非法迁移不抛异常(ok=False + 机器码)」,且 mark_dependents 契约是
767
- # 「永不抛、不阻断本次裁决」——但**绝不写盘**,并把拒绝记进 `_trust.jsonl`
768
- #(不静默:与 `mark_dependents_degraded` 同一「留痕降级」口径)。
769
- try:
770
- protect.require_layer(cg, node_id, layer=fm.get("layer"),
771
- sensitivity=fm.get("sensitivity"))
772
- except AccessDenied as exc:
773
- _record(cg, {"t": time.time(), "action": "set_state_denied",
774
- "node_id": node_id, "from": src, "to": dst,
775
- "error": f"{type(exc).__name__}: {exc}",
776
- "actor": actor, "trigger": trigger})
777
- return {"node_id": node_id, "from": src, "to": dst, "ok": False,
778
- "error": "layer_denied", "reason": str(exc), "changed": False}
779
- ok, code, why = stamp(fm, dst, reason=reason, actor=actor, evidence=evidence,
780
- method=method, trigger=trigger, override=override)
781
- base = {"node_id": node_id, "from": src, "to": dst, "code": code}
782
- if not ok:
783
- return {**base, "ok": False, "error": code, "reason": why}
784
- if code == "noop":
785
- return {**base, "ok": True, "changed": False, "reason": why}
786
- at = fm[HISTORY_FIELD][-1]["at"]
787
- cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
788
- node.get("content") or "")
789
- _sync_index(cg, node_id, fm)
790
- _record(cg, {"t": at, "action": "set_state", "node_id": node_id,
791
- "from": src, "to": dst, "reason": reason, "actor": actor,
792
- "method": method, "trigger": trigger, "override": bool(override)})
793
- if fm.get(DEPS_FIELD):
794
- invalidate_cache(cg)
795
- return {**base, "ok": True, "changed": True, "reason": why, "at": at}
796
-
797
-
798
- # ---------------------------------------------------------------- 失效传播
799
-
800
- def mark_dependents(cg, node_id: str, reason: str = None, *, apply: bool = True,
801
- actor: str = "system", trigger: str = None,
802
- depth: int = 1, override: bool = False) -> dict:
803
- """**一跳同步传播**:把直接下游标为 `doubted`(异常的新定义)。
804
-
805
- 根因口径:异常不再仅是「内容错」,而是「**它所依赖的地基动了**」——被依赖
806
- 单元被修改/证伪时,直接下游立刻产生存疑标记,无需等全库巡检。
807
-
808
- **永不抛**(对齐 provenance G8 纪律:传播失败不得阻断写入)。`apply=False`
809
- 只预演;同状态下游是 no-op(幂等,不写盘、不留痕)。
810
- """
811
- try:
812
- dep_map = dependents_index(cg)
813
- kids = list(dep_map.get(node_id, []))
814
- kids.sort()
815
- if not kids:
816
- return {"ok": True, "changed": 0, "dependents": [], "apply": bool(apply),
817
- "reason": "no_dependents"}
818
- reason = reason or f"上游 {node_id} 变动"
819
- planned = [k for k in kids
820
- if state_of((cg.index or {}).get("nodes", {}).get(k) or {})
821
- != "doubted"]
822
- if not apply:
823
- return {"ok": True, "dry_run": True, "changed": 0,
824
- "dependents": kids, "planned": len(planned)}
825
- done, skipped = [], []
826
- for k in kids:
827
- r = set_state(cg, k, "doubted", reason=reason, actor=actor,
828
- trigger=trigger or f"dep_changed:{node_id}",
829
- override=override)
830
- if r.get("ok") and r.get("changed"):
831
- done.append(k)
832
- elif r.get("ok"):
833
- skipped.append(k) # 已是 doubted:幂等
834
- else:
835
- skipped.append(f"{k}({r.get('error')})")
836
- return {"ok": True, "changed": len(done), "dependents": kids,
837
- "updated": done, "skipped": skipped, "apply": True,
838
- "reason": reason}
839
- except Exception as exc: # noqa: BLE001
840
- _record(cg, {"t": time.time(), "action": "mark_dependents_degraded",
841
- "node_id": node_id, "error": f"{type(exc).__name__}: {exc}",
842
- "actor": actor})
843
- return {"ok": False, "degraded": True, "changed": 0,
844
- "error": f"{type(exc).__name__}: {exc}"}
845
-
846
-
847
- def propagate(cg, *, apply: bool = False, max_nodes: int = MAX_NODES_DEFAULT,
848
- actor: str = "patrol") -> dict:
849
- """**多跳异步重算**(巡检面,不阻塞写入/查询)。
850
-
851
- BFS 从所有 `expired` / `rechecking` / 显式根源节点出发,把可达下游标
852
- `doubted`(**只降不升**:复核通过须由人显式 `set_state(verified)`)。
853
- 默认 `apply=False` 只出报表;`max_nodes` 封顶防大库爆炸。
854
-
855
- `doubted` 中间节点的语义(2026-09-20 v14 缺陷 B 修复):**穿过,但不重复
856
- 标记**。已 doubted 说明它已被标记,无需再标(幂等);但它**不是传播终点**
857
- ——「地基动了」的波及范围必须继续往其下游走。旧实现把 doubted 直接
858
- `continue`(当作终点),于是「先 `mark_dependents` 预演直接下游、再
859
- `propagate` 正式传播」这一最常见序列会使多跳传播**整体失效**
860
- (`reachable`/`updated` 全 0)且**无任何报错**。穿过的节点在
861
- `passed_doubted` 中如实透出(可审计)。
862
-
863
- **`reachable` / `updated` 的口径**(2026-09-20 v15-4 澄清,勿读成「波及集
864
- 大小」):两者计的是「本次**需要新标记**的节点数」——`apply=False` 时 =
865
- 计划标记数(`planned` 的长度),`apply=True` 时 = 实际标记成功数(`done` 的
866
- 长度)。**穿过的 `doubted` 中继不计入**(它早已被标记,本次幂等跳过)。故
867
- 「本次的完整波及集」= `reachable`(或 `updated`)+ `passed_doubted`,只读
868
- 前者会低估。`roots` 是传播起点(`expired`/`rechecking`),不属于波及集。
869
- """
870
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
871
- dep_map = dependents_index(cg)
872
- roots = []
873
- for nid, e in list(nodes.items()):
874
- st = (e or {}).get(STATE_FIELD)
875
- if st in ("expired", "rechecking"):
876
- roots.append(nid)
877
- roots.sort()
878
- cap = max(0, int(max_nodes))
879
- admitted_roots = roots[:cap]
880
- seen, waves, passed = set(admitted_roots), [], set()
881
- root_set = set(roots)
882
- frontier, depth = list(admitted_roots), 0
883
- truncated = len(admitted_roots) < len(roots)
884
- while frontier and len(seen) < cap:
885
- depth += 1
886
- nxt = []
887
- for nid in frontier:
888
- for k in dep_map.get(nid, []):
889
- if k in seen or k in root_set:
890
- continue
891
- # The cap applies across the whole wave, not once per parent.
892
- if len(seen) >= cap:
893
- truncated = True
894
- break
895
- seen.add(k)
896
- if state_of(nodes.get(k) or {}) == "doubted":
897
- passed.add(k) # 穿过但不重复标记(不是终点)
898
- nxt.append(k)
899
- if truncated:
900
- break
901
- for k in nxt:
902
- if k in passed:
903
- continue # 已 doubted:无需再标(幂等)
904
- waves.append({"node_id": k, "depth": depth,
905
- # Incoming dependencies are already on this entry.
906
- # Scanning every parent's child list per result was
907
- # quadratic even for a sparse star/chain graph.
908
- "via": sorted(n for n in as_deps((nodes.get(k) or {}).get(DEPS_FIELD))
909
- if n in seen)})
910
- if truncated:
911
- break
912
- frontier = nxt
913
- if frontier and len(seen) >= cap and not truncated:
914
- truncated = any(k not in seen and k not in root_set
915
- for nid in frontier for k in dep_map.get(nid, ()))
916
- bounds = {"visited": len(seen), "truncated": truncated,
917
- "roots_admitted": len(admitted_roots)}
918
- if not apply:
919
- return {"ok": True, "dry_run": True, "roots": roots[:50],
920
- "roots_count": len(roots), "reachable": len(waves),
921
- "planned": waves[:50], "passed_doubted": sorted(passed)[:20],
922
- "max_nodes": cap, **bounds,
923
- "note": "预演:未改盘;只降不升(复核须显式)"}
924
- done, skipped = [], []
925
- for w in waves:
926
- r = set_state(cg, w["node_id"], "doubted",
927
- reason="多跳失效传播(上游时间轴/证据失效)",
928
- actor=actor, trigger=f"propagate:d{w['depth']}")
929
- if r.get("ok") and r.get("changed"):
930
- done.append(w["node_id"])
931
- elif not r.get("ok"):
932
- skipped.append(f"{w['node_id']}({r.get('error')})")
933
- return {"ok": True, "dry_run": False, "roots": roots[:50],
934
- "roots_count": len(roots), "updated": done, "updated_count": len(done),
935
- "passed_doubted": sorted(passed)[:20],
936
- "skipped": skipped[:20], "max_nodes": cap, **bounds}
937
-
938
-
939
- # ---------------------------------------------------------------- 巡检 / 回填
940
-
941
- # 生效条件:cg 传入即只读遍历 index 快照并返回悬空/未生效/已过期/存疑四类计数与样本,不写盘、不改状态、不抛(index 缺失按空库处理);
942
- def patrol(cg, *, limit: int = 20, now: float = None) -> dict:
943
- """只读巡检:悬空依赖 / 时间轴失效 / 存疑积压。**不改状态、不删节点**。
944
-
945
- 命名纪律(负记忆,2026-09-19 实测):本函数**不得叫 `check`**——裁决层已有
946
- `check(src, dst, ...)`(唯一裁决点)。同模块内同名二次定义会**静默遮蔽**前者,
947
- `stamp()` 随即调到巡检版并抛 `TypeError`(现场:`set_verification` 整条链断)。
948
- 两者语义分属不同层次(纯函数裁决 vs 全库只读巡检),名字必须分开。
949
- """
950
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
951
- known = set(nodes)
952
- dangling, expired, not_yet, doubted = [], [], [], []
953
- for nid, e in sorted(nodes.items()):
954
- for p in as_deps((e or {}).get(DEPS_FIELD)):
955
- if p not in known:
956
- dangling.append({"node_id": nid, "missing": p})
957
- st = (e or {}).get(STATE_FIELD)
958
- if st == "doubted":
959
- doubted.append(nid)
960
- # 时间轴按索引可判定字段粗判(精确判定需 fm,巡检读面只给候选)
961
- kind = _index_validity(e, now=now)
962
- if kind == "expired":
963
- expired.append(nid)
964
- elif kind == "not_yet":
965
- not_yet.append(nid)
966
- return {
967
- "ok": not dangling,
968
- "checked": True, "root": cg.root, "nodes": len(known),
969
- "dangling": dangling[:int(limit)], "dangling_count": len(dangling),
970
- "expired": expired[:int(limit)], "expired_count": len(expired),
971
- "not_yet": not_yet[:int(limit)], "not_yet_count": len(not_yet),
972
- "doubted": doubted[:int(limit)], "doubted_count": len(doubted),
973
- "readonly": True,
974
- "note": "只读巡检:悬空依赖/时效仅检出并报告,不自动改状态(处置由人/巡检动作发起)"}
975
-
976
-
977
- def _index_validity(e, now: float = None) -> str:
978
- """索引快照口径的时效粗判(索引缺时间字段时返回 unknown,零读文件)。"""
979
- if not isinstance(e, dict):
980
- return "unknown"
981
- return validity(e, now=now)[0]
982
-
983
-
984
- def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
985
- """存量回填:把缺 `verification_state` 的节点显式补成 `unverified`(幂等)。
986
-
987
- 缺字段本就按 unverified 解释(`state_of`),故回填**不是让功能工作的前提**,
988
- 而是把「缺省」变成「显式」——索引/审计里从此可直接读到验证态。默认只盘点。
989
- """
990
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
991
- missing = []
992
- for nid, e in list(nodes.items()):
993
- if len(missing) >= limit:
994
- break
995
- if (e or {}).get(STATE_FIELD) in STATES:
996
- continue
997
- missing.append(nid)
998
- missing.sort()
999
- if not apply:
1000
- return {"ok": True, "dry_run": True, "scanned": len(nodes),
1001
- "missing": len(missing), "planned": missing[:50]}
1002
- done, failed = [], []
1003
- for nid in missing:
1004
- node = cg.get(nid)
1005
- if not node:
1006
- failed.append(nid)
1007
- continue
1008
- fm = dict(node.get("frontmatter") or {})
1009
- fm[STATE_FIELD] = state_of(fm)
1010
- cg._write_node(nid, os.path.join(cg.root, node["path"]), fm,
1011
- node.get("content") or "")
1012
- _sync_index(cg, nid, fm)
1013
- done.append(nid)
1014
- return {"ok": True, "dry_run": False, "scanned": len(nodes),
1015
- "missing": len(missing), "backfilled": len(done),
1016
- "planned": done[:50], "failed": failed[:20]}
1017
-
1018
-
1019
- def describe(cg, node_id: str, now: float = None) -> dict:
1020
- """单节点验证态全貌(供 op=status / 状态头渲染)。只读、失败不抛。
1021
-
1022
- N205(2026-09-28):`cg.get` 被读闸拒后**不得**回落索引条目仍报 ok=True——
1023
- 索引条目本身就是密级/会话/验证态元数据(layer/tags/session/verification_state),
1024
- 回落等于把「不可读」当「可见」返回(实测:guest 对 private 节点 get→None,
1025
- 而 status 仍回 ok=True + verification_state='verified' + depends_on +
1026
- 状态头「✓ 已验证」)。口径改为与 get/search/recall 一致的「不可见即不存在」:
1027
- 判定走跨层单点 `security.node_visible`(纯 MdCGOS 无身份模型 → 不受影响;
1028
- 设计者 can_admin 豁免不变)。
1029
- """
1030
- try:
1031
- node = cg.get(node_id)
1032
- except Exception: # noqa: BLE001
1033
- node = None
1034
- e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
1035
- if not node and not e:
1036
- return {"ok": False, "error": "node_not_found", "node_id": node_id}
1037
- if not node and not _security.node_visible(cg, node_id):
1038
- return {"ok": False, "error": "node_not_found", "node_id": node_id}
1039
- fm = (node or {}).get("frontmatter") or {}
1040
- deps = as_deps(fm.get(DEPS_FIELD)) or as_deps((e or {}).get(DEPS_FIELD))
1041
- kind, start, end = validity(fm if fm else (e or {}), now=now)
1042
- dep_map = dependents_index(cg)
1043
- hist = list(fm.get(HISTORY_FIELD) or [])[-5:]
1044
- return {"ok": True, "node_id": node_id,
1045
- "verification_state": state_of(fm if fm else (e or {})),
1046
- "verification_basis": fm.get("verification_basis"),
1047
- "verification_method": fm.get("verification_method"),
1048
- "verified_at": fm.get("verified_at"),
1049
- "depends_on": deps,
1050
- "depended_by": dep_map.get(node_id, []),
1051
- "validity": {"kind": kind, "valid_from": fm.get(FROM_FIELD),
1052
- "valid_until": fm.get(UNTIL_FIELD),
1053
- "start": start, "end": end},
1054
- "history": hist,
1055
- "lifecycle_state": fm.get("lifecycle_state"),
1056
- "protected": bool(fm.get("protected") or fm.get("immutable"))}
1057
-
1058
-
1059
- def summary(cg) -> dict:
1060
- """轻量摘要(只读;失败不抛,避免拖垮 health / 常驻循环)。"""
1061
- try:
1062
- rep = patrol(cg, limit=3)
1063
- return {"dangling": rep["dangling_count"], "expired": rep["expired_count"],
1064
- "not_yet": rep["not_yet_count"], "doubted": rep["doubted_count"],
1065
- "nodes": rep["nodes"], "sample": [
1066
- f"{r['node_id']}->?{r['missing']}" for r in rep["dangling"]]}
1067
- except Exception: # noqa: BLE001
1068
- return {}
1069
-
1070
-
1071
- def load_ledger(cg, *, node_id: str = None, limit: int = None) -> list:
1072
- """读验证态台账(跳过坏行;可按节点过滤)。
1073
-
1074
- N205(2026-09-28):行内 `reason` 含**明文证据串**(外部裁决理由),此前
1075
- 只按 node_id 等值过滤、零可见性判定 ⇒ 任何持 read op 的身份(含无令牌
1076
- guest,`cg(op="status", action="ledger")` 在 guest 的 ops_allow 内)可读走
1077
- 他人私密节点的裁决证据与验证态。口径与库读面统一:逐行按
1078
- `security.node_visible`(跨层单点)判定行所属节点对本身份是否可见,
1079
- 不可见/不可证(已 forget、索引无条目)→ 该行整条不出;设计者豁免。
1080
- """
1081
- path = os.path.join(cg.root, AUDIT_FILE)
1082
- out = []
1083
- for r in read_jsonl(path):
1084
- if not isinstance(r, dict):
1085
- continue
1086
- if node_id and r.get("node_id") != node_id:
1087
- continue
1088
- if not _security.node_visible(cg, r.get("node_id")):
1089
- continue
1090
- out.append(r)
1091
- return out[:int(limit)] if limit else out
1092
-
1093
-
1094
- def catalog(root: str = None) -> dict:
1095
- """自描述(供 MCP catalog / 人工核对)。"""
1096
- return {
1097
- "layer": "可验证记忆单元",
1098
- "question": "它还成不成立(验证态 + 依赖 + 时效)",
1099
- "ledger": os.path.join(root, AUDIT_FILE) if root else AUDIT_FILE,
1100
- "states": list(STATES),
1101
- "state_field": STATE_FIELD,
1102
- "history_field": HISTORY_FIELD,
1103
- "deps_field": DEPS_FIELD,
1104
- "time_fields": [FROM_FIELD, UNTIL_FIELD],
1105
- "transitions": sorted(f"{a}→{b}" for a, b in TRANSITIONS),
1106
- "max_deps": MAX_DEPS,
1107
- "max_nodes_default": MAX_NODES_DEFAULT,
1108
- "discipline": {"never_block_write": True, "no_backfill": True,
1109
- "patrol_readonly": True, "one_hop_sync": True,
1110
- "multi_hop_async": True, "only_downgrade": True},
1111
- "distinct_from": ("lifecycle.py = 节点生命周期(lifecycle_state);"
1112
- "provenance.py = 派生血缘(_link.jsonl);"
1113
- "本层 = 验证态与依赖(verification_state/_trust.jsonl)"),
1114
- }
1
+ # -*- coding: utf-8 -*-
2
+ """md_cg · 可验证记忆单元(验证态状态机 + 依赖图 + 双时间轴)
3
+
4
+ 把「可信度」从散文式描述,变成**显式、可查询、可传播、可输出**的结构化状态。
5
+ 三件事:
6
+
7
+ 1. **验证态持续化**——`verification_state` ∈ (unverified / verified /
8
+ expired / doubted / rechecking),随验证动作与依赖变动**流转**,不是一次性
9
+ 布尔开关;状态落 `frontmatter.verification_state`(节点 md 是唯一真源),
10
+ 索引快照同名透出(免读文件可查)。
11
+ 2. **依赖声明与失效传播**——单元显式声明它依赖谁(`depends_on`);被依赖单元
12
+ 被修改/证伪时,**直接下游立即同步标为 doubted**(一跳,低成本);**多跳**
13
+ 交由 `propagate()` 后台巡检重算,不阻塞写入与查询。
14
+ 3. **双时间轴**——既有「何时不再成立」(`valid_until`)之外补「何时开始成立」
15
+ (`valid_from`),使时效区间可判定:未生效 / 生效中 / 已过期。
16
+
17
+ 与 `lifecycle.py` 刻意分层(同构实现、**正交语义**,禁跨套复用常量):
18
+ · `lifecycle.py` = 节点**生命周期**(active/converged/demoted/archived);
19
+ · 本模块 = 节点**验证态**(unverified/verified/expired/doubted/rechecking)。
20
+ 两者都是「单点裁决 + 单点推进 + 硬拒入口」,但状态集不共享、`_RANK` 不共享。
21
+
22
+ 与 `provenance.py` 刻意分层:
23
+ · `provenance.py` = 节点**派生血缘**(「它由谁派生」,`_link.jsonl`);
24
+ · 本模块 = 节点**依赖与证据强度**(「它靠谁成立、现在还成不成立」,
25
+ `_trust.jsonl`)。血缘是既成事实,依赖是可失效假设——不可混用。
26
+
27
+ 三条纪律(对齐 G8 裁定与 lifecycle 口径):
28
+ 1. **台账失败降级不阻断写**——`mark_dependents()` 永不抛,写不进只留痕告警;
29
+ 2. **历史不回填**——存量缺 `verification_state` 视为 `unverified`,`backfill()`
30
+ 只在显式调用时把「缺省」变「显式」;
31
+ 3. **巡检只读**——`patrol()` 检出悬空依赖/过期节点但**不自动改状态、不删节点**。
32
+
33
+ 命名避让(既有先例):字段**不叫 `state`**——该名已被裁决四态
34
+ (ACCEPT/REJECT/DEFER/BLINDSPOT)占用,`lifecycle_state` 的先例同此动机。
35
+
36
+ 零第三方依赖(D-005)。
37
+ """
38
+ from __future__ import annotations
39
+
40
+ import os
41
+ import time
42
+ import math
43
+ from datetime import datetime
44
+
45
+ from . import protect
46
+ from . import security as _security
47
+ from .fsutil import append_jsonl, read_jsonl
48
+ from .security import AccessDenied
49
+
50
+ #: 验证态全集。语义:
51
+ #: unverified 未验证(默认;存量缺字段即视为它)
52
+ #: verified 已验证(有验证方式与证据,且依赖未动)
53
+ #: doubted 存疑(**依赖的地基动了**——异常的新定义)
54
+ #: rechecking 重新验证中(复核进行态)
55
+ #: expired 已过期(超出时效区间,或证据整体失效)
56
+ STATES = ("unverified", "verified", "doubted", "rechecking", "expired")
57
+
58
+ #: frontmatter 字段名(索引快照同名透出)。刻意避开 `state`——与 lifecycle 同动机。
59
+ STATE_FIELD = "verification_state"
60
+ #: 验证履历字段(frontmatter 侧历史,滚动保留最近 HISTORY_KEEP 条)
61
+ HISTORY_FIELD = "verification_history"
62
+ HISTORY_KEEP = 20
63
+ #: 依赖声明字段(CCG「子功能」槽的落字段)
64
+ DEPS_FIELD = "depends_on"
65
+ #: 双时间轴(**效力时间**)字段。2026-09-19 阶段一:规范名迁移到
66
+ #: `effective_from` / `effective_until`(**新写入落规范键**),历史名
67
+ #: `valid_from` / `valid_until` 保留为**读取侧回落别名**(存量不迁移、零破坏)。
68
+ FROM_FIELD = "valid_from"
69
+ UNTIL_FIELD = "valid_until"
70
+ #: 规范名(新写入落此;读取时优先于同名族旧键)
71
+ EFFECTIVE_FROM_FIELD = "effective_from"
72
+ EFFECTIVE_UNTIL_FIELD = "effective_until"
73
+ #: 信念时间(体系**何时确认此条**):取代/审核的锚。
74
+ #: **不是效力语义**——它既不是「已结束」也不是「尚未开始」,
75
+ #: 故绝不并入 `scrub._EXPIRY_KEYS`(已结束族)或 `scrub._NOT_YET_KEYS`(未生效族)。
76
+ BELIEVED_FIELD = "believed_at"
77
+ #: 过期时刻(写盘冗余:由 `effective_until` 派生落盘,供审计/对账直读)。
78
+ EXPIRED_FIELD = "expired_at"
79
+
80
+ #: 端点取值优先级(**规范键优先、别名回落**,2026-09-19 阶段一)。
81
+ #: 与 `scrub._NOT_YET_KEYS` / `scrub._EXPIRY_KEYS` 同键族——两处共用同一套别名,
82
+ #: 任一侧新增键须同步另一侧(交叉守卫测试 test_validity_filter 守住)。
83
+ FROM_ALIASES = (EFFECTIVE_FROM_FIELD, FROM_FIELD, "valid_since", "starts_at")
84
+ UNTIL_ALIASES = (EFFECTIVE_UNTIL_FIELD, UNTIL_FIELD,
85
+ "expires_at", "expire_at", "expiry", "deadline")
86
+ #: 验证态迁移审计(append-only,与 _lifecycle.jsonl / _maintain.jsonl 同风格)
87
+ AUDIT_FILE = "_trust.jsonl"
88
+
89
+ #: 降级序位(用于「受保护豁免降级」判定)。verified 最高,doubted/expired 更低。
90
+ _RANK = {"verified": 0, "rechecking": 1, "unverified": 1, "doubted": 2, "expired": 3}
91
+
92
+ #: 合法迁移表。刻意不收录的(即拒绝的):
93
+ #: verified → unverified(回落未验证:证据已存在,只应「存疑」而非「清零」)
94
+ #: doubted → expired(跳级:存疑未经复核不得直接判过期)
95
+ #: 注:`unverified → doubted` **收录**——两条路都真实到达这里:①上游变动波及一个
96
+ #: 从未验证过的下游(「地基动了」对未验证者同样成立);②未验证节点收到**负证据**
97
+ #: (证据削弱本身就是存疑的依据,比停在「未验证」更准确)。
98
+ TRANSITIONS = frozenset({
99
+ ("unverified", "verified"),
100
+ ("unverified", "doubted"),
101
+ ("unverified", "rechecking"),
102
+ ("unverified", "expired"),
103
+ ("verified", "doubted"),
104
+ ("verified", "rechecking"),
105
+ ("verified", "expired"),
106
+ ("doubted", "rechecking"),
107
+ ("doubted", "verified"),
108
+ ("rechecking", "verified"),
109
+ ("rechecking", "doubted"),
110
+ ("rechecking", "unverified"),
111
+ ("rechecking", "expired"),
112
+ ("expired", "rechecking"),
113
+ ("expired", "verified"),
114
+ })
115
+
116
+ #: 依赖边上限(单节点直接下游数);超出即拒收,防「依赖声明写成噪声」。
117
+ MAX_DEPS = 32
118
+ #: 多跳传播的节点上限(对齐 subgraph.MAX_NODES_DEFAULT 的量级)
119
+ MAX_NODES_DEFAULT = 500
120
+
121
+
122
+ class TrustError(Exception):
123
+ """非法验证态迁移 / 依赖声明非法(写路径用 `require_transition` 直接抛)。"""
124
+
125
+ def __init__(self, src, dst, code, reason):
126
+ super().__init__(f"非法验证态迁移 {src}→{dst}({code}):{reason}")
127
+ self.src, self.dst, self.code, self.reason = src, dst, code, reason
128
+
129
+
130
+ # ---------------------------------------------------------------- 纯函数裁决
131
+
132
+ def state_of(fm) -> str:
133
+ """frontmatter → 验证态;缺字段或未知值 → "unverified"(存量兼容,不猜测)。"""
134
+ if not isinstance(fm, dict):
135
+ return "unverified"
136
+ s = fm.get(STATE_FIELD)
137
+ return s if s in STATES else "unverified"
138
+
139
+
140
+ def is_downgrade(src: str, dst: str) -> bool:
141
+ """是否向「更低可信度」迁移(verified < unverified/rechecking < doubted < expired)。"""
142
+ return _RANK.get(dst, 0) > _RANK.get(src, 0)
143
+
144
+
145
+ def can_transition(src, dst) -> bool:
146
+ """迁移是否合法(含幂等;未知 src 按 unverified 处理)。"""
147
+ src = src if src in STATES else "unverified"
148
+ if dst not in STATES:
149
+ return False
150
+ if src == dst:
151
+ return True # 幂等:同状态是 no-op
152
+ return (src, dst) in TRANSITIONS
153
+
154
+
155
+ def check(src, dst, protected: bool = False, override: bool = False):
156
+ """迁移合法性裁决 → `(ok, code, reason)`。**唯一裁决点**(纯函数,无 IO)。
157
+
158
+ code 取值:`ok` / `noop`(同状态,不写盘)/ `unknown_state` /
159
+ `illegal_transition` / `protected`。
160
+ """
161
+ src = src if src in STATES else "unverified"
162
+ if dst not in STATES:
163
+ return False, "unknown_state", f"未知验证态 {dst!r}(允许:{STATES})"
164
+ if src == dst:
165
+ return True, "noop", "验证态未变(幂等,不写盘)"
166
+ if (src, dst) not in TRANSITIONS:
167
+ legal = "、".join(f"{a}→{b}" for a, b in sorted(TRANSITIONS))
168
+ return False, "illegal_transition", (
169
+ f"{src}→{dst} 不在合法迁移表内(允许:{legal})——"
170
+ "验证态只沿「验证/存疑/复核/过期」四条路径流转,跨级迁移一律拒绝")
171
+ if is_downgrade(src, dst) and protected and not override:
172
+ return False, "protected", (
173
+ f"受保护节点不接受降级迁移 {src}→{dst}(保护 = 不可轻弃);"
174
+ "确需降级请显式 override=True")
175
+ return True, "ok", f"{src}→{dst} 合法"
176
+
177
+
178
+ def require_transition(src, dst, protected: bool = False, override: bool = False):
179
+ """合法则返回 code,非法则抛 `TrustError`(写路径的硬拒入口)。"""
180
+ ok, code, why = check(src, dst, protected=protected, override=override)
181
+ if not ok:
182
+ raise TrustError(src if src in STATES else "unverified", dst, code, why)
183
+ return code
184
+
185
+
186
+ #: 裸 frontmatter 探针的假 node_id(`protect.is_protected` 的 `(cg, node_id)` 形态所需;
187
+ #: 真实节点 id 来自文件名/显式声明,不含 NUL ⇒ 与既有索引键不可能相撞)。
188
+ _FM_PROBE_ID = "\x00fm-probe"
189
+
190
+
191
+ class _FmProbe:
192
+ """裸 frontmatter → `protect.is_protected` 所需的 `(cg, node_id)` 形态(**零规则载体**)。
193
+
194
+ #377(2026-10-14):本模块的降级判据此前只读 `fm["protected"]` / `fm["immutable"]`
195
+ 两位,漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**。
196
+ 本类**不复制任何判据**——规则单点仍是 `protect.is_protected`——只把调用方手里
197
+ 已有的 frontmatter 摆成该判据所需的索引快照形态(唯一索引条目=该映射本身)。
198
+ 刻意**不提供** `_maybe_reload_index`(`protect._fm` 的探活分支取不到即跳过)且
199
+ `get()` 恒返回 None(门控字段回退读文件的分支在此无文件可读、**不抛异常**)⇒
200
+ 判定 100% 基于传入映射:零 IO、零副作用(`stamp` 是就地改 fm 的纯函数面)。
201
+ """
202
+
203
+ __slots__ = ("index",)
204
+
205
+ def __init__(self, fm):
206
+ self.index = {"nodes": {_FM_PROBE_ID: fm if isinstance(fm, dict) else {}}}
207
+
208
+ def get(self, node_id=None): # protect._fm 的回退分支:探针无文件可读
209
+ return None
210
+
211
+
212
+ def _is_protected_fm(fm) -> tuple:
213
+ """裸 frontmatter 的「不可遗忘」判定 → `(是否受保护, 原因)`。
214
+
215
+ 判据单点=**`protect.is_protected`**(层保护 self/anchor ∪ 显式 protected 位 ∪
216
+ 按分保护 ≥0.70 且来源缺省/hint);本函数只负责把它喂给判据,不自带任何规则。
217
+ """
218
+ return protect.is_protected_entry(fm) # #431 批:_FmProbe 副本收口到条目口径单点
219
+
220
+
221
+ def stamp(fm: dict, dst: str, reason: str = None, actor: str = None,
222
+ evidence: str = None, method: str = None, trigger: str = None,
223
+ override: bool = False):
224
+ """在给定 frontmatter 上**就地**推进验证态(无 IO)→ `(ok, code, why)`。
225
+
226
+ 与 `set_state()` 共用同一裁决点(`check`),供**需与其他字段同批落盘**的
227
+ 收口点使用(写入时一次写盘改依赖/时间轴/验证态)。
228
+ """
229
+ src = state_of(fm)
230
+ # #377(2026-10-14):原判据只读 fm 的**显式两位**(protected / immutable),
231
+ # 漏了 `protect.is_protected` 的**层保护**(layer ∈ {self, anchor})与**按分保护**
232
+ # ——anchor/self 层节点可被无痕降级。改为「显式两位 ∪ is_protected」:
233
+ # **超集**,原判据一字不减(immutable 位照旧、override=True 照旧短路到 check 的
234
+ # override 分支)⇒ 既有判定与 override 通路逐位不变;判据本体仍是 protect 的单点,
235
+ # 不在本模块复制一份。
236
+ prot = bool(fm.get("protected") or fm.get("immutable")) \
237
+ or _is_protected_fm(fm)[0]
238
+ ok, code, why = check(src, dst, protected=prot, override=override)
239
+ if not ok or code == "noop":
240
+ return ok, code, why
241
+ fm[STATE_FIELD] = dst
242
+ rec = {"at": time.time(), "from": src, "to": dst, "reason": reason,
243
+ "actor": actor, "trigger": trigger}
244
+ if method:
245
+ rec["method"] = str(method)[:120]
246
+ if evidence:
247
+ rec["evidence"] = str(evidence)[:300]
248
+ hist = list(fm.get(HISTORY_FIELD) or [])
249
+ hist.append(rec)
250
+ fm[HISTORY_FIELD] = hist[-HISTORY_KEEP:]
251
+ if method:
252
+ fm["verification_method"] = str(method)[:120]
253
+ if evidence:
254
+ fm["verification_evidence"] = str(evidence)[:300]
255
+ fm["verified_at"] = rec["at"]
256
+ return True, code, why
257
+
258
+
259
+ # ---------------------------------------------------------------- 双时间轴
260
+
261
+ #: 单位归一判据:epoch **秒**到公元 5138 年仍 < 1e11,而 epoch **毫秒**自 1973-03
262
+ #: 起已 > 1e11 —— 量级差 3 个数量级,故「>= 1e11」判为毫秒。
263
+ #: 受保护的既有值:全时窗哨兵 `9999999999.0`(nodefile.FULL_TIME_WINDOW_MAX)
264
+ #: 与秒级 `created_at` 一律**不受影响**(test_trust 的「数字直通」断言同此)。
265
+ _MS_EPOCH_THRESHOLD = 1e11
266
+
267
+
268
+ def epoch_seconds(value, *, _allow_nonfinite=False):
269
+ """时间**数值** → epoch 秒(单位归一的**唯一实现点**);非数值 → None。
270
+
271
+ 为什么需要它(issue #23 根因):图内规范单位是**秒**——`created_at`、
272
+ `mdcg._write` 的默认观测窗、全时窗哨兵、`parse_time` 全是秒;但摄取链
273
+ (`sources.DSHSessionSource` / `JsonlSource`)历史上产出**毫秒**。毫秒值一旦
274
+ 进入 `condition_space.time_window`,`stg(op=timeline)` 的倒序排序被 1e3 倍放大
275
+ 顶到最前,摄取节点**永久占据头部**(auto-recall 取到的「最新 N 条」全是它们);
276
+ 同一根因还让 S2 时间门控把秒节点的区间判成不相交而误剔除。
277
+
278
+ 口径(不猜测):有限数值 `>= _MS_EPOCH_THRESHOLD` → `/1000.0`;其余原样 float。
279
+ NaN / Infinity / 超出 float 范围的数值返回 None,不得遮蔽合法别名。
280
+ 于是「已落库的历史毫秒数据」**无需改盘**即可参与排序与区间比较
281
+ (读取侧归一,零迁移)。
282
+
283
+ 不适用条件:日期/日期时间**字符串**(走 `parse_time`);`spatial.bbox` 等
284
+ 非时间的数值;全时窗哨兵判定(`nodefile.is_full_time_window` 按「两侧极值
285
+ 恰好覆盖」判,不做单位换算)。
286
+ """
287
+ if not isinstance(value, (int, float)):
288
+ return None
289
+ try:
290
+ v = float(value)
291
+ except (ValueError, OverflowError):
292
+ return None
293
+ if not _allow_nonfinite and not math.isfinite(v):
294
+ return None
295
+ return v / 1000.0 if v >= _MS_EPOCH_THRESHOLD else v
296
+
297
+
298
+ def parse_time(value, *, _allow_nonfinite=False):
299
+ """时间值 → epoch 秒;不可解析返回 None(**不猜测**)。
300
+
301
+ 接受:数字(epoch 秒;**毫秒自动归一**,见 `epoch_seconds`)/ 数字串
302
+ (同左)/ 日期或日期时间字符串(ISO 8601,宽松:空格分隔、`Z` 后缀、
303
+ 日期精度都容忍)。显式 Z / UTC offset 按绝对时刻解析;无时区日期保留
304
+ 既有本地时间语义。纯标准库实现。
305
+
306
+ 单位归一单点落在此处:它是全系统时间数值的**唯一读入口**
307
+ (时间算子 / `validity` / `provenance` 边 / 效力轴端点 / `stg._interval`),
308
+ 故历史毫秒数据在**所有**读取面上一次生效,不再逐调用点打补丁。
309
+ """
310
+ if value is None or value == "":
311
+ return None
312
+ if isinstance(value, (int, float)):
313
+ return epoch_seconds(value, _allow_nonfinite=_allow_nonfinite)
314
+ s = str(value).strip()
315
+ if not s:
316
+ return None
317
+ try:
318
+ return epoch_seconds(float(s), _allow_nonfinite=_allow_nonfinite)
319
+ except ValueError:
320
+ pass
321
+ # Explicit offsets denote an instant, independent of the host timezone.
322
+ # Naive dates below deliberately retain the existing local-time contract.
323
+ t = s.replace("/", "-")
324
+ try:
325
+ aware = datetime.fromisoformat(t)
326
+ if aware.tzinfo is not None:
327
+ ts = aware.timestamp()
328
+ return ts if math.isfinite(ts) else None
329
+ except (ValueError, OverflowError, OSError):
330
+ pass
331
+ t = t.replace("T", " ")
332
+ fmts = ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d")
333
+ for f in fmts:
334
+ try:
335
+ return time.mktime(time.strptime(t, f))
336
+ except ValueError:
337
+ continue
338
+ return None
339
+
340
+
341
+ def first_endpoint(fm, keys):
342
+ """按 `keys` 优先级取首个**可解析**端点 → `(epoch, key)`;全链无值 → `(None, None)`。
343
+
344
+ 单点定义「规范键优先、别名回落」的取值口径:某键**存在但不可解析**时继续回落
345
+ (而非按 None 定案)——「写坏了的时间值」不得遮蔽同族另一个合法键。
346
+ """
347
+ if not isinstance(fm, dict):
348
+ return None, None
349
+ for k in keys:
350
+ if k in fm:
351
+ ts = parse_time(fm.get(k))
352
+ if ts is not None:
353
+ return ts, k
354
+ return None, None
355
+
356
+
357
+ def validity(fm, now: float = None):
358
+ """双时间轴判定 → `(kind, start, end)`。
359
+
360
+ kind ∈ `unknown`(无时间轴约束)/ `not_yet`(未生效)/ `active`(生效中)/
361
+ `expired`(已过期)。任一端点不可解析 → 该端点按 None 处理(不猜测、不误判)。
362
+
363
+ 端点取值(2026-09-19 阶段一):**规范键优先、别名回落**——
364
+ 起点 `effective_from` > `valid_from` > `valid_since` > `starts_at`;
365
+ 终点 `effective_until` > `valid_until` > `expires_at` > `expire_at` > `expiry` > `deadline`。
366
+ `believed_at`(信念时间)**不参与**本判定:它是「体系何时确认此条」(取代/审核的锚),
367
+ 不是效力端点——并入任一方向都会把「已确认」误判成「已生效/已失效」。
368
+ """
369
+ if not isinstance(fm, dict):
370
+ return "unknown", None, None
371
+ start, _sk = first_endpoint(fm, FROM_ALIASES)
372
+ end, _ek = first_endpoint(fm, UNTIL_ALIASES)
373
+ if start is None and end is None:
374
+ return "unknown", None, None
375
+ t = time.time() if now is None else float(now)
376
+ if start is not None and t < start:
377
+ return "not_yet", start, end
378
+ if end is not None and t > end:
379
+ return "expired", start, end
380
+ return "active", start, end
381
+
382
+
383
+ def believed_at(fm) -> float:
384
+ """信念时间(体系**何时确认此条**)→ epoch 秒;缺字段/不可解析 → None(不猜测)。
385
+
386
+ 用途:取代(supersede)/ 审核的排序锚——「谁更晚被确认」是判定新旧的正路;
387
+ **不得**拿 `valid_from`/`valid_until` 代替(那是事实在任务世界里何时有效,
388
+ 与体系何时知道它无关)。
389
+ """
390
+ if not isinstance(fm, dict):
391
+ return None
392
+ return parse_time(fm.get(BELIEVED_FIELD))
393
+
394
+
395
+ def is_expired(fm, now: float = None) -> bool:
396
+ """`validity` 的布尔快捷:是否「**已过期**」。
397
+
398
+ 只判 `expired`——`not_yet`(尚未生效)**不算**:两者语义相反
399
+ (见 `scrub._NOT_YET_KEYS` 纪律「`valid_from` 绝不并入 `_EXPIRY_KEYS`」),
400
+ 「尚未开始」不等于「已失效」。无时间轴 / 端点不可解析 → False(不猜测、不误杀)。
401
+ """
402
+ return validity(fm, now=now)[0] == "expired"
403
+
404
+
405
+ def time_window_msg(fm, now: float = None) -> str:
406
+ """时效判定的一句话(空串表示无时间轴约束)。**点名实际命中的键**(含别名)。"""
407
+ kind, start, end = validity(fm, now=now)
408
+ if kind == "unknown":
409
+ return ""
410
+ if kind == "not_yet":
411
+ _ts, k = first_endpoint(fm, FROM_ALIASES)
412
+ return f"未生效({k or FROM_FIELD} 未到)"
413
+ if kind == "expired":
414
+ _ts, k = first_endpoint(fm, UNTIL_ALIASES)
415
+ return f"已过期({k or UNTIL_FIELD} 已过)"
416
+ return "时效内"
417
+
418
+
419
+ # ---------------------------------------------------------------- 时间算子(阶段二 4.1)
420
+
421
+ #: 时间轴(**封闭枚举**)。两条轴物理隔离、语义不可互换(同 `believed_at` 的隔离纪律):
422
+ #: effective 效力轴——这条事实**何时开始/不再成立**(`effective_from/until` 及别名)
423
+ #: observed 观察轴——这条记忆**何时被观测/事件何时发生**(`temporal` / `time_window`)
424
+ #: 不设**隐式**默认轴:入口在「启用时间算子但未指定轴」时回落 `effective`
425
+ #: (与既有 `validity=` 语义连续),但轴本身永远由调用方显式决定。
426
+ TIME_AXES = ("effective", "observed")
427
+
428
+ #: 时间算子(**封闭枚举**,拒收未知名):候选轴端点 与 查询端点 的比较关系。
429
+ #: 缺省(不给 operator)= **区间重叠**语义,见 `window_match`。
430
+ TIME_OPERATORS = ("gt", "gte", "eq", "lte", "lt")
431
+
432
+ #: 观察轴字段名(与 `stg._interval` 同源口径,**不新增第二套解析**)。
433
+ OBSERVED_TIME_FIELD = "temporal"
434
+ OBSERVED_WINDOW_FIELD = "time_window"
435
+
436
+
437
+ def time_axis_of(axis) -> str:
438
+ """轴名归一 → `"effective"` / `"observed"`;`None` → `"effective"`;
439
+ 其余(含 `"believed"`)→ `ValueError`(**fail-closed,不静默降级**)。
440
+
441
+ 与 `_stg_call`「不做签名推导——猜错会静默返回错误视图,比报错更贵」同风格:
442
+ 轴写错时必须报错,因为静默按另一条轴过滤会产出**无法复算**的结果集。
443
+ """
444
+ if axis is None:
445
+ return "effective"
446
+ a = str(axis).strip().lower()
447
+ if a in TIME_AXES:
448
+ return a
449
+ raise ValueError(f"未知 time_axis {axis!r}(允许:{TIME_AXES})")
450
+
451
+
452
+ def time_window_of(fm, axis: str = "effective", *, _allow_nonfinite=False):
453
+ """按轴取候选时间窗口 → `(start, end)`;不可判定 → `(None, None)`(不猜测)。
454
+
455
+ · `effective`:效力轴,走 `first_endpoint(FROM_ALIASES/UNTIL_ALIASES)`
456
+ (规范键优先、别名回落,与 `validity` **同源**);
457
+ 缺字段/不可解析 → 该侧 `None`(= 无界,与 `validity` 的「不误判」口径一致)。
458
+ · `observed`:观察轴,与 `stg._interval` **同源口径**——`temporal`(事件时刻)优先,
459
+ 缺失才回退 `condition_space.time_window`(观测窗);任一端不可解析 → `(None, None)`
460
+ (与 `_interval` 的「整体不可用」语义一致)。
461
+
462
+ `believed_at` **永不参与**(`BELIEVED_FIELD` 不出现于任何轴)。
463
+ 内部 `_allow_nonfinite=True` 仅供派生 STG 索引维持异常时间的保守候选桶;
464
+ 查询入参、效力轴别名与正常消费者均使用有限端点规则。
465
+ """
466
+ if not isinstance(fm, dict):
467
+ return None, None
468
+ if time_axis_of(axis) == "observed":
469
+ t = fm.get(OBSERVED_TIME_FIELD)
470
+ if t is not None:
471
+ ts = parse_time(t, _allow_nonfinite=_allow_nonfinite)
472
+ if ts is not None:
473
+ return ts, ts
474
+ # 兼容两种载体形态:**fm**(`condition_space.time_window`)与**索引扁平快照**
475
+ # (`time_window` 平铺在 entry 上,见 `mdcg._scan_nodes`/`_stage`)。
476
+ # 只读嵌套会让「按 entry 过滤」的路径永不命中(同类坑:S2 时间门控,
477
+ # mdcg.py L639 已记「直接读 cs 会让门控永不生效」)。
478
+ cs = fm.get("condition_space") or {}
479
+ tw = fm.get(OBSERVED_WINDOW_FIELD)
480
+ if tw is None and isinstance(cs, dict):
481
+ tw = cs.get(OBSERVED_WINDOW_FIELD)
482
+ if isinstance(tw, (list, tuple)) and len(tw) == 2:
483
+ s, e = (parse_time(v, _allow_nonfinite=_allow_nonfinite) for v in tw)
484
+ if s is None or e is None:
485
+ return None, None
486
+ return s, e
487
+ return None, None
488
+ start, _sk = first_endpoint(fm, FROM_ALIASES)
489
+ end, _ek = first_endpoint(fm, UNTIL_ALIASES)
490
+ return start, end
491
+
492
+
493
+ def _op_ok(cand, q, op) -> bool:
494
+ """单个端点比较;任一端不可解析 → False(缺字段的处置归**轴策略**,此处不猜测)。"""
495
+ if cand is None or q is None:
496
+ return False
497
+ if op == "gt":
498
+ return cand > q
499
+ if op == "gte":
500
+ return cand >= q
501
+ if op == "eq":
502
+ return cand == q
503
+ if op == "lte":
504
+ return cand <= q
505
+ if op == "lt":
506
+ return cand < q
507
+ return False # 未知算子:入口已 fail-closed,此处保守拒
508
+
509
+
510
+ def window_match(cand_start, cand_end, q_start=None, q_end=None,
511
+ start_op: str = None, end_op: str = None) -> bool:
512
+ """候选窗口与查询窗口是否匹配(§1.2 B1/B2 的**唯一实现点**,纯函数)。
513
+
514
+ 两种模式由「是否给 operator」**显式分叉**(不允许隐式混用——混用会产出
515
+ 「无法复算」的过滤,违反白箱):
516
+
517
+ · **重叠模式**(`start_op`/`end_op` 均为 `None`):候选窗口与查询窗口有交集
518
+ 即命中(记忆窗口是**区间**不是点)。查询端点缺省 = 该侧**无界**(不隐含 now)。
519
+ · **端点模式**(至少给一个 operator):对**显式启用的侧**做 `op(cand端, q端)`;
520
+ 一侧未给 operator 但**给了该侧查询端点**时,用 B1 缺省(起点 `gte` / 终点 `lte`);
521
+ 该侧查询端点也没有 → **不约束该侧**。
522
+
523
+ 「未给 operator 且未给查询端点 → 不约束」是刻意的:若一律回落到 B1 缺省再比较,
524
+ `_op_ok(cand, None, op)` 恒伪,于是 `start_operator="gte" + start_time=T`
525
+ (单端算子,合法调用)会静默返回**空集**——把「只筛起点」误答成「没有匹配」。
526
+ 端点模式下候选的该侧端点不可解析 → `False`(该侧无法比较,不猜)。
527
+
528
+ 候选窗口两端皆不可解析 → `False`(该节点「无时间轴可判」)——是否因此剔除
529
+ 由**轴的策略**决定(效力轴 fail-open / 观察轴 fail-closed,见候选过滤处)。
530
+ """
531
+ cs, ce = parse_time(cand_start), parse_time(cand_end)
532
+ if cs is None and ce is None:
533
+ return False
534
+ qs, qe = parse_time(q_start), parse_time(q_end)
535
+ if start_op is None and end_op is None:
536
+ if qs is not None and ce is not None and ce < qs:
537
+ return False
538
+ if qe is not None and cs is not None and cs > qe:
539
+ return False
540
+ return True
541
+ if start_op is not None or qs is not None:
542
+ if not _op_ok(cs, qs, start_op or "gte"):
543
+ return False
544
+ if end_op is not None or qe is not None:
545
+ if not _op_ok(ce, qe, end_op or "lte"):
546
+ return False
547
+ return True
548
+
549
+
550
+ def check_time_args(start_time=None, end_time=None, start_operator=None,
551
+ end_operator=None, time_axis=None):
552
+ """时间算子入参 fail-closed 校验 → `(enabled, axis, why)`。
553
+
554
+ **入口(`mdcg.search` / `entity_contexts`)与库层共用的唯一校验点**
555
+ (避免两处各写一套、口径漂移)。三则误用一律拒(`why` 非空即应抛
556
+ `ValueError`,不静默忽略——与 `_stg_call` 同风格):
557
+
558
+ 1. 只给 operator 而不给对应的 `start_time`/`end_time`;
559
+ 2. `time_axis` 非 `{"effective","observed"}`(含 `"believed"`);
560
+ 3. `start_time > end_time`。
561
+
562
+ 未启用(五参全 `None`)→ `(False, None, "")`(默认路径零变更)。
563
+ """
564
+ if time_axis is not None and str(time_axis).strip().lower() not in TIME_AXES:
565
+ return False, None, (f"未知 time_axis {time_axis!r}(允许:{TIME_AXES})——"
566
+ "轴必须显式且合法,静默按另一条轴过滤会产出无法复算的结果")
567
+ for op, val, nm in ((start_operator, start_time, "start_operator/start_time"),
568
+ (end_operator, end_time, "end_operator/end_time")):
569
+ if op is None:
570
+ continue
571
+ if str(op).strip().lower() not in TIME_OPERATORS:
572
+ return False, None, (f"未知算子 {op!r}(允许:{TIME_OPERATORS})")
573
+ if val is None:
574
+ return False, None, f"给了 {nm.split('/')[0]} 但缺 {nm.split('/')[1]}(不猜默认值)"
575
+ s, e = parse_time(start_time), parse_time(end_time)
576
+ if start_time is not None and s is None:
577
+ return False, None, f"start_time 不可解析:{start_time!r}"
578
+ if end_time is not None and e is None:
579
+ return False, None, f"end_time 不可解析:{end_time!r}"
580
+ if s is not None and e is not None and s > e:
581
+ return False, None, f"start_time({s}) > end_time({e}):空窗口,拒绝"
582
+ enabled = any(x is not None for x in (start_time, end_time,
583
+ start_operator, end_operator))
584
+ if not enabled:
585
+ return False, None, ""
586
+ return True, time_axis_of(time_axis), ""
587
+
588
+
589
+ def window_matches_node(fm, axis, q_start, q_end, start_op=None, end_op=None):
590
+ """候选节点按轴取窗后做 `window_match` → `(matched, missing)`。
591
+
592
+ `missing=True` 表示该节点在**该轴上不可判定**(窗口两端皆 `None`)——
593
+ 调用方据此执行轴策略:效力轴 fail-open(保留)、观察轴 fail-closed
594
+ (剔除并计入 `axis_missing`)。策略按**保证强度**定,不按「一致好看」定:
595
+ 效力轴字段是可选声明,观察轴字段由写入侧保证存在。
596
+ """
597
+ cs, ce = time_window_of(fm, axis)
598
+ if cs is None and ce is None:
599
+ return False, True
600
+ return window_match(cs, ce, q_start, q_end, start_op, end_op), False
601
+
602
+
603
+ def time_filter_meta(axis=None, mode="overlap", start=None, end=None,
604
+ start_operator=None, end_operator=None, dropped=0,
605
+ axis_missing=0, applied=False) -> dict:
606
+ """`meta["time_filter"]` 审计块(**五键齐备**,可复算):
607
+
608
+ `dropped + 存活数 == 候选数` 由调用方保证;`axis_missing` 单独记账,
609
+ 使「观察轴缺字段被剔除」的条数可查(静默放行会把数据异常藏起来)。
610
+ """
611
+ return {"axis": axis, "mode": mode, "start": start, "end": end,
612
+ "start_operator": start_operator, "end_operator": end_operator,
613
+ "dropped": int(dropped), "axis_missing": int(axis_missing),
614
+ "applied": bool(applied)}
615
+
616
+
617
+ def filter_by_time(entries, axis, q_start, q_end, start_op=None, end_op=None):
618
+ """按轴过滤候选 → `(kept, dropped, axis_missing)`。**候选层唯一过滤点**。
619
+
620
+ 轴策略按**字段保证强度**定(不按「行为一致好看」定):
621
+ · `effective` 效力轴:`effective_from/until` 是**可选声明**(多数节点没有)
622
+ → 不可判定一律 fail-open(保留)——否则「没写时效 = 被过滤掉」,
623
+ 会把沉默当否认;
624
+ · `observed` 观察轴:`temporal` / `time_window` 由**写入侧保证**存在
625
+ (add 缺省填观测窗)→ 不可判定一律 fail-closed(剔除并计入
626
+ `axis_missing`,使数据异常可查而非静默放行)。
627
+ """
628
+ kept, dropped, missing = [], 0, 0
629
+ for e in entries:
630
+ m, miss = window_matches_node(e, axis, q_start, q_end, start_op, end_op)
631
+ if miss:
632
+ if axis == "observed":
633
+ dropped += 1
634
+ missing += 1
635
+ else:
636
+ kept.append(e)
637
+ continue
638
+ if m:
639
+ kept.append(e)
640
+ else:
641
+ dropped += 1
642
+ return kept, dropped, missing
643
+
644
+
645
+ # ---------------------------------------------------------------- 依赖声明
646
+
647
+ def as_deps(value) -> list:
648
+ """把单值 / 序列 / 逗号串统一成**去重、排序**的节点 id 列表(上限 MAX_DEPS)。
649
+
650
+ 容错口径(写路径的入参形态不由本模块决定,收窄会误伤):
651
+ · `None` / 空串 / 纯空白项 → 丢弃(不是目标,也不是「声明了依赖」);
652
+ · 半角/全角逗号串 → 切分(`"a, b"` 与 `["a", "b"]` 等价);
653
+ · 排序的动机:依赖是**集合语义**(声明顺序不承载信息),排序让 fm 与
654
+ 索引快照对同一组依赖恒等——比较/去重/审计不再依赖声明顺序。
655
+ """
656
+ if value is None:
657
+ return []
658
+ items = list(value) if isinstance(value, (list, tuple, set)) else [value]
659
+ out = []
660
+ for x in items:
661
+ if x is None:
662
+ continue
663
+ for s in str(x).replace(",", ",").split(","):
664
+ s = s.strip()
665
+ if s and s not in out:
666
+ out.append(s)
667
+ out.sort()
668
+ return out[:MAX_DEPS]
669
+
670
+
671
+ def deps_of(cg, nid: str) -> list:
672
+ """读某节点声明的依赖(**零读文件**:索引快照缺失才回读节点)。"""
673
+ e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid) or {}
674
+ deps = as_deps(e.get(DEPS_FIELD))
675
+ if deps:
676
+ return deps
677
+ node = cg.get(nid)
678
+ if not node:
679
+ return []
680
+ return as_deps((node.get("frontmatter") or {}).get(DEPS_FIELD))
681
+
682
+
683
+ def invalidate_cache(cg) -> None:
684
+ """作废反查缓存(写/删节点后调用;下次读时增量重建)。"""
685
+ try:
686
+ cg.__dict__.pop("_trust_dependents", None)
687
+ except Exception: # noqa: BLE001
688
+ pass
689
+
690
+
691
+ def dependents_index(cg, refresh: bool = False) -> dict:
692
+ """反查索引:`{被依赖节点: [依赖它的节点…]}`(「谁依赖我」)。
693
+
694
+ 缓存挂在 cg 实例上(与 `subgraph` 的缓存化做法同构);`refresh=True` 强制重建。
695
+ """
696
+ generation = getattr(cg, "_cache_generation", None)
697
+ generation = generation() if callable(generation) else None
698
+ if not refresh and getattr(cg, "_trust_generation", None) == generation:
699
+ cached = getattr(cg, "_trust_dependents", None)
700
+ if isinstance(cached, dict):
701
+ return cached
702
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
703
+ idx = {}
704
+ for nid, e in list(nodes.items()):
705
+ for p in as_deps((e or {}).get(DEPS_FIELD)):
706
+ idx.setdefault(p, []).append(nid)
707
+ for k in idx:
708
+ idx[k].sort()
709
+ try:
710
+ cg._trust_dependents = idx
711
+ cg._trust_generation = generation
712
+ except Exception: # noqa: BLE001
713
+ pass
714
+ return idx
715
+
716
+
717
+ def _record(cg, rec: dict) -> None:
718
+ """台账追加(best-effort:失败静默,**绝不阻断写路径**)。"""
719
+ try:
720
+ # issue #547:本模块的审计台账(`_trust.jsonl`)此前声明「失败静默」;按 #549
721
+ # 对审计账本的口径(不能丢 ⇒ durable=True)统一,丢行不再静默。
722
+ append_jsonl(os.path.join(cg.root, AUDIT_FILE), rec, durable=True)
723
+ except Exception: # noqa: BLE001
724
+ pass
725
+
726
+
727
+ # ---------------------------------------------------------------- 推进
728
+
729
+ def _sync_index(cg, node_id, fm) -> None:
730
+ """把验证态同步进索引快照(免读文件可查);无索引实现时静默跳过。"""
731
+ idx = getattr(cg, "index", None)
732
+ if not isinstance(idx, dict):
733
+ return
734
+ e = (idx.get("nodes") or {}).get(node_id)
735
+ if e is None:
736
+ return
737
+ e[STATE_FIELD] = fm.get(STATE_FIELD)
738
+ dirty = getattr(cg, "_dirty", None)
739
+ if isinstance(dirty, dict):
740
+ dirty[node_id] = e
741
+ flush = getattr(cg, "flush", None)
742
+ if callable(flush):
743
+ flush()
744
+
745
+
746
+ # 生效条件:cg.get(node_id) 为假值(节点不存在)时返回 {"ok": False, "error": "node_not_found", "node_id": node_id};否则先过层写闸 protect.require_layer(cg, node_id, layer=fm.layer, sensitivity=fm.sensitivity)(N209:越权身份抛 AccessDenied → 转成 {"ok": False, "error": "layer_denied", "changed": False} 负路由,记 set_state_denied 台账,**不写盘**),再经 stamp 裁决:code 为 noop 或非法迁移时返回 ok=False 或 changed=False 不写盘,成功时把 fm 经 cg._write_node 落盘、_sync_index 同步验证态快照、_record 追加台账,fm 含 depends_on 时再 invalidate_cache,返回 {node_id, from, to, code, ok, changed, reason, at}。
747
+ def set_state(cg, node_id: str, dst: str, reason: str = None, actor: str = None,
748
+ evidence: str = None, method: str = None, trigger: str = None,
749
+ override: bool = False) -> dict:
750
+ """推进一个节点的验证态(**唯一推进入口**)。
751
+
752
+ 非法迁移不走异常而是返回 `{"ok": False, "error": <code>, ...}`(负路由)。
753
+ 幂等迁移返回 `changed=False` 且不写盘。**写盘前另过 principal 层写闸**
754
+ (N209:无权写该层 → `error="layer_denied"` 负路由,零写盘 + 台账留痕)。
755
+ """
756
+ node = cg.get(node_id)
757
+ if not node:
758
+ return {"ok": False, "error": "node_not_found", "node_id": node_id}
759
+ fm = dict(node.get("frontmatter") or {})
760
+ src = state_of(fm)
761
+ # N209(同族未接线的相邻写面):验证态推进 = 对节点本体 frontmatter 的一次
762
+ # **覆写**(`cg._write_node` 全量重写 fm + 正文),与 add / 覆写写面同一层闸。
763
+ # 此前该路径零层闸(MdCGSecure 对 set_state/set_verification/mark_dependents
764
+ # 无任何覆盖)⇒ 持 verify 令牌者经 verify→mark_dependents → 把**任意层**
765
+ # 依赖者(实测 self 层)置 doubted。拒绝走**负路由**而非 raise:本函数契约是
766
+ # 「非法迁移不抛异常(ok=False + 机器码)」,且 mark_dependents 契约是
767
+ # 「永不抛、不阻断本次裁决」——但**绝不写盘**,并把拒绝记进 `_trust.jsonl`
768
+ #(不静默:与 `mark_dependents_degraded` 同一「留痕降级」口径)。
769
+ try:
770
+ protect.require_layer(cg, node_id, layer=fm.get("layer"),
771
+ sensitivity=fm.get("sensitivity"))
772
+ except AccessDenied as exc:
773
+ _record(cg, {"t": time.time(), "action": "set_state_denied",
774
+ "node_id": node_id, "from": src, "to": dst,
775
+ "error": f"{type(exc).__name__}: {exc}",
776
+ "actor": actor, "trigger": trigger})
777
+ return {"node_id": node_id, "from": src, "to": dst, "ok": False,
778
+ "error": "layer_denied", "reason": str(exc), "changed": False}
779
+ ok, code, why = stamp(fm, dst, reason=reason, actor=actor, evidence=evidence,
780
+ method=method, trigger=trigger, override=override)
781
+ base = {"node_id": node_id, "from": src, "to": dst, "code": code}
782
+ if not ok:
783
+ return {**base, "ok": False, "error": code, "reason": why}
784
+ if code == "noop":
785
+ return {**base, "ok": True, "changed": False, "reason": why}
786
+ at = fm[HISTORY_FIELD][-1]["at"]
787
+ cg._write_node(node_id, os.path.join(cg.root, node["path"]), fm,
788
+ node.get("content") or "")
789
+ _sync_index(cg, node_id, fm)
790
+ _record(cg, {"t": at, "action": "set_state", "node_id": node_id,
791
+ "from": src, "to": dst, "reason": reason, "actor": actor,
792
+ "method": method, "trigger": trigger, "override": bool(override)})
793
+ if fm.get(DEPS_FIELD):
794
+ invalidate_cache(cg)
795
+ return {**base, "ok": True, "changed": True, "reason": why, "at": at}
796
+
797
+
798
+ # ---------------------------------------------------------------- 失效传播
799
+
800
+ def mark_dependents(cg, node_id: str, reason: str = None, *, apply: bool = True,
801
+ actor: str = "system", trigger: str = None,
802
+ depth: int = 1, override: bool = False) -> dict:
803
+ """**一跳同步传播**:把直接下游标为 `doubted`(异常的新定义)。
804
+
805
+ 根因口径:异常不再仅是「内容错」,而是「**它所依赖的地基动了**」——被依赖
806
+ 单元被修改/证伪时,直接下游立刻产生存疑标记,无需等全库巡检。
807
+
808
+ **永不抛**(对齐 provenance G8 纪律:传播失败不得阻断写入)。`apply=False`
809
+ 只预演;同状态下游是 no-op(幂等,不写盘、不留痕)。
810
+ """
811
+ try:
812
+ dep_map = dependents_index(cg)
813
+ kids = list(dep_map.get(node_id, []))
814
+ kids.sort()
815
+ if not kids:
816
+ return {"ok": True, "changed": 0, "dependents": [], "apply": bool(apply),
817
+ "reason": "no_dependents"}
818
+ reason = reason or f"上游 {node_id} 变动"
819
+ planned = [k for k in kids
820
+ if state_of((cg.index or {}).get("nodes", {}).get(k) or {})
821
+ != "doubted"]
822
+ if not apply:
823
+ return {"ok": True, "dry_run": True, "changed": 0,
824
+ "dependents": kids, "planned": len(planned)}
825
+ done, skipped = [], []
826
+ for k in kids:
827
+ r = set_state(cg, k, "doubted", reason=reason, actor=actor,
828
+ trigger=trigger or f"dep_changed:{node_id}",
829
+ override=override)
830
+ if r.get("ok") and r.get("changed"):
831
+ done.append(k)
832
+ elif r.get("ok"):
833
+ skipped.append(k) # 已是 doubted:幂等
834
+ else:
835
+ skipped.append(f"{k}({r.get('error')})")
836
+ return {"ok": True, "changed": len(done), "dependents": kids,
837
+ "updated": done, "skipped": skipped, "apply": True,
838
+ "reason": reason}
839
+ except Exception as exc: # noqa: BLE001
840
+ _record(cg, {"t": time.time(), "action": "mark_dependents_degraded",
841
+ "node_id": node_id, "error": f"{type(exc).__name__}: {exc}",
842
+ "actor": actor})
843
+ return {"ok": False, "degraded": True, "changed": 0,
844
+ "error": f"{type(exc).__name__}: {exc}"}
845
+
846
+
847
+ def propagate(cg, *, apply: bool = False, max_nodes: int = MAX_NODES_DEFAULT,
848
+ actor: str = "patrol") -> dict:
849
+ """**多跳异步重算**(巡检面,不阻塞写入/查询)。
850
+
851
+ BFS 从所有 `expired` / `rechecking` / 显式根源节点出发,把可达下游标
852
+ `doubted`(**只降不升**:复核通过须由人显式 `set_state(verified)`)。
853
+ 默认 `apply=False` 只出报表;`max_nodes` 封顶防大库爆炸。
854
+
855
+ `doubted` 中间节点的语义(2026-09-20 v14 缺陷 B 修复):**穿过,但不重复
856
+ 标记**。已 doubted 说明它已被标记,无需再标(幂等);但它**不是传播终点**
857
+ ——「地基动了」的波及范围必须继续往其下游走。旧实现把 doubted 直接
858
+ `continue`(当作终点),于是「先 `mark_dependents` 预演直接下游、再
859
+ `propagate` 正式传播」这一最常见序列会使多跳传播**整体失效**
860
+ (`reachable`/`updated` 全 0)且**无任何报错**。穿过的节点在
861
+ `passed_doubted` 中如实透出(可审计)。
862
+
863
+ **`reachable` / `updated` 的口径**(2026-09-20 v15-4 澄清,勿读成「波及集
864
+ 大小」):两者计的是「本次**需要新标记**的节点数」——`apply=False` 时 =
865
+ 计划标记数(`planned` 的长度),`apply=True` 时 = 实际标记成功数(`done` 的
866
+ 长度)。**穿过的 `doubted` 中继不计入**(它早已被标记,本次幂等跳过)。故
867
+ 「本次的完整波及集」= `reachable`(或 `updated`)+ `passed_doubted`,只读
868
+ 前者会低估。`roots` 是传播起点(`expired`/`rechecking`),不属于波及集。
869
+ """
870
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
871
+ dep_map = dependents_index(cg)
872
+ roots = []
873
+ for nid, e in list(nodes.items()):
874
+ st = (e or {}).get(STATE_FIELD)
875
+ if st in ("expired", "rechecking"):
876
+ roots.append(nid)
877
+ roots.sort()
878
+ cap = max(0, int(max_nodes))
879
+ admitted_roots = roots[:cap]
880
+ seen, waves, passed = set(admitted_roots), [], set()
881
+ root_set = set(roots)
882
+ frontier, depth = list(admitted_roots), 0
883
+ truncated = len(admitted_roots) < len(roots)
884
+ while frontier and len(seen) < cap:
885
+ depth += 1
886
+ nxt = []
887
+ for nid in frontier:
888
+ for k in dep_map.get(nid, []):
889
+ if k in seen or k in root_set:
890
+ continue
891
+ # The cap applies across the whole wave, not once per parent.
892
+ if len(seen) >= cap:
893
+ truncated = True
894
+ break
895
+ seen.add(k)
896
+ if state_of(nodes.get(k) or {}) == "doubted":
897
+ passed.add(k) # 穿过但不重复标记(不是终点)
898
+ nxt.append(k)
899
+ if truncated:
900
+ break
901
+ for k in nxt:
902
+ if k in passed:
903
+ continue # 已 doubted:无需再标(幂等)
904
+ waves.append({"node_id": k, "depth": depth,
905
+ # Incoming dependencies are already on this entry.
906
+ # Scanning every parent's child list per result was
907
+ # quadratic even for a sparse star/chain graph.
908
+ "via": sorted(n for n in as_deps((nodes.get(k) or {}).get(DEPS_FIELD))
909
+ if n in seen)})
910
+ if truncated:
911
+ break
912
+ frontier = nxt
913
+ if frontier and len(seen) >= cap and not truncated:
914
+ truncated = any(k not in seen and k not in root_set
915
+ for nid in frontier for k in dep_map.get(nid, ()))
916
+ bounds = {"visited": len(seen), "truncated": truncated,
917
+ "roots_admitted": len(admitted_roots)}
918
+ if not apply:
919
+ return {"ok": True, "dry_run": True, "roots": roots[:50],
920
+ "roots_count": len(roots), "reachable": len(waves),
921
+ "planned": waves[:50], "passed_doubted": sorted(passed)[:20],
922
+ "max_nodes": cap, **bounds,
923
+ "note": "预演:未改盘;只降不升(复核须显式)"}
924
+ done, skipped = [], []
925
+ for w in waves:
926
+ r = set_state(cg, w["node_id"], "doubted",
927
+ reason="多跳失效传播(上游时间轴/证据失效)",
928
+ actor=actor, trigger=f"propagate:d{w['depth']}")
929
+ if r.get("ok") and r.get("changed"):
930
+ done.append(w["node_id"])
931
+ elif not r.get("ok"):
932
+ skipped.append(f"{w['node_id']}({r.get('error')})")
933
+ return {"ok": True, "dry_run": False, "roots": roots[:50],
934
+ "roots_count": len(roots), "updated": done, "updated_count": len(done),
935
+ "passed_doubted": sorted(passed)[:20],
936
+ "skipped": skipped[:20], "max_nodes": cap, **bounds}
937
+
938
+
939
+ # ---------------------------------------------------------------- 巡检 / 回填
940
+
941
+ # 生效条件:cg 传入即只读遍历 index 快照并返回悬空/未生效/已过期/存疑四类计数与样本,不写盘、不改状态、不抛(index 缺失按空库处理);
942
+ def patrol(cg, *, limit: int = 20, now: float = None) -> dict:
943
+ """只读巡检:悬空依赖 / 时间轴失效 / 存疑积压。**不改状态、不删节点**。
944
+
945
+ 命名纪律(负记忆,2026-09-19 实测):本函数**不得叫 `check`**——裁决层已有
946
+ `check(src, dst, ...)`(唯一裁决点)。同模块内同名二次定义会**静默遮蔽**前者,
947
+ `stamp()` 随即调到巡检版并抛 `TypeError`(现场:`set_verification` 整条链断)。
948
+ 两者语义分属不同层次(纯函数裁决 vs 全库只读巡检),名字必须分开。
949
+ """
950
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
951
+ known = set(nodes)
952
+ dangling, expired, not_yet, doubted = [], [], [], []
953
+ for nid, e in sorted(nodes.items()):
954
+ for p in as_deps((e or {}).get(DEPS_FIELD)):
955
+ if p not in known:
956
+ dangling.append({"node_id": nid, "missing": p})
957
+ st = (e or {}).get(STATE_FIELD)
958
+ if st == "doubted":
959
+ doubted.append(nid)
960
+ # 时间轴按索引可判定字段粗判(精确判定需 fm,巡检读面只给候选)
961
+ kind = _index_validity(e, now=now)
962
+ if kind == "expired":
963
+ expired.append(nid)
964
+ elif kind == "not_yet":
965
+ not_yet.append(nid)
966
+ return {
967
+ "ok": not dangling,
968
+ "checked": True, "root": cg.root, "nodes": len(known),
969
+ "dangling": dangling[:int(limit)], "dangling_count": len(dangling),
970
+ "expired": expired[:int(limit)], "expired_count": len(expired),
971
+ "not_yet": not_yet[:int(limit)], "not_yet_count": len(not_yet),
972
+ "doubted": doubted[:int(limit)], "doubted_count": len(doubted),
973
+ "readonly": True,
974
+ "note": "只读巡检:悬空依赖/时效仅检出并报告,不自动改状态(处置由人/巡检动作发起)"}
975
+
976
+
977
+ def _index_validity(e, now: float = None) -> str:
978
+ """索引快照口径的时效粗判(索引缺时间字段时返回 unknown,零读文件)。"""
979
+ if not isinstance(e, dict):
980
+ return "unknown"
981
+ return validity(e, now=now)[0]
982
+
983
+
984
+ def backfill(cg, apply: bool = False, limit: int = 5000) -> dict:
985
+ """存量回填:把缺 `verification_state` 的节点显式补成 `unverified`(幂等)。
986
+
987
+ 缺字段本就按 unverified 解释(`state_of`),故回填**不是让功能工作的前提**,
988
+ 而是把「缺省」变成「显式」——索引/审计里从此可直接读到验证态。默认只盘点。
989
+ """
990
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
991
+ missing = []
992
+ for nid, e in list(nodes.items()):
993
+ if len(missing) >= limit:
994
+ break
995
+ if (e or {}).get(STATE_FIELD) in STATES:
996
+ continue
997
+ missing.append(nid)
998
+ missing.sort()
999
+ if not apply:
1000
+ return {"ok": True, "dry_run": True, "scanned": len(nodes),
1001
+ "missing": len(missing), "planned": missing[:50]}
1002
+ done, failed = [], []
1003
+ for nid in missing:
1004
+ node = cg.get(nid)
1005
+ if not node:
1006
+ failed.append(nid)
1007
+ continue
1008
+ fm = dict(node.get("frontmatter") or {})
1009
+ fm[STATE_FIELD] = state_of(fm)
1010
+ cg._write_node(nid, os.path.join(cg.root, node["path"]), fm,
1011
+ node.get("content") or "")
1012
+ _sync_index(cg, nid, fm)
1013
+ done.append(nid)
1014
+ return {"ok": True, "dry_run": False, "scanned": len(nodes),
1015
+ "missing": len(missing), "backfilled": len(done),
1016
+ "planned": done[:50], "failed": failed[:20]}
1017
+
1018
+
1019
+ def describe(cg, node_id: str, now: float = None) -> dict:
1020
+ """单节点验证态全貌(供 op=status / 状态头渲染)。只读、失败不抛。
1021
+
1022
+ N205(2026-09-28):`cg.get` 被读闸拒后**不得**回落索引条目仍报 ok=True——
1023
+ 索引条目本身就是密级/会话/验证态元数据(layer/tags/session/verification_state),
1024
+ 回落等于把「不可读」当「可见」返回(实测:guest 对 private 节点 get→None,
1025
+ 而 status 仍回 ok=True + verification_state='verified' + depends_on +
1026
+ 状态头「✓ 已验证」)。口径改为与 get/search/recall 一致的「不可见即不存在」:
1027
+ 判定走跨层单点 `security.node_visible`(纯 MdCGOS 无身份模型 → 不受影响;
1028
+ 设计者 can_admin 豁免不变)。
1029
+ """
1030
+ try:
1031
+ node = cg.get(node_id)
1032
+ except Exception: # noqa: BLE001
1033
+ node = None
1034
+ e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
1035
+ if not node and not e:
1036
+ return {"ok": False, "error": "node_not_found", "node_id": node_id}
1037
+ if not node and not _security.node_visible(cg, node_id):
1038
+ return {"ok": False, "error": "node_not_found", "node_id": node_id}
1039
+ fm = (node or {}).get("frontmatter") or {}
1040
+ deps = as_deps(fm.get(DEPS_FIELD)) or as_deps((e or {}).get(DEPS_FIELD))
1041
+ kind, start, end = validity(fm if fm else (e or {}), now=now)
1042
+ dep_map = dependents_index(cg)
1043
+ hist = list(fm.get(HISTORY_FIELD) or [])[-5:]
1044
+ return {"ok": True, "node_id": node_id,
1045
+ "verification_state": state_of(fm if fm else (e or {})),
1046
+ "verification_basis": fm.get("verification_basis"),
1047
+ "verification_method": fm.get("verification_method"),
1048
+ "verified_at": fm.get("verified_at"),
1049
+ "depends_on": deps,
1050
+ "depended_by": dep_map.get(node_id, []),
1051
+ "validity": {"kind": kind, "valid_from": fm.get(FROM_FIELD),
1052
+ "valid_until": fm.get(UNTIL_FIELD),
1053
+ "start": start, "end": end},
1054
+ "history": hist,
1055
+ "lifecycle_state": fm.get("lifecycle_state"),
1056
+ "protected": bool(fm.get("protected") or fm.get("immutable"))}
1057
+
1058
+
1059
+ def summary(cg) -> dict:
1060
+ """轻量摘要(只读;失败不抛,避免拖垮 health / 常驻循环)。"""
1061
+ try:
1062
+ rep = patrol(cg, limit=3)
1063
+ return {"dangling": rep["dangling_count"], "expired": rep["expired_count"],
1064
+ "not_yet": rep["not_yet_count"], "doubted": rep["doubted_count"],
1065
+ "nodes": rep["nodes"], "sample": [
1066
+ f"{r['node_id']}->?{r['missing']}" for r in rep["dangling"]]}
1067
+ except Exception: # noqa: BLE001
1068
+ return {}
1069
+
1070
+
1071
+ def load_ledger(cg, *, node_id: str = None, limit: int = None) -> list:
1072
+ """读验证态台账(跳过坏行;可按节点过滤)。
1073
+
1074
+ N205(2026-09-28):行内 `reason` 含**明文证据串**(外部裁决理由),此前
1075
+ 只按 node_id 等值过滤、零可见性判定 ⇒ 任何持 read op 的身份(含无令牌
1076
+ guest,`cg(op="status", action="ledger")` 在 guest 的 ops_allow 内)可读走
1077
+ 他人私密节点的裁决证据与验证态。口径与库读面统一:逐行按
1078
+ `security.node_visible`(跨层单点)判定行所属节点对本身份是否可见,
1079
+ 不可见/不可证(已 forget、索引无条目)→ 该行整条不出;设计者豁免。
1080
+ """
1081
+ path = os.path.join(cg.root, AUDIT_FILE)
1082
+ out = []
1083
+ for r in read_jsonl(path):
1084
+ if not isinstance(r, dict):
1085
+ continue
1086
+ if node_id and r.get("node_id") != node_id:
1087
+ continue
1088
+ if not _security.node_visible(cg, r.get("node_id")):
1089
+ continue
1090
+ out.append(r)
1091
+ return out[:int(limit)] if limit else out
1092
+
1093
+
1094
+ def catalog(root: str = None) -> dict:
1095
+ """自描述(供 MCP catalog / 人工核对)。"""
1096
+ return {
1097
+ "layer": "可验证记忆单元",
1098
+ "question": "它还成不成立(验证态 + 依赖 + 时效)",
1099
+ "ledger": os.path.join(root, AUDIT_FILE) if root else AUDIT_FILE,
1100
+ "states": list(STATES),
1101
+ "state_field": STATE_FIELD,
1102
+ "history_field": HISTORY_FIELD,
1103
+ "deps_field": DEPS_FIELD,
1104
+ "time_fields": [FROM_FIELD, UNTIL_FIELD],
1105
+ "transitions": sorted(f"{a}→{b}" for a, b in TRANSITIONS),
1106
+ "max_deps": MAX_DEPS,
1107
+ "max_nodes_default": MAX_NODES_DEFAULT,
1108
+ "discipline": {"never_block_write": True, "no_backfill": True,
1109
+ "patrol_readonly": True, "one_hop_sync": True,
1110
+ "multi_hop_async": True, "only_downgrade": True},
1111
+ "distinct_from": ("lifecycle.py = 节点生命周期(lifecycle_state);"
1112
+ "provenance.py = 派生血缘(_link.jsonl);"
1113
+ "本层 = 验证态与依赖(verification_state/_trust.jsonl)"),
1114
+ }