@zhuoyuezs/ml-platform 0.1.7 → 0.1.8

package/checksums.json

@@ -2,8 +2,8 @@
   "files": [
     {
       "path": "runtime/business-client/README.md",
-      "sha256": "sha256:b12f30609c756ac4473723df434e6b1055f8713b7acfc3278b091b52288f6347",
-      "size_bytes": 2459
+      "sha256": "sha256:02e6561b80cbef3cce2fd690750d863d8afb9c45bf5ccfcce3e3e2b082ff0761",
+      "size_bytes": 3780
     },
     {
       "path": "runtime/business-client/package-lock.json",
@@ -22,8 +22,8 @@
     },
     {
       "path": "runtime/business-client/src/cli.js",
-      "sha256": "sha256:ca7bbee61e83f4597c0da75fd3527f1ee43d5257fff07693b581987efeeaafd3",
-      "size_bytes": 41926
+      "sha256": "sha256:6ee4ed29a9df9f462502ccc0e10d5d9109bf00b52b8c27c9808730c7d8520592",
+      "size_bytes": 44480
     },
     {
       "path": "runtime/business-client/src/config.js",
@@ -37,8 +37,8 @@
     },
     {
       "path": "skills/feature-management/SKILL.md",
-      "sha256": "sha256:ba725b6be2d0f8e4d741d3a6f96e64657112c15935f8e9fd2818cd0b17380816",
-      "size_bytes": 30428
+      "sha256": "sha256:50646fd4c5884fe25b9488f223b680ad44417b96da160950b454202ea756e7f8",
+      "size_bytes": 30846
     },
     {
       "path": "skills/feature-management/agents/openai.yaml",
@@ -97,8 +97,8 @@
     },
     {
       "path": "skills/feature-management/references/contracts.md",
-      "sha256": "sha256:913d5f0ad52b5183aa3a4bdeef2b6974f7757842300f547679fee38552792892",
-      "size_bytes": 27738
+      "sha256": "sha256:b705dec6e801f95d0d354a0d0f0d6fb5bd139d5f9938f78d70f1fe108b7c95b9",
+      "size_bytes": 27741
     },
     {
       "path": "skills/feature-management/references/operator-authoring.md",
@@ -107,33 +107,48 @@
     },
     {
       "path": "skills/feature-management/references/platform-capability-guide.md",
-      "sha256": "sha256:40d0f43a30688c5852ef09203ec35b4dc2c6b9db4bc7dd26dfae52e12d10e9ee",
-      "size_bytes": 4257
+      "sha256": "sha256:6acb35f57e1bd6385702b6114e96c0ed1db34c9650d18658f74f212af9f91d14",
+      "size_bytes": 4423
+    },
+    {
+      "path": "skills/feature-management/references/supervised-datasets.md",
+      "sha256": "sha256:2c7a894330a649248e7f52c944422bcd7a3aba4558f7984d129dfd21c8736cf3",
+      "size_bytes": 4540
     },
     {
       "path": "skills/model-lifecycle-management/SKILL.md",
-      "sha256": "sha256:48c60d20ab9203cde9681fc61a0515ce3f316ad674e4f349aa21e320127a7520",
-      "size_bytes": 2837
+      "sha256": "sha256:98437e919b6d76822b2a3521713400b2c73ae42fbe5086f2e0b864aadd6cbf55",
+      "size_bytes": 3464
     },
     {
       "path": "skills/model-lifecycle-management/agents/openai.yaml",
       "sha256": "sha256:37857849a8baa6b06b6d5d07ae6036080239356fcccd36f77bbdc52c1dfa283f",
       "size_bytes": 249
     },
+    {
+      "path": "skills/model-lifecycle-management/references/discovery.md",
+      "sha256": "sha256:c87a9efacb1a18125bc1ee1b3061c5a9b876355e238aa5f7f17a985014413281",
+      "size_bytes": 4899
+    },
     {
       "path": "skills/model-lifecycle-management/references/evaluation.md",
-      "sha256": "sha256:0139e5fc79beeab84fb31792bdac37c3331676e1f591c57390ecc6336873dcc9",
-      "size_bytes": 1797
+      "sha256": "sha256:099fc54af2a1d8bed287f9e557cee8583558e594880235c32b89276b385cce90",
+      "size_bytes": 8858
     },
     {
       "path": "skills/model-lifecycle-management/references/packaging.md",
-      "sha256": "sha256:c987d4095f23a1f18ba55effb14f946e0f4cdcb661d7af28af560cc8f72d8b2c",
-      "size_bytes": 1101
+      "sha256": "sha256:fd87f0ea6f79bff0498ff1688ab782340d572815872c86520032549910160028",
+      "size_bytes": 2858
+    },
+    {
+      "path": "skills/model-lifecycle-management/references/training-contracts.md",
+      "sha256": "sha256:e93f5361f5f7cfaef53ba65b2606e58b06585d7de6c966706c66995e844b4804",
+      "size_bytes": 6909
     },
     {
       "path": "skills/model-lifecycle-management/references/training.md",
-      "sha256": "sha256:e6971f2ef9c2b8645388dd4bac4562408f7a7b1adb0b7171c7e6b4912ea48b50",
-      "size_bytes": 1852
+      "sha256": "sha256:10a6694f1904ce210f062221273a0687574354764bafb573318a5f7fcb425e55",
+      "size_bytes": 4206
     }
   ],
   "schema_version": "data_platform.ml_platform_checksums/v1"

package/package.json

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

package/release.json

@@ -13,7 +13,7 @@
     "entrypoint": "src/cli.js",
     "name": "ml-platform",
     "path": "runtime/business-client",
-    "sha256": "sha256:bbb3c59d5d7e16f92e6496e5596e59af3af4fdf4f820487d9ceb6eb85ca0857b",
+    "sha256": "sha256:fb2ebe76ddba0ccfcd052741e8e290e25fc2897df7656d48267e82fe6be06d1c",
     "version": "0.7.0"
   },
   "policy_sha256": "sha256:02fbde0134696b78c0c365d6e0b76c9814227208da5b2b3d4e5dbd82dc4a3606",
@@ -25,7 +25,7 @@
     "ml_data_platform.feature_set/v1",
     "ml_data_platform.dataset_manifest/v1"
   ],
-  "release_version": "0.1.7",
+  "release_version": "0.1.8",
   "runtime_requirements": {
     "node": ">=18",
     "os": [
@@ -38,15 +38,15 @@
     "feature-management": {
       "path": "skills/feature-management",
       "requires_cli": ">=0.7.0 <0.8.0",
-      "revision": "0.1.7",
-      "sha256": "sha256:15131c1303b143373e4b8671301f5b884013a1906a44cfc85dd6f93f43c5d8c8"
+      "revision": "0.1.8",
+      "sha256": "sha256:38ec81d73353bf8eb39ae56074c15cc0fcae14701e8aba1462b5cbd155a1fa65"
     },
     "model-lifecycle-management": {
       "path": "skills/model-lifecycle-management",
       "requires_cli": ">=0.7.0 <0.8.0",
-      "revision": "0.1.7",
-      "sha256": "sha256:b6eac3ac75a82cf27db2efe2daf2b5b8777c95a0841d48f93ada29ef08b8d8fe"
+      "revision": "0.1.8",
+      "sha256": "sha256:e3eefccb76748847975024cc6fc124df1a581d286d8de165195bd708f5dfa00f"
     }
   },
-  "source_commit": "62db427abfd17b9c8dc58964b03aec21927217b5"
+  "source_commit": "07afde3b78bcf2fcee220a136f226c0ccdf96e38"
 }

package/runtime/business-client/README.md

@@ -54,3 +54,25 @@ uv run python scripts/generate_openapi_schema.py --ref origin/dev
 uv run python scripts/generate_openapi_schema.py --ref origin/dev --check
 npm run api:check --prefix business-client-js
 ```
+
+## Lifecycle discovery and preflight
+
+Use `get-model-runtime-release` to inspect approved trainer/device/image bindings
+and the effective evaluation identity. Find immutable resources with
+`list-training-runs`, `list-training-jobs`, `list-model-artifacts`,
+`list-evaluation-configs`, `list-evaluation-runs`, `list-evaluation-jobs`,
+`list-metric-definitions`, `list-executable-packages`, and `list-model-packages`.
+These commands accept `-q`, `--limit` (1–500), and `--offset`; responses contain
+`items`, `total`, `limit`, `offset`. Query matches serialized metadata substrings.
+Use the returned exact IDs with detail commands; Job lists contain immutable
+specs, while Job detail refreshes status.
+
+`validate-training-job REQUEST_JSON` and `validate-model-package REQUEST_JSON`
+resolve the same contracts as submission without registering or scheduling
+workloads. Read `submitted=false` and `unchecked`: successful preflight does not
+verify image pulls, cluster resources or runtime execution. Complete request
+examples and identity propagation are in the bundled model lifecycle Skill.
+
+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.

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

@@ -9,7 +9,12 @@ const { PlatformApiClient } = require("./http");
 const { applyCatalog, loadCatalog, normalizeDataset, normalizeRegistryDataset } = require("./catalog");
 const { version: CLIENT_VERSION } = require("../package.json");
 
+const LIFECYCLE_COLLECTIONS = new Set(["training-runs", "training-jobs", "model-artifacts", "evaluation-configs", "evaluation-runs", "evaluation-jobs", "metric-definitions", "executable-packages", "model-packages"]);
+
 const BUSINESS_COMMANDS = new Set([
+  ...[...LIFECYCLE_COLLECTIONS].map((name) => `list-${name}`),
+  "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",
   "configure", "show-config", "health", "list-parameters", "list-operators", "list-features",
   "list-feature-sets", "list-datasets", "get-dataset", "list-jobs", "resolve-manifest",
@@ -33,6 +38,13 @@ const BUSINESS_COMMANDS = new Set([
 ]);
 
 const COMMAND_USAGE = {
+  ...Object.fromEntries([...LIFECYCLE_COLLECTIONS].map((name) => [`list-${name}`, `list-${name} [--limit N] [--offset N] [-q QUERY]`])),
+  "get-model-runtime-release": "get-model-runtime-release",
+  "get-training-run": "get-training-run RUN_ID",
+  "get-model-artifact": "get-model-artifact ARTIFACT_ID",
+  "get-executable-package": "get-executable-package NAME VERSION",
+  "validate-training-job": "validate-training-job REQUEST_JSON",
+  "validate-model-package": "validate-model-package REQUEST_JSON",
   version: "version",
   configure: "configure --api-url URL",
   "show-config": "show-config",
@@ -354,7 +366,7 @@ async function runBusinessCli(argv) {
     if (allPages && (rawLimit !== undefined || rawOffset !== undefined)) throw new Error("--all cannot be combined with --limit or --offset");
     if (allPages) result = await fetchAll(client(options), `/${endpoint}/${encodeURIComponent(project)}/${encodeURIComponent(name)}`);
     else { const limit = Number(rawLimit ?? 50); const offset = Number(rawOffset ?? 0); if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error("limit must be between 1 and 500"); if (!Number.isInteger(offset) || offset < 0) throw new Error("offset must be >= 0"); result = await client(options).get(`/${endpoint}/${encodeURIComponent(project)}/${encodeURIComponent(name)}`, { limit, offset }); }
-  } else if (options.command.startsWith("list-") && !["list-jobs", "list-dataset-artifacts", "list-trainer-definitions"].includes(options.command)) {
+  } else if (["list-parameters", "list-operators", "list-features", "list-feature-sets", "list-datasets"].includes(options.command)) {
     const endpoints = { "list-parameters": "/parameters", "list-operators": "/operators", "list-features": "/features", "list-feature-sets": "/feature-sets", "list-datasets": "/datasets" };
     const project = take(rest, "--project");
     const name = take(rest, "--name"); const version = take(rest, "--version");
@@ -439,6 +451,21 @@ async function runBusinessCli(argv) {
     const request = { manifest: readDataset(manifest), cutoff_time: cutoffTime }; if (Object.keys(realtime).length) request.realtime_fetch = realtime; result = await client(options).post("/inference-data/fetch", request);
   } else if (options.command === "fetch-inference-context") {
     result = await client(options).post("/inference-data/context", readSpec(positional(rest, "request JSON")));
+  } else if (options.command === "get-model-runtime-release") {
+    result = await client(options).get("/model-runtime-release");
+  } else if (options.command.startsWith("list-") && LIFECYCLE_COLLECTIONS.has(options.command.slice(5))) {
+    const params = {};
+    const limit = take(rest, "--limit"); const offset = take(rest, "--offset"); const query = take(rest, "-q");
+    if (limit !== undefined) { params.limit = integer(limit, "--limit"); if (params.limit < 1 || params.limit > 500) throw new Error("--limit must be between 1 and 500"); }
+    if (offset !== undefined) { params.offset = integer(offset, "--offset"); if (params.offset < 0) throw new Error("--offset must be non-negative"); }
+    if (query !== undefined) params.q = query;
+    result = await client(options).get(`/${options.command.slice(5)}`, params);
+  } else if (options.command === "get-training-run" || options.command === "get-model-artifact") {
+    const endpoint = options.command === "get-training-run" ? "training-runs" : "model-artifacts";
+    result = await client(options).get(`/${endpoint}/${encodeURIComponent(positional(rest, "resource id"))}`);
+  } else if (options.command === "get-executable-package") {
+    const name = positional(rest, "package name"); const version = positional(rest, "package version");
+    result = await client(options).get(`/executable-packages/${encodeURIComponent(name)}/${encodeURIComponent(version)}`);
   } else if (options.command === "list-trainer-definitions") {
     result = await client(options).get("/trainer-definitions");
   } else if (options.command === "get-trainer-definition") {
@@ -446,11 +473,11 @@ async function runBusinessCli(argv) {
     result = await client(options).get(`/trainer-definitions/${encodeURIComponent(project)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`);
   } else if ({
     "register-trainer": "/trainer-definitions", "register-training-run": "/training-runs", "validate-training-run": "/training-runs/validate",
-    "submit-training-job": "/training-jobs", "register-evaluation-config": "/evaluation-configs", "register-metric-definition": "/metric-definitions",
+    "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]) {
-    const endpoint = { "register-trainer": "/trainer-definitions", "register-training-run": "/training-runs", "validate-training-run": "/training-runs/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];
+    const endpoint = { "register-trainer": "/trainer-definitions", "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")));
   } else if (/^(get|retry|cancel)-training-job$/.test(options.command)) {
     const jobId = positional(rest, "training job id"); const endpoint = `/training-jobs/${encodeURIComponent(jobId)}`;

package/skills/feature-management/SKILL.md

@@ -24,9 +24,11 @@ It records versions, lineage, quality, missingness, freshness, and execution
 metadata so an algorithm project can consume data without owning source routing
 or cache details.
 
-It does not train, evaluate, or serve models; own complete business feature
+This Skill does not train, evaluate, or serve models; own complete business feature
 engineering; provision arbitrary source tables; or administer Kubernetes and
-platform services. Read
+platform services. Training, evaluation and model packaging are handled by the
+separate `model-lifecycle-management` Skill; this scope limit is not a claim that
+the platform lacks those capabilities. Read
 [references/platform-capability-guide.md](references/platform-capability-guide.md)
 when the user needs the detailed platform boundary or evidence-level explanation.
 
@@ -308,6 +310,11 @@ Reference immutable Feature versions in the exact consumer column order. Keep th
 
 ### Define The DatasetManifest
 
+For supervised datasets, read
+[references/supervised-datasets.md](references/supervised-datasets.md) before
+publishing the first version. Settle labels, clocks, split bindings and the final
+DataSchema before expensive training.
+
 Do not use DatasetManifest as a catch-all for unresolved semantics. Confirm the
 dataset purpose and consumer, then separately confirm the target grid, horizon,
 read policy, explicit Parameter outputs, rowset or rowset splits, abnormal windows and

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

@@ -524,7 +524,7 @@ Supported strategies are `event_driven`, `fixed_grid`, and
 `exact_horizon_measured` requires `horizon` and accepts a `tolerance`. An
 optional rowset `time_range` overrides the manifest range for that strategy.
 Use `rowset_splits` instead of `rowset` when training needs named strategies
-such as `support`, `validation`, and `test`; when present, it overrides the
+such as `support`, `validation`, and `test`; it is mutually exclusive with the
 single `rowset`. Split ranges must not overlap and must cover every emitted
 target row. A split-level `fixed_grid.grid` is an explicit assertion and must
 equal `DatasetManifest.time_range.grid`; it cannot silently resample one split.

package/skills/feature-management/references/platform-capability-guide.md

@@ -10,8 +10,10 @@ layer for algorithm projects. It turns confirmed source Parameters and approved
 deterministic Operators into ordered Features and reproducible DatasetManifests,
 then either materializes a batch DatasetArtifact or serves one causal realtime
 read. It owns source adapters, quality/missingness/freshness evidence, lineage,
-replay metadata, and Job execution; it does not own model training, model
-evaluation, model serving, source-table creation, or Kubernetes administration.
+replay metadata, and data Job execution. This Skill covers that data subsystem;
+use the separate model lifecycle Skill for training, evaluation and packaging.
+Model serving, source-table creation and Kubernetes administration are outside
+this Skill's scope. Do not present a Skill boundary as a platform capability gap.
 
 The following distinctions are part of the platform contract:
 

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

@@ -0,0 +1,101 @@
+# Supervised dataset preflight
+
+Use before the first immutable publication for training/evaluation. Examples
+describe the current contract; deployed capabilities still require validation.
+
+## Labels and clocks
+
+Keep labels out of FeatureSet order. Training rejects overlap with `data.labels`
+even when an input adapter would omit that column. Generic supervised labels use
+`label_materializations`, mutually exclusive with legacy `target`.
+
+Merge this fragment into a complete manifest, replacing source identities:
+
+```json
+{
+  "mode": "training",
+  "prediction": {"horizon": "5min"},
+  "label_materializations": [{
+    "name": "future_pressure",
+    "source": {"kind": "parameter", "ref": {
+      "name": "pressure", "version": "v1", "project": "default"
+    }},
+    "output_column": "future_pressure",
+    "event_time": {"source_field": "timestamp", "offset": "0min"},
+    "alignment": {"method": "exact"},
+    "missing_policy": "report",
+    "dtype": "float64"
+  }]
+}
+```
+
+`source_field` names a column in the normalized Parameter frame, commonly
+`timestamp`, not automatically the output Feature frame's `event_time`. Other
+names need source-frame evidence. The schema lists `dataset_column` and
+`operator_output`, but the current materializer supports Parameter sources;
+resolve before building rather than treating schema acceptance as runtime support.
+Choose `report`, `reject` or `drop` according to the intended label population.
+
+- `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
+  exact alignment, source time `s` matches label time `t` when `s + offset = t`.
+
+For cutoff 10:00 and horizon 5min, expect label time 10:05 and, with zero offset,
+the source value at 10:05. A positive offset is not a shortcut to future values
+and does not change the forecast horizon. `offset_minutes` belongs to legacy
+`target`, not generic label materialization. Free-form dictionaries can accept
+unused keys: inspect resolved semantics and sampled built rows too.
+
+Check every Operator's `input_schema.prediction` before publication. A maximum
+horizon of zero is incompatible with a 5min manifest. Review a new immutable
+Operator version and causal tests, or select a compatible Operator; do not
+compensate with label offsets or silently reduce the requested horizon. Zero
+horizon does not itself disable named splits.
+
+## Splits and schema must precede training
+
+`rowset_splits` is a mapping, not an array, and is mutually exclusive with
+`rowset`. Values are RowsetStrategy objects: `strategy`, optional `time_range`,
+and `grid` for `fixed_grid`. See [contracts.md](contracts.md) for the full split
+example. Fixed-grid split grids must match the manifest grid; ranges are
+half-open and must not overlap.
+
+Building splits adds `rowset_split` and can change the complete DataSchema hash.
+Settle split/metadata columns, labels, time columns, dtypes, roles and FeatureSet
+order before training. Matching feature values alone does not ensure evaluation
+compatibility after adding columns.
+
+Dataset split declaration does not populate the TrainingRun binding. Hand this
+fragment to the lifecycle consumer to merge under `data`:
+
+```json
+{
+  "splits": {
+    "assignment_column": "rowset_split",
+    "train": ["training"],
+    "validation": ["validation"],
+    "test": ["test"]
+  }
+}
+```
+
+Keys are consumer roles; array values are actual artifact assignment values.
+For a manifest split named `train`, use `["train"]`. Hand off the exact artifact
+identity, DataSchema hash, FeatureSet order, label/temporal contracts, observed
+split counts and binding together.
+
+## Evidence checkpoints
+
+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
+equation, source-label alignment, nulls and split counts. A small authorized
+diagnostic build can test source semantics but cannot replace final artifact
+identity or full-data validation.
+
+Before training, validate the TrainingRun with explicit splits and confirm
+trainer shape/device and evaluation runtime support. Do not create successive
+immutable dataset versions or launch training to discover field names. Stop at
+the first unexplained error, preserve the request and evidence outside the
+repository, and correct the draft once the cause is understood.

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

@@ -14,8 +14,19 @@ DatasetArtifact -> TrainingRun -> TrainingJob -> ModelArtifact
 
 Read [references/training.md](references/training.md) for training work, [references/evaluation.md](references/evaluation.md) for governed evaluation, and [references/packaging.md](references/packaging.md) for ModelArtifact validation and packaging. Read only the references required by the request.
 
+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.
+
 ## Shared Gates
 
+Before training a model that will be evaluated, also read
+[references/evaluation.md](references/evaluation.md). Check the final dataset
+schema, training split binding and evaluation runtime before submission.
+OpenAPI free-form dictionaries are not complete nested contracts: use the
+examples in these references and same-release validation, not successive 422s
+to discover fields. Preserve release/error evidence when deployment differs.
+
 - Establish exact immutable inputs, TrainerDefinition `v1`, runtime image digest, model inputs/targets, resources, evaluation policy, and package destination from authoritative contracts. Do not infer them from model names.
 - Validate, register, submit, retry, cancel, and package creation are separate actions. Read-only discovery and validation do not authorize mutation or workload submission.
 - Before submission, show the exact JSON path, immutable identities, expected workload, and target API. Obtain explicit authorization. Retry and cancel require separate authorization for the exact Job.

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

@@ -0,0 +1,89 @@
+# Discover exact contracts before authoring requests
+
+Use the same-release CLI/API. Start with `version`, `show-config`, `health` and
+`get-model-runtime-release`. If a documented command is absent from `--help`,
+or a new endpoint returns 404, record client/server release evidence and upgrade
+to the matching release; do not guess another resource name or submit work as a
+capability probe.
+
+## Effective runtime policy
+
+```bash
+ml-platform --profile server get-model-runtime-release
+ml-platform --profile server list-trainer-definitions
+ml-platform --profile server get-trainer-definition NAME v1 --project PROJECT
+```
+
+Discovery returns `configured`, `release_id`, `approval_policy`, and `bindings`.
+Each binding contains the exact `project/name:version:device` trainer key,
+immutable training and Serving base images, input modes and architectures.
+Compare the registered TrainerDefinition image against the binding before Job
+preflight. A binding is release approval, not proof that a matching definition
+is registered. `configured=false` means capability-based validation without a
+release allowlist; it does not mean every trainer/device is approved by a release.
+`evaluation.runtime_identity` and `default_executor` are effective server values.
+`worker_dependencies_verified=false` explicitly means discovery has not tested
+imports, image pulls or model prediction in the Worker.
+
+## Resource lookup and pagination
+
+```bash
+ml-platform --profile server list-training-runs -q pressure --limit 50 --offset 0
+ml-platform --profile server get-training-run RUN_ID
+ml-platform --profile server list-training-jobs -q RUN_ID
+ml-platform --profile server list-model-artifacts -q JOB_ID
+ml-platform --profile server get-model-artifact ARTIFACT_ID
+ml-platform --profile server list-evaluation-configs
+ml-platform --profile server list-evaluation-runs -q ARTIFACT_ID
+ml-platform --profile server list-evaluation-jobs -q RUN_ID
+ml-platform --profile server list-metric-definitions
+ml-platform --profile server list-executable-packages
+ml-platform --profile server get-executable-package NAME VERSION
+ml-platform --profile server list-model-packages -q ARTIFACT_ID
+```
+
+All these list commands return `items`, `total`, `limit`, `offset`; default limit
+is 50, maximum 500. Continue with offset plus returned item count until total is
+reached. `-q` is a case-insensitive substring of serialized metadata, not a query
+language or project authorization filter. Always verify exact identities after
+search. Collections are global metadata views; no project filter is claimed.
+Jobs in lists are immutable specs; use the exact get-job command for refreshed
+status. Lists do not reconcile or schedule workloads. `get-training-run` returns
+`training_run` plus `spec_hash`; artifact/package detail returns the object.
+
+## Read-only preflight
+
+```bash
+ml-platform --profile server validate-training-job training-job-request.json
+ml-platform --profile server validate-model-package model-package-request.json
+```
+
+Training preflight requires an already registered Run with its exact hash and
+resolves the same Job spec used by submission, including device/runtime approval,
+resources and distributed capability. Packaging preflight resolves the same
+artifact eligibility, selected runtime, input modes and immutable-version conflict
+checks used by creation. Both return `status=valid`, the proposed `job_spec` or
+`package`, `submitted=false` and `unchecked` execution checks. They do not register
+Jobs/packages or invoke schedulers. Artifact reads can populate local caches.
+
+A valid preview does not prove image availability, cluster capacity, credentials,
+framework imports, training success or packaging test success. Read `unchecked`
+and inspect an existing package's status: an immutable failed version is not
+made runnable by validation. Submission rechecks current state; preflight is not
+a reservation. Preserve the preview alongside the approved submission request.
+
+## Structured request errors
+
+Training Run `task`, `data`, `data.artifact`, `features.feature_set`, `splits`,
+`temporal` and `trainer` are explicit objects in OpenAPI. Evaluation artifact,
+config references, members and execution, plus ModelPackage requests, are also
+structured. Unknown keys return 422 with `detail[].loc` identifying the field.
+Keep algorithm-specific `trainer.parameters` and documented plugin configuration
+maps extensible; validate them against the registered plugin schema. Do not treat
+all remaining `additionalProperties` as a platform schema defect.
+
+These HTTP checks preserve accepted values and do not rewrite historical stored
+contracts or hashes. Legacy records remain readable. A previously ignored typo
+is now rejected on a new submission; correct the input rather than removing
+validation. Omit evaluation runtime identity for the server default; if execution
+is supplied it must name `executor` explicitly.

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

@@ -1,5 +1,144 @@
 # Evaluation Commands
 
+## Request bodies and prerequisites
+
+Evaluation reuses the model's original TrainingRun, replaces its artifact
+reference and compares the complete evaluation DataSchema hash with the trained
+Job's hash. Matching feature names is insufficient: added split/metadata columns
+or changed roles/dtypes can fail. Settle the final schema before training and
+validate compatibility before concluding that retraining is required.
+
+Example `evaluation-config.json` (exploratory, not a release gate):
+
+```json
+{
+  "name": "pressure_metrics",
+  "version": "v1",
+  "task_type": "regression",
+  "mode": "exploratory",
+  "metrics": [{
+    "name": "regression.mae", "version": "v1",
+    "targets": ["future_pressure"], "calculation_space": "business"
+  }]
+}
+```
+
+Inspect `get-metric-definition regression.mae v1` before relying on this metric.
+Release mode additionally requires at least one required validation rule with a
+business-approved threshold; do not invent thresholds to obtain PASS.
+
+Example `evaluation-request.json` shape; replace illustrative identities before
+validation or submission:
+
+```json
+{
+  "model_artifact_id": "replace_model_artifact_id",
+  "dataset": {
+    "project": "default",
+    "dataset_id": "replace_dataset_id",
+    "manifest_hash": "replace_with_exact_artifact_manifest_hash"
+  },
+  "rowset": "test",
+  "targets": ["future_pressure"],
+  "config": {"name": "pressure_metrics", "version": "v1"},
+  "execution": {
+    "executor": "kubernetes",
+    "resources": {"cpu": "2", "memory": "3Gi"},
+    "deadline": "90min",
+    "retry_limit": 0
+  }
+}
+```
+
+`config` is a name/version reference, not an inline policy. `targets` are
+model-bound label column names. The HTTP validation and submission endpoints
+fill omitted `runtime_identity` with the server's supported evaluation identity;
+omit it rather than guessing. Explicit pinning requires that exact identity
+(`sha256:` plus 64 hex digits), not an image digest or trainer hash. Inspect the
+returned frozen Job's `policy.runtime_identity` and retain it as evidence.
+Resources above illustrate shape, not Chronos-2 sizing guidance.
+
+If `execution` is omitted entirely, these HTTP endpoints use the configured
+server execution backend. If supplied, include `executor` explicitly: an empty
+execution dictionary falls back to the domain's `local` default. Do not assume
+the domain default is the deployed HTTP default. Kubernetes selection alone does
+not prove Worker dependency availability. Validate before submitting and confirm
+the approved Worker supports the model plugin. Successful training in another
+image does not establish evaluation support.
+
+## Diagnose before another build or training run
+
+| Symptom | Actual check and next action |
+| --- | --- |
+| `requires a named split` | Inherited TrainingRun `data.splits` is not a dictionary and requested rowset is not `all`. Inspect the original training request, not only manifest/resolved/Parquet splits. This check has no horizon-zero branch. |
+| `rowset is not declared` | Inspect `data.splits` role keys (`train`, `validation`, `test`), nonempty value arrays, assignment column and observed values. Manifest `training` can map to consumer role `train`. |
+| DataSchema mismatch | Compare the full schema with the trained Job's hash, including split columns, roles and dtypes. Do not remove columns or falsify hashes to pass. |
+| Label leakage | Materialize label columns separately from FeatureSet order; input selection alone cannot repair the contract. |
+| Chronos-2 runtime unavailable | Record executor, error stage/Job, runtime identity and Worker image evidence. The prediction plugin cannot load a dependency; request runtime support from the platform owner. New dataset/model versions do not install dependencies. |
+
+Do not change to `rowset=all` to bypass a requested holdout. Adding `data.splits`
+to EvaluationRunRequest is unsupported and cannot repair an immutable original
+TrainingRun. Explain the missing binding and validate a corrected training draft
+before any authorized retraining.
+
+`ExecutablePackage` is a custom metric Python wheel with verification and
+publication lifecycle, not a model Serving container. Built-in metrics need no
+user-created wheel. `ModelPackage` is a separate model image packaging object;
+creating one does not configure evaluation Workers or automatically satisfy the
+evaluation runtime identity. Empty package registration cannot repair a
+Chronos-2 import failure.
+
+## Discovery and evidence retention
+
+Submission returns `run.run_id`, singular `job.job_id` / `job_status` for the
+first member, and `jobs[].spec` / `jobs[].status` for all members. Track all
+members when present. `get-evaluation-job` returns `spec`, `status`, `attempts`;
+inspect `status.phase` and, on success, `status.result_id`. Top-level
+`status=accepted` is not completion. Read `spec.policy.runtime_identity` for the
+resolved runtime. There is no evaluation wait CLI; poll the get command with a
+bounded interval/deadline and preserve the ID on timeout. Do not use dataset
+`wait-job` for a training or evaluation Job.
+
+Evaluation request reuse is normally deduplicated. `force_rerun=true` explicitly
+requests another execution; do not set it to work around an unexplained timeout
+or missing result. Retry keeps the immutable contract; corrections to inputs
+require a corrected request, not a retry with hidden changed semantics.
+
+Default coverage requires at least one row and both prediction and label
+coverage of 1.0. Null labels and sequence context loss can prevent a gate pass
+despite successful computation. Do not lower coverage to obtain PASS. If the
+business policy intentionally permits incomplete coverage, declare the approved
+values under `coverage.minimum_rows`, `minimum_prediction_coverage` and
+`minimum_label_coverage`, and report the excluded population.
+
+A release-rule shape is shown below; the threshold is illustrative and must be
+replaced by a business-approved value. Merge under the policy and set
+`mode=release`; `metric` and version must also appear in `metrics`.
+
+```json
+{
+  "validation": [{
+    "metric": "regression.mae", "version": "v1",
+    "target": "future_pressure", "operator": "<=", "threshold": 1.0,
+    "required": true, "level": "job", "source": "metric", "slice": "overall"
+  }]
+}
+```
+
+`slices` names metadata/entity-key columns, not filter expressions or arbitrary
+Feature columns. `SUCCEEDED` describes execution; `PASS`, `FAIL`, `INCONCLUSIVE`
+describe decisions. Inspect required decisions and coverage before reporting
+release readiness. A Result and a Summary are distinct evidence objects;
+record the actual returned IDs rather than deriving one ID from another.
+
+Use `list-evaluation-configs`, `list-evaluation-runs`, `list-evaluation-jobs`
+and their get commands to locate prior evidence; see [discovery.md](discovery.md)
+for paging and exact identity recovery. `list-evaluation-attempts JOB_ID` lists
+attempt history, not all runs. Preserve request/config versions and returned
+run/job/result/summary IDs; do not search metric names instead of provenance.
+
+## Commands
+
 ```bash
 ml-platform --profile server register-evaluation-config evaluation-config.json
 ml-platform --profile server register-metric-definition metric-definition.json

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

@@ -1,7 +1,41 @@
 # Model Packaging Commands
 
+## Request shape and managed runtime
+
+```json
+{
+  "model_artifact_id": "replace_registered_model_artifact_id",
+  "package_version": "1.0.0",
+  "input_modes": ["inline"]
+}
+```
+
+The artifact must be `REGISTERED` and pass validation. Creation submits work;
+first use `validate-model-package` for read-only contract/runtime preflight. Version defaults to `1` if omitted;
+use an explicit immutable version (semantic versioning is a convention, not an
+enforced three-component schema). Capture `package.package_id` and
+`package.package_version` from the creation response.
+
+The server resolves images and destination from the approved trainer/device
+runtime configuration. Optional request keys `base_image`, `worker_image`,
+`builder_image`, `destination_repository` are equality assertions against that
+configuration, not arbitrary overrides. Omit them when using managed defaults;
+do not guess registries or pass deployment secrets. A mismatch needs the approved
+runtime contract, not repeated package versions. Unknown request keys return 422; do not add `runtime`, `image`, or `resources`
+fields. Inspect the returned resolved package.
+
+`input_modes` must be unique, include `inline`, and may additionally include
+`feature_lookup` only when supported by the selected runtime and artifact lineage
+has `online_eligible=true`. Do not infer online eligibility from training success.
+Omit rather than use an empty list to request default inline behavior.
+
+Always query the exact package ID and version; states are `PACKAGING`, `READY`,
+`FAILED`, `CANCELLED`. A client timeout does not prove packaging failed. Retain the
+known identity and query it before attempting another creation.
+
 ```bash
 ml-platform --profile server validate-model-artifact <artifact-id>
+ml-platform --profile server validate-model-package model-package-request.json
 ml-platform --profile server create-model-package model-package-request.json
 ml-platform --profile server get-model-package <package-id> --package-version <version>
 ```

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

@@ -0,0 +1,139 @@
+# Training request and response contracts
+
+These examples require only the released CLI, inspected registry definitions and
+downloaded dataset contracts. Replace example identities and business choices;
+they are not a ready-to-submit trainer recommendation. Never import platform
+Python modules or require a checkout to author these requests.
+
+## TrainingRunSpec
+
+Example forecasting sequence run:
+
+```json
+{
+  "schema_version": "ml_data_platform.training_run/v2",
+  "run_id": "pressure_forecast_run_01",
+  "experiment": "pressure_forecast",
+  "task": {"kind": "forecasting", "objective": "regression"},
+  "data": {
+    "artifact": {
+      "project": "default", "dataset_id": "pressure_dataset",
+      "manifest_hash": "REPLACE_WITH_RETURNED_MANIFEST_HASH"
+    },
+    "features": {"feature_set": {
+      "project": "default", "name": "pressure_features", "version": "v1"
+    }},
+    "labels": ["future_pressure"],
+    "temporal": {
+      "prediction_time_column": "event_time", "label_time_column": "label_time",
+      "frequency": "5min", "horizon": "5min", "series_keys": []
+    },
+    "splits": {
+      "assignment_column": "rowset_split", "train": ["training"],
+      "validation": ["validation"], "test": ["test"]
+    }
+  },
+  "input_adapter": {
+    "kind": "sequence", "context_length": 24,
+    "context_end": "prediction_time_inclusive", "frequency": "5min",
+    "stride": 1, "gap_policy": "reject", "padding_policy": "none"
+  },
+  "label_transform": {"name": "identity", "version": "v1"},
+  "trainer": {
+    "project": "default", "name": "replace_approved_trainer", "version": "v1",
+    "parameters": {}
+  },
+  "reproducibility": {"seed": 0, "deterministic": true},
+  "evaluation": {"split": "validation", "metrics": ["mae", "rmse", "r2"]}
+}
+```
+
+`task.kind`, objective and input kind must match inspected TrainerCapabilities.
+`trainer.parameters` must satisfy the definition's parameter schema; `{}` only
+works if no parameters are required. Resource/device settings belong to the Job,
+not the Run. `run_id` is the immutable run identity, not a name/version pair.
+Do not add guessed `version`, `model`, `dataset` or `hyperparameters` top-level keys.
+
+For tabular input use `input_adapter: {"kind":"tabular"}`; omit sequence context
+fields. Forecasting tasks still require `data.temporal`, even with tabular input.
+Non-temporal regression can omit it. Do not change task kind just to evade checks.
+`series_keys` must identify entity-key columns when multiple series coexist;
+an empty list treats the entire artifact as one series.
+
+Inspect `data_schema.json`, `resolved_manifest.json` and the feature Parquet via
+`download-dataset-artifact DATASET_ID MANIFEST_HASH --project PROJECT --out-dir DIR`
+(repeat `--file` for selective downloads). The FeatureSet reference must match
+the artifact; the full ordered FeatureSet determines model channels. There is
+no documented `data.features.columns` shortcut for choosing a subset.
+
+`identity:v1` leaves labels unchanged. `difference` requires a baseline Feature
+in `required_inputs` and at least one `online_inputs` entry, which must be a
+subset; it must have an inverse. Do not use target transforms to fix incorrect
+dataset label clocks or to invent unsupported transforms.
+
+## TrainingJobRequest and identity propagation
+
+After validation and authorized registration, use the returned `spec_hash`
+unchanged in the Job request. Do not calculate it from raw JSON bytes.
+
+```json
+{
+  "run": {
+    "run_id": "pressure_forecast_run_01",
+    "spec_hash": "REPLACE_WITH_REGISTERED_SPEC_HASH"
+  },
+  "execution": {
+    "executor": "kubernetes", "device": "cpu",
+    "resources": {"cpu": "2", "memory": "4Gi"},
+    "deadline": "90min", "retry_limit": 0
+  }
+}
+```
+
+Sizing is illustrative. `spec_hash` uses `sha256:<64 hex>`. Omit `output_uri`
+to use managed storage unless an approved contract supplies it. Runtime device
+approval occurs during Job resolution; `validate-training-run` has no execution
+device and cannot prove device approval. Use `validate-training-job` after Run registration to validate device and
+execution settings without creating a Job.
+
+| Command | Fields to retain / inspect |
+| --- | --- |
+| `validate-training-run` | `status=valid`, `spec_hash`, `data_schema_hash`, `feature_columns`, `label_columns` |
+| `register-training-run` | `training_run.run_id`, top-level `spec_hash`; response `status=validated` also represents registration, not mere dry-run |
+| `submit-training-job` | `job_spec.job_id`, `job_spec.job_spec_hash`, `job.phase`; top-level `status=accepted` is not completion |
+| `get-training-job` | `spec` and `status`; inspect `status.phase`, then successful `status.artifact_id` |
+| `validate-model-artifact` | Validation evidence for the exact returned artifact ID; Job success alone is insufficient |
+
+Use `get-training-run`, `get-model-artifact` and their list commands to recover
+identities; see [discovery.md](discovery.md). There is no training wait command.
+Preserve the original Run JSON and IDs.
+Poll `get-training-job` at a bounded interval (for example 15 seconds) with a
+user-appropriate deadline; a polling timeout does not cancel or fail the Job.
+After a submission timeout, retain the request and reconcile any known Job ID
+before retrying. Never create a new run merely because the HTTP response was lost.
+
+## Sequence population semantics
+
+Context step is `frequency * stride`. Stride spaces context observations; it
+does not select every Nth target endpoint. Inclusive context with length L covers
+offsets `(L-1)..0`; exclusive covers `L..1`. For 24 points, 5min frequency and
+stride 1, inclusive context starts 115min before the cutoff, exclusive 120min.
+Keep Operator source history and endpoint-policy lookback as separate contracts.
+
+The adapter materializes history over the full series, then assigns samples by
+the target endpoint's split. Test endpoints may use causal Feature history from
+earlier splits; splitting does not truncate their context. Duplicate timestamps
+within a series are invalid. Missing early context with no padding is skipped;
+null Features or labels also skip samples. Candidate row counts therefore are
+not training/evaluation sample counts. Report the materialized population and
+coverage instead of assuming all Parquet rows were used.
+
+`gap_policy=fill` requires `padding_policy=edge` or `zero`; non-fill requires
+`padding_policy=none`. Filling changes model inputs and needs an intended
+business policy. `skip` and padding are not automatic fixes for rejected grids.
+
+Training's `evaluation.metrics` uses `mae`, `rmse`, `r2`. Independent governed
+EvaluationConfig uses versioned names such as `regression.mae`. They are different
+contracts. Training `evaluation.split=auto` prefers nonempty test, then validation,
+then train; choose an explicit split when reserving the test set for final review.
+Training metrics are not a governed EvaluationResult or release gate pass.

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

@@ -1,5 +1,52 @@
 # Training Commands
 
+## Preflight before expensive training
+
+Settle the final DataSchema (including split/metadata and label/time columns),
+FeatureSet order and evaluation runtime before the first Job. See
+[evaluation.md](evaluation.md) for inherited split bindings and runtime failures.
+
+- Inspect exact TrainerDefinition `project/name:v1`, entrypoint, image digest,
+  capabilities and parameter schema. Similar names in different projects are
+  distinct identities; registration does not imply runtime approval.
+- Match definition and device to the active runtime release. On `not approved
+  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.
+- The current platform Chronos2Plugin requires `[sample, context, 1]`, exactly
+  one channel. This is a platform adapter restriction, not a universal statement
+  about Chronos-2. Six-feature sequences are incompatible. Do not silently drop
+  business inputs: select a suitable trainer or agree a univariate contract.
+- Keep labels outside FeatureSet order, verify temporal horizon against
+  `label_time - prediction_time`, and validate the complete TrainingRun before
+  registration/submission. Validation may not catch undeclared plugin limits or
+  missing dependencies in the eventual Worker.
+
+Merge this fragment under TrainingRun `data`, alongside `artifact`, `features`,
+`labels` and the applicable `temporal` binding:
+
+```json
+{
+  "splits": {
+    "assignment_column": "rowset_split",
+    "train": ["training"],
+    "validation": ["validation"],
+    "test": ["test"]
+  }
+}
+```
+
+`train` is the consumer role; `training` is an example observed artifact value.
+Use the actual assignment values. Evaluation inherits this original binding;
+it does not reconstruct it from manifest `rowset_splits`. Save the submitted
+TrainingRun JSON, validation output, Job ID and ModelArtifact ID in the user's
+working directory so later diagnosis needs no source repository.
+
+## Commands
+
+Read [training-contracts.md](training-contracts.md) when authoring a Run or Job
+JSON. It provides complete request shapes, response paths and sequence semantics.
+
 Discover already-registered TrainerDefinitions (read-only) before authoring a
 TrainingRunSpec or deciding whether registration is needed:
 
@@ -18,6 +65,7 @@ separate mutation below, and a 404 means the definition (not the model plugin) i
 ml-platform --profile server register-trainer trainer-definition.json
 ml-platform --profile server validate-training-run training-run.json
 ml-platform --profile server register-training-run training-run.json
+ml-platform --profile server validate-training-job training-job-request.json
 ml-platform --profile server submit-training-job training-job-request.json
 ml-platform --profile server get-training-job <job-id>
 ```