相容性檢查

相容性檢查將已發布清單與明確的宿主描述進行比較，不匯入實作模組，也不安裝任何內容。在載入已安裝或已解包的外掛前執行它。

描述宿主

儲存預檢檔，例如 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 鍵相同且包含所有必要操作身分。不能組合不同服務或不完整提供者的操作來滿足需求。選用服務不阻止啟動。不同操作版本不能替代請求的版本。套件版本用於執行環境需求與來源記錄，不能替代操作相容性。

檢查通過以中繼資料真實且宿主清單準確為前提，不證明探針、外部連線、任意業務語意或原生程式碼安全。發布前驗證清單並執行一致性測試。信任與授權仍由維運策略決定。