docs(code-runtime-python): state the pythonBin load rejection in the README and the load-check comment

The review's warning: the pythonBin load-rejection is a product-visible change
(unresolvable basename now fails at load instead of a run-time worker-exit),
but the READMEs (en + zh) only said the basename is resolved against PATH, and
the load-check comment still described the old fallback. The README pythonBin
entries and the load-check comment now state the rejection; pairing
re-recorded.
This commit is contained in:
Chinesezjc
2026-08-31 15:06:05 +08:00
committed by Tianyi Cui
parent f931c2128a
commit 3151ecb848
4 changed files with 10 additions and 8 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: 2e22a5122f891b8317e13ee395ce222805b01b29
README.zh.md: a0372bbe1148ca259f1fc6849060d13fcec24947
README.md: ef0ec3c1d2577f7001933e8f496446a6ed4b7d4a
README.zh.md: 1ffef1de5da46b1e580730d3e473f0277907dcf7
@@ -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).
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 wire
@@ -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` 解析)。
包的默认导出是 `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`)。
### wire
@@ -747,14 +747,16 @@ export class PythonCodeRuntime extends CodeRuntime {
if (!Number.isSafeInteger(this.config.addressSpaceMb * 1024 * 1024)) {
throw new Error(`dsh-code-runtime-python: config.addressSpaceMb must be at most ${Math.floor(Number.MAX_SAFE_INTEGER / (1024 * 1024))} (its byte count crosses the wire as an exact integer), got ${String(this.config.addressSpaceMb)}`)
}
// `pythonBin` reaches `spawn` as the executable path, where two values the
// `pythonBin` reaches `spawn` as the executable path, where values the
// string schema admits fail late and unhelpfully. An empty string makes
// `spawn` throw `ERR_INVALID_ARG_VALUE` synchronously, and an embedded NUL
// throws `ERR_INVALID_ARG_TYPE` — both from inside `run()`, so the method
// REJECTS instead of resolving the `worker-exit` the seam promises for a
// child that cannot start. An empty basename also makes `resolvePythonBin`
// probe every PATH directory itself for the X_OK bit. Both are
// self-contained configuration errors, so they fail at load.
// child that cannot start. A basename with no `PATH` match would silently
// fall to execvp's platform default `PATH` under the empty spawn
// environment (see the resolvePythonBin JSDoc), so it is rejected here
// too. All three are self-contained configuration errors that fail at
// load.
if (this.config.pythonBin === '' || this.config.pythonBin.includes('\0')) {
throw new Error(`dsh-code-runtime-python: config.pythonBin must be a non-empty path without NUL bytes, got ${JSON.stringify(this.config.pythonBin)}`)
}