docs(migrations): files asset declaration + why the index cannot adopt it yet

[Sunrisepeak]

纯文档，不改任何 recipe。

为什么是文档而不是迁移

我原本要迁 openssl（B 类，独占目录，最安全的一个）。实测后停手了：

用 2026.7.27.0 之前的二进制跑一个声明 type="files" 的 fixture：

  error: unsupported registration node kind 'files'
         code:     xvm-node-payload-invalid
         field:    /nodes/3/kind
         nothing was changed

索引由所有版本的客户端共用，而 xim-pkgindex 没有 min_xlings 之类的客户端版本下限 —— 没有办法给老客户端发老 recipe。

今天迁任何一个 recipe，等于让每一个还没升级的用户装不上这个包。

所以本 PR 只落文档，并把放行条件写死：xlings 发布并经过采纳周期 → 索引引入版本下限（或明确弃用低版本）→ 逐包迁移并在隔离 HOME 实测。

文档内容

• 新能力 type = "files" 的用法与两端必须相对的硬约束（payload 跨 subos 共享 + 引用计数）
• dst 白名单：usr/ etc/ share/；拒绝绝对路径、../、bin/、lib/
• 兼容性闸门（§2，最重要）
• 28 个待迁 recipe 按风险分 A–G，附 openssl 的完整 diff 示例
• 明确不管的：subos 外的 desktop entry / 字体 / pmwrapper

一处更正

文档里更正了我先前的一个说法：glibc 的 skip-if-exists 不是为了"host 头文件优先"。

sysroot.install_headers 的目标是 <subos>/usr/include，而 sandbox 把 host 的 /usr 挂在 /usr —— 两个不同目录，host 从不往前者放东西；gcc 又注入 --sysroot=<subos>，只看前者。真正起作用的是包与包之间的碰撞。

结论不变（glibc 仍是最后迁），但理由变了：不是 host 优先，而是缺跨包冲突策略。

上游

• feat(xpkg): files assets (src/dst) and injected args — 0.0.47 libxpkg#31（0.0.47）
• feat(xpkg): publish 0.0.47 mcpplibs/mcpp-index#128（已合并，artifact 已发布）
• fix(xvm): 0.4.70 — libraries follow the release, and the sysroot stops mixing versions xlings#410