@furongjun1999/dsh-memory 0.8.1 → 0.9.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (714) hide show
  1. package/README.md +662 -659
  2. package/codebuddy/README.md +1 -1
  3. package/data/policy.json +17 -6
  4. package/docs/README.md +18 -2
  5. package/docs/discipline/harnesses.yaml +1 -1
  6. package/docs/discipline/templates/spec.txt.tmpl +23 -0
  7. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203.md +179 -0
  8. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203_/347/201/265/346/236/242/351/200/202/351/205/215.md +45 -0
  9. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203_/350/207/252/346/243/200/346/270/205/345/215/225.md +69 -0
  10. package/dsh/README.md +1 -1
  11. package/dsh/cordis.yml.example +1 -1
  12. package/hive/README.md +705 -0
  13. package/hive/id_charset_blocks.txt +147 -0
  14. package/lib/bridge.d.ts +3 -0
  15. package/lib/bridge.js +32 -11
  16. package/lib/cli.js +14 -17
  17. package/lib/hooks.d.ts +18 -3
  18. package/lib/hooks.js +147 -18
  19. package/lib/index.d.ts +2 -2
  20. package/lib/index.js +18 -4
  21. package/lib/init.js +21 -21
  22. package/lib/lib/datapath.d.ts +56 -0
  23. package/lib/lib/datapath.js +102 -9
  24. package/lib/lib/hook_audit.d.ts +0 -1
  25. package/lib/lib/hook_audit.js +13 -1
  26. package/lib/lib/mdcg_client.d.ts +4 -1
  27. package/lib/lib/mdcg_client.js +10 -2
  28. package/lib/lib/mutual.js +61 -15
  29. package/lib/lib/prompt_safety.js +16 -1
  30. package/lib/lib/roleplay_web.js +30 -2
  31. package/lib/lib/token_store.d.ts +25 -6
  32. package/lib/lib/token_store.js +224 -33
  33. package/lib/tools.d.ts +8 -2
  34. package/lib/tools.js +22 -3
  35. package/md_cg/_guard_kit.py +121 -0
  36. package/md_cg/admission.py +718 -718
  37. package/md_cg/anchor.py +114 -0
  38. package/md_cg/audit.py +22 -5
  39. package/md_cg/autonomy.py +433 -288
  40. package/md_cg/autonomy_modes.py +781 -642
  41. package/md_cg/bench_beir_bm25.py +154 -0
  42. package/md_cg/bench_beir_scifact.py +170 -0
  43. package/md_cg/bench_bm25_blockmax.py +134 -0
  44. package/md_cg/bench_bm25_incremental.py +246 -0
  45. package/md_cg/bench_ccg_heading.py +118 -0
  46. package/md_cg/bench_csre_correctness.py +145 -0
  47. package/md_cg/bench_excerpt_budget.py +94 -0
  48. package/md_cg/bench_fuzzy_substrings.py +299 -0
  49. package/md_cg/bench_memory_rsi.py +358 -0
  50. package/md_cg/bench_memory_rsi_latency.py +82 -0
  51. package/md_cg/bench_memory_rsi_public.py +116 -0
  52. package/md_cg/bench_memory_rsi_tools.py +229 -0
  53. package/md_cg/bench_rrf_candidates.py +212 -0
  54. package/md_cg/bench_rrf_public.py +100 -0
  55. package/md_cg/bench_text_projections.py +221 -0
  56. package/md_cg/bench_timeanchor.py +357 -0
  57. package/md_cg/bm25.py +601 -0
  58. package/md_cg/branches.py +404 -327
  59. package/md_cg/build_postings.py +74 -73
  60. package/md_cg/ccgc.py +4 -2
  61. package/md_cg/chain.py +572 -379
  62. package/md_cg/coldverify.py +531 -292
  63. package/md_cg/condaccept.py +263 -0
  64. package/md_cg/condgate.py +308 -0
  65. package/md_cg/config_registry.py +329 -0
  66. package/md_cg/config_registry_bulk.py +482 -0
  67. package/md_cg/config_registry_guard.py +487 -0
  68. package/md_cg/config_render.py +354 -0
  69. package/md_cg/config_validate.py +455 -0
  70. package/md_cg/conformance.py +21 -0
  71. package/md_cg/conformance_core.py +753 -0
  72. package/md_cg/consistency.py +1278 -955
  73. package/md_cg/consolidate.py +180 -20
  74. package/md_cg/crypto.py +794 -472
  75. package/md_cg/datapath.py +137 -12
  76. package/md_cg/eval_common.py +522 -575
  77. package/md_cg/evidence.py +946 -585
  78. package/md_cg/evidence_delivery.py +101 -0
  79. package/md_cg/experience_consolidation.py +317 -0
  80. package/md_cg/export.py +329 -222
  81. package/md_cg/forgetting.py +1050 -922
  82. package/md_cg/freshness.py +601 -548
  83. package/md_cg/fsutil.py +1120 -824
  84. package/md_cg/goal_gen.py +458 -0
  85. package/md_cg/hotcache.py +107 -9
  86. package/md_cg/hyperedge.py +14 -3
  87. package/md_cg/identity.py +573 -391
  88. package/md_cg/imgskill.py +1712 -0
  89. package/md_cg/insight.py +540 -521
  90. package/md_cg/interface_schema.py +146 -0
  91. package/md_cg/interop.py +20 -0
  92. package/md_cg/judgment_manifest.py +24 -1
  93. package/md_cg/lifecycle.py +86 -5
  94. package/md_cg/links.py +27 -6
  95. package/md_cg/logref.py +332 -327
  96. package/md_cg/mcp_server.py +5227 -4449
  97. package/md_cg/mdcg.py +1301 -203
  98. package/md_cg/mdcos.py +7104 -5440
  99. package/md_cg/memory_rsi.py +308 -0
  100. package/md_cg/metacognition.py +726 -591
  101. package/md_cg/nodefile.py +151 -3
  102. package/md_cg/op_table.py +1128 -0
  103. package/md_cg/postings.py +524 -300
  104. package/md_cg/predict.py +4 -1
  105. package/md_cg/probe_memory_rsi.py +95 -0
  106. package/md_cg/probe_memory_rsi_mcp.py +66 -0
  107. package/md_cg/protect.py +188 -28
  108. package/md_cg/protocol.py +492 -411
  109. package/md_cg/provenance.py +7 -1
  110. package/md_cg/qmd.py +477 -0
  111. package/md_cg/qmd_llm.py +334 -0
  112. package/md_cg/query_excerpt.py +171 -0
  113. package/md_cg/queue_health.py +130 -0
  114. package/md_cg/reach.py +470 -453
  115. package/md_cg/readcache.py +115 -3
  116. package/md_cg/reconcile.py +239 -228
  117. package/md_cg/refindex.py +1191 -1042
  118. package/md_cg/refine.py +12 -3
  119. package/md_cg/retrieve.py +128 -0
  120. package/md_cg/review_cli.py +204 -26
  121. package/md_cg/revise.py +140 -0
  122. package/md_cg/rollback.py +256 -19
  123. package/md_cg/rollback_cli.py +21 -1
  124. package/md_cg/rotate.py +347 -0
  125. package/md_cg/routing.py +62 -1
  126. package/md_cg/rrf_candidates.py +204 -0
  127. package/md_cg/run_tests.py +19 -1
  128. package/md_cg/scrub.py +177 -23
  129. package/md_cg/security.py +269 -17
  130. package/md_cg/self_state.py +1053 -1029
  131. package/md_cg/self_surface.py +50 -0
  132. package/md_cg/semantic/canonical.py +1 -1
  133. package/md_cg/semantic/export_en_zh_map.py +2 -2
  134. package/md_cg/semantic/zh_en_atoms.py +2 -0
  135. package/md_cg/session5.py +106 -0
  136. package/md_cg/signer.py +76 -2
  137. package/md_cg/sleep.py +1779 -1583
  138. package/md_cg/sources.py +273 -15
  139. package/md_cg/state_events.py +75 -10
  140. package/md_cg/state_slots.py +312 -221
  141. package/md_cg/stg.py +82 -16
  142. package/md_cg/stgidx.py +537 -281
  143. package/md_cg/subgraph.py +851 -729
  144. package/md_cg/sustain.py +458 -19
  145. package/md_cg/task_memory.py +367 -0
  146. package/md_cg/test_action_derive.py +210 -203
  147. package/md_cg/test_audit_heartbeat_20261015.py +417 -0
  148. package/md_cg/test_audit_protection_20261015.py +483 -0
  149. package/md_cg/test_audit_rotate_parity.py +280 -0
  150. package/md_cg/test_audit_state_20261015.py +253 -0
  151. package/md_cg/test_audit_write_20261015.py +161 -0
  152. package/md_cg/test_auto_defaults.py +43 -4
  153. package/md_cg/test_autonomy_emotion.py +328 -0
  154. package/md_cg/test_autonomy_modes.py +43 -3
  155. package/md_cg/test_b1_foreign_read.py +245 -0
  156. package/md_cg/test_bm25.py +438 -0
  157. package/md_cg/test_bm25_hydration_refill.py +265 -0
  158. package/md_cg/test_bm25_incremental.py +241 -0
  159. package/md_cg/test_bm25_incremental_mutations.py +160 -0
  160. package/md_cg/test_bm25_mutations.py +205 -0
  161. package/md_cg/test_bm25_pool_view.py +196 -0
  162. package/md_cg/test_boot_openblas_guard.py +218 -197
  163. package/md_cg/test_boundary_hit.py +1 -1
  164. package/md_cg/test_branches_sensitivity.py +375 -0
  165. package/md_cg/test_c8_search_rrf_gates.py +1 -1
  166. package/md_cg/test_canonical_timezones.py +211 -0
  167. package/md_cg/test_ccg_heading_parser.py +73 -0
  168. package/md_cg/test_chain_best_first.py +403 -0
  169. package/md_cg/test_chain_candidate_scope.py +227 -0
  170. package/md_cg/test_cn_recall_grams.py +206 -0
  171. package/md_cg/test_coldverify_drain.py +127 -0
  172. package/md_cg/test_condaccept.py +156 -0
  173. package/md_cg/test_condgate.py +141 -0
  174. package/md_cg/test_config_registry.py +55 -0
  175. package/md_cg/test_crypto_rotate.py +257 -0
  176. package/md_cg/test_csre_correctness.py +297 -0
  177. package/md_cg/test_csre_index_import_guard.py +161 -0
  178. package/md_cg/test_csre_mutations.py +34 -0
  179. package/md_cg/test_csre_session.py +69 -0
  180. package/md_cg/test_curiosity_budget.py +468 -0
  181. package/md_cg/test_d17_autostart_toolface.py +453 -0
  182. package/md_cg/test_datapath_tilde_home.py +271 -0
  183. package/md_cg/test_derived_cache_generations.py +256 -0
  184. package/md_cg/test_evidence_delivery_compact.py +54 -0
  185. package/md_cg/test_exact_text_cache.py +191 -0
  186. package/md_cg/test_excerpt_budget.py +188 -0
  187. package/md_cg/test_experience_consolidation.py +112 -0
  188. package/md_cg/test_export_default_collision.py +138 -0
  189. package/md_cg/test_export_snapshots.py +322 -0
  190. package/md_cg/test_fuzzy_substring_equivalence.py +127 -0
  191. package/md_cg/test_gain_gate.py +16 -5
  192. package/md_cg/test_goal_gen.py +355 -0
  193. package/md_cg/test_h2_session_view_norm.py +251 -233
  194. package/md_cg/test_h4_sustain_snapshot.py +1490 -1387
  195. package/md_cg/test_heartbeat_ledger.py +557 -0
  196. package/md_cg/test_hierarchy_audit_graph.py +237 -0
  197. package/md_cg/test_i50c_meta_passthrough.py +628 -608
  198. package/md_cg/test_i50e_readside_protection.py +6 -4
  199. package/md_cg/test_identity_attribution.py +96 -2
  200. package/md_cg/test_identity_contract.py +329 -0
  201. package/md_cg/test_imgskill.py +1444 -0
  202. package/md_cg/test_index_snapshot_shape.py +240 -0
  203. package/md_cg/test_interop_judgment.py +258 -228
  204. package/md_cg/test_issue111_gate_order.py +77 -0
  205. package/md_cg/test_issue111_scoring_contract.py +87 -0
  206. package/md_cg/test_issue121_calibration_bounds.py +293 -0
  207. package/md_cg/test_issue128_session_env_authority.py +246 -0
  208. package/md_cg/test_issue130_rrf_rank_credibility.py +217 -0
  209. package/md_cg/test_issue131_postings_content_staleness.py +424 -0
  210. package/md_cg/test_issue145_sleep_no_silent_rollback.py +168 -0
  211. package/md_cg/test_issue146_frontmatter_quarantine.py +428 -0
  212. package/md_cg/test_issue147_pack_id_escape.py +378 -0
  213. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -0
  214. package/md_cg/test_issue149_accel_default_face.py +249 -0
  215. package/md_cg/test_issue150_empty_query_terms.py +328 -0
  216. package/md_cg/test_issue151_153_157_write_cache_index.py +152 -0
  217. package/md_cg/test_issue151b_base_add_importance_guard.py +166 -0
  218. package/md_cg/test_issue152_sealed_postings.py +309 -0
  219. package/md_cg/test_issue152b_decrypt_cache.py +218 -0
  220. package/md_cg/test_issue153b_cache_alias_and_canon.py +236 -0
  221. package/md_cg/test_issue153b_index_generation_invalidation.py +143 -0
  222. package/md_cg/test_issue157b_index_remainder.py +344 -0
  223. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -0
  224. package/md_cg/test_issue190_tidy_idempotent.py +806 -0
  225. package/md_cg/test_issue191_import_trust.py +382 -0
  226. package/md_cg/test_issue192_move_layer_indices_guard.py +258 -0
  227. package/md_cg/test_issue193_consistency_knowledge_guard.py +524 -0
  228. package/md_cg/test_issue193_write_scope.py +378 -0
  229. package/md_cg/test_issue197_rank_credibility_property.py +201 -0
  230. package/md_cg/test_issue211_export_target.py +325 -0
  231. package/md_cg/test_issue212_writeface_gaps.py +349 -0
  232. package/md_cg/test_issue214_reject_sensitivity.py +267 -0
  233. package/md_cg/test_issue215_condition_source_gap.py +272 -0
  234. package/md_cg/test_issue216_clash_routes.py +214 -0
  235. package/md_cg/test_issue217_slot_routes.py +248 -0
  236. package/md_cg/test_issue218_postcondition_value_blind.py +222 -0
  237. package/md_cg/test_issue225_consistency_torn_log.py +433 -0
  238. package/md_cg/test_issue245_swarm_traversal.py +366 -0
  239. package/md_cg/test_issue258_pack_sensitivity.py +468 -0
  240. package/md_cg/test_issue265_coldverify_multiproc.py +438 -0
  241. package/md_cg/test_issue274_read_node_id_none.py +341 -0
  242. package/md_cg/test_issue275_layer_param.py +250 -0
  243. package/md_cg/test_issue277_node_id_traversal.py +384 -0
  244. package/md_cg/test_issue278_neg_separated_tension.py +271 -0
  245. package/md_cg/test_issue278_neg_window.py +294 -0
  246. package/md_cg/test_issue278_negative_layering.py +83 -0
  247. package/md_cg/test_issue279_signers_path_guard.py +652 -0
  248. package/md_cg/test_issue284_skip_not_pass.py +291 -0
  249. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -0
  250. package/md_cg/test_issue295_sleep_root_binding.py +589 -0
  251. package/md_cg/test_issue297_rewrite_sensitivity.py +454 -0
  252. package/md_cg/test_issue298_consistency_ledger_sensitivity.py +421 -0
  253. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -0
  254. package/md_cg/test_issue303_design_boundaries.py +262 -0
  255. package/md_cg/test_issue313_writelimit_sensitivity.py +404 -0
  256. package/md_cg/test_issue315_merge_branch_sensitivity.py +384 -0
  257. package/md_cg/test_issue315_sensitivity_passthrough_guard.py +514 -0
  258. package/md_cg/test_issue319_tenant_unregistered_bypass.py +257 -0
  259. package/md_cg/test_issue320_vstate_requires_verify.py +279 -0
  260. package/md_cg/test_issue321_mcp_deep_json.py +305 -0
  261. package/md_cg/test_issue322_node_write_lock.py +727 -0
  262. package/md_cg/test_issue323_aggregate_segment_boundary.py +365 -0
  263. package/md_cg/test_issue324_write_size_fields.py +215 -0
  264. package/md_cg/test_issue325_audit_poison.py +230 -0
  265. package/md_cg/test_issue326_append_jsonl_oserror.py +464 -0
  266. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -0
  267. package/md_cg/test_issue326_key_perms.py +355 -0
  268. package/md_cg/test_issue326_twin_parser_parity.py +323 -0
  269. package/md_cg/test_issue326_vm_call_frame.py +569 -0
  270. package/md_cg/test_issue345_writelimit_effective_sens.py +234 -0
  271. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -0
  272. package/md_cg/test_issue346_review_overwrite_guard.py +509 -0
  273. package/md_cg/test_issue348_insight_verify_op.py +200 -0
  274. package/md_cg/test_issue348_merge_rmw_lock.py +345 -0
  275. package/md_cg/test_issue350_casefold_collision.py +236 -0
  276. package/md_cg/test_issue351_ingest_root_fallback.py +202 -0
  277. package/md_cg/test_issue352_imgaudit.py +418 -0
  278. package/md_cg/test_issue352_pathsjson.py +537 -0
  279. package/md_cg/test_issue352_refindex.py +412 -0
  280. package/md_cg/test_issue352_rollback.py +604 -0
  281. package/md_cg/test_issue352_vstateinherit.py +196 -0
  282. package/md_cg/test_issue354_p1_writelimit_type.py +522 -0
  283. package/md_cg/test_issue354_p2_datapath_clock.py +381 -0
  284. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -0
  285. package/md_cg/test_issue354_rust_index_containment.py +571 -0
  286. package/md_cg/test_issue354_rust_wal_containment.py +606 -0
  287. package/md_cg/test_issue358_truncation_observable.py +247 -0
  288. package/md_cg/test_issue360_tidy_private_excerpt.py +196 -0
  289. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -0
  290. package/md_cg/test_issue362_neg_condition.py +468 -0
  291. package/md_cg/test_issue363_lexical_idf.py +275 -0
  292. package/md_cg/test_issue370_readcache_assembly.py +488 -0
  293. package/md_cg/test_issue375_state_slot_retire.py +325 -0
  294. package/md_cg/test_issue376_heartbeat_failed.py +293 -0
  295. package/md_cg/test_issue377_layer_protect_stamp.py +324 -0
  296. package/md_cg/test_issue378_protected_floor.py +310 -0
  297. package/md_cg/test_issue383_state_event_write_gate.py +462 -0
  298. package/md_cg/test_issue397_sens_eff_wiring.py +435 -0
  299. package/md_cg/test_issue398_toolface_op_parity.py +511 -0
  300. package/md_cg/test_issue399_hive_json_shape.py +317 -0
  301. package/md_cg/test_issue400_hive_dirty_args.py +450 -0
  302. package/md_cg/test_issue401_wisdom_codegen.py +295 -0
  303. package/md_cg/test_issue404_heal_receipt.py +390 -0
  304. package/md_cg/test_issue405_git_pathspec.py +333 -0
  305. package/md_cg/test_issue408_eface_registry.py +291 -0
  306. package/md_cg/test_issue409_compact_index_completeness.py +509 -0
  307. package/md_cg/test_issue410_verify_demote_write.py +366 -0
  308. package/md_cg/test_issue411_scrub_idempotence.py +575 -0
  309. package/md_cg/test_issue412_discipline_producer_parity.py +312 -0
  310. package/md_cg/test_issue413_preimage_failclosed.py +239 -0
  311. package/md_cg/test_issue413_preimage_twin.py +340 -0
  312. package/md_cg/test_issue414_write_args_parity.py +613 -0
  313. package/md_cg/test_issue415_deps_gate_probe.py +358 -0
  314. package/md_cg/test_issue416_entry_key_subset.py +525 -0
  315. package/md_cg/test_issue417_twophase_merge_landed.py +423 -0
  316. package/md_cg/test_issue418_identity_role_type_gate.py +188 -0
  317. package/md_cg/test_issue418_role_type_gate.py +265 -0
  318. package/md_cg/test_issue419_pii_redaction.py +642 -0
  319. package/md_cg/test_issue424_merge_confirm_sensitivity.py +381 -0
  320. package/md_cg/test_issue425_ingest_library_path.py +331 -0
  321. package/md_cg/test_issue426a_dedup_receipt.py +242 -0
  322. package/md_cg/test_issue426b_root_clash_invisible.py +270 -0
  323. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -0
  324. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -0
  325. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -0
  326. package/md_cg/test_issue427_serve_status_shape.py +191 -0
  327. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -0
  328. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -0
  329. package/md_cg/test_issue434_435_float_gate.py +90 -0
  330. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -0
  331. package/md_cg/test_issue43_default_policy.py +13 -4
  332. package/md_cg/test_issue443a_state_event_length_gate.py +94 -0
  333. package/md_cg/test_issue443b_audit_record_length_gate.py +83 -0
  334. package/md_cg/test_issue443c_self_state_imgskill_length_gate.py +77 -0
  335. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -0
  336. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -0
  337. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -0
  338. package/md_cg/test_issue446_is_encrypted_envelope.py +166 -0
  339. package/md_cg/test_issue447_recent_sens_failclosed.py +270 -0
  340. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -0
  341. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -0
  342. package/md_cg/test_issue451_audit_actor.py +313 -0
  343. package/md_cg/test_issue452_ingest_root_hint.py +238 -0
  344. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -0
  345. package/md_cg/test_issue463_ghost_prune_guard.py +259 -0
  346. package/md_cg/test_issue466_basis_registry.py +469 -0
  347. package/md_cg/test_issue467_identity_sensitivity.py +204 -0
  348. package/md_cg/test_issue467_identity_sensitivity_parity.py +361 -0
  349. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -0
  350. package/md_cg/test_issue470_wal_event_durable.py +427 -0
  351. package/md_cg/test_issue471_identity_readable.py +137 -0
  352. package/md_cg/test_issue472_audit_chain.py +91 -0
  353. package/md_cg/test_issue472_prune_ledger.py +106 -0
  354. package/md_cg/test_issue472_rollback_degraded.py +82 -0
  355. package/md_cg/test_issue491_compose_sandbox.py +460 -0
  356. package/md_cg/test_issue492_dup_readout_opt_in.py +292 -0
  357. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -0
  358. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -0
  359. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -0
  360. package/md_cg/test_issue522_review_record_sensitivity.py +267 -0
  361. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -0
  362. package/md_cg/test_issue525_read_null_semantics.py +52 -0
  363. package/md_cg/test_issue538_hook_condition_space.py +97 -0
  364. package/md_cg/test_issue540_path_guard_whitespace.py +126 -0
  365. package/md_cg/test_issue541_tidy_protect_gate.py +141 -0
  366. package/md_cg/test_issue542_tenant_root_same.py +153 -0
  367. package/md_cg/test_issue543_issue_authorization.py +147 -0
  368. package/md_cg/test_issue544_sandbox_reflection_gate.py +175 -0
  369. package/md_cg/test_issue545_charset_vs_size_diagnostic.py +77 -0
  370. package/md_cg/test_issue546_ledger_concurrency.py +81 -0
  371. package/md_cg/test_issue547_append_jsonl_whitelist.py +115 -0
  372. package/md_cg/test_issue547_audit_durable.py +96 -0
  373. package/md_cg/test_issue549_durable_append.py +143 -0
  374. package/md_cg/test_issue557_r1_credential_value_forms.py +76 -0
  375. package/md_cg/test_issue557_r2_write_entries_size_gate.py +84 -0
  376. package/md_cg/test_issue557_r3_pem_block_redaction.py +75 -0
  377. package/md_cg/test_issue559_refine_prefix.py +70 -0
  378. package/md_cg/test_issue561_pending_review.py +109 -0
  379. package/md_cg/test_issue66_scrub_semantics.py +107 -0
  380. package/md_cg/test_issue67_scrub_control_pool.py +233 -0
  381. package/md_cg/test_issue69_audit_boundary.py +129 -0
  382. package/md_cg/test_issue71_queue_backlog.py +377 -0
  383. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -0
  384. package/md_cg/test_issue73_doc_chapter_refs.py +326 -0
  385. package/md_cg/test_issue75_neural_failure.py +582 -0
  386. package/md_cg/test_issue78_export_concurrency.py +334 -0
  387. package/md_cg/test_issue80_residual_flush.py +169 -0
  388. package/md_cg/test_issue82_credential_rules.py +271 -0
  389. package/md_cg/test_issue82_layer_and_size.py +120 -0
  390. package/md_cg/test_issue84_portability.py +95 -0
  391. package/md_cg/test_issue85_export_overwrite.py +113 -0
  392. package/md_cg/test_issue86_runtime_revoke.py +110 -0
  393. package/md_cg/test_issue87_default_sensitivity_single.py +201 -0
  394. package/md_cg/test_issue88_conclusion_face.py +280 -0
  395. package/md_cg/test_issue88_execution_conflicts.py +87 -0
  396. package/md_cg/test_issue89_zero_score.py +169 -0
  397. package/md_cg/test_issue89a_score_cap_tiebreak.py +279 -0
  398. package/md_cg/test_issue91_verifier_sandbox.py +314 -0
  399. package/md_cg/test_issue91_verifier_timeout.py +528 -0
  400. package/md_cg/test_issue93_remember_redaction.py +282 -0
  401. package/md_cg/test_issue96_key_fallback.py +102 -0
  402. package/md_cg/test_issue98_tenant_root.py +104 -0
  403. package/md_cg/test_jsonl_commit_watermark.py +221 -0
  404. package/md_cg/test_live_validity_cache.py +256 -0
  405. package/md_cg/test_logref.py +32 -0
  406. package/md_cg/test_mcp_call_argument_types.py +99 -0
  407. package/md_cg/test_md_access_parity.py +80 -5
  408. package/md_cg/test_md_cg_no_hive_dep.py +140 -0
  409. package/md_cg/test_memory_rsi.py +215 -0
  410. package/md_cg/test_memory_rsi_adversarial.py +91 -0
  411. package/md_cg/test_mode_parity.py +1413 -1393
  412. package/md_cg/test_mutation_residue.py +120 -0
  413. package/md_cg/test_mutation_rollback.py +62 -32
  414. package/md_cg/test_n123_derive_expiry_chain.py +10 -5
  415. package/md_cg/test_n130_verify_falsified_protect.py +185 -185
  416. package/md_cg/test_n209_verify_write_face_gates.py +7 -2
  417. package/md_cg/test_n230_dirty_replay.py +52 -9
  418. package/md_cg/test_n62_tenant_bind_failclosed.py +3 -3
  419. package/md_cg/test_neg_coverage_budget.py +500 -0
  420. package/md_cg/test_neg_tail_honesty.py +79 -9
  421. package/md_cg/test_p0.py +16 -2
  422. package/md_cg/test_p14_root_fallback.py +373 -0
  423. package/md_cg/test_p1x_ref_root.py +47 -10
  424. package/md_cg/test_p21_tokens.py +2 -1
  425. package/md_cg/test_p24_evidence.py +232 -227
  426. package/md_cg/test_p26_refindex.py +20 -3
  427. package/md_cg/test_p27_docindex.py +16 -1
  428. package/md_cg/test_p28_refcheck.py +45 -24
  429. package/md_cg/test_p29_session_ingest_export.py +6 -0
  430. package/md_cg/test_p2_mcp.py +474 -453
  431. package/md_cg/test_p2_six_elements.py +14 -1
  432. package/md_cg/test_p3.py +370 -261
  433. package/md_cg/test_p33_ccg_wiring.py +9 -2
  434. package/md_cg/test_p3_legacy_closure.py +6 -1
  435. package/md_cg/test_p40_refine_worklist.py +5 -2
  436. package/md_cg/test_p47_session_view.py +25 -9
  437. package/md_cg/test_p4_freshness.py +8 -1
  438. package/md_cg/test_p83_jsonrpc_parse_error.py +124 -0
  439. package/md_cg/test_p9c_dedup_hints.py +7 -2
  440. package/md_cg/test_policy_required_ccg.py +12 -0
  441. package/md_cg/test_postings_digest_memo.py +139 -0
  442. package/md_cg/test_predict_beta.py +138 -135
  443. package/md_cg/test_qmd.py +500 -0
  444. package/md_cg/test_query_excerpt.py +209 -0
  445. package/md_cg/test_reach.py +456 -378
  446. package/md_cg/test_reach_snapshot_admission.py +218 -0
  447. package/md_cg/test_readcache_prodpath.py +4 -0
  448. package/md_cg/test_recall_face_guards.py +854 -812
  449. package/md_cg/test_recall_metadata.py +422 -0
  450. package/md_cg/test_retr_s5.py +104 -5
  451. package/md_cg/test_retr_score_once.py +14 -2
  452. package/md_cg/test_review_cli_attribution.py +11 -7
  453. package/md_cg/test_review_queue_batch.py +123 -0
  454. package/md_cg/test_review_queue_index.py +130 -0
  455. package/md_cg/test_rrf_candidates.py +292 -0
  456. package/md_cg/test_rrf_qualified_topk.py +214 -0
  457. package/md_cg/test_rrf_unique_votes.py +218 -0
  458. package/md_cg/test_s1_ast_judge.py +110 -0
  459. package/md_cg/test_scrub_ledger.py +413 -0
  460. package/md_cg/test_security_audit_b26.py +34 -3
  461. package/md_cg/test_security_audit_v21.py +1 -2
  462. package/md_cg/test_sensitivity_predicate_single_point.py +184 -0
  463. package/md_cg/test_session5_identity.py +93 -0
  464. package/md_cg/test_session_attribution_consistency.py +813 -0
  465. package/md_cg/test_session_identity_tristate.py +486 -0
  466. package/md_cg/test_sleep_p1.py +35 -3
  467. package/md_cg/test_state_event_op.py +8 -1
  468. package/md_cg/test_state_projection_streaming.py +136 -0
  469. package/md_cg/test_stg_interval_candidates.py +280 -0
  470. package/md_cg/test_stg_time_blocks.py +239 -0
  471. package/md_cg/test_stgidx_index_parity.py +16 -12
  472. package/md_cg/test_subgraph_bounded_bfs.py +227 -0
  473. package/md_cg/test_sustain_bounded.py +30 -2
  474. package/md_cg/test_task_memory.py +394 -0
  475. package/md_cg/test_text_projection_mutations.py +101 -0
  476. package/md_cg/test_time_anchor.py +421 -0
  477. package/md_cg/test_time_core_lint.py +1024 -975
  478. package/md_cg/test_tool_face.py +200 -189
  479. package/md_cg/test_trust_bounded_frontier.py +248 -0
  480. package/md_cg/test_trust_edge_reachability.py +405 -0
  481. package/md_cg/test_w5_path_fingerprint.py +381 -0
  482. package/md_cg/test_w7_redlines.py +659 -0
  483. package/md_cg/test_write_return_shape.py +919 -0
  484. package/md_cg/test_writepipe.py +5 -3
  485. package/md_cg/timeanchor.py +534 -0
  486. package/md_cg/tokens.py +68 -5
  487. package/md_cg/tool_face.py +273 -260
  488. package/md_cg/trust.py +110 -26
  489. package/md_cg/twophase.py +74 -2
  490. package/md_cg/weights.py +642 -638
  491. package/md_cg/whitebox.py +9 -0
  492. package/md_cg/whitebox_kb/aeis_core/core.py +5026 -5026
  493. package/md_cg/whitebox_kb/wisdom/chat_engine.py +1504 -1506
  494. package/md_cg/whitebox_kb/wisdom/code_compose.py +876 -837
  495. package/md_cg/whitebox_kb/wisdom/compiler_code_units.py +3040 -3033
  496. package/md_cg/whitebox_kb/wisdom/compose_engine.py +3 -2
  497. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +22 -2
  498. package/md_cg/whitebox_kb/wisdom/core/parser.py +17 -0
  499. package/md_cg/whitebox_kb/wisdom/csre.py +412 -264
  500. package/md_cg/whitebox_kb/wisdom/csre_session.py +97 -0
  501. package/md_cg/whitebox_kb/wisdom/md_access.py +23 -3
  502. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +21 -0
  503. package/md_cg/whitebox_kb/wisdom/mini_python.py +44 -7
  504. package/md_cg/whitebox_kb/wisdom/navigate.py +249 -248
  505. package/md_cg/whitebox_kb/wisdom/net_units.py +12 -7
  506. package/md_cg/whitebox_kb/wisdom/neural_retrieve.py +100 -10
  507. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +13 -7
  508. package/md_cg/whitebox_kb/wisdom/test_ecosystem_assembly.py +158 -158
  509. package/md_cg/whitebox_kb/wisdom/test_safe_module_proxy.py +147 -0
  510. package/md_cg/whitebox_kb/wisdom/verifier.py +1918 -1297
  511. package/md_cg/writelimit.py +584 -390
  512. package/md_cg/writepipe.py +587 -76
  513. package/package.json +13 -9
  514. package/src/bridge.ts +34 -11
  515. package/src/cli.ts +75 -65
  516. package/src/hooks.ts +908 -776
  517. package/src/index.ts +19 -5
  518. package/src/init.ts +362 -361
  519. package/src/lib/datapath.ts +419 -326
  520. package/src/lib/hook_audit.ts +256 -243
  521. package/src/lib/mdcg_client.ts +10 -2
  522. package/src/lib/mutual.ts +481 -432
  523. package/src/lib/prompt_safety.ts +164 -149
  524. package/src/lib/roleplay_web.ts +30 -2
  525. package/src/lib/token_store.ts +274 -52
  526. package/src/tools.ts +249 -223
  527. package/zcode/README.md +1 -1
  528. package/docs/GBrain/345/217/257/345/200/237/351/211/264/347/202/271_/347/201/265/346/236/242/350/220/275/347/202/271/344/272/244/346/216/245_20260919.md +0 -169
  529. package/docs/Pi/345/217/257/345/255/246/344/271/240/344/274/230/347/202/271_/347/201/265/346/236/242/345/244/247/350/204/221/346/224/271/350/277/233/344/272/244/346/216/245_20260915.md +0 -144
  530. package/docs/eval/AGI/344/270/203/347/273/264/350/257/204/345/210/206/346/212/245/345/221/212_md_cg_v1.0.md +0 -299
  531. package/docs/eval/AGI/344/270/203/347/273/264/350/257/204/345/210/206/346/212/245/345/221/212_md_cg_v2.0.md +0 -239
  532. package/docs/eval/AGI/344/270/203/347/273/264/350/257/204/345/210/206/346/212/245/345/221/212_/345/205/255/345/256/266/350/256/260/345/277/206/347/263/273/347/273/237/345/220/214/345/260/272/345/256/236/346/265/213_v3.1.md +0 -340
  533. package/docs/eval/DSH/346/227/245/345/277/227/347/264/242/345/274/225v2_/345/217/202/350/200/203dsh-TUI_v1.0.md +0 -248
  534. package/docs/eval/DSH/346/227/245/345/277/227/347/264/242/345/274/225/346/225/210/346/236/234/351/252/214/350/257/201_v1.0.md +0 -209
  535. package/docs/eval/DSH/347/253/257/347/274/272/351/231/267/344/270/223/351/241/271_v1.0.md +0 -254
  536. package/docs/eval/N225_/347/264/242/345/274/225/346/227/245/345/277/227/351/235/236/345/257/271/350/261/241/350/243/205/350/275/275/351/235/242/347/261/273/345/236/213/351/227/270_v1.0.md +0 -418
  537. package/docs/eval/P1b2_/350/257/273/351/235/242/344/273/243/351/231/205/344/277/256/345/244/215_v1.0.md +0 -124
  538. package/docs/eval/bench_lingshu_self/bench_self.py +0 -140
  539. package/docs/eval/bench_lingshu_self/self_bench_result.json +0 -404
  540. package/docs/eval/bench_lingshu_self//347/201/265/346/236/242/350/207/252/345/272/223/347/253/257/345/210/260/347/253/257/346/243/200/347/264/242/345/256/236/346/265/213_v1.0.md +0 -38
  541. package/docs/eval/cons200_/345/206/262/347/252/201/346/243/200/346/265/213/351/200/211/351/235/242_/345/256/236/346/226/275/350/256/260/345/275/225_v1.0.md +0 -223
  542. package/docs/eval/cons200_/345/206/262/347/252/201/346/243/200/346/265/213/351/200/211/351/235/242_/345/256/236/346/226/275/350/256/260/345/275/225_v1.1.md +0 -340
  543. package/docs/eval/issue43_/351/273/230/350/256/244/347/255/226/347/225/245/344/270/216/351/224/256/347/261/273/345/236/213/351/227/270_v1.1.md +0 -441
  544. package/docs/eval/issue43_/351/273/230/350/256/244/347/255/226/347/225/245/345/212/240/350/275/275/344/270/216/345/207/255/346/215/256/346/230/216/346/226/207/351/230/237/345/210/227_v1.0.md +0 -398
  545. package/docs/eval/issue50_/345/205/203/346/225/260/346/215/256/351/200/217/344/274/240/344/270/216/345/205/234/345/272/225_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -437
  546. package/docs/eval/issue50_/345/215/212/351/207/215/345/244/215/345/276/205/345/256/232/345/244/215/346/240/270_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -488
  547. package/docs/eval/issue50_/345/276/205/345/256/232/345/244/215/346/240/270/345/205/245/351/230/237_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -428
  548. package/docs/eval/issue50_/350/257/273/351/235/242/344/277/235/346/212/244/345/217/252/350/256/244/346/230/276/345/274/217/346/235/245/346/272/220_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -271
  549. package/docs/eval/issue50_/351/207/215/350/246/201/345/272/246/345/220/214/346/272/220/344/270/216/344/277/235/346/212/244/350/257/255/344/271/211_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -306
  550. package/docs/eval/issue51_/344/270/200/351/224/256/345/256/211/350/243/205/345/244/261/350/264/245_/345/275/222/345/261/236/345/210/244/345/256/232_v1.0.md +0 -58
  551. package/docs/eval/issue52_/346/235/241/344/273/266/345/205/210/350/241/214/344/270/216/346/210/252/346/226/255/345/217/257/350/247/202/346/265/213_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -360
  552. package/docs/eval/issue64_replay_check_/346/240/270/351/252/214/344/270/216/344/277/256/345/244/215_v1.0.md +0 -284
  553. package/docs/eval/issue65_session_recall_/344/274/232/350/257/235/351/232/224/347/246/273_/346/240/270/351/252/214/344/270/216/344/277/256/345/244/215_v1.0.md +0 -329
  554. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/241/346/241/243/344/275/215/345/215/225/344/270/200/345/205/245/345/217/243_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -651
  555. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/242/345/217/230/346/233/264/345/215/225/344/270/216/345/233/236/346/273/232/345/216/237/350/257/255_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -439
  556. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/243/345/207/206/345/205/245/350/257/273/346/225/260_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -1337
  557. package/docs/eval//344/270/211/346/241/243/350/207/252/346/262/273_/346/255/245/351/252/244/342/221/244/346/224/266/345/256/230/344/270/216/345/205/250/351/223/276/351/252/214/346/224/266_/350/220/275/347/240/201/350/256/260/345/275/225_v1.0.md +0 -1817
  558. package/docs/eval//344/270/215/345/217/257/351/235/240/346/200/247/350/220/275/345/234/260_P0_v1.0.md +0 -185
  559. package/docs/eval//344/274/230/345/214/226/347/254/254/344/270/200/346/211/271_/346/216/245/347/272/277/344/270/216/347/255/211/344/273/267/345/217/230/346/215/242_v1.0.md +0 -498
  560. package/docs/eval//344/274/230/345/214/226/347/254/254/344/270/211/346/211/271_/351/227/250/347/246/201/350/275/254/346/255/243/344/270/216/350/260/203/345/272/246/346/255/242/350/241/200/344/270/216/351/227/250/346/216/247/346/224/266/345/217/243_v1.0.md +0 -669
  561. package/docs/eval//344/274/230/345/214/226/347/254/254/344/272/214/346/211/271_/344/276/235/350/265/226/351/200/217/344/274/240/344/270/216/345/257/271/346/213/215/345/217/243/345/276/204/344/270/216/350/264/237/347/274/223/345/255/230_v1.0.md +0 -683
  562. package/docs/eval//345/207/272/350/264/247/351/235/242/345/206/222/347/203/237_/350/277/233/350/264/247/351/227/250/347/246/201_v1.0.md +0 -460
  563. package/docs/eval//345/217/221/345/270/20306_/344/270/200/351/224/256/351/205/215/347/275/256/344/270/216DSH0172_v1.0.md +0 -171
  564. package/docs/eval//345/217/221/345/270/20307_/345/244/226/351/203/250/346/212/245/345/221/212/345/233/233/346/211/271/344/277/256/345/244/215/344/270/216/346/217/222/344/273/266/351/235/242/345/212/240/345/233/272_v1.0.md +0 -209
  565. package/docs/eval//345/217/221/345/270/20308_/350/207/252/350/277/255/344/273/243/344/270/216/347/235/241/347/234/240_/345/233/276/346/243/200/347/264/242/350/267/257/344/270/216/346/235/203/351/207/215_v1.0.md +0 -97
  566. package/docs/eval//345/217/221/345/270/20309_/346/243/200/347/264/242/351/235/242/344/270/211/346/211/271/346/224/266/345/217/243_v1.0.md +0 -66
  567. package/docs/eval//345/217/221/345/270/20310_/350/257/273/351/235/242/346/215/237/345/235/217UTF8/345/256/266/346/227/217/346/224/266/345/217/243_v1.0.md +0 -71
  568. package/docs/eval//345/217/221/345/270/20311_/345/244/226/346/212/245/345/205/255/350/277/236/344/277/256/344/270/216/344/270/226/347/225/214/346/250/241/345/236/213/345/272/225/345/272/247_v1.0.md +0 -91
  569. package/docs/eval//345/217/221/345/270/20312_/344/270/226/347/225/214/346/250/241/345/236/213/345/212/237/350/203/275/347/253/257_v1.0.md +0 -108
  570. package/docs/eval//345/217/221/345/270/20313_/344/270/212/344/270/213/346/226/207/350/207/252/347/256/241/347/220/206/346/234/272/345/210/266_v1.0.md +0 -114
  571. package/docs/eval//345/217/221/345/270/20314_/350/272/253/344/275/223/303/227/350/204/221/347/273/204/345/220/210_v1.0.md +0 -160
  572. package/docs/eval//345/217/221/345/270/20315_/344/274/232/350/257/235/351/232/224/347/246/273/344/277/256/345/244/215/344/270/216/350/272/253/344/275/223/345/272/223/345/261/225/347/244/272_v1.0.md +0 -88
  573. package/docs/eval//345/256/236/351/252/214/346/226/271/346/241/210_/345/255/246/344/271/240/351/227/255/347/216/257AB/344/270/216/346/250/252/350/257/204_v1.0.md +0 -174
  574. package/docs/eval//345/275/222/344/270/200/345/261/202/347/274/272/347/234/201/347/277/273/345/205/263_/344/277/256/345/244/215/350/256/260/345/275/225_v1.0.md +0 -458
  575. package/docs/eval//346/200/247/350/203/275/344/270/223/351/241/271_/345/206/267/346/237/245/350/257/242/344/270/216/345/206/205/345/255/230_v1.0.md +0 -218
  576. package/docs/eval//346/225/205/351/232/234/346/263/250/345/205/245/345/256/236/346/265/213_v1.0.md +0 -432
  577. package/docs/eval//346/250/252/350/257/204_/345/205/255/345/256/266100/351/242/230/344/270/255/350/213/261/345/217/214/346/237/245_v1.0.md +0 -223
  578. package/docs/eval//347/224/250/346/210/267/350/243/201/345/206/263/345/244/204/347/275/256_/347/254/254/344/270/200/346/211/271_v1.0.md +0 -195
  579. package/docs/eval//347/224/250/346/210/267/350/243/201/345/206/263/345/244/204/347/275/256_/347/254/254/344/272/214/346/211/271B6_/346/234/254/346/234/272/350/267/257/345/276/204/347/233/270/345/257/271/345/214/226_v1.0.md +0 -78
  580. package/docs/eval//347/253/257/345/210/260/347/253/257LoCoMoQA/345/220/214/345/217/243/345/276/204/345/257/271/347/205/247_v1.0.md +0 -100
  581. package/docs/eval//347/253/257/345/210/260/347/253/257/345/271/262/346/211/260/346/261/240/350/257/204/346/265/213_/347/241/256/345/256/232/346/200/247/350/243/201/345/206/263vsLLM_judge_v1.1.md +0 -197
  582. package/docs/eval//347/254/2543/345/261/202stg/347/273/223/346/236/204/347/264/242/345/274/225_/345/256/236/346/226/275/350/256/260/345/275/225_v1.0.md +0 -250
  583. package/docs/eval//347/254/254/344/270/211/346/226/271/351/252/214/350/257/201/346/212/245/345/221/212_LoCoMo_/347/201/265/346/236/242_.png +0 -0
  584. package/docs/eval//347/254/254/344/270/211/346/226/271/351/252/214/350/257/201/346/212/245/345/221/212_/347/201/265/346/236/242_vs_dejavu_/347/273/237/344/270/200/350/257/204/345/210/206_v7.md +0 -202
  585. package/docs/eval//347/274/226/347/240/201/351/235/242/345/211/215/347/275/256_/345/205/245/345/217/243/350/207/252/344/277/235/350/257/201UTF8/344/270/216/346/226/207/346/234/254open/345/256/210/345/215/253_v1.0.md +0 -646
  586. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v1.md +0 -156
  587. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v10.md +0 -210
  588. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v11.md +0 -227
  589. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v12.md +0 -203
  590. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v13.md +0 -233
  591. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v14.md +0 -191
  592. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v15.md +0 -213
  593. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v16.md +0 -214
  594. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v17.md +0 -199
  595. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v18.md +0 -183
  596. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v19.md +0 -207
  597. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v2.md +0 -156
  598. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v20.md +0 -283
  599. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v21.md +0 -224
  600. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v22.md +0 -223
  601. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v23.md +0 -293
  602. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v24.md +0 -303
  603. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v25.md +0 -230
  604. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v26.md +0 -196
  605. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v27.md +0 -259
  606. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v28.md +0 -217
  607. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v29.md +0 -270
  608. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v3.md +0 -152
  609. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v30.md +0 -231
  610. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v31.md +0 -281
  611. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v4.md +0 -128
  612. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v5.md +0 -114
  613. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v6.md +0 -192
  614. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v7.md +0 -187
  615. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v8.md +0 -207
  616. package/docs/eval//347/274/272/351/231/267/346/214/226/346/216/230_/350/207/252/344/270/273/350/277/255/344/273/243_v9.md +0 -203
  617. package/docs/eval//350/257/255/344/271/211/346/227/266/347/251/272/345/233/276/350/241/245/345/205/250_P1_/346/212/275/345/217/226/345/231/250v4_/344/270/211/347/216/207/350/257/273/346/225/260_v1.0.md +0 -231
  618. package/docs/eval//351/262/270/345/250/230/344/270/203/347/261/273/347/212/266/346/200/201/350/277/275/350/270/252_v1.0.md +0 -176
  619. package/docs/hive//344/270/273/344/273/243/347/220/206/345/255/220/344/273/243/347/220/206/350/256/260/345/277/206/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -385
  620. package/docs/hive//344/273/244/347/211/214/344/270/216/350/247/222/350/211/262/346/235/203/350/201/214/345/210/206/347/246/273_v0.1.md +0 -165
  621. package/docs/hive//344/273/244/347/211/214/350/257/255/344/271/211/344/277/256/346/255/243_/344/273/262/350/243/201/344/275/215_v0.1.md +0 -76
  622. package/docs/hive//345/244/232/347/253/257harness/351/200/232/344/277/241/345/245/221/347/272/246_v0.1.md +0 -42
  623. package/docs/hive//345/255/220/344/273/243/347/220/206/351/205/215/347/275/256/346/240/207/345/207/206_v0.5.md +0 -236
  624. package/docs/hive//345/256/211/345/205/250/345/256/241/350/256/241/345/256/236/351/224/232_v0.1.md +0 -202
  625. package/docs/hive//346/243/200/347/264/242/346/224/266/346/225/233/345/256/236/346/265/213/344/270/216S1b/350/256/276/350/256/241_v0.1.md +0 -43
  626. package/docs/hive//346/243/200/347/264/242/347/256/227/346/263/225/345/217/243/345/276/204/345/257/271/347/205/247_v0.1.md +0 -210
  627. package/docs/hive//346/243/200/347/264/242/350/267/257/345/276/204/344/270/216/350/256/244/347/237/245/347/273/223/346/236/204/345/245/221/347/272/246_v0.1.md +0 -152
  628. package/docs/hive//350/234/202/345/267/242M6_ingest/345/256/236/346/226/275/350/256/241/345/210/222_v0.1.md +0 -47
  629. package/docs/hive//350/234/202/345/267/242/345/217/214/345/256/236/344/276/213/344/272/222/351/252/214_/350/256/276/350/256/241/345/256/232/347/250/277.md +0 -519
  630. package/docs/hive//350/234/202/345/267/242/345/267/245/344/275/234/350/256/260/345/277/206_/351/241/271/347/233/256/350/256/241/345/210/222.md +0 -85
  631. package/docs/hive//350/234/202/345/267/242/350/256/276/350/256/241_/347/220/206/350/256/272/345/257/271/351/275/220_v0.1.md +0 -191
  632. package/docs/hive//350/234/202/345/267/242/350/277/255/344/273/243_/345/256/217/350/247/202/344/270/216/347/276/244/344/275/223/350/260/203/345/272/246_v0.1.md +0 -90
  633. package/docs/images/lingshu-moonlight-covenant-poster-preview.jpg +0 -0
  634. package/docs/images/lingshu-moonlight-covenant-poster.png +0 -0
  635. package/docs/mdcg/D_meta_/345/267/245/347/250/213/345/214/226/346/226/271/346/241/210_v0.2.md +0 -216
  636. package/docs/mdcg/README/350/257/246/347/273/206/347/211/210_v0.4.10.md +0 -746
  637. package/docs/mdcg/guardrail-charter.md +0 -164
  638. package/docs/mdcg/lingshu_tutorial.html +0 -14956
  639. package/docs/mdcg/memory-assessment.html +0 -923
  640. package/docs/mdcg/memory_score.html +0 -213
  641. package/docs/mdcg/memory_score.png +0 -0
  642. package/docs/mdcg/release_v0.3.0.md +0 -36
  643. package/docs/mdcg/release_v0.4.11.md +0 -49
  644. package/docs/mdcg/release_v0.4.5.md +0 -55
  645. package/docs/mdcg/tool_table_v0.3.0.md +0 -117
  646. package/docs/mdcg//344/270/226/347/225/214/346/250/241/345/236/213/345/212/237/350/203/275/347/253/257_/344/275/277/347/224/250/344/270/216/350/277/220/347/273/264_v1.0.md +0 -384
  647. package/docs/mdcg//344/273/243/347/240/201/350/257/204/345/256/241/344/270/216/346/235/241/344/273/266/345/214/226/346/263/250/351/207/212_/345/245/221/347/272/246_v0.1.md +0 -82
  648. package/docs/mdcg//345/205/250/345/272/223/344/273/243/347/240/201/350/257/204/345/256/241/344/270/216/346/235/241/344/273/266/345/214/226/346/263/250/351/207/212_/350/256/241/345/210/222_v0.1.md +0 -600
  649. package/docs/mdcg//345/212/237/350/203/275/350/260/203/347/224/250/346/230/240/345/260/204/350/241/250_v0.1.md +0 -266
  650. package/docs/mdcg//345/215/225/345/205/203/350/207/252/346/210/221/351/224/232/347/202/271_/347/263/273/347/273/237/346/217/220/347/244/272/350/257/215/346/240/207/345/207/206_v0.3.md +0 -275
  651. package/docs/mdcg//345/217/221/345/270/203/351/227/250/347/246/201/351/223/276_v0.1.md +0 -134
  652. package/docs/mdcg//346/272/220/347/240/201/347/272/247/346/236/266/346/236/204/345/256/241/350/256/241_GPT/346/211/271/350/257/204/345/257/271/347/205/247_v1.0.md +0 -130
  653. package/docs/mdcg//347/201/265/346/236/24282/345/267/245/345/205/267_/345/212/237/350/203/275/346/225/264/347/220/206/344/270/216/350/277/201/347/247/273/346/230/240/345/260/204_v0.1.md +0 -278
  654. package/docs/mdcg//347/201/265/346/236/242MCP/345/267/245/345/205/267/346/200/273/350/241/250_v3.4.md +0 -164
  655. package/docs/mdcg//347/201/265/346/236/242_/350/207/252/346/210/221/345/261/202/345/256/232/344/271/211.md +0 -43
  656. package/docs/mdcg//347/201/265/346/236/242/344/270/211/345/261/202/346/213/206/345/210/206/350/247/204/345/210/222_v0.1.md +0 -181
  657. package/docs/mdcg//347/201/265/346/236/242/350/256/260/345/277/206/345/212/250/350/257/215/345/215/217/350/256/256_v1.0-draft.md +0 -177
  658. package/docs/mdcg//347/216/257/344/272/214_/347/231/275/347/256/261/345/241/253/345/205/205/346/265/201/346/260/264/347/272/277_v0.1.md +0 -31
  659. package/docs/mdcg//347/235/241/347/234/240/345/221/250/346/234/237_/350/277/220/347/273/264/345/211/215/346/217/220/344/270/216/347/273/264/346/212/244/346/214/207/345/215/227_v1.0.md +0 -337
  660. package/docs/mdcg//347/274/272/345/217/243/345/215/225_P0/346/224/266/345/217/243_v0.1.md +0 -270
  661. package/docs/mdcg//350/256/244/347/237/245/345/233/276_G4-G8/347/274/272/345/217/243/350/243/201/345/256/232/345/215/225_v0.1.md +0 -491
  662. package/docs/mdcg//350/256/244/347/237/245/345/233/276_MD/347/233/256/345/275/225/346/226/271/346/241/210_v0.1.md +0 -552
  663. package/docs/mdcg//350/256/244/347/237/245/345/233/276_/346/235/241/344/273/266/347/251/272/351/227/264/345/220/210/346/210/220/344/270/216/347/224/237/346/225/210/346/235/241/344/273/266/345/217/243/345/276/204_v0.1.md +0 -340
  664. package/docs/mdcg//350/256/244/347/237/245/345/233/276_/347/264/242/345/274/225/344/270/216/345/267/245/347/250/213/350/247/204/350/214/203/345/214/226_/350/256/241/345/210/222_v0.1.md +0 -624
  665. package/docs/mdcg//350/256/244/347/237/245/345/233/276/344/275/234/344/270/272/350/256/260/345/277/206/346/223/215/344/275/234/347/263/273/347/273/237_/350/257/204/344/274/260/344/270/216/350/267/257/347/272/277_v0.1.md +0 -94
  666. package/docs/mdcg//350/256/260/345/277/206/346/223/215/344/275/234/347/263/273/347/273/237_MdCGOS/344/270/216MCP/346/216/245/345/205/245_v0.1.md +0 -281
  667. package/docs/mdcg//350/267/250/347/253/257/351/252/214/350/257/201/344/270/216/345/220/214/346/255/245/345/215/217/350/256/256_v0.1.md +0 -93
  668. package/docs/plans/GridWorld/346/234/200/345/260/217/351/227/255/347/216/257/350/247/204/346/240/274_v0.1.md +0 -176
  669. package/docs/plans/stg/346/235/241/344/273/266/345/214/226/344/270/216/347/273/223/346/236/204/347/264/242/345/274/225_/350/256/276/350/256/241_v0.1.md +0 -124
  670. package/docs/plans//345/205/250/344/270/255/346/226/207/347/274/226/347/240/201/344/270/216/350/234/202/345/267/242/344/273/273/345/212/241/346/240/207/350/257/206/345/245/221/347/272/246_v2.0.md +0 -220
  671. package/docs/plans//345/221/275/345/220/215/346/262/273/347/220/206_/351/241/271/347/233/256/350/256/241/345/210/222.md +0 -81
  672. package/docs/plans//345/244/232/344/270/273/344/275/223/344/270/226/347/225/214/346/250/241/345/236/213_/345/257/271/351/275/220/350/257/204/344/274/260/344/270/216/350/220/275/345/234/260/350/256/276/350/256/241_v0.1.md +0 -141
  673. package/docs/plans//347/201/265/346/236/242/350/272/253/344/275/223/303/227/350/204/221_/344/270/226/347/225/214/346/250/241/345/236/213/345/257/271/346/216/245/350/256/276/350/256/241_v0.1.md +0 -119
  674. package/docs/plans//347/234/237/346/272/220/347/264/242/345/274/225_/351/200/232/347/224/250/346/234/272/345/210/266_v0.3.md +0 -227
  675. package/docs/plans//347/235/241/347/234/240/344/270/216/350/207/252/350/277/255/344/273/243_/345/212/237/350/203/275/344/274/230/345/214/226/350/256/276/350/256/241_v0.4.md +0 -547
  676. package/docs/plans//347/237/245/350/257/206/345/233/276/350/260/261/351/241/271/347/233/256_/344/272/244/346/216/245/346/226/207/346/241/243_20260914.md +0 -308
  677. package/docs/plans//350/234/202/345/267/242/346/250/241/345/236/213/345/257/206/351/222/245/351/205/215/347/275/256/351/235/242_v1.0.md +0 -385
  678. package/docs/plans//350/256/260/345/277/206/350/207/252/345/244/204/347/220/206/344/270/211/346/241/243/350/207/252/346/262/273_/350/256/276/350/256/241_v0.2.md +0 -207
  679. package/docs/plans//350/257/255/344/271/211/346/227/266/347/251/272/345/233/276/350/241/245/345/205/250_/344/270/226/347/225/214/346/250/241/345/236/213/345/212/237/350/203/275/347/253/257_/350/256/276/350/256/241_v0.1.md +0 -107
  680. package/docs/promo/bilibili-cover.jpg +0 -0
  681. package/docs/promo/promo-visual-1.png +0 -0
  682. package/docs/promo/promo-visual-2.png +0 -0
  683. package/docs/promo/promo-visual-3.png +0 -0
  684. package/docs/promo/promo-visual-4.png +0 -0
  685. package/docs/promo/promo-visual-5.png +0 -0
  686. package/docs/swarm//350/234/202/347/276/244/344/272/222/350/201/224_v0.1.md +0 -704
  687. package/docs/swarm//350/234/202/347/276/244/345/220/214/351/224/231/346/243/200/346/265/213/345/256/236/351/252/214/345/215/217/350/256/256_v0.1.md +0 -242
  688. package/docs/swarm//350/234/202/347/276/244/345/244/232/346/231/272/350/203/275/344/275/223_/344/275/277/347/224/250/346/212/245/345/221/212_20260913.md +0 -68
  689. package/docs/swarm//350/234/202/347/276/244/345/244/232/346/231/272/350/203/275/344/275/223_/345/212/237/350/203/275/350/257/264/346/230/216_v0.6.md +0 -130
  690. package/docs/swarm//350/234/202/347/276/244/347/233/262/345/214/272/346/240/207/350/256/260_v1.0.md +0 -89
  691. package/docs/theory//344/270/215/345/217/257/351/235/240/345/256/232/347/220/206/344/270/216/345/244/261/346/225/210/344/274/230/345/205/210/346/241/206/346/236/266_v0.3.md +0 -365
  692. package/docs/theory//344/277/241/346/201/257/345/267/256/344/270/272/344/273/200/344/271/210/345/277/205/347/204/266/345/255/230/345/234/250/344/270/224/350/207/252/347/204/266/346/211/251/345/244/247.md +0 -239
  693. package/docs/theory//345/215/225/347/272/277/347/250/213/344/270/216/346/263/250/346/204/217/345/212/233/351/233/206/344/270/255_/346/227/240/344/272/211/350/256/256/347/220/206/350/256/272/346/226/207/346/241/243_v1.0.md +0 -129
  694. package/docs/theory//345/271/266/345/217/221/345/277/205/347/204/266/346/200/247/347/220/206/350/256/272_v0.2.md +0 -134
  695. package/docs/theory//346/231/272/350/203/275/347/232/204/345/205/254/347/220/206/345/214/226/345/237/272/347/237/263.md +0 -789
  696. package/docs/theory//346/231/272/350/203/275/347/232/204/350/256/244/347/237/245/350/277/207/347/250/213.md +0 -379
  697. package/docs/theory//346/231/272/350/203/275/350/256/2723.4.md +0 -5260
  698. package/docs/theory//346/246/202/345/277/265/345/210/206/345/261/202/345/257/271/351/275/220/350/241/250_v0.1.md +0 -145
  699. package/docs/theory//347/220/206/350/256/272_/346/234/272/345/210/266_/344/273/243/347/240/201_/345/256/236/351/252/214_/347/274/272/345/217/243/347/237/251/351/230/265_v0.1.md +0 -144
  700. package/docs/theory//347/220/206/350/256/272/344/273/223/346/213/206/345/210/206/344/270/216/347/231/275/347/256/261/347/237/245/350/257/206/345/272/223/345/206/205/350/277/201_v0.1.md +0 -198
  701. package/docs/theory//347/231/275/347/256/261/346/231/272/350/203/275/346/230/257/344/273/200/344/271/210/357/274/237.md +0 -812
  702. package/docs/theory//347/231/275/347/256/261/346/231/272/350/203/275/347/263/273/345/210/227/302/267/347/254/254/344/272/224/347/257/207/357/274/232/350/256/251AI/347/234/237/346/255/243/350/243/205/344/270/212/350/256/260/345/277/206.md +0 -421
  703. package/docs/theory//350/256/244/347/237/245/344/273/243/347/220/206/344/270/216/346/224/266/346/225/233/347/273/223/346/236/204_/346/235/241/344/273/266/350/256/272/351/207/215/346/236/204_v0.1.md +0 -221
  704. package/docs/world_model//344/270/226/347/225/214/346/250/241/345/236/213_/347/245/236/347/273/217/347/275/221/347/273/234/345/272/225/345/261/202/346/236/266/346/236/204_v1.0.md +0 -237
  705. package/docs//344/270/215/345/217/257/351/235/240/346/200/247/347/220/206/350/256/272_v0.1.md +0 -343
  706. package/docs//345/217/221/345/270/203/344/273/266/345/233/236/346/272/257/350/257/264/346/230/216_v0.1.md +0 -82
  707. package/docs//345/255/230/347/256/227/344/270/200/344/275/223/346/236/266/346/236/204/345/255/246/344/271/240_/345/244/226/351/203/250/347/220/206/350/256/272/345/257/271/347/205/247/344/270/216/350/267/257/347/272/277/344/272/244/346/216/245_20260916.md +0 -98
  708. package/docs//345/255/230/347/256/227/344/270/200/344/275/223/347/245/236/347/273/217/347/275/221/347/273/234/346/236/266/346/236/204_/346/200/273/347/272/262/344/270/216/344/272/244/346/216/245_20260916.md +0 -109
  709. package/docs//347/201/265/346/236/242/350/207/252/346/210/221/346/224/271/350/277/233/345/267/245/344/275/234/350/256/241/345/210/222_/345/244/226/351/203/250/347/240/224/347/251/266/347/263/273/345/210/227/345/220/270/346/224/266_v1_20260919.md +0 -286
  710. package/docs//347/231/275/347/256/261/345/214/226/347/272/262/351/242/206_/344/270/211/351/241/271/347/233/256/345/255/246/344/271/240/346/200/273/346/236/266/346/236/204/344/270/216Ghidra/344/272/244/346/216/245_20260916.md +0 -104
  711. package/docs//347/247/244_/350/256/260/345/277/206/347/263/273/347/273/237/350/257/204/346/265/213/350/247/204/350/214/203_v2.1.md +0 -225
  712. package/docs//350/256/260/345/277/206/347/263/273/347/273/237/345/215/263/347/231/275/347/256/261/345/214/226/346/231/272/350/203/275_/346/236/266/346/236/204/345/257/271/347/205/247_v0.2.md +0 -121
  713. package/docs//350/256/260/345/277/206/347/263/273/347/273/237/345/215/263/347/231/275/347/256/261/345/214/226/346/231/272/350/203/275_/346/236/266/346/236/204/345/257/271/347/205/247_v0.3.md +0 -117
  714. package/docs//350/256/260/345/277/206/350/257/204/345/256/241/347/263/273/347/273/237_/347/253/213/351/241/271/350/256/276/350/256/241/344/270/216/346/226/275/345/267/245/344/272/244/346/216/245_20260915.md +0 -183
package/md_cg/subgraph.py CHANGED
@@ -1,729 +1,851 @@
1
- # -*- coding: utf-8 -*-
2
- """嵌套子图(nested subgraph):结构要素的可递归表示 + flatten。
3
-
4
- 对齐 AEIS《认知图写入纪律 v1.0》四要素中的第三项:
5
- subgraph = 内部子内容(可嵌套:子节点 + 边),角色=结构(可检索/可递归)。
6
-
7
- 与 AEIS 的两处**有意差异**(都有工程理由,不是简化):
8
-
9
- 1) 存储形态:AEIS 把子节点**内联**在父节点 `subgraph.nodes` 里
10
- (`aeis/image_semantics_cg.py:37-57`)。md_cg 的检索粒度是「节点 = 文件」
11
- (RRF 按节点召回),内联子节点无法被任何检索路单独命中,会违背「子图可检索」
12
- 这一规范本身。故 md_cg 采用**引用式**:`subgraph.nodes` 存子节点 id,
13
- 子节点各自是独立 `.md`,可被 lexical/entity/chain 等路独立召回。
14
- 同时兼容内联写法(`{"id": ...}` 对象)以承接 AEIS 语料。
15
-
16
- 2) 递归深度:AEIS 明确「深度上限不是协议常数,数据驱动,= 可分性条件的自然耗尽」
17
- (`子部件提取_理论稿_v0.4.md:146-150`)。故 `max_depth=None` 表示一直展开到
18
- 自然耗尽(无子节点);`max_depth=k` 只是工程硬截断,会置 `truncated=True`。
19
-
20
- 父边唯一(每个节点至多一个 `part_of` 父)——`子部件提取_理论稿_v0.4.md:105`;
21
- 违反者由 `validate()` 报 `multi_parent`,对齐「树形不一致 → 退回 DEFER」。
22
- """
23
- from __future__ import annotations
24
-
25
- import hashlib
26
- import os
27
- import re
28
- import time
29
-
30
- from .fsutil import append_jsonl
31
-
32
- MAX_DEPTH_HARD = 64 # 工程硬截断上限(防止畸形数据把遍历拖爆)
33
- MAX_NODES_DEFAULT = 2000 # 单次展开的节点上限
34
-
35
- # ---- 模式分离(maintain.separate)参数 -----------------------------------
36
- MAINTAIN_LOG = "_maintain.jsonl"
37
- SEP_MIN_JACCARD = 0.55 # 内容相似度下限(越高=越像,才值得谈分离)
38
- SEP_MAX_COND_OVERLAP = 0.35 # 条件重合上限(越高=条件越同,就该合并而非分离)
39
- SEP_MAX_NODES = 400 # 单次扫描节点上限(防 O(N²) 读盘爆炸)
40
- SEP_MAX_PAIRS = 50 # 单次返回/落库的候选对上限
41
-
42
-
43
- # 生效条件:fm 为假值或 fm.get("subgraph") 取值为假(None/[]/{}/空串)时直接返回 {'nodes': [], 'edges': []};subgraph 为 list/tuple 时其元素作节点、边记空列表,为 dict 时节点取 sg.get("nodes")(缺键或假值回落 [])、边取 sg.get("edges")(同样回落),为其他类型仍返回空;节点项为 dict 时取 n.get("id")、否则取元素本身,nid 为 None 跳过,仅当 str(nid).strip() 非空且未出现过才追加;边只保留 isinstance(e, dict) 的项;
44
- def declared(fm):
45
- """规范化 `frontmatter.subgraph` → `{"nodes": [id...], "edges": [edge...]}`。
46
-
47
- 兼容三种写法:
48
- {"nodes": ["a", "b"], "edges": [...]} 引用式(md_cg 主用)
49
- ["a", "b"] 纯 id 列表
50
- {"nodes": [{"id": "a"}, ...]} 内联式(AEIS 原样,只取 id)
51
- """
52
- sg = (fm or {}).get("subgraph")
53
- if not sg:
54
- return {"nodes": [], "edges": []}
55
- if isinstance(sg, (list, tuple)):
56
- raw_nodes, raw_edges = list(sg), []
57
- elif isinstance(sg, dict):
58
- raw_nodes, raw_edges = list(sg.get("nodes") or []), list(sg.get("edges") or [])
59
- else:
60
- return {"nodes": [], "edges": []}
61
- nodes = []
62
- for n in raw_nodes:
63
- nid = n.get("id") if isinstance(n, dict) else n
64
- if nid is None:
65
- continue
66
- nid = str(nid).strip()
67
- if nid and nid not in nodes:
68
- nodes.append(nid)
69
- return {"nodes": nodes, "edges": [e for e in raw_edges if isinstance(e, dict)]}
70
-
71
-
72
- # 生效条件:当 getattr(cg,"index",None) 的 nodes 字典中存在 nid(entry 非 None)且 "subgraph" in entry 时,返回 {'id': nid, 'subgraph': entry.get("subgraph"), 'edges': entry.get("edges") or []}(subgraph 值为 None 也照样返回);否则改走 cg.get(nid),返回 (node or {}).get("frontmatter") or {},节点不存在或 frontmatter 为假值时得空 dict;
73
- def _fm(cg, nid):
74
- """取节点 frontmatter:优先索引快照(免 IO),快照缺字段时回退读文件。"""
75
- entry = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid)
76
- if entry is not None and "subgraph" in entry:
77
- return {"id": nid, "subgraph": entry.get("subgraph"),
78
- "edges": entry.get("edges") or []}
79
- node = cg.get(nid)
80
- return (node or {}).get("frontmatter") or {}
81
-
82
-
83
- # --------------------------------------------------------------------------
84
- # 迁移边适配:源 sqlite 认知图 → md_cg 本地边
85
- # --------------------------------------------------------------------------
86
- # 源库的 `hierarchical` 方向是 **source=父、target=子**(白箱
87
- # `wisdom-book-cloud.db` 全量实测:`source_is_parent=2832`、`target_is_parent=0`)。
88
- # md_cg 的父边约定与其**相反**:`part_of` 表示「本节点是子、target 是父」
89
- # (见下方 children_index)。若把源库 hierarchical 原样搬进来,树会整体倒置;
90
- # 故迁移时翻译成语义等价的 `contains`(本节点是父、target 是子)。
91
- SRC_REL_MAP = {"hierarchical": "contains"}
92
-
93
-
94
- # 生效条件:rel 先经 str(rel or "").strip().lower() 归一(None/空串得 ""),返回 {'target': str(tgt), 'relation_type': SRC_REL_MAP.get(rel, rel), 'confidence': confidence, 'verified': verified}——归一后的 rel 命中模块常量 SRC_REL_MAP 时用映射值、未命中(含 rel 为空串)时原样保留,confidence/verified 直接透传默认 1.0/0 的实参不做校验;
95
- def normalize_edge(tgt, rel, confidence=1.0, verified=0):
96
- """源库边 → md_cg 本地边(迁移器专用)。做两件事:
97
-
98
- 1) 键名统一为 `relation_type`。`children_index` / `parents_index` 只认
99
- `relation_type` / `relation`;早期迁移器写的 `"type"` 会被静默忽略
100
- (`chain.edge_rel` 兼容 `type`,但 `subgraph` 不兼容),使迁入的图不可遍历。
101
- 2) 方向按 `SRC_REL_MAP` 翻译(源库 hierarchical = source 是父)。
102
- """
103
- rel = str(rel or "").strip().lower()
104
- return {"target": str(tgt), "relation_type": SRC_REL_MAP.get(rel, rel),
105
- "confidence": confidence, "verified": verified}
106
-
107
-
108
- # 生效条件:cg 的 `_subgraph_children` 不为 None 时原样返回该缓存字典,否则遍历 cg.index["nodes"] 的键,用 declared(fm)["nodes"] 收子节点、并按边 rel 为 part_of/hierarchical(target 记为父、当前 pid 记为子)或 parent_of/contains(当前 pid 记为父、target 记为子,target 为 None 则该边跳过)补全 parent_id→[child_id] 索引,回写 cg._subgraph_children 后返回 idx;
109
- def children_index(cg):
110
- """全局正查:parent_id → [child_id...](声明式 ∪ 边式,一次 O(N) 后缓存)。"""
111
- idx = getattr(cg, "_subgraph_children", None)
112
- if idx is not None:
113
- return idx
114
- idx = {}
115
- for pid in list(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys()):
116
- fm = _fm(cg, pid)
117
- for ch in declared(fm)["nodes"]:
118
- idx.setdefault(pid, [])
119
- if ch not in idx[pid]:
120
- idx[pid].append(ch)
121
- for e in (fm.get("edges") or []):
122
- if not isinstance(e, dict):
123
- continue
124
- # 兼容历史语料:早期迁移器把关系类型写在 `type` 键(`migrate.py:43`、
125
- # `migrate_aeis.py:99`),写侧已按 `normalize_edge` 修正,读侧一并容错。
126
- rel = str(e.get("relation_type") or e.get("relation") or e.get("type")
127
- or "").strip().lower()
128
- tgt = e.get("target") or e.get("target_id")
129
- if tgt is None:
130
- continue
131
- tgt = str(tgt).strip()
132
- if rel in ("part_of", "hierarchical"): # 本节点是子,target 是父
133
- idx.setdefault(tgt, [])
134
- if pid not in idx[tgt]:
135
- idx[tgt].append(pid)
136
- elif rel in ("parent_of", "contains"): # 本节点是父,target 是子
137
- idx.setdefault(pid, [])
138
- if tgt not in idx[pid]:
139
- idx[pid].append(tgt)
140
- try:
141
- cg._subgraph_children = idx
142
- except Exception:
143
- pass
144
- return idx
145
-
146
-
147
- # 生效条件:返回 list(children_index(cg).get(nid) or []),即 nid 在索引中无键或对应值为空(None/空列表)时得空列表,否则返回其子 id 的浅拷贝列表;
148
- def children(cg, nid):
149
- """直接子节点 id 列表:`subgraph.nodes` 声明 ∪ 边式父子关系。"""
150
- return list(children_index(cg).get(nid) or [])
151
-
152
-
153
- # 生效条件:cg 的 `_subgraph_parents` 不为 None 时原样返回该缓存字典,否则遍历 cg.index["nodes"] 的键,用 declared(fm)["nodes"] 把 pid 记为每个子节点的父、并按边 rel 为 part_of/hierarchical(target 记为 pid 的父)或 parent_of/contains(pid 记为 target 的父,target 为 None 则该边跳过)补全 child_id→[parent_id] 索引,回写 cg._subgraph_parents 后返回 idx;
154
- def parents_index(cg):
155
- """全局反查:child_id → [parent_id...](供 children/validate 复用,一次 O(N))。"""
156
- idx = getattr(cg, "_subgraph_parents", None)
157
- if idx is not None:
158
- return idx
159
- idx = {}
160
- for pid in list(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys()):
161
- for ch in declared(_fm(cg, pid))["nodes"]:
162
- idx.setdefault(ch, [])
163
- if pid not in idx[ch]:
164
- idx[ch].append(pid)
165
- for e in (_fm(cg, pid).get("edges") or []):
166
- if not isinstance(e, dict):
167
- continue
168
- rel = str(e.get("relation_type") or e.get("relation") or e.get("type")
169
- or "").strip().lower()
170
- tgt = e.get("target") or e.get("target_id")
171
- if tgt is None:
172
- continue
173
- tgt = str(tgt).strip()
174
- # 与 children_index 逐字对称,只是方向取反:
175
- # part_of / hierarchical → 本节点是子,故 target 是本节点的父
176
- # parent_of / contains → 本节点是父,故本节点是 target 的父
177
- if rel in ("part_of", "hierarchical"):
178
- idx.setdefault(pid, [])
179
- if tgt not in idx[pid]:
180
- idx[pid].append(tgt)
181
- elif rel in ("parent_of", "contains"):
182
- idx.setdefault(tgt, [])
183
- if pid not in idx[tgt]:
184
- idx[tgt].append(pid)
185
- try:
186
- cg._subgraph_parents = idx
187
- except Exception:
188
- pass
189
- return idx
190
-
191
-
192
- # 生效条件:无条件执行——把 cg 的 _subgraph_parents 与 _subgraph_children 依次 setattr 为 None(setattr 抛异常被 except 吞掉后继续下一个),无返回值,与 cg 是否已建有缓存无关;
193
- def invalidate_cache(cg):
194
- """写入/删除节点后调用,丢弃父子正查/反查缓存。"""
195
- for attr in ("_subgraph_parents", "_subgraph_children"):
196
- try:
197
- setattr(cg, attr, None)
198
- except Exception:
199
- pass
200
-
201
-
202
- # 生效条件:取 parents_index(cg).get(nid) or [],列表非空时返回其首元素,键缺失或值为空/假(None、[])时返回 None;多父时只返回第一个,不在此处报歧义;
203
- def parent_of(cg, nid):
204
- """唯一父(多父时返回第一个并置 `ambiguous` 标记由 validate 报出)。"""
205
- ps = parents_index(cg).get(nid) or []
206
- return ps[0] if ps else None
207
-
208
-
209
- # 生效条件:max_depth 非 None 时先 max(0, min(int(max_depth), MAX_DEPTH_HARD)) 收敛;以 nid 为根迭代 DFS,已入 seen 的节点跳过,len(seen) >= max_nodes(max_nodes 传 0 时首次循环即成立)置 truncated=True 并 break,depth >= max_depth 且 children 非空时置 truncated=True 并 continue,否则对 children(cg,cur) 逆序、对未出现过的 (ch,cur) 追加 part_of 边并压栈;返回 {'root','nodes','paths','edges','n_nodes','n_edges','truncated'};
210
- def expand(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
211
- """递归展开子树(迭代 DFS,防递归深度爆栈)。
212
-
213
- 返回 `{"root","nodes","paths","edges","n_nodes","n_edges","truncated"}`;
214
- `paths` 为 `节点 id → "根/子/孙"` 层级路径(flatten 后仍可定位来源)。
215
- 边为 `part_of(child→parent)`,与 AEIS flatten 的方向一致。
216
- """
217
- if max_depth is not None:
218
- max_depth = max(0, min(int(max_depth), MAX_DEPTH_HARD))
219
- seen, edges, truncated = {}, [], False
220
- seen_edges = set()
221
- stack = [(nid, 0, nid)]
222
- while stack:
223
- cur, depth, path = stack.pop()
224
- if cur in seen:
225
- continue
226
- if len(seen) >= max_nodes:
227
- truncated = True
228
- break
229
- seen[cur] = path
230
- if max_depth is not None and depth >= max_depth:
231
- if children(cg, cur):
232
- truncated = True
233
- continue
234
- kids = children(cg, cur)
235
- for ch in reversed(kids):
236
- key = (ch, cur)
237
- if key not in seen_edges:
238
- seen_edges.add(key)
239
- edges.append({"source": ch, "target": cur,
240
- "relation_type": "part_of",
241
- "confidence": 1.0, "verified": 0})
242
- if ch not in seen:
243
- stack.append((ch, depth + 1, f"{path}/{ch}"))
244
- return {"root": nid, "nodes": list(seen.keys()), "paths": seen,
245
- "edges": edges, "n_nodes": len(seen), "n_edges": len(edges),
246
- "truncated": truncated}
247
-
248
-
249
- # 生效条件:先调用 expand(cg, nid, max_depth=max_depth, max_nodes=max_nodes),对其中每条边复制一份并追加 source/target 互换、relation_type="parent_of"、confidence/verified 沿用原边 .get(…,1.0/0) 的反向边;返回 root=nid、nodes=ex["nodes"]、paths=ex["paths"]、n_nodes=ex["n_nodes"]、n_edges=双边后条数、truncated=ex["truncated"];
250
- def flatten(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
251
- """把嵌套子图摊平成「节点 + 边」,父子生成**对称双边**。
252
-
253
- 对齐 AEIS `flatten_image_semantics_graph`(`image_semantics_cg.py:151-173`):
254
- 每个有父的节点同时产出 `part_of(child→parent)` 与 `parent_of(parent→child)`。
255
- 检索侧因此既能「从父找子」(下钻),也能「从子找父」(溯源)。
256
- """
257
- ex = expand(cg, nid, max_depth=max_depth, max_nodes=max_nodes)
258
- edges = []
259
- for e in ex["edges"]:
260
- edges.append(dict(e))
261
- edges.append({"source": e["target"], "target": e["source"],
262
- "relation_type": "parent_of",
263
- "confidence": e.get("confidence", 1.0),
264
- "verified": e.get("verified", 0)})
265
- return {"root": nid, "nodes": ex["nodes"], "edges": edges, "paths": ex["paths"],
266
- "n_nodes": ex["n_nodes"], "n_edges": len(edges),
267
- "truncated": ex["truncated"]}
268
-
269
-
270
- # 生效条件:known 取 cg.index 的 nodes 键集合,仅当 parents_index(cg).get(nid) or [] 为空(键缺失或空列表)的 nid 才视为树根,返回其排序后的 id 列表;
271
- def roots(cg):
272
- """无父节点(树根)的 id 列表。"""
273
- known = set(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys())
274
- pmap = parents_index(cg)
275
- return sorted(nid for nid in known if not (pmap.get(nid) or []))
276
-
277
-
278
- # 生效条件:known 取 cg.index 的 nodes 键列表,max_scan 为真值时截断为 known[:int(max_scan)];逐 pid 遍历 declared(_fm(cg,pid))["nodes"]:ch==pid 记 self_loop 并 continue(不再进入悬空/多父判断),ch 不在 known_set 记 dangling_child,随后 parent 中已有 ch 且 prev != pid 记 multi_parent、否则写 parent[ch]=pid;再沿 parent 指针上溯,遇本路径已访问节点记 cycle;_issue 仅在 len(issues) < limit*4 时追加(limit 为 0 时 0<0 不成立,不追加任何 issue);返回 scanned、issues=len(issues)、items=issues[:limit]、truncated=len(issues)>limit;
279
- def validate(cg, limit=50, max_scan=None):
280
- """树一致性校验:自环 / 悬空子节点 / 多父 / 环。
281
-
282
- 对齐 AEIS:父边唯一、拓扑无矛盾、树形不一致 → 该层判定退回 DEFER
283
- (`子部件提取_理论稿_v0.4.md:105-107`)。
284
- """
285
- known = list(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys())
286
- if max_scan:
287
- known = known[:int(max_scan)]
288
- known_set = set(known)
289
- parent, issues = {}, []
290
-
291
- # 生效条件:仅当 len(issues) < limit*4 时把 kw 追加进 issues(限流防报告膨胀);无返回值,只改外层 issues;
292
- def _issue(**kw):
293
- if len(issues) < limit * 4:
294
- issues.append(kw)
295
-
296
- for pid in known:
297
- for ch in declared(_fm(cg, pid))["nodes"]:
298
- if ch == pid:
299
- _issue(id=pid, issue="self_loop", child=ch)
300
- continue
301
- if ch not in known_set:
302
- _issue(id=pid, issue="dangling_child", child=ch)
303
- prev = parent.get(ch)
304
- if prev is not None and prev != pid:
305
- _issue(id=ch, issue="multi_parent", parents=sorted({prev, pid}))
306
- else:
307
- parent[ch] = pid
308
-
309
- # 环检测:沿 parent 指针上溯,遇本路径已访问节点即成环
310
- for nid in known:
311
- path, cur = [], nid
312
- while cur is not None:
313
- if cur in path:
314
- _issue(id=cur, issue="cycle", path=path[path.index(cur):] + [cur])
315
- break
316
- path.append(cur)
317
- cur = parent.get(cur)
318
-
319
- return {"scanned": len(known), "issues": len(issues),
320
- "items": issues[:limit], "truncated": len(issues) > limit}
321
-
322
-
323
- # ==========================================================================
324
- # 模式分离(maintain.separate)
325
- # ==========================================================================
326
- #
327
- # 问题:两条记忆**内容高度相似但生效条件不同**。若放任不管,检索会把它们混为
328
- # 一体——按 A 的条件召回、却拿到 B 的结论。海马体的做法是 pattern separation:
329
- # 把相似但情境不同的表征拆开,各挂各的条件线索。
330
- #
331
- # 本层的工程兑现(保守、可逆、幂等):
332
- # · 不动正文(不制造第二份真相),只加**对称分离边** `distinct_from`;
333
- # · 边携带 reason + 判定分量,供后续重构/审计追溯;
334
- # · 条件**相同**的相似对**不是**分离候选(那是重复,该走 MERGE)。
335
-
336
- # 生效条件:cg.get(nid) 为假值(None/{})时返回 None;否则取 fm=node.get("frontmatter") or {}、content=node.get("content") or "",返回 {'grams': bigrams(forgetting.payload(content)), 'pos','neg': consistency.condition_terms(fm, content) 的结果, 'layer': fm.get("layer")}——grams 为空也照常返回该字典,不返回 None;
337
- def _node_terms_and_grams(cg, nid):
338
- """读取节点并返回 (payload 二元组, 正条件词面, 负条件词面);不可读返回 None。"""
339
- from . import consistency, forgetting
340
- from .mdcg import bigrams # 惰性导入:避开 mdcg↔subgraph 循环
341
- node = cg.get(nid)
342
- if not node:
343
- return None
344
- fm = node.get("frontmatter") or {}
345
- content = node.get("content") or ""
346
- grams = bigrams(forgetting.payload(content))
347
- pos, neg = consistency.condition_terms(fm, content)
348
- return {"grams": grams, "pos": pos, "neg": neg, "layer": fm.get("layer")}
349
-
350
-
351
- # 生效条件:pool 初取 cg.index 的 nodes 键,layer 为假值(None/"")时不按层过滤、否则只留 e.get("layer")==layer 的 nid,ids 为真值时只留 str(x) 属于该集合的 nid;pool 排序后 truncated=len(pool)>int(max_nodes)、并截为前 int(max_nodes) 个;只有 _node_terms_and_grams 返回非 None 且 grams 非空的节点进 cache;对 cache 键两两比较——无公共 bigram 跳过、jaccard 小于 float(min_jaccard) 跳过、condition_distinct 的 distinct 为假或 overlap > float(max_cond_overlap) 跳过,其余成候选并按 (-jaccard,a,b) 排序;返回 scanned、compared、candidates=out[:int(limit)]、total_candidates、truncated、note;
352
- def separation_pairs(cg, layer=None, ids=None, max_nodes=SEP_MAX_NODES,
353
- min_jaccard=SEP_MIN_JACCARD,
354
- max_cond_overlap=SEP_MAX_COND_OVERLAP,
355
- limit=SEP_MAX_PAIRS):
356
- """找出「内容高度相似、条件却不同」的节点对(模式分离候选)。
357
-
358
- 返回 {scanned, compared, candidates:[{a,b,jaccard,cond_overlap,distinct,reason}],
359
- truncated, note}。只读,不写盘。
360
- """
361
- from . import consistency
362
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
363
- pool = [nid for nid, e in list(nodes.items())
364
- if (not layer or e.get("layer") == layer)]
365
- if ids:
366
- want = {str(x) for x in ids}
367
- pool = [nid for nid in pool if nid in want]
368
- pool.sort()
369
- truncated = len(pool) > int(max_nodes)
370
- pool = pool[:int(max_nodes)]
371
- cache = {}
372
- for nid in pool:
373
- got = _node_terms_and_grams(cg, nid)
374
- if got and got["grams"]:
375
- cache[nid] = got
376
- keys = sorted(cache.keys())
377
- out, compared = [], 0
378
- for i in range(len(keys)):
379
- gi = cache[keys[i]]["grams"]
380
- for j in range(i + 1, len(keys)):
381
- gj = cache[keys[j]]["grams"]
382
- inter = len(gi & gj)
383
- if not inter:
384
- continue
385
- compared += 1
386
- jac = inter / float(len(gi | gj) or 1)
387
- if jac < float(min_jaccard):
388
- continue
389
- a, b = keys[i], keys[j]
390
- cd = consistency.condition_distinct(
391
- cache[a]["pos"], cache[a]["neg"],
392
- cache[b]["pos"], cache[b]["neg"])
393
- if not cd["distinct"] or cd["overlap"] > float(max_cond_overlap):
394
- continue # 条件相同 → 是重复,不是分离
395
- out.append({
396
- "a": a, "b": b,
397
- "a_layer": cache[a]["layer"], "b_layer": cache[b]["layer"],
398
- "jaccard": round(jac, 4), "cond_overlap": cd["overlap"],
399
- "reason": (f"内容相似 {jac:.2f} 但条件重合仅 {cd['overlap']:.2f}"
400
- f"(相似而不同情境,需分离)"),
401
- "a_conditions": sorted(cache[a]["pos"] | cache[a]["neg"])[:6],
402
- "b_conditions": sorted(cache[b]["pos"] | cache[b]["neg"])[:6],
403
- })
404
- out.sort(key=lambda x: (-x["jaccard"], x["a"], x["b"]))
405
- return {"scanned": len(keys), "compared": compared,
406
- "candidates": out[:int(limit)],
407
- "total_candidates": len(out), "truncated": truncated,
408
- "note": "只读候选;apply=True 才写分离边"}
409
-
410
-
411
- # 生效条件:batch 为假值(None 或空串)时回落到 time.strftime("%Y%m%d-%H%M%S");按 (a,b)、(b,a) 两向处理:cg.get(src) 为假值跳过,dst 已出现在 consistency.separation_targets(fm) 中跳过,否则往 fm["edges"] 追加 distinct_from 边、向 fm["pattern_separated_from"] 追加 dst,按 os.path.join(cg.root, e.get("path") or f"{src}.md") 调 cg._write_node 写盘并追加 MAINTAIN_LOG 行,src 记入 written;返回 {'a','b','written','batch'};
412
- def mark_separated(cg, a, b, reason="", actor="maintain", batch=None):
413
- """写入 (a↔b) 对称 `distinct_from` 边(幂等:已存在则不重复写)。"""
414
- from . import consistency
415
- batch = batch or time.strftime("%Y%m%d-%H%M%S")
416
- written = []
417
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
418
- for src, dst in ((a, b), (b, a)):
419
- node = cg.get(src)
420
- if not node:
421
- continue
422
- fm = node.get("frontmatter") or {}
423
- edges = list(fm.get("edges") or [])
424
- if dst in consistency.separation_targets(fm):
425
- continue
426
- edges.append({"target": dst, "relation_type": consistency.SEPARATION_REL,
427
- "reason": reason, "created_at": time.time(),
428
- "confidence": 1.0, "verified": 0})
429
- fm["edges"] = edges
430
- sep = list(fm.get("pattern_separated_from") or [])
431
- if dst not in sep:
432
- sep.append(dst)
433
- fm["pattern_separated_from"] = sep
434
- e = nodes.get(src) or {}
435
- path = os.path.join(cg.root, e.get("path") or f"{src}.md")
436
- cg._write_node(src, path, fm, node.get("content") or "")
437
- if e:
438
- e["edges"] = edges
439
- written.append(src)
440
- append_jsonl(os.path.join(cg.root, MAINTAIN_LOG), {
441
- "t": time.time(), "action": "separate", "batch": batch,
442
- "from": src, "to": dst, "reason": reason, "actor": actor})
443
- return {"a": a, "b": b, "written": written, "batch": batch}
444
-
445
-
446
- # 生效条件:pairs 为 None 时调 separation_pairs 取 candidates 与 meta(scanned/compared/truncated/total_candidates),否则 cands=list(pairs) 且 meta 中 scanned/compared 记 0、truncated 记 False、total_candidates=len(cands);apply 为真值时先生成统一 batch=time.strftime(...),逐个候选调 mark_separated(..., batch=batch),written 非空且 cg 有 rebuild_index 时调 cg.rebuild_index()、否则调 invalidate_cache(cg),apply 为假值时不写盘;返回 ok、action='separate'、dry_run=not apply、layer、candidates、written、written_count、elapsed_ms、log 与 meta、note;
447
- def separate_run(cg, layer=None, pairs=None, apply=False, ids=None,
448
- min_jaccard=SEP_MIN_JACCARD, limit=SEP_MAX_PAIRS,
449
- actor="maintain"):
450
- """模式分离:扫描相似但条件不同的节点对,按需写入对称分离边。
451
-
452
- apply=False(默认)只出候选报表(对应计划「可预演」)。
453
- """
454
- t0 = time.time()
455
- if pairs is None:
456
- rep = separation_pairs(cg, layer=layer, ids=ids,
457
- min_jaccard=min_jaccard, limit=limit)
458
- cands = rep["candidates"]
459
- meta = {k: rep[k] for k in ("scanned", "compared", "truncated",
460
- "total_candidates")}
461
- else:
462
- cands = list(pairs)
463
- meta = {"scanned": 0, "compared": 0, "truncated": False,
464
- "total_candidates": len(cands)}
465
- written = []
466
- if apply:
467
- batch = time.strftime("%Y%m%d-%H%M%S")
468
- for c in cands:
469
- written.append(mark_separated(cg, c["a"], c["b"],
470
- reason=c.get("reason", ""),
471
- actor=actor, batch=batch))
472
- if written and hasattr(cg, "rebuild_index"):
473
- cg.rebuild_index() # 边写盘后重建索引 + 清子图缓存
474
- else:
475
- invalidate_cache(cg)
476
- return {"ok": True, "action": "separate", "dry_run": not apply,
477
- "layer": layer, "candidates": cands, "written": written,
478
- "written_count": len(written), "elapsed_ms": int((time.time() - t0) * 1000),
479
- "log": MAINTAIN_LOG, **meta,
480
- "note": ("dry-run:未写盘;apply=True 才写分离边" if not apply
481
- else f"已写 {len(written)} 对对称分离边")}
482
-
483
-
484
- # ==========================================================================
485
- # 情景重构(insight.reconstruct)
486
- # ==========================================================================
487
- #
488
- # 问题:记忆被检索回来时,往往只剩一条「结论」,它当时**为什么成立**(生效条件 /
489
- # 不适用条件 / 同行情境)已经散落在相邻节点里。情景重构做的就是:由给定线索
490
- # (词面 / 节点 id)反推当时的**条件空间**,把散落的场景要素重新聚在一起。
491
- #
492
- # 与检索(read/route)的区别:检索按「当前查询」做资格判定;重构按「线索」做
493
- # **条件空间复原**,输出条件结构而非排序结果,用于回答「这件事成立于什么条件」。
494
- #
495
- # 诚实边界:
496
- # · 重构是条件空间的**近似重建**,不是事件回放(输出显式标注);
497
- # · 定位不到任何锚点时判 blindspot,**不得凭空编造条件空间**。
498
-
499
- RECON_MIN_SCORE = 0.15 # 词面命中下限(低于此不算锚点)
500
- RECON_MAX_NODES = 80 # 单次扫描节点上限(防 O(N) 读盘爆炸)
501
- RECON_MAX_ANCHORS = 12 # 锚点上限
502
- RECON_NEIGHBOR_LIMIT = 24 # 每锚点取的邻居上限
503
- RECON_COMMON_SHARE = 0.5 # 共同条件判定:≥ 半数锚点共享
504
- RECON_SCENE_PREFIX = "scene_"
505
-
506
-
507
- # 生效条件:clues 为 None 时返回 [];clues 为 str 时包装成单元素列表;逐项取 str(c or "").strip().lower(),空串跳过,整串去重入 out,再按 re.split(r"[\s,,、;;/|]+") 切词、去重后追加;返回 out;
508
- def _clue_terms(clues):
509
- """线索归一化:字符串 / 列表 → 去重词面(保留整串 + 切分后的词)。"""
510
- if clues is None:
511
- return []
512
- if isinstance(clues, str):
513
- clues = [clues]
514
- out = []
515
- for c in clues:
516
- s = str(c or "").strip().lower()
517
- if not s:
518
- continue
519
- if s not in out:
520
- out.append(s)
521
- for w in re.split(r"[\s,,、;;/|]+", s):
522
- w = w.strip()
523
- if w and w not in out:
524
- out.append(w)
525
- return out
526
-
527
-
528
- # 生效条件:term_sets 为假值(None/[])时返回 [];否则对每个集合的 set(s or ()) 统计词面出现次数,need = max(2, int(len(term_sets)*RECON_COMMON_SHARE) 向上取整),返回出现次数 >= need 的词面排序列表(阈值取自模块常量 RECON_COMMON_SHARE);
529
- def _shared_terms(term_sets):
530
- """出现在 ≥ RECON_COMMON_SHARE 比例集合中的词面(且至少 2 个集合共享)。"""
531
- if not term_sets:
532
- return []
533
- cnt = {}
534
- for s in term_sets:
535
- for t in set(s or ()):
536
- cnt[t] = cnt.get(t, 0) + 1
537
- need = max(2, int(len(term_sets) * RECON_COMMON_SHARE) + (1 if len(term_sets) * RECON_COMMON_SHARE % 1 else 0))
538
- return sorted(t for t, c in cnt.items() if c >= need)
539
-
540
-
541
- # 生效条件:按 term_sets 原顺序遍历每个集合的 sorted(s or ()),首次出现的词面追加到 seen,返回 seen[:limit](limit 默认 99,传 0 时切片为空列表,无 or 回落);
542
- def _uniq_terms(term_sets, limit=99):
543
- seen = []
544
- for s in term_sets:
545
- for t in sorted(s or ()):
546
- if t not in seen:
547
- seen.append(t)
548
- return seen[:limit]
549
-
550
-
551
- # 生效条件:bigrams(" ".join(clue_terms)) 为空时返回 [];否则遍历 pool,cg.get(nid) 为假值、或 forgetting.payload 后 bigrams 为空、或与 clue_grams 无交集时跳过,否则 jac=inter/len(并集 or 1)、exact 为 clue_terms 中非空且作为子串出现在 body 的个数,score=jac+0.05*exact,仅 score >= RECON_MIN_SCORE 才收录,最终按 (-score, nid) 排序返回;
552
- def _anchor_scores(cg, pool, clue_terms):
553
- """按词面重合给候选锚点打分(返回 [(nid, score, shared, exact)],降序)。"""
554
- from . import forgetting
555
- from .mdcg import bigrams
556
- clue_grams = bigrams(" ".join(clue_terms))
557
- if not clue_grams:
558
- return []
559
- scored = []
560
- for nid in pool:
561
- node = cg.get(nid)
562
- if not node:
563
- continue
564
- body = forgetting.payload(node.get("content") or "")
565
- grams = bigrams(body)
566
- if not grams:
567
- continue
568
- inter = len(grams & clue_grams)
569
- if not inter:
570
- continue
571
- jac = inter / float(len(grams | clue_grams) or 1)
572
- exact = sum(1 for t in clue_terms if t and t in body)
573
- score = jac + 0.05 * exact
574
- if score >= RECON_MIN_SCORE:
575
- scored.append((nid, round(score, 4), inter, exact))
576
- scored.sort(key=lambda x: (-x[1], x[0]))
577
- return scored
578
-
579
-
580
- # 生效条件:对 anchor_ids 中每个 nid,cg.get(nid) 为假值跳过,否则取 fm 与 consistency.condition_terms 得 pos/neg,per[nid] 记为 {"effective": sorted(pos)[:8], "non_applicable": sorted(neg)[:8]};返回 common=_shared_terms(pos_sets)、individual=_uniq_terms(pos_sets) 中不在 common 的项、non_applicable=_uniq_terms(neg_sets)、declared=list(declared_terms or [])、per_anchor=per;
581
- def _condition_space(cg, anchor_ids, declared_terms=None):
582
- """合成锚点群的条件空间:共同条件 / 个别条件 / 不适用条件 / 逐锚点明细。"""
583
- from . import consistency
584
- pos_sets, neg_sets, per = [], [], {}
585
- for nid in anchor_ids:
586
- node = cg.get(nid)
587
- if not node:
588
- continue
589
- fm = node.get("frontmatter") or {}
590
- pos, neg = consistency.condition_terms(fm, node.get("content") or "")
591
- pos_sets.append(pos)
592
- neg_sets.append(neg)
593
- per[nid] = {"effective": sorted(pos)[:8], "non_applicable": sorted(neg)[:8]}
594
- common = _shared_terms(pos_sets)
595
- individual = [t for t in _uniq_terms(pos_sets) if t not in common]
596
- return {"common": common, "individual": individual,
597
- "non_applicable": _uniq_terms(neg_sets),
598
- "declared": list(declared_terms or []), "per_anchor": per}
599
-
600
-
601
- # 生效条件:以 cg.index["nodes"] 为节点池(layer 为真时只保留 layer 等于该值的节点,池按 max_nodes 截断),由 clues 词项与 ids 收集锚点并截取 limit 个,锚点为空则返回 status="blindspot" 且 condition_space=None,否则返回 status="reconstructed"(neighbors 为真时按链邻接补边并在 max_nodes 内补节点,apply 为真且算出的 scene_id 尚不在 nodes 中时再写入该情境节点并记日志);
602
- def reconstruct_scene(cg, clues=None, ids=None, conditions=None, layer=None,
603
- max_nodes=RECON_MAX_NODES, limit=RECON_MAX_ANCHORS,
604
- neighbors=True, apply=False, actor="insight"):
605
- """情景重构:由线索反推条件空间,还原记忆成立的场景。
606
-
607
- 只读(apply=False 默认);apply=True 额外落一个 `scene_<hash>` 情境节点,
608
- 携带 `reconstructed_from` 锚点与 inferred 边,便于追溯与撤销。
609
-
610
- 返回 status ∈ {"reconstructed", "blindspot"};blindspot 时条件空间为 None,
611
- 不编造(对应计划「诚实边界」)。
612
- """
613
- from . import chain
614
- t0 = time.time()
615
- nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
616
- clue_terms = _clue_terms(clues)
617
- declared = [str(c).strip().lower() for c in (conditions or []) if str(c).strip()]
618
- want_ids = [str(x) for x in (ids or []) if str(x).strip()]
619
-
620
- # 线索里若直接写了节点 id,也算显式锚点
621
- for t in clue_terms:
622
- if t in nodes and t not in want_ids:
623
- want_ids.append(t)
624
-
625
- pool = [nid for nid, e in list(nodes.items())
626
- if (not layer or (e or {}).get("layer") == layer)]
627
- truncated = len(pool) > int(max_nodes)
628
- pool.sort()
629
- pool = pool[:int(max_nodes)]
630
-
631
- anchors, missing = [], []
632
- for nid in want_ids:
633
- if nid in nodes:
634
- anchors.append({"node_id": nid, "score": 1.0, "source": "explicit"})
635
- else:
636
- missing.append(nid)
637
- if clue_terms:
638
- have = {a["node_id"] for a in anchors}
639
- for nid, score, inter, exact in _anchor_scores(cg, pool, clue_terms):
640
- if nid in have:
641
- continue
642
- anchors.append({"node_id": nid, "score": score, "source": "lexical",
643
- "shared_bigrams": inter, "exact_hits": exact})
644
- have.add(nid)
645
- anchors = anchors[:int(limit)]
646
-
647
- base = {"ok": True, "action": "reconstruct", "op": "insight",
648
- "clues": clue_terms, "requested_ids": want_ids, "layer": layer,
649
- "truncated": truncated, "scanned": len(pool)}
650
-
651
- if not anchors:
652
- base.update({
653
- "status": "blindspot", "anchors": [], "nodes": [], "edges": [],
654
- "condition_space": None,
655
- "missing": missing or (["锚点"] if clue_terms else ["线索"]),
656
- "elapsed_ms": int((time.time() - t0) * 1000),
657
- "note": "线索未能定位任何锚点:判 blindspot,不编造条件空间(诚实边界)"})
658
- return base
659
-
660
- anchor_ids = [a["node_id"] for a in anchors]
661
- node_ids, edges = list(anchor_ids), []
662
- if neighbors:
663
- adj = {}
664
- try:
665
- adj = chain.adjacency(cg)
666
- except Exception:
667
- adj = {}
668
- seen = set(node_ids)
669
- for nid in anchor_ids:
670
- outs = (adj.get(nid) or [])[:RECON_NEIGHBOR_LIMIT]
671
- for tgt, e in outs:
672
- rel = chain.edge_rel(e)
673
- edges.append({"from": nid, "to": tgt, "relation": rel,
674
- "evidence": (e or {}).get("evidence")})
675
- if tgt not in seen and len(node_ids) < int(max_nodes):
676
- seen.add(tgt)
677
- node_ids.append(tgt)
678
-
679
- cs = _condition_space(cg, anchor_ids, declared_terms=declared)
680
- separated = [nid for nid in anchor_ids
681
- if any(e.get("relation") == "distinct_from" for e in edges
682
- if e.get("from") == nid)]
683
- with_conditions = sum(1 for nid in anchor_ids
684
- if (cs["per_anchor"].get(nid) or {}).get("effective"))
685
- confidence = round(
686
- min(1.0, (sum(a["score"] for a in anchors) / float(len(anchors)))
687
- * (0.5 + 0.5 * with_conditions / float(len(anchor_ids)))), 4)
688
-
689
- out = dict(base)
690
- out.update({
691
- "status": "reconstructed", "anchors": anchors, "nodes": node_ids,
692
- "edges": edges, "condition_space": cs,
693
- "signals": {"anchors": len(anchors), "with_conditions": with_conditions,
694
- "separated": separated},
695
- "confidence": confidence,
696
- "elapsed_ms": int((time.time() - t0) * 1000),
697
- "note": "条件空间的近似重建(非事件回放);common=共同生效条件,"
698
- "individual=个别条件,non_applicable=不适用条件"})
699
-
700
- if apply:
701
- sid = RECON_SCENE_PREFIX + hashlib.sha1(
702
- "|".join(sorted(node_ids)).encode("utf-8")).hexdigest()[:10]
703
- written = False
704
- if sid not in nodes:
705
- common_txt = ";".join(cs["common"][:6]) or "(未提炼出共同条件)"
706
- neg_txt = ";".join(cs["non_applicable"][:6]) or "(未判定)"
707
- body = (
708
- "# 功能名:情景重构:%s\n"
709
- "# 生效条件:%s\n"
710
- "# 子功能:由 %d 个锚点复原的条件空间(锚点:%s)\n"
711
- "# 执行:由 insight.reconstruct 反推(inferred 近似重建,非事件回放)\n"
712
- "# 验证方式:待验证(推断结果,需人工/实践核对后方可升格)\n"
713
- "# 不适用条件:%s\n"
714
- % ("、".join(clue_terms[:6]) or "线索", common_txt, len(anchor_ids),
715
- "、".join(anchor_ids), neg_txt))
716
- cg.add(sid, body, layer="contextual",
717
- tags=["scene", "reconstructed"], importance=0.4,
718
- verification_basis="other", reconstructed_from=list(anchor_ids),
719
- clues=list(clue_terms), confidence=confidence,
720
- actor=actor)
721
- append_jsonl(os.path.join(cg.root, MAINTAIN_LOG), {
722
- "t": time.time(), "action": "reconstruct", "scene": sid,
723
- "anchors": list(anchor_ids), "clues": clue_terms,
724
- "common": cs["common"], "confidence": confidence, "actor": actor})
725
- invalidate_cache(cg)
726
- written = True
727
- out["scene_id"] = sid
728
- out["scene_written"] = written
729
- return out
1
+ # -*- coding: utf-8 -*-
2
+ """嵌套子图(nested subgraph):结构要素的可递归表示 + flatten。
3
+
4
+ 对齐 AEIS《认知图写入纪律 v1.0》四要素中的第三项:
5
+ subgraph = 内部子内容(可嵌套:子节点 + 边),角色=结构(可检索/可递归)。
6
+
7
+ 与 AEIS 的两处**有意差异**(都有工程理由,不是简化):
8
+
9
+ 1) 存储形态:AEIS 把子节点**内联**在父节点 `subgraph.nodes` 里
10
+ (`aeis/image_semantics_cg.py:37-57`)。md_cg 的检索粒度是「节点 = 文件」
11
+ (RRF 按节点召回),内联子节点无法被任何检索路单独命中,会违背「子图可检索」
12
+ 这一规范本身。故 md_cg 采用**引用式**:`subgraph.nodes` 存子节点 id,
13
+ 子节点各自是独立 `.md`,可被 lexical/entity/chain 等路独立召回。
14
+ 同时兼容内联写法(`{"id": ...}` 对象)以承接 AEIS 语料。
15
+
16
+ 2) 递归深度:AEIS 明确「深度上限不是协议常数,数据驱动,= 可分性条件的自然耗尽」
17
+ (`子部件提取_理论稿_v0.4.md:146-150`)。故 `max_depth=None` 表示一直展开到
18
+ 自然耗尽(无子节点);`max_depth=k` 只是工程硬截断,会置 `truncated=True`。
19
+
20
+ 父边唯一(每个节点至多一个 `part_of` 父)——`子部件提取_理论稿_v0.4.md:105`;
21
+ 违反者由 `validate()` 报 `multi_parent`,对齐「树形不一致 → 退回 DEFER」。
22
+ """
23
+ from __future__ import annotations
24
+
25
+ import hashlib
26
+ import os
27
+ import re
28
+ import time
29
+ from collections import deque
30
+
31
+ from .fsutil import append_jsonl
32
+
33
+ MAX_DEPTH_HARD = 64 # 工程硬截断上限(防止畸形数据把遍历拖爆)
34
+ MAX_NODES_DEFAULT = 2000 # 单次展开的节点上限
35
+
36
+ # ---- 模式分离(maintain.separate)参数 -----------------------------------
37
+ MAINTAIN_LOG = "_maintain.jsonl"
38
+ SEP_MIN_JACCARD = 0.55 # 内容相似度下限(越高=越像,才值得谈分离)
39
+ SEP_MAX_COND_OVERLAP = 0.35 # 条件重合上限(越高=条件越同,就该合并而非分离)
40
+ SEP_MAX_NODES = 400 # 单次扫描节点上限(防 O(N²) 读盘爆炸)
41
+ SEP_MAX_PAIRS = 50 # 单次返回/落库的候选对上限
42
+
43
+
44
+ # 生效条件:fm 为假值或 fm.get("subgraph") 取值为假(None/[]/{}/空串)时直接返回 {'nodes': [], 'edges': []};subgraph 为 list/tuple 时其元素作节点、边记空列表,为 dict 时节点取 sg.get("nodes")(缺键或假值回落 [])、边取 sg.get("edges")(同样回落),为其他类型仍返回空;节点项为 dict 时取 n.get("id")、否则取元素本身,nid 为 None 跳过,仅当 str(nid).strip() 非空且未出现过才追加;边只保留 isinstance(e, dict) 的项;
45
+ def declared(fm):
46
+ """规范化 `frontmatter.subgraph` → `{"nodes": [id...], "edges": [edge...]}`。
47
+
48
+ 兼容三种写法:
49
+ {"nodes": ["a", "b"], "edges": [...]} 引用式(md_cg 主用)
50
+ ["a", "b"] 纯 id 列表
51
+ {"nodes": [{"id": "a"}, ...]} 内联式(AEIS 原样,只取 id)
52
+ """
53
+ sg = (fm or {}).get("subgraph")
54
+ if not sg:
55
+ return {"nodes": [], "edges": []}
56
+ if isinstance(sg, (list, tuple)):
57
+ raw_nodes, raw_edges = list(sg), []
58
+ elif isinstance(sg, dict):
59
+ raw_nodes, raw_edges = list(sg.get("nodes") or []), list(sg.get("edges") or [])
60
+ else:
61
+ return {"nodes": [], "edges": []}
62
+ nodes, seen = [], set()
63
+ for n in raw_nodes:
64
+ nid = n.get("id") if isinstance(n, dict) else n
65
+ if nid is None:
66
+ continue
67
+ nid = str(nid).strip()
68
+ if nid and nid not in seen:
69
+ seen.add(nid)
70
+ nodes.append(nid)
71
+ return {"nodes": nodes, "edges": [e for e in raw_edges if isinstance(e, dict)]}
72
+
73
+
74
+ # 生效条件:当 getattr(cg,"index",None) 的 nodes 字典中存在 nid(entry 非 None)且 "subgraph" in entry 时,返回 {'id': nid, 'subgraph': entry.get("subgraph"), 'edges': entry.get("edges") or []}(subgraph 值为 None 也照样返回);否则改走 cg.get(nid),返回 (node or {}).get("frontmatter") or {},节点不存在或 frontmatter 为假值时得空 dict;
75
+ def _fm(cg, nid):
76
+ """取节点 frontmatter:优先索引快照(免 IO),快照缺字段时回退读文件。"""
77
+ entry = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid)
78
+ if entry is not None and "subgraph" in entry:
79
+ return {"id": nid, "subgraph": entry.get("subgraph"),
80
+ "edges": entry.get("edges") or []}
81
+ node = cg.get(nid)
82
+ return (node or {}).get("frontmatter") or {}
83
+
84
+
85
+ # --------------------------------------------------------------------------
86
+ # 迁移边适配:源 sqlite 认知图 → md_cg 本地边
87
+ # --------------------------------------------------------------------------
88
+ # 源库的 `hierarchical` 方向是 **source=父、target=子**(白箱
89
+ # `wisdom-book-cloud.db` 全量实测:`source_is_parent=2832`、`target_is_parent=0`)。
90
+ # md_cg 的父边约定与其**相反**:`part_of` 表示「本节点是子、target 是父」
91
+ # (见下方 children_index)。若把源库 hierarchical 原样搬进来,树会整体倒置;
92
+ # 故迁移时翻译成语义等价的 `contains`(本节点是父、target 是子)。
93
+ SRC_REL_MAP = {"hierarchical": "contains"}
94
+
95
+
96
+ # 生效条件:rel 先经 str(rel or "").strip().lower() 归一(None/空串得 ""),返回 {'target': str(tgt), 'relation_type': SRC_REL_MAP.get(rel, rel), 'confidence': confidence, 'verified': verified}——归一后的 rel 命中模块常量 SRC_REL_MAP 时用映射值、未命中(含 rel 为空串)时原样保留,confidence/verified 直接透传默认 1.0/0 的实参不做校验;
97
+ def normalize_edge(tgt, rel, confidence=1.0, verified=0):
98
+ """源库边 → md_cg 本地边(迁移器专用)。做两件事:
99
+
100
+ 1) 键名统一为 `relation_type`。`children_index` / `parents_index` 只认
101
+ `relation_type` / `relation`;早期迁移器写的 `"type"` 会被静默忽略
102
+ (`chain.edge_rel` 兼容 `type`,但 `subgraph` 不兼容),使迁入的图不可遍历。
103
+ 2) 方向按 `SRC_REL_MAP` 翻译(源库 hierarchical = source 是父)。
104
+ """
105
+ rel = str(rel or "").strip().lower()
106
+ return {"target": str(tgt), "relation_type": SRC_REL_MAP.get(rel, rel),
107
+ "confidence": confidence, "verified": verified}
108
+
109
+
110
+ # 生效条件:pid 为当前节点 id、fm 为 frontmatter;声明子节点与登记层级关系统一产出 (child,parent),兼容 relation/type/target_id 别名,未知关系/非 dict 边不产出。
111
+ def _hierarchy_pairs(pid, fm):
112
+ """Single hierarchy direction/alias source for both indexes and validation."""
113
+ for child in declared(fm)["nodes"]:
114
+ yield child, pid
115
+ edges = fm.get("edges") or []
116
+ if not isinstance(edges, (list, tuple)):
117
+ return
118
+ for edge in edges:
119
+ if not isinstance(edge, dict):
120
+ continue
121
+ rel = str(edge.get("relation_type") or edge.get("relation") or edge.get("type")
122
+ or "").strip().lower()
123
+ target = edge.get("target") or edge.get("target_id")
124
+ if target is None:
125
+ continue
126
+ target = str(target).strip()
127
+ if rel in ("part_of", "hierarchical"):
128
+ yield pid, target
129
+ elif rel in ("parent_of", "contains"):
130
+ yield target, pid
131
+
132
+
133
+ # 生效条件:已有 _subgraph_children 缓存则原样返回;否则遍历索引节点快照,按 _hierarchy_pairs 去重 (child,parent),构建 parent→[child] 并缓存。
134
+ # 生效条件:cg 的 `_cache_generation` 可调用时取其代际,与上次记录的 `_subgraph_generation` 不同即调用 invalidate_cache(cg) 并更新记录(issue #343:派生面随真源换代——真源变了,派生索引必须失效,否则 cache 那一维会给出旧答案)。
135
+ def _ensure_cache_generation(cg):
136
+ """Both directions belong to the same current node snapshot."""
137
+ generation = getattr(cg, "_cache_generation", None)
138
+ if not callable(generation):
139
+ return
140
+ generation = generation()
141
+ if getattr(cg, "_subgraph_generation", None) != generation:
142
+ invalidate_cache(cg)
143
+ cg._subgraph_generation = generation
144
+
145
+
146
+ def children_index(cg):
147
+ """全局正查;声明和边共用单一方向规则,保留首次出现顺序。"""
148
+ _ensure_cache_generation(cg) # #343 换代守卫
149
+ idx = getattr(cg, "_subgraph_children", None)
150
+ if idx is not None:
151
+ return idx
152
+ idx, pairs = {}, set()
153
+ for pid in list(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys()):
154
+ for child, parent in _hierarchy_pairs(pid, _fm(cg, pid)):
155
+ if (child, parent) in pairs:
156
+ continue
157
+ pairs.add((child, parent))
158
+ idx.setdefault(parent, []).append(child)
159
+ try:
160
+ cg._subgraph_children = idx
161
+ except Exception:
162
+ pass
163
+ return idx
164
+
165
+
166
+ # 生效条件:返回 list(children_index(cg).get(nid) or []),即 nid 在索引中无键或对应值为空(None/空列表)时得空列表,否则返回其子 id 的浅拷贝列表;
167
+ def children(cg, nid):
168
+ """直接子节点 id 列表:`subgraph.nodes` 声明 ∪ 边式父子关系。"""
169
+ return list(children_index(cg).get(nid) or [])
170
+
171
+
172
+ # 生效条件:已有 _subgraph_parents 缓存则原样返回;否则遍历索引节点快照,按 _hierarchy_pairs 去重 (child,parent),构建 child→[parent] 并缓存。
173
+ def parents_index(cg):
174
+ """全局反查;与 children_index 共用规范化后的同一边集合。"""
175
+ _ensure_cache_generation(cg) # #343 换代守卫
176
+ idx = getattr(cg, "_subgraph_parents", None)
177
+ if idx is not None:
178
+ return idx
179
+ idx, pairs = {}, set()
180
+ for pid in list(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys()):
181
+ for child, parent in _hierarchy_pairs(pid, _fm(cg, pid)):
182
+ if (child, parent) in pairs:
183
+ continue
184
+ pairs.add((child, parent))
185
+ idx.setdefault(child, []).append(parent)
186
+ try:
187
+ cg._subgraph_parents = idx
188
+ except Exception:
189
+ pass
190
+ return idx
191
+
192
+
193
+ # 生效条件:无条件执行——把 cg 的 _subgraph_parents 与 _subgraph_children 依次 setattr 为 None(setattr 抛异常被 except 吞掉后继续下一个),无返回值,与 cg 是否已建有缓存无关;
194
+ def invalidate_cache(cg):
195
+ """写入/删除节点后调用,丢弃父子正查/反查缓存。"""
196
+ for attr in ("_subgraph_parents", "_subgraph_children"):
197
+ try:
198
+ setattr(cg, attr, None)
199
+ except Exception:
200
+ pass
201
+
202
+
203
+ # 生效条件:取 parents_index(cg).get(nid) or [],列表非空时返回其首元素,键缺失或值为空/假(None、[])时返回 None;多父时只返回第一个,不在此处报歧义;
204
+ def parent_of(cg, nid):
205
+ """唯一父(多父时返回第一个并置 `ambiguous` 标记由 validate 报出)。"""
206
+ ps = parents_index(cg).get(nid) or []
207
+ return ps[0] if ps else None
208
+
209
+
210
+ # 生效条件:max_depth 非 None 时先 max(0, min(int(max_depth), MAX_DEPTH_HARD)) 收敛;max_nodes 非 None 时 int() 收敛(nan/inf 抛 ValueError/OverflowError,不得解除上界);以 nid 为根迭代 BFS(deque.popleft),已入 seen 的节点跳过,len(seen) >= max_nodes(max_nodes 传 0 时首次循环即成立)置 truncated=True 并 break,depth >= max_depth 且邻接非空时置 truncated=True 并 continue,否则按 children_index 顺序把未出现过的 (ch,cur) 追加 part_of 边并入队;返回前只保留两端均已 admit 的边;返回 {'root','nodes','paths','edges','n_nodes','n_edges','truncated'};
211
+ def expand(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
212
+ """按最短层级展开子树(迭代 BFS,防递归深度爆栈)。
213
+
214
+ 返回 `{"root","nodes","paths","edges","n_nodes","n_edges","truncated"}`;
215
+ `paths` 为 `节点 id → "根/子/孙"` 层级路径(flatten 后仍可定位来源)。
216
+ 边为 `part_of(child→parent)`,与 AEIS flatten 的方向一致。
217
+
218
+ v0.9.0 起改为 BFS:① 共享子节点按最短层级登记路径;② 节点预算耗尽时不预拷贝宽邻接表;
219
+ ③ 返回前只保留两端均已 admit 的边(边闭合,不把未 admit 的子节点留在边里)。
220
+ """
221
+ if max_depth is not None:
222
+ max_depth = max(0, min(int(max_depth), MAX_DEPTH_HARD))
223
+ if max_nodes is not None:
224
+ max_nodes = int(max_nodes) # v0.9.0:nan/inf 预算必须结构化拒绝(int() 抛 ValueError/OverflowError),不得解除上界
225
+ seen, edges, truncated = {}, [], False
226
+ seen_edges = set()
227
+ queue = deque([(nid, 0, nid)])
228
+ while queue:
229
+ cur, depth, path = queue.popleft()
230
+ if cur in seen:
231
+ continue
232
+ if len(seen) >= max_nodes:
233
+ truncated = True
234
+ break
235
+ seen[cur] = path
236
+ adjacency = children_index(cg).get(cur) or ()
237
+ if max_depth is not None and depth >= max_depth:
238
+ if adjacency:
239
+ truncated = True
240
+ continue
241
+ for ch in adjacency:
242
+ key = (ch, cur)
243
+ if key not in seen_edges:
244
+ seen_edges.add(key)
245
+ edges.append({"source": ch, "target": cur,
246
+ "relation_type": "part_of",
247
+ "confidence": 1.0, "verified": 0})
248
+ if ch not in seen:
249
+ # 预算守卫必须在入队前:已 admit + 在飞 达上界即停,既不超预算,也不预扫整份宽邻接;
250
+ # 已登记的边在返回前按 admit 面过滤(下面那行),不会留下指向未 admit 节点的边。
251
+ if len(seen) + len(queue) >= max_nodes:
252
+ truncated = True
253
+ break
254
+ queue.append((ch, depth + 1, f"{path}/{ch}"))
255
+ edges = [e for e in edges if e["source"] in seen and e["target"] in seen]
256
+ return {"root": nid, "nodes": list(seen.keys()), "paths": seen,
257
+ "edges": edges, "n_nodes": len(seen), "n_edges": len(edges),
258
+ "truncated": truncated}
259
+
260
+
261
+ # 生效条件:先调用 expand(cg, nid, max_depth=max_depth, max_nodes=max_nodes),对其中每条边复制一份并追加 source/target 互换、relation_type="parent_of"、confidence/verified 沿用原边 .get(…,1.0/0) 的反向边;返回 root=nid、nodes=ex["nodes"]、paths=ex["paths"]、n_nodes=ex["n_nodes"]、n_edges=双边后条数、truncated=ex["truncated"];
262
+ def flatten(cg, nid, max_depth=None, max_nodes=MAX_NODES_DEFAULT):
263
+ """把嵌套子图摊平成「节点 + 边」,父子生成**对称双边**。
264
+
265
+ 对齐 AEIS `flatten_image_semantics_graph`(`image_semantics_cg.py:151-173`):
266
+ 每个有父的节点同时产出 `part_of(child→parent)` 与 `parent_of(parent→child)`。
267
+ 检索侧因此既能「从父找子」(下钻),也能「从子找父」(溯源)。
268
+ """
269
+ ex = expand(cg, nid, max_depth=max_depth, max_nodes=max_nodes)
270
+ edges = []
271
+ for e in ex["edges"]:
272
+ edges.append(dict(e))
273
+ edges.append({"source": e["target"], "target": e["source"],
274
+ "relation_type": "parent_of",
275
+ "confidence": e.get("confidence", 1.0),
276
+ "verified": e.get("verified", 0)})
277
+ return {"root": nid, "nodes": ex["nodes"], "edges": edges, "paths": ex["paths"],
278
+ "n_nodes": ex["n_nodes"], "n_edges": len(edges),
279
+ "truncated": ex["truncated"]}
280
+
281
+
282
+ # 生效条件:known 取 cg.index 的 nodes 键集合,仅当 parents_index(cg).get(nid) or [] 为空(键缺失或空列表)的 nid 才视为树根,返回其排序后的 id 列表;
283
+ def roots(cg):
284
+ """无父节点(树根)的 id 列表。"""
285
+ known = set(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys())
286
+ pmap = parents_index(cg)
287
+ return sorted(nid for nid in known if not (pmap.get(nid) or []))
288
+
289
+
290
+ # 生效条件:parent 为 child→首父 映射;逐分量记忆化链尾,返回 node→None(无环)或 (cycle_tuple,entry_offset),不递归、不重复上溯已解析尾链。
291
+ def _cycle_entries(parent):
292
+ """O(V) functional-parent analysis; cycle report bytes are a separate cost."""
293
+ resolved = {}
294
+ for start in parent:
295
+ if start in resolved:
296
+ continue
297
+ path, positions, cur = [], {}, start
298
+ while cur is not None and cur not in positions and cur not in resolved:
299
+ positions[cur] = len(path)
300
+ path.append(cur)
301
+ cur = parent.get(cur)
302
+ if cur in positions:
303
+ cycle = tuple(path[positions[cur]:])
304
+ for offset, node in enumerate(cycle):
305
+ resolved[node] = (cycle, offset)
306
+ inherited = resolved.get(cur)
307
+ for node in reversed(path):
308
+ if node in resolved:
309
+ inherited = resolved[node]
310
+ else:
311
+ resolved[node] = inherited
312
+ return resolved
313
+
314
+
315
+ # 生效条件:max_scan 只限源节点处理数,以全节点快照判断悬空端点;层级关系统一经 _hierarchy_pairs,报告自环/悬空/多父,再检查首父投影的环;保留旧声明图的报告顺序、路径和 limit*4 缓冲上限。
316
+ def validate(cg, limit=50, max_scan=None):
317
+ """声明和边使用同一层级模型;有多父即报错,环沿首父投影诊断。"""
318
+ all_known = list(((getattr(cg, "index", None) or {}).get("nodes") or {}).keys())
319
+ known = all_known
320
+ if max_scan:
321
+ known = known[:int(max_scan)]
322
+ known_set = set(all_known)
323
+ parent, issues, seen_pairs = {}, [], set()
324
+
325
+ # 生效条件:仅缓冲前 limit*4 条问题,保持旧报告计数与截断口径。
326
+ def _issue(**kw):
327
+ if len(issues) < limit * 4:
328
+ issues.append(kw)
329
+
330
+ for pid in known:
331
+ fm = _fm(cg, pid)
332
+ if fm.get("edges") is not None and not isinstance(fm["edges"], (list, tuple)):
333
+ _issue(id=pid, issue="invalid_edges")
334
+ for child, par in _hierarchy_pairs(pid, fm):
335
+ if (child, par) in seen_pairs:
336
+ continue
337
+ seen_pairs.add((child, par))
338
+ if child == par:
339
+ _issue(id=par, issue="self_loop", child=child)
340
+ continue
341
+ if child not in known_set:
342
+ _issue(id=par, issue="dangling_child", child=child)
343
+ if par not in known_set:
344
+ _issue(id=child, issue="dangling_parent", parent=par)
345
+ prev = parent.get(child)
346
+ if prev is not None and prev != par:
347
+ _issue(id=child, issue="multi_parent", parents=sorted({prev, par}))
348
+ else:
349
+ parent[child] = par
350
+ if len(issues) < limit * 4:
351
+ resolved = _cycle_entries(parent)
352
+ for nid in known:
353
+ if len(issues) >= limit * 4:
354
+ break
355
+ info = resolved.get(nid)
356
+ if info is not None:
357
+ cycle, offset = info
358
+ rotation = cycle[offset:] + cycle[:offset]
359
+ _issue(id=rotation[0], issue="cycle", path=list(rotation) + [rotation[0]])
360
+ return {"scanned": len(known), "issues": len(issues),
361
+ "items": issues[:limit], "truncated": len(issues) > limit}
362
+
363
+
364
+ # ==========================================================================
365
+ # 模式分离(maintain.separate)
366
+ # ==========================================================================
367
+ #
368
+ # 问题:两条记忆**内容高度相似但生效条件不同**。若放任不管,检索会把它们混为
369
+ # 一体——按 A 的条件召回、却拿到 B 的结论。海马体的做法是 pattern separation:
370
+ # 把相似但情境不同的表征拆开,各挂各的条件线索。
371
+ #
372
+ # 本层的工程兑现(保守、可逆、幂等):
373
+ # · 不动正文(不制造第二份真相),只加**对称分离边** `distinct_from`;
374
+ # · 边携带 reason + 判定分量,供后续重构/审计追溯;
375
+ # · 条件**相同**的相似对**不是**分离候选(那是重复,该走 MERGE)。
376
+
377
+ # issue #164:派生节点(概念归纳 / 情景重构)必须带密级,密级 = 来源锚点最高档;
378
+ # 判不了(缺 / 非法)fail-closed 不生成。加密档(crypto.ENCRYPTED_LEVELS)只抄
379
+ # id 不抄条件词——判据读 frontmatter 明文,不依赖 cg.get 是否已解密。
380
+ def _sensitivity_of(fm):
381
+ """从 frontmatter 读合法密级;缺/非法返回 None(不猜测)。"""
382
+ from . import security as _sec
383
+ s = (fm or {}).get("sensitivity")
384
+ if s is None:
385
+ return _sec.DEFAULT_SENSITIVITY
386
+ try:
387
+ _sec._rank(str(s))
388
+ return str(s)
389
+ except Exception:
390
+ return None
391
+
392
+
393
+ def node_sensitivity(cg, nid):
394
+ """读节点密级:优先索引快照(元数据明文),回退读文件;判不了返回 None。"""
395
+ e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid)
396
+ if e is not None and e.get("sensitivity") is not None:
397
+ return _sensitivity_of(e)
398
+ node = cg.get(nid)
399
+ if not node:
400
+ return None
401
+ return _sensitivity_of(node.get("frontmatter") or {})
402
+
403
+
404
+ def derive_sensitivity(cg, nids):
405
+ """派生节点密级 = 来源锚点最高档;任一来源判不了 → None(fail-closed)。"""
406
+ from . import security as _sec
407
+ best = None
408
+ for nid in nids:
409
+ s = node_sensitivity(cg, nid)
410
+ if s is None:
411
+ return None
412
+ if best is None or _sec._rank(s) > _sec._rank(best):
413
+ best = s
414
+ return best
415
+
416
+
417
+ # 生效条件:cg.get(nid) 为假值(None/{})时返回 None;否则取 fm=node.get("frontmatter") or {}、content=node.get("content") or "",返回 {'grams': bigrams(forgetting.payload(content)), 'pos','neg': consistency.condition_terms(fm, content) 的结果, 'layer': fm.get("layer"), 'sensitivity': _sensitivity_of(fm)};加密档返回 grams/pos/neg 为空集、encrypted=True,不抄条件词;
418
+ def _node_terms_and_grams(cg, nid):
419
+ """读取节点并返回 (payload 二元组, 正条件词面, 负条件词面);不可读返回 None。"""
420
+ from . import consistency, forgetting, crypto
421
+ from .mdcg import bigrams # 惰性导入:避开 mdcg↔subgraph 循环
422
+ e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid)
423
+ if e is not None and e.get("sensitivity") is not None:
424
+ sens = _sensitivity_of(e)
425
+ if sens is None:
426
+ return {"grams": set(), "pos": set(), "neg": set(),
427
+ "layer": e.get("layer"), "sensitivity": None,
428
+ "unjudgeable": True}
429
+ if crypto.is_encrypted_level(sens): # v0.9.0:加密档判定走单点谓词
430
+ return {"grams": set(), "pos": set(), "neg": set(),
431
+ "layer": e.get("layer"), "sensitivity": sens,
432
+ "encrypted": True}
433
+ node = cg.get(nid)
434
+ if not node:
435
+ return None
436
+ fm = node.get("frontmatter") or {}
437
+ content = node.get("content") or ""
438
+ sens = _sensitivity_of(fm)
439
+ if crypto.is_encrypted_level(sens): # v0.9.0:加密档判定走单点谓词
440
+ return {"grams": set(), "pos": set(), "neg": set(),
441
+ "layer": fm.get("layer"), "sensitivity": sens, "encrypted": True}
442
+ grams = bigrams(forgetting.payload(content))
443
+ pos, neg = consistency.condition_terms(fm, content)
444
+ return {"grams": grams, "pos": pos, "neg": neg, "layer": fm.get("layer"),
445
+ "sensitivity": sens}
446
+
447
+
448
+ # 生效条件:pool 初取 cg.index 的 nodes 键,layer 为假值(None/"")时不按层过滤、否则只留 e.get("layer")==layer 的 nid,ids 为真值时只留 str(x) 属于该集合的 nid;pool 排序后 truncated=len(pool)>int(max_nodes)、并截为前 int(max_nodes) 个;只有 _node_terms_and_grams 返回非 None 且 grams 非空的节点进 cache;对 cache 键两两比较——无公共 bigram 跳过、jaccard 小于 float(min_jaccard) 跳过、condition_distinct 的 distinct 为假或 overlap > float(max_cond_overlap) 跳过,其余成候选并按 (-jaccard,a,b) 排序;返回 scanned、compared、candidates=out[:int(limit)]、total_candidates、truncated、note;
449
+ def separation_pairs(cg, layer=None, ids=None, max_nodes=SEP_MAX_NODES,
450
+ min_jaccard=SEP_MIN_JACCARD,
451
+ max_cond_overlap=SEP_MAX_COND_OVERLAP,
452
+ limit=SEP_MAX_PAIRS):
453
+ """找出「内容高度相似、条件却不同」的节点对(模式分离候选)。
454
+
455
+ 返回 {scanned, compared, candidates:[{a,b,jaccard,cond_overlap,distinct,reason}],
456
+ truncated, note}。只读,不写盘。
457
+ """
458
+ from . import consistency
459
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
460
+ pool = [nid for nid, e in list(nodes.items())
461
+ if (not layer or e.get("layer") == layer)]
462
+ if ids:
463
+ want = {str(x) for x in ids}
464
+ pool = [nid for nid in pool if nid in want]
465
+ pool.sort()
466
+ truncated = len(pool) > int(max_nodes)
467
+ pool = pool[:int(max_nodes)]
468
+ cache = {}
469
+ for nid in pool:
470
+ got = _node_terms_and_grams(cg, nid)
471
+ if got and got["grams"]:
472
+ cache[nid] = got
473
+ keys = sorted(cache.keys())
474
+ out, compared = [], 0
475
+ for i in range(len(keys)):
476
+ gi = cache[keys[i]]["grams"]
477
+ for j in range(i + 1, len(keys)):
478
+ gj = cache[keys[j]]["grams"]
479
+ inter = len(gi & gj)
480
+ if not inter:
481
+ continue
482
+ compared += 1
483
+ jac = inter / float(len(gi | gj) or 1)
484
+ if jac < float(min_jaccard):
485
+ continue
486
+ a, b = keys[i], keys[j]
487
+ cd = consistency.condition_distinct(
488
+ cache[a]["pos"], cache[a]["neg"],
489
+ cache[b]["pos"], cache[b]["neg"])
490
+ if not cd["distinct"] or cd["overlap"] > float(max_cond_overlap):
491
+ continue # 条件相同 → 是重复,不是分离
492
+ out.append({
493
+ "a": a, "b": b,
494
+ "a_layer": cache[a]["layer"], "b_layer": cache[b]["layer"],
495
+ "jaccard": round(jac, 4), "cond_overlap": cd["overlap"],
496
+ "reason": (f"内容相似 {jac:.2f} 但条件重合仅 {cd['overlap']:.2f}"
497
+ f"(相似而不同情境,需分离)"),
498
+ "a_conditions": sorted(cache[a]["pos"] | cache[a]["neg"])[:6],
499
+ "b_conditions": sorted(cache[b]["pos"] | cache[b]["neg"])[:6],
500
+ })
501
+ out.sort(key=lambda x: (-x["jaccard"], x["a"], x["b"]))
502
+ return {"scanned": len(keys), "compared": compared,
503
+ "candidates": out[:int(limit)],
504
+ "total_candidates": len(out), "truncated": truncated,
505
+ "note": "只读候选;apply=True 才写分离边"}
506
+
507
+
508
+ # 生效条件:batch 为假值(None 或空串)时回落到 time.strftime("%Y%m%d-%H%M%S");按 (a,b)、(b,a) 两向处理:cg.get(src) 为假值跳过,dst 已出现在 consistency.separation_targets(fm) 中跳过,否则往 fm["edges"] 追加 distinct_from 边、向 fm["pattern_separated_from"] 追加 dst,按 os.path.join(cg.root, e.get("path") or f"{src}.md") 调 cg._write_node 写盘并追加 MAINTAIN_LOG 行,src 记入 written;返回 {'a','b','written','batch'};
509
+ def mark_separated(cg, a, b, reason="", actor="maintain", batch=None):
510
+ """写入 (a↔b) 对称 `distinct_from` 边(幂等:已存在则不重复写)。"""
511
+ from . import consistency
512
+ batch = batch or time.strftime("%Y%m%d-%H%M%S")
513
+ written = []
514
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
515
+ for src, dst in ((a, b), (b, a)):
516
+ node = cg.get(src)
517
+ if not node:
518
+ continue
519
+ fm = node.get("frontmatter") or {}
520
+ edges = list(fm.get("edges") or [])
521
+ if dst in consistency.separation_targets(fm):
522
+ continue
523
+ edges.append({"target": dst, "relation_type": consistency.SEPARATION_REL,
524
+ "reason": reason, "created_at": time.time(),
525
+ "confidence": 1.0, "verified": 0})
526
+ fm["edges"] = edges
527
+ sep = list(fm.get("pattern_separated_from") or [])
528
+ if dst not in sep:
529
+ sep.append(dst)
530
+ fm["pattern_separated_from"] = sep
531
+ e = nodes.get(src) or {}
532
+ path = os.path.join(cg.root, e.get("path") or f"{src}.md")
533
+ cg._write_node(src, path, fm, node.get("content") or "")
534
+ if e:
535
+ e["edges"] = edges
536
+ written.append(src)
537
+ append_jsonl(os.path.join(cg.root, MAINTAIN_LOG), {
538
+ "t": time.time(), "action": "separate", "batch": batch,
539
+ "from": src, "to": dst, "reason": reason, "actor": actor})
540
+ return {"a": a, "b": b, "written": written, "batch": batch}
541
+
542
+
543
+ # 生效条件:pairs 为 None 时调 separation_pairs 取 candidates 与 meta(scanned/compared/truncated/total_candidates),否则 cands=list(pairs) 且 meta 中 scanned/compared 记 0、truncated 记 False、total_candidates=len(cands);apply 为真值时先生成统一 batch=time.strftime(...),逐个候选调 mark_separated(..., batch=batch),written 非空且 cg 有 rebuild_index 时调 cg.rebuild_index()、否则调 invalidate_cache(cg),apply 为假值时不写盘;返回 ok、action='separate'、dry_run=not apply、layer、candidates、written、written_count、elapsed_ms、log 与 meta、note;
544
+ def separate_run(cg, layer=None, pairs=None, apply=False, ids=None,
545
+ min_jaccard=SEP_MIN_JACCARD, limit=SEP_MAX_PAIRS,
546
+ actor="maintain"):
547
+ """模式分离:扫描相似但条件不同的节点对,按需写入对称分离边。
548
+
549
+ apply=False(默认)只出候选报表(对应计划「可预演」)。
550
+ """
551
+ t0 = time.time()
552
+ if pairs is None:
553
+ rep = separation_pairs(cg, layer=layer, ids=ids,
554
+ min_jaccard=min_jaccard, limit=limit)
555
+ cands = rep["candidates"]
556
+ meta = {k: rep[k] for k in ("scanned", "compared", "truncated",
557
+ "total_candidates")}
558
+ else:
559
+ cands = list(pairs)
560
+ meta = {"scanned": 0, "compared": 0, "truncated": False,
561
+ "total_candidates": len(cands)}
562
+ written = []
563
+ if apply:
564
+ batch = time.strftime("%Y%m%d-%H%M%S")
565
+ for c in cands:
566
+ written.append(mark_separated(cg, c["a"], c["b"],
567
+ reason=c.get("reason", ""),
568
+ actor=actor, batch=batch))
569
+ if written and hasattr(cg, "rebuild_index"):
570
+ cg.rebuild_index() # 边写盘后重建索引 + 清子图缓存
571
+ else:
572
+ invalidate_cache(cg)
573
+ return {"ok": True, "action": "separate", "dry_run": not apply,
574
+ "layer": layer, "candidates": cands, "written": written,
575
+ "written_count": len(written), "elapsed_ms": int((time.time() - t0) * 1000),
576
+ "log": MAINTAIN_LOG, **meta,
577
+ "note": ("dry-run:未写盘;apply=True 才写分离边" if not apply
578
+ else f"已写 {len(written)} 对对称分离边")}
579
+
580
+
581
+ # ==========================================================================
582
+ # 情景重构(insight.reconstruct)
583
+ # ==========================================================================
584
+ #
585
+ # 问题:记忆被检索回来时,往往只剩一条「结论」,它当时**为什么成立**(生效条件 /
586
+ # 不适用条件 / 同行情境)已经散落在相邻节点里。情景重构做的就是:由给定线索
587
+ # (词面 / 节点 id)反推当时的**条件空间**,把散落的场景要素重新聚在一起。
588
+ #
589
+ # 与检索(read/route)的区别:检索按「当前查询」做资格判定;重构按「线索」做
590
+ # **条件空间复原**,输出条件结构而非排序结果,用于回答「这件事成立于什么条件」。
591
+ #
592
+ # 诚实边界:
593
+ # · 重构是条件空间的**近似重建**,不是事件回放(输出显式标注);
594
+ # · 定位不到任何锚点时判 blindspot,**不得凭空编造条件空间**。
595
+
596
+ RECON_MIN_SCORE = 0.15 # 词面命中下限(低于此不算锚点)
597
+ RECON_MAX_NODES = 80 # 单次扫描节点上限(防 O(N) 读盘爆炸)
598
+ RECON_MAX_ANCHORS = 12 # 锚点上限
599
+ RECON_NEIGHBOR_LIMIT = 24 # 每锚点取的邻居上限
600
+ RECON_COMMON_SHARE = 0.5 # 共同条件判定:≥ 半数锚点共享
601
+ RECON_SCENE_PREFIX = "scene_"
602
+
603
+
604
+ # 生效条件:clues 为 None 时返回 [];clues 为 str 时包装成单元素列表;逐项取 str(c or "").strip().lower(),空串跳过,整串去重入 out,再按 re.split(r"[\s,,、;;/|]+") 切词、去重后追加;返回 out;
605
+ def _clue_terms(clues):
606
+ """线索归一化:字符串 / 列表 → 去重词面(保留整串 + 切分后的词)。"""
607
+ if clues is None:
608
+ return []
609
+ if isinstance(clues, str):
610
+ clues = [clues]
611
+ out = []
612
+ for c in clues:
613
+ s = str(c or "").strip().lower()
614
+ if not s:
615
+ continue
616
+ if s not in out:
617
+ out.append(s)
618
+ for w in re.split(r"[\s,,、;;/|]+", s):
619
+ w = w.strip()
620
+ if w and w not in out:
621
+ out.append(w)
622
+ return out
623
+
624
+
625
+ # 生效条件:term_sets 为假值(None/[])时返回 [];否则对每个集合的 set(s or ()) 统计词面出现次数,need = max(2, int(len(term_sets)*RECON_COMMON_SHARE) 向上取整),返回出现次数 >= need 的词面排序列表(阈值取自模块常量 RECON_COMMON_SHARE);
626
+ def _shared_terms(term_sets):
627
+ """出现在 ≥ RECON_COMMON_SHARE 比例集合中的词面(且至少 2 个集合共享)。"""
628
+ if not term_sets:
629
+ return []
630
+ cnt = {}
631
+ for s in term_sets:
632
+ for t in set(s or ()):
633
+ cnt[t] = cnt.get(t, 0) + 1
634
+ need = max(2, int(len(term_sets) * RECON_COMMON_SHARE) + (1 if len(term_sets) * RECON_COMMON_SHARE % 1 else 0))
635
+ return sorted(t for t, c in cnt.items() if c >= need)
636
+
637
+
638
+ # 生效条件:按 term_sets 原顺序遍历每个集合的 sorted(s or ()),首次出现的词面追加到 seen,返回 seen[:limit](limit 默认 99,传 0 时切片为空列表,无 or 回落);
639
+ def _uniq_terms(term_sets, limit=99):
640
+ seen = []
641
+ for s in term_sets:
642
+ for t in sorted(s or ()):
643
+ if t not in seen:
644
+ seen.append(t)
645
+ return seen[:limit]
646
+
647
+
648
+ # 生效条件:bigrams(" ".join(clue_terms)) 为空时返回 [];否则遍历 pool,cg.get(nid) 为假值、或 forgetting.payload 后 bigrams 为空、或与 clue_grams 无交集时跳过,否则 jac=inter/len(并集 or 1)、exact 为 clue_terms 中非空且作为子串出现在 body 的个数,score=jac+0.05*exact,仅 score >= RECON_MIN_SCORE 才收录,最终按 (-score, nid) 排序返回;
649
+ def _anchor_scores(cg, pool, clue_terms):
650
+ """按词面重合给候选锚点打分(返回 [(nid, score, shared, exact)],降序)。"""
651
+ from . import forgetting
652
+ from .mdcg import bigrams
653
+ clue_grams = bigrams(" ".join(clue_terms))
654
+ if not clue_grams:
655
+ return []
656
+ scored = []
657
+ for nid in pool:
658
+ node = cg.get(nid)
659
+ if not node:
660
+ continue
661
+ body = forgetting.payload(node.get("content") or "")
662
+ grams = bigrams(body)
663
+ if not grams:
664
+ continue
665
+ inter = len(grams & clue_grams)
666
+ if not inter:
667
+ continue
668
+ jac = inter / float(len(grams | clue_grams) or 1)
669
+ exact = sum(1 for t in clue_terms if t and t in body)
670
+ score = jac + 0.05 * exact
671
+ if score >= RECON_MIN_SCORE:
672
+ scored.append((nid, round(score, 4), inter, exact))
673
+ scored.sort(key=lambda x: (-x[1], x[0]))
674
+ return scored
675
+
676
+
677
+ # 生效条件:对 anchor_ids 中每个 nid 合成条件空间——加密档锚点不读正文条件词(per 记空集、不进 pos_sets/neg_sets),其余取 fm 与 consistency.condition_terms 得 pos/neg,per[nid] 记为 {"effective": sorted(pos)[:8], "non_applicable": sorted(neg)[:8]};返回 common=_shared_terms(pos_sets)、individual=_uniq_terms(pos_sets) 中不在 common 的项、non_applicable=_uniq_terms(neg_sets)、declared=list(declared_terms or [])、per_anchor=per、sensitivity=derive_sensitivity(cg, anchor_ids);
678
+ def _condition_space(cg, anchor_ids, declared_terms=None):
679
+ """合成锚点群的条件空间:共同条件 / 个别条件 / 不适用条件 / 逐锚点明细。"""
680
+ from . import consistency, crypto
681
+ pos_sets, neg_sets, per = [], [], {}
682
+ for nid in anchor_ids:
683
+ e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(nid) or {}
684
+ sens = _sensitivity_of(e)
685
+ if crypto.is_encrypted_level(sens): # v0.9.0:加密档判定走单点谓词
686
+ per[nid] = {"effective": [], "non_applicable": []}
687
+ continue
688
+ node = cg.get(nid)
689
+ if not node:
690
+ continue
691
+ fm = node.get("frontmatter") or {}
692
+ pos, neg = consistency.condition_terms(fm, node.get("content") or "")
693
+ pos_sets.append(pos)
694
+ neg_sets.append(neg)
695
+ per[nid] = {"effective": sorted(pos)[:8], "non_applicable": sorted(neg)[:8]}
696
+ common = _shared_terms(pos_sets)
697
+ individual = [t for t in _uniq_terms(pos_sets) if t not in common]
698
+ return {"common": common, "individual": individual,
699
+ "non_applicable": _uniq_terms(neg_sets),
700
+ "declared": list(declared_terms or []), "per_anchor": per,
701
+ "sensitivity": derive_sensitivity(cg, anchor_ids)}
702
+
703
+
704
+ # 生效条件:以 cg.index["nodes"] 为节点池(layer 为真时只保留 layer 等于该值的节点,池按 max_nodes 截断),由 clues 词项与 ids 收集锚点并截取 limit 个,锚点为空则返回 status="blindspot" 且 condition_space=None,否则返回 status="reconstructed"(neighbors 为真时按链邻接补边并在 max_nodes 内补节点,apply 为真且算出的 scene_id 尚不在 nodes 中时再写入该情境节点并记日志);
705
+ def reconstruct_scene(cg, clues=None, ids=None, conditions=None, layer=None,
706
+ max_nodes=RECON_MAX_NODES, limit=RECON_MAX_ANCHORS,
707
+ neighbors=True, apply=False, actor="insight"):
708
+ """情景重构:由线索反推条件空间,还原记忆成立的场景。
709
+
710
+ 只读(apply=False 默认);apply=True 额外落一个 `scene_<hash>` 情境节点,
711
+ 携带 `reconstructed_from` 锚点与 inferred 边,便于追溯与撤销。
712
+
713
+ 返回 status ∈ {"reconstructed", "blindspot"};blindspot 时条件空间为 None,
714
+ 不编造(对应计划「诚实边界」)。
715
+ """
716
+ from . import chain
717
+ t0 = time.time()
718
+ nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
719
+ clue_terms = _clue_terms(clues)
720
+ declared = [str(c).strip().lower() for c in (conditions or []) if str(c).strip()]
721
+ want_ids = [str(x) for x in (ids or []) if str(x).strip()]
722
+
723
+ # 线索里若直接写了节点 id,也算显式锚点
724
+ for t in clue_terms:
725
+ if t in nodes and t not in want_ids:
726
+ want_ids.append(t)
727
+
728
+ pool = [nid for nid, e in list(nodes.items())
729
+ if (not layer or (e or {}).get("layer") == layer)]
730
+ truncated = len(pool) > int(max_nodes)
731
+ pool.sort()
732
+ pool = pool[:int(max_nodes)]
733
+
734
+ anchors, missing = [], []
735
+ for nid in want_ids:
736
+ if nid in nodes:
737
+ anchors.append({"node_id": nid, "score": 1.0, "source": "explicit"})
738
+ else:
739
+ missing.append(nid)
740
+ if clue_terms:
741
+ have = {a["node_id"] for a in anchors}
742
+ for nid, score, inter, exact in _anchor_scores(cg, pool, clue_terms):
743
+ if nid in have:
744
+ continue
745
+ anchors.append({"node_id": nid, "score": score, "source": "lexical",
746
+ "shared_bigrams": inter, "exact_hits": exact})
747
+ have.add(nid)
748
+ anchors = anchors[:int(limit)]
749
+
750
+ base = {"ok": True, "action": "reconstruct", "op": "insight",
751
+ "clues": clue_terms, "requested_ids": want_ids, "layer": layer,
752
+ "truncated": truncated, "scanned": len(pool)}
753
+
754
+ if not anchors:
755
+ base.update({
756
+ "status": "blindspot", "anchors": [], "nodes": [], "edges": [],
757
+ "condition_space": None,
758
+ "missing": missing or (["锚点"] if clue_terms else ["线索"]),
759
+ "elapsed_ms": int((time.time() - t0) * 1000),
760
+ "note": "线索未能定位任何锚点:判 blindspot,不编造条件空间(诚实边界)"})
761
+ return base
762
+
763
+ anchor_ids = [a["node_id"] for a in anchors]
764
+ node_ids, edges = list(anchor_ids), []
765
+ if neighbors:
766
+ adj = {}
767
+ try:
768
+ adj = chain.adjacency(cg)
769
+ except Exception:
770
+ adj = {}
771
+ seen = set(node_ids)
772
+ for nid in anchor_ids:
773
+ outs = (adj.get(nid) or [])[:RECON_NEIGHBOR_LIMIT]
774
+ for tgt, e in outs:
775
+ rel = chain.edge_rel(e)
776
+ edges.append({"from": nid, "to": tgt, "relation": rel,
777
+ "evidence": (e or {}).get("evidence")})
778
+ if tgt not in seen and len(node_ids) < int(max_nodes):
779
+ seen.add(tgt)
780
+ node_ids.append(tgt)
781
+
782
+ cs = _condition_space(cg, anchor_ids, declared_terms=declared)
783
+ separated = [nid for nid in anchor_ids
784
+ if any(e.get("relation") == "distinct_from" for e in edges
785
+ if e.get("from") == nid)]
786
+ with_conditions = sum(1 for nid in anchor_ids
787
+ if (cs["per_anchor"].get(nid) or {}).get("effective"))
788
+ confidence = round(
789
+ min(1.0, (sum(a["score"] for a in anchors) / float(len(anchors)))
790
+ * (0.5 + 0.5 * with_conditions / float(len(anchor_ids)))), 4)
791
+
792
+ out = dict(base)
793
+ out.update({
794
+ "status": "reconstructed", "anchors": anchors, "nodes": node_ids,
795
+ "edges": edges, "condition_space": cs,
796
+ "signals": {"anchors": len(anchors), "with_conditions": with_conditions,
797
+ "separated": separated},
798
+ "confidence": confidence,
799
+ "elapsed_ms": int((time.time() - t0) * 1000),
800
+ "note": "条件空间的近似重建(非事件回放);common=共同生效条件,"
801
+ "individual=个别条件,non_applicable=不适用条件"})
802
+
803
+ if apply:
804
+ sid = RECON_SCENE_PREFIX + hashlib.sha1(
805
+ "|".join(sorted(node_ids)).encode("utf-8")).hexdigest()[:10]
806
+ written = False
807
+ sens = cs.get("sensitivity")
808
+ if sens is None:
809
+ append_jsonl(os.path.join(cg.root, MAINTAIN_LOG), {
810
+ "t": time.time(), "action": "reconstruct", "scene": None,
811
+ "anchors": list(anchor_ids), "clues": clue_terms,
812
+ "reason": "sensitivity_not_judgeable", "actor": actor})
813
+ elif sid not in nodes:
814
+ common_txt = ";".join(cs["common"][:6]) or "(未提炼出共同条件)"
815
+ neg_txt = ";".join(cs["non_applicable"][:6]) or "(未判定)"
816
+ body = (
817
+ "# 功能名:情景重构:%s\n"
818
+ "# 生效条件:%s\n"
819
+ "# 子功能:由 %d 个锚点复原的条件空间(锚点:%s)\n"
820
+ "# 执行:由 insight.reconstruct 反推(inferred 近似重建,非事件回放)\n"
821
+ "# 验证方式:待验证(推断结果,需人工/实践核对后方可升格)\n"
822
+ "# 不适用条件:%s\n"
823
+ % ("、".join(clue_terms[:6]) or "线索", common_txt, len(anchor_ids),
824
+ "、".join(anchor_ids), neg_txt))
825
+ cg.add(sid, body, layer="contextual",
826
+ tags=["scene", "reconstructed"], importance=0.4,
827
+ verification_basis="other", sensitivity=sens,
828
+ reconstructed_from=list(anchor_ids),
829
+ clues=list(clue_terms), confidence=confidence,
830
+ actor=actor)
831
+ try:
832
+ from . import security as _sec
833
+ _high = _sec._rank(str(sens)) > _sec._rank(_sec.DEFAULT_SENSITIVITY)
834
+ except Exception:
835
+ _high = False
836
+ if _high:
837
+ append_jsonl(os.path.join(cg.root, MAINTAIN_LOG), {
838
+ "t": time.time(), "action": "reconstruct", "scene": sid,
839
+ "anchors": list(anchor_ids), "clues": clue_terms,
840
+ "common": [], "condition_terms_withheld": True,
841
+ "confidence": confidence, "actor": actor})
842
+ else:
843
+ append_jsonl(os.path.join(cg.root, MAINTAIN_LOG), {
844
+ "t": time.time(), "action": "reconstruct", "scene": sid,
845
+ "anchors": list(anchor_ids), "clues": clue_terms,
846
+ "common": cs["common"], "confidence": confidence, "actor": actor})
847
+ invalidate_cache(cg)
848
+ written = True
849
+ out["scene_id"] = sid
850
+ out["scene_written"] = written
851
+ return out