English

Recipe：文本资源闭包与宿主构建¶

1. 场景与非场景¶

适用：需要把一组文本资源归一成可复算的闭包，并据此在受收容处 materialize 一个宿主适配构建，且构建清单可全摘要复验。

不适用：需要把二进制资源纳入 adapter 投影（仅支持文本闭包）；需要 Kit CLI apply、通用或远端 apply、自动删除式 uninstall。

2. 架构选择及能力 ID¶

首选能力：foundation.harness.resource-closure（确定性闭包与 sha256 摘要）与 foundation.harness.host-adapter（adapter source closure / build / manifest 校验 / materialize / verifyPeerAdapterDirectories 只读同级验证）。

3. 前置条件与信任边界¶

adapter source 为已声明的文本闭包（content 只接受 string，utf8）。
信任边界：materialize 用 sibling staging + 单次 rename，目标已存在则拒绝；probe 默认不 spawn、不走 PATH。

4. 最小代码¶

import {
  computeResourceClosure,
  buildAdapterClosure,
  verifyAdapterBuildManifest,
  materializeAdapterBuild,
} from "skill-family-harness-node";

const closure = computeResourceClosure([
  { path: "skill.json", content: "{}" },
  { path: "readme.md", content: "# demo" },
]);
const built = buildAdapterClosure(closure);
verifyAdapterBuildManifest(built.manifest); // 全摘要复验
await materializeAdapterBuild(built, { outDir: "./out" }); // 受收容落盘

以上代码展示了先算闭包、再校验清单、最后原子 materialize 的顺序。

5. 预期输出与证据¶

computeResourceClosure 返回确定性闭包对象与 sha256 摘要；materializeAdapterBuild 在受收容目标写出产物。证据：packages/skill-family-harness-node/test/closure.test.mjs 与 test/host.test.mjs。

6. 安全/失败负例¶

// 负例：二进制 content 不支持 -> 校验/构建拒绝
buildAdapterClosure({ path: "x.bin", content: Buffer.from([0, 1, 2]) });
// 抛 HarnessError：adapter source content 仅支持 string (utf8)

清单摘要不符、目标已存在、非受信可执行文件也会抛错。

7. 可复制验证命令¶

node --test packages/skill-family-harness-node/test/closure.test.mjs \
           packages/skill-family-harness-node/test/host.test.mjs

8. 调用方继续拥有的业务逻辑¶

宿主具体业务语义。
宿主差异声明由 Profile + Kit host 子动作注入。

9. 升级与回滚注意事项¶

Harness 只负责构建和只读同级验证。包 API applyHostPlan 在 Kit 层支持已登记、摘要绑定的本地 install/update；执行 uninstall 计划不删除文件。Kit CLI apply、通用或远端 apply 仍稳定拒绝，Qoder 完整 driver 为 unsupported。
verifyPeerAdapterDirectories 只证明同级目录的闭包、字节和 logicalMappings 一致，不推导安装、发布或领域状态。
materialize 为原子 sibling + rename，失败时不影响既有目标；升级跟随 skill-family-harness-node 版本。