@avantf/dsh-plugin-base 0.4.1 → 0.5.1

package/README.md

@@ -1,7 +1,8 @@
 # @avantf/dsh-plugin-base
 
-给 DSH 插件用的基础包，把三件容易各写一遍的事收在一起：**启动期资源预装**、**宿主兼容门禁**、
-**一组与 DSH 无关的共享工具**。
+DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动态加载它**——不静态 `import`、不打包进插件，
+拿不到就降级挂载——把三件容易各写一遍的事收在一起：**启动期资源预装**、**宿主兼容门禁**、**一组与 DSH
+无关的共享工具**。
 
 - **运行期零依赖**：`dependencies` 为空，源码里连 `zod` 都不 import。
 - 唯一一条 peer 是 `zod`（`>=4.4.3 <5`），由宿主 / 上层提供，好让调用方、本包与宿主解析到**同一份**
@@ -22,7 +23,7 @@
 - 需要安装的由框架下载、校验完整性、**原子落盘**（同目录临时文件 + rename；跨进程一把族根锁）；
 - 锁被活体进程长期持有（锁文件 mtime 越过 `staleMs` 而 holder 的 pid 仍活着）时**不抢锁**：打一条用户可见的
   `warn`（写明 holder 的 pid、已持有时长、本次已等待时长）后继续按预算等待；等不到就报 `lock/timeout`，
-  消息里带 holder 与 mtime 诊断。抢一个活写者的锁会让两个写者进同一目录，超时只是报告；
+  消息里带 holder 与 mtime 诊断；
 - 每一项给出 `present / installed / skipped / failed`，失败带稳定 `code`；
 - 三种内置资源种类：`npm-package`、`binary-archive`、`model-cache`。新的种类 = 一个新的 provider，
   核心不动；
@@ -48,25 +49,8 @@
 | `familyHome` / `familyToolsDir` / `familyModelsDir` / `resolveDataHome` / `expandHome` | 家族根与数据根解析：**⑤ 显式 → ④ 环境变量 → ② 配置值 → 默认**，一律传**具名 slot** |
 | `wellFormedText` / `wellFormedDeep` | 出站文本的良构修复：孤立代理（lone surrogate）会被 `JSON.stringify` 原样写出、被严格解析器整篇拒收，这里统一换成 U+FFFD；引擎没有 `String.prototype.toWellFormed` 时走等价扫描。递归版只修字符串、数组与普通对象（含键），`Date` / 类实例等一律按同一性原样返回 |
 
-> 世代 v3 把没有运行期消费者的构件移到了 `./internal`（如 `createPluginLogger`、Typert 符号
-> `strictCodec` / `endpointId` / `fieldSymbol` / `resultSymbol`、compat 门禁的单个探针、`npmPackageProvider`）。
-> 它们不再是 `.` 接口的一部分；本包自己的插件各有自己的 logger 与 Typert 镜像，不需要它们。
-
-### 4. 接口世代
-
-`.` 上的导出构成本包的**接口**，由世代号冻结：
-
-- `INTERFACE_VERSION`（正整数）+ `api/interface-vN.json` 快照（该代的值名与类型名，随源码在仓库里，
-  不进产物）；
-- `checkInterface(required, module)`：把"调用方构建时所对的世代"与"运行时加载到的本包报告的世代"
-  比一比，返回 `ok` / `incompatible` / `cannot-tell`。纯函数、**非对称**、读属性有守卫（取属性就抛的
-  对象读成"没报"）、**永不抛**。只有加载到的世代**更旧**（成员可能缺失）才是 `incompatible`；加载到的
-  世代**更新**是 `ok` + 一句话的 `warning`（新世代不拿走有消费者的成员 —— v1→v2 是名字超集，v2→v3 是
-  剪枝，剪掉的 18 个成员经证明零消费者），相等是 `ok`；
-- `readInterfaceRequirement(url)`：读调用方产物里烘着的那条记录 `{ baseVersion, interfaceVersion }`；
-  缺失或畸形返回 `undefined`（"没烘"），不抛；
-- 拿到 `incompatible` 时的建议动作是**降级**（不使用本包的共享能力）而不是拒绝挂载；拿到 `ok` + `warning`
-  时照常使用、只把那条警告记下来 —— 本包只把裁决与一句话的 `reason` / `warning` 交出去，怎么处理由调用方决定。
+没有运行期消费者的构件（如 `createPluginLogger`、Typert 符号、compat 的单个探针、`npmPackageProvider`）
+放在不承诺兼容的 `./internal` 子路径，不属于 `.` 接口。
 
 ## 怎么用
 
@@ -76,7 +60,79 @@
 npm install @avantf/dsh-plugin-base
 ```
 
-### 预装资源
+自己的插件把它声明成**普通运行期依赖**，装上插件就会带上它；插件在运行时从**自己的依赖树**解析它。
+
+### 最小示例（完整，可直接抄）
+
+下面是一个插件从构建期准备到启动期取用资源的完整路径。四步都要，缺一步会出现"能跑但拿不到底座"的
+隐性降级。
+
+```ts
+// ── ① 构建期：把零依赖的 bootstrap 拷进自己的源码树，按相对路径 import ──────────────
+//    cp node_modules/@avantf/dsh-plugin-base/dist/bootstrap.js src/envinit-bootstrap.js
+//    （有打包步骤时用 ./preset 自动内联，见「运行时装载」。）
+import { loadFramework } from './envinit-bootstrap.js'
+
+// ── ② 启动期：解析底座 → 校验版本 → 动态 import() ─────────────────────────────────
+//    底座缺失或版本超出 supportedRange 时只返回 undefined（并打一条 warn），
+//    插件照常挂载、走自己的降级路径。
+const framework = await loadFramework<typeof import('@avantf/dsh-plugin-base')>({
+  logger: { warn: (message) => { log.warn(`envinit: ${message}`) } },
+})
+
+if (framework === undefined) {
+  log.warn('envinit: @avantf/dsh-plugin-base 不可用，改用内置默认路径继续')
+} else {
+  // ── ③ 取用一项就绪资源（完整调用；清单的形状见「写清单」）───────────────────────
+  const home = framework.familyHome()                       // 受管族根（受 AVANTF_HOME 约束）
+  const provisioner = framework.createProvisioner({ home, logger: log })
+  provisioner.register(framework.binaryArchiveProvider())
+  provisioner.register(framework.modelCacheProvider())
+  provisioner.declare({
+    plugin: 'my-plugin',
+    items: [{
+      id: 'my-plugin:tool',
+      kind: 'binary-archive',
+      spec: {
+        id: 'tool',
+        version: '1.2.3',
+        packs: { 'linux-x64': { url: 'https://example.com/tool.tar.gz', sha256: '<hex>' } },
+      },
+      target: { root: 'tools' },
+      schemaVersion: 1,
+    }],
+  })
+  await provisioner.ensure({ only: ['my-plugin:tool'], deadlineMs: 30_000 })
+  const state = provisioner.resolve('my-plugin:tool')
+  if (state.state === 'ready') {
+    // handle.dir 是可用入口目录（归档：可执行文件所在目录）；handle.env 是 PATH 等增量。
+    process.env.PATH = [state.handle.dir, process.env.PATH].filter(Boolean).join(delimiter)
+  } else {
+    // pending / failed / skipped / missing 都走这里：用内置默认实现，不取消挂载。
+    log.warn(`my-plugin:tool 未就绪（${state.state}），改用内置默认路径`)
+  }
+
+  // ── ④ 跑一次兼容门禁，读 compatReport 的结论（可选，但拒绝加载前必须有）──────────
+  //    ctx 是插件自己的宿主 ctx，spec 是本插件的契约清单（服务 / 工具 / schema / 版本）。
+  const verdict = framework.verdictOf(framework.gatherEvidence(ctx, spec))
+  if (!verdict.load) {
+    log.error(framework.compatReport(verdict, {
+      heading: '插件未加载：与当前宿主的兼容性检查未通过。',
+      warningsLabel: '风险提示：',
+      warnings: verdict.warnings,
+      fix: '升级宿主，或按本插件声明的版本重建。',
+      logPointer: prefix => `完整诊断见日志里 ${prefix} 开头的行。`,
+    }))
+  } else if (verdict.warning !== undefined) {
+    log.warn(`compat: ${verdict.warning}`)
+  }
+}
+```
+
+`delimiter` 来自 `node:path`（`import { delimiter } from 'node:path'`），`log` / `ctx` / `spec` 是插件自己的
+对象——它们不来自底座，所以底座缺席时照样存在。
+
+### 预装资源（逐项）
 
 ```ts
 import { homedir } from 'node:os'
@@ -173,7 +229,7 @@ framework.createProvisioner({
 })
 ```
 
-清单可以离线检查：
+清单可以不联网检查：
 
 ```bash
 provision lint manifest.json
@@ -224,10 +280,11 @@ const files = new PromptFiles({ dir: join(dataHome, 'prompts'), namespace: 'my-p
 
 如果调用方要在**运行时**装载本包（而不是让它出现在自己的 import 图里），本包提供零依赖的
 `./bootstrap`：解析本包在哪 → 校验版本落在给定区间 → 动态 `import()`。它**不安装任何东西**，
-失败只返回 `undefined` 并给出原因。
+失败只返回 `undefined` 并给出原因。把它拷进自己的源码、按相对路径 import（上面的最小示例），
+本包缺席时调用方仍能加载，只是走降级路径。
 
 ```ts
-import { loadFramework, readDependencyRange } from '@avantf/dsh-plugin-base/bootstrap'
+import { loadFramework, readDependencyRange } from './envinit-bootstrap.js'
 
 const range = await readDependencyRange(import.meta.url)   // 调用方自己声明的区间
 const framework = await loadFramework<typeof import('@avantf/dsh-plugin-base')>({ logger })
@@ -280,6 +337,26 @@ const report = await runProviderConformance({ provider: myProvider, items: [...]
 assertProviderConformance(report)
 ```
 
+## 接口要点
+
+`.` 上的导出（值 + 类型）构成本包的**接口**，由世代号冻结；`./preset` / `./conformance` / `./bootstrap`
+三个子路径也在承诺内，`./internal` 从不承诺稳定。
+
+- `INTERFACE_VERSION`（正整数）标识当前世代；每一代的名字面有一份随包的快照，名称与导出对不上就是
+  接口变更，必须升世代号。
+- `checkInterface(required, module)`：把"调用方构建时所对的世代"与"运行时加载到的本包报告的世代"比一比，
+  返回 `ok` / `incompatible` / `cannot-tell`。纯函数、**非对称**、读属性有守卫（取属性就抛的对象读成
+  "没报"）、**永不抛**。只有加载到的世代**更旧**（成员可能缺失）才是 `incompatible`；加载到的世代
+  **更新**是 `ok` + 一句话的 `warning`（新世代不拿走有消费者的成员），相等是 `ok`。
+- `readInterfaceRequirement(url)`：读调用方产物里烘着的那条记录 `{ baseVersion, interfaceVersion }`；
+  缺失或畸形返回 `undefined`（"没烘"），不抛。
+- `verifyRegisteredFaces({ ctx, packageId, schemaNames?, toolNames, log, scope? })`：挂载之后复查每条声明的
+  schema 与工具是否真的可见，返回没看到的那些名字（warn-only）。`scope` 是可选的**不透明**值（本包不认识
+  作用域的类型），会原样传给 `tools.get(name, scope)`；不传就按全局视图 `tools.get(name)` 读。
+- 拿到 `incompatible` 时的建议动作是**降级**（不使用本包的共享能力）而不是拒绝挂载；拿到 `ok` + `warning`
+  时照常使用、只把那条警告记下来 —— 本包只把裁决与一句话的 `reason` / `warning` 交出去，怎么处理由
+  调用方决定。
+
 ## 边界（不做的事）
 
 - **不做包管理器**：不推导传递依赖、不生成 lockfile、不做版本求解；每个 item 自包含。
@@ -290,28 +367,19 @@ assertProviderConformance(report)
 ## 版本承诺
 
 - 接口面是 `.` 上的导出（值 + 类型）加上 `./preset` / `./conformance` / `./bootstrap` 三个子路径；`./internal`
-  是内部件，从不承诺稳定（v3 起落在这里的还有那些没有运行期消费者的构件：compat 的单个探针、
-  provisioner 的常量、`npmPackageProvider`、Typert 符号、`createPluginLogger`）。
-- **当前这一代（v3）把 `.` 收成了一个稳定子集**：`.` 只列"插件真取用、或插件作者被期望调用"的成员
-  （32 个值 + 66 个类型），其余进 `./internal`。名字面落在 `api/interface-vN.json` 快照里，随源码在仓库、
-  不进产物。这是为了把"内部件的改动"与"接口"解耦（v3 之前 `.` 是两句 `export *` 的副产品，加一个内部
-  helper 就算接口变更），不是"这个集合永远不变"：新能力从明确标注为不稳定的入口引入，既有成员按弃用
-  周期退出。
-- **v3 是第一次破坏性换代**：v2 的成员如果有消费者，v3 一个不少（剪掉的 18 个经跨树证明零消费者）；
-  但 v3 不再对 v2 做结构超集。旧调用方遇到更新的 base 仍判 `ok` + `warning`，遇到更旧的 base 才降级。
-- **接口与包版本是两条轴**：接口换代只升 `INTERFACE_VERSION` 并新增 `api/interface-vN.json`；包版本是
-  普通 semver，只表达包自身（行为变更 minor、修复 patch）。
+  是内部件，从不承诺稳定。
+- **当前这一代（v4）沿用 v3 的名字面**：`.` 只列"插件真取用、或插件作者被期望调用"的成员，其余进
+  `./internal`。这是为了把"内部件的改动"与"接口"解耦，不是"这个集合永远不变"：新能力从明确标注为
+  不稳定的入口引入，既有成员按弃用周期退出。v4 一个名字都没动 —— 它加宽的是**既有成员接受的入参**：
+  `verifyRegisteredFaces({ …, scope? })` 多了个可选、不透明的 `scope`，原样透传给 `tools.get(name,
+  scope)`，好让按作用域注册的工具面能被复查到；不传时行为与 v3 逐字相同。
+- **v3 是第一次破坏性换代**：v2 的成员如果有消费者，v3 一个不少；但 v3 不再对 v2 做结构超集。旧调用方
+  遇到更新的 base 仍判 `ok` + `warning`，遇到更旧的 base 才降级。
+- **接口与包版本是两条轴**：接口换代只升 `INTERFACE_VERSION` 并新增快照；包版本是普通 semver，只表达
+  包自身（行为变更 minor、修复 patch）。
 - 顺序敏感的参数一律传**具名对象**（如 `resolveDataHome({ explicit, env, configured })`）；可观察的文案
   由调用方给（如 `compatReport` 的 `words`）。
 
-## 开发
-
-```bash
-pnpm check          # 类型检查 + 测试
-pnpm build          # tsc → dist/
-pnpm pack           # 打包出 tarball
-```
-
 ## 许可
 
 MIT

package/dist/bootstrap.d.ts

@@ -3,18 +3,20 @@
  * @module bootstrap
  */
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.5.1";
 /**
  * The framework interval this bootstrap can launch.
  *
- * Kept equal to the plugins' peer range for the base: the plugin passes no override, so THIS is the
- * runtime gate. It is a plain comparator interval, NOT a caret: the package version is ordinary
- * semver again and no longer tracks the interface, so the interval stays as wide as the family's
- * compatibility promise — `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can
- * consume, and stops at the major that invented a new interface generation. The interface itself is
- * the separate, runtime axis: a base inside this interval whose `INTERFACE_VERSION` differs is judged
- * by the base's own gate (INTERFACE.md §1, §3) — an OLDER base degrades, a NEWER one is `ok` + a
- * warning (generations are additive), and neither ever refuses the mount.
+ * This is the PACKAGE-version window, and nothing else: the interval is byte-for-byte the range the
+ * plugins declare in their `dependencies` for the base (the install-time gate; the base is a plain
+ * dependency, not a peer) and the plugin passes no override, so THIS is the runtime gate too. It is
+ * a plain comparator interval, NOT a caret: the package version is ordinary semver and does not
+ * track the interface, so the interval stays as wide as the family's compatibility promise —
+ * `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can consume. Its upper bound
+ * marks no generation boundary. Generation is the separate, runtime axis, judged on its own: the
+ * base's `INTERFACE_VERSION` is compared by the base's gate (INTERFACE.md §1, §3) — an OLDER base
+ * degrades to `incompatible`, a NEWER one is `ok` + a WARNING (generations are additive), and
+ * neither ever refuses the mount.
  */
 export declare const supportedRange = ">=0.3.0 <1.0.0";
 /** Sink for the warnings that replace a throw. */
@@ -49,7 +51,10 @@ export declare function ensureFramework(options: EnsureFrameworkOptions): Promis
 export declare function loadFramework<T = unknown>(options: EnsureFrameworkOptions): Promise<T | undefined>;
 /**
  * Read the range a plugin declares in the nearest `package.json`: walk up from `from`,
- * preferring `peerDependencies` over `devDependencies`; `undefined` when none is found.
+ * preferring `dependencies` over `peerDependencies` over `devDependencies`; `undefined` when none is
+ * found. `dependencies` is the live declaration — the base ships as a normal dependency of the
+ * plugins — while `peerDependencies` stays as the fallback for plugins built when the base was
+ * declared a peer, and `devDependencies` covers a local checkout.
  */
 export declare function readDependencyRange(from?: string): Promise<string | undefined>;
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,yFAAyF;AACzF,eAAO,MAAM,OAAO,UAAU,CAAA;AAC9B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAI9C,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,iDAAiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AA8LD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoC7G;AAED,oFAAoF;AACpF,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAaxG;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuCnG"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,yFAAyF;AACzF,eAAO,MAAM,OAAO,UAAU,CAAA;AAC9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAI9C,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,iDAAiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AA8LD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoC7G;AAED,oFAAoF;AACpF,wBAAsB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAaxG;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyCnG"}

package/dist/bootstrap.js

@@ -7,18 +7,20 @@ import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export const VERSION = '0.4.1';
+export const VERSION = '0.5.1';
 /**
  * The framework interval this bootstrap can launch.
  *
- * Kept equal to the plugins' peer range for the base: the plugin passes no override, so THIS is the
- * runtime gate. It is a plain comparator interval, NOT a caret: the package version is ordinary
- * semver again and no longer tracks the interface, so the interval stays as wide as the family's
- * compatibility promise — `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can
- * consume, and stops at the major that invented a new interface generation. The interface itself is
- * the separate, runtime axis: a base inside this interval whose `INTERFACE_VERSION` differs is judged
- * by the base's own gate (INTERFACE.md §1, §3) — an OLDER base degrades, a NEWER one is `ok` + a
- * warning (generations are additive), and neither ever refuses the mount.
+ * This is the PACKAGE-version window, and nothing else: the interval is byte-for-byte the range the
+ * plugins declare in their `dependencies` for the base (the install-time gate; the base is a plain
+ * dependency, not a peer) and the plugin passes no override, so THIS is the runtime gate too. It is
+ * a plain comparator interval, NOT a caret: the package version is ordinary semver and does not
+ * track the interface, so the interval stays as wide as the family's compatibility promise —
+ * `>=0.3.0 <1.0.0` admits every 0.x base this generation of plugins can consume. Its upper bound
+ * marks no generation boundary. Generation is the separate, runtime axis, judged on its own: the
+ * base's `INTERFACE_VERSION` is compared by the base's gate (INTERFACE.md §1, §3) — an OLDER base
+ * degrades to `incompatible`, a NEWER one is `ok` + a WARNING (generations are additive), and
+ * neither ever refuses the mount.
  */
 export const supportedRange = '>=0.3.0 <1.0.0';
 const PACKAGE = '@avantf/dsh-plugin-base';
@@ -276,7 +278,10 @@ export async function loadFramework(options) {
 }
 /**
  * Read the range a plugin declares in the nearest `package.json`: walk up from `from`,
- * preferring `peerDependencies` over `devDependencies`; `undefined` when none is found.
+ * preferring `dependencies` over `peerDependencies` over `devDependencies`; `undefined` when none is
+ * found. `dependencies` is the live declaration — the base ships as a normal dependency of the
+ * plugins — while `peerDependencies` stays as the fallback for plugins built when the base was
+ * declared a peer, and `devDependencies` covers a local checkout.
  */
 export async function readDependencyRange(from = process.cwd()) {
     let current = from;
@@ -318,7 +323,9 @@ export async function readDependencyRange(from = process.cwd()) {
             if (typeof parsed !== 'object' || parsed === null)
                 return undefined;
             const manifest = parsed;
-            return rangeOf(manifest['peerDependencies']) ?? rangeOf(manifest['devDependencies']);
+            return rangeOf(manifest['dependencies'])
+                ?? rangeOf(manifest['peerDependencies'])
+                ?? rangeOf(manifest['devDependencies']);
         }
         catch {
             // The nearest manifest is unparseable: stop.

package/dist/compat.d.ts

@@ -397,7 +397,16 @@ export declare function declaredSchemaKeys(packageId: string, names: readonly st
  * Known limit: invocation ENDPOINTS are not observable through the documented query surface
  * (`list`/`listPackages` expose schemas and the package model only), so the four descriptors are
  * covered through the schema keys they use, not counted themselves.
- * @param input - the live context, the real tool names, and the logger.
+ *
+ * `scope` is the OPTIONAL second argument the tools half hands to `tools.get`. A host whose registry
+ * is addressed per scope (a sub-session's `agent.ctx.tools.register`, for instance) answers `undefined`
+ * for a name that was really registered in some other scope, so a caller reading a scoped registration
+ * back has to name that scope or the check reports a false "missing". This module has NO DSH
+ * dependency and does not know what a scope IS: the value is passed through opaquely, exactly as the
+ * caller's own registry expects it. Omitting it keeps the older reading — the second argument is then
+ * `undefined`, which any registry that ignores it (every one that existed through v3) treats exactly as
+ * it treated the single-argument call.
+ * @param input - the live context, the real tool names, the logger, and the caller's optional scope.
  * @returns the registrations that did not show up (empty on success).
  */
 export declare function verifyRegisteredFaces(input: {
@@ -407,6 +416,12 @@ export declare function verifyRegisteredFaces(input: {
     readonly schemaNames?: readonly string[];
     readonly toolNames: readonly string[];
     readonly log: CompatLogger;
+    /**
+     * Opaque pass-through scope for the tools lookup (interface generation v4). Base does not interpret
+     * it — it is whatever the live `tools.get(name, scope)` accepts — and omitting it keeps the global
+     * one-argument reading.
+     */
+    readonly scope?: unknown;
 }): {
     readonly missing: readonly string[];
 };

package/dist/compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"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"}

package/dist/compat.js

@@ -716,7 +716,16 @@ export function declaredSchemaKeys(packageId, names) {
  * Known limit: invocation ENDPOINTS are not observable through the documented query surface
  * (`list`/`listPackages` expose schemas and the package model only), so the four descriptors are
  * covered through the schema keys they use, not counted themselves.
- * @param input - the live context, the real tool names, and the logger.
+ *
+ * `scope` is the OPTIONAL second argument the tools half hands to `tools.get`. A host whose registry
+ * is addressed per scope (a sub-session's `agent.ctx.tools.register`, for instance) answers `undefined`
+ * for a name that was really registered in some other scope, so a caller reading a scoped registration
+ * back has to name that scope or the check reports a false "missing". This module has NO DSH
+ * dependency and does not know what a scope IS: the value is passed through opaquely, exactly as the
+ * caller's own registry expects it. Omitting it keeps the older reading — the second argument is then
+ * `undefined`, which any registry that ignores it (every one that existed through v3) treats exactly as
+ * it treated the single-argument call.
+ * @param input - the live context, the real tool names, the logger, and the caller's optional scope.
  * @returns the registrations that did not show up (empty on success).
  */
 export function verifyRegisteredFaces(input) {
@@ -741,7 +750,11 @@ export function verifyRegisteredFaces(input) {
     if (isRecord(tools) && typeof tools['get'] === 'function') {
         for (const name of input.toolNames) {
             try {
-                if (tools['get'](name) === undefined)
+                // The property is read once and called with the caller's scope; a `get` that only accepts one
+                // parameter (every registry v3 and earlier knew) simply ignores the second argument, so the
+                // omitted-scope reading is unchanged.
+                const get = tools['get'];
+                if (get(name, input.scope) === undefined)
                     missing.push(name);
             }
             catch {

package/dist/index.d.ts

@@ -8,7 +8,14 @@
  * installed plugins actually consume plus the extension points a plugin author is expected to call,
  * and nothing else: the zero-consumer composition pieces moved to `./internal` (see that module).
  *
- * The same surface is stated as a type + two name lists in `./interface.js`; `api/interface-v3.json`
+ * Those are two DIFFERENT kinds of claim, and `test/public-surface.spec.ts` keeps them apart instead of
+ * describing both as "consumed": the consumer half is PROVEN by a cross-tree scan (every `.` member must
+ * be read by a discovered plugin tree), while a member no tree reads today — an author-facing entry
+ * point such as `verdictOf` / `gatherEvidence` or the family paths — must be REGISTERED in that file's
+ * `EXTENSION_POINTS` with a one-line reason. A `.` member that is neither consumed nor registered is a
+ * red gate, not a hidden promise.
+ *
+ * The same surface is stated as a type + two name lists in `./interface.js`; `api/interface-v4.json`
  * is its snapshot, and `test/public-surface.spec.ts` keeps the three in step. Do not add a member
  * here without a generation decision.
  *
@@ -29,7 +36,7 @@ export { PromptFiles } from './kit/prompt_files.js';
 export type { LoadedPromptText, PromptFileSpec, PromptFilesIo, PromptFilesLogger, PromptFilesOptions } from './kit/prompt_files.js';
 export { wellFormedDeep, wellFormedText } from './kit/wellformed.js';
 export { INTERFACE_VERSION } from './interface.js';
-export type { BaseRuntimeV1, BaseRuntimeV2, BaseRuntimeV3, BaseTypeSurfaceV1, BaseTypeSurfaceV2, BaseTypeSurfaceV3, } from './interface.js';
+export type { BaseRuntimeV1, BaseRuntimeV2, BaseRuntimeV3, BaseRuntimeV4, BaseTypeSurfaceV1, BaseTypeSurfaceV2, BaseTypeSurfaceV3, BaseTypeSurfaceV4, } from './interface.js';
 export { checkInterface, readInterfaceRequirement } from './interface_gate.js';
 export type { InterfaceRequirement, InterfaceVerdict } from './interface_gate.js';
 export type { AtStartup, AtUse, BuiltinKind, ItemPolicy, Kind, Manifest, MirrorPolicy, OnMissing, ProvisionItem, ResourceHandle, ResourceSource, ResourceState, Startup, EnsureOptions, Plan, PlanAction, PlanEntry, PlanOptions, ProvisionEvent, ProvisionReport, ProvisionReportEntry, ProvisionStatus, ReportAction, Disposable, ProgressEvent, ProvisionFs, ProvisionLock, ProvisionLogger, ProvisionPolicy, Provisioner, ProvisionerExperimental, ProvisionerOptions, PrunePolicy, PruneReport, InstallContext, InstallManifest, Provider, ProviderContext, ProviderPlan, ProbeResult, PublishMeta, Resolved, ResourceIdentity, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACnF,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAQ5E,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,SAAS,EACT,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAA;AAYpB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC1G,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AACnI,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAapE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,YAAY,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AAMvB,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEjF,YAAY,EAEV,SAAS,EACT,KAAK,EACL,WAAW,EACX,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,aAAa,EAEb,cAAc,EACd,cAAc,EACd,aAAa,EACb,OAAO,EAEP,aAAa,EACb,IAAI,EACJ,UAAU,EACV,SAAS,EACT,WAAW,EACX,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,YAAY,EAEZ,UAAU,EACV,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,EACf,eAAe,EACf,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,WAAW,EAEX,cAAc,EACd,eAAe,EACf,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,WAAW,EACX,WAAW,EACX,QAAQ,EACR,gBAAgB,GACjB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACnF,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAQ5E,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,SAAS,EACT,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAA;AAYpB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC1G,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AACnI,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAcpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,YAAY,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AAMvB,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEjF,YAAY,EAEV,SAAS,EACT,KAAK,EACL,WAAW,EACX,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,aAAa,EAEb,cAAc,EACd,cAAc,EACd,aAAa,EACb,OAAO,EAEP,aAAa,EACb,IAAI,EACJ,UAAU,EACV,SAAS,EACT,WAAW,EACX,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,YAAY,EAEZ,UAAU,EACV,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,EACf,eAAe,EACf,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,WAAW,EAEX,cAAc,EACd,eAAe,EACf,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,WAAW,EACX,WAAW,EACX,QAAQ,EACR,gBAAgB,GACjB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -8,7 +8,14 @@
  * installed plugins actually consume plus the extension points a plugin author is expected to call,
  * and nothing else: the zero-consumer composition pieces moved to `./internal` (see that module).
  *
- * The same surface is stated as a type + two name lists in `./interface.js`; `api/interface-v3.json`
+ * Those are two DIFFERENT kinds of claim, and `test/public-surface.spec.ts` keeps them apart instead of
+ * describing both as "consumed": the consumer half is PROVEN by a cross-tree scan (every `.` member must
+ * be read by a discovered plugin tree), while a member no tree reads today — an author-facing entry
+ * point such as `verdictOf` / `gatherEvidence` or the family paths — must be REGISTERED in that file's
+ * `EXTENSION_POINTS` with a one-line reason. A `.` member that is neither consumed nor registered is a
+ * red gate, not a hidden promise.
+ *
+ * The same surface is stated as a type + two name lists in `./interface.js`; `api/interface-v4.json`
  * is its snapshot, and `test/public-surface.spec.ts` keeps the three in step. Do not add a member
  * here without a generation decision.
  *
@@ -30,10 +37,10 @@ export { BUILD_VERSIONS_FILE, COMPAT_PREFIX, compatReport, gatherEvidence, provi
 // base release, without rebuilding or republishing any plugin. Plugins therefore never inline this
 // code: they load the base at startup and take these capabilities from it at runtime.
 //
-// Generation v3 moved the members with no runtime consumer off `.`: `createPluginLogger` (both trees
-// use their own logger, which must exist before the base is resolved) and the Typert symbol kit
-// (`strictCodec` / `endpointId` / `fieldSymbol` / `resultSymbol`), which both trees keep as local
-// two-line mirrors because the Remote/wire faces are assembled at module load. Both live on
+// Generation v3 moved the members with no runtime consumer off `.`: `createPluginLogger` (each tree
+// uses its own logger, which must exist before the base is resolved) and the Typert symbol kit
+// (`strictCodec` / `endpointId` / `fieldSymbol` / `resultSymbol`), which each tree keeps as a local
+// two-line mirror because the Remote/wire faces are assembled at module load. Both live on
 // `./internal` now.
 export { expandHome, familyHome, familyModelsDir, familyToolsDir, resolveDataHome } from './kit/family.js';
 export { PromptFiles } from './kit/prompt_files.js';
@@ -44,11 +51,12 @@ export { wellFormedDeep, wellFormedText } from './kit/wellformed.js';
 // build time and compare against the value the base they loaded at runtime reports — it is the one
 // value here whose job is the RUNTIME interface gate rather than a caller's API, so it belongs on `.`.
 //
-// v1/v2 stay exported as their generations' type records: a caller compiled against them keeps a
-// name. v3 is the first generation that is NOT `extends` its predecessor — it PRUNES the zero-consumer
-// members to `./internal` (INTERFACE.md §9); the proof that this lost nothing is
-// `VALUE_NAMES_V3 ∪ PRUNED_VALUE_NAMES === VALUE_NAMES_V2` plus the cross-tree zero-consumer check in
-// `test/public-surface.spec.ts`.
+// v1/v2/v3 stay exported as their generations' type records: a caller compiled against them keeps a
+// name. v3 is the generation that PRUNES the zero-consumer members to `./internal` (INTERFACE.md §9);
+// the proof that this lost nothing is `VALUE_NAMES_V3 ∪ PRUNED_VALUE_NAMES === VALUE_NAMES_V2` plus
+// the cross-tree zero-consumer check in `test/public-surface.spec.ts`. v4 changes no name: it is the
+// generation in which `verifyRegisteredFaces` takes an optional opaque `scope` (INTERFACE.md §10), so
+// its lists are the v3 lists and `public-surface.spec.ts` asserts that instead of assuming it.
 export { INTERFACE_VERSION } from './interface.js';
 // The runtime interface gate: the verdict function the plugins call with the generation they baked,
 // and the ONE reader of a plugin's `lib/interface-version.json`. They live here rather than in each