@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
@@ -1,748 +1,748 @@
1
- # -*- coding: utf-8 -*-
2
- """md_cg · 数据健康不变量断言集(Pi⑤)+ G1 类型空间正交性审计 + G3 unanalyzed 显式占位
3
-
4
- 把 2026-09-15 的一次性审计改写为**周期可复跑**的断言集(混层比例阈值 / 重复度阈值 /
5
- 字段覆盖率下限 / 闸门四态分布),挂 sustain 周期巡检;超阈值**只告警,不自动改数据**。
6
-
7
- 三条纪律:
8
- 1. **不变量 fail-closed**:类型空间封闭性 / 边键规范 / 边目标可解析 / 索引↔盘一致 /
9
- 重复度不劣化——任一 FAIL = 库结构失真,须人工处置。
10
- 2. **健康指标只告警**:混层比 / role 覆盖率 / evidence 覆盖率 / 分析覆盖率 /
11
- 闸门四态 / 触达率——低于靶值 WARN,不阻断、不改数据。
12
- 3. **缺数据源 → BLINDSPOT**(如实上报),绝不冒充 PASS。
13
-
14
- G1(Ghidra 交接 §5.4):输出各类型空间的「声明值 / 实测值 / 未声明已用 / 声明未用 /
15
- 跨空间重叠 / 方向口径分歧」——类型空间不封闭是写入侧漂移的前兆。
16
-
17
- G3(同 §5.4):unanalyzed 采用**派生断言**(不新增字段、零写入),判据
18
- `evidence_count==0 ∧ verification_basis 空 ∧ lifecycle_state 空`。
19
- 不做字段级占位的理由:生命周期是单向降级轴,与分析覆盖正交,塞同一字段破坏正交性。
20
-
21
- 用法:
22
- python -m md_cg.conformance [--root R] [--json out.json] [--baseline b.json]
23
- [--no-path-check] [--strict]
24
- """
25
- from __future__ import annotations
26
-
27
- import argparse
28
- import json
29
- import os
30
- import sys
31
- import time
32
- from collections import Counter, deque
33
-
34
- REPORT_VERSION = 1
35
- INDEX_FILE = "_index.json"
36
- ACCESS_LOG = "_access.log"
37
- DECISION_LOG = os.path.join("hippocampus", "decisions.jsonl")
38
- INBOX_LOG = os.path.join("hippocampus", "inbox.jsonl")
39
- DEFAULT_ROOT = os.path.join(
40
- os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "data", "mdcg")
41
- #: _audit.jsonl 只读尾部窗口行数(append-only 全史可数十 MB,周期巡检不扫全史)
42
- AUDIT_TAIL = 20000
43
-
44
-
45
- # 生效条件:无入参,datapath.mdcg_root() 返回真值时返回该值,导入或调用抛异常、或返回假值(如空串)时返回模块常量 DEFAULT_ROOT;
46
- def _default_root() -> str:
47
- """根解析沿用本仓约定:env `MDCG_ROOT` > `paths.json`(用户级,旧包内兼容读)
48
- > 用户级状态根 `data/mdcg`。
49
-
50
- 走 `datapath.mdcg_root()`(兜底纪律:与其它工具同源解析,不另立一套)。
51
- """
52
- try:
53
- from .datapath import mdcg_root
54
- got = mdcg_root()
55
- if got:
56
- return got
57
- except Exception: # noqa: BLE001
58
- pass
59
- return DEFAULT_ROOT
60
-
61
- # 阈值口径 = 9-15 审计基线(2026-09-16 复跑实测:混层 6468/11076=58.4% / role 2.13% /
62
- # verification_basis 60.3% / evidence 0.10% / dir_mismatch 0 / 闸门 142 条) + M4 治理靶值。
63
- # 比率型阈值只表达「离靶多远」,不阻断任何写入。
64
- # 注:触达率随 _access.log 滚动追加而单调增长,9-15 快照 7.0% → 09-16 实测 8.7%,
65
- # 差异来自时间而非口径;故**不纳入基线不劣化比对**(日志轮转会误报)。
66
- THRESHOLDS = {
67
- "stratum_ratio_max": 0.60,
68
- "stratum_target": 0.30,
69
- "role_coverage_min": 0.90,
70
- "evidence_coverage_min": 0.50,
71
- "analysis_coverage_min": 0.90,
72
- "reach_ratio_min": 0.30,
73
- "gate_sample_min": 20,
74
- # 样本下限:低于此值比率型指标不可判(如仓内自建语料),一律 BLINDSPOT 不冒充 PASS
75
- "min_nodes": 200,
76
- }
77
-
78
- #: 单一内容指纹的最大同组节点数(超过即「同模板批量写入」体征,须人工治理)
79
- DUP_GROUP_MAX = 200
80
-
81
- # 写侧规范边键。取证更正(2026-09-16):subgraph.children_index:122 / parents_index:162
82
- # 已含 `or e.get("type")` 容错,**读侧不忽略** legacy `type`(`subgraph` 内 normalize_edge
83
- # 的 docstring 仍写「会被静默忽略」,属文档滞后于代码,已登记 DOC_CODE_DRIFT)。
84
- # 仍记为规范项:chain.edge_rel 与 subgraph 双兼容是本库私约,非 md_cg 读侧(Rust 引擎 /
85
- # 外部消费者)可能只读 relation_type。
86
- CANONICAL_EDGE_KEYS = ("relation_type", "relation")
87
- LAYER_DIRS = ("knowledge", "contextual", "self", "structural", "anchor",
88
- "rejected", "unresolved", "goals", "data", "trash")
89
-
90
- # G1 静态登记:已取证的方向口径分歧(事实,非推断)
91
- KNOWN_DIRECTION_CONFLICTS = [
92
- {"literal": "hierarchical",
93
- "conflict": "md_cg subgraph 视其为「本节点是子、target 是父」"
94
- "(children_index:128);白箱源库语义为 source 是父 —— 同名反义,"
95
- "直接迁移整树倒置",
96
- "workaround": "migrate_wisdom_graph.SRC_REL_MAP 迁移时改写为 contains(语义等价)"},
97
- ]
98
- # G1 静态登记:已核对**无**方向分歧的项(防止「看起来像冲突」被反复误报)
99
- VERIFIED_CONSISTENT = [
100
- {"literal": "part_of / parent_of / contains",
101
- "verified": "children_index:128-135 与 parents_index:171-178 逐字对称、方向取反,自洽"},
102
- ]
103
- # G1 已取证的**文档滞后于代码**实例(陈述与实现不符,非缺陷但会误导写侧)
104
- DOC_CODE_DRIFT = [
105
- {"where": "subgraph.normalize_edge docstring:96",
106
- "claims": "「早期迁移器写的 type 会被静默忽略(subgraph 不兼容)」",
107
- "fact": "children_index:122 / parents_index:162 已含 `or e.get(\"type\")` 容错 —— "
108
- "读侧兼容,陈述已过期"},
109
- ]
110
-
111
- # G1 静态登记:新增类型的散落点(回答「新增类型要不要改引擎」)
112
- NEW_TYPE_TOUCHPOINTS = {
113
- "layer": ["mdcg.LAYERS", "mdcg.BUCKETED_LAYERS", "mdcg.NEG_MEMORY_MARKS",
114
- "nodefile(fm 契约)", "routing(bucket)", "MCP 工具面描述"],
115
- "edge_type": ["chain.EDGE_WEIGHTS", "subgraph(父子方向分支)",
116
- "migrate_wisdom_graph.SRC_REL_MAP"],
117
- }
118
-
119
-
120
- # 生效条件:root 下 INDEX_FILE 可读且 JSON 顶层为 dict 并含 nodes 字典时返回该 nodes;不可读抛 OSError、JSON 非法抛 JSONDecodeError、nodes 非 dict 抛 ValueError;
121
- def load_index(root: str) -> dict:
122
- """读索引快照(唯一必需数据源);损坏即抛——断言集不建立在猜测上。"""
123
- with open(os.path.join(root, INDEX_FILE), encoding="utf-8") as f:
124
- raw = json.load(f)
125
- nodes = raw.get("nodes") if isinstance(raw, dict) else None
126
- if not isinstance(nodes, dict):
127
- raise ValueError(f"索引格式异常(缺 nodes 字典): {root}/{INDEX_FILE}")
128
- return nodes
129
-
130
-
131
- # 生效条件:path 不存在(os.path.exists 为假)时返回 [];存在时逐行解析,空行与 JSONDecodeError 行被跳过,返回可解析记录的列表(可能为 []);
132
- def _read_jsonl(path: str) -> list:
133
- if not os.path.exists(path):
134
- return []
135
- out = []
136
- with open(path, encoding="utf-8", errors="replace") as f:
137
- for line in f:
138
- line = line.strip()
139
- if not line:
140
- continue
141
- try:
142
- out.append(json.loads(line))
143
- except json.JSONDecodeError:
144
- continue
145
- return out
146
-
147
-
148
- # 生效条件:rec 的 tags 缺失或为假值时按空列表处理,仅对含 ":" 的 tag 取首个冒号前的前缀构成集合并返回;无此类 tag 时返回空集合;
149
- def _tag_prefixes(rec: dict) -> set:
150
- return {str(t).split(":", 1)[0] for t in (rec.get("tags") or []) if ":" in str(t)}
151
-
152
-
153
- # 生效条件:r 的 verification_basis 为 list/tuple 时返回其真值元素的 str 列表;否则该值真值时返回 [str(b)],缺失或为假值(None/空串/空容器)时返回 [];
154
- def _basis_of(r: dict):
155
- b = r.get("verification_basis")
156
- if isinstance(b, (list, tuple)):
157
- return [str(x) for x in b if x]
158
- return [str(b)] if b else []
159
-
160
-
161
- # 生效条件:无入参,返回 layer(取自导入的模块常量 LAYERS 的排序值)+ edge_type/derived_relation/verification_basis/lifecycle_state 五键声明值映射,后四键对应模块导入或属性取值失败、属性值为假值(空容器/None)时该键 declared=None;
162
- def enum_spaces() -> dict:
163
- """各类型空间的声明值(模块真源取不到 → declared=None,报告标 BLINDSPOT)。"""
164
- from .mdcg import LAYERS
165
- spaces = {"layer": {"declared": sorted(LAYERS), "source": "mdcg.LAYERS"}}
166
- # #122(2026-10-12 DSH 端):**审计必须知道第二份权威的下场**。修前白箱侧
167
- # (md_access.py)另有一份独立 LAYERS,而本函数只声明 mdcg 一份 ⇒ 审计对
168
- # 「是否另立一份、是否已转发、是否已漂移」完全不知情。此处只**增**一个嵌套键
169
- # (不动既有 declared/source ⇒ 既有消费者零变化):former 二份权威的现状读数。
170
- try:
171
- _WB = os.path.join(os.path.dirname(os.path.abspath(__file__)), "whitebox_kb")
172
- for _p in (_WB, os.path.join(_WB, "wisdom")):
173
- if _p not in sys.path:
174
- sys.path.insert(0, _p)
175
- import md_access as _ma
176
- spaces["layer"]["second_authority"] = {
177
- "symbol": "md_access.LAYERS",
178
- "source": getattr(_ma, "LAYERS_SOURCE", "unknown"),
179
- "same_tuple": tuple(_ma.LAYERS) == tuple(LAYERS),
180
- # 身份判据:True = 真转发(同一对象);False = 仍是副本(哪怕值相同)
181
- "forwarded": _ma.LAYERS is LAYERS,
182
- }
183
- except Exception as _exc: # noqa: BLE001
184
- spaces["layer"]["second_authority"] = {
185
- "symbol": "md_access.LAYERS", "source": "unavailable",
186
- "error": "%s: %s" % (type(_exc).__name__, _exc)}
187
-
188
- # 生效条件:以 md_cg.<mod> 导入并 getattr(attr)(导入或取值抛异常则 val=None),把 {"declared": sorted(val) if val else None, "source": "<mod>.<attr>"} 写入片段外闭包变量 spaces 的 key 键(val 为假值时 declared=None),无返回值;
189
- def _grab(mod: str, attr: str, key: str):
190
- try:
191
- m = __import__(f"md_cg.{mod}", fromlist=[attr])
192
- val = getattr(m, attr, None)
193
- except Exception: # noqa: BLE001
194
- val = None
195
- spaces[key] = {"declared": sorted(val) if val else None,
196
- "source": f"{mod}.{attr}"}
197
-
198
- _grab("chain", "EDGE_WEIGHTS", "edge_type")
199
- _grab("provenance", "RELATIONS", "derived_relation")
200
- _grab("nodefile", "VERIFICATION_BASIS", "verification_basis")
201
- _grab("lifecycle", "STATES", "lifecycle_state")
202
- return spaces
203
-
204
-
205
- # ---------------------------- 指标 ----------------------------
206
-
207
- # 生效条件:对 nodes 各记录按 str(content_hash) 计数,content_hash 缺失被折成 "None",返回出现次数 >1 且哈希不为 "None"/"" 的组数、涉及节点数与前 5 大组大小;
208
- def _dup_metrics(nodes: dict) -> dict:
209
- ch = Counter(str(r.get("content_hash")) for r in nodes.values())
210
- groups = {h: c for h, c in ch.items() if c > 1 and h not in ("None", "")}
211
- return {"groups": len(groups), "nodes": sum(groups.values()),
212
- "largest": sorted(groups.values(), reverse=True)[:5]}
213
-
214
-
215
- # 生效条件:对 nodes 中每个节点的 "edges" 真值且为 list/tuple 的边列表,仅遍历其中 dict 边;依据 CANONICAL_EDGE_KEYS 与 "type" 统计键组合、关系类型、总边数、非规范键样本(最多 5)和悬空边,返回汇总字典。
216
- def _edge_metrics(nodes: dict) -> dict:
217
- types, key_mix = Counter(), Counter()
218
- total = dangling = with_edges = non_canonical = 0
219
- samples = []
220
- for nid, r in nodes.items():
221
- es = r.get("edges") or []
222
- if not isinstance(es, (list, tuple)) or not es:
223
- continue
224
- with_edges += 1
225
- for e in es:
226
- if not isinstance(e, dict):
227
- continue
228
- total += 1
229
- keys = [k for k in CANONICAL_EDGE_KEYS + ("type",) if e.get(k)]
230
- types[str(e.get("relation_type") or e.get("relation") or e.get("type"))] += 1
231
- key_mix["+".join(keys) if keys else "<无关系键>"] += 1
232
- if not any(k in CANONICAL_EDGE_KEYS for k in keys):
233
- non_canonical += 1
234
- if len(samples) < 5:
235
- samples.append({"node": nid, "edge": dict(e)})
236
- tgt = e.get("target") or e.get("target_id")
237
- if tgt is None or str(tgt) not in nodes:
238
- dangling += 1
239
- return {"nodes_with_edges": with_edges, "total": total,
240
- "types": dict(types.most_common(20)), "key_mix": dict(key_mix.most_common(10)),
241
- "non_canonical": non_canonical, "dangling": dangling, "samples": samples}
242
-
243
-
244
- # 生效条件:遍历 nodes 的值作为记录,path 经 str(r.get("path") or "") 为空即 missing++ 并 continue,不以记录含 layer/path 为前置;仅对非空 path 执行 layer 与 head 检查(layer 非空且 head != layer 且 head in LAYER_DIRS 时 layer_mismatch++),且 check_exists 为 True 时才对非空 path 以 os.path.join(root, rel) 判断不存在并计入 missing,最终返回 missing/layer_mismatch/samples 统计;。
245
- def _path_metrics(root: str, nodes: dict, check_exists: bool) -> dict:
246
- missing = mismatch = 0
247
- samples = []
248
- for r in nodes.values():
249
- layer, p = str(r.get("layer") or ""), str(r.get("path") or "")
250
- if not p:
251
- missing += 1
252
- if len(samples) < 5:
253
- samples.append({"id": r.get("id"), "why": "path 缺失"})
254
- continue
255
- rel = p.replace("\\", "/")
256
- head = rel.split("/", 1)[0]
257
- if layer and head != layer and head in LAYER_DIRS:
258
- mismatch += 1
259
- if len(samples) < 5:
260
- samples.append({"id": r.get("id"), "path": p, "layer": layer})
261
- if check_exists and not os.path.exists(os.path.join(root, rel)):
262
- missing += 1
263
- if len(samples) < 5:
264
- samples.append({"id": r.get("id"), "path": p, "why": "文件不存在"})
265
- return {"missing": missing, "layer_mismatch": mismatch, "samples": samples}
266
-
267
-
268
- # 生效条件:root 下 DECISION_LOG/INBOX_LOG 不存在时按空列表计,返回 decisions(decision 或 status 回落 "?" 的前 10 项)、decisions_total、inbox_pending=max(0, 收件数−决策数)、以及 _audit.jsonl 末尾 AUDIT_TAIL 行内 op 计数的前 6 项与尾窗元信息;
269
- def _gate_metrics(root: str) -> dict:
270
- dec = _read_jsonl(os.path.join(root, DECISION_LOG))
271
- inbox = _read_jsonl(os.path.join(root, INBOX_LOG))
272
- ops = Counter()
273
- # _audit.jsonl 是 append-only 且可达数十 MB(真源 15.9MB / 7.4 万行)——
274
- # 只读尾部窗口(近 AUDIT_TAIL 行)取 op 分布,避免周期巡检在此处 O(全史)。
275
- audit = os.path.join(root, "_audit.jsonl")
276
- tail = []
277
- if os.path.exists(audit):
278
- with open(audit, encoding="utf-8", errors="replace") as f:
279
- tail = list(deque(f, maxlen=AUDIT_TAIL))
280
- for line in tail:
281
- if not line.strip():
282
- continue
283
- try:
284
- ops[str(json.loads(line).get("op"))] += 1
285
- except json.JSONDecodeError:
286
- continue
287
- return {"decisions": dict(Counter(str(r.get("decision") or r.get("status") or "?")
288
- for r in dec).most_common(10)),
289
- "decisions_total": len(dec),
290
- "inbox_pending": max(0, len(inbox) - len(dec)),
291
- "audit_ops": dict(ops.most_common(6)), "audit_tail_lines": len(tail),
292
- "audit_tail_window": AUDIT_TAIL}
293
-
294
-
295
- # 生效条件:对 root 与 nodes,若 root/ACCESS_LOG 路径不存在则返回 {"distinct": None, "ratio": None, "lines": None};否则逐行解析 JSON,当 "ids" 为 list 或 tuple 时把其中真值元素 str 后加入 seen,且当 "id"/"node_id"/"nid" 任一真值时把其 str 加入 seen,返回 distinct 为 seen 与 nodes 键交集数量、ratio 为 distinct/max(len(nodes),1)、lines 为非空行数。
296
- def _reach_metrics(root: str, nodes: dict) -> dict:
297
- p = os.path.join(root, ACCESS_LOG)
298
- if not os.path.exists(p):
299
- return {"distinct": None, "ratio": None, "lines": None}
300
- seen, lines = set(), 0
301
- with open(p, encoding="utf-8", errors="replace") as f:
302
- for line in f:
303
- line = line.strip()
304
- if not line:
305
- continue
306
- lines += 1
307
- try:
308
- rec = json.loads(line)
309
- except json.JSONDecodeError:
310
- continue
311
- # 实际落盘形态:{"t":..., "ids":[<nid>,...], "tier":...}(_access.log 逐次追加)
312
- got = rec.get("ids")
313
- if isinstance(got, (list, tuple)):
314
- seen.update(str(x) for x in got if x)
315
- nid = rec.get("id") or rec.get("node_id") or rec.get("nid")
316
- if nid:
317
- seen.add(str(nid))
318
- hit = len(seen & set(nodes))
319
- return {"distinct": hit, "ratio": hit / max(len(nodes), 1), "lines": lines}
320
-
321
-
322
- # 生效条件:对 nodes,筛出 layer 字符串为 "knowledge" 的 kn;mixed 为 kn 中标签前缀含 doc 或 code 的数量;返回全库 nodes 数与 knowledge 层数、mixed、mixed_ratio=mixed/max(len(kn),1),以及全库口径 role_ratio/basis_ratio/evidence_ratio/state_ratio 和 knowledge 层口径 role_ratio_kn/basis_ratio_kn/evidence_ratio_kn。
323
- def _coverage_metrics(nodes: dict) -> dict:
324
- """混层口径 + 字段覆盖率(9-15 审计基线口径,逐项可复现)。
325
-
326
- **分母口径取证(2026-09-16,关键)**:审计的「role 99.99% 为空」「evidence_count
327
- 仅 6 条」是 **knowledge 层**分母;全库分母会摊薄成「role 2.13% / evidence 12 条」,
328
- 把一个 99.99% 的空缺伪装成「还行」。故两类分母并存上报,**健康判据一律取
329
- knowledge 层口径**(`*_ratio_kn`),全库口径只作对照片段。
330
- """
331
- kn = [r for r in nodes.values() if str(r.get("layer")) == "knowledge"]
332
- mixed = sum(1 for r in kn if {"doc", "code"} & _tag_prefixes(r))
333
- n, nk = len(nodes), max(len(kn), 1)
334
- return {"nodes": n, "knowledge": len(kn), "mixed_layer": mixed,
335
- "mixed_ratio": mixed / nk,
336
- "role_ratio": sum(1 for r in nodes.values() if r.get("role")) / max(n, 1),
337
- "basis_ratio": sum(1 for r in nodes.values() if _basis_of(r)) / max(n, 1),
338
- "evidence_ratio": sum(1 for r in nodes.values()
339
- if _as_int(r.get("evidence_count")) > 0) / max(n, 1),
340
- "state_ratio": sum(1 for r in nodes.values()
341
- if r.get("lifecycle_state")) / max(n, 1),
342
- # —— knowledge 层口径(= 审计原口径,判据用这组)——
343
- "role_ratio_kn": sum(1 for r in kn if r.get("role")) / nk,
344
- "basis_ratio_kn": sum(1 for r in kn if _basis_of(r)) / nk,
345
- "evidence_ratio_kn": sum(1 for r in kn
346
- if _as_int(r.get("evidence_count")) > 0) / nk}
347
-
348
-
349
- # 生效条件:int(v) 转换成功时返回该整数;抛 TypeError/ValueError(如 None、非数字串)时返回 0;
350
- def _as_int(v) -> int:
351
- try:
352
- return int(v)
353
- except (TypeError, ValueError):
354
- return 0
355
-
356
-
357
- # ---------------------------- G3 · unanalyzed 派生集合 ----------------------------
358
-
359
- # 生效条件:仅当记录 _as_int(evidence_count)==0 且 verification_basis 为空且 lifecycle_state 为假值时计入 ids,返回 count、ratio=count/max(len(nodes),1) 与前 5 个 id 样本;
360
- def unanalyzed(nodes: dict) -> dict:
361
- """G3:unanalyzed **派生**判据(不新增字段、零写入)。
362
-
363
- 判据 = `evidence_count==0 ∧ verification_basis 空 ∧ lifecycle_state 空`
364
- —— 三者皆空 = 「无一维分析痕迹」,与「分析结论为负」不同(后者会留 basis)。
365
-
366
- 不做字段级占位的理由(Ghidra 交接 §5.4):
367
- * 生命周期是**单向降级轴**(active→converged→demoted→archived),与分析覆盖正交,
368
- 塞进同一字段即破坏正交性;
369
- * **逃逸口已存在**——`verification_basis` 声明集里有 `other`(真源 273 条在用),
370
- 「分析过但无法归类」有明确归宿,故「basis 为空」不再与「分析结论为空」混淆。
371
- """
372
- ids = [nid for nid, r in nodes.items()
373
- if _as_int(r.get("evidence_count")) == 0
374
- and not _basis_of(r)
375
- and not r.get("lifecycle_state")]
376
- return {"count": len(ids), "ratio": len(ids) / max(len(nodes), 1),
377
- "sample": ids[:5]}
378
-
379
-
380
- # ---------------------------- G1 · 类型空间正交性审计 ----------------------------
381
-
382
- # 生效条件:调用 _usage(nodes, edges) 时 edges 形参未被源码引用,对 nodes.values() 中每个节点 r,仅当 r.get("layer")、r.get("role")、r.get("derived_relation")、r.get("lifecycle_state") 为真值时分别以 str 值计入对应 Counter,_basis_of(r) 与 _tag_prefixes(r) 展开的元素分别计入 verification_basis 与 tag_prefix,再遍历各 r 的 r.get("edges") or [] 中 isinstance(e, dict) 的项按 edge_rel(e) 计数,最终 edge_type 仅保留键为真值的计数,返回 used 字典;
383
- def _usage(nodes: dict, edges: dict) -> dict:
384
- """各类型空间的**实测**取值(与 enum_spaces 的声明值对照)。"""
385
- from .chain import edge_rel
386
- used = {
387
- "layer": Counter(str(r.get("layer")) for r in nodes.values() if r.get("layer")),
388
- "role": Counter(str(r.get("role")) for r in nodes.values() if r.get("role")),
389
- "verification_basis": Counter(b for r in nodes.values() for b in _basis_of(r)),
390
- "derived_relation": Counter(str(r.get("derived_relation"))
391
- for r in nodes.values() if r.get("derived_relation")),
392
- "lifecycle_state": Counter(str(r.get("lifecycle_state"))
393
- for r in nodes.values() if r.get("lifecycle_state")),
394
- "tag_prefix": Counter(p for r in nodes.values() for p in _tag_prefixes(r)),
395
- }
396
- rels = Counter()
397
- for r in nodes.values():
398
- for e in (r.get("edges") or []):
399
- if isinstance(e, dict):
400
- rels[edge_rel(e)] += 1
401
- used["edge_type"] = Counter({k: v for k, v in rels.items() if k})
402
- return used
403
-
404
-
405
- # 生效条件:以 enum_spaces 的声明集与 _usage 的实测集逐空间对照(closed 仅在 declared 非 None 且无未声明已用时为 True),role 与 tag_prefix 两空间的 declared/closed 恒为 None,另附 _cross_space_overlap(字面量出现在 ≥2 空间或 layer∩tag_prefix)及 KNOWN_DIRECTION_CONFLICTS/VERIFIED_CONSISTENT/DOC_CODE_DRIFT/NEW_TYPE_TOUCHPOINTS 四个常量;
406
- def _g1_audit(nodes: dict, edges: dict) -> dict:
407
- """G1:声明值 / 实测值 / 未声明已用 / 声明未用 / 跨空间重叠 / 方向口径分歧。"""
408
- spaces = enum_spaces()
409
- used = _usage(nodes, edges)
410
- out = {}
411
- for name, spec in spaces.items():
412
- dec = set(spec.get("declared") or [])
413
- u = set(used.get(name, {}).keys())
414
- out[name] = {
415
- "source": spec.get("source"),
416
- "declared": sorted(dec),
417
- "used": dict(used.get(name, {}).most_common(30)),
418
- "undeclared_used": sorted(u - dec),
419
- "declared_unused": sorted(dec - u),
420
- "closed": (spec.get("declared") is not None and not (u - dec)),
421
- }
422
- for name in ("role", "tag_prefix"):
423
- out[name] = {"source": None, "declared": None,
424
- "used": dict(used.get(name, {}).most_common(30)),
425
- "undeclared_used": sorted(used.get(name, {})),
426
- "declared_unused": [], "closed": None}
427
- # 跨空间重叠:同一字面量出现在 ≥2 个空间 → 解析歧义风险
428
- owners = Counter()
429
- for name, spec in out.items():
430
- for lit in (spec.get("declared") or []):
431
- owners[str(lit)] += 1
432
- out["_cross_space_overlap"] = sorted(l for l, c in owners.items() if c > 1) + \
433
- sorted(set(used.get("layer", {})) & set(used.get("tag_prefix", {})))
434
- out["_direction_conflicts"] = KNOWN_DIRECTION_CONFLICTS
435
- out["_verified_consistent"] = VERIFIED_CONSISTENT
436
- out["_doc_code_drift"] = DOC_CODE_DRIFT
437
- out["_new_type_touchpoints"] = NEW_TYPE_TOUCHPOINTS
438
- return out
439
-
440
-
441
- # ---------------------------- 断言集 ----------------------------
442
-
443
- # 生效条件:四参齐备时返回 {"id": cid, "level": level, "ok": bool(ok), "detail": detail},ok 经 bool() 归一为布尔;
444
- def _ck(cid: str, level: str, ok: bool, detail: str) -> dict:
445
- return {"id": cid, "level": level, "ok": bool(ok), "detail": detail}
446
-
447
-
448
- # 生效条件:调用 check(root, check_paths, baseline, strict) 时,root 原样传入 load_index 得 nodes,check_paths 原样传入 _path_metrics 并在 index.path.present 检查消息中当其为假时追加“(--no-path-check 未查盘)”,baseline 为真时追加 _regression 基线不劣化检查、为假(None 或空 dict)时跳过,n=len(nodes) 小于 THRESHOLDS["min_nodes"] 时 small 为真且使 _ratio 各项及 reach.ratio、stratum.mixed_ratio 在 val 为 None 或 small 为真时记 BLINDSPOT、否则记 WARN,最终 verdict 为 FAIL(存在 level="FAIL" 且 ok 为假)、否则 WARN(存在 level="WARN" 且 ok 为假,或 strict 为真且存在 level="BLINDSPOT")、否则 PASS,返回含 REPORT_VERSION、t、elapsed_s、root 绝对路径、verdict、nodes、checks、counts、coverage、dup、edges、paths、gate、reach、unanalyzed、g1、protocol(=protocol.audit() 静态对账,恒追加四条 FAIL 级断言:op.declared 无未登记分支 / verb.implemented live 动词均有实现分支 / verb.reserved_clean 预留动词未被静默实现 / shape.declared 形状声明完备)、thresholds 的 dict;
449
- def check(root: str, *, check_paths: bool = True,
450
- baseline: dict = None, strict: bool = False) -> dict:
451
- """跑一遍全部断言,返回报告 dict(零写入:不修任何数据、不落任何文件)。"""
452
- t0 = time.time()
453
- nodes = load_index(root)
454
- n = len(nodes)
455
- small = n < THRESHOLDS["min_nodes"]
456
- cov = _coverage_metrics(nodes)
457
- edges = _edge_metrics(nodes)
458
- paths = _path_metrics(root, nodes, check_paths)
459
- gate = _gate_metrics(root)
460
- reach = _reach_metrics(root, nodes)
461
- un = unanalyzed(nodes)
462
- g1 = _g1_audit(nodes, edges)
463
- dup = _dup_metrics(nodes)
464
- checks = []
465
- T = THRESHOLDS
466
-
467
- # ---- 不变量(fail-closed)----
468
- for space, use_key in (("layer", "layer"), ("verification_basis", "verification_basis"),
469
- ("derived_relation", "derived_relation"),
470
- ("lifecycle_state", "lifecycle_state")):
471
- spec = g1[space]
472
- undecl = spec["undeclared_used"]
473
- checks.append(_ck(f"enum.{space}.closed", "FAIL", not undecl,
474
- f"声明源={spec['source']};未声明已用={undecl or '无'}"))
475
- checks.append(_ck("edge.rel.declared", "WARN",
476
- not g1["edge_type"]["undeclared_used"],
477
- f"未声明边类型={g1['edge_type']['undeclared_used'] or '无'}"
478
- "(读侧退化为 chain.DEFAULT_EDGE_WEIGHT=0.50,不炸但权重失真)"))
479
- checks.append(_ck("edge.key.canonical", "WARN", edges["non_canonical"] == 0,
480
- f"非规范键边 {edges['non_canonical']}/{edges['total']}"
481
- f"(写侧规范={CANONICAL_EDGE_KEYS};md_cg 读侧兼容 type,"
482
- "非 md_cg 读侧不兼容——存量债,判据=不劣化)"))
483
- checks.append(_ck("edge.target.resolvable", "FAIL", edges["dangling"] == 0,
484
- f"悬空边 {edges['dangling']}/{edges['total']}(图断裂)"))
485
- checks.append(_ck("index.path.present", "FAIL", paths["missing"] == 0,
486
- f"path 缺失/文件不存在 {paths['missing']}"
487
- + ("" if check_paths else "(--no-path-check 未查盘)")))
488
- checks.append(_ck("index.layer.dir.match", "FAIL", paths["layer_mismatch"] == 0,
489
- f"层-目录不一致 {paths['layer_mismatch']}(9-15 基线=0)"))
490
- top_dup = dup["largest"][0] if dup["largest"] else 0
491
- checks.append(_ck("dup.content.no_blowup", "FAIL", top_dup <= DUP_GROUP_MAX,
492
- f"内容指纹重复组 {dup['groups']} / 涉及节点 {dup['nodes']}"
493
- f" / 最大组 {dup['largest'][:3]}(最大组上限 {DUP_GROUP_MAX})"))
494
-
495
- # ---- 健康指标(只告警)----
496
- # 生效条件:val 为 None 或片段外闭包布尔 small 为真(small、n、T 均未在本片段定义)时追加 level="BLINDSPOT" 项;否则追加 level="WARN"、ok=(val>=low) 的项;两分支均无返回值;
497
- def _ratio(cid, val, low, name):
498
- if small or val is None:
499
- checks.append(_ck(cid, "BLINDSPOT", True,
500
- f"{name} 不可判(样本 {n} < {T['min_nodes']} / 数据源缺失)"))
501
- return
502
- checks.append(_ck(cid, "WARN", val >= low, f"{name}={val * 100:.1f}%(下限 {low:.0%})"))
503
-
504
- mr = None if small else cov["mixed_ratio"]
505
- checks.append(_ck("stratum.mixed_ratio",
506
- "BLINDSPOT" if mr is None else "WARN",
507
- mr is None or mr <= T["stratum_ratio_max"],
508
- "混层比(knowledge 中 doc∪code 标签)=N/A(样本不足)" if mr is None else
509
- f"混层比(knowledge 中 doc∪code 标签)={mr * 100:.1f}%"
510
- f"(上限 {T['stratum_ratio_max']:.0%},治理靶 {T['stratum_target']:.0%})"))
511
- _ratio("stratum.role_coverage", cov["role_ratio_kn"], T["role_coverage_min"],
512
- "role 覆盖率[knowledge]")
513
- _ratio("stratum.evidence_coverage", cov["evidence_ratio_kn"],
514
- T["evidence_coverage_min"], "evidence 覆盖率[knowledge]")
515
- _ratio("analysis.coverage", 1 - un["ratio"], T["analysis_coverage_min"],
516
- f"分析覆盖率(非 unanalyzed;unanalyzed={un['count']})")
517
- _ratio("reach.ratio", None if small else reach["ratio"], T["reach_ratio_min"], "触达率")
518
- checks.append(_ck("gate.sample", "WARN",
519
- gate["decisions_total"] >= T["gate_sample_min"],
520
- f"闸门裁决样本 {gate['decisions_total']} 条 {gate['decisions']}"
521
- f"(下限 {T['gate_sample_min']})"))
522
-
523
- # ---- 记忆动词协议 v1 静态对账(声明 ↔ MCP 面实现,纯源码事实、不连库)----
524
- # 与 G1 的分工:G1 对账**数据值域**,这里对账**动词面**——两者都是
525
- # 「声明了没做 / 做了没说」的前置红灯,属结构性不变量(FAIL 级,fail-closed)。
526
- from . import protocol as _proto
527
- pa = _proto.audit()
528
- checks.append(_ck("protocol.op.extension_surface", "WARN", True,
529
- f"协议 v{pa['protocol_version']} 冻结面={pa['declared']}"
530
- f"(live {len(pa['live'])} / reserved {len(pa['reserved'])});"
531
- f"MCP 面另有 {len(pa['extension_ops'])} 个扩展 op 不属协议面"
532
- f"(文档一致性由 cogmap 门禁承担)"))
533
- checks.append(_ck("protocol.verb.implemented", "FAIL",
534
- not pa["missing_impl"],
535
- f"声明为 live 的动词 {pa['live']} 均有实现分支"
536
- if not pa["missing_impl"] else
537
- f"声明为 live 却无实现分支:{pa['missing_impl']}"))
538
- checks.append(_ck("protocol.verb.reserved_clean", "FAIL",
539
- not pa["reserved_leaked"],
540
- f"reserved 动词 {pa['reserved']} 未出现实现分支"
541
- if not pa["reserved_leaked"] else
542
- f"reserved 动词被静默实现(须先改 status=live):"
543
- f"{pa['reserved_leaked']}"))
544
- checks.append(_ck("protocol.shape.declared", "FAIL",
545
- not pa["shape_errors"],
546
- f"{len(pa['declared'])} 个动词形状声明完备"
547
- if not pa["shape_errors"] else
548
- f"形状声明不完整:{pa['shape_errors']}"))
549
-
550
- # ---- 基线不劣化(有 baseline 时才可判)----
551
- if baseline:
552
- checks += _regression({"mixed_ratio": cov["mixed_ratio"],
553
- "non_canonical": edges["non_canonical"],
554
- "dangling": edges["dangling"],
555
- "dup_groups": dup["groups"],
556
- "unanalyzed": un["count"]}, baseline)
557
-
558
- fails = [c for c in checks if c["level"] == "FAIL" and not c["ok"]]
559
- warns = [c for c in checks if c["level"] == "WARN" and not c["ok"]]
560
- blind = [c for c in checks if c["level"] == "BLINDSPOT"]
561
- v = "FAIL" if fails else ("WARN" if (warns or (strict and blind)) else "PASS")
562
- return {"report_version": REPORT_VERSION, "t": t0, "elapsed_s": round(time.time() - t0, 2),
563
- "root": os.path.abspath(root), "verdict": v,
564
- "nodes": n, "checks": checks,
565
- "counts": {"fail": len(fails), "warn": len(warns), "blindspot": len(blind),
566
- "total": len(checks)},
567
- "coverage": cov, "dup": dup, "edges": edges, "paths": paths,
568
- "gate": gate, "reach": reach, "unanalyzed": un, "g1": g1,
569
- "protocol": pa, "thresholds": T}
570
-
571
-
572
- # 生效条件:对 cur 各键,baseline(或其 metrics)缺失、该键在基线为 None 或 cur 值为 None 时跳过;否则以 val > b+1e-9 判劣化,产出 level 恒为 "FAIL"、ok=not worse 的检查项;
573
- def _regression(cur: dict, baseline: dict) -> list:
574
- """与基线比对:单调量只准不变或改善(重复度/悬空/非规范键/混层/unanalyzed)。
575
-
576
- 只收**单调有害量**(越大越坏);触达率等随运行时间自然增长的量不进比对,
577
- 否则日志轮转即误报。
578
- """
579
- base = (baseline or {}).get("metrics") or {}
580
- out = []
581
- for key, val in cur.items():
582
- b = base.get(key)
583
- if b is None or val is None:
584
- continue
585
- worse = val > b + 1e-9
586
- out.append(_ck(f"baseline.{key}", "FAIL", not worse,
587
- f"现值 {val:.4f} vs 基线 {b:.4f}"
588
- + ("(劣化)" if worse else "(未劣化)")))
589
- return out
590
-
591
-
592
- # 生效条件:rep 含 coverage/edges/dup/unanalyzed/gate/reach 子字典与 nodes 键时(全部按下标取值,缺键即抛 KeyError)返回扁平指标映射;
593
- def metrics_of(rep: dict) -> dict:
594
- """抽成可比对的扁平指标(--baseline 的写入面)。"""
595
- return {"mixed_ratio": rep["coverage"]["mixed_ratio"],
596
- "non_canonical": rep["edges"]["non_canonical"],
597
- "dangling": rep["edges"]["dangling"],
598
- "dup_groups": rep["dup"]["groups"],
599
- "unanalyzed": rep["unanalyzed"]["count"],
600
- "nodes": rep["nodes"],
601
- "role_ratio": rep["coverage"]["role_ratio"],
602
- "basis_ratio": rep["coverage"]["basis_ratio"],
603
- "evidence_ratio": rep["coverage"]["evidence_ratio"],
604
- "role_ratio_kn": rep["coverage"]["role_ratio_kn"],
605
- "evidence_ratio_kn": rep["coverage"]["evidence_ratio_kn"],
606
- "reach_ratio": rep["reach"]["ratio"],
607
- "gate_decisions": rep["gate"]["decisions_total"]}
608
-
609
-
610
- # ---------------------------- 报告 ----------------------------
611
-
612
- # 生效条件:rep 各键齐备(按下标取值,任一键缺失抛 KeyError)时拼接为多行文本,reach.ratio 为 None 时渲染 "N/A",g1 中以 "_" 开头的键在遍历中被跳过;
613
- def render(rep: dict) -> str:
614
- L = []
615
- a = L.append
616
- a(f"== conformance v{rep['report_version']} · {rep['root']}")
617
- a(f" verdict: {rep['verdict']} nodes={rep['nodes']} "
618
- f"checks={rep['counts']['total']} (fail {rep['counts']['fail']} / "
619
- f"warn {rep['counts']['warn']} / blindspot {rep['counts']['blindspot']})")
620
- a("\n-- 断言集(FAIL=fail-closed 不变量 / WARN=健康指标只告警)--")
621
- for c in rep["checks"]:
622
- mark = {"FAIL": "!!", "WARN": " ?", "BLINDSPOT": " ~"}.get(c["level"], " .")
623
- ok = "ok " if c["ok"] else "NO "
624
- a(f" [{mark}] {ok}{c['id']}: {c['detail']}")
625
- c = rep["coverage"]
626
- a(f"\n-- 口径复核(9-15 基线)--")
627
- a(f" nodes={c['nodes']} knowledge={c['knowledge']} 混层={c['mixed_layer']}"
628
- f" ({c['mixed_ratio'] * 100:.1f}%)")
629
- a(f" dir_mismatch={rep['paths']['layer_mismatch']} path_missing={rep['paths']['missing']}")
630
- a(f" 覆盖率[knowledge 层·判据口径] role={c['role_ratio_kn'] * 100:.3f}%"
631
- f" basis={c['basis_ratio_kn'] * 100:.1f}% evidence={c['evidence_ratio_kn'] * 100:.3f}%")
632
- a(f" 覆盖率为对照[全库口径] role={c['role_ratio'] * 100:.2f}%"
633
- f" basis={c['basis_ratio'] * 100:.1f}% evidence={c['evidence_ratio'] * 100:.2f}%"
634
- f" state={c['state_ratio'] * 100:.1f}%")
635
- a(f" 重复 content_hash 组={rep['dup']['groups']} 节点={rep['dup']['nodes']}"
636
- f" 最大组={rep['dup']['largest'][:3]}")
637
- a(f" 边 total={rep['edges']['total']} 非规范键={rep['edges']['non_canonical']}"
638
- f" 悬空={rep['edges']['dangling']} 类型={rep['edges']['types']}")
639
- r = rep["reach"]
640
- a(f" 触达 distinct={r['distinct']} ratio="
641
- + ("N/A" if r['ratio'] is None else f"{r['ratio'] * 100:.1f}%") + f" log_lines={r['lines']}")
642
- a(f" 闸门 decisions={rep['gate']['decisions_total']} {rep['gate']['decisions']}"
643
- f" inbox_pending={rep['gate']['inbox_pending']}")
644
- a(f" 审计 op(尾窗 {rep['gate']['audit_tail_lines']}"
645
- f"/{rep['gate']['audit_tail_window']} 行)={rep['gate']['audit_ops']}")
646
- a(f" G3 unanalyzed 派生={rep['unanalyzed']['count']}"
647
- f" ({rep['unanalyzed']['ratio'] * 100:.1f}%)")
648
- pr = rep.get("protocol") or {}
649
- if pr:
650
- a("\n-- 记忆动词协议 v1 静态对账 --")
651
- a(f" {pr['doc']} frozen={pr['frozen']} ok={pr['ok']}")
652
- a(f" 声明={pr['declared']}")
653
- a(f" live={pr['live']} reserved={pr['reserved']}(未实现即如实登记,不冒充)")
654
- a(f" MCP 面 op 分支={len(pr['actual'])} 个,其中扩展能力面"
655
- f"(不属协议 v1){len(pr['extension_ops'])} 个")
656
- if pr["errors"]:
657
- for e in pr["errors"]:
658
- a(f" !! {e}")
659
- a("\n-- G1 类型空间正交性 --")
660
- for name, spec in rep["g1"].items():
661
- if name.startswith("_"):
662
- continue
663
- a(f" [{name}] 源={spec['source']} 封闭={spec['closed']}")
664
- a(f" 实测={spec['used']}")
665
- if spec["undeclared_used"]:
666
- a(f" ★未声明已用={spec['undeclared_used']}")
667
- if spec["declared_unused"]:
668
- a(f" 声明未用={spec['declared_unused']}")
669
- a(f" 跨空间重叠={rep['g1']['_cross_space_overlap'] or '无'}")
670
- a(f" 方向口径分歧={[d['literal'] for d in rep['g1']['_direction_conflicts']]}")
671
- a(f" 已核对无分歧={[d['literal'] for d in rep['g1']['_verified_consistent']]}")
672
- a(f" 文档滞后于代码={[d['where'] for d in rep['g1']['_doc_code_drift']]}")
673
- a(f" 新增类型触点={rep['g1']['_new_type_touchpoints']}")
674
- return "\n".join(L)
675
-
676
-
677
- # 生效条件:传入对象可写属性时执行赋值 sustain_module.conformance_summary = report_summary,无返回值(None);
678
- def register_sustain(sustain_module) -> None: # pragma: no cover
679
- """挂点说明(供 sustain 侧最小侵入调用)。
680
-
681
- 周期巡检**不加新 tick**:`_tick_tidy()` 已是「contextual 存量治理」的
682
- 读侧巡检,本断言集复用同一节奏(tidy_interval),由 `report_summary(cg)`
683
- 只取结论不落盘——避免为只读检查新增后台周期与 env 开关。
684
- """
685
- sustain_module.conformance_summary = report_summary
686
-
687
-
688
- # 生效条件:root 依次取 cg_or_root.root 属性、cg_or_root 本身、_default_root()(前者为假值即回落,故 0/空串会继续回落);check 抛异常时返回 ok=False、verdict="BLINDSPOT"、error,否则返回 ok=(verdict!="FAIL") 与 fail/warn/blindspot/failed_ids/t;
689
- def report_summary(cg_or_root) -> dict:
690
- """给常驻循环用的**轻量**结论(不渲染全文、不写盘):verdict + 计数。"""
691
- root = getattr(cg_or_root, "root", None) or cg_or_root or _default_root()
692
- try:
693
- rep = check(root, check_paths=False)
694
- except Exception as e: # noqa: BLE001
695
- return {"ok": False, "verdict": "BLINDSPOT", "error": f"{type(e).__name__}: {e}"}
696
- return {"ok": rep["verdict"] != "FAIL", "verdict": rep["verdict"],
697
- "fail": rep["counts"]["fail"], "warn": rep["counts"]["warn"],
698
- "blindspot": rep["counts"]["blindspot"],
699
- "failed_ids": [c["id"] for c in rep["checks"]
700
- if c["level"] == "FAIL" and not c["ok"]],
701
- "t": rep["t"]}
702
-
703
-
704
- # 生效条件:argv 为 None 时 argparse 从 sys.argv 取值,--root 缺失或为假值回落 _default_root();check 抛 OSError/ValueError(如索引不可读)时打印 BLINDSPOT 并返回 2,否则按 --write-baseline/--json 写盘后返回 0(verdict≠"FAIL")或 1("FAIL");
705
- def main(argv=None) -> int:
706
- p = argparse.ArgumentParser(prog="python -m md_cg.conformance",
707
- description="数据健康不变量断言集(只读,零写入)")
708
- p.add_argument("--root", default=None,
709
- help="认知图根(默认 MDCG_ROOT > paths.json > 用户级状态根 data/mdcg)")
710
- p.add_argument("--json", dest="json_out", default=None)
711
- p.add_argument("--baseline", default=None, help="基线报告 json(比对不劣化)")
712
- p.add_argument("--write-baseline", default=None, help="把本次指标写成新基线")
713
- p.add_argument("--no-path-check", action="store_true", help="不查盘上文件是否存在")
714
- p.add_argument("--strict", action="store_true", help="BLINDSPOT 也视为非 PASS")
715
- a = p.parse_args(argv)
716
-
717
- root = a.root or _default_root()
718
- baseline = None
719
- if a.baseline:
720
- with open(a.baseline, encoding="utf-8") as f:
721
- baseline = json.load(f)
722
- try:
723
- rep = check(root, check_paths=not a.no_path_check,
724
- baseline=baseline, strict=a.strict)
725
- except (OSError, ValueError) as e:
726
- # 数据源不可读 = BLINDSPOT(如实上报),绝不打印「通过」
727
- print(f"== conformance v{REPORT_VERSION} · {os.path.abspath(root)}")
728
- print(f" verdict: BLINDSPOT —— 索引不可读: {type(e).__name__}: {e}")
729
- print(f" 缺失维度: 数据源({INDEX_FILE});修复后重跑,勿以本结果为「通过」。")
730
- return 2
731
- print(render(rep))
732
- if a.write_baseline:
733
- with open(a.write_baseline, "w", encoding="utf-8") as f:
734
- json.dump({"report_version": REPORT_VERSION, "t": rep["t"],
735
- "root": rep["root"], "metrics": metrics_of(rep)},
736
- f, ensure_ascii=False, indent=2)
737
- print(f"\n 基线已写入: {a.write_baseline}")
738
- if a.json_out:
739
- with open(a.json_out, "w", encoding="utf-8") as f:
740
- json.dump(rep, f, ensure_ascii=False, indent=2, default=str)
741
- print(f" 报告已写入: {a.json_out}")
742
- return 0 if rep["verdict"] != "FAIL" else 1
743
-
744
-
745
- if __name__ == "__main__":
746
- if hasattr(sys.stdout, "reconfigure"):
747
- sys.stdout.reconfigure(encoding="utf-8", errors="replace")
1
+ # -*- coding: utf-8 -*-
2
+ """md_cg · 数据健康不变量断言集(Pi⑤)+ G1 类型空间正交性审计 + G3 unanalyzed 显式占位
3
+
4
+ 把 2026-09-15 的一次性审计改写为**周期可复跑**的断言集(混层比例阈值 / 重复度阈值 /
5
+ 字段覆盖率下限 / 闸门四态分布),挂 sustain 周期巡检;超阈值**只告警,不自动改数据**。
6
+
7
+ 三条纪律:
8
+ 1. **不变量 fail-closed**:类型空间封闭性 / 边键规范 / 边目标可解析 / 索引↔盘一致 /
9
+ 重复度不劣化——任一 FAIL = 库结构失真,须人工处置。
10
+ 2. **健康指标只告警**:混层比 / role 覆盖率 / evidence 覆盖率 / 分析覆盖率 /
11
+ 闸门四态 / 触达率——低于靶值 WARN,不阻断、不改数据。
12
+ 3. **缺数据源 → BLINDSPOT**(如实上报),绝不冒充 PASS。
13
+
14
+ G1(Ghidra 交接 §5.4):输出各类型空间的「声明值 / 实测值 / 未声明已用 / 声明未用 /
15
+ 跨空间重叠 / 方向口径分歧」——类型空间不封闭是写入侧漂移的前兆。
16
+
17
+ G3(同 §5.4):unanalyzed 采用**派生断言**(不新增字段、零写入),判据
18
+ `evidence_count==0 ∧ verification_basis 空 ∧ lifecycle_state 空`。
19
+ 不做字段级占位的理由:生命周期是单向降级轴,与分析覆盖正交,塞同一字段破坏正交性。
20
+
21
+ 用法:
22
+ python -m md_cg.conformance [--root R] [--json out.json] [--baseline b.json]
23
+ [--no-path-check] [--strict]
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import argparse
28
+ import json
29
+ import os
30
+ import sys
31
+ import time
32
+ from collections import Counter, deque
33
+
34
+ REPORT_VERSION = 1
35
+ INDEX_FILE = "_index.json"
36
+ ACCESS_LOG = "_access.log"
37
+ DECISION_LOG = os.path.join("hippocampus", "decisions.jsonl")
38
+ INBOX_LOG = os.path.join("hippocampus", "inbox.jsonl")
39
+ DEFAULT_ROOT = os.path.join(
40
+ os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "data", "mdcg")
41
+ #: _audit.jsonl 只读尾部窗口行数(append-only 全史可数十 MB,周期巡检不扫全史)
42
+ AUDIT_TAIL = 20000
43
+
44
+
45
+ # 生效条件:无入参,datapath.mdcg_root() 返回真值时返回该值,导入或调用抛异常、或返回假值(如空串)时返回模块常量 DEFAULT_ROOT;
46
+ def _default_root() -> str:
47
+ """根解析沿用本仓约定:env `MDCG_ROOT` > `paths.json`(用户级,旧包内兼容读)
48
+ > 用户级状态根 `data/mdcg`。
49
+
50
+ 走 `datapath.mdcg_root()`(兜底纪律:与其它工具同源解析,不另立一套)。
51
+ """
52
+ try:
53
+ from .datapath import mdcg_root
54
+ got = mdcg_root()
55
+ if got:
56
+ return got
57
+ except Exception: # noqa: BLE001
58
+ pass
59
+ return DEFAULT_ROOT
60
+
61
+ # 阈值口径 = 9-15 审计基线(2026-09-16 复跑实测:混层 6468/11076=58.4% / role 2.13% /
62
+ # verification_basis 60.3% / evidence 0.10% / dir_mismatch 0 / 闸门 142 条) + M4 治理靶值。
63
+ # 比率型阈值只表达「离靶多远」,不阻断任何写入。
64
+ # 注:触达率随 _access.log 滚动追加而单调增长,9-15 快照 7.0% → 09-16 实测 8.7%,
65
+ # 差异来自时间而非口径;故**不纳入基线不劣化比对**(日志轮转会误报)。
66
+ THRESHOLDS = {
67
+ "stratum_ratio_max": 0.60,
68
+ "stratum_target": 0.30,
69
+ "role_coverage_min": 0.90,
70
+ "evidence_coverage_min": 0.50,
71
+ "analysis_coverage_min": 0.90,
72
+ "reach_ratio_min": 0.30,
73
+ "gate_sample_min": 20,
74
+ # 样本下限:低于此值比率型指标不可判(如仓内自建语料),一律 BLINDSPOT 不冒充 PASS
75
+ "min_nodes": 200,
76
+ }
77
+
78
+ #: 单一内容指纹的最大同组节点数(超过即「同模板批量写入」体征,须人工治理)
79
+ DUP_GROUP_MAX = 200
80
+
81
+ # 写侧规范边键。取证更正(2026-09-16):subgraph.children_index:122 / parents_index:162
82
+ # 已含 `or e.get("type")` 容错,**读侧不忽略** legacy `type`(`subgraph` 内 normalize_edge
83
+ # 的 docstring 仍写「会被静默忽略」,属文档滞后于代码,已登记 DOC_CODE_DRIFT)。
84
+ # 仍记为规范项:chain.edge_rel 与 subgraph 双兼容是本库私约,非 md_cg 读侧(Rust 引擎 /
85
+ # 外部消费者)可能只读 relation_type。
86
+ CANONICAL_EDGE_KEYS = ("relation_type", "relation")
87
+ LAYER_DIRS = ("knowledge", "contextual", "self", "structural", "anchor",
88
+ "rejected", "unresolved", "goals", "data", "trash")
89
+
90
+ # G1 静态登记:已取证的方向口径分歧(事实,非推断)
91
+ KNOWN_DIRECTION_CONFLICTS = [
92
+ {"literal": "hierarchical",
93
+ "conflict": "md_cg subgraph 视其为「本节点是子、target 是父」"
94
+ "(children_index:128);白箱源库语义为 source 是父 —— 同名反义,"
95
+ "直接迁移整树倒置",
96
+ "workaround": "migrate_wisdom_graph.SRC_REL_MAP 迁移时改写为 contains(语义等价)"},
97
+ ]
98
+ # G1 静态登记:已核对**无**方向分歧的项(防止「看起来像冲突」被反复误报)
99
+ VERIFIED_CONSISTENT = [
100
+ {"literal": "part_of / parent_of / contains",
101
+ "verified": "children_index:128-135 与 parents_index:171-178 逐字对称、方向取反,自洽"},
102
+ ]
103
+ # G1 已取证的**文档滞后于代码**实例(陈述与实现不符,非缺陷但会误导写侧)
104
+ DOC_CODE_DRIFT = [
105
+ {"where": "subgraph.normalize_edge docstring:96",
106
+ "claims": "「早期迁移器写的 type 会被静默忽略(subgraph 不兼容)」",
107
+ "fact": "children_index:122 / parents_index:162 已含 `or e.get(\"type\")` 容错 —— "
108
+ "读侧兼容,陈述已过期"},
109
+ ]
110
+
111
+ # G1 静态登记:新增类型的散落点(回答「新增类型要不要改引擎」)
112
+ NEW_TYPE_TOUCHPOINTS = {
113
+ "layer": ["mdcg.LAYERS", "mdcg.BUCKETED_LAYERS", "mdcg.NEG_MEMORY_MARKS",
114
+ "nodefile(fm 契约)", "routing(bucket)", "MCP 工具面描述"],
115
+ "edge_type": ["chain.EDGE_WEIGHTS", "subgraph(父子方向分支)",
116
+ "migrate_wisdom_graph.SRC_REL_MAP"],
117
+ }
118
+
119
+
120
+ # 生效条件:root 下 INDEX_FILE 可读且 JSON 顶层为 dict 并含 nodes 字典时返回该 nodes;不可读抛 OSError、JSON 非法抛 JSONDecodeError、nodes 非 dict 抛 ValueError;
121
+ def load_index(root: str) -> dict:
122
+ """读索引快照(唯一必需数据源);损坏即抛——断言集不建立在猜测上。"""
123
+ with open(os.path.join(root, INDEX_FILE), encoding="utf-8") as f:
124
+ raw = json.load(f)
125
+ nodes = raw.get("nodes") if isinstance(raw, dict) else None
126
+ if not isinstance(nodes, dict):
127
+ raise ValueError(f"索引格式异常(缺 nodes 字典): {root}/{INDEX_FILE}")
128
+ return nodes
129
+
130
+
131
+ # 生效条件:path 不存在(os.path.exists 为假)时返回 [];存在时逐行解析,空行与 JSONDecodeError 行被跳过,返回可解析记录的列表(可能为 []);
132
+ def _read_jsonl(path: str) -> list:
133
+ if not os.path.exists(path):
134
+ return []
135
+ out = []
136
+ with open(path, encoding="utf-8", errors="replace") as f:
137
+ for line in f:
138
+ line = line.strip()
139
+ if not line:
140
+ continue
141
+ try:
142
+ out.append(json.loads(line))
143
+ except json.JSONDecodeError:
144
+ continue
145
+ return out
146
+
147
+
148
+ # 生效条件:rec 的 tags 缺失或为假值时按空列表处理,仅对含 ":" 的 tag 取首个冒号前的前缀构成集合并返回;无此类 tag 时返回空集合;
149
+ def _tag_prefixes(rec: dict) -> set:
150
+ return {str(t).split(":", 1)[0] for t in (rec.get("tags") or []) if ":" in str(t)}
151
+
152
+
153
+ # 生效条件:r 的 verification_basis 为 list/tuple 时返回其真值元素的 str 列表;否则该值真值时返回 [str(b)],缺失或为假值(None/空串/空容器)时返回 [];
154
+ def _basis_of(r: dict):
155
+ b = r.get("verification_basis")
156
+ if isinstance(b, (list, tuple)):
157
+ return [str(x) for x in b if x]
158
+ return [str(b)] if b else []
159
+
160
+
161
+ # 生效条件:无入参,返回 layer(取自导入的模块常量 LAYERS 的排序值)+ edge_type/derived_relation/verification_basis/lifecycle_state 五键声明值映射,后四键对应模块导入或属性取值失败、属性值为假值(空容器/None)时该键 declared=None;
162
+ def enum_spaces() -> dict:
163
+ """各类型空间的声明值(模块真源取不到 → declared=None,报告标 BLINDSPOT)。"""
164
+ from .mdcg import LAYERS
165
+ spaces = {"layer": {"declared": sorted(LAYERS), "source": "mdcg.LAYERS"}}
166
+ # #122(2026-10-12 DSH 端):**审计必须知道第二份权威的下场**。修前白箱侧
167
+ # (md_access.py)另有一份独立 LAYERS,而本函数只声明 mdcg 一份 ⇒ 审计对
168
+ # 「是否另立一份、是否已转发、是否已漂移」完全不知情。此处只**增**一个嵌套键
169
+ # (不动既有 declared/source ⇒ 既有消费者零变化):former 二份权威的现状读数。
170
+ try:
171
+ _WB = os.path.join(os.path.dirname(os.path.abspath(__file__)), "whitebox_kb")
172
+ for _p in (_WB, os.path.join(_WB, "wisdom")):
173
+ if _p not in sys.path:
174
+ sys.path.insert(0, _p)
175
+ import md_access as _ma
176
+ spaces["layer"]["second_authority"] = {
177
+ "symbol": "md_access.LAYERS",
178
+ "source": getattr(_ma, "LAYERS_SOURCE", "unknown"),
179
+ "same_tuple": tuple(_ma.LAYERS) == tuple(LAYERS),
180
+ # 身份判据:True = 真转发(同一对象);False = 仍是副本(哪怕值相同)
181
+ "forwarded": _ma.LAYERS is LAYERS,
182
+ }
183
+ except Exception as _exc: # noqa: BLE001
184
+ spaces["layer"]["second_authority"] = {
185
+ "symbol": "md_access.LAYERS", "source": "unavailable",
186
+ "error": "%s: %s" % (type(_exc).__name__, _exc)}
187
+
188
+ # 生效条件:以 md_cg.<mod> 导入并 getattr(attr)(导入或取值抛异常则 val=None),把 {"declared": sorted(val) if val else None, "source": "<mod>.<attr>"} 写入片段外闭包变量 spaces 的 key 键(val 为假值时 declared=None),无返回值;
189
+ def _grab(mod: str, attr: str, key: str):
190
+ try:
191
+ m = __import__(f"md_cg.{mod}", fromlist=[attr])
192
+ val = getattr(m, attr, None)
193
+ except Exception: # noqa: BLE001
194
+ val = None
195
+ spaces[key] = {"declared": sorted(val) if val else None,
196
+ "source": f"{mod}.{attr}"}
197
+
198
+ _grab("chain", "EDGE_WEIGHTS", "edge_type")
199
+ _grab("provenance", "RELATIONS", "derived_relation")
200
+ _grab("nodefile", "VERIFICATION_BASIS", "verification_basis")
201
+ _grab("lifecycle", "STATES", "lifecycle_state")
202
+ return spaces
203
+
204
+
205
+ # ---------------------------- 指标 ----------------------------
206
+
207
+ # 生效条件:对 nodes 各记录按 str(content_hash) 计数,content_hash 缺失被折成 "None",返回出现次数 >1 且哈希不为 "None"/"" 的组数、涉及节点数与前 5 大组大小;
208
+ def _dup_metrics(nodes: dict) -> dict:
209
+ ch = Counter(str(r.get("content_hash")) for r in nodes.values())
210
+ groups = {h: c for h, c in ch.items() if c > 1 and h not in ("None", "")}
211
+ return {"groups": len(groups), "nodes": sum(groups.values()),
212
+ "largest": sorted(groups.values(), reverse=True)[:5]}
213
+
214
+
215
+ # 生效条件:对 nodes 中每个节点的 "edges" 真值且为 list/tuple 的边列表,仅遍历其中 dict 边;依据 CANONICAL_EDGE_KEYS 与 "type" 统计键组合、关系类型、总边数、非规范键样本(最多 5)和悬空边,返回汇总字典。
216
+ def _edge_metrics(nodes: dict) -> dict:
217
+ types, key_mix = Counter(), Counter()
218
+ total = dangling = with_edges = non_canonical = 0
219
+ samples = []
220
+ for nid, r in nodes.items():
221
+ es = r.get("edges") or []
222
+ if not isinstance(es, (list, tuple)) or not es:
223
+ continue
224
+ with_edges += 1
225
+ for e in es:
226
+ if not isinstance(e, dict):
227
+ continue
228
+ total += 1
229
+ keys = [k for k in CANONICAL_EDGE_KEYS + ("type",) if e.get(k)]
230
+ types[str(e.get("relation_type") or e.get("relation") or e.get("type"))] += 1
231
+ key_mix["+".join(keys) if keys else "<无关系键>"] += 1
232
+ if not any(k in CANONICAL_EDGE_KEYS for k in keys):
233
+ non_canonical += 1
234
+ if len(samples) < 5:
235
+ samples.append({"node": nid, "edge": dict(e)})
236
+ tgt = e.get("target") or e.get("target_id")
237
+ if tgt is None or str(tgt) not in nodes:
238
+ dangling += 1
239
+ return {"nodes_with_edges": with_edges, "total": total,
240
+ "types": dict(types.most_common(20)), "key_mix": dict(key_mix.most_common(10)),
241
+ "non_canonical": non_canonical, "dangling": dangling, "samples": samples}
242
+
243
+
244
+ # 生效条件:遍历 nodes 的值作为记录,path 经 str(r.get("path") or "") 为空即 missing++ 并 continue,不以记录含 layer/path 为前置;仅对非空 path 执行 layer 与 head 检查(layer 非空且 head != layer 且 head in LAYER_DIRS 时 layer_mismatch++),且 check_exists 为 True 时才对非空 path 以 os.path.join(root, rel) 判断不存在并计入 missing,最终返回 missing/layer_mismatch/samples 统计;。
245
+ def _path_metrics(root: str, nodes: dict, check_exists: bool) -> dict:
246
+ missing = mismatch = 0
247
+ samples = []
248
+ for r in nodes.values():
249
+ layer, p = str(r.get("layer") or ""), str(r.get("path") or "")
250
+ if not p:
251
+ missing += 1
252
+ if len(samples) < 5:
253
+ samples.append({"id": r.get("id"), "why": "path 缺失"})
254
+ continue
255
+ rel = p.replace("\\", "/")
256
+ head = rel.split("/", 1)[0]
257
+ if layer and head != layer and head in LAYER_DIRS:
258
+ mismatch += 1
259
+ if len(samples) < 5:
260
+ samples.append({"id": r.get("id"), "path": p, "layer": layer})
261
+ if check_exists and not os.path.exists(os.path.join(root, rel)):
262
+ missing += 1
263
+ if len(samples) < 5:
264
+ samples.append({"id": r.get("id"), "path": p, "why": "文件不存在"})
265
+ return {"missing": missing, "layer_mismatch": mismatch, "samples": samples}
266
+
267
+
268
+ # 生效条件:root 下 DECISION_LOG/INBOX_LOG 不存在时按空列表计,返回 decisions(decision 或 status 回落 "?" 的前 10 项)、decisions_total、inbox_pending=max(0, 收件数−决策数)、以及 _audit.jsonl 末尾 AUDIT_TAIL 行内 op 计数的前 6 项与尾窗元信息;
269
+ def _gate_metrics(root: str) -> dict:
270
+ dec = _read_jsonl(os.path.join(root, DECISION_LOG))
271
+ inbox = _read_jsonl(os.path.join(root, INBOX_LOG))
272
+ ops = Counter()
273
+ # _audit.jsonl 是 append-only 且可达数十 MB(真源 15.9MB / 7.4 万行)——
274
+ # 只读尾部窗口(近 AUDIT_TAIL 行)取 op 分布,避免周期巡检在此处 O(全史)。
275
+ audit = os.path.join(root, "_audit.jsonl")
276
+ tail = []
277
+ if os.path.exists(audit):
278
+ with open(audit, encoding="utf-8", errors="replace") as f:
279
+ tail = list(deque(f, maxlen=AUDIT_TAIL))
280
+ for line in tail:
281
+ if not line.strip():
282
+ continue
283
+ try:
284
+ ops[str(json.loads(line).get("op"))] += 1
285
+ except json.JSONDecodeError:
286
+ continue
287
+ return {"decisions": dict(Counter(str(r.get("decision") or r.get("status") or "?")
288
+ for r in dec).most_common(10)),
289
+ "decisions_total": len(dec),
290
+ "inbox_pending": max(0, len(inbox) - len(dec)),
291
+ "audit_ops": dict(ops.most_common(6)), "audit_tail_lines": len(tail),
292
+ "audit_tail_window": AUDIT_TAIL}
293
+
294
+
295
+ # 生效条件:对 root 与 nodes,若 root/ACCESS_LOG 路径不存在则返回 {"distinct": None, "ratio": None, "lines": None};否则逐行解析 JSON,当 "ids" 为 list 或 tuple 时把其中真值元素 str 后加入 seen,且当 "id"/"node_id"/"nid" 任一真值时把其 str 加入 seen,返回 distinct 为 seen 与 nodes 键交集数量、ratio 为 distinct/max(len(nodes),1)、lines 为非空行数。
296
+ def _reach_metrics(root: str, nodes: dict) -> dict:
297
+ p = os.path.join(root, ACCESS_LOG)
298
+ if not os.path.exists(p):
299
+ return {"distinct": None, "ratio": None, "lines": None}
300
+ seen, lines = set(), 0
301
+ with open(p, encoding="utf-8", errors="replace") as f:
302
+ for line in f:
303
+ line = line.strip()
304
+ if not line:
305
+ continue
306
+ lines += 1
307
+ try:
308
+ rec = json.loads(line)
309
+ except json.JSONDecodeError:
310
+ continue
311
+ # 实际落盘形态:{"t":..., "ids":[<nid>,...], "tier":...}(_access.log 逐次追加)
312
+ got = rec.get("ids")
313
+ if isinstance(got, (list, tuple)):
314
+ seen.update(str(x) for x in got if x)
315
+ nid = rec.get("id") or rec.get("node_id") or rec.get("nid")
316
+ if nid:
317
+ seen.add(str(nid))
318
+ hit = len(seen & set(nodes))
319
+ return {"distinct": hit, "ratio": hit / max(len(nodes), 1), "lines": lines}
320
+
321
+
322
+ # 生效条件:对 nodes,筛出 layer 字符串为 "knowledge" 的 kn;mixed 为 kn 中标签前缀含 doc 或 code 的数量;返回全库 nodes 数与 knowledge 层数、mixed、mixed_ratio=mixed/max(len(kn),1),以及全库口径 role_ratio/basis_ratio/evidence_ratio/state_ratio 和 knowledge 层口径 role_ratio_kn/basis_ratio_kn/evidence_ratio_kn。
323
+ def _coverage_metrics(nodes: dict) -> dict:
324
+ """混层口径 + 字段覆盖率(9-15 审计基线口径,逐项可复现)。
325
+
326
+ **分母口径取证(2026-09-16,关键)**:审计的「role 99.99% 为空」「evidence_count
327
+ 仅 6 条」是 **knowledge 层**分母;全库分母会摊薄成「role 2.13% / evidence 12 条」,
328
+ 把一个 99.99% 的空缺伪装成「还行」。故两类分母并存上报,**健康判据一律取
329
+ knowledge 层口径**(`*_ratio_kn`),全库口径只作对照片段。
330
+ """
331
+ kn = [r for r in nodes.values() if str(r.get("layer")) == "knowledge"]
332
+ mixed = sum(1 for r in kn if {"doc", "code"} & _tag_prefixes(r))
333
+ n, nk = len(nodes), max(len(kn), 1)
334
+ return {"nodes": n, "knowledge": len(kn), "mixed_layer": mixed,
335
+ "mixed_ratio": mixed / nk,
336
+ "role_ratio": sum(1 for r in nodes.values() if r.get("role")) / max(n, 1),
337
+ "basis_ratio": sum(1 for r in nodes.values() if _basis_of(r)) / max(n, 1),
338
+ "evidence_ratio": sum(1 for r in nodes.values()
339
+ if _as_int(r.get("evidence_count")) > 0) / max(n, 1),
340
+ "state_ratio": sum(1 for r in nodes.values()
341
+ if r.get("lifecycle_state")) / max(n, 1),
342
+ # —— knowledge 层口径(= 审计原口径,判据用这组)——
343
+ "role_ratio_kn": sum(1 for r in kn if r.get("role")) / nk,
344
+ "basis_ratio_kn": sum(1 for r in kn if _basis_of(r)) / nk,
345
+ "evidence_ratio_kn": sum(1 for r in kn
346
+ if _as_int(r.get("evidence_count")) > 0) / nk}
347
+
348
+
349
+ # 生效条件:int(v) 转换成功时返回该整数;抛 TypeError/ValueError(如 None、非数字串)时返回 0;
350
+ def _as_int(v) -> int:
351
+ try:
352
+ return int(v)
353
+ except (TypeError, ValueError):
354
+ return 0
355
+
356
+
357
+ # ---------------------------- G3 · unanalyzed 派生集合 ----------------------------
358
+
359
+ # 生效条件:仅当记录 _as_int(evidence_count)==0 且 verification_basis 为空且 lifecycle_state 为假值时计入 ids,返回 count、ratio=count/max(len(nodes),1) 与前 5 个 id 样本;
360
+ def unanalyzed(nodes: dict) -> dict:
361
+ """G3:unanalyzed **派生**判据(不新增字段、零写入)。
362
+
363
+ 判据 = `evidence_count==0 ∧ verification_basis 空 ∧ lifecycle_state 空`
364
+ —— 三者皆空 = 「无一维分析痕迹」,与「分析结论为负」不同(后者会留 basis)。
365
+
366
+ 不做字段级占位的理由(Ghidra 交接 §5.4):
367
+ * 生命周期是**单向降级轴**(active→converged→demoted→archived),与分析覆盖正交,
368
+ 塞进同一字段即破坏正交性;
369
+ * **逃逸口已存在**——`verification_basis` 声明集里有 `other`(真源 273 条在用),
370
+ 「分析过但无法归类」有明确归宿,故「basis 为空」不再与「分析结论为空」混淆。
371
+ """
372
+ ids = [nid for nid, r in nodes.items()
373
+ if _as_int(r.get("evidence_count")) == 0
374
+ and not _basis_of(r)
375
+ and not r.get("lifecycle_state")]
376
+ return {"count": len(ids), "ratio": len(ids) / max(len(nodes), 1),
377
+ "sample": ids[:5]}
378
+
379
+
380
+ # ---------------------------- G1 · 类型空间正交性审计 ----------------------------
381
+
382
+ # 生效条件:调用 _usage(nodes, edges) 时 edges 形参未被源码引用,对 nodes.values() 中每个节点 r,仅当 r.get("layer")、r.get("role")、r.get("derived_relation")、r.get("lifecycle_state") 为真值时分别以 str 值计入对应 Counter,_basis_of(r) 与 _tag_prefixes(r) 展开的元素分别计入 verification_basis 与 tag_prefix,再遍历各 r 的 r.get("edges") or [] 中 isinstance(e, dict) 的项按 edge_rel(e) 计数,最终 edge_type 仅保留键为真值的计数,返回 used 字典;
383
+ def _usage(nodes: dict, edges: dict) -> dict:
384
+ """各类型空间的**实测**取值(与 enum_spaces 的声明值对照)。"""
385
+ from .chain import edge_rel
386
+ used = {
387
+ "layer": Counter(str(r.get("layer")) for r in nodes.values() if r.get("layer")),
388
+ "role": Counter(str(r.get("role")) for r in nodes.values() if r.get("role")),
389
+ "verification_basis": Counter(b for r in nodes.values() for b in _basis_of(r)),
390
+ "derived_relation": Counter(str(r.get("derived_relation"))
391
+ for r in nodes.values() if r.get("derived_relation")),
392
+ "lifecycle_state": Counter(str(r.get("lifecycle_state"))
393
+ for r in nodes.values() if r.get("lifecycle_state")),
394
+ "tag_prefix": Counter(p for r in nodes.values() for p in _tag_prefixes(r)),
395
+ }
396
+ rels = Counter()
397
+ for r in nodes.values():
398
+ for e in (r.get("edges") or []):
399
+ if isinstance(e, dict):
400
+ rels[edge_rel(e)] += 1
401
+ used["edge_type"] = Counter({k: v for k, v in rels.items() if k})
402
+ return used
403
+
404
+
405
+ # 生效条件:以 enum_spaces 的声明集与 _usage 的实测集逐空间对照(closed 仅在 declared 非 None 且无未声明已用时为 True),role 与 tag_prefix 两空间的 declared/closed 恒为 None,另附 _cross_space_overlap(字面量出现在 ≥2 空间或 layer∩tag_prefix)及 KNOWN_DIRECTION_CONFLICTS/VERIFIED_CONSISTENT/DOC_CODE_DRIFT/NEW_TYPE_TOUCHPOINTS 四个常量;
406
+ def _g1_audit(nodes: dict, edges: dict) -> dict:
407
+ """G1:声明值 / 实测值 / 未声明已用 / 声明未用 / 跨空间重叠 / 方向口径分歧。"""
408
+ spaces = enum_spaces()
409
+ used = _usage(nodes, edges)
410
+ out = {}
411
+ for name, spec in spaces.items():
412
+ dec = set(spec.get("declared") or [])
413
+ u = set(used.get(name, {}).keys())
414
+ out[name] = {
415
+ "source": spec.get("source"),
416
+ "declared": sorted(dec),
417
+ "used": dict(used.get(name, {}).most_common(30)),
418
+ "undeclared_used": sorted(u - dec),
419
+ "declared_unused": sorted(dec - u),
420
+ "closed": (spec.get("declared") is not None and not (u - dec)),
421
+ }
422
+ for name in ("role", "tag_prefix"):
423
+ out[name] = {"source": None, "declared": None,
424
+ "used": dict(used.get(name, {}).most_common(30)),
425
+ "undeclared_used": sorted(used.get(name, {})),
426
+ "declared_unused": [], "closed": None}
427
+ # 跨空间重叠:同一字面量出现在 ≥2 个空间 → 解析歧义风险
428
+ owners = Counter()
429
+ for name, spec in out.items():
430
+ for lit in (spec.get("declared") or []):
431
+ owners[str(lit)] += 1
432
+ out["_cross_space_overlap"] = sorted(l for l, c in owners.items() if c > 1) + \
433
+ sorted(set(used.get("layer", {})) & set(used.get("tag_prefix", {})))
434
+ out["_direction_conflicts"] = KNOWN_DIRECTION_CONFLICTS
435
+ out["_verified_consistent"] = VERIFIED_CONSISTENT
436
+ out["_doc_code_drift"] = DOC_CODE_DRIFT
437
+ out["_new_type_touchpoints"] = NEW_TYPE_TOUCHPOINTS
438
+ return out
439
+
440
+
441
+ # ---------------------------- 断言集 ----------------------------
442
+
443
+ # 生效条件:四参齐备时返回 {"id": cid, "level": level, "ok": bool(ok), "detail": detail},ok 经 bool() 归一为布尔;
444
+ def _ck(cid: str, level: str, ok: bool, detail: str) -> dict:
445
+ return {"id": cid, "level": level, "ok": bool(ok), "detail": detail}
446
+
447
+
448
+ # 生效条件:调用 check(root, check_paths, baseline, strict) 时,root 原样传入 load_index 得 nodes,check_paths 原样传入 _path_metrics 并在 index.path.present 检查消息中当其为假时追加“(--no-path-check 未查盘)”,baseline 为真时追加 _regression 基线不劣化检查、为假(None 或空 dict)时跳过,n=len(nodes) 小于 THRESHOLDS["min_nodes"] 时 small 为真且使 _ratio 各项及 reach.ratio、stratum.mixed_ratio 在 val 为 None 或 small 为真时记 BLINDSPOT、否则记 WARN,最终 verdict 为 FAIL(存在 level="FAIL" 且 ok 为假)、否则 WARN(存在 level="WARN" 且 ok 为假,或 strict 为真且存在 level="BLINDSPOT")、否则 PASS,返回含 REPORT_VERSION、t、elapsed_s、root 绝对路径、verdict、nodes、checks、counts、coverage、dup、edges、paths、gate、reach、unanalyzed、g1、protocol(=protocol.audit() 静态对账,恒追加四条 FAIL 级断言:op.declared 无未登记分支 / verb.implemented live 动词均有实现分支 / verb.reserved_clean 预留动词未被静默实现 / shape.declared 形状声明完备)、thresholds 的 dict;
449
+ def check(root: str, *, check_paths: bool = True,
450
+ baseline: dict = None, strict: bool = False) -> dict:
451
+ """跑一遍全部断言,返回报告 dict(零写入:不修任何数据、不落任何文件)。"""
452
+ t0 = time.time()
453
+ nodes = load_index(root)
454
+ n = len(nodes)
455
+ small = n < THRESHOLDS["min_nodes"]
456
+ cov = _coverage_metrics(nodes)
457
+ edges = _edge_metrics(nodes)
458
+ paths = _path_metrics(root, nodes, check_paths)
459
+ gate = _gate_metrics(root)
460
+ reach = _reach_metrics(root, nodes)
461
+ un = unanalyzed(nodes)
462
+ g1 = _g1_audit(nodes, edges)
463
+ dup = _dup_metrics(nodes)
464
+ checks = []
465
+ T = THRESHOLDS
466
+
467
+ # ---- 不变量(fail-closed)----
468
+ for space, use_key in (("layer", "layer"), ("verification_basis", "verification_basis"),
469
+ ("derived_relation", "derived_relation"),
470
+ ("lifecycle_state", "lifecycle_state")):
471
+ spec = g1[space]
472
+ undecl = spec["undeclared_used"]
473
+ checks.append(_ck(f"enum.{space}.closed", "FAIL", not undecl,
474
+ f"声明源={spec['source']};未声明已用={undecl or '无'}"))
475
+ checks.append(_ck("edge.rel.declared", "WARN",
476
+ not g1["edge_type"]["undeclared_used"],
477
+ f"未声明边类型={g1['edge_type']['undeclared_used'] or '无'}"
478
+ "(读侧退化为 chain.DEFAULT_EDGE_WEIGHT=0.50,不炸但权重失真)"))
479
+ checks.append(_ck("edge.key.canonical", "WARN", edges["non_canonical"] == 0,
480
+ f"非规范键边 {edges['non_canonical']}/{edges['total']}"
481
+ f"(写侧规范={CANONICAL_EDGE_KEYS};md_cg 读侧兼容 type,"
482
+ "非 md_cg 读侧不兼容——存量债,判据=不劣化)"))
483
+ checks.append(_ck("edge.target.resolvable", "FAIL", edges["dangling"] == 0,
484
+ f"悬空边 {edges['dangling']}/{edges['total']}(图断裂)"))
485
+ checks.append(_ck("index.path.present", "FAIL", paths["missing"] == 0,
486
+ f"path 缺失/文件不存在 {paths['missing']}"
487
+ + ("" if check_paths else "(--no-path-check 未查盘)")))
488
+ checks.append(_ck("index.layer.dir.match", "FAIL", paths["layer_mismatch"] == 0,
489
+ f"层-目录不一致 {paths['layer_mismatch']}(9-15 基线=0)"))
490
+ top_dup = dup["largest"][0] if dup["largest"] else 0
491
+ checks.append(_ck("dup.content.no_blowup", "FAIL", top_dup <= DUP_GROUP_MAX,
492
+ f"内容指纹重复组 {dup['groups']} / 涉及节点 {dup['nodes']}"
493
+ f" / 最大组 {dup['largest'][:3]}(最大组上限 {DUP_GROUP_MAX})"))
494
+
495
+ # ---- 健康指标(只告警)----
496
+ # 生效条件:val 为 None 或片段外闭包布尔 small 为真(small、n、T 均未在本片段定义)时追加 level="BLINDSPOT" 项;否则追加 level="WARN"、ok=(val>=low) 的项;两分支均无返回值;
497
+ def _ratio(cid, val, low, name):
498
+ if small or val is None:
499
+ checks.append(_ck(cid, "BLINDSPOT", True,
500
+ f"{name} 不可判(样本 {n} < {T['min_nodes']} / 数据源缺失)"))
501
+ return
502
+ checks.append(_ck(cid, "WARN", val >= low, f"{name}={val * 100:.1f}%(下限 {low:.0%})"))
503
+
504
+ mr = None if small else cov["mixed_ratio"]
505
+ checks.append(_ck("stratum.mixed_ratio",
506
+ "BLINDSPOT" if mr is None else "WARN",
507
+ mr is None or mr <= T["stratum_ratio_max"],
508
+ "混层比(knowledge 中 doc∪code 标签)=N/A(样本不足)" if mr is None else
509
+ f"混层比(knowledge 中 doc∪code 标签)={mr * 100:.1f}%"
510
+ f"(上限 {T['stratum_ratio_max']:.0%},治理靶 {T['stratum_target']:.0%})"))
511
+ _ratio("stratum.role_coverage", cov["role_ratio_kn"], T["role_coverage_min"],
512
+ "role 覆盖率[knowledge]")
513
+ _ratio("stratum.evidence_coverage", cov["evidence_ratio_kn"],
514
+ T["evidence_coverage_min"], "evidence 覆盖率[knowledge]")
515
+ _ratio("analysis.coverage", 1 - un["ratio"], T["analysis_coverage_min"],
516
+ f"分析覆盖率(非 unanalyzed;unanalyzed={un['count']})")
517
+ _ratio("reach.ratio", None if small else reach["ratio"], T["reach_ratio_min"], "触达率")
518
+ checks.append(_ck("gate.sample", "WARN",
519
+ gate["decisions_total"] >= T["gate_sample_min"],
520
+ f"闸门裁决样本 {gate['decisions_total']} 条 {gate['decisions']}"
521
+ f"(下限 {T['gate_sample_min']})"))
522
+
523
+ # ---- 记忆动词协议 v1 静态对账(声明 ↔ MCP 面实现,纯源码事实、不连库)----
524
+ # 与 G1 的分工:G1 对账**数据值域**,这里对账**动词面**——两者都是
525
+ # 「声明了没做 / 做了没说」的前置红灯,属结构性不变量(FAIL 级,fail-closed)。
526
+ from . import protocol as _proto
527
+ pa = _proto.audit()
528
+ checks.append(_ck("protocol.op.extension_surface", "WARN", True,
529
+ f"协议 v{pa['protocol_version']} 冻结面={pa['declared']}"
530
+ f"(live {len(pa['live'])} / reserved {len(pa['reserved'])});"
531
+ f"MCP 面另有 {len(pa['extension_ops'])} 个扩展 op 不属协议面"
532
+ f"(文档一致性由 cogmap 门禁承担)"))
533
+ checks.append(_ck("protocol.verb.implemented", "FAIL",
534
+ not pa["missing_impl"],
535
+ f"声明为 live 的动词 {pa['live']} 均有实现分支"
536
+ if not pa["missing_impl"] else
537
+ f"声明为 live 却无实现分支:{pa['missing_impl']}"))
538
+ checks.append(_ck("protocol.verb.reserved_clean", "FAIL",
539
+ not pa["reserved_leaked"],
540
+ f"reserved 动词 {pa['reserved']} 未出现实现分支"
541
+ if not pa["reserved_leaked"] else
542
+ f"reserved 动词被静默实现(须先改 status=live):"
543
+ f"{pa['reserved_leaked']}"))
544
+ checks.append(_ck("protocol.shape.declared", "FAIL",
545
+ not pa["shape_errors"],
546
+ f"{len(pa['declared'])} 个动词形状声明完备"
547
+ if not pa["shape_errors"] else
548
+ f"形状声明不完整:{pa['shape_errors']}"))
549
+
550
+ # ---- 基线不劣化(有 baseline 时才可判)----
551
+ if baseline:
552
+ checks += _regression({"mixed_ratio": cov["mixed_ratio"],
553
+ "non_canonical": edges["non_canonical"],
554
+ "dangling": edges["dangling"],
555
+ "dup_groups": dup["groups"],
556
+ "unanalyzed": un["count"]}, baseline)
557
+
558
+ fails = [c for c in checks if c["level"] == "FAIL" and not c["ok"]]
559
+ warns = [c for c in checks if c["level"] == "WARN" and not c["ok"]]
560
+ blind = [c for c in checks if c["level"] == "BLINDSPOT"]
561
+ v = "FAIL" if fails else ("WARN" if (warns or (strict and blind)) else "PASS")
562
+ return {"report_version": REPORT_VERSION, "t": t0, "elapsed_s": round(time.time() - t0, 2),
563
+ "root": os.path.abspath(root), "verdict": v,
564
+ "nodes": n, "checks": checks,
565
+ "counts": {"fail": len(fails), "warn": len(warns), "blindspot": len(blind),
566
+ "total": len(checks)},
567
+ "coverage": cov, "dup": dup, "edges": edges, "paths": paths,
568
+ "gate": gate, "reach": reach, "unanalyzed": un, "g1": g1,
569
+ "protocol": pa, "thresholds": T}
570
+
571
+
572
+ # 生效条件:对 cur 各键,baseline(或其 metrics)缺失、该键在基线为 None 或 cur 值为 None 时跳过;否则以 val > b+1e-9 判劣化,产出 level 恒为 "FAIL"、ok=not worse 的检查项;
573
+ def _regression(cur: dict, baseline: dict) -> list:
574
+ """与基线比对:单调量只准不变或改善(重复度/悬空/非规范键/混层/unanalyzed)。
575
+
576
+ 只收**单调有害量**(越大越坏);触达率等随运行时间自然增长的量不进比对,
577
+ 否则日志轮转即误报。
578
+ """
579
+ base = (baseline or {}).get("metrics") or {}
580
+ out = []
581
+ for key, val in cur.items():
582
+ b = base.get(key)
583
+ if b is None or val is None:
584
+ continue
585
+ worse = val > b + 1e-9
586
+ out.append(_ck(f"baseline.{key}", "FAIL", not worse,
587
+ f"现值 {val:.4f} vs 基线 {b:.4f}"
588
+ + ("(劣化)" if worse else "(未劣化)")))
589
+ return out
590
+
591
+
592
+ # 生效条件:rep 含 coverage/edges/dup/unanalyzed/gate/reach 子字典与 nodes 键时(全部按下标取值,缺键即抛 KeyError)返回扁平指标映射;
593
+ def metrics_of(rep: dict) -> dict:
594
+ """抽成可比对的扁平指标(--baseline 的写入面)。"""
595
+ return {"mixed_ratio": rep["coverage"]["mixed_ratio"],
596
+ "non_canonical": rep["edges"]["non_canonical"],
597
+ "dangling": rep["edges"]["dangling"],
598
+ "dup_groups": rep["dup"]["groups"],
599
+ "unanalyzed": rep["unanalyzed"]["count"],
600
+ "nodes": rep["nodes"],
601
+ "role_ratio": rep["coverage"]["role_ratio"],
602
+ "basis_ratio": rep["coverage"]["basis_ratio"],
603
+ "evidence_ratio": rep["coverage"]["evidence_ratio"],
604
+ "role_ratio_kn": rep["coverage"]["role_ratio_kn"],
605
+ "evidence_ratio_kn": rep["coverage"]["evidence_ratio_kn"],
606
+ "reach_ratio": rep["reach"]["ratio"],
607
+ "gate_decisions": rep["gate"]["decisions_total"]}
608
+
609
+
610
+ # ---------------------------- 报告 ----------------------------
611
+
612
+ # 生效条件:rep 各键齐备(按下标取值,任一键缺失抛 KeyError)时拼接为多行文本,reach.ratio 为 None 时渲染 "N/A",g1 中以 "_" 开头的键在遍历中被跳过;
613
+ def render(rep: dict) -> str:
614
+ L = []
615
+ a = L.append
616
+ a(f"== conformance v{rep['report_version']} · {rep['root']}")
617
+ a(f" verdict: {rep['verdict']} nodes={rep['nodes']} "
618
+ f"checks={rep['counts']['total']} (fail {rep['counts']['fail']} / "
619
+ f"warn {rep['counts']['warn']} / blindspot {rep['counts']['blindspot']})")
620
+ a("\n-- 断言集(FAIL=fail-closed 不变量 / WARN=健康指标只告警)--")
621
+ for c in rep["checks"]:
622
+ mark = {"FAIL": "!!", "WARN": " ?", "BLINDSPOT": " ~"}.get(c["level"], " .")
623
+ ok = "ok " if c["ok"] else "NO "
624
+ a(f" [{mark}] {ok}{c['id']}: {c['detail']}")
625
+ c = rep["coverage"]
626
+ a(f"\n-- 口径复核(9-15 基线)--")
627
+ a(f" nodes={c['nodes']} knowledge={c['knowledge']} 混层={c['mixed_layer']}"
628
+ f" ({c['mixed_ratio'] * 100:.1f}%)")
629
+ a(f" dir_mismatch={rep['paths']['layer_mismatch']} path_missing={rep['paths']['missing']}")
630
+ a(f" 覆盖率[knowledge 层·判据口径] role={c['role_ratio_kn'] * 100:.3f}%"
631
+ f" basis={c['basis_ratio_kn'] * 100:.1f}% evidence={c['evidence_ratio_kn'] * 100:.3f}%")
632
+ a(f" 覆盖率为对照[全库口径] role={c['role_ratio'] * 100:.2f}%"
633
+ f" basis={c['basis_ratio'] * 100:.1f}% evidence={c['evidence_ratio'] * 100:.2f}%"
634
+ f" state={c['state_ratio'] * 100:.1f}%")
635
+ a(f" 重复 content_hash 组={rep['dup']['groups']} 节点={rep['dup']['nodes']}"
636
+ f" 最大组={rep['dup']['largest'][:3]}")
637
+ a(f" 边 total={rep['edges']['total']} 非规范键={rep['edges']['non_canonical']}"
638
+ f" 悬空={rep['edges']['dangling']} 类型={rep['edges']['types']}")
639
+ r = rep["reach"]
640
+ a(f" 触达 distinct={r['distinct']} ratio="
641
+ + ("N/A" if r['ratio'] is None else f"{r['ratio'] * 100:.1f}%") + f" log_lines={r['lines']}")
642
+ a(f" 闸门 decisions={rep['gate']['decisions_total']} {rep['gate']['decisions']}"
643
+ f" inbox_pending={rep['gate']['inbox_pending']}")
644
+ a(f" 审计 op(尾窗 {rep['gate']['audit_tail_lines']}"
645
+ f"/{rep['gate']['audit_tail_window']} 行)={rep['gate']['audit_ops']}")
646
+ a(f" G3 unanalyzed 派生={rep['unanalyzed']['count']}"
647
+ f" ({rep['unanalyzed']['ratio'] * 100:.1f}%)")
648
+ pr = rep.get("protocol") or {}
649
+ if pr:
650
+ a("\n-- 记忆动词协议 v1 静态对账 --")
651
+ a(f" {pr['doc']} frozen={pr['frozen']} ok={pr['ok']}")
652
+ a(f" 声明={pr['declared']}")
653
+ a(f" live={pr['live']} reserved={pr['reserved']}(未实现即如实登记,不冒充)")
654
+ a(f" MCP 面 op 分支={len(pr['actual'])} 个,其中扩展能力面"
655
+ f"(不属协议 v1){len(pr['extension_ops'])} 个")
656
+ if pr["errors"]:
657
+ for e in pr["errors"]:
658
+ a(f" !! {e}")
659
+ a("\n-- G1 类型空间正交性 --")
660
+ for name, spec in rep["g1"].items():
661
+ if name.startswith("_"):
662
+ continue
663
+ a(f" [{name}] 源={spec['source']} 封闭={spec['closed']}")
664
+ a(f" 实测={spec['used']}")
665
+ if spec["undeclared_used"]:
666
+ a(f" ★未声明已用={spec['undeclared_used']}")
667
+ if spec["declared_unused"]:
668
+ a(f" 声明未用={spec['declared_unused']}")
669
+ a(f" 跨空间重叠={rep['g1']['_cross_space_overlap'] or '无'}")
670
+ a(f" 方向口径分歧={[d['literal'] for d in rep['g1']['_direction_conflicts']]}")
671
+ a(f" 已核对无分歧={[d['literal'] for d in rep['g1']['_verified_consistent']]}")
672
+ a(f" 文档滞后于代码={[d['where'] for d in rep['g1']['_doc_code_drift']]}")
673
+ a(f" 新增类型触点={rep['g1']['_new_type_touchpoints']}")
674
+ return "\n".join(L)
675
+
676
+
677
+ # 生效条件:传入对象可写属性时执行赋值 sustain_module.conformance_summary = report_summary,无返回值(None);
678
+ def register_sustain(sustain_module) -> None: # pragma: no cover
679
+ """挂点说明(供 sustain 侧最小侵入调用)。
680
+
681
+ 周期巡检**不加新 tick**:`_tick_tidy()` 已是「contextual 存量治理」的
682
+ 读侧巡检,本断言集复用同一节奏(tidy_interval),由 `report_summary(cg)`
683
+ 只取结论不落盘——避免为只读检查新增后台周期与 env 开关。
684
+ """
685
+ sustain_module.conformance_summary = report_summary
686
+
687
+
688
+ # 生效条件:root 依次取 cg_or_root.root 属性、cg_or_root 本身、_default_root()(前者为假值即回落,故 0/空串会继续回落);check 抛异常时返回 ok=False、verdict="BLINDSPOT"、error,否则返回 ok=(verdict!="FAIL") 与 fail/warn/blindspot/failed_ids/t;
689
+ def report_summary(cg_or_root) -> dict:
690
+ """给常驻循环用的**轻量**结论(不渲染全文、不写盘):verdict + 计数。"""
691
+ root = getattr(cg_or_root, "root", None) or cg_or_root or _default_root()
692
+ try:
693
+ rep = check(root, check_paths=False)
694
+ except Exception as e: # noqa: BLE001
695
+ return {"ok": False, "verdict": "BLINDSPOT", "error": f"{type(e).__name__}: {e}"}
696
+ return {"ok": rep["verdict"] != "FAIL", "verdict": rep["verdict"],
697
+ "fail": rep["counts"]["fail"], "warn": rep["counts"]["warn"],
698
+ "blindspot": rep["counts"]["blindspot"],
699
+ "failed_ids": [c["id"] for c in rep["checks"]
700
+ if c["level"] == "FAIL" and not c["ok"]],
701
+ "t": rep["t"]}
702
+
703
+
704
+ # 生效条件:argv 为 None 时 argparse 从 sys.argv 取值,--root 缺失或为假值回落 _default_root();check 抛 OSError/ValueError(如索引不可读)时打印 BLINDSPOT 并返回 2,否则按 --write-baseline/--json 写盘后返回 0(verdict≠"FAIL")或 1("FAIL");
705
+ def main(argv=None) -> int:
706
+ p = argparse.ArgumentParser(prog="python -m md_cg.conformance",
707
+ description="数据健康不变量断言集(只读,零写入)")
708
+ p.add_argument("--root", default=None,
709
+ help="认知图根(默认 MDCG_ROOT > paths.json > 用户级状态根 data/mdcg)")
710
+ p.add_argument("--json", dest="json_out", default=None)
711
+ p.add_argument("--baseline", default=None, help="基线报告 json(比对不劣化)")
712
+ p.add_argument("--write-baseline", default=None, help="把本次指标写成新基线")
713
+ p.add_argument("--no-path-check", action="store_true", help="不查盘上文件是否存在")
714
+ p.add_argument("--strict", action="store_true", help="BLINDSPOT 也视为非 PASS")
715
+ a = p.parse_args(argv)
716
+
717
+ root = a.root or _default_root()
718
+ baseline = None
719
+ if a.baseline:
720
+ with open(a.baseline, encoding="utf-8") as f:
721
+ baseline = json.load(f)
722
+ try:
723
+ rep = check(root, check_paths=not a.no_path_check,
724
+ baseline=baseline, strict=a.strict)
725
+ except (OSError, ValueError) as e:
726
+ # 数据源不可读 = BLINDSPOT(如实上报),绝不打印「通过」
727
+ print(f"== conformance v{REPORT_VERSION} · {os.path.abspath(root)}")
728
+ print(f" verdict: BLINDSPOT —— 索引不可读: {type(e).__name__}: {e}")
729
+ print(f" 缺失维度: 数据源({INDEX_FILE});修复后重跑,勿以本结果为「通过」。")
730
+ return 2
731
+ print(render(rep))
732
+ if a.write_baseline:
733
+ with open(a.write_baseline, "w", encoding="utf-8") as f:
734
+ json.dump({"report_version": REPORT_VERSION, "t": rep["t"],
735
+ "root": rep["root"], "metrics": metrics_of(rep)},
736
+ f, ensure_ascii=False, indent=2)
737
+ print(f"\n 基线已写入: {a.write_baseline}")
738
+ if a.json_out:
739
+ with open(a.json_out, "w", encoding="utf-8") as f:
740
+ json.dump(rep, f, ensure_ascii=False, indent=2, default=str)
741
+ print(f" 报告已写入: {a.json_out}")
742
+ return 0 if rep["verdict"] != "FAIL" else 1
743
+
744
+
745
+ if __name__ == "__main__":
746
+ if hasattr(sys.stdout, "reconfigure"):
747
+ sys.stdout.reconfigure(encoding="utf-8", errors="replace")
748
748
  sys.exit(main())