@avantf/dsh-plugin-base 0.5.3 → 0.6.0

package/README.md

@@ -1,8 +1,8 @@
 # @avantf/dsh-plugin-base
 
 DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动态加载它**——不静态 `import`、不打包进插件，
-拿不到就降级挂载——把三件容易各写一遍的事收在一起：**启动期资源预装**、**宿主兼容门禁**、**一组与 DSH
-无关的共享工具**。
+拿不到就降级挂载——把四件容易各写一遍的事收在一起：**启动期资源预装**、**共享运行期依赖**、
+**宿主兼容门禁**、**一组与 DSH 无关的共享工具**。
 
 - **运行期零依赖**：`dependencies` 为空，源码里连 `zod` 都不 import。
 - 唯一一条 peer 是 `zod`（`>=4.4.3 <5`），由宿主 / 上层提供，好让调用方、本包与宿主解析到**同一份**
@@ -25,11 +25,38 @@ DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动
   `warn`（写明 holder 的 pid、已持有时长、本次已等待时长）后继续按预算等待；等不到就报 `lock/timeout`，
   消息里带 holder 与 mtime 诊断；
 - 每一项给出 `present / installed / skipped / failed`，失败带稳定 `code`；
-- 三种内置资源种类：`npm-package`、`binary-archive`、`model-cache`。新的种类 = 一个新的 provider，
-  核心不动；
+- 四种内置资源种类：`npm-package`、`binary-archive`、`model-cache`、`runtime-deps`。新的种类 =
+  一个新的 provider，核心不动；
 - 策略可配：离线、镜像、每项的并发与超时、启动预算、下载总闸。
 
-### 2. 宿主兼容门禁
+### 2. 共享运行期依赖（runtime-deps）
+
+插件需要**自己 install 树里没有**的运行期 npm 包（例如某个带原生模块的推理库），但两个插件不该各装一份、
+更不该把宿主单例（`zod`、DSH 包）装成两份。base 提供一个**按 spec 寻址（spec-addressed）、装一次就不再
+改写、全局共享**的依赖根：
+
+```
+插件声明（packages / sources / attempts / verify / peers）
+  → key = sha256(packages + verify + lockfile + platform/arch/Node ABI + manager 版本
+                 + attempts 的 source/env/scripts + peer 名/区间 + 解析到的宿主副本)
+  → 在 <home>/deps/runtime/<key>/ 只装一次（per-key 锁 + staging + 原子 rename）
+  → 插件用 createRequire(<根>/package.json) 加载
+```
+
+- key 是**声明**的摘要，不是取回字节的摘要：不给 `lockfile` 时，同一个 key 在不同时间/机器上可以装出不同
+  版本；根保证的是“装一次，之后本地不再改写”。要字节级可复现就把 `lockfile` 传进来；
+- 同 key ⇒ 同一份物理安装，所有插件共用；改了包、verify、lockfile、平台、manager、env，或 peer 的区间/
+  解析到的副本 ⇒ 新 key、新根，**旧根永不被改写**；
+- `sources` + `attempts` 按顺序尝试（registry / cache / 离线 / 脚本策略）；每个 attempt 都记录，全部失败报
+  `runtime-deps/install-failed`，插件照常挂载（`failed` 只是一条报告）；
+- `verify` 的每一项在写 `.ready` 之前用 `createRequire(...).resolve()` 验过；失败换下一个 attempt；
+- `peers` **只链接不安装**：宿主单例写在 `peerDependencies`（optional），装完从插件自己的树链接进来；复用
+  时同时核对**链接目标**与链接到的版本，同版本的另一个目录不算本 key 的根（没有 symlink 时的复制回退是
+  版本级身份，记录在 `.runtime.json` 的 `copiedPeers`）；
+- **base 不认识任何包名**：装什么、从哪装、验什么，全部来自插件的 `RuntimeDepsSpec`；
+- GC **显式**（`./internal` 的 `gcRuntimeDeps`），按 `status.json` 里记录的 key 保留，绝不在启动时自动回收。
+
+### 3. 宿主兼容门禁
 
 在挂载之前判断"当前宿主能不能跑这段代码"，语义是**只有被证实的不兼容才拒绝**：
 
@@ -39,7 +66,7 @@ DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动
 - `registerMegaphone` 在拒绝加载的路径上留一条用户可见的命令（那时它是唯一的信息渠道）；
 - `verifyRegisteredFaces` 在挂载后复查"声明的每个 schema / 工具真的注册上了"（只告警）。
 
-### 3. 共享工具（kit）
+### 4. 共享工具（kit）
 
 与 DSH 无关的纯逻辑，调用方在运行时复用：
 
@@ -259,6 +286,87 @@ if (!verdict.load) {
 }
 ```
 
+### 取用共享运行期依赖（runtime-deps）
+
+```ts
+// 注册 provider（它和别的 provider 一样进 provisioner）
+provisioner.register(framework.runtimeDepsProvider())
+
+provisioner.declare({
+  plugin: 'my-plugin',
+  items: [{
+    id: 'my-plugin:transformers',
+    kind: framework.RUNTIME_DEPS_KIND,           // 'runtime-deps'
+    spec: {
+      packages: { '@huggingface/transformers': '^4.2.0' },
+      sources: [
+        { id: 'npmmirror', registry: 'https://registry.npmmirror.com' },
+        { id: 'npmjs', registry: 'https://registry.npmjs.org' },
+      ],
+      attempts: [
+        { source: 'npmmirror' },
+        { source: 'npmmirror', env: { ONNXRUNTIME_NODE_INSTALL: 'skip' } },
+        { source: 'npmjs', manager: 'npm' },
+      ],
+      verify: ['@huggingface/transformers'],
+      peers: { zod: '>=4.4.3 <5' },              // 宿主单例：只链接，不从 registry 装
+    },
+    target: { root: 'deps/runtime' },            // 规范位置；换 root 就是另一个共享根
+    onMissing: { atStartup: 'degrade', atUse: 'error' },
+    schemaVersion: 1,
+  }],
+})
+
+const report = await provisioner.ensure({ only: ['my-plugin:transformers'], deadlineMs: 120_000 })
+if (!report.ok) logger.warn('运行期依赖未就绪，用内置降级路径继续')
+
+const state = provisioner.resolve('my-plugin:transformers')
+if (state.state === 'ready') {
+  const dir = state.handle.dir                   // <home>/deps/runtime/<key>
+  const req = createRequire(join(dir, 'package.json'))
+  const transformers = await import(req.resolve('@huggingface/transformers'))
+  // 完整记录（key / attempts / integrity / installedAt）在 <dir>/.runtime.json
+}
+```
+
+### 用 helper 声明运行期依赖 + 会话提示（v6）
+
+上面那种接线（注册 provider、拼 item、`ensure`、`createRequire`）可以缩成一次调用。helper 只是糖，底层
+`runtimeDepsProvider()` + `createProvisioner()` 的行为一字未改：
+
+```ts
+import { createRuntimeDeps } from '@avantf/dsh-plugin-base'
+
+const runtime = createRuntimeDeps({
+  namespace: 'my-plugin',                       // item id 默认 my-plugin:runtime-deps
+  packages: { 'some-runtime-pkg': '^1.2.0' },
+  sources: [{ id: 'npmmirror', registry: 'https://registry.npmmirror.com' }],
+  attempts: [{ source: 'npmmirror' }],
+  verify: ['some-runtime-pkg'],
+  // 文案永远是插件的（base 里没有任何包名/命令/句子）；when 决定它对应哪种状态
+  notices: [{
+    id: 'my-plugin:runtime-pkg',
+    severity: 'degraded',
+    when: 'failed',
+    body: '[my-plugin] 可选能力未就绪，已降级为内置路径。',
+  }],
+})
+
+provisioner.declare({ plugin: 'my-plugin', items: [runtime.item] })
+const entry = await runtime.ensure(provisioner)          // 这个 item 的报告条目
+if (entry?.action === 'failed') logger.warn(entry.reason ?? '')
+
+// 自己的 pre-step 里（owner 会话）：
+const lines = runtime.notices.consume(sessionId, { ownerOnly: true })
+if (lines.length > 0) return [...lines, existingHint].join('\n')   // 与已有提示合并成 ONE 条
+
+// 就绪后从共享根加载：不复制包、不写 node_modules
+const mod = await runtime.load('some-runtime-pkg')
+```
+
+`notices` 的状态是**每次 consume 重新判断**的（依赖修好了就不再提），一个 id 对每个 session 最多出一次，
+多条同时成立时按 `degraded` > `warning` > `info` 排序合并；`consume` 永不抛。
+
 ### 取用共享工具
 
 ```ts
@@ -333,6 +441,13 @@ assertProviderConformance(report)
 
 ## 接口要点
 
+- **v6（0.7.0）新增**：会话提示 registry `createSessionNotices`（+ `SessionNoticeSpec` /
+  `SessionNoticeRegistry`）与 runtime-deps 的薄 helper `createRuntimeDeps`（+ `RuntimeDepsConfig` /
+  `RuntimeDepsHandle`）；v6 是 v5 的增量世代（`BaseRuntimeV6 extends BaseRuntimeV5`），没有拿走任何旧名字。
+- **v5（0.6.0）新增**：`RUNTIME_DEPS_KIND` / `runtimeDepsProvider` 与 `DependencySource` /
+  `InstallAttempt` / `RuntimeDepsSpec`；v5 是 v4 的增量世代（`BaseRuntimeV5 extends BaseRuntimeV4`）。
+  `BuiltinKind` 增加 `'runtime-deps'`、`ProvisionCode` 增加 `runtime-deps/install-failed`（都是并集加宽）。
+
 `.` 上的导出（值 + 类型）构成本包的**接口**，由世代号冻结；`./preset` / `./conformance` / `./bootstrap`
 三个子路径也在承诺内，`./internal` 从不承诺稳定。
 
@@ -353,8 +468,10 @@ assertProviderConformance(report)
 
 ## 边界（不做的事）
 
-- **不做包管理器**：不推导传递依赖、不生成 lockfile、不做版本求解；每个 item 自包含。
-- **不接管原生模块**：`binding.gyp` / `*.node` / 依赖 `postinstall` 的包会被识别并拒绝。
+- **不自己当包管理器**：不推导传递依赖、不做版本求解；`runtime-deps` 把安装交给调用方声明的 npm / pnpm，
+  依赖图与 lockfile 由 manager 负责，base 只做 spec 寻址、锁、校验与失败报告。
+- **`npm-package` provider 不接管原生模块**：`binding.gyp` / `*.node` / 依赖 `postinstall` 的包会被识别并
+  拒绝；需要原生模块时走 `runtime-deps`（由 manager 安装）或 `binary-archive`。
 - **不跳过校验**：npm 包核对 `dist.integrity`，归档核对 `sha256`。
 - **不做进程内预热**：让文件在盘上是框架的事，读进内存是调用方自己的事。
 
@@ -362,11 +479,13 @@ assertProviderConformance(report)
 
 - 接口面是 `.` 上的导出（值 + 类型）加上 `./preset` / `./conformance` / `./bootstrap` 三个子路径；`./internal`
   是内部件，从不承诺稳定。
-- **当前这一代（v4）沿用 v3 的名字面**：`.` 只列"插件真取用、或插件作者被期望调用"的成员，其余进
-  `./internal`。这是为了把"内部件的改动"与"接口"解耦，不是"这个集合永远不变"：新能力从明确标注为
-  不稳定的入口引入，既有成员按弃用周期退出。v4 一个名字都没动 —— 它加宽的是**既有成员接受的入参**：
-  `verifyRegisteredFaces({ …, scope? })` 多了个可选、不透明的 `scope`，原样透传给 `tools.get(name,
-  scope)`，好让按作用域注册的工具面能被复查到；不传时行为与 v3 逐字相同。
+- **当前这一代（v6）是 v5 的增量**：`.` 仍然只列"插件真取用、或插件作者被期望调用"的成员，其余进
+  `./internal`。v6 新增会话提示 registry 与 runtime-deps helper（2 个值名 + 4 个类型名），没有拿走 v5 的
+  任何名字；`BaseRuntimeV6 extends BaseRuntimeV5`，所以 v1–v5 构建遇到 v6 base 仍判 `ok` + `warning`。
+  v5 本身是 v4 的增量（共享运行期依赖 provider：2 个值名 + 3 个类型名，外加 `BuiltinKind` /
+  `ProvisionCode` 两个并集加宽）；v4 则是一个名字都没动的换代 —— 它加宽的是**既有成员接受的入参**：
+  `verifyRegisteredFaces({ …, scope? })` 多了个可选、不透明的 `scope`，原样透传给
+  `tools.get(name, scope)`，不传时行为与 v3 逐字相同。
 - **v3 是第一次破坏性换代**：v2 的成员如果有消费者，v3 一个不少；但 v3 不再对 v2 做结构超集。旧调用方
   遇到更新的 base 仍判 `ok` + `warning`，遇到更旧的 base 才降级。
 - **接口与包版本是两条轴**：接口换代只升 `INTERFACE_VERSION` 并新增快照；包版本是普通 semver，只表达

package/lib/bootstrap.d.ts

@@ -3,7 +3,7 @@
  * @module bootstrap
  */
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export declare const VERSION = "0.5.3";
+export declare const VERSION = "0.6.0";
 /**
  * The framework interval this bootstrap can launch.
  *

package/lib/bootstrap.js

@@ -6,7 +6,7 @@ import { existsSync, promises as fsp, readFileSync } from 'node:fs';
 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.5.3';
+export const VERSION = '0.6.0';
 /**
  * The framework interval this bootstrap can launch.
  *

package/lib/conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAIV,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EAGf,QAAQ,EAKT,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,wEAAwE;IACxE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAC9B;AA+JD,2FAA2F;AAC3F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4mBpG;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAMzE"}
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAIV,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EAGf,QAAQ,EAKT,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,wEAAwE;IACxE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAC9B;AAoKD,2FAA2F;AAC3F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4mBpG;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAMzE"}

package/lib/conformance.js

@@ -54,11 +54,16 @@ function recordingFs(inner) {
     const mutations = [];
     // Recording is on by default.
     let recording = true;
+    // Bound once: `realpath` is optional on the seam, and forwarding it only when the wrapped fs has it
+    // keeps the kit honest about the documented path-level fallback (a kit-invented realpath would hide
+    // the difference between "resolved" and "spelled"). Read-only, so nothing is recorded.
+    const realpath = inner.realpath?.bind(inner);
     const note = (op, path, to) => {
         if (recording)
             mutations.push(to === undefined ? { op, path } : { op, path, to });
     };
     const fs = {
+        ...(realpath === undefined ? {} : { realpath }),
         readFile: path => inner.readFile(path),
         readdir: path => inner.readdir(path),
         stat: path => inner.stat(path),

package/lib/errors.d.ts

@@ -4,7 +4,9 @@
  */
 /** Every stable code this framework reports.
  *  @stable */
-export type ProvisionCode = 'invalid-option' | 'ignored-field' | 'missing-need' | 'policy/download-disabled' | 'policy/offline' | 'unknown-provider' | 'provider/unavailable' | 'provider/conflict' | 'peer/unsatisfied' | 'npm/no-satisfying-version' | 'npm/no-integrity' | 'npm/integrity-mismatch' | 'npm/lifecycle-script-unsupported' | 'archive/path-traversal' | 'archive/integrity-mismatch'
+export type ProvisionCode = 'invalid-option' | 'ignored-field' | 'missing-need' | 'policy/download-disabled' | 'policy/offline' | 'unknown-provider' | 'provider/unavailable' | 'provider/conflict' | 'peer/unsatisfied' | 'npm/no-satisfying-version' | 'npm/no-integrity' | 'npm/integrity-mismatch' | 'npm/lifecycle-script-unsupported'
+/** Every declared source/attempt of a `runtime-deps` item failed (see `detail` for each attempt). */
+ | 'runtime-deps/install-failed' | 'archive/path-traversal' | 'archive/integrity-mismatch'
 /** This artifact has no pack for the running platform. */
  | 'archive/no-platform-pack' | 'unsupported-envinit' | 'unsupported-item-schema' | 'layout/too-new' | 'layout/mismatch'
 /** `.layout.json` exists but could not be read (EACCES / ENOSPC / half-written). It shares the

package/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;cACc;AACd,MAAM,MAAM,aAAa,GAErB,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,0BAA0B,GAC1B,gBAAgB,GAEhB,kBAAkB,GAClB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAElB,2BAA2B,GAC3B,kBAAkB,GAClB,wBAAwB,GACxB,kCAAkC,GAElC,wBAAwB,GACxB,4BAA4B;AAC9B,0DAA0D;GACxD,0BAA0B,GAE1B,qBAAqB,GACrB,yBAAyB,GACzB,gBAAgB,GAChB,iBAAiB;AACnB;;sFAEsF;GACpF,mBAAmB,GAEnB,cAAc,GACd,sBAAsB,GACtB,cAAc;AAChB;;;6EAG6E;GAC3E,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GAEf,eAAe,CAAA;AAEnB,iGAAiG;AACjG,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEvB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAMlE;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAQjF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;cACc;AACd,MAAM,MAAM,aAAa,GAErB,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,0BAA0B,GAC1B,gBAAgB,GAEhB,kBAAkB,GAClB,sBAAsB,GACtB,mBAAmB,GACnB,kBAAkB,GAElB,2BAA2B,GAC3B,kBAAkB,GAClB,wBAAwB,GACxB,kCAAkC;AAEpC,qGAAqG;GACnG,6BAA6B,GAE7B,wBAAwB,GACxB,4BAA4B;AAC9B,0DAA0D;GACxD,0BAA0B,GAE1B,qBAAqB,GACrB,yBAAyB,GACzB,gBAAgB,GAChB,iBAAiB;AACnB;;sFAEsF;GACpF,mBAAmB,GAEnB,cAAc,GACd,sBAAsB,GACtB,cAAc;AAChB;;;6EAG6E;GAC3E,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GAEf,eAAe,CAAA;AAEnB,iGAAiG;AACjG,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;gBAEvB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAMlE;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAQjF"}

package/lib/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,2BAA2B;AAC3B,wBAAsB,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE5E;AAED,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,uFAAuF;AACvF,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWlF;AAwCD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAO,GACpG,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAU9B;AAED,iCAAiC;AACjC,wBAAgB,SAAS,IAAI,WAAW,CA4DvC"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,2BAA2B;AAC3B,wBAAsB,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE5E;AAED,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,uFAAuF;AACvF,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWlF;AAwCD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAO,GACpG,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAU9B;AAED,iCAAiC;AACjC,wBAAgB,SAAS,IAAI,WAAW,CA+DvC"}

package/lib/fs.js

@@ -147,6 +147,9 @@ export function defaultFs() {
         async chmod(path, mode) {
             await fsp.chmod(path, mode);
         },
+        async realpath(path) {
+            return fsp.realpath(path);
+        },
     };
 }
 //# sourceMappingURL=fs.js.map

package/lib/index.d.ts

@@ -15,9 +15,9 @@
  * `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.
+ * The same surface is stated as a type + two name lists in `./interface.js`; `api/interface-v6.json`
+ * (the file whose `N` equals `INTERFACE_VERSION`) is its snapshot, and `test/public-surface.spec.ts`
+ * keeps the three in step. Do not add a member here without a generation decision.
  *
  * @module index
  */
@@ -28,6 +28,12 @@ export { binaryArchiveProvider, BINARY_ARCHIVE_KIND } from './providers/archive.
 export type { ArchivePack, BinaryArchiveSpec } from './providers/archive.js';
 export { modelCacheProvider, MODEL_CACHE_KIND } from './providers/model.js';
 export type { ModelCacheLayout, ModelCacheSpec } from './providers/model.js';
+export { runtimeDepsProvider, RUNTIME_DEPS_KIND } from './providers/runtime_deps.js';
+export type { DependencySource, InstallAttempt, RuntimeDepsSpec } from './providers/runtime_deps.js';
+export { createSessionNotices } from './session_notices.js';
+export type { SessionNoticeRegistry, SessionNoticeSpec } from './session_notices.js';
+export { createRuntimeDeps } from './runtime_deps_helper.js';
+export type { RuntimeDepsConfig, RuntimeDepsHandle } from './runtime_deps_helper.js';
 export { BUILD_VERSIONS_FILE, COMPAT_PREFIX, compatReport, gatherEvidence, provision, readBuildVersions, readDeclaredVersions, readRuntimeVersions, registerMegaphone, schemaNamesFrom, toolProbeDeclaration, verdictOf, verifyRegisteredFaces, } from './compat.js';
 export type { CompatContext, CompatEvidence, CompatLine, CompatLogger, CompatReportWords, CompatSpec, CompatVerdict, ProbeOutcome, ServiceContract, ServiceProbe, } from './compat.js';
 export { expandHome, familyHome, familyModelsDir, familyToolsDir, resolveDataHome } from './kit/family.js';
@@ -36,7 +42,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, BaseRuntimeV4, BaseTypeSurfaceV1, BaseTypeSurfaceV2, BaseTypeSurfaceV3, BaseTypeSurfaceV4, } from './interface.js';
+export type { BaseRuntimeV1, BaseRuntimeV2, BaseRuntimeV3, BaseRuntimeV4, BaseRuntimeV5, BaseTypeSurfaceV1, BaseTypeSurfaceV2, BaseTypeSurfaceV3, BaseTypeSurfaceV4, BaseTypeSurfaceV5, } 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/lib/index.d.ts.map

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

package/lib/index.js

@@ -15,9 +15,9 @@
  * `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.
+ * The same surface is stated as a type + two name lists in `./interface.js`; `api/interface-v6.json`
+ * (the file whose `N` equals `INTERFACE_VERSION`) is its snapshot, and `test/public-surface.spec.ts`
+ * keeps the three in step. Do not add a member here without a generation decision.
  *
  * @module index
  */
@@ -25,6 +25,21 @@ export { ITEM_SCHEMA_VERSION, createProvisioner } from './provisioner.js';
 export { ProvisionError, reasonOf } from './errors.js';
 export { binaryArchiveProvider, BINARY_ARCHIVE_KIND } from './providers/archive.js';
 export { modelCacheProvider, MODEL_CACHE_KIND } from './providers/model.js';
+// v5: the shared runtime-dependency provider. It is a provider like the three above, but its store is
+// keyed by the DECLARED spec and shared across plugins instead of living under one plugin's item root.
+// Base names no package: the plugin's `RuntimeDepsSpec` supplies packages, sources, attempts, verify
+// entries and peers.
+export { runtimeDepsProvider, RUNTIME_DEPS_KIND } from './providers/runtime_deps.js';
+// v6: session-scoped NOTICES. A generic, in-memory registry: the caller registers an id, a severity and
+// its own state predicate, and consumes at most one line per (notice id, session id). Base supplies no
+// wording, no session identity and no persistence — the plugin owns the hook, the text and the
+// owner/worker decision, which is what keeps base a library rather than a DSH plugin.
+export { createSessionNotices } from './session_notices.js';
+// v6: the thin helper over the v5 provider — one `runtime-deps` ITEM built from the caller's spec, the
+// notices above bound to that item's real state, `ensure`/`resolve`, and a loader that resolves from the
+// shared root (no copy, no `node_modules` write). The lower-level pair (`runtimeDepsProvider` +
+// `createProvisioner`) stays the stable interface; this is optional sugar over it.
+export { createRuntimeDeps } from './runtime_deps_helper.js';
 // The compatibility gate (rules / probes / verdict / report / post-registration check). It used to
 // be the separate `@avantf/dsh-compat` package, provisioned into the framework's managed root; it
 // lives in THIS package now and its composition-layer members are on `.` — a plugin that loaded the