@zhuoyuezs/ml-platform 0.2.8 → 0.2.9

package/CI-ARTIFACT.md

@@ -17,5 +17,5 @@ npm install --global ./zhuoyuezs-ml-platform-*.tgz
 ml-platform version
 ```
 
-运行已安装的 CLI 不需要 Python、`uv`、Git 仓库或平台源码。`uv` 只在 CI 构建阶段用于
-执行现有的 release staging 脚本。
+运行已安装的 CLI 不需要 Python、`uv`、Git 仓库或平台源码。CI 构建阶段使用
+`node:22-bookworm` 中的 Python 3.11 运行 release staging 脚本。

package/checksums.json

@@ -2,23 +2,23 @@
   "files": [
     {
       "path": "runtime/business-client/README.md",
-      "sha256": "sha256:ef7aabd0a1434dbf5d60018e357b018eeb08099de32a9b6a01a89d1f6764bc20",
-      "size_bytes": 17026
+      "sha256": "sha256:9f81e4400f46c53952a0df6f7442d4c0b58cff4ca1be61f1daf785e111b3f8eb",
+      "size_bytes": 20557
     },
     {
       "path": "runtime/business-client/package-lock.json",
-      "sha256": "sha256:706e7515b082fe20d4ad482347e222e41e34cd153c50bb947dc14f795cd5efb6",
+      "sha256": "sha256:9d19700ee4b348406bd0134f0539c37c2800e41a87dc130c1b0476eb2d23b931",
       "size_bytes": 1628
     },
     {
       "path": "runtime/business-client/package.json",
-      "sha256": "sha256:6462d955b53f556056493bb6ee7acb506ced249e58d44532b9395cd8e1be684f",
+      "sha256": "sha256:d967d64289276cf1ce94f826a138f60fc93982b7478c1fb9f78f068f47f9d803",
       "size_bytes": 671
     },
     {
       "path": "runtime/business-client/src/catalog.js",
-      "sha256": "sha256:369259ccfef1b079acf616eca1dc0040dda61cfb4b69941d0fcca30a658cd549",
-      "size_bytes": 58749
+      "sha256": "sha256:94e4b43f248b752d9a9cec42e1f705849f01e4167bb570b9557b556c5be12c19",
+      "size_bytes": 59791
     },
     {
       "path": "runtime/business-client/src/cli-arguments.js",
@@ -27,8 +27,8 @@
     },
     {
       "path": "runtime/business-client/src/cli.js",
-      "sha256": "sha256:cfabcb75a2e2b4e694c9c36390589299abcca3c0fd87e7171ea40b4a29d4e4eb",
-      "size_bytes": 73361
+      "sha256": "sha256:c235053473fb55737dc2c6269a556ed9e4206b074327c0acaf8ac663f1ea00da",
+      "size_bytes": 79409
     },
     {
       "path": "runtime/business-client/src/config.js",
@@ -37,8 +37,8 @@
     },
     {
       "path": "runtime/business-client/src/http.js",
-      "sha256": "sha256:088ef5fa067cc830a95db7d8ad3887ae58276179b524533f338daa781e243979",
-      "size_bytes": 19452
+      "sha256": "sha256:91dc66d086deb5b5c0fd016560e6fddd369ccce9d430ce8f926bcae3f324cc86",
+      "size_bytes": 29035
     },
     {
       "path": "skills/data-source-exploration/SKILL.md",
@@ -52,8 +52,8 @@
     },
     {
       "path": "skills/feature-management/SKILL.md",
-      "sha256": "sha256:6b16afd7fde7949879a9277e29268c203fd42ac1bd630108d3c0101a56db1558",
-      "size_bytes": 34392
+      "sha256": "sha256:1435e380ede73fc9775bd0579ff9df08baf07b4eed8b1bbc174b5b394a72914f",
+      "size_bytes": 35359
     },
     {
       "path": "skills/feature-management/agents/openai.yaml",
@@ -107,18 +107,18 @@
     },
     {
       "path": "skills/feature-management/references/commands.md",
-      "sha256": "sha256:bb6d8508bad62db6987df7d97802a679d5ccfc1fd7eb00f47b61b28396452be6",
-      "size_bytes": 15872
+      "sha256": "sha256:375f953bac0263f9a40d217c99f029226d2a838c9510fce8d6e2324b8f548fb1",
+      "size_bytes": 18288
     },
     {
       "path": "skills/feature-management/references/contracts.md",
-      "sha256": "sha256:a9f6c8d6c8b1220a26a282f3ff73db54c6359372df02c322159087507ca0318d",
-      "size_bytes": 30894
+      "sha256": "sha256:717b81364f8508cd73d52f18d7b5dd012a3f3638921a8a5a93c41991a4f27998",
+      "size_bytes": 38182
     },
     {
       "path": "skills/feature-management/references/operator-authoring.md",
-      "sha256": "sha256:2ecfccbc9fe771bc1103db679d67af78847307eeb440f680f4055c35405ac923",
-      "size_bytes": 6089
+      "sha256": "sha256:68ec5861800a6623db8e3cfae8e3363493c54772c4719d60dc66e4f4f0d3a347",
+      "size_bytes": 12570
     },
     {
       "path": "skills/feature-management/references/platform-capability-guide.md",
@@ -132,8 +132,8 @@
     },
     {
       "path": "skills/model-deployment-management/SKILL.md",
-      "sha256": "sha256:e4ec21765e23a02ad86bd6b0c92414eee182d74a9f7032e738711c823478ecfe",
-      "size_bytes": 4960
+      "sha256": "sha256:84c58dbc71046ead45e3bd1aea55a5f98908e633314dbd088ce6d2c83987011c",
+      "size_bytes": 5195
     },
     {
       "path": "skills/model-deployment-management/agents/openai.yaml",
@@ -147,8 +147,8 @@
     },
     {
       "path": "skills/model-deployment-management/references/operations.md",
-      "sha256": "sha256:2eb0fb62d971e21bfbdc1f398a5dcb91916dfccec35e7cbfa4a6404799bfdfb3",
-      "size_bytes": 6165
+      "sha256": "sha256:262ac8d3ab7524a9b30a14a95550a28821626a8832fd967fe3e9acd015f8c7b2",
+      "size_bytes": 6987
     },
     {
       "path": "skills/model-deployment-management/references/troubleshooting.md",
@@ -157,8 +157,8 @@
     },
     {
       "path": "skills/model-lifecycle-management/SKILL.md",
-      "sha256": "sha256:5880a2f7dc5077767c05f3c2e34be30699d63ea620a08b7ed6944c6b5b29f801",
-      "size_bytes": 6482
+      "sha256": "sha256:55f0172c0b79a04b8ddfeb6bb9f617e7cb5da622b6bd43b3dbae2d3318f6f877",
+      "size_bytes": 7447
     },
     {
       "path": "skills/model-lifecycle-management/agents/openai.yaml",
@@ -167,13 +167,13 @@
     },
     {
       "path": "skills/model-lifecycle-management/references/discovery.md",
-      "sha256": "sha256:ad4623e84b8d972357497a55df0aed84be5ada59ef197f6a217f19ce97821195",
-      "size_bytes": 5789
+      "sha256": "sha256:6ae9afc7169f4e51eefa8ac124b2fa5d9d26bed13ebbc57ec9fbbbcdc6b1960c",
+      "size_bytes": 6643
     },
     {
       "path": "skills/model-lifecycle-management/references/evaluation.md",
-      "sha256": "sha256:e5c82007aa19632565ac3b9862b2c12e896c08f21171985795d342992324a683",
-      "size_bytes": 10310
+      "sha256": "sha256:ba16117c0bf37ac92e28dc9b5e3bda266ac6ad29993c3d4bfcc1c955bb0ab3fa",
+      "size_bytes": 16573
     },
     {
       "path": "skills/model-lifecycle-management/references/model-comparison.md",
@@ -182,18 +182,18 @@
     },
     {
       "path": "skills/model-lifecycle-management/references/packaging.md",
-      "sha256": "sha256:10a30f3408c1c387c215603db4d4aa436ce3bdb925e060139c3283653dd18505",
-      "size_bytes": 7949
+      "sha256": "sha256:da2bde7db390643efbf7a3c8dbb668b0ffe69a1d62ec2dd6436cec5b05cc14ec",
+      "size_bytes": 9921
     },
     {
       "path": "skills/model-lifecycle-management/references/training-contracts.md",
-      "sha256": "sha256:eb774709bc94e07a51a539e1a871202bd7569ae2c4a3d0fa4ebd2b1784ee08a6",
-      "size_bytes": 17803
+      "sha256": "sha256:45568961f933b134e912a20b4ad37d435616d44c3159f302fbccaff2ffe16389",
+      "size_bytes": 27143
     },
     {
       "path": "skills/model-lifecycle-management/references/training.md",
-      "sha256": "sha256:6732128fd6e0ef1fd1d40340bccd4ef555936c9050a7ccbf5ccbfc6c5854a8c3",
-      "size_bytes": 8369
+      "sha256": "sha256:654d3d45bfae4906f7f37898d09fa1fa84ecaab46346190c439f9f3fc0e17f95",
+      "size_bytes": 9691
     },
     {
       "path": "skills/model-lifecycle-management/references/zero-shot-inference.md",
@@ -202,8 +202,8 @@
     },
     {
       "path": "skills/prediction-report-management/SKILL.md",
-      "sha256": "sha256:7c751b1c6176a807f287095ece6463747007f9277afa82abad0c6035f7cbdca5",
-      "size_bytes": 6489
+      "sha256": "sha256:fb1f8c579d392cc4d030d41b5c3b06cd59ab0c488de343bae93cbc87a27dd650",
+      "size_bytes": 8707
     },
     {
       "path": "skills/prediction-report-management/agents/openai.yaml",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuoyuezs/ml-platform",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "ML 数据平台 business CLI 与 Agent Skills 管理工具",
   "bin": {
     "ml-platform": "scripts/main.js"

package/release.json

@@ -13,8 +13,8 @@
     "entrypoint": "src/cli.js",
     "name": "ml-platform",
     "path": "runtime/business-client",
-    "sha256": "sha256:eec6e0e65cf300d6fbfbddcc13bdee6af324409567222454c9ba7abc812a79f3",
-    "version": "0.8.6"
+    "sha256": "sha256:6b8adc18d15ead31da78bd6e4274d17bb7277edcb0d76a9b476ae77a3be22812",
+    "version": "0.8.7"
   },
   "policy_sha256": "sha256:02fbde0134696b78c0c365d6e0b76c9814227208da5b2b3d4e5dbd82dc4a3606",
   "public_schema_versions": [
@@ -25,7 +25,7 @@
     "ml_data_platform.feature_set/v1",
     "ml_data_platform.dataset_manifest/v1"
   ],
-  "release_version": "0.2.8",
+  "release_version": "0.2.9",
   "runtime_requirements": {
     "node": ">=18",
     "os": [
@@ -37,34 +37,34 @@
   "skills": {
     "data-source-exploration": {
       "path": "skills/data-source-exploration",
-      "requires_cli": ">=0.8.6 <0.9.0",
-      "revision": "0.2.8",
+      "requires_cli": ">=0.8.7 <0.9.0",
+      "revision": "0.2.9",
       "sha256": "sha256:6cb1cad3e9531e5098582c532288edd9838c2acab2b324794ec99d2550418f32"
     },
     "feature-management": {
       "path": "skills/feature-management",
-      "requires_cli": ">=0.8.6 <0.9.0",
-      "revision": "0.2.8",
-      "sha256": "sha256:91c59ad073fc6d13ae024ba3f2f5652742ebb7dbee8a0ad4573332e8f009a580"
+      "requires_cli": ">=0.8.7 <0.9.0",
+      "revision": "0.2.9",
+      "sha256": "sha256:2bd8e19ffe43e414fe74a269a75ccfdb88e66c7f2a52df6230a929321dbb54ea"
     },
     "model-deployment-management": {
       "path": "skills/model-deployment-management",
-      "requires_cli": ">=0.8.6 <0.9.0",
-      "revision": "0.2.8",
-      "sha256": "sha256:a83471a2914210065b4354c50b9ddb8f6e4be582739636a116b9098524948a11"
+      "requires_cli": ">=0.8.7 <0.9.0",
+      "revision": "0.2.9",
+      "sha256": "sha256:26cbe95ca26371f3b34a4b83a1f185eeb879f64f099d9dbc30e4cc4ec81d9c64"
     },
     "model-lifecycle-management": {
       "path": "skills/model-lifecycle-management",
-      "requires_cli": ">=0.8.6 <0.9.0",
-      "revision": "0.2.8",
-      "sha256": "sha256:113c673d383cdfb191d3c0efbc91aa0f950e2db0ca03a163209680c6dc1683a0"
+      "requires_cli": ">=0.8.7 <0.9.0",
+      "revision": "0.2.9",
+      "sha256": "sha256:40d8b5eef72a937c208c3607b41666015ac143f604fb0521e0953659306182b2"
     },
     "prediction-report-management": {
       "path": "skills/prediction-report-management",
-      "requires_cli": ">=0.8.6 <0.9.0",
-      "revision": "0.2.8",
-      "sha256": "sha256:671f65e54bf464c7fa46398d4fae31a6317290cf0987fc5c886e56a89309fafc"
+      "requires_cli": ">=0.8.7 <0.9.0",
+      "revision": "0.2.9",
+      "sha256": "sha256:0aee744970236f0357aa9e264e31e144b3cb6fab4a3ea6a01f184dcdaef7e846"
     }
   },
-  "source_commit": "f05d2c98eddd9a4d2cdf47a1d7a3133fc421ffc9"
+  "source_commit": "e0c33cf9f1d052d2a24a574393fdf804438a4543"
 }

package/runtime/business-client/README.md

@@ -81,8 +81,10 @@ ml-platform get-deployment <deployment-id>
 ml-platform get-deployment-events <deployment-id> --limit 100 --offset 0
 ```
 
-`list-deployments` 也支持按 `service`、`environment`、`state` 和自由文本 `q` 过滤，返回平台
-Deployment Controller 管理的部署，不把模型中心回写的 delivery 状态当作平台部署。
+`list-deployments` 支持 `--service` 对 service 名称做不区分大小写的子串匹配（忽略首尾空白），
+也支持按 `environment`、`state` 和跨字段自由文本 `q` 过滤，返回平台
+Deployment Controller 管理的部署，不把模型中心回写的 delivery 状态当作平台部署。列表支持
+`--sort-by created_at|updated_at` 和 `--sort-order asc|desc`，默认按 `deployment_id` 升序。
 
 部署业务分类由平台控制面管理。领域固定为 `power`（电力）、`blast_furnace`（高炉）和
 `other`（其他），场景可按领域自定义：
@@ -126,8 +128,11 @@ ml-platform list-deployments --business-domain-id power --scenario-id energy_sto
       "values": {
         "source": "predictions", "type": "array",
         "items": {"fields": {
+          "date": {"source": "target_time", "format": "%Y-%m-%d", "timezone": "Asia/Shanghai",
+                    "midnight_as_24": true, "type": "string"},
           "time": {"source": "target_time", "format": "%H:%M", "timezone": "Asia/Shanghai",
                     "midnight_as_24": true, "type": "string"},
+          "timestamp": {"source": "target_time", "type": "string"},
           "value": {"source": "value", "type": "number", "scale": 1.0, "offset": 0.0}
         }}
       }
@@ -159,8 +164,11 @@ ml-platform list-deployments --business-domain-id power --scenario-id energy_sto
 `target_time`。`source` 引用平台标准预测结果中的字段；`fields` 生成嵌套对象，`items` 将数组逐项转换，
 `constant` 写入固定值，`template` 可拼接已存在的字符串字段。`format` 可格式化时间；需要按业务时区格式化时，
 同时设置 `timezone`（IANA 名称），例如 `2026-09-10T16:00:00Z` 配置 `Asia/Shanghai` 后得到 `2026-09-11`；
-如果目标接口把本地日界的午夜表达为 `24:00`，在包含 `%H` 的时间格式上设置 `midnight_as_24: true`，例如
-`%H:%M` 会将本地 `00:00` 映射为 `24:00`，其他时刻保持不变；
+如果目标接口把本地日界的午夜表达为前一日的 `24:00`，在业务日期和时间两个字段上均设置
+`midnight_as_24: true` 和 `timezone: "Asia/Shanghai"`：`%Y-%m-%d` 输出前一日，`%H:%M` 输出 `24:00`。
+例如 `2026-10-31T00:00:00+08:00` 对应 `date=2026-10-30`、`time=24:00`，其他时刻保持不变。
+`timestamp` 直接引用 `target_time`，MW 数值直接引用 `value`，不添加格式化或数值换算即可保持原值。
+表示起报本地日期的 `origin_date` 不设置 `midnight_as_24`；
 `scale` 和 `offset` 可执行受控数值换算，`type` 校验最终类型。`token_path`、业务成功码和
 `/forecast/report` 只是示例，必须按目标接口的真实响应和路径配置。
 映射字段缺失或类型不匹配时不会发送请求，Run 会记录 `payload_mapping_failed`。若响应提供有效期，可设置 `expires_in_path` 与 `expires_in_unit`；否则服务端默认按 7200 秒缓存，
@@ -304,10 +312,62 @@ Training Run and Job validation also return `effective_trainer_parameters`;
 for Job preflight it must match `job_spec.trainer_parameters` and represents
 the complete mapping delivered to the Worker after defaults are resolved.
 
+## Artifact file downloads
+
+```bash
+ml-platform download-model-artifact <artifact_id> --out-dir /tmp/model [--file runtime.json] [--project <project>]
+ml-platform download-evaluation-result-artifact <result_id> --out-dir /tmp/eval [--file predictions.parquet]
+ml-platform download-dataset-artifact <dataset_id> <artifact_manifest_hash> --project <project> --out-dir /tmp/ds
+```
+
+The lifecycle commands read the registry file index (`get-model-artifact` /
+`get-evaluation-result-artifacts`), download every indexed file or each
+repeated `--file`, and keep a file only when its sha256 equals the registry
+record; a mismatch removes the output directory. Names outside the index fail
+before any file request. They call the read-only
+`GET /model-artifacts/{id}/files/{path}` and
+`GET /evaluation-results/{id}/files/{path}` routes, which verify the sha256
+server-side, accept an optional `project` scope, and refuse files above
+`DATA_PLATFORM_LIFECYCLE_ARTIFACT_FILE_MAX_BYTES` (default 2 GiB).
+
+A DatasetArtifact is keyed by the artifact manifest hash, not the registered
+manifest hash. `build-dataset --wait`, `build-registered-dataset --wait` and
+`wait-job` add an `artifact` object (`project`, `dataset_id`,
+`dataset_version`, `manifest_hash`, `artifact_uri`, `row_count`) to a succeeded
+build Job; use `artifact.manifest_hash` for downloads and dataset bindings. The
+Job's top-level `manifest_hash` is unchanged.
+
+`--idempotency-key` on `create-project`, `register-training-run`,
+`submit-training-job`, `register-evaluation-config`, `submit-evaluation` and
+`create-model-package` is sent as the `Idempotency-Key` header, which the
+current server does not enforce. Inspect platform state before retrying an
+uncertain submission.
+
 Maintainers can export the current API, including uncommitted schema changes,
 with `uv run python scripts/generate_openapi_schema.py --working-tree` from the
 repository root; use `--check` with it to verify the committed snapshot.
 
+## Connection handling
+
+Every request is sent with `Connection: close`, so the CLI never writes a new
+request onto a pooled keep-alive socket that the API (uvicorn closes idle
+sockets after 5 s) or a slow VPN path has already dropped. Connection errors
+report the underlying cause, for example
+`fetch failed (UND_ERR_SOCKET: other side closed)` or
+`request timed out after 30s (...)`.
+
+Automatic retry (at most 3 retries, 0.5 s / 1 s / 2 s backoff, each attempt
+with its own `--timeout`) happens only before response headers arrive:
+
+- `GET`/`HEAD` (including `wait-job` polling and downloads): connection
+  errors such as `ECONNREFUSED`, `ECONNRESET`, `UND_ERR_SOCKET`,
+  `UND_ERR_CONNECT_TIMEOUT`, and the request timeout.
+- `POST`/`PUT`/`PATCH`/`DELETE`: only `ECONNREFUSED` and
+  `UND_ERR_CONNECT_TIMEOUT`, where no TCP connection existed and the request
+  cannot have reached the server. Any other failure is reported once with
+  `not retried because the server may have received it`; inspect platform
+  state before resubmitting.
+
 ## Agent 宿主接入
 
 Coding agent 加载已安装的 Skills 后，通过原生 shell/exec 直接运行普通 `ml-platform` 命令。

package/runtime/business-client/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@zhuoyuezs/ml-platform-business-client",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@zhuoyuezs/ml-platform-business-client",
-      "version": "0.8.6",
+      "version": "0.8.7",
       "license": "UNLICENSED",
       "bin": {
         "ml-platform": "src/cli.js"

package/runtime/business-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuoyuezs/ml-platform-business-client",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "private": true,
   "description": "JavaScript implementation of the ML Platform business client",
   "bin": {

package/runtime/business-client/src/catalog.js

@@ -454,11 +454,27 @@ function canonical(value) { if (Array.isArray(value))
     return value.map(canonical); if (value && typeof value === "object")
     return Object.fromEntries(Object.keys(value).sort().map((name) => [name, canonical(value[name])])); return value; }
 function equal(left, right) { return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right)); }
-function assertImmutable(label, assetKey, candidate, existing) { if (existing && !equal(candidate, existing)) {
-    const error = new Error(`${label} version is immutable: ${assetKey}`);
-    error.code = "EEXIST";
-    throw error;
-} }
+function immutableError(label, assetKey) { const error = new Error(`${label} version is immutable: ${assetKey}`); error.code = "EEXIST"; return error; }
+function assertImmutable(label, assetKey, candidate, existing) { if (existing && !equal(candidate, existing))
+    throw immutableError(label, assetKey); }
+// A registered DatasetManifest carries server-filled defaults, including nested ones, that a catalog may
+// omit. A raw mismatch is therefore settled by the server's normalized contract hash; servers without
+// /datasets/validate keep the raw-comparison conflict.
+async function assertDatasetImmutable(client, assetKey, candidate, existing) {
+    if (!existing || equal(candidate, existing))
+        return;
+    let result;
+    try {
+        result = await client.post("/datasets/validate", candidate);
+    }
+    catch (error) {
+        if (/HTTP 40[45]\b/.test(String(error.message)))
+            throw immutableError("datasets", assetKey);
+        throw error;
+    }
+    if (!result?.registered_manifest_hash || result.manifest_hash !== result.registered_manifest_hash)
+        throw immutableError("datasets", assetKey);
+}
 function sha256File(file) { return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex")}`; }
 async function applyCatalog(catalog, client, dryRun, targetProject) {
     validateCatalogProject(catalog, targetProject);
@@ -483,7 +499,10 @@ async function applyCatalog(catalog, client, dryRun, targetProject) {
     }
     const plain = async (assets, existing, label, endpoint, keyFn = key, params) => { for (const asset of assets) {
         const assetKey = keyFn(asset);
-        assertImmutable(label, assetKey, asset, existing.get(assetKey));
+        if (label === "datasets")
+            await assertDatasetImmutable(client, assetKey, asset, existing.get(assetKey));
+        else
+            assertImmutable(label, assetKey, asset, existing.get(assetKey));
         if (existing.has(assetKey))
             summary[label].unchanged += 1;
         else if (dryRun)

package/runtime/business-client/src/cli.js

@@ -25,7 +25,7 @@ const BUSINESS_COMMANDS = new Set([
     "get-parameter", "get-feature", "get-feature-set", "get-operator",
     "delete-parameter", "delete-feature", "delete-feature-set",
     "restore-parameter", "restore-feature", "restore-feature-set",
-    "get-parameter-lifecycle", "get-feature-lifecycle", "get-feature-set-lifecycle",
+    "get-parameter-lifecycle", "get-feature-lifecycle", "get-feature-set-lifecycle", "get-parameter-freshness",
     "list-parameter-references", "list-feature-references", "list-feature-set-references",
     "list-parameter-versions", "list-feature-versions", "list-feature-set-versions", "list-operator-versions",
     "add-parameter", "add-feature", "add-feature-set", "add-operator", "publish-operator",
@@ -38,6 +38,7 @@ const BUSINESS_COMMANDS = new Set([
     "register-executable-package", "verify-executable-package", "publish-executable-package",
     "validate-evaluation-run", "submit-evaluation", "get-evaluation-run", "get-evaluation-job", "retry-evaluation-job", "cancel-evaluation-job", "list-evaluation-attempts",
     "get-evaluation-result", "get-evaluation-result-metrics", "get-evaluation-result-artifacts", "summarize-evaluation-run", "get-evaluation-summary",
+    "download-model-artifact", "download-evaluation-result-artifact",
     "create-model-package", "get-model-package", "cancel-model-package", "validate-model-artifact", "register-model-artifact",
     "list-business-domains", "list-scenarios", "create-scenario", "put-deployment-metadata",
     "list-deployment-targets", "validate-deployment", "create-deployment", "list-deployments",
@@ -91,6 +92,7 @@ const COMMAND_USAGE = {
     "restore-feature": "restore-feature NAME VERSION [--project PROJECT] [--actor ACTOR] [--reason TEXT] [--idempotency-key KEY]",
     "restore-feature-set": "restore-feature-set NAME VERSION [--project PROJECT] [--actor ACTOR] [--reason TEXT] [--idempotency-key KEY]",
     "get-parameter-lifecycle": "get-parameter-lifecycle NAME VERSION [--project PROJECT]",
+    "get-parameter-freshness": "get-parameter-freshness NAME VERSION [--project PROJECT] [--lookback DURATION] [--end TIMESTAMP] [--online]",
     "get-feature-lifecycle": "get-feature-lifecycle NAME VERSION [--project PROJECT]",
     "get-feature-set-lifecycle": "get-feature-set-lifecycle NAME VERSION [--project PROJECT]",
     "list-parameter-references": "list-parameter-references NAME VERSION [--project PROJECT] [--direct]",
@@ -159,6 +161,8 @@ const COMMAND_USAGE = {
     "get-evaluation-result": "get-evaluation-result RESULT_ID",
     "get-evaluation-result-metrics": "get-evaluation-result-metrics RESULT_ID",
     "get-evaluation-result-artifacts": "get-evaluation-result-artifacts RESULT_ID",
+    "download-model-artifact": "download-model-artifact ARTIFACT_ID --out-dir PATH [--file NAME] [--project PROJECT] [--force]",
+    "download-evaluation-result-artifact": "download-evaluation-result-artifact RESULT_ID --out-dir PATH [--file NAME] [--project PROJECT] [--force]",
     "summarize-evaluation-run": "summarize-evaluation-run RUN_ID",
     "get-evaluation-summary": "get-evaluation-summary SUMMARY_ID",
     "create-model-package": "create-model-package REQUEST_JSON [--idempotency-key KEY]",
@@ -173,7 +177,7 @@ const COMMAND_USAGE = {
     "list-deployment-targets": "list-deployment-targets",
     "validate-deployment": "validate-deployment SPEC_JSON --evaluation-id ID",
     "create-deployment": "create-deployment SPEC_JSON --evaluation-id ID",
-    "list-deployments": "list-deployments [--service SERVICE] [--environment ENV] [--package-id ID] [--package-version VERSION] [--model-artifact-id ID] [--state STATE] [--business-domain-id ID] [--scenario-id ID] [-q QUERY] [--limit N] [--offset N]",
+    "list-deployments": "list-deployments [--service TEXT] [--environment ENV] [--package-id ID] [--package-version VERSION] [--model-artifact-id ID] [--state STATE] [--business-domain-id ID] [--scenario-id ID] [-q QUERY] [--sort-by deployment_id|created_at|updated_at] [--sort-order asc|desc] [--limit N] [--offset N]",
     "get-deployment": "get-deployment DEPLOYMENT_ID",
     "wait-deployment": "wait-deployment DEPLOYMENT_ID [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
     "reconcile-deployment": "reconcile-deployment DEPLOYMENT_ID",
@@ -200,10 +204,22 @@ const COMMAND_USAGE = {
     "get-prediction-report-run": "get-prediction-report-run RUN_ID",
     apply: "apply CATALOG_DIRECTORY [--dry-run] [--project PROJECT]",
 };
+const IDEMPOTENCY_HEADER_NOTE = "--idempotency-key is sent as the Idempotency-Key header; the current server does not enforce it, so inspect platform state before retrying an uncertain submission.";
+const BUILD_WAIT_NOTE = "With --wait, a succeeded result adds artifact.manifest_hash: the DatasetArtifact key for get/download-dataset-artifact and training/evaluation dataset bindings. The top-level manifest_hash identifies the submitted manifest and is not an artifact key.";
+// Help-only notes. Keep them out of COMMAND_USAGE, which is also the argv grammar.
+const COMMAND_NOTES = {
+    "download-dataset-artifact": "MANIFEST_HASH is the artifact manifest hash (list-dataset-artifacts, or artifact.manifest_hash from build-registered-dataset --wait), not the registered manifest hash.",
+    "build-dataset": BUILD_WAIT_NOTE,
+    "build-registered-dataset": BUILD_WAIT_NOTE,
+    "wait-job": "A succeeded build Job result adds artifact.manifest_hash, the DatasetArtifact key.",
+    "download-model-artifact": "Downloads every indexed ModelArtifact file, or only each --file NAME, and verifies each sha256 against the registry record. --project fails closed when the artifact belongs to another project.",
+    "download-evaluation-result-artifact": "Downloads every indexed EvaluationResult file (for example predictions.parquet, metrics.json, runtime.json), or only each --file NAME, and verifies each sha256 against the registry record.",
+    ...Object.fromEntries(["create-project", "register-training-run", "submit-training-job", "register-evaluation-config", "submit-evaluation", "create-model-package"].map((name) => [name, IDEMPOTENCY_HEADER_NOTE])),
+};
 function usage(command) {
     const prefix = "ml-platform [--profile server] [--api-url URL] [--request-timeout-seconds SECONDS]";
     if (command)
-        return `usage: ${prefix} ${COMMAND_USAGE[command]}\n`;
+        return `usage: ${prefix} ${COMMAND_USAGE[command]}\n${COMMAND_NOTES[command] ? `\n${COMMAND_NOTES[command]}\n` : ""}`;
     return `usage: ${prefix} COMMAND [ARGS]\n\ncommands:\n  ${[...BUSINESS_COMMANDS].join("\n  ")}\n`;
 }
 function parse(args) {
@@ -363,12 +379,33 @@ async function submitBuild(api, manifest, build) {
     if (build.wait) {
         if (!result || typeof result !== "object" || !result.job_id)
             throw new Error("server build did not return a job_id to wait for");
-        result = await waitForJob(api, String(result.job_id), build.pollInterval, build.waitTimeout);
+        result = withBuildArtifact(await waitForJob(api, String(result.job_id), build.pollInterval, build.waitTimeout));
         if (["failed", "cancelled"].includes(result.status))
             exitCode = 1;
     }
     return { result, exitCode };
 }
+// A build Job's top-level manifest_hash identifies the submitted (registered)
+// manifest. The published DatasetArtifact is keyed by the resolved contract hash,
+// so surface it additively as `artifact` for downloads and dataset bindings.
+function withBuildArtifact(job) {
+    if (!job || typeof job !== "object" || Array.isArray(job) || job.status !== "succeeded")
+        return job;
+    const resolved = job.resolved_manifest;
+    if (!resolved || typeof resolved !== "object" || !resolved.manifest_hash)
+        return job;
+    return {
+        ...job,
+        artifact: {
+            project: resolved.project ?? job.manifest?.project ?? "default",
+            dataset_id: resolved.dataset_id ?? job.manifest?.dataset_id ?? null,
+            dataset_version: resolved.dataset_version ?? job.manifest?.dataset_version ?? null,
+            manifest_hash: resolved.manifest_hash,
+            artifact_uri: resolved.artifact_uri ?? null,
+            row_count: resolved.row_count ?? null,
+        },
+    };
+}
 async function waitForJob(api, jobId, pollInterval, timeoutSeconds) {
     if (!(pollInterval > 0))
         throw new Error("job poll interval must be positive");
@@ -559,6 +596,21 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
             actor: take(rest, "--actor") || "anonymous", reason: take(rest, "--reason", ""), idempotency_key: take(rest, "--idempotency-key"),
         });
     }
+    else if (options.command === "get-parameter-freshness") {
+        const name = positional(rest, "parameter name");
+        const version = positional(rest, "parameter version");
+        const project = take(rest, "--project", "default");
+        const params = {};
+        const lookback = take(rest, "--lookback");
+        const end = take(rest, "--end");
+        if (lookback !== undefined)
+            params.lookback = lookback;
+        if (end !== undefined)
+            params.end = end;
+        if (boolean(rest, "--online"))
+            params.online = true;
+        result = await client(options).get(`/parameters/${encodeURIComponent(project)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}/freshness`, params);
+    }
     else if (/^get-(parameter|feature|feature-set)-lifecycle$/.test(options.command)) {
         const name = positional(rest, "resource name");
         const version = positional(rest, "resource version");
@@ -730,7 +782,7 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
         const jobId = positional(rest, "job id");
         const poll = finiteNumber(take(rest, "--poll-interval", 2), "--poll-interval");
         const rawTimeout = take(rest, "--wait-timeout-seconds");
-        result = await waitForJob(client(options), jobId, poll, rawTimeout === undefined ? undefined : finiteNumber(rawTimeout, "--wait-timeout-seconds"));
+        result = withBuildArtifact(await waitForJob(client(options), jobId, poll, rawTimeout === undefined ? undefined : finiteNumber(rawTimeout, "--wait-timeout-seconds")));
         if (["failed", "cancelled"].includes(result.status))
             exitCode = 1;
     }
@@ -868,6 +920,8 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
             business_domain_id: take(rest, "--business-domain-id"),
             scenario_id: take(rest, "--scenario-id"),
             q: take(rest, "--q", take(rest, "-q")),
+            sort_by: take(rest, "--sort-by"),
+            sort_order: take(rest, "--sort-order"),
         };
         boolean(rest, "--all");
         result = await listCollection(client(options), "/deployments", params, rest);
@@ -1074,6 +1128,36 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
         const suffix = options.command.endsWith("-metrics") ? "/metrics" : options.command.endsWith("-artifacts") ? "/artifacts" : "";
         result = await client(options).get(`/evaluation-results/${encodeURIComponent(resultId)}${suffix}`);
     }
+    else if (options.command === "download-model-artifact" || options.command === "download-evaluation-result-artifact") {
+        const model = options.command === "download-model-artifact";
+        const resourceId = positional(rest, model ? "model artifact id" : "evaluation result id");
+        const outDir = take(rest, "--out-dir");
+        const project = take(rest, "--project");
+        const force = boolean(rest, "--force");
+        if (!outDir)
+            throw new Error("--out-dir is required");
+        const files = [];
+        while (rest.includes("--file"))
+            files.push(take(rest, "--file"));
+        const api = client(options);
+        let index;
+        let owner = project;
+        if (model) {
+            const record = await api.get(`/model-artifacts/${encodeURIComponent(resourceId)}`);
+            if (project !== undefined && record.project !== project)
+                throw new Error(`model artifact ${resourceId} belongs to project ${JSON.stringify(record.project)}, not ${JSON.stringify(project)}`);
+            index = record.files;
+            owner = record.project;
+        }
+        else {
+            const listing = await api.get(`/evaluation-results/${encodeURIComponent(resourceId)}/artifacts`);
+            if (!Array.isArray(listing.items))
+                throw new Error("evaluation result artifact listing has no items");
+            index = Object.fromEntries(listing.items.map((item) => [String(item.name), String(item.sha256)]));
+        }
+        const downloaded = await api.downloadLifecycleArtifactFiles(model ? "model-artifacts" : "evaluation-results", resourceId, index, files, resolvedPath(outDir), { force, project });
+        result = { [model ? "model_artifact_id" : "result_id"]: resourceId, ...downloaded, project: owner ?? null };
+    }
     else if (/^(get-evaluation-config|get-metric-definition)$/.test(options.command)) {
         const name = positional(rest, "resource name");
         const version = positional(rest, "resource version");
@@ -1137,7 +1221,7 @@ async function listCollection(api, endpoint, params, rest) {
         throw new Error("offset must be >= 0");
     return api.get(endpoint, { ...params, limit, offset });
 }
-module.exports = { BUSINESS_COMMANDS, fetchAll, listCollection, parse, runBusinessCli, usage, waitForDeployment, waitForJob };
+module.exports = { BUSINESS_COMMANDS, COMMAND_NOTES, withBuildArtifact, fetchAll, listCollection, parse, runBusinessCli, usage, waitForDeployment, waitForJob };
 if (require.main === module) {
     runBusinessCli(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => {
         process.stderr.write(`error: ${error.message}\n`);