@synopackageland/cli 0.3.10 → 0.4.0

package/dist/error-registry.js

@@ -1,866 +1,814 @@
 export const ERROR_REGISTRY = {
-    // --- Contract Validation ---
-    CONTRACT_SCHEMA_UNSUPPORTED: {
-        code: "CONTRACT_SCHEMA_UNSUPPORTED",
-        description: "synology-app.yaml 的 schema 版本不受支援。",
-        suggestion: "請將 synology-app.yaml 的 schema 欄位設為 1。",
-    },
-    CONTRACT_MISSING_FIELD: {
-        code: "CONTRACT_MISSING_FIELD",
-        description: "synology-app.yaml 缺少必填欄位。",
-        suggestion: "請在 synology-app.yaml 補上缺少的必填欄位（例如 package, version, displayname 等）。",
-    },
-    CONTRACT_SCHEMA_INVALID: {
-        code: "CONTRACT_SCHEMA_INVALID",
-        description: "synology-app.yaml 格式與 JSON Schema 規格不符。",
-        suggestion: "請修正 synology-app.yaml 的欄位格式以符合規範。",
-    },
-    PACKAGE_IDENTITY_TOO_LONG: {
-        code: "PACKAGE_IDENTITY_TOO_LONG",
-        description: "Package Identity 超過長度上限（正式身分上限 28 字元，最終身分上限 32 字元）。",
-        suggestion: "請縮短 synology-app.yaml 中的 package 名稱（正式身分至多 28 字元，以保留 4 字元供 .dev 開發後綴使用）。",
-    },
-    CONTRACT_PACKAGE_TOO_LONG: {
-        code: "CONTRACT_PACKAGE_TOO_LONG",
-        description: "Package Identity 超過 DSM 上限 32 字元。",
-        suggestion: "請縮短 synology-app.yaml 中的 package 名稱至 32 字元以內。",
-    },
-    CONTRACT_ADMINPORT_INVALID: {
-        code: "CONTRACT_ADMINPORT_INVALID",
-        description: "adminport 必須是整數。",
-        suggestion: "請在 synology-app.yaml 提供與 Compose published port 對應的整數 adminport。",
-    },
-    CONTRACT_ADMINPORT_UNMAPPED: {
-        code: "CONTRACT_ADMINPORT_UNMAPPED",
-        description: "adminport 未在 Compose ports 宣告中對應到容器 port。",
-        suggestion: "請在 compose.yaml 的 ports 區塊宣告與 adminport 對應的連接埠映射（例如 \"8080:80\"）。",
-    },
-    CONTRACT_LAUNCH_INVALID: {
-        code: "CONTRACT_LAUNCH_INVALID",
-        description: "integration.web.launch 模式無效。",
-        suggestion: "請改為 dsm-window（DSM 視窗，預設）或 new-page（新分頁），Headless App 請省略此欄位。",
-    },
-    CONTRACT_LAUNCH_REQUIRES_WEB: {
-        code: "CONTRACT_LAUNCH_REQUIRES_WEB",
-        description: "Headless App 不需要宣告 Web Launch Mode。",
-        suggestion: "請省略 integration.web.launch，或補上對應 Compose published port 的 adminport。",
-    },
-    CONTRACT_INVALID_STRING: {
-        code: "CONTRACT_INVALID_STRING",
-        description: "合約字串含有不允許的控制字元或未允許的插值語法。",
-        suggestion: "請移除控制字元與 ${ 插值語法，安裝參數請在 install 區塊宣告。",
-    },
-    CONTRACT_DSM_USER_DUPLICATE: {
-        code: "CONTRACT_DSM_USER_DUPLICATE",
-        description: "每顆 App 至多宣告一個 dsm_user 安裝參數。",
-        suggestion: "請在 synology-app.yaml 只保留一個 Container Run-as 參數。",
-    },
-    INSTALL_STRING_TOO_LONG: {
-        code: "INSTALL_STRING_TOO_LONG",
-        description: "Install Parameter 字串預設值超過 256 字元。",
-        suggestion: "請縮短 synology-app.yaml 中 install 參數的預設字串長度。",
-    },
-    INSTALL_STRING_INVALID: {
-        code: "INSTALL_STRING_INVALID",
-        description: "Install Parameter 字串值含有不合法字元或插值。",
-        suggestion: "請移除 install 參數預設值中的控制字元與 ${ 插值語法。",
-    },
-    INSTALL_PARAMETER_UNREFERENCED: {
-        code: "INSTALL_PARAMETER_UNREFERENCED",
-        description: "install 宣告的參數未在 Compose 中被引用。",
-        suggestion: "請在 compose.yaml 以 ${參數名稱} 引用該參數，或從 synology-app.yaml 移除未使用的宣告。",
-    },
-    INSTALL_DSM_USER_UNREFERENCED: {
-        code: "INSTALL_DSM_USER_UNREFERENCED",
-        description: "dsm_user 參數未在 Compose 中完整引用 UID 與 GID。",
-        suggestion: "請在 compose.yaml 將容器 user 或 PUID/PGID 設為 ${NAME_UID}:${NAME_GID}。",
-    },
-    CONTRACT_HOMES_PATH_FORBIDDEN: {
-        code: "CONTRACT_HOMES_PATH_FORBIDDEN",
-        description: "homes Install Parameter 不得在契約中寫入 NAS 實體路徑或預設值。",
-        suggestion: "請只宣告 type: homes 並在 Compose 引用該參數，由 glue／Broker 在安裝時解析這台 NAS 的 User Home 路徑。",
-    },
-    CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN: {
-        code: "CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN",
-        description: "POSIX all-shares 參數不得在契約中指定 default 或 NAS 實體路徑。",
-        suggestion: "請只宣告 type: posix_all_shares，讓 wizard／CLI 在安裝時取得當下的 Share snapshot。",
-    },
-    DSM_USER_REQUIRED: {
-        code: "DSM_USER_REQUIRED",
-        description: "有 Shared Folder 時必須宣告恰好一個 dsm_user 作為 Container Run-as。",
-        suggestion: "請在 synology-app.yaml 新增 install.<NAME>.type: dsm_user，並在 Compose 引用 ${NAME_UID}:${NAME_GID}。",
-    },
-    // --- Compose / Security Validation ---
-    PROJECT_RUNTIME_EXCLUSIVE: {
-        code: "PROJECT_RUNTIME_EXCLUSIVE",
-        description: "專案同時存在 compose.yaml 與 native.yaml，兩者互斥。",
-        suggestion: "請選擇使用 compose.yaml（容器 App）或 native.yaml（原生 App），並刪除另一個檔案。",
-    },
-    COMPOSE_MISSING: {
-        code: "COMPOSE_MISSING",
-        description: "找不到 compose.yaml 或 native.yaml。",
-        suggestion: "請在專案根目錄建立 compose.yaml 或 native.yaml。",
-    },
-    COMPOSE_SERVICE_NOT_FOUND: {
-        code: "COMPOSE_SERVICE_NOT_FOUND",
-        description: "depends_on 引用的服務不存在於 compose.yaml 中。",
-        suggestion: "請修正 compose.yaml 中的 depends_on，指向正確已定義的 service 名稱。",
-    },
-    COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN: {
-        code: "COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN",
-        description: "會走 DSM Docker Project resource worker 的 Compose command/entrypoint 陣列含純數字字串，可能在 worker YAML round-trip 後變成整數而無法 acquire。",
-        suggestion: "請把整個命令包成單一字串，例如 command: [\"sh\", \"-c\", \"httpd -f -p 8080 -h /srv\"]，或與 flag 併寫成 \"-p8080\"。",
-    },
-    COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED: {
-        code: "COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED",
-        description: "Compose dynamic route 超出 D1/D2 白名單，或使用 DSM worker 不會載入的 secret/config 來源。",
-        suggestion: "請只使用 string/boolean wizard answer 的 ${NAME} interpolation；secret/config 因 DSM worker 不讀 docker-compose.override.yml 而拒收。",
-    },
-    COMPOSE_LEGACY_BROKER_STATE_PRESENT: {
-        code: "COMPOSE_LEGACY_BROKER_STATE_PRESENT",
-        description: "偵測到既有 Broker installer App Data，dynamic package-only route 不支援同一 Package Identity 的就地遷移。",
-        suggestion: "請改用新的 Package Identity 安裝，或先完整卸載舊套件並清除 App Data。",
-    },
-    COMPOSE_BUILD_FORBIDDEN: {
-        code: "COMPOSE_BUILD_FORBIDDEN",
-        description: "D0 Compose route 禁止在 NAS install-time 使用 build:；build capability 永久拒收。",
-        suggestion: "請移除 build:，改用已存在的 image（最好使用 image@sha256:... 固定 digest），再重新執行 validate。",
-    },
-    COMPOSE_SOCKET_MOUNT_FORBIDDEN: {
-        code: "COMPOSE_SOCKET_MOUNT_FORBIDDEN",
-        description: "嚴禁掛載 Docker Socket 或系統敏感 Socket。",
-        suggestion: "請從 compose.yaml 移除 docker.sock 掛載；如需存取檔案請改用 shared_folder 或 File Gateway。",
-    },
-    COMPOSE_BIND_SOURCE_FORBIDDEN: {
-        code: "COMPOSE_BIND_SOURCE_FORBIDDEN",
-        description: "掛載來源路徑不合法或屬於受保護的系統路徑。",
-        suggestion: "請使用受控的 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR} 或已宣告的 ${SHARED_FOLDER} 槽位。",
-    },
-    COMPOSE_BIND_SOURCE_UNDECLARED: {
-        code: "COMPOSE_BIND_SOURCE_UNDECLARED",
-        description: "Volume 掛載使用了未宣告的 Shared Folder 變數。",
-        suggestion: "請先在 synology-app.yaml 的 install 區塊宣告該 shared_folder 參數。",
-    },
-    COMPOSE_BIND_SUFFIX_INVALID: {
-        code: "COMPOSE_BIND_SUFFIX_INVALID",
-        description: "Shared Folder 子路徑格式不合法（含有 .. 或控制字元）。",
-        suggestion: "請改用合法的相對子路徑，例如 ${MEDIA_SHARE}/data:/data。",
-    },
-    COMPOSE_POSIX_ALL_SHARES_UNDECLARED: {
-        code: "COMPOSE_POSIX_ALL_SHARES_UNDECLARED",
-        description: "Compose 使用了未宣告的 POSIX all-shares marker。",
-        suggestion: "請宣告 type: posix_all_shares，讓 package-only wizard／CLI 取得安裝當下的 Share snapshot。",
-    },
-    COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN: {
-        code: "COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN",
-        description: "POSIX all-shares marker 不得附加 Share 子路徑。",
-        suggestion: "請只使用完整的 ${ALL_SHARES} source；每個 Share 的 container target 由 package-only preinst 展開。",
-    },
-    COMPOSE_HOST_BIND_FORBIDDEN: {
-        code: "COMPOSE_HOST_BIND_FORBIDDEN",
-        description: "禁止直接硬編碼本機路徑（例如 /volume1/... 或 ./）。",
-        suggestion: "請在 synology-app.yaml 宣告 shared_folder 參數，並在 Compose 改用 ${SLOT} 引用。",
-    },
-    COMPOSE_NAMED_VOLUME_UNDECLARED: {
-        code: "COMPOSE_NAMED_VOLUME_UNDECLARED",
-        description: "服務使用了未在頂層 volumes 宣告的 Named Volume。",
-        suggestion: "請在 compose.yaml 頂層 volumes 區塊補上該 Volume 宣告，或改用受控目錄。",
-    },
-    COMPOSE_USER_ROOT_FORBIDDEN: {
-        code: "COMPOSE_USER_ROOT_FORBIDDEN",
-        description: "容器以 root (0:0) 執行，違反最小權限原則。",
-        suggestion: "請在 synology-app.yaml 宣告 dsm_user 並在 Compose 使用 ${USER_UID}:${USER_GID}。",
-    },
-    COMPOSE_USER_CONFLICTS_DSM_USER: {
-        code: "COMPOSE_USER_CONFLICTS_DSM_USER",
-        description: "Compose 服務自定義了 user 欄位，與 contract 宣告的 dsm_user 衝突。",
-        suggestion: "請移除 Compose 中的 user 欄位，交由 dsm_user 自動注入 ${NAME_UID}:${NAME_GID} 與 group_add。",
-    },
-    COMPOSE_USER_NUMERIC_FORBIDDEN: {
-        code: "COMPOSE_USER_NUMERIC_FORBIDDEN",
-        description: "禁止在 compose.yaml 硬編碼數字 uid:gid。",
-        suggestion: "請在 synology-app.yaml 宣告 dsm_user，並在 Compose 引用 ${NAME_UID}:${NAME_GID}。",
-    },
-    COMPOSE_PRIVILEGED_FORBIDDEN: {
-        code: "COMPOSE_PRIVILEGED_FORBIDDEN",
-        description: "使用了 privileged: true 但未在合約宣告。",
-        suggestion: "請在 synology-app.yaml 加上 privilege.privileged: true，或移除 privileged: true。",
-    },
-    COMPOSE_HOST_NETWORK_FORBIDDEN: {
-        code: "COMPOSE_HOST_NETWORK_FORBIDDEN",
-        description: "使用了 host network 模式但未在合約宣告。",
-        suggestion: "請在 synology-app.yaml 加上 privilege.host_network: true，或改用受控網路模式。",
-    },
-    COMPOSE_HOST_PID_FORBIDDEN: {
-        code: "COMPOSE_HOST_PID_FORBIDDEN",
-        description: "使用了 pid: host 但未在合約宣告。",
-        suggestion: "請在 synology-app.yaml 加上 privilege.host_pid: true，或移除 pid: host。",
-    },
-    COMPOSE_HOST_IPC_FORBIDDEN: {
-        code: "COMPOSE_HOST_IPC_FORBIDDEN",
-        description: "使用了 ipc: host 但未在合約宣告。",
-        suggestion: "請在 synology-app.yaml 加上 privilege.host_ipc: true，或移除 ipc: host。",
-    },
-    COMPOSE_DEVICES_FORBIDDEN: {
-        code: "COMPOSE_DEVICES_FORBIDDEN",
-        description: "使用了 devices 裝置存取但未在合約宣告。",
-        suggestion: "請在 synology-app.yaml 加上 privilege.devices: true，或移除 devices 區塊。",
-    },
-    COMPOSE_CAP_ADD_FORBIDDEN: {
-        code: "COMPOSE_CAP_ADD_FORBIDDEN",
-        description: "使用了 cap_add 權限提升但未在合約宣告。",
-        suggestion: "請在 synology-app.yaml 加上 privilege.cap_add: true，或移除 cap_add 區塊。",
-    },
-    COMPOSE_ENV_MISSING: {
-        code: "COMPOSE_ENV_MISSING",
-        description: "專案缺少必要的環境變數目錄結構。",
-        suggestion: "請確認 SYNOPKG_PKGVAR 與 secrets 目錄已正確建立。",
-    },
-    COMPOSE_NOT_HEALTHY: {
-        code: "COMPOSE_NOT_HEALTHY",
-        description: "Compose 服務未能於時限內通過 healthcheck 達到 healthy 狀態。",
-        suggestion: "請檢查容器健康檢查設定與應用程式日誌：synopkgland log --host <nas>。",
-    },
-    COMPOSE_NOT_RUNNING: {
-        code: "COMPOSE_NOT_RUNNING",
-        description: "Compose 服務未能於時限內維持 running 狀態。",
-        suggestion: "請檢查容器啟動腳本與日誌以排除崩潰原因：synopkgland log --host <nas>。",
-    },
-    // --- Native Validation / Payload ---
-    NATIVE_LOAD_FAILED: {
-        code: "NATIVE_LOAD_FAILED",
-        description: "無法讀取或解析 native.yaml。",
-        suggestion: "請確認 native.yaml 存在且為合法 YAML 格式。",
-    },
-    NATIVE_SCHEMA_INVALID: {
-        code: "NATIVE_SCHEMA_INVALID",
-        description: "native.yaml schema 版本無效（必須為整數 1）。",
-        suggestion: "請在 native.yaml 設定 schema: 1。",
-    },
-    NATIVE_TARGETS_REQUIRED: {
-        code: "NATIVE_TARGETS_REQUIRED",
-        description: "native.yaml 缺少 targets 區塊。",
-        suggestion: "請在 native.yaml 宣告 targets 區塊並指定 x86_64 或 aarch64 目標。",
-    },
-    NATIVE_TARGETS_EMPTY: {
-        code: "NATIVE_TARGETS_EMPTY",
-        description: "native.yaml 中的 targets 區塊不可為空。",
-        suggestion: "請在 native.yaml 的 targets 內至少定義一個架構目標（x86_64 或 aarch64）。",
-    },
-    NATIVE_ARCH_UNKNOWN: {
-        code: "NATIVE_ARCH_UNKNOWN",
-        description: "native.yaml 定義了不受支援的架構目標名稱。",
-        suggestion: "目標架構名稱僅支援 x86_64 與 aarch64。",
-    },
-    NATIVE_TARGET_INVALID: {
-        code: "NATIVE_TARGET_INVALID",
-        description: "native.yaml 目標架構定義無效。",
-        suggestion: "每個目標架構必須包含 path 或 url 下載來源設定。",
-    },
-    NATIVE_TARGET_NOT_DECLARED: {
-        code: "NATIVE_TARGET_NOT_DECLARED",
-        description: "欲建置或部署的架構目標未在 native.yaml 中宣告。",
-        suggestion: "請在 native.yaml 的 targets 補上該架構目標，或透過 --arch 指定已宣告的目標。",
-    },
-    NATIVE_TARGET_SOURCE_EXCLUSIVE: {
-        code: "NATIVE_TARGET_SOURCE_EXCLUSIVE",
-        description: "目標架構不可同時包含 path 與 url，兩者互斥。",
-        suggestion: "請在該目標架構中只保留 path（本機）或 url（遠端二進位檔）。",
-    },
-    NATIVE_PATH_FORBIDDEN_IN_LISTING: {
-        code: "NATIVE_PATH_FORBIDDEN_IN_LISTING",
-        description: "公開上架審查禁止使用本機 path 來源的 native 目標。",
-        suggestion: "請將 target 改為公開可下載的 url 並附帶 sha256 校驗碼。",
-    },
-    NATIVE_SHA256_REQUIRED_IN_LISTING: {
-        code: "NATIVE_SHA256_REQUIRED_IN_LISTING",
-        description: "公開上架審查要求 url 目標必須提供 sha256 校驗碼。",
-        suggestion: "請在 native.yaml 的 url 目標補上 64 位十六進位 sha256 欄位。",
-    },
-    NATIVE_SHA256_INVALID: {
-        code: "NATIVE_SHA256_INVALID",
-        description: "sha256 校驗碼格式無效。",
-        suggestion: "請提供恰好 64 字元的十六進位 SHA-256 字串。",
-    },
-    NATIVE_STRIP_COMPONENTS_INVALID: {
-        code: "NATIVE_STRIP_COMPONENTS_INVALID",
-        description: "strip_components 必須是非負整數。",
-        suggestion: "請在 native.yaml 將 strip_components 設為大於等於 0 的整數。",
-    },
-    NATIVE_SERVICE_REQUIRED: {
-        code: "NATIVE_SERVICE_REQUIRED",
-        description: "native.yaml 缺少 service 區塊。",
-        suggestion: "請在 native.yaml 補上 service 區塊並宣告 exec 與 args/env。",
-    },
-    NATIVE_SERVICE_USER_FORBIDDEN: {
-        code: "NATIVE_SERVICE_USER_FORBIDDEN",
-        description: "native service 不允許自訂 user 欄位（固定以 package 使用者執行）。",
-        suggestion: "請從 native.yaml 的 service 區塊移除 user 欄位。",
-    },
-    NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN: {
-        code: "NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN",
-        description: "禁止在 native service 使用 command/shell 等字串欄位以免 shell injection。",
-        suggestion: "請改用 exec（路徑）與 args（字串陣列）方式宣告啟動指令。",
-    },
-    NATIVE_EXEC_REQUIRED: {
-        code: "NATIVE_EXEC_REQUIRED",
-        description: "native service 缺少 exec 執行檔路徑。",
-        suggestion: "請在 native.yaml 的 service 區塊指定 exec: <相對路徑>。",
-    },
-    NATIVE_EXEC_INVALID_PATH: {
-        code: "NATIVE_EXEC_INVALID_PATH",
-        description: "exec 必須是相對路徑，且不可包含 .. 或絕對路徑。",
-        suggestion: "請指定相對於安裝根目錄的合法相對路徑，例如 exec: bin/app。",
-    },
-    NATIVE_ARGS_INVALID: {
-        code: "NATIVE_ARGS_INVALID",
-        description: "service.args 必須是字串陣列。",
-        suggestion: "請在 native.yaml 將 args 宣告為字串列表格式（例如 args: [\"--port\", \"8080\"]）。",
-    },
-    NATIVE_ENV_INVALID: {
-        code: "NATIVE_ENV_INVALID",
-        description: "service.env 必須是 key-value 字串映射表。",
-        suggestion: "請將 env 宣告為字典物件且每個值皆為字串。",
-    },
-    NATIVE_PKGVAR_REQUIRED: {
-        code: "NATIVE_PKGVAR_REQUIRED",
-        description: "原生二進位 App 必須在 args 或 env 中引用 ${SYNOPKG_PKGVAR} 以指定資料路徑。",
-        suggestion: "請在 native.yaml 的 service.args 或 service.env 加入 ${SYNOPKG_PKGVAR} 參數。",
-    },
-    NATIVE_ARCH_FAMILY_REQUIRED: {
-        code: "NATIVE_ARCH_FAMILY_REQUIRED",
-        description: "建置原生 SPK 時缺少目標架構家族（x86_64 或 aarch64）。",
-        suggestion: "請在指令加上 --arch x86_64 或 --arch aarch64。",
-    },
-    NATIVE_ARCH_UNDETERMINED: {
-        code: "NATIVE_ARCH_UNDETERMINED",
-        description: "無法從目標 NAS 的 CPU 資訊自動判定架構家族。",
-        suggestion: "請使用 --arch x86_64 或 --arch aarch64 明確指定目標架構。",
-    },
-    NATIVE_PAYLOAD_BUNDLE_COLLISION: {
-        code: "NATIVE_PAYLOAD_BUNDLE_COLLISION",
-        description: "原生 payload 解壓縮內容與 App Bundle 核心保留檔衝突。",
-        suggestion: "請檢查 payload 內容，避免在根目錄覆蓋 synology-app.yaml 或 native.yaml。",
-    },
-    NATIVE_PAYLOAD_DOWNLOAD_FAILED: {
-        code: "NATIVE_PAYLOAD_DOWNLOAD_FAILED",
-        description: "下載原生二進位檔 payload 失敗。",
-        suggestion: "請檢查 native.yaml 中的 url 是否有效且網路連線正常。",
-    },
-    NATIVE_PAYLOAD_DOWNLOAD_INVALID: {
-        code: "NATIVE_PAYLOAD_DOWNLOAD_INVALID",
-        description: "下載的原生 payload 回傳內容無效。",
-        suggestion: "請確認目標 URL 回傳了有效的二進位檔案內容。",
-    },
-    NATIVE_PAYLOAD_DUPLICATE_ENTRY: {
-        code: "NATIVE_PAYLOAD_DUPLICATE_ENTRY",
-        description: "原生 payload 壓縮檔內包含重複的檔案路徑。",
-        suggestion: "請重新打包原始檔案，確保壓縮檔內無重複 entry。",
-    },
-    NATIVE_PAYLOAD_ERROR: {
-        code: "NATIVE_PAYLOAD_ERROR",
-        description: "處理原生二進位 payload 時發生未預期錯誤。",
-        suggestion: "請檢查 payload 壓縮檔完整性或重新建置 SPK。",
-    },
-    NATIVE_PAYLOAD_EXTRACTION_FAILED: {
-        code: "NATIVE_PAYLOAD_EXTRACTION_FAILED",
-        description: "解壓縮原生二進位 payload 失敗。",
-        suggestion: "請確認壓縮檔格式正確無損壞，且支援 tar.gz / tar.xz / zip。",
-    },
-    NATIVE_PAYLOAD_INVALID_HARDLINK: {
-        code: "NATIVE_PAYLOAD_INVALID_HARDLINK",
-        description: "原生 payload 含有無效或循環的 hardlink。",
-        suggestion: "請移除壓縮檔中不合法的 hardlink 後重新打包。",
-    },
-    NATIVE_PAYLOAD_INVALID_STRIP_COMPONENTS: {
-        code: "NATIVE_PAYLOAD_INVALID_STRIP_COMPONENTS",
-        description: "strip_components 設定超過了壓縮檔目錄層級深度。",
-        suggestion: "請在 native.yaml 調整或減少 strip_components 數值。",
-    },
-    NATIVE_PAYLOAD_INVALID_SYMLINK: {
-        code: "NATIVE_PAYLOAD_INVALID_SYMLINK",
-        description: "原生 payload 含有無效的符號連結。",
-        suggestion: "請檢查壓縮檔內的 symlink 目標是否存在且合法。",
-    },
-    NATIVE_PAYLOAD_INVALID_ZIP: {
-        code: "NATIVE_PAYLOAD_INVALID_ZIP",
-        description: "ZIP 壓縮檔格式無效或已損壞。",
-        suggestion: "請檢查 zip 檔案完整性或重新打包。",
-    },
-    NATIVE_PAYLOAD_SHA256_MISMATCH: {
-        code: "NATIVE_PAYLOAD_SHA256_MISMATCH",
-        description: "下載的 payload SHA-256 校驗碼與 native.yaml 宣告不符。",
-        suggestion: "請更新 native.yaml 中的 sha256 欄位以符合實際檔案雜湊。",
-    },
-    NATIVE_PAYLOAD_SOURCE_AMBIGUOUS: {
-        code: "NATIVE_PAYLOAD_SOURCE_AMBIGUOUS",
-        description: "目標架構同時宣告了 path 與 url，來源衝突。",
-        suggestion: "請在該目標架構中只保留 path 或 url 其中一種來源。",
-    },
-    NATIVE_PAYLOAD_SOURCE_REQUIRED: {
-        code: "NATIVE_PAYLOAD_SOURCE_REQUIRED",
-        description: "目標架構缺少 path 或 url 來源設定。",
-        suggestion: "請在 native.yaml 的 targets 內為各架構補上 path 或 url。",
-    },
-    NATIVE_PAYLOAD_SYMLINK_CYCLE: {
-        code: "NATIVE_PAYLOAD_SYMLINK_CYCLE",
-        description: "原生 payload 包含循環符號連結 (Symlink cycle)。",
-        suggestion: "請移除壓縮檔中的循環 symlink。",
-    },
-    NATIVE_PAYLOAD_UNSAFE_HARDLINK: {
-        code: "NATIVE_PAYLOAD_UNSAFE_HARDLINK",
-        description: "原生 payload hardlink 試圖連結至目標目錄外。",
-        suggestion: "請確保 hardlink 僅指向 payload 目錄內部的有效檔案。",
-    },
-    NATIVE_PAYLOAD_UNSAFE_PATH: {
-        code: "NATIVE_PAYLOAD_UNSAFE_PATH",
-        description: "原生 payload 含有路徑穿越 (Path traversal) 等不安全路徑。",
-        suggestion: "請確保壓縮檔內無包含 .. 或絕對路徑的檔案名稱。",
-    },
-    NATIVE_PAYLOAD_UNSAFE_SYMLINK: {
-        code: "NATIVE_PAYLOAD_UNSAFE_SYMLINK",
-        description: "原生 payload symlink 指向了安裝目錄之外。",
-        suggestion: "請確保 symlink 僅指向 payload 目錄內部的相對目標。",
-    },
-    NATIVE_PAYLOAD_UNSUPPORTED_ENTRY: {
-        code: "NATIVE_PAYLOAD_UNSUPPORTED_ENTRY",
-        description: "原生 payload 包含不支援的特殊檔案類型（如 device node 或 fifo）。",
-        suggestion: "請從壓縮檔中移除特殊檔案，僅保留一般檔案、目錄與合法 symlink。",
-    },
-    NATIVE_PAYLOAD_UNSUPPORTED_ZIP: {
-        code: "NATIVE_PAYLOAD_UNSUPPORTED_ZIP",
-        description: "不支援的 ZIP 特性（例如 ZIP64、多卷分割或密碼加密）。",
-        suggestion: "請使用標準未加密的 ZIP 或改用 tar.gz 打包。",
-    },
-    NATIVE_PAYLOAD_XZ_FAILED: {
-        code: "NATIVE_PAYLOAD_XZ_FAILED",
-        description: "解壓縮 tar.xz 失敗。",
-        suggestion: "請確認本機已安裝 xz 工具且檔案未損壞。",
-    },
-    NATIVE_PAYLOAD_XZ_UNAVAILABLE: {
-        code: "NATIVE_PAYLOAD_XZ_UNAVAILABLE",
-        description: "系統中找不到 xz 指令可用於解壓縮 .tar.xz 檔案。",
-        suggestion: "請在作業系統中安裝 xz-utils 或改用 tar.gz 格式打包。",
-    },
-    // --- SPK Build & Attestation ---
-    EMBEDDED_ATTESTATION_TOKEN_EMPTY: {
-        code: "EMBEDDED_ATTESTATION_TOKEN_EMPTY",
-        description: "建置 Curated SPK 時嵌入的 Attestation Token 為空。",
-        suggestion: "請檢查 CI Attestation 簽章步驟是否正常產出 JWT。",
-    },
-    BUILD_SPK_FAILED: {
-        code: "BUILD_SPK_FAILED",
-        description: "SPK 打包流程失敗。",
-        suggestion: "請檢查 validate 錯誤與目錄檔案權限後重試。",
-    },
-    // --- Deploy & Host ---
-    VALIDATION_FAILED: {
-        code: "VALIDATION_FAILED",
-        description: "專案未通過契約或安全驗證，終止部署。",
-        suggestion: "請先執行 synopkgland validate 排除合約與 Compose 錯誤。",
-    },
-    DEPLOY_FAILED: {
-        code: "DEPLOY_FAILED",
-        description: "部署至 NAS 時發生未分類錯誤。",
-        suggestion: "請檢查 NAS 網路連線與日誌：synopkgland log --host <nas>。",
-    },
-    DEPLOY_PERSONAL_BUILD_EXHAUSTED: {
-        code: "DEPLOY_PERSONAL_BUILD_EXHAUSTED",
-        description: "Personal App 的 Package Build 已用盡 0001–9999 命名範圍。",
-        suggestion: "請改用新的 App Version，或先清理並確認不會與 Curated 版本命名空間混用。",
-    },
-    DEPLOY_VERSION_NOT_ASCENDING: {
-        code: "DEPLOY_VERSION_NOT_ASCENDING",
-        description: "部署產生的 Package Version 不高於既有版本。",
-        suggestion: "請提高 synology-app.yaml 的 version，或確認目標 NAS 與 Package Source 上的既有版本。",
-    },
-    SHARE_VALUE_REQUIRED: {
-        code: "SHARE_VALUE_REQUIRED",
-        description: "部署時缺少合約中宣告的 shared_folder 實際路徑映射。",
-        suggestion: "請使用 --share <SLOT>=<邏輯名> 提供對應的 Shared Folder 名稱。",
-    },
-    SHARE_LOGICAL_NAME_REQUIRED: {
-        code: "SHARE_LOGICAL_NAME_REQUIRED",
-        description: "Share 參數必須提供邏輯名稱，禁止使用 /volume1/... 等實體路徑。",
-        suggestion: "請指定 DSM 控制台中的 Shared Folder 邏輯名稱，例如 --share MEDIA_SHARE=photos。",
-    },
-    SHARE_NOT_FOUND: {
-        code: "SHARE_NOT_FOUND",
-        description: "在目標 NAS 上找不到指定的 Shared Folder。",
-        suggestion: "請在 DSM 控制台建立該 Shared Folder，或檢查名稱拼字。",
-    },
-    HOMES_NOT_ENABLED: {
-        code: "HOMES_NOT_ENABLED",
-        description: "目標 NAS 未啟用 User Home，或無法解析 homes 的實體 bind source。",
-        suggestion: "請在這台 NAS 啟用 DSM User Home，並確認 Broker／glue 能回傳解析後的路徑，再重新部署。",
-    },
-    DSM_USER_LOGICAL_NAME_REQUIRED: {
-        code: "DSM_USER_LOGICAL_NAME_REQUIRED",
-        description: "dsm_user 參數必須提供 DSM 使用者邏輯名稱，禁止使用數字 UID。",
-        suggestion: "請在 --run-as 指定 DSM 使用者帳號名稱（例如 --run-as RUN_AS=alice）。",
-    },
-    SHARE_RUN_AS_NO_ACCESS: {
-        code: "SHARE_RUN_AS_NO_ACCESS",
-        description: "deploy 的安裝前檢查發現選定的 Container Run-as 使用者對選定的 Shared Folder 沒有權限（或被明確拒絕）。容器會以該使用者掛載該 Share，安裝會成功但 runtime 讀寫會拿到 Permission denied。",
-        suggestion: "請在 DSM 控制台把該 Shared Folder 的權限授予該使用者（或其群組），或改選別的使用者／Share，再重新部署。此檢查只在 deploy 進行；Package Center 安裝精靈不經過這裡，ACL 仍是管理員的前提責任。",
-    },
-    PORT_ALREADY_IN_USE: {
-        code: "PORT_ALREADY_IN_USE",
-        description: "deploy 的安裝前檢查發現 Compose published TCP port 已被其他服務或容器佔用。",
-        suggestion: "請更換 synology-app.yaml／compose.yaml 的 published host port；同一 Package Identity 的既有容器會在升級或重裝時放行。",
-    },
-    CURATED_DEPLOY_REFUSED: {
-        code: "CURATED_DEPLOY_REFUSED",
-        description: "目標 NAS 已持有 Curated App Package Attestation，禁止隨意覆蓋部署。",
-        suggestion: "請改用 --dev 部署至開發隔離環境，或加上 --replace-curated 明確降級。",
-    },
-    CATALOG_PUBLISH_FAILED: {
-        code: "CATALOG_PUBLISH_FAILED",
-        description: "發布 SPK 至 Package Source 失敗。",
-        suggestion: "請確認 Package Source 服務運作正常且網路可達。",
-    },
-    LOCAL_SPK_INSTALL_UNSUPPORTED: {
-        code: "LOCAL_SPK_INSTALL_UNSUPPORTED",
-        description: "目標主機介面不支援直接安裝本機 SPK。",
-        suggestion: "請透過 Package Center 或支援 local-spk 安裝的 Host Adapter 進行部署。",
-    },
-    CATALOG_INSTALL_FAILED: {
-        code: "CATALOG_INSTALL_FAILED",
-        description: "NAS Package Center 安裝套件失敗。",
-        suggestion: "請至 DSM Package Center 檢查安裝日誌或手動嘗試安裝。",
-    },
-    DEPLOY_PARAM_UNDECLARED: {
-        code: "DEPLOY_PARAM_UNDECLARED",
-        description: "deploy --param 提供了契約未宣告的 Install Parameter。",
-        suggestion: "請只傳 synology-app.yaml install 中宣告的 string 或 boolean 名稱。",
-    },
-    DEPLOY_PARAM_TYPE_INVALID: {
-        code: "DEPLOY_PARAM_TYPE_INVALID",
-        description: "deploy --param 的值不符合契約宣告的 string 或 boolean 型別。",
-        suggestion: "string 請傳非空字串；boolean 請只傳 true 或 false。",
-    },
-    DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED: {
-        code: "DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED",
-        description: "無法以管理員 session 列出部署當下的 Shared Folder 清單。",
-        suggestion: "請確認 DSM 管理員 session 可呼叫 SYNO.Core.Share list，或用 --param NAME=... 明確提供清單。",
-    },
-    DSM_DEPENDENCY_CONFLICT: {
-        code: "DSM_DEPENDENCY_CONFLICT",
-        description: "DSM 複合安裝請求因執行中的依賴套件而拒絕。",
-        suggestion: "請先停止列出的依賴套件再重試升級。",
-    },
-    DSM_COMPOUND_FAILED: {
-        code: "DSM_COMPOUND_FAILED",
-        description: "DSM 複合安裝請求的子步驟失敗。",
-        suggestion: "請檢查回應中的 api、method、errorCode 與 DSM Package Center 日誌後重試。",
-    },
-    DSM_REQUEST_FAILED: {
-        code: "DSM_REQUEST_FAILED",
-        description: "DSM SYNO.Entry.Request 複合請求失敗。",
-        suggestion: "請檢查 DSM session、請求參數與 Package Center 日誌後重試。",
-    },
-    INNER_LOOP_API_MISSING: {
-        code: "INNER_LOOP_API_MISSING",
-        description: "目標 NAS 上的 SynoPkgLandService Broker inner-loop API 不可用。",
-        suggestion: "請確認已在 NAS 安裝並啟動 SynoPkgLandService (Broker >= 0.1.0-0016)。",
-    },
-    ATTESTATION_FAILED: {
-        code: "ATTESTATION_FAILED",
-        description: "向 NAS 申請或驗證 Local Attestation 失敗。",
-        suggestion: "請檢查 DSM 登入身分是否為管理者，以及 Broker 運作狀態。",
-    },
-    NOT_INSTALLED: {
-        code: "NOT_INSTALLED",
-        description: "套件尚未在目標 NAS 上安裝部署。",
-        suggestion: "請先執行 synopkgland deploy --host <nas> 安裝套件。",
-    },
-    HOST_CREDENTIALS_MISSING: {
-        code: "HOST_CREDENTIALS_MISSING",
-        description: "找不到目標 NAS 的連線憑證。",
-        suggestion: "請在 ~/.synoagentcli/setting.json 設定 profile，或設定 DSM_URL 與 DSM_PASSWORD 環境變數。",
-    },
-    HOST_UNREACHABLE: {
-        code: "HOST_UNREACHABLE",
-        description: "無法連線至目標 NAS（連線逾時或網路不可達）。",
-        suggestion: "請檢查 NAS IP/網址與網路連線；Node 網路若遇 EHOSTUNREACH 可使用 curl fallback 模式。",
-    },
-    BROKER_NOT_INSTALLED: {
-        code: "BROKER_NOT_INSTALLED",
-        description: "目標 NAS 尚未安裝 SynoPkgLandService (Broker)。",
-        suggestion: "請至 DSM Package Center 安裝 SynoPkgLandService 套件。",
-    },
-    PACKAGE_BROKEN: {
-        code: "PACKAGE_BROKEN",
-        description: "套件在 DSM Package Center 處於損毀或安裝失敗狀態 (status 150 / broken)。",
-        suggestion: "請至 DSM Package Center 嘗試修復 (Repair) 或重新安裝套件。",
-    },
-    ATTESTATION_TRUST_ROOT_MISSING: {
-        code: "ATTESTATION_TRUST_ROOT_MISSING",
-        description: "Broker 缺少生產環境 Attestation Trust Root 信任根憑證。",
-        suggestion: "請確認 SynoPkgLandService 套件完整安裝且 trust root keyring 未被移除。",
-    },
-    ATTESTATION_MISSING: {
-        code: "ATTESTATION_MISSING",
-        description: "App Bundle 缺少必要的 Attestation 簽章憑證。",
-        suggestion: "請先透過 synopkgland deploy 簽發 Local Attestation 或透過 Curated CI 簽署。",
-    },
-    ATTESTATION_INVALID: {
-        code: "ATTESTATION_INVALID",
-        description: "Attestation Token 驗證失敗或與目前 App Bundle 雜湊不符。",
-        suggestion: "檔案修改後請重新執行 synopkgland deploy 產生並安裝新 Attestation。",
-    },
-    READINESS_TIMEOUT: {
-        code: "READINESS_TIMEOUT",
-        description: "App 容器未在時限內就緒 (Readiness Deadline)。",
-        suggestion: "請使用 synopkgland log --host <nas> 檢查容器啟動日誌與健康檢查。",
-    },
-    PROJECT_BINDING_NOT_FOUND: {
-        code: "PROJECT_BINDING_NOT_FOUND",
-        description: "在 Broker 中找不到此套件的 Project Binding 紀錄。",
-        suggestion: "請執行 synopkgland deploy --host <nas> 重新建立部署。",
-    },
-    PROJECT_BINDING_DRIFTED: {
-        code: "PROJECT_BINDING_DRIFTED",
-        description: "Container Manager 中的實際專案狀態與 Broker 綁定記錄不一致。",
-        suggestion: "請執行 synopkgland deploy --host <nas> 重新同步專案。",
-    },
-    PROJECT_BINDING_REMOVED: {
-        code: "PROJECT_BINDING_REMOVED",
-        description: "此套件的 Project Binding 已被標記為移除。",
-        suggestion: "請執行 synopkgland deploy --host <nas> 重新安裝套件。",
-    },
-    PROJECT_BINDING_UNKNOWN: {
-        code: "PROJECT_BINDING_UNKNOWN",
-        description: "Container Manager 暫時無法取得 Project 狀態。",
-        suggestion: "請至 DSM 確認 Container Manager 服務正常運作。",
-    },
-    CLI_VERSION_DRIFT: {
-        code: "CLI_VERSION_DRIFT",
-        description: "本機 @synopackageland/cli 版本與 CI TOOLCHAIN_VERSION 不一致。",
-        suggestion: "請更新 package.json / package-lock.json 或執行 npm install @synopackageland/cli@latest。",
-    },
-    PROJECT_FILES_MISSING: {
-        code: "PROJECT_FILES_MISSING",
-        description: "專案根目錄缺少核心檔案（synology-app.yaml, compose.yaml/native.yaml, README.md, icon.png）。",
-        suggestion: "請補齊缺失的專案核心檔案。",
-    },
-    TRUSTED_APP_ENTRY_FAILED: {
-        code: "TRUSTED_APP_ENTRY_FAILED",
-        description: "Trusted App Entry HTTP 探測失敗（回傳非 200 或無法連線）。",
-        suggestion: "請檢查 Web Station 入口與容器 Web 服務是否正常監聽 adminport。",
-    },
-    TEST_HOST_FAILED: {
-        code: "TEST_HOST_FAILED",
-        description: "在 NAS 上執行 Open smoke 測試失敗（無法取得 DSM User Context）。",
-        suggestion: "請檢查 App 是否正確呼叫 requireLogin 或檢查 DSM Session 登入態。",
-    },
-    // --- Curated Release & Trust Root ---
-    CURATED_TRUST_ROOT_MISSING: {
-        code: "CURATED_TRUST_ROOT_MISSING",
-        description: "缺少 Curated Public Keyring 信任根設定。",
-        suggestion: "請設定 SYNOPKGLAND_CURATED_ATTESTATION_KEYRING 或 SYNOPKGLAND_CURATED_ATTESTATION_KEYRING_PATH。",
-    },
-    CURATED_TRUST_ROOT_INVALID: {
-        code: "CURATED_TRUST_ROOT_INVALID",
-        description: "Curated Public Keyring 格式或內容無效。",
-        suggestion: "請確認信任根為合法 JSON 且包含合規的 RS256 公鑰物件。",
-    },
-    CURATED_SIGNING_KEY_UNKNOWN: {
-        code: "CURATED_SIGNING_KEY_UNKNOWN",
-        description: "簽署金鑰的 kid 不存在於 Curated Public Keyring 中。",
-        suggestion: "請確認所使用的簽署金鑰已登錄於受信任的 Keyring 信任根。",
-    },
-    CURATED_SIGNING_KEY_REVOKED: {
-        code: "CURATED_SIGNING_KEY_REVOKED",
-        description: "簽署金鑰已被標記為撤銷 (revoked)。",
-        suggestion: "請更換為有效且處於 active 狀態的簽署金鑰。",
-    },
-    CURATED_SIGNING_KEY_NOT_ACTIVE: {
-        code: "CURATED_SIGNING_KEY_NOT_ACTIVE",
-        description: "簽署金鑰非 active 狀態（可能為 verify-only）。",
-        suggestion: "請使用具備簽章權限的 active 簽署金鑰。",
-    },
-    CURATED_SIGNING_KEY_MISMATCH: {
-        code: "CURATED_SIGNING_KEY_MISMATCH",
-        description: "私鑰對應的公鑰內容與 Keyring 中登錄的公鑰不符。",
-        suggestion: "請檢查簽署金鑰與 Keyring 憑證是否匹配。",
-    },
-    CURATED_SIGNING_MATERIAL_MISSING: {
-        code: "CURATED_SIGNING_MATERIAL_MISSING",
-        description: "缺少 Curated 簽署私鑰環境變數。",
-        suggestion: "請設定 SYNOPKGLAND_CURATED_ATTESTATION_PRIVATE_JWK 或 PRIVATE_PKCS8。",
-    },
-    CURATED_SIGNING_MATERIAL_AMBIGUOUS: {
-        code: "CURATED_SIGNING_MATERIAL_AMBIGUOUS",
-        description: "同時設定了 JWK 與 PKCS8 私鑰環境變數，來源衝突。",
-        suggestion: "請僅保留 SYNOPKGLAND_CURATED_ATTESTATION_PRIVATE_JWK 或 PRIVATE_PKCS8 其中之一。",
-    },
-    CURATED_SIGNING_MATERIAL_INVALID: {
-        code: "CURATED_SIGNING_MATERIAL_INVALID",
-        description: "提供的簽署私鑰格式無效或無法匯入。",
-        suggestion: "請確認私鑰為合法未加密的 RS256 RSA 私鑰。",
-    },
-    CURATED_RELEASE_SIGNER_MISSING: {
-        code: "CURATED_RELEASE_SIGNER_MISSING",
-        description: "發布流程中未提供 Attestation 簽章器。",
-        suggestion: "請確認 CI 權限與 release custody 金鑰已正確注入。",
-    },
-    CURATED_RELEASE_FAILED: {
-        code: "CURATED_RELEASE_FAILED",
-        description: "Curated Release 發布流程失敗。",
-        suggestion: "請檢查 release CI 日誌以定位失敗步驟。",
-    },
-    CURATED_APP_NOT_FOUND: {
-        code: "CURATED_APP_NOT_FOUND",
-        description: "在 Community Apps 目錄中找不到目標 App。",
-        suggestion: "請確認 synopkgland-community-apps/apps/<package> 目錄存在。",
-    },
-    CURATED_APP_VERSION_REQUIRED: {
-        code: "CURATED_APP_VERSION_REQUIRED",
-        description: "發布時合約必須宣告 version 版本號。",
-        suggestion: "請在 synology-app.yaml 設定合法的 version（例如 1.0.0）。",
-    },
-    CURATED_BUILD_INVALID: {
-        code: "CURATED_BUILD_INVALID",
-        description: "Package Build 號碼格式無效（必須為四位數字）。",
-        suggestion: "請確保 build 號碼為四位數字字串（例如 0001）。",
-    },
-    CURATED_BUILD_MUST_NOT_BE_IN_SOURCE_VERSION: {
-        code: "CURATED_BUILD_MUST_NOT_BE_IN_SOURCE_VERSION",
-        description: "合約中的 version 不得包含 -build 後綴（Build 由 CI Ledger 分配）。",
-        suggestion: "請將 synology-app.yaml 的 version 改為純語意化版本（例如 1.0.0，不含 -0001）。",
-    },
-    CURATED_PACKAGE_IDENTITY_REQUIRED: {
-        code: "CURATED_PACKAGE_IDENTITY_REQUIRED",
-        description: "合約中缺少 package 識別碼宣告。",
-        suggestion: "請在 synology-app.yaml 設定 package 欄位。",
-    },
-    CURATED_DEVELOPMENT_IDENTITY_FORBIDDEN: {
-        code: "CURATED_DEVELOPMENT_IDENTITY_FORBIDDEN",
-        description: "Curated 上架發布嚴禁使用 .dev 開發後綴識別碼。",
-        suggestion: "請移除 package 名稱末尾的 .dev 後綴。",
-    },
-    CURATED_PACKAGE_DIRECTORY_MISMATCH: {
-        code: "CURATED_PACKAGE_DIRECTORY_MISMATCH",
-        description: "Community Apps 目錄名稱與 synology-app.yaml 中的 package 名稱不一致。",
-        suggestion: "請將 app 目錄重新命名為 apps/<package>。",
-    },
-    CURATED_VALIDATION_FAILED: {
-        code: "CURATED_VALIDATION_FAILED",
-        description: "專案未通過 Curated listing profile 嚴格驗證門檻。",
-        suggestion: "請執行 synopkgland validate 排除錯誤後再進行 release。",
-    },
-    CURATED_NATIVE_MISSING: {
-        code: "CURATED_NATIVE_MISSING",
-        description: "原生 App 發布時找不到 native.yaml 定義檔。",
-        suggestion: "請在專案根目錄補上 native.yaml。",
-    },
-    CURATED_NATIVE_TARGETS_EMPTY: {
-        code: "CURATED_NATIVE_TARGETS_EMPTY",
-        description: "原生 App 發布時 targets 不可為空。",
-        suggestion: "請在 native.yaml targets 至少定義一個架構目標。",
-    },
-    CURATED_COMPOSE_MISSING: {
-        code: "CURATED_COMPOSE_MISSING",
-        description: "容器 App 發布時找不到 compose.yaml 定義檔。",
-        suggestion: "請在專案根目錄補上 compose.yaml。",
-    },
-    CURATED_COMPOSE_GATE_FAILED: {
-        code: "CURATED_COMPOSE_GATE_FAILED",
-        description: "Compose 未通過 Curated CI 嚴格門檻（如映像檔必須帶 immutable sha256 digest）。",
-        suggestion: "請在 compose.yaml 使用固定 digest 的公開 OCI 映像檔（image@sha256:...），並移除 build 區塊。",
-    },
-    CURATED_COMPOSE_BUILD_FORBIDDEN: {
-        code: "CURATED_COMPOSE_BUILD_FORBIDDEN",
-        description: "Curated 發布禁止使用 compose build: 區塊。",
-        suggestion: "請移除 compose.yaml 中的 build: 區塊，並指定已發布至公開 registry 的 image。",
-    },
-    CURATED_COMPOSE_IMAGE_REQUIRED: {
-        code: "CURATED_COMPOSE_IMAGE_REQUIRED",
-        description: "Curated 服務必須宣告 image 映像檔名稱。",
-        suggestion: "請在 compose.yaml 的 service 中宣告 image: 欄位。",
-    },
-    CURATED_COMPOSE_IMAGE_DIGEST_REQUIRED: {
-        code: "CURATED_COMPOSE_IMAGE_DIGEST_REQUIRED",
-        description: "Curated 映像檔必須使用不可變的 @sha256: 摘要鎖定。",
-        suggestion: "請在 image 加上不可變的 SHA-256 Digest（例如 image: redis@sha256:...）。",
-    },
-    CURATED_COMPOSE_SERVICES_REQUIRED: {
-        code: "CURATED_COMPOSE_SERVICES_REQUIRED",
-        description: "compose.yaml 缺少 services 區塊或服務為空。",
-        suggestion: "請在 compose.yaml 至少定義一個容器服務。",
-    },
-    CURATED_BROKER_ROUTE_FORBIDDEN: {
-        code: "CURATED_BROKER_ROUTE_FORBIDDEN",
-        description: "此 Compose 會落到 Broker installer 路線；rootless Broker 不支援 Container Manager，Curated listing 拒絕。",
-        suggestion: "請改成零設定 resource-worker：使用 ./html bind 與預先 build 的 image；將 ${SYNOPKG_PKGVAR} 等平台 bind 改成 named volume，或改用 D1 dynamic route 的 string/boolean install 參數。",
-    },
-    CURATED_BUNDLE_FILE_MISSING: {
-        code: "CURATED_BUNDLE_FILE_MISSING",
-        description: "打包 Curated Release 時缺少必要的 Bundle 檔案。",
-        suggestion: "請確認專案根目錄包含完整的 synology-app.yaml 與 compose.yaml/native.yaml。",
-    },
-    CURATED_ATTESTATION_BINDING_FAILED: {
-        code: "CURATED_ATTESTATION_BINDING_FAILED",
-        description: "Curated Attestation Token 簽署或綁定聲明失敗。",
-        suggestion: "請檢查 signing keys 與 claims 內容。",
-    },
-    CURATED_ATTESTATION_SIGNATURE_INVALID: {
-        code: "CURATED_ATTESTATION_SIGNATURE_INVALID",
-        description: "Curated Attestation JWT 簽章無效。",
-        suggestion: "請確認簽署私鑰與公開信任根 Keyring 一致。",
-    },
-    CURATED_BUILD_FAILED: {
-        code: "CURATED_BUILD_FAILED",
-        description: "建置 Curated SPK 失敗。",
-        suggestion: "請檢查建置日誌以排除檔案或權限錯誤。",
-    },
-    CURATED_RELEASE_ATTESTATION_BINDING_FAILED: {
-        code: "CURATED_RELEASE_ATTESTATION_BINDING_FAILED",
-        description: "Detached Release Attestation 綁定 SPK 雜湊失敗。",
-        suggestion: "請確保產出的 SPK 位元組雜湊與簽署聲明一致。",
-    },
-    CURATED_EMBEDDED_ATTESTATION_MISSING: {
-        code: "CURATED_EMBEDDED_ATTESTATION_MISSING",
-        description: "已建置的 Curated SPK 內缺少嵌入的 Attestation Token。",
-        suggestion: "請檢查 build-spk 是否正確將 token 寫入 package/.synopkgland/token。",
-    },
-    CURATED_EMBEDDED_ATTESTATION_BINDING_FAILED: {
-        code: "CURATED_EMBEDDED_ATTESTATION_BINDING_FAILED",
-        description: "SPK 內嵌入的 Attestation 與 Release Claims 聲明不符。",
-        suggestion: "請確認嵌入式 Token 的 Digest 與 Claims 一致。",
-    },
-    // --- Publish & Preflight ---
-    PREFLIGHT_FAILED: {
-        code: "PREFLIGHT_FAILED",
-        description: "送審公開發布前置檢查未通過。",
-        suggestion: "請先修正 preflight 列出的錯誤後再重新送審。",
-    },
-    COMMUNITY_APPS_ROOT_MISSING: {
-        code: "COMMUNITY_APPS_ROOT_MISSING",
-        description: "找不到 synopkgland-community-apps 本機副本。",
-        suggestion: "請 clone synopkgland-community-apps 並設定 SYNOPKGLAND_COMMUNITY_APPS_ROOT 環境變數。",
-    },
-    PACKAGE_IDENTITY_MISSING: {
-        code: "PACKAGE_IDENTITY_MISSING",
-        description: "專案 synology-app.yaml 中缺少 package 欄位。",
-        suggestion: "請在 synology-app.yaml 補上 package 宣告。",
-    },
-    PACKAGE_DIRECTORY_MISMATCH: {
-        code: "PACKAGE_DIRECTORY_MISMATCH",
-        description: "專案目錄或 Community Apps 子目錄與 package 名稱不一致。",
-        suggestion: "請確保專案目錄名稱與 package 宣告一致。",
-    },
-    PUBLISH_SOURCE_IS_COMMUNITY_APP: {
-        code: "PUBLISH_SOURCE_IS_COMMUNITY_APP",
-        description: "publish 指令不可在 synopkgland-community-apps/apps 目錄內直接執行。",
-        suggestion: "請在您的獨立 App 開發專案目錄中執行 public-release-submit。",
-    },
-    PUBLISH_PR_FAILED: {
-        code: "PUBLISH_PR_FAILED",
-        description: "透過 GitHub CLI 建立 Pull Request 失敗。",
-        suggestion: "請確認 gh 已登入 (gh auth login) 或已設定 GITHUB_TOKEN。",
-    },
+    "COMPOSE_ROUTE_UNSUPPORTED": {
+        "code": "COMPOSE_ROUTE_UNSUPPORTED",
+        "description": "Compose 沒有可用的 DSM resource worker 執行路徑。",
+        "suggestion": "使用 prebuilt image 與支援的安裝參數；移除不支援的特權、secret 或 build 設定。"
+    },
+    "LOCAL_SPK_INSTALL_FAILED": {
+        "code": "LOCAL_SPK_INSTALL_FAILED",
+        "description": "DSM 本機 SPK 安裝失敗。",
+        "suggestion": "查看 DSM Package Center 安裝錯誤，確認套件版本及需求。"
+    },
+    "CONTRACT_SCHEMA_UNSUPPORTED": {
+        "code": "CONTRACT_SCHEMA_UNSUPPORTED",
+        "description": "synology-app.yaml 的 schema 版本不受支援。",
+        "suggestion": "請將 synology-app.yaml 的 schema 欄位設為 1。"
+    },
+    "CONTRACT_MISSING_FIELD": {
+        "code": "CONTRACT_MISSING_FIELD",
+        "description": "synology-app.yaml 缺少必填欄位。",
+        "suggestion": "請在 synology-app.yaml 補上缺少的必填欄位（例如 package, version, displayname 等）。"
+    },
+    "CONTRACT_SCHEMA_INVALID": {
+        "code": "CONTRACT_SCHEMA_INVALID",
+        "description": "synology-app.yaml 格式與 JSON Schema 規格不符。",
+        "suggestion": "請修正 synology-app.yaml 的欄位格式以符合規範。"
+    },
+    "PACKAGE_IDENTITY_TOO_LONG": {
+        "code": "PACKAGE_IDENTITY_TOO_LONG",
+        "description": "Package Identity 超過長度上限（正式身分上限 28 字元，最終身分上限 32 字元）。",
+        "suggestion": "請縮短 synology-app.yaml 中的 package 名稱（正式身分至多 28 字元，以保留 4 字元供 .dev 開發後綴使用）。"
+    },
+    "CONTRACT_PACKAGE_TOO_LONG": {
+        "code": "CONTRACT_PACKAGE_TOO_LONG",
+        "description": "Package Identity 超過 DSM 上限 32 字元。",
+        "suggestion": "請縮短 synology-app.yaml 中的 package 名稱至 32 字元以內。"
+    },
+    "CONTRACT_ADMINPORT_INVALID": {
+        "code": "CONTRACT_ADMINPORT_INVALID",
+        "description": "adminport 必須是整數。",
+        "suggestion": "請在 synology-app.yaml 提供與 Compose published port 對應的整數 adminport。"
+    },
+    "CONTRACT_ADMINPORT_UNMAPPED": {
+        "code": "CONTRACT_ADMINPORT_UNMAPPED",
+        "description": "adminport 未在 Compose ports 宣告中對應到容器 port。",
+        "suggestion": "請在 compose.yaml 的 ports 區塊宣告與 adminport 對應的連接埠映射（例如 \"8080:80\"）。"
+    },
+    "CONTRACT_LAUNCH_INVALID": {
+        "code": "CONTRACT_LAUNCH_INVALID",
+        "description": "integration.web.launch 模式無效。",
+        "suggestion": "請改為 dsm-window（DSM 視窗，預設）或 new-page（新分頁），Headless App 請省略此欄位。"
+    },
+    "CONTRACT_LAUNCH_REQUIRES_WEB": {
+        "code": "CONTRACT_LAUNCH_REQUIRES_WEB",
+        "description": "Headless App 不需要宣告 Web Launch Mode。",
+        "suggestion": "請省略 integration.web.launch，或補上對應 Compose published port 的 adminport。"
+    },
+    "CONTRACT_INVALID_STRING": {
+        "code": "CONTRACT_INVALID_STRING",
+        "description": "合約字串含有不允許的控制字元或未允許的插值語法。",
+        "suggestion": "請移除控制字元與 ${ 插值語法，安裝參數請在 install 區塊宣告。"
+    },
+    "CONTRACT_DSM_USER_DUPLICATE": {
+        "code": "CONTRACT_DSM_USER_DUPLICATE",
+        "description": "每顆 App 至多宣告一個 dsm_user 安裝參數。",
+        "suggestion": "請在 synology-app.yaml 只保留一個 Container Run-as 參數。"
+    },
+    "INSTALL_STRING_TOO_LONG": {
+        "code": "INSTALL_STRING_TOO_LONG",
+        "description": "Install Parameter 字串預設值超過 256 字元。",
+        "suggestion": "請縮短 synology-app.yaml 中 install 參數的預設字串長度。"
+    },
+    "INSTALL_STRING_INVALID": {
+        "code": "INSTALL_STRING_INVALID",
+        "description": "Install Parameter 字串值含有不合法字元或插值。",
+        "suggestion": "請移除 install 參數預設值中的控制字元與 ${ 插值語法。"
+    },
+    "CONTRACT_SECRET_UNSUPPORTED": {
+        "code": "CONTRACT_SECRET_UNSUPPORTED",
+        "description": "install.<NAME>.type: secret 目前沒有可用的安裝路徑。2026-08-27 於 vt-nas 實測：無論是否在 Compose 引用，Package Center 安裝都以 DSM broken／150 結束且不建立 Container Manager project（同一台 NAS 上無參數的對照套件正常安裝）。",
+        "suggestion": "請改用 type: string（非敏感值），或把敏感值改成 App 啟動後自行取得／由管理員放進 ${SYNO_APP_SECRETS_DIR} 的檔案。secret 型別要能用，需要先讓 DSM worker 的失敗原因可觀測（見 STATUS.md A22／A45）。"
+    },
+    "CONTRACT_HOMES_UNSUPPORTED": {
+        "code": "CONTRACT_HOMES_UNSUPPORTED",
+        "description": "install.<NAME>.type: homes 目前沒有可用的安裝路徑。2026-08-27 於 vt-nas 實測：wizard 不產生輸入控制項，Package Center 安裝以 DSM broken／150 結束；CLI deploy 能解析出 /volume1/homes，但 DSM 於 compound install 回 4540 拒絕。",
+        "suggestion": "若 App 需要一個由管理員選定的資料夾，請改用 type: shared_folder。homes 型別要能用，需要補齊 wizard 控制項與 preinst materialization（見 STATUS.md A46）。"
+    },
+    "INSTALL_PARAMETER_UNREFERENCED": {
+        "code": "INSTALL_PARAMETER_UNREFERENCED",
+        "description": "install 宣告的參數未在 Compose 中被引用。",
+        "suggestion": "請在 compose.yaml 以 ${參數名稱} 引用該參數，或從 synology-app.yaml 移除未使用的宣告。"
+    },
+    "CONTRACT_HOMES_PATH_FORBIDDEN": {
+        "code": "CONTRACT_HOMES_PATH_FORBIDDEN",
+        "description": "homes Install Parameter 不得在契約中寫入 NAS 實體路徑或預設值。",
+        "suggestion": "請只宣告 type: homes 並在 Compose 引用該參數，由套件 在安裝時解析這台 NAS 的 User Home 路徑。"
+    },
+    "CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN": {
+        "code": "CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN",
+        "description": "POSIX all-shares 參數不得在契約中指定 default 或 NAS 實體路徑。",
+        "suggestion": "請只宣告 type: posix_all_shares，讓 wizard／CLI 在安裝時取得當下的 Share snapshot。"
+    },
+    "CONTRACT_POSIX_ALL_SHARES_LISTING_UNSUPPORTED": {
+        "code": "CONTRACT_POSIX_ALL_SHARES_LISTING_UNSUPPORTED",
+        "description": "posix_all_shares 需要 CLI 在安裝時以管理員 session 取得這台 NAS 的 Share 清單快照；Package Center 與 Package Source listing 無法履行此合約。",
+        "suggestion": "請使用 synopkgland deploy --host <name>，由管理員 session 在安裝時取得 Share 清單快照；此型別不能透過 Package Center 或 Package Source listing 上架。"
+    },
+    "DSM_USER_REQUIRED": {
+        "code": "DSM_USER_REQUIRED",
+        "description": "有 Shared Folder 時必須宣告恰好一個 dsm_user 作為 Container Run-as。",
+        "suggestion": "請在 synology-app.yaml 新增 install.<NAME>.type: dsm_user，並在 Compose 引用 ${NAME_UID}:${NAME_GID}。"
+    },
+    "PROJECT_RUNTIME_EXCLUSIVE": {
+        "code": "PROJECT_RUNTIME_EXCLUSIVE",
+        "description": "專案同時存在 compose.yaml 與 native.yaml，兩者互斥。",
+        "suggestion": "請選擇使用 compose.yaml（容器 App）或 native.yaml（原生 App），並刪除另一個檔案。"
+    },
+    "COMPOSE_MISSING": {
+        "code": "COMPOSE_MISSING",
+        "description": "找不到 compose.yaml 或 native.yaml。",
+        "suggestion": "請在專案根目錄建立 compose.yaml 或 native.yaml。"
+    },
+    "COMPOSE_SERVICE_NOT_FOUND": {
+        "code": "COMPOSE_SERVICE_NOT_FOUND",
+        "description": "depends_on 引用的服務不存在於 compose.yaml 中。",
+        "suggestion": "請修正 compose.yaml 中的 depends_on，指向正確已定義的 service 名稱。"
+    },
+    "COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN": {
+        "code": "COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN",
+        "description": "會走 DSM Docker Project resource worker 的 Compose command/entrypoint 陣列含純數字字串，可能在 worker YAML round-trip 後變成整數而無法 acquire。",
+        "suggestion": "請把整個命令包成單一字串，例如 command: [\"sh\", \"-c\", \"httpd -f -p 8080 -h /srv\"]，或與 flag 併寫成 \"-p8080\"。"
+    },
+    "COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED": {
+        "code": "COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED",
+        "description": "Compose dynamic route 超出 D1/D2 白名單，或使用 DSM worker 不會載入的 secret/config 來源。",
+        "suggestion": "請只使用 string/boolean wizard answer 的 ${NAME} interpolation；secret/config 因 DSM worker 不讀 docker-compose.override.yml 而拒收。"
+    },
+    "COMPOSE_BUILD_FORBIDDEN": {
+        "code": "COMPOSE_BUILD_FORBIDDEN",
+        "description": "D0 Compose route 禁止在 NAS install-time 使用 build:；build capability 永久拒收。",
+        "suggestion": "請移除 build:，改用已存在的 image（最好使用 image@sha256:... 固定 digest），再重新執行 validate。"
+    },
+    "COMPOSE_SOCKET_MOUNT_FORBIDDEN": {
+        "code": "COMPOSE_SOCKET_MOUNT_FORBIDDEN",
+        "description": "嚴禁掛載 Docker Socket 或系統敏感 Socket。",
+        "suggestion": "請從 compose.yaml 移除 docker.sock 掛載；如需存取檔案請改用 shared_folder 或 App 自己的檔案 API。"
+    },
+    "COMPOSE_BIND_SOURCE_FORBIDDEN": {
+        "code": "COMPOSE_BIND_SOURCE_FORBIDDEN",
+        "description": "掛載來源路徑不合法或屬於受保護的系統路徑。",
+        "suggestion": "請使用受控的 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR} 或已宣告的 ${SHARED_FOLDER} 槽位。"
+    },
+    "COMPOSE_BIND_SOURCE_UNDECLARED": {
+        "code": "COMPOSE_BIND_SOURCE_UNDECLARED",
+        "description": "Volume 掛載使用了未宣告的 Shared Folder 變數。",
+        "suggestion": "請先在 synology-app.yaml 的 install 區塊宣告該 shared_folder 參數。"
+    },
+    "COMPOSE_BIND_SUFFIX_INVALID": {
+        "code": "COMPOSE_BIND_SUFFIX_INVALID",
+        "description": "Shared Folder 子路徑格式不合法（含有 .. 或控制字元）。",
+        "suggestion": "請改用合法的相對子路徑，例如 ${MEDIA_SHARE}/data:/data。"
+    },
+    "COMPOSE_POSIX_ALL_SHARES_UNDECLARED": {
+        "code": "COMPOSE_POSIX_ALL_SHARES_UNDECLARED",
+        "description": "Compose 使用了未宣告的 POSIX all-shares marker。",
+        "suggestion": "請宣告 type: posix_all_shares，讓 package-only wizard／CLI 取得安裝當下的 Share snapshot。"
+    },
+    "COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN": {
+        "code": "COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN",
+        "description": "POSIX all-shares marker 不得附加 Share 子路徑。",
+        "suggestion": "請只使用完整的 ${ALL_SHARES} source；每個 Share 的 container target 由 package-only preinst 展開。"
+    },
+    "COMPOSE_HOST_BIND_FORBIDDEN": {
+        "code": "COMPOSE_HOST_BIND_FORBIDDEN",
+        "description": "禁止直接硬編碼本機路徑（例如 /volume1/... 或 ./）。",
+        "suggestion": "請在 synology-app.yaml 宣告 shared_folder 參數，並在 Compose 改用 ${SLOT} 引用。"
+    },
+    "COMPOSE_NAMED_VOLUME_UNDECLARED": {
+        "code": "COMPOSE_NAMED_VOLUME_UNDECLARED",
+        "description": "服務使用了未在頂層 volumes 宣告的 Named Volume。",
+        "suggestion": "請在 compose.yaml 頂層 volumes 區塊補上該 Volume 宣告，或改用受控目錄。"
+    },
+    "COMPOSE_USER_ROOT_FORBIDDEN": {
+        "code": "COMPOSE_USER_ROOT_FORBIDDEN",
+        "description": "容器以 root (0:0) 執行，違反最小權限原則。",
+        "suggestion": "請在 synology-app.yaml 宣告 dsm_user 並在 Compose 使用 ${USER_UID}:${USER_GID}。"
+    },
+    "COMPOSE_USER_CONFLICTS_DSM_USER": {
+        "code": "COMPOSE_USER_CONFLICTS_DSM_USER",
+        "description": "Compose 服務自定義了 user 欄位，與 contract 宣告的 dsm_user 衝突。",
+        "suggestion": "請移除 Compose 中的 user 欄位，交由 dsm_user 自動注入 ${NAME_UID}:${NAME_GID} 與 group_add。"
+    },
+    "COMPOSE_USER_NUMERIC_FORBIDDEN": {
+        "code": "COMPOSE_USER_NUMERIC_FORBIDDEN",
+        "description": "禁止在 compose.yaml 硬編碼數字 uid:gid。",
+        "suggestion": "請在 synology-app.yaml 宣告 dsm_user，並在 Compose 引用 ${NAME_UID}:${NAME_GID}。"
+    },
+    "COMPOSE_PRIVILEGED_FORBIDDEN": {
+        "code": "COMPOSE_PRIVILEGED_FORBIDDEN",
+        "description": "使用了 privileged: true 但未在合約宣告。",
+        "suggestion": "請在 synology-app.yaml 加上 privilege.privileged: true，或移除 privileged: true。"
+    },
+    "COMPOSE_HOST_NETWORK_FORBIDDEN": {
+        "code": "COMPOSE_HOST_NETWORK_FORBIDDEN",
+        "description": "使用了 host network 模式但未在合約宣告。",
+        "suggestion": "請在 synology-app.yaml 加上 privilege.host_network: true，或改用受控網路模式。"
+    },
+    "COMPOSE_HOST_PID_FORBIDDEN": {
+        "code": "COMPOSE_HOST_PID_FORBIDDEN",
+        "description": "使用了 pid: host 但未在合約宣告。",
+        "suggestion": "請在 synology-app.yaml 加上 privilege.host_pid: true，或移除 pid: host。"
+    },
+    "COMPOSE_HOST_IPC_FORBIDDEN": {
+        "code": "COMPOSE_HOST_IPC_FORBIDDEN",
+        "description": "使用了 ipc: host 但未在合約宣告。",
+        "suggestion": "請在 synology-app.yaml 加上 privilege.host_ipc: true，或移除 ipc: host。"
+    },
+    "COMPOSE_DEVICES_FORBIDDEN": {
+        "code": "COMPOSE_DEVICES_FORBIDDEN",
+        "description": "使用了 devices 裝置存取但未在合約宣告。",
+        "suggestion": "請在 synology-app.yaml 加上 privilege.devices: true，或移除 devices 區塊。"
+    },
+    "COMPOSE_CAP_ADD_FORBIDDEN": {
+        "code": "COMPOSE_CAP_ADD_FORBIDDEN",
+        "description": "使用了 cap_add 權限提升但未在合約宣告。",
+        "suggestion": "請在 synology-app.yaml 加上 privilege.cap_add: true，或移除 cap_add 區塊。"
+    },
+    "COMPOSE_ENV_MISSING": {
+        "code": "COMPOSE_ENV_MISSING",
+        "description": "專案缺少必要的環境變數目錄結構。",
+        "suggestion": "請確認 SYNOPKG_PKGVAR 與 secrets 目錄已正確建立。"
+    },
+    "COMPOSE_NOT_HEALTHY": {
+        "code": "COMPOSE_NOT_HEALTHY",
+        "description": "Compose 服務未能於時限內通過 healthcheck 達到 healthy 狀態。",
+        "suggestion": "請檢查容器健康檢查設定與應用程式日誌：synopkgland log --host <nas>。"
+    },
+    "COMPOSE_NOT_RUNNING": {
+        "code": "COMPOSE_NOT_RUNNING",
+        "description": "Compose 服務未能於時限內維持 running 狀態。",
+        "suggestion": "請檢查容器啟動腳本與日誌以排除崩潰原因：synopkgland log --host <nas>。"
+    },
+    "NATIVE_LOAD_FAILED": {
+        "code": "NATIVE_LOAD_FAILED",
+        "description": "無法讀取或解析 native.yaml。",
+        "suggestion": "請確認 native.yaml 存在且為合法 YAML 格式。"
+    },
+    "NATIVE_SCHEMA_INVALID": {
+        "code": "NATIVE_SCHEMA_INVALID",
+        "description": "native.yaml schema 版本無效（必須為整數 1）。",
+        "suggestion": "請在 native.yaml 設定 schema: 1。"
+    },
+    "NATIVE_TARGETS_REQUIRED": {
+        "code": "NATIVE_TARGETS_REQUIRED",
+        "description": "native.yaml 缺少 targets 區塊。",
+        "suggestion": "請在 native.yaml 宣告 targets 區塊並指定 x86_64 或 aarch64 目標。"
+    },
+    "NATIVE_TARGETS_EMPTY": {
+        "code": "NATIVE_TARGETS_EMPTY",
+        "description": "native.yaml 中的 targets 區塊不可為空。",
+        "suggestion": "請在 native.yaml 的 targets 內至少定義一個架構目標（x86_64 或 aarch64）。"
+    },
+    "NATIVE_ARCH_UNKNOWN": {
+        "code": "NATIVE_ARCH_UNKNOWN",
+        "description": "native.yaml 定義了不受支援的架構目標名稱。",
+        "suggestion": "目標架構名稱僅支援 x86_64 與 aarch64。"
+    },
+    "NATIVE_TARGET_INVALID": {
+        "code": "NATIVE_TARGET_INVALID",
+        "description": "native.yaml 目標架構定義無效。",
+        "suggestion": "每個目標架構必須包含 path 或 url 下載來源設定。"
+    },
+    "NATIVE_TARGET_NOT_DECLARED": {
+        "code": "NATIVE_TARGET_NOT_DECLARED",
+        "description": "欲建置或部署的架構目標未在 native.yaml 中宣告。",
+        "suggestion": "請在 native.yaml 的 targets 補上該架構目標，或透過 --arch 指定已宣告的目標。"
+    },
+    "NATIVE_TARGET_SOURCE_EXCLUSIVE": {
+        "code": "NATIVE_TARGET_SOURCE_EXCLUSIVE",
+        "description": "目標架構不可同時包含 path 與 url，兩者互斥。",
+        "suggestion": "請在該目標架構中只保留 path（本機）或 url（遠端二進位檔）。"
+    },
+    "NATIVE_PATH_FORBIDDEN_IN_LISTING": {
+        "code": "NATIVE_PATH_FORBIDDEN_IN_LISTING",
+        "description": "公開上架審查禁止使用本機 path 來源的 native 目標。",
+        "suggestion": "請將 target 改為公開可下載的 url 並附帶 sha256 校驗碼。"
+    },
+    "NATIVE_SHA256_REQUIRED_IN_LISTING": {
+        "code": "NATIVE_SHA256_REQUIRED_IN_LISTING",
+        "description": "公開上架審查要求 url 目標必須提供 sha256 校驗碼。",
+        "suggestion": "請在 native.yaml 的 url 目標補上 64 位十六進位 sha256 欄位。"
+    },
+    "NATIVE_SHA256_INVALID": {
+        "code": "NATIVE_SHA256_INVALID",
+        "description": "sha256 校驗碼格式無效。",
+        "suggestion": "請提供恰好 64 字元的十六進位 SHA-256 字串。"
+    },
+    "NATIVE_STRIP_COMPONENTS_INVALID": {
+        "code": "NATIVE_STRIP_COMPONENTS_INVALID",
+        "description": "strip_components 必須是非負整數。",
+        "suggestion": "請在 native.yaml 將 strip_components 設為大於等於 0 的整數。"
+    },
+    "NATIVE_SERVICE_REQUIRED": {
+        "code": "NATIVE_SERVICE_REQUIRED",
+        "description": "native.yaml 缺少 service 區塊。",
+        "suggestion": "請在 native.yaml 補上 service 區塊並宣告 exec 與 args/env。"
+    },
+    "NATIVE_SERVICE_USER_FORBIDDEN": {
+        "code": "NATIVE_SERVICE_USER_FORBIDDEN",
+        "description": "native service 不允許自訂 user 欄位（固定以 package 使用者執行）。",
+        "suggestion": "請從 native.yaml 的 service 區塊移除 user 欄位。"
+    },
+    "NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN": {
+        "code": "NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN",
+        "description": "禁止在 native service 使用 command/shell 等字串欄位以免 shell injection。",
+        "suggestion": "請改用 exec（路徑）與 args（字串陣列）方式宣告啟動指令。"
+    },
+    "NATIVE_EXEC_REQUIRED": {
+        "code": "NATIVE_EXEC_REQUIRED",
+        "description": "native service 缺少 exec 執行檔路徑。",
+        "suggestion": "請在 native.yaml 的 service 區塊指定 exec: <相對路徑>。"
+    },
+    "NATIVE_EXEC_INVALID_PATH": {
+        "code": "NATIVE_EXEC_INVALID_PATH",
+        "description": "exec 必須是相對路徑，且不可包含 .. 或絕對路徑。",
+        "suggestion": "請指定相對於安裝根目錄的合法相對路徑，例如 exec: bin/app。"
+    },
+    "NATIVE_ARGS_INVALID": {
+        "code": "NATIVE_ARGS_INVALID",
+        "description": "service.args 必須是字串陣列。",
+        "suggestion": "請在 native.yaml 將 args 宣告為字串列表格式（例如 args: [\"--port\", \"8080\"]）。"
+    },
+    "NATIVE_ENV_INVALID": {
+        "code": "NATIVE_ENV_INVALID",
+        "description": "service.env 必須是 key-value 字串映射表。",
+        "suggestion": "請將 env 宣告為字典物件且每個值皆為字串。"
+    },
+    "NATIVE_PKGVAR_REQUIRED": {
+        "code": "NATIVE_PKGVAR_REQUIRED",
+        "description": "原生二進位 App 必須在 args 或 env 中引用 ${SYNOPKG_PKGVAR} 以指定資料路徑。",
+        "suggestion": "請在 native.yaml 的 service.args 或 service.env 加入 ${SYNOPKG_PKGVAR} 參數。"
+    },
+    "NATIVE_ARCH_FAMILY_REQUIRED": {
+        "code": "NATIVE_ARCH_FAMILY_REQUIRED",
+        "description": "建置原生 SPK 時缺少目標架構家族（x86_64 或 aarch64）。",
+        "suggestion": "請在指令加上 --arch x86_64 或 --arch aarch64。"
+    },
+    "NATIVE_ARCH_UNDETERMINED": {
+        "code": "NATIVE_ARCH_UNDETERMINED",
+        "description": "無法從目標 NAS 的 CPU 資訊自動判定架構家族。",
+        "suggestion": "請使用 --arch x86_64 或 --arch aarch64 明確指定目標架構。"
+    },
+    "NATIVE_PAYLOAD_BUNDLE_COLLISION": {
+        "code": "NATIVE_PAYLOAD_BUNDLE_COLLISION",
+        "description": "原生 payload 解壓縮內容與 App Bundle 核心保留檔衝突。",
+        "suggestion": "請檢查 payload 內容，避免在根目錄覆蓋 synology-app.yaml 或 native.yaml。"
+    },
+    "NATIVE_PAYLOAD_DOWNLOAD_FAILED": {
+        "code": "NATIVE_PAYLOAD_DOWNLOAD_FAILED",
+        "description": "下載原生二進位檔 payload 失敗。",
+        "suggestion": "請檢查 native.yaml 中的 url 是否有效且網路連線正常。"
+    },
+    "NATIVE_PAYLOAD_DOWNLOAD_INVALID": {
+        "code": "NATIVE_PAYLOAD_DOWNLOAD_INVALID",
+        "description": "下載的原生 payload 回傳內容無效。",
+        "suggestion": "請確認目標 URL 回傳了有效的二進位檔案內容。"
+    },
+    "NATIVE_PAYLOAD_DUPLICATE_ENTRY": {
+        "code": "NATIVE_PAYLOAD_DUPLICATE_ENTRY",
+        "description": "原生 payload 壓縮檔內包含重複的檔案路徑。",
+        "suggestion": "請重新打包原始檔案，確保壓縮檔內無重複 entry。"
+    },
+    "NATIVE_PAYLOAD_ERROR": {
+        "code": "NATIVE_PAYLOAD_ERROR",
+        "description": "處理原生二進位 payload 時發生未預期錯誤。",
+        "suggestion": "請檢查 payload 壓縮檔完整性或重新建置 SPK。"
+    },
+    "NATIVE_PAYLOAD_EXTRACTION_FAILED": {
+        "code": "NATIVE_PAYLOAD_EXTRACTION_FAILED",
+        "description": "解壓縮原生二進位 payload 失敗。",
+        "suggestion": "請確認壓縮檔格式正確無損壞，且支援 tar.gz / tar.xz / zip。"
+    },
+    "NATIVE_PAYLOAD_INVALID_HARDLINK": {
+        "code": "NATIVE_PAYLOAD_INVALID_HARDLINK",
+        "description": "原生 payload 含有無效或循環的 hardlink。",
+        "suggestion": "請移除壓縮檔中不合法的 hardlink 後重新打包。"
+    },
+    "NATIVE_PAYLOAD_INVALID_STRIP_COMPONENTS": {
+        "code": "NATIVE_PAYLOAD_INVALID_STRIP_COMPONENTS",
+        "description": "strip_components 設定超過了壓縮檔目錄層級深度。",
+        "suggestion": "請在 native.yaml 調整或減少 strip_components 數值。"
+    },
+    "NATIVE_PAYLOAD_INVALID_SYMLINK": {
+        "code": "NATIVE_PAYLOAD_INVALID_SYMLINK",
+        "description": "原生 payload 含有無效的符號連結。",
+        "suggestion": "請檢查壓縮檔內的 symlink 目標是否存在且合法。"
+    },
+    "NATIVE_PAYLOAD_INVALID_ZIP": {
+        "code": "NATIVE_PAYLOAD_INVALID_ZIP",
+        "description": "ZIP 壓縮檔格式無效或已損壞。",
+        "suggestion": "請檢查 zip 檔案完整性或重新打包。"
+    },
+    "NATIVE_PAYLOAD_SHA256_MISMATCH": {
+        "code": "NATIVE_PAYLOAD_SHA256_MISMATCH",
+        "description": "下載的 payload SHA-256 校驗碼與 native.yaml 宣告不符。",
+        "suggestion": "請更新 native.yaml 中的 sha256 欄位以符合實際檔案雜湊。"
+    },
+    "NATIVE_PAYLOAD_SOURCE_AMBIGUOUS": {
+        "code": "NATIVE_PAYLOAD_SOURCE_AMBIGUOUS",
+        "description": "目標架構同時宣告了 path 與 url，來源衝突。",
+        "suggestion": "請在該目標架構中只保留 path 或 url 其中一種來源。"
+    },
+    "NATIVE_PAYLOAD_SOURCE_REQUIRED": {
+        "code": "NATIVE_PAYLOAD_SOURCE_REQUIRED",
+        "description": "目標架構缺少 path 或 url 來源設定。",
+        "suggestion": "請在 native.yaml 的 targets 內為各架構補上 path 或 url。"
+    },
+    "NATIVE_PAYLOAD_SYMLINK_CYCLE": {
+        "code": "NATIVE_PAYLOAD_SYMLINK_CYCLE",
+        "description": "原生 payload 包含循環符號連結 (Symlink cycle)。",
+        "suggestion": "請移除壓縮檔中的循環 symlink。"
+    },
+    "NATIVE_PAYLOAD_UNSAFE_HARDLINK": {
+        "code": "NATIVE_PAYLOAD_UNSAFE_HARDLINK",
+        "description": "原生 payload hardlink 試圖連結至目標目錄外。",
+        "suggestion": "請確保 hardlink 僅指向 payload 目錄內部的有效檔案。"
+    },
+    "NATIVE_PAYLOAD_UNSAFE_PATH": {
+        "code": "NATIVE_PAYLOAD_UNSAFE_PATH",
+        "description": "原生 payload 含有路徑穿越 (Path traversal) 等不安全路徑。",
+        "suggestion": "請確保壓縮檔內無包含 .. 或絕對路徑的檔案名稱。"
+    },
+    "NATIVE_PAYLOAD_UNSAFE_SYMLINK": {
+        "code": "NATIVE_PAYLOAD_UNSAFE_SYMLINK",
+        "description": "原生 payload symlink 指向了安裝目錄之外。",
+        "suggestion": "請確保 symlink 僅指向 payload 目錄內部的相對目標。"
+    },
+    "NATIVE_PAYLOAD_UNSUPPORTED_ENTRY": {
+        "code": "NATIVE_PAYLOAD_UNSUPPORTED_ENTRY",
+        "description": "原生 payload 包含不支援的特殊檔案類型（如 device node 或 fifo）。",
+        "suggestion": "請從壓縮檔中移除特殊檔案，僅保留一般檔案、目錄與合法 symlink。"
+    },
+    "NATIVE_PAYLOAD_UNSUPPORTED_ZIP": {
+        "code": "NATIVE_PAYLOAD_UNSUPPORTED_ZIP",
+        "description": "不支援的 ZIP 特性（例如 ZIP64、多卷分割或密碼加密）。",
+        "suggestion": "請使用標準未加密的 ZIP 或改用 tar.gz 打包。"
+    },
+    "NATIVE_PAYLOAD_XZ_FAILED": {
+        "code": "NATIVE_PAYLOAD_XZ_FAILED",
+        "description": "解壓縮 tar.xz 失敗。",
+        "suggestion": "請確認本機已安裝 xz 工具且檔案未損壞。"
+    },
+    "NATIVE_PAYLOAD_XZ_UNAVAILABLE": {
+        "code": "NATIVE_PAYLOAD_XZ_UNAVAILABLE",
+        "description": "系統中找不到 xz 指令可用於解壓縮 .tar.xz 檔案。",
+        "suggestion": "請在作業系統中安裝 xz-utils 或改用 tar.gz 格式打包。"
+    },
+    "BUILD_SPK_FAILED": {
+        "code": "BUILD_SPK_FAILED",
+        "description": "SPK 打包流程失敗。",
+        "suggestion": "請檢查 validate 錯誤與目錄檔案權限後重試。"
+    },
+    "VALIDATION_FAILED": {
+        "code": "VALIDATION_FAILED",
+        "description": "專案未通過契約或安全驗證，終止部署。",
+        "suggestion": "請先執行 synopkgland validate 排除合約與 Compose 錯誤。"
+    },
+    "DEPLOY_FAILED": {
+        "code": "DEPLOY_FAILED",
+        "description": "部署至 NAS 時發生未分類錯誤。",
+        "suggestion": "請檢查 NAS 網路連線與日誌：synopkgland log --host <nas>。"
+    },
+    "SHARE_VALUE_REQUIRED": {
+        "code": "SHARE_VALUE_REQUIRED",
+        "description": "部署時缺少合約中宣告的 shared_folder 實際路徑映射。",
+        "suggestion": "請使用 --share <SLOT>=<邏輯名> 提供對應的 Shared Folder 名稱。"
+    },
+    "SHARE_LOGICAL_NAME_REQUIRED": {
+        "code": "SHARE_LOGICAL_NAME_REQUIRED",
+        "description": "Share 參數必須提供邏輯名稱，禁止使用 /volume1/... 等實體路徑。",
+        "suggestion": "請指定 DSM 控制台中的 Shared Folder 邏輯名稱，例如 --share MEDIA_SHARE=photos。"
+    },
+    "SHARE_NOT_FOUND": {
+        "code": "SHARE_NOT_FOUND",
+        "description": "在目標 NAS 上找不到指定的 Shared Folder。",
+        "suggestion": "請在 DSM 控制台建立該 Shared Folder，或檢查名稱拼字。"
+    },
+    "HOMES_NOT_ENABLED": {
+        "code": "HOMES_NOT_ENABLED",
+        "description": "目標 NAS 未啟用 User Home，或無法解析 homes 的實體 bind source。",
+        "suggestion": "請在這台 NAS 啟用 DSM User Home，並確認 DSM API 能回傳解析後的路徑，再重新部署。"
+    },
+    "DSM_USER_LOGICAL_NAME_REQUIRED": {
+        "code": "DSM_USER_LOGICAL_NAME_REQUIRED",
+        "description": "dsm_user 參數必須提供 DSM 使用者邏輯名稱，禁止使用數字 UID。",
+        "suggestion": "請在 --run-as 指定 DSM 使用者帳號名稱（例如 --run-as RUN_AS=alice）。"
+    },
+    "SHARE_RUN_AS_NO_ACCESS": {
+        "code": "SHARE_RUN_AS_NO_ACCESS",
+        "description": "deploy 的安裝前檢查發現選定的 Container Run-as 使用者對選定的 Shared Folder 沒有權限（或被明確拒絕）。容器會以該使用者掛載該 Share，安裝會成功但 runtime 讀寫會拿到 Permission denied。",
+        "suggestion": "請在 DSM 控制台把該 Shared Folder 的權限授予該使用者（或其群組），或改選別的使用者／Share，再重新部署。此檢查只在 deploy 進行；Package Center 安裝精靈不經過這裡，ACL 仍是管理員的前提責任。"
+    },
+    "PORT_ALREADY_IN_USE": {
+        "code": "PORT_ALREADY_IN_USE",
+        "description": "deploy 的安裝前檢查發現 Compose published TCP port 已被其他服務或容器佔用。",
+        "suggestion": "請更換 synology-app.yaml／compose.yaml 的 published host port；同一 Package Identity 的既有容器會在升級或重裝時放行。"
+    },
+    "CATALOG_INSTALL_FAILED": {
+        "code": "CATALOG_INSTALL_FAILED",
+        "description": "NAS Package Center 安裝套件失敗。",
+        "suggestion": "請至 DSM Package Center 檢查安裝日誌或手動嘗試安裝。"
+    },
+    "DEPLOY_PARAM_UNDECLARED": {
+        "code": "DEPLOY_PARAM_UNDECLARED",
+        "description": "deploy --param 提供了契約未宣告的 Install Parameter。",
+        "suggestion": "請只傳 synology-app.yaml install 中宣告的 string 或 boolean 名稱。"
+    },
+    "DEPLOY_PARAM_TYPE_INVALID": {
+        "code": "DEPLOY_PARAM_TYPE_INVALID",
+        "description": "deploy --param 的值不符合契約宣告的 string 或 boolean 型別。",
+        "suggestion": "string 請傳非空字串；boolean 請只傳 true 或 false。"
+    },
+    "DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED": {
+        "code": "DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED",
+        "description": "無法以管理員 session 列出部署當下的 Shared Folder 清單。",
+        "suggestion": "請確認 DSM 管理員 session 可呼叫 SYNO.Core.Share list，或用 --param NAME=... 明確提供清單。"
+    },
+    "DSM_DEPENDENCY_CONFLICT": {
+        "code": "DSM_DEPENDENCY_CONFLICT",
+        "description": "DSM 複合安裝請求因執行中的依賴套件而拒絕。",
+        "suggestion": "請先停止列出的依賴套件再重試升級。"
+    },
+    "DSM_COMPOUND_FAILED": {
+        "code": "DSM_COMPOUND_FAILED",
+        "description": "DSM 複合安裝請求的子步驟失敗。",
+        "suggestion": "請檢查回應中的 api、method、errorCode 與 DSM Package Center 日誌後重試。"
+    },
+    "DSM_REQUEST_FAILED": {
+        "code": "DSM_REQUEST_FAILED",
+        "description": "DSM SYNO.Entry.Request 複合請求失敗。",
+        "suggestion": "請檢查 DSM session、請求參數與 Package Center 日誌後重試。"
+    },
+    "NOT_INSTALLED": {
+        "code": "NOT_INSTALLED",
+        "description": "套件尚未在目標 NAS 上安裝部署。",
+        "suggestion": "請先執行 synopkgland deploy --host <nas> 安裝套件。"
+    },
+    "STANDALONE_MANIFEST_MISSING": {
+        "code": "STANDALONE_MANIFEST_MISSING",
+        "description": "找不到 dsm-package.yaml。",
+        "suggestion": "請在專案根目錄執行，或以 synopkgland init -t native-go 建立專案。"
+    },
+    "STANDALONE_MANIFEST_YAML": {
+        "code": "STANDALONE_MANIFEST_YAML",
+        "description": "dsm-package.yaml 不是合法的 YAML 物件。",
+        "suggestion": "請修正 dsm-package.yaml 的 YAML 語法。"
+    },
+    "STANDALONE_FIELD_UNKNOWN": {
+        "code": "STANDALONE_FIELD_UNKNOWN",
+        "description": "dsm-package.yaml 含有不支援的欄位。",
+        "suggestion": "請移除該欄位；Standalone Package 不接受自訂 lifecycle scripts 或 DSM conf。"
+    },
+    "STANDALONE_SCHEMA_INVALID": {
+        "code": "STANDALONE_SCHEMA_INVALID",
+        "description": "dsm-package.yaml 的 schema 版本不受支援。",
+        "suggestion": "請將 schema 設為 1。"
+    },
+    "STANDALONE_PRIVILEGE_UNSUPPORTED": {
+        "code": "STANDALONE_PRIVILEGE_UNSUPPORTED",
+        "description": "privilege 只能是 none（只以 package 帳號執行）或 root（另加管理員核准的 root 操作）。",
+        "suggestion": "請改為 privilege: none，或用 privilege: root 搭配 root/<名稱>.sh。"
+    },
+    "STANDALONE_ROOT_OPS_MISSING": {
+        "code": "STANDALONE_ROOT_OPS_MISSING",
+        "description": "privilege: root 但沒有任何 root 操作。",
+        "suggestion": "請在 root/ 放至少一個 <名稱>.sh，或改為 privilege: none。"
+    },
+    "STANDALONE_INTEGRATION_INVALID": {
+        "code": "STANDALONE_INTEGRATION_INVALID",
+        "description": "每包 helper 的 integration 宣告不合法。",
+        "suggestion": "使用 native-go、privilege: root、protocol: 1 和 workers map；不要自訂 helper_ 操作。"
+    },
+    "HELPER_WORKER_UNSAFE": {
+        "code": "HELPER_WORKER_UNSAFE",
+        "description": "worker inventory 檔案不在專案內或不是一般檔案。",
+        "suggestion": "使用專案內的一般檔案，不接受 symlink。"
+    },
+    "HELPER_WORKERS_TOO_LARGE": {
+        "code": "HELPER_WORKERS_TOO_LARGE",
+        "description": "worker inventory payload 超過 1 MiB。",
+        "suggestion": "減少 worker inventory 檔案大小。"
+    },
+    "HELPER_TASK_TOO_LARGE": {
+        "code": "HELPER_TASK_TOO_LARGE",
+        "description": "helper task 超過 4095 bytes 保守限制。",
+        "suggestion": "縮短固定 literal；不要內嵌 binary 或將授權改為可寫 script 路徑。"
+    },
+    "HELPER_METADATA_TOO_LARGE": {
+        "code": "HELPER_METADATA_TOO_LARGE",
+        "description": "helper scheduler metadata 超過 8191 bytes 限制。",
+        "suggestion": "減少 metadata 並核對 DSM readback 的 exact script。"
+    },
+    "HELPER_GO_REQUIRED": {
+        "code": "HELPER_GO_REQUIRED",
+        "description": "目前 integration 需要 Go backend。",
+        "suggestion": "使用現有 native-go 模板。"
+    },
+    "HELPER_BUILD_FAILED": {
+        "code": "HELPER_BUILD_FAILED",
+        "description": "Go helper 編譯失敗。",
+        "suggestion": "檢查 Go toolchain 與 backend/cmd/helper 編譯錯誤。"
+    },
+    "HELPER_ARTIFACT_REQUIRED": {
+        "code": "HELPER_ARTIFACT_REQUIRED",
+        "description": "integration SPK 缺少已建置的 helper artifact。",
+        "suggestion": "使用現有 buildStandalone pipeline 建置完整 helper 與 immutable inventory。"
+    },
+    "STANDALONE_ROOT_OP_INVALID": {
+        "code": "STANDALONE_ROOT_OP_INVALID",
+        "description": "root/ 內有不合法的 root 操作檔案。",
+        "suggestion": "每個檔案必須是 root/<小寫名稱>.sh 一般檔案、以 #!/bin/sh 開頭、16 KiB 以內。"
+    },
+    "STANDALONE_ROOT_OPS_UNUSED": {
+        "code": "STANDALONE_ROOT_OPS_UNUSED",
+        "description": "專案有 root/ 資料夾，但 privilege 不是 root。",
+        "suggestion": "要使用 root 操作請設 privilege: root；不需要就刪除 root/。"
+    },
+    "STANDALONE_PACKAGE_INVALID": {
+        "code": "STANDALONE_PACKAGE_INVALID",
+        "description": "package 名稱不合法。",
+        "suggestion": "請使用英文字母開頭、只含英數字的 2–64 字名稱，例如 PhotoTagger。"
+    },
+    "STANDALONE_VERSION_INVALID": {
+        "code": "STANDALONE_VERSION_INVALID",
+        "description": "version 不是數字版本。",
+        "suggestion": "請使用 1.2.0 這類版本，build 號碼另外填在 build。"
+    },
+    "STANDALONE_BUILD_INVALID": {
+        "code": "STANDALONE_BUILD_INVALID",
+        "description": "build 不是 1–9999 的整數。",
+        "suggestion": "請將 build 設為 1–9999 的整數，每次發出 SPK 時遞增。"
+    },
+    "STANDALONE_OS_MIN_VER_INVALID": {
+        "code": "STANDALONE_OS_MIN_VER_INVALID",
+        "description": "os_min_ver 格式不正確。",
+        "suggestion": "請使用 <major>.<minor>-<build>，例如 7.2-64570。"
+    },
+    "STANDALONE_TEXT_INVALID": {
+        "code": "STANDALONE_TEXT_INVALID",
+        "description": "顯示文字欄位不合法。",
+        "suggestion": "請使用單行、非空且不含 \" 或 \\ 的文字。"
+    },
+    "STANDALONE_ARCHES_INVALID": {
+        "code": "STANDALONE_ARCHES_INVALID",
+        "description": "arches 不合法。",
+        "suggestion": "請列出不重複的 x86_64 或 aarch64，至少一個。"
+    },
+    "STANDALONE_ARCH_NOT_DECLARED": {
+        "code": "STANDALONE_ARCH_NOT_DECLARED",
+        "description": "要求建置的架構不在 arches 內。",
+        "suggestion": "請把該架構加入 dsm-package.yaml 的 arches，或改用已宣告的 --arch。"
+    },
+    "STANDALONE_BACKEND_INVALID": {
+        "code": "STANDALONE_BACKEND_INVALID",
+        "description": "backend 設定不合法。",
+        "suggestion": "backend 需恰好包含 go（dir 與 ./ 開頭的 main）或 binary（以架構為 key）其中之一。"
+    },
+    "STANDALONE_BINARY_ARCH_MISSING": {
+        "code": "STANDALONE_BINARY_ARCH_MISSING",
+        "description": "arches 宣告的架構沒有對應的 backend.binary 執行檔。",
+        "suggestion": "請在 backend.binary 補上該架構的執行檔，或從 arches 移除它。"
+    },
+    "STANDALONE_BINARY_MISSING": {
+        "code": "STANDALONE_BINARY_MISSING",
+        "description": "找不到 backend 執行檔。",
+        "suggestion": "請確認 backend.binary 指向的檔案存在。"
+    },
+    "STANDALONE_BINARY_NOT_REGULAR": {
+        "code": "STANDALONE_BINARY_NOT_REGULAR",
+        "description": "backend 執行檔不是一般檔案。",
+        "suggestion": "請改用實際檔案，不可是 symlink、目錄或特殊檔案。"
+    },
+    "STANDALONE_BINARY_TOO_LARGE": {
+        "code": "STANDALONE_BINARY_TOO_LARGE",
+        "description": "backend 執行檔超過 256 MiB。",
+        "suggestion": "請縮小執行檔（例如 -ldflags \"-s -w\"）。"
+    },
+    "STANDALONE_BINARY_NOT_ELF": {
+        "code": "STANDALONE_BINARY_NOT_ELF",
+        "description": "backend 執行檔不是 64-bit little-endian Linux ELF。",
+        "suggestion": "請提供為 Linux 編譯的 x86_64 或 aarch64 執行檔。"
+    },
+    "STANDALONE_BINARY_ARCH_MISMATCH": {
+        "code": "STANDALONE_BINARY_ARCH_MISMATCH",
+        "description": "backend 執行檔的 CPU 架構與目標不符。",
+        "suggestion": "請為該架構重新編譯，或修正 backend.binary 的對應。"
+    },
+    "STANDALONE_BINARY_DYNAMIC": {
+        "code": "STANDALONE_BINARY_DYNAMIC",
+        "description": "backend 執行檔是動態連結。",
+        "suggestion": "請靜態連結（Go 用 CGO_ENABLED=0），DSM 各機型的 libc 版本不同。"
+    },
+    "STANDALONE_PATH_INVALID": {
+        "code": "STANDALONE_PATH_INVALID",
+        "description": "路徑欄位不是專案內的相對路徑。",
+        "suggestion": "請使用相對於專案根目錄的路徑。"
+    },
+    "STANDALONE_PATH_OUTSIDE_PROJECT": {
+        "code": "STANDALONE_PATH_OUTSIDE_PROJECT",
+        "description": "路徑指向專案目錄之外。",
+        "suggestion": "請把檔案放在專案目錄內（symlink 解析後也必須在專案內）。"
+    },
+    "STANDALONE_UI_INVALID": {
+        "code": "STANDALONE_UI_INVALID",
+        "description": "ui 設定不合法。",
+        "suggestion": "請提供 ui.dir。"
+    },
+    "STANDALONE_UI_BUILD_INVALID": {
+        "code": "STANDALONE_UI_BUILD_INVALID",
+        "description": "ui.build 設定不合法。",
+        "suggestion": "ui.build.command 必須是 argv 字串陣列（不經 shell），例如 [npm, run, build]。"
+    },
+    "STANDALONE_IDENTITY_BUILD_FAILED": {
+        "code": "STANDALONE_IDENTITY_BUILD_FAILED",
+        "description": "選用的 Better Auth bundle 建置失敗。",
+        "suggestion": "在 node/ 執行 npm ci 與 npm run build，確認 Node 22 以上。"
+    },
+    "STANDALONE_IDENTITY_PAYLOAD_INVALID": {
+        "code": "STANDALONE_IDENTITY_PAYLOAD_INVALID",
+        "description": "Better Auth bundle 不是專案內的有界一般檔案。",
+        "suggestion": "重新建置 node/dist/app.mjs，移除 symlink 並確認大小。"
+    },
+    "STANDALONE_UI_BUILD_FAILED": {
+        "code": "STANDALONE_UI_BUILD_FAILED",
+        "description": "UI build 指令失敗。",
+        "suggestion": "請在 ui.build.cwd 手動執行該指令並修正錯誤。"
+    },
+    "STANDALONE_UI_ENTRY_MISSING": {
+        "code": "STANDALONE_UI_ENTRY_MISSING",
+        "description": "UI 目錄缺少 app.js 或 app.css。",
+        "suggestion": "請讓 ui.dir（或 UI build 輸出）包含 app.js 與 app.css。"
+    },
+    "STANDALONE_UI_SYMLINK": {
+        "code": "STANDALONE_UI_SYMLINK",
+        "description": "UI 目錄含有 symlink。",
+        "suggestion": "請以實際檔案取代 symlink。"
+    },
+    "STANDALONE_UI_SPECIAL_FILE": {
+        "code": "STANDALONE_UI_SPECIAL_FILE",
+        "description": "UI 目錄含有特殊檔案。",
+        "suggestion": "UI 目錄只能有一般檔案與目錄。"
+    },
+    "STANDALONE_UI_TOO_LARGE": {
+        "code": "STANDALONE_UI_TOO_LARGE",
+        "description": "UI 檔案總大小超過 64 MiB。",
+        "suggestion": "請縮小 UI 資產。"
+    },
+    "STANDALONE_GO_MISSING": {
+        "code": "STANDALONE_GO_MISSING",
+        "description": "找不到 go 指令。",
+        "suggestion": "請安裝 Go 1.24 以上版本（https://go.dev/dl/），或改用 backend.binary 打包既有執行檔。"
+    },
+    "STANDALONE_GO_BUILD_FAILED": {
+        "code": "STANDALONE_GO_BUILD_FAILED",
+        "description": "go build 失敗。",
+        "suggestion": "請在 backend 目錄執行 go build ./... 並修正錯誤。"
+    },
+    "STANDALONE_I18N_INVALID": {
+        "code": "STANDALONE_I18N_INVALID",
+        "description": "dsm-package.yaml 的 i18n 設定不合法。",
+        "suggestion": "i18n 只接受 messages、glossary 與 info；info 以 zh-TW、ja 等支援語言為 key（英文寫在頂層）。"
+    },
+    "STANDALONE_I18N_MESSAGES_MISSING": {
+        "code": "STANDALONE_I18N_MESSAGES_MISSING",
+        "description": "i18n.messages 目錄缺少 en.json。",
+        "suggestion": "請加入 en.json；它是所有語言的後備文字與 key 清單。"
+    },
+    "STANDALONE_I18N_LOCALE_UNSUPPORTED": {
+        "code": "STANDALONE_I18N_LOCALE_UNSUPPORTED",
+        "description": "訊息檔的語言不在支援的九種語言內。",
+        "suggestion": "請使用 en、zh-TW、zh-CN、ja、ko、de、fr、es、it；其他 DSM 語言會顯示英文。"
+    },
+    "STANDALONE_I18N_CATALOG_INVALID": {
+        "code": "STANDALONE_I18N_CATALOG_INVALID",
+        "description": "訊息檔不是扁平的 key → 文字 JSON 物件。",
+        "suggestion": "請改成 { \"greeting.save\": \"Save\" } 這種格式。"
+    },
+    "STANDALONE_I18N_KEYS_MISMATCH": {
+        "code": "STANDALONE_I18N_KEYS_MISMATCH",
+        "description": "某語言的訊息 key 與 en.json 不同。",
+        "suggestion": "請讓每個語言檔都恰好有 en.json 的所有 key。"
+    },
+    "STANDALONE_I18N_PLACEHOLDER_MISMATCH": {
+        "code": "STANDALONE_I18N_PLACEHOLDER_MISMATCH",
+        "description": "翻譯少了或多了 {placeholder}。",
+        "suggestion": "請保留 en.json 文字中的每個 {name} 佔位符。"
+    },
+    "STANDALONE_I18N_GLOSSARY_INVALID": {
+        "code": "STANDALONE_I18N_GLOSSARY_INVALID",
+        "description": "用語表格式錯誤，或指向不存在的訊息 key。",
+        "suggestion": "請修正 glossary.json 的 terms（id、text、keys）。"
+    },
+    "STANDALONE_I18N_GLOSSARY_MISMATCH": {
+        "code": "STANDALONE_I18N_GLOSSARY_MISMATCH",
+        "description": "訊息沒有使用用語表中的 Synology 官方用語。",
+        "suggestion": "請改用 glossary.json 中該語言的用語，與 DSM 介面保持一致。"
+    },
+    "DEPLOY_VERSION_INVALID": {
+        "code": "DEPLOY_VERSION_INVALID",
+        "description": "套件版本無效或低於已安裝版本。",
+        "suggestion": "設定更高的有效 version/build 再部署。"
+    }
 };
 export function getErrorCode(code) {
     return ERROR_REGISTRY[code];