@furongjun1999/dsh-memory 0.8.1 → 0.9.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (717) hide show
  1. package/README.md +662 -659
  2. package/codebuddy/README.md +1 -1
  3. package/data/policy.json +38 -27
  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 +139 -139
  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 +37 -3
  18. package/lib/hooks.js +176 -24
  19. package/lib/index.d.ts +2 -2
  20. package/lib/index.js +29 -6
  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 +51 -3
  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 +28 -2
  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 +15 -2
  34. package/lib/tools.js +44 -4
  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 +37 -7
  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 +573 -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 +747 -726
  71. package/md_cg/conformance_core.py +753 -0
  72. package/md_cg/consistency.py +1278 -955
  73. package/md_cg/consolidate.py +1793 -1633
  74. package/md_cg/crypto.py +346 -24
  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 +262 -251
  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 +426 -345
  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 +7108 -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 +1103 -1100
  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 +654 -494
  108. package/md_cg/protocol.py +492 -411
  109. package/md_cg/provenance.py +606 -600
  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 +613 -604
  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 +657 -420
  123. package/md_cg/rollback_cli.py +124 -104
  124. package/md_cg/rotate.py +347 -0
  125. package/md_cg/routing.py +490 -429
  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 +144 -144
  133. package/md_cg/semantic/export_en_zh_map.py +2 -2
  134. package/md_cg/semantic/zh_en_atoms.py +141 -139
  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 +1091 -833
  139. package/md_cg/state_events.py +75 -10
  140. package/md_cg/state_slots.py +312 -221
  141. package/md_cg/stg.py +85 -18
  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 +2013 -1973
  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_code_kind_forbidden.py +101 -0
  172. package/md_cg/test_coldverify_drain.py +127 -0
  173. package/md_cg/test_condaccept.py +156 -0
  174. package/md_cg/test_condgate.py +141 -0
  175. package/md_cg/test_config_registry.py +55 -0
  176. package/md_cg/test_crypto_rotate.py +257 -0
  177. package/md_cg/test_csre_correctness.py +297 -0
  178. package/md_cg/test_csre_index_import_guard.py +161 -0
  179. package/md_cg/test_csre_mutations.py +34 -0
  180. package/md_cg/test_csre_session.py +69 -0
  181. package/md_cg/test_curiosity_budget.py +468 -0
  182. package/md_cg/test_d17_autostart_toolface.py +453 -0
  183. package/md_cg/test_datapath_tilde_home.py +271 -0
  184. package/md_cg/test_derived_cache_generations.py +256 -0
  185. package/md_cg/test_evidence_delivery_compact.py +54 -0
  186. package/md_cg/test_exact_text_cache.py +191 -0
  187. package/md_cg/test_excerpt_budget.py +188 -0
  188. package/md_cg/test_experience_consolidation.py +112 -0
  189. package/md_cg/test_export_default_collision.py +138 -0
  190. package/md_cg/test_export_snapshots.py +322 -0
  191. package/md_cg/test_fuzzy_substring_equivalence.py +127 -0
  192. package/md_cg/test_gain_gate.py +16 -5
  193. package/md_cg/test_goal_gen.py +355 -0
  194. package/md_cg/test_h2_session_view_norm.py +251 -233
  195. package/md_cg/test_h4_sustain_snapshot.py +1490 -1387
  196. package/md_cg/test_heartbeat_ledger.py +557 -0
  197. package/md_cg/test_hierarchy_audit_graph.py +237 -0
  198. package/md_cg/test_i50c_meta_passthrough.py +628 -608
  199. package/md_cg/test_i50e_readside_protection.py +658 -656
  200. package/md_cg/test_identity_attribution.py +96 -2
  201. package/md_cg/test_identity_contract.py +329 -0
  202. package/md_cg/test_imgskill.py +1444 -0
  203. package/md_cg/test_index_snapshot_shape.py +240 -0
  204. package/md_cg/test_interop_judgment.py +258 -228
  205. package/md_cg/test_issue111_gate_order.py +77 -0
  206. package/md_cg/test_issue111_scoring_contract.py +87 -0
  207. package/md_cg/test_issue121_calibration_bounds.py +293 -0
  208. package/md_cg/test_issue128_session_env_authority.py +246 -0
  209. package/md_cg/test_issue130_rrf_rank_credibility.py +217 -0
  210. package/md_cg/test_issue131_postings_content_staleness.py +424 -0
  211. package/md_cg/test_issue145_sleep_no_silent_rollback.py +168 -0
  212. package/md_cg/test_issue146_frontmatter_quarantine.py +428 -0
  213. package/md_cg/test_issue147_pack_id_escape.py +378 -0
  214. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -0
  215. package/md_cg/test_issue149_accel_default_face.py +249 -0
  216. package/md_cg/test_issue150_empty_query_terms.py +328 -0
  217. package/md_cg/test_issue151_153_157_write_cache_index.py +152 -0
  218. package/md_cg/test_issue151b_base_add_importance_guard.py +166 -0
  219. package/md_cg/test_issue152_sealed_postings.py +309 -0
  220. package/md_cg/test_issue152b_decrypt_cache.py +218 -0
  221. package/md_cg/test_issue153b_cache_alias_and_canon.py +236 -0
  222. package/md_cg/test_issue153b_index_generation_invalidation.py +143 -0
  223. package/md_cg/test_issue157b_index_remainder.py +344 -0
  224. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -0
  225. package/md_cg/test_issue190_tidy_idempotent.py +806 -0
  226. package/md_cg/test_issue191_import_trust.py +382 -0
  227. package/md_cg/test_issue192_move_layer_indices_guard.py +258 -0
  228. package/md_cg/test_issue193_consistency_knowledge_guard.py +524 -0
  229. package/md_cg/test_issue193_write_scope.py +378 -0
  230. package/md_cg/test_issue197_rank_credibility_property.py +201 -0
  231. package/md_cg/test_issue211_export_target.py +325 -0
  232. package/md_cg/test_issue212_writeface_gaps.py +349 -0
  233. package/md_cg/test_issue214_reject_sensitivity.py +267 -0
  234. package/md_cg/test_issue215_condition_source_gap.py +272 -0
  235. package/md_cg/test_issue216_clash_routes.py +214 -0
  236. package/md_cg/test_issue217_slot_routes.py +248 -0
  237. package/md_cg/test_issue218_postcondition_value_blind.py +222 -0
  238. package/md_cg/test_issue225_consistency_torn_log.py +433 -0
  239. package/md_cg/test_issue245_swarm_traversal.py +366 -0
  240. package/md_cg/test_issue258_pack_sensitivity.py +468 -0
  241. package/md_cg/test_issue265_coldverify_multiproc.py +438 -0
  242. package/md_cg/test_issue274_read_node_id_none.py +341 -0
  243. package/md_cg/test_issue275_layer_param.py +250 -0
  244. package/md_cg/test_issue277_node_id_traversal.py +384 -0
  245. package/md_cg/test_issue278_neg_separated_tension.py +271 -0
  246. package/md_cg/test_issue278_neg_window.py +294 -0
  247. package/md_cg/test_issue278_negative_layering.py +83 -0
  248. package/md_cg/test_issue279_signers_path_guard.py +652 -0
  249. package/md_cg/test_issue284_skip_not_pass.py +291 -0
  250. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -0
  251. package/md_cg/test_issue295_sleep_root_binding.py +589 -0
  252. package/md_cg/test_issue297_rewrite_sensitivity.py +454 -0
  253. package/md_cg/test_issue298_consistency_ledger_sensitivity.py +421 -0
  254. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -0
  255. package/md_cg/test_issue303_design_boundaries.py +262 -0
  256. package/md_cg/test_issue313_writelimit_sensitivity.py +404 -0
  257. package/md_cg/test_issue315_merge_branch_sensitivity.py +384 -0
  258. package/md_cg/test_issue315_sensitivity_passthrough_guard.py +514 -0
  259. package/md_cg/test_issue319_tenant_unregistered_bypass.py +257 -0
  260. package/md_cg/test_issue320_vstate_requires_verify.py +279 -0
  261. package/md_cg/test_issue321_mcp_deep_json.py +305 -0
  262. package/md_cg/test_issue322_node_write_lock.py +727 -0
  263. package/md_cg/test_issue323_aggregate_segment_boundary.py +365 -0
  264. package/md_cg/test_issue324_write_size_fields.py +215 -0
  265. package/md_cg/test_issue325_audit_poison.py +230 -0
  266. package/md_cg/test_issue326_append_jsonl_oserror.py +464 -0
  267. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -0
  268. package/md_cg/test_issue326_key_perms.py +355 -0
  269. package/md_cg/test_issue326_twin_parser_parity.py +323 -0
  270. package/md_cg/test_issue326_vm_call_frame.py +569 -0
  271. package/md_cg/test_issue345_writelimit_effective_sens.py +234 -0
  272. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -0
  273. package/md_cg/test_issue346_review_overwrite_guard.py +509 -0
  274. package/md_cg/test_issue348_insight_verify_op.py +200 -0
  275. package/md_cg/test_issue348_merge_rmw_lock.py +345 -0
  276. package/md_cg/test_issue350_casefold_collision.py +236 -0
  277. package/md_cg/test_issue351_ingest_root_fallback.py +202 -0
  278. package/md_cg/test_issue352_imgaudit.py +418 -0
  279. package/md_cg/test_issue352_pathsjson.py +537 -0
  280. package/md_cg/test_issue352_refindex.py +412 -0
  281. package/md_cg/test_issue352_rollback.py +604 -0
  282. package/md_cg/test_issue352_vstateinherit.py +196 -0
  283. package/md_cg/test_issue354_p1_writelimit_type.py +522 -0
  284. package/md_cg/test_issue354_p2_datapath_clock.py +381 -0
  285. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -0
  286. package/md_cg/test_issue354_rust_index_containment.py +571 -0
  287. package/md_cg/test_issue354_rust_wal_containment.py +606 -0
  288. package/md_cg/test_issue358_truncation_observable.py +247 -0
  289. package/md_cg/test_issue360_tidy_private_excerpt.py +196 -0
  290. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -0
  291. package/md_cg/test_issue362_neg_condition.py +468 -0
  292. package/md_cg/test_issue363_lexical_idf.py +275 -0
  293. package/md_cg/test_issue370_readcache_assembly.py +488 -0
  294. package/md_cg/test_issue375_state_slot_retire.py +325 -0
  295. package/md_cg/test_issue376_heartbeat_failed.py +293 -0
  296. package/md_cg/test_issue377_layer_protect_stamp.py +324 -0
  297. package/md_cg/test_issue378_protected_floor.py +310 -0
  298. package/md_cg/test_issue383_state_event_write_gate.py +462 -0
  299. package/md_cg/test_issue397_sens_eff_wiring.py +435 -0
  300. package/md_cg/test_issue398_toolface_op_parity.py +511 -0
  301. package/md_cg/test_issue399_hive_json_shape.py +317 -0
  302. package/md_cg/test_issue400_hive_dirty_args.py +450 -0
  303. package/md_cg/test_issue401_wisdom_codegen.py +295 -0
  304. package/md_cg/test_issue404_heal_receipt.py +390 -0
  305. package/md_cg/test_issue405_git_pathspec.py +333 -0
  306. package/md_cg/test_issue408_eface_registry.py +291 -0
  307. package/md_cg/test_issue409_compact_index_completeness.py +509 -0
  308. package/md_cg/test_issue410_verify_demote_write.py +366 -0
  309. package/md_cg/test_issue411_scrub_idempotence.py +575 -0
  310. package/md_cg/test_issue412_discipline_producer_parity.py +312 -0
  311. package/md_cg/test_issue413_preimage_failclosed.py +239 -0
  312. package/md_cg/test_issue413_preimage_twin.py +340 -0
  313. package/md_cg/test_issue414_write_args_parity.py +613 -0
  314. package/md_cg/test_issue415_deps_gate_probe.py +358 -0
  315. package/md_cg/test_issue416_entry_key_subset.py +525 -0
  316. package/md_cg/test_issue417_twophase_merge_landed.py +423 -0
  317. package/md_cg/test_issue418_identity_role_type_gate.py +188 -0
  318. package/md_cg/test_issue418_role_type_gate.py +265 -0
  319. package/md_cg/test_issue419_pii_redaction.py +642 -0
  320. package/md_cg/test_issue424_merge_confirm_sensitivity.py +381 -0
  321. package/md_cg/test_issue425_ingest_library_path.py +331 -0
  322. package/md_cg/test_issue426a_dedup_receipt.py +242 -0
  323. package/md_cg/test_issue426b_root_clash_invisible.py +270 -0
  324. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -0
  325. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -0
  326. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -0
  327. package/md_cg/test_issue427_serve_status_shape.py +191 -0
  328. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -0
  329. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -0
  330. package/md_cg/test_issue434_435_float_gate.py +90 -0
  331. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -0
  332. package/md_cg/test_issue43_default_policy.py +874 -865
  333. package/md_cg/test_issue443a_state_event_length_gate.py +94 -0
  334. package/md_cg/test_issue443b_audit_record_length_gate.py +83 -0
  335. package/md_cg/test_issue443c_self_state_imgskill_length_gate.py +77 -0
  336. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -0
  337. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -0
  338. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -0
  339. package/md_cg/test_issue446_is_encrypted_envelope.py +166 -0
  340. package/md_cg/test_issue447_recent_sens_failclosed.py +270 -0
  341. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -0
  342. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -0
  343. package/md_cg/test_issue451_audit_actor.py +313 -0
  344. package/md_cg/test_issue452_ingest_root_hint.py +238 -0
  345. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -0
  346. package/md_cg/test_issue463_ghost_prune_guard.py +259 -0
  347. package/md_cg/test_issue466_basis_registry.py +469 -0
  348. package/md_cg/test_issue467_identity_sensitivity.py +204 -0
  349. package/md_cg/test_issue467_identity_sensitivity_parity.py +361 -0
  350. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -0
  351. package/md_cg/test_issue470_wal_event_durable.py +427 -0
  352. package/md_cg/test_issue471_identity_readable.py +137 -0
  353. package/md_cg/test_issue472_audit_chain.py +91 -0
  354. package/md_cg/test_issue472_prune_ledger.py +106 -0
  355. package/md_cg/test_issue472_rollback_degraded.py +82 -0
  356. package/md_cg/test_issue491_compose_sandbox.py +460 -0
  357. package/md_cg/test_issue492_dup_readout_opt_in.py +292 -0
  358. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -0
  359. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -0
  360. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -0
  361. package/md_cg/test_issue522_review_record_sensitivity.py +267 -0
  362. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -0
  363. package/md_cg/test_issue525_read_null_semantics.py +52 -0
  364. package/md_cg/test_issue538_hook_condition_space.py +97 -0
  365. package/md_cg/test_issue540_path_guard_whitespace.py +126 -0
  366. package/md_cg/test_issue541_tidy_protect_gate.py +141 -0
  367. package/md_cg/test_issue542_tenant_root_same.py +153 -0
  368. package/md_cg/test_issue543_issue_authorization.py +147 -0
  369. package/md_cg/test_issue544_sandbox_reflection_gate.py +175 -0
  370. package/md_cg/test_issue545_charset_vs_size_diagnostic.py +77 -0
  371. package/md_cg/test_issue546_ledger_concurrency.py +81 -0
  372. package/md_cg/test_issue547_append_jsonl_whitelist.py +115 -0
  373. package/md_cg/test_issue547_audit_durable.py +96 -0
  374. package/md_cg/test_issue549_durable_append.py +143 -0
  375. package/md_cg/test_issue557_r1_credential_value_forms.py +76 -0
  376. package/md_cg/test_issue557_r2_write_entries_size_gate.py +84 -0
  377. package/md_cg/test_issue557_r3_pem_block_redaction.py +75 -0
  378. package/md_cg/test_issue559_refine_prefix.py +70 -0
  379. package/md_cg/test_issue561_pending_review.py +109 -0
  380. package/md_cg/test_issue562_retired_faces.py +150 -0
  381. package/md_cg/test_issue66_scrub_semantics.py +107 -0
  382. package/md_cg/test_issue67_scrub_control_pool.py +233 -0
  383. package/md_cg/test_issue69_audit_boundary.py +129 -0
  384. package/md_cg/test_issue71_queue_backlog.py +377 -0
  385. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -0
  386. package/md_cg/test_issue73_doc_chapter_refs.py +326 -0
  387. package/md_cg/test_issue75_neural_failure.py +582 -0
  388. package/md_cg/test_issue78_export_concurrency.py +334 -0
  389. package/md_cg/test_issue80_residual_flush.py +169 -0
  390. package/md_cg/test_issue82_credential_rules.py +271 -0
  391. package/md_cg/test_issue82_layer_and_size.py +120 -0
  392. package/md_cg/test_issue84_portability.py +95 -0
  393. package/md_cg/test_issue85_export_overwrite.py +113 -0
  394. package/md_cg/test_issue86_runtime_revoke.py +110 -0
  395. package/md_cg/test_issue87_default_sensitivity_single.py +201 -0
  396. package/md_cg/test_issue88_conclusion_face.py +280 -0
  397. package/md_cg/test_issue88_execution_conflicts.py +87 -0
  398. package/md_cg/test_issue89_zero_score.py +169 -0
  399. package/md_cg/test_issue89a_score_cap_tiebreak.py +279 -0
  400. package/md_cg/test_issue91_verifier_sandbox.py +314 -0
  401. package/md_cg/test_issue91_verifier_timeout.py +528 -0
  402. package/md_cg/test_issue93_remember_redaction.py +282 -0
  403. package/md_cg/test_issue96_key_fallback.py +102 -0
  404. package/md_cg/test_issue98_tenant_root.py +104 -0
  405. package/md_cg/test_jsonl_commit_watermark.py +221 -0
  406. package/md_cg/test_live_validity_cache.py +256 -0
  407. package/md_cg/test_logref.py +1141 -1109
  408. package/md_cg/test_mcp_call_argument_types.py +99 -0
  409. package/md_cg/test_md_access_parity.py +330 -255
  410. package/md_cg/test_md_cg_no_hive_dep.py +140 -0
  411. package/md_cg/test_memory_rsi.py +215 -0
  412. package/md_cg/test_memory_rsi_adversarial.py +91 -0
  413. package/md_cg/test_mode_parity.py +1413 -1393
  414. package/md_cg/test_mutation_residue.py +120 -0
  415. package/md_cg/test_mutation_rollback.py +835 -805
  416. package/md_cg/test_n123_derive_expiry_chain.py +210 -205
  417. package/md_cg/test_n130_verify_falsified_protect.py +185 -185
  418. package/md_cg/test_n209_verify_write_face_gates.py +466 -461
  419. package/md_cg/test_n230_dirty_replay.py +52 -9
  420. package/md_cg/test_n62_tenant_bind_failclosed.py +200 -200
  421. package/md_cg/test_neg_coverage_budget.py +500 -0
  422. package/md_cg/test_neg_tail_honesty.py +733 -663
  423. package/md_cg/test_p0.py +16 -2
  424. package/md_cg/test_p14_root_fallback.py +373 -0
  425. package/md_cg/test_p1x_ref_root.py +47 -10
  426. package/md_cg/test_p21_tokens.py +294 -293
  427. package/md_cg/test_p24_evidence.py +232 -227
  428. package/md_cg/test_p26_refindex.py +20 -3
  429. package/md_cg/test_p27_docindex.py +792 -777
  430. package/md_cg/test_p28_refcheck.py +1053 -1032
  431. package/md_cg/test_p29_session_ingest_export.py +6 -0
  432. package/md_cg/test_p2_mcp.py +474 -453
  433. package/md_cg/test_p2_six_elements.py +476 -463
  434. package/md_cg/test_p3.py +370 -261
  435. package/md_cg/test_p33_ccg_wiring.py +300 -293
  436. package/md_cg/test_p3_legacy_closure.py +438 -433
  437. package/md_cg/test_p40_refine_worklist.py +244 -241
  438. package/md_cg/test_p47_session_view.py +25 -9
  439. package/md_cg/test_p4_freshness.py +781 -774
  440. package/md_cg/test_p83_jsonrpc_parse_error.py +124 -0
  441. package/md_cg/test_p9c_dedup_hints.py +288 -283
  442. package/md_cg/test_policy_required_ccg.py +444 -432
  443. package/md_cg/test_postings_digest_memo.py +139 -0
  444. package/md_cg/test_predict_beta.py +138 -135
  445. package/md_cg/test_qmd.py +500 -0
  446. package/md_cg/test_query_excerpt.py +209 -0
  447. package/md_cg/test_reach.py +456 -378
  448. package/md_cg/test_reach_snapshot_admission.py +218 -0
  449. package/md_cg/test_readcache_prodpath.py +4 -0
  450. package/md_cg/test_recall_face_guards.py +854 -812
  451. package/md_cg/test_recall_metadata.py +422 -0
  452. package/md_cg/test_retr_s5.py +312 -213
  453. package/md_cg/test_retr_score_once.py +14 -2
  454. package/md_cg/test_review_cli_attribution.py +11 -7
  455. package/md_cg/test_review_queue_batch.py +123 -0
  456. package/md_cg/test_review_queue_index.py +130 -0
  457. package/md_cg/test_rrf_candidates.py +292 -0
  458. package/md_cg/test_rrf_qualified_topk.py +214 -0
  459. package/md_cg/test_rrf_unique_votes.py +218 -0
  460. package/md_cg/test_s1_ast_judge.py +110 -0
  461. package/md_cg/test_scrub_ledger.py +413 -0
  462. package/md_cg/test_security_audit_b26.py +34 -3
  463. package/md_cg/test_security_audit_v21.py +1 -2
  464. package/md_cg/test_sensitivity_predicate_single_point.py +184 -0
  465. package/md_cg/test_session5_identity.py +93 -0
  466. package/md_cg/test_session_attribution_consistency.py +813 -0
  467. package/md_cg/test_session_identity_tristate.py +486 -0
  468. package/md_cg/test_sleep_p1.py +35 -3
  469. package/md_cg/test_state_event_op.py +521 -514
  470. package/md_cg/test_state_projection_streaming.py +136 -0
  471. package/md_cg/test_stg_interval_candidates.py +280 -0
  472. package/md_cg/test_stg_time_blocks.py +239 -0
  473. package/md_cg/test_stgidx_index_parity.py +1024 -1020
  474. package/md_cg/test_subgraph_bounded_bfs.py +227 -0
  475. package/md_cg/test_sustain_bounded.py +652 -624
  476. package/md_cg/test_task_memory.py +394 -0
  477. package/md_cg/test_text_projection_mutations.py +101 -0
  478. package/md_cg/test_time_anchor.py +421 -0
  479. package/md_cg/test_time_core_lint.py +1024 -975
  480. package/md_cg/test_tool_face.py +200 -189
  481. package/md_cg/test_trust_bounded_frontier.py +248 -0
  482. package/md_cg/test_trust_edge_reachability.py +405 -0
  483. package/md_cg/test_w5_path_fingerprint.py +381 -0
  484. package/md_cg/test_w7_redlines.py +659 -0
  485. package/md_cg/test_write_return_shape.py +919 -0
  486. package/md_cg/test_writepipe.py +228 -226
  487. package/md_cg/timeanchor.py +534 -0
  488. package/md_cg/tokens.py +68 -5
  489. package/md_cg/tool_face.py +273 -260
  490. package/md_cg/trust.py +1114 -1030
  491. package/md_cg/twophase.py +303 -231
  492. package/md_cg/weights.py +642 -638
  493. package/md_cg/whitebox.py +536 -527
  494. package/md_cg/whitebox_kb/aeis_core/core.py +5026 -5026
  495. package/md_cg/whitebox_kb/wisdom/chat_engine.py +1504 -1506
  496. package/md_cg/whitebox_kb/wisdom/code_compose.py +876 -837
  497. package/md_cg/whitebox_kb/wisdom/compiler_code_units.py +3040 -3033
  498. package/md_cg/whitebox_kb/wisdom/compose_engine.py +1634 -1633
  499. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +318 -298
  500. package/md_cg/whitebox_kb/wisdom/core/parser.py +1082 -1065
  501. package/md_cg/whitebox_kb/wisdom/csre.py +412 -264
  502. package/md_cg/whitebox_kb/wisdom/csre_session.py +97 -0
  503. package/md_cg/whitebox_kb/wisdom/md_access.py +490 -470
  504. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +497 -476
  505. package/md_cg/whitebox_kb/wisdom/mini_python.py +995 -958
  506. package/md_cg/whitebox_kb/wisdom/navigate.py +249 -248
  507. package/md_cg/whitebox_kb/wisdom/net_units.py +2900 -2895
  508. package/md_cg/whitebox_kb/wisdom/neural_retrieve.py +100 -10
  509. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +4060 -4054
  510. package/md_cg/whitebox_kb/wisdom/test_ecosystem_assembly.py +158 -158
  511. package/md_cg/whitebox_kb/wisdom/test_safe_module_proxy.py +147 -0
  512. package/md_cg/whitebox_kb/wisdom/verifier.py +1918 -1297
  513. package/md_cg/writelimit.py +584 -390
  514. package/md_cg/writepipe.py +1337 -826
  515. package/package.json +14 -9
  516. package/scripts/workspace_index.py +328 -0
  517. package/src/bridge.ts +34 -11
  518. package/src/cli.ts +75 -65
  519. package/src/hooks.ts +932 -776
  520. package/src/index.ts +30 -7
  521. package/src/init.ts +362 -361
  522. package/src/lib/datapath.ts +419 -326
  523. package/src/lib/hook_audit.ts +42 -3
  524. package/src/lib/mdcg_client.ts +469 -461
  525. package/src/lib/mutual.ts +481 -432
  526. package/src/lib/prompt_safety.ts +178 -149
  527. package/src/lib/roleplay_web.ts +30 -2
  528. package/src/lib/token_store.ts +274 -52
  529. package/src/tools.ts +271 -223
  530. package/zcode/README.md +1 -1
  531. 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
  532. 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
  533. 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
  534. 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
  535. 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
  536. 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
  537. 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
  538. package/docs/eval/DSH/347/253/257/347/274/272/351/231/267/344/270/223/351/241/271_v1.0.md +0 -254
  539. 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
  540. 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
  541. package/docs/eval/bench_lingshu_self/bench_self.py +0 -140
  542. package/docs/eval/bench_lingshu_self/self_bench_result.json +0 -404
  543. 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
  544. 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
  545. 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
  546. 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
  547. 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
  548. 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
  549. 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
  550. 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
  551. 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
  552. 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
  553. 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
  554. 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
  555. 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
  556. 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
  557. 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
  558. 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
  559. 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
  560. 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
  561. 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
  562. 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
  563. 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
  564. 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
  565. 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
  566. 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
  567. 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
  568. 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
  569. 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
  570. 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
  571. 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
  572. 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
  573. 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
  574. 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
  575. 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
  576. 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
  577. 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
  578. 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
  579. 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
  580. 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
  581. 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
  582. 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
  583. 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
  584. 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
  585. 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
  586. 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
  587. 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
  588. 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
  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_v1.md +0 -156
  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_v10.md +0 -210
  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_v11.md +0 -227
  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_v12.md +0 -203
  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_v13.md +0 -233
  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_v14.md +0 -191
  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_v15.md +0 -213
  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_v16.md +0 -214
  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_v17.md +0 -199
  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_v18.md +0 -183
  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_v19.md +0 -207
  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_v2.md +0 -156
  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_v20.md +0 -283
  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_v21.md +0 -224
  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_v22.md +0 -223
  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_v23.md +0 -293
  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_v24.md +0 -303
  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_v25.md +0 -230
  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_v26.md +0 -196
  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_v27.md +0 -259
  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_v28.md +0 -217
  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_v29.md +0 -270
  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_v3.md +0 -152
  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_v30.md +0 -231
  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_v31.md +0 -281
  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_v4.md +0 -128
  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_v5.md +0 -114
  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_v6.md +0 -192
  617. 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
  618. 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
  619. 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
  620. 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
  621. 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
  622. 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
  623. 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
  624. 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
  625. 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
  626. 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
  627. 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
  628. 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
  629. 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
  630. 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
  631. 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
  632. 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
  633. 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
  634. 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
  635. 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
  636. package/docs/images/lingshu-moonlight-covenant-poster-preview.jpg +0 -0
  637. package/docs/images/lingshu-moonlight-covenant-poster.png +0 -0
  638. 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
  639. package/docs/mdcg/README/350/257/246/347/273/206/347/211/210_v0.4.10.md +0 -746
  640. package/docs/mdcg/guardrail-charter.md +0 -164
  641. package/docs/mdcg/lingshu_tutorial.html +0 -14956
  642. package/docs/mdcg/memory-assessment.html +0 -923
  643. package/docs/mdcg/memory_score.html +0 -213
  644. package/docs/mdcg/memory_score.png +0 -0
  645. package/docs/mdcg/release_v0.3.0.md +0 -36
  646. package/docs/mdcg/release_v0.4.11.md +0 -49
  647. package/docs/mdcg/release_v0.4.5.md +0 -55
  648. package/docs/mdcg/tool_table_v0.3.0.md +0 -117
  649. 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
  650. 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
  651. 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
  652. 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
  653. 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
  654. package/docs/mdcg//345/217/221/345/270/203/351/227/250/347/246/201/351/223/276_v0.1.md +0 -134
  655. 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
  656. 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
  657. 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
  658. 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
  659. 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
  660. 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
  661. 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
  662. 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
  663. package/docs/mdcg//347/274/272/345/217/243/345/215/225_P0/346/224/266/345/217/243_v0.1.md +0 -270
  664. 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
  665. 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
  666. 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
  667. 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
  668. 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
  669. 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
  670. 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
  671. 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
  672. 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
  673. 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
  674. 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
  675. 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
  676. 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
  677. 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
  678. 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
  679. 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
  680. 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
  681. 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
  682. 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
  683. package/docs/promo/bilibili-cover.jpg +0 -0
  684. package/docs/promo/promo-visual-1.png +0 -0
  685. package/docs/promo/promo-visual-2.png +0 -0
  686. package/docs/promo/promo-visual-3.png +0 -0
  687. package/docs/promo/promo-visual-4.png +0 -0
  688. package/docs/promo/promo-visual-5.png +0 -0
  689. package/docs/swarm//350/234/202/347/276/244/344/272/222/350/201/224_v0.1.md +0 -704
  690. 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
  691. 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
  692. 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
  693. 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
  694. 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
  695. 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
  696. 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
  697. 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
  698. 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
  699. 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
  700. package/docs/theory//346/231/272/350/203/275/350/256/2723.4.md +0 -5260
  701. 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
  702. 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
  703. 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
  704. 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
  705. 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
  706. 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
  707. 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
  708. 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
  709. 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
  710. 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
  711. 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
  712. 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
  713. 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
  714. 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
  715. 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
  716. 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
  717. 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())