兼容性检查

兼容性检查将已发布清单与显式的宿主描述进行比较，不导入实现模块，也不安装任何内容。在加载已安装或已解包的插件前运行它。

描述宿主

保存预检文件，例如 graft.check.json：

{
  "host": {
    "node": "22.22.0",
    "effect": "4.1.2",
    "graft": "0.0.0",
    "placement": "Worker",
    "filesystem": true,
    "nativeModules": false,
    "services": [],
    "operations": []
  },
  "entries": [
    {
      "id": "forecasts",
      "directory": "./node_modules/@acme/forecast",
      "entry": "."
    }
  ],
  "catalog": []
}

字段	含义
host	所选部署宿主的实际运行时版本和能力。
host.services	宿主提供的服务组，格式为 { "key": "service/key", "operations": ["read@1"] }，键必须与实际 Context 键一致。
host.operations	宿主提供的契约操作记录，格式与清单中的 operations 相同。
entries	一起启用的条目，包含实例 id、包目录和公开入口。
catalog	可供建议的其他包。列在这里不等于启用。
路径	相对于此预检文件，包括 catalog 中的路径。

host.services 中每个操作都必须在 host.operations 中有对应记录，包含契约包名、版本和 Artifact 目录摘要。即使没有已选择条目使用它，缺失记录仍产生 InvalidManifest，指出宿主服务和操作。宿主与包记录参与同一来源冲突检查。

入口名称使用 . 或具体的 ./subpath 导出。配置拒绝裸名称、空路径段、点路径段、目录跳转和通配符。缺失入口返回 MissingEntry；继承的对象属性不算入口。

运行检查

graft --no-plugins check graft.check.json

--no-plugins 还会跳过命令插件发现。存在任何诊断时，命令以非零状态退出。嵌入式应用可用 Manifest.check 运行同一个纯检查。文件描述平面部署，不表示 Loader realm 可见性或依赖启动顺序。它不改写 graft.yml，也不改变 graft add 和 graft start；在部署脚本中显式先运行预检。

诊断	操作
MissingEntry	选择包清单中列出的公开入口。
MissingOperation	启用提供指定服务及其完整操作集的单个包。消息指出需要它的条目，并从 catalog 中建议匹配的包。
ProvenanceConflict	同一操作来自不同契约包名或不同目录摘要。诊断列出双方来源；选择同一包的同一摘要。
Runtime	使用满足包版本范围的 Node、Effect 和 Graft，或选择其他插件版本。
Placement	选择受支持且具备所需文件系统或原生模块能力的位置。
InvalidManifest	使用 graft remote manifest 重新生成包元数据，或在 host.operations 中补齐诊断所指宿主服务的来源记录。

同一契约包名与同一目录摘要永远不会冲突，即使多个条目或导出声明同一操作。这是来源检查，不比较 schema 定义。

每个必需服务必须由宿主或其他已选择条目中的单个提供者满足，Context 键相同且包含所有必需操作身份。不能组合不同服务或不完整提供者的操作来满足需求。可选服务不阻止启动。不同操作版本不能替代请求的版本。包版本用于运行时需求和来源记录，不能替代操作兼容性。

检查通过以元数据真实且宿主清单准确为前提，不证明探针、外部连接、任意业务语义或原生代码安全。发布前验证清单并运行一致性测试。信任和授权仍由运维策略决定。