docs(design): 落成 0006 与 0007,公共 API 的名字、签名与接缝行为

0006 定「叫什么、什么形状」:五个接缝的 Protocol 名与签名、公共类型的英文名与
字段清单、类型分到 types / ports / tools 三个模块的判据。
0007 定「同一个签名下什么算对」:三个动作状态的触发条件、动作被拒绝时观察由库
合成而不取执行器那段、解释器不许抛异常、read_log 读不存在的运行返回空日志。
两份拆开是因为后者的权威处按 §0 是 tests/contract/,design doc 只记当初为什么这么定。

这两份改动了 0003 四处,全部在文首登记:记录集合是六种东西不是五类;
参数视图是方法不是字段;预算是四项不是两个计数;ports 装「Protocol 与它们的
入参/返回结构体」那半句写不出来——照它写 types 会反向依赖 ports。
四处全是「把字段类型逐个写出来」这个动作本身逼出来的,纯读文档看不见。

四轮评审:两轮硕士生冷读报了约 45 条,两轮 Codex 对抗审查报了 13 条,
逐条核实后基本全部成立并修完。最后一轮是唯一一次契约测试与文档互相抓到对方的错——
文档改了方法名测试没跟,测试把 dissect 的动作语言写死成输入会误杀 GovDoc 的实现。

结论回写 architecture.md:第七节补类型归属判据,第八节改 ports 那一行,
第九节补五个 Protocol 的英文名,第十四节把「英文名还没定」那条缺口换成指向;
决策索引加两行。字段表刻意不回写——按 §0 那是代码的权威。
CLAUDE.md 与 README.md 开头的「一次 Agent Session」是术语漂移,改成「一次运行」。

CLAUDE.md §7 加两条工作方式:能压成一段结论的活尽量交给 subagent、
委托出去的活交证据不交判断;以及持续往下做,只在人类门和真判断不了的岔路停。
§8 那句「讲完停下来等回应」与后者打架,收窄到只管说话方式。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-09 23:56:38 -04:00
parent a14bf8d288
commit f8e02290f4
10 changed files with 986 additions and 34 deletions
+9 -5
View File
@@ -19,13 +19,17 @@ async def test_emit_accepts_an_event(event_sink, records):
await event_sink.emit(records.event())
async def test_delivery_failure_does_not_break_the_caller(event_sink, records):
"""投递失败由库捕获、记日志、把失败计数加一,然后继续跑。
def test_a_sink_is_allowed_to_raise_on_delivery_failure():
"""**这一层不断言「emit 不抛」——一个后端连不上时抛异常的出口是合规实现。**
一次运行不该因为进度回写的数据库连不上就终止——事件是观察通道,不是控制通道。
这条测试面对的是一个必然投递失败的出口,断言它不会把异常泄漏成循环的终止条件。
契约写的是「投递失败由**库**捕获、记日志、把失败计数加一,然后继续跑」,所以要断言的
行为在库那一侧,不在出口这一侧。原来这里写了一条 `await emit(...)` 不抛的断言,那会把
一个完全合法的审计 sink 判失败——它在日志管道不可用时抛 `ConnectionError`,而库本来就
该接住。
「库接住了失败并继续跑」属于整次运行的行为,落在驱动入口那一层的测试里,不在这个接缝的
契约里。这条留成一个说明,是为了让下一个想在这儿加断言的人先看到这段。
"""
await event_sink.emit(records.event(kind="always-fails"))
@pytest.mark.xfail(reason="事件集还没定,见 docstring", strict=True)