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