docs(code-runtime-python): drop the fixed empty-open limitation; declare the test helpers

The empty-open continuation skip (5b61a8fe6) made the Known Limitations entry
stale — the held fragment array no longer grows per empty frame — so the entry
is removed on both sides. The public-surface list now declares
resolvePythonBin and readProcessStart, which the '.' entry re-exports for the
test suite.
This commit is contained in:
Chinesezjc
2026-08-31 15:06:05 +08:00
committed by Tianyi Cui
parent 716060a04a
commit ca0e3e573e
3 changed files with 4 additions and 6 deletions
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-python/README.md
README.md: ef0ec3c1d2577f7001933e8f496446a6ed4b7d4a
README.zh.md: 1ffef1de5da46b1e580730d3e473f0277907dcf7
README.md: ea842882beb4c3badaa103b65fac45b844e02370
README.zh.md: e8b381d2b0e0e2f83e8bcf7de5c619e4974689c3
@@ -29,7 +29,7 @@ Choose this package to run Python model code through the code-runtime seam: regi
### What you get
The package's default export is the `PythonCodeRuntime` plugin. Its public surface also re-exports the host-side protocol vocabulary: `validateChildFrame` (rebuilds every inbound frame), the lossless-JSON codec and meters (`encodeJsonPlain`, `checkDoneValue`, `hasUnsafeIntegerToken`, `hasNonLosslessNumber`), and `logTruncationMarker` (the shared truncation-marker text). Every cap is a validated `Config` field with a default: `cpuSeconds` (60), `maxWallMs` (600000), `addressSpaceMb` (512, not applied on Darwin), `maxLogBytes` (65536), `maxValueBytes` (32768), `graceMs` (3000), and `pythonBin` (`python3`, resolved against `PATH` before the child spawns with an empty environment; a basename with no `PATH` match is rejected at load rather than silently falling to the platform default `PATH`).
The package's default export is the `PythonCodeRuntime` plugin. Its public surface also re-exports the host-side protocol vocabulary: `validateChildFrame` (rebuilds every inbound frame), the lossless-JSON codec and meters (`encodeJsonPlain`, `checkDoneValue`, `hasUnsafeIntegerToken`, `hasNonLosslessNumber`), `logTruncationMarker` (the shared truncation-marker text), plus `resolvePythonBin` (interpreter lookup against the current `PATH`) and `readProcessStart` (process-start statistics for tests). Every cap is a validated `Config` field with a default: `cpuSeconds` (60), `maxWallMs` (600000), `addressSpaceMb` (512, not applied on Darwin), `maxLogBytes` (65536), `maxValueBytes` (32768), `graceMs` (3000), and `pythonBin` (`python3`, resolved against `PATH` before the child spawns with an empty environment; a basename with no `PATH` match is rejected at load rather than silently falling to the platform default `PATH`).
### The wire
@@ -118,7 +118,6 @@ These limits define what the package does and does not cover; they are current p
- **No state persists across runs** — every request executes in a fresh subprocess; a persistent REPL-style kernel stays deferred until a backend brings its own logging scheme.
- **An fd-3 frame whose raw length exceeds 64 MiB settles the run as a worker-exit** — `maxLogBytes`/`maxValueBytes` are load-bounded to the same parser cap so an honest child's frames always fit; a model-constructed binding ARGUMENT above 64 MiB (a value with no seam-level budget) trips the same cap — an accepted residual of the OOM guard.
- **A combined log-and-value peak is not modelled by the load gate** — a model daemon thread that keeps writing while the completion value is metered and framed can add the two peaks in a way no gate admits or rejects; the run dies as `worker-exit`, containment holds, and only the failure classification is degraded.
- **An empty `open` continuation frame bills zero and holds one host slot** — a forged `{"type":"log","text":"","open":true}` flood grows the held fragment ARRAY without touching `logBudget` (each empty fragment's billed cost is `max(cost - 2, 0) = 0`). Accepted residual: per frame the host cost is far below its ~30-byte fd-3 wire cost, the flood is bounded by pipe throughput, and the trust level of model code equals bash.
- **A 1-second dual-limit `ulimit -t 1` CPU overrun is reported as `worker-exit`, not a timeout** — when the host starts under a hard CPU limit equal to the soft and that limit is 1, `_clamped` cannot lower the soft, so the kernel SIGKILLs the busy loop and SIGXCPU is never delivered; containment holds, only the classification is degraded.
- **No byte cap on intermediate binding values** — the implementation remains bounded by the lossless-JSON serialization cost and process memory, and a provider or executor may apply its own fetch cap.
@@ -29,7 +29,7 @@ kind: "package-reference"
### 你得到什么
包的默认导出是 `PythonCodeRuntime` 插件。其公开面还重新导出宿主侧协议词汇:`validateChildFrame`(重建每条入站帧)、无损 JSON codec 与计量器(`encodeJsonPlain``checkDoneValue``hasUnsafeIntegerToken``hasNonLosslessNumber`以及 `logTruncationMarker`(共享截断标记文本)。每个上限都是带默认值并经校验的 `Config` 字段:`cpuSeconds`60)、`maxWallMs`600000)、`addressSpaceMb`512Darwin 上不生效)、`maxLogBytes`65536)、`maxValueBytes`32768)、`graceMs`3000)与 `pythonBin``python3`,在子进程以空环境启动前对照 `PATH` 解析;在 `PATH` 上无命中的裸名会在加载期被拒绝,而不是静默回退到平台默认 `PATH`)。
包的默认导出是 `PythonCodeRuntime` 插件。其公开面还重新导出宿主侧协议词汇:`validateChildFrame`(重建每条入站帧)、无损 JSON codec 与计量器(`encodeJsonPlain``checkDoneValue``hasUnsafeIntegerToken``hasNonLosslessNumber``logTruncationMarker`(共享截断标记文本),以及 `resolvePythonBin`(对照当前 `PATH` 的解释器查找)和 `readProcessStart`(供测试用的进程启动统计)。每个上限都是带默认值并经校验的 `Config` 字段:`cpuSeconds`60)、`maxWallMs`600000)、`addressSpaceMb`512Darwin 上不生效)、`maxLogBytes`65536)、`maxValueBytes`32768)、`graceMs`3000)与 `pythonBin``python3`,在子进程以空环境启动前对照 `PATH` 解析;在 `PATH` 上无命中的裸名会在加载期被拒绝,而不是静默回退到平台默认 `PATH`)。
### wire
@@ -118,7 +118,6 @@ kind: "package-reference"
- **运行之间不保留状态**——每次请求都在全新子进程中执行;持久 REPL 风格内核在某个后端带来自己的日志方案之前保持延期。
- **原始长度超过 64 MiB 的 fd-3 帧会让本次运行以 worker-exit 结算**——`maxLogBytes`/`maxValueBytes` 在加载期被限制到同一解析器上限,因此诚实子进程的帧总能放得下;模型构造的超过 64 MiB 的 binding 实参(一个在 seam 层没有预算的值)会触发同一上限——这是该 OOM 防护的已接受残余。
- **组合日志与值的峰值不被加载门建模**——持续写入的模型 daemon 线程与完成值计量、分帧相加的峰值没有任何门会放行或拒绝;运行以 `worker-exit` 告终,隔离成立,只有失败分类降级。
- **空 `open` 续接帧计费为零并占用一个宿主槽位**——伪造的 `{"type":"log","text":"","open":true}` 洪泛在不触碰 `logBudget` 的情况下增长持有的片段数组(每个空片段的计费为 `max(cost - 2, 0) = 0`)。接受的残余:每帧的宿主成本远低于其约 30 字节的 fd-3 线上成本,洪泛受管道吞吐限界,且模型代码的信任级别与 bash 相同。
- **1 秒双限 `ulimit -t 1` CPU 超限被报告为 `worker-exit` 而非 timeout**——当宿主在一个与软限相等的硬 CPU 限下启动且该限为 1 时,`_clamped` 无法下调软限,内核在同一 tick SIGKILL 忙循环,SIGXCPU 永远不会送达;隔离成立,只有分类降级。
- **中间 binding 值没有字节上限**——实现仍受无损 JSON 序列化成本与进程内存约束,提供方或执行器可能应用自己的获取上限。