@hanamesh/dsh-app-host 0.2.0-rc.2 → 0.6.14

package/node_modules/@hanamesh/lib-provision/README.md

@@ -0,0 +1,134 @@
+# @hanamesh/lib-provision
+
+**历史基线：0.1.0-rc.1 · P01–P06、P08、P09、X01–X03 PASS（本机真实网络 + 真实 SIGKILL）；P07 Windows 真实门 NOT_RUN（PLAT，需 mayn）。完整记录与原始输出：`docs/acceptance/P.md` 与同目录 `raw/`、`mutations/`。0.1.0-rc.2 的开发工具迁移已交独立组件验证；0.1.0-rc.3 已更新分发元数据与许可记录；0.1.0-rc.4 同步了已独立验证的 devkit rc.2 开发 vendor；0.2.0 加了正常 Git 范围供给与 `contract/`；当前 0.2.1（与候选 0.2.1-rc.2 功能字节相同，仅版本字段不同）去掉公开的 devkit 可选 peer，`lib/` 随 tag 提交、去掉安装期构建，自身 Devkit 改走 Devkit 源 Git 范围（pnpm）。业务 src/bin/原测试不变。ACCEPTED 由用户亲跑 P01 后给出。**
+
+把「把一个大文件安全地放到用户机器上」做成唯一实现：**选源 → 可续传下载 → sha256 必须等于 manifest → 解压到 root 内唯一 staging → 可选 `verify.exec` → 原子提升 → 账本**。任一步失败：staging 清理、已落位的不动。它不猜任何东西——来源、摘要、目标路径全部来自调用方给的 manifest；唯一的「探测」是 `process.platform-process.arch`。
+
+零运行时依赖（tar.gz / zip 读取用 Node 内置 `zlib` 自写；HTTP 用 Node 24 自带 `fetch`）。不支持 `.tar.xz`。
+
+## 实际环境
+
+| 项目 | 本次实测 | 产品目标 |
+|---|---|---|
+| 系统 | macOS darwin-arm64（Darwin 25.3.0） | macOS / Windows / Linux 四平台；Windows 仅纯函数单测 |
+| Node / npm | 24.13.1 / 11.8.0 | Node 24.13.1，`engines` `>=24.13.1 <25` |
+| TypeScript | 5.9.3（devDependency 钉死） | 5.9.3，`strict` + `exactOptionalPropertyTypes`，`skipLibCheck=false` |
+| 运行时依赖 | 无 | 无 |
+| 真实网络 | nodejs.org 官方 `node-v24.13.1-darwin-arm64.tar.gz`（sha256 取自官方 `SHASUMS256.txt`） | GitHub Releases / CN 反代 / 离线 `file:` |
+
+## 用法
+
+```sh
+# 正常 Git 范围（tag 里已含构建好的 lib/，没有安装期脚本，不装本包开发依赖；npm、pnpm 都直接可用）
+npm install 'git+https://github.com/yzsnstotz/hanamesh-lib-provision.git#semver:^0.2.1'
+# 或已封归档
+npm install /abs/path/hanamesh-lib-provision-0.2.1.tgz
+```
+
+范围边界（npm 自带 semver 7.7.3 实测）：0.x 的 `^0.2.0` 只覆盖 `>=0.2.0 <0.3.0`，不覆盖 0.3.x 或 1.x，也不含任何预发布；`^0.2.1` 只覆盖 `>=0.2.1 <0.3.0`，不含任何预发布；`^0.2.1-rc.2` 也会选到 0.2.1 正式版。公开 manifest 没有 peer，与消费方自己装的任何 Devkit 版本不冲突（pnpm `--strict-peer-dependencies` 实测）。
+
+供给契约在包内 `contract/`：`lib-provision.schema.json`（provider / requirement 两个定义）、`fixtures/provider.json`、`fixtures/consumer.json`，消费方可 `import { describeInstalled, checkSupply } from '@hanamesh/lib-provision/contract/conformance.mjs'` 读出已装包实际提供的 API/CLI/bin 并核对自己的需求。只比较包大版本；`manifestSchema: 1` 是 manifest 数据格式号，不是包 SemVer。
+
+```ts
+import { plan, provision, verify, remove, platformKey } from '@hanamesh/lib-provision';
+
+const manifest = JSON.parse(await fs.readFile('node-24.13.1.json', 'utf8'));
+const root = '/Users/me/Library/Application Support/HanaMesh';
+
+for (const e of await plan(manifest, { root })) console.log(e.item, e.state);   // absent | installed | stale | unsupported
+const results = await provision(manifest, {
+  root,
+  onProgress: (e) => console.error(e.item, e.phase, e.source, e.bytes, e.total, e.note),
+  sourceOrder: ['cn', 'direct'],   // 可选：只用这些源、按这个顺序
+});
+await verify({ root });            // 按所有权清单重算摘要、修复账本
+await remove('node', { root });    // 只删清单里列出的文件
+```
+
+CLI（进度到 stderr，JSON 结果到 stdout，退出码非 0 = 没做完；不需要 PATH/HOME）：
+
+```sh
+hanamesh-provision plan    manifest.json --root <dir>
+hanamesh-provision install manifest.json --root <dir> [--source cn]... [--only node]... [--force]
+hanamesh-provision verify  --root <dir>
+hanamesh-provision remove  node --root <dir>
+hanamesh-provision platform
+```
+
+`docs/acceptance/manifests/node-24.13.1.json` 是一份可直接用的 manifest（官方 Node 24.13.1 四平台，摘要来自 `docs/acceptance/raw/nodejs-SHASUMS256.txt`）。
+
+## Manifest（调用方给，本库只执行）
+
+见 `lib/index.d.ts` 的 `Manifest` 类型。要点：
+
+- `sources[]` 按顺序尝试；`kind` 只能是 `https` / `file`，`base` 协议必须一致。`http:`、`ftp:` 等在校验阶段就拒绝；下载时重定向到非 `https:` 也拒绝。
+- 每个 item 的 `platforms[<platformKey>]` 必须带 64 位小写 hex `sha256`，缺了整个 item 拒绝——**不猜摘要**。可选 `size`、`strip`（剥掉的顶层目录层数）、`url`（该资产的绝对 URL，绕过 `sources`）。
+- `installTo` 是 root 内的相对 POSIX 路径，不得进 `.provision/`。
+- `verify.exec` 是解压后树内的相对路径；以**绝对路径**执行**刚解出的**文件，`env` 只有 `PATH=''`（Windows 加 `SystemRoot`），从不用宿主 PATH。
+- 缺当前平台条目的 item 记为 `unsupported`，不报错。
+
+## 磁盘布局与原子提升
+
+```
+<root>/
+  .provision/ledger.json                 账本（temp + fsync + rename 原子写）
+  .provision/staging/<item>-<sha12>/     唯一 staging（下载的 archive、.part、.part.json、tree/）
+  .provision/trash/<ts>-<item>/          升级时旧版临时停放（成功后删除；verify 能原样放回）
+  .provision/pending/<item>.json         提升进行中的意向记录（verify 据此发现未登账的树）
+  <installTo>/                           目标树
+  <installTo>.manifest.json              所有权清单：文件清单 + 每文件 sha256 + symlink + 目录
+```
+
+提升顺序（每步落盘后才做下一步，任一步失败回滚到旧状态）：
+
+1. 写 pending 记录；写 `<target>.manifest.json.next`（新清单，temp+fsync+rename）
+2. 若 target 存在：`rename(target → trash/tree)`、`rename(旧清单 → trash/manifest.json)`
+3. `rename(.next → <target>.manifest.json)`
+4. `rename(staging/tree → target)`（跨设备 `EXDEV` 直接报错，不复制）
+5. 原子写账本
+6. 删 trash、删 pending、删 staging
+
+被 `kill -9` 打断在任何一步之后的状态都被 `tests/kill.test.mjs` 真实注入过（`HANAMESH_PROVISION_KILL_AT=<checkpoint>`）：rename 之前 → target 是旧版或不存在，绝无半棵树，`verify` 把 trash 里的旧版放回；rename 之后账本之前 → 磁盘领先账本，`verify` 按清单重算摘要后补账本。账本永远不会声称磁盘上没有的东西（`consistency.json` 的 boundary，安全侧 = target；顺序反转变异会让 X03 变红）。
+
+`remove` 只认 `<target>.manifest.json`：清单没有的文件一律不碰，空目录才删；清单缺失时拒绝删除任何东西。
+
+## 续传与换源
+
+- https 下载写 `<archive>.part` + `.part.json`（去掉 query 的 URL、etag、总长）。重跑时对同一 URL 发 `Range: bytes=<n>-`（带 `If-Range`）；服务端回 200 就从头，416 就丢弃 `.part`。传输失败（断连、5xx）保留 `.part`；摘要不符则删文件、换下一个源；所有源都不行才报错（`E_SHA256` / `E_DOWNLOAD`）。
+- `file:` 源直接复制（离线介质）。
+- 进度事件 `{item, phase, bytes?, total?, source?, note?}`；日志与错误信息里的 URL 一律去掉 query / 凭据。
+
+## 安全边界
+
+- 只接受 `https:` 与 `file:`；不跟随到非 https 的重定向（最多 10 跳）。
+- 解压：拒绝绝对路径、盘符、`..`、NUL；symlink 目标必须解析在树内；拒绝穿过已建 symlink 写文件；tar 只接受普通文件/目录/symlink/hardlink（hardlink 只能指向本 archive 里已解出的文件）；zip 校验 CRC32，只支持 store/deflate，拒绝加密条目。
+- 下载内容永不执行，除 `verify.exec` 指定、且 archive 已过 sha256 的那个文件。
+- 不读 PATH 上的任何东西（`tests/platform.test.mjs` 锁死源码里没有按名 spawn `node`/`npm`/`python`、没有读 `process.env.PATH`）。
+
+## Windows
+
+所有对外返回的路径经过 `externalPath()`：绝对、规范化、**去掉 `\\?\` / `\\?\UNC\` 前缀**（clawso 教训：带前缀的路径进 PATH 会被命令搜索忽略）。`stripVerbatimPrefix` / `toVerbatimPath` 导出供壳层使用。zip 在 Windows 上没有可执行位这一说，`mode` 记录但不 chmod。真实 Windows 未跑（P07 PLAT NOT_RUN）。
+
+## 耐久性说明
+
+原子性针对的是**进程终止**（CONSISTENCY.md X02/X03 的级别）。解压时不做逐文件 fsync（Node 树 4500 文件在 APFS 上要 20 s+），清单、账本、目录 rename 都 fsync。整机断电后若树内文件损坏，`verify` 通过清单里的逐文件 sha256 报 `corrupt`，用 `install --force` 重装即可。
+
+## 开发
+
+```sh
+export npm_config_cache=$(mktemp -d)
+pnpm install --frozen-lockfile   # 开发依赖（Devkit 走 Git 子目录，只有 pnpm 能解析）
+npm test                 # tsc + node --test --test-reporter=tap tests/*.test.mjs（含真实 SIGKILL 注入）
+npm run test:types       # tests/types/consumer.ts 用 TS 5.9 严格模式消费 lib/index.d.ts
+npm run test:mutation    # devkit：原 6 条变异，输出到卡运行目录
+npm run check:consistency
+node scripts/acceptance-real.mjs p01|p02   # 真实网络（nodejs.org）
+```
+
+测试 fixture（`tests/fixtures/https-fixture.mjs`）是本地 HTTPS 服务器（自签证书 `fixture-cert.pem`，测试进程内用 `tls.setDefaultCACertificates` 信任，子进程用 `NODE_EXTRA_CA_CERTS`），支持 Range、可注入错文件 / 断连 / 5xx / 重定向 / 慢速。
+
+开发工具 `@hanamesh/devkit` 用 Devkit 源的正常 Git 范围 `git+https://github.com/yzsnstotz/hanamesh-server-shared.git#semver:^0.2.0&path:/packages/devkit` 安装（pnpm 10.33.0，锁在 `pnpm-lock.yaml`），只是 devDependency，不是 peer、不随包分发。`lib/` 提交在仓里，`npm run check:lib` 从 src 重新构建到临时目录并要求与 lib/ 逐字节相同（改了 src 就 `npm run compile` 后提交 lib/；不用 `build` 这个脚本名，因为 npm 的 Git 安装（pacote 21 `lib/git.js`）见到 `build`/`prepare`/`prepack`/`(pre|post)install` 就会在克隆里装开发依赖）。`npm run check` 校验工具链、provision 包策略、consistency 与 lib/；封包后 `npm run verify:pack` 经 devkit 校验纯包 JavaScript、严格 TypeScript、空环境 CLI 与 contract。默认运行目录为 `~/.cache/hanamesh-runs/CONSOLIDATION-03-PROVISION`，可用 `HANAMESH_DEVKIT_RUN_DIR` 覆盖；`HANAMESH_PROVISION_TARBALL` 指定待验归档。运行时依赖仍为零。
+
+## 分发记录
+
+自有代码已按 D-2026-10-05-02 获准分发。包元数据 `private: false`，`license: SEE LICENSE IN LICENSE` 指向随包的原文授权记录；不新增 MIT 或其他许可。名称、版本、协议、来源、用途见 `THIRD_PARTY_NOTICES.md`。开发用 devkit 0.2.0 来自 Devkit 源已发布 tag v0.2.0 → 8f9bcc69cbacf01d97ffe63bbbade4f865e6dd89（子目录 packages/devkit，CONTRACT-DEVKIT-GIT-SUPPLY-01），四个工具与此前 vendor 的 rc.2 字节相同。它只用于开发，不成为运行时依赖或随业务包分发。

package/node_modules/@hanamesh/lib-provision/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# 分发与第三方记录
+
+`@hanamesh/lib-provision` 0.2.1 没有运行时依赖。tar / zip 读取、CRC32、sha256、HTTP 下载全部基于 Node.js 内置模块（`zlib`、`crypto`、`fs`、`fetch`）。
+
+本记录按名称、版本、协议、来源、用途列明真实输入。自有代码的协议栏记录已有分发授权，不新增 SPDX 许可或再许可权利；原文见包内 `LICENSE`。
+
+| 名称 | 版本 | 协议 / 依据 | 来源 | 用途 |
+|---|---|---|---|---|
+| @hanamesh/lib-provision | 0.2.1 | HanaMesh 自有代码分发授权 D-2026-10-05-02（非 SPDX；未指定新许可） | https://github.com/yzsnstotz/hanamesh-lib-provision（Git 范围 `#semver:^0.2.1`）；业务输入 e8707089409ffd3483fc4c964d6032c370dae634 / rc.3，经 ac2896c1fad2fd0373d80e6a9b2ab6833f79251a / rc.4 | Node 库与 hanamesh-provision CLI 的校验、解包、原子提升及账本 |
+| @hanamesh/devkit | 0.2.0 | SEE LICENSE IN LICENSE；HanaMesh 自有工具分发授权 D-2026-10-05-02 / D-2026-10-05-16；未指定新标准许可或再许可权利，原文见安装包内 LICENSE 与 LICENSE_RECORD.md | https://github.com/yzsnstotz/hanamesh-server-shared；Git 范围 `#semver:^0.2.0&path:/packages/devkit`，锁定 tag v0.2.0 → 8f9bcc69cbacf01d97ffe63bbbade4f865e6dd89（CONTRACT-DEVKIT-GIT-SUPPLY-01） | 开发与包门工具（check-toolchain / preflight / mutations / verify-pack）；不随包分发，不是 peer |
+| typescript | 5.9.3 | Apache-2.0（安装包 LICENSE.txt 原文） | https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz | 构建 lib/ 与 .d.ts；不随包分发 |
+| @types/node | 22.19.7 | MIT（安装包 LICENSE 原文） | https://registry.npmjs.org/@types/node/-/node-22.19.7.tgz | 类型声明；不随包分发 |
+| undici-types | 6.21.0 | MIT（安装包 LICENSE 原文） | https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz | @types/node 的锁定传递类型依赖；不随包分发 |
+
+第三方类型与编译工具的协议和锁定来源保留不变。devkit 0.2.0 的四个工具与 rc.2 字节相同，private=false、SEE LICENSE IN LICENSE 不变；不将该授权扩展为 MIT 或其他再许可。旧 devkit rc.1 / rc.2 vendor 归档保全于 Git 历史，不同版替换。
+
+测试 fixture 的自签证书（`tests/fixtures/fixture-cert.pem` / `fixture-key.pem`）由本仓生成，仅供本地 HTTPS fixture 使用，不随包分发。

package/node_modules/@hanamesh/lib-provision/bin/hanamesh-provision.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin launcher; the CLI logic lives in lib/cli.js. Needs no PATH, HOME or working directory.
+import { main } from '../lib/cli.js';
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exitCode = 1;
+  },
+);

package/node_modules/@hanamesh/lib-provision/consistency.json

@@ -0,0 +1,20 @@
+{
+  "module": "lib-provision",
+  "groups": [
+    {
+      "name": "目标树与它的所有权清单",
+      "facts": ["target:tree", "ownership-manifest:<target>.manifest.json"],
+      "medium": "fs:<root>",
+      "why": "树只通过一次 rename(staging/tree → target) 出现或不出现，永无半棵树；清单在 rename 之前以 temp+fsync+rename 落位并只描述这棵树（含每文件 sha256）。rename 前被杀：target 要么是旧版要么不存在（旧版在 .provision/trash 里，verify 原样放回）。"
+    }
+  ],
+  "boundaries": [
+    {
+      "name": "目标树 ↔ 账本 .provision/ledger.json",
+      "sides": ["fs:target+ownership-manifest", "fs:.provision/ledger.json"],
+      "safeDirection": "target",
+      "why": "两个文件不能一次提交。顺序固定为先 rename 树、后写账本：残留只会是「磁盘上已有新树而账本落后」，verify 按所有权清单重算摘要后把账本补齐；绝不允许「账本声称已装而磁盘没有」。单写者（同一 root 同时只跑一个 provision），X03 的真实中断与顺序反转变异见 tests/kill.test.mjs 与 scripts/mutations.mjs。"
+    }
+  ],
+  "exempt": false
+}

package/node_modules/@hanamesh/lib-provision/contract/CHANGELOG.md

@@ -0,0 +1,5 @@
+- 0.2.0-rc.1 — 正常 Git 范围供给：`prepare` 构建使 `git+https://github.com/yzsnstotz/hanamesh-lib-provision.git#semver:^0.2.0-rc.1` 安装得到含 `lib/` 的完整包；新增 contract/ schema、提供方/消费方 fixture 与一致性检查；业务 API/CLI/manifest schema 1 不变。
+- 0.2.0 — 0.2.0-rc.1 转正式：同一内容，只改版本、tag 与消费方范围 `#semver:^0.2.0`。
+- 0.2.1-rc.1 — 公开 manifest 去掉 `@hanamesh/devkit` 可选精确 peer（它只是开发工具记录，与消费方正常 Devkit 0.2.x 在 pnpm strict 下冲突）；`lib/` 随 tag 提交、去掉安装期 `prepare`，Git 消费方不再装本包开发依赖、pnpm 无需 allowlist；自身 Devkit 改走 Devkit 源 `#semver:^0.2.0&path:/packages/devkit`（pnpm），去 vendor。API/CLI/manifest schema 1 不变。
+- 0.2.1-rc.2 — 修 0.2.1-rc.1 的 npm Git 安装：npm（pacote 21）见到 `build` 脚本也会在克隆里装开发依赖、遇 pnpm-only 的 Devkit 子目录说明符 `EINVALIDTAGNAME` 失败；编译脚本改名 `compile`。其余同 0.2.1-rc.1。
+- 0.2.1 — 0.2.1-rc.2 经 AppHost 实际消费回执后转正式：只改版本、tag 与消费方范围 `#semver:^0.2.1` 字段；lib/bin/contract 代码与候选同字节。

package/node_modules/@hanamesh/lib-provision/contract/conformance.mjs

@@ -0,0 +1,80 @@
+// Supply-contract checks shared by the provider tests and installed consumers. Node built-ins only.
+import {spawnSync} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+export const schema = JSON.parse(readFileSync(new URL('./lib-provision.schema.json', import.meta.url), 'utf8'));
+export const providerFixture = JSON.parse(readFileSync(new URL('./fixtures/provider.json', import.meta.url), 'utf8'));
+export const consumerFixture = JSON.parse(readFileSync(new URL('./fixtures/consumer.json', import.meta.url), 'utf8'));
+
+// Validates the subset of JSON Schema the contract file uses: $ref, type, const, pattern, minLength,
+// minimum, required, additionalProperties, properties, items, uniqueItems.
+function check(node, value, at, errors) {
+  if (node.$ref !== undefined) return check(schema.$defs[node.$ref.split('/').at(-1)], value, at, errors);
+  if ('const' in node && JSON.stringify(value) !== JSON.stringify(node.const)) errors.push(`${at}: must be ${JSON.stringify(node.const)}`);
+  const type = Array.isArray(value) ? 'array' : value === null ? 'null' : Number.isInteger(value) ? 'integer' : typeof value;
+  if (node.type !== undefined && node.type !== type) return errors.push(`${at}: must be ${node.type}`);
+  if (node.pattern !== undefined && !new RegExp(node.pattern, 'u').test(value)) errors.push(`${at}: must match ${node.pattern}`);
+  if (node.minLength !== undefined && value.length < node.minLength) errors.push(`${at}: too short`);
+  if (node.minimum !== undefined && value < node.minimum) errors.push(`${at}: below ${node.minimum}`);
+  if (type === 'array') {
+    if (node.uniqueItems && new Set(value).size !== value.length) errors.push(`${at}: items must be unique`);
+    if (node.items !== undefined) value.forEach((v, i) => check(node.items, v, `${at}[${i}]`, errors));
+  }
+  if (type === 'object') {
+    for (const key of node.required ?? []) if (!(key in value)) errors.push(`${at}.${key}: required`);
+    for (const [key, v] of Object.entries(value)) {
+      const sub = node.properties?.[key] ?? node.additionalProperties;
+      if (sub === false) errors.push(`${at}.${key}: not allowed`);
+      else if (sub !== undefined && sub !== true) check(sub, v, `${at}.${key}`, errors);
+    }
+  }
+  return errors;
+}
+
+export function validate(kind, value) {
+  return check(schema.$defs[kind], value, kind, []);
+}
+
+const major = version => Number(version.split('.')[0]);
+const missing = (need, have) => need.filter(name => !have.includes(name));
+
+// Only the major is a compatibility boundary; which minor gets installed is the package manager's range.
+export function checkSupply(provider, requirement) {
+  const errors = [...validate('provider', provider), ...validate('requirement', requirement)];
+  if (errors.length > 0) return errors;
+  if (provider.package !== requirement.package) errors.push(`package ${provider.package} is not ${requirement.package}`);
+  if (major(provider.version) !== requirement.major) errors.push(`major ${major(provider.version)} of ${provider.version} is not required major ${requirement.major}`);
+  if (provider.source.tag !== `v${provider.version}`) errors.push(`tag ${provider.source.tag} does not name version ${provider.version}`);
+  if (provider.manifestSchema !== requirement.manifestSchema) errors.push(`manifest schema ${provider.manifestSchema} is not ${requirement.manifestSchema}`);
+  for (const name of missing(requirement.api, provider.api)) errors.push(`api ${name} missing`);
+  for (const name of missing(requirement.bin, Object.keys(provider.bin))) errors.push(`bin ${name} missing`);
+  for (const name of missing(requirement.cli, provider.cli)) errors.push(`cli command ${name} missing`);
+  return errors;
+}
+
+// Reads what an installed (or built) package directory actually provides.
+export async function describeInstalled(dir) {
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+  const mod = await import(pathToFileURL(join(dir, pkg.exports['.'].import)).href);
+  const api = Object.keys(mod).sort();
+  const accepts = schemaNumber => {
+    try { mod.validateManifest({schema: schemaNumber, sources: [], items: []}); return true; } catch { return false; }
+  };
+  const manifestSchema = [1, 2].filter(accepts);
+  const usage = spawnSync(process.execPath, [join(dir, pkg.bin['hanamesh-provision']), 'help'], {env: {}, encoding: 'utf8'});
+  if (usage.status !== 0) throw new Error(`hanamesh-provision help exited ${usage.status}: ${usage.stderr}`);
+  const cli = [...usage.stdout.matchAll(/^ {2}hanamesh-provision (\w+)/gmu)].map(m => m[1]).sort();
+  return {
+    package: pkg.name,
+    version: pkg.version,
+    source: {git: providerFixture.source.git, tag: `v${pkg.version}`},
+    exports: Object.keys(pkg.exports).sort(),
+    bin: pkg.bin,
+    api,
+    cli,
+    manifestSchema: manifestSchema.length === 1 ? manifestSchema[0] : manifestSchema,
+    runtimeDependencies: Object.keys(pkg.dependencies ?? {}).length,
+  };
+}

package/node_modules/@hanamesh/lib-provision/contract/fixtures/consumer.json

@@ -0,0 +1,9 @@
+{
+  "package": "@hanamesh/lib-provision",
+  "range": "git+https://github.com/yzsnstotz/hanamesh-lib-provision.git#semver:^0.2.1",
+  "major": 0,
+  "api": ["isProvisionError", "plan", "platformKey", "provision", "remove", "validateManifest", "verify"],
+  "bin": ["hanamesh-provision"],
+  "cli": ["install", "plan", "platform", "remove", "verify"],
+  "manifestSchema": 1
+}

package/node_modules/@hanamesh/lib-provision/contract/fixtures/provider.json

@@ -0,0 +1,11 @@
+{
+  "package": "@hanamesh/lib-provision",
+  "version": "0.2.1",
+  "source": {"git": "git+https://github.com/yzsnstotz/hanamesh-lib-provision.git", "tag": "v0.2.1"},
+  "exports": [".", "./contract/*", "./package.json"],
+  "bin": {"hanamesh-provision": "bin/hanamesh-provision.js"},
+  "api": ["ProvisionError", "externalPath", "isInside", "isProvisionError", "ledger", "ledgerPath", "ownershipPath", "plan", "platformKey", "provision", "redactUrl", "remove", "safeEntrySegments", "safeLinkTarget", "stripVerbatimPrefix", "targetPath", "toVerbatimPath", "validateManifest", "verify"],
+  "cli": ["install", "plan", "platform", "remove", "verify"],
+  "manifestSchema": 1,
+  "runtimeDependencies": 0
+}

package/node_modules/@hanamesh/lib-provision/contract/lib-provision.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/yzsnstotz/hanamesh-lib-provision/contract/lib-provision.schema.json",
+  "title": "@hanamesh/lib-provision supply contract",
+  "description": "provider: what one released version actually ships. requirement: what a consumer needs. version is the package SemVer; manifestSchema is the provision manifest data format number and is never compared as SemVer.",
+  "$defs": {
+    "names": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
+    "provider": {
+      "type": "object",
+      "required": ["package", "version", "source", "exports", "bin", "api", "cli", "manifestSchema", "runtimeDependencies"],
+      "additionalProperties": false,
+      "properties": {
+        "package": {"const": "@hanamesh/lib-provision"},
+        "version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.]+)?$"},
+        "source": {
+          "type": "object",
+          "required": ["git", "tag"],
+          "additionalProperties": false,
+          "properties": {
+            "git": {"const": "git+https://github.com/yzsnstotz/hanamesh-lib-provision.git"},
+            "tag": {"type": "string", "pattern": "^v\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.]+)?$"}
+          }
+        },
+        "exports": {"$ref": "#/$defs/names"},
+        "bin": {"type": "object", "additionalProperties": {"type": "string"}},
+        "api": {"$ref": "#/$defs/names"},
+        "cli": {"$ref": "#/$defs/names"},
+        "manifestSchema": {"const": 1},
+        "runtimeDependencies": {"const": 0}
+      }
+    },
+    "requirement": {
+      "type": "object",
+      "required": ["package", "range", "major", "api", "bin", "cli", "manifestSchema"],
+      "additionalProperties": false,
+      "properties": {
+        "package": {"const": "@hanamesh/lib-provision"},
+        "range": {"type": "string", "pattern": "^git\\+https://github\\.com/yzsnstotz/hanamesh-lib-provision\\.git#semver:"},
+        "major": {"type": "integer", "minimum": 0},
+        "api": {"$ref": "#/$defs/names"},
+        "bin": {"$ref": "#/$defs/names"},
+        "cli": {"$ref": "#/$defs/names"},
+        "manifestSchema": {"const": 1}
+      }
+    }
+  }
+}

package/node_modules/@hanamesh/lib-provision/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hanamesh/lib-provision",
+  "version": "0.2.1",
+  "description": "Safely place a large file on the user's machine: source selection, resumable download, sha256, sandboxed extraction, atomic promotion, ledger.",
+  "private": false,
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=24.13.1 <25"
+  },
+  "bin": {
+    "hanamesh-provision": "bin/hanamesh-provision.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./contract/*": "./contract/*",
+    "./package.json": "./package.json"
+  },
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib/",
+    "bin/",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "consistency.json",
+    "contract/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "compile": "tsc -p tsconfig.json",
+    "pretest": "tsc -p tsconfig.json",
+    "test": "node --test --test-reporter=tap tests/*.test.mjs",
+    "test:types": "tsc -p tests/types/tsconfig.json",
+    "test:mutation": "node scripts/mutations.mjs",
+    "check:consistency": "node scripts/check-consistency.mjs",
+    "check:lib": "node scripts/check-lib.mjs",
+    "check": "hanamesh-devkit check-toolchain && hanamesh-devkit preflight && node scripts/check-consistency.mjs && node scripts/check-lib.mjs",
+    "verify:pack": "bash scripts/verify-artifact.sh",
+    "preflight": "hanamesh-devkit preflight"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "5.9.3",
+    "undici-types": "6.21.0",
+    "@hanamesh/devkit": "git+https://github.com/yzsnstotz/hanamesh-server-shared.git#semver:^0.2.0&path:/packages/devkit"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hanamesh/dsh-app-host",
-  "version": "0.2.0-rc.2",
-  "description": "HanaMesh application ownership, durable view leases, and application library for official DSH 0.2.0-rc.2",
+  "version": "0.6.14",
+  "description": "HanaMesh application ownership, durable view leases, and application library for official DSH 0.2.x",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -31,6 +31,23 @@
     "./client-ui": {
       "types": "./dist/client-ui.d.ts",
       "default": "./dist/client-ui.js"
+    },
+    "./install-target/suite": {
+      "types": "./dist/install-target/suite.d.ts",
+      "default": "./dist/install-target/suite.js"
+    },
+    "./install-target/schema.json": "./schemas/install-target.schema.json",
+    "./install-target/fixtures/*": "./dist/install-target/fixtures/*",
+    "./catalog/suite": {
+      "types": "./dist/catalog/suite.d.ts",
+      "default": "./dist/catalog/suite.js"
+    },
+    "./catalog/fixtures/*": "./dist/catalog/fixtures/*",
+    "./catalog/schema/manifest.json": "./schemas/catalog-source.schema.json",
+    "./catalog/schema/page.json": "./schemas/catalog-provider-page.schema.json",
+    "./installation-status": {
+      "types": "./dist/installation-status.d.ts",
+      "default": "./dist/installation-status.js"
     }
   },
   "files": [
@@ -46,18 +63,32 @@
     "docs/PROVENANCE.json",
     "docs/LICENSES.json",
     "schemas",
-    "profile"
+    "profile",
+    "docs/INSTALL_TARGET.md",
+    "docs/DSH_COMPATIBILITY.md",
+    "docs/INSTALLATION_STATUS.md"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
-    "test": "node --test --test-concurrency=1 tests/*.test.mjs",
-    "test:mutation": "node scripts/mutations.mjs",
+    "test": "node scripts/safe-git.mjs node --test --test-reporter=tap --test-concurrency=1 tests/*.test.mjs",
+    "test:contract": "pnpm run build && node --test --test-reporter=tap --test-concurrency=1 tests/install-target-contract.test.mjs tests/catalog-major-compat.test.mjs",
+    "test:mutation": "node scripts/safe-git.mjs node scripts/mutations.mjs",
     "test:types": "tsc --noEmit --strict --target ES2022 --module NodeNext --moduleResolution NodeNext tests/consumer.mts",
-    "check": "npm run build && npm run check:consistency && npm test && npm run test:mutation",
+    "test:native-driver": "node scripts/safe-git.mjs node --test --test-reporter=tap tests/native/driver.test.mjs",
+    "check": "node scripts/safe-git.mjs node scripts/check.mjs",
     "prepack": "npm run build",
     "demo": "node examples/demo.mjs",
     "preflight:dsh": "node scripts/preflight-dsh.mjs",
-    "check:consistency": "node scripts/check-consistency.mjs"
+    "check:consistency": "node scripts/check-consistency.mjs",
+    "check:toolchain": "node scripts/check-toolchain.mjs",
+    "preflight": "node scripts/preflight.mjs",
+    "verify:pack": "node scripts/safe-git.mjs node scripts/verify-package.mjs",
+    "check:devkit-supply": "node scripts/check-devkit-consumption.mjs",
+    "check:provision-supply": "node scripts/check-provision-consumption.mjs",
+    "install:safe": "node scripts/safe-git.mjs pnpm install --frozen-lockfile",
+    "release:check": "hanamesh-release check --lockfile pnpm-lock.yaml",
+    "release:publish": "hanamesh-release publish --lockfile pnpm-lock.yaml",
+    "prepublishOnly": "hanamesh-release source-guard"
   },
   "dsh": {
     "bundle": {
@@ -65,7 +96,7 @@
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-renderer",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-locale"
       ],
@@ -76,37 +107,54 @@
     }
   },
   "dependencies": {
-    "zod": "4.5.4"
+    "zod": "4.5.4",
+    "@hanamesh/lib-provision": "file:vendor/hanamesh-lib-provision-0.2.1.tgz",
+    "semver": "7.8.5"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-storage-domain": "0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "3.18.4",
-    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
-    "react": "18.3.1"
+    "@deepseek-ai/cordis": ">=4.0.4 <4.1.0-0 || >=4.0.5-alpha.1 <4.1.0-0",
+    "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "@deepseek-ai/schemastery": ">=3.18.4 <3.19.0-0 || >=3.18.5-alpha.1 <3.19.0-0",
+    "@deepseek-ai/dsh-host-webserver": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "@deepseek-ai/dsh-client-connection": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "react": "^18.3.1"
   },
   "hanamesh": {
     "module": "app-host",
     "contractVersion": 1,
-    "dshTarget": "0.2.0-rc.2",
-    "upstreamFilesModified": 0
+    "dshTarget": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0",
+    "upstreamFilesModified": 0,
+    "installTarget": {
+      "contract": "hanamesh.install-target",
+      "contractVersion": "1",
+      "supported": [
+        "1"
+      ],
+      "schema": "./schemas/install-target.schema.json"
+    }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-storage": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-storage-json": "0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "3.18.4",
-    "typescript": "5.8.3"
-  }
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-storage": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-storage-json": "0.2.1-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
+    "typescript": "5.8.3",
+    "@hanamesh/devkit": "file:vendor/hanamesh-devkit-0.2.3.tgz",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-alpha.2",
+    "@hanamesh/release-platform-gate": "file:vendor/hanamesh-release-platform-gate-0.1.9.tgz"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "bundleDependencies": [
+    "@hanamesh/lib-provision"
+  ]
 }