@avantf/dsh-plugin-base 0.3.1 → 0.4.0

package/README.md

@@ -20,6 +20,9 @@
 
 - 已经在盘上 / PATH 上的直接用，不重复下载；
 - 需要安装的由框架下载、校验完整性、**原子落盘**（同目录临时文件 + rename；跨进程一把族根锁）；
+- 锁被活体进程长期持有（锁文件 mtime 越过 `staleMs` 而 holder 的 pid 仍活着）时**不抢锁**：打一条用户可见的
+  `warn`（写明 holder 的 pid、已持有时长、本次已等待时长）后继续按预算等待；等不到就报 `lock/timeout`，
+  消息里带 holder 与 mtime 诊断。抢一个活写者的锁会让两个写者进同一目录，超时只是报告；
 - 每一项给出 `present / installed / skipped / failed`，失败带稳定 `code`；
 - 三种内置资源种类：`npm-package`、`binary-archive`、`model-cache`。新的种类 = 一个新的 provider，
   核心不动；
@@ -41,10 +44,13 @@
 
 | 工具 | 作用 |
 | --- | --- |
-| `PromptFiles` | "缺失或空白就写入默认、有内容则逐字读回"的用户可编辑文本文件层（含崩溃残留的死临时文件清理） |
-| `createPluginLogger` | 带统一前缀、可镜像到宿主 logger 的 logger |
+| `PromptFiles` | "缺失或空白就写入默认、有内容则逐字读回"的用户可编辑文本文件层（含崩溃残留的死临时文件清理）。可传 `namespace` 把 `<dataHome>/prompts` 里属于本插件的 `mem-*` / `mission-*` 前缀变成 base 校验的字段（不传则行为不变） |
 | `familyHome` / `familyToolsDir` / `familyModelsDir` / `resolveDataHome` / `expandHome` | 家族根与数据根解析：**⑤ 显式 → ④ 环境变量 → ② 配置值 → 默认**，一律传**具名 slot** |
-| `strictCodec` / `endpointId` / `fieldSymbol` / `resultSymbol` | 组装 Typert wire 描述符的几行约定 |
+| `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. 接口世代
 
@@ -53,12 +59,14 @@
 - `INTERFACE_VERSION`（正整数）+ `api/interface-vN.json` 快照（该代的值名与类型名，随源码在仓库里，
   不进产物）；
 - `checkInterface(required, module)`：把"调用方构建时所对的世代"与"运行时加载到的本包报告的世代"
-  比一比，返回 `ok` / `incompatible` / `cannot-tell`。纯函数、**双向**、读属性有守卫（取属性就抛的
-  对象读成"没报"）、**永不抛**；
+  比一比，返回 `ok` / `incompatible` / `cannot-tell`。纯函数、**非对称**、读属性有守卫（取属性就抛的
+  对象读成"没报"）、**永不抛**。只有加载到的世代**更旧**（成员可能缺失）才是 `incompatible`；加载到的
+  世代**更新**是 `ok` + 一句话的 `warning`（新世代不拿走有消费者的成员 —— v1→v2 是名字超集，v2→v3 是
+  剪枝，剪掉的 18 个成员经证明零消费者），相等是 `ok`；
 - `readInterfaceRequirement(url)`：读调用方产物里烘着的那条记录 `{ baseVersion, interfaceVersion }`；
   缺失或畸形返回 `undefined`（"没烘"），不抛；
-- 拿到 `incompatible` 时的建议动作是**降级**（不使用本包的共享能力）而不是拒绝挂载 —— 本包只把裁决与
-  一句话的 `reason` 交出去，怎么处理由调用方决定。
+- 拿到 `incompatible` 时的建议动作是**降级**（不使用本包的共享能力）而不是拒绝挂载；拿到 `ok` + `warning`
+  时照常使用、只把那条警告记下来 —— 本包只把裁决与一句话的 `reason` / `warning` 交出去，怎么处理由调用方决定。
 
 ## 怎么用
 
@@ -78,7 +86,6 @@ import type { Provisioner } from '@avantf/dsh-plugin-base'
 const home = join(homedir(), '.avantf', 'env')
 
 const provisioner: Provisioner = framework.createProvisioner({ home, logger })
-provisioner.register(framework.npmPackageProvider())
 provisioner.register(framework.binaryArchiveProvider())
 provisioner.register(framework.modelCacheProvider())
 provisioner.declare(manifest)
@@ -205,10 +212,10 @@ if (!verdict.load) {
 ### 取用共享工具
 
 ```ts
-import { PromptFiles, createPluginLogger } from '@avantf/dsh-plugin-base'
+import { PromptFiles } from '@avantf/dsh-plugin-base'
 
-const log = createPluginLogger({ prefix: '@scope/my-plugin' })
-const files = new PromptFiles({ dir: join(dataHome, 'prompts'), logger: log })
+// 插件自己的 logger（base 解析之前就要用）；提示词层传 `namespace` 让 base 校验前缀。
+const files = new PromptFiles({ dir: join(dataHome, 'prompts'), namespace: 'my-plugin', logger })
   .load([{ file: 'my-plugin-prompt.md', fallback: '内置默认正文\n' }])
 // files[0].text —— 用户写的正文（逐字），或刚写下的默认正文
 ```
@@ -282,8 +289,16 @@ assertProviderConformance(report)
 
 ## 版本承诺
 
-- 承诺稳定的接口是 `.` 上的导出（值 + 类型）与 `./preset` / `./conformance` / `./bootstrap` 三个子路径；
-  `./internal` 是内部件，不承诺稳定。
+- 接口面是 `.` 上的导出（值 + 类型）加上 `./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）。
 - 顺序敏感的参数一律传**具名对象**（如 `resolveDataHome({ explicit, env, configured })`）；可观察的文案
@@ -294,8 +309,7 @@ assertProviderConformance(report)
 ```bash
 pnpm check          # 类型检查 + 测试
 pnpm build          # tsc → dist/
-pnpm pack           # 打包到 release/ 并断言产物
-pnpm release:check  # 发布门禁：typecheck → build → test → pack
+pnpm pack           # 打包出 tarball
 ```
 
 ## 许可

package/dist/bootstrap.d.ts

@@ -3,7 +3,7 @@
  * @module bootstrap
  */
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.4.0";
 /**
  * The framework interval this bootstrap can launch.
  *
@@ -13,7 +13,8 @@ export declare const VERSION = "0.3.1";
  * 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), which degrades rather than refusing.
+ * 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.
  */
 export declare const supportedRange = ">=0.3.0 <1.0.0";
 /** Sink for the warnings that replace a throw. */

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;;;;;;;;;;GAUG;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;;;;;;;;;;;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"}

package/dist/bootstrap.js

@@ -7,7 +7,7 @@ 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.3.1';
+export const VERSION = '0.4.0';
 /**
  * The framework interval this bootstrap can launch.
  *
@@ -17,7 +17,8 @@ export const VERSION = '0.3.1';
  * 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), which degrades rather than refusing.
+ * 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.
  */
 export const supportedRange = '>=0.3.0 <1.0.0';
 const PACKAGE = '@avantf/dsh-plugin-base';

package/dist/compat.d.ts

@@ -247,7 +247,7 @@ export declare function toolProbeDeclaration(defineTool: ToolDeclarationHelper):
  *
  * What this proves that a method-presence check cannot: the registry ACCEPTED our
  * declaration shape and still lists it. It is the difference between "`register` is a
- * function" and "registering what we register works".
+ * function" and "registering what we register missions".
  * @param registry - `ctx.tools`.
  * @returns the outcome; never throws.
  */
@@ -279,7 +279,7 @@ export declare function readRuntimeVersions(packages: readonly string[], base?:
  * Read a live context into the plain evidence the rules consume.
  *
  * The probes are throwaway declarations shaped like the real ones: "`register` is a function" and
- * "registering what we register works" are different claims, and only the second one catches a
+ * "registering what we register missions" are different claims, and only the second one catches a
  * moved contract.
  * @param ctx - the live context (structural: only `get` is used).
  * @param spec - what the caller declared about itself.

package/dist/compat.js

@@ -252,7 +252,7 @@ export function toolProbeDeclaration(defineTool) {
  *
  * What this proves that a method-presence check cannot: the registry ACCEPTED our
  * declaration shape and still lists it. It is the difference between "`register` is a
- * function" and "registering what we register works".
+ * function" and "registering what we register missions".
  * @param registry - `ctx.tools`.
  * @returns the outcome; never throws.
  */
@@ -423,7 +423,7 @@ export function readRuntimeVersions(packages, base = import.meta.url) {
  * Read a live context into the plain evidence the rules consume.
  *
  * The probes are throwaway declarations shaped like the real ones: "`register` is a function" and
- * "registering what we register works" are different claims, and only the second one catches a
+ * "registering what we register missions" are different claims, and only the second one catches a
  * moved contract.
  * @param ctx - the live context (structural: only `get` is used).
  * @param spec - what the caller declared about itself.
@@ -519,7 +519,7 @@ export function verdictOf(evidence) {
         }
         if (version.runtime !== version.declared) {
             versionDiffered = true;
-            warnings.push(`this build was compiled against ${version.package} ${version.declared}, but its links now resolve to ${version.runtime} — rebuild against this machine's dsh (\`pnpm build:dsh\`)`);
+            warnings.push(`this build was compiled against ${version.package} ${version.declared}, but its links now resolve to ${version.runtime} — switch to the dsh version this build declares compatible, or upgrade this package`);
         }
     }
     if (evidence.events.length > 0) {
@@ -553,7 +553,7 @@ export function verdictOf(evidence) {
     else {
         lines.push({
             level: 'error',
-            message: `${COMPAT_PREFIX} REFUSING to load — ${String(problems.length)} proven incompatibility(ies). Rebuild against this machine's dsh (\`pnpm build:dsh\`) or install the @deepseek-ai/dsh this build declares.`,
+            message: `${COMPAT_PREFIX} REFUSING to load — ${String(problems.length)} proven incompatibility(ies). Switch to the @deepseek-ai/dsh this build declares compatible, or upgrade this package.`,
         });
     }
     // `probe-failed` covers every PROVEN break — a service or method that is gone is the same finding
@@ -735,7 +735,7 @@ export function verifyRegisteredFaces(input) {
     if (missing.length > 0) {
         input.log.warn(`${COMPAT_PREFIX} WARNING — ${String(missing.length)} of ${String(expectedKeys.length + input.toolNames.length)} `
             + `real registrations are not visible afterwards: ${missing.join(', ')} — the plugin is already mounted, so this is `
-            + 'reported rather than undone; rebuild against this machine\'s dsh (`pnpm build:dsh`), restart `dsh`, and check again');
+            + 'reported rather than undone; switch to the dsh version this build declares compatible (or upgrade this package), restart `dsh`, and check again');
     }
     return { missing };
 }

package/dist/errors.d.ts

@@ -10,7 +10,12 @@ export type ProvisionCode = 'invalid-option' | 'ignored-field' | 'missing-need'
 /** `.layout.json` exists but could not be read (EACCES / ENOSPC / half-written). It shares the
  *  read-only CONSEQUENCE with the two above and not their meaning: "a newer layout wrote this, do
  *  not touch it" is a verdict about the home, while this is a fact about the read. */
- | 'layout/unreadable' | 'lock/timeout' | 'publish/cross-device' | 'fetch/failed' | 'extract/failed' | 'verify/failed' | 'unknown-error';
+ | 'layout/unreadable' | 'lock/timeout' | 'publish/cross-device' | 'fetch/failed'
+/** A response body crossed a hard byte cap — either the declared `content-length` or the bytes
+ *  actually read. Unlike a short read (which is a truncated DOWNLOAD and retries the next mirror),
+ *  this is TERMINAL: every mirror serves the same oversized object, so trying another one cannot
+ *  help. Providers branch on this code to decide whether to fall through. */
+ | 'fetch/too-large' | 'extract/failed' | 'verify/failed' | 'unknown-error';
 /** An error that carries a stable `code`; a caller branches on `code`, never on message text. */
 export declare class ProvisionError extends Error {
     readonly code: ProvisionCode;

package/dist/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,GACd,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,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"}

package/dist/index.d.ts

@@ -1,22 +1,36 @@
 /**
- * Plugin environment initialisation at startup.
+ * Plugin environment initialisation at startup — the `.` entry, written as an EXPLICIT list.
+ *
+ * Generation v3 (INTERFACE.md §9) replaced the two `export *` re-exports this file used to carry
+ * (`./compat.js`, `./kit/index.js`) with the list below. That is the whole point of the generation:
+ * before v3 the frozen surface was "whatever those two files happened to export", so adding an
+ * internal helper to `compat.ts` was silently an interface change. Now `.` carries the members the
+ * 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`
+ * 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
  */
-export { CAPABILITIES, DEFAULT_DEADLINE_MS, ITEM_SCHEMA_VERSION, createProvisioner, normalizeOnMissing, } from './provisioner.js';
+export { ITEM_SCHEMA_VERSION, createProvisioner } from './provisioner.js';
 export { ProvisionError, reasonOf } from './errors.js';
 export type { ProvisionCode } from './errors.js';
-export { npmPackageProvider, NPM_PACKAGE_KIND } from './providers/npm.js';
-export type { NpmPackageSpec } from './providers/npm.js';
 export { binaryArchiveProvider, BINARY_ARCHIVE_KIND } from './providers/archive.js';
 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 * from './compat.js';
-export * from './kit/index.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';
+export type { DataHomeInput } from './kit/family.js';
+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, BaseTypeSurfaceV1 } from './interface.js';
+export type { BaseRuntimeV1, BaseRuntimeV2, BaseRuntimeV3, BaseTypeSurfaceV1, BaseTypeSurfaceV2, BaseTypeSurfaceV3, } from './interface.js';
 export { checkInterface, readInterfaceRequirement } from './interface_gate.js';
-export type { InterfaceVerdict, InterfaceRequirement } 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';
-export type { PluginLogger, PluginLoggerOptions, PromptFilesIo, PromptFilesLogger, PromptFilesOptions, StrictCodec, } from './kit/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,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;AAM5E,cAAc,aAAa,CAAA;AAM3B,cAAc,gBAAgB,CAAA;AAW9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAClD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAMtE,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,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;AAKnB,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,GACZ,MAAM,gBAAgB,CAAA"}
+{"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"}

package/dist/index.js

@@ -1,35 +1,58 @@
 /**
- * Plugin environment initialisation at startup.
+ * Plugin environment initialisation at startup — the `.` entry, written as an EXPLICIT list.
+ *
+ * Generation v3 (INTERFACE.md §9) replaced the two `export *` re-exports this file used to carry
+ * (`./compat.js`, `./kit/index.js`) with the list below. That is the whole point of the generation:
+ * before v3 the frozen surface was "whatever those two files happened to export", so adding an
+ * internal helper to `compat.ts` was silently an interface change. Now `.` carries the members the
+ * 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`
+ * 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
  */
-export { CAPABILITIES, DEFAULT_DEADLINE_MS, ITEM_SCHEMA_VERSION, createProvisioner, normalizeOnMissing, } from './provisioner.js';
+export { ITEM_SCHEMA_VERSION, createProvisioner } from './provisioner.js';
 export { ProvisionError, reasonOf } from './errors.js';
-export { npmPackageProvider, NPM_PACKAGE_KIND } from './providers/npm.js';
 export { binaryArchiveProvider, BINARY_ARCHIVE_KIND } from './providers/archive.js';
 export { modelCacheProvider, MODEL_CACHE_KIND } from './providers/model.js';
-// The compatibility gate lives in the SAME package now (it used to be `@avantf/dsh-compat`,
-// provisioned into the framework's managed root as an `npm-package` item). Re-exported from the root
-// so a plugin that loaded this package through the inlined bootstrap already holds the gate — no
-// second import path, and no plugin ever names the base by specifier at runtime.
-export * from './compat.js';
-// The shared KIT: pure, DSH-free helpers (prompt files, plugin logger, Typert wire conventions).
-// They are part of THIS package on purpose — fixing or extending a shared helper must be possible
-// with one 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.
-export * from './kit/index.js';
-// The INTERFACE TYPE: the named, frozen v1 surface of this `.` entry. Plugins hold this ONE name
-// instead of the whole `typeof import(...)` namespace, and `api/interface-v1.json` records its names
-// as a machine-checked snapshot. `INTERFACE_VERSION` is the integer plugins bake at 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 `.`.
+// 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
+// base through the inlined bootstrap already holds the gate, with no second import path. The
+// INDIVIDUAL probes (`floorOf` / `checkServices` / `probeToolsRegistry` …) are composition pieces of
+// `gatherEvidence` and moved to `./internal` in v3.
+export { BUILD_VERSIONS_FILE, COMPAT_PREFIX, compatReport, gatherEvidence, provision, readBuildVersions, readDeclaredVersions, readRuntimeVersions, registerMegaphone, schemaNamesFrom, toolProbeDeclaration, verdictOf, verifyRegisteredFaces, } from './compat.js';
+// The shared KIT: pure, DSH-free helpers (prompt files, family paths, well-formed text). They are
+// part of THIS package on purpose — fixing or extending a shared helper must be possible with one
+// 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.
 //
-// `VALUE_NAMES_V1` / `TYPE_NAMES_V1` are deliberately NOT re-exported: they are the snapshot gate's
-// data (read from the source by `test/public-surface.spec.ts`), and exporting them would put the
-// inventory itself into the inventory it describes.
+// 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
+// `./internal` now.
+export { expandHome, familyHome, familyModelsDir, familyToolsDir, resolveDataHome } from './kit/family.js';
+export { PromptFiles } from './kit/prompt_files.js';
+export { wellFormedDeep, wellFormedText } from './kit/wellformed.js';
+// The INTERFACE TYPE: the named, frozen surface of this `.` entry. Plugins hold ONE of these names
+// instead of the whole `typeof import(...)` namespace, and `api/interface-vN.json` records the current
+// generation's names as a machine-checked snapshot. `INTERFACE_VERSION` is the integer plugins bake at
+// 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`.
 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
-// plugin so their semantics (bidirectional, guarded, total) are fixable with one base release; the
+// plugin so their semantics (asymmetric, guarded, total) are fixable with one base release; the
 // plugins keep only the consumption and the degrade decision.
 export { checkInterface, readInterfaceRequirement } from './interface_gate.js';
 //# sourceMappingURL=index.js.map