@furongjun1999/dsh-memory 0.8.1 → 0.9.6

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 (714) hide show
  1. package/README.md +662 -659
  2. package/codebuddy/README.md +1 -1
  3. package/data/policy.json +17 -6
  4. package/docs/README.md +18 -2
  5. package/docs/discipline/harnesses.yaml +1 -1
  6. package/docs/discipline/templates/spec.txt.tmpl +23 -0
  7. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203.md +179 -0
  8. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203_/347/201/265/346/236/242/351/200/202/351/205/215.md +45 -0
  9. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203_/350/207/252/346/243/200/346/270/205/345/215/225.md +69 -0
  10. package/dsh/README.md +1 -1
  11. package/dsh/cordis.yml.example +1 -1
  12. package/hive/README.md +705 -0
  13. package/hive/id_charset_blocks.txt +147 -0
  14. package/lib/bridge.d.ts +3 -0
  15. package/lib/bridge.js +32 -11
  16. package/lib/cli.js +14 -17
  17. package/lib/hooks.d.ts +18 -3
  18. package/lib/hooks.js +147 -18
  19. package/lib/index.d.ts +2 -2
  20. package/lib/index.js +18 -4
  21. package/lib/init.js +21 -21
  22. package/lib/lib/datapath.d.ts +56 -0
  23. package/lib/lib/datapath.js +102 -9
  24. package/lib/lib/hook_audit.d.ts +0 -1
  25. package/lib/lib/hook_audit.js +13 -1
  26. package/lib/lib/mdcg_client.d.ts +4 -1
  27. package/lib/lib/mdcg_client.js +10 -2
  28. package/lib/lib/mutual.js +61 -15
  29. package/lib/lib/prompt_safety.js +16 -1
  30. package/lib/lib/roleplay_web.js +30 -2
  31. package/lib/lib/token_store.d.ts +25 -6
  32. package/lib/lib/token_store.js +224 -33
  33. package/lib/tools.d.ts +8 -2
  34. package/lib/tools.js +22 -3
  35. package/md_cg/_guard_kit.py +121 -0
  36. package/md_cg/admission.py +718 -718
  37. package/md_cg/anchor.py +114 -0
  38. package/md_cg/audit.py +22 -5
  39. package/md_cg/autonomy.py +433 -288
  40. package/md_cg/autonomy_modes.py +781 -642
  41. package/md_cg/bench_beir_bm25.py +154 -0
  42. package/md_cg/bench_beir_scifact.py +170 -0
  43. package/md_cg/bench_bm25_blockmax.py +134 -0
  44. package/md_cg/bench_bm25_incremental.py +246 -0
  45. package/md_cg/bench_ccg_heading.py +118 -0
  46. package/md_cg/bench_csre_correctness.py +145 -0
  47. package/md_cg/bench_excerpt_budget.py +94 -0
  48. package/md_cg/bench_fuzzy_substrings.py +299 -0
  49. package/md_cg/bench_memory_rsi.py +358 -0
  50. package/md_cg/bench_memory_rsi_latency.py +82 -0
  51. package/md_cg/bench_memory_rsi_public.py +116 -0
  52. package/md_cg/bench_memory_rsi_tools.py +229 -0
  53. package/md_cg/bench_rrf_candidates.py +212 -0
  54. package/md_cg/bench_rrf_public.py +100 -0
  55. package/md_cg/bench_text_projections.py +221 -0
  56. package/md_cg/bench_timeanchor.py +357 -0
  57. package/md_cg/bm25.py +601 -0
  58. package/md_cg/branches.py +404 -327
  59. package/md_cg/build_postings.py +74 -73
  60. package/md_cg/ccgc.py +4 -2
  61. package/md_cg/chain.py +572 -379
  62. package/md_cg/coldverify.py +531 -292
  63. package/md_cg/condaccept.py +263 -0
  64. package/md_cg/condgate.py +308 -0
  65. package/md_cg/config_registry.py +329 -0
  66. package/md_cg/config_registry_bulk.py +482 -0
  67. package/md_cg/config_registry_guard.py +487 -0
  68. package/md_cg/config_render.py +354 -0
  69. package/md_cg/config_validate.py +455 -0
  70. package/md_cg/conformance.py +21 -0
  71. package/md_cg/conformance_core.py +753 -0
  72. package/md_cg/consistency.py +1278 -955
  73. package/md_cg/consolidate.py +180 -20
  74. package/md_cg/crypto.py +794 -472
  75. package/md_cg/datapath.py +137 -12
  76. package/md_cg/eval_common.py +522 -575
  77. package/md_cg/evidence.py +946 -585
  78. package/md_cg/evidence_delivery.py +101 -0
  79. package/md_cg/experience_consolidation.py +317 -0
  80. package/md_cg/export.py +329 -222
  81. package/md_cg/forgetting.py +1050 -922
  82. package/md_cg/freshness.py +601 -548
  83. package/md_cg/fsutil.py +1120 -824
  84. package/md_cg/goal_gen.py +458 -0
  85. package/md_cg/hotcache.py +107 -9
  86. package/md_cg/hyperedge.py +14 -3
  87. package/md_cg/identity.py +573 -391
  88. package/md_cg/imgskill.py +1712 -0
  89. package/md_cg/insight.py +540 -521
  90. package/md_cg/interface_schema.py +146 -0
  91. package/md_cg/interop.py +20 -0
  92. package/md_cg/judgment_manifest.py +24 -1
  93. package/md_cg/lifecycle.py +86 -5
  94. package/md_cg/links.py +27 -6
  95. package/md_cg/logref.py +332 -327
  96. package/md_cg/mcp_server.py +5227 -4449
  97. package/md_cg/mdcg.py +1301 -203
  98. package/md_cg/mdcos.py +7104 -5440
  99. package/md_cg/memory_rsi.py +308 -0
  100. package/md_cg/metacognition.py +726 -591
  101. package/md_cg/nodefile.py +151 -3
  102. package/md_cg/op_table.py +1128 -0
  103. package/md_cg/postings.py +524 -300
  104. package/md_cg/predict.py +4 -1
  105. package/md_cg/probe_memory_rsi.py +95 -0
  106. package/md_cg/probe_memory_rsi_mcp.py +66 -0
  107. package/md_cg/protect.py +188 -28
  108. package/md_cg/protocol.py +492 -411
  109. package/md_cg/provenance.py +7 -1
  110. package/md_cg/qmd.py +477 -0
  111. package/md_cg/qmd_llm.py +334 -0
  112. package/md_cg/query_excerpt.py +171 -0
  113. package/md_cg/queue_health.py +130 -0
  114. package/md_cg/reach.py +470 -453
  115. package/md_cg/readcache.py +115 -3
  116. package/md_cg/reconcile.py +239 -228
  117. package/md_cg/refindex.py +1191 -1042
  118. package/md_cg/refine.py +12 -3
  119. package/md_cg/retrieve.py +128 -0
  120. package/md_cg/review_cli.py +204 -26
  121. package/md_cg/revise.py +140 -0
  122. package/md_cg/rollback.py +256 -19
  123. package/md_cg/rollback_cli.py +21 -1
  124. package/md_cg/rotate.py +347 -0
  125. package/md_cg/routing.py +62 -1
  126. package/md_cg/rrf_candidates.py +204 -0
  127. package/md_cg/run_tests.py +19 -1
  128. package/md_cg/scrub.py +177 -23
  129. package/md_cg/security.py +269 -17
  130. package/md_cg/self_state.py +1053 -1029
  131. package/md_cg/self_surface.py +50 -0
  132. package/md_cg/semantic/canonical.py +1 -1
  133. package/md_cg/semantic/export_en_zh_map.py +2 -2
  134. package/md_cg/semantic/zh_en_atoms.py +2 -0
  135. package/md_cg/session5.py +106 -0
  136. package/md_cg/signer.py +76 -2
  137. package/md_cg/sleep.py +1779 -1583
  138. package/md_cg/sources.py +273 -15
  139. package/md_cg/state_events.py +75 -10
  140. package/md_cg/state_slots.py +312 -221
  141. package/md_cg/stg.py +82 -16
  142. package/md_cg/stgidx.py +537 -281
  143. package/md_cg/subgraph.py +851 -729
  144. package/md_cg/sustain.py +458 -19
  145. package/md_cg/task_memory.py +367 -0
  146. package/md_cg/test_action_derive.py +210 -203
  147. package/md_cg/test_audit_heartbeat_20261015.py +417 -0
  148. package/md_cg/test_audit_protection_20261015.py +483 -0
  149. package/md_cg/test_audit_rotate_parity.py +280 -0
  150. package/md_cg/test_audit_state_20261015.py +253 -0
  151. package/md_cg/test_audit_write_20261015.py +161 -0
  152. package/md_cg/test_auto_defaults.py +43 -4
  153. package/md_cg/test_autonomy_emotion.py +328 -0
  154. package/md_cg/test_autonomy_modes.py +43 -3
  155. package/md_cg/test_b1_foreign_read.py +245 -0
  156. package/md_cg/test_bm25.py +438 -0
  157. package/md_cg/test_bm25_hydration_refill.py +265 -0
  158. package/md_cg/test_bm25_incremental.py +241 -0
  159. package/md_cg/test_bm25_incremental_mutations.py +160 -0
  160. package/md_cg/test_bm25_mutations.py +205 -0
  161. package/md_cg/test_bm25_pool_view.py +196 -0
  162. package/md_cg/test_boot_openblas_guard.py +218 -197
  163. package/md_cg/test_boundary_hit.py +1 -1
  164. package/md_cg/test_branches_sensitivity.py +375 -0
  165. package/md_cg/test_c8_search_rrf_gates.py +1 -1
  166. package/md_cg/test_canonical_timezones.py +211 -0
  167. package/md_cg/test_ccg_heading_parser.py +73 -0
  168. package/md_cg/test_chain_best_first.py +403 -0
  169. package/md_cg/test_chain_candidate_scope.py +227 -0
  170. package/md_cg/test_cn_recall_grams.py +206 -0
  171. package/md_cg/test_coldverify_drain.py +127 -0
  172. package/md_cg/test_condaccept.py +156 -0
  173. package/md_cg/test_condgate.py +141 -0
  174. package/md_cg/test_config_registry.py +55 -0
  175. package/md_cg/test_crypto_rotate.py +257 -0
  176. package/md_cg/test_csre_correctness.py +297 -0
  177. package/md_cg/test_csre_index_import_guard.py +161 -0
  178. package/md_cg/test_csre_mutations.py +34 -0
  179. package/md_cg/test_csre_session.py +69 -0
  180. package/md_cg/test_curiosity_budget.py +468 -0
  181. package/md_cg/test_d17_autostart_toolface.py +453 -0
  182. package/md_cg/test_datapath_tilde_home.py +271 -0
  183. package/md_cg/test_derived_cache_generations.py +256 -0
  184. package/md_cg/test_evidence_delivery_compact.py +54 -0
  185. package/md_cg/test_exact_text_cache.py +191 -0
  186. package/md_cg/test_excerpt_budget.py +188 -0
  187. package/md_cg/test_experience_consolidation.py +112 -0
  188. package/md_cg/test_export_default_collision.py +138 -0
  189. package/md_cg/test_export_snapshots.py +322 -0
  190. package/md_cg/test_fuzzy_substring_equivalence.py +127 -0
  191. package/md_cg/test_gain_gate.py +16 -5
  192. package/md_cg/test_goal_gen.py +355 -0
  193. package/md_cg/test_h2_session_view_norm.py +251 -233
  194. package/md_cg/test_h4_sustain_snapshot.py +1490 -1387
  195. package/md_cg/test_heartbeat_ledger.py +557 -0
  196. package/md_cg/test_hierarchy_audit_graph.py +237 -0
  197. package/md_cg/test_i50c_meta_passthrough.py +628 -608
  198. package/md_cg/test_i50e_readside_protection.py +6 -4
  199. package/md_cg/test_identity_attribution.py +96 -2
  200. package/md_cg/test_identity_contract.py +329 -0
  201. package/md_cg/test_imgskill.py +1444 -0
  202. package/md_cg/test_index_snapshot_shape.py +240 -0
  203. package/md_cg/test_interop_judgment.py +258 -228
  204. package/md_cg/test_issue111_gate_order.py +77 -0
  205. package/md_cg/test_issue111_scoring_contract.py +87 -0
  206. package/md_cg/test_issue121_calibration_bounds.py +293 -0
  207. package/md_cg/test_issue128_session_env_authority.py +246 -0
  208. package/md_cg/test_issue130_rrf_rank_credibility.py +217 -0
  209. package/md_cg/test_issue131_postings_content_staleness.py +424 -0
  210. package/md_cg/test_issue145_sleep_no_silent_rollback.py +168 -0
  211. package/md_cg/test_issue146_frontmatter_quarantine.py +428 -0
  212. package/md_cg/test_issue147_pack_id_escape.py +378 -0
  213. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -0
  214. package/md_cg/test_issue149_accel_default_face.py +249 -0
  215. package/md_cg/test_issue150_empty_query_terms.py +328 -0
  216. package/md_cg/test_issue151_153_157_write_cache_index.py +152 -0
  217. package/md_cg/test_issue151b_base_add_importance_guard.py +166 -0
  218. package/md_cg/test_issue152_sealed_postings.py +309 -0
  219. package/md_cg/test_issue152b_decrypt_cache.py +218 -0
  220. package/md_cg/test_issue153b_cache_alias_and_canon.py +236 -0
  221. package/md_cg/test_issue153b_index_generation_invalidation.py +143 -0
  222. package/md_cg/test_issue157b_index_remainder.py +344 -0
  223. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -0
  224. package/md_cg/test_issue190_tidy_idempotent.py +806 -0
  225. package/md_cg/test_issue191_import_trust.py +382 -0
  226. package/md_cg/test_issue192_move_layer_indices_guard.py +258 -0
  227. package/md_cg/test_issue193_consistency_knowledge_guard.py +524 -0
  228. package/md_cg/test_issue193_write_scope.py +378 -0
  229. package/md_cg/test_issue197_rank_credibility_property.py +201 -0
  230. package/md_cg/test_issue211_export_target.py +325 -0
  231. package/md_cg/test_issue212_writeface_gaps.py +349 -0
  232. package/md_cg/test_issue214_reject_sensitivity.py +267 -0
  233. package/md_cg/test_issue215_condition_source_gap.py +272 -0
  234. package/md_cg/test_issue216_clash_routes.py +214 -0
  235. package/md_cg/test_issue217_slot_routes.py +248 -0
  236. package/md_cg/test_issue218_postcondition_value_blind.py +222 -0
  237. package/md_cg/test_issue225_consistency_torn_log.py +433 -0
  238. package/md_cg/test_issue245_swarm_traversal.py +366 -0
  239. package/md_cg/test_issue258_pack_sensitivity.py +468 -0
  240. package/md_cg/test_issue265_coldverify_multiproc.py +438 -0
  241. package/md_cg/test_issue274_read_node_id_none.py +341 -0
  242. package/md_cg/test_issue275_layer_param.py +250 -0
  243. package/md_cg/test_issue277_node_id_traversal.py +384 -0
  244. package/md_cg/test_issue278_neg_separated_tension.py +271 -0
  245. package/md_cg/test_issue278_neg_window.py +294 -0
  246. package/md_cg/test_issue278_negative_layering.py +83 -0
  247. package/md_cg/test_issue279_signers_path_guard.py +652 -0
  248. package/md_cg/test_issue284_skip_not_pass.py +291 -0
  249. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -0
  250. package/md_cg/test_issue295_sleep_root_binding.py +589 -0
  251. package/md_cg/test_issue297_rewrite_sensitivity.py +454 -0
  252. package/md_cg/test_issue298_consistency_ledger_sensitivity.py +421 -0
  253. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -0
  254. package/md_cg/test_issue303_design_boundaries.py +262 -0
  255. package/md_cg/test_issue313_writelimit_sensitivity.py +404 -0
  256. package/md_cg/test_issue315_merge_branch_sensitivity.py +384 -0
  257. package/md_cg/test_issue315_sensitivity_passthrough_guard.py +514 -0
  258. package/md_cg/test_issue319_tenant_unregistered_bypass.py +257 -0
  259. package/md_cg/test_issue320_vstate_requires_verify.py +279 -0
  260. package/md_cg/test_issue321_mcp_deep_json.py +305 -0
  261. package/md_cg/test_issue322_node_write_lock.py +727 -0
  262. package/md_cg/test_issue323_aggregate_segment_boundary.py +365 -0
  263. package/md_cg/test_issue324_write_size_fields.py +215 -0
  264. package/md_cg/test_issue325_audit_poison.py +230 -0
  265. package/md_cg/test_issue326_append_jsonl_oserror.py +464 -0
  266. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -0
  267. package/md_cg/test_issue326_key_perms.py +355 -0
  268. package/md_cg/test_issue326_twin_parser_parity.py +323 -0
  269. package/md_cg/test_issue326_vm_call_frame.py +569 -0
  270. package/md_cg/test_issue345_writelimit_effective_sens.py +234 -0
  271. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -0
  272. package/md_cg/test_issue346_review_overwrite_guard.py +509 -0
  273. package/md_cg/test_issue348_insight_verify_op.py +200 -0
  274. package/md_cg/test_issue348_merge_rmw_lock.py +345 -0
  275. package/md_cg/test_issue350_casefold_collision.py +236 -0
  276. package/md_cg/test_issue351_ingest_root_fallback.py +202 -0
  277. package/md_cg/test_issue352_imgaudit.py +418 -0
  278. package/md_cg/test_issue352_pathsjson.py +537 -0
  279. package/md_cg/test_issue352_refindex.py +412 -0
  280. package/md_cg/test_issue352_rollback.py +604 -0
  281. package/md_cg/test_issue352_vstateinherit.py +196 -0
  282. package/md_cg/test_issue354_p1_writelimit_type.py +522 -0
  283. package/md_cg/test_issue354_p2_datapath_clock.py +381 -0
  284. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -0
  285. package/md_cg/test_issue354_rust_index_containment.py +571 -0
  286. package/md_cg/test_issue354_rust_wal_containment.py +606 -0
  287. package/md_cg/test_issue358_truncation_observable.py +247 -0
  288. package/md_cg/test_issue360_tidy_private_excerpt.py +196 -0
  289. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -0
  290. package/md_cg/test_issue362_neg_condition.py +468 -0
  291. package/md_cg/test_issue363_lexical_idf.py +275 -0
  292. package/md_cg/test_issue370_readcache_assembly.py +488 -0
  293. package/md_cg/test_issue375_state_slot_retire.py +325 -0
  294. package/md_cg/test_issue376_heartbeat_failed.py +293 -0
  295. package/md_cg/test_issue377_layer_protect_stamp.py +324 -0
  296. package/md_cg/test_issue378_protected_floor.py +310 -0
  297. package/md_cg/test_issue383_state_event_write_gate.py +462 -0
  298. package/md_cg/test_issue397_sens_eff_wiring.py +435 -0
  299. package/md_cg/test_issue398_toolface_op_parity.py +511 -0
  300. package/md_cg/test_issue399_hive_json_shape.py +317 -0
  301. package/md_cg/test_issue400_hive_dirty_args.py +450 -0
  302. package/md_cg/test_issue401_wisdom_codegen.py +295 -0
  303. package/md_cg/test_issue404_heal_receipt.py +390 -0
  304. package/md_cg/test_issue405_git_pathspec.py +333 -0
  305. package/md_cg/test_issue408_eface_registry.py +291 -0
  306. package/md_cg/test_issue409_compact_index_completeness.py +509 -0
  307. package/md_cg/test_issue410_verify_demote_write.py +366 -0
  308. package/md_cg/test_issue411_scrub_idempotence.py +575 -0
  309. package/md_cg/test_issue412_discipline_producer_parity.py +312 -0
  310. package/md_cg/test_issue413_preimage_failclosed.py +239 -0
  311. package/md_cg/test_issue413_preimage_twin.py +340 -0
  312. package/md_cg/test_issue414_write_args_parity.py +613 -0
  313. package/md_cg/test_issue415_deps_gate_probe.py +358 -0
  314. package/md_cg/test_issue416_entry_key_subset.py +525 -0
  315. package/md_cg/test_issue417_twophase_merge_landed.py +423 -0
  316. package/md_cg/test_issue418_identity_role_type_gate.py +188 -0
  317. package/md_cg/test_issue418_role_type_gate.py +265 -0
  318. package/md_cg/test_issue419_pii_redaction.py +642 -0
  319. package/md_cg/test_issue424_merge_confirm_sensitivity.py +381 -0
  320. package/md_cg/test_issue425_ingest_library_path.py +331 -0
  321. package/md_cg/test_issue426a_dedup_receipt.py +242 -0
  322. package/md_cg/test_issue426b_root_clash_invisible.py +270 -0
  323. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -0
  324. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -0
  325. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -0
  326. package/md_cg/test_issue427_serve_status_shape.py +191 -0
  327. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -0
  328. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -0
  329. package/md_cg/test_issue434_435_float_gate.py +90 -0
  330. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -0
  331. package/md_cg/test_issue43_default_policy.py +13 -4
  332. package/md_cg/test_issue443a_state_event_length_gate.py +94 -0
  333. package/md_cg/test_issue443b_audit_record_length_gate.py +83 -0
  334. package/md_cg/test_issue443c_self_state_imgskill_length_gate.py +77 -0
  335. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -0
  336. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -0
  337. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -0
  338. package/md_cg/test_issue446_is_encrypted_envelope.py +166 -0
  339. package/md_cg/test_issue447_recent_sens_failclosed.py +270 -0
  340. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -0
  341. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -0
  342. package/md_cg/test_issue451_audit_actor.py +313 -0
  343. package/md_cg/test_issue452_ingest_root_hint.py +238 -0
  344. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -0
  345. package/md_cg/test_issue463_ghost_prune_guard.py +259 -0
  346. package/md_cg/test_issue466_basis_registry.py +469 -0
  347. package/md_cg/test_issue467_identity_sensitivity.py +204 -0
  348. package/md_cg/test_issue467_identity_sensitivity_parity.py +361 -0
  349. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -0
  350. package/md_cg/test_issue470_wal_event_durable.py +427 -0
  351. package/md_cg/test_issue471_identity_readable.py +137 -0
  352. package/md_cg/test_issue472_audit_chain.py +91 -0
  353. package/md_cg/test_issue472_prune_ledger.py +106 -0
  354. package/md_cg/test_issue472_rollback_degraded.py +82 -0
  355. package/md_cg/test_issue491_compose_sandbox.py +460 -0
  356. package/md_cg/test_issue492_dup_readout_opt_in.py +292 -0
  357. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -0
  358. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -0
  359. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -0
  360. package/md_cg/test_issue522_review_record_sensitivity.py +267 -0
  361. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -0
  362. package/md_cg/test_issue525_read_null_semantics.py +52 -0
  363. package/md_cg/test_issue538_hook_condition_space.py +97 -0
  364. package/md_cg/test_issue540_path_guard_whitespace.py +126 -0
  365. package/md_cg/test_issue541_tidy_protect_gate.py +141 -0
  366. package/md_cg/test_issue542_tenant_root_same.py +153 -0
  367. package/md_cg/test_issue543_issue_authorization.py +147 -0
  368. package/md_cg/test_issue544_sandbox_reflection_gate.py +175 -0
  369. package/md_cg/test_issue545_charset_vs_size_diagnostic.py +77 -0
  370. package/md_cg/test_issue546_ledger_concurrency.py +81 -0
  371. package/md_cg/test_issue547_append_jsonl_whitelist.py +115 -0
  372. package/md_cg/test_issue547_audit_durable.py +96 -0
  373. package/md_cg/test_issue549_durable_append.py +143 -0
  374. package/md_cg/test_issue557_r1_credential_value_forms.py +76 -0
  375. package/md_cg/test_issue557_r2_write_entries_size_gate.py +84 -0
  376. package/md_cg/test_issue557_r3_pem_block_redaction.py +75 -0
  377. package/md_cg/test_issue559_refine_prefix.py +70 -0
  378. package/md_cg/test_issue561_pending_review.py +109 -0
  379. package/md_cg/test_issue66_scrub_semantics.py +107 -0
  380. package/md_cg/test_issue67_scrub_control_pool.py +233 -0
  381. package/md_cg/test_issue69_audit_boundary.py +129 -0
  382. package/md_cg/test_issue71_queue_backlog.py +377 -0
  383. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -0
  384. package/md_cg/test_issue73_doc_chapter_refs.py +326 -0
  385. package/md_cg/test_issue75_neural_failure.py +582 -0
  386. package/md_cg/test_issue78_export_concurrency.py +334 -0
  387. package/md_cg/test_issue80_residual_flush.py +169 -0
  388. package/md_cg/test_issue82_credential_rules.py +271 -0
  389. package/md_cg/test_issue82_layer_and_size.py +120 -0
  390. package/md_cg/test_issue84_portability.py +95 -0
  391. package/md_cg/test_issue85_export_overwrite.py +113 -0
  392. package/md_cg/test_issue86_runtime_revoke.py +110 -0
  393. package/md_cg/test_issue87_default_sensitivity_single.py +201 -0
  394. package/md_cg/test_issue88_conclusion_face.py +280 -0
  395. package/md_cg/test_issue88_execution_conflicts.py +87 -0
  396. package/md_cg/test_issue89_zero_score.py +169 -0
  397. package/md_cg/test_issue89a_score_cap_tiebreak.py +279 -0
  398. package/md_cg/test_issue91_verifier_sandbox.py +314 -0
  399. package/md_cg/test_issue91_verifier_timeout.py +528 -0
  400. package/md_cg/test_issue93_remember_redaction.py +282 -0
  401. package/md_cg/test_issue96_key_fallback.py +102 -0
  402. package/md_cg/test_issue98_tenant_root.py +104 -0
  403. package/md_cg/test_jsonl_commit_watermark.py +221 -0
  404. package/md_cg/test_live_validity_cache.py +256 -0
  405. package/md_cg/test_logref.py +32 -0
  406. package/md_cg/test_mcp_call_argument_types.py +99 -0
  407. package/md_cg/test_md_access_parity.py +80 -5
  408. package/md_cg/test_md_cg_no_hive_dep.py +140 -0
  409. package/md_cg/test_memory_rsi.py +215 -0
  410. package/md_cg/test_memory_rsi_adversarial.py +91 -0
  411. package/md_cg/test_mode_parity.py +1413 -1393
  412. package/md_cg/test_mutation_residue.py +120 -0
  413. package/md_cg/test_mutation_rollback.py +62 -32
  414. package/md_cg/test_n123_derive_expiry_chain.py +10 -5
  415. package/md_cg/test_n130_verify_falsified_protect.py +185 -185
  416. package/md_cg/test_n209_verify_write_face_gates.py +7 -2
  417. package/md_cg/test_n230_dirty_replay.py +52 -9
  418. package/md_cg/test_n62_tenant_bind_failclosed.py +3 -3
  419. package/md_cg/test_neg_coverage_budget.py +500 -0
  420. package/md_cg/test_neg_tail_honesty.py +79 -9
  421. package/md_cg/test_p0.py +16 -2
  422. package/md_cg/test_p14_root_fallback.py +373 -0
  423. package/md_cg/test_p1x_ref_root.py +47 -10
  424. package/md_cg/test_p21_tokens.py +2 -1
  425. package/md_cg/test_p24_evidence.py +232 -227
  426. package/md_cg/test_p26_refindex.py +20 -3
  427. package/md_cg/test_p27_docindex.py +16 -1
  428. package/md_cg/test_p28_refcheck.py +45 -24
  429. package/md_cg/test_p29_session_ingest_export.py +6 -0
  430. package/md_cg/test_p2_mcp.py +474 -453
  431. package/md_cg/test_p2_six_elements.py +14 -1
  432. package/md_cg/test_p3.py +370 -261
  433. package/md_cg/test_p33_ccg_wiring.py +9 -2
  434. package/md_cg/test_p3_legacy_closure.py +6 -1
  435. package/md_cg/test_p40_refine_worklist.py +5 -2
  436. package/md_cg/test_p47_session_view.py +25 -9
  437. package/md_cg/test_p4_freshness.py +8 -1
  438. package/md_cg/test_p83_jsonrpc_parse_error.py +124 -0
  439. package/md_cg/test_p9c_dedup_hints.py +7 -2
  440. package/md_cg/test_policy_required_ccg.py +12 -0
  441. package/md_cg/test_postings_digest_memo.py +139 -0
  442. package/md_cg/test_predict_beta.py +138 -135
  443. package/md_cg/test_qmd.py +500 -0
  444. package/md_cg/test_query_excerpt.py +209 -0
  445. package/md_cg/test_reach.py +456 -378
  446. package/md_cg/test_reach_snapshot_admission.py +218 -0
  447. package/md_cg/test_readcache_prodpath.py +4 -0
  448. package/md_cg/test_recall_face_guards.py +854 -812
  449. package/md_cg/test_recall_metadata.py +422 -0
  450. package/md_cg/test_retr_s5.py +104 -5
  451. package/md_cg/test_retr_score_once.py +14 -2
  452. package/md_cg/test_review_cli_attribution.py +11 -7
  453. package/md_cg/test_review_queue_batch.py +123 -0
  454. package/md_cg/test_review_queue_index.py +130 -0
  455. package/md_cg/test_rrf_candidates.py +292 -0
  456. package/md_cg/test_rrf_qualified_topk.py +214 -0
  457. package/md_cg/test_rrf_unique_votes.py +218 -0
  458. package/md_cg/test_s1_ast_judge.py +110 -0
  459. package/md_cg/test_scrub_ledger.py +413 -0
  460. package/md_cg/test_security_audit_b26.py +34 -3
  461. package/md_cg/test_security_audit_v21.py +1 -2
  462. package/md_cg/test_sensitivity_predicate_single_point.py +184 -0
  463. package/md_cg/test_session5_identity.py +93 -0
  464. package/md_cg/test_session_attribution_consistency.py +813 -0
  465. package/md_cg/test_session_identity_tristate.py +486 -0
  466. package/md_cg/test_sleep_p1.py +35 -3
  467. package/md_cg/test_state_event_op.py +8 -1
  468. package/md_cg/test_state_projection_streaming.py +136 -0
  469. package/md_cg/test_stg_interval_candidates.py +280 -0
  470. package/md_cg/test_stg_time_blocks.py +239 -0
  471. package/md_cg/test_stgidx_index_parity.py +16 -12
  472. package/md_cg/test_subgraph_bounded_bfs.py +227 -0
  473. package/md_cg/test_sustain_bounded.py +30 -2
  474. package/md_cg/test_task_memory.py +394 -0
  475. package/md_cg/test_text_projection_mutations.py +101 -0
  476. package/md_cg/test_time_anchor.py +421 -0
  477. package/md_cg/test_time_core_lint.py +1024 -975
  478. package/md_cg/test_tool_face.py +200 -189
  479. package/md_cg/test_trust_bounded_frontier.py +248 -0
  480. package/md_cg/test_trust_edge_reachability.py +405 -0
  481. package/md_cg/test_w5_path_fingerprint.py +381 -0
  482. package/md_cg/test_w7_redlines.py +659 -0
  483. package/md_cg/test_write_return_shape.py +919 -0
  484. package/md_cg/test_writepipe.py +5 -3
  485. package/md_cg/timeanchor.py +534 -0
  486. package/md_cg/tokens.py +68 -5
  487. package/md_cg/tool_face.py +273 -260
  488. package/md_cg/trust.py +110 -26
  489. package/md_cg/twophase.py +74 -2
  490. package/md_cg/weights.py +642 -638
  491. package/md_cg/whitebox.py +9 -0
  492. package/md_cg/whitebox_kb/aeis_core/core.py +5026 -5026
  493. package/md_cg/whitebox_kb/wisdom/chat_engine.py +1504 -1506
  494. package/md_cg/whitebox_kb/wisdom/code_compose.py +876 -837
  495. package/md_cg/whitebox_kb/wisdom/compiler_code_units.py +3040 -3033
  496. package/md_cg/whitebox_kb/wisdom/compose_engine.py +3 -2
  497. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +22 -2
  498. package/md_cg/whitebox_kb/wisdom/core/parser.py +17 -0
  499. package/md_cg/whitebox_kb/wisdom/csre.py +412 -264
  500. package/md_cg/whitebox_kb/wisdom/csre_session.py +97 -0
  501. package/md_cg/whitebox_kb/wisdom/md_access.py +23 -3
  502. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +21 -0
  503. package/md_cg/whitebox_kb/wisdom/mini_python.py +44 -7
  504. package/md_cg/whitebox_kb/wisdom/navigate.py +249 -248
  505. package/md_cg/whitebox_kb/wisdom/net_units.py +12 -7
  506. package/md_cg/whitebox_kb/wisdom/neural_retrieve.py +100 -10
  507. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +13 -7
  508. package/md_cg/whitebox_kb/wisdom/test_ecosystem_assembly.py +158 -158
  509. package/md_cg/whitebox_kb/wisdom/test_safe_module_proxy.py +147 -0
  510. package/md_cg/whitebox_kb/wisdom/verifier.py +1918 -1297
  511. package/md_cg/writelimit.py +584 -390
  512. package/md_cg/writepipe.py +587 -76
  513. package/package.json +13 -9
  514. package/src/bridge.ts +34 -11
  515. package/src/cli.ts +75 -65
  516. package/src/hooks.ts +908 -776
  517. package/src/index.ts +19 -5
  518. package/src/init.ts +362 -361
  519. package/src/lib/datapath.ts +419 -326
  520. package/src/lib/hook_audit.ts +256 -243
  521. package/src/lib/mdcg_client.ts +10 -2
  522. package/src/lib/mutual.ts +481 -432
  523. package/src/lib/prompt_safety.ts +164 -149
  524. package/src/lib/roleplay_web.ts +30 -2
  525. package/src/lib/token_store.ts +274 -52
  526. package/src/tools.ts +249 -223
  527. package/zcode/README.md +1 -1
  528. package/docs/GBrain/345/217/257/345/200/237/351/211/264/347/202/271_/347/201/265/346/236/242/350/220/275/347/202/271/344/272/244/346/216/245_20260919.md +0 -169
  529. package/docs/Pi/345/217/257/345/255/246/344/271/240/344/274/230/347/202/271_/347/201/265/346/236/242/345/244/247/350/204/221/346/224/271/350/277/233/344/272/244/346/216/245_20260915.md +0 -144
  530. package/docs/eval/AGI/344/270/203/347/273/264/350/257/204/345/210/206/346/212/245/345/221/212_md_cg_v1.0.md +0 -299
  531. package/docs/eval/AGI/344/270/203/347/273/264/350/257/204/345/210/206/346/212/245/345/221/212_md_cg_v2.0.md +0 -239
  532. package/docs/eval/AGI/344/270/203/347/273/264/350/257/204/345/210/206/346/212/245/345/221/212_/345/205/255/345/256/266/350/256/260/345/277/206/347/263/273/347/273/237/345/220/214/345/260/272/345/256/236/346/265/213_v3.1.md +0 -340
  533. package/docs/eval/DSH/346/227/245/345/277/227/347/264/242/345/274/225v2_/345/217/202/350/200/203dsh-TUI_v1.0.md +0 -248
  534. package/docs/eval/DSH/346/227/245/345/277/227/347/264/242/345/274/225/346/225/210/346/236/234/351/252/214/350/257/201_v1.0.md +0 -209
  535. package/docs/eval/DSH/347/253/257/347/274/272/351/231/267/344/270/223/351/241/271_v1.0.md +0 -254
  536. package/docs/eval/N225_/347/264/242/345/274/225/346/227/245/345/277/227/351/235/236/345/257/271/350/261/241/350/243/205/350/275/275/351/235/242/347/261/273/345/236/213/351/227/270_v1.0.md +0 -418
  537. package/docs/eval/P1b2_/350/257/273/351/235/242/344/273/243/351/231/205/344/277/256/345/244/215_v1.0.md +0 -124
  538. package/docs/eval/bench_lingshu_self/bench_self.py +0 -140
  539. package/docs/eval/bench_lingshu_self/self_bench_result.json +0 -404
  540. package/docs/eval/bench_lingshu_self//347/201/265/346/236/242/350/207/252/345/272/223/347/253/257/345/210/260/347/253/257/346/243/200/347/264/242/345/256/236/346/265/213_v1.0.md +0 -38
  541. package/docs/eval/cons200_/345/206/262/347/252/201/346/243/200/346/265/213/351/200/211/351/235/242_/345/256/236/346/226/275/350/256/260/345/275/225_v1.0.md +0 -223
  542. package/docs/eval/cons200_/345/206/262/347/252/201/346/243/200/346/265/213/351/200/211/351/235/242_/345/256/236/346/226/275/350/256/260/345/275/225_v1.1.md +0 -340
  543. package/docs/eval/issue43_/351/273/230/350/256/244/347/255/226/347/225/245/344/270/216/351/224/256/347/261/273/345/236/213/351/227/270_v1.1.md +0 -441
  544. package/docs/eval/issue43_/351/273/230/350/256/244/347/255/226/347/225/245/345/212/240/350/275/275/344/270/216/345/207/255/346/215/256/346/230/216/346/226/207/351/230/237/345/210/227_v1.0.md +0 -398
  545. package/docs/eval/issue50_/345/205/203/346/225/260/346/215/256/351/200/217/344/274/240/344/270/216/345/205/234/345/272/225_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -437
  546. package/docs/eval/issue50_/345/215/212/351/207/215/345/244/215/345/276/205/345/256/232/345/244/215/346/240/270_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -488
  547. package/docs/eval/issue50_/345/276/205/345/256/232/345/244/215/346/240/270/345/205/245/351/230/237_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -428
  548. package/docs/eval/issue50_/350/257/273/351/235/242/344/277/235/346/212/244/345/217/252/350/256/244/346/230/276/345/274/217/346/235/245/346/272/220_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -271
  549. package/docs/eval/issue50_/351/207/215/350/246/201/345/272/246/345/220/214/346/272/220/344/270/216/344/277/235/346/212/244/350/257/255/344/271/211_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -306
  550. package/docs/eval/issue51_/344/270/200/351/224/256/345/256/211/350/243/205/345/244/261/350/264/245_/345/275/222/345/261/236/345/210/244/345/256/232_v1.0.md +0 -58
  551. package/docs/eval/issue52_/346/235/241/344/273/266/345/205/210/350/241/214/344/270/216/346/210/252/346/226/255/345/217/257/350/247/202/346/265/213_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -360
  552. package/docs/eval/issue64_replay_check_/346/240/270/351/252/214/344/270/216/344/277/256/345/244/215_v1.0.md +0 -284
  553. package/docs/eval/issue65_session_recall_/344/274/232/350/257/235/351/232/224/347/246/273_/346/240/270/351/252/214/344/270/216/344/277/256/345/244/215_v1.0.md +0 -329
  554. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/241/346/241/243/344/275/215/345/215/225/344/270/200/345/205/245/345/217/243_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -651
  555. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/242/345/217/230/346/233/264/345/215/225/344/270/216/345/233/236/346/273/232/345/216/237/350/257/255_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -439
  556. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/243/345/207/206/345/205/245/350/257/273/346/225/260_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -1337
  557. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/244/346/224/266/345/256/230/344/270/216/345/205/250/351/223/276/351/252/214/346/224/266_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -1817
  558. package/docs/eval//344/270/215/345/217/257/351/235/240/346/200/247/350/220/275/345/234/260_P0_v1.0.md +0 -185
  559. package/docs/eval//344/274/230/345/214/226/347/254/254/344/270/200/346/211/271_/346/216/245/347/272/277/344/270/216/347/255/211/344/273/267/345/217/230/346/215/242_v1.0.md +0 -498
  560. package/docs/eval//344/274/230/345/214/226/347/254/254/344/270/211/346/211/271_/351/227/250/347/246/201/350/275/254/346/255/243/344/270/216/350/260/203/345/272/246/346/255/242/350/241/200/344/270/216/351/227/250/346/216/247/346/224/266/345/217/243_v1.0.md +0 -669
  561. package/docs/eval//344/274/230/345/214/226/347/254/254/344/272/214/346/211/271_/344/276/235/350/265/226/351/200/217/344/274/240/344/270/216/345/257/271/346/213/215/345/217/243/345/276/204/344/270/216/350/264/237/347/274/223/345/255/230_v1.0.md +0 -683
  562. package/docs/eval//345/207/272/350/264/247/351/235/242/345/206/222/347/203/237_/350/277/233/350/264/247/351/227/250/347/246/201_v1.0.md +0 -460
  563. package/docs/eval//345/217/221/345/270/20306_/344/270/200/351/224/256/351/205/215/347/275/256/344/270/216DSH0172_v1.0.md +0 -171
  564. package/docs/eval//345/217/221/345/270/20307_/345/244/226/351/203/250/346/212/245/345/221/212/345/233/233/346/211/271/344/277/256/345/244/215/344/270/216/346/217/222/344/273/266/351/235/242/345/212/240/345/233/272_v1.0.md +0 -209
  565. package/docs/eval//345/217/221/345/270/20308_/350/207/252/350/277/255/344/273/243/344/270/216/347/235/241/347/234/240_/345/233/276/346/243/200/347/264/242/350/267/257/344/270/216/346/235/203/351/207/215_v1.0.md +0 -97
  566. package/docs/eval//345/217/221/345/270/20309_/346/243/200/347/264/242/351/235/242/344/270/211/346/211/271/346/224/266/345/217/243_v1.0.md +0 -66
  567. package/docs/eval//345/217/221/345/270/20310_/350/257/273/351/235/242/346/215/237/345/235/217UTF8/345/256/266/346/227/217/346/224/266/345/217/243_v1.0.md +0 -71
  568. package/docs/eval//345/217/221/345/270/20311_/345/244/226/346/212/245/345/205/255/350/277/236/344/277/256/344/270/216/344/270/226/347/225/214/346/250/241/345/236/213/345/272/225/345/272/247_v1.0.md +0 -91
  569. package/docs/eval//345/217/221/345/270/20312_/344/270/226/347/225/214/346/250/241/345/236/213/345/212/237/350/203/275/347/253/257_v1.0.md +0 -108
  570. package/docs/eval//345/217/221/345/270/20313_/344/270/212/344/270/213/346/226/207/350/207/252/347/256/241/347/220/206/346/234/272/345/210/266_v1.0.md +0 -114
  571. package/docs/eval//345/217/221/345/270/20314_/350/272/253/344/275/223/303/227/350/204/221/347/273/204/345/220/210_v1.0.md +0 -160
  572. package/docs/eval//345/217/221/345/270/20315_/344/274/232/350/257/235/351/232/224/347/246/273/344/277/256/345/244/215/344/270/216/350/272/253/344/275/223/345/272/223/345/261/225/347/244/272_v1.0.md +0 -88
  573. package/docs/eval//345/256/236/351/252/214/346/226/271/346/241/210_/345/255/246/344/271/240/351/227/255/347/216/257AB/344/270/216/346/250/252/350/257/204_v1.0.md +0 -174
  574. package/docs/eval//345/275/222/344/270/200/345/261/202/347/274/272/347/234/201/347/277/273/345/205/263_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -458
  575. package/docs/eval//346/200/247/350/203/275/344/270/223/351/241/271_/345/206/267/346/237/245/350/257/242/344/270/216/345/206/205/345/255/230_v1.0.md +0 -218
  576. package/docs/eval//346/225/205/351/232/234/346/263/250/345/205/245/345/256/236/346/265/213_v1.0.md +0 -432
  577. package/docs/eval//346/250/252/350/257/204_/345/205/255/345/256/266100/351/242/230/344/270/255/350/213/261/345/217/214/346/237/245_v1.0.md +0 -223
  578. package/docs/eval//347/224/250/346/210/267/350/243/201/345/206/263/345/244/204/347/275/256_/347/254/254/344/270/200/346/211/271_v1.0.md +0 -195
  579. package/docs/eval//347/224/250/346/210/267/350/243/201/345/206/263/345/244/204/347/275/256_/347/254/254/344/272/214/346/211/271B6_/346/234/254/346/234/272/350/267/257/345/276/204/347/233/270/345/257/271/345/214/226_v1.0.md +0 -78
  580. package/docs/eval//347/253/257/345/210/260/347/253/257LoCoMoQA/345/220/214/345/217/243/345/276/204/345/257/271/347/205/247_v1.0.md +0 -100
  581. package/docs/eval//347/253/257/345/210/260/347/253/257/345/271/262/346/211/260/346/261/240/350/257/204/346/265/213_/347/241/256/345/256/232/346/200/247/350/243/201/345/206/263vsLLM_judge_v1.1.md +0 -197
  582. package/docs/eval//347/254/2543/345/261/202stg/347/273/223/346/236/204/347/264/242/345/274/225_/345/256/236/346/226/275/350/256/260/345/275/225_v1.0.md +0 -250
  583. package/docs/eval//347/254/254/344/270/211/346/226/271/351/252/214/350/257/201/346/212/245/345/221/212_LoCoMo_/347/201/265/346/236/242_.png +0 -0
  584. package/docs/eval//347/254/254/344/270/211/346/226/271/351/252/214/350/257/201/346/212/245/345/221/212_/347/201/265/346/236/242_vs_dejavu_/347/273/237/344/270/200/350/257/204/345/210/206_v7.md +0 -202
  585. package/docs/eval//347/274/226/347/240/201/351/235/242/345/211/215/347/275/256_/345/205/245/345/217/243/350/207/252/344/277/235/350/257/201UTF8/344/270/216/346/226/207/346/234/254open/345/256/210/345/215/253_v1.0.md +0 -646
  586. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v1.md +0 -156
  587. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v10.md +0 -210
  588. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v11.md +0 -227
  589. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v12.md +0 -203
  590. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v13.md +0 -233
  591. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v14.md +0 -191
  592. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v15.md +0 -213
  593. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v16.md +0 -214
  594. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v17.md +0 -199
  595. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v18.md +0 -183
  596. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v19.md +0 -207
  597. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v2.md +0 -156
  598. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v20.md +0 -283
  599. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v21.md +0 -224
  600. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v22.md +0 -223
  601. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v23.md +0 -293
  602. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v24.md +0 -303
  603. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v25.md +0 -230
  604. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v26.md +0 -196
  605. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v27.md +0 -259
  606. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v28.md +0 -217
  607. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v29.md +0 -270
  608. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v3.md +0 -152
  609. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v30.md +0 -231
  610. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v31.md +0 -281
  611. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v4.md +0 -128
  612. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v5.md +0 -114
  613. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v6.md +0 -192
  614. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v7.md +0 -187
  615. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v8.md +0 -207
  616. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v9.md +0 -203
  617. package/docs/eval//350/257/255/344/271/211/346/227/266/347/251/272/345/233/276/350/241/245/345/205/250_P1_/346/212/275/345/217/226/345/231/250v4_/344/270/211/347/216/207/350/257/273/346/225/260_v1.0.md +0 -231
  618. package/docs/eval//351/262/270/345/250/230/344/270/203/347/261/273/347/212/266/346/200/201/350/277/275/350/270/252_v1.0.md +0 -176
  619. package/docs/hive//344/270/273/344/273/243/347/220/206/345/255/220/344/273/243/347/220/206/350/256/260/345/277/206/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -385
  620. package/docs/hive//344/273/244/347/211/214/344/270/216/350/247/222/350/211/262/346/235/203/350/201/214/345/210/206/347/246/273_v0.1.md +0 -165
  621. package/docs/hive//344/273/244/347/211/214/350/257/255/344/271/211/344/277/256/346/255/243_/344/273/262/350/243/201/344/275/215_v0.1.md +0 -76
  622. package/docs/hive//345/244/232/347/253/257harness/351/200/232/344/277/241/345/245/221/347/272/246_v0.1.md +0 -42
  623. package/docs/hive//345/255/220/344/273/243/347/220/206/351/205/215/347/275/256/346/240/207/345/207/206_v0.5.md +0 -236
  624. package/docs/hive//345/256/211/345/205/250/345/256/241/350/256/241/345/256/236/351/224/232_v0.1.md +0 -202
  625. package/docs/hive//346/243/200/347/264/242/346/224/266/346/225/233/345/256/236/346/265/213/344/270/216S1b/350/256/276/350/256/241_v0.1.md +0 -43
  626. package/docs/hive//346/243/200/347/264/242/347/256/227/346/263/225/345/217/243/345/276/204/345/257/271/347/205/247_v0.1.md +0 -210
  627. package/docs/hive//346/243/200/347/264/242/350/267/257/345/276/204/344/270/216/350/256/244/347/237/245/347/273/223/346/236/204/345/245/221/347/272/246_v0.1.md +0 -152
  628. package/docs/hive//350/234/202/345/267/242M6_ingest/345/256/236/346/226/275/350/256/241/345/210/222_v0.1.md +0 -47
  629. package/docs/hive//350/234/202/345/267/242/345/217/214/345/256/236/344/276/213/344/272/222/351/252/214_/350/256/276/350/256/241/345/256/232/347/250/277.md +0 -519
  630. package/docs/hive//350/234/202/345/267/242/345/267/245/344/275/234/350/256/260/345/277/206_/351/241/271/347/233/256/350/256/241/345/210/222.md +0 -85
  631. package/docs/hive//350/234/202/345/267/242/350/256/276/350/256/241_/347/220/206/350/256/272/345/257/271/351/275/220_v0.1.md +0 -191
  632. package/docs/hive//350/234/202/345/267/242/350/277/255/344/273/243_/345/256/217/350/247/202/344/270/216/347/276/244/344/275/223/350/260/203/345/272/246_v0.1.md +0 -90
  633. package/docs/images/lingshu-moonlight-covenant-poster-preview.jpg +0 -0
  634. package/docs/images/lingshu-moonlight-covenant-poster.png +0 -0
  635. package/docs/mdcg/D_meta_/345/267/245/347/250/213/345/214/226/346/226/271/346/241/210_v0.2.md +0 -216
  636. package/docs/mdcg/README/350/257/246/347/273/206/347/211/210_v0.4.10.md +0 -746
  637. package/docs/mdcg/guardrail-charter.md +0 -164
  638. package/docs/mdcg/lingshu_tutorial.html +0 -14956
  639. package/docs/mdcg/memory-assessment.html +0 -923
  640. package/docs/mdcg/memory_score.html +0 -213
  641. package/docs/mdcg/memory_score.png +0 -0
  642. package/docs/mdcg/release_v0.3.0.md +0 -36
  643. package/docs/mdcg/release_v0.4.11.md +0 -49
  644. package/docs/mdcg/release_v0.4.5.md +0 -55
  645. package/docs/mdcg/tool_table_v0.3.0.md +0 -117
  646. package/docs/mdcg//344/270/226/347/225/214/346/250/241/345/236/213/345/212/237/350/203/275/347/253/257_/344/275/277/347/224/250/344/270/216/350/277/220/347/273/264_v1.0.md +0 -384
  647. package/docs/mdcg//344/273/243/347/240/201/350/257/204/345/256/241/344/270/216/346/235/241/344/273/266/345/214/226/346/263/250/351/207/212_/345/245/221/347/272/246_v0.1.md +0 -82
  648. package/docs/mdcg//345/205/250/345/272/223/344/273/243/347/240/201/350/257/204/345/256/241/344/270/216/346/235/241/344/273/266/345/214/226/346/263/250/351/207/212_/350/256/241/345/210/222_v0.1.md +0 -600
  649. package/docs/mdcg//345/212/237/350/203/275/350/260/203/347/224/250/346/230/240/345/260/204/350/241/250_v0.1.md +0 -266
  650. package/docs/mdcg//345/215/225/345/205/203/350/207/252/346/210/221/351/224/232/347/202/271_/347/263/273/347/273/237/346/217/220/347/244/272/350/257/215/346/240/207/345/207/206_v0.3.md +0 -275
  651. package/docs/mdcg//345/217/221/345/270/203/351/227/250/347/246/201/351/223/276_v0.1.md +0 -134
  652. package/docs/mdcg//346/272/220/347/240/201/347/272/247/346/236/266/346/236/204/345/256/241/350/256/241_GPT/346/211/271/350/257/204/345/257/271/347/205/247_v1.0.md +0 -130
  653. package/docs/mdcg//347/201/265/346/236/24282/345/267/245/345/205/267_/345/212/237/350/203/275/346/225/264/347/220/206/344/270/216/350/277/201/347/247/273/346/230/240/345/260/204_v0.1.md +0 -278
  654. package/docs/mdcg//347/201/265/346/236/242MCP/345/267/245/345/205/267/346/200/273/350/241/250_v3.4.md +0 -164
  655. package/docs/mdcg//347/201/265/346/236/242_/350/207/252/346/210/221/345/261/202/345/256/232/344/271/211.md +0 -43
  656. package/docs/mdcg//347/201/265/346/236/242/344/270/211/345/261/202/346/213/206/345/210/206/350/247/204/345/210/222_v0.1.md +0 -181
  657. package/docs/mdcg//347/201/265/346/236/242/350/256/260/345/277/206/345/212/250/350/257/215/345/215/217/350/256/256_v1.0-draft.md +0 -177
  658. package/docs/mdcg//347/216/257/344/272/214_/347/231/275/347/256/261/345/241/253/345/205/205/346/265/201/346/260/264/347/272/277_v0.1.md +0 -31
  659. package/docs/mdcg//347/235/241/347/234/240/345/221/250/346/234/237_/350/277/220/347/273/264/345/211/215/346/217/220/344/270/216/347/273/264/346/212/244/346/214/207/345/215/227_v1.0.md +0 -337
  660. package/docs/mdcg//347/274/272/345/217/243/345/215/225_P0/346/224/266/345/217/243_v0.1.md +0 -270
  661. package/docs/mdcg//350/256/244/347/237/245/345/233/276_G4-G8/347/274/272/345/217/243/350/243/201/345/256/232/345/215/225_v0.1.md +0 -491
  662. package/docs/mdcg//350/256/244/347/237/245/345/233/276_MD/347/233/256/345/275/225/346/226/271/346/241/210_v0.1.md +0 -552
  663. package/docs/mdcg//350/256/244/347/237/245/345/233/276_/346/235/241/344/273/266/347/251/272/351/227/264/345/220/210/346/210/220/344/270/216/347/224/237/346/225/210/346/235/241/344/273/266/345/217/243/345/276/204_v0.1.md +0 -340
  664. package/docs/mdcg//350/256/244/347/237/245/345/233/276_/347/264/242/345/274/225/344/270/216/345/267/245/347/250/213/350/247/204/350/214/203/345/214/226_/350/256/241/345/210/222_v0.1.md +0 -624
  665. package/docs/mdcg//350/256/244/347/237/245/345/233/276/344/275/234/344/270/272/350/256/260/345/277/206/346/223/215/344/275/234/347/263/273/347/273/237_/350/257/204/344/274/260/344/270/216/350/267/257/347/272/277_v0.1.md +0 -94
  666. package/docs/mdcg//350/256/260/345/277/206/346/223/215/344/275/234/347/263/273/347/273/237_MdCGOS/344/270/216MCP/346/216/245/345/205/245_v0.1.md +0 -281
  667. package/docs/mdcg//350/267/250/347/253/257/351/252/214/350/257/201/344/270/216/345/220/214/346/255/245/345/215/217/350/256/256_v0.1.md +0 -93
  668. package/docs/plans/GridWorld/346/234/200/345/260/217/351/227/255/347/216/257/350/247/204/346/240/274_v0.1.md +0 -176
  669. package/docs/plans/stg/346/235/241/344/273/266/345/214/226/344/270/216/347/273/223/346/236/204/347/264/242/345/274/225_/350/256/276/350/256/241_v0.1.md +0 -124
  670. package/docs/plans//345/205/250/344/270/255/346/226/207/347/274/226/347/240/201/344/270/216/350/234/202/345/267/242/344/273/273/345/212/241/346/240/207/350/257/206/345/245/221/347/272/246_v2.0.md +0 -220
  671. package/docs/plans//345/221/275/345/220/215/346/262/273/347/220/206_/351/241/271/347/233/256/350/256/241/345/210/222.md +0 -81
  672. package/docs/plans//345/244/232/344/270/273/344/275/223/344/270/226/347/225/214/346/250/241/345/236/213_/345/257/271/351/275/220/350/257/204/344/274/260/344/270/216/350/220/275/345/234/260/350/256/276/350/256/241_v0.1.md +0 -141
  673. package/docs/plans//347/201/265/346/236/242/350/272/253/344/275/223/303/227/350/204/221_/344/270/226/347/225/214/346/250/241/345/236/213/345/257/271/346/216/245/350/256/276/350/256/241_v0.1.md +0 -119
  674. package/docs/plans//347/234/237/346/272/220/347/264/242/345/274/225_/351/200/232/347/224/250/346/234/272/345/210/266_v0.3.md +0 -227
  675. package/docs/plans//347/235/241/347/234/240/344/270/216/350/207/252/350/277/255/344/273/243_/345/212/237/350/203/275/344/274/230/345/214/226/350/256/276/350/256/241_v0.4.md +0 -547
  676. package/docs/plans//347/237/245/350/257/206/345/233/276/350/260/261/351/241/271/347/233/256_/344/272/244/346/216/245/346/226/207/346/241/243_20260914.md +0 -308
  677. package/docs/plans//350/234/202/345/267/242/346/250/241/345/236/213/345/257/206/351/222/245/351/205/215/347/275/256/351/235/242_v1.0.md +0 -385
  678. package/docs/plans//350/256/260/345/277/206/350/207/252/345/244/204/347/220/206/344/270/211/346/241/243/350/207/252/346/262/273_/350/256/276/350/256/241_v0.2.md +0 -207
  679. package/docs/plans//350/257/255/344/271/211/346/227/266/347/251/272/345/233/276/350/241/245/345/205/250_/344/270/226/347/225/214/346/250/241/345/236/213/345/212/237/350/203/275/347/253/257_/350/256/276/350/256/241_v0.1.md +0 -107
  680. package/docs/promo/bilibili-cover.jpg +0 -0
  681. package/docs/promo/promo-visual-1.png +0 -0
  682. package/docs/promo/promo-visual-2.png +0 -0
  683. package/docs/promo/promo-visual-3.png +0 -0
  684. package/docs/promo/promo-visual-4.png +0 -0
  685. package/docs/promo/promo-visual-5.png +0 -0
  686. package/docs/swarm//350/234/202/347/276/244/344/272/222/350/201/224_v0.1.md +0 -704
  687. package/docs/swarm//350/234/202/347/276/244/345/220/214/351/224/231/346/243/200/346/265/213/345/256/236/351/252/214/345/215/217/350/256/256_v0.1.md +0 -242
  688. package/docs/swarm//350/234/202/347/276/244/345/244/232/346/231/272/350/203/275/344/275/223_/344/275/277/347/224/250/346/212/245/345/221/212_20260913.md +0 -68
  689. package/docs/swarm//350/234/202/347/276/244/345/244/232/346/231/272/350/203/275/344/275/223_/345/212/237/350/203/275/350/257/264/346/230/216_v0.6.md +0 -130
  690. package/docs/swarm//350/234/202/347/276/244/347/233/262/345/214/272/346/240/207/350/256/260_v1.0.md +0 -89
  691. package/docs/theory//344/270/215/345/217/257/351/235/240/345/256/232/347/220/206/344/270/216/345/244/261/346/225/210/344/274/230/345/205/210/346/241/206/346/236/266_v0.3.md +0 -365
  692. package/docs/theory//344/277/241/346/201/257/345/267/256/344/270/272/344/273/200/344/271/210/345/277/205/347/204/266/345/255/230/345/234/250/344/270/224/350/207/252/347/204/266/346/211/251/345/244/247.md +0 -239
  693. package/docs/theory//345/215/225/347/272/277/347/250/213/344/270/216/346/263/250/346/204/217/345/212/233/351/233/206/344/270/255_/346/227/240/344/272/211/350/256/256/347/220/206/350/256/272/346/226/207/346/241/243_v1.0.md +0 -129
  694. package/docs/theory//345/271/266/345/217/221/345/277/205/347/204/266/346/200/247/347/220/206/350/256/272_v0.2.md +0 -134
  695. package/docs/theory//346/231/272/350/203/275/347/232/204/345/205/254/347/220/206/345/214/226/345/237/272/347/237/263.md +0 -789
  696. package/docs/theory//346/231/272/350/203/275/347/232/204/350/256/244/347/237/245/350/277/207/347/250/213.md +0 -379
  697. package/docs/theory//346/231/272/350/203/275/350/256/2723.4.md +0 -5260
  698. package/docs/theory//346/246/202/345/277/265/345/210/206/345/261/202/345/257/271/351/275/220/350/241/250_v0.1.md +0 -145
  699. package/docs/theory//347/220/206/350/256/272_/346/234/272/345/210/266_/344/273/243/347/240/201_/345/256/236/351/252/214_/347/274/272/345/217/243/347/237/251/351/230/265_v0.1.md +0 -144
  700. package/docs/theory//347/220/206/350/256/272/344/273/223/346/213/206/345/210/206/344/270/216/347/231/275/347/256/261/347/237/245/350/257/206/345/272/223/345/206/205/350/277/201_v0.1.md +0 -198
  701. package/docs/theory//347/231/275/347/256/261/346/231/272/350/203/275/346/230/257/344/273/200/344/271/210/357/274/237.md +0 -812
  702. package/docs/theory//347/231/275/347/256/261/346/231/272/350/203/275/347/263/273/345/210/227/302/267/347/254/254/344/272/224/347/257/207/357/274/232/350/256/251AI/347/234/237/346/255/243/350/243/205/344/270/212/350/256/260/345/277/206.md +0 -421
  703. package/docs/theory//350/256/244/347/237/245/344/273/243/347/220/206/344/270/216/346/224/266/346/225/233/347/273/223/346/236/204_/346/235/241/344/273/266/350/256/272/351/207/215/346/236/204_v0.1.md +0 -221
  704. package/docs/world_model//344/270/226/347/225/214/346/250/241/345/236/213_/347/245/236/347/273/217/347/275/221/347/273/234/345/272/225/345/261/202/346/236/266/346/236/204_v1.0.md +0 -237
  705. package/docs//344/270/215/345/217/257/351/235/240/346/200/247/347/220/206/350/256/272_v0.1.md +0 -343
  706. package/docs//345/217/221/345/270/203/344/273/266/345/233/236/346/272/257/350/257/264/346/230/216_v0.1.md +0 -82
  707. package/docs//345/255/230/347/256/227/344/270/200/344/275/223/346/236/266/346/236/204/345/255/246/344/271/240_/345/244/226/351/203/250/347/220/206/350/256/272/345/257/271/347/205/247/344/270/216/350/267/257/347/272/277/344/272/244/346/216/245_20260916.md +0 -98
  708. package/docs//345/255/230/347/256/227/344/270/200/344/275/223/347/245/236/347/273/217/347/275/221/347/273/234/346/236/266/346/236/204_/346/200/273/347/272/262/344/270/216/344/272/244/346/216/245_20260916.md +0 -109
  709. package/docs//347/201/265/346/236/242/350/207/252/346/210/221/346/224/271/350/277/233/345/267/245/344/275/234/350/256/241/345/210/222_/345/244/226/351/203/250/347/240/224/347/251/266/347/263/273/345/210/227/345/220/270/346/224/266_v1_20260919.md +0 -286
  710. package/docs//347/231/275/347/256/261/345/214/226/347/272/262/351/242/206_/344/270/211/351/241/271/347/233/256/345/255/246/344/271/240/346/200/273/346/236/266/346/236/204/344/270/216Ghidra/344/272/244/346/216/245_20260916.md +0 -104
  711. package/docs//347/247/244_/350/256/260/345/277/206/347/263/273/347/273/237/350/257/204/346/265/213/350/247/204/350/214/203_v2.1.md +0 -225
  712. package/docs//350/256/260/345/277/206/347/263/273/347/273/237/345/215/263/347/231/275/347/256/261/345/214/226/346/231/272/350/203/275_/346/236/266/346/236/204/345/257/271/347/205/247_v0.2.md +0 -121
  713. package/docs//350/256/260/345/277/206/347/263/273/347/273/237/345/215/263/347/231/275/347/256/261/345/214/226/346/231/272/350/203/275_/346/236/266/346/236/204/345/257/271/347/205/247_v0.3.md +0 -117
  714. package/docs//350/256/260/345/277/206/350/257/204/345/256/241/347/263/273/347/273/237_/347/253/213/351/241/271/350/256/276/350/256/241/344/270/216/346/226/275/345/267/245/344/272/244/346/216/245_20260915.md +0 -183
package/md_cg/protocol.py CHANGED
@@ -1,411 +1,492 @@
1
- # -*- coding: utf-8 -*-
2
- """md_cg · 记忆动词协议 v1(单一真源 · draft 期未冻结)
3
-
4
- 目的(工作计划 §3.4):把 MCP 记忆工具面的**动词与 I/O 形状**冻结成可裁决的声明,
5
- 使三端(本仓 MCP / DSH 内建基元 / 第三方客户端)能各自实现客户端而不必读源码;
6
- 再由 `conformance.py` 的静态对账把「声明 ↔ 实现」钉死:
7
-
8
- · 声明为 live 却在 MCP 面无分支 → FAIL(说了没做)
9
- · reserved 动词在 MCP 面出现实现分支 → FAIL(预留位被静默实现,协议形同虚设)
10
- · 协议外 op 分支 → 报告(扩展能力面,不是违例)
11
-
12
- 范围(先行收窄):route / read / write / supersede / forget 五动词。
13
-
14
- **扩展能力面的契约登记**(不并入五动词形状表,但同为本文件真源,2026-09-30):
15
- ① `ACTION_SOURCE_KEY / ACTION_SOURCE_VALUES`——wrapper 级恒定键 `action_source`
16
- (M4,四态 explicit/sig/default/none,任何 op 的 dict 返回恒在场);
17
- ② `PROTECT_MARK_NEG_ROUTE`——`protect.mark` 的负路由 error 形态(H9)。
18
- 两者由 `audit()` 的 `action_source` / `protect_neg_route` 段透出,并由 `test_protocol`
19
- 的**同源源码守卫**钉住 mcp_server / protect 的实现(防「声明了没做」)。
20
-
21
- **协议面 ≠ MCP 面全量**(2026-09-19 实测):`_cg_dispatch` 现有 35 个 op 分支,
22
- 其中 30 个(ccg / review / protect / verify / whitebox …)属**扩展能力面**——它们是能力,
23
- 不是协议违例。把「协议覆盖范围」当成「MCP 面全量」会让协议每加一个 op 就永久红灯,
24
- 故反向对账降级为 `extension_ops` 报告项(清单可见、不 FAIL);扩展面的文档一致性由
25
- README 认知图 + `docs/mdcg/功能调用映射表` 的 cogmap 门禁承担(已在 CI)。
26
-
27
- 三条纪律:
28
- 1. **本文件是协议唯一真源**——文档 `docs/mdcg/灵枢记忆动词协议_v1.0-draft.md`
29
- 与 `conformance.py` 的断言均从本文件取值,不另立第二份清单。
30
- 2. **不冒充**——未实现的动词登记 `status="reserved"` 并给出 `map_to` 现状映射证据,
31
- 不得写 live;live 的形状取**代码实测**(executor / 分支 return),不取设想。
32
- 3. **draft 期(FROZEN=False)**——形状可破坏性调整;冻结是单向门,须三端实测收敛后
33
- 由使用者拍板(工作计划 §9 风险 3)。
34
-
35
- 用法:
36
- python -m md_cg.protocol # 打印静态对账结论(只读,零写入)
37
- """
38
- from __future__ import annotations
39
-
40
- import argparse
41
- import ast
42
- import inspect
43
- import json
44
- import textwrap
45
-
46
- PROTOCOL_VERSION = 1
47
- #: 冻结开关:True 后形状变更须走版本号递增(v1 → v2),不得原地改 v1 的形状
48
- FROZEN = False
49
- PROTOCOL_DOC = "docs/mdcg/灵枢记忆动词协议_v1.0-draft.md"
50
- SURFACE_MODULE = "md_cg.mcp_server"
51
- DISPATCH_FUNC = "_cg_dispatch"
52
- CALL_FUNC = "_cg_call"
53
-
54
- #: 协议声明的动词全集(顺序即文档呈现顺序)
55
- VERBS = ("route", "read", "write", "supersede", "forget")
56
-
57
- #: write 返回**铁律**:任一形态必含此三键——客户端据此判定「是否落盘」而非猜测。
58
- #: 这是协议对三端客户端最有价值的一条:ok/committed 分离表达「闸门行为 ≠ 工具故障」。
59
- WRITE_TRIO = ("ok", "id", "committed")
60
-
61
- #: op 推导兜底(`_cg_call` wrapper,2026-09-13 防呆落地):op 漏传时按入参签名推导。
62
- #: 协议侧只作**文档化声明**(供客户端理解兜底语义),不做静态对账——
63
- #: 推导实现散落在 wrapper 分支里,强做正则对账会误报(宁可少断言,不可假绿灯)。
64
- OP_DERIVE = (
65
- {"when": "content", "op": "write"},
66
- {"when": "query", "op": "read"},
67
- {"when": "node_id", "op": "read"},
68
- {"when": "intent", "op": "route"},
69
- {"when": "(无签名)", "op": "read"},
70
- )
71
-
72
- #: op 推导发生时**追加透出**的键(实测):additive,不破坏各形态 required 子集判定。
73
- #: 协议语义:客户端看到这些键即知道「本次 op 是猜的」——据此可要求调用方补显式 op。
74
- DERIVE_EXTRA_KEYS = ("op", "op_derived", "hint")
75
-
76
- #: 校验裁决(verdict)的字段集——写路径闸门短路时随返回透出(实测)。
77
- #: state 取值 = ACCEPT / REJECT / DEFER / BLINDSPOT(四态资格裁决)。
78
- VERDICT_FIELDS = ("state", "kind", "basis", "evidence", "detail")
79
-
80
- #: M4(2026-09-30)· **wrapper 级恒定键**:**任何 op** 的 dict 返回都带此键
81
- #: (`_cg_call` 追加,实测 mcp_server.py:1849-1857 的 act_source 三元表达式 +
82
- #: 其后 `out.setdefault("action_source", act_source)`)。
83
- #: 取值四态(顺序即优先级):explicit(调用方显式传了 action)> sig(漏传 action
84
- #: 但按参数签名推导出)> default(该 op 在默认动作表里有条目,走了默认)>
85
- #: none(该 op 无默认动作,不编造)。协议语义:客户端据此可判断本次 action 是
86
- #: **自己传的**还是**系统挑的**——旧行为只在「推导过」时透出 action_derived,
87
- #: 显式传 action 时返回里没有任何痕迹。
88
- #: 与 DERIVE_EXTRA_KEYS 的边界:那是「推导发生过才追加」(显式态下不出现),
89
- #: 本键**恒在场**;两套标记并存互补,见 test_read_face_input_gates 的 M4-C 组。
90
- ACTION_SOURCE_KEY = "action_source"
91
- ACTION_SOURCE_VALUES = ("explicit", "sig", "default", "none")
92
-
93
- #: H9(2026-09-30)· protect.mark 的**负路由形态**(实测 protect.py:374)。
94
- #: 目标不存在时该分支返回此 dict——不是裸 None:旧行为裸返 None 被
95
- #: `_protect_call` 序列化成 `null` 回客户端,「id 不存在」被读成「打标成功」,
96
- #: 而 `_write_node` 从未发生。与 read 的 `node_missing` 同为「缺失 ≠ 成功」,
97
- #: 但**形态不同、须分别处理**:read 返 `null`(returns_null=True),
98
- #: protect 返结构化 error(ok=False + error + node_id)。
99
- #: 调用方分流:失败看 `r.get("ok") is False` 或 `"error" in r`;成功路径的返回键
100
- #: **不变**(node_id / protected / reason,**无 ok 键**——不可用 `ok` 判成功)。
101
- PROTECT_MARK_NEG_ROUTE = {"ok": False, "error": "node_not_found",
102
- "node_id": "<目标 id>"}
103
- PROTECT_MARK_NEG_ROUTE_ERROR = "node_not_found"
104
-
105
- VERB_SPECS = {
106
- "route": {
107
- "status": "live",
108
- "mutating": False,
109
- "impl": ("mcp_server", "_cg_dispatch"),
110
- "requires_any": (("intent", "query"),),
111
- "optional": ("k", "context"),
112
- "shapes": {
113
- "default": {
114
- "when": "恒",
115
- "required": ("knowledge", "meta"),
116
- "optional": ("suggested_capabilities", "note"),
117
- },
118
- },
119
- "semantics": "只给知识与建议能力名,不执行;由调用方决定下一步",
120
- },
121
- "read": {
122
- "status": "live",
123
- "mutating": False,
124
- "impl": ("mcp_server", "_cg_dispatch"),
125
- "requires_any": (("node_id",), ("query", "intent"), ("budget_tokens",)),
126
- "optional": ("offset", "k", "context", "goal", "include_recent", "limit",
127
- "session", "validity", "layer", "branch"),
128
- "shapes": {
129
- "node": {
130
- "when": "node_id 非空且目标存在且可见",
131
- "required": ("id", "path", "frontmatter", "content",
132
- "verification_state"),
133
- "optional": ("truncated", "content_lines", "content_bytes",
134
- "offset", "next_offset", "note"),
135
- },
136
- "node_missing": {
137
- "when": "node_id 非空但目标不存在 / 不可见 / 已软删",
138
- "returns_null": True,
139
- "required": (),
140
- "optional": (),
141
- "note": "**实测返回 null**(不是错误对象)——客户端须先判空再解析,"
142
- "把 null 当异常会误报;把 null 当空内容会静默吞未知",
143
- },
144
- "list": {
145
- "when": "budget_tokens 为空",
146
- "required": ("meta", "results"),
147
- "optional": (),
148
- },
149
- "pack": {
150
- "when": "budget_tokens 非空(优先于 node_id 之外的 query 路径)",
151
- "required": ("pack", "tokens_used", "budget", "skipped", "recent",
152
- "meta"),
153
- "optional": (),
154
- },
155
- },
156
- "semantics": "读动词三分态:单节点视图 / 检索结果列表 / token 预算包",
157
- },
158
- "write": {
159
- "status": "live",
160
- "mutating": True,
161
- "impl": ("writepipe", "default_pipeline"),
162
- "requires_any": (("content",),),
163
- "optional": ("content_kind", "layer", "tags", "importance",
164
- "verification_basis", "condition_space",
165
- "non_applicable_conditions", "depends_on", "derived_from",
166
- "relation", "valid_from", "valid_until", "verification_state",
167
- "consistency", "on_conflict", "gated", "override",
168
- "importance_hint", "semantic", "node_id"),
169
- "shapes": {
170
- "committed": {
171
- "when": "链尾执行器落盘",
172
- "required": WRITE_TRIO,
173
- "optional": ("verdict", "consistency", "propagation"),
174
- },
175
- "gate_short_circuit": {
176
- "when": "任一 before 闸门短路(审核 REJECT / DEFER / 冲突)",
177
- "required": WRITE_TRIO + ("moved_to", "verdict", "hint"),
178
- "optional": ("pid", "dedup", "dup_of", "dup_status", "consistency"),
179
- },
180
- "gate_hard_reject": {
181
- "when": "契约缺失硬拒(依赖声明闸 E050/E051)",
182
- "required": WRITE_TRIO + ("gate", "error", "hint"),
183
- "optional": ("missing", "verdict"),
184
- },
185
- "gate_gated": {
186
- "when": "主动遗忘闸(gated=true)替代落盘路径",
187
- "required": WRITE_TRIO + ("gate", "verdict"),
188
- "optional": ("consistency", "moved_to", "propagation"),
189
- },
190
- },
191
- "semantics": "写动词多形态:committed=已落盘;未 committed 时 moved_to/gate 说明去向,"
192
- "hint 说明下一步(闸门正常行为、不是工具故障;政策违规类 REJECT「重试同样结果」,"
193
- "缺必需要素类 REJECT 给出完整缺失清单与「补齐后重写」指引)",
194
- },
195
- "supersede": {
196
- "status": "reserved",
197
- "mutating": True,
198
- "impl": None,
199
- "requires_any": (("node_id",), ("superseded_by",)),
200
- "optional": ("reason", "inherit_verification", "propagate"),
201
- "shapes": {
202
- "planned": {
203
- "when": "(预留位,尚未实现)",
204
- "required": ("ok", "id", "superseded_by"),
205
- "optional": ("supersedes", "propagation", "verdict"),
206
- },
207
- },
208
- "semantics": "以新节点取代旧节点:旧节点保留可审计但退出默认检索面,取代关系可追溯",
209
- "map_to": (
210
- {"verb": "write", "note": "新节点写入本身走 write(五动词不重复造写入通道)"},
211
- {"verb": "review/verify", "note": "现有撤回体系由校验(verify 验伪)与审核"
212
- "(review 的 delete/merge)承担,无独立取代动词"},
213
- {"field": "nodefile.believed_at", "note": "取代语义的锚字段已就位(写侧注释),"
214
- "缺的是动词入口与检索面过滤"},
215
- ),
216
- "reserved_reason": "取代会改变默认检索面(被取代节点是否可见),属行为变更,"
217
- "须先冻结协议再落实现——避免三端各自发明可见性口径",
218
- },
219
- "forget": {
220
- "status": "live",
221
- "mutating": True,
222
- "impl": ("mdcos", "MdCG.forget"),
223
- "requires_any": (("node_id",),),
224
- "optional": ("reason", "override", "action"),
225
- "shapes": {
226
- "forgotten": {
227
- "when": "action 缺省或非 restore",
228
- "required": ("ok", "id", "tombstone"),
229
- "optional": (),
230
- },
231
- "restored": {
232
- "when": "action == 'restore'",
233
- "required": ("ok", "id", "forced"),
234
- "optional": (),
235
- },
236
- "failed": {
237
- "when": "目标不存在 / 已 tombstone(未 force)/ trash 无文件 / OSError",
238
- "required": ("ok", "error"),
239
- "optional": ("reason", "t", "action", "action_derived",
240
- "hint_action"),
241
- },
242
- },
243
- "semantics": "软删除与恢复:文件移入 trash/、写删除清单、摘索引;受保护节点需 override",
244
- },
245
- }
246
-
247
-
248
- # 生效条件:node 为 ast 表达式节点;沿 Attribute/Call 递归剥到 Name,命中 Name("op") 返回 True,落到其它节点类型(含常量/字面量)返回 False;
249
- def _is_op_expr(node) -> bool:
250
- """判断 AST 表达式是否指向 `op`(兼容 `op.strip().lower()` 形态)。"""
251
- cur = node
252
- while True:
253
- if isinstance(cur, ast.Name):
254
- return cur.id == "op"
255
- if isinstance(cur, ast.Attribute):
256
- cur = cur.value
257
- continue
258
- if isinstance(cur, ast.Call):
259
- cur = cur.func
260
- continue
261
- return False
262
-
263
-
264
- # 生效条件:src 为字符串源码(缩进任意,内部先 dedent);ast.parse 成功返回按出现序去重的 op 字面量列表(识别 `op == "x"` 与 `op in ("x","y")` 两种形态,op 侧兼容 `op.strip().lower()`),解析失败(SyntaxError/TypeError/任意异常)返回空列表,不抛异常;
265
- def _ops_from_source(src: str) -> list:
266
- """从源码文本提取 op 分支名(dispatch_ops 与测试共用;测试可直接喂合成源码)。"""
267
- try:
268
- tree = ast.parse(textwrap.dedent(src or ""))
269
- except Exception: # noqa: BLE001
270
- return []
271
- out = []
272
- for node in ast.walk(tree):
273
- if not isinstance(node, ast.Compare) or not _is_op_expr(node.left):
274
- continue
275
- for opnode, comp in zip(node.ops, node.comparators):
276
- items = []
277
- if isinstance(opnode, ast.Eq):
278
- items = [comp]
279
- elif isinstance(opnode, ast.In) and isinstance(
280
- comp, (ast.Tuple, ast.List, ast.Set)):
281
- items = list(comp.elts)
282
- for it in items:
283
- if isinstance(it, ast.Constant) and isinstance(it.value, str):
284
- if it.value not in out:
285
- out.append(it.value)
286
- return out
287
-
288
-
289
- # 生效条件:module 缺省取 SURFACE_MODULE、func 缺省取 DISPATCH_FUNC;导入模块 / 取属性 / getsource 任一抛异常,返回 {"ok": False, "error": "<类型>: <消息>", "ops": []};成功返回 {"ok": True, "module", "func", "ops": 按出现序去重的 op 字面量列表};
290
- def dispatch_ops(module: str = None, func: str = None) -> dict:
291
- """从分发函数源码用 **AST** 提取 op 分支(`if op == "x"` 与 `op in ("x","y")`)。
292
-
293
- 为何用 AST 而非正则:正则对单引号/换行/`op.strip().lower()` 形态会静默漏提,
294
- 而「漏提」在本协议里等于假绿灯(cogmap 已有同类教训)。AST 结构性识别不依赖写法。
295
- """
296
- mod_name = module or SURFACE_MODULE
297
- fn_name = func or DISPATCH_FUNC
298
- try:
299
- m = __import__(mod_name, fromlist=[fn_name])
300
- obj = getattr(m, fn_name)
301
- src = inspect.getsource(obj)
302
- except Exception as e: # noqa: BLE001
303
- return {"ok": False, "error": f"{type(e).__name__}: {e}", "ops": []}
304
- return {"ok": True, "module": mod_name, "func": fn_name,
305
- "ops": _ops_from_source(src)}
306
-
307
-
308
- # 生效条件:module/func 透传 dispatch_ops(默认面取模块常量);始终返回 dict,含 protocol_version/frozen/doc/live/reserved/declared/actual/has_impl/missing_impl/extension_ops/reserved_leaked/shape_errors/derive/errors/ok,任一静态对账项失败则 ok=False 且失败明细进 errors;
309
- def audit(module: str = None, func: str = None) -> dict:
310
- """静态对账:协议声明 ↔ MCP 面实现(不连库、不执行,纯源码事实)。"""
311
- got = dispatch_ops(module, func)
312
- actual = list(got.get("ops") or [])
313
- declared = list(VERBS)
314
- live = [v for v in declared if VERB_SPECS[v].get("status") == "live"]
315
- reserved = [v for v in declared if VERB_SPECS[v].get("status") == "reserved"]
316
- has_impl = [v for v in declared if v in actual]
317
- missing_impl = [v for v in live if v not in actual]
318
- # 协议 v1 只冻结五动词;MCP 面其余 op 属**扩展能力面**——它们是能力不是违例。
319
- # 反向对账降级为报告项(extension_ops),理由见模块 docstring。
320
- extension_ops = [v for v in actual if v not in declared]
321
- reserved_leaked = [v for v in reserved if v in actual]
322
- shape_errors = []
323
- for v in declared:
324
- spec = VERB_SPECS[v]
325
- if spec.get("status") not in ("live", "reserved"):
326
- shape_errors.append(f"{v}: status 取值非法 {spec.get('status')!r}")
327
- shapes = spec.get("shapes") or {}
328
- if not shapes:
329
- shape_errors.append(f"{v}: 未声明任何形状")
330
- for sname, sh in shapes.items():
331
- if not sh.get("required") and not sh.get("returns_null"):
332
- shape_errors.append(
333
- f"{v}.{sname}: required 为空且未声明 returns_null")
334
- if not sh.get("when"):
335
- shape_errors.append(f"{v}.{sname}: 缺 when(何时走该形态)")
336
- if spec.get("status") == "reserved" and not spec.get("map_to"):
337
- shape_errors.append(f"{v}: reserved 但未声明 map_to 现状映射证据")
338
- if spec.get("status") == "live" and not spec.get("impl"):
339
- shape_errors.append(f"{v}: live 但未声明 impl 落点")
340
- errors = []
341
- if not got.get("ok"):
342
- errors.append(f"源码提取失败:{got.get('error')}")
343
- if missing_impl:
344
- errors.append(f"声明为 live 但 MCP 面无分支:{missing_impl}")
345
- if reserved_leaked:
346
- errors.append(f"reserved 动词出现实现分支(实现了却未登记):{reserved_leaked}")
347
- if shape_errors:
348
- errors.append(f"形状声明不完整:{shape_errors}")
349
- return {"protocol_version": PROTOCOL_VERSION, "frozen": FROZEN,
350
- "doc": PROTOCOL_DOC, "declared": declared, "live": live,
351
- "reserved": reserved, "actual": actual, "has_impl": has_impl,
352
- "missing_impl": missing_impl, "extension_ops": extension_ops,
353
- "reserved_leaked": reserved_leaked, "shape_errors": shape_errors,
354
- "derive": list(OP_DERIVE), "errors": errors, "ok": not errors,
355
- # 扩展能力面的两条契约登记(2026-09-30):wrapper 级恒定键 +
356
- # protect.mark 负路由形态——都不属五动词形状表,故不并入 VERB_SPECS。
357
- "action_source": {"key": ACTION_SOURCE_KEY,
358
- "values": list(ACTION_SOURCE_VALUES)},
359
- "protect_neg_route": {"error": PROTECT_MARK_NEG_ROUTE_ERROR,
360
- "shape": dict(PROTECT_MARK_NEG_ROUTE)}}
361
-
362
-
363
- # 生效条件:verb 为 VERBS 成员时返回其 VERB_SPECS 规格 dict,非成员(含 None/空串)抛 KeyError;
364
- def spec_of(verb: str) -> dict:
365
- """取动词规格(非声明动词直接抛 KeyError——fail-closed,不返回空壳)。"""
366
- return VERB_SPECS[verb]
367
-
368
-
369
- # 生效条件:verb 已声明且 shape 为该动词 shapes 的键时返回该形态 dict;shape 缺省(None/空串)时返回其第一个形态;verb 未声明或 shape 不存在抛 KeyError;
370
- def shape_of(verb: str, shape: str = None) -> dict:
371
- """取某动词的形态声明(shape 缺省取第一个)。"""
372
- shapes = VERB_SPECS[verb]["shapes"]
373
- return shapes[shape] if shape else shapes[next(iter(shapes))]
374
-
375
-
376
- # 生效条件:无入参;始终返回单行字符串(格式 "protocol v1 live=4/5 reserved=1 ops=4 ok=True"),不抛异常;
377
- def summary() -> str:
378
- """单行结论(供 sustain / 报告页眉引用)。"""
379
- a = audit()
380
- return (f"protocol v{PROTOCOL_VERSION} live={len(a['live'])}/{len(a['declared'])} "
381
- f"reserved={len(a['reserved'])} ops={len(a['actual'])} "
382
- f"ext={len(a['extension_ops'])} ok={a['ok']}")
383
-
384
-
385
- # 生效条件:argv 为 None 时 argparse 取 sys.argv;--json 为真时打印缩进 JSON,否则打印人类可读多行;返回 0(ok)或 1(对账失败);
386
- def main(argv=None) -> int:
387
- p = argparse.ArgumentParser(prog="python -m md_cg.protocol",
388
- description="记忆动词协议 v1 静态对账(只读,零写入)")
389
- p.add_argument("--json", action="store_true", help="输出 JSON")
390
- a = p.parse_args(argv)
391
- rep = audit()
392
- if a.json:
393
- print(json.dumps(rep, ensure_ascii=False, indent=2))
394
- else:
395
- print(f"== {summary()} doc={rep['doc']} frozen={rep['frozen']}")
396
- print(f" 声明 = {rep['declared']}")
397
- print(f" MCP 实际 = {rep['actual']}")
398
- print(f" 扩展能力面(不属协议 v1,共 {len(rep['extension_ops'])} 项)"
399
- f"= {rep['extension_ops']}")
400
- for v in rep["declared"]:
401
- s = VERB_SPECS[v]
402
- print(f" [{s['status']:8s}] {v}: "
403
- f"{len(s['shapes'])} 形态 / requires_any={s['requires_any']}")
404
- for e in rep["errors"]:
405
- print(f" !! {e}")
406
- return 0 if rep["ok"] else 1
407
-
408
-
409
- if __name__ == "__main__":
410
- import sys
411
- sys.exit(main())
1
+ # -*- coding: utf-8 -*-
2
+ """md_cg · 记忆动词协议 v1(单一真源 · draft 期未冻结)
3
+
4
+ 目的(工作计划 §3.4):把 MCP 记忆工具面的**动词与 I/O 形状**冻结成可裁决的声明,
5
+ 使三端(本仓 MCP / DSH 内建基元 / 第三方客户端)能各自实现客户端而不必读源码;
6
+ 再由 `conformance.py` 的静态对账把「声明 ↔ 实现」钉死:
7
+
8
+ · 声明为 live 却在 MCP 面无分支 → FAIL(说了没做)
9
+ · reserved 动词在 MCP 面出现实现分支 → FAIL(预留位被静默实现,协议形同虚设)
10
+ · 协议外 op 分支 → 报告(扩展能力面,不是违例)
11
+
12
+ 范围(先行收窄):route / read / write / supersede / forget 五动词。
13
+
14
+ **扩展能力面的契约登记**(不并入五动词形状表,但同为本文件真源,2026-09-30):
15
+ ① `ACTION_SOURCE_KEY / ACTION_SOURCE_VALUES`——wrapper 级恒定键 `action_source`
16
+ (M4,四态 explicit/sig/default/none,任何 op 的 dict 返回恒在场);
17
+ ② `PROTECT_MARK_NEG_ROUTE`——`protect.mark` 的负路由 error 形态(H9)。
18
+ 两者由 `audit()` 的 `action_source` / `protect_neg_route` 段透出,并由 `test_protocol`
19
+ 的**同源源码守卫**钉住 mcp_server / protect 的实现(防「声明了没做」)。
20
+
21
+ **协议面 ≠ MCP 面全量**(2026-09-19 实测,issue #133 复核):`_cg_dispatch` 有数十个
22
+ op 分支(**确切数目不在此写死**——取 `audit()["actual"]`,或真源
23
+ `md_cg/op_table.py::_OP_TABLE`;修前此处写死「35 个」,已陈旧),
24
+ 其中除五动词外的(ccg / review / protect / verify / whitebox …)属**扩展能力面**——它们是能力,
25
+ 不是协议违例。把「协议覆盖范围」当成「MCP 面全量」会让协议每加一个 op 就永久红灯,
26
+ 故反向对账降级为 `extension_ops` 报告项(清单可见、不 FAIL);扩展面的文档一致性由
27
+ README 认知图 + `docs/mdcg/功能调用映射表` 的 cogmap 门禁承担(已在 CI)。
28
+
29
+ 三条纪律:
30
+ 1. **本文件是协议唯一真源**——文档 `docs/mdcg/灵枢记忆动词协议_v1.0-draft.md`
31
+ 与 `conformance.py` 的断言均从本文件取值,不另立第二份清单。
32
+ 2. **不冒充**——未实现的动词登记 `status="reserved"` 并给出 `map_to` 现状映射证据,
33
+ 不得写 live;live 的形状取**代码实测**(executor / 分支 return),不取设想。
34
+ 3. **draft 期(FROZEN=False)**——形状可破坏性调整;冻结是单向门,须三端实测收敛后
35
+ 由使用者拍板(工作计划 §9 风险 3)。
36
+
37
+ 用法:
38
+ python -m md_cg.protocol # 打印静态对账结论(只读,零写入)
39
+ """
40
+ from __future__ import annotations
41
+
42
+ import argparse
43
+ import ast
44
+ import inspect
45
+ import json
46
+ import textwrap
47
+
48
+ PROTOCOL_VERSION = 1
49
+ #: 冻结开关:True 后形状变更须走版本号递增(v1 → v2),不得原地改 v1 的形状
50
+ FROZEN = False
51
+ PROTOCOL_DOC = "docs/mdcg/灵枢记忆动词协议_v1.0-draft.md"
52
+ SURFACE_MODULE = "md_cg.mcp_server"
53
+ DISPATCH_FUNC = "_cg_dispatch"
54
+ CALL_FUNC = "_cg_call"
55
+
56
+ #: 协议声明的动词全集(顺序即文档呈现顺序)
57
+ VERBS = ("route", "read", "write", "supersede", "forget")
58
+
59
+ #: write 返回**铁律**:任一形态必含此三键——客户端据此判定「是否落盘」而非猜测。
60
+ #: 这是协议对三端客户端最有价值的一条:ok/committed 分离表达「闸门行为 ≠ 工具故障」。
61
+ WRITE_TRIO = ("ok", "id", "committed")
62
+
63
+ #: **盲区声明**(2026-10-12 设计者裁定,收束 issue #109 题3(b) 的争议):
64
+ #: 「本路径没有 audit 裁决可透出」这件事,**必须用一个显式标记表达**,而不是
65
+ #: 让 `verdict` 键**缺席**。缺席是歧义源(客户端无法区分「这条路径没有裁决」
66
+ #: 与「这个实现漏了给」);而**键在场、值为 `None`** 是可机器判读的**盲区声明**:
67
+ #: 「我们知道这里没填」。
68
+ #: ★裁定原文:补 `verdict: None`(键必在场,值表明「本路径无裁决」),使它满足
69
+ #: `gate_short_circuit`。**这是盲区声明,说明了一个我们知道当前没有填补的内容。**
70
+ #: 而「该分支没有 audit verdict 可透出,硬补一个 verdict 等于编造判据」这个判断
71
+ #: 也是对的 —— **正因如此,我们需要为一个无法识别的内容进行标记。盲区就是为这个
72
+ #: 情况设计的。**
73
+ #: ⇒ 两条不矛盾:**不许编造一个「有值」的裁决**(那条仍然成立),但**必须留标记**
74
+ #: (本条)。故凡「闸门短路且无 audit 裁决」的形态,`verdict` 一律进 `required`,
75
+ #: 取值 `None` 表示盲区。
76
+ VERDICT_BLINDSPOT = None
77
+
78
+ #: **工具面 → 动词绑定**(issue #109 题1,2026-10-10 裁定):写动词的 I/O 形状铁律
79
+ #: 不只约束 `cg(op=write)`,也约束**专用工具面**。`mdcg_remember` 是 hooks 自动记忆
80
+ #: 与直写的主通路(`mcp_server._dispatch` 的 mdcg_remember 分支),它此前**未在协议里
81
+ #: 出现**——于是「同一返回体在成功分支不给 committed、在待审分支给 committed=False」
82
+ #: 这类漂移没有声明可对:客户端只能按 ok 猜(把待审读成已提交)。
83
+ #: 声明语义:该工具面的每个 **dict 返回体**都必须 ①含 WRITE_TRIO;②未 committed 时
84
+ #: 给去向(moved_to 或 gate);③满足 write 的**至少一个声明形态**。由
85
+ #: `test_write_return_shape` 的「按声明形态全量校验」(静态 AST 面 + 运行面)钉住。
86
+ #: 注:`gated=true` 分支委托 `mdcos.remember_gated` 返回**闸门裁决信封**
87
+ #: (ok/gate/verdict/written,无 id/committed)——它不在三键面,见该守卫的显式豁免判据。
88
+ TOOL_FACE_BINDINGS = {
89
+ "mdcg_remember": {
90
+ "verb": "write",
91
+ "mutating": True,
92
+ "shapes_from": "write",
93
+ "impl": ("mcp_server", "_dispatch"),
94
+ "note": "受 WRITE_TRIO 铁律约束;gated=true 分支委托 remember_gated(闸门裁决信封,另计)",
95
+ },
96
+ }
97
+
98
+ #: op 推导兜底(`_cg_call` wrapper,2026-09-13 防呆落地):op 漏传时按入参签名推导。
99
+ #: 协议侧只作**文档化声明**(供客户端理解兜底语义),不做静态对账——
100
+ #: 推导实现散落在 wrapper 分支里,强做正则对账会误报(宁可少断言,不可假绿灯)。
101
+ OP_DERIVE = (
102
+ {"when": "content", "op": "write"},
103
+ {"when": "query", "op": "read"},
104
+ {"when": "node_id", "op": "read"},
105
+ {"when": "intent", "op": "route"},
106
+ {"when": "(无签名)", "op": "read"},
107
+ )
108
+
109
+ #: op 推导发生时**追加透出**的键(实测):additive,不破坏各形态 required 子集判定。
110
+ #: 协议语义:客户端看到这些键即知道「本次 op 是猜的」——据此可要求调用方补显式 op。
111
+ DERIVE_EXTRA_KEYS = ("op", "op_derived", "hint")
112
+
113
+ #: 校验裁决(verdict)的字段集——写路径闸门短路时随返回透出(实测)。
114
+ #: state 取值 = ACCEPT / REJECT / DEFER / BLINDSPOT(四态资格裁决)。
115
+ VERDICT_FIELDS = ("state", "kind", "basis", "evidence", "detail")
116
+
117
+ #: M4(2026-09-30)· **wrapper 级恒定键**:**任何 op** 的 dict 返回都带此键
118
+ #: (`_cg_call` 追加,实测 mcp_server.py:1849-1857 的 act_source 三元表达式 +
119
+ #: 其后 `out.setdefault("action_source", act_source)`)。
120
+ #: 取值四态(顺序即优先级):explicit(调用方显式传了 action)> sig(漏传 action
121
+ #: 但按参数签名推导出)> default(该 op 在默认动作表里有条目,走了默认)>
122
+ #: none(该 op 无默认动作,不编造)。协议语义:客户端据此可判断本次 action 是
123
+ #: **自己传的**还是**系统挑的**——旧行为只在「推导过」时透出 action_derived,
124
+ #: 显式传 action 时返回里没有任何痕迹。
125
+ #: 与 DERIVE_EXTRA_KEYS 的边界:那是「推导发生过才追加」(显式态下不出现),
126
+ #: 本键**恒在场**;两套标记并存互补,见 test_read_face_input_gates 的 M4-C 组。
127
+ ACTION_SOURCE_KEY = "action_source"
128
+ ACTION_SOURCE_VALUES = ("explicit", "sig", "default", "none")
129
+
130
+ #: H9(2026-09-30)· protect.mark 的**负路由形态**(实测 protect.py:374)。
131
+ #: 目标不存在时该分支返回此 dict——不是裸 None:旧行为裸返 None 被
132
+ #: `_protect_call` 序列化成 `null` 回客户端,「id 不存在」被读成「打标成功」,
133
+ #: 而 `_write_node` 从未发生。与 read 的 `node_missing` 同为「缺失 ≠ 成功」,
134
+ #: 但**形态不同、须分别处理**:read 返 `null`(returns_null=True),
135
+ #: protect 返结构化 error(ok=False + error + node_id)。
136
+ #: 调用方分流:失败看 `r.get("ok") is False` 或 `"error" in r`;成功路径的返回键
137
+ #: **不变**(node_id / protected / reason,**无 ok 键**——不可用 `ok` 判成功)。
138
+ PROTECT_MARK_NEG_ROUTE = {"ok": False, "error": "node_not_found",
139
+ "node_id": "<目标 id>"}
140
+ PROTECT_MARK_NEG_ROUTE_ERROR = "node_not_found"
141
+
142
+ VERB_SPECS = {
143
+ "route": {
144
+ "status": "live",
145
+ "mutating": False,
146
+ "impl": ("mcp_server", "_cg_dispatch"),
147
+ "requires_any": (("intent", "query"),),
148
+ "optional": ("k", "context"),
149
+ "shapes": {
150
+ "default": {
151
+ "when": "恒",
152
+ "required": ("knowledge", "meta"),
153
+ "optional": ("suggested_capabilities", "note"),
154
+ },
155
+ },
156
+ "semantics": "只给知识与建议能力名,不执行;由调用方决定下一步",
157
+ },
158
+ "read": {
159
+ "status": "live",
160
+ "mutating": False,
161
+ "impl": ("mcp_server", "_cg_dispatch"),
162
+ "requires_any": (("node_id",), ("query", "intent"), ("budget_tokens",)),
163
+ "optional": ("offset", "k", "context", "goal", "include_recent", "limit",
164
+ "session", "validity", "layer", "branch"),
165
+ "shapes": {
166
+ "node": {
167
+ "when": "node_id 非空且目标存在且可见",
168
+ "required": ("id", "path", "frontmatter", "content",
169
+ "verification_state"),
170
+ "optional": ("truncated", "content_lines", "content_bytes",
171
+ "offset", "next_offset", "note"),
172
+ },
173
+ "node_missing": {
174
+ "when": "node_id 非空但目标不存在 / 不可见 / 已软删",
175
+ "returns_null": True,
176
+ "required": (),
177
+ "optional": (),
178
+ "note": "**实测返回 null**(不是错误对象)——客户端须先判空再解析,"
179
+ "把 null 当异常会误报;把 null 当空内容会静默吞未知",
180
+ },
181
+ "list": {
182
+ "when": "budget_tokens 为空",
183
+ "required": ("meta", "results"),
184
+ "optional": (),
185
+ },
186
+ "pack": {
187
+ "when": "budget_tokens 非空(优先于 node_id 之外的 query 路径)",
188
+ "required": ("pack", "tokens_used", "budget", "skipped", "recent",
189
+ "meta"),
190
+ "optional": (),
191
+ # issue #76(2026-10-09 DSH 端登记):pack 的**条目级**形状。
192
+ # 顶层 required/optional 只声明**响应级**键;条目级此前无任何声明,
193
+ # 新增的 metadata 面因此无处可查。此处登记条目级与 metadata 级字段,
194
+ # 并由 test_recall_metadata 的声明一致性断言 + --mutate 组 A 守卫不漂移。
195
+ # 注:state=ACCEPT 只表示「当前查询适用」,与 verification_state
196
+ # (持久验证状态)**语义不同**,同一条可同时是 ACCEPT + unverified。
197
+ "entry_required": ("id", "score", "state", "tokens", "content",
198
+ "frontmatter", "provenance", "metadata"),
199
+ "entry_optional": ("truncated",),
200
+ "entry_metadata_required": ("state", "reason", "verification_state"),
201
+ "entry_metadata_optional": ("verification_basis", "check_strength",
202
+ "derived_from", "derived_relation",
203
+ "source"),
204
+ },
205
+ },
206
+ "semantics": "读动词三分态:单节点视图 / 检索结果列表 / token 预算包",
207
+ },
208
+ "write": {
209
+ "status": "live",
210
+ "mutating": True,
211
+ "impl": ("writepipe", "default_pipeline"),
212
+ "requires_any": (("content",),),
213
+ "optional": ("content_kind", "layer", "tags", "importance",
214
+ "verification_basis", "condition_space",
215
+ "non_applicable_conditions", "depends_on", "derived_from",
216
+ "relation", "valid_from", "valid_until", "verification_state",
217
+ "consistency", "on_conflict", "gated", "override",
218
+ "importance_hint", "semantic", "node_id"),
219
+ "shapes": {
220
+ "committed": {
221
+ "when": "链尾执行器落盘",
222
+ "required": WRITE_TRIO,
223
+ "optional": ("verdict", "consistency", "propagation"),
224
+ },
225
+ "gate_short_circuit": {
226
+ "when": "任一 before 闸门短路(审核 REJECT / DEFER / 冲突)",
227
+ "required": WRITE_TRIO + ("moved_to", "verdict", "hint"),
228
+ "optional": ("pid", "dedup", "dup_of", "dup_status", "consistency"),
229
+ },
230
+ "gate_hard_reject": {
231
+ "when": "契约缺失硬拒(依赖声明闸 E050/E051)",
232
+ # 2026-10-12 收束:同属「闸门短路且无 audit 裁决」⇒ verdict 进 required、
233
+ # 取值 None(盲区声明,见 VERDICT_BLINDSPOT)。实现见 writepipe._gate_deps。
234
+ "required": WRITE_TRIO + ("gate", "error", "verdict", "hint"),
235
+ "optional": ("missing",),
236
+ },
237
+ "gate_gated": {
238
+ "when": "主动遗忘闸(gated=true)替代落盘路径",
239
+ "required": WRITE_TRIO + ("gate", "verdict"),
240
+ "optional": ("consistency", "moved_to", "propagation"),
241
+ },
242
+ "autonomy_ticket": {
243
+ "when": "自治档位出单(确认档:变更单入审核队列、本次不落盘)",
244
+ # issue #109 题3(b)(2026-10-10 裁定)+ **2026-10-12 设计者收束**:
245
+ # 自治出单**不走 audit 链**,故**没有 audit 裁决可透出**——但这不是
246
+ # 「不要这个键」,而是「键必在场、值取盲区标记 None」(见 VERDICT_BLINDSPOT)。
247
+ # 原裁定「硬补 verdict 等于编造判据」指的是**不许编造一个有值的裁决**,
248
+ # 与「必须留盲区标记」不矛盾;缺席反而是歧义源(分不清「无裁决」与
249
+ # 「实现漏给」)。故 verdict 进 required,取值 None。
250
+ "required": WRITE_TRIO + ("moved_to", "pid", "mutation",
251
+ "autonomy", "verdict", "hint"),
252
+ # 特征键(**不含 verdict**):用于识别「本应是本形态、却缺了 verdict」
253
+ # 的**降级**返回体 —— 缺 verdict 时它仍会命中更松的 committed 形态,
254
+ # 若不额外判降级,就会「被更松的形态吞掉」(判据静默失效)。
255
+ # 由 `test_write_return_shape._static_violations` 判红。
256
+ "fingerprint": ("moved_to", "pid", "mutation", "autonomy"),
257
+ "optional": (),
258
+ },
259
+ },
260
+ "semantics": "写动词多形态:committed=已落盘;未 committed 时 moved_to/gate 说明去向,"
261
+ "hint 说明下一步(闸门正常行为、不是工具故障;政策违规类 REJECT「重试同样结果」,"
262
+ "缺必需要素类 REJECT 给出完整缺失清单与「补齐后重写」指引)",
263
+ },
264
+ "supersede": {
265
+ "status": "reserved",
266
+ "mutating": True,
267
+ "impl": None,
268
+ "requires_any": (("node_id",), ("superseded_by",)),
269
+ "optional": ("reason", "inherit_verification", "propagate"),
270
+ "shapes": {
271
+ "planned": {
272
+ "when": "(预留位,尚未实现)",
273
+ "required": ("ok", "id", "superseded_by"),
274
+ "optional": ("supersedes", "propagation", "verdict"),
275
+ },
276
+ },
277
+ "semantics": "以新节点取代旧节点:旧节点保留可审计但退出默认检索面,取代关系可追溯",
278
+ "map_to": (
279
+ {"verb": "write", "note": "新节点写入本身走 write(五动词不重复造写入通道)"},
280
+ {"verb": "review/verify", "note": "现有撤回体系由校验(verify 验伪)与审核"
281
+ "(review 的 delete/merge)承担,无独立取代动词"},
282
+ {"field": "nodefile.believed_at", "note": "取代语义的锚字段已就位(写侧注释),"
283
+ "缺的是动词入口与检索面过滤"},
284
+ ),
285
+ "reserved_reason": "取代会改变默认检索面(被取代节点是否可见),属行为变更,"
286
+ "须先冻结协议再落实现——避免三端各自发明可见性口径",
287
+ },
288
+ "forget": {
289
+ "status": "live",
290
+ "mutating": True,
291
+ "impl": ("mdcos", "MdCG.forget"),
292
+ "requires_any": (("node_id",),),
293
+ "optional": ("reason", "override", "action"),
294
+ "shapes": {
295
+ "forgotten": {
296
+ "when": "action 缺省或非 restore",
297
+ "required": ("ok", "id", "tombstone"),
298
+ "optional": (),
299
+ },
300
+ "restored": {
301
+ "when": "action == 'restore'",
302
+ "required": ("ok", "id", "forced"),
303
+ "optional": (),
304
+ },
305
+ "failed": {
306
+ "when": "目标不存在 / 已 tombstone(未 force)/ trash 无文件 / OSError",
307
+ "required": ("ok", "error"),
308
+ "optional": ("reason", "t", "action", "action_derived",
309
+ "hint_action"),
310
+ },
311
+ },
312
+ "semantics": "软删除与恢复:文件移入 trash/、写删除清单、摘索引;受保护节点需 override",
313
+ },
314
+ }
315
+
316
+
317
+ # 生效条件:node 为 ast 表达式节点;沿 Attribute/Call 递归剥到 Name,命中 Name("op") 返回 True,落到其它节点类型(含常量/字面量)返回 False;
318
+ def _is_op_expr(node) -> bool:
319
+ """判断 AST 表达式是否指向 `op`(兼容 `op.strip().lower()` 形态)。"""
320
+ cur = node
321
+ while True:
322
+ if isinstance(cur, ast.Name):
323
+ return cur.id == "op"
324
+ if isinstance(cur, ast.Attribute):
325
+ cur = cur.value
326
+ continue
327
+ if isinstance(cur, ast.Call):
328
+ cur = cur.func
329
+ continue
330
+ return False
331
+
332
+
333
+ # 生效条件:src 为字符串源码(缩进任意,内部先 dedent);ast.parse 成功返回按出现序去重的 op 字面量列表(识别 `op == "x"` 与 `op in ("x","y")` 两种形态,op 侧兼容 `op.strip().lower()`),解析失败(SyntaxError/TypeError/任意异常)返回空列表,不抛异常;
334
+ def _ops_from_source(src: str) -> list:
335
+ """从源码文本提取 op 分支名(dispatch_ops 与测试共用;测试可直接喂合成源码)。"""
336
+ try:
337
+ tree = ast.parse(textwrap.dedent(src or ""))
338
+ except Exception: # noqa: BLE001
339
+ return []
340
+ out = []
341
+ for node in ast.walk(tree):
342
+ if not isinstance(node, ast.Compare) or not _is_op_expr(node.left):
343
+ continue
344
+ for opnode, comp in zip(node.ops, node.comparators):
345
+ items = []
346
+ if isinstance(opnode, ast.Eq):
347
+ items = [comp]
348
+ elif isinstance(opnode, ast.In) and isinstance(
349
+ comp, (ast.Tuple, ast.List, ast.Set)):
350
+ items = list(comp.elts)
351
+ for it in items:
352
+ if isinstance(it, ast.Constant) and isinstance(it.value, str):
353
+ if it.value not in out:
354
+ out.append(it.value)
355
+ return out
356
+
357
+
358
+ # 生效条件:module 缺省取 SURFACE_MODULE、func 缺省取 DISPATCH_FUNC;导入模块 / 取属性 / getsource 任一抛异常,返回 {"ok": False, "error": "<类型>: <消息>", "ops": []};成功返回 {"ok": True, "module", "func", "ops": 按出现序去重的 op 字面量列表};
359
+ def dispatch_ops(module: str = None, func: str = None) -> dict:
360
+ """从分发函数源码用 **AST** 提取 op 分支(`if op == "x"` 与 `op in ("x","y")`)。
361
+
362
+ 为何用 AST 而非正则:正则对单引号/换行/`op.strip().lower()` 形态会静默漏提,
363
+ 而「漏提」在本协议里等于假绿灯(cogmap 已有同类教训)。AST 结构性识别不依赖写法。
364
+ """
365
+ mod_name = module or SURFACE_MODULE
366
+ fn_name = func or DISPATCH_FUNC
367
+ try:
368
+ m = __import__(mod_name, fromlist=[fn_name])
369
+ obj = getattr(m, fn_name)
370
+ src = inspect.getsource(obj)
371
+ except Exception as e: # noqa: BLE001
372
+ return {"ok": False, "error": f"{type(e).__name__}: {e}", "ops": []}
373
+ return {"ok": True, "module": mod_name, "func": fn_name,
374
+ "ops": _ops_from_source(src)}
375
+
376
+
377
+ # 生效条件:module/func 透传 dispatch_ops(默认面取模块常量);始终返回 dict,含 protocol_version/frozen/doc/live/reserved/declared/actual/has_impl/missing_impl/extension_ops/reserved_leaked/shape_errors/derive/errors/ok,任一静态对账项失败则 ok=False 且失败明细进 errors;
378
+ def audit(module: str = None, func: str = None) -> dict:
379
+ """静态对账:协议声明 ↔ MCP 面实现(不连库、不执行,纯源码事实)。"""
380
+ got = dispatch_ops(module, func)
381
+ actual = list(got.get("ops") or [])
382
+ declared = list(VERBS)
383
+ live = [v for v in declared if VERB_SPECS[v].get("status") == "live"]
384
+ reserved = [v for v in declared if VERB_SPECS[v].get("status") == "reserved"]
385
+ has_impl = [v for v in declared if v in actual]
386
+ missing_impl = [v for v in live if v not in actual]
387
+ # 协议 v1 只冻结五动词;MCP 面其余 op 属**扩展能力面**——它们是能力不是违例。
388
+ # 反向对账降级为报告项(extension_ops),理由见模块 docstring。
389
+ extension_ops = [v for v in actual if v not in declared]
390
+ reserved_leaked = [v for v in reserved if v in actual]
391
+ shape_errors = []
392
+ for v in declared:
393
+ spec = VERB_SPECS[v]
394
+ if spec.get("status") not in ("live", "reserved"):
395
+ shape_errors.append(f"{v}: status 取值非法 {spec.get('status')!r}")
396
+ shapes = spec.get("shapes") or {}
397
+ if not shapes:
398
+ shape_errors.append(f"{v}: 未声明任何形状")
399
+ for sname, sh in shapes.items():
400
+ if not sh.get("required") and not sh.get("returns_null"):
401
+ shape_errors.append(
402
+ f"{v}.{sname}: required 为空且未声明 returns_null")
403
+ if not sh.get("when"):
404
+ shape_errors.append(f"{v}.{sname}: 缺 when(何时走该形态)")
405
+ if spec.get("status") == "reserved" and not spec.get("map_to"):
406
+ shape_errors.append(f"{v}: reserved 但未声明 map_to 现状映射证据")
407
+ if spec.get("status") == "live" and not spec.get("impl"):
408
+ shape_errors.append(f"{v}: live 但未声明 impl 落点")
409
+ # 工具面绑定自洽(issue #109 题1):绑定的动词必须已声明,且 shapes_from 必须
410
+ # 指向一个已声明动词——否则「该工具面受三键铁律约束」这句声明无从校验(装饰)。
411
+ for _tool, _bind in TOOL_FACE_BINDINGS.items():
412
+ if _bind.get("verb") not in VERB_SPECS:
413
+ shape_errors.append(
414
+ f"{_tool}: 绑定动词未声明 {_bind.get('verb')!r}")
415
+ if _bind.get("shapes_from") not in VERB_SPECS:
416
+ shape_errors.append(
417
+ f"{_tool}: shapes_from 未声明 {_bind.get('shapes_from')!r}")
418
+ errors = []
419
+ if not got.get("ok"):
420
+ errors.append(f"源码提取失败:{got.get('error')}")
421
+ if missing_impl:
422
+ errors.append(f"声明为 live 但 MCP 面无分支:{missing_impl}")
423
+ if reserved_leaked:
424
+ errors.append(f"reserved 动词出现实现分支(实现了却未登记):{reserved_leaked}")
425
+ if shape_errors:
426
+ errors.append(f"形状声明不完整:{shape_errors}")
427
+ return {"protocol_version": PROTOCOL_VERSION, "frozen": FROZEN,
428
+ "doc": PROTOCOL_DOC, "declared": declared, "live": live,
429
+ "reserved": reserved, "actual": actual, "has_impl": has_impl,
430
+ "missing_impl": missing_impl, "extension_ops": extension_ops,
431
+ "reserved_leaked": reserved_leaked, "shape_errors": shape_errors,
432
+ "derive": list(OP_DERIVE), "errors": errors, "ok": not errors,
433
+ # 扩展能力面的两条契约登记(2026-09-30):wrapper 级恒定键 +
434
+ # protect.mark 负路由形态——都不属五动词形状表,故不并入 VERB_SPECS。
435
+ # 工具面绑定(issue #109 题1):声明的「工具面 → 动词」落点,客户端可据此
436
+ # 知道专用工具面与动词面**同一套形状铁律**。
437
+ "tool_faces": {t: dict(b) for t, b in TOOL_FACE_BINDINGS.items()},
438
+ "action_source": {"key": ACTION_SOURCE_KEY,
439
+ "values": list(ACTION_SOURCE_VALUES)},
440
+ "protect_neg_route": {"error": PROTECT_MARK_NEG_ROUTE_ERROR,
441
+ "shape": dict(PROTECT_MARK_NEG_ROUTE)}}
442
+
443
+
444
+ # 生效条件:verb 为 VERBS 成员时返回其 VERB_SPECS 规格 dict,非成员(含 None/空串)抛 KeyError;
445
+ def spec_of(verb: str) -> dict:
446
+ """取动词规格(非声明动词直接抛 KeyError——fail-closed,不返回空壳)。"""
447
+ return VERB_SPECS[verb]
448
+
449
+
450
+ # 生效条件:verb 已声明且 shape 为该动词 shapes 的键时返回该形态 dict;shape 缺省(None/空串)时返回其第一个形态;verb 未声明或 shape 不存在抛 KeyError;
451
+ def shape_of(verb: str, shape: str = None) -> dict:
452
+ """取某动词的形态声明(shape 缺省取第一个)。"""
453
+ shapes = VERB_SPECS[verb]["shapes"]
454
+ return shapes[shape] if shape else shapes[next(iter(shapes))]
455
+
456
+
457
+ # 生效条件:无入参;始终返回单行字符串(格式 "protocol v1 live=4/5 reserved=1 ops=4 ok=True"),不抛异常;
458
+ def summary() -> str:
459
+ """单行结论(供 sustain / 报告页眉引用)。"""
460
+ a = audit()
461
+ return (f"protocol v{PROTOCOL_VERSION} live={len(a['live'])}/{len(a['declared'])} "
462
+ f"reserved={len(a['reserved'])} ops={len(a['actual'])} "
463
+ f"ext={len(a['extension_ops'])} ok={a['ok']}")
464
+
465
+
466
+ # 生效条件:argv 为 None 时 argparse 取 sys.argv;--json 为真时打印缩进 JSON,否则打印人类可读多行;返回 0(ok)或 1(对账失败);
467
+ def main(argv=None) -> int:
468
+ p = argparse.ArgumentParser(prog="python -m md_cg.protocol",
469
+ description="记忆动词协议 v1 静态对账(只读,零写入)")
470
+ p.add_argument("--json", action="store_true", help="输出 JSON")
471
+ a = p.parse_args(argv)
472
+ rep = audit()
473
+ if a.json:
474
+ print(json.dumps(rep, ensure_ascii=False, indent=2))
475
+ else:
476
+ print(f"== {summary()} doc={rep['doc']} frozen={rep['frozen']}")
477
+ print(f" 声明 = {rep['declared']}")
478
+ print(f" MCP 实际 = {rep['actual']}")
479
+ print(f" 扩展能力面(不属协议 v1,共 {len(rep['extension_ops'])} 项)"
480
+ f"= {rep['extension_ops']}")
481
+ for v in rep["declared"]:
482
+ s = VERB_SPECS[v]
483
+ print(f" [{s['status']:8s}] {v}: "
484
+ f"{len(s['shapes'])} 形态 / requires_any={s['requires_any']}")
485
+ for e in rep["errors"]:
486
+ print(f" !! {e}")
487
+ return 0 if rep["ok"] else 1
488
+
489
+
490
+ if __name__ == "__main__":
491
+ import sys
492
+ sys.exit(main())