diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml index 27be4990fc..eb31a73022 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md 2026-07-31-code-runtime-python-settlement-fixes.md: 0bbf5280afef5071a78c51beb5ea48bcf7223a63 -2026-07-31-code-runtime-python-settlement-fixes.zh.md: befa577b5f1e8106de92b28bb9366f41c9773aac +2026-07-31-code-runtime-python-settlement-fixes.zh.md: da696a9070d5c7c59595db88cb8c41898a730cac diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md index befa577b5f..da696a9070 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md @@ -6,7 +6,7 @@ Status: implemented ## Problem -用于 Code Mode 的 CPython 子进程后端建立在 [fd-3 帧协议](../architecture/2026-07-31-code-runtime-python-fd3-protocol.md)之上,把每个程序结果都 resolve 成一个 `CodeRunResult`,仅在 seam 被误用时才 reject `run()`,并且会 dispose 到完全停稳,从而没有任何留在子进程自己进程组内的子进程存活得比 fiber 更久(一个用 `setsid()` 逃出该进程组的后代是有文档记载的例外——见该包 README 的 Known Limitations)。一连串审查暴露出一些缺陷,它们以单元测试覆盖率无法捕获的方式破坏了这些契约:每一个都藏在一处 `/* v8 ignore */` 之后、一个读起来像修复但实际并非修复的捕获可调用对象之后、一处透过 seam 不可见的内存效应之后、一处重复计数的加载期上界之后、一处存活者能够熬过的进程组升级之后、一处静默死锁的跨事件循环完成之后、一处位于结算路径之外的同步抛出之后,或者一处被当作日志边界处理的传输边界之后。大多数行为修复都附带一个在缺少它时会失败的测试;有十处没有,并被如此标注——分块读取帧(一处系统调用次数的改进,没有可跨平台确定性断言的失败)、确认为空后的收尾(它唯一透过 seam 可观测的效应,即一个冻结的心跳,会在 SIGKILL 被投递的瞬间冻结,而修复前"投递即收尾"的代码也会产生同样的结果,用于区分的探测手段是 Alternatives 以跨环境不可靠为由否决的 signal-0 检查)、共享的 stdout/stderr 预算(它唯一透过 seam 可观测的差异,是一次流中冲刷落在哪条条目边界上,而这取决于两条相互独立的 OS 管道的相对到达时机,`os.sched_yield` 并不能使其确定;它所强化的按管道计的内存界限确实由单管道洪泛测试覆盖),`flush_line` 的 join-清空-push 重排序(它把结算期冲刷的峰值从三份副本降到两份,但 12× 加载门本就覆盖了换行路径的三副本峰值,因此每个被门放行的配置在两种顺序下都落在地址空间之内、不存在透过 seam 可观测的差异——该内存效应在 Python 子进程内部,与共享预算那处一样无法透过 seam 度量),节流 binding 回复(它的树内用例只断言分帧后的回复仍能完整往返;它所移除的峰值位于宿主 fd-3 可写缓冲内部、透过 seam 不可见,因此 32.0 MiB → 0.0 MiB 的降幅只能在树外度量),以及在快照之前丢弃迟到的 binding 解析(它的三条断言在修复前同样成立,因为 `sendReply` 本就丢弃结算之后的值——只是比快照晚),完成值的 TOCTOU 预编码(与编码竞态的并发变异无法透过 seam 确定性构造——它的 daemon 变异回归只断言结果永不为 `worker-exit`,这种断言是概率性的、不具有判别力,因此按既有的"无 fail-before 测试且有理由"先例登记为无 fail-before)、stray UTF-8 预算冲刷的扣留(正好落在多字节边界上的预算冲刷无法透过 seam 调度;它被交叉标注为 v8-ignored),以及结算后到达的迟到拒绝的 settled 先查(在运行已经结算之后才到达的拒绝无法从 seam 确定性构造),以及日志分片封口(25 M 级单字符滴灌 OOM 无法在 CI 确定性构造;树内用例只断言其完成并截断)。 +用于 Code Mode 的 CPython 子进程后端建立在 [fd-3 帧协议](../architecture/2026-07-31-code-runtime-python-fd3-protocol.md)之上,把每个程序结果都 resolve 成一个 `CodeRunResult`,仅在 seam 被误用时才 reject `run()`,并且会 dispose 到完全停稳,从而没有任何留在子进程自己进程组内的子进程存活得比 fiber 更久(一个用 `setsid()` 逃出该进程组的后代是有文档记载的例外——见该包 README 的 Known Limitations)。一连串审查暴露出一些缺陷,它们以单元测试覆盖率无法捕获的方式破坏了这些契约:每一个都藏在一处 `/* v8 ignore */` 之后、一个读起来像修复但实际并非修复的捕获可调用对象之后、一处透过 seam 不可见的内存效应之后、一处重复计数的加载期上界之后、一处存活者能够熬过的进程组升级之后、一处静默死锁的跨事件循环完成之后、一处位于结算路径之外的同步抛出之后,或者一处被当作日志边界处理的传输边界之后。大多数行为修复都附带一个在缺少它时会失败的测试;有十处没有,并被如此标注——分块读取帧(一处系统调用次数的改进,没有可跨平台确定性断言的失败)、确认为空后的收尾(它唯一透过 seam 可观测的效应,即一个冻结的心跳,会在 SIGKILL 被投递的瞬间冻结,而修复前"投递即收尾"的代码也会产生同样的结果,用于区分的探测手段是 Alternatives 以跨环境不可靠为由否决的 signal-0 检查)、共享的 stdout/stderr 预算(它唯一透过 seam 可观测的差异,是一次流中冲刷落在哪条条目边界上,而这取决于两条相互独立的 OS 管道的相对到达时机,`os.sched_yield` 并不能使其确定;它所强化的按管道计的内存界限确实由单管道洪泛测试覆盖),`flush_line` 的 join-清空-push 重排序(它把结算期冲刷的峰值从三份副本降到两份,但 12× 加载门本就覆盖了换行路径的三副本峰值,因此每个被门放行的配置在两种顺序下都落在地址空间之内、不存在透过 seam 可观测的差异——该内存效应在 Python 子进程内部,与共享预算那处一样无法透过 seam 度量),节流 binding 回复(它的树内用例只断言分帧后的回复仍能完整往返;它所移除的峰值位于宿主 fd-3 可写缓冲内部、透过 seam 不可见,因此 32.0 MiB → 0.0 MiB 的降幅只能在树外度量),以及在快照之前丢弃迟到的 binding 解析(它的三条断言在修复前同样成立,因为 `sendReply` 本就丢弃结算之后的值——只是比快照晚),完成值的 TOCTOU 预编码(与编码竞态的并发变异无法透过 seam 确定性构造——它的 daemon 变异回归只断言结果永不为 `worker-exit`,这种断言是概率性的、不具有判别力,因此按既有的"无 fail-before 测试且有理由"先例登记为无 fail-before)、stray UTF-8 预算冲刷的扣留(正好落在多字节边界上的预算冲刷无法透过 seam 调度;它被交叉标注为 v8-ignored),以及结算后到达的迟到拒绝的 settled 先查(在运行已经结算之后才到达的拒绝无法从 seam 确定性构造),以及日志分片封存(25 M 级单字符滴灌 OOM 无法在 CI 确定性构造;树内用例只断言其完成并截断)。 ## Decision @@ -132,4 +132,4 @@ Status: implemented ## Consequences -seam 的"只 resolve、不 reject"契约在引导写入路径和同步 spawn 失败路径上都得以成立,两者的覆盖率都是被度量的,且两者都不会遗留一个暂存目录。日志捕获是线程安全的,代价是每次写入和 flush 都要获取一次可重入锁,并且散逸的原生输出由它自己的换行符来分隔,而不是由传输分片来分隔。fd-3 残余数据的内存受实际保留的字节数约束,并且两个帧读取器都以一次而非平方级的方式扫描一个不断累积的帧。输出上限放行一个帧所能承载的每一个值,并在加载期拒绝一个非整数的预算。dispose 面对同进程组存活者是真正完全停稳的(以 `graceMs + 2 * CLOSE_REAP_MARGIN_MS` 为界,在进程组已为空时代价为零,并且一旦进程组清空就清除 SIGKILL 定时器,从而一次滞留的 kill 无法击中一个被回收的 pgid),RLIMIT 强制在 soft 和 hard 两者上都保持配置值与继承值中的最严格者(并且 SIGXCPU 诊断不再把一个宿主无法保证的预算说出来),并且从模型创建的线程调用的绑定会完成而不是超时,而且握手帧读取器不再在一个大程序上烧掉 CPU 预算。每处行为修复都附带一个在缺少它时会失败的测试,除了 Problem 一节点出的那十处——分块读取帧(一处系统调用次数的改进)、确认为空后的收尾(它唯一透过 seam 可观测的效应会在信号投递时冻结,而修复前的代码也会产生同样的结果)、共享的 stdout/stderr 预算(它唯一透过 seam 可观测的差异取决于不确定的跨管道到达时机),`flush_line` 重排序(它降低后的峰值仍落在 12× 门本就放行的范围内,因此没有配置会有不同表现)、节流 binding 回复(32.0 MiB → 0.0 MiB 的峰值降幅位于宿主 fd-3 可写缓冲内部、透过 seam 不可度量),在快照之前丢弃迟到的 binding 解析(它的三条断言在修复前同样成立,因此不是一处缺代码即变红的用例),完成值的 TOCTOU 预编码(它的并发变异竞态无法透过 seam 确定性构造,而 daemon 变异回归的唯一断言是概率性的),stray UTF-8 预算冲刷的扣留(落在多字节边界上的预算冲刷无法透过 seam 调度——v8-ignored),以及结算后到达的迟到拒绝的 settled 先查(结算之后才到达的拒绝无法从 seam 确定性构造)——因此其余各处未来若发生回归都会变红。 +seam 的"只 resolve、不 reject"契约在引导写入路径和同步 spawn 失败路径上都得以成立,两者的覆盖率都是被度量的,且两者都不会遗留一个暂存目录。日志捕获是线程安全的,代价是每次写入和 flush 都要获取一次可重入锁,并且散逸的原生输出由它自己的换行符来分隔,而不是由传输分片来分隔。fd-3 残余数据的内存受实际保留的字节数约束,并且两个帧读取器都以一次而非平方级的方式扫描一个不断累积的帧。输出上限放行一个帧所能承载的每一个值,并在加载期拒绝一个非整数的预算。dispose 面对同进程组存活者是真正完全停稳的(以 `graceMs + 2 * CLOSE_REAP_MARGIN_MS` 为界,在进程组已为空时代价为零,并且一旦进程组清空就清除 SIGKILL 定时器,从而一次滞留的 kill 无法击中一个被回收的 pgid),RLIMIT 强制在 soft 和 hard 两者上都保持配置值与继承值中的最严格者(并且 SIGXCPU 诊断不再把一个宿主无法保证的预算说出来),并且从模型创建的线程调用的绑定会完成而不是超时,而且握手帧读取器不再在一个大程序上烧掉 CPU 预算。每处行为修复都附带一个在缺少它时会失败的测试,除了 Problem 一节点出的那十处——分块读取帧(一处系统调用次数的改进)、确认为空后的收尾(它唯一透过 seam 可观测的效应会在信号投递时冻结,而修复前的代码也会产生同样的结果)、共享的 stdout/stderr 预算(它唯一透过 seam 可观测的差异取决于不确定的跨管道到达时机),`flush_line` 重排序(它降低后的峰值仍落在 12× 门本就放行的范围内,因此没有配置会有不同表现)、节流 binding 回复(32.0 MiB → 0.0 MiB 的峰值降幅位于宿主 fd-3 可写缓冲内部、透过 seam 不可度量),在快照之前丢弃迟到的 binding 解析(它的三条断言在修复前同样成立,因此不是一处缺代码即变红的用例),完成值的 TOCTOU 预编码(它的并发变异竞态无法透过 seam 确定性构造,而 daemon 变异回归的唯一断言是概率性的),stray UTF-8 预算冲刷的扣留(落在多字节边界上的预算冲刷无法透过 seam 调度——v8-ignored),以及结算后到达的迟到拒绝的 settled 先查(结算之后才到达的拒绝无法从 seam 确定性构造),以及日志分片封存(其 25 M 规模的 OOM 无法在 CI 中确定性构造)——因此其余各处未来若发生回归都会变红。