@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/postings.py CHANGED
@@ -1,300 +1,524 @@
1
- # -*- coding: utf-8 -*-
2
- """倒排(发布表)候选层:不读遍全库即可取「词法候选」。
3
-
4
- 为何需要(实测依据:docs/hive/真实库端到端实测_S1b与召回权衡_v0.1.md):
5
- S1b 桶收敛能少扫 5.5~10.4 倍,但**召回集合会变**(真实库一致率仅 1/4)。要两全,
6
- 必须有「廉价高精度候选生成器」——即本模块:把「字符 bigram → 节点」做成发布表,
7
- 查询时按 bigram 交集取候选,再用既有 `_like` 精确过滤,从而**召回与全表扫描一致**。
8
-
9
- 设计要点:
10
- 1. 索引对象 = 节点 **content + tags** 的字符 bigram(与打分口径同源:mdcg.bigrams/normalize_en)。
11
- 2. 查询侧:对每个查询词 t(len ≥ 2)取 t 的 bigram 集合在发布表中的**交集**;
12
- 这些节点必然包含 t 的全部 bigram(是「包含 t」的超集,可能跨词假阳性);
13
- 各词取并集 → 候选 ⊇ 真命中集 → 再用 `_like` 精确过滤 → 结果与全表扫描一致。
14
- 3. 单字查询词无法用 bigram 表达 → 该查询**回退全量**(安全,记 reason)。
15
- 4. 发布表是**快照**:节点被改写后即过期。故 build 记录**快照指纹**(节点数 + 节点目录
16
- mtime + 索引文件 mtime),查询前先验指纹;过期即**回退全量**(宁可慢,不可丢召回)。
17
- 指纹只用 stat(约等于「目录数」次,本库 1,074 个目录 ≈ 0.03s),不重读节点。
18
- 5. 存储:`<root>/_postings.json`({bigram: [id,...]})+ `<root>/_postings_meta.json`(版本/规模/指纹)。
19
- 6. 位置:只作**候选生成器**(契约 §7 允许的「候选内加速」),不替代认知路径。
20
- 7. v1 不接写入路径的增量维护(每次写都 load+save 75MB 不可接受):**改写后请重建**;
21
- 重建是幂等且无副作用的(不改任何节点内容)。增量(dirty 集)为下一里程碑。
22
- """
23
- import io
24
- import json
25
- import os
26
- import time
27
-
28
- from .fsutil import publish
29
-
30
- SCHEMA = "mdcg-postings-2"
31
-
32
-
33
- # 生效条件:root 为真值时返回 root 下 postings 数据文件路径,否则返回 "_postings.json"(相对路径)。
34
- def postings_path(root: str) -> str:
35
- return os.path.join(root or "", "_postings.json")
36
-
37
-
38
- # 生效条件:root 为真值时返回 root 下 postings 元数据文件路径,否则返回 "_postings_meta.json"。
39
- def meta_path(root: str) -> str:
40
- return os.path.join(root or "", "_postings_meta.json")
41
-
42
-
43
- # 生效条件:无条件以 utf-8 惰性引入 mdcg 的 bigrams/normalize_en 并返回;导入失败返回 (None, None)。
44
- def _bigrams_fn():
45
- try:
46
- from .mdcg import bigrams, normalize_en
47
- return bigrams, normalize_en
48
- except Exception:
49
- return None, None
50
-
51
-
52
- # 生效条件:path 可 stat 时返回 st_mtime_ns(int),否则返回 None。
53
- def _mtime_ns(path: str):
54
- try:
55
- return os.stat(path).st_mtime_ns
56
- except OSError:
57
- return None
58
-
59
-
60
- # 生效条件:text 与 tags 均为假值时返回空集合;否则返回二者(tags 以空格拼接)经 normalize_en 后的 bigram 并集;
61
- # bigrams/normalize_en 不可用时返回空集合。
62
- def ngrams(text, tags=None) -> set:
63
- """节点侧取词:content + tags 的字符 bigram 集合(与打分同源)。"""
64
- bigrams, normalize_en = _bigrams_fn()
65
- if bigrams is None:
66
- return set()
67
- buf = str(text or "")
68
- if tags:
69
- buf += " " + " ".join(str(t) for t in tags)
70
- if not buf.strip():
71
- return set()
72
- return set(bigrams(normalize_en(buf)))
73
-
74
-
75
- # 生效条件:terms 为假值时返回([],'empty_terms');任一词的 normalize_en 结果长度 < 2 时返回([],'single_char_term');
76
- # 否则返回([每词 bigram 集合],''),供 candidates 逐词取交集。
77
- def term_ngram_sets(terms):
78
- """查询侧取词:把每个查询词转成 bigram 集合;含单字词则整体不可用(安全回退)。"""
79
- bigrams, normalize_en = _bigrams_fn()
80
- if not terms:
81
- return [], "empty_terms"
82
- if bigrams is None or normalize_en is None:
83
- return [], "no_bigram_fn"
84
- sets = []
85
- for t in terms:
86
- nt = normalize_en(str(t))
87
- if len(nt) < 2:
88
- return [], "single_char_term"
89
- sets.append(set(bigrams(nt)))
90
- return sets, ""
91
-
92
-
93
- # 生效条件:index_nodes 为 dict 时返回 {"nodes": 节点数, "dir_mtimes": {相对目录: mtime_ns}, "index_mtime": 索引文件 mtime_ns};
94
- # 假值时返回 {"nodes": 0, "dir_mtimes": {}, "index_mtime": None}。
95
- def snapshot(root: str, index_nodes) -> dict:
96
- """快照指纹:节点数 + 各节点目录 mtime + 索引文件 mtime。
97
-
98
- 为何用目录 mtime:节点写入走 fsutil.atomic_write(temp + os.replace),
99
- 目录 mtime 必然变化,故「目录 mtime + 节点数」能以 O(目录数) 次 stat
100
- 发现「发布表已过期」,无需重读/重哈希任何节点文件。
101
- """
102
- dirs, files = set(), {}
103
- for e in (index_nodes or {}).values():
104
- p = (e or {}).get("path") or ""
105
- d = os.path.dirname(p)
106
- if d:
107
- dirs.add(d)
108
- elif p:
109
- # 根级节点(path 无目录)不能靠「根目录 mtime」判定:我们自己写的
110
- # _postings.json / _postings_meta.json 就在根目录,会把根目录 mtime 改掉
111
- # → 快照刚建就自判过期(独立复核 2026-09-19 指出)。改为逐文件记 mtime。
112
- files[p] = _mtime_ns(os.path.join(root or "", p))
113
- return {"nodes": len(index_nodes or {}),
114
- "dir_mtimes": {d: _mtime_ns(os.path.join(root or "", d)) for d in dirs},
115
- "file_mtimes": files,
116
- "index_mtime": _mtime_ns(os.path.join(root or "", "_index.json"))}
117
-
118
-
119
- # 生效条件:meta 非 dict 或 schema 不符 → 'no_meta'(无数据文件时 'no_index');无 snapshot → 'no_snapshot';
120
- # 节点数 / 目录集合 / 目录 mtime / 根级文件集合 / 根级文件 mtime / 索引 mtime 任一不一致 → 对应 reason;
121
- # 全部一致 → ''(空串,代表新鲜可用)。index_nodes 为假值时返回 'no_index'。
122
- def stale_reason(root: str, index_nodes, meta=None) -> str:
123
- """返回 '' 表示快照仍与当前索引一致;否则返回过期原因(调用方必须回退全量)。"""
124
- if not index_nodes:
125
- return "no_index"
126
- if meta is None:
127
- meta = load_meta(root)
128
- if not isinstance(meta, dict) or meta.get("schema") != SCHEMA:
129
- return "no_meta" if os.path.exists(postings_path(root)) else "no_index"
130
- snap = meta.get("snapshot")
131
- if not isinstance(snap, dict):
132
- return "no_snapshot"
133
- if snap.get("nodes") != len(index_nodes):
134
- return "node_count_changed"
135
- want = snap.get("dir_mtimes") or {}
136
- dirs_now = set()
137
- for e in index_nodes.values():
138
- d = os.path.dirname((e or {}).get("path") or "")
139
- if d:
140
- dirs_now.add(d) # 根级路径(无目录)由 file_mtimes 记账,见下
141
- if set(want.keys()) != dirs_now:
142
- return "dirs_changed"
143
- for d, mt in want.items():
144
- if _mtime_ns(os.path.join(root or "", d)) != mt:
145
- return "dir_touched"
146
- want_files = snap.get("file_mtimes") or {}
147
- files_now = set()
148
- for e in index_nodes.values():
149
- p = (e or {}).get("path") or ""
150
- if p and not os.path.dirname(p):
151
- files_now.add(p)
152
- if set(want_files.keys()) != files_now:
153
- return "root_files_changed"
154
- for p, mt in want_files.items():
155
- if _mtime_ns(os.path.join(root or "", p)) != mt:
156
- return "root_file_touched"
157
- if snap.get("index_mtime") != _mtime_ns(os.path.join(root or "", "_index.json")):
158
- return "index_touched"
159
- return ""
160
-
161
-
162
- # 生效条件:无条件读 root/_postings_meta.json 并返回 dict(缺文件/解析失败/非 dict 一律返回 {})。
163
- def load_meta(root: str) -> dict:
164
- try:
165
- with io.open(meta_path(root), encoding="utf-8") as f:
166
- m = json.load(f)
167
- return m if isinstance(m, dict) else {}
168
- except Exception:
169
- return {}
170
-
171
-
172
- # 生效条件:无条件以 utf-8 原子写 path(tmp + publish,即带 Windows 短重试的 os.replace),写入的字符串为 obj 的 JSON 序列化。
173
- def _atomic_json(path: str, obj, indent=None) -> None:
174
- tmp = path + ".tmp"
175
- with io.open(tmp, "w", encoding="utf-8", newline=chr(10)) as f:
176
- json.dump(obj, f, ensure_ascii=False, indent=indent, separators=None if indent else (",", ":"))
177
- publish(tmp, path)
178
-
179
-
180
- # 生效条件:无条件读 root/_postings.json 并返回 dict(缺文件/解析失败返回 {};内容非 dict 亦返回 {})。
181
- def load(root: str) -> dict:
182
- p = postings_path(root)
183
- try:
184
- with io.open(p, encoding="utf-8") as f:
185
- t = json.load(f)
186
- return t if isinstance(t, dict) else {}
187
- except Exception:
188
- return {}
189
-
190
-
191
- _CACHE = {}
192
-
193
-
194
- # 生效条件:root/postings 为假值返回 {};否则按 (路径, mtime, size) 缓存命中则返回缓存表,未命中则 load 后写入缓存并返回。
195
- def load_cached(root: str) -> dict:
196
- p = postings_path(root)
197
- try:
198
- st = os.stat(p)
199
- except OSError:
200
- return {}
201
- key = (p, st.st_mtime_ns, st.st_size)
202
- hit = _CACHE.get(p)
203
- if hit and hit[0] == key:
204
- return hit[1]
205
- t = load(root)
206
- _CACHE[p] = (key, t)
207
- return t
208
-
209
-
210
- # 生效条件:cg 为假值或取不到 index["nodes"] 时返回 {"nodes":0,"terms":0,"postings":0,"rebuilt":False};
211
- # 否则遍历 index 逐节点取 content+tags 的 bigram、按 id 去重累积,先写数据表、再取快照指纹并写元数据,
212
- # 返回含 nodes/terms/postings/rebuild=True/snapshot 的 stats。limit 为真值时最多处理 limit 个节点。
213
- def build(cg, limit: int = None) -> dict:
214
- """全量重建发布表(幂等、不改节点内容)。"""
215
- nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
216
- if not nodes:
217
- return {"nodes": 0, "terms": 0, "postings": 0, "rebuilt": False}
218
- table = {}
219
- n = 0
220
- for nid, e in list(nodes.items()):
221
- if limit and n >= limit:
222
- break
223
- got = cg.get(nid)
224
- if not got:
225
- continue
226
- gs = ngrams(got.get("content"), got.get("frontmatter", {}).get("tags"))
227
- if not gs:
228
- continue
229
- for g in gs:
230
- table.setdefault(g, []).append(nid)
231
- n += 1
232
- stats = {"schema": SCHEMA, "built_at": int(time.time()), "nodes": n,
233
- "terms": len(table), "postings": sum(len(v) for v in table.values())}
234
- _atomic_json(postings_path(cg.root), table)
235
- if limit:
236
- # 抽样构建(冒烟用)只索引了部分节点 —— **绝不能**留下看似新鲜的快照,
237
- # 否则未索引的节点会被静默漏召回。无 snapshot → stale_reason 判 'no_snapshot'。
238
- stats["partial"] = True
239
- else:
240
- # 快照指纹必须在写完数据文件之后取:否则 root 目录自身的 mtime 会被本次写入改掉。
241
- stats["snapshot"] = snapshot(cg.root, nodes)
242
- _atomic_json(meta_path(cg.root), stats, indent=1)
243
- return dict(stats, rebuilt=True)
244
-
245
-
246
- # 生效条件:无条件把 node_id 追加进 table 中每个 bigram 的列表(bigram 不存在则新建列表),返回追加的 bigram 个数。
247
- def add_to_table(table: dict, node_id, text, tags=None) -> int:
248
- """增量维护:把某节点的 bigram 追加进表(调用方负责持久化)。v1 未接入写入路径。"""
249
- gs = ngrams(text, tags)
250
- for g in gs:
251
- table.setdefault(g, []).append(node_id)
252
- return len(gs)
253
-
254
-
255
- # 生效条件:无条件把 node_id 从 table 各列表中移除(不存在则无操作并原样返回 table),返回剩余 bigram 数。
256
- def remove_from_table(table: dict, node_id) -> int:
257
- for g in list(table.keys()):
258
- lst = table.get(g)
259
- if not lst:
260
- continue
261
- try:
262
- table[g] = [x for x in lst if x != node_id]
263
- except Exception:
264
- continue
265
- if not table[g]:
266
- table.pop(g, None)
267
- return len(table)
268
-
269
-
270
- # 生效条件:terms 为假值或任一词为单字(或 bigram 函数不可用)时返回 (None, reason);发布表为空时返回 (None,'no_index');
271
- # 否则逐词以「该词的全部 bigram 发布列表交集」取候选、各词取并集,返回 (候选 id 集合, '')。
272
- def candidates(root: str, terms):
273
- """返回 (candidate_ids | None, reason)。None 表示「不可用,调用方应回退全量」。"""
274
- sets, reason = term_ngram_sets(terms)
275
- if not sets:
276
- return None, reason or "unusable_terms"
277
- table = load_cached(root)
278
- if not table:
279
- return None, "no_index"
280
- out = set()
281
- for gs in sets:
282
- lists = [table.get(g) for g in gs]
283
- if any(x is None for x in lists):
284
- continue # 该词有 bigram 不在表里 → 该词无候选(并集里不贡献)
285
- inter = set(lists[0])
286
- for x in lists[1:]:
287
- inter &= set(x)
288
- if not inter:
289
- break
290
- out |= inter
291
- return out, ""
292
-
293
-
294
- # 生效条件:无条件统计 root 下发布表规模并返回 {"terms": 词项数, "postings": 倒排条目数, "meta": 元数据 dict 或 None};
295
- # index_nodes 为真值时附带 "stale_reason"('' 表示新鲜),否则该项为 None。
296
- def stats(root: str, index_nodes=None) -> dict:
297
- t = load_cached(root)
298
- meta = load_meta(root) or None
299
- return {"terms": len(t), "postings": sum(len(v) for v in t.values()), "meta": meta,
300
- "stale_reason": (stale_reason(root, index_nodes, meta) if index_nodes is not None else None)}
1
+ # -*- coding: utf-8 -*-
2
+ """倒排(发布表)候选层:不读遍全库即可取「词法候选」。
3
+
4
+ 为何需要(实测依据:docs/hive/真实库端到端实测_S1b与召回权衡_v0.1.md):
5
+ S1b 桶收敛能少扫 5.5~10.4 倍,但**召回集合会变**(真实库一致率仅 1/4)。要两全,
6
+ 必须有「廉价高精度候选生成器」——即本模块:把「字符 bigram → 节点」做成发布表,
7
+ 查询时按 bigram 交集取候选,再用既有 `_like` 精确过滤,从而**召回与全表扫描一致**。
8
+
9
+ 设计要点:
10
+ 1. 索引对象 = 节点 **content + tags** 的字符 bigram(与打分口径同源:mdcg.bigrams/normalize_en)。
11
+ 2. 查询侧:对每个查询词 t(len ≥ 2)取 t 的 bigram 集合在发布表中的**交集**;
12
+ 这些节点必然包含 t 的全部 bigram(是「包含 t」的超集,可能跨词假阳性);
13
+ 各词取并集 → 候选 ⊇ 真命中集 → 再用 `_like` 精确过滤 → 结果与全表扫描一致。
14
+ 3. 单字查询词无法用 bigram 表达 → 该查询**回退全量**(安全,记 reason)。
15
+ 4. 发布表是**快照**:节点被改写后即过期。故 build 记录**快照指纹**(节点数 + 节点目录
16
+ mtime + 索引文件 mtime),查询前先验指纹;过期即**回退全量**(宁可慢,不可丢召回)。
17
+ 指纹只用 stat(约等于「目录数」次,本库 1,074 个目录 ≈ 0.03s),不重读节点。
18
+ 5. 存储:`<root>/_postings.json`({bigram: [id,...]})+ `<root>/_postings_meta.json`(版本/规模/指纹)。
19
+ 6. 位置:只作**候选生成器**(契约 §7 允许的「候选内加速」),不替代认知路径。
20
+ 7. v1 不接写入路径的增量维护(每次写都 load+save 75MB 不可接受):**改写后请重建**;
21
+ 重建是幂等且无副作用的(不改任何节点内容)。增量(dirty 集)为下一里程碑。
22
+ """
23
+ import hashlib
24
+ import io
25
+ import json
26
+ import os
27
+ import sys
28
+ import time
29
+
30
+ from .fsutil import publish
31
+
32
+ SCHEMA = "mdcg-postings-2"
33
+
34
+
35
+ # 生效条件:root 为真值时返回 root 下 postings 数据文件路径,否则返回 "_postings.json"(相对路径)。
36
+ def postings_path(root: str) -> str:
37
+ return os.path.join(root or "", "_postings.json")
38
+
39
+
40
+ # 生效条件:root 为真值时返回 root 下 postings 元数据文件路径,否则返回 "_postings_meta.json"。
41
+ def meta_path(root: str) -> str:
42
+ return os.path.join(root or "", "_postings_meta.json")
43
+
44
+
45
+ # 生效条件:无条件以 utf-8 惰性引入 mdcg 的 bigrams/normalize_en 并返回;导入失败返回 (None, None)。
46
+ def _bigrams_fn():
47
+ try:
48
+ from .mdcg import bigrams, normalize_en
49
+ return bigrams, normalize_en
50
+ except Exception:
51
+ return None, None
52
+
53
+
54
+ # 生效条件:path 可 stat 时返回 st_mtime_ns(int),否则返回 None。
55
+ def _mtime_ns(path: str):
56
+ try:
57
+ return os.stat(path).st_mtime_ns
58
+ except OSError:
59
+ return None
60
+
61
+
62
+ # 生效条件:text 与 tags 均为假值时返回空集合;否则返回二者(tags 以空格拼接)经 normalize_en 后的 bigram 并集;
63
+ # bigrams/normalize_en 不可用时返回空集合。
64
+ def ngrams(text, tags=None) -> set:
65
+ """节点侧取词:content + tags 的字符 bigram 集合(与打分同源)。"""
66
+ bigrams, normalize_en = _bigrams_fn()
67
+ if bigrams is None:
68
+ return set()
69
+ buf = str(text or "")
70
+ if tags:
71
+ buf += " " + " ".join(str(t) for t in tags)
72
+ if not buf.strip():
73
+ return set()
74
+ return set(bigrams(normalize_en(buf)))
75
+
76
+
77
+ # 生效条件:terms 为假值时返回([],'empty_terms');任一词的 normalize_en 结果长度 < 2 时返回([],'single_char_term');
78
+ # 否则返回([每词 bigram 集合],''),供 candidates 逐词取交集。
79
+ def term_ngram_sets(terms):
80
+ """查询侧取词:把每个查询词转成 bigram 集合;含单字词则整体不可用(安全回退)。"""
81
+ bigrams, normalize_en = _bigrams_fn()
82
+ if not terms:
83
+ return [], "empty_terms"
84
+ if bigrams is None or normalize_en is None:
85
+ return [], "no_bigram_fn"
86
+ sets = []
87
+ for t in terms:
88
+ nt = normalize_en(str(t))
89
+ if len(nt) < 2:
90
+ return [], "single_char_term"
91
+ sets.append(set(bigrams(nt)))
92
+ return sets, ""
93
+
94
+
95
+ # 生效条件:fp 为可读文件路径时返回其**整文件字节**的 sha256 十六进制前 16 位;open/read 抛 OSError 时返回 None(读不到即「证不出」,调用方按内容层判据收口);不缓存、不解析、不看扩展名。
96
+ def _file_digest(fp: str):
97
+ """节点文件的**整字节身份指纹**(#131;口径与 `mdcg._file_digest` /
98
+ `refindex._sha256_file` 同源——身份由字节定,不由时间戳定)。
99
+
100
+ 为什么必须与目录 mtime 并置:目录 mtime 只在**直接子项增删**时变化,
101
+ **同目录内容级改写**(就地追写、备份还原、同步盘回写、人手编辑)不动它。
102
+ 实测(issue #131):就地给节点正文追加一个词后目录 mtime 逐位不变
103
+ (1791742330453756100 → 1791742330453756100),而**文件** mtime 与 size
104
+ 都变了;旧判据只 stat 目录 ⇒ `stale_reason` 判「新鲜」,S7 放心用旧表
105
+ 收窄、把只在新正文里出现的真命中**整条剔掉**(静默丢召回)。
106
+
107
+ 为什么还要第三元 sha256(而不是只比文件的 mtime_ns + size):**mtime 可被
108
+ 还原**——cp -p / rsync -t / tar x / robocopy /DCOPY:T / 备份还原 / 网盘同步
109
+ 客户端回写原 mtime;粗粒度文件系统(FAT 2s、ext3 1s)下同刻度写入更是常态。
110
+ 届时一次**等长**改写同时满足 size 相等与 mtime 相等 ⇒ 身份失配判不出来。
111
+ 故 (mtime_ns, size) 失配即判陈旧(零额外 IO),**双双相等时再比内容哈希**
112
+ ——与 `mdcg._note_witness`(#80)同一范式、同一口径。
113
+
114
+ 截 16 位:与全仓 sha256 系列(`mdcg._file_digest` 截 16、`refindex`
115
+ 截 64)同族;本判据只做同/异比较、不做安全承诺。
116
+ """
117
+ try:
118
+ with open(fp, "rb") as f:
119
+ return hashlib.sha256(f.read()).hexdigest()[:16]
120
+ except OSError:
121
+ return None
122
+
123
+
124
+ # ---- issue #178:内容指纹按 stat 身份记忆化(把整文件读盘从检索热路径上摘掉)----
125
+ # 键 = 节点文件绝对路径;值 = (st_mtime_ns, st_size, st_ctime_ns, digest)。
126
+ _DIGEST_MEMO = {}
127
+ #: 记忆表条目上界(越界即整表 clear(),避免进程内无界增长)。
128
+ _DIGEST_MEMO_MAX = 4096
129
+
130
+ #: `st_ctime` 是否等价于「inode 状态变更时间」(**记忆表命中判据的前提**)。
131
+ #:
132
+ #: ★平台差异(本笔修正的根因):`os.stat().st_ctime` 的**含义随平台而异**——
133
+ #: · POSIX(Linux/macOS):**最近一次元数据变更时间**,内容改写必使其变化
134
+ #: ⇒ (mtime_ns, size, ctime_ns) 三元组可作内容身份。
135
+ #: · **Windows:文件创建时间**,内容改写**不**使其变化
136
+ #: ⇒ 三元组退化为 (mtime_ns, size),而二者都可被还原/打平
137
+ #: (`cp -p` / `rsync -t` / 备份还原 / 粗粒度文件系统)⇒ **会返回过期 digest**。
138
+ #:
139
+ #: 实测(win32 / Python 3.12.14):同长度就地改写 + `os.utime` 只还原 mtime 后,
140
+ #: 三项逐位相等而两次 sha256 不同(`63c1dd95…` → `4a8d8134…`)⇒ 记忆表命中并
141
+ #: 复用旧指纹 ⇒ `stale_reason` 不报 `content_changed`,`#131` 的内容层收口被绕开。
142
+ #: 故非 POSIX 平台**禁用**该记忆表(退回逐次读盘的既有语义,宁可慢、不可给陈旧结论)。
143
+ _CTIME_IS_STATUS_CHANGE = sys.platform != "win32"
144
+
145
+
146
+ # 生效条件:st 为真值且 (st_mtime_ns, st_size, st_ctime_ns) 与记忆中的三元组逐位相等时返回记忆的 digest(不读盘);
147
+ # 否则调用既有 _file_digest(fp) 重算,结果非 None 时回填(越界先 clear())并返回;st 为 None 或 digest 为 None 时直接返回重算结果;
148
+ # **非 POSIX 平台(`_CTIME_IS_STATUS_CHANGE` 为假)一律退回无缓存路径**。
149
+ def _file_digest_memo(fp: str, st):
150
+ """带「按 stat 身份记忆化」的内容指纹(issue #178;判据语义与 _file_digest 逐位一致)。
151
+
152
+ 动机:`stale_reason` 的内容层原先**每次调用都逐节点整文件读盘 + sha256**,而它
153
+ 落在**检索热路径**上(`MdCG.search` → `_pd.stale_reason`;实测 800 节点 116ms
154
+ ≈ 146µs/节点)。而每个节点在进本层之前的快路径里已确认 (mtime_ns, size) 与快照
155
+ 逐位相等——此时内容几乎总是没变,重复读盘纯属浪费。
156
+
157
+ 为什么命中判据要加平台闸:见 `_CTIME_IS_STATUS_CHANGE` 的注释。**在 POSIX 上**
158
+ `st_ctime_ns` 是 inode 状态变更时间,用户态无法用 `utime` / `utimensat` /
159
+ `cp -p` / `rsync -t` 伪造(那些只还原 mtime)⇒ 三元组逐位相等等价于「内容自
160
+ 上次读取以来未被改动」⇒ 复用不可能返回过期 digest。**在 Windows 上 `st_ctime`
161
+ 是创建时间**,该等价关系**不成立**(已实测复现过期 digest),故禁用记忆表。
162
+
163
+ 失败不落缓存:`_file_digest` 返回 None(OSError)时不回填,避免把一次瞬时读失败
164
+ 固化成长期结论——下次调用仍会重试读盘。
165
+ """
166
+ if st is None or not _CTIME_IS_STATUS_CHANGE:
167
+ return _file_digest(fp) # 无可用 stat 身份 ⇒ 退回无缓存路径
168
+ hit = _DIGEST_MEMO.get(fp)
169
+ if (hit is not None and hit[0] == st.st_mtime_ns
170
+ and hit[1] == st.st_size and hit[2] == st.st_ctime_ns):
171
+ return hit[3]
172
+ digest = _file_digest(fp)
173
+ if digest is not None:
174
+ if len(_DIGEST_MEMO) >= _DIGEST_MEMO_MAX:
175
+ _DIGEST_MEMO.clear()
176
+ _DIGEST_MEMO[fp] = (st.st_mtime_ns, st.st_size, st.st_ctime_ns, digest)
177
+ return digest
178
+
179
+
180
+ # 生效条件:index_nodes 为 dict 时返回 {"nodes": 节点数, "dir_mtimes": {相对目录: mtime_ns}, "file_mtimes": {根级相对文件: mtime_ns}, "node_files": {相对路径: [mtime_ns, size, sha256 前16位]}, "index_mtime": 索引文件 mtime_ns};
181
+ # 假值时返回 {"nodes": 0, "dir_mtimes": {}, "file_mtimes": {}, "node_files": {}, "index_mtime": None}。
182
+ def snapshot(root: str, index_nodes) -> dict:
183
+ """快照指纹:节点数 + 各节点目录 mtime + 根级文件 mtime + **逐节点文件内容身份** + 索引文件 mtime。
184
+
185
+ 为何用目录 mtime(第一层,廉价):节点写入走 fsutil.atomic_write(temp +
186
+ os.replace),目录 mtime 必然变化,故「目录 mtime + 节点数」能以 O(目录数)
187
+ 次 stat 发现「发布表已过期」,无需重读/重哈希任何节点文件。
188
+
189
+ 为何还要 node_files(第二层,内容同源;#131):上述断言**只对走
190
+ atomic_write 的合作写者成立**。非合作写者(就地追写/备份还原/同步盘回写)
191
+ 不动目录 mtime ⇒ 第一层判不出来。本层逐节点记 (mtime_ns, size, sha256),
192
+ 与 `mdcg._note_witness` 同款口径,使判据与**被判对象(节点正文)同源**。
193
+ """
194
+ dirs, files, node_files = set(), {}, {}
195
+ for e in (index_nodes or {}).values():
196
+ p = (e or {}).get("path") or ""
197
+ if not p:
198
+ continue
199
+ d = os.path.dirname(p)
200
+ if d:
201
+ dirs.add(d)
202
+ else:
203
+ # 根级节点(path 无目录)不能靠「根目录 mtime」判定:我们自己写的
204
+ # _postings.json / _postings_meta.json 就在根目录,会把根目录 mtime 改掉
205
+ # → 快照刚建就自判过期(独立复核 2026-09-19 指出)。改为逐文件记 mtime。
206
+ files[p] = None # [#154②] 由同趟 node_files 的 stat 回填(原为再 stat 一次)
207
+ fp = os.path.join(root or "", p)
208
+ try:
209
+ st = os.stat(fp)
210
+ except OSError:
211
+ node_files[p] = [None, None, None] # 读不到即「证不出」,判据侧据此判陈旧
212
+ else:
213
+ node_files[p] = [st.st_mtime_ns, st.st_size, _file_digest(fp)]
214
+ if p in files:
215
+ files[p] = st.st_mtime_ns
216
+ return {"nodes": len(index_nodes or {}),
217
+ "dir_mtimes": {d: _mtime_ns(os.path.join(root or "", d)) for d in dirs},
218
+ "file_mtimes": files,
219
+ "node_files": node_files,
220
+ "index_mtime": _mtime_ns(os.path.join(root or "", "_index.json"))}
221
+
222
+
223
+ # 生效条件:meta 非 dict 或 schema 不符 → 'no_meta'(无数据文件时 'no_index');无 snapshot → 'no_snapshot';
224
+ # 节点数 / 目录集合 / 目录 mtime / 根级文件集合 / 根级文件 mtime / 索引 mtime 任一不一致 → 对应 reason;
225
+ # 旧快照无 node_files(内容层)→ 'no_content_snapshot';节点文件集合变化 → 'node_files_changed';
226
+ # 逐节点 stat 失败 → 'node_file_missing';文件 (mtime_ns, size) 或整文件 sha256 与快照不符 → 'content_changed';
227
+ # 全部一致 → ''(空串,代表新鲜可用)。index_nodes 为假值时返回 'no_index'。
228
+ def stale_reason(root: str, index_nodes, meta=None) -> str:
229
+ """返回 '' 表示快照仍与当前索引一致;否则返回过期原因(调用方必须回退全量)。
230
+
231
+ 判据与**被判对象同源**(#131):`_postings.json` 索引的是**节点正文 + tags**
232
+ 的字符 bigram,故新鲜度判据的最后一层必须落到**节点文件的内容身份**上。
233
+ 前几层(节点数 / 目录 mtime / 根级文件 mtime / `_index.json` mtime)只覆盖
234
+ 「合作写者」(走 atomic_write ⇒ 目录 mtime 必变)与跨进程写(`_index.json`
235
+ mtime 变化);**同进程内的就地改写**两层都漏(实测:目录 mtime 逐位不变、
236
+ `_index.json` 不变 ⇒ 旧判据返回 ''),故补 `node_files` 内容层收口。
237
+
238
+ #178(热路径去 IO):内容层原先在**每次调用**里逐节点整文件读盘 + sha256,而它
239
+ 落在检索热路径上(`MdCG.search` → `_pd.stale_reason`;实测 800 节点 116ms ≈
240
+ 146µs/节点)。现改为经 `_file_digest_memo(fp, st)` 取指纹:按 (mtime_ns, size,
241
+ **ctime_ns**) 三项 stat 身份在**进程内**记忆化,命中即复用、**不读盘**;未命中
242
+ 才读盘算 digest。判据语义、返回串、快照 schema(3 元组)**逐位不变**。
243
+
244
+ 为什么不削弱 #131:**在 POSIX 上** `st_ctime_ns` 是 **inode 状态变更时间**,用户态
245
+ **无法**用 `utime` / `utimensat` / `cp -p` / `rsync -t` 伪造——那些只还原 mtime。
246
+ 故「三项 stat 身份逐位相等」等价于「内容自上次读取以来未被改动」,复用**不可能**
247
+ 返回过期 digest;mtime 被还原、size 不变的就地改写 ⇒ **ctime 必变** ⇒ 未命中 ⇒
248
+ 重算 ⇒ 与快照不符 ⇒ 仍判 `content_changed`。
249
+
250
+ ★平台闸(本笔修正):该等价关系**只在 POSIX 成立**——**Windows 上 `st_ctime`
251
+ 是创建时间**,内容改写不使其变化。实测(win32 / Python 3.12.14)同长度就地改写
252
+ + `os.utime` 只还原 mtime 后三项逐位相等而两次 sha256 不同 ⇒ 记忆表会返回过期
253
+ digest ⇒ 本层不报 `content_changed`(即 #131 的内容层收口被绕开)。故
254
+ `_CTIME_IS_STATUS_CHANGE` 为假时 `_file_digest_memo` **退回无缓存路径**,
255
+ 本层语义回到「逐次读盘算 digest」的既有保证(只损失 #178 的性能收益)。
256
+ """
257
+ if not index_nodes:
258
+ return "no_index"
259
+ if meta is None:
260
+ meta = load_meta(root)
261
+ if not isinstance(meta, dict) or meta.get("schema") != SCHEMA:
262
+ return "no_meta" if os.path.exists(postings_path(root)) else "no_index"
263
+ snap = meta.get("snapshot")
264
+ if not isinstance(snap, dict):
265
+ return "no_snapshot"
266
+ if snap.get("nodes") != len(index_nodes):
267
+ return "node_count_changed"
268
+ want = snap.get("dir_mtimes") or {}
269
+ # [#154①] 三趟「按 index_nodes 派生集合」(目录 / 根级文件 / 节点路径)收成一趟:
270
+ # 原实现每节点算两次 os.path.dirname;本趟内 os.stat 亦记忆化——根级文件在
271
+ # file_mtimes 层与内容层会在同一次调用里各 stat 一次。判据与返回串逐位不变。
272
+ _stat_cache = {}
273
+ def _stat_of(_p):
274
+ if _p not in _stat_cache:
275
+ try:
276
+ _stat_cache[_p] = os.stat(_p)
277
+ except OSError:
278
+ _stat_cache[_p] = None
279
+ return _stat_cache[_p]
280
+ dirs_now = set()
281
+ files_now = set()
282
+ paths_now = set()
283
+ for e in index_nodes.values():
284
+ _p = (e or {}).get("path") or ""
285
+ d = os.path.dirname(_p)
286
+ if _p:
287
+ paths_now.add(_p)
288
+ if not d:
289
+ files_now.add(_p)
290
+ if d:
291
+ dirs_now.add(d) # 根级路径(无目录)由 file_mtimes 记账,见下
292
+ if set(want.keys()) != dirs_now:
293
+ return "dirs_changed"
294
+ for d, mt in want.items():
295
+ _st = _stat_of(os.path.join(root or "", d))
296
+ if (_st.st_mtime_ns if _st is not None else None) != mt:
297
+ return "dir_touched"
298
+ want_files = snap.get("file_mtimes") or {}
299
+ if set(want_files.keys()) != files_now:
300
+ return "root_files_changed"
301
+ for p, mt in want_files.items():
302
+ _st = _stat_of(os.path.join(root or "", p))
303
+ if (_st.st_mtime_ns if _st is not None else None) != mt:
304
+ return "root_file_touched"
305
+ if snap.get("index_mtime") != _mtime_ns(os.path.join(root or "", "_index.json")):
306
+ return "index_touched"
307
+ # ---- 内容层(#131):逐节点文件身份 = (mtime_ns, size) 快路径 → sha256 定身份 ----
308
+ want_nf = snap.get("node_files")
309
+ if not isinstance(want_nf, dict):
310
+ # 旧快照(本层引入前构建)无法证明「表与正文同源」——按「宁可慢,不可
311
+ # 丢召回」的既有承诺 fail-closed:判过期、回退全量(重建一次即补上本层)。
312
+ return "no_content_snapshot"
313
+ if set(want_nf.keys()) != paths_now:
314
+ return "node_files_changed"
315
+ for p, rec in want_nf.items():
316
+ fp = os.path.join(root or "", p)
317
+ st = _stat_of(fp)
318
+ if st is None:
319
+ return "node_file_missing" # 快照里有、盘上没了 ⇒ 表必过期
320
+ if not isinstance(rec, (list, tuple)) or len(rec) < 2:
321
+ return "no_content_snapshot"
322
+ if (st.st_mtime_ns, st.st_size) != (rec[0], rec[1]):
323
+ return "content_changed" # ① 快路径:时间戳/长度任一变化即陈旧
324
+ # ② 双双相等**不足以定身份**——mtime 可被还原(cp -p / rsync -t / 备份
325
+ # 还原 / 粗粒度文件系统),等长改写会同时满足两式 ⇒ 比内容哈希。
326
+ if rec[2] is None or _file_digest_memo(fp, st) != rec[2]:
327
+ return "content_changed"
328
+ return ""
329
+
330
+
331
+ # 生效条件:无条件读 root/_postings_meta.json 并返回 dict(缺文件/解析失败/非 dict 一律返回 {})。
332
+ def load_meta(root: str) -> dict:
333
+ try:
334
+ with io.open(meta_path(root), encoding="utf-8") as f:
335
+ m = json.load(f)
336
+ return m if isinstance(m, dict) else {}
337
+ except Exception:
338
+ return {}
339
+
340
+
341
+ # 生效条件:无条件以 utf-8 原子写 path(tmp + publish,即带 Windows 短重试的 os.replace),写入的字符串为 obj 的 JSON 序列化。
342
+ def _atomic_json(path: str, obj, indent=None) -> None:
343
+ tmp = path + ".tmp"
344
+ with io.open(tmp, "w", encoding="utf-8", newline=chr(10)) as f:
345
+ json.dump(obj, f, ensure_ascii=False, indent=indent, separators=None if indent else (",", ":"))
346
+ publish(tmp, path)
347
+
348
+
349
+ # 生效条件:无条件读 root/_postings.json 并返回 dict(缺文件/解析失败返回 {};内容非 dict 亦返回 {})。
350
+ def load(root: str) -> dict:
351
+ p = postings_path(root)
352
+ try:
353
+ with io.open(p, encoding="utf-8") as f:
354
+ t = json.load(f)
355
+ return t if isinstance(t, dict) else {}
356
+ except Exception:
357
+ return {}
358
+
359
+
360
+ _CACHE = {}
361
+
362
+
363
+ # 生效条件:root/postings 为假值返回 {};否则按 (路径, mtime, size) 缓存命中则返回缓存表,未命中则 load 后写入缓存并返回。
364
+ def load_cached(root: str) -> dict:
365
+ p = postings_path(root)
366
+ try:
367
+ st = os.stat(p)
368
+ except OSError:
369
+ return {}
370
+ key = (p, st.st_mtime_ns, st.st_size)
371
+ hit = _CACHE.get(p)
372
+ if hit and hit[0] == key:
373
+ return hit[1]
374
+ t = load(root)
375
+ _CACHE[p] = (key, t)
376
+ return t
377
+
378
+
379
+ # 生效条件:level 经 crypto.is_encrypted_level 判为加密档时返回 True;crypto 不可用时返回 False(与 _encrypted_levels 空集同口径)。
380
+ def _crypto_is_encrypted_level(level) -> bool:
381
+ try:
382
+ from . import crypto
383
+ except Exception:
384
+ return False
385
+ return crypto.is_encrypted_level(level)
386
+
387
+
388
+ # 生效条件:无条件惰性导入 crypto 并返回其 ENCRYPTED_LEVELS 的小写集合;crypto 不可用/无该常量时返回空集(空集=不启用密封面判据,退回旧行为)。
389
+ def _encrypted_levels() -> set:
390
+ try:
391
+ from . import crypto
392
+ return {crypto.normalize_sensitivity(x)
393
+ for x in getattr(crypto, "ENCRYPTED_LEVELS", ())} - {None}
394
+ except Exception:
395
+ return set()
396
+
397
+
398
+ # 生效条件:cg 同时具备 kek 与 dek 两个属性(即 MdCGSecure 一类挂了密钥面的实例)时返回 True,否则 False;
399
+ # 鸭子类型判定——不 import mdcos,避免 postings ← mdcg ← mdcos 的循环导入。
400
+ def _is_sealed_instance(cg) -> bool:
401
+ return hasattr(cg, "kek") and hasattr(cg, "dek")
402
+
403
+
404
+ # 生效条件:nodes 为 dict 时返回其中 entry["sensitivity"] 属加密级的 id 列表(只读索引元数据,不解密、不读正文);
405
+ # nodes 为假值、crypto 不可用或加密级集合为空时返回 []。
406
+ def _sealed_node_ids(nodes) -> list:
407
+ lv = _encrypted_levels()
408
+ if not lv or not nodes:
409
+ return []
410
+ return [nid for nid, e in (nodes or {}).items()
411
+ if _crypto_is_encrypted_level((e or {}).get("sensitivity"))]
412
+
413
+
414
+ # 生效条件:cg 为假值或取不到 index["nodes"] 时返回 {"nodes":0,"terms":0,"postings":0,"rebuilt":False};
415
+ # **密封面 fail-closed(#152①)**:索引中存在加密级节点、或本实例挂密钥面且当前可解密(dek 为真)时,
416
+ # 一律**不写任何文件**并返回 {"schema":…,"rebuilt":False,"refused":<原因>,"sealed_nodes":N,"reason":…}——
417
+ # 密文节点的明文 bigram 不得落进 <root>/_postings.json;
418
+ # 否则遍历 index 逐节点取 content+tags 的 bigram、按 id 去重累积,先写数据表、再取快照指纹并写元数据,
419
+ # 返回含 nodes/terms/postings/rebuild=True/snapshot 的 stats。limit 为真值时最多处理 limit 个节点。
420
+ def build(cg, limit: int = None) -> dict:
421
+ """全量重建发布表(幂等、不改节点内容)。
422
+
423
+ #152①(2026-10-12):**密文库拒绝构建(fail-closed)**。本函数经 `cg.get()` 取到的
424
+ 是**解密后**的 content,其明文 bigram 一旦写进 `<root>/_postings.json` 就不再随
425
+ `lock()` 收回——节点正文加密而词项索引不加密,等于把主题词表留在盘上。
426
+ 故:只要待索引面里存在加密级节点(或本实例正持密钥可解密),**不写任何文件**直接拒绝;
427
+ 调用方据返回值的 `refused` 字段判因(`sealed_nodes` / `sealed_instance_unlocked`)。
428
+ """
429
+ nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
430
+ if not nodes:
431
+ return {"nodes": 0, "terms": 0, "postings": 0, "rebuilt": False}
432
+ sealed_ids = _sealed_node_ids(nodes)
433
+ if sealed_ids:
434
+ return {"schema": SCHEMA, "nodes": 0, "terms": 0, "postings": 0,
435
+ "rebuilt": False, "refused": "sealed_nodes",
436
+ "sealed_nodes": len(sealed_ids),
437
+ "reason": "密封面 fail-closed(#152①):密文节点的明文 bigram 不得落进 _postings.json"}
438
+ if _is_sealed_instance(cg) and getattr(cg, "dek", None):
439
+ return {"schema": SCHEMA, "nodes": 0, "terms": 0, "postings": 0,
440
+ "rebuilt": False, "refused": "sealed_instance_unlocked", "sealed_nodes": 0,
441
+ "reason": "密封面 fail-closed(#152①):实例持密钥可解密,明文 bigram 不得落进 _postings.json"}
442
+ table = {}
443
+ n = 0
444
+ for nid, e in list(nodes.items()):
445
+ if limit and n >= limit:
446
+ break
447
+ got = cg.get(nid)
448
+ if not got:
449
+ continue
450
+ gs = ngrams(got.get("content"), got.get("frontmatter", {}).get("tags"))
451
+ if not gs:
452
+ continue
453
+ for g in gs:
454
+ table.setdefault(g, []).append(nid)
455
+ n += 1
456
+ stats = {"schema": SCHEMA, "built_at": int(time.time()), "nodes": n,
457
+ "terms": len(table), "postings": sum(len(v) for v in table.values())}
458
+ _atomic_json(postings_path(cg.root), table)
459
+ if limit:
460
+ # 抽样构建(冒烟用)只索引了部分节点 —— **绝不能**留下看似新鲜的快照,
461
+ # 否则未索引的节点会被静默漏召回。无 snapshot → stale_reason 判 'no_snapshot'。
462
+ stats["partial"] = True
463
+ else:
464
+ # 快照指纹必须在写完数据文件之后取:否则 root 目录自身的 mtime 会被本次写入改掉。
465
+ stats["snapshot"] = snapshot(cg.root, nodes)
466
+ _atomic_json(meta_path(cg.root), stats, indent=1)
467
+ return dict(stats, rebuilt=True)
468
+
469
+
470
+ # 生效条件:无条件把 node_id 追加进 table 中每个 bigram 的列表(bigram 不存在则新建列表),返回追加的 bigram 个数。
471
+ def add_to_table(table: dict, node_id, text, tags=None) -> int:
472
+ """增量维护:把某节点的 bigram 追加进表(调用方负责持久化)。v1 未接入写入路径。"""
473
+ gs = ngrams(text, tags)
474
+ for g in gs:
475
+ table.setdefault(g, []).append(node_id)
476
+ return len(gs)
477
+
478
+
479
+ # 生效条件:无条件把 node_id 从 table 各列表中移除(不存在则无操作并原样返回 table),返回剩余 bigram 数。
480
+ def remove_from_table(table: dict, node_id) -> int:
481
+ for g in list(table.keys()):
482
+ lst = table.get(g)
483
+ if not lst:
484
+ continue
485
+ try:
486
+ table[g] = [x for x in lst if x != node_id]
487
+ except Exception:
488
+ continue
489
+ if not table[g]:
490
+ table.pop(g, None)
491
+ return len(table)
492
+
493
+
494
+ # 生效条件:terms 为假值或任一词为单字(或 bigram 函数不可用)时返回 (None, reason);发布表为空时返回 (None,'no_index');
495
+ # 否则逐词以「该词的全部 bigram 发布列表交集」取候选、各词取并集,返回 (候选 id 集合, '')。
496
+ def candidates(root: str, terms):
497
+ """返回 (candidate_ids | None, reason)。None 表示「不可用,调用方应回退全量」。"""
498
+ sets, reason = term_ngram_sets(terms)
499
+ if not sets:
500
+ return None, reason or "unusable_terms"
501
+ table = load_cached(root)
502
+ if not table:
503
+ return None, "no_index"
504
+ out = set()
505
+ for gs in sets:
506
+ lists = [table.get(g) for g in gs]
507
+ if any(x is None for x in lists):
508
+ continue # 该词有 bigram 不在表里 → 该词无候选(并集里不贡献)
509
+ inter = set(lists[0])
510
+ for x in lists[1:]:
511
+ inter &= set(x)
512
+ if not inter:
513
+ break
514
+ out |= inter
515
+ return out, ""
516
+
517
+
518
+ # 生效条件:无条件统计 root 下发布表规模并返回 {"terms": 词项数, "postings": 倒排条目数, "meta": 元数据 dict 或 None};
519
+ # index_nodes 为真值时附带 "stale_reason"('' 表示新鲜),否则该项为 None。
520
+ def stats(root: str, index_nodes=None) -> dict:
521
+ t = load_cached(root)
522
+ meta = load_meta(root) or None
523
+ return {"terms": len(t), "postings": sum(len(v) for v in t.values()), "meta": meta,
524
+ "stale_reason": (stale_reason(root, index_nodes, meta) if index_nodes is not None else None)}