iomgaa/PolyLoop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
51 Commits 1 Branch 3 Tags
67f0d355d0fbd52e869ebe5161609d1863824f4e
Commit Graph

51 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
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>
v1.0.1 		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 30895cd306 feat(tools): 落成工具规格与注册表，四者同源由同一个实例驱动 
ToolSpec 五个字段加构造期校验（空名字、非映射 parameters），parameters 深拷贝一份存下来
——不拷贝的话调用方在别处改那个字典会连带改掉模型看见的 schema，而那次修改没有任何地方
记录得到。

ToolRegistry 是不可变值对象：注册顺序保留（工具清单要贴进提示词，而 restrict_to 收到的
常常是 set，照集合顺序输出会让同一份配置在不同进程里渲染出不同提示词）；相等按内容判
不按身份判，供 RunRequest 那条一致性校验用；restrict_to 遇到不认识的名字直接报错，
不静默丢弃。

validate 校验的是 JSON Schema 的一个子集（必填键、additionalProperties: false 时的多余键、
顶层 type），子集边界写在 docstring 里。完整校验只能靠第三方库，而公共签名上不许出现
第三方类型。剩下那部分由工具自己报错，那是一条正常观察。

executor() 没写，缺口见 design/0008（待确认，要过人类门）。
 2026-08-10 00:45:53 -04:00
iomgaa 77ffad9dc4 docs(design): 落成 0008，补上工具实现挂在哪里这个洞 
0006 决策六定的 ToolSpec 五个字段里没有一处装工具本身的实现，注册表派生的执行器
拿到一次合法调用之后无处分发。handler 这个词只在 0003 的正文里出现过，从没写成字段。

本文定四件事：实现挂在 ToolSpec 上（不另开清单，防漂移）、可以为空但 executor()
那一刻就查、签名是收参数返回观察文本的协程、派生执行器怎么填 ActionOutcome 五个字段。
状态待确认，要过 CLAUDE.md §2 人类门。
 2026-08-10 00:45:40 -04:00
iomgaa c9f10973ff feat(types,ports): 落成公共值类型与五个接缝的 Protocol 
第 ⑤ 阶段第一块，按 0006 与 0007 落地。从依赖图的底部开始写：
这两个模块定错了上面全得跟着改。

types 装 22 个公共值类型、枚举与持久化记录。StepCompleted 带一条构造期校验——
result_id 为空当且仅当 action_outcome 也为空，两者一空一有值是结构上说不通的，
放行它等于把「有动作结果却没有意图」这档日志损坏当成合法完整步接受。
校验用显式异常不用 assert，因为 -O 会把断言整条剥掉，下游用 -O 跑的那天守卫就静默消失。

ports 装五个 Protocol 与四个只在调用往返之间存在的壳。每个接缝多一个同步
parameters()，参数快照靠它聚合——原先没有这个方法，那个快照根本调不动。
RunLog 五个字段全带默认值，所以「读一个从没写过的运行标识返回空日志」就是 RunLog()。

零业务假设那条测试第二次抓到我：StopReason 的 docstring 里写了下游的实验词汇，
另有四处直接点名下游项目。库源码点名下游本身就是 §1.1 禁的——三个下游领域互不相交，
一个业务词进来就是替其中一个做了另外两个不需要的假设。已改成中性说法加 design doc 指向。

import-linter 从此不再是平凡的绿：Analyzed 15 files, 7 dependencies，
ports → types 那几条边真的被检查了一遍，之前是 0 dependencies。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-10 00:01:24 -04:00
iomgaa f8e02290f4 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>
 2026-08-09 23:56:38 -04:00
iomgaa a14bf8d288 test(contract): 落成五个接缝的契约骨架，用它逼出七个设计洞 
第 ④ 阶段的核心交付物。这套测试不针对任何具体实现，写的是「不管你怎么实现
都必须满足这些行为」，下游写完自己的实现接到 fixture 上跑一遍即可，
是任何新适配器的准入标准（CLAUDE.md §0）。

现在全部跳过，因为公共类型与 Protocol 还没落地。价值不在跑，在写：
写一条契约要求把每次调用逐字写出来——方法叫什么、参数填什么、返回值怎么取，
而散文里读着通顺的地方，落到这一步就露出来了。

三轮文档评审没报出的七个洞，写这套测试时全部撞了出来：
没有动作的步 result_id 填什么；三个 ActionStatus 取值的触发条件；
动作被拒绝时观察的来源（执行器与 SyntheticObservations 两处都有）；
解释器能不能抛异常；Event 没有字段所以事件出口的契约只写得出一半；
read_log 读不存在的运行必须返回空日志而不是抛异常；
以及原子性与前缀持久性这两条 0005 的承诺根本没有机器兜底——
写这套测试之前我们默认它们会被契约测试接住。

洞标成 xfail(strict=True) 而不是常驻 fail：一个永远红的套件会训练所有人忽略红。
它们都不带 fixture，否则会被「实现还没有」那个跳过挡住，
于是「答不上来」就伪装成了「还没轮到」。补上之后 XPASS 会报错，逼人回来删标记。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-09 23:37:13 -04:00
iomgaa e017160c45 build(repo): 落成工具链、依赖契约与十个模块的空骨架 
第 ③ 阶段剩下的那半：架构文档之外，import-linter 契约也落地了。

pyproject.toml 把九条依赖规则里的七条写成五条 import-linter 契约。
分层用一条 layers 契约表达规则 1、2、3、8，`|` 表示同层互不 import；
另外四条 forbidden 分别管下游反向 import、polygateway 的唯一入口、
以及三个纯逻辑模块不碰 asyncio 与 pathlib。
契约不是平凡的绿：故意注入两处违规验证过，都被点名到行号。

先建十个模块的空包，是为了避开 PolyGateway bootstrap 期那段 Makefile 门控——
它当时没有包，lint-imports 报 module not found 而红，只好加一段跳过逻辑。
空包让契约从第一天就真的在跑。

剩下两条规则落不进契约，写成了 tests/unit 下的测试：
规则 6「types 与 ports 不许 import 任何第三方」判据要反过来写（只许标准库和自己），
规则 9「import polyloop 之后 sys.modules 里没有 polygateway」是运行时事实。
另加硬约束 §1.1 零业务假设的黑名单扫描——它第一次跑就抓到 _assembly 的 docstring
里写了 dissect 的业务词，已改。三个扫描类测试都带 fail-closed 守卫，
防止目录搬走之后扫到空列表安静地绿。

工程约定取自实验室已有项目：setuptools + src layout、ruff 十一项 select、
line-length 100 来自 PolyGateway；dev 工具链版本钉死、--strict-markers 与
--import-mode=importlib 来自 CHSAnalyzer 与 dissect 踩过的坑，各自的理由写在配置注释里。
e2e 默认不跑，它打真实网关要花钱。

CLAUDE.md §0 那句「契约还没写，要等 src/ 落地」已过期，改掉；
README 勾掉第 ②③ 阶段，补上本地检查命令与 GovDoc-Editor 那一行。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-09 21:28:59 -04:00
iomgaa 766f7a0290 docs(design): 落成 0005，修订存储接缝的原子写与步记录三处 
第二轮 Codex 对抗审查报的五条全部核实成立，0003/0004 已冻结，修订新写一份。
五条都不改任何决策的结论，改的是结论到形状之间那一段的落实。

决策一：步记录加一个布尔的完成信号列。0004 决策二承诺靠它区分两条完成通路，
而决策四的字段表里没有这个字段。它自己就够区分，不必查注册表——
事后分析手上常常只有轨迹文件。
决策二：存储接缝六个方法重切一刀，把「按预分配 ID 写一条结果」拆成
「写模型调用结果」与「写动作结果与步记录」。原子性从散文变成签名里不可表达其他形态。
决策三：观察那一列的口径改成「回填进历史的那段文本」，不加字段。
dissect 的 render_messages 把 step.observation 原样套模板发出，
raw_output 也是解析器截断后的版本——两侧同构，都是一段文本加一个数字。
决策四：作废 0004 词表里「一个可能取不到的完成信号」，那是上一轮 fatal bug 的原话。
决策五：存储接缝加前缀持久性。少了它，一次明明成功的模型调用会被恢复
记成「状态未知」，而它成功的证据就在同一份日志里。

结论已回写 architecture.md 第九节与决策索引；migrations/dissect.md 需求七
补上「分开记的是文本加数字，不是两段文本」，堵掉这次审查里出现过的误读。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-09 12:02:38 -04:00
iomgaa 4f8812fa82 docs(design): 落成边界、续跑、公共 API 形状与停止语义四份决策 
第 ② 阶段需求对齐与第 ③ 阶段架构的产出，代码尚未开始。

design/0001 定边界判据：三道测试（时机 / 信息 / 性质）全过才在界内，
外加「只认接缝、不认接缝后面是什么」与不夺走下游实验因子的排除条款。
design/0002 定步级续跑：不承诺原子性，承诺绝不静默丢失与不替工具猜幂等性；
先写意图再执行、结果 ID 预分配、重放策略由工具声明且默认绝不重放。
design/0003 定公共 API 形状：单一入口两个动词、五个接缝、三个伪接缝的排除理由、
分层与九条依赖规则。design/0004 定停止判定顺序、十个停止原因取值与步记录字段表。
0003 与 0004 需过 CLAUDE.md §2 人类门，已由项目负责人确认，状态转为已接受。

explanation/scope.md 与 explanation/architecture.md 是这四份决策的常青回写，
分层与模块边界的权威在 architecture.md，将来由 import-linter 契约机器断言。
migrations/ 下 dissect 是唯一的硬迁移验收，govdoc-saas 只做设计级对齐。

三道闸都过了：14 agent 对抗辩论定骨架，两轮硕士生阅读报的 30 余条已修完，
Codex 对抗审查抓出的两条致命问题（提交型完成被误判成环境故障、
崩溃恢复漏一个状态）已修，修完的形状还没送 Codex 复审。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-09 10:48:33 -04:00