npm 依賴政策

套件支援是准入控管的平台功能，不是提交或部署時的 npm install。提交永遠不會向 registry 解析套件；builder 從平台映像檔內預先安裝的套件打包。

目錄

edge/department-workers/scripts/dependency-catalog.mjs 是 builder 與 CLI 共同的唯一事實來源。新增套件是一次平台映像檔／目錄變更，需經 license、integrity、runtime 與安全審查。目前目錄恰好一個套件：

zod 4.3.6
  integrity  sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==
  resolved   https://registry.npmjs.org/zod/-/zod-4.3.6.tgz
  license    MIT

zod 另外做了 jitless 釘定：三個核心檔案被原始碼轉換為對動態程式碼生成直接丟例外，各自以 SHA-256 釘死 — 安裝的套件有任何漂移都會 fail-closed（approved_dependency_unavailable，可重試的平台錯誤，不是租戶錯誤）。

專案可以宣告什麼

• package.json：鍵 ⊆ {name, version, private, type, dependencies}；private: true；type: "module"；≤10 個依賴，每個都必須是精確核可版本；禁止 packageManager。name／version 必須等於 module.name／module.version。
• package-lock.json：lockfileVersion: 3（數字）、requires: true；套件圖必須恰為根項目加上每個宣告依賴一筆 node_modules/<dep>；每筆的 version、resolved、integrity、license 必須與目錄逐位元組相等。
• 匯入：只有靜態 ESM。沒有 semver range、alias、Git/URL/file/workspace/private 依賴、lifecycle 或 install script、原生模組、Wasm、動態 import()、require、使用者建置指令或外掛。壓縮檔裡不得有 node_modules。

專案無法選擇 Node、npm、esbuild、compatibility flag 或其他套件管理器 — 那些屬於 builderPolicy（目前為 department-worker-project-v2.10；依賴目錄本身自後端 5.10.11 起沒有改變），並被釘進每份建置回執。政策版本也決定 release 擁有哪些執行期功能（能力表）。

三層驗證

1. package.json 版本對目錄。
2. package-lock.json 的 resolved + integrity + license 對目錄。
3. builder 映像檔裡實際安裝的套件：node_modules/<name> 經 realpath 解析，其 package.json.version 必須等於核可版本。

目錄沒有的一律 fail-closed（package_dependency_not_approved／source_dependency_not_approved）。打包時 esbuild 的 metafile 會被稽核：每個輸入必須是生成的 entry、專案虛擬模組、或真正通過政策 loader 的核可套件檔案 — 不存在繞過路徑。

builder 映像檔契約

基底映像 node:22.23.2-bullseye（digest 釘死）、npm ci --omit=dev 搭配 NPM_CONFIG_IGNORE_SCRIPTS=true、builder 根目錄 /opt/teamsync/edge-worker-builder。只有 node、node_modules 與 scripts 從 builder stage 被複製進 runtime 映像 — npm 本身刻意不存在於 runtime，所以請求時解析根本不可能。API 映像的 builder stage 另外複製 CLI 與範本打包腳本以及兩份專案範本，並執行範本打包程式；它的 runtime stage 也會收到生成的範本目錄（/opt/teamsync/edge-worker-starters，由範本與原始碼下載提供）。兩個背景 worker 映像維持較早、不含範本的 builder stage，因此三個生產 Dockerfile 的 builder stage 不再逐位元組相同。