@furongjun1999/dsh-memory 0.9.6 → 0.9.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (216) hide show
  1. package/data/policy.json +38 -38
  2. package/docs/discipline/templates/spec.txt.tmpl +1 -1
  3. package/dsh/cordis.yml.example +139 -139
  4. package/lib/hooks.d.ts +19 -0
  5. package/lib/hooks.js +29 -6
  6. package/lib/index.js +11 -2
  7. package/lib/lib/hook_audit.js +38 -2
  8. package/lib/lib/prompt_safety.js +14 -3
  9. package/lib/tools.d.ts +7 -0
  10. package/lib/tools.js +22 -1
  11. package/md_cg/_guard_kit.py +121 -121
  12. package/md_cg/anchor.py +114 -114
  13. package/md_cg/audit.py +15 -2
  14. package/md_cg/chain.py +3 -2
  15. package/md_cg/config_registry_guard.py +487 -487
  16. package/md_cg/conformance.py +747 -747
  17. package/md_cg/consolidate.py +1793 -1793
  18. package/md_cg/crypto.py +794 -794
  19. package/md_cg/hyperedge.py +262 -262
  20. package/md_cg/interface_schema.py +146 -146
  21. package/md_cg/lifecycle.py +426 -426
  22. package/md_cg/mdcos.py +12 -8
  23. package/md_cg/predict.py +1103 -1103
  24. package/md_cg/protect.py +654 -654
  25. package/md_cg/provenance.py +606 -606
  26. package/md_cg/queue_health.py +130 -130
  27. package/md_cg/refine.py +613 -613
  28. package/md_cg/retrieve.py +128 -128
  29. package/md_cg/revise.py +140 -140
  30. package/md_cg/rollback.py +657 -657
  31. package/md_cg/rollback_cli.py +124 -124
  32. package/md_cg/rotate.py +346 -346
  33. package/md_cg/routing.py +490 -490
  34. package/md_cg/self_surface.py +50 -50
  35. package/md_cg/semantic/canonical.py +144 -144
  36. package/md_cg/semantic/zh_en_atoms.py +141 -141
  37. package/md_cg/sources.py +1091 -1091
  38. package/md_cg/stg.py +3 -2
  39. package/md_cg/test_audit_rotate_parity.py +279 -279
  40. package/md_cg/test_autonomy_modes.py +2013 -2013
  41. package/md_cg/test_cn_recall_grams.py +206 -206
  42. package/md_cg/test_code_kind_forbidden.py +101 -0
  43. package/md_cg/test_condaccept.py +156 -156
  44. package/md_cg/test_condgate.py +141 -141
  45. package/md_cg/test_heartbeat_ledger.py +557 -557
  46. package/md_cg/test_i50e_readside_protection.py +658 -658
  47. package/md_cg/test_issue111_gate_order.py +76 -76
  48. package/md_cg/test_issue111_scoring_contract.py +86 -86
  49. package/md_cg/test_issue121_calibration_bounds.py +293 -293
  50. package/md_cg/test_issue145_sleep_no_silent_rollback.py +167 -167
  51. package/md_cg/test_issue147_pack_id_escape.py +378 -378
  52. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -192
  53. package/md_cg/test_issue149_accel_default_face.py +248 -248
  54. package/md_cg/test_issue150_empty_query_terms.py +328 -328
  55. package/md_cg/test_issue151_153_157_write_cache_index.py +151 -151
  56. package/md_cg/test_issue152_sealed_postings.py +309 -309
  57. package/md_cg/test_issue153b_index_generation_invalidation.py +142 -142
  58. package/md_cg/test_issue157b_index_remainder.py +344 -344
  59. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -223
  60. package/md_cg/test_issue191_import_trust.py +382 -382
  61. package/md_cg/test_issue193_write_scope.py +378 -378
  62. package/md_cg/test_issue212_writeface_gaps.py +349 -349
  63. package/md_cg/test_issue214_reject_sensitivity.py +266 -266
  64. package/md_cg/test_issue215_condition_source_gap.py +272 -272
  65. package/md_cg/test_issue216_clash_routes.py +214 -214
  66. package/md_cg/test_issue217_slot_routes.py +248 -248
  67. package/md_cg/test_issue218_postcondition_value_blind.py +222 -222
  68. package/md_cg/test_issue258_pack_sensitivity.py +468 -468
  69. package/md_cg/test_issue265_coldverify_multiproc.py +438 -438
  70. package/md_cg/test_issue274_read_node_id_none.py +341 -341
  71. package/md_cg/test_issue275_layer_param.py +250 -250
  72. package/md_cg/test_issue277_node_id_traversal.py +384 -384
  73. package/md_cg/test_issue278_neg_separated_tension.py +271 -271
  74. package/md_cg/test_issue278_neg_window.py +294 -294
  75. package/md_cg/test_issue278_negative_layering.py +83 -83
  76. package/md_cg/test_issue284_skip_not_pass.py +291 -291
  77. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -573
  78. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -245
  79. package/md_cg/test_issue303_design_boundaries.py +262 -262
  80. package/md_cg/test_issue315_merge_branch_sensitivity.py +383 -383
  81. package/md_cg/test_issue319_tenant_unregistered_bypass.py +256 -256
  82. package/md_cg/test_issue321_mcp_deep_json.py +304 -304
  83. package/md_cg/test_issue322_node_write_lock.py +727 -727
  84. package/md_cg/test_issue324_write_size_fields.py +214 -214
  85. package/md_cg/test_issue325_audit_poison.py +229 -229
  86. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -331
  87. package/md_cg/test_issue326_key_perms.py +355 -355
  88. package/md_cg/test_issue326_twin_parser_parity.py +323 -323
  89. package/md_cg/test_issue326_vm_call_frame.py +569 -569
  90. package/md_cg/test_issue345_writelimit_effective_sens.py +233 -233
  91. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -424
  92. package/md_cg/test_issue348_insight_verify_op.py +199 -199
  93. package/md_cg/test_issue348_merge_rmw_lock.py +345 -345
  94. package/md_cg/test_issue350_casefold_collision.py +235 -235
  95. package/md_cg/test_issue351_ingest_root_fallback.py +201 -201
  96. package/md_cg/test_issue352_imgaudit.py +418 -418
  97. package/md_cg/test_issue352_pathsjson.py +537 -537
  98. package/md_cg/test_issue352_refindex.py +412 -412
  99. package/md_cg/test_issue352_rollback.py +604 -604
  100. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -327
  101. package/md_cg/test_issue354_rust_index_containment.py +571 -571
  102. package/md_cg/test_issue354_rust_wal_containment.py +606 -606
  103. package/md_cg/test_issue358_truncation_observable.py +247 -247
  104. package/md_cg/test_issue360_tidy_private_excerpt.py +195 -195
  105. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -494
  106. package/md_cg/test_issue362_neg_condition.py +468 -468
  107. package/md_cg/test_issue363_lexical_idf.py +275 -275
  108. package/md_cg/test_issue370_readcache_assembly.py +488 -488
  109. package/md_cg/test_issue376_heartbeat_failed.py +293 -293
  110. package/md_cg/test_issue377_layer_protect_stamp.py +324 -324
  111. package/md_cg/test_issue378_protected_floor.py +310 -310
  112. package/md_cg/test_issue383_state_event_write_gate.py +462 -462
  113. package/md_cg/test_issue397_sens_eff_wiring.py +435 -435
  114. package/md_cg/test_issue398_toolface_op_parity.py +511 -511
  115. package/md_cg/test_issue399_hive_json_shape.py +317 -317
  116. package/md_cg/test_issue401_wisdom_codegen.py +295 -295
  117. package/md_cg/test_issue404_heal_receipt.py +389 -389
  118. package/md_cg/test_issue409_compact_index_completeness.py +509 -509
  119. package/md_cg/test_issue410_verify_demote_write.py +366 -366
  120. package/md_cg/test_issue411_scrub_idempotence.py +575 -575
  121. package/md_cg/test_issue412_discipline_producer_parity.py +311 -311
  122. package/md_cg/test_issue413_preimage_failclosed.py +239 -239
  123. package/md_cg/test_issue413_preimage_twin.py +339 -339
  124. package/md_cg/test_issue415_deps_gate_probe.py +357 -357
  125. package/md_cg/test_issue416_entry_key_subset.py +525 -525
  126. package/md_cg/test_issue417_twophase_merge_landed.py +423 -423
  127. package/md_cg/test_issue425_ingest_library_path.py +331 -331
  128. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -346
  129. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -310
  130. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -301
  131. package/md_cg/test_issue427_serve_status_shape.py +191 -191
  132. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -322
  133. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -278
  134. package/md_cg/test_issue434_435_float_gate.py +90 -90
  135. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -448
  136. package/md_cg/test_issue43_default_policy.py +874 -874
  137. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -281
  138. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -454
  139. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -382
  140. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -51
  141. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -203
  142. package/md_cg/test_issue451_audit_actor.py +313 -313
  143. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -299
  144. package/md_cg/test_issue463_ghost_prune_guard.py +259 -259
  145. package/md_cg/test_issue466_basis_registry.py +469 -469
  146. package/md_cg/test_issue467_identity_sensitivity_parity.py +360 -360
  147. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -126
  148. package/md_cg/test_issue470_wal_event_durable.py +427 -427
  149. package/md_cg/test_issue471_identity_readable.py +136 -136
  150. package/md_cg/test_issue472_audit_chain.py +90 -90
  151. package/md_cg/test_issue472_prune_ledger.py +105 -105
  152. package/md_cg/test_issue472_rollback_degraded.py +81 -81
  153. package/md_cg/test_issue491_compose_sandbox.py +460 -460
  154. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -280
  155. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -256
  156. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -110
  157. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -88
  158. package/md_cg/test_issue525_read_null_semantics.py +52 -52
  159. package/md_cg/test_issue547_append_jsonl_whitelist.py +114 -114
  160. package/md_cg/test_issue547_audit_durable.py +96 -96
  161. package/md_cg/test_issue557_r2_write_entries_size_gate.py +83 -83
  162. package/md_cg/test_issue559_refine_prefix.py +69 -69
  163. package/md_cg/test_issue562_retired_faces.py +150 -0
  164. package/md_cg/test_issue71_queue_backlog.py +376 -376
  165. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -420
  166. package/md_cg/test_issue82_credential_rules.py +271 -271
  167. package/md_cg/test_issue91_verifier_sandbox.py +314 -314
  168. package/md_cg/test_issue93_remember_redaction.py +282 -282
  169. package/md_cg/test_logref.py +1141 -1141
  170. package/md_cg/test_md_access_parity.py +330 -330
  171. package/md_cg/test_md_cg_no_hive_dep.py +139 -139
  172. package/md_cg/test_mutation_residue.py +119 -119
  173. package/md_cg/test_mutation_rollback.py +835 -835
  174. package/md_cg/test_n123_derive_expiry_chain.py +210 -210
  175. package/md_cg/test_n209_verify_write_face_gates.py +466 -466
  176. package/md_cg/test_n62_tenant_bind_failclosed.py +200 -200
  177. package/md_cg/test_neg_tail_honesty.py +733 -733
  178. package/md_cg/test_p21_tokens.py +294 -294
  179. package/md_cg/test_p27_docindex.py +792 -792
  180. package/md_cg/test_p28_refcheck.py +1053 -1053
  181. package/md_cg/test_p2_six_elements.py +476 -476
  182. package/md_cg/test_p33_ccg_wiring.py +300 -300
  183. package/md_cg/test_p3_legacy_closure.py +438 -438
  184. package/md_cg/test_p40_refine_worklist.py +244 -244
  185. package/md_cg/test_p4_freshness.py +781 -781
  186. package/md_cg/test_p9c_dedup_hints.py +288 -288
  187. package/md_cg/test_policy_required_ccg.py +444 -444
  188. package/md_cg/test_retr_s5.py +312 -312
  189. package/md_cg/test_s1_ast_judge.py +109 -109
  190. package/md_cg/test_state_event_op.py +521 -521
  191. package/md_cg/test_stgidx_index_parity.py +1024 -1024
  192. package/md_cg/test_sustain_bounded.py +652 -652
  193. package/md_cg/test_trust_edge_reachability.py +405 -405
  194. package/md_cg/test_w7_redlines.py +659 -659
  195. package/md_cg/test_write_return_shape.py +919 -919
  196. package/md_cg/test_writepipe.py +228 -228
  197. package/md_cg/trust.py +1114 -1114
  198. package/md_cg/twophase.py +303 -303
  199. package/md_cg/whitebox.py +536 -536
  200. package/md_cg/whitebox_kb/wisdom/compose_engine.py +1634 -1634
  201. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +318 -318
  202. package/md_cg/whitebox_kb/wisdom/core/parser.py +1082 -1082
  203. package/md_cg/whitebox_kb/wisdom/md_access.py +490 -490
  204. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +497 -497
  205. package/md_cg/whitebox_kb/wisdom/mini_python.py +995 -995
  206. package/md_cg/whitebox_kb/wisdom/net_units.py +2900 -2900
  207. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +4060 -4060
  208. package/md_cg/writepipe.py +1337 -1337
  209. package/package.json +3 -2
  210. package/scripts/workspace_index.py +328 -0
  211. package/src/hooks.ts +30 -6
  212. package/src/index.ts +14 -5
  213. package/src/lib/hook_audit.ts +282 -256
  214. package/src/lib/mdcg_client.ts +469 -469
  215. package/src/lib/prompt_safety.ts +17 -3
  216. package/src/tools.ts +23 -1
package/md_cg/retrieve.py CHANGED
@@ -1,128 +1,128 @@
1
- # -*- coding: utf-8 -*-
2
- """取(retrieve)—— 四动作之一,返回**定型信封**(Envelope)。
3
-
4
- 为什么要这层(外部 issue #5 第 15 条):
5
- 既有检索面 cg.search 返回 (results, meta),是内部检索包的形状;「可复跑」要求
6
- 接口形状本身可判,故另立定型入口,把检索包规范化成 Envelope。
7
-
8
- **不改既有 search 路径**:search 被几十处调用,改它的返回形状是破坏性变更。
9
- 本模块只做适配,新调用方用新入口,老调用方一字不动。
10
-
11
- Envelope 字段(schema 见 interface_schema.ENVELOPE):
12
-
13
- items[] 条目:node_id / content / condition_space / qualification /
14
- lifecycle_state / content_kind
15
- completeness bool 本次检索是否覆盖了候选全集(false 时不得进入零命中路径)
16
- hit_count int 命中数;**非 success 时恒 null**(I1)
17
- snapshot_id str 索引快照标识(跨快照比较必须显式声明)
18
- operation_status success | partial | timeout | unavailable | operation_error
19
-
20
- 两条必须守的纪律:
21
- * **I1**:非 success 时 hit_count 必须为 null——不能让人把「故障」读成「没有」。
22
- * **条件空间如实**:索引条目不含 condition_space(见 condgate.qualify 的说明),
23
- 故本模块对**每条命中**回查一次 frontmatter(k 条,代价可接受),
24
- 以给出准确的 qualification,而不是拿索引的空字段糊弄。
25
- 这也是 gap_cs_not_indexed 在「取」这一层的局部解法——全量索引改造另议。
26
- """
27
-
28
- import time
29
-
30
- from . import condgate, lifecycle
31
-
32
- __all__ = ["retrieve", "ENVELOPE_FIELDS"]
33
-
34
- ENVELOPE_FIELDS = ("items", "completeness", "hit_count", "snapshot_id",
35
- "operation_status")
36
-
37
-
38
- def _snapshot_id(cg):
39
- """索引快照标识 = 节点数 + 索引文件 mtime。
40
-
41
- 首版读 cg._index_mtime(该属性不存在)→ 恒得 0,于是所有快照都叫 snap-N-0,
42
- **跨快照比较失去意义**(而 snapshot_id 的全部用途就是显式声明版本差异)。
43
- 改为直接取索引文件 mtime;取不到(如内存库)则回落 0 并如实反映。
44
- """
45
- import os as _os
46
- idx = getattr(cg, "index", None) or {}
47
- n = len((idx.get("nodes") or {}))
48
- path = getattr(cg, "index_path", None)
49
- mtime = 0
50
- if path:
51
- try:
52
- mtime = int(_os.path.getmtime(str(path)))
53
- except OSError:
54
- mtime = 0
55
- return "snap-%d-%d" % (n, mtime)
56
-
57
-
58
- def retrieve(cg, query, k=10, layer=None, session=None,
59
- condition_space=None, snapshot_id=None):
60
- """检索并返回定型 Envelope。失败也返回 Envelope(带 operation_status),不抛。"""
61
- q = (query or "").strip()
62
- if not q:
63
- return {"items": [], "completeness": True, "hit_count": 0,
64
- "snapshot_id": snapshot_id or _snapshot_id(cg),
65
- "operation_status": "success", "reason": "empty_query"}
66
-
67
- try:
68
- res = cg.search(q, k=k, layer=layer, session=session)
69
- hits, meta = res if isinstance(res, tuple) and len(res) == 2 else (res, {})
70
- except Exception as exc: # noqa: BLE001 —— 失败要如实成形态
71
- return {"items": [], "completeness": False, "hit_count": None,
72
- "snapshot_id": snapshot_id or _snapshot_id(cg),
73
- "operation_status": "operation_error",
74
- "error": "%s: %s" % (type(exc).__name__, exc)}
75
-
76
- items = []
77
- for h in (hits or []):
78
- node = h[0] if isinstance(h, (list, tuple)) and h else h
79
- if not isinstance(node, dict):
80
- continue
81
- nid = node.get("id")
82
- # 回查 frontmatter:索引里没有 condition_space,只能从节点本体取
83
- fm = {}
84
- try:
85
- got = cg.get(nid) if nid else None
86
- fm = (got or {}).get("frontmatter") or {}
87
- except Exception: # noqa: BLE001
88
- fm = {}
89
- full = node.get("content") or ""
90
- items.append({
91
- "node_id": nid,
92
- "content": full[:400],
93
- # I17 / I16(2026-10-18):投影不得自称权威——截断必须显式声明。
94
- # 不声明的话,读者会把 400 字当成原文全文,这正是「投影冒充原文」。
95
- "content_truncated": len(full) > 400,
96
- "content_full_len": len(full),
97
- "condition_space": fm.get("condition_space"),
98
- "qualification": condgate.qualify(fm),
99
- "lifecycle_state": lifecycle.state_of(fm),
100
- "content_kind": node.get("content_kind") or fm.get("content_kind"),
101
- })
102
-
103
- scanned = meta.get("scanned")
104
- completeness = bool(meta.get("completeness", True)) if isinstance(meta, dict) else True
105
- status = "success"
106
- if isinstance(meta, dict) and meta.get("tier") is None and not items:
107
- status = "success" # 真空结果仍是 success
108
- elif isinstance(meta, dict) and meta.get("partial"):
109
- status = "partial"
110
- completeness = False
111
-
112
- # I2(2026-10-18):completeness=False 时**不得断言「没有」**。
113
- # 零命中 + 不完整,若报 hit_count=0,调用方会读成「查了,确实没有」——
114
- # 而实际是「没查全」。故此时 hit_count 必须为 null(与 I1 同一精神:
115
- # 不确定的结论不能伪装成确定)。有命中时仍给数量,由 completeness 标注覆盖面。
116
- hit_count = len(items)
117
- if not completeness and hit_count == 0:
118
- hit_count = None
119
-
120
- return {
121
- "items": items,
122
- "completeness": completeness,
123
- "hit_count": hit_count, # 仅 success/partial 且完整时有意义
124
- "snapshot_id": snapshot_id or _snapshot_id(cg),
125
- "operation_status": status,
126
- "scanned": scanned,
127
- "tier": (meta or {}).get("tier") if isinstance(meta, dict) else None,
128
- }
1
+ # -*- coding: utf-8 -*-
2
+ """取(retrieve)—— 四动作之一,返回**定型信封**(Envelope)。
3
+
4
+ 为什么要这层(外部 issue #5 第 15 条):
5
+ 既有检索面 cg.search 返回 (results, meta),是内部检索包的形状;「可复跑」要求
6
+ 接口形状本身可判,故另立定型入口,把检索包规范化成 Envelope。
7
+
8
+ **不改既有 search 路径**:search 被几十处调用,改它的返回形状是破坏性变更。
9
+ 本模块只做适配,新调用方用新入口,老调用方一字不动。
10
+
11
+ Envelope 字段(schema 见 interface_schema.ENVELOPE):
12
+
13
+ items[] 条目:node_id / content / condition_space / qualification /
14
+ lifecycle_state / content_kind
15
+ completeness bool 本次检索是否覆盖了候选全集(false 时不得进入零命中路径)
16
+ hit_count int 命中数;**非 success 时恒 null**(I1)
17
+ snapshot_id str 索引快照标识(跨快照比较必须显式声明)
18
+ operation_status success | partial | timeout | unavailable | operation_error
19
+
20
+ 两条必须守的纪律:
21
+ * **I1**:非 success 时 hit_count 必须为 null——不能让人把「故障」读成「没有」。
22
+ * **条件空间如实**:索引条目不含 condition_space(见 condgate.qualify 的说明),
23
+ 故本模块对**每条命中**回查一次 frontmatter(k 条,代价可接受),
24
+ 以给出准确的 qualification,而不是拿索引的空字段糊弄。
25
+ 这也是 gap_cs_not_indexed 在「取」这一层的局部解法——全量索引改造另议。
26
+ """
27
+
28
+ import time
29
+
30
+ from . import condgate, lifecycle
31
+
32
+ __all__ = ["retrieve", "ENVELOPE_FIELDS"]
33
+
34
+ ENVELOPE_FIELDS = ("items", "completeness", "hit_count", "snapshot_id",
35
+ "operation_status")
36
+
37
+
38
+ def _snapshot_id(cg):
39
+ """索引快照标识 = 节点数 + 索引文件 mtime。
40
+
41
+ 首版读 cg._index_mtime(该属性不存在)→ 恒得 0,于是所有快照都叫 snap-N-0,
42
+ **跨快照比较失去意义**(而 snapshot_id 的全部用途就是显式声明版本差异)。
43
+ 改为直接取索引文件 mtime;取不到(如内存库)则回落 0 并如实反映。
44
+ """
45
+ import os as _os
46
+ idx = getattr(cg, "index", None) or {}
47
+ n = len((idx.get("nodes") or {}))
48
+ path = getattr(cg, "index_path", None)
49
+ mtime = 0
50
+ if path:
51
+ try:
52
+ mtime = int(_os.path.getmtime(str(path)))
53
+ except OSError:
54
+ mtime = 0
55
+ return "snap-%d-%d" % (n, mtime)
56
+
57
+
58
+ def retrieve(cg, query, k=10, layer=None, session=None,
59
+ condition_space=None, snapshot_id=None):
60
+ """检索并返回定型 Envelope。失败也返回 Envelope(带 operation_status),不抛。"""
61
+ q = (query or "").strip()
62
+ if not q:
63
+ return {"items": [], "completeness": True, "hit_count": 0,
64
+ "snapshot_id": snapshot_id or _snapshot_id(cg),
65
+ "operation_status": "success", "reason": "empty_query"}
66
+
67
+ try:
68
+ res = cg.search(q, k=k, layer=layer, session=session)
69
+ hits, meta = res if isinstance(res, tuple) and len(res) == 2 else (res, {})
70
+ except Exception as exc: # noqa: BLE001 —— 失败要如实成形态
71
+ return {"items": [], "completeness": False, "hit_count": None,
72
+ "snapshot_id": snapshot_id or _snapshot_id(cg),
73
+ "operation_status": "operation_error",
74
+ "error": "%s: %s" % (type(exc).__name__, exc)}
75
+
76
+ items = []
77
+ for h in (hits or []):
78
+ node = h[0] if isinstance(h, (list, tuple)) and h else h
79
+ if not isinstance(node, dict):
80
+ continue
81
+ nid = node.get("id")
82
+ # 回查 frontmatter:索引里没有 condition_space,只能从节点本体取
83
+ fm = {}
84
+ try:
85
+ got = cg.get(nid) if nid else None
86
+ fm = (got or {}).get("frontmatter") or {}
87
+ except Exception: # noqa: BLE001
88
+ fm = {}
89
+ full = node.get("content") or ""
90
+ items.append({
91
+ "node_id": nid,
92
+ "content": full[:400],
93
+ # I17 / I16(2026-10-18):投影不得自称权威——截断必须显式声明。
94
+ # 不声明的话,读者会把 400 字当成原文全文,这正是「投影冒充原文」。
95
+ "content_truncated": len(full) > 400,
96
+ "content_full_len": len(full),
97
+ "condition_space": fm.get("condition_space"),
98
+ "qualification": condgate.qualify(fm),
99
+ "lifecycle_state": lifecycle.state_of(fm),
100
+ "content_kind": node.get("content_kind") or fm.get("content_kind"),
101
+ })
102
+
103
+ scanned = meta.get("scanned")
104
+ completeness = bool(meta.get("completeness", True)) if isinstance(meta, dict) else True
105
+ status = "success"
106
+ if isinstance(meta, dict) and meta.get("tier") is None and not items:
107
+ status = "success" # 真空结果仍是 success
108
+ elif isinstance(meta, dict) and meta.get("partial"):
109
+ status = "partial"
110
+ completeness = False
111
+
112
+ # I2(2026-10-18):completeness=False 时**不得断言「没有」**。
113
+ # 零命中 + 不完整,若报 hit_count=0,调用方会读成「查了,确实没有」——
114
+ # 而实际是「没查全」。故此时 hit_count 必须为 null(与 I1 同一精神:
115
+ # 不确定的结论不能伪装成确定)。有命中时仍给数量,由 completeness 标注覆盖面。
116
+ hit_count = len(items)
117
+ if not completeness and hit_count == 0:
118
+ hit_count = None
119
+
120
+ return {
121
+ "items": items,
122
+ "completeness": completeness,
123
+ "hit_count": hit_count, # 仅 success/partial 且完整时有意义
124
+ "snapshot_id": snapshot_id or _snapshot_id(cg),
125
+ "operation_status": status,
126
+ "scanned": scanned,
127
+ "tier": (meta or {}).get("tier") if isinstance(meta, dict) else None,
128
+ }
package/md_cg/revise.py CHANGED
@@ -1,140 +1,140 @@
1
- # -*- coding: utf-8 -*-
2
- """修订与回滚(revise / rollback)——四动作里此前完全缺失的那一条。
3
-
4
- 背景(外部 issue #5 第 8/11 条,2026-10-18):
5
- revise 在文档里早有签名,但**代码全仓 0 命中**;superseded 档已随方案 A 落地,
6
- 本模块把「产生新版本、旧版转 superseded、可回滚」这三件事接起来。
7
-
8
- 三条设计纪律:
9
-
10
- 1. **先写新、再改旧**。新版本必须真正落盘成功,才允许把旧版本标为 superseded;
11
- 否则会出现「旧版被取代、新版不存在」的悬空状态。任何一步失败都不动旧节点。
12
- 2. **CAS 防并发覆盖**。调用方可传 expect_state;与当前状态不符即 DEFER 让调用方
13
- 重读,而不是覆盖别人的修改(issue #5 第 11 条:state_from 天然可作 CAS 前置)。
14
- 3. **回滚不删任何东西**。rollback 只做状态互换:旧版 superseded→active,
15
- 新版 active→superseded。不归档、不删除——因为 active→archived 是跳级(被
16
- TRANSITIONS 拒绝),而「互换取代关系」既可逆又符合状态机。
17
- """
18
-
19
- import time
20
-
21
- from . import lifecycle
22
-
23
- __all__ = ["revise", "rollback"]
24
-
25
- #: 回滚令牌的最小形状(写进返回体,可持久化)
26
- TOKEN_KEYS = ("old_id", "old_state", "new_id", "new_state", "ts")
27
-
28
-
29
- def _state_of_node(cg, node_id):
30
- """取节点当前生命周期状态。
31
-
32
- 实测(2026-10-18):cg.get() 返回 {id, content, frontmatter, path},
33
- lifecycle_state 在 frontmatter 里,**不在顶层**。首版把整个 dict 当 fm,
34
- state_of 读不到键就 fail-open 成 active——于是 set_state 明明成功、
35
- 读回却是 active,conformance 直接红。
36
-
37
- 这是同一类错误的第二次(前一次是 cg.search 返回 (res, meta) 而非 res):
38
- **不要假设接口返回结构,先实测。**
39
- """
40
- node = cg.get(node_id)
41
- if node is None:
42
- return None
43
- if isinstance(node, dict):
44
- fm = node.get("frontmatter") or node
45
- elif isinstance(node, (list, tuple)) and node:
46
- fm = node[0]
47
- else:
48
- fm = node
49
- return lifecycle.state_of(fm)
50
-
51
-
52
- def _write_new(cg, content, layer, tags, condition_space):
53
- """走正常写入链(含形式完备闸),返回 disp 结构。"""
54
- from .mcp_server import _cg_dispatch
55
- a = {"op": "write", "content": content, "content_kind": "work_done",
56
- "layer": layer or "knowledge", "tags": tags or ["revise"]}
57
- if condition_space:
58
- a["condition_space"] = condition_space
59
- r = _cg_dispatch(cg, a)
60
- return r if isinstance(r, dict) else {}
61
-
62
-
63
- def revise(cg, old_id, new_content, expect_state=None, reason="修订",
64
- layer=None, tags=None, condition_space=None):
65
- """产生新版本并把旧版本标为 superseded。
66
-
67
- 返回:
68
- {"verdict": "ACCEPT"|"REJECT"|"DEFER", "state_from", "state_to",
69
- "new_id", "rollback_token", "reason"}
70
- """
71
- old_state = _state_of_node(cg, old_id)
72
- if old_state is None:
73
- return {"verdict": "REJECT", "reason": "旧节点不存在:%s" % old_id,
74
- "state_from": None, "state_to": None, "new_id": None,
75
- "rollback_token": None}
76
-
77
- # CAS:并发前置条件
78
- if expect_state is not None and str(expect_state) != old_state:
79
- return {"verdict": "DEFER", "state_from": old_state, "state_to": old_state,
80
- "new_id": None, "rollback_token": None,
81
- "reason": "CAS 不符:期望 %s,实际 %s(请重读后再修订)"
82
- % (expect_state, old_state)}
83
-
84
- if old_state in ("archived", "superseded"):
85
- return {"verdict": "REJECT", "state_from": old_state, "state_to": old_state,
86
- "new_id": None, "rollback_token": None,
87
- "reason": "已退役版本不可再被修订(%s)" % old_state}
88
-
89
- # ① 先写新版——失败则完全不动旧节点
90
- disp = _write_new(cg, new_content, layer, tags, condition_space)
91
- verdict = (disp.get("verdict") or {}).get("state")
92
- if not disp.get("committed") or verdict != "ACCEPT":
93
- return {"verdict": verdict or "REJECT", "state_from": old_state,
94
- "state_to": old_state, "new_id": None, "rollback_token": None,
95
- "reason": "新版未落盘,旧版保持不动",
96
- "new_verdict": disp.get("verdict")}
97
-
98
- new_id = disp.get("id")
99
-
100
- # ② 再改旧版——此时新版已确认存在
101
- lifecycle.set_state(cg, old_id, "superseded",
102
- reason="%s(被 %s 取代)" % (reason, new_id))
103
- new_state = _state_of_node(cg, old_id)
104
-
105
- token = {"old_id": old_id, "old_state": old_state, "new_id": new_id,
106
- "new_state": "active", "ts": time.time()}
107
- return {"verdict": "ACCEPT", "state_from": old_state, "state_to": new_state,
108
- "new_id": new_id, "rollback_token": token, "reason": reason}
109
-
110
-
111
- def rollback(cg, token, reason="回滚"):
112
- """撤销一次修订:旧版复活、新版转为被取代。**不删除任何节点。**
113
-
114
- 不用「新版→archived」的理由:active→archived 是跳级(TRANSITIONS 拒绝);
115
- 互换取代关系既可逆,又正确表达了「回滚后谁是当前版本」。
116
- """
117
- if not isinstance(token, dict) or not token.get("old_id") or not token.get("new_id"):
118
- return {"verdict": "REJECT", "reason": "回滚令牌不完整"}
119
-
120
- old_id, new_id = token["old_id"], token["new_id"]
121
- st_old = _state_of_node(cg, old_id)
122
- st_new = _state_of_node(cg, new_id)
123
- if st_old is None or st_new is None:
124
- return {"verdict": "REJECT", "reason": "令牌指向的节点不存在",
125
- "state_old": st_old, "state_new": st_new}
126
-
127
- if st_old != "superseded":
128
- return {"verdict": "DEFER", "reason": "旧版当前不在 superseded(%s),拒绝回滚" % st_old,
129
- "state_old": st_old, "state_new": st_new}
130
-
131
- # 互换:旧版复活、新版被取代
132
- lifecycle.set_state(cg, old_id, "active", reason="%s:恢复旧版" % reason)
133
- if st_new == "active":
134
- lifecycle.set_state(cg, new_id, "superseded",
135
- reason="%s:新版转为被取代" % reason)
136
-
137
- return {"verdict": "ACCEPT",
138
- "state_old_after": _state_of_node(cg, old_id),
139
- "state_new_after": _state_of_node(cg, new_id),
140
- "reason": reason}
1
+ # -*- coding: utf-8 -*-
2
+ """修订与回滚(revise / rollback)——四动作里此前完全缺失的那一条。
3
+
4
+ 背景(外部 issue #5 第 8/11 条,2026-10-18):
5
+ revise 在文档里早有签名,但**代码全仓 0 命中**;superseded 档已随方案 A 落地,
6
+ 本模块把「产生新版本、旧版转 superseded、可回滚」这三件事接起来。
7
+
8
+ 三条设计纪律:
9
+
10
+ 1. **先写新、再改旧**。新版本必须真正落盘成功,才允许把旧版本标为 superseded;
11
+ 否则会出现「旧版被取代、新版不存在」的悬空状态。任何一步失败都不动旧节点。
12
+ 2. **CAS 防并发覆盖**。调用方可传 expect_state;与当前状态不符即 DEFER 让调用方
13
+ 重读,而不是覆盖别人的修改(issue #5 第 11 条:state_from 天然可作 CAS 前置)。
14
+ 3. **回滚不删任何东西**。rollback 只做状态互换:旧版 superseded→active,
15
+ 新版 active→superseded。不归档、不删除——因为 active→archived 是跳级(被
16
+ TRANSITIONS 拒绝),而「互换取代关系」既可逆又符合状态机。
17
+ """
18
+
19
+ import time
20
+
21
+ from . import lifecycle
22
+
23
+ __all__ = ["revise", "rollback"]
24
+
25
+ #: 回滚令牌的最小形状(写进返回体,可持久化)
26
+ TOKEN_KEYS = ("old_id", "old_state", "new_id", "new_state", "ts")
27
+
28
+
29
+ def _state_of_node(cg, node_id):
30
+ """取节点当前生命周期状态。
31
+
32
+ 实测(2026-10-18):cg.get() 返回 {id, content, frontmatter, path},
33
+ lifecycle_state 在 frontmatter 里,**不在顶层**。首版把整个 dict 当 fm,
34
+ state_of 读不到键就 fail-open 成 active——于是 set_state 明明成功、
35
+ 读回却是 active,conformance 直接红。
36
+
37
+ 这是同一类错误的第二次(前一次是 cg.search 返回 (res, meta) 而非 res):
38
+ **不要假设接口返回结构,先实测。**
39
+ """
40
+ node = cg.get(node_id)
41
+ if node is None:
42
+ return None
43
+ if isinstance(node, dict):
44
+ fm = node.get("frontmatter") or node
45
+ elif isinstance(node, (list, tuple)) and node:
46
+ fm = node[0]
47
+ else:
48
+ fm = node
49
+ return lifecycle.state_of(fm)
50
+
51
+
52
+ def _write_new(cg, content, layer, tags, condition_space):
53
+ """走正常写入链(含形式完备闸),返回 disp 结构。"""
54
+ from .mcp_server import _cg_dispatch
55
+ a = {"op": "write", "content": content, "content_kind": "work_done",
56
+ "layer": layer or "knowledge", "tags": tags or ["revise"]}
57
+ if condition_space:
58
+ a["condition_space"] = condition_space
59
+ r = _cg_dispatch(cg, a)
60
+ return r if isinstance(r, dict) else {}
61
+
62
+
63
+ def revise(cg, old_id, new_content, expect_state=None, reason="修订",
64
+ layer=None, tags=None, condition_space=None):
65
+ """产生新版本并把旧版本标为 superseded。
66
+
67
+ 返回:
68
+ {"verdict": "ACCEPT"|"REJECT"|"DEFER", "state_from", "state_to",
69
+ "new_id", "rollback_token", "reason"}
70
+ """
71
+ old_state = _state_of_node(cg, old_id)
72
+ if old_state is None:
73
+ return {"verdict": "REJECT", "reason": "旧节点不存在:%s" % old_id,
74
+ "state_from": None, "state_to": None, "new_id": None,
75
+ "rollback_token": None}
76
+
77
+ # CAS:并发前置条件
78
+ if expect_state is not None and str(expect_state) != old_state:
79
+ return {"verdict": "DEFER", "state_from": old_state, "state_to": old_state,
80
+ "new_id": None, "rollback_token": None,
81
+ "reason": "CAS 不符:期望 %s,实际 %s(请重读后再修订)"
82
+ % (expect_state, old_state)}
83
+
84
+ if old_state in ("archived", "superseded"):
85
+ return {"verdict": "REJECT", "state_from": old_state, "state_to": old_state,
86
+ "new_id": None, "rollback_token": None,
87
+ "reason": "已退役版本不可再被修订(%s)" % old_state}
88
+
89
+ # ① 先写新版——失败则完全不动旧节点
90
+ disp = _write_new(cg, new_content, layer, tags, condition_space)
91
+ verdict = (disp.get("verdict") or {}).get("state")
92
+ if not disp.get("committed") or verdict != "ACCEPT":
93
+ return {"verdict": verdict or "REJECT", "state_from": old_state,
94
+ "state_to": old_state, "new_id": None, "rollback_token": None,
95
+ "reason": "新版未落盘,旧版保持不动",
96
+ "new_verdict": disp.get("verdict")}
97
+
98
+ new_id = disp.get("id")
99
+
100
+ # ② 再改旧版——此时新版已确认存在
101
+ lifecycle.set_state(cg, old_id, "superseded",
102
+ reason="%s(被 %s 取代)" % (reason, new_id))
103
+ new_state = _state_of_node(cg, old_id)
104
+
105
+ token = {"old_id": old_id, "old_state": old_state, "new_id": new_id,
106
+ "new_state": "active", "ts": time.time()}
107
+ return {"verdict": "ACCEPT", "state_from": old_state, "state_to": new_state,
108
+ "new_id": new_id, "rollback_token": token, "reason": reason}
109
+
110
+
111
+ def rollback(cg, token, reason="回滚"):
112
+ """撤销一次修订:旧版复活、新版转为被取代。**不删除任何节点。**
113
+
114
+ 不用「新版→archived」的理由:active→archived 是跳级(TRANSITIONS 拒绝);
115
+ 互换取代关系既可逆,又正确表达了「回滚后谁是当前版本」。
116
+ """
117
+ if not isinstance(token, dict) or not token.get("old_id") or not token.get("new_id"):
118
+ return {"verdict": "REJECT", "reason": "回滚令牌不完整"}
119
+
120
+ old_id, new_id = token["old_id"], token["new_id"]
121
+ st_old = _state_of_node(cg, old_id)
122
+ st_new = _state_of_node(cg, new_id)
123
+ if st_old is None or st_new is None:
124
+ return {"verdict": "REJECT", "reason": "令牌指向的节点不存在",
125
+ "state_old": st_old, "state_new": st_new}
126
+
127
+ if st_old != "superseded":
128
+ return {"verdict": "DEFER", "reason": "旧版当前不在 superseded(%s),拒绝回滚" % st_old,
129
+ "state_old": st_old, "state_new": st_new}
130
+
131
+ # 互换:旧版复活、新版被取代
132
+ lifecycle.set_state(cg, old_id, "active", reason="%s:恢复旧版" % reason)
133
+ if st_new == "active":
134
+ lifecycle.set_state(cg, new_id, "superseded",
135
+ reason="%s:新版转为被取代" % reason)
136
+
137
+ return {"verdict": "ACCEPT",
138
+ "state_old_after": _state_of_node(cg, old_id),
139
+ "state_new_after": _state_of_node(cg, new_id),
140
+ "reason": reason}