@jayyuen66/dsh-plugin-shared 0.2.2 → 0.2.3

package/README.md

@@ -79,11 +79,11 @@ End users do not install or enable it separately: any consumer package pulls it
 | Requirement | Value |
 | --- | --- |
 | Node.js | `>=22.12.0` — the publish-side floor the plugin family shares, so a package declaring the same `engines.node` never rejects this library |
-| dsh | `^0.2.1-rc.3`, declared as an **optional** peer (importing this package does not need a host) |
+| dsh | `^0.2.1-rc.3 || ^0.2.2-alpha.2`, declared as an **optional** peer (importing this package does not need a host) |
 | Module format | ESM only. `require()` works only where Node supports `require(esm)` |
 | Tree shaking | `"sideEffects": false` |
 
-- **The host window rolls.** This package is verified against the three most recently released host versions at publish time and re-verified once the window moves; the ranges in `engines.dsh` and in the peers are an install gate and a compile-time discipline, not the verification scope.
+- **The host window rolls.** This package is verified against the exact development line pinned in `devDependencies`; the ranges in `engines.dsh` and in the peers are an install gate and a compile-time discipline, not the verification scope. Moving the window means moving those pins, re-running the host parity check and republishing.
 
 ### Dependency requirements
 
@@ -92,7 +92,7 @@ End users do not install or enable it separately: any consumer package pulls it
 - **A host package under `dependencies` disables the consumer's host.** Profiles install with `nodeLinker: hoisted` and `autoInstallPeers: false`, so a listed host package is materialized as a real directory next to the copy the host process already loaded. `@deepseek-ai/dsh-tools` keys its tool-runtime scheduler with a plain `Symbol` (not `Symbol.for`), so symbol identity is per module instance: the host reads the scheduler from the duplicate and gets `undefined`, and every native tool call throws. Build, typecheck and tests pass up to that point; the invariant has to be stated in the manifest.
 - **`@deepseek-ai/dsh-output-retention` is the one required peer.** It is a value import (`truncateEnd`), provided by the host at runtime, and marked `"optional": false` in `peerDependenciesMeta` rather than left implicit — a peer left out of that table is a hard requirement for npm 7+.
 - **The remaining peers are optional.** Except for the bare `@deepseek-ai/dsh` peer, which only declares the host line, they carry type declarations only. `devDependencies` holds the exact development line, including `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-util-values`, whose types the local PTC declarations name, and `@deepseek-ai/dsh-tool-executor-ptc`, whose types only the parity check reads. Profiles never install peers, so no duplicate appears.
-- **Version requirements separate the install gate from the build baseline.** Every `@deepseek-ai/dsh-*` peer uses the same `^0.2.1-rc.3` range as `engines.dsh`, and that range deliberately names one host line. npm resolves each peer on its own, so a peer listing both lines (`^0.2.1-rc.3||^0.2.2-alpha.2`) lets the required `@deepseek-ai/dsh-output-retention` come from the alpha line while cordis comes from the rc line, and a clean install stops at `ERESOLVE`. The supported window is not narrowed by this: the host compares `engines.dsh` with `includePrerelease: true`, under which `^0.2.1-rc.3` is true for `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.1-rc.5` and `0.2.2-alpha.2`. `devDependencies` pin the exact line this repository compiles and tests against (`0.2.2-alpha.2`) and must stay uniform: one `dsh-session` version per tree keeps the nominal types recognizable. `@deepseek-ai/cordis` stays exact in `devDependencies` (`4.0.6-alpha.1`) and its peer range `^4.0.5||^4.0.6-alpha.1` covers both host lines, because one package cannot mix lines the way the host family does; union ranges carry no spaces around `||`, so one spec stays one argument wherever a spec list is split on blanks. `test/publish-manifest.test.ts` checks each of these separately.
+- **Version requirements separate the install gate from the build baseline.** Every `@deepseek-ai/dsh-*` peer carries the same window as `engines.dsh`, and that window names two host lines: a caret's prerelease comparison only covers its own patch tuple, so a single `^0.2.1-rc.3` does not admit `0.2.2-alpha.*` — measured with this workspace's semver, `satisfies('0.2.2-alpha.3','^0.2.1-rc.3')` is false and `{includePrerelease:true}` turns it true, and that flag is exactly what the host's own comparison passes. The cost is measured and belongs here: npm resolves each peer on its own, while the host family pins its own line inside every member (a member of the `0.2.1-rc` line asks cordis `~4.0.5`, the `0.2.2-alpha.2` host line asks `~4.0.6-alpha.1`, and `0.2.2-alpha.3` asks `~4.0.6-alpha.2`), so a consumer that pins the older host line can still stop at `ERESOLVE`, while the same tree resolves on the newest line. The union also admits later prereleases in the same `0.2.2` tuple, such as `0.2.2-rc.1`; that is range semantics, not a compatibility certification. The verified baseline for this release remains exactly `0.2.2-alpha.3`; moving to `rc.1` requires moving the dev pins and re-running the host parity check. pnpm — the installer this workspace supports, and the one behind the host's `dsh plugin add` — resolves both shapes and only prints a peer warning. The loading gate is unaffected either way, because the host compares `engines.dsh` with `includePrerelease: true`. `devDependencies` pin the exact line this repository compiles and tests against (`0.2.2-alpha.3`) and must stay uniform: one `dsh-session` version per tree keeps the nominal types recognizable. `@deepseek-ai/cordis` stays exact in `devDependencies` (`4.0.6-alpha.2`) and its peer range `^4.0.5||^4.0.6-alpha.1` covers both host lines, because one package cannot mix lines the way the host family does: alpha.2 requires `~4.0.6-alpha.1`, alpha.3 requires `~4.0.6-alpha.2`, and the range also admits `4.1.0`. The cordis union carries no spaces around `||`; the install-matrix probe reads one specifier per line now, while the dsh-family window keeps spaces. `test/publish-manifest.test.ts` checks each of these separately.
 - Known upstream limitation: `@deepseek-ai/dsh-llm`'s declarations import `@deepseek-ai/dsh-attachment`, which that package does not declare. It is reached through `dsh-session`, so a consumer running with `skipLibCheck: false` sees `TS2307` from that package, not from this one. The published `./lib/tool-events` declaration also names `@deepseek-ai/dsh-util-values`, which is reached through `dsh-session` / `dsh-tools`; a consumer running with `skipLibCheck: false` must have that package resolvable as well.
 
 ### Shared version floor

package/README.zh-CN.md

@@ -79,11 +79,11 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 | 要求 | 值 |
 | --- | --- |
 | Node.js | `>=22.12.0`——插件家族共用的发布侧下限，声明同一个 `engines.node` 的包不会因为这个库而被拒 |
-| dsh | `^0.2.1-rc.3`，声明为 **optional** peer（import 本包不需要宿主存在） |
+| dsh | `^0.2.1-rc.3 || ^0.2.2-alpha.2`，声明为 **optional** peer（import 本包不需要宿主存在） |
 | 模块形态 | 仅 ESM。`require()` 只在支持 `require(esm)` 的 Node 上可用 |
 | Tree shaking | `"sideEffects": false` |
 
-- **宿主窗口是滚动的。** 本包在发布时最近的三个已发布宿主版本上逐版取证，窗口滚动后重新取证；`engines.dsh` 与 peer 里的范围只是装载门与编译期纪律，不等于取证范围。
+- **宿主窗口是滚动的。** 本包对着 `devDependencies` 里精确锁定的开发线取证；`engines.dsh` 与 peer 里的范围只是装载门与编译期纪律，不等于取证范围。窗口滚动意味着同步移动这些钉版、重跑宿主对照断言并重新发布。
 
 ### 依赖要求
 
@@ -92,7 +92,7 @@ import { isRecord, fieldOf } from "@jayyuen66/dsh-plugin-shared/lib/record";
 - **宿主包写进 `dependencies` 会让消费方的宿主无法工作。** profile 用 `nodeLinker: hoisted` 与 `autoInstallPeers: false` 安装，于是列在 `dependencies` 里的宿主包会被安装成真实目录，与宿主进程已加载的那份并存。`@deepseek-ai/dsh-tools` 的工具运行期调度键是普通 `Symbol`（不是 `Symbol.for`），符号身份按模块实例计算：宿主从副本上读那个键得到 `undefined`，于是每一次原生工具调用都抛错。构建、类型检查与测试在此之前全部通过；这条不变式只能写在 manifest 上。
 - **`@deepseek-ai/dsh-output-retention` 是唯一必需 peer。** 它是值导入（`truncateEnd`），运行期由宿主提供；在 `peerDependenciesMeta` 里明写成 `"optional": false`，不靠"没写就等于必需"，因为没写进那张表对 npm 7+ 就是硬要求。
 - **其余 peer 都是 optional。** 除裸 `@deepseek-ai/dsh`（只声明宿主版本线）外，它们只承载类型声明。`devDependencies` 保存精确的开发线，其中包括本包 PTC 声明所引用的 `@deepseek-ai/dsh-llm` 与 `@deepseek-ai/dsh-util-values`，以及只有对照断言会读其类型的 `@deepseek-ai/dsh-tool-executor-ptc`。profile 不装 peer，所以不会产生副本。
-- **版本要求把装载门与构建基线分开。** 每条 `@deepseek-ai/dsh-*` peer 与 `engines.dsh` 使用同一条 `^0.2.1-rc.3` 范围，而这条范围刻意只写一条宿主线：npm 对每条 peer 独立解析，把两条线并列（`^0.2.1-rc.3||^0.2.2-alpha.2`）会让必需 peer `@deepseek-ai/dsh-output-retention` 取到 alpha 线、cordis 取到 rc 线，干净目录安装止步于 `ERESOLVE`。支持窗口并没有因此变窄——宿主比较 `engines.dsh` 时带 `includePrerelease: true`，在该语义下 `^0.2.1-rc.3` 对 `0.2.1-rc.3`、`0.2.1-rc.4`、`0.2.1-rc.5`、`0.2.2-alpha.2` 全为真。`devDependencies` 精确锁定本仓编译与测试用的那一线（`0.2.2-alpha.2`），且必须统一：一棵树里只有一份 `dsh-session`，nominal 类型才互相认得。`@deepseek-ai/cordis` 在 `devDependencies` 里精确锁定 `4.0.6-alpha.1`，peer 范围 `^4.0.5||^4.0.6-alpha.1` 同时覆盖 rc 线与 alpha 线——单独一枚包不存在宿主家族那种混线问题。含多条比较符的范围在 `||` 两侧不带空格：一枚说明符因此是一个不含空白的 token，在任何按空白切分参数表的安装命令里都不会被拆开（CI 的类型面 peer 安装按行读取）。`test/publish-manifest.test.ts` 分别检查这三件事。
+- **版本要求把装载门与构建基线分开。** 每条 `@deepseek-ai/dsh-*` peer 与 `engines.dsh` 写同一条窗口，而这条窗口点明两条宿主线：caret 的预发布比较只吃自己那条 patch 元组，单写 `^0.2.1-rc.3` 收不进 `0.2.2-alpha.*`——用本工作区的 semver 实测 `satisfies('0.2.2-alpha.3','^0.2.1-rc.3')` 为 false，带 `{includePrerelease:true}` 才为 true，而宿主自己那道比较正是带这一档。代价是量出来写在这里的：npm 逐条 peer 独立解析，宿主家族每一枚包内部又把自己的那条线精确钉住（`0.2.1-rc` 线上的成员要求 cordis `~4.0.5`，`0.2.2-alpha.2` 宿主线要求 `~4.0.6-alpha.1`，`0.2.2-alpha.3` 要求 `~4.0.6-alpha.2`），所以消费者把宿主钉在旧那条线时仍可能止步 `ERESOLVE`，同一条树落在最新线上则可解。并集窗口也收得进同一 `0.2.2` 元组里更晚的预发布，例如 `0.2.2-rc.1`；那只是范围语义，不是兼容性取证。本版实际取证的基线仍是 `0.2.2-alpha.3`，要抬到 `rc.1` 必须同步移动 dev 钉版并重跑宿主对照断言。pnpm——本工作区支持、也是宿主 `dsh plugin add` 在用的安装器——两种形状都解得出，只打一条 peer 告警。装载门两边都不受影响。`devDependencies` 精确锁定本仓编译与测试用的那一线（`0.2.2-alpha.3`），且必须统一：一棵树里只有一份 `dsh-session`，nominal 类型才互相认得。`@deepseek-ai/cordis` 在 `devDependencies` 里精确锁定 `4.0.6-alpha.2`，peer 范围 `^4.0.5||^4.0.6-alpha.1` 同时覆盖 rc 线与 alpha 线——单独一枚包不存在宿主家族那种混线问题：alpha.2 要求 `~4.0.6-alpha.1`，alpha.3 要求 `~4.0.6-alpha.2`，该范围也收得下 `4.1.0`。cordis 这条并集在 `||` 两侧不带空格；类型面 peer 安装现已按行逐枚读取，dsh 家族窗口保留空格。`test/publish-manifest.test.ts` 分别检查这三件事。
 - 已知上游限制：`@deepseek-ai/dsh-llm` 的声明文件引用了它自己没声明的 `@deepseek-ai/dsh-attachment`。它经 `dsh-session` 传递进来，所以开 `skipLibCheck: false` 的消费方会看到来自那个包的 `TS2307`，不是来自本包。发布出去的 `./lib/tool-events` 声明还引用了 `@deepseek-ai/dsh-util-values`，它经 `dsh-session` / `dsh-tools` 传递进来；开 `skipLibCheck: false` 的消费方同样必须能解析到这个包。
 
 ### shared 的版本下限

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayyuen66/dsh-plugin-shared",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "dsh 自研插件的共享工具库：tool 事件流记账扫描 + 卡片 apply/差异骨架 + 统一设置卡 UI 组件 + 官方作业结局映射 + 项目键派生 + 代理对安全截断。作为库包被 import，不由用户启用",
   "keywords": [
     "cordis",
@@ -119,18 +119,18 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.6-alpha.1",
-    "@deepseek-ai/dsh-brand": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-output-retention": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-session": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-shell": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-tool-executor-ptc": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.2",
+    "@deepseek-ai/cordis": "4.0.6-alpha.2",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-locale": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-output-retention": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-shell": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tool-executor-ptc": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.3",
     "@e18e/eslint-plugin": "0.8.1",
     "@types/node": "26.6.6",
     "@types/react": "19.3.0",
@@ -139,6 +139,7 @@
     "eslint-plugin-regexp": "3.3.2",
     "eslint-plugin-sonarjs": "4.2.2",
     "eslint-plugin-zod": "5.2.2",
+    "fast-check": "4.10.2",
     "happy-dom": "21.0.4",
     "oxfmt": "0.75.0",
     "oxlint": "1.90.0",
@@ -152,13 +153,13 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5||^4.0.6-alpha.1",
-    "@deepseek-ai/dsh": "^0.2.1-rc.3",
-    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.3",
-    "@deepseek-ai/dsh-jobs": "^0.2.1-rc.3",
-    "@deepseek-ai/dsh-output-retention": "^0.2.1-rc.3",
-    "@deepseek-ai/dsh-session": "^0.2.1-rc.3",
-    "@deepseek-ai/dsh-shell": "^0.2.1-rc.3",
-    "@deepseek-ai/dsh-tools": "^0.2.1-rc.3",
+    "@deepseek-ai/dsh": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-jobs": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-output-retention": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-shell": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
     "react": "^19.3.0"
   },
   "peerDependenciesMeta": {
@@ -192,7 +193,7 @@
   },
   "icon": "icon.svg",
   "engines": {
-    "dsh": "^0.2.1-rc.3",
+    "dsh": "^0.2.1-rc.3 || ^0.2.2-alpha.2",
     "node": ">=22.12.0"
   },
   "scripts": {