dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/site/reference/tool-execution-pipeline.md

@@ -1,5 +1,6 @@
 ---
 editSource: "docs/tool-execution-pipeline.zh.md"
+rawMarkdownPath: "reference/tool-execution-pipeline.md"
 ---
 
 <!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
@@ -7,7 +8,7 @@ editSource: "docs/tool-execution-pipeline.zh.md"
 
 # 工具执行流水线
 
-此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `finalizeContent` 和 `tools/result` 在此之后运行。
+此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `projectContent` 在执行后策略之前安装已准备内容；`finalizeContent` 和 `tools/result` 在此之后运行。
 
 ```mermaid
 flowchart TD
@@ -22,6 +23,7 @@ flowchart TD
   toolBody["Registered tool execute() body"]
   fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
   owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
+  project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
   post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
   normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
   finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
@@ -43,13 +45,15 @@ flowchart TD
   approval -->|allowed-once| guards
   approval -->|rejected, cancelled, unavailable| denied
   approval -.->|throw| normalized
-  denied --> post
+  denied --> project
   pre -.->|throw| normalized
   toolBody --> fsGate
   fsGate --> toolBody
   toolBody --> owned
   toolBody --> around
-  around --> post
+  around --> project
+  project --> post
+  project -.->|throw| normalized
   around -.->|wrapper throws| normalized
   post -.->|throw| normalized
   post --> finalize

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-dev-kb",
-  "description": "dsh 插件开发知识库：DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 188 页）+ 62 篇仓库补充开发参考 + 主题导航与 253 文件全量搜索索引；以 dsh-plugin-dev-kb 技能让 agent 在插件开发任务中自动加载定位文档。纯数据插件，零运行时依赖。",
-  "version": "1.3.0",
+  "description": "dsh 插件辅助：① dsh-plugin-dev-kb 技能 = DeepSeek Harness 官方文档站完整 Markdown 镜像（中英双语 188 页）+ 182 篇仓库补充开发参考 + 主题导航与 373 文件全量搜索索引；② dsh-dev-sandbox 技能 = 独立 dev profile 开发沙箱工作流，开发中的插件隔离运行，agent 自主启动/重启/冒烟验证，插件崩了不影响主力 dsh。零运行时依赖。",
+  "version": "1.5.1",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/skills/dsh-dev-sandbox.md

@@ -0,0 +1,67 @@
+---
+name: dsh-dev-sandbox
+description: dsh 插件开发沙箱：用独立 dev profile 隔离开发中的插件，插件崩了只崩沙箱、绝不影响主力 dsh。所有启动 / 重启 / 看日志 / 冒烟验证都由 agent 自己完成，不要求用户重启。开发或调试 dsh 插件、需要验证插件能否加载、插件改完要重启验证时加载本技能。
+whenToUse: 开发/调试 dsh 插件需要启动、重启、验证插件加载，或插件疑似把 dsh 搞挂时
+---
+# dsh 插件开发沙箱（dsh-dev-sandbox）
+
+核心原则：**开发中的插件永远装在独立沙箱 profile 里，不进主力 profile**。
+插件写崩 → 只有沙箱起不来，主力 dsh（desktop）照常运行，agent 还活着就能自己看日志、改代码、重启沙箱、再验证——闭环不需要用户参与。
+
+## 1. profile 约定
+
+- **默认沙箱 profile 名：`dev`**，目录 `%USERPROFILE%\.dsh\profiles\dev`（与 `desktop` / `web` 平级）。
+- **用户指定了别的名字就用用户的**（如「用 test 沙箱」→ `profiles\test`），下文的 `dev` 全部替换。
+- 沙箱与主力 profile 完全隔离：插件、patch、会话、设置各一份；provider/模型配置可从主力 profile 的 `cordis.patch.yml` 拷贝 provider 段过来（用编辑工具，UTF-8 无 BOM，勿用 PowerShell 重定向写）。
+
+## 2. 沙箱不存在时：初始化（一次）
+
+```powershell
+# 版本与目标 dsh 对齐：先用主力安装的实际版本号替换下面的 <ver>（插件自身 peerDependencies 也要覆盖它）
+npx -y "@deepseek-ai/dsh@<ver>" plugin --profile dev add file:/绝对路径/插件目录
+```
+
+- `add` 走兼容闸门：peerDependencies 不覆盖当前 dsh 版本会整体拒绝并回滚——这不是网络问题，改 peer 或按提示 `allow-version` 豁免。
+- 开发中插件优先用 `link:`（目录 junction）依赖挂进沙箱 profile 的 `package.json`：**改 lib 后重启沙箱即生效**，不用反复 add。
+- 改完 profile 的 `package.json` / `cordis.patch.yml` 后必须 `pnpm install`（在 profile 目录里）再启动；同一插件严禁双挂载（进 bundles 就不要再 insert）。
+
+## 3. 启动 / 重启沙箱（agent 自己做，不找用户）
+
+```powershell
+# 后台启动（run_in_background），端口避开主力；日志里找 token 行与报错
+npx -y "@deepseek-ai/dsh@<ver>" web --profile dev --port 3081
+```
+
+- 启动日志含 `dsh web: http://127.0.0.1:3081/?token=…`（token 每次启动轮换，用它开 GUI 验证 UI 类插件）。
+- **逐条看 stderr 的 `dsh: skipping profile bundle "X"`**——被跳过 = 插件静默失效（不崩但功能没了），立即修，别当没看见。
+- **自主重启循环**（改代码 / 改配置后）：
+  1. 找进程：`Get-NetTCPConnection -LocalPort 3081 -State Listen | Select OwningProcess`；
+  2. 核对 PID 后 `Stop-Process -Id <pid> -Force`；
+  3. 重新后台启动，读日志验证（无 skipping 警告、无崩溃栈、端口起来）。
+- **红线：沙箱操作只允许碰沙箱端口/profile；绝不 Stop 主力 dsh 进程、绝不改 `profiles\desktop` 下的东西。**
+
+## 4. 冒烟验证（不起 GUI）
+
+一次性 headless 跑同 profile，验证插件能加载、工具能注册：
+
+```powershell
+npx -y "@deepseek-ai/dsh@<ver>" --profile dev "列出你当前可用的工具，并调用 <插件工具名> 做一次最小调用"
+```
+
+启动即崩（exit 非 0 / 打印异常栈）= 插件破坏了 profile 启动，直接读栈修代码，主 dsh 无恙。
+
+## 5. 收尾：进主力 profile
+
+插件在沙箱里稳定后，才走正常流程挪进主力 profile：同步版本与 peerDependencies → 改主力 profile → `pnpm install` → 自检 → 由用户重启主力 dsh（主力重启永远由用户决定）。发布流程遵循该插件仓库自己的发布规范/CI。
+
+## 6. 常见坑速查
+
+| 症状 | 原因 |
+|---|---|
+| 插件没加载也没报错 | 被 `skipping profile bundle` 跳过（peer 不兼容）；或 inject 的服务无 provider 静默 PENDING |
+| 启动即崩 `duplicate loader entry id` | 双挂载：既进 bundles 又被 insert |
+| `installation rejected: incompatible` | 兼容闸门拒绝安装并回滚，改 peer 或 allow-version |
+| 配置文件解析炸 | BOM / UTF-16 污染；只用编辑工具或 UTF-8 无 BOM 写 |
+| 依赖装了不生效 | 改 profile package.json 后忘 `pnpm install` |
+
+更多：dsh 能力与 API 查 `dsh-plugin-dev-kb` 技能的知识库。

package/skills/dsh-plugin-dev-kb.md

@@ -17,17 +17,18 @@ whenToUse: 开发 dsh 插件、查询 dsh 能力与 API、写 Tool、配置 cord
 ```
 kb/
 ├── site/            线上站点完整镜像（中英双语 188 页，优先读这里）
-│   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy
+│   ├── guide/       入门：quickstart / providers / python-sdk / github-review / schedule / mcp-memory / network-proxy / public-deployments
 │   ├── develop/     basic(第一个插件/tool/config/publish)、framework(生命周期/服务/事件)、
 │   │                practice(能力分层/LLM适配器/动态装配)、cordis-tutorial(7章)
 │   ├── reference/   index(架构)、cordis-primer、capability-seams、agent-lifecycle、
 │   │                config-catalog、tool-catalog、api-gateway、cordis-api/(6)、cookbook/(5)、subsystems/(46)
 │   └── en/          英文站镜像（结构与中文站一致）
-├── extra/           仓库内未发布到站点的补充文档（62 篇）：glossary、defensive-patterns、
-│                    module-graph、testing、postmortem/(4)、i18n/、cookbook 与 subsystems 扩展
+├── extra/           仓库内未发布到站点的补充文档（182 篇）：glossary、defensive-patterns、
+│                    module-graph、testing、postmortem/、i18n/、cookbook 与 subsystems 扩展、
+│                    upgrade-guide/(各版本升级指南)、persistence-changes/(持久化格式变更)
 ├── meta/
 │   ├── topics.md    ★ 主题导航：任务场景 → 要读的文件（先用这个）
-│   ├── search-index.json  全量检索索引（253 文件：path/url/title/字符数）
+│   ├── search-index.json  全量检索索引（373 文件：path/url/title/字符数）
 │   ├── source.json  来源信息（commit/时间/统计）
 │   └── site-pages.txt     线上站点页面清单
 ├── INDEX.md         全部 站点 URL ↔ 本地文件 对照

package/kb/extra/defensive-patterns.md

@@ -1,33 +0,0 @@
-# Defensive patterns
-
-English | [中文](defensive-patterns.zh.md)
-
-Hard-won bug-class rules: each pattern below is a class of defect that actually shipped or nearly shipped here, stated as the rule that prevents its recurrence. Read this before writing lifecycle, concurrency, subprocess, or teardown code. Test-tier counterparts (real entry path, world-verification, resource ownership) are in [testing.md](testing.md).
-
-## Report orthogonal outcomes independently
-
-A result can be several things at once — a process can time out AND exit 0 because it trapped the signal. Surface each independent fact (`timedOut`, `signal`, `exitCode`) on its own; never nest one flag's report inside another's branch, or a caller reads a cut-short run as a clean success.
-
-## Honor public contracts on BOTH sides
-
-When an implementation receives several representations of one outcome, normalize them before returning through the public API. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmRuntime.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer.
-
-## Async state is not synchronous state
-
-`agent.followup()` has no per-message completion or result; a background job's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never treat `agent/status` or `whenIdle()` as the result of one follow-up: several queued follow-ups, steering, and injected work may share one `running` interval, while cancellation or disposal can discard unstarted items. An automation caller that truly owns a run must define its interval explicitly—for example, from its message's durable inbox receipt through the next whole-agent `idle`—and describe any selected output as interval-wide rather than causally attributed to that message. The guard cuts both ways: if the awaited transition can never occur, the wait hangs, so handle the "nothing to wait for" branch explicitly.
-
-## Dispose must reach quiescence, not just request it
-
-A teardown that issues kills/aborts but returns before the work stops leaves orphans. Make cleanup async and await the children's exit (kill → await `done`), and close listener/notification registries BEFORE killing so late completions stay silent.
-
-## Contain callback exceptions in the dispatcher
-
-A user-supplied listener that throws must not reject the promise it runs inside or starve the listeners after it. Wrap the dispatch loop in try/catch and log; one bad subscriber never breaks core lifecycle.
-
-## Never hand untrusted output the ambient environment or predictable paths
-
-Spawned commands get a scrubbed env (drop `*KEY*`/`*SECRET*`/`*TOKEN*`/`*PASSWORD*`) so harness credentials cannot leak into output, `env`, or spill files. Temp/spill files use a private (0700) dir, random names, and exclusive owner-only opens (`'wx'`, `0o600`) — predictable world-readable paths invite symlink races and disclosure.
-
-## Unlink link-shaped paths
-
-A path that may be a symlink or Windows junction is removed with `lstatSync().isSymbolicLink()` then `unlinkSync`: unlink deletes only the link and refuses a real directory, so it never follows the link into its target. Windows `rmSync(link)` throws `ERR_FS_EISDIR` on a junction; recursive deletion may descend through one into its target. Reserve recursive `rmSync` for known real directories.

package/kb/extra/defensive-patterns.zh.md

@@ -1,35 +0,0 @@
-# 防御性模式
-
-[English](defensive-patterns.md) | 中文
-
-来之不易的缺陷类别规则：下面每条模式都是本项目实际发布或差点发布的一类缺陷，以防止其复发的规则形式陈述。在编写生命周期、并发、子进程或清理代码之前请先阅读本文。测试层面的对应规则（真实入口路径、验证实际结果、资源归属）见 [testing.md](testing.zh.md)。
-
-## 正交结果独立上报
-
-一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。
-
-## 公共约定两侧都要遵守
-
-当一个实现收到同一结果的多种表示时，应在通过公共 API 返回前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmRuntime.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、分片日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
-
-## 异步状态不是同步状态
-
-`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
-
-<a id="dispose-must-reach-quiescence-not-just-request-it"></a>
-
-## dispose 必须达到完全停稳，而不仅仅是请求停止
-
-如果清理流程只发出终止或中止信号便返回，而不等待工作真正停止，就会留下孤儿进程。清理逻辑应采用异步流程，并等待子进程退出（发出终止信号后等待 `done`）；还应在终止进程前关闭监听器注册表和通知注册表，使迟到的完成事件保持静默。
-
-## 在分发器中隔离回调异常
-
-用户提供的监听器如果抛出异常，不得导致它所在的 promise 被 reject，也不得饿死排在它后面的监听器。请用 try/catch 包裹分发循环并记录日志；一个行为不当的订阅者绝不能破坏核心生命周期。
-
-## 绝不将环境变量或可预测路径暴露给不可信输出
-
-启动的命令应使用经过清理的环境变量，移除名称匹配 `*KEY*`、`*SECRET*`、`*TOKEN*` 或 `*PASSWORD*` 的项，防止 harness 凭证通过命令输出、`env` 或 spill 文件泄漏。临时文件和 spill 文件应放在权限为 0700 的私有目录中，使用随机文件名，并以独占且仅所有者可访问的方式打开（`'wx'`、`0o600`）；可预测且全局可读的路径会引发符号链接竞态和信息泄露。
-
-## 用 unlink 删除链接形态的路径
-
-可能是符号链接或 Windows junction 的路径，应先用 `lstatSync().isSymbolicLink()` 判断，再用 `unlinkSync` 删除：unlink 只删除链接本身并拒绝真实目录，因此绝不会跟随链接进入其目标。Windows 上对 junction 调用 `rmSync(link)` 会抛 `ERR_FS_EISDIR`；递归删除可能穿过 junction 进入其目标。真实目录才使用带 `recursive` 的 `rmSync`。

package/kb/site/en/reference/subsystems/code-runtime.md

@@ -1,198 +0,0 @@
----
-editSource: "docs/subsystems/code-runtime.md"
-outline: [2,3]
----
-
-# Code Runtime
-
-The code-execution seam — a [capability seam](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose Service Definition ([dsh-code-runtime](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](./core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service Provider and tool-registry Consumer are specified by the [PTC mode foundation](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-06-15-ptc.md) and [typed-return contract](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-07-20-ptc-typed-tool-returns.md).
-
-Source: [`packages/code-runtime/code-runtime/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/code-runtime/code-runtime/src/types.ts)
-
-## The run: request in, result out
-
-A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package boundaries" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
-
-```ts type-equiv
-/**
- * One run: the program source plus everything the runtime acts on. Per the
- * explicit-over-implicit convention, defaulting (time budgets, output caps)
- * is the implementation's validated config — a request carries no optional
- * tuning knobs for a hidden `??` to fill in.
- */
-interface CodeRunRequest {
-  /**
-   * The program source, in the runtime's {@link ../index.ts | language}. It
-   * runs as the body of an async function: top-level `await` and `return`
-   * are available, and the completion value becomes
-   * {@link CodeRunResult.value}.
-   */
-  program: string
-  /** Host functions exposed to the program, one global object per namespace. */
-  bindings: CodeBindingNamespace[]
-  /**
-   * Abort the run: the runtime stops the program (hard, even mid-loop) and
-   * resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
-   * binding calls are the CALLER's to settle — the runtime only stops asking.
-   */
-  signal?: AbortSignal
-}
-```
-
-The result reports an error as a **field**, never a rejection of `run()` — reporting a failed program is the caller's job, not an exception path (matching `ShellExecutor.run`'s resolve-on-failure contract):
-
-```ts type-equiv
-/**
- * The outcome of one run. An error is a FIELD on a resolved result, never a
- * rejection of `run()` — reporting a failed program is the caller's job, not
- * an exception path.
- */
-interface CodeRunResult {
-  /**
-   * The program's completion value (its top-level `return`), when it ran to
-   * completion and the value crossed the runtime's lossless-JSON boundary.
-   * Invalid or over-limit completions fail the run instead of substituting a
-   * rendered string; a failed or value-less run leaves this absent.
-   */
-  value?: CodeJsonValue
-  /**
-   * Captured text. Each source channel preserves emission order; interleaving
-   * across independent channels is backend-dependent. Bounded only as part of
-   * the outer result.
-   */
-  logs: string[]
-  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
-  error?: CodeRunFailure
-}
-```
-
-## Bindings: host functions as program globals
-
-Each `CodeBindingNamespace` becomes one global object of async callables inside the program (the PTC mode consumer passes one: `tools`). Arguments and resolutions must be lossless JSON and cross without a seam-level byte cap; the runtime may bridge them through structured clone. A namespace may declare a program-visible error class without making the runtime know the consumer's names: the runtime injects the real constructor and turns rejected calls into its instances. A runtime also treats binding names as hostile input (`__proto__` is an ordinary own property, never a prototype collision):
-
-```ts type-equiv
-/**
- * Program-visible typed rejection for one binding namespace. The runtime
- * injects a real error constructor under `name`; rejected member calls become
- * its instances and expose the exact member name through
- * `memberNameProperty`. Both strings are runtime data rather than knowledge
- * of a particular consumer such as PTC mode.
- */
-interface CodeBindingErrorClass {
-  /** Constructor global and resulting `Error.name`; same portable identifier rule as {@link CodeBindingNamespace.global}. */
-  name: string
-  /**
-   * Non-empty own property for the member name. The portable exclusion set is
-   * `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
-   * middle), enforced identically by every backend; any other name —
-   * identifiers or not — is accepted everywhere.
-   */
-  memberNameProperty: string
-}
-```
-
-```ts type-equiv
-/**
- * A named group of {@link CodeBindingFunction}s the runtime exposes to the
- * program as one global object (e.g. `tools`). Function names are arbitrary
- * strings — a runtime must treat names like `__proto__` or `constructor` as
- * ordinary own properties (null-prototype construction), never as prototype
- * collisions.
- */
-interface CodeBindingNamespace {
-  /**
-   * The global identifier the program sees. Must match the LANGUAGE-PORTABLE
-   * identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
-   * 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`, 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. */
-  functions: Record<string, CodeBindingFunction>
-  /** Optional program-visible typed rejection contract for this namespace. */
-  errorClass?: CodeBindingErrorClass
-}
-```
-
-```ts type-equiv
-/** A lossless JSON value transferable through the dependency-light Service Definition. */
-type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
-```
-
-```ts type-equiv
-/**
- * One host-side function exposed to the program as an async callable. The
- * runtime bridges calls to it (possibly across a serialization boundary), so
- * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
- * lossy or non-cloneable value with a descriptive error rather than corrupting
- * the run. No seam-level byte cap applies to a binding resolution. A rejection
- * of this function surfaces inside the program as a rejection of the
- * corresponding call.
- */
-type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
-```
-
-## Captured output and the failure taxonomy
-
-Logs are plain strings. Each source channel preserves emission order, while interleaving across independent channels is backend-dependent because channel metadata is not part of the seam. The runtime captures the program's console and stream output, and consumers render only the text. Implementations cap the serialized outer log-array plus completion-value or failure-message payload; fixed result-envelope syntax and consumer presentation whitespace are not part of that variable-payload ledger. Overflow is an explicit failure rather than in-band value substitution.
-
-Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
-
-```ts type-equiv
-/**
- * Why a run failed. The kinds are orthogonal outcomes reported independently
- * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
- * abort is not a timeout, and a substrate death is neither.
- *
- * - `'exception'` — the program threw or failed to parse/transform.
- * - `'timeout'` — an implementation-owned budget expired; the message says which.
- * - `'abort'` — {@link CodeRunRequest.signal} fired.
- * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
- * - `'invalid-output'` — the completion value was not lossless JSON.
- * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
- */
-interface CodeRunFailure {
-  /** The failure class (see the interface doc for each kind's meaning). */
-  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
-  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
-  message: string
-}
-```
-
-## The service
-
-`CodeRuntime` (`ctx.codeRuntime`, abstract — defined in [`packages/code-runtime/code-runtime/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/code-runtime/code-runtime/src/index.ts)) is `run(request)` plus two readonly descriptors: `language` (what the program must be written in — `'typescript'` and `'python'` are the well-known values, those `dsh-tools` presents, the TypeScript backend released and the Python backend experimental and private (not published); a consumer generating language-specific presentation switches on it and fails loud on one it cannot present) and `isolation` (the execution substrate — `'worker-thread'`, `'process'`, `'container'`; a diagnostic label, **not a security claim**). Implementations must keep runs isolated from each other (no cross-run state) and dispose to quiescence: in-flight runs are terminated and awaited before teardown completes.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
-
-### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
-
-Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
-
-```ts cordis-catalog
-/**
- * Execute one program against the request's bindings and capture what it
- * emitted. See the class doc for the resolution contract (error is a result
- * field; rejection means Service Definition contract misuse only).
- * @param request - the program, its bindings, and the abort signal; the
- *   request carries everything the runtime acts on, with no hidden defaults.
- * @returns the run's outcome: completion value (when transferable), the
- *   ordered log capture, and the failure (if any).
- */
-abstract run(request: CodeRunRequest): Promise<CodeRunResult>
-```
-
-Source: [`packages/code-runtime/code-runtime/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/code-runtime/code-runtime/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/invariants.md

@@ -1,91 +0,0 @@
----
-editSource: "docs/subsystems/invariants.md"
-outline: [2,3]
----
-
-# Runtime Invariants
-
-[dsh-invariants](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/runtime-diagnostics/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/AGENTS.md#conventions).
-
-Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/runtime-diagnostics/invariants/src/index.ts)
-
-## Selection
-
-```ts type-equiv
-/** Runtime invariant selection configured on the service plugin. */
-interface Config {
-  /** Global switch; defaults to `true`. */
-  readonly enabled?: boolean
-  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
-  readonly package_allowlist?: string[]
-  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
-  readonly package_blocklist?: string[]
-}
-```
-
-A package is selected when the service is enabled, the allowlist is empty or at least one pattern matches its full npm name, and no blocklist pattern matches — a blocklist match overrides an allowlist match. Entries compile with `new RegExp(source)`: matching is unanchored unless the source supplies `^` and `$`, and `/pattern/flags` syntax is not parsed. Validation fails loud at service startup: a blank, whitespace-padded, duplicate, or invalid entry throws instead of being skipped. A valid pattern may match no currently loaded package, so later loading and HMR stay deterministic; filters are fixed for the service lifetime ([README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/runtime-diagnostics/invariants/README.md)).
-
-## The installer
-
-```ts type-equiv
-/**
- * Throw a package-attributed invariant failure.
- * @param message - violated package contract without the standard prefix.
- * @returns never because reporting a violation throws.
- */
-type InvariantFailure = (message: string) => never
-```
-
-```ts type-equiv
-/** Install one package's checks into the registration's child context. */
-interface InvariantInstaller {
-  /**
-   * Install the package contribution.
-   * @param ctx - child context owned by this invariant registration.
-   * @param fail - reporter bound to the registering package name.
-   * @returns nothing, or a promise settling after asynchronous checks finish.
-   */
-  (ctx: Context, fail: InvariantFailure): void | Promise<void>
-  /** Services the child installer fiber may access. */
-  readonly inject?: Inject
-}
-```
-
-An enabled installer runs in a dedicated child Cordis fiber; `installer.inject` declares the services that fiber may access, and synchronous or asynchronous installer completion is joined before the registration succeeds. `fail(message)` throws `InvariantError` — `extends Error` with stable `code: 'INVARIANT'`, the owning `packageName`, and a message prefixed `invariant violated by "<package>": …` — so a violation is attributable without the registry importing any product package.
-
-## The service
-
-`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name and returns its effect-scoped disposer. The reservation holds even when filters keep the installer inactive, so two plugins can never silently claim the same package name; a duplicate, blank, or whitespace-containing name throws. An installer failure disposes the child fiber and releases the reservation atomically. The service owns every registration fiber while the returned disposer also belongs to the companion fiber: unloading either side removes listeners, trace state, and the reservation, so a companion can reload and register the same name again without retained state.
-
-## The companion contract
-
-Every workspace package owns a `./invariant` companion ([package contract](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/runtime-diagnostics/invariants/README.md).
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxinvariants--invariantregistry"></a>
-
-### `ctx.invariants` — `InvariantRegistry`
-
-Package-owned invariant registry with global and regex-based selection.
-
-```ts cordis-catalog
-/**
- * Register one package's invariant installer. The package name is reserved
- * even when filtering disables its checks. Enabled installers run in a child
- * fiber; failure disposes that fiber and releases the reservation.
- * @param packageName - full npm package name that owns the contribution.
- * @param installer - listener or startup-check installer for the child context.
- * @returns an effect-scoped disposer for the registration.
- */
-register(packageName: string, installer: InvariantInstaller): () => void
-```
-
-Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/runtime-diagnostics/invariants/src/index.ts)
-<!-- END GENERATED cordis-surface -->