@furongjun1999/dsh-memory 0.9.6 → 0.9.8

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 (233) hide show
  1. package/README.md +150 -662
  2. package/codebuddy/CODEBUDDY.md +333 -204
  3. package/data/policy.json +38 -38
  4. package/docs/README.md +18 -0
  5. package/docs/discipline/harnesses.yaml +11 -3
  6. package/docs/discipline/templates/compact.txt.tmpl +20 -18
  7. package/docs/discipline/templates/full.md.tmpl +63 -61
  8. package/docs/discipline/templates/rules.mdc.tmpl +5 -3
  9. package/docs/discipline/templates/skill.md.tmpl +25 -23
  10. package/docs/discipline/templates/spec.txt.tmpl +2 -2
  11. package/docs/discipline/templates/zcode-user.md.tmpl +1 -1
  12. package/dsh/cordis.yml.example +139 -139
  13. package/lib/hooks.d.ts +19 -0
  14. package/lib/hooks.js +30 -7
  15. package/lib/index.js +18 -3
  16. package/lib/init.js +19 -4
  17. package/lib/lib/hook_audit.js +64 -2
  18. package/lib/lib/prompt_safety.js +14 -3
  19. package/lib/tools.d.ts +7 -0
  20. package/lib/tools.js +22 -1
  21. package/md_cg/_guard_kit.py +121 -121
  22. package/md_cg/anchor.py +114 -114
  23. package/md_cg/audit.py +15 -2
  24. package/md_cg/chain.py +3 -2
  25. package/md_cg/config_registry_guard.py +487 -487
  26. package/md_cg/conformance.py +747 -747
  27. package/md_cg/consolidate.py +1793 -1793
  28. package/md_cg/crypto.py +794 -794
  29. package/md_cg/hyperedge.py +262 -262
  30. package/md_cg/interface_schema.py +146 -146
  31. package/md_cg/lifecycle.py +426 -426
  32. package/md_cg/mdcos.py +12 -8
  33. package/md_cg/predict.py +1103 -1103
  34. package/md_cg/protect.py +654 -654
  35. package/md_cg/provenance.py +606 -606
  36. package/md_cg/queue_health.py +130 -130
  37. package/md_cg/refine.py +613 -613
  38. package/md_cg/retrieve.py +128 -128
  39. package/md_cg/revise.py +140 -140
  40. package/md_cg/rollback.py +657 -657
  41. package/md_cg/rollback_cli.py +124 -124
  42. package/md_cg/rotate.py +346 -346
  43. package/md_cg/routing.py +490 -490
  44. package/md_cg/self_surface.py +50 -50
  45. package/md_cg/semantic/canonical.py +144 -144
  46. package/md_cg/semantic/zh_en_atoms.py +141 -141
  47. package/md_cg/sources.py +1091 -1091
  48. package/md_cg/stg.py +3 -2
  49. package/md_cg/sustain.py +10 -1
  50. package/md_cg/test_audit_rotate_parity.py +279 -279
  51. package/md_cg/test_autonomy_modes.py +2013 -2013
  52. package/md_cg/test_cn_recall_grams.py +206 -206
  53. package/md_cg/test_code_kind_forbidden.py +101 -0
  54. package/md_cg/test_condaccept.py +156 -156
  55. package/md_cg/test_condgate.py +141 -141
  56. package/md_cg/test_heartbeat_ledger.py +9 -3
  57. package/md_cg/test_i50e_readside_protection.py +658 -658
  58. package/md_cg/test_issue111_gate_order.py +76 -76
  59. package/md_cg/test_issue111_scoring_contract.py +86 -86
  60. package/md_cg/test_issue121_calibration_bounds.py +293 -293
  61. package/md_cg/test_issue145_sleep_no_silent_rollback.py +167 -167
  62. package/md_cg/test_issue147_pack_id_escape.py +378 -378
  63. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -192
  64. package/md_cg/test_issue149_accel_default_face.py +248 -248
  65. package/md_cg/test_issue150_empty_query_terms.py +328 -328
  66. package/md_cg/test_issue151_153_157_write_cache_index.py +151 -151
  67. package/md_cg/test_issue152_sealed_postings.py +309 -309
  68. package/md_cg/test_issue153b_index_generation_invalidation.py +142 -142
  69. package/md_cg/test_issue157b_index_remainder.py +344 -344
  70. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -223
  71. package/md_cg/test_issue191_import_trust.py +382 -382
  72. package/md_cg/test_issue193_write_scope.py +378 -378
  73. package/md_cg/test_issue212_writeface_gaps.py +349 -349
  74. package/md_cg/test_issue214_reject_sensitivity.py +266 -266
  75. package/md_cg/test_issue215_condition_source_gap.py +272 -272
  76. package/md_cg/test_issue216_clash_routes.py +214 -214
  77. package/md_cg/test_issue217_slot_routes.py +248 -248
  78. package/md_cg/test_issue218_postcondition_value_blind.py +222 -222
  79. package/md_cg/test_issue258_pack_sensitivity.py +468 -468
  80. package/md_cg/test_issue265_coldverify_multiproc.py +438 -438
  81. package/md_cg/test_issue274_read_node_id_none.py +341 -341
  82. package/md_cg/test_issue275_layer_param.py +250 -250
  83. package/md_cg/test_issue277_node_id_traversal.py +384 -384
  84. package/md_cg/test_issue278_neg_separated_tension.py +271 -271
  85. package/md_cg/test_issue278_neg_window.py +294 -294
  86. package/md_cg/test_issue278_negative_layering.py +83 -83
  87. package/md_cg/test_issue284_skip_not_pass.py +291 -291
  88. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -573
  89. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -245
  90. package/md_cg/test_issue303_design_boundaries.py +262 -262
  91. package/md_cg/test_issue315_merge_branch_sensitivity.py +383 -383
  92. package/md_cg/test_issue319_tenant_unregistered_bypass.py +256 -256
  93. package/md_cg/test_issue321_mcp_deep_json.py +304 -304
  94. package/md_cg/test_issue322_node_write_lock.py +727 -727
  95. package/md_cg/test_issue324_write_size_fields.py +214 -214
  96. package/md_cg/test_issue325_audit_poison.py +229 -229
  97. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -331
  98. package/md_cg/test_issue326_key_perms.py +355 -355
  99. package/md_cg/test_issue326_twin_parser_parity.py +323 -323
  100. package/md_cg/test_issue326_vm_call_frame.py +569 -569
  101. package/md_cg/test_issue345_writelimit_effective_sens.py +233 -233
  102. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -424
  103. package/md_cg/test_issue348_insight_verify_op.py +199 -199
  104. package/md_cg/test_issue348_merge_rmw_lock.py +345 -345
  105. package/md_cg/test_issue350_casefold_collision.py +235 -235
  106. package/md_cg/test_issue351_ingest_root_fallback.py +201 -201
  107. package/md_cg/test_issue352_imgaudit.py +418 -418
  108. package/md_cg/test_issue352_pathsjson.py +537 -537
  109. package/md_cg/test_issue352_refindex.py +412 -412
  110. package/md_cg/test_issue352_rollback.py +604 -604
  111. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -327
  112. package/md_cg/test_issue354_rust_index_containment.py +571 -571
  113. package/md_cg/test_issue354_rust_wal_containment.py +606 -606
  114. package/md_cg/test_issue358_truncation_observable.py +247 -247
  115. package/md_cg/test_issue360_tidy_private_excerpt.py +195 -195
  116. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -494
  117. package/md_cg/test_issue362_neg_condition.py +468 -468
  118. package/md_cg/test_issue363_lexical_idf.py +275 -275
  119. package/md_cg/test_issue370_readcache_assembly.py +488 -488
  120. package/md_cg/test_issue376_heartbeat_failed.py +293 -293
  121. package/md_cg/test_issue377_layer_protect_stamp.py +324 -324
  122. package/md_cg/test_issue378_protected_floor.py +310 -310
  123. package/md_cg/test_issue383_state_event_write_gate.py +462 -462
  124. package/md_cg/test_issue397_sens_eff_wiring.py +435 -435
  125. package/md_cg/test_issue398_toolface_op_parity.py +511 -511
  126. package/md_cg/test_issue399_hive_json_shape.py +317 -317
  127. package/md_cg/test_issue401_wisdom_codegen.py +295 -295
  128. package/md_cg/test_issue404_heal_receipt.py +389 -389
  129. package/md_cg/test_issue409_compact_index_completeness.py +509 -509
  130. package/md_cg/test_issue410_verify_demote_write.py +366 -366
  131. package/md_cg/test_issue411_scrub_idempotence.py +575 -575
  132. package/md_cg/test_issue412_discipline_producer_parity.py +311 -311
  133. package/md_cg/test_issue413_preimage_failclosed.py +239 -239
  134. package/md_cg/test_issue413_preimage_twin.py +339 -339
  135. package/md_cg/test_issue415_deps_gate_probe.py +357 -357
  136. package/md_cg/test_issue416_entry_key_subset.py +525 -525
  137. package/md_cg/test_issue417_twophase_merge_landed.py +423 -423
  138. package/md_cg/test_issue425_ingest_library_path.py +331 -331
  139. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -346
  140. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -310
  141. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -301
  142. package/md_cg/test_issue427_serve_status_shape.py +191 -191
  143. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -322
  144. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -278
  145. package/md_cg/test_issue434_435_float_gate.py +90 -90
  146. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -448
  147. package/md_cg/test_issue43_default_policy.py +874 -874
  148. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -281
  149. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -454
  150. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -382
  151. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -51
  152. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -203
  153. package/md_cg/test_issue451_audit_actor.py +313 -313
  154. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -299
  155. package/md_cg/test_issue463_ghost_prune_guard.py +259 -259
  156. package/md_cg/test_issue466_basis_registry.py +469 -469
  157. package/md_cg/test_issue467_identity_sensitivity_parity.py +360 -360
  158. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -126
  159. package/md_cg/test_issue470_wal_event_durable.py +427 -427
  160. package/md_cg/test_issue471_identity_readable.py +136 -136
  161. package/md_cg/test_issue472_audit_chain.py +90 -90
  162. package/md_cg/test_issue472_prune_ledger.py +105 -105
  163. package/md_cg/test_issue472_rollback_degraded.py +81 -81
  164. package/md_cg/test_issue491_compose_sandbox.py +460 -460
  165. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -280
  166. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -256
  167. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -110
  168. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -88
  169. package/md_cg/test_issue525_read_null_semantics.py +52 -52
  170. package/md_cg/test_issue547_append_jsonl_whitelist.py +114 -114
  171. package/md_cg/test_issue547_audit_durable.py +96 -96
  172. package/md_cg/test_issue557_r2_write_entries_size_gate.py +83 -83
  173. package/md_cg/test_issue559_refine_prefix.py +69 -69
  174. package/md_cg/test_issue562_retired_faces.py +150 -0
  175. package/md_cg/test_issue71_queue_backlog.py +376 -376
  176. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -420
  177. package/md_cg/test_issue82_credential_rules.py +271 -271
  178. package/md_cg/test_issue91_verifier_sandbox.py +314 -314
  179. package/md_cg/test_issue93_remember_redaction.py +282 -282
  180. package/md_cg/test_logref.py +1141 -1141
  181. package/md_cg/test_md_access_parity.py +330 -330
  182. package/md_cg/test_md_cg_no_hive_dep.py +139 -139
  183. package/md_cg/test_mutation_residue.py +119 -119
  184. package/md_cg/test_mutation_rollback.py +835 -835
  185. package/md_cg/test_n123_derive_expiry_chain.py +210 -210
  186. package/md_cg/test_n184_keys_concurrent_provision.py +1 -1
  187. package/md_cg/test_n209_verify_write_face_gates.py +466 -466
  188. package/md_cg/test_n62_tenant_bind_failclosed.py +200 -200
  189. package/md_cg/test_neg_tail_honesty.py +733 -733
  190. package/md_cg/test_p21_tokens.py +294 -294
  191. package/md_cg/test_p27_docindex.py +792 -792
  192. package/md_cg/test_p28_refcheck.py +1053 -1053
  193. package/md_cg/test_p2_six_elements.py +476 -476
  194. package/md_cg/test_p33_ccg_wiring.py +300 -300
  195. package/md_cg/test_p3_legacy_closure.py +438 -438
  196. package/md_cg/test_p40_refine_worklist.py +244 -244
  197. package/md_cg/test_p4_freshness.py +781 -781
  198. package/md_cg/test_p9c_dedup_hints.py +288 -288
  199. package/md_cg/test_policy_required_ccg.py +444 -444
  200. package/md_cg/test_read_scope_b27.py +2 -2
  201. package/md_cg/test_retr_s5.py +312 -312
  202. package/md_cg/test_s1_ast_judge.py +109 -109
  203. package/md_cg/test_security_audit_v21.py +249 -249
  204. package/md_cg/test_state_event_op.py +521 -521
  205. package/md_cg/test_stgidx_index_parity.py +1024 -1024
  206. package/md_cg/test_sustain_bad_stamp.py +178 -0
  207. package/md_cg/test_sustain_bounded.py +652 -652
  208. package/md_cg/test_trust_edge_reachability.py +405 -405
  209. package/md_cg/test_w7_redlines.py +659 -659
  210. package/md_cg/test_write_return_shape.py +919 -919
  211. package/md_cg/test_writepipe.py +228 -228
  212. package/md_cg/trust.py +1114 -1114
  213. package/md_cg/twophase.py +303 -303
  214. package/md_cg/whitebox.py +536 -536
  215. package/md_cg/whitebox_kb/wisdom/compose_engine.py +1634 -1634
  216. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +318 -318
  217. package/md_cg/whitebox_kb/wisdom/core/parser.py +1082 -1082
  218. package/md_cg/whitebox_kb/wisdom/md_access.py +490 -490
  219. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +497 -497
  220. package/md_cg/whitebox_kb/wisdom/mini_python.py +995 -995
  221. package/md_cg/whitebox_kb/wisdom/net_units.py +2900 -2900
  222. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +4060 -4060
  223. package/md_cg/writepipe.py +1337 -1337
  224. package/package.json +3 -2
  225. package/scripts/workspace_index.py +328 -0
  226. package/src/hooks.ts +932 -908
  227. package/src/index.ts +21 -6
  228. package/src/init.ts +16 -4
  229. package/src/lib/hook_audit.ts +48 -2
  230. package/src/lib/mdcg_client.ts +469 -469
  231. package/src/lib/prompt_safety.ts +17 -3
  232. package/src/tools.ts +23 -1
  233. package/zcode/AGENTS.md +333 -204
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}