 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
|
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
|
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
|
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
|
a2e94318b9
|
chore(repo): 建仓，落成协作规范与文档骨架
协作方式以 CHSAnalyzer 为蓝本，按「库」这个身份改写：
- CLAUDE.md §0 的权威表换成公共 API 契约、公共类型、下游迁移三条主线，
数据库 schema / HTTP 契约 / alembic 迁移在本项目不存在，整体删去。
- §1 新增四条库特有的硬约束：字段只增不删不改名、持久化 schema 走显式版本、
不反向 import 下游、发布必须走完整流程（PolyGateway 有两个版本只 bump
没上传，registry 长期停在旧版且无人发现）。
- §3 的四类 Codex 对抗审查按同一判据重定：公共签名、停止判定与预算结算、
取消传播与 Session 隔离、schema 演进。共同点是错了不会当场炸。
- research-wiki 在常青层加第四类 migrations/，因为本项目的核心验收标准就是
能否搬回 dissect、能否替代 GovDoc-SaaS 的 docagent-core/，塞进 guides/
会让它看起来像可选工序。
reference/ 不入库：五个仓库各带一个 .git、合计约 96MB，提交进来会变成一堆
不可用的嵌套仓库。它也不是任何事实的权威，agent-core.md 同理。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
2026-08-07 07:02:09 -04:00 |
|