@zhuoyuezs/ml-platform 0.2.6 → 0.2.8

package/checksums.json

@@ -2,17 +2,17 @@
   "files": [
     {
       "path": "runtime/business-client/README.md",
-      "sha256": "sha256:e0bf5707e13eb8bc36b530741a476827eef8263f23ff796f064dc0bfae9a8bfb",
-      "size_bytes": 14154
+      "sha256": "sha256:ef7aabd0a1434dbf5d60018e357b018eeb08099de32a9b6a01a89d1f6764bc20",
+      "size_bytes": 17026
     },
     {
       "path": "runtime/business-client/package-lock.json",
-      "sha256": "sha256:744e49f72a879478a18899c6eb64cf3bbdc22700e9d8a4b61d45ad3a5927deb9",
+      "sha256": "sha256:706e7515b082fe20d4ad482347e222e41e34cd153c50bb947dc14f795cd5efb6",
       "size_bytes": 1628
     },
     {
       "path": "runtime/business-client/package.json",
-      "sha256": "sha256:97145119a4080392bbd2242b6a5a67046aa45e720c38977686fa0f4346c41bf0",
+      "sha256": "sha256:6462d955b53f556056493bb6ee7acb506ced249e58d44532b9395cd8e1be684f",
       "size_bytes": 671
     },
     {
@@ -20,10 +20,15 @@
       "sha256": "sha256:369259ccfef1b079acf616eca1dc0040dda61cfb4b69941d0fcca30a658cd549",
       "size_bytes": 58749
     },
+    {
+      "path": "runtime/business-client/src/cli-arguments.js",
+      "sha256": "sha256:7e18df77a96a8a88035573406e26dc70f803211699021933a28c8e922ee38712",
+      "size_bytes": 2251
+    },
     {
       "path": "runtime/business-client/src/cli.js",
-      "sha256": "sha256:6ad8fb06e410cb5a197a696f3cb9819e9e3b06919d443d303a3e9d285cf4c0e2",
-      "size_bytes": 68793
+      "sha256": "sha256:cfabcb75a2e2b4e694c9c36390589299abcca3c0fd87e7171ea40b4a29d4e4eb",
+      "size_bytes": 73361
     },
     {
       "path": "runtime/business-client/src/config.js",
@@ -47,8 +52,8 @@
     },
     {
       "path": "skills/feature-management/SKILL.md",
-      "sha256": "sha256:1118aef3734fe14fd8f7d1074ff730340663e42565155bde984ab5b397c2da77",
-      "size_bytes": 33777
+      "sha256": "sha256:6b16afd7fde7949879a9277e29268c203fd42ac1bd630108d3c0101a56db1558",
+      "size_bytes": 34392
     },
     {
       "path": "skills/feature-management/agents/openai.yaml",
@@ -102,8 +107,8 @@
     },
     {
       "path": "skills/feature-management/references/commands.md",
-      "sha256": "sha256:ffd106cd785fe0d07ee20f51b7f55ca520da2fc6367bc5bc1ec0218600146d6e",
-      "size_bytes": 13905
+      "sha256": "sha256:bb6d8508bad62db6987df7d97802a679d5ccfc1fd7eb00f47b61b28396452be6",
+      "size_bytes": 15872
     },
     {
       "path": "skills/feature-management/references/contracts.md",
@@ -122,8 +127,8 @@
     },
     {
       "path": "skills/feature-management/references/supervised-datasets.md",
-      "sha256": "sha256:2c7a894330a649248e7f52c944422bcd7a3aba4558f7984d129dfd21c8736cf3",
-      "size_bytes": 4540
+      "sha256": "sha256:2c23ed96c49af1954864660bf8d13f3114bb03a6598e20df6abbc191c5986e2b",
+      "size_bytes": 10024
     },
     {
       "path": "skills/model-deployment-management/SKILL.md",
@@ -152,8 +157,8 @@
     },
     {
       "path": "skills/model-lifecycle-management/SKILL.md",
-      "sha256": "sha256:785219483f917d83d9a371772ea107dc03ddf024a0c4bd098711c4689c5c2ce4",
-      "size_bytes": 5718
+      "sha256": "sha256:5880a2f7dc5077767c05f3c2e34be30699d63ea620a08b7ed6944c6b5b29f801",
+      "size_bytes": 6482
     },
     {
       "path": "skills/model-lifecycle-management/agents/openai.yaml",
@@ -167,8 +172,13 @@
     },
     {
       "path": "skills/model-lifecycle-management/references/evaluation.md",
-      "sha256": "sha256:4314e65b162f0a72c5c5e6411186340661c853551dc8b2ebce3597680acef117",
-      "size_bytes": 9477
+      "sha256": "sha256:e5c82007aa19632565ac3b9862b2c12e896c08f21171985795d342992324a683",
+      "size_bytes": 10310
+    },
+    {
+      "path": "skills/model-lifecycle-management/references/model-comparison.md",
+      "sha256": "sha256:cb97b16476e28d3ca6f984ef2a964f936227bbb28a11570bbcd86f6ea51bccba",
+      "size_bytes": 9359
     },
     {
       "path": "skills/model-lifecycle-management/references/packaging.md",
@@ -177,13 +187,13 @@
     },
     {
       "path": "skills/model-lifecycle-management/references/training-contracts.md",
-      "sha256": "sha256:26ca0f0b8bc212bd30ea69b0a0afc169554681a16317ebb054d9147ae9c0587a",
-      "size_bytes": 14994
+      "sha256": "sha256:eb774709bc94e07a51a539e1a871202bd7569ae2c4a3d0fa4ebd2b1784ee08a6",
+      "size_bytes": 17803
     },
     {
       "path": "skills/model-lifecycle-management/references/training.md",
-      "sha256": "sha256:ae87837e5c315aa0fc9c02575213e1fd293f192ed43a1c68e9f8d08407becc48",
-      "size_bytes": 8235
+      "sha256": "sha256:6732128fd6e0ef1fd1d40340bccd4ef555936c9050a7ccbf5ccbfc6c5854a8c3",
+      "size_bytes": 8369
     },
     {
       "path": "skills/model-lifecycle-management/references/zero-shot-inference.md",
@@ -192,8 +202,8 @@
     },
     {
       "path": "skills/prediction-report-management/SKILL.md",
-      "sha256": "sha256:35242893137502ece779eb3b66f0d5a2e36d10dd944af5e2fead20547c7866e3",
-      "size_bytes": 5923
+      "sha256": "sha256:7c751b1c6176a807f287095ece6463747007f9277afa82abad0c6035f7cbdca5",
+      "size_bytes": 6489
     },
     {
       "path": "skills/prediction-report-management/agents/openai.yaml",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuoyuezs/ml-platform",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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:3cf1b6b441fc99bfc8e1615f7c0949a3234da0e4ccaa70fca2ddb4ed7b96cae4",
-    "version": "0.8.5"
+    "sha256": "sha256:eec6e0e65cf300d6fbfbddcc13bdee6af324409567222454c9ba7abc812a79f3",
+    "version": "0.8.6"
   },
   "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.6",
+  "release_version": "0.2.8",
   "runtime_requirements": {
     "node": ">=18",
     "os": [
@@ -37,34 +37,34 @@
   "skills": {
     "data-source-exploration": {
       "path": "skills/data-source-exploration",
-      "requires_cli": ">=0.8.5 <0.9.0",
-      "revision": "0.2.6",
+      "requires_cli": ">=0.8.6 <0.9.0",
+      "revision": "0.2.8",
       "sha256": "sha256:6cb1cad3e9531e5098582c532288edd9838c2acab2b324794ec99d2550418f32"
     },
     "feature-management": {
       "path": "skills/feature-management",
-      "requires_cli": ">=0.8.5 <0.9.0",
-      "revision": "0.2.6",
-      "sha256": "sha256:6dfa708172c3b5b23af75997c82a6d43bc2eb8ca67cc2275c8b95022455b0c42"
+      "requires_cli": ">=0.8.6 <0.9.0",
+      "revision": "0.2.8",
+      "sha256": "sha256:91c59ad073fc6d13ae024ba3f2f5652742ebb7dbee8a0ad4573332e8f009a580"
     },
     "model-deployment-management": {
       "path": "skills/model-deployment-management",
-      "requires_cli": ">=0.8.5 <0.9.0",
-      "revision": "0.2.6",
+      "requires_cli": ">=0.8.6 <0.9.0",
+      "revision": "0.2.8",
       "sha256": "sha256:a83471a2914210065b4354c50b9ddb8f6e4be582739636a116b9098524948a11"
     },
     "model-lifecycle-management": {
       "path": "skills/model-lifecycle-management",
-      "requires_cli": ">=0.8.5 <0.9.0",
-      "revision": "0.2.6",
-      "sha256": "sha256:0f63e9122b55a72a11258d517b7eb378d84ef7e64ea9b613491c910e6ed8efc8"
+      "requires_cli": ">=0.8.6 <0.9.0",
+      "revision": "0.2.8",
+      "sha256": "sha256:113c673d383cdfb191d3c0efbc91aa0f950e2db0ca03a163209680c6dc1683a0"
     },
     "prediction-report-management": {
       "path": "skills/prediction-report-management",
-      "requires_cli": ">=0.8.5 <0.9.0",
-      "revision": "0.2.6",
-      "sha256": "sha256:3a6991eec5cfa6bf30eaf43295f0c7d5c1e70e4f638904dfde1be2a39965d64f"
+      "requires_cli": ">=0.8.6 <0.9.0",
+      "revision": "0.2.8",
+      "sha256": "sha256:671f65e54bf464c7fa46398d4fae31a6317290cf0987fc5c886e56a89309fafc"
     }
   },
-  "source_commit": "working-tree-request-time-mixed-availability"
+  "source_commit": "f05d2c98eddd9a4d2cdf47a1d7a3133fc421ffc9"
 }

package/runtime/business-client/README.md

@@ -20,6 +20,8 @@ node business-client-js/src/cli.js --help
 ml-platform list-datasets --project <project>
 ml-platform get-dataset <dataset_id> <dataset_version> --project <project>
 ml-platform resolve-dataset <dataset_id> <dataset_version> --project <project>
+ml-platform build-registered-dataset <dataset_id> <dataset_version> \
+  --project <project> --plan
 ml-platform build-registered-dataset <dataset_id> <dataset_version> \
   --project <project> --wait
 ml-platform register-model-artifact <artifact_id> --evaluation-id <evaluation_result_or_summary_id>
@@ -34,6 +36,15 @@ ml-platform register-model-artifact <artifact_id> --evaluation-id <evaluation_re
 `resolve-manifest` 和 `build-dataset <manifest.json>` 仍用于尚未注册的本地契约。Catalog
 normalizer 保留并校验非默认 `project`；`apply --project` 与 Catalog 内项目不一致时拒绝执行。
 
+两个 build 命令默认 `--partition-duration auto`，按目标行数、输出宽度和源读取包络选择
+分区。`--plan` 只读预览，不创建 Job，与 `--wait` 互斥。返回估算、原因及限制；
+提交时固定具体时长，重试不重新选择。`--partition-duration 7d` 可显式覆盖，
+`--partition-duration none` 保留不分区。软目标可通过 `--target-partition-rows`、
+`--target-partition-source-rows`、`--target-partition-cells` 调整，默认分别为
+50000、500000、1000000；并非内存或耗时承诺，并行度当前仍为 1。
+此流程需要 API 支持 `/datasets/build-plan` 和 `partition_duration=auto`；应配套升级，
+不自动回退为未经预览的提交。API 省略时长仍保留原兼容语义。
+
 同一 Parameter 需要从历史库训练、从实时库取数时，在 Parameter JSON 同时填写 `source` 与
 可选的 `online_source`，然后照常使用 `add-parameter` 或 Catalog `apply`；CLI 原样透传该
 字段，不需要额外参数。离线构建读取 `source`，实时因果读取自动选择 `online_source`。
@@ -73,6 +84,22 @@ ml-platform get-deployment-events <deployment-id> --limit 100 --offset 0
 `list-deployments` 也支持按 `service`、`environment`、`state` 和自由文本 `q` 过滤，返回平台
 Deployment Controller 管理的部署，不把模型中心回写的 delivery 状态当作平台部署。
 
+部署业务分类由平台控制面管理。领域固定为 `power`（电力）、`blast_furnace`（高炉）和
+`other`（其他），场景可按领域自定义：
+
+```bash
+ml-platform list-business-domains
+ml-platform list-scenarios --business-domain-id power
+ml-platform create-scenario /absolute/path/to/scenario.json
+ml-platform put-deployment-metadata <deployment-id> /absolute/path/to/metadata.json
+ml-platform list-deployments --business-domain-id power --scenario-id energy_storage
+```
+
+场景 JSON 包含 `scenario_id`、`business_domain_id`、`name`。元数据 JSON 包含
+`display_name`、`description`、`scenario_id`、可选 `updated_by`；保存采用完整替换，
+省略场景或传 `null` 清除归属，操作不会创建部署 revision 或触发模型重启。
+完整示例见[部署业务分类](../docs/designs/model-deployment-management.md#7-部署业务分类)。
+
 ## Prediction reporting
 
 定时预测上报通过业务 CLI 管理版本化推送目标、计划与运行记录。下面的 JSON 是字段示例，
@@ -99,7 +126,8 @@ Deployment Controller 管理的部署，不把模型中心回写的 delivery 状
       "values": {
         "source": "predictions", "type": "array",
         "items": {"fields": {
-          "time": {"source": "target_time", "type": "string"},
+          "time": {"source": "target_time", "format": "%H:%M", "timezone": "Asia/Shanghai",
+                    "midnight_as_24": true, "type": "string"},
           "value": {"source": "value", "type": "number", "scale": 1.0, "offset": 0.0}
         }}
       }
@@ -129,7 +157,10 @@ Deployment Controller 管理的部署，不把模型中心回写的 delivery 状
 `cutoff_time`、`entity`、`horizon`、`output_window`、`prediction_hash` 和标准化的
 `predictions`。每个 prediction point 至少包含 `series_index`、`value`，序列结果通常还包含
 `target_time`。`source` 引用平台标准预测结果中的字段；`fields` 生成嵌套对象，`items` 将数组逐项转换，
-`constant` 写入固定值，`template` 可拼接已存在的字符串字段。`format` 可格式化时间，
+`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`，其他时刻保持不变；
 `scale` 和 `offset` 可执行受控数值换算，`type` 校验最终类型。`token_path`、业务成功码和
 `/forecast/report` 只是示例，必须按目标接口的真实响应和路径配置。
 映射字段缺失或类型不匹配时不会发送请求，Run 会记录 `payload_mapping_failed`。若响应提供有效期，可设置 `expires_in_path` 与 `expires_in_unit`；否则服务端默认按 7200 秒缓存，
@@ -276,3 +307,13 @@ the complete mapping delivered to the Worker after defaults are resolved.
 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.
+
+## Agent 宿主接入
+
+Coding agent 加载已安装的 Skills 后，通过原生 shell/exec 直接运行普通 `ml-platform` 命令。
+使用 `ml-platform --help` 和 `ml-platform <command> --help` 发现命令及参数；业务结果沿用
+CLI 原有 JSON 输出和退出码。CLI 不要求专用 Agent 调用协议。
+
+方法、预检顺序、幂等键使用及结果核验由 Skills 指导，命令参数和平台校验由 CLI/API 负责。
+宿主复用自己的权限、超时、Stop、输出截断及工具历史；进程中断不代表服务端任务已取消。
+提交结果不明时，先查询平台真实状态，再决定是否重试。

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

@@ -1,12 +1,12 @@
 {
   "name": "@zhuoyuezs/ml-platform-business-client",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@zhuoyuezs/ml-platform-business-client",
-      "version": "0.8.5",
+      "version": "0.8.6",
       "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.5",
+  "version": "0.8.6",
   "private": true,
   "description": "JavaScript implementation of the ML Platform business client",
   "bin": {

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Validate ordinary CLI arguments from the command usage maintained by the CLI.
+function grammar(command, usages) {
+    const signature = usages[command];
+    if (!signature)
+        throw new Error(`unknown business command: ${command}`);
+    const tokens = signature.replace(/[\[\]]/g, "").split(/\s+/).slice(1);
+    const flags = new Map();
+    const positionals = [];
+    for (let i = 0; i < tokens.length; i++) {
+        if (tokens[i].startsWith("-")) {
+            const value = tokens[i + 1] && !tokens[i + 1].startsWith("-") ? tokens[++i] : null;
+            flags.set(tokens[value ? i - 1 : i], value);
+        }
+        else
+            positionals.push(tokens[i]);
+    }
+    return { flags, positionals };
+}
+function parseCommand(argv, usages, allowMissing = false) {
+    if (!Array.isArray(argv) || !argv.length || !argv[0] || argv.length > 200 || argv.some(arg => typeof arg !== "string" || arg.includes("\0") || arg.length > 65536))
+        throw new Error("argv must be a bounded string array with a non-empty command");
+    const command = argv[0];
+    const spec = grammar(command, usages);
+    if (argv.length === 2 && ["--help", "-h"].includes(argv[1]))
+        return;
+    const flags = {};
+    let count = 0;
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        let label, value;
+        if (arg.startsWith("-")) {
+            if (!spec.flags.has(arg))
+                throw new Error(`unknown argument: ${arg}`);
+            if (arg in flags && arg !== "--file")
+                throw new Error(`duplicate argument: ${arg}`);
+            label = spec.flags.get(arg);
+            if (label && (i + 1 >= argv.length || argv[i + 1].startsWith("--")))
+                throw new Error(`${arg} requires a value`);
+            value = label ? argv[++i] : true;
+            flags[arg] = value;
+        }
+        else {
+            label = spec.positionals[count++];
+            if (!label)
+                throw new Error(`unknown argument: ${arg}`);
+        }
+    }
+    if (!allowMissing && count !== spec.positionals.length)
+        throw new Error(`${spec.positionals[count]} is required`);
+}
+module.exports = { parseCommand };

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

@@ -13,6 +13,7 @@ const BUSINESS_COMMANDS = new Set([
     "get-model-runtime-release", "get-training-run", "get-model-artifact", "get-executable-package",
     "validate-training-job", "validate-model-package",
     "version", "create-project", "list-projects", "get-project", "delete-project",
+    "get-dataset-contract-file", "validate-evaluation-comparison",
     "configure", "show-config", "health",
     "list-datasource-connections", "list-datasource-namespaces", "list-datasource-objects",
     "list-datasource-fields", "query-datasource-object", "create-datasource-connection",
@@ -38,6 +39,7 @@ const BUSINESS_COMMANDS = new Set([
     "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",
     "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",
     "get-deployment", "wait-deployment", "reconcile-deployment", "approve-deployment",
     "promote-deployment", "rollback-deployment", "suspend-deployment", "resume-deployment",
@@ -69,7 +71,7 @@ const COMMAND_USAGE = {
     "update-datasource-connection": "update-datasource-connection CONNECTION_ID SPEC_JSON",
     "delete-datasource-connection": "delete-datasource-connection CONNECTION_ID",
     "test-datasource-connection": "test-datasource-connection CONNECTION_ID",
-    "create-project": "create-project NAME [--display-name TEXT] [--description TEXT] [--owner OWNER]",
+    "create-project": "create-project NAME [--display-name TEXT] [--description TEXT] [--owner OWNER] [--idempotency-key KEY]",
     "list-projects": "list-projects",
     "get-project": "get-project NAME",
     "delete-project": "delete-project NAME",
@@ -108,11 +110,11 @@ const COMMAND_USAGE = {
     "delete-dataset": "delete-dataset DATASET_ID DATASET_VERSION [--project PROJECT]",
     "list-dataset-artifacts": "list-dataset-artifacts [--project PROJECT] [--dataset-id ID] [--dataset-version VERSION] [--include-deleted] [--limit N] [--offset N]",
     "get-dataset": "get-dataset DATASET_ID DATASET_VERSION [--project PROJECT] [--include-deleted]",
-    "list-jobs": "list-jobs [filters] [-q QUERY] [--limit N] [--offset N] [--all]",
+    "list-jobs": "list-jobs [--project PROJECT] [--dataset-id ID] [--dataset-version VERSION] [--manifest-hash HASH] [--status STATUS] [--parent-job-id ID] [--created-from TIMESTAMP] [--created-to TIMESTAMP] [--updated-from TIMESTAMP] [--updated-to TIMESTAMP] [-q QUERY] [--limit N] [--offset N] [--all]",
     "resolve-manifest": "resolve-manifest MANIFEST [--out PATH]",
     "resolve-dataset": "resolve-dataset DATASET_ID DATASET_VERSION [--project PROJECT] [--out PATH]",
-    "build-dataset": "build-dataset MANIFEST [--engine chronon] [--source-mode direct] [--upload-chronon-metadata] [--partition-duration DURATION] [--max-parallelism N] [--no-resume] [--wait] [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
-    "build-registered-dataset": "build-registered-dataset DATASET_ID DATASET_VERSION [--project PROJECT] [--engine chronon] [--source-mode direct] [--upload-chronon-metadata] [--partition-duration DURATION] [--max-parallelism N] [--no-resume] [--wait] [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
+    "build-dataset": "build-dataset MANIFEST [--plan] [--engine chronon] [--source-mode direct] [--upload-chronon-metadata] [--partition-duration auto|none|DURATION (default: auto)] [--target-partition-rows N] [--target-partition-source-rows N] [--target-partition-cells N] [--max-parallelism N] [--no-resume] [--wait] [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
+    "build-registered-dataset": "build-registered-dataset DATASET_ID DATASET_VERSION [--project PROJECT] [--plan] [--engine chronon] [--source-mode direct] [--upload-chronon-metadata] [--partition-duration auto|none|DURATION (default: auto)] [--target-partition-rows N] [--target-partition-source-rows N] [--target-partition-cells N] [--max-parallelism N] [--no-resume] [--wait] [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
     "get-job": "get-job JOB_ID",
     "wait-job": "wait-job JOB_ID [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
     "retry-job": "retry-job JOB_ID",
@@ -122,6 +124,7 @@ const COMMAND_USAGE = {
     "delete-operator": "delete-operator NAME VERSION [--project PROJECT]",
     "run-operator": "run-operator NAME VERSION [--project PROJECT] [--config JSON]",
     "get-dataset-artifact": "get-dataset-artifact DATASET_ID MANIFEST_HASH [--project PROJECT]",
+    "get-dataset-contract-file": "get-dataset-contract-file DATASET_ID MANIFEST_HASH FILE [--project PROJECT]",
     "download-dataset-artifact": "download-dataset-artifact DATASET_ID MANIFEST_HASH [--project PROJECT] --out-dir PATH [--file PATH] [--force]",
     "fetch-inference-data": "fetch-inference-data MANIFEST --cutoff-time TIMESTAMP [--max-workers N] [--max-source-lag-hours HOURS] [--no-validate-freshness] [--allow-missing]",
     "fetch-inference-context": "fetch-inference-context REQUEST_JSON",
@@ -132,13 +135,13 @@ const COMMAND_USAGE = {
     "predict-foundation-csv": "predict-foundation-csv NAME CSV_FILE --schema SCHEMA_JSON --forecast FORECAST_JSON [--release-id ID]",
     "list-system-models": "list-system-models",
     "get-system-model": "get-system-model NAME VERSION [--project PROJECT]",
-    "register-training-run": "register-training-run RUN_JSON",
+    "register-training-run": "register-training-run RUN_JSON [--idempotency-key KEY]",
     "validate-training-run": "validate-training-run RUN_JSON",
-    "submit-training-job": "submit-training-job REQUEST_JSON",
+    "submit-training-job": "submit-training-job REQUEST_JSON [--idempotency-key KEY]",
     "get-training-job": "get-training-job JOB_ID",
     "retry-training-job": "retry-training-job JOB_ID",
     "cancel-training-job": "cancel-training-job JOB_ID",
-    "register-evaluation-config": "register-evaluation-config CONFIG_JSON",
+    "register-evaluation-config": "register-evaluation-config CONFIG_JSON [--idempotency-key KEY]",
     "get-evaluation-config": "get-evaluation-config NAME VERSION",
     "register-metric-definition": "register-metric-definition DEFINITION_JSON",
     "get-metric-definition": "get-metric-definition NAME VERSION",
@@ -146,7 +149,8 @@ const COMMAND_USAGE = {
     "verify-executable-package": "verify-executable-package NAME VERSION",
     "publish-executable-package": "publish-executable-package NAME VERSION",
     "validate-evaluation-run": "validate-evaluation-run REQUEST_JSON",
-    "submit-evaluation": "submit-evaluation REQUEST_JSON",
+    "validate-evaluation-comparison": "validate-evaluation-comparison REQUEST_JSON",
+    "submit-evaluation": "submit-evaluation REQUEST_JSON [--idempotency-key KEY]",
     "get-evaluation-run": "get-evaluation-run RUN_ID",
     "get-evaluation-job": "get-evaluation-job JOB_ID",
     "retry-evaluation-job": "retry-evaluation-job JOB_ID",
@@ -157,15 +161,19 @@ const COMMAND_USAGE = {
     "get-evaluation-result-artifacts": "get-evaluation-result-artifacts RESULT_ID",
     "summarize-evaluation-run": "summarize-evaluation-run RUN_ID",
     "get-evaluation-summary": "get-evaluation-summary SUMMARY_ID",
-    "create-model-package": "create-model-package REQUEST_JSON",
+    "create-model-package": "create-model-package REQUEST_JSON [--idempotency-key KEY]",
     "get-model-package": "get-model-package PACKAGE_ID [--package-version VERSION]",
     "cancel-model-package": "cancel-model-package PACKAGE_ID [--package-version VERSION]",
     "validate-model-artifact": "validate-model-artifact ARTIFACT_ID",
     "register-model-artifact": "register-model-artifact ARTIFACT_ID --evaluation-id EVALUATION_ID",
+    "list-business-domains": "list-business-domains",
+    "list-scenarios": "list-scenarios [--business-domain-id ID]",
+    "create-scenario": "create-scenario SPEC_JSON",
+    "put-deployment-metadata": "put-deployment-metadata DEPLOYMENT_ID SPEC_JSON",
     "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] [-q QUERY] [--limit N] [--offset N]",
+    "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]",
     "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",
@@ -314,6 +322,19 @@ function buildOptions(rest) {
     if (maxParallelism < 1)
         throw new Error("--max-parallelism must be at least 1");
     const wait = boolean(rest, "--wait");
+    const plan = boolean(rest, "--plan");
+    if (plan && wait)
+        throw new Error("--plan is read-only and cannot be combined with --wait");
+    const sizing = {};
+    for (const [flag, key] of [["--target-partition-rows", "target_partition_rows"], ["--target-partition-source-rows", "target_partition_source_rows"], ["--target-partition-cells", "target_partition_cells"]]) {
+        const raw = take(rest, flag);
+        if (raw !== undefined) {
+            const value = integer(raw, flag);
+            if (value < 1)
+                throw new Error(`${flag} must be at least 1`);
+            sizing[key] = value;
+        }
+    }
     const pollInterval = finiteNumber(take(rest, "--poll-interval", 2), "--poll-interval");
     if (!(pollInterval > 0))
         throw new Error("--poll-interval must be positive");
@@ -325,7 +346,9 @@ function buildOptions(rest) {
         engine,
         sourceMode,
         upload: boolean(rest, "--upload-chronon-metadata"),
-        partitionDuration: take(rest, "--partition-duration"),
+        partitionDuration: take(rest, "--partition-duration", "auto"),
+        plan,
+        sizing,
         maxParallelism,
         resume: !boolean(rest, "--no-resume"),
         wait,
@@ -334,7 +357,8 @@ function buildOptions(rest) {
     };
 }
 async function submitBuild(api, manifest, build) {
-    let result = await api.post("/datasets/build", manifest, { engine: build.engine, source_mode: build.sourceMode, upload_chronon_metadata: build.upload, partition_duration: build.partitionDuration, max_parallelism: build.maxParallelism, resume: build.resume });
+    const controls = { partition_duration: build.partitionDuration, max_parallelism: build.maxParallelism, resume: build.resume, ...build.sizing };
+    let result = await api.post(build.plan ? "/datasets/build-plan" : "/datasets/build", manifest, build.plan ? controls : { engine: build.engine, source_mode: build.sourceMode, upload_chronon_metadata: build.upload, ...controls });
     let exitCode = 0;
     if (build.wait) {
         if (!result || typeof result !== "object" || !result.job_id)
@@ -397,18 +421,21 @@ async function waitForDeployment(api, deploymentId, pollInterval, timeoutSeconds
         await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
     }
 }
-async function runBusinessCli(argv) {
+async function runBusinessCli(argv, output = { write: text => process.stdout.write(text) }) {
     if (argv.length === 0)
         throw new Error("a business command is required");
     if (argv.includes("--help") || argv.includes("-h")) {
         const command = argv.find((item) => BUSINESS_COMMANDS.has(item));
         if (command || argv[0] === "--help" || argv[0] === "-h") {
-            process.stdout.write(usage(command));
+            output.write(usage(command));
             return 0;
         }
     }
     const options = parse(argv);
     const rest = [...options.rest];
+    const { parseCommand } = require("./cli-arguments");
+    // Reject malformed argv before a handler can mutate the platform.
+    parseCommand([options.command, ...rest], COMMAND_USAGE, true);
     let result;
     let exitCode = 0;
     if (options.command === "version")
@@ -473,7 +500,9 @@ async function runBusinessCli(argv) {
     }
     else if (options.command === "create-project") {
         const name = positional(rest, "project name");
-        result = await client(options).post("/projects", { schema_version: "ml_data_platform.project/v1", name, display_name: take(rest, "--display-name", name), description: take(rest, "--description", ""), owner: take(rest, "--owner", "demo") });
+        const spec = { schema_version: "ml_data_platform.project/v1", name, display_name: take(rest, "--display-name", name), description: take(rest, "--description", ""), owner: take(rest, "--owner", "demo") };
+        const key = take(rest, "--idempotency-key");
+        result = key ? await client(options).postWithHeaders("/projects", spec, { "Idempotency-Key": key }) : await client(options).post("/projects", spec);
     }
     else if (options.command === "list-projects")
         result = await client(options).get("/projects");
@@ -717,6 +746,15 @@ async function runBusinessCli(argv) {
         const project = take(rest, "--project", "default");
         result = await client(options).get(`/dataset-artifacts/${encodeURIComponent(project)}/${encodeURIComponent(dataset)}/${encodeURIComponent(hash)}`);
     }
+    else if (options.command === "get-dataset-contract-file") {
+        const dataset = positional(rest, "dataset id");
+        const hash = positional(rest, "manifest hash");
+        const file = positional(rest, "contract file");
+        const project = take(rest, "--project", "default");
+        if (!["data_schema.json", "resolved_manifest.json"].includes(file))
+            throw new Error("unsupported contract file; use data_schema.json or resolved_manifest.json");
+        result = await client(options).get(`/dataset-artifacts/${encodeURIComponent(project)}/${encodeURIComponent(dataset)}/${encodeURIComponent(hash)}/files/${file}`);
+    }
     else if (options.command === "download-dataset-artifact") {
         const dataset = positional(rest, "dataset id");
         const hash = positional(rest, "manifest hash");
@@ -795,6 +833,19 @@ async function runBusinessCli(argv) {
         const headers = releaseId ? { "X-ITSMP-Foundation-Release": releaseId } : {};
         result = await client(options).uploadFoundationCsv(`/foundation-models/${encodeURIComponent(name)}/predict-file`, readSpec(schemaFile), readSpec(forecastFile), csvFile, headers);
     }
+    else if (options.command === "list-business-domains") {
+        result = await client(options).get("/business-domains");
+    }
+    else if (options.command === "list-scenarios") {
+        result = await client(options).get("/scenarios", { business_domain_id: take(rest, "--business-domain-id") });
+    }
+    else if (options.command === "create-scenario") {
+        result = await client(options).post("/scenarios", readSpec(positional(rest, "scenario spec JSON")));
+    }
+    else if (options.command === "put-deployment-metadata") {
+        const deploymentId = positional(rest, "deployment id");
+        result = await client(options).put("/deployments/" + encodeURIComponent(deploymentId) + "/metadata", readSpec(positional(rest, "metadata spec JSON")));
+    }
     else if (options.command === "list-deployment-targets") {
         result = await client(options).get("/deployment-targets");
     }
@@ -814,6 +865,8 @@ async function runBusinessCli(argv) {
             package_version: take(rest, "--package-version"),
             model_artifact_id: take(rest, "--model-artifact-id"),
             state: take(rest, "--state"),
+            business_domain_id: take(rest, "--business-domain-id"),
+            scenario_id: take(rest, "--scenario-id"),
             q: take(rest, "--q", take(rest, "-q")),
         };
         boolean(rest, "--all");
@@ -984,11 +1037,16 @@ async function runBusinessCli(argv) {
     else if ({
         "register-training-run": "/training-runs", "validate-training-run": "/training-runs/validate",
         "validate-training-job": "/training-jobs/validate", "validate-model-package": "/model-packages/validate", "submit-training-job": "/training-jobs", "register-evaluation-config": "/evaluation-configs", "register-metric-definition": "/metric-definitions",
-        "register-executable-package": "/executable-packages", "validate-evaluation-run": "/evaluation-runs/validate", "submit-evaluation": "/evaluation-runs",
+        "register-executable-package": "/executable-packages", "validate-evaluation-run": "/evaluation-runs/validate", "validate-evaluation-comparison": "/evaluation-comparisons/validate", "submit-evaluation": "/evaluation-runs",
         "create-model-package": "/model-packages",
     }[options.command]) {
-        const endpoint = { "register-training-run": "/training-runs", "validate-training-run": "/training-runs/validate", "validate-training-job": "/training-jobs/validate", "validate-model-package": "/model-packages/validate", "submit-training-job": "/training-jobs", "register-evaluation-config": "/evaluation-configs", "register-metric-definition": "/metric-definitions", "register-executable-package": "/executable-packages", "validate-evaluation-run": "/evaluation-runs/validate", "submit-evaluation": "/evaluation-runs", "create-model-package": "/model-packages" }[options.command];
-        result = await client(options).post(endpoint, readSpec(positional(rest, "request JSON")));
+        const endpoint = { "register-training-run": "/training-runs", "validate-training-run": "/training-runs/validate", "validate-training-job": "/training-jobs/validate", "validate-model-package": "/model-packages/validate", "submit-training-job": "/training-jobs", "register-evaluation-config": "/evaluation-configs", "register-metric-definition": "/metric-definitions", "register-executable-package": "/executable-packages", "validate-evaluation-run": "/evaluation-runs/validate", "validate-evaluation-comparison": "/evaluation-comparisons/validate", "submit-evaluation": "/evaluation-runs", "create-model-package": "/model-packages" }[options.command];
+        const spec = readSpec(positional(rest, "request JSON"));
+        const operationCommands = new Set(["register-training-run", "submit-training-job", "register-evaluation-config", "submit-evaluation", "create-model-package"]);
+        const key = operationCommands.has(options.command) ? take(rest, "--idempotency-key") : null;
+        result = key
+            ? await client(options).postWithHeaders(endpoint, spec, { "Idempotency-Key": key })
+            : await client(options).post(endpoint, spec);
     }
     else if (/^(get|retry|cancel)-training-job$/.test(options.command)) {
         const jobId = positional(rest, "training job id");
@@ -1053,7 +1111,7 @@ async function runBusinessCli(argv) {
         throw new Error(`unknown business command: ${options.command}`);
     if (rest.length)
         throw new Error(`unknown arguments: ${rest.join(" ")}`);
-    process.stdout.write(typeof result === "string" ? `${result}\n` : `${JSON.stringify(result, null, 2)}\n`);
+    output.write(typeof result === "string" ? `${result}\n` : `${JSON.stringify(result, null, 2)}\n`);
     return exitCode;
 }
 async function fetchAll(api, endpoint, params = {}) { const items = []; for (let offset = 0;; offset += 500) {

package/skills/feature-management/SKILL.md

@@ -48,10 +48,11 @@ Keep these evidence rules active in every workflow:
 
 1. Resolve the Skill root as the directory containing this `SKILL.md`.
 2. Read [references/contracts.md](references/contracts.md) before creating or changing JSON assets.
-3. Read [references/operator-authoring.md](references/operator-authoring.md) whenever creating or changing Operator code or a wheel.
-4. Read [references/commands.md](references/commands.md) immediately before a platform CLI action: discovery, validation, publication, build, realtime fetch, or artifact download. A local-only draft that is forbidden to call the CLI does not need this reference.
-5. Use [assets/catalog-template](assets/catalog-template) as a copyable starting point for a new end-to-end catalog. Rename every `example_*` identifier and update every referenced path before validation.
-6. Read [references/platform-capability-guide.md](references/platform-capability-guide.md) only when selecting an asset type or explaining a platform capability. Do not load it merely to write a confirmed local draft; it is never evidence for unresolved business semantics.
+3. Read [references/supervised-datasets.md](references/supervised-datasets.md) when preparing time-series supervision, labels, fixed grids, or training/validation/test splits. It distinguishes DatasetArtifact data semantics from model-specific sequence adapters.
+4. Read [references/operator-authoring.md](references/operator-authoring.md) whenever creating or changing Operator code or a wheel.
+5. Read [references/commands.md](references/commands.md) immediately before a platform CLI action: discovery, validation, publication, build, realtime fetch, or artifact download. A local-only draft that is forbidden to call the CLI does not need this reference.
+6. Use [assets/catalog-template](assets/catalog-template) as a copyable starting point for a new end-to-end catalog. Rename every `example_*` identifier and update every referenced path before validation.
+7. Read [references/platform-capability-guide.md](references/platform-capability-guide.md) only when selecting an asset type or explaining a platform capability. Do not load it merely to write a confirmed local draft; it is never evidence for unresolved business semantics.
 
 ## Initialize The Client
 
@@ -404,7 +405,7 @@ Stop on any error. Do not weaken schema validation, fabricate a missing dependen
 
 Publish only after the user explicitly approves Registry and wheel changes. Use catalog `apply` so publication follows Parameter -> Operator -> Feature -> FeatureSet -> Dataset order.
 
-After publication, resolve every new DatasetManifest and compare its exact Parameter, Operator, Feature, and FeatureSet versions with the pre-publication mapping. Stop if an affected old key or any unexpected version remains. Resolve the manifest before building. Submit a build only when requested. For the current partitioned materialization runtime, use `--max-parallelism 1` unless a separately verified platform capability says otherwise; do not retry or resubmit a failed Job until its error and already-completed partitions are understood. For server builds, wait for the terminal Job state and download the exact artifact by `dataset_id + manifest_hash`.
+After publication, resolve every new DatasetManifest and compare its exact Parameter, Operator, Feature, and FeatureSet versions with the pre-publication mapping. Stop if an affected old key or any unexpected version remains. Resolve the manifest before building. Submit a build only when requested. Before choosing partition controls, use the build command's read-only `--plan` capability described in [commands.md](references/commands.md), inspect its estimates and warnings, and prefer platform automatic sizing over a copied daily example. Explicit overrides need source/resource evidence; preserve the submitted Job's concrete plan when resuming. For the current partitioned materialization runtime, use `--max-parallelism 1` unless a separately verified platform capability says otherwise; do not retry or resubmit a failed Job until its error and already-completed partitions are understood. For server builds, wait for the terminal Job state and download the exact artifact by `dataset_id + manifest_hash`.
 
 Do not delete versioned Registry assets, cancel Jobs, rebuild images, modify Kubernetes, or change service configuration as part of this workflow unless the user separately and explicitly requests that action. An empty Project may be soft-deleted only on an explicit request; rely on the server to reject deletion when resources still exist.
 

package/skills/feature-management/references/commands.md

@@ -177,13 +177,28 @@ ml-platform --profile server \
   resolve-dataset <dataset_id> <dataset_version> --project <project>
 ```
 
+Preview execution sizing without submitting a build:
+
+```bash
+ml-platform --profile server \
+  build-registered-dataset <dataset_id> <dataset_version> \
+  --project <project> --plan
+```
+
+Inspect `execution_spec`, estimated target/source rows, partition count, reasons
+and warnings. This reads registry metadata only. It does not query source data,
+start Operators or submit a Job. The defaults are soft sizing targets, not
+measured memory or runtime limits. The installed CLI and API must both support
+this capability; inspect `--help` and report version drift instead of silently
+submitting when a preview is unavailable.
+
 After the user confirms the exact triple and authorizes one build:
 
 ```bash
 ml-platform --profile server \
   build-registered-dataset <dataset_id> <dataset_version> \
   --project <project> \
-  --partition-duration 1d \
+  --partition-duration auto \
   --max-parallelism 1 \
   --wait
 ```
@@ -210,15 +225,35 @@ Submit and wait for a server build:
 ```bash
 ml-platform --profile server \
   build-dataset <catalog>/datasets/<dataset>.json \
-  --partition-duration 1d \
+  --partition-duration auto \
   --max-parallelism 1 \
   --wait
 ```
 
+Both build commands default to `--partition-duration auto`. Add `--plan` to
+either command for read-only preview; it cannot be combined with `--wait`.
+The platform sizes windows from target grids, output width, source frequency
+and history/label read overlap. Do not copy `1d` as a performance default.
+Use the same execution options for preview and submission, then record the
+actual Job's persisted `build_plan` and concrete `execution_spec`.
+
+When resource evidence justifies a change, the soft sizing controls are
+`--target-partition-rows`, `--target-partition-source-rows` and
+`--target-partition-cells` (defaults 50000, 500000 and 1000000). Explicit
+`--partition-duration 7d` overrides selection; `--partition-duration none`
+preserves full-window execution. Unknown source frequencies, event-driven
+rowsets, source fan-out and Operator allocations require inspection; automatic
+sizing is not a resource guarantee. Final merge memory is not bounded by a
+partition's estimated rows. A long prediction horizon is not itself a reason to
+use daily partitions: inspect the reported source read amplification.
+
 `--partition-duration` is an execution control and does not change the
-DatasetManifest hash. The initial implementation is sequential, so keep
+DatasetManifest hash. The current implementation is sequential, so keep
 `--max-parallelism 1`. Completed partitions are checkpointed and resumed by
-default; use `--no-resume` only to force a clean execution.
+default; use `--no-resume` only to force a clean execution. Retries preserve the
+resolved partition duration. Changing it requires a new execution, rather than
+reusing old checkpoint boundaries. Changing partition size does not authorize
+cancelling or resubmitting an already-running Job.
 
 Record the returned `job_id`, `dataset_id`, and resolved `manifest_hash`; for a registered Dataset
 also retain `registered_manifest_hash` for FeatureRetrievalSpec binding. If a separate wait is needed:

package/skills/feature-management/references/supervised-datasets.md

@@ -36,6 +36,72 @@ names need source-frame evidence. The schema lists `dataset_column` and
 resolve before building rather than treating schema acceptance as runtime support.
 Choose `report`, `reject` or `drop` according to the intended label population.
 
+## Four different time-series concepts
+
+Do not use *target*, *label*, *history* and *grid* interchangeably. They describe
+different data and are checked at different stages:
+
+| Concept | Meaning | Contract location |
+| --- | --- | --- |
+| Continuous target series | Observed target-channel values at successive `prediction_time` rows, used as a trajectory for a forecasting Trainer. It is not the future label column. | `forecast_target_adapter.target_input_column` (v1) or `targets[].input_column` (v2); the selected column must be a numeric Feature with availability at prediction. |
+| Supervised label | The ground-truth value for one sample's future `label_time`; it is generated by `label_materializations` and listed in `data.labels`. | DatasetArtifact label column plus `TemporalBinding.label_time_column`; for a fixed horizon, `label_time = prediction_time + horizon`. |
+| Historical input window | The model's past covariate/feature rows visible to one prediction. It is assembled around the sample's prediction time and is independent of the label horizon. | Sequence `input_adapter.context_length`, `frequency`, `stride`, `context_end`, `gap_policy` and `padding_policy`. |
+| Grid break | An absent expected timestamp between rows for a series at the declared frequency. It is not a present row whose value is null or non-finite. | `input_adapter.gap_policy` for historical windows; `forecast_target_adapter.target_gap_policy` for continuous target trajectories. |
+
+For example, with a 5-minute grid, a cutoff at 10:00, and a 15-minute horizon:
+the historical window ends at 10:00 when `context_end` is inclusive; the
+supervised label is at 10:15; and a continuous target trajectory may contain
+the target Feature's observed values at 10:00, 10:05, 10:10, and later times
+within its split. The future label is materialized per sample. It must not be
+copied backward into the target trajectory or treated as a prediction-time
+input.
+
+The platform assembles continuous target trajectories per split before the
+forecast Trainer samples its own context/future windows. A trajectory starts a
+new segment at a gap when `target_gap_policy="split"`; `"reject"` fails on the
+gap. Segments shorter than the effective minimum history plus prediction
+length are dropped. This policy does not fill missing values: a null or
+non-finite value in a target or required covariate is an error. Likewise,
+`input_adapter.gap_policy` governs sequence history construction and does not
+change target-trajectory segmentation. Do not select `fill` or `split` merely
+to hide missing values; identify whether the row itself is absent or its value
+is invalid and apply an explicitly supported data-quality method.
+
+Splits are applied before continuous target-trajectory assembly. A
+train/validation or validation/test boundary therefore ends one trajectory and
+starts another; never concatenate split values into one target trajectory.
+Sequence input windows are assembled for each prediction row from timestamped
+rows in the artifact, using only the adapter's expected history timestamps at
+or before that row. In a chronological holdout, validation/test windows may
+therefore use earlier training-period observations as history; this does not
+move those rows into the validation/test target population. Verify the split's
+temporal ordering and preserve the platform's sample membership. Do not use
+rows after a prediction time to complete its history, and do not infer that
+target-trajectory split behavior also applies to sequence windows. An early
+row may lack enough history; padding or skipping follows the declared adapter,
+not the label policy.
+
+When diagnosing a built artifact, inspect timestamps and values separately:
+
+1. Group by `series_keys` and sort by `prediction_time_column`; compare adjacent
+   timestamp deltas with `temporal.frequency` to find grid breaks and duplicate
+   times.
+2. At existing grid rows, inspect numeric target/input values for null and
+   non-finite cells. A row with a null value is not a grid break.
+3. Check label null rates independently using the final artifact's label column,
+   `missing_stats.labels`, and the chosen `missing_policy`; inspect Parquet rows
+   when exact row identities or counts are needed.
+4. Check history sufficiency against `context_length`, `context_end`, `stride`
+   and split boundaries; check forecast-trajectory sufficiency against
+   `min_past + prediction_length` within each uninterrupted segment.
+
+Do not infer final label null rates or counts from an earlier materialization's
+`missing_before_drop`: that statistic describes rows before the configured
+drop stage, while the final artifact may contain only retained rows. Use the
+final `missing_stats.labels` for rates and sampled/final Parquet rows for exact
+counts and row identities in the published artifact. Do not infer grid
+completeness from null counts alone.
+
 - `prediction_time = event_time` is the causal cutoff.
 - `label_time = prediction_time + prediction.horizon` is the forecast target.
 - `event_time.offset` shifts the source observation clock before alignment. At
@@ -87,6 +153,15 @@ split counts and binding together.
 
 ## Evidence checkpoints
 
+SQL-source `verifiable=false` means the automatic clock analysis could not
+establish the claim; `availability_guarantee=not_enforced` means availability
+is not enforced. Neither alone proves leakage or a platform-wide training ban.
+Check the actual feature cutoff, label clock and split evidence, preserve
+remaining uncertainty, and obtain the platform's read-only validation result.
+Future labels are supervision and need not be available at prediction time;
+feature inputs still obey their declared causal/availability contract.
+Passing schema or training preflight is not proof of leakage-free data.
+
 Before publication, review schema and Operator limits and run catalog dry-run.
 After publication, resolve labels, source fields, horizon and dependencies before
 building. After build, inspect DataSchema and sampled Parquet rows for the clock

package/skills/model-lifecycle-management/SKILL.md

@@ -19,10 +19,23 @@ For late-arriving context observations, read the package-bound
 The caller supplies one cutoff; the package chooses strict cutoff visibility or
 visibility at the actual retrieval attempt.
 
+When authoring time-series data or comparing sequence and tabular models over
+the same artifact, follow
+[feature-management/references/supervised-datasets.md](../feature-management/references/supervised-datasets.md)
+for the distinction between continuous target trajectories, future labels,
+historical windows and grid breaks. Do not replace that data method with a
+Runtime or TUI prompt rule.
+
 Read [references/discovery.md](references/discovery.md) before locating existing
 resources or selecting runtime bindings. It also defines Job/package preflight
 and version-skew handling.
 
+For multiple-model experiments or iterative optimization, read
+[references/model-comparison.md](references/model-comparison.md). This method
+uses platform CLI contracts and works without an ITSMP TUI or a specific Agent
+Runtime. An execution host may additionally persist plans, method hashes,
+attempts and checkpoints; those records do not replace platform evidence.
+
 Read [references/zero-shot-inference.md](references/zero-shot-inference.md) when
 the user wants synchronous zero-shot forecasting from JSON or CSV. This path
 uses the platform-owned `chronos2_forecaster` model name, not a public project

package/skills/model-lifecycle-management/references/evaluation.md

@@ -1,5 +1,29 @@
 # Evaluation Commands
 
+## Comparing completed results
+
+Use a read-only comparison preflight when the installed CLI/deployed API supports it:
+
+```bash
+ml-platform validate-evaluation-comparison comparison.json
+```
+
+```json
+{
+  "schema_version": "ml_data_platform.evaluation_result_comparison_request/v1",
+  "comparison_type": "model",
+  "result_ids": ["replace_result_a", "replace_result_b"],
+  "metrics": ["regression.mae"],
+  "sort_direction": "ascending"
+}
+```
+
+Use actual distinct, immutable complete results. Check the returned status,
+`ranking_allowed` and incompatibility reasons before naming a winner; matching
+metric names alone is insufficient. Direction comes from MetricDefinition;
+neutral metrics and ties do not establish a unique best model. A missing CLI
+command is a version/capability gap; do not bypass it with caller-authored results.
+
 ## Request bodies and prerequisites
 
 Evaluation reuses the model's original TrainingRun, replaces its artifact

package/skills/model-lifecycle-management/references/model-comparison.md

@@ -0,0 +1,148 @@
+# Comparing models within one experiment
+
+Use one documented goal and user-authorized scope: metric, target, candidate
+constraints and any maximum number of training submissions. Preserve that goal
+when a follow-up changes a constraint or asks for verification. Reuse existing
+authorization when it covers the next action; ask only for missing decisions.
+No TUI, session service, or Runtime-specific tool is required for this method.
+
+## Shared scope and candidate execution
+
+Freeze a common comparison scope before training: DatasetArtifact identity,
+DataSchema, label/temporal semantics, train/validation/test assignment values,
+evaluation configuration, metric definition/version, target, slice and
+calculation space. Use the training/evaluation references for exact JSON.
+When data needs authoring or rebuilding, use `feature-management` first; a
+registered manifest alone is not training data.
+
+Discover actual SystemModels and Runtime Release bindings through the CLI.
+Validate each complete TrainingRun before registration/submission. Candidate
+models may differ in estimator, hyperparameters or ordered input subsets that
+the platform accepts; changing labels, frozen rowsets or evaluation semantics
+starts a different comparison scope. Read-only preflight does not consume a
+training submission, and passing validation is not proof of leakage-free data.
+
+The common scope freezes the data and evaluation population; it does not imply
+that every candidate must consume an identical model-input tensor. For each
+candidate, bind a registered exact-version FeatureSet that is an allowed
+subset/order projection of the same DatasetArtifact and validate the model's
+own `input_adapter` and (only when required by its Trainer capability)
+`forecast_target_adapter`. A tabular tree model and a sequence model can share
+the artifact, labels, temporal binding, split assignments and EvaluationConfig
+while using different ordered FeatureSet projections or adapters. Keep the
+target definition, rowset membership, metric, evaluation slice and calculation
+space fixed. If a candidate requires data that is absent from the frozen
+artifact, it is not comparable under this scope; do not rebuild only for that
+candidate and call it the same comparison.
+
+For forecast comparisons, distinguish future supervised labels from a
+continuous target trajectory and from a sequence model's historical context.
+Check the final artifact for label alignment, grid breaks, null/non-finite
+values, and per-split history/trajectory sufficiency using
+[`feature-management/references/supervised-datasets.md`](../../feature-management/references/supervised-datasets.md).
+Do not treat a candidate-specific context length as a change to the shared
+forecast horizon, and do not let trajectory construction cross split
+boundaries. Compare complete platform-produced EvaluationResults only after
+each candidate passes its own TrainingRun and evaluation preflight.
+
+For each candidate, record its hypothesis, exact changed inputs, parent attempt
+if any, request JSON and returned immutable IDs in the agent's working
+directory. Submit within the user's authorization, observe the TrainingJob,
+validate the resulting ModelArtifact, then submit and inspect governed
+evaluation. Explain the observed result before choosing another candidate.
+Do not resubmit after an unknown outcome: reconcile the existing Job or retry
+only the exact supported idempotent request. Infrastructure retries require
+the authorization described in the training reference.
+
+## Rounds, failure evidence and stopping
+
+A round groups candidates that test a related hypothesis under the frozen
+comparison scope. Keep a small round record in the agent's working directory
+(outside a platform source checkout), using normal file tools. Include the
+scope/request paths, candidate identities and changes, submission IDs, observed
+status, result IDs, per-candidate reflection and the round's next decision.
+This is an agent work record, not a new platform resource or required tool.
+Update it after submissions and observations so another coding agent can resume.
+
+When a candidate fails, inspect the actual Job status, attempts and diagnostic
+evidence. Distinguish a model execution failure from a runtime/infrastructure
+failure, a rejected contract and an unexplained error. Preserve the original
+error and its source; a keyword in an error message is insufficient to establish
+the cause. A failed Job has no quality score and cannot be ranked as a bad model.
+
+A known terminal failure of one candidate need not block independent candidates
+whose data, contracts and runtime remain valid. Record what failed and continue
+within the existing authorization. A shared data/contract/runtime defect blocks
+affected candidates until corrected. Unknown submission outcomes require
+reconciliation before further submissions. A timeout while polling does not
+prove a Job failed or stopped, and does not authorize a duplicate or cancellation.
+
+At the round boundary, account for all candidates: complete, failed, still
+running, outcome unknown or skipped with reason. Compare only complete,
+comparable validation evidence. State whether it supports the hypothesis and
+what would change next. Keep global-best and model-family-best references only
+within the same comparison scope and metric direction; ties remain ties.
+
+Training-count constraints are optional user instructions. Omitted constraints
+do not mean zero permission, and shell hosts need not implement a submission
+counter. Count actual submissions from retained CLI/platform evidence, including
+failures; distinguish preflight, reused Jobs and newly submitted retries. Resolve
+uncertainty before claiming remaining capacity. If useful, agree on a
+no-improvement window, minimum meaningful metric change, failure threshold or
+observation deadline for a long optimization task. Do not invent default hard
+quotas. Apply improvement criteria only to comparable complete validation
+results; infrastructure failures are not evidence of no improvement.
+
+## Validation selection and held-out test
+
+Compare only complete platform-produced EvaluationResults. When supported,
+use `ml-platform validate-evaluation-comparison REQUEST_JSON`; the request and
+evidence rules are in [evaluation.md](evaluation.md). Rank only when the
+platform confirms comparability and the MetricDefinition gives a direction.
+Report ties and inconclusive results as such. Never compute or register a
+replacement platform result to manufacture a winner.
+
+Before reading held-out test metrics, save the selected validation candidate's
+exact ModelArtifact ID, validation Result IDs, selection rationale and frozen
+evaluation request. For conflicting metrics or ties, report the tradeoff or
+obtain the missing selection criterion rather than inventing a unique winner.
+
+Evaluate that same immutable ModelArtifact on the declared test rowset using
+the normal `validate-evaluation-run`, `submit-evaluation`, Job reads and Result
+reads described in [evaluation.md](evaluation.md). Evaluation JSON uses
+`rowset: "test"` (or the actual declared role); it has no `purpose` field.
+Test and validation may be disjoint splits of the **same DatasetArtifact**.
+Inspect the original TrainingRun split assignment values and temporal coverage
+to establish isolation. Different artifact hashes alone do not prove that the
+rows are independent. A separate artifact also needs the model's full schema
+compatibility; do not rebuild a dataset merely to give test a different hash.
+
+Test results assess the locked candidate, not the next tuning decision. Retain
+validation selection and test evidence separately; never mix their Result IDs
+in a validation ranking. Do not retrain or choose another candidate based on
+test results while claiming an unseen final test. If the test was already used
+for selection, disclose that limitation and define a new holdout only within
+the user's authorized scope. A task without a valid test split may deliver its
+validation results with that limitation; it must not invent test evidence.
+
+## Resume and delivery
+
+On resume, read the saved requests/round record and query the actual platform
+Jobs, ModelArtifacts and EvaluationResults before continuing. A stopped TUI or
+shell process does not cancel remote Jobs. Preserve a running or unknown Job ID;
+do not rerun its submission command just because the prior tool result is missing.
+
+Stop when the requested target is reached, the authorized training count is
+used, the user stops, or evidence establishes a concrete blocker. Deliver the
+candidate/input changes, Run/Job/ModelArtifact/EvaluationResult IDs, metrics,
+comparison limitations and explanation. Distinguish a finished conversation
+from a completed modeling task. A report is complete only when it accounts
+for every submitted candidate and its actual outcome; no model is best when
+there are no comparable results. Publishing or deploying remains a separate
+authorized action.
+
+Deliver the stop reason, each round's hypothesis and outcome, validation
+comparison, locked candidate and any test evidence, plus failed/skipped/pending
+candidates and concrete blockers. When all candidates fail, deliver a diagnostic
+report without naming a winner. An unfinished remote Job or unresolved submission
+must remain explicitly pending; ending the conversation is not completion of it.

package/skills/model-lifecycle-management/references/training-contracts.md

@@ -68,6 +68,50 @@ Non-temporal regression can omit it. Do not change task kind just to evade check
 `series_keys` must identify entity-key columns when multiple series coexist;
 an empty list treats the entire artifact as one series.
 
+### Target trajectory, labels and historical context
+
+Keep these contracts separate:
+
+- `data.labels` and `TemporalBinding.label_time_column` identify supervised
+  future truth, normally materialized at `prediction_time + horizon`.
+- `forecast_target_adapter.target_input_column` (v1) or
+  `targets[].input_column` (v2) identifies a numeric prediction-time Feature
+  whose successive observations form a continuous target trajectory for a
+  trajectory-capable Trainer. It is not a substitute for `data.labels`.
+- `input_adapter` defines tabular rows or the model's historical input window.
+  Sequence `context_length`, `context_end`, `frequency`, `stride` and
+  `gap_policy` concern that window, independently of forecast horizon and
+  label alignment.
+- `temporal.frequency` defines expected adjacent prediction-time grid points.
+  A grid break is an absent timestamp; a null/non-finite value at an existing
+  timestamp is invalid data, not a grid break.
+
+The platform applies split assignment before constructing continuous target
+trajectories. `target_gap_policy="reject"` fails if adjacent trajectory rows
+are not one frequency apart; `"split"` begins a new segment at each break.
+Neither setting imputes null/non-finite target or covariate values. A segment
+must meet the effective minimum history plus prediction length or it is
+excluded. `input_adapter.gap_policy` separately controls sequence-window
+behavior (`reject`, `skip` or supported `fill` with a padding policy). Do not
+use either setting to conceal nulls. Target trajectories are split-isolated.
+Sequence history is assembled per prediction row from artifact timestamps at
+or before that row; with chronological holdouts, an evaluation window may use
+earlier training-period history while its target sample remains in the
+evaluation split. Preserve the declared sample membership and never use rows
+after the prediction cutoff. Do not assume target-trajectory split handling
+and sequence-window handling are interchangeable.
+
+Before creating a forecast TrainingRun, establish from the final DatasetArtifact
+that the target-input Feature is present, numeric, prediction-time available,
+and sufficiently continuous in each split; labels are separately aligned to
+the declared horizon; and each candidate's history requirements are met. A
+tabular model may consume one row per sample without a sequence history window,
+while a sequence model may need a model-specific window over the same artifact.
+The target-trajectory adapter is required only when the selected Trainer
+capability requires it; do not attach it just because the task is a forecast.
+For the platform's detailed diagnostic and label-statistics procedure, read
+[`feature-management/references/supervised-datasets.md`](../../feature-management/references/supervised-datasets.md).
+
 ## Chronos-2 LoRA parameters
 
 Chronos-2 fine-tuning settings belong under `trainer.parameters`; they are

package/skills/model-lifecycle-management/references/training.md

@@ -13,6 +13,8 @@ FeatureSet order and evaluation runtime before the first Job. See
   for device`, preserve the rejected identity, device and release ID. Use `get-model-runtime-release` to find the
   approved binding; if the deployed release lacks discovery, request its contract;
   do not try similar names or re-register trainers to bypass approval.
+- ARIMA supports the v1 single-target adapter for single-channel CPU
+  forecasting; it does not support covariates or the v2 adapter.
 - Chronos-2 supports the legacy v1 single-target adapter and the v2
   covariate-aware adapter. v2 jointly forecasts ordered target channels and
   accepts numeric `past_only` and `known_future` covariates. Do not silently

package/skills/prediction-report-management/SKILL.md

@@ -75,9 +75,17 @@ business configuration submitted through this API, not Kubernetes Secrets.
 Mapping sources use standard report fields such as `run_id`, `schedule_id`,
 `deployment_id`, `cutoff_time`, `entity`, and `predictions`. Use `fields` for
 nested objects, `items` for array conversion, `constant` for fixed values,
-`template` for string composition, and `format`, `scale`, `offset`, and `type`
-for bounded transformations and validation. Arbitrary code and expressions are
-not supported. A missing field or type failure produces
+`template` for string composition, and `format`, `timezone`, `scale`, `offset`,
+and `type` for bounded transformations and validation. `timezone` is an IANA
+timezone and must be used together with `format`; it converts an aware ISO-8601
+timestamp before formatting. For a business endpoint that represents local
+midnight as the end of the previous business day, set `midnight_as_24: true`
+on a time field whose format contains `%H` (for example, `%H:%M`). This maps
+local `00:00` to `24:00` after timezone conversion and leaves other times
+unchanged. For example, use
+`{"source":"cutoff_time","format":"%Y-%m-%d","timezone":"Asia/Shanghai"}`
+to map `2026-09-10T16:00:00Z` to `2026-09-11`. Arbitrary code and expressions
+are not supported. A missing field or type failure produces
 `payload_mapping_failed` before any HTTP request is made.
 
 Use `preview-destination-profile` with a standard prediction payload to inspect