dsh-ptc-plus 0.3.2 → 0.4.1

package/docs/user-bindings.en.md

@@ -0,0 +1,64 @@
+# Global binding guide
+
+[简体中文](user-bindings.md) · English
+
+Global bindings save reusable TypeScript helpers for use across sessions. For example, a binding named `textTools` lets the model call `textTools.clean(text)` inside `run_code`.
+
+## Create and use a binding
+
+1. Open PTC Plus settings (when the sparkle shortcut is already present, choose **PTC Plus settings** from its menu; the host's native entry is the plugin's **Configure** on the current DSH side-bar **Plugins** page, or **Settings → Plugin configuration → PTC Plus** on the preceding DSH) and enable **Global User Bindings**.
+2. In a PTC session, open the sparkle menu by the composer and choose **Write a new binding**, or enter `/binding new <requirement>`.
+3. Inspect the draft's source, interface, and model prompt in the panel above the composer.
+4. Choose **Save and enable**. Subsequent `run_code` calls load the binding; initialization failures appear in execution results.
+
+During authoring, the Agent starts with a small in-memory check of the core behavior, then adds normal, edge, and failure assertions with `node:assert/strict`. Bulk tests report totals and a few representative failures instead of printing every successful case into the context. Tests must not modify external files or services. File and network helpers use in-memory substitutes to verify argument forwarding and error propagation; the answer identifies integration behavior that remains untested. Submission delivers a draft for your review. You decide whether to save and enable it.
+
+To revise a saved binding, use `/binding edit <id> <requirement>`. Its storage `id`, shown in the workbench, may differ from its call name. You can also select the Agent editing action from the binding list.
+
+## Draft panel
+
+A new draft opens above the composer. Click the title bar or use Enter/Space to collapse and expand it. Long content scrolls inside the panel.
+
+- **Save as disabled**: keep the entry in the global list without loading it.
+- **Save and enable**: save it and allow subsequent calls to load it.
+- **Discard draft**: abandon this unsaved candidate.
+- **Close panel**: hide it without saving or discarding.
+
+The sparkle button shows a PTC Plus tooltip on hover or focus that names it as the Global User Binding entry; a pending draft changes the tooltip to the draft state. The button shows a badge for pending drafts. Open its menu by hovering, clicking, or using the keyboard, then select the draft to show it again. Each session retains one current candidate. A confirmed save or discard closes the panel; failures leave the draft available for retry.
+
+The sparkle menu is available before the first message, and opens once the pointer dwells on the entry: crossing the composer no longer drops a menu over it. A hovered menu closes as soon as the pointer leaves it; clicking keeps it open until you click again, click elsewhere, or press Escape. Global bindings show their names, purposes, and enabled states using text and a checkmark. Click an entry to toggle it for all sessions. The catalog refreshes in the background, and the entries stay usable while it does; toggles are disabled only while saving, and reload after a conflict or failure before trying again. **Manage global bindings** opens the full workbench. **Write a new binding** and **Revise a binding** appear when the authoring command is available; the revision step lists existing entries and prefills `/binding edit <id> `. The reusable REPL binding list shows how many later cells reused each binding, with the total in the section title; the count comes from static references in each later cell's compiled source, and a redeclaration counts as neither a reuse nor a reset of the accumulated count.
+
+The original binding request retains its requirement, status, and accepted source in history. Historical inspection does not restore permission to save that draft. When another edit changes the catalog, reload its current state before deciding whether to save.
+
+## Interface and model prompt
+
+Each entry has two independent settings:
+
+| Setting | Purpose |
+| --- | --- |
+| Include interface declaration for the model | On by default. Names, parameters, return types, and API comments come from source; no separate declaration is needed |
+| Prompt for the model | Optional. Add usage conditions, input constraints, or examples missing from the types |
+
+For example, a size formatter might add: “Input is in bytes; display using IEC units.” Usage already clear from the interface need not be repeated.
+
+The model receives one line identifying `run_code` and the updated API reference, followed by entry names, configured prompts and selected interfaces. Ordinary calls do not resend unchanged documentation.
+
+Omitting the interface leaves a separate prompt available. Omitting both does not disable execution. Enabled entries are described from the first request in a new session. Saving, enabling, disabling, deleting, or editing an entry updates the next permitted request. DSH runtime-context suppression defers delivery.
+
+Changing only the prompt, interface switch, purpose, or top-level display name preserves loaded module state. Changing implementation source, scope, namespace call name, or selected exports reloads the module on subsequent execution.
+
+## Manual management and testing
+
+Open **Manage global bindings** in settings or use the session's **REPL** tab. Manual creation, `.ts` import, interface inspection, editing, enablement, and removal are available without an active PTC session.
+
+Source must be a TypeScript module with named value exports. Default exports and re-exports are unsupported. `namespace` exposes selected exports under one object; `top-level` exposes them directly. Leaving the export list empty selects all named value exports. Conflicting names are rejected before enablement.
+
+The code console runs the entry's unsaved source draft. It supports top-level `await` and retains temporary variables between commands. Its state is separate from the Agent session, but it has the same process permissions: file and network operations you run have real effects. Stopping, resetting, switching entries, or leaving the workbench releases the environment. After source changes, the next execution starts fresh. Ten minutes without execution also releases it while preserving the displayed input and output history.
+
+Bindings are stored in `$DSH_HOME/ptc-plus/bindings.json`. Relative imports in binding modules resolve from that file's directory; ordinary session REPL imports resolve from the session's project directory.
+
+## Limits
+
+Enabled configuration allows loading but does not guarantee successful initialization. Assigning or redeclaring a same-name variable can override the global default in the current session without modifying its saved entry.
+
+Restart recovery retains only verifiable session state. External files and services may have changed. Recovery does not repeat historical tool operations; diagnostics identify state that could not be recovered. See the [runtime reference](runtime-reference.md#global-user-bindings) for source formats, resource limits, and recovery, and [Client UI](client-ui.md) for workbench details.

package/docs/user-bindings.md

@@ -0,0 +1,64 @@
+# 全局绑定使用指南
+
+简体中文 · [English](user-bindings.en.md)
+
+全局绑定把常用 TypeScript helper 保存下来，供多个会话复用。例如，保存名为 `textTools` 的绑定后，模型可以在 `run_code` 中调用 `textTools.clean(text)`。
+
+## 创建和使用
+
+1. 打开 PTC Plus 设置（已有星光入口时可直接选择菜单中的 **PTC Plus 设置**；宿主原生入口在当前 DSH 为侧栏 **Plugins** 页面里本插件的 **Configure**，旧版 DSH 为 **设置 → 插件配置 → PTC Plus**），开启“全局用户绑定”。
+2. 在 PTC 会话中打开输入框星光按钮的菜单，选择“编写新绑定”，或输入 `/binding new <需求>`。
+3. 等待 Agent 提交草稿，在输入框上方检查源码、接口和给模型的提示词。
+4. 选择“保存并启用”。后续 `run_code` 会加载该绑定；如果初始化失败，执行结果会说明原因。
+
+编写过程中，Agent 会先用小型内存样例验证核心行为，再用 `node:assert/strict` 补充正常、边界和失败断言。批量测试只报告总数和少量代表性失败，避免把每个成功样例写入上下文。测试不得修改外部文件或服务；文件和网络 helper 可以用内存替代对象验证参数转发与错误传播，未实际验证的集成部分应在回答中说明。提交草稿只交给你审阅，保存与启用由你决定。
+
+编辑已有绑定可用 `/binding edit <id> <需求>`。`id` 是管理工作台中的存储标识，不一定与调用名称相同；也可以在绑定清单中选择 Agent 编辑入口。
+
+## 草稿面板
+
+新草稿自动在输入框上方展开。点击标题栏或使用 Enter/Space 折叠、展开；长内容可在面板内滚动。
+
+- **保存为停用**：保存到全局列表，暂不加载。
+- **保存并启用**：保存并允许后续调用加载。
+- **丢弃草稿**：放弃这份未保存候选。
+- **关闭面板**：只隐藏面板，不保存或丢弃。
+
+输入框星光按钮显示待处理草稿的角标。悬停、点击或键盘打开菜单后，选择草稿即可重新显示。每个会话保留一份当前候选。保存或丢弃确认成功后面板关闭；失败时保留草稿供重试。
+
+星光按钮悬浮或聚焦时显示 PTC Plus 提示，说明它是全局用户绑定入口；有待处理草稿时改为提示草稿状态。星光菜单在首条消息发出前即可使用，鼠标停留一下才展开，扫过输入区不会弹出。悬停打开后鼠标移开菜单即自动关闭；点击可让菜单保持常开，再点一次、点击别处或按 Escape 关闭。全局绑定按名称和用途列出，选中标记与文字表示启用状态；点击条目切换启停，配置对所有会话生效。目录在后台刷新，刷新期间沿用上一次的列表并可以继续操作；保存期间暂时禁用切换，发生冲突或失败时可重新加载后再操作。“管理全局绑定”打开完整工作台；编写命令可用时显示“编写新绑定”和“修改绑定”，“修改绑定”第二步从已有条目中选择后预填 `/binding edit <id> `。REPL 可复用绑定列表会显示每项被后续 cell 复用的次数，并在区块标题显示总复用次数；次数按后续 cell 编译后源码中的静态引用统计，重定义或重声明本身不算一次复用，也不会把已累计的次数清零。
+
+历史中的“绑定编写”请求保留需求、状态和接受时的源码。它供查看当时内容，不重新获得保存资格。目录发生并发修改时，重新加载最新状态后再决定是否保存。
+
+## 接口和给模型的提示词
+
+每个条目有两个独立设置：
+
+| 设置 | 用途 |
+| --- | --- |
+| 将接口声明提供给模型 | 默认开启。从源码生成名称、参数、返回类型和 API 注释，无需另写声明 |
+| 给模型的提示词 | 可留空。补充类型未表达的使用时机、输入约束或示例 |
+
+例如，一个接受字节数的格式化函数可补充：“输入单位为字节，显示时使用 IEC 单位。”函数签名已经清楚的用法无需再写一遍。
+
+模型收到一行 `run_code` 调用位置和接口参考文档更新说明，以及各条目的名称、已配置提示词和所选接口。内容未变时不会因普通调用重复发送。
+
+关闭接口展示不会关闭独立提示词；两者都省略也不会禁用绑定执行。已启用条目的说明在新会话首轮提供，中途保存、启停、删除或修改后在下一次允许的请求中更新。若 DSH 暂停运行时上下文投递，更新会暂缓。
+
+仅修改提示词、声明开关、用途说明或 top-level 显示名会保留已加载模块状态。修改实现源码、scope、namespace 调用名或导出列表会在后续执行时重新加载。
+
+## 手动管理和试运行
+
+从设置中的“管理全局绑定”或会话 **REPL** 页签打开工作台。没有当前 PTC 会话也可以手动创建、导入 `.ts`、检查声明、编辑、启停或删除绑定。
+
+源码必须是带具名值导出的 TypeScript 模块，不支持默认导出或转出其他模块的导出。`namespace` 将选中导出放在一个对象下；`top-level` 直接暴露选中导出。导出列表留空时使用全部具名值导出。名称冲突会在启用前被拒绝。
+
+代码控制台运行当前条目的未保存草稿，支持顶层 `await`，并在连续输入之间保留临时变量。它与 Agent 会话的变量分开，但拥有相同的进程权限；你手动执行的文件、网络等操作会产生真实效果。停止、重置、切换条目或离开工作台会释放环境；源码修改后的下一次运行重新开始。连续十分钟不运行代码也会释放环境，界面中的输入输出记录仍保留。
+
+绑定保存在 `$DSH_HOME/ptc-plus/bindings.json`。条目源码中的相对 import 从该文件所在目录解析，普通会话 REPL 的 import 则从会话项目目录解析。
+
+## 使用限制
+
+已启用表示绑定配置允许加载，不保证每次初始化都成功。当前会话中同名变量的赋值或重声明可以覆盖全局默认值，不会修改保存的条目。
+
+重启后只能恢复可验证的会话状态，不能保证外部文件或服务仍与历史执行时相同。恢复不会重发历史工具操作；无法恢复的部分通过诊断说明。源码格式、资源上限和恢复机制见[运行时参考](runtime-reference.md#global-user-bindings)；工作台详细交互见[客户端 UI](client-ui.md)。

package/docs/value-wire.md

@@ -7,7 +7,7 @@ PTC runtime value、持久 wire 与模型文本是三个不同契约：
 ```text
 JavaScript value
   -> ptc-value-graph/v1 envelope     worker IPC / journal / replay identity
-  -> structured JSON or TS-like text outer CodeRuntime projection
+  -> structured JSON or TS-like text outer execution-seam projection
 ```
 
 wire 从不使用 `eval` 或 `Function` 解码，模型文本也从不作为可执行序列化读取。
@@ -44,10 +44,10 @@ graph 发现顺序与 ECMAScript own-key 顺序共同确定唯一编码。plain
 
 worker completion 显式携带 `hasValue`，协议字段缺失不能与已编码的 JavaScript `undefined` 混淆。显式 `return undefined` 有值；自然无输出的声明 cell 仍保持无值。
 
-DSH 的公共 `CodeRuntime`/tool output 只接受 JSON-safe structured value。为保持社区插件边界：
+DSH 的公共执行缝/tool output 只接受 JSON-safe structured value。为保持社区插件边界：
 
 - dense、无 shared identity 的 plain JSON tree 继续作为 structured result 返回；
-- 包含 `undefined`、special number、BigInt、hole、shared identity 或 cycle 的合法 PTC value 使用确定性、有 byte ceiling 的 TS-like renderer，作为 string result 进入外层 CodeRuntime；
+- 包含 `undefined`、special number、BigInt、hole、shared identity 或 cycle 的合法 PTC value 使用确定性、有 byte ceiling 的 TS-like renderer，作为 string result 进入外层执行缝；
 - 外层投影是 untagged overlapping union：plain JSON 根值本身也可以是 string，调用方不能用 `typeof value === "string"` 判断是否经过 renderer；
 - renderer 只是模型展示，不参与 hydrate；需要继续计算时应保留 live REPL binding；
 - journal 保存 canonical graph envelope，不保存 renderer 反解析结果，也不把 decoded rich value 交给外层 `JSON.stringify`。

package/docs/verification.md

@@ -0,0 +1,57 @@
+# Deterministic verification
+
+`npm run check` runs `npm run verify`, checks that the source tree and review ledger did not change, and records the verified tree for the commit hook. Run `check` alone when the ledger is absent or resolved; running `verify` immediately before it repeats the full suite. While the ledger has unresolved findings, use `npm run verify` to collect verification evidence.
+
+Both commands validate the ledger, compare generated bundles, check syntax, run Client tests, and run all backend tests with coverage. Backend test files run in separate Node processes. The default process count is half the available CPUs, rounded down and bounded between one and four; each process can also own runtime Workers. Tests within each file retain their existing ordering. Coverage still requires 100% lines and functions and at least 95% branches, including compiler source remapping.
+
+Source fingerprints use Git with temporary administrative files, an index and an object directory. Configuration includes and repository attributes preserve canonical content, and newly computed objects stay in the temporary directory. One tagged file inventory identifies tracked, missing, untracked and sparse entries without repeatedly starting Git for each category. The temporary files are written directly, avoiding repeated Git initialization and configuration processes; explicit Git command arguments preserve isolation across Windows/WSL command forwarders.
+
+Set `DSH_PTC_TEST_CONCURRENCY` to a positive integer to override the backend process count. Use `1` for serial diagnosis or when CPU/memory contention affects timing-sensitive tests. This changes scheduling, not runtime compute budgets, test selection, or coverage thresholds. For example:
+
+```bash
+DSH_PTC_TEST_CONCURRENCY=1 npm run verify
+```
+
+```powershell
+$env:DSH_PTC_TEST_CONCURRENCY = '1'
+npm run verify
+Remove-Item Env:DSH_PTC_TEST_CONCURRENCY
+```
+
+Coverage runs additionally set `DSH_PTC_TEST_WORKER_COVERAGE=1` and load `scripts/instrument-worker-coverage.mjs` through Node's `--import`; that test-only seam adds the coverage variable to the helper's inner-Worker launch environment so real kernel, console, and candidate worker branches are measured. Production never sets the marker and continues to project `NODE_V8_COVERAGE` out of the user Worker environment. Because some transport tests install module mocks before importing the real transport, the runner executes two backend groups into the same coverage directory: the mock-dependent files run without the preload, and the remaining files run with it. Each group writes its own `run-*-mock.tap` or `run-*-instrumented.tap` diagnostic, both managed by the same retention and cleanup lifecycle. Test arguments such as `--test-name-pattern` are placed before the selected file list so Node applies them to test selection rather than treating them as file inputs.
+
+`npm run coverage` uses the same scheduling and prints test and total elapsed time. Each invocation collects worker coverage in its own temporary directory under `coverage/`, removed after c8 finishes reporting, so simultaneous runs cannot erase or combine each other's evidence. The default report is printed to the terminal. A separate `coverage/run-*.tap` log retains Node's test diagnostics, including process exit codes and signals that the concise terminal reporter can omit. An explicit Node test reporter option replaces these default reporters. Source changes during verification still invalidate a `check` proof; separate coverage directories do not make concurrent source edits safe.
+
+Windows Node 24 and 26 reproductions and stacks identify a cppgc finalizer (`node::contextify::ContextifyScript`, or `ContextifyContext` when coverage was enabled) running after the environment that owned its private realm was gone, which wrote through a dangling `node::Realm` during isolate teardown. The reproduction ended the whole DSH process when an in-host session worker was terminated; macOS runners also observed whole-file aborts under coverage, but the available evidence does not establish that those aborts came from the same Windows stack or that the same cause applies across platforms. The session kernel now runs in a plugin-owned helper process (`internal/kernel-child.js`); `IsolatedWorker` sends a cooperative shutdown and, if the helper does not leave within its bound, kills only that helper. DSH is no longer the worker-teardown target on any supported host, so a wedged kernel is contained as a helper failure rather than a host-native crash. `.github/workflows/ci.yml` sets `DSH_PTC_TEST_CONCURRENCY: 1` and runs `npm run check` once; the former file-level retry wrapper is gone, and any failing test or file-level abort fails that run. This boundary removes the plugin's in-host kill exposure; it neither repairs the upstream Node path nor proves the macOS abort shared the Windows cause.
+
+Native oracle workers and external Windows command fixtures explicitly disable inherited `NODE_V8_COVERAGE`; they execute no code included by the plugin coverage gate. Subprocesses testing plugin implementations still collect coverage. PowerShell semantic-version observations share one invocation, and Windows registry fixtures read the three effective registry values with one real npm configuration query. Each retains its original inputs and assertions.
+
+The reporting adapter filters script records before c8 merges them. It reads source-map metadata once per input file, retains maps that lead to selected original sources, and leaves unknown or malformed maps to c8. Dependency-only compiler artifacts can be excluded before remapping; mixed compiler bundles retain their original coverage records. c8 still owns merging, remapping, counters, reporting and threshold checks. This uses an isolated adapter for c8's normalization method; dependency upgrades must pass the comparison with ordinary c8, including uncovered counters and mapped sources. The raw V8 reports are not rewritten.
+
+Runtime Workers defer parsing the compiler bundle until their first compiler operation. Ordinary cells already prepared by the host avoid that startup work. Once an uninstrumented host has initialized its compiler, it snapshots V8 compiler bytecode for subsequent session kernel Workers. Coverage runs prepare that snapshot once in a separate uninstrumented process and pass its temporary file through `DSH_PTC_COMPILER_BYTECODE`; instrumented compiler instances neither produce nor consume bytecode. The runner owns this variable and removes the file after the tests. Workers receive private bytes through their initialization data and do not inherit the temporary file setting.
+
+A Worker uses a snapshot only when its complete compiler source matches; V8 checks bytecode compatibility and recompiles when it rejects the snapshot. Workers still initialize independent compiler realms and session state. The host retains one snapshot in memory, and each Worker discards its private copy after consumption; bytecode contains no saved program values. The bundle source, VM constructor and options are captured or isolated from source-owned mutations before execution.
+
+Repeated Global User Binding validation reuses export descriptions and durability analysis inside the private compiler realm. Each cache keys the complete source and transform generation, retains at most 64 entries and 512 Ki characters of serialized keys, and returns fresh data to its caller. Snapshot fields, fingerprints and publication evidence still undergo validation on each request. This cache contains source-derived metadata, never executed values or module state, and is rebuilt for every compiler realm.
+
+Cell preparation carries its successful native JavaScript parse proof into scope normalization, as module preparation already does. Decorator and resource transforms consume their feature scan's existing syntax tree through Babel's AST API. Recovered invalid decorator input retains the original parser diagnostic path. Intrinsic binding skips its source scan when the compiler recorded no bindings to replace. These changes remove repeated preparation work without changing execution budgets or coverage collection.
+
+Nested callable reflection reuses completed ordinary function recipes inside enclosing recipes. A source-position index selects the outermost reusable descendants, and syntax inspection skips their complete AST subtrees. Each reused function already contains its generated helper dependencies; class and method definition recipes keep their separate lowering paths. If all non-native syntax is inside those substituted functions, the surrounding recipe needs no additional type-erasure pass. Enclosing type syntax and resource declarations still undergo their own lowering. Callable marker emission uses cumulative edit offsets and binary searches to retain exact source boundaries without rescanning all edits for each mapping point. Declaration analysis groups at most 64 declarations into each shared ancestry witness, so Babel assigns ownership without repeatedly walking the same ancestors or retaining a full expression graph.
+
+Dynamic eval and Function preparation reuse source-derived compilation results within their private compiler realm. The key includes the complete source and syntax options. Every hit rechecks the original-source facts consulted by that compilation; a changed fact requires compilation again. The cache holds at most 64 entries and 2 Mi characters of serialized keys, results and source facts. Callers receive fresh metadata, and each execution still declares its variables and creates a new activation against the current environment. Cell operation plans remain with their existing compiler owner.
+
+Optional-chain transforms allocate temporary names through the complete compilation unit's allocator. A scoped Babel adapter retains Babel's UID reservations and restores its original method when the transform completes or throws. This avoids a subsequent whole-scope rename for every generated temporary while preserving uniqueness across module regions.
+
+Callable catalogs compress windows containing referenced source ranges. Ranges separated by at most one source block share a window, preserving compression across nearby functions; large unreferenced gaps and unused buffers are omitted. Empty catalogs retain no source buffers. Entries keep their registration order and exact UTF-16 text in the existing catalog format.
+
+Cell preparation traverses parsed trees and edit mappings without allocating a
+temporary object per unit of work. The namespace walk reads a node's own keys
+once and indexes node arrays directly instead of materializing an entry pair
+per property; the source-map builder validates and writes its four offsets
+positionally, and replacement runs reach that builder through a direct emitter
+instead of a generator and a per-run segment object. Rehomed compiler messages
+write their owned data descriptor directly rather than copying a generic
+descriptor first. Every one of these paths produced identical output before and
+after the change; only the immediately discarded allocations are gone.
+
+For focused diagnostics, use `npm run test:client`, `npm run test:semantics`, or Node's test runner with selected test files. These do not replace the final complete command. Model-backed evaluation remains separate and opt-in; see [Evaluation](evaluation.md).