docs(code-runtime): fix remaining dunder/backend wording and document exports in README

- index.ts: RESERVED_ERROR_MEMBERS JSDoc now says `__x__` (non-empty
  middle), matching DUNDER_MEMBER and the derivative docs; and
  PORTABLE_RESERVED_WORDS is described as covering portable *target*
  languages (Python is a later-PR backend, not yet shipped).
- types.ts + type-equiv docs: CodeBindingNamespace.global points to
  RESERVED_BINDING_GLOBALS by name with an `e.g.` sample rather than
  enumerating the set (single home), no longer implying `__debug__` is a
  seeded slot.
- Agent Note: separate `__debug__` (CPython compile-time constant) from
  the seeded bootstrap globals.
- README (en/zh): document the four exported exclusion sets and the
  portable identifier/naming contract — no cross-package link needed.
- Regenerate cordis services catalog for the shifted source line.
This commit is contained in:
Chinesezjc
2026-08-07 11:20:05 +08:00
parent c05db227d5
commit efdc78cba3
12 changed files with 30 additions and 24 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/README.md
README.md: c7a2d519e47d160f5ab123bfc887e7e9f24ec602
README.zh.md: 22d0b120d7cea50b578a184b3e40d77707ebc489
README.md: fafaca85ac63e83e16882ef17f9f8995103866fd
README.zh.md: dc771bc16557d4b68529f2fde29eef1c09f299b5
@@ -20,6 +20,8 @@ Semantics every implementation must honor (contract details in the class JSDoc):
`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets and outer-output cap) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions` + optional `errorClass`), each exposed to the program as one global object of async callables returning `CodeJsonValue`, the seam-local structural equivalent of canonical `JsonValue` that keeps this interface package independent of sessions. An `errorClass` descriptor names a real program-global constructor and the own property that receives the rejected member name; runtimes remain independent of consumer terms such as `ToolCallError`. `CodeRunResult` reports the lossless JSON completion `value?`, ordered `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
Binding-global and error-class names are **language-portable**: they must match the identifier subset `[A-Za-z_][A-Za-z0-9_]*` (no JS-only `$`) and clear the seam-exported exclusion sets, so one `bindings` list is valid against every backend regardless of its `language`. The package exports the contract every backend enforces — `PORTABLE_RESERVED_WORDS` (ECMAScript Python reserved words), `RESERVED_BINDING_GLOBALS` (backend-owned globals such as `console`), `RESERVED_ERROR_MEMBERS` and `DUNDER_MEMBER` (error-member exclusions) — so a name like `$tools`, `lambda`, or `__dsh_main__` makes `run()` reject as seam misuse on any backend, not just some. See `src/index.ts` for the exact sets and rationale.
## Model Experience
Indirectly, through Code Mode in `dsh-tools`, which exposes `run_code` and returns program logs, values, or failures as retained tool-result tokens.
@@ -20,6 +20,8 @@
`CodeRunRequest``program``bindings``signal?`)携带运行时操作所需的全部内容;默认值解析(时间预算与外层输出上限)属于实现的已验证配置,绝不能是隐藏的 `??`,更不能藏在 `run()` 内部。`bindings``CodeBindingNamespace` 列表(`global` + `functions` + 可选 `errorClass`);每个命名空间会作为一个由异步可调用函数组成的全局对象公开给程序,这些函数返回 `CodeJsonValue`。后者是 seam 本地、与规范 `JsonValue` 结构等价的类型,使接口包保持独立于会话。`errorClass` 描述符点名真实的程序全局构造器,以及用于接收被拒绝成员名称的自有属性;运行时不依赖 `ToolCallError` 等消费方术语。`CodeRunResult` 报告无损 JSON 完成值 `value?`、有序的 `logs: string[]``error?``CodeRunFailure``kind` + 可反馈给模型的 `message`)。完整契约见 `src/types.ts`
binding-global 与 error-class 名称是**语言可移植**的:必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`(不含 JS 专有的 `$`)并通过 seam 导出的排除集,因此同一份 `bindings` 列表对每个后端都有效,无论其 `language` 为何。本包导出每个后端都执行的契约——`PORTABLE_RESERVED_WORDS`ECMAScript Python 保留字)、`RESERVED_BINDING_GLOBALS`(如 `console` 等后端拥有的 global)、`RESERVED_ERROR_MEMBERS``DUNDER_MEMBER`error-member 排除)——因此 `$tools``lambda``__dsh_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject,而非只在某些后端。确切集合与理由见 `src/index.ts`
## 模型体验
通过 `dsh-tools` 中的 Code Mode 间接提供;后者公开 `run_code`,并将程序日志、值或失败作为保留的工具结果 token 返回。
@@ -48,10 +48,10 @@ export const RESERVED_BINDING_GLOBALS: ReadonlySet<string> = new Set([
* one shared contract so a request valid on one backend is valid on all. The
* JS `Error` exclusions (`name`, `message`, `stack`) and Python's
* exception-protocol members (`args`, `with_traceback`, `add_note`) are
* listed by name; dunder-form names (`__*__`) are refused wholesale — several
* are constrained CPython descriptors whose `setattr` raises while
* constructing the rejection, and the exact set is an interpreter version
* detail. Any other non-empty own property name is accepted everywhere.
* listed by name; dunder-form names (`__x__`, non-empty middle) are refused
* wholesale — several are constrained CPython descriptors whose `setattr`
* raises while constructing the rejection, and the exact set is an interpreter
* version detail. Any other non-empty own property name is accepted everywhere.
*/
export const RESERVED_ERROR_MEMBERS: ReadonlySet<string> = new Set([
'name', 'message', 'stack',
@@ -65,9 +65,11 @@ export const RESERVED_ERROR_MEMBERS: ReadonlySet<string> = new Set([
export const DUNDER_MEMBER = /^__.+__$/
/**
* Reserved words of EVERY shipped backend language (ECMAScript Python),
* Reserved words of every portable target language (ECMAScript Python),
* refused as {@link CodeBindingNamespace.global} / error-class names by all
* backends. The portable-identifier contract promises a namespace list valid
* backends. Python is a portability target here even though only the
* TypeScript worker ships in this PR (the CPython backend is a later PR in the
* stack). The portable-identifier contract promises a namespace list valid
* on one backend is valid on every backend; a per-language check would let
* `lambda` pass the TypeScript backend and fail the Python one. Extending the
* seam with a new language means widening this union (a breaking review of
@@ -53,9 +53,9 @@ export interface CodeBindingNamespace {
* words, so the same namespace list works against every backend regardless
* of `language` — a JS-only spelling like `$tools` is rejected by design,
* not just by the Python backend. Names that satisfy the identifier rule but
* name a backend-owned slot (`RESERVED_BINDING_GLOBALS`: `console`,
* `__dsh_main__`, `__builtins__`, `__name__`, `__debug__`) are also refused
* everywhere, since some backend seeds that slot in the program's namespace.
* name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
* `__dsh_main__`) are also refused everywhere; see its declaration for the
* exact set and why each entry is reserved.
*/
global: string
/** The callable members, keyed by the exact name the program calls. */