iomgaa
92785eb3e1
feat(stores): 补上易失存储实现，stores 拆成四个文件
...
design 0003 的否决方案一节承诺过「显式命名的、明确不提供恢复的内存实现」，那个实现一直
没写，migrations/dissect.md 还专门登记着「不要照那句话去找一个不存在的类」。
**名字取 VolatileRunStore 不取「不提供恢复」**：一个真的读不回自己写过的东西的存储过不了
自家的契约套件（套件第一条要的就是「写进去的意图读得回来」），而这一层的准入标准就是那套
套件。一个过不了自家准入标准的实现不该存在。它不提供的是跨进程恢复，Volatile 说的正是这
件事。
桶里存编码后的载荷、读的时候才解码，两个方向的别名都堵上：调用方写完再改自己手里那个 dict
改不到日志，读回来的日志被就地改动也污染不了存储本身。落盘那个实现每次重新解析文件，天然
如此，这个实现靠同一条路径对齐它。**写入只编码不解码**——落盘那边写的时候只做 json.dumps，
一条字段类型不对的记录写得进去、读的时候才炸，两边现在一致。
两张平行的表（记录类→标签、标签→解码器）合成一张三元组再派生视图。加上易失实现要用的第三
张视图之后，三张表之间那个谁也不检查的一致性要求就不可能被违反了。
2026-08-27 03:58:29 -04:00
iomgaa
e701563a0b
docs(design): 落定第一个下游提的五个缺口的三份方案
...
0014 契约套件怎么发给下游、0015 参数快照的内容契约、0016 动作执行接缝抛异常时的契约。
三份都过了 CLAUDE.md §3 的硕士生冷读，冷读抓到的八处「在讲文档自己」的句子、五处缺前置
知识、三处只写结论没写理由、三处参数两地取值不同，全部采纳。
0016 否掉了提 issue 那一方倾向的方案（库捕获执行器异常转 ENV_ERROR）。三层理由：日志
「不自洽」这个前提本身不成立——异常抛出时副作用状态未知，日志停在「动作意图有、结果无」
正是照实记录；库替它写一条步记录反而是在编造，而那条记录会让恢复把未知状态抹掉；最后
它会把执行器里一个 AttributeError 变成一批环境故障，run() 照常返回正常结果，调用方拿不到
任何异常。
2026-08-27 03:58:08 -04:00
iomgaa
e10f024c9b
docs: 撤掉阶段清单的自毁条款
...
原话是「开发结束后把本节删掉即可」。六个阶段现在都走完了，而这份清单没有变成过期条文——
它记的是每个阶段各自的验收标准与结论，那是「当初凭什么算完成」的答案，删掉就没有别处
记着了。留着它不需要维护：勾完就不再动。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 12:31:49 -04:00
iomgaa
1b8e8367f9
docs: ⑥ 验收完成，两半都交付了
...
压测那一半的结果写进阶段清单：193 次运行、1743 次真实调用、十一条不变量全过，九类故障
注入 58 条判据零击穿。库本身没有被压出 bug——压出来的四个问题全在压测这一侧，各自的
commit 里写了是怎么发现的。
AppWorld 那一路的步数分布与 dissect 已有的 937 条真实轨迹基本重合，那是「同一个 benchmark
换个内核驱动、轨迹形状没变」的证据。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:57:06 -04:00
iomgaa
0752723c3c
docs(explanation): 写自造压测负载这份常青文档，过了一轮硕士生冷读
...
讲这套压测是什么、九类故障各守什么、判据为什么全是结构不变量、以及怎么重跑。具体数字
一个都不写——那些是一次实测的结果，放进常青文档等于种下过期条文。
冷读抓到的九条全部采纳：产物那段自相矛盾（谁写了那四个文件）、GovDoc 三个阶段全文一个字
没有而后面两节都建立在它上面、判据的权威出现两个说法、六个核心概念没解释就在用、哨兵那个
例子整句读不懂、四处只写结论没写理由、重跑那节缺环境前提、故障注入为什么没有自己的报告、
以及一步没写出来的因果。
冷读同时报了三段跳读，按它给的事实处置：脱敏那节压掉后半段、九类列表重排成只读粗体也拿得到
每类守什么、打包那两段压成一段。
更新触发点写在文首：这套压测是一次性工具，验收阶段过去之后如果它被删掉，这份文档跟着删——
一份描述已经不存在的目录的常青文档，比没有更坏。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:54:15 -04:00
iomgaa
ff59457482
fix(soak): 记分板的真空成立与停止原因覆盖，两处都会把「什么都没验」显示成绿
...
Codex 报了两条数据不足时真空成立的不变量，顺着同类找齐了七条：零步的「步号连续」与
「动作结果与步记录一致」、不足两步的「提示词字符数单调不减」、零意图的「意图都有归宿」、
零载荷的「步记录的内部不变量」、零记录的「不串台」、零行的「日志能被读回来」。同一类
缺陷改一半，剩下那一半照样会在某天把一次什么都没验的跑显示成绿。
各条的数据下限不一样，反直觉的三处写进了说明：「步记录的内部不变量」数的是打着标签的行
不是解出来的记录（违反配对的行本来就解不出记录，按记录数当下限会把它最该判的对象数漏）；
「动作结果与步记录一致」不要求那条步记录带动作结果；「不串台」两半各判各的，合成一个的话
一半的真空会被另一半的绿盖住。
「停止原因与轨迹自洽」原本只覆盖四个取值、另外六个直接放行——不是数据不足，是判据本来就
该覆盖而没覆盖，后果和真空成立一样。六个都补了规矩，llm_error 那条按库自己的判据写
（解析失败必定带说明，模型调用失败那一步压根没走到解释器，只看有没有动作结果分不开这两者）。
另加一条断言十个取值一个不漏，将来加了取值而这里没跟上会显式报「还没有规矩」。
「提示词字符数单调不减」的说明原本承诺「历史只追加」，实现只比较库自己记录的数——承诺了
它，读者看见绿就以为截断被排除了。改成只承诺它验得到的，真正的对账在故障注入那侧。
拿 193 次真实运行重跑：十一条仍然全过，而这次那 8 次解析失败连击、1 次模型调用失败、
1 次撞步数上限是被真规矩判过的。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:53:56 -04:00
iomgaa
5a4d13b0f2
fix(soak): 按 Codex 对抗审查加固故障注入的判据
...
九类实跑全过之后让 Codex 专门找「判据其实验不到它声称要验的东西」，它报的每条都带具体
失败场景。这次的绿不是假的——实跑数据里这些判据都有料可判——但它们在别的输入下会假绿。
真空成立三处改成无法判定：空日志的「全都解得开」、零步的「没有 env_error」、前后都空的
「审计账没变」。上一版实跑里最后那条正是 0 vs 0 通过的。
「环境是在完整一步之后坏的」原本只有通过和无法判定两档，没有击穿分支——那条判的是注入器
自己，它对外宣称在第 N 次执行之后动手，整类故障的结论都建立在这句话上。
提示词那两条原本只读库写进日志的数，而这套东西反复强调不能拿库的自述验库的行为——它在
自己的核心主张上破了例。现在包一层模型客户端记下每次真正发出去的消息字符数，跑完逐步
对账。字符数口径与库的算法对拍过，不然会全程假击穿。
绝不重放那条补了两个角度：崩溃时账上那几条续跑之后要逐行原样还在（旧条目被改写、被抹掉
原来一路绿灯），以及续跑段里不许出现与崩溃前完全相同的条目。Codex 提的「同一文件不同
内容」在 b 档已被条数判据挡住，a 档不能加同样的规则——那一档续跑本来就该接着跑，模型
再写一次是正常行为，加了会变成随机红。
取消补了环境侧的静默判据与事件文件完整性。容器里已经发出去的执行在客户端计数上不留痕，
这个盲区如实写进已知缺口，没假装验到；崩溃形态只能落在写入调用返回之后，同样记下来。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:53:00 -04:00
iomgaa
e590bea70e
fix(soak): 环境客户端把传输层失败也翻成 AppWorldError，「连不上」那一档原本没实现
...
execute 的 docstring 一直写着「只有环境自己坏了——连不上、HTTP 非 2xx、返回体不是约定
形状——才抛 AppWorldError」，但实现里只处理了后两档。连不上、读超时、连接中途断掉时，
httpx 抛的是它自己的异常类型，而上层的动作执行接缝只认 AppWorldError，于是容器一挂整次
运行会以一个未捕获的第三方异常炸出去，正确的行为是记成环境故障、由库合成一段观察、以
env_error 收尾。
这个缺口是压测里真把容器 docker kill 掉之后才暴露的——在那之前它只写在 docstring 里。
顺带覆盖了另一个一直没验过的路径：客户端读超时同属这一类。
CancelledError 继承 BaseException，不在 httpx.HTTPError 的范围内，取消照旧原样穿过去。
修完重跑那一类，七条判据仍然全过。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:16:08 -04:00
iomgaa
67f0d355d0
feat(soak): 补上 context_overflow 与 env_error 两类，七类变九类
...
一次 193 个运行的全量跑完之后，停止原因的十个取值里有两个一次都没出现过。没出现不等于
它们是对的，只等于没验过——这正是「全绿要先怀疑负载」该指向的地方。
context_overflow 的判据不能照字面写成「最后一步的提示词超过上限」：规模判定在调模型之前
做，命中时不产生步记录，所以落盘的每条步记录必定不超上限，那样断言等于断言契约的反面。
改成判「再走一步会有多大」，公式拿全量里 865 对相邻步验过，0 处不符。
env_error 是真把容器 docker kill 掉，不是用测试替身。它自己起一个池、用另一个端口——
共用那个 size=1 的池的话，排在它后面的每一类都会跑在一个不存在的环境上。
实跑：两类都通过，击穿 0、无法判定 0。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 11:14:04 -04:00
iomgaa
5d5371792d
fix(soak): 父子两侧的崩溃条件对齐，并给自杀留一个窗口
...
上一轮实跑里确定性自杀一次都没走到——父进程一看见日志尾部形态对上就发信号，而自杀条件
比它严一档（还要求审计账非空），于是外部信号永远抢先，自杀路径成了死代码，崩溃点又变回
碰运气。表现是崩得太早：动作还没执行过，最硬的那条判据没有实料可判。
两处对齐：父进程的命中条件也要求审计账非空（做成必传参数，给默认值等于让某个调用点静默
跳过这一条，而这正是这次出问题的方式）；兜底 SIGKILL 之前先等两秒看子进程是不是自己以
137 退出。
实跑结果：两档都走确定性自杀路径，都崩在「写入执行过之后」，绝不重放那条判据在两档都有
实料——审计账 1 条、去重后仍 1 条，续跑前后也都是 1 条。整套七类击穿 0 条、无法判定 0 条。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 10:41:27 -04:00
iomgaa
a641a1fc11
fix(soak): 合成观察那两档不该逐字比对，判据写错了
...
193 次真实运行报了 9 处击穿，核下来是判据的错不是库的错：动作被拒绝或环境故障时，库
刻意不把执行器给的观察回填进历史，而是换成合成观察那一段。两个字段承载的本来就不是同
一件事——一个是执行器原文的留痕，一个是真正喂给模型的文本。
改判据时顺着源码发现被替换的是三列不是一列：观察文本、是否合成、截断字符数在那两档下
全部由库填。所以旧判据在环境故障那一档上必然也会误报，只是这 193 次里没撞上真的环境
故障；截断数那一列则是恰好两边都是 0，潜伏着没炸。
现在 executed 档三列仍然逐字比对，另两档改成断言步记录的「是否合成」标记确实立起来了——
库既然替换了观察，不立这个标记才是真出了问题。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 10:35:25 -04:00
iomgaa
fe33faa3ec
fix(soak): 崩溃改成子进程内部的确定性自杀，外部 SIGKILL 抢不到那个窗口
...
第一次实跑的结果：时机 A（一步完整落地之后崩）三次都没命中，每次都是「发信号与子进程停笔
之间又写进了记录」。原因是库写完步记录之后紧接着就写下一条意图，中间只有内存计算，窗口
窄到外部信号挤不进去。这个观察本身留在模块 docstring 里——它说明自然崩溃几乎总是落在
「有意图没结果」那一态上。
改成在子进程里包一层存储，在写入落盘返回之后按条件调 os._exit(137)。os._exit 不跑
finally、不跑 atexit、不 flush，对磁盘的效果与 SIGKILL 等价，而 JsonlRunStore 本来就
写完即 fsync，没有未刷缓冲要指望退出时替它写。外部 SIGKILL 那条路降级成兜底，没有删。
自杀条件都要求工作区审计账已经非空，即那个声明绝不重放的写入真的执行过。上一次实跑里
最硬的那条判据（绝不重放的动作没被执行两次）报的是无法判定，就是因为崩得太早、审计账
是空的，去重比对真空成立——判定器诚实地报了无法判定而不是绿，现在给它补上实料。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 09:20:01 -04:00
iomgaa
43971573b7
feat(soak): 故障注入——崩溃续跑、取消、撞预算、解析失败连击
...
这七类是压测真正要看的东西：一百个任务顺利跑完什么都证明不了，能证明东西的是这些没有
失败现场的路径上库有没有守住承诺。
判据一条都不依赖模型的确定性，全是结构不变量。最硬的那条是「声明绝不重放的动作没有被
执行两次」——证据取自环境侧自己记的账（工作区的审计文件），不取库报的步数或动作数，
后者是库对自己行为的陈述，拿它验库的行为就是我们和我们自己对账。
崩溃是真 SIGKILL 子进程，不是模拟的注入点，而且分两种时机：一步完整落地之后崩（续跑应
该真的接着跑），以及意图落盘、结果还没落盘时崩（那条意图声明绝不重放，库应该判定状态
未知、干净停下）。第二种的命中条件是「最后一条意图的重放策略是 never」而不是「最后一条
是意图」——只读工具声明的是 safe，悬在那种意图上续跑会重放接着走，判据会时对时错，而错
的那几次看起来只像模型走了别的路。
判定和记分板一样分三档，「无法判定」不折算成通过：审计账为空时「去重前后条数相等」是真
空成立的，报成通过等于把「什么都没验到」显示成绿。命中不了时机也报无法判定，不降级成
另一种时机假装验过。
调用数护栏按每类故障的边界拦，不在模型客户端里抛异常——在那里抛的话库会把它记成模型调用
失败、合成观察接着跑，护栏本身就成了一次注入进来的故障，把要验的停止原因搅乱了。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 09:05:05 -04:00
iomgaa
a426cbbd21
feat(soak): 压测入口——预算护栏、并发上限、干跑，以及记分板要的四个产物
...
--budget-calls 与 --concurrency 都没有默认值：一个能跑飞的压测入口迟早会跑飞。达到调用
上限时停止派发新任务，但已经在跑的让它跑完——半路砍断会制造一批没有结束记录的日志，而
那和崩溃长得一模一样，会污染故障注入那边的判定。
--dry-run 不打模型，只把任务集列出来、把每个 RunRequest 真的装配一遍，确认容器起得来、
语料读得进、脱敏闸过得了。它也刻意不往 runs-dir 写东西，写了的话紧接着的全量会撞上
RunIdentityError。
两个场景同时跑时任务轮流排开而不是拼接：共用一份预算，拼接的话排在前面的场景会把预算
吃光，而报告看起来只是「因预算停在第 N 个任务」——一次只压了一半的跑长得像一次正常的跑。
测试里最有价值的一条是真的把产物喂给记分板：手工搭两个 GovDoc 任务共六次运行（真的走
polyloop.session.run，模型是写死的替身），再 import 记分板判定，验十一条不变量全绿。
两边的 sidecar 约定对不上的话这条会当场红。
实跑过一次干跑：两道 AppWorld 题各装配出 12.4k 字符上下文，GovDoc 两个任务六次运行全部
装配成功，脱敏替换 64 处，跑完零残留容器。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 09:02:53 -04:00
iomgaa
10f4a49f37
fix(soak): 给 plan 与 execute 补上完成通路，它们原本必然跑满预算
...
打真实模型跑通一个完整任务时发现的：这两个阶段的工具集里没有带完成标记的工具，解释器
也从不产出最终回答，于是模型在第 4 步写完产出物之后还在继续读文档，直到撞上步数上限。
按原来的 50/50/16 算，二十个任务要两千三百多次调用，而且整批的停止原因会全是
step_budget，别的什么都压不出来。
解释器加一条最终回答支路（{"final_answer": "..."}），plan 与 execute 的提示词写死收尾
动作；summarize 不变，仍然只能靠 submit_finding 结束。这样三条完成路径同时在场：模型
自报最终回答、agent 调用带完成标记的工具、环境报告完成（AppWorld 那路），它们的可信度
各不相同，压测正需要这个对照。
预算随之下调到 20/25/16——实测每阶段真实用 5 到 7 步，留了一倍余量。原来那个 50 的来历
是 gov-auditor.yaml 的 turns 上限，但那边靠编排校验产物落盘来收阶段，跑满 turns 无所谓；
这里靠模型自己收尾，上限定高只会让它在产出物写完之后接着白烧。
实测：plan 7 步 agent_finished、execute 6 步 agent_finished、summarize 5 步
task_completed，一个任务 18 次调用。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 08:58:57 -04:00
iomgaa
f277197071
feat(soak): GovDoc 形态的场景——JSON 工具调用、按次收窄、提交型完成
...
这条路径至今零真实负载，而它和 AppWorld 那路压的东西完全不同：动作是 JSON 工具调用而
不是代码，完成由 agent 自报（带完成标记的提交工具）而不是环境报告，工具集按阶段收窄。
一个任务拆成三次运行（plan / execute / summarize），因为「按次收窄工具集」在这个库里
只能这么表达——治理单位是一次运行，一次运行只有一个工具注册表，阶段之间靠工作区传状态。
语料是真实公文，但先脱敏再用，且原文与脱敏文本都只在内存里，一个字节不落盘、不入库。
机构名、电话、信用代码、邮箱、联系人姓名换成明显是假的稳定假名（同一原名整份文档换成
同一假名，否则模型会以为是不同主体）；金额、项目编号、日期原样保留，它们是审核判断的
依据，换掉任务就没得判了。脱敏后必须过一遍独立的检出校验，有残留就拒绝启动——把未脱敏
的第三方真实信息发给外部模型服务是不可逆的，而漏一处的表现是「压测正常跑完」。
实测：主招标文件 17.5 万字符，校验函数对原文报 61 处、对脱敏后放行，六份语料全过，
40 个金额与全部日期无误伤。
write_note 与 submit_finding 声明为绝不重放，每次调用在工作区留一行审计——那份审计是
环境侧的实际执行次数证据，故障注入要验的「绝不重放的动作没有被执行两次」数的就是它。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 08:36:58 -04:00
iomgaa
292a936d42
feat(soak): 记分板——十一条不变量逐条判定，任一被击穿整批失败
...
判定分三档：通过 / 击穿 / 无法判定。第三档不许折算成通过——缺文件、缺字段导致判不了，
和判过了是两回事，混起来会让一次什么都没验的跑看起来全绿。退出码 1 是击穿，2 是只有
无法判定，--allow-undetermined 只放行后者。
守的东西：日志读得回来、跨进程的结果与内存里逐字段相等、步号连续、意图都有归宿（至多
一条悬空且必须在末尾，那正是崩溃点）、动作结果与步记录说同一件事、提示词字符数单调不
减、事件条数等于本进程走完的步数、投递失败计数对得上、并发之间不串台、停止原因与轨迹
自洽。
报告里不出现模型原文、观察、工具名与文档片段——压测语料里有第三方的真实文档，而报告
是要贴给人看的。有四条测试拿哨兵字符串验它确实漏不出去，其中一条是拿恶意工具名试出来
的：原本打算按字符白名单放行工具名，白名单恰好把哨兵放了过去。
每条不变量都配一个「构造出违反它的日志、验它确实报击穿」的用例——一个永远返回通过的
判定器比没有判定器更糟。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 08:27:09 -04:00
iomgaa
21a9a30ee9
feat(soak): AppWorld 场景适配器——代码围栏解释器与容器执行器
...
复刻 dissect 的动作协议当压测负载：两条正则、first_only 策略、五条纠错说明逐字照抄，
提示词模板连同出处一起收进 tools/soak/prompts/。有两处刻意不同，都写在代码注释里——
未闭合围栏那一支不补回三反引号（公共契约要求回填历史的文本不长于模型原文），空围栏
那一支不截断。
执行器在 execute 内部顺带问一次 is_done 填 env_reported_completion，并把环境自己数的
执行次数透出来。那个数字是故障注入的判据来源：验「声明绝不重放的动作没有被执行两次」
必须数环境侧，数库自己的计数器等于我们和我们自己对账。
端到端真跑过一道题（82e2fac_1）：8 步 task_completed，环境判分通过，事件数与步数与
环境执行次数三者相等，耗时 30 秒。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 08:16:31 -04:00
iomgaa
4cbdb056b6
feat(soak): 压测的环境层——AppWorld 容器池与薄 HTTP 客户端
...
⑥ 的验收要自己造负载压，环境用 AppWorld：733 个任务与 197M 数据都在本机、docker 镜像已
拉好、而且它自带评测端点做程序化判分——换成让另一个模型判对错，等于往验收里再塞一个非
确定源，验收本身就不可复现了。
**不 import dissect**（§1.2 禁止反向 import），照它那两个文件当协议文档自己写了一份。
副作用是这反而更强：证明一个不认识 dissect 的第三方只用公共 API 就能驱动真实环境。
复刻了 dissect 记下的几个坑：httpx 必须 trust_env=False，否则本机代理会把 127.0.0.1 的
请求也劫走、表现成 502；健康检查失败先抓容器日志再删；关闭失败按端口分开计数，用全局
计数器的话坏容器的失败会被别的容器的成功清零。
放在仓库根的 tools/ 下而不是 tests/ 下：打包只收 src/，所以它不进 wheel 也不进 sdist
（实测两个产物里 soak 命中数都是 0）；而 §1.9 的四层是按「依赖什么」分的，压测不属于其中
任何一层，塞进 tests/ 要么破坏分层要么和 e2e 共用同一道花钱的闸。Makefile 的检查目标
跟着加上 tools/。
冒烟真跑通：起容器、初始化真题、跨调用保持变量、错误代码返回 traceback 而不抛异常、
评测、无容器残留；另验 2 容器并发的租借与归还。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 07:38:08 -04:00
iomgaa
71e7762814
docs(migrations): 撤掉一张空头支票——那个「不提供恢复的内存实现」不存在
...
0003 的否决方案那一节定过要给一个明确命名的、不提供恢复的存储实现，好让「我不要恢复」
成为一次看得见的选择。那个实现至今没写，polyloop.stores 里只有 JsonlRunStore，而
dissect 那份迁移文档一直在叫人去装配它。
调研 dissect 迁移面时撞出来的。对 dissect 不构成阻塞（它本来就要恢复能力），但一份指着
不存在的类的迁移指引，读的人会先怀疑自己装错了包。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:46:01 -04:00
iomgaa
aa2cc46ef8
docs: ⑥ 的验收标准换成自造负载 + 迁移方案交付
...
原来写的是「真的把 dissect 迁过来、以它原有测试全绿为准」，两个前提都不成立了：
GovDoc-SaaS 的实现已经整体清空，没有东西可迁；dissect 正在 Phase-1 中间，而且它的方案
该由那边自己排期，不该由本库直接改它的代码。
换成两件：自己照三个消费者将来的用法造约一百个任务的真实负载压一遍——这一步必须自己做，
因为三个消费者一个都还没到能用它的时候，而「从没被任何人用过」是它现在最大的未验证项；
以及把 dissect 的迁移方案写成一份提到它 issue 上的东西。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:32:51 -04:00
iomgaa
8c63367d3a
docs(guides): 按硕士生冷读改发布指南，并对齐 build/twine 已进 dev extra
...
冷读抓到三条确定性矛盾：registry 说「停在 1.0.5」而同一份文档又说 1.1.1/1.1.2 发出去了
（真实情况是版本号中间断了一截，缺的恰好是 1.0.6 与 1.1.0）；「1.1.0 改回 1.0.4」与「版本
只能往前走」打架（那次发生在 1.0.4 发布之前，发布前版本号只是文件里的字符串）；跑 Python
的命令带不带 conda 前缀两种形状并存（Makefile 的 target 内部已经包好了，裸敲就对）。
作为操作指南，「照着做会卡住」就是缺陷，补了八处：建仓与接 remote 的命令、tea 要不要装、
第四步合并与 push 的命令、token 那三个 export 只活在当前 shell、第八步解包看什么算通过、
README 里哪几行会随版本变、CHANGELOG 的日期形状、人类门批的是哪一次。
末节「这些坑为什么在这里」整节删掉——冷读是扫读跳过的，因为五条里四条正文已经讲过，而且
那一节的主语是「这份文档的九个步骤」不是发布这件事，正是 §6 禁止的自述。其中正文没有的
三句就地并进对应步骤。
另修一处它和代码的漂移：那一节写 build/twine 不在 dev extra、要手工装，而同一批改动正是
把它们钉了进去。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:25:03 -04:00
iomgaa
855d9c376a
docs(guides): 写发布指南，guides/ 的第一份
...
CLAUDE.md §1.10 一直指着一份「还没写」的文档，现在它在了。九个步骤逐条写清为什么是这一步、
为什么在这个位置，末节按「哪一步防哪个坑」把 PolyGateway 踩过的十来个坑映射回步骤，读者
不用自己对应。
素材来自对 PolyGateway 的调研并逐条核实过：registry 是 owner 级、工具只能是 twine
（tea 0.15.0 没有 packages 子命令）、token 在 tea 的配置里不在 .pypirc、这台机器的代理
到不了外面所以上传与验证都要绕开、同版本重传会被 409 拒绝、缺 readme 会让包页面空白而
twine check 只警告不拦。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:14:22 -04:00
iomgaa
8f5caa0924
docs: CLAUDE.md 补上发布的判据与代理这条环境事实，清掉三处过期记载
...
§1.10 那条指向的发布指南现在有了，同时补两件调研 PolyGateway 时核实到的：它当年那次
补救只写了文档没有回补上传，所以 1.0.6 与 1.1.0 到今天仍然不在 registry 上，而 dissect
的依赖恰好钉在那个空区间里装不上——记下教训不等于修好问题；以及发布完成的判据是外部可见
结果不是本地步骤跑通，1.1.2 三步全绿而包页面是空白的。
§4 新增一条：这台机器的代理到不了外面，访问实验室 Gitea 的命令都要绕开，否则失败看起来
像服务器挂了。过期记载三处：conda 环境早就建了、契约测试早就写了、十个模块早就不是空骨架。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:12:46 -04:00
iomgaa
303e4ebc1c
chore(release): 打包元数据补齐，版本定到 1.0.1
...
发布前置：readme 与 project.urls 从第一版就写全——缺 readme 的话 registry 包页面正文一片
空白，而 twine 只警告不阻塞上传，三步全绿产物却是坏的（PolyGateway 1.1.2 的教训）。
build 与 twine 钉进 dev extra 而不是靠人手装，PolyGateway 那边它们不在任何 extra 里，
于是发布指南得多写一条「记得先装」，那种步骤迟早有人漏。
README 里那条「项目还没有可用的功能、十个模块是空骨架」的横幅早就过期了，而打包会把当时的
README 固化进 sdist、发布后再改无效，所以在构建之前换成安装说明与现状。顺带修两处与事实
不符的：GovDoc-SaaS 的实现已经在 8 月 3 日整体清空，⑥ 对它的验收标准改成设计级验收。
新建 CHANGELOG.md，写清楚首个版本为什么是 1.0.1 而不是 0.x——「公共类型的字段只增不删不
改名」那条承诺从第一个下游装上它那天起就生效，而 0.x 意味着随时可以破坏兼容。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-11 00:11:04 -04:00
iomgaa
d4aa5e117e
test(e2e): 补上打真实网关的那一层，四层测试到齐
...
两个用例：一次运行走通「模型→解释→工具→观察回填→再问模型→收尾」，以及取消能穿过真实的
HTTP 请求并留下已取消的结束记录。测试自带解释器、工具注册表与事件出口——库故意不带它们，
带了就等于替某一家定了动作语言。
断言只绑结构不变量，一条都不绑模型输出的文字：停止原因落在两个正常终态里、至少两步且至少
一步真的执行过动作、每步 call_id 非空（网关那边生成的，替身给不出来）、日志读回来与返回值
逐字段相等、事件条数等于步数。绑内容的测试会随机红，而随机红的测试很快没人看。
两道跳过闸：网关装没装，以及 POLYLOOP_E2E 是不是 1。分开是因为填好密钥不等于同意花钱。
实测跑一次三次真实模型调用、约 12 秒；开关关着时整层跳过；make ci 283 passed / 16 skipped。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 23:49:11 -04:00
iomgaa
94b9923d8f
chore: 加 .env.example，只列 e2e 那一层必需的键
...
.gitignore 里早就写好了 !.env.example 的例外，文件一直没建。只列 e2e 跑起来必需的最小集，
每个键什么意思、还有哪些可选键，权威在 PolyGateway 自己的模板里，不在本仓库复述第二遍。
两处不是照抄网关默认值的：缓存必须 none——开着的话第二次跑同样的提示词直接命中缓存返回，
而 e2e 唯一要证明的就是「真的打出去过一次」；e2e 开关和密钥分成两件事——填好密钥不等于
同意花钱，没这道闸的话有人随手跑一次全套测试就会产生真实账单。
模板填完之后实测装配得起来：GatewaySettings.from_env() 与 GatewayClient.from_env() 都过，
适配器的 parameters() 读得出源名、供应商与模型名。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 23:02:20 -04:00
iomgaa
95898bccf3
docs: 事件集落地后回写 GovDoc 缺口清单与阶段清单
...
「审计出口与事件流的关系」那条缺口转到已回答：审计由意图日志承担，出口要包在存储接缝上
而不是接在事件出口上；三类事件里 phase_recovery 那一类在界外。新登记一条缺口：工具单独的
耗时拿不到，本库只有整步墙钟，迁过去口径会变。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 22:57:09 -04:00
iomgaa
8c642e7881
test(contract): 按 Codex 审查改掉五条说明型测试的名字
...
它们函数体是空的，名字却承诺了一个行为，读起来像「这条已经验过了」——而契约套件是新适配器
的准入标准，下游跑一遍看见绿的会以为自己那一条被验过。名字改成说清楚断言在哪一层，
函数体那段解释保持不动。
Codex 另报「测试 docstring 里出现 GovDoc 是业务词汇」，不采纳：§1.1 那道扫描挡的是领域词
（公文、超声、招标），说明一条测试被哪个消费者的需求逼出来不构成业务假设，仓库里这类引用
本来就有十几处。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 22:56:02 -04:00
iomgaa
e71dca7c35
feat(session): 落成事件出口，五个接缝全部有调用点
...
Event 从零字段变成 kind + run_id + model_binding + step，新增 EventKind（只有一种取值，
但第一天就带 kind，逼每个出口分发）。事件在「一步走完」原子落地之后发，只有这次进程里
真的执行过的步才发；投递失败接住、计数进 RunResult、继续跑，CancelledError 原样穿过。
契约套件那两条 xfail 关掉：一条要断言的是库发了几次、接缝自己看不到；另一条的前提是错的
——审计纪律由意图日志承担不由事件流承担，改成在 unit 层验日志里原文与改写后的文本各有
位置。_project_observation 那段说「将来靠事件流送出去」的注释一并改对。
283 passed / 15 skipped / 2 xfailed，剩下两条 xfail 是原子写与前缀持久性，没有机器兜底。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 22:51:19 -04:00
iomgaa
2385da3a97
docs(design): 0013 转已接受，补进四条来自 pi 的实据
...
去核 reference/pi 之后补的：它同一组三份投影对不上的地方有四处不是一处（决策四）；
它先发事件再落盘，反着做没问题是因为订阅者与进程同生共死，本库的出口活得比进程久
（决策五）；它的回调失败处置独立收敛到同一条分界——观察型抛异常照跑、工具执行前那个
fail-closed（决策八）；它一轮发十来条是被终端界面逼出来的，而它同样把实时事件流与
持久记录分成两套（决策三）。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 22:43:20 -04:00
iomgaa
8aa430c7df
test(contract): 0007 确认后关掉那三条 xfail
...
解释器不许抛异常是接缝自己的行为，改成正面断言（等实现接进来才跑）。另两条的答案
落在库这一侧不在接缝上：动作状态的触发条件是执行器自己的判断，套件面对任意实现逼
不出后两档，硬探会把 dissect 那种状态恒为 EXECUTED 的合法实现判成不合格；观察由谁
合成同理。两条留成不断言的说明，指向 tests/unit/test_session.py 里真正验它们的地方。
273 passed / 15 skipped / 4 xfailed。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 04:53:27 -04:00
iomgaa
1cd4344b16
docs(design): 落成 0013，定事件集、发事件的那一处与回调清单
...
事件集只有「一步走完」一种，带整条步记录而不是摘要；审计纪律由意图日志承担，
事件流保持可丢。写文档时去核 0007 决策二那笔「执行器原文丢了」的代价，发现它
并没有真的发生——「一步走完」这条记录持久化的是动作执行接缝的原样返回值，库只
替换了步记录里那一列，所以那段文本一直在日志里。
状态待确认：Event 从零字段变成有字段，按 CLAUDE.md §2 要过人类门。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com >
2026-08-10 04:50:33 -04:00
iomgaa
183113f624
docs: 0011 与 0012 转已接受，README 阶段清单勾到 ⑤
...
④ 与 ⑤ 都勾上但各自注明了欠账：e2e 那一层还是空的（它要打真实模型网关）；事件出口没有调用
点（Event 还没有字段）；stores 只有逐行追加那一种形态。勾上是因为骨架与十个模块确实都落地
了，注明欠账是因为清单是进度的权威处，含糊会让人以为这两件事已经做完。
2026-08-10 04:24:01 -04:00
iomgaa
4f3f43d218
docs(design): 按两轮硕士生冷读改 0011 与 0012
...
0011 最要紧的一条是文档和代码对不上：Codex 那轮把坏行判据从「第一条解不开的行」改成了「有没有
被换行终结」，文档还停在旧规则上。改完顺带答掉冷读问的「末尾连着两条坏行算什么」——按新规则
第一条终结过的坏行就已经报错了。
三处确定性矛盾全部成立：标题写「fsync 在三处，其余三处不做」而正文写「那两次」、表格里 fsync=否
只有两行（改成按「一步之内四次写」重排，并把「处」的单位说清）；「五个记录类」里没有「动作
结果」（它是逐步结果那条记录的一个字段，不是第六个记录类，表格行名会误导）；「每步四次写」与
表格看着像五次（同一根因）。另外契约套件的状态从「24 条全跳过」改成不给会过期的数字，并把
skip 与 xfail 分开说——它们是「还没有实现」与「没有机器兜底」两回事。
还补了：一节名词解释（前缀持久性、耐久屏障、恢复判定、⑥ 都是首次出现即使用）；「取消能穿过去」
那段原本自相矛盾（说线程会把写做完，又说没写完的是尾行）；文件的字面约定（UTF-8、\n 结尾、
非 ASCII 不转义、目录不存在时创建）——这些恰恰是外部读取方必须知道的，而文档反复强调那份日志
要能离开这个库读懂；为什么保留键叫 record 而不是加下划线前缀；为什么用 to_thread；独占创建
只挡住一种撞车（两个进程同时续跑挡不住，登记为已知缺口）；以及运行开始那次 fsync 真正的理由
是目录项而不是「读不出配置」。
最实的一条留到最后：那五维里的题目很可能带中文或空格，过不了运行标识的字符判据，而同一份
文档又规定不做转义。现在写明编码方式归下游自己选（要单射），并说清库为什么不替它选——库一旦
选了，文件名就不再等于运行标识，而它按标识去目录里找文件的用法就断了。migrations/dissect.md
同步登记。
0012：把 parent_card_id 这个笔误改成 parent_call_id（冷读的人不知道哪个对，只能问「card 是
什么」，正好把它顶出来）；「每个源报四样」实际枚举了五样；补一节名词解释（scope、源、恒定采样
参数、推理开关全是首次出现即使用）；补上本库这一侧的接缝签名与 ModelCall 的五个字段，并说明
中间那三个为什么一个都不往下传；补上非文本块报错、拼接不加分隔符的代价、1.1.1 那个 bug 到底
是什么、空串调用标识是防御而不是常规路径、以及为什么超时与重试次数不算模型身份。
2026-08-10 04:06:16 -04:00
iomgaa
39417a21ec
feat(adapters): 落成网关适配器，十个模块全部有内容
...
design 0012（待确认）定六条：收一个已经装配好的客户端而不自己装配（治理参数按 §1.5 不归本库
管，而且项目常要在多个用途间共享同一个限流器和缓存）；同时收那份配置只为算模型身份（客户端
把源列表与 scope 收在内部不公开）；内容块按顺序拼成一个字符串不加分隔符；绑定里只有网关认得
的两个键往下传、其余留在参数快照里且不报错；网关异常原样穿出去不翻译不重试；空串的调用标识
映射成空值。
参数快照不用网关内部那个 build_model_fingerprint：它不在 __all__ 里（用它就得从子模块 import，
他们重排一次我们就断），而且它是为缓存键设计的、按模型名去重。续跑守卫怕的是「配置变了而我
没发现」，所以宁可更严——改一个源名也报出来，那意味着这次运行打的可能是另一个端点。
tests/integration/ 这一层第一次有内容：用的是网关真实的 GatewaySettings / LLMResponse /
异常类型，装配守卫也真的跑了，只把「真的发出去」那一下换成受控替身。没装 polyloop[gateway]
时整份文件跳过——一个因为可选依赖没装而常年红的套件会训练所有人忽略红。
环境：从 ~/Projects/PolyGateway（活版本 1.1.2，比 reference/ 那份 1.1.1 新）复制一份装进
conda 环境。没有配私有源，polygateway 不在任何可达的 index 上。
2026-08-10 03:57:50 -04:00
iomgaa
aeb575e0f7
fix(stores): 修 Codex 对抗审查报的五条，其中两条同一根因
...
最实的一条：读取端只要一段能解析成 JSON 就收下，没检查它后面有没有换行。而短写完全可能
正好写完整个 JSON 对象、只差那个换行——那次写从来没被确认过（调用方的 await 还没返回），
按契约就是「没发生」，但它会被当成一条有效的动作意图读回来，恢复据此判成「状态未知」并可能
重放，而那个动作一定没执行过（调用方是在写意图返回之后才去执行的）。
判据改成「这一行有没有被换行终结」，不是「能不能解析」。同一个改动顺带修掉第三条：一行完整
终结的坏行（比如被外部追加的 {}）此前会被当成撕裂尾行吞掉，读成「少了一条记录但看起来完整」
的日志；现在终结过的行解不开就是损坏，直接报错。
其余三条：
- 新建日志文件不 fsync 父目录。os.fsync(fd) 刷的是文件内容，刷不到「这个目录里多了一个
文件」这条目录项；掉电后内容可能在而文件不存在，read_log 走「文件不存在」返回空日志，
驱动入口判成全新运行，一次已经花过钱的运行静默没了留痕。只在新建时刷。
- 同一运行标识上的并发写会交错：一条记录可能由不止一次 os.write 写完，而 O_APPEND 只保证
每次 write 的追加位置原子，保证不了一条逻辑行整体原子。按运行标识加锁串起来（不同运行
照样并行），跨进程那一半仍靠独占创建挡。有一条用短写逼出那个窗口的测试。
- 往返测试的 TOTAL_WRITES 是硬编码，而且漏写结束标记它发现不了（恢复会把最后一步之后那次
停止判定重演一遍，得出同样结果）。加一条把十次写的记录类型序列整个钉死的测试。
2026-08-10 03:52:35 -04:00
iomgaa
7f6066701e
style(tests): 那个模拟崩溃的异常改名带 Error 后缀，过 ruff N818
...
上一个提交串在 make ci 后面，ci 挂了 commit 照样跑了——这是把两件事写进一条命令的代价。
2026-08-10 03:42:03 -04:00
iomgaa
7c52eeb33f
test(round-trip): 在每一个写入边界上崩一次，断言续跑与一口气跑完等价
...
0002 末尾点名要这类测试，理由是恢复的 bug 天然没有失败现场——它不抛异常，只表现成「跑出来
的结果有点不一样」，而一次运行本来就次次不同，人眼分不出来。
一次两步的运行写十次（运行开始 + 每步四次 + 运行结束），十个边界逐个崩一遍，续跑的结果与
不中断跑完的逐字段相等（只抹平墙钟时间那一列）。工具与模型调用都声明可重放时十个断点全都
续得上。另外四条：恢复出来的消息历史与不中断时逐字相同（多一轮少一轮都不报错，只会让模型
从此看见不一样的东西）；声明绝不重放时崩在动作意图与步记录之间正当地停在「状态未知」；模型
调用意图写了结果没写、且声明不能重来时同样停在那儿；以及续跑写下去的东西不能让下一次续跑
读不动（重放要是又写一条同种意图，恢复会判成日志被并发写过，一次成功的重放反倒把日志弄坏）。
放在 unit 而不是 integration：分层判据是「依赖什么」（CLAUDE.md §1.9），这里模型、解释器、
执行器全是替身，只多用了一个真实文件系统。等 adapters 落地真的连上网关，那两层才有内容。
2026-08-10 03:41:27 -04:00
iomgaa
6af289d283
feat(stores): 落成逐行追加的日志存储，契约套件第一次真的在跑
...
design 0011（待确认）定了六条：一次运行一个文件且文件名就是运行标识（不转义不哈希，按标识
去目录里找文件是最自然的用法；标识必须是安全文件名，否则 ../ 会把文件写到目录外面）；一行
一条记录加一个 record 类型标签（serialization 编出来的载荷没有元信息键，标签是存储这层加的，
record 从此是保留键）；第一条解不开的行就是日志结尾、它后面还有内容就是损坏；fsync 只在
运行开始、两条意图、运行结束四处（其余两处靠前缀持久性兜）；写入走 to_thread；运行开始记录
用 O_EXCL 兜住跨进程撞车。
契约套件里那条 test_step_without_an_action_is_still_recorded 转成真断言——它标着 xfail 的
理由是「StepCompleted.result_id 在 0006 里是必填字符串」，而 0006 决策七早就把它改成可为空
并加了不变量。xfail 8→7，跳过 24→14。
原子写「一起不可见」那一半按契约套件的点名在这一层补上了：给实现留一个可注入的故障点
（一个可替换的「把这些字节写进去」），测试把它换成写一半就抛异常，断言那条记录整条不可见。
前缀持久性仍然验不了（掉电才看得出来），继续登记为已知缺口。
调研三条实据写进了 0011：两个下游 fsync 全仓零处（一个的 SQLite 还开着 synchronous=NORMAL），
所以这条比它们都严、代价是每步两次 fsync；一个下游的轨迹检查器同样是「碰到第一条坏行就放弃
整个文件」；另一个下游踩过「文件名少一维导致两个阶段静默互相覆盖」，O_EXCL 把那类静默覆盖
变成显式失败。这几条我自己逐条核过——那份调研的 subagent 承认它编过一句「我抽查过了」。
migrations/dissect.md 登记两条：运行标识要带齐现在文件名里那五维，以及这份意图日志和它那份
逐步轨迹是两样东西不要混。
2026-08-10 03:38:31 -04:00
iomgaa
c5c1e68706
docs(design): 按两轮硕士生冷读改 0009 与 0010
...
0009 最实的一条是文档与代码对不上：文档说那条扫描测试断言 __dataclass_params__.kw_only，
而代码实际查的是构造签名。冷读的人正确地指出前者守的范围更窄——哨兵写法 KW_ONLY 达成了同样
的效果但那个标志是假（会误杀），而 kw_only=True 的类里用 field(kw_only=False) 开口子那个
标志仍然是真（会漏掉）。文档改成描述实际做法并写清楚这条理由。另修：「长六个字符」实际是
五个；补上两种写法的区别、Pydantic AI 那条「超过一个位置参数」与本文「一个都不许」的差别
来自处境不同、规则作用域只管数据类（NamedTuple 与 pydantic 绕得过，是已知边界）、
以及 §1.3「新增字段必带默认值」为什么不受影响。
0010 最实的一条是论据自相矛盾：决策二拿「跑通了的下游逐字一致」当段序依据，决策三又说那个
槽位在那边至今没实现、收到非空注入直接抛错。改成说准——它证明的是有人设计装配顺序时把槽位
放在了这里，不是这个位置在真实提示词里验证过。另补一节「读本文需要的几个名字」（注入/通道/
解释器/合成观察/四者同源/pi 全是首次出现即使用，而且「Skill 条目」「工件」「Injection」三个
说法指同一样东西却没有一处对上）；承认库实际还定了消息边界的粒度，超出了「只管顺序槽位规模」
那句话，并给出这条线画在哪的判据；说明「变化频率」指的是跨运行而不是一次运行内部；补上规模
量出来给谁用、模板为什么在构造请求时就校验、以及为什么不回填解释出来的动作。
2026-08-10 03:15:46 -04:00
iomgaa
76495d9e39
fix(session,_recovery,types): 修 Codex 对抗审查报的五条
...
逐条核实全部成立。最重的是第一条：停止判定的结果只存在于结束记录里，而步记录与结束记录是
两次写。崩在两者之间那次判定就丢了，恢复照常回到预算准入——一次「恰好用满预算完成」被改写
成「预算耗尽」（两条轨迹长度一模一样），一次已经达成目标的运行接着往下跑，一次该以连续解析
失败收尾的运行再花一次模型调用。修法是续跑时把那次判定重演一遍：判定要的东西全在日志里
（动作结果在步记录那条原子写里、工具名在步记录上、模型回复在模型调用结果里）。最终回答那
一档更麻烦，答案文本只存在于结束记录里，靠重新解释那条已存下来的回复找回来——那时副作用还
没发生，重新解释是安全的。五种收尾各一条测试。
其余四条：
- 模型调用失败步在续跑时补写，prompt_chars 填了 0。重新装配出来的和被打断时是同一份，
照它算。填 0 是把轨迹里那一列改写成假值。
- 取消正好落在写运行开始记录那一下时不留取消标记，留下一份只有开始记录的日志：run 因标识
已存在而拒绝、resume 当成可以从第 0 步续跑。用 shield 让那条记录一定落地，取消结束记录
才有地方挂（反过来先写结束记录会拼出结构上说不通的日志）。
- ModelCallResult 能同时带 reply 和 failure，而恢复只看 reply is None，于是把一次失败的
调用当成成功、接着解释那段回复执行动作。加构造期不变量。
- call_id 空串一路能进持久化记录。docstring 里那句「绝不能是空串」原本没有任何东西守着。
顺带把主循环里重复的一次上下文装配去掉，并把只在续跑第一次迭代成立的那个分支挪出循环。
2026-08-10 03:12:42 -04:00
iomgaa
0132887cb9
feat(session): 落成主循环、两个装配对象与两条入口
...
A 到 H 八档由这里唯一执行，每档的判定住在 _stopping。三处容易写错的地方都有测试钉着：
恰好用满预算完成记成目标达成而不是预算耗尽（结算在下一次迭代开头）；规模超限不写步也不写
意图（唯一一种真的一步都没走的终止）；未执行与环境故障两档的观察取库合成的那段，执行器
给的不进历史。
写入序列断言成一条流水：模型意图 → 模型结果 → 动作意图 → 步记录，模型调用失败也落一条
结果记录（不落的话恢复会把一次已知的失败判成状态未知走重放）。结果 ID 从运行标识与序号
推出来而不是随机数——重放同一步拿到同一个 ID，轨迹里也少一列每次都不同的值。
写这块时修掉的两个自己的坑：
- 重放时会重复写意图，而同一步两条同种意图被 _recovery 判成「日志被并发写过」，一次成功的
重放反倒把日志弄坏。加了两个一次性开关跳过已经落过盘的那条。
- _recovery 数连续解析失败时把模型调用失败那一步也算进去了。它压根没走到解释器，判据改成
「解释器给了一段回喂文本」——解析失败必定带着那段说明，模型调用失败没有。
取消：CancelledError 原样重抛、run 不返回结果，但结束标记要在宽限期内尽力写下去，写不完
只记日志不再抛（再抛会把取消这件事本身盖掉）。并发隔离：全部可变状态住在每次运行一个的
_Driver 里，定义与请求都是 frozen 的，有一条并发跑两次的测试。
Budget 加了构造期校验（四项都必须为正）：零或负数会产出一次「零步、预算耗尽」的运行，
那和一次真的跑满上限的运行在停止原因上完全一样，混进统计里分不出来。
事件出口收下了但没有调用点——Event 还没有字段，发一条内容为空的事件既没用又会变成一份
要兼容的形状。
2026-08-10 02:59:34 -04:00
iomgaa
2367d3afbc
feat(_assembly): 落成段序与注入槽；design 0010 删掉工具段模板
...
0010 取代 0006 决策三里 tool_section_template 那一行。三条理由：两个真实消费者都是项目侧
自己把工具清单拼进上下文的（一个塞在 run 级模板里伪装成示例演示的一次执行输出，另一个的
render_tool_docs 全仓零生产调用方）；留着它的话迁移的人会去填，填完提示词里有两份工具清单，
而那个下游的验收标准是轨迹逐字段可比、变了还不报错；参考框架 pi 的内核同样不渲染，它的应用层
虽有 Available tools 段，但每行来自与 description 分开的 promptSnippet 字段——说明就算要渲染，
那段文字也不该是从校验用的 schema 生成的。四者同源不受影响，schema_for_model() 还在。
段序照唯一跑通了的下游：run 级片段 → 注入槽 → 目标级片段 → 逐步的模型输出/观察交替，
按变化频率从低到高排（供应商按前缀缓存计费）。库不合成任何 system 消息——有一个下游全程
没有 system 消息，加一条它的提示词会凭空多出一段。
注入槽每条一条 USER 消息、正文原样、不加任何分隔符（分隔符是渲染格式，归项目侧），通道按
名字排序（映射的迭代顺序取决于调用方怎么构造，用集合建出来的每进程都不同）。空注入等同有
测试守着。观察模板必须含占位符，缺了就报错——不校验的话每一步的观察会整个消失，而模型收到
的是一段看起来完全正常的固定文本。规模度量逐块问，认不得的块类型直接失败而不是当成 0。
零业务假设扫描第三次抓到我自己（模块 docstring 里写了「实验因子」），已改成中性说法。
migrations/govdoc-saas.md 登记了「模型原生工具调用没有路」这个缺口。
2026-08-10 02:48:56 -04:00
iomgaa
7da5e07726
docs(design): 给 0008 与 0009 补上外部先例，两个决定都是印证不是改动
...
0008：主流框架没有一家把截断量做成工具返回值上的字段（Anthropic 的 tool_result 只有三个
字段，OpenAI/LlamaIndex/Pydantic AI 的结果类型都没有），唯一结构化记下来的 LangChain 走的
是通用 artifact 通道而不是专设字段。另补「将来要加时怎么加」的正反两例：Pydantic AI 在允许
返回的类型集合里加一个新类型、旧路径不动，零兼容问题；OpenAI Agents SDK 改成运行期形状
嗅探，一个返回 {"msg": ...} 的普通工具被当成图片输出转掉、线上 400，三天后回落。
0009：Pydantic AI 2026-07 加过一条几乎同形的 meta-test（扫描包、新增公共数据类超过一个位置
参数就失败），PR 正文两句正好对上本文两条论证——「一条老在评审里被提却没有机器执行的意见」，
以及「不给已有的数据类补，那会打断按位置构造的调用方；白名单只减不增，清空它得发新 major」。
它已经付了本文想避开的那笔账。另记一条连带影响：kw_only 字段不进 __match_args__。
2026-08-10 01:21:12 -04:00
iomgaa
6fafd95d6c
feat(tools): 落成 executor() 与派生分发器；公共数据类一律只收关键字参数
...
两个自行调研后决定的问题，各自的证据写进了 design doc：
一、handler 返回 str 而不是带截断计数的小结构（0008 决策三，文末新增一节）。三条实据：
两个真实消费者的执行函数今天就返回纯字符串（GovDoc 的 handler 是 Coroutine[..., str]，
dissect 的环境 execute 是 -> str）；dissect 的 observation_truncated_chars 唯一的生产写入点
硬编码 0 且全仓零读取点，存在的是名字不是需求；reference/pi 是唯一把截断做完整的，它记的是
totalBytes/outputBytes/maxBytes 这组绝对量而不是一个差值——现在补 truncated_chars 补的
大概率是错形状，正是 scope.md 说的「猜出来的接缝比没有接缝更难拆」。
二、新增 design 0009：src/polyloop/ 下每个数据类都加 kw_only=True，另加一条扫描测试守它。
实验室七个仓库 223 个 dataclass 里 kw_only 出现零次，但那是默认行为不是选择。真正的证据是
PolyGateway：它的 LLMResponse 前 11 个字段顺序被三个下游的测试替身按位置构造锁死，模块
docstring 写着「字段顺序即公共承诺」，还得专门写一条 test_eleven_legacy_fields_positional
守着，从此再也插不进字段。那个约束不是它选的是它继承的，而本库还没有下游装上。
扫描测试查的是构造签名不是那个装饰器参数——要守的承诺是「按位置构造不了」。
executor() 在派生那一刻全查一遍实现，缺一个就报错，不拖到分发时才炸。RegistryExecutor 是
具体类而不是闭包，因为 RunRequest 要用 isinstance 认它。CancelledError 不被那个
except Exception 接住（它继承 BaseException），有测试守着。
2026-08-10 01:19:15 -04:00
iomgaa
fa09e873c5
feat(_recovery): 落成四态判定与四个断点各自的续跑路径
...
一步之内写四次（模型意图 → 模型结果 → 动作意图 → 步记录原子写），所以断点有四个，
这个模块的全部工作就是把断点认出来：
- 模型意图有、结果无 → 状态未知，按请求声明的模型重放策略决定重调还是停下来报告
- 结果条目在但记的是失败 → 状态一点都不未知，补上那一步以模型调用失败收尾
（判成未知走重放的话，一次已知的失败会被当成可能成功过）
- 回复已存、动作意图未写 → 副作用还没发生，重新解释那条回复，不再花一次调用的钱
- 动作意图有、步记录无 → 按意图记录里存下的那个策略决定；重放沿用原来那个预分配 ID，
另分配一个的话原意图永远配不上结果，下次恢复读到的还是「状态未知」
四态表最后一行（结果有、意图无）判为日志损坏拒绝续跑，另加几种撞号与缺号：同一步两条
同种意图（并发写）、步序号不连续（中间某一步的原子写整个丢了）、意图跑到步记录前面、
有动作意图却没有模型调用意图、有记录却没有运行开始记录。
模块 docstring 里写明了一条此前只是隐含的对齐：步序号与模型调用序号是同一个数。没有它，
result_id 为空的步记录（解析失败、模型调用失败、最终回答三档）认不出属于哪一步。
2026-08-10 01:10:09 -04:00
iomgaa
4bf74bf5ac
feat(_stopping): 落成停止判定四档，0008 转已接受
...
四个纯函数各管一档，顺序本身由主循环走：预算准入（A）、提示词规模（B）、连续解析失败（D）、
完成判定（G）。加一个不可变的三计数结构。
三处刻意钉死的边界，都写了测试：
- 两个预算上界同时耗尽报步数那一个。理由是兼容性不是原理（某下游按步数耗尽的占比告警），
正因为推不出来才必须被测试钉死。
- 预算「达到即拦」用 >=，提示词规模「超过才拦」用 >。两处不是同一件事：一个数已经用掉
几个额度，一个量一个东西有多大。
- 环境故障排在完成判定前面；未执行不做完成判定；完成信号恒为假不是故障（初稿在这里
写错过，会让某个下游的每一次运行都在第一步终止）。
不 import polyloop.tools，五个逻辑层模块互不 import，所以「这次执行的工具被标了完成标记吗」
由调用方查好注册表传一个布尔进来。
2026-08-10 01:04:38 -04:00
iomgaa
956d98652d
fix(tools): 修掉两个假阳性与一个改得动的内部状态，按两轮独立评审
...
代码审查（新鲜上下文，只给 diff 与验收标准）报了五条影响正确性的，逐条核实全部成立：
1. spec_for() 交出去的 parameters 就是注册表内部那份真字典。docstring 承诺的快照只挡住了
「调用方改自己那份」，没挡住「从注册表取出来往里伸一层改」——而后者一下同时改掉模型
看见的 schema 和校验用的 schema。改成逐层冻成只读视图，schema_for_model 出口再化回
普通字典与列表。
2. {type: integer} 拒掉 3.0。JSON Schema draft-06 起小数部分为零的浮点数是合法整数，
模型写 1e2 时 json.loads 给的就是 float。这是我自己在注释里点名最怕的那种假阳性。
3. additionalProperties: false 撞上 patternProperties 时拒掉一切匹配 pattern 的键。
那些正是这份 schema 专门要收的键，模型改名也绕不过去。patternProperties 在场就跳过。
4. 工具名不校验类型、纯空白名放行。名字要落进发给模型的 schema，不是字符串会让整个请求
被网关拒掉，报错指向请求体不指向注册表。
5. _by_name 是可变 dict，两条查询路径能被就地改到分岔。换成只读视图。
不可哈希那条不修，改在 docstring 里写明（参数 schema 是映射，注册表放不进 set）。
scope.md 的行号引用换成条目名——行号是最容易漂的一种参数，插一行就静默指错。
0008 按一轮硕士生冷读重写：字段位置那段原来自相矛盾（一边说位置是公共承诺、插在中间会
静默改掉后面字段的含义，一边就插在中间，且没讨论追加在末尾这个同一判据下的显然选项），
改成追加在末尾并说明规则；补上四个名字的就地解释（重放策略、两条完成通路、动作结果五个
字段、restrict_to）；决策四那张表原来只有三列却被正文说成填五个字段，恒定的两个单列出来
并各自给了理由；补上 validate 不通过为什么算未执行、executor() 为什么全查、为什么必须是
具体类而不是闭包、异常栈去哪了。
2026-08-10 00:57:36 -04:00
iomgaa
6abe13abb1
feat(serialization): 落成记录的编解码与 schema 版本校验
...
一个 encode 对七个 decode_*。编码不需要知道目标类型（对象自己知道），解码需要
（一个字典什么都不知道），不对称是这个原因。
载荷就是记录类的字段，没有任何元信息键——没有类型标签、没有时间戳。哪一行是哪种记录由
存储实现自己解决，库不替它定文件布局；多塞一个键会让步记录的载荷不再和迁移前那份逐行
轨迹同形，而那边的验收标准是逐字段可比。
解码三条：带版本的三种记录（运行开始、步记录、运行结果）版本必须在场且认得，缺了或者
认不得都失败；记录类上的每个字段都必须在载荷里，有默认值的也一样（默认值补齐会把
「这件事没发生过」改写成「发生了但值为空」）；多余键忽略（存储常要在同一个字典里塞
自己的东西，把它整个递回来解码是最自然的写法）。
第二条的直接后果写进了模块 docstring：往持久化结构里加字段必须同时抬 schema 版本。
CLAUDE.md §1.3 那条「新增字段必带默认值」管的是 Python 构造器，持久化这一侧由 §1.4 管。
SchemaVersionError 与 DecodeError 分开：一个说去升级库，一个说去查数据。压成一个的话，
一次例行升级漏做会被读成数据损坏，然后有人去修数据。
2026-08-10 00:52:01 -04:00
iomgaa