@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
@@ -1,601 +1,607 @@
1
- # -*- coding: utf-8 -*-
2
- """派生溯源(G8):新增节点常态化建链 + 悬空可检出。
3
-
4
- 回答「这个节点**从哪来**」——与 `md_cg.links` 刻意分层:
5
- · `links.py` = 跨节点信任(「我信你多少」,P_trust,落 `~/.mdcg/_links.json`);
6
- · 本模块 = 节点派生关系(「它由谁派生」,落 `<root>/_link.jsonl`)。
7
- 两者都叫「链接」,但一个管**信任状态**、一个管**演进血缘**,不可混用。
8
-
9
- 存储形态(对齐「md 单一真相源 + 派生索引可重建」):
10
- · 权威声明在节点 frontmatter(`derived_from` / `derived_relation`);
11
- · `<root>/_link.jsonl` 是 **append-only 派生台账**(快查用,可由 frontmatter 重建);
12
- · 建链失败写 `<root>/_link.jsonl.fail`(降级留痕)。
13
-
14
- 三条纪律(对齐 G8 裁定 §六):
15
- 1. **只对新增节点常态化建链,历史不回填**——`rebuild_ledger` 只重放 frontmatter
16
- 里**已经声明**的关系,不为历史节点发明任何边(当前库历史声明为 0 → 重建为空);
17
- 2. **建链失败不得阻断写入**——`record()` 永不抛(best-effort),失败降级为告警 +
18
- 失败台账留痕,节点写入照常提交;
19
- 3. **巡检只读**——`check()` 检出悬空边(目标/子节点不在索引内)但**不自动删边**,
20
- 关系事实去留由人处置。
21
-
22
- 零第三方依赖。
23
- """
24
- from __future__ import annotations
25
-
26
- import json
27
- import os
28
- import time
29
-
30
- from . import trust as _trust
31
- from . import security as _security
32
- from .fsutil import FileLock, append_jsonl, atomic_write, read_jsonl
33
-
34
- LEDGER_NAME = "_link.jsonl"
35
- FAIL_SUFFIX = ".fail"
36
- LEDGER_ENV = "MDCG_LINK_FILE"
37
- SCHEMA = 1
38
-
39
- #: 允许的派生关系(显式枚举,避免「自由字符串」把血缘写成噪声)
40
- RELATIONS = ("derived_from", "split_from", "extracted_from",
41
- "merged_from", "refined_from", "source")
42
- DEFAULT_RELATION = "derived_from"
43
-
44
- #: frontmatter 里承载派生声明的字段(写路径只读这两处,不猜)
45
- FM_FIELD = "derived_from"
46
- FM_REL_FIELD = "derived_relation"
47
-
48
- _LOCK_TIMEOUT = 2.0
49
-
50
-
51
- class ProvenanceError(Exception):
52
- """派生溯源错误。写路径侧一律由 `record()` 兜住,不向上抛。"""
53
-
54
-
55
- # --------------------------------------------------------------------------
56
- # 路径 / 规范化
57
- # --------------------------------------------------------------------------
58
-
59
- # 生效条件:path 为真值时返回 path;否则 os.environ.get(LEDGER_ENV) 为非空真值时返回该环境变量值;否则返回 os.path.join(root, LEDGER_NAME)。
60
- def ledger_file(root: str, path: str = None) -> str:
61
- """台账路径:显式 → MDCG_LINK_FILE → <root>/_link.jsonl。"""
62
- return path or os.environ.get(LEDGER_ENV) or os.path.join(root, LEDGER_NAME)
63
-
64
-
65
- # 生效条件:传入 root(path 为真值则以其为准,否则由 ledger_file 的回落决定落点)时返回 ledger_file(root, path) 结果拼接 FAIL_SUFFIX。
66
- def fail_log_file(root: str, path: str = None) -> str:
67
- """降级留痕路径(台账写不进时的「本该建的边」)。"""
68
- return ledger_file(root, path) + FAIL_SUFFIX
69
-
70
-
71
- # 生效条件:value 为 None 返回 [];否则 list/tuple/set 逐个元素、其他类型视作单元素,元素经 str(x).strip() 后非空且未出现过才保留(重复只留首次)。
72
- def as_list(value) -> list:
73
- """把单值 / 序列统一成去重、去空白的字符串列表。"""
74
- if value is None:
75
- return []
76
- items = list(value) if isinstance(value, (list, tuple, set)) else [value]
77
- out = []
78
- for x in items:
79
- s = str(x).strip()
80
- if s and s not in out:
81
- out.append(s)
82
- return out
83
-
84
-
85
- # 生效条件:rel 为假值(None/空串)或 str(rel).strip().lower() 后为空白的串(如 " ")时 r 回落 default(默认常量 DEFAULT_RELATION);r 不在 RELATIONS 内(含回落后的 default 本身非法)即抛 ProvenanceError,否则返回该小写串。
86
- def normalize_relation(rel, default: str = DEFAULT_RELATION) -> str:
87
- """严格校验关系名;非法抛 `ProvenanceError`(显式 API 用)。"""
88
- r = str(rel or "").strip().lower()
89
- if not r:
90
- r = default
91
- if r not in RELATIONS:
92
- raise ProvenanceError(f"未知派生关系:{rel}(允许:{RELATIONS})")
93
- return r
94
-
95
-
96
- # 生效条件:normalize_relation(rel, default) 抛 ProvenanceError(含 rel 为假值/仅空白且 default 非法时)则原样返回 default;否则返回该调用的返回值。
97
- def coerce_relation(rel, default: str = DEFAULT_RELATION) -> str:
98
- """宽松兜底:非法关系名回退默认值(**写路径用,保证永不阻断写入**)。"""
99
- try:
100
- return normalize_relation(rel, default)
101
- except ProvenanceError:
102
- return default
103
-
104
-
105
- # 生效条件:child 或 parent 为假值或仅空白使 str(x or "").strip() 为空、或二者 strip 后相等(自环)时返回 None;否则返回含 schema/t/child/parent/rel/batch/actor 的 dict,note 为真值时才附上并截断到 200 字符。
106
- def make_edge(child, parent, *, relation=DEFAULT_RELATION, batch=None,
107
- actor="system", note=None, t=None):
108
- """构造一条派生边;自环 / 空端点返回 None(**不产生无意义边**)。"""
109
- c, p = str(child or "").strip(), str(parent or "").strip()
110
- if not c or not p or c == p:
111
- return None
112
- edge = {"schema": SCHEMA,
113
- "t": float(t if t is not None else time.time()),
114
- "child": c, "parent": p, "rel": coerce_relation(relation),
115
- "batch": batch, "actor": actor}
116
- if note:
117
- edge["note"] = str(note)[:200]
118
- return edge
119
-
120
-
121
- # 生效条件:对 as_list(parents) 的每个父项调用 make_edge,只保留返回非 None 的边,全部被丢弃时返回空列表。
122
- def edges_for(child, parents, **kw) -> list:
123
- """`(child, [parents]) → [edge]`:空端点 / 自环自动丢弃。"""
124
- out = []
125
- for p in as_list(parents):
126
- e = make_edge(child, p, **kw)
127
- if e:
128
- out.append(e)
129
- return out
130
-
131
-
132
- # --------------------------------------------------------------------------
133
- # 写:台账追加(record 为写路径唯一入口,永不抛)
134
- # --------------------------------------------------------------------------
135
-
136
- # 生效条件:edges 为 None/空/全为假元素时返回 0;否则在 FileLock(p, timeout=_LOCK_TIMEOUT) 内逐条 append_jsonl,抛 OSError 时转抛 ProvenanceError,成功返回 len(edges)。
137
- def append(root: str, edges, *, path: str = None) -> int:
138
- """台账追加(加锁串行,防 Windows 并发交错丢边)。IO 失败抛 `ProvenanceError`。"""
139
- edges = [e for e in (edges or []) if e]
140
- if not edges:
141
- return 0
142
- p = ledger_file(root, path)
143
- try:
144
- os.makedirs(os.path.dirname(os.path.abspath(p)) or ".", exist_ok=True)
145
- with FileLock(p, timeout=_LOCK_TIMEOUT):
146
- for e in edges:
147
- append_jsonl(p, e)
148
- except OSError as exc:
149
- raise ProvenanceError(f"派生台账写入失败:{p}({exc})") from exc
150
- return len(edges)
151
-
152
-
153
- # 生效条件:给定 root/path/child/parents/relation/reason/code 即恒返回 {'ok': False, 'added': 0, 'edges': [], 'degraded': True, 'degrade_code': code, 'reason': reason},其中写 fail_log_file 台账的异常被 except Exception 吞掉。
154
- def _degrade(root: str, path, child, parents, relation, reason,
155
- code: str) -> dict:
156
- """降级留痕:把「本该建的边」记进 .fail 台账(自身也 best-effort)。"""
157
- rec = {"t": time.time(), "code": code, "child": str(child or ""),
158
- "parents": as_list(parents), "rel": str(relation or ""),
159
- "reason": str(reason)[:300]}
160
- try:
161
- append_jsonl(fail_log_file(root, path), rec)
162
- except Exception: # noqa: BLE001
163
- pass
164
- return {"ok": False, "added": 0, "edges": [], "degraded": True,
165
- "degrade_code": code, "reason": reason}
166
-
167
-
168
- # 生效条件:edges_for 抛异常时经 _degrade(code='bad_edge') 返回;edges 为空时返回 {'ok': True, 'added': 0, 'edges': [], 'reason': 'no_parents'};append 抛 ProvenanceError 或其他异常时经 _degrade(code='ledger_io') 返回;其余返回 {'ok': True, 'added': n, 'edges': edges, 'ledger': …},恒不向外抛。
169
- def record(root: str, child, parents, *, relation=DEFAULT_RELATION,
170
- batch=None, actor="system", note=None, path: str = None) -> dict:
171
- """写路径建链入口:**永不抛**(G8 硬约束:建链失败不得阻断节点写入)。
172
-
173
- 返回 `{ok, added, edges, ...}`;失败时 `ok=False` + `degraded=True` 且已写
174
- `.fail` 留痕。调用方**不得**因本函数返回 False 而回滚节点。
175
- """
176
- try:
177
- edges = edges_for(child, parents, relation=relation, batch=batch,
178
- actor=actor, note=note)
179
- except Exception as exc: # noqa: BLE001
180
- return _degrade(root, path, child, parents, relation,
181
- f"{type(exc).__name__}: {exc}", "bad_edge")
182
- if not edges:
183
- return {"ok": True, "added": 0, "edges": [], "reason": "no_parents"}
184
- try:
185
- n = append(root, edges, path=path)
186
- except ProvenanceError as exc:
187
- return _degrade(root, path, child, parents, relation, str(exc),
188
- "ledger_io")
189
- except Exception as exc: # noqa: BLE001
190
- return _degrade(root, path, child, parents, relation,
191
- f"{type(exc).__name__}: {exc}", "ledger_io")
192
- return {"ok": True, "added": n, "edges": edges,
193
- "ledger": ledger_file(root, path)}
194
-
195
-
196
- # --------------------------------------------------------------------------
197
- # 读:台账 / 索引 / 悬空巡检
198
- # --------------------------------------------------------------------------
199
-
200
- # 生效条件:遍历 read_jsonl(ledger_file(root, path)),仅收录 isinstance(r, dict) 且 r.get("child") 与 r.get("parent") 均为真值(键缺失或值为假即丢弃)的记录。
201
- def load(root: str, *, path: str = None) -> list:
202
- """读台账(跳过坏行;只取有端点的记录)。"""
203
- out = []
204
- for r in read_jsonl(ledger_file(root, path)):
205
- if isinstance(r, dict) and r.get("child") and r.get("parent"):
206
- out.append(r)
207
- return out
208
-
209
-
210
- # 生效条件:rows 中每行按 (r.get("child"), r.get("parent"), r.get("rel")) 三元组判重,仅首次出现的行保留,按原顺序返回去重列表。
211
- def _dedupe(rows):
212
- out, seen = [], set()
213
- for r in rows:
214
- key = (r.get("child"), r.get("parent"), r.get("rel"))
215
- if key in seen:
216
- continue
217
- seen.add(key)
218
- out.append(r)
219
- return out
220
-
221
-
222
- # 生效条件:child/parent/relation/batch 各为真值时才做对应等值过滤(假值或 None 不过滤),去重后 limit 为真值时返回 out[:int(limit)],limit 为 None 或 0 时返回全部 out。
223
- def edges(root: str, *, child=None, parent=None, relation=None, batch=None,
224
- limit: int = None, path: str = None) -> list:
225
- """按端点 / 关系 / 批次过滤台账边(只读,去重,保持写入顺序)。"""
226
- out = []
227
- for r in load(root, path=path):
228
- if child and r.get("child") != child:
229
- continue
230
- if parent and r.get("parent") != parent:
231
- continue
232
- if relation and r.get("rel") != relation:
233
- continue
234
- if batch and r.get("batch") != batch:
235
- continue
236
- out.append(r)
237
- out = _dedupe(out)
238
- return out[:int(limit)] if limit else out
239
-
240
-
241
- # 生效条件:以 (getattr(cg, "index", None) or {}).get("nodes") or {} 遍历(缺失时视作空);prefix 为真值时仅保留 str(nid).startswith(prefix) 的节点,输出经 _dedupe 去重。
242
- def index_edges(cg, *, prefix: str = None) -> list:
243
- """从**索引快照**恢复派生边(零读文件)——台账丢失/未重建时的只读兜底。"""
244
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
245
- out = []
246
- for nid, e in list(nodes.items()):
247
- if prefix and not str(nid).startswith(prefix):
248
- continue
249
- rel = coerce_relation((e or {}).get(FM_REL_FIELD))
250
- for p in as_list((e or {}).get(FM_FIELD)):
251
- out.append({"schema": SCHEMA, "child": nid, "parent": p, "rel": rel,
252
- "batch": (e or {}).get("derived_batch"), "actor": None,
253
- "origin": "index"})
254
- return _dedupe(out)
255
-
256
-
257
- # 生效条件:给定 cg 即返回 _dedupe(load(cg.root, path=path) + index_edges(cg)),台账记录在前、按边去重。
258
- def all_edges(cg, *, path: str = None) -> list:
259
- """台账 ∪ 索引声明(台账优先,按边去重)。"""
260
- return _dedupe(load(cg.root, path=path) + index_edges(cg))
261
-
262
-
263
- # 生效条件:include_index 为真值时取 all_edges(cg, path=path)、为假时取 load(cg.root, path=path),对 child/parent 不在 cg 索引节点键集合中的边记为 dangling 并列出 missing;返回 ok=not dangling,dangling 仅取 int(limit)(默认 20)项,不写盘。
264
- def check(cg, *, path: str = None, limit: int = 20,
265
- include_index: bool = True) -> dict:
266
- """只读巡检:检出**悬空派生边**(端点不在索引内)。**不删边、不写盘**。
267
-
268
- `ok=False` 仅表示「有悬空」,不代表巡检失败;`checked=True` 恒成立。
269
- """
270
- known = set((getattr(cg, "index", None) or {}).get("nodes") or {})
271
- rows = all_edges(cg, path=path) if include_index else load(cg.root, path=path)
272
- dangling = []
273
- for e in rows:
274
- missing = []
275
- if e.get("child") not in known:
276
- missing.append("child")
277
- if e.get("parent") not in known:
278
- missing.append("parent")
279
- if missing:
280
- dangling.append({"child": e.get("child"), "parent": e.get("parent"),
281
- "rel": e.get("rel"), "missing": missing,
282
- "batch": e.get("batch"), "t": e.get("t"),
283
- "origin": e.get("origin") or "ledger"})
284
- dangling.sort(key=lambda r: (r.get("child") or "", r.get("parent") or ""))
285
- ledger = ledger_file(cg.root, path)
286
- return {"ok": not dangling, "checked": True, "root": cg.root,
287
- "ledger": ledger, "ledger_exists": os.path.exists(ledger),
288
- "edges": len(rows), "nodes": len(known),
289
- "dangling": dangling[:int(limit)], "dangling_count": len(dangling),
290
- "readonly": True,
291
- "note": "只读巡检:悬空边仅检出并报告,不自动删除(关系事实由人处置)"}
292
-
293
-
294
- # 生效条件:apply 为假值(默认 False)时只返回 dry_run 报表(written=0、sample=es[:5]);apply 为真值时把 index_edges(cg) 的边写入 ledger_file(cg.root, path) 并返回 written=len(es)。
295
- def rebuild_ledger(cg, *, apply: bool = False, path: str = None) -> dict:
296
- """按 frontmatter 重建台账——**只重放已声明的边,不发明任何边**。
297
-
298
- 历史节点未声明派生关系 → 重建结果为空,正合「历史不回填」。
299
- 默认 dry_run(只出报表)。
300
- """
301
- es = index_edges(cg)
302
- if not apply:
303
- return {"ok": True, "dry_run": True, "edges": len(es),
304
- "written": 0, "sample": es[:5],
305
- "note": "预演:未写盘;只重放 frontmatter 已声明的关系"}
306
- body = "".join(json.dumps(e, ensure_ascii=False, separators=(",", ":")) + "\n"
307
- for e in es)
308
- p = ledger_file(cg.root, path)
309
- atomic_write(p, body)
310
- return {"ok": True, "dry_run": False, "edges": len(es),
311
- "written": len(es), "ledger": p}
312
-
313
-
314
- # 生效条件:check(cg, path=path, limit=3) 成功时返回 edges/dangling/ledger/exists/sample(悬空边 child->parent);该调用抛任何异常时被 except Exception 吞掉并返回 {}。
315
- def summary(cg, *, path: str = None) -> dict:
316
- """轻量摘要(只读;失败不抛,避免拖垮 health_os / 常驻循环)。"""
317
- try:
318
- rep = check(cg, path=path, limit=3)
319
- return {"edges": rep["edges"], "dangling": rep["dangling_count"],
320
- "ledger": rep["ledger"], "exists": rep["ledger_exists"],
321
- "sample": [f"{r['child']}->{r['parent']}"
322
- for r in rep["dangling"]]}
323
- except Exception: # noqa: BLE001
324
- return {}
325
-
326
-
327
- # 生效条件:root 为真值时 ledger 字段取 ledger_file(root),否则取常量 LEDGER_NAME;其余自描述字段(SCHEMA、RELATIONS、DEFAULT_RELATION、FM_FIELD/FM_REL_FIELD 等)恒定返回。
328
- def catalog(root: str = None) -> dict:
329
- """自描述(供 MCP catalog / 人工核对)。"""
330
- return {
331
- "layer": "派生溯源(G8)",
332
- "question": "这个节点从哪来(演进血缘)",
333
- "ledger": ledger_file(root) if root else LEDGER_NAME,
334
- "schema": SCHEMA,
335
- "relations": list(RELATIONS),
336
- "default_relation": DEFAULT_RELATION,
337
- "fm_fields": [FM_FIELD, FM_REL_FIELD],
338
- "discipline": {"incremental_only": True, "no_backfill": True,
339
- "never_block_write": True, "patrol_readonly": True},
340
- "distinct_from": ("links.py = 跨节点信任 P_trust(_links.json);"
341
- "本层 = 节点派生关系(_link.jsonl)"),
342
- }
343
-
344
-
345
- # --------------------------------------------------------------------------
346
- # 读:三元组反查原语(阶段二 4.2 · find_entity_contexts 式)
347
- # --------------------------------------------------------------------------
348
- # 术语映射(**同一件事,勿新造第二套字段**):三元组 `subject / predicate /
349
- # object` 在本层就是派生边的 `child / rel / parent`——即节点写入时声明的
350
- # `derived_from` 关系。不另建 subject/predicate/object 参数字面量,理由有二:
351
- # ① `cg` 工具面是**扁平 schema**,`subject` 已被 `identity`(`subject:<id>`
352
- # 主体语义)与 `link.evidence`(证据主体)占用,同名异义会把两处口径搅在一起;
353
- # ② `edges()` 已是唯一谓词载体(child/parent/relation/batch 四键),反查只是它的
354
- # **只读超集**——另造一套参数必然分叉。
355
- # 与 `edges()` 的三处**有意**差异(不是漂移):
356
- # · 时间轴缺省 `observed`(边只有记录时刻 `t`,见 FIND_DEFAULT_AXIS);
357
- # · 默认排序 `desc`(按 `t` 新→旧)且 `limit` 缺省 50、上限 500(分页原语,
358
- # 不给「静默全量倾倒」);
359
- # · 加 `aggregation`(分页前全集分桶)与 `expand_nodes`(端点摘要,索引级零读盘)。
360
-
361
- #: 排序方向(封闭枚举,拒收未知名——与 `trust.TIME_OPERATORS` 同风格)
362
- ORDERINGS = ("desc", "asc")
363
- #: 聚合维度(封闭枚举):按谓词 / 对象端 / 主体端分桶
364
- AGGREGATIONS = ("by_relation", "by_parent", "by_child")
365
- #: 聚合维度 → 边字段(谓词在边上叫 `rel`;聚合名沿用三元组术语命名)
366
- _AGG_FIELD = {"by_relation": "rel", "by_parent": "parent", "by_child": "child"}
367
- #: 反查缺省时间轴:派生边只有一个时刻字段 `t`(写入时刻,观察轴),
368
- #: **效力轴字段根本不存在**。与 `mdcg.search` 缺省 `effective` **有意不同**:
369
- #: 那里 `effective_from/until` 是可选声明(多数节点没写),沿用 fail-open 不会
370
- #: 出错;这里若缺省 `effective`,则「给了时间条件却恒不过滤」——把静默 no-op
371
- #: 当成了「没有匹配」,属无法复算的错答。
372
- FIND_DEFAULT_AXIS = "observed"
373
- DEFAULT_FIND_LIMIT = 50
374
- MAX_FIND_LIMIT = 500
375
- #: `expand_nodes=True` 时透出的索引字段白名单(只读索引快照,**零读节点文件**)
376
- EXPAND_FIELDS = ("layer", "tags", "importance", "writer", "session",
377
- "derived_from", "derived_relation", "derived_batch",
378
- "temporal", "time_window", "condition_space")
379
-
380
-
381
- # 生效条件:value 为 None 或 str(value).strip() 为空时返回 "desc";小写后命中 ORDERINGS 返回该值;否则抛 ProvenanceError。
382
- def _ordering_of(value) -> str:
383
- """排序方向归一 → `"desc"` / `"asc"`;未知 → `ProvenanceError`(fail-closed)。"""
384
- if value is None or not str(value).strip():
385
- return "desc"
386
- v = str(value).strip().lower()
387
- if v not in ORDERINGS:
388
- raise ProvenanceError(f"未知 ordering {value!r}(允许:{ORDERINGS})")
389
- return v
390
-
391
-
392
- # 生效条件:value 为 None 或 str(value).strip() 为空时返回 None(= 不聚合);小写后命中 AGGREGATIONS 返回该值;否则抛 ProvenanceError。
393
- def _aggregation_of(value):
394
- """聚合维度归一 → `None` / `AGGREGATIONS` 之一;未知 → `ProvenanceError`。"""
395
- if value is None or not str(value).strip():
396
- return None
397
- v = str(value).strip().lower()
398
- if v not in AGGREGATIONS:
399
- raise ProvenanceError(f"未知 aggregation {value!r}(允许:{AGGREGATIONS})")
400
- return v
401
-
402
-
403
- # 生效条件:axis 为 "observed" 且 edge.get("t") 可经 trust.parse_time 解析时返回 (t, t, False);axis 非 observed 或 t 不可解析/缺失时返回 (None, None, True)。
404
- def _edge_window(edge, axis: str):
405
- """边的轴窗口 → `(start, end, missing)`(与 `trust.time_window_of` **同形**)。
406
-
407
- observed 轴:`t`(写入时刻)→ `(t, t, False)`;`t` 缺失(`index_edges` 兜底边
408
- 不带时间)→ `(None, None, True)`。其余轴一律 `(None, None, True)`——边没有效力轴
409
- 声明可读,如实报「不可判定」,由**轴策略**处置(observed fail-closed 剔除并计入
410
- `axis_missing`;effective fail-open 保留),不在这里悄悄换轴。
411
- """
412
- if str(axis) == "observed":
413
- t = _trust.parse_time((edge or {}).get("t"))
414
- if t is None:
415
- return None, None, True
416
- return t, t, False
417
- return None, None, True
418
-
419
-
420
- # 生效条件:start_operator 与 end_operator 均为 None 时返回 "overlap",否则返回 "endpoint"。
421
- def _mode_of(start_operator, end_operator) -> str:
422
- """时间过滤模式(与 `trust.window_match` 的显式分叉口径同源,不另立判据)。"""
423
- return "endpoint" if (start_operator is not None or end_operator is not None) \
424
- else "overlap"
425
-
426
-
427
- # 生效条件:nid 不在 (cg.index or {}).get("nodes") or {} 的 dict 条目中(含 cg.index 缺失、条目非 dict)时返回 {'id': nid, 'present': False};条目在但对本身份不可见(security.node_visible 为假)时同样返回 {'id': nid, 'present': False}(不附任何字段);否则返回 {'id','present':True} 并附 EXPAND_FIELDS 中值非 None 的字段。
428
- def _node_digest(cg, nid) -> dict:
429
- """端点摘要(只读索引快照,**零读节点文件**);端点缺失/不可见 → `present=False`。
430
-
431
- N226(2026-09-28):此前直读 `cg.index` 无可见性判定 ⇒ 端点摘要(layer/
432
- tags/importance/writer/session/temporal)把读闸拒绝节点的元数据照返回
433
- (实测 guest 经 `cg(op="edges", expand_nodes=true)` 拿到私密节点摘要)。
434
- 同库同身份的 `stg.timeline`(stg.py:144/238)早已接线 `_readable`——本处
435
- 是漏网的旁路出口,改为同一个跨层单点(`security.node_visible`)。
436
- """
437
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
438
- e = nodes.get(nid)
439
- if not isinstance(e, dict) or not _security.node_visible(cg, nid):
440
- return {"id": nid, "present": False}
441
- d = {"id": nid, "present": True}
442
- for k in EXPAND_FIELDS:
443
- if e.get(k) is not None:
444
- d[k] = e[k]
445
- return d
446
-
447
-
448
- # 生效条件:child/parent/relation/batch 各为真值(str(x).strip() 非空)时归一为过滤条件,relation 经 normalize_relation 非法即抛 ProvenanceError;ordering/aggregation 经 _ordering_of/_aggregation_of 非法即抛;offset 为负或 limit<=0 或 limit>MAX_FIND_LIMIT 即抛;时间五参经 trust.check_time_args 校验,why 非空即抛 ProvenanceError;返回 {'ok': True, 'readonly': True, 'op': 'edges', 'triple', 'total', 'matched', 'returned', 'offset', 'limit', 'ordering', 'aggregation', 'edges', 'aggregates', 'nodes_expanded', 'time_filter', 'ledger', 'distinct_from', 'note'},其中 total=谓词过滤后条数、matched=时间过滤后条数(dropped+matched==total)、edges=按 t 排序后 offset:offset+limit 切片(expand_nodes 时每边附 child_node/parent_node 摘要)、aggregates 为分页前全集分桶(未请求为 None)。
449
- def find_edges(cg, *, child=None, parent=None, relation=None, batch=None,
450
- start_time=None, end_time=None, start_operator=None,
451
- end_operator=None, time_axis=None, ordering=None, offset=0,
452
- limit=None, aggregation=None, expand_nodes: bool = False,
453
- path: str = None) -> dict:
454
- """三元组反查(阶段二 4.2):按**任意端 / 谓词 / 时间**反查派生边(只读)。
455
-
456
- `subject/predicate/object` ≡ `child/rel/parent`(见本节术语映射注释)。
457
-
458
- 谓词(`child` / `parent` / `relation` / `batch`)与 `edges()` **同源同义**:
459
- 给了就等值过滤、不给就不过滤。时间条件走 `trust.check_time_args`
460
- (**与检索共用的唯一校验点**,本层不另写一套),比较语义由
461
- `trust.window_match` 提供(不给 operator = 区间重叠;给 operator = 端点比较)。
462
-
463
- fail-closed 清单(宁可报错,不静默降级):
464
- · `relation` 非 `RELATIONS`(经 `normalize_relation`);
465
- · `ordering` / `aggregation` 非各自枚举;
466
- · `offset < 0`;`limit <= 0` 或 `> MAX_FIND_LIMIT`(**不把 0/负数当「全部」**);
467
- · 时间五参非法(未知轴 / 未知算子 / 给了算子缺时间 / start > end)。
468
-
469
- 分页与聚合的次序是刻意的:**聚合基于分页前全集**(`matched`),
470
- 否则「先切页再聚合」会给出随 offset 漂移的分桶——不可复算。
471
- 审计块 `time_filter.dropped + matched == total` 由本函数保证。
472
- """
473
- # ---- 谓词归一(空/空白 = 不约束,与 edges() 同口径) ------------------
474
- c_f = str(child).strip() if child is not None and str(child).strip() else None
475
- p_f = str(parent).strip() if parent is not None and str(parent).strip() else None
476
- b_f = str(batch).strip() if batch is not None and str(batch).strip() else None
477
- r_f = normalize_relation(relation) if (relation is not None
478
- and str(relation).strip()) else None
479
- # ---- 排序 / 分页 / 聚合 入参校验 --------------------------------------
480
- ord_v = _ordering_of(ordering)
481
- agg_v = _aggregation_of(aggregation)
482
- try:
483
- off = int(offset or 0)
484
- except (TypeError, ValueError) as exc:
485
- raise ProvenanceError(f"offset 非法:{offset!r}") from exc
486
- if off < 0:
487
- raise ProvenanceError(f"offset 不能为负:{off}")
488
- lim = DEFAULT_FIND_LIMIT if limit is None else int(limit)
489
- if lim <= 0:
490
- raise ProvenanceError(f"limit 必须为正整数(0/负数不当「全部」):{limit!r}")
491
- if lim > MAX_FIND_LIMIT:
492
- raise ProvenanceError(f"limit 超上限 {MAX_FIND_LIMIT}:{lim}")
493
- # ---- 时间算子:复用唯一校验点,缺省轴按本层语义补 observed -----------
494
- enabled, axis0, why = _trust.check_time_args(
495
- start_time=start_time, end_time=end_time,
496
- start_operator=start_operator, end_operator=end_operator,
497
- time_axis=time_axis)
498
- if why:
499
- raise ProvenanceError(why)
500
- axis = FIND_DEFAULT_AXIS if time_axis is None else axis0
501
- q_s = _trust.parse_time(start_time) if enabled else None
502
- q_e = _trust.parse_time(end_time) if enabled else None
503
-
504
- rows = all_edges(cg, path=path)
505
- # N226(2026-09-28):可见性前置过滤(在谓词过滤**之前**,故 `total` 与
506
- # 审计不变式 `dropped + len(kept) == total` 的口径随之收敛为「本身份可见
507
- # 候选数」,仍可复算)。判定用**两端都可见**才保留:边拓扑(child->parent
508
- # + relation + t)本身就会泄露隐藏端点的 id 与关系(实测
509
- # `aggregates.sample=['child_mark->priv_mark(derived_from)']` 即此形态),
510
- # 「至少一端可见」不足以闭口;口径与 `linkref` 的目标白名单、
511
- # `stg._scan` 同策略——可见集之外一律当不存在(不含半条边)。
512
- rows = [e for e in rows
513
- if _security.node_visible(cg, e.get("child"))
514
- and _security.node_visible(cg, e.get("parent"))]
515
- cand = []
516
- for e in rows:
517
- if c_f and e.get("child") != c_f:
518
- continue
519
- if p_f and e.get("parent") != p_f:
520
- continue
521
- if r_f and e.get("rel") != r_f:
522
- continue
523
- if b_f and e.get("batch") != b_f:
524
- continue
525
- cand.append(e)
526
- total = len(cand)
527
-
528
- # ---- 时间过滤(候选层:与 trust.filter_by_time 同策略) ---------------
529
- dropped = missing = 0
530
- kept = []
531
- for e in cand:
532
- if not enabled:
533
- kept.append(e)
534
- continue
535
- cs, ce, miss = _edge_window(e, axis)
536
- if miss:
537
- if axis == "observed": # 观察轴 fail-closed
538
- dropped += 1
539
- missing += 1
540
- continue
541
- kept.append(e) # 效力轴 fail-open(无效力声明可读)
542
- continue
543
- if _trust.window_match(cs, ce, q_s, q_e, start_operator, end_operator):
544
- kept.append(e)
545
- else:
546
- dropped += 1
547
- if dropped + len(kept) != total: # 审计不变式(可复算)
548
- raise ProvenanceError(
549
- f"审计不变式破缺:dropped({dropped}) + kept({len(kept)}) != total({total})")
550
-
551
- # ---- 排序(t 缺失按 0 计,确定性次级键防抖) --------------------------
552
- kept.sort(key=lambda e: (float(e.get("t") or 0.0),
553
- str(e.get("child") or ""),
554
- str(e.get("parent") or "")),
555
- reverse=(ord_v == "desc"))
556
- page = kept[off:off + lim]
557
- if expand_nodes:
558
- page = [dict(e) for e in page]
559
- for e in page:
560
- e["child_node"] = _node_digest(cg, e.get("child"))
561
- e["parent_node"] = _node_digest(cg, e.get("parent"))
562
-
563
- # ---- 聚合(分页前全集;无分页漂移) ----------------------------------
564
- aggregates = None
565
- if agg_v:
566
- field = _AGG_FIELD[agg_v]
567
- buckets = {}
568
- for e in kept:
569
- k = str(e.get(field) or "")
570
- b = buckets.get(k)
571
- if b is None:
572
- b = buckets[k] = {"key": k, "count": 0, "t_min": None,
573
- "t_max": None, "sample": []}
574
- b["count"] += 1
575
- t = e.get("t")
576
- if t is not None:
577
- t = float(t)
578
- b["t_min"] = t if b["t_min"] is None else min(b["t_min"], t)
579
- b["t_max"] = t if b["t_max"] is None else max(b["t_max"], t)
580
- if len(b["sample"]) < 3:
581
- b["sample"].append(f"{e.get('child')}->{e.get('parent')}"
582
- f"({e.get('rel')})")
583
- aggregates = sorted(buckets.values(), key=lambda b: (-b["count"], b["key"]))
584
-
585
- return {"ok": True, "readonly": True, "op": "edges",
586
- "triple": {"child": c_f, "relation": r_f, "parent": p_f, "batch": b_f},
587
- "total": total, "matched": len(kept), "returned": len(page),
588
- "offset": off, "limit": lim, "ordering": ord_v,
589
- "aggregation": agg_v, "aggregates": aggregates,
590
- "nodes_expanded": bool(expand_nodes),
591
- "edges": page,
592
- "time_filter": _trust.time_filter_meta(
593
- axis=axis, mode=_mode_of(start_operator, end_operator),
594
- start=start_time, end=end_time,
595
- start_operator=start_operator, end_operator=end_operator,
596
- dropped=dropped, axis_missing=missing, applied=bool(enabled)),
597
- "ledger": ledger_file(cg.root, path),
598
- "distinct_from": "links.py = 跨节点信任 P_trust(_links.json)",
599
- "note": ("只读:台账 ∪ 索引声明(台账优先,按边去重);"
600
- "聚合基于分页前全集;边时刻字段为 t(观察轴),"
1
+ # -*- coding: utf-8 -*-
2
+ """派生溯源(G8):新增节点常态化建链 + 悬空可检出。
3
+
4
+ 回答「这个节点**从哪来**」——与 `md_cg.links` 刻意分层:
5
+ · `links.py` = 跨节点信任(「我信你多少」,P_trust,落 `~/.mdcg/_links.json`);
6
+ · 本模块 = 节点派生关系(「它由谁派生」,落 `<root>/_link.jsonl`)。
7
+ 两者都叫「链接」,但一个管**信任状态**、一个管**演进血缘**,不可混用。
8
+
9
+ 存储形态(对齐「md 单一真相源 + 派生索引可重建」):
10
+ · 权威声明在节点 frontmatter(`derived_from` / `derived_relation`);
11
+ · `<root>/_link.jsonl` 是 **append-only 派生台账**(快查用,可由 frontmatter 重建);
12
+ · 建链失败写 `<root>/_link.jsonl.fail`(降级留痕)。
13
+
14
+ 三条纪律(对齐 G8 裁定 §六):
15
+ 1. **只对新增节点常态化建链,历史不回填**——`rebuild_ledger` 只重放 frontmatter
16
+ 里**已经声明**的关系,不为历史节点发明任何边(当前库历史声明为 0 → 重建为空);
17
+ 2. **建链失败不得阻断写入**——`record()` 永不抛(best-effort),失败降级为告警 +
18
+ 失败台账留痕,节点写入照常提交;
19
+ 3. **巡检只读**——`check()` 检出悬空边(目标/子节点不在索引内)但**不自动删边**,
20
+ 关系事实去留由人处置。
21
+
22
+ 零第三方依赖。
23
+ """
24
+ from __future__ import annotations
25
+
26
+ import json
27
+ import os
28
+ import time
29
+
30
+ from . import trust as _trust
31
+ from . import security as _security
32
+ from .fsutil import FileLock, append_jsonl, atomic_write, read_jsonl
33
+
34
+ LEDGER_NAME = "_link.jsonl"
35
+ FAIL_SUFFIX = ".fail"
36
+ LEDGER_ENV = "MDCG_LINK_FILE"
37
+ SCHEMA = 1
38
+
39
+ #: 允许的派生关系(显式枚举,避免「自由字符串」把血缘写成噪声)
40
+ RELATIONS = ("derived_from", "split_from", "extracted_from",
41
+ "merged_from", "refined_from", "source")
42
+ DEFAULT_RELATION = "derived_from"
43
+
44
+ #: frontmatter 里承载派生声明的字段(写路径只读这两处,不猜)
45
+ FM_FIELD = "derived_from"
46
+ FM_REL_FIELD = "derived_relation"
47
+
48
+ _LOCK_TIMEOUT = 2.0
49
+
50
+
51
+ class ProvenanceError(Exception):
52
+ """派生溯源错误。写路径侧一律由 `record()` 兜住,不向上抛。"""
53
+
54
+
55
+ # --------------------------------------------------------------------------
56
+ # 路径 / 规范化
57
+ # --------------------------------------------------------------------------
58
+
59
+ # 生效条件:path 为真值时返回 path;否则 os.environ.get(LEDGER_ENV) 为非空真值时返回该环境变量值;否则返回 os.path.join(root, LEDGER_NAME)。
60
+ def ledger_file(root: str, path: str = None) -> str:
61
+ """台账路径:显式 → MDCG_LINK_FILE → <root>/_link.jsonl。"""
62
+ return path or os.environ.get(LEDGER_ENV) or os.path.join(root, LEDGER_NAME)
63
+
64
+
65
+ # 生效条件:传入 root(path 为真值则以其为准,否则由 ledger_file 的回落决定落点)时返回 ledger_file(root, path) 结果拼接 FAIL_SUFFIX。
66
+ def fail_log_file(root: str, path: str = None) -> str:
67
+ """降级留痕路径(台账写不进时的「本该建的边」)。"""
68
+ return ledger_file(root, path) + FAIL_SUFFIX
69
+
70
+
71
+ # 生效条件:value 为 None 返回 [];否则 list/tuple/set 逐个元素、其他类型视作单元素,元素经 str(x).strip() 后非空且未出现过才保留(重复只留首次)。
72
+ def as_list(value) -> list:
73
+ """把单值 / 序列统一成去重、去空白的字符串列表。"""
74
+ if value is None:
75
+ return []
76
+ items = list(value) if isinstance(value, (list, tuple, set)) else [value]
77
+ out = []
78
+ for x in items:
79
+ s = str(x).strip()
80
+ if s and s not in out:
81
+ out.append(s)
82
+ return out
83
+
84
+
85
+ # 生效条件:rel 为假值(None/空串)或 str(rel).strip().lower() 后为空白的串(如 " ")时 r 回落 default(默认常量 DEFAULT_RELATION);r 不在 RELATIONS 内(含回落后的 default 本身非法)即抛 ProvenanceError,否则返回该小写串。
86
+ def normalize_relation(rel, default: str = DEFAULT_RELATION) -> str:
87
+ """严格校验关系名;非法抛 `ProvenanceError`(显式 API 用)。"""
88
+ r = str(rel or "").strip().lower()
89
+ if not r:
90
+ r = default
91
+ if r not in RELATIONS:
92
+ raise ProvenanceError(f"未知派生关系:{rel}(允许:{RELATIONS})")
93
+ return r
94
+
95
+
96
+ # 生效条件:normalize_relation(rel, default) 抛 ProvenanceError(含 rel 为假值/仅空白且 default 非法时)则原样返回 default;否则返回该调用的返回值。
97
+ def coerce_relation(rel, default: str = DEFAULT_RELATION) -> str:
98
+ """宽松兜底:非法关系名回退默认值(**写路径用,保证永不阻断写入**)。"""
99
+ try:
100
+ return normalize_relation(rel, default)
101
+ except ProvenanceError:
102
+ return default
103
+
104
+
105
+ # 生效条件:child 或 parent 为假值或仅空白使 str(x or "").strip() 为空、或二者 strip 后相等(自环)时返回 None;否则返回含 schema/t/child/parent/rel/batch/actor 的 dict,note 为真值时才附上并截断到 200 字符。
106
+ def make_edge(child, parent, *, relation=DEFAULT_RELATION, batch=None,
107
+ actor="system", note=None, t=None):
108
+ """构造一条派生边;自环 / 空端点返回 None(**不产生无意义边**)。"""
109
+ c, p = str(child or "").strip(), str(parent or "").strip()
110
+ if not c or not p or c == p:
111
+ return None
112
+ edge = {"schema": SCHEMA,
113
+ "t": float(t if t is not None else time.time()),
114
+ "child": c, "parent": p, "rel": coerce_relation(relation),
115
+ "batch": batch, "actor": actor}
116
+ if note:
117
+ edge["note"] = str(note)[:200]
118
+ return edge
119
+
120
+
121
+ # 生效条件:对 as_list(parents) 的每个父项调用 make_edge,只保留返回非 None 的边,全部被丢弃时返回空列表。
122
+ def edges_for(child, parents, **kw) -> list:
123
+ """`(child, [parents]) → [edge]`:空端点 / 自环自动丢弃。"""
124
+ out = []
125
+ for p in as_list(parents):
126
+ e = make_edge(child, p, **kw)
127
+ if e:
128
+ out.append(e)
129
+ return out
130
+
131
+
132
+ # --------------------------------------------------------------------------
133
+ # 写:台账追加(record 为写路径唯一入口,永不抛)
134
+ # --------------------------------------------------------------------------
135
+
136
+ # 生效条件:edges 为 None/空/全为假元素时返回 0;否则在 FileLock(p, timeout=_LOCK_TIMEOUT) 内逐条 append_jsonl,抛 OSError 时转抛 ProvenanceError,成功返回 len(edges)。
137
+ def append(root: str, edges, *, path: str = None) -> int:
138
+ """台账追加(加锁串行,防 Windows 并发交错丢边)。IO 失败抛 `ProvenanceError`。"""
139
+ edges = [e for e in (edges or []) if e]
140
+ if not edges:
141
+ return 0
142
+ p = ledger_file(root, path)
143
+ try:
144
+ os.makedirs(os.path.dirname(os.path.abspath(p)) or ".", exist_ok=True)
145
+ with FileLock(p, timeout=_LOCK_TIMEOUT):
146
+ for e in edges:
147
+ # #326-④:append_jsonl 不再上抛 OSError(改返回布尔)——本处是
148
+ # **fail-closed**(写失败必须报 ProvenanceError),故必须读返回值,
149
+ # 否则「写失败」会静默变成「写成功」(修前由 except OSError 兜住)。
150
+ if append_jsonl(p, e) is False:
151
+ raise ProvenanceError(
152
+ f"派生台账写入失败:{p}(append_jsonl 返回 False,"
153
+ f"源头已记 fsutil.APPEND_FAILURES)")
154
+ except OSError as exc:
155
+ raise ProvenanceError(f"派生台账写入失败:{p}({exc})") from exc
156
+ return len(edges)
157
+
158
+
159
+ # 生效条件:给定 root/path/child/parents/relation/reason/code 即恒返回 {'ok': False, 'added': 0, 'edges': [], 'degraded': True, 'degrade_code': code, 'reason': reason},其中写 fail_log_file 台账的异常被 except Exception 吞掉。
160
+ def _degrade(root: str, path, child, parents, relation, reason,
161
+ code: str) -> dict:
162
+ """降级留痕:把「本该建的边」记进 .fail 台账(自身也 best-effort)。"""
163
+ rec = {"t": time.time(), "code": code, "child": str(child or ""),
164
+ "parents": as_list(parents), "rel": str(relation or ""),
165
+ "reason": str(reason)[:300]}
166
+ try:
167
+ append_jsonl(fail_log_file(root, path), rec)
168
+ except Exception: # noqa: BLE001
169
+ pass
170
+ return {"ok": False, "added": 0, "edges": [], "degraded": True,
171
+ "degrade_code": code, "reason": reason}
172
+
173
+
174
+ # 生效条件:edges_for 抛异常时经 _degrade(code='bad_edge') 返回;edges 为空时返回 {'ok': True, 'added': 0, 'edges': [], 'reason': 'no_parents'};append 抛 ProvenanceError 或其他异常时经 _degrade(code='ledger_io') 返回;其余返回 {'ok': True, 'added': n, 'edges': edges, 'ledger': …},恒不向外抛。
175
+ def record(root: str, child, parents, *, relation=DEFAULT_RELATION,
176
+ batch=None, actor="system", note=None, path: str = None) -> dict:
177
+ """写路径建链入口:**永不抛**(G8 硬约束:建链失败不得阻断节点写入)。
178
+
179
+ 返回 `{ok, added, edges, ...}`;失败时 `ok=False` + `degraded=True` 且已写
180
+ `.fail` 留痕。调用方**不得**因本函数返回 False 而回滚节点。
181
+ """
182
+ try:
183
+ edges = edges_for(child, parents, relation=relation, batch=batch,
184
+ actor=actor, note=note)
185
+ except Exception as exc: # noqa: BLE001
186
+ return _degrade(root, path, child, parents, relation,
187
+ f"{type(exc).__name__}: {exc}", "bad_edge")
188
+ if not edges:
189
+ return {"ok": True, "added": 0, "edges": [], "reason": "no_parents"}
190
+ try:
191
+ n = append(root, edges, path=path)
192
+ except ProvenanceError as exc:
193
+ return _degrade(root, path, child, parents, relation, str(exc),
194
+ "ledger_io")
195
+ except Exception as exc: # noqa: BLE001
196
+ return _degrade(root, path, child, parents, relation,
197
+ f"{type(exc).__name__}: {exc}", "ledger_io")
198
+ return {"ok": True, "added": n, "edges": edges,
199
+ "ledger": ledger_file(root, path)}
200
+
201
+
202
+ # --------------------------------------------------------------------------
203
+ # 读:台账 / 索引 / 悬空巡检
204
+ # --------------------------------------------------------------------------
205
+
206
+ # 生效条件:遍历 read_jsonl(ledger_file(root, path)),仅收录 isinstance(r, dict) 且 r.get("child") 与 r.get("parent") 均为真值(键缺失或值为假即丢弃)的记录。
207
+ def load(root: str, *, path: str = None) -> list:
208
+ """读台账(跳过坏行;只取有端点的记录)。"""
209
+ out = []
210
+ for r in read_jsonl(ledger_file(root, path)):
211
+ if isinstance(r, dict) and r.get("child") and r.get("parent"):
212
+ out.append(r)
213
+ return out
214
+
215
+
216
+ # 生效条件:rows 中每行按 (r.get("child"), r.get("parent"), r.get("rel")) 三元组判重,仅首次出现的行保留,按原顺序返回去重列表。
217
+ def _dedupe(rows):
218
+ out, seen = [], set()
219
+ for r in rows:
220
+ key = (r.get("child"), r.get("parent"), r.get("rel"))
221
+ if key in seen:
222
+ continue
223
+ seen.add(key)
224
+ out.append(r)
225
+ return out
226
+
227
+
228
+ # 生效条件:child/parent/relation/batch 各为真值时才做对应等值过滤(假值或 None 不过滤),去重后 limit 为真值时返回 out[:int(limit)],limit 为 None 或 0 时返回全部 out。
229
+ def edges(root: str, *, child=None, parent=None, relation=None, batch=None,
230
+ limit: int = None, path: str = None) -> list:
231
+ """按端点 / 关系 / 批次过滤台账边(只读,去重,保持写入顺序)。"""
232
+ out = []
233
+ for r in load(root, path=path):
234
+ if child and r.get("child") != child:
235
+ continue
236
+ if parent and r.get("parent") != parent:
237
+ continue
238
+ if relation and r.get("rel") != relation:
239
+ continue
240
+ if batch and r.get("batch") != batch:
241
+ continue
242
+ out.append(r)
243
+ out = _dedupe(out)
244
+ return out[:int(limit)] if limit else out
245
+
246
+
247
+ # 生效条件:以 (getattr(cg, "index", None) or {}).get("nodes") or {} 遍历(缺失时视作空);prefix 为真值时仅保留 str(nid).startswith(prefix) 的节点,输出经 _dedupe 去重。
248
+ def index_edges(cg, *, prefix: str = None) -> list:
249
+ """从**索引快照**恢复派生边(零读文件)——台账丢失/未重建时的只读兜底。"""
250
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
251
+ out = []
252
+ for nid, e in list(nodes.items()):
253
+ if prefix and not str(nid).startswith(prefix):
254
+ continue
255
+ rel = coerce_relation((e or {}).get(FM_REL_FIELD))
256
+ for p in as_list((e or {}).get(FM_FIELD)):
257
+ out.append({"schema": SCHEMA, "child": nid, "parent": p, "rel": rel,
258
+ "batch": (e or {}).get("derived_batch"), "actor": None,
259
+ "origin": "index"})
260
+ return _dedupe(out)
261
+
262
+
263
+ # 生效条件:给定 cg 即返回 _dedupe(load(cg.root, path=path) + index_edges(cg)),台账记录在前、按边去重。
264
+ def all_edges(cg, *, path: str = None) -> list:
265
+ """台账 ∪ 索引声明(台账优先,按边去重)。"""
266
+ return _dedupe(load(cg.root, path=path) + index_edges(cg))
267
+
268
+
269
+ # 生效条件:include_index 为真值时取 all_edges(cg, path=path)、为假时取 load(cg.root, path=path),对 child/parent 不在 cg 索引节点键集合中的边记为 dangling 并列出 missing;返回 ok=not dangling,dangling 仅取 int(limit)(默认 20)项,不写盘。
270
+ def check(cg, *, path: str = None, limit: int = 20,
271
+ include_index: bool = True) -> dict:
272
+ """只读巡检:检出**悬空派生边**(端点不在索引内)。**不删边、不写盘**。
273
+
274
+ `ok=False` 仅表示「有悬空」,不代表巡检失败;`checked=True` 恒成立。
275
+ """
276
+ known = set((getattr(cg, "index", None) or {}).get("nodes") or {})
277
+ rows = all_edges(cg, path=path) if include_index else load(cg.root, path=path)
278
+ dangling = []
279
+ for e in rows:
280
+ missing = []
281
+ if e.get("child") not in known:
282
+ missing.append("child")
283
+ if e.get("parent") not in known:
284
+ missing.append("parent")
285
+ if missing:
286
+ dangling.append({"child": e.get("child"), "parent": e.get("parent"),
287
+ "rel": e.get("rel"), "missing": missing,
288
+ "batch": e.get("batch"), "t": e.get("t"),
289
+ "origin": e.get("origin") or "ledger"})
290
+ dangling.sort(key=lambda r: (r.get("child") or "", r.get("parent") or ""))
291
+ ledger = ledger_file(cg.root, path)
292
+ return {"ok": not dangling, "checked": True, "root": cg.root,
293
+ "ledger": ledger, "ledger_exists": os.path.exists(ledger),
294
+ "edges": len(rows), "nodes": len(known),
295
+ "dangling": dangling[:int(limit)], "dangling_count": len(dangling),
296
+ "readonly": True,
297
+ "note": "只读巡检:悬空边仅检出并报告,不自动删除(关系事实由人处置)"}
298
+
299
+
300
+ # 生效条件:apply 为假值(默认 False)时只返回 dry_run 报表(written=0、sample=es[:5]);apply 为真值时把 index_edges(cg) 的边写入 ledger_file(cg.root, path) 并返回 written=len(es)。
301
+ def rebuild_ledger(cg, *, apply: bool = False, path: str = None) -> dict:
302
+ """按 frontmatter 重建台账——**只重放已声明的边,不发明任何边**。
303
+
304
+ 历史节点未声明派生关系 → 重建结果为空,正合「历史不回填」。
305
+ 默认 dry_run(只出报表)。
306
+ """
307
+ es = index_edges(cg)
308
+ if not apply:
309
+ return {"ok": True, "dry_run": True, "edges": len(es),
310
+ "written": 0, "sample": es[:5],
311
+ "note": "预演:未写盘;只重放 frontmatter 已声明的关系"}
312
+ body = "".join(json.dumps(e, ensure_ascii=False, separators=(",", ":")) + "\n"
313
+ for e in es)
314
+ p = ledger_file(cg.root, path)
315
+ atomic_write(p, body)
316
+ return {"ok": True, "dry_run": False, "edges": len(es),
317
+ "written": len(es), "ledger": p}
318
+
319
+
320
+ # 生效条件:check(cg, path=path, limit=3) 成功时返回 edges/dangling/ledger/exists/sample(悬空边 child->parent);该调用抛任何异常时被 except Exception 吞掉并返回 {}。
321
+ def summary(cg, *, path: str = None) -> dict:
322
+ """轻量摘要(只读;失败不抛,避免拖垮 health_os / 常驻循环)。"""
323
+ try:
324
+ rep = check(cg, path=path, limit=3)
325
+ return {"edges": rep["edges"], "dangling": rep["dangling_count"],
326
+ "ledger": rep["ledger"], "exists": rep["ledger_exists"],
327
+ "sample": [f"{r['child']}->{r['parent']}"
328
+ for r in rep["dangling"]]}
329
+ except Exception: # noqa: BLE001
330
+ return {}
331
+
332
+
333
+ # 生效条件:root 为真值时 ledger 字段取 ledger_file(root),否则取常量 LEDGER_NAME;其余自描述字段(SCHEMA、RELATIONS、DEFAULT_RELATION、FM_FIELD/FM_REL_FIELD 等)恒定返回。
334
+ def catalog(root: str = None) -> dict:
335
+ """自描述(供 MCP catalog / 人工核对)。"""
336
+ return {
337
+ "layer": "派生溯源(G8)",
338
+ "question": "这个节点从哪来(演进血缘)",
339
+ "ledger": ledger_file(root) if root else LEDGER_NAME,
340
+ "schema": SCHEMA,
341
+ "relations": list(RELATIONS),
342
+ "default_relation": DEFAULT_RELATION,
343
+ "fm_fields": [FM_FIELD, FM_REL_FIELD],
344
+ "discipline": {"incremental_only": True, "no_backfill": True,
345
+ "never_block_write": True, "patrol_readonly": True},
346
+ "distinct_from": ("links.py = 跨节点信任 P_trust(_links.json);"
347
+ "本层 = 节点派生关系(_link.jsonl)"),
348
+ }
349
+
350
+
351
+ # --------------------------------------------------------------------------
352
+ # 读:三元组反查原语(阶段二 4.2 · find_entity_contexts 式)
353
+ # --------------------------------------------------------------------------
354
+ # 术语映射(**同一件事,勿新造第二套字段**):三元组 `subject / predicate /
355
+ # object` 在本层就是派生边的 `child / rel / parent`——即节点写入时声明的
356
+ # `derived_from` 关系。不另建 subject/predicate/object 参数字面量,理由有二:
357
+ # ① `cg` 工具面是**扁平 schema**,`subject` 已被 `identity`(`subject:<id>`
358
+ # 主体语义)与 `link.evidence`(证据主体)占用,同名异义会把两处口径搅在一起;
359
+ # ② `edges()` 已是唯一谓词载体(child/parent/relation/batch 四键),反查只是它的
360
+ # **只读超集**——另造一套参数必然分叉。
361
+ # 与 `edges()` 的三处**有意**差异(不是漂移):
362
+ # · 时间轴缺省 `observed`(边只有记录时刻 `t`,见 FIND_DEFAULT_AXIS);
363
+ # · 默认排序 `desc`(按 `t` 新→旧)且 `limit` 缺省 50、上限 500(分页原语,
364
+ # 不给「静默全量倾倒」);
365
+ # · 加 `aggregation`(分页前全集分桶)与 `expand_nodes`(端点摘要,索引级零读盘)。
366
+
367
+ #: 排序方向(封闭枚举,拒收未知名——与 `trust.TIME_OPERATORS` 同风格)
368
+ ORDERINGS = ("desc", "asc")
369
+ #: 聚合维度(封闭枚举):按谓词 / 对象端 / 主体端分桶
370
+ AGGREGATIONS = ("by_relation", "by_parent", "by_child")
371
+ #: 聚合维度 → 边字段(谓词在边上叫 `rel`;聚合名沿用三元组术语命名)
372
+ _AGG_FIELD = {"by_relation": "rel", "by_parent": "parent", "by_child": "child"}
373
+ #: 反查缺省时间轴:派生边只有一个时刻字段 `t`(写入时刻,观察轴),
374
+ #: **效力轴字段根本不存在**。与 `mdcg.search` 缺省 `effective` **有意不同**:
375
+ #: 那里 `effective_from/until` 是可选声明(多数节点没写),沿用 fail-open 不会
376
+ #: 出错;这里若缺省 `effective`,则「给了时间条件却恒不过滤」——把静默 no-op
377
+ #: 当成了「没有匹配」,属无法复算的错答。
378
+ FIND_DEFAULT_AXIS = "observed"
379
+ DEFAULT_FIND_LIMIT = 50
380
+ MAX_FIND_LIMIT = 500
381
+ #: `expand_nodes=True` 时透出的索引字段白名单(只读索引快照,**零读节点文件**)
382
+ EXPAND_FIELDS = ("layer", "tags", "importance", "writer", "session",
383
+ "derived_from", "derived_relation", "derived_batch",
384
+ "temporal", "time_window", "condition_space")
385
+
386
+
387
+ # 生效条件:value 为 None 或 str(value).strip() 为空时返回 "desc";小写后命中 ORDERINGS 返回该值;否则抛 ProvenanceError。
388
+ def _ordering_of(value) -> str:
389
+ """排序方向归一 → `"desc"` / `"asc"`;未知 → `ProvenanceError`(fail-closed)。"""
390
+ if value is None or not str(value).strip():
391
+ return "desc"
392
+ v = str(value).strip().lower()
393
+ if v not in ORDERINGS:
394
+ raise ProvenanceError(f"未知 ordering {value!r}(允许:{ORDERINGS})")
395
+ return v
396
+
397
+
398
+ # 生效条件:value 为 None 或 str(value).strip() 为空时返回 None(= 不聚合);小写后命中 AGGREGATIONS 返回该值;否则抛 ProvenanceError。
399
+ def _aggregation_of(value):
400
+ """聚合维度归一 → `None` / `AGGREGATIONS` 之一;未知 → `ProvenanceError`。"""
401
+ if value is None or not str(value).strip():
402
+ return None
403
+ v = str(value).strip().lower()
404
+ if v not in AGGREGATIONS:
405
+ raise ProvenanceError(f"未知 aggregation {value!r}(允许:{AGGREGATIONS})")
406
+ return v
407
+
408
+
409
+ # 生效条件:axis 为 "observed" 且 edge.get("t") 可经 trust.parse_time 解析时返回 (t, t, False);axis 非 observed 或 t 不可解析/缺失时返回 (None, None, True)。
410
+ def _edge_window(edge, axis: str):
411
+ """边的轴窗口 → `(start, end, missing)`(与 `trust.time_window_of` **同形**)。
412
+
413
+ observed 轴:`t`(写入时刻)→ `(t, t, False)`;`t` 缺失(`index_edges` 兜底边
414
+ 不带时间)→ `(None, None, True)`。其余轴一律 `(None, None, True)`——边没有效力轴
415
+ 声明可读,如实报「不可判定」,由**轴策略**处置(observed fail-closed 剔除并计入
416
+ `axis_missing`;effective fail-open 保留),不在这里悄悄换轴。
417
+ """
418
+ if str(axis) == "observed":
419
+ t = _trust.parse_time((edge or {}).get("t"))
420
+ if t is None:
421
+ return None, None, True
422
+ return t, t, False
423
+ return None, None, True
424
+
425
+
426
+ # 生效条件:start_operator 与 end_operator 均为 None 时返回 "overlap",否则返回 "endpoint"。
427
+ def _mode_of(start_operator, end_operator) -> str:
428
+ """时间过滤模式(与 `trust.window_match` 的显式分叉口径同源,不另立判据)。"""
429
+ return "endpoint" if (start_operator is not None or end_operator is not None) \
430
+ else "overlap"
431
+
432
+
433
+ # 生效条件:nid 不在 (cg.index or {}).get("nodes") or {} 的 dict 条目中(含 cg.index 缺失、条目非 dict)时返回 {'id': nid, 'present': False};条目在但对本身份不可见(security.node_visible 为假)时同样返回 {'id': nid, 'present': False}(不附任何字段);否则返回 {'id','present':True} 并附 EXPAND_FIELDS 中值非 None 的字段。
434
+ def _node_digest(cg, nid) -> dict:
435
+ """端点摘要(只读索引快照,**零读节点文件**);端点缺失/不可见 → `present=False`。
436
+
437
+ N226(2026-09-28):此前直读 `cg.index` 无可见性判定 ⇒ 端点摘要(layer/
438
+ tags/importance/writer/session/temporal)把读闸拒绝节点的元数据照返回
439
+ (实测 guest 经 `cg(op="edges", expand_nodes=true)` 拿到私密节点摘要)。
440
+ 同库同身份的 `stg.timeline`(stg.py:144/238)早已接线 `_readable`——本处
441
+ 是漏网的旁路出口,改为同一个跨层单点(`security.node_visible`)。
442
+ """
443
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
444
+ e = nodes.get(nid)
445
+ if not isinstance(e, dict) or not _security.node_visible(cg, nid):
446
+ return {"id": nid, "present": False}
447
+ d = {"id": nid, "present": True}
448
+ for k in EXPAND_FIELDS:
449
+ if e.get(k) is not None:
450
+ d[k] = e[k]
451
+ return d
452
+
453
+
454
+ # 生效条件:child/parent/relation/batch 各为真值(str(x).strip() 非空)时归一为过滤条件,relation 经 normalize_relation 非法即抛 ProvenanceError;ordering/aggregation 经 _ordering_of/_aggregation_of 非法即抛;offset 为负或 limit<=0 或 limit>MAX_FIND_LIMIT 即抛;时间五参经 trust.check_time_args 校验,why 非空即抛 ProvenanceError;返回 {'ok': True, 'readonly': True, 'op': 'edges', 'triple', 'total', 'matched', 'returned', 'offset', 'limit', 'ordering', 'aggregation', 'edges', 'aggregates', 'nodes_expanded', 'time_filter', 'ledger', 'distinct_from', 'note'},其中 total=谓词过滤后条数、matched=时间过滤后条数(dropped+matched==total)、edges=按 t 排序后 offset:offset+limit 切片(expand_nodes 时每边附 child_node/parent_node 摘要)、aggregates 为分页前全集分桶(未请求为 None)。
455
+ def find_edges(cg, *, child=None, parent=None, relation=None, batch=None,
456
+ start_time=None, end_time=None, start_operator=None,
457
+ end_operator=None, time_axis=None, ordering=None, offset=0,
458
+ limit=None, aggregation=None, expand_nodes: bool = False,
459
+ path: str = None) -> dict:
460
+ """三元组反查(阶段二 4.2):按**任意端 / 谓词 / 时间**反查派生边(只读)。
461
+
462
+ `subject/predicate/object` ≡ `child/rel/parent`(见本节术语映射注释)。
463
+
464
+ 谓词(`child` / `parent` / `relation` / `batch`)与 `edges()` **同源同义**:
465
+ 给了就等值过滤、不给就不过滤。时间条件走 `trust.check_time_args`
466
+ (**与检索共用的唯一校验点**,本层不另写一套),比较语义由
467
+ `trust.window_match` 提供(不给 operator = 区间重叠;给 operator = 端点比较)。
468
+
469
+ fail-closed 清单(宁可报错,不静默降级):
470
+ · `relation` 非 `RELATIONS`(经 `normalize_relation`);
471
+ · `ordering` / `aggregation` 非各自枚举;
472
+ · `offset < 0`;`limit <= 0` 或 `> MAX_FIND_LIMIT`(**不把 0/负数当「全部」**);
473
+ · 时间五参非法(未知轴 / 未知算子 / 给了算子缺时间 / start > end)。
474
+
475
+ 分页与聚合的次序是刻意的:**聚合基于分页前全集**(`matched`),
476
+ 否则「先切页再聚合」会给出随 offset 漂移的分桶——不可复算。
477
+ 审计块 `time_filter.dropped + matched == total` 由本函数保证。
478
+ """
479
+ # ---- 谓词归一(空/空白 = 不约束,与 edges() 同口径) ------------------
480
+ c_f = str(child).strip() if child is not None and str(child).strip() else None
481
+ p_f = str(parent).strip() if parent is not None and str(parent).strip() else None
482
+ b_f = str(batch).strip() if batch is not None and str(batch).strip() else None
483
+ r_f = normalize_relation(relation) if (relation is not None
484
+ and str(relation).strip()) else None
485
+ # ---- 排序 / 分页 / 聚合 入参校验 --------------------------------------
486
+ ord_v = _ordering_of(ordering)
487
+ agg_v = _aggregation_of(aggregation)
488
+ try:
489
+ off = int(offset or 0)
490
+ except (TypeError, ValueError) as exc:
491
+ raise ProvenanceError(f"offset 非法:{offset!r}") from exc
492
+ if off < 0:
493
+ raise ProvenanceError(f"offset 不能为负:{off}")
494
+ lim = DEFAULT_FIND_LIMIT if limit is None else int(limit)
495
+ if lim <= 0:
496
+ raise ProvenanceError(f"limit 必须为正整数(0/负数不当「全部」):{limit!r}")
497
+ if lim > MAX_FIND_LIMIT:
498
+ raise ProvenanceError(f"limit 超上限 {MAX_FIND_LIMIT}:{lim}")
499
+ # ---- 时间算子:复用唯一校验点,缺省轴按本层语义补 observed -----------
500
+ enabled, axis0, why = _trust.check_time_args(
501
+ start_time=start_time, end_time=end_time,
502
+ start_operator=start_operator, end_operator=end_operator,
503
+ time_axis=time_axis)
504
+ if why:
505
+ raise ProvenanceError(why)
506
+ axis = FIND_DEFAULT_AXIS if time_axis is None else axis0
507
+ q_s = _trust.parse_time(start_time) if enabled else None
508
+ q_e = _trust.parse_time(end_time) if enabled else None
509
+
510
+ rows = all_edges(cg, path=path)
511
+ # N226(2026-09-28):可见性前置过滤(在谓词过滤**之前**,故 `total` 与
512
+ # 审计不变式 `dropped + len(kept) == total` 的口径随之收敛为「本身份可见
513
+ # 候选数」,仍可复算)。判定用**两端都可见**才保留:边拓扑(child->parent
514
+ # + relation + t)本身就会泄露隐藏端点的 id 与关系(实测
515
+ # `aggregates.sample=['child_mark->priv_mark(derived_from)']` 即此形态),
516
+ # 「至少一端可见」不足以闭口;口径与 `linkref` 的目标白名单、
517
+ # `stg._scan` 同策略——可见集之外一律当不存在(不含半条边)。
518
+ rows = [e for e in rows
519
+ if _security.node_visible(cg, e.get("child"))
520
+ and _security.node_visible(cg, e.get("parent"))]
521
+ cand = []
522
+ for e in rows:
523
+ if c_f and e.get("child") != c_f:
524
+ continue
525
+ if p_f and e.get("parent") != p_f:
526
+ continue
527
+ if r_f and e.get("rel") != r_f:
528
+ continue
529
+ if b_f and e.get("batch") != b_f:
530
+ continue
531
+ cand.append(e)
532
+ total = len(cand)
533
+
534
+ # ---- 时间过滤(候选层:与 trust.filter_by_time 同策略) ---------------
535
+ dropped = missing = 0
536
+ kept = []
537
+ for e in cand:
538
+ if not enabled:
539
+ kept.append(e)
540
+ continue
541
+ cs, ce, miss = _edge_window(e, axis)
542
+ if miss:
543
+ if axis == "observed": # 观察轴 fail-closed
544
+ dropped += 1
545
+ missing += 1
546
+ continue
547
+ kept.append(e) # 效力轴 fail-open(无效力声明可读)
548
+ continue
549
+ if _trust.window_match(cs, ce, q_s, q_e, start_operator, end_operator):
550
+ kept.append(e)
551
+ else:
552
+ dropped += 1
553
+ if dropped + len(kept) != total: # 审计不变式(可复算)
554
+ raise ProvenanceError(
555
+ f"审计不变式破缺:dropped({dropped}) + kept({len(kept)}) != total({total})")
556
+
557
+ # ---- 排序(t 缺失按 0 计,确定性次级键防抖) --------------------------
558
+ kept.sort(key=lambda e: (float(e.get("t") or 0.0),
559
+ str(e.get("child") or ""),
560
+ str(e.get("parent") or "")),
561
+ reverse=(ord_v == "desc"))
562
+ page = kept[off:off + lim]
563
+ if expand_nodes:
564
+ page = [dict(e) for e in page]
565
+ for e in page:
566
+ e["child_node"] = _node_digest(cg, e.get("child"))
567
+ e["parent_node"] = _node_digest(cg, e.get("parent"))
568
+
569
+ # ---- 聚合(分页前全集;无分页漂移) ----------------------------------
570
+ aggregates = None
571
+ if agg_v:
572
+ field = _AGG_FIELD[agg_v]
573
+ buckets = {}
574
+ for e in kept:
575
+ k = str(e.get(field) or "")
576
+ b = buckets.get(k)
577
+ if b is None:
578
+ b = buckets[k] = {"key": k, "count": 0, "t_min": None,
579
+ "t_max": None, "sample": []}
580
+ b["count"] += 1
581
+ t = e.get("t")
582
+ if t is not None:
583
+ t = float(t)
584
+ b["t_min"] = t if b["t_min"] is None else min(b["t_min"], t)
585
+ b["t_max"] = t if b["t_max"] is None else max(b["t_max"], t)
586
+ if len(b["sample"]) < 3:
587
+ b["sample"].append(f"{e.get('child')}->{e.get('parent')}"
588
+ f"({e.get('rel')})")
589
+ aggregates = sorted(buckets.values(), key=lambda b: (-b["count"], b["key"]))
590
+
591
+ return {"ok": True, "readonly": True, "op": "edges",
592
+ "triple": {"child": c_f, "relation": r_f, "parent": p_f, "batch": b_f},
593
+ "total": total, "matched": len(kept), "returned": len(page),
594
+ "offset": off, "limit": lim, "ordering": ord_v,
595
+ "aggregation": agg_v, "aggregates": aggregates,
596
+ "nodes_expanded": bool(expand_nodes),
597
+ "edges": page,
598
+ "time_filter": _trust.time_filter_meta(
599
+ axis=axis, mode=_mode_of(start_operator, end_operator),
600
+ start=start_time, end=end_time,
601
+ start_operator=start_operator, end_operator=end_operator,
602
+ dropped=dropped, axis_missing=missing, applied=bool(enabled)),
603
+ "ledger": ledger_file(cg.root, path),
604
+ "distinct_from": "links.py = 跨节点信任 P_trust(_links.json)",
605
+ "note": ("只读:台账 ∪ 索引声明(台账优先,按边去重);"
606
+ "聚合基于分页前全集;边时刻字段为 t(观察轴),"
601
607
  "无效力轴字段——真实时间条件请用缺省 time_axis=observed")}