@furongjun1999/dsh-memory 0.9.23 → 0.10.3

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 (118) hide show
  1. package/CHANGELOG.en.md +515 -404
  2. package/CHANGELOG.md +642 -449
  3. package/README.en.md +244 -240
  4. package/README.md +272 -262
  5. package/codebuddy/CODEBUDDY.md +1 -1
  6. package/docs/discipline/templates/full.md.tmpl +1 -1
  7. package/docs/discipline/templates/rules.mdc.tmpl +1 -1
  8. package/docs/en/mdcg/world-model-endpoint.md +1 -1
  9. package/docs/mdcg/cogmap_ops.md +19 -16
  10. package/lib/client.js +29 -3
  11. package/lib/hooks.d.ts +12 -0
  12. package/lib/hooks.js +43 -1
  13. package/lib/tools.d.ts +2 -2
  14. package/md_cg/bucketindex.py +231 -0
  15. package/md_cg/bucketscope.py +357 -0
  16. package/md_cg/cohesion.py +337 -0
  17. package/md_cg/config_registry_bulk.py +24 -10
  18. package/md_cg/config_validate.py +14 -2
  19. package/md_cg/constraint_audit.py +231 -0
  20. package/md_cg/constraint_watch.py +206 -0
  21. package/md_cg/context_audit.py +240 -0
  22. package/md_cg/context_plan.py +142 -0
  23. package/md_cg/detrerank.py +137 -0
  24. package/md_cg/distill.py +247 -0
  25. package/md_cg/dossier.py +151 -0
  26. package/md_cg/entities.py +133 -0
  27. package/md_cg/fsutil.py +135 -0
  28. package/md_cg/govern/__init__.py +23 -0
  29. package/md_cg/iface/__init__.py +46 -0
  30. package/md_cg/iface/_verify.py +609 -0
  31. package/md_cg/iface/contracts.py +337 -0
  32. package/md_cg/judgment_manifest.py +14 -0
  33. package/md_cg/kernel/__init__.py +27 -0
  34. package/md_cg/mcp_server.py +6044 -5761
  35. package/md_cg/mdcg.py +501 -16
  36. package/md_cg/mdcos.py +546 -12
  37. package/md_cg/metacognition.py +66 -13
  38. package/md_cg/mutate_extract_shipped.py +126 -0
  39. package/md_cg/mutate_ledger_e2e.py +100 -0
  40. package/md_cg/op_table.py +22 -0
  41. package/md_cg/probe_c_ledger_integrity.py +258 -0
  42. package/md_cg/probe_d_retirement_discipline.py +263 -0
  43. package/md_cg/profiles.py +298 -0
  44. package/md_cg/protocol.py +7 -1
  45. package/md_cg/reldate.py +142 -0
  46. package/md_cg/review_cli.py +6 -1
  47. package/md_cg/run_tests.py +30 -1
  48. package/md_cg/scopeselect.py +214 -0
  49. package/md_cg/scrub.py +66 -9
  50. package/md_cg/selfstmt.py +139 -0
  51. package/md_cg/state_extract.py +149 -0
  52. package/md_cg/state_slots.py +62 -10
  53. package/md_cg/state_view.py +181 -0
  54. package/md_cg/structboost.py +179 -0
  55. package/md_cg/sustain.py +28 -2
  56. package/md_cg/test_alternatives_historical.py +165 -0
  57. package/md_cg/test_b2_sensitivity_landing.py +226 -223
  58. package/md_cg/test_b3_merge_keeps_content.py +608 -583
  59. package/md_cg/test_bucket_cards.py +85 -0
  60. package/md_cg/test_bucket_day_order.py +74 -0
  61. package/md_cg/test_bucket_quota.py +79 -0
  62. package/md_cg/test_bucket_recency_guards.py +75 -0
  63. package/md_cg/test_bucket_three_causes.py +83 -0
  64. package/md_cg/test_bucket_time_rounds.py +87 -0
  65. package/md_cg/test_bucketindex.py +130 -0
  66. package/md_cg/test_bucketscope_early.py +71 -0
  67. package/md_cg/test_cohesion.py +107 -0
  68. package/md_cg/test_cond_term_fold_gate.py +1210 -0
  69. package/md_cg/test_cond_term_neg_scope.py +147 -0
  70. package/md_cg/test_constraint_audit.py +87 -0
  71. package/md_cg/test_constraint_watch.py +108 -0
  72. package/md_cg/test_context_audit.py +110 -0
  73. package/md_cg/test_context_plan.py +81 -0
  74. package/md_cg/test_detrerank.py +157 -0
  75. package/md_cg/test_gate_four_kpi.py +136 -0
  76. package/md_cg/test_generation_guard.py +14 -2
  77. package/md_cg/test_issue192_move_layer_indices_guard.py +48 -0
  78. package/md_cg/test_issue39_utf8_stdio.py +572 -572
  79. package/md_cg/test_issue413_preimage_failclosed.py +147 -9
  80. package/md_cg/test_issue768_overwrite_time_window_anchor.py +135 -0
  81. package/md_cg/test_issue789_log_plaintext_probe.py +100 -0
  82. package/md_cg/test_issue790_verb_negation.py +77 -0
  83. package/md_cg/test_issue810_root_guard.py +71 -0
  84. package/md_cg/test_issue812_info_index_stale.py +78 -0
  85. package/md_cg/test_issue827_weaken_dedup.py +361 -0
  86. package/md_cg/test_issue829_calibration_positive_gate.py +473 -0
  87. package/md_cg/test_kernel_iface_contracts.py +18 -0
  88. package/md_cg/test_md_cg_no_hive_dep.py +238 -17
  89. package/md_cg/test_probe_cd_shipped.py +385 -0
  90. package/md_cg/test_recent_tail.py +93 -0
  91. package/md_cg/test_run_tests_entry_gates.py +110 -0
  92. package/md_cg/test_scopeselect.py +70 -0
  93. package/md_cg/test_scopeselect_clock.py +70 -0
  94. package/md_cg/test_session_attribution_consistency.py +835 -813
  95. package/md_cg/test_state_extract_shipped.py +162 -0
  96. package/md_cg/test_state_ledger_chain.py +207 -0
  97. package/md_cg/test_state_ledger_e2e.py +145 -0
  98. package/md_cg/test_structboost.py +102 -0
  99. package/md_cg/test_timeboost.py +83 -0
  100. package/md_cg/test_timeboost_relativedate.py +71 -0
  101. package/md_cg/test_topicagg.py +129 -0
  102. package/md_cg/timeboost.py +223 -0
  103. package/md_cg/tokens.py +1 -1
  104. package/md_cg/topicagg.py +142 -0
  105. package/md_cg/version_anchor.py +84 -1
  106. package/md_cg/whitebox_kb/wisdom/code_compose.py +33 -5
  107. package/md_cg/whitebox_kb/wisdom/code_solidified.json +6195 -6195
  108. package/md_cg/whitebox_kb/wisdom/compose_engine.py +5 -1
  109. package/md_cg/whitebox_kb/wisdom/role_compose.py +271 -268
  110. package/package.json +1 -1
  111. package/src/hooks.ts +43 -1
  112. package/ui/minimal/payload/build-ui.mjs +41 -2
  113. package/ui/minimal/payload/lib/client.js +29 -3
  114. package/ui/minimal/payload/web/app.js +3 -1
  115. package/ui/minimal/payload/web/client.js +30 -3
  116. package/web/app.js +3 -1
  117. package/web/client.js +30 -3
  118. package/zcode/AGENTS.md +1 -1
@@ -0,0 +1,609 @@
1
+ # -*- coding: utf-8 -*-
2
+ """W1 验收守卫:契约类型 + 导入图单向性(路线稿 §9 W1「验收可判」)。
3
+
4
+ 判定两件事,各自可红可绿:
5
+
6
+ ① **契约单测**(`_test_contracts`):四个契约的名字/形状/不变量真的成立——
7
+ `provenance` 必填、`why` 必填、打分层吐 `state` 必红、`status()` 四键齐备、
8
+ `WriteReceipt` 无账必红、`ContractViolation.code` 稳定可断言。
9
+
10
+ ② **导入图无反向依赖**(`_test_import_direction`):按路线稿 §2 分层
11
+ `adapter > iface > govern > kernel`,**下层不得 import 上层**;
12
+ 且 `md_cg/kernel` 与 `md_cg/govern` 不得出现 `from ..dsh`、不得出现
13
+ 宿主类型(`mcp`、`aiohttp`、`starlette`、`flask`、`fastapi`)。
14
+
15
+ 生效条件:以 `ast` 静态解析本仓 `md_cg/kernel` 与 `md_cg/govern` 下全部 `.py`
16
+ (不执行、不 import、零副作用);本守卫自带夹具(临时目录写样例模块)验证
17
+ 「反向依赖真的能被抓到」,故不是恒绿断言。
18
+
19
+ 不适用条件:
20
+ - **不检查** `md_cg/mdcos.py` 等存量单体——那是 M5 的目标,W1 只管新骨架;
21
+ - **不检查** 运行时动态 import(`importlib`)——静态看不住,留给 M2 的运行时守卫;
22
+ - **不承诺** 契约的**实现**已在位:W1 只交付骨架,实现属 M2–M4。
23
+
24
+ 验证方式:`python -X utf8 -m md_cg.test_kernel_iface_contracts`
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import ast
30
+ import contextlib
31
+ import io
32
+ import os
33
+ import shutil
34
+ import tempfile
35
+ import sys
36
+ import tempfile
37
+
38
+ from . import contracts as C
39
+ from .contracts import (
40
+ CONTRACT_NAMES,
41
+ ContractViolation,
42
+ ReadItem,
43
+ ReadRequest,
44
+ SelfCheckReport,
45
+ WriteReceipt,
46
+ WriteRequest,
47
+ reject_state_in_scoring,
48
+ require_provenance,
49
+ require_why,
50
+ )
51
+
52
+ _REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
53
+
54
+ #: 路线稿 §2 的分层顺序(上 → 下)。下层 import 上层即「反向依赖」。
55
+ _LAYERS = ("adapter", "iface", "govern", "kernel")
56
+
57
+ #: 宿主类型:内核/治理层出现即判耦合(路线稿 §2 禁止项)。
58
+ #: **按全名分段匹配**(见 `_violations`),不再只看首段——否则
59
+ #: `from md_cg.mcp_server import x` 这类本仓最自然的违规写法会整段穿网。
60
+ _HOST_MODULES = (
61
+ "mcp", "mcp_server", # 本仓 md_cg/mcp_server.py 即宿主接线面
62
+ "hooks", "plugin", "inject", # 宿主注入面
63
+ "aiohttp", "starlette", "flask", "fastapi", "requests", # HTTP 框架
64
+ )
65
+
66
+ #: 分层序号:数字越小越靠上。下层引用层号**更小**的即反向依赖。
67
+ _LAYER_RANK = {name: rank for rank, name in enumerate(_LAYERS)}
68
+
69
+ #: 需要扫描的层:``_LAYERS`` 里除最顶层(``adapter``)之外**全部**。
70
+ #:
71
+ #: 为什么从 ``_LAYERS`` 推导而不是手写 ``("kernel", "govern")``:
72
+ #: 手写清单会与 ``_LAYERS`` 漂移——事实就是漂了,「iface 层引 adapter」这类
73
+ #: 反向依赖在 ``_violations`` 里判得出来,却因为层名不在手写清单里而**从不被扫**,
74
+ #: 形成第二个「判据有、守卫不接电」的盲区。此处从真值表推导,加层即自动覆盖。
75
+ #:
76
+ #: ``adapter`` 不扫:它是宿主接线层(路线稿 §2 顶端),允许向下引用任意内层,
77
+ #: 不存在「反向」可言。
78
+ _INTERNAL_LAYERS = tuple(name for name in _LAYERS if name != "adapter")
79
+
80
+ _results = []
81
+
82
+
83
+ def _check(name, fn):
84
+ try:
85
+ fn()
86
+ except AssertionError as exc:
87
+ _results.append((name, False, str(exc)))
88
+ print(f"FAIL {name}\n {exc}")
89
+ except Exception as exc: # noqa: BLE001 - 守卫需报出任意异常
90
+ _results.append((name, False, f"{type(exc).__name__}: {exc}"))
91
+ print(f"FAIL {name}\n {type(exc).__name__}: {exc}")
92
+ else:
93
+ _results.append((name, True, ""))
94
+ print(f"PASS {name}")
95
+
96
+
97
+ # --------------------------------------------------------------------------
98
+ # ① 契约单测
99
+ # --------------------------------------------------------------------------
100
+
101
+ def _test_contract_names():
102
+ assert CONTRACT_NAMES == ("Write", "Read", "Govern", "SelfCheck"), (
103
+ f"契约必须恰好四个且顺序固定,实为 {CONTRACT_NAMES!r}"
104
+ )
105
+
106
+
107
+ def _test_write_requires_provenance():
108
+ # 三态全红,且 code 稳定
109
+ for value, want in ((None, "missing_provenance"), ({}, "empty_provenance"), ("x", "not_a_mapping")):
110
+ try:
111
+ require_provenance(value)
112
+ except ContractViolation as exc:
113
+ assert exc.code == want, f"provenance={value!r} 应得 code={want},实得 {exc.code}"
114
+ else:
115
+ raise AssertionError(f"provenance={value!r} 必须抛 ContractViolation,实际通过了")
116
+ # 正常态放行
117
+ assert require_provenance({"src": "mem_1"}) == {"src": "mem_1"}
118
+
119
+
120
+ def _test_write_request_shape():
121
+ req = WriteRequest("mem_1", "正文", conditions={"c": 1}, provenance={"src": "s"})
122
+ d = req.as_dict()
123
+ assert set(d) == {"node_id", "content", "conditions", "provenance"}, f"as_dict 键面不符: {sorted(d)}"
124
+ assert req.digest() == WriteRequest("mem_1", "正文", conditions={"c": 1}, provenance={"src": "s"}).digest(), (
125
+ "同内容同依据的指纹必须相等"
126
+ )
127
+ assert req.digest() != WriteRequest("mem_1", "正文2", provenance={"src": "s"}).digest(), (
128
+ "内容变则指纹必须变"
129
+ )
130
+ # 构造期即校验:缺 provenance 必须在构造时红,而非等到写入
131
+ try:
132
+ WriteRequest("mem_1", "正文")
133
+ except ContractViolation as exc:
134
+ assert exc.code == "missing_provenance", exc.code
135
+ else:
136
+ raise AssertionError("WriteRequest 缺 provenance 必须在构造期抛错")
137
+
138
+
139
+ def _test_write_request_immutable():
140
+ """``WriteRequest`` 必须**真不可变**:属性赋值与 mapping 内部改写都要被拒。
141
+
142
+ 为什么单列一条:``__slots__`` 只防新增属性、不防重新赋值,而 ``digest()``
143
+ 每次重算 ⇒ 指纹可被外部改写污染。没有这条断言,「不可变」只是 docstring 上
144
+ 的一句话。
145
+ """
146
+ req = WriteRequest("mem_1", "正文", conditions={"c": 1}, provenance={"src": "s"})
147
+ digest0 = req.digest()
148
+
149
+ for attr, value in (("node_id", "hacked"), ("content", "篡改"), ("conditions", {}), ("provenance", {})):
150
+ try:
151
+ setattr(req, attr, value)
152
+ except AttributeError:
153
+ pass
154
+ else:
155
+ raise AssertionError(f"WriteRequest 必须拒绝给 {attr!r} 赋值(否则指纹可被污染)")
156
+
157
+ for mapping in ("provenance", "conditions"):
158
+ try:
159
+ getattr(req, mapping)["k"] = 1 # type: ignore[index]
160
+ except TypeError:
161
+ pass
162
+ else:
163
+ raise AssertionError(f"WriteRequest.{mapping} 必须是只读视图,不得内部改写")
164
+
165
+ assert req.digest() == digest0, "不可变对象上 digest() 必须恒定(指纹被污染即失守)"
166
+
167
+
168
+ def _test_write_receipt_requires_ledger():
169
+ ok = WriteReceipt("r1", "mem_1", "active", "d" * 64, {"status": "ok"})
170
+ assert ok.as_dict()["id"] == "r1"
171
+ try:
172
+ WriteReceipt("r1", "mem_1", "active", "d" * 64, {})
173
+ except ContractViolation as exc:
174
+ assert exc.code == "empty_ledger", exc.code
175
+ else:
176
+ raise AssertionError("写回执无账必须红——「写失败必须留账」是 W1 不变量")
177
+ try:
178
+ WriteReceipt("r1", "mem_1", "bogus", "d" * 64, {"k": 1})
179
+ except ContractViolation as exc:
180
+ assert exc.code == "bad_state", exc.code
181
+ else:
182
+ raise AssertionError("非法 state 必须红")
183
+
184
+
185
+ def _test_read_requires_why():
186
+ for value, want in ((None, "missing_why"), ("", "empty_why"), (" ", "empty_why"), (1, "not_a_string")):
187
+ try:
188
+ require_why(value)
189
+ except ContractViolation as exc:
190
+ assert exc.code == want, f"why={value!r} 应得 {want},实得 {exc.code}"
191
+ else:
192
+ raise AssertionError(f"why={value!r} 必须红")
193
+ item = ReadItem("mem_1", 0.9, "命中:标题含《灵枢》", "active", "mem_1#L3")
194
+ assert item.as_dict()["why"], "ReadItem.why 不得为空"
195
+ assert item.as_dict()["evidence_ref"] == "mem_1#L3", "evidence_ref 必须可定位(#593 推论 C)"
196
+
197
+
198
+ def _test_read_state_only_from_govern():
199
+ # 打分层吐 state 必红
200
+ try:
201
+ reject_state_in_scoring([{"id": "a", "score": 1.0, "state": "active"}])
202
+ except ContractViolation as exc:
203
+ assert exc.code == "state_in_scoring", exc.code
204
+ else:
205
+ raise AssertionError("打分层吐 state 必须红(#111 / 路线稿 §4)")
206
+ # 完全不带 state 才放行
207
+ assert reject_state_in_scoring([{"id": "a", "score": 1.0}]) == [{"id": "a", "score": 1.0}]
208
+ # state 为空串/None 视作未输出
209
+ assert reject_state_in_scoring([{"id": "a", "score": 1.0, "state": ""}]), "空 state 不应误红"
210
+
211
+
212
+ def _test_selfcheck_four_keys():
213
+ rep = SelfCheckReport(counts={"nodes": 3}, lag=0.5, drift=False, wal_ok=True)
214
+ assert rep.missing_keys() == [], f"四键必须齐备,缺 {rep.missing_keys()}"
215
+ assert set(rep.as_dict()) == {"counts", "lag", "drift", "wal_ok"}, "status() 返回键面不符"
216
+
217
+
218
+ def _test_protocols_runtime_checkable():
219
+ for proto, name in (
220
+ (C.WriteContract, "Write"),
221
+ (C.ReadContract, "Read"),
222
+ (C.GovernContract, "Govern"),
223
+ (C.SelfCheckContract, "SelfCheck"),
224
+ ):
225
+ assert isinstance(proto, type) or hasattr(proto, "_is_protocol"), f"{name} 必须是 Protocol"
226
+ methods = {
227
+ "Write": ["write"],
228
+ "Read": ["read"],
229
+ "Govern": ["revise", "retire", "rollback", "audit"],
230
+ "SelfCheck": ["status"],
231
+ }[name]
232
+ for m in methods:
233
+ assert hasattr(proto, m), f"{name} 契约缺方法 {m}"
234
+
235
+
236
+ # --------------------------------------------------------------------------
237
+ # ② 导入图单向性
238
+ # --------------------------------------------------------------------------
239
+
240
+ def _iter_py(pkg_dir):
241
+ if not os.path.isdir(pkg_dir):
242
+ return
243
+ for root, dirs, files in os.walk(pkg_dir):
244
+ dirs[:] = [d for d in dirs if d != "__pycache__"]
245
+ for fn in files:
246
+ if fn.endswith(".py"):
247
+ yield os.path.join(root, fn)
248
+
249
+
250
+ def _imported_names(path):
251
+ """静态解析出该文件的 import 名集合(不执行)。
252
+
253
+ 形态:绝对导入保留全名(``md_cg.mcp_server``);相对导入保留前导点
254
+ (``..mcp_server`` / ``.``)。**空 module 的相对导入也保留**——它是
255
+ ``from . import x`` 的形态,绝不能被静默丢掉(否则该形态完全不可见)。
256
+
257
+ 别名必须一起保留——这是本函数曾经的致命缺陷。``from X import a`` 在语义上
258
+ 等价于``import X.a``,被导入的是 ``X`` **加上** 别名 ``a``。只记 ``X`` 会
259
+ 让「别名才是违规所在」的写法整段穿网:
260
+
261
+ from md_cg import mcp_server 记成 ``md_cg`` → 判据看不见 mcp_server
262
+ from .. import mcp_server 记成 ``..`` → 判据更看不见
263
+ from . import mcp_server 记成 ``.`` → 连目标包都丢失
264
+
265
+ 三条都是「宿主模块在别名位、包名完全干净」的最自然写法,也正是路线稿 §2
266
+ 要禁的东西。故对每个别名补一条 ``base + "." + alias``。
267
+ """
268
+ with io.open(path, "r", encoding="utf-8") as fh:
269
+ source = fh.read()
270
+ tree = ast.parse(source, filename=path)
271
+ names = set()
272
+ for node in ast.walk(tree):
273
+ if isinstance(node, ast.Import):
274
+ for a in node.names:
275
+ names.add(a.name)
276
+ elif isinstance(node, ast.ImportFrom):
277
+ base = node.module or ""
278
+ star = any(a.name == "*" for a in node.names)
279
+ aliases = [a.name for a in node.names if a.name != "*"]
280
+ # `from X import a` 的被导入对象是 **X.a**,不是 X 本身。
281
+ # 只有「星号导入」或「没有别名」时,X 才单独构成一条导入记录。
282
+ # 若在此额外记一条裸 ``X``,像 `from md_cg import kernel` 这样的
283
+ # **合法**写法会因为裸 ``md_cg`` 解析不出目标段而被 fail-closed 误判成
284
+ # 违规——这是修别名盲区时自己引入的假红,实测确认过。
285
+ if star or not aliases:
286
+ names.add("." * node.level + base if node.level else base)
287
+ for alias in aliases:
288
+ tail = f"{base}.{alias}" if base else alias
289
+ # 相对导入要在**去掉点之后再拼**,拼完补回同样多的点:
290
+ # level=2, base="", alias="mcp_server" → "..mcp_server"
291
+ # 天真地用 f"{stem}.{alias}" 会得到 "...mcp_server"(多一层),
292
+ # 层级多算一层正是本函数要避免的那类偏移。
293
+ names.add("." * node.level + tail if node.level else tail)
294
+ return names
295
+
296
+
297
+ def _resolve_fqn(rel_file, name, root=None):
298
+ """把一条 import 记录解析成**从 md_cg 起算的绝对全名**。
299
+
300
+ 相对导入按所在文件的位置合成:``md_cg/kernel/x.py`` 里的
301
+ ``..mcp_server`` → ``md_cg.mcp_server``;``.`` → 所在包的 ``__init__``
302
+ (返回 ``md_cg.kernel`` 这类包名,供后续分段判定)。
303
+
304
+ 返回 (segments, kind):segments 是从 ``md_cg`` 之后开始的段列表
305
+ (``md_cg.mcp_server`` → ``["mcp_server"]``);无法解析时返回 ([], name)。
306
+ """
307
+ # 文件相对仓根的路径 → 包段(去掉 md_cg 之前的部分与 .py)
308
+ # 解析根可注入(`root`):夹具要在**临时目录**里跑,绝不能在真树里写文件。
309
+ # 不变量:`x.py` 与 `__init__.py` 同属一个包,同一条相对导入必须解析一致。
310
+ root = _REPO if root is None else root
311
+ rel = os.path.relpath(os.path.abspath(rel_file), root).replace(os.sep, "/")
312
+ parts = rel[:-3].split("/") if rel.endswith(".py") else rel.split("/")
313
+ is_pkg_init = bool(parts) and parts[-1] == "__init__"
314
+ if is_pkg_init:
315
+ parts = parts[:-1]
316
+ # 定位 md_cg 在路径里的位置
317
+ if "md_cg" not in parts:
318
+ return [], name
319
+ idx = parts.index("md_cg")
320
+ # cur = **当前文件所在的包**(相对 md_cg)。
321
+ # md_cg/kernel/x.py → ['kernel'](文件所在的包)
322
+ # md_cg/kernel/__init__.py → ['kernel'](同一个包,不能少这一层)
323
+ # 曾经一律写 `parts[idx+1:-1]`,对 `__init__.py` 会错误地再切掉一层变成 `[]`,
324
+ # 于是**同一个包内的同一条相对导入**在 `x.py` 与 `__init__.py` 里解析出不同结果:
325
+ # `.foo` → x.py 得 md_cg.kernel.foo,__init__.py 却得 md_cg.foo
326
+ # 而 W1 骨架的 kernel/ 与 govern/ 目录下**恰好只有 __init__.py**,
327
+ # 即这条偏移对真树是百分之百命中,不是边角情形。
328
+ cur = parts[idx + 1:] if is_pkg_init else parts[idx + 1:-1]
329
+ level = len(name) - len(name.lstrip("."))
330
+ body = name.lstrip(".")
331
+ if level == 0: # 绝对导入
332
+ segs = body.split(".")
333
+ if segs and segs[0] == "md_cg":
334
+ segs = segs[1:]
335
+ return segs, name
336
+ # 相对导入:level=1 指当前包,level=2 指父包
337
+ up = level - 1
338
+ # 越过 md_cg 包根:`len(cur)` 不够上溯。此处**必须显式返回空段**,
339
+ # 不能像旧写法那样 `else []` 静默截成空列表——那样 `from ... import x`
340
+ # 在 md_cg/kernel/ 下会拼出 `['x']`,即被当成 `md_cg.x` 这份**合法**导入,
341
+ # 于是「越过包根」这个真正不可判的形态被伪装成了正常引用。
342
+ if up > len(cur):
343
+ return [], name
344
+ base = cur[:len(cur) - up] if up else list(cur)
345
+ tail = body.split(".") if body else []
346
+ return base + tail, name
347
+
348
+
349
+ def _violations(layer, relpath, names, file_path=None, root=None):
350
+ """导入图判据**唯一实现**:给定层名与一组 import 记录,返回违规说明列表。
351
+
352
+ 这是**纯函数**(不做 IO),守卫与夹具自证共用它——因此「删掉判据就必红」,
353
+ 不会出现「断的是 ast 能不能解析 import」这种恒真断言。
354
+
355
+ 判据(路线稿 §2):
356
+ 1. 宿主类型:全名**任一段**命中 ``_HOST_MODULES`` 即判耦合;
357
+ 2. 宿主包:全名含 ``dsh`` 段即判耦合;
358
+ 3. 反向依赖:本层引用层号更小的层(如 kernel 引 iface/govern/adapter)。
359
+ """
360
+ problems = []
361
+ rank = _LAYER_RANK.get(layer)
362
+ for name in names:
363
+ if file_path:
364
+ segs, _ = _resolve_fqn(file_path, name, root=root)
365
+ else: # 夹具不落地时按字面分段
366
+ segs = name.lstrip(".").split(".") if name.lstrip(".") else []
367
+ # 与 `_resolve_fqn` 的绝对导入分支保持**同一口径**:剥掉包根 `md_cg`。
368
+ # 不剥就会让 `md_cg.adapter` 的首段变成 `md_cg`(不是层名),
369
+ # 反向依赖判据整条穿网——这正是宿主类型判据上
370
+ # 「`from md_cg.mcp_server import x` 首段是 md_cg 故不命中」的同型盲区,
371
+ # 上一轮只修了宿主类型那条路,反向依赖这条一直没修。现两条都按剥根后判定。
372
+ if segs and segs[0] == "md_cg":
373
+ segs = segs[1:]
374
+ # 1) 宿主类型:任意段命中(不再只看首段)
375
+ hit = [s for s in segs if s in _HOST_MODULES]
376
+ if hit:
377
+ problems.append(f"{relpath} 引宿主类型 {name!r}(命中段 {hit},路线稿 §2 禁止项)")
378
+ # 2) 宿主包
379
+ if "dsh" in segs:
380
+ problems.append(f"{relpath} 引宿主包 {name!r}(路线稿 §2 禁止项)")
381
+ # 3) 反向依赖
382
+ if rank is not None and segs:
383
+ head = segs[0]
384
+ other = _LAYER_RANK.get(head)
385
+ if other is not None and other < rank:
386
+ problems.append(f"{relpath} {layer} 层反向依赖上层 {name!r}(路线稿 §2)")
387
+ # 4) 解析不出目标段:显式报错,不许静默跳过。
388
+ # 真实形态:`md_cg/kernel/__init__.py` 里写 `from .. import x`——
389
+ # level=2 越过了 md_cg 这一点,合成后为空段。静默跳过就漏报。
390
+ if not segs and not file_path:
391
+ pass # 无 file_path 时由调用方负责给出可解析的名字
392
+ elif not segs:
393
+ problems.append(
394
+ f"{relpath} 导入 {name!r} 解析不出目标段(越过 md_cg 包根)——"
395
+ "无法判定归属,按 fail-closed 记为违规"
396
+ )
397
+ return problems
398
+
399
+
400
+ def _scan_layers():
401
+ """守卫**实际扫描**的层清单——单独成函数,好让覆盖性断言直接盯它。
402
+
403
+ 为什么不让它内联在 ``_test_import_direction`` 里:内联时,把循环的取值
404
+ 换成手写元组(``for layer in ("kernel", "govern")``)不会有任何断言变红
405
+ ——我实测过,覆盖性用例照样 PASS。抽成函数后,覆盖性用例断言的是
406
+ **扫描器自己**,而不是一个旁边放着的常量,于是「扫描范围退回手写清单」
407
+ 这种回退能被抓住。
408
+ """
409
+ return _INTERNAL_LAYERS
410
+
411
+
412
+ def _test_import_direction():
413
+ """kernel / govern / iface 不得 import 上层,也不得碰宿主类型。"""
414
+ problems = []
415
+ for layer in _scan_layers():
416
+ pkg = os.path.join(_REPO, "md_cg", layer)
417
+ for path in _iter_py(pkg):
418
+ rel = os.path.relpath(path, _REPO)
419
+ problems.extend(_violations(layer, rel, _imported_names(path), path))
420
+ assert not problems, "导入图违规:\n " + "\n ".join(problems)
421
+
422
+
423
+ @contextlib.contextmanager
424
+ def _fixture_repo():
425
+ """在**临时目录**里搭一个最小假仓(``md_cg/{kernel,govern,iface}/``)。
426
+
427
+ 用于「夹具自证」类断言:这些断言需要真实文件系统上的包结构才能跑,
428
+ 但**绝不能**在真树里建删文件——``run_tests.py`` 默认 ``--jobs 4`` 并行,
429
+ 多线程同时建删同名路径会互相污染;且任何一次中断都会把临时文件留在仓里。
430
+ 假仓每次新建、退出即删,天然并行安全。
431
+ """
432
+ repo = tempfile.mkdtemp(prefix="w1_fixture_")
433
+ try:
434
+ for layer in _LAYERS:
435
+ os.makedirs(os.path.join(repo, "md_cg", layer), exist_ok=True)
436
+ io.open(os.path.join(repo, "md_cg", "__init__.py"), "w", encoding="utf-8").write("")
437
+ yield repo
438
+ finally:
439
+ shutil.rmtree(repo, ignore_errors=True)
440
+
441
+
442
+ def _test_import_guard_catches_violation():
443
+ """守卫自证:真的能在**夹具**里抓到反向依赖与宿主类型(防「恒绿断言」)。
444
+
445
+ 关键:断言走的是**与真实扫描同一个 `_violations()`**,而不是「ast 能否
446
+ 解析出 import 名」。因此把 `_HOST_MODULES` 或反向依赖判据整段删掉,本用例
447
+ 必然转红——这正是它区别于恒真断言的地方。
448
+ """
449
+ # 夹具落在**临时目录**里搭的假仓,绝不写进真树。
450
+ # 曾经的写法直接在 `md_cg/kernel/` 下建文件再删:`run_tests.py` 默认
451
+ # `--jobs 4` 并行,多线程同时建删同名路径会互相污染(A 删了 B 刚建的文件),
452
+ # 且任何一次中断都会把临时文件留在仓里。假仓 + 注入 root 两个问题一起消掉。
453
+ with _fixture_repo() as repo:
454
+ kernel_dir = os.path.join(repo, "md_cg", "kernel")
455
+ cases = [
456
+ # (夹具源码, 夹具文件名, 期望违规关键词)
457
+ ("from mcp.server import x\n", "bad_mcp.py", "宿主类型"),
458
+ ("from md_cg.mcp_server import x\n", "bad_host.py", "宿主类型"),
459
+ ("from ..mcp_server import x\n", "bad_rel.py", "宿主类型"),
460
+ ("from ..govern import y\n", "bad_gov.py", "反向依赖"),
461
+ ("from ..iface import contracts\n", "bad_iface.py", "反向依赖"),
462
+ # 宿主包(`dsh`)判据的夹具:缺了它,把「dsh in segs」删掉也不会红
463
+ ("from ..dsh import plugin\n", "bad_dsh.py", "宿主包"),
464
+ # 多段穿透:首段是 md_cg,真正的宿主模块在第 2 段
465
+ ("from md_cg.hooks import inject\n", "bad_deep.py", "宿主类型"),
466
+ # 越过包根:md_cg/kernel/x.py 里写 `from ... import y` —— 上溯层数
467
+ # 超过 md_cg 包根,归属不可判。静默截断会把它伪装成 `md_cg.y`,
468
+ # 故按 fail-closed 记为违规。
469
+ ("from ... import y\n", "bad_overroot.py", "解析不出目标段"),
470
+ # `from .. import x`(kernel 下的文件)**是合法的**:level=2 恰好
471
+ # 指到 md_cg 包根,合成 `md_cg.x`。这条曾经被当作「越过包根」的
472
+ # 违规用例——那只是丢别名缺陷造成的假象,修好后必须放过。
473
+ ("from .. import x\n", "ok_rootpkg.py", None),
474
+ # `from . import govern` 解析为 md_cg.kernel.govern(同包内),
475
+ # 不是反向依赖、也不是空名——它**必须被判为干净**,
476
+ # 这样判据才不会把正常的同包引用误伤成违规。
477
+ ("from . import helpers\n", "ok_samepkg.py", None),
478
+ # ---- 别名位盲区回归(本轮实测确认的 3 处穿网形态)----
479
+ # 三条的共同点:**包名本身完全干净**,违规的是别名。
480
+ # 旧 `_imported_names` 只记包名、丢掉别名,于是三条全绿。
481
+ # `from . import mcp_server` → 旧: ['.'] → 0 条
482
+ ("from . import mcp_server\n", "bad_alias_dot.py", "宿主类型"),
483
+ # `from .. import mcp_server` → 旧: ['..'] → 仅靠「空段」碰巧兜住,
484
+ # 一旦按作者选项 3 放过空段就真穿网;修后由别名判据直接命中。
485
+ ("from .. import mcp_server\n", "bad_alias_up.py", "宿主类型"),
486
+ # `from md_cg import mcp_server` → 旧: ['md_cg'] → 靠「空段」兜住,同型。
487
+ ("from md_cg import mcp_server\n", "bad_alias_abs.py", "宿主类型"),
488
+ # ---- 假红回归:修别名时必须**只记别名**,不能额外记一条裸包名 ----
489
+ # `from md_cg import kernel` 是合法写法(同层导入自己的包),
490
+ # 但裸 ``md_cg`` 解析不出目标段,会被 fail-closed 误判成违规。
491
+ # 下面两条一正一反,把「只记 X.a、不记 X」这个不变量钉死。
492
+ ("from md_cg import kernel\n", "ok_selfpkg.py", None),
493
+ ("from md_cg import iface\n", "bad_alias_layer.py", "反向依赖"),
494
+ ]
495
+ for source, fname, want in cases:
496
+ relpath = "md_cg/kernel/" + fname
497
+ # 必须走**真实的** `_imported_names`,不能在这里另手写一套解析。
498
+ # 这里原先是 `line.split(" import ")[0]` 只看包名——等于把
499
+ # `_imported_names` 的「丢别名」缺陷在夹具里原样抄了一遍,
500
+ # 于是三条别名盲区夹具喂进去的仍然是干净包名,守卫再对也必绿。
501
+ # 夹具与被测路径共用同一个解析器,这个 bug 才不可能被夹具自己掩盖。
502
+ fixture = os.path.join(kernel_dir, fname)
503
+ io.open(fixture, "w", encoding="utf-8").write(source)
504
+ names = _imported_names(fixture)
505
+ got = _violations("kernel", relpath, names, fixture, root=repo)
506
+ joined = " | ".join(got)
507
+ if want is None:
508
+ assert not got, f"夹具 {fname}({source.strip()!r})应判为干净,实得 {got!r}"
509
+ else:
510
+ assert got and want in joined, (
511
+ f"夹具 {fname}({source.strip()!r})应判出「{want}」,实得 {got!r}"
512
+ )
513
+
514
+
515
+ def _test_import_guard_clean_on_real_tree():
516
+ """真树上当前骨架必须是干净的(与上一条夹具自证互为对照)。"""
517
+ for layer in _scan_layers():
518
+ pkg = os.path.join(_REPO, "md_cg", layer)
519
+ assert os.path.isdir(pkg), f"W1 骨架缺失:md_cg/{layer}"
520
+ for path in _iter_py(pkg):
521
+ rel = os.path.relpath(path, _REPO)
522
+ assert not _violations(layer, rel, _imported_names(path), path), (
523
+ f"{rel} 不该有导入图违规"
524
+ )
525
+
526
+
527
+ def _test_pkg_init_resolves_like_sibling_module():
528
+ """同一个包内的同一条相对导入,在 ``x.py`` 与 ``__init__.py`` 里必须解析一致。
529
+
530
+ 为什么单列一条:变异测试显示,把 ``__init__.py`` 的定位改回
531
+ ``parts[idx+1:-1]``(即 ``cur=[]``),**13 条用例全绿**——因为没有任何
532
+ 断言盯过这个分支。而 W1 骨架里 ``kernel/`` 与 ``govern/`` 目录下
533
+ **只有 __init__.py**,这条偏移对真树是百分之百命中,不是边角情形。
534
+
535
+ 语义基准:``md_cg/kernel/x.py`` 与 ``md_cg/kernel/__init__.py`` 同属
536
+ ``md_cg.kernel`` 包,故 ``.foo`` 在两者中都应是 ``md_cg.kernel.foo``。
537
+ """
538
+ sibling = os.path.join(_REPO, "md_cg", "kernel", "_probe_sibling.py")
539
+ init = os.path.join(_REPO, "md_cg", "kernel", "__init__.py")
540
+ for name, want in (
541
+ (".foo", ["kernel", "foo"]),
542
+ ("..govern", ["govern"]),
543
+ ("..mcp_server", ["mcp_server"]),
544
+ ):
545
+ got_sibling = _resolve_fqn(sibling, name)[0]
546
+ got_init = _resolve_fqn(init, name)[0]
547
+ assert got_sibling == want, f"x.py 里 {name!r} 应解析为 {want},实得 {got_sibling}"
548
+ assert got_init == want, (
549
+ f"__init__.py 里 {name!r} 应解析为 {want}(与同包的 x.py 一致),实得 {got_init}"
550
+ "—— __init__ 的相对定位偏了一层"
551
+ )
552
+ assert got_sibling == got_init, (
553
+ f"{name!r} 在 x.py 与 __init__.py 解析不一致:{got_sibling} vs {got_init}"
554
+ )
555
+
556
+
557
+ def _test_guard_covers_every_internal_layer():
558
+ """守卫必须对 ``_LAYERS`` 里**每个**内层都接电(防「判据有、扫描不覆盖」)。
559
+
560
+ 为什么单列一条:本仓已经栽过两次同型事故——先是判据只看首段(写法穿网),
561
+ 后是扫描层名手写成 ``("kernel", "govern")``(``iface`` 层从不被扫)。
562
+ 判据正确 ≠ 守卫生效:只要「被扫描的层」和 ``_LAYERS`` 漂开,反证就白写。
563
+ 这条断言把「覆盖范围」本身变成可红可绿的检查对象。
564
+ """
565
+ # 1) 扫描器必须真的覆盖 `_LAYERS` 里除顶层外的每一层。
566
+ # 断言对象是 `_scan_layers()`(扫描器本身),不是旁边的常量——
567
+ # 否则把循环改回手写 `("kernel", "govern")` 仍会绿(实测过)。
568
+ scanned = _scan_layers()
569
+ expected = tuple(n for n in _LAYERS if n != "adapter")
570
+ assert scanned == expected, (
571
+ f"扫描器覆盖层必须等于 _LAYERS 去掉顶层 adapter,实得 {scanned!r}(应为 {expected!r})"
572
+ )
573
+ assert "adapter" not in scanned, "adapter 是宿主接线层,不该被扫"
574
+
575
+ # 2) 逐层实证:对每个被扫描的层,「它引用最顶层 adapter」必须判出违规。
576
+ # 若某层漏在 `_LAYER_RANK` 里(层号查不到),这里必红。
577
+ for layer in scanned:
578
+ got = _violations(layer, f"md_cg/{layer}/_probe.py", {"md_cg.adapter"}, None)
579
+ assert got, f"{layer} 层引用 adapter 必须判为反向依赖,实际未判出(该层未接电)"
580
+
581
+
582
+ def main():
583
+ print("=== W1 验收:契约类型 + 导入图单向性 ===")
584
+ _check("契约恰好四个且顺序固定", _test_contract_names)
585
+ _check("Write.provenance 必填(三态全红)", _test_write_requires_provenance)
586
+ _check("WriteRequest 形状与指纹", _test_write_request_shape)
587
+ _check("WriteRequest 真不可变(指纹不可污染)", _test_write_request_immutable)
588
+ _check("WriteReceipt 无账必红", _test_write_receipt_requires_ledger)
589
+ _check("Read.why 必填(四态全红)", _test_read_requires_why)
590
+ _check("打分层吐 state 必红(#111)", _test_read_state_only_from_govern)
591
+ _check("SelfCheck 四键齐备", _test_selfcheck_four_keys)
592
+ _check("四契约 Protocol 方法面", _test_protocols_runtime_checkable)
593
+ _check("导入图单向(kernel/govern/iface)", _test_import_direction)
594
+ _check("导入图守卫夹具自证", _test_import_guard_catches_violation)
595
+ _check("守卫覆盖每个内层(防判据空转)", _test_guard_covers_every_internal_layer)
596
+ _check("__init__ 相对定位与同级模块一致", _test_pkg_init_resolves_like_sibling_module)
597
+ _check("真树骨架干净", _test_import_guard_clean_on_real_tree)
598
+
599
+ failed = [r for r in _results if not r[1]]
600
+ print()
601
+ print(f"===== W1 守卫:{len(_results) - len(failed)} 通过,{len(failed)} 失败 =====")
602
+ if failed:
603
+ print("失败:" + "、".join(r[0] for r in failed))
604
+ return 1
605
+ return 0
606
+
607
+
608
+ if __name__ == "__main__":
609
+ sys.exit(main())