@zhuoyuezs/ml-platform 0.2.8 → 0.2.10

package/skills/feature-management/references/operator-authoring.md

@@ -7,13 +7,25 @@ Read this file whenever a workflow creates or changes executable Operator code.
 1. Package contract
 2. Feature entrypoint contract
 3. Causal calculation rules
-4. Required tests
-5. Build and publication
-6. Security boundary
+4. Online period aggregates
+5. Required tests
+6. Build and publication
+7. Security boundary
 
 ## Package Contract
 
-Build a standalone pure-Python wheel. Do not import report-local, experiment-local, or unregistered business packages. Declare runtime dependencies explicitly, but keep the package small and compatible with `py3-none-any`.
+Build a standalone pure-Python wheel (`py3-none-any`). The platform verifies
+the wheel digest and only extracts it into an isolated import path; it does not
+install `Requires-Dist` dependencies, run `pip`, or accept native code. At run
+time an Operator can import only the Python standard library, its own wheel,
+and packages already present in the image that executes it: dataset builds
+(the `dataset-chronon` dependency group, which provides `pandas`, `numpy` via
+`pandas`, `pyarrow` and `pydantic`) and API realtime reads (the `api`
+dependency group). Do not import report-local, experiment-local, or
+unregistered business packages, and do not depend on libraries such as `scipy`
+or `scikit-learn` that those images do not provide; vendor small pure-Python
+helpers into the wheel instead. `[project].dependencies` documents the expected
+environment for local tests only; it does not make a dependency available.
 
 Minimal `pyproject.toml`:
 
@@ -63,9 +75,19 @@ computation_hash
 
 Each `metric_frames[parameter_key]` is a standard long frame with source timestamps and values. Resolve frames from `context.inputs`; do not reach into a database, API, filesystem secret, or environment credential.
 
-Use `context.cutoff_times` for causal feature windows. It is derived once from
-`context.target_times - context.prediction_horizon` using the DatasetManifest
-prediction contract; do not parse a duplicated Feature-level horizon.
+Use `context.cutoff_times` for causal feature windows. `context.target_times`
+are the materialized rows' `event_time` values, which are the prediction
+decision times, and `context.cutoff_times` equals them: a row's feature
+cutoff is its own `event_time`. The DatasetManifest `prediction.horizon` moves
+label availability to `label_time = event_time + horizon` (and the realtime
+response `target_time = cutoff_time + horizon`); it does not move the Operator
+context's feature reads earlier. Do not subtract `context.prediction_horizon`
+from either index, and do not parse a duplicated Feature-level horizon. This
+rule covers Operator inputs only: a DatasetManifest `endpoint_policy` evaluates
+abnormal-window context overlap with its own `cutoff = t - h` formula, described
+in [contracts.md](contracts.md). Resolved lineage records this as
+`prediction_time_semantics: event_time_is_causal_cutoff` and
+`label_time_derivation: prediction_time_plus_horizon`.
 
 An Operator requires an explicit forecast contract whenever its formula or code
 uses `context.cutoff_times`, or any `input_schema.history_requirements` entry uses
@@ -100,7 +122,11 @@ One Operator may return multiple physical columns. Each public Feature still bin
 
 ## Causal Calculation Rules
 
-State every time rule in tests and descriptions:
+State every time rule in tests and descriptions. A formula that needs the
+complete requested window rather than a bounded causal lookback (for example
+full-window interpolation or smoothing) is not partition-invariant; document
+that the Dataset must be built with `--partition-duration none
+--max-parallelism 1` (see [commands.md](commands.md)).
 
 - forecast horizon and cutoff derivation;
 - whether an event exactly at cutoff is included (`<=`) or excluded (`<`);
@@ -113,6 +139,72 @@ State every time rule in tests and descriptions:
 
 Never infer a rule from a Feature name alone. Require a business decision when a boundary is unspecified.
 
+## Online Period Aggregates
+
+Use this method when one Feature row summarizes a whole period (for example a
+day, shift or batch window) and the Feature must also be served online through
+`fetch-inference-data` or a model's `feature_lookup`. The realtime path gives
+the Operator exactly one target row, `event_time = cutoff`, and only source
+rows with `timestamp <= cutoff`, so the batch and online values agree only when
+the formula is causal and bounded.
+
+Row semantics:
+
+- Anchor the row at the period end: the row at cutoff `T` summarizes the
+  period that ended at `T` (for a daily Feature, `T` is local midnight and the
+  period is the previous day). Never label a row with the period start and
+  aggregate data after it.
+- Decide the period boundary from the source timestamp meaning, which must be
+  confirmed by the data owner (see [contracts.md](contracts.md), realtime
+  policy questions). If an hourly record is stamped at the hour start, the
+  record stamped `T` belongs to the next period, so use `[T - period, T)`. If it
+  is stamped at the hour end, the record stamped `T` closes the period, so use
+  `(T - period, T]`. Test the record exactly at `T` either way.
+
+Contract declarations:
+
+- `supports_online: true` on the Operator and `offline_online_supported: true`
+  on each Feature that will be served online.
+- `input_schema.history_requirements` with `anchor: cutoff` and a lookback that
+  covers the aggregation period, any multi-period context (for example a
+  3-day rolling statistic), and alignment slack for source timestamps. For
+  example, a daily mean that also uses the two previous days needs at least
+  `3d` plus slack. This lookback is also the per-Parameter realtime read
+  window; the default realtime floor `min_lookback=1h` is far too short for a
+  period aggregate, and it is not a substitute for the declaration.
+- `input_schema.prediction` with `required`, `minimum_horizon` and
+  `maximum_horizon` (a strict nowcast uses `true`, `0min`, `0min`).
+- Do not use `anchor: target_time` with zero lookback for a period aggregate;
+  online that reads almost nothing.
+
+Formula rules:
+
+- Use only rows inside the declared lookback that are at or before the row's
+  cutoff. A row's value must not change when data after its cutoff is added,
+  or when history older than the lookback is added or removed.
+- Freeze fitted constants in Feature `config`. Values fitted on training data,
+  such as fallback medians, clipping limits or normal ranges, must be computed
+  once offline, written into `config`, and versioned with the Feature. Do not
+  recompute them from the window at run time: the online window holds only
+  the lookback, so a recomputed value differs between batch and online and
+  between partitions. A retrain that refits these constants needs a new
+  Feature (and usually Operator) version.
+- Fill gaps only forward in time, and bound each fill by a maximum age or a
+  frozen constant. Never backward-fill from an observation after the row's
+  cutoff. Avoid backward-filling the start of the window too: the result then
+  depends on where the window starts and breaks partition invariance.
+- The Operator owns interior gap handling. The platform's realtime tolerances
+  (`allow_tail_edge_missing`, `allow_internal_gap_fill`) only judge how far the
+  newest source row lags the cutoff; they do not insert values. Keep one
+  missing-data rule, inside the Operator or a declared Parameter rule, so batch
+  builds and realtime reads compute the same value.
+- Emit data-quality flags as their own output columns, each bound to its own
+  Feature: for example a valid-observation count, an "insufficient data" flag,
+  or a business state flag such as "plant stopped". A flag tells consumers
+  that a row was computed under a fallback rule; do not hide that by silently
+  filling the value. Include a flag in the model FeatureSet only if it is an
+  intended model input.
+
 ## Required Tests
 
 Use deterministic fixtures and cover each applicable item with a separately
@@ -131,6 +223,22 @@ requested-output, event-time-order, or dtype/rounding cases below:
 9. output dtype and rounding;
 10. every dated business-rule branch.
 
+For an online-capable Operator (`supports_online: true`), also add:
+
+11. cutoff invariance: adding source rows after the cutoff leaves the row
+    unchanged;
+12. lookback invariance: adding or removing history older than the declared
+    lookback leaves the row unchanged;
+13. partition invariance: computing many cutoffs in one call equals computing
+    each cutoff alone with only its lookback window, which is what a realtime
+    read does;
+14. fallback rows: a period with no or too few valid observations produces the
+    documented fallback value and quality flag, using the frozen constants.
+
+After publication, compare `fetch-inference-data` at a few historical cutoffs
+with the same rows of a batch DatasetArtifact. Any difference means the
+Operator, its fill rule or its lookback is not causal; fix it before training.
+
 Run package tests before building the wheel. Then inspect the wheel tag and ensure it is `py3-none-any`.
 
 ## Build And Publication

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

@@ -14,6 +14,12 @@ 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.
+Parameters may read through the platform's direct database adapters or a pinned,
+published external data-platform Mapping. Mapping discovery and source query
+semantics remain owned by `$data-source-exploration`; binding its approved outputs
+to ordinary Parameters is documented in
+[data-platform-mapping.md](data-platform-mapping.md). Kubernetes Worker image and
+Secret configuration remain platform-operator responsibilities.
 
 The following distinctions are part of the platform contract:
 

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

@@ -151,6 +151,19 @@ 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.
 
+When the same immutable DatasetArtifact must be evaluated with different date
+boundaries, use the TrainingRun level derived binding instead of rebuilding the
+artifact. The supported forms are `mode: derived`, with `strategy: time_range`
+or `chronological_ratio`. Time ranges use timezone aware half open
+ranges for `train`, `validation` and optional `test`. The resolver freezes row identities and uses
+the prediction time column as the sample start. It removes rows whose
+`label_time` crosses that role's end boundary and reports the count; it never
+moves or rewrites the label. `test` remains an independent evaluation role,
+`chronological_ratio` keeps equal prediction timestamps together. Actual counts
+can differ from requested ratios. The ordinary
+`assignment_column` form remains the compatibility path for artifacts that
+already contain a split column.
+
 ## Evidence checkpoints
 
 SQL-source `verifiable=false` means the automatic clock analysis could not

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

@@ -35,6 +35,9 @@ deployment does not reach `READY` or an operation is rejected.
   the model capacity and sampling grid. In `feature_lookup` mode, never send
   `future_covariates`; the platform retrieves the complete known-future Feature
   window visible at the cutoff. Inline mode still supplies those rows in inputs.
+- Clustering deployments take no `inference_policy`, `horizon`, or
+  `output_window`; an optional `include_inputs: true` echoes the model input
+  row. See the clustering request in [references/operations.md](references/operations.md).
 - Run `validate-deployment` before `create-deployment`. Validation is read-only
   and does not authorize creation.
 - Obtain explicit authorization for the exact deployment and operation before
@@ -43,6 +46,10 @@ deployment does not reach `READY` or an operation is rejected.
   returned an ambiguous result.
 - Treat `READY` as valid only when `ReplicasReady`, `ArtifactsVerified`, and
   `SmokePredictionPassed` are all true for the current revision.
+- A READY staging revision can use unified prediction and scheduled reporting.
+  Do not promote merely to enable either workflow. Promote only when the user
+  requests routed canary/production traffic; unified prediction selects the
+  deployment's current revision and does not split traffic by canary weight.
 - Use `predict-deployment` for governed deployment verification. Do not infer
   Kubernetes Service names from a deployment ID.
 - Treat every prediction response `target_time` as China Standard Time in RFC

package/skills/model-deployment-management/references/contracts.md

@@ -72,6 +72,12 @@ continues to carry them in `inputs.future_covariates`.
 The first deployment starts at `staging`. A replacement for an existing
 service/environment declares the active leaf in `previous_deployment_id`.
 Production is reached only by staging to canary to production promotion.
+This stage sequence governs routed rollout, not eligibility for unified prediction
+or reporting: a READY staging revision is sufficient for those workflows.
+New promotion requires `service_exposure.type=Ingress` or an explicit
+`rollout.gateway_name`. NodePort alone does not provide weighted routing.
+The server checks routing prerequisites before persisting the promoted revision;
+a rejected preflight preserves the existing revision and its READY state.
 
 `service_exposure` is optional and defaults to `{"type":"ClusterIP"}`. Set
 `type=NodePort` only when direct node access is required. `node_port` is

package/skills/model-deployment-management/references/operations.md

@@ -39,7 +39,11 @@ ml-platform --profile server list-deployments \
   --model-artifact-id <artifact-id>
 ```
 
-The filters may be used independently and combined with `--service`,
+列表默认按 `deployment_id` 升序；需要按生命周期时间排序时使用
+`--sort-by created_at|updated_at --sort-order asc|desc`。
+
+Use `--service TEXT` for a case-insensitive service-name substring; surrounding
+whitespace is ignored and an empty value does not filter. The filter may be combined with
 `--environment`, `--state`, `--q`, `--limit`, and `--offset`. These results are
 ITSMP platform deployments; external model-center delivery callbacks are a
 separate status surface.
@@ -74,6 +78,20 @@ exposure mode.
 
 ## Promotion And Approval
 
+Skip this step for ordinary unified prediction or scheduled reports on a READY
+staging deployment. For weighted traffic, use an environment's existing
+ingress-nginx with `service_exposure.type=Ingress`, or an explicitly bound,
+ready Gateway via `rollout.gateway_name`. Inspect the immutable DeploymentSpec
+first; changing exposure requires a reviewed replacement deployment. Do not
+install a Gateway merely because the default ClusterIP or NodePort deployment
+cannot be promoted.
+
+Promotion performs Kubernetes routing dry-run admission before saving a new
+revision. This checks API permissions and admission, not live ingress-controller
+health or end-to-end reachability. Continue observing reconciliation and READY
+conditions after an accepted promotion. Canary weights apply to the routed
+entrypoint; `predict-deployment` directly verifies the selected revision.
+
 ```bash
 ml-platform --profile server promote-deployment <deployment-id> \
   --stage canary --actor <actor> --reason <reason>
@@ -157,6 +175,15 @@ ml-platform --profile server predict-deployment <deployment-id> \
   /absolute/path/request.json
 ```
 
+For a clustering model (`task_type: clustering` in `GET /v1/model`), send no
+`horizon` or `output_window`; they are rejected. The single result is
+`prediction: {kind: "clustering", cluster_id, distance_to_center |
+cluster_probability}` without `target_time`. Add `"include_inputs": true` to
+receive `results[0].inputs`, the validated model input row in signature column
+order (before the model's own transform); it defaults to `false`, is rejected
+for forecasting models, and requires a package image that supports it. Missing
+or non-finite retrieved inputs fail the request.
+
 For a package with an explicit `availability_boundary`, inspect
 `lineage.visibility` in the prediction response. It records the package's
 boundary, `cutoff_time`, `attempt_started_at`, `knowledge_time`,

package/skills/model-deployment-management/references/troubleshooting.md

@@ -10,6 +10,14 @@ ml-platform --profile server get-deployment-events <deployment-id> \
 
 Interpret conditions before considering a reconcile:
 
+- A rejected promotion mentioning `rollout.gateway_name`, Gateway HTTP status,
+  or routing RBAC leaves the current revision unchanged. Check it with
+  `get-deployment`; if staging is READY, unified prediction and reporting remain
+  usable. Use existing Ingress for intentional canary traffic, or correct the
+  explicit Gateway binding and permissions. Do not repeatedly promote to make
+  ordinary prediction work. Historical FAILED promotion revisions are not
+  automatically repaired by this guard; inspect the active replacement before
+  planning recovery.
 - `ReplicasReady=false`: inspect scheduler, image pull, resource quota, and Pod
   readiness through the platform/cluster diagnostic boundary.
 - `ArtifactsVerified=false`: the Serving `/model` identity does not match the

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

@@ -1,6 +1,6 @@
 ---
 name: model-lifecycle-management
-description: Manage ITSMP system-model discovery, model training, evaluation, immutable model packaging, and contract-bound inference requests. Use when a user asks to inspect platform-owned SystemModels and runtime bindings, validate or submit a training run, inspect/retry/cancel training jobs, configure or run governed evaluation, inspect evaluation evidence, validate a ModelArtifact, create and inspect a ModelPackage, or invoke a deployed model. Do not use for feature catalog authoring, dataset builds, model deployment, Kubernetes administration, or image release engineering.
+description: Manage ITSMP system-model discovery, model training, evaluation, controlled model comparison and feature/input ablation, immutable model packaging, and contract-bound inference requests. Use when a user asks to inspect platform-owned SystemModels and runtime bindings, validate or submit a training run, run a baseline/variant ablation experiment, inspect/retry/cancel training jobs, configure or run governed evaluation, inspect evaluation evidence, validate a ModelArtifact, create and inspect a ModelPackage, or invoke a deployed model. Do not use for feature catalog authoring, dataset builds, model deployment, Kubernetes administration, or image release engineering.
 ---
 
 # Model Lifecycle Management
@@ -31,10 +31,32 @@ 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.
+[references/model-comparison.md](references/model-comparison.md) and
+[references/experiment-runs.md](references/experiment-runs.md). Use the
+platform's durable `ExperimentRun` to associate candidates and reconcile jobs.
+The method still comes from this Skill; ExperimentRun does not select a winner
+or deploy a model.
+
+For feature or input ablation experiments, also read
+[references/ablation.md](references/ablation.md). Ablation is a comparison
+protocol represented by `ExperimentRun` and linked to ordinary TrainingRun and
+EvaluationRun resources; there is no separate `AblationRun` API.
+
+For unsupervised clustering (`task.kind=clustering`, for example
+`kmeans_clusterer` or `gaussian_mixture_clusterer`), read the clustering
+section of [references/training-contracts.md](references/training-contracts.md)
+for the Run, parameter and model-file contract, and the clustering section of
+[references/packaging.md](references/packaging.md) for packaging and
+single-row inference without a horizon. The cluster count and preprocessing
+have silent defaults (8 clusters for KMeans, no scaling or PCA). Ask the user
+for them, or select them with the documented method in that reference, before
+submitting a clustering Run.
+
+For clustering evaluation and registration, read the clustering section of
+[references/evaluation.md](references/evaluation.md). Use a `task_type:
+"clustering"` EvaluationConfig with `targets: ["cluster_id"]`, and label
+`all`/`train` rowset results as in-sample. Register only with one PASS,
+COMPLETE EvaluationResult for that artifact.
 
 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

package/skills/model-lifecycle-management/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "模型训练、评估与打包"
-  short_description: "管理 ITSMP 模型训练、评估与不可变模型打包流程"
-  default_prompt: "使用 $model-lifecycle-management 管理模型训练、评估或打包流程。"
+  short_description: "管理 ITSMP 模型训练、评估、比较与消融实验"
+  default_prompt: "使用 $model-lifecycle-management 管理模型训练、评估、比较或消融实验流程。"

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

@@ -0,0 +1,111 @@
+# Feature and input ablation
+
+Use this method when the question is whether a feature, feature group,
+covariate, input channel or preprocessing input contributes to a model result.
+It is a controlled comparison protocol represented by an `ExperimentRun`. The
+run links existing `TrainingRun`, `ModelArtifact`, `EvaluationRun` and
+`EvaluationResult` facts. Read [experiment-runs.md](experiment-runs.md) for
+execution and [model-comparison.md](model-comparison.md) for evidence rules.
+
+## Freeze the baseline scope
+
+Define one baseline candidate with the complete approved input FeatureSet and
+freeze these values for the whole ablation round:
+
+- the exact `DatasetArtifact` and `manifest_hash`;
+- DataSchema, label columns, prediction/label time semantics and series keys;
+- train/validation/test assignment and rowset population;
+- evaluation config, metric versions, calculation space and slices;
+- SystemModel, runtime release, reproducibility settings and execution policy.
+
+The baseline is the full input set for the hypothesis being tested. A model
+name, FeatureSet name or metric value is not enough to identify it. Store the
+baseline and variants in one immutable ExperimentRun spec.
+
+## Define variants
+
+Create one candidate per removal or replacement under test. Prefer one-factor
+variants:
+
+```text
+baseline: [load, temperature, pressure, calendar]
+remove_load: [temperature, pressure, calendar]
+remove_weather: [load, pressure, calendar]
+remove_calendar: [load, temperature, pressure]
+```
+
+Keep the retained columns in their declared order. Give every candidate a
+stable candidate ID, a short hypothesis, the exact removed input keys and the
+parent baseline candidate ID in the ExperimentRun spec. Do not change hyperparameters,
+labels, splits or evaluation policy at the same time as the ablated input.
+If several inputs must be removed together for a single hypothesis, name that
+group explicitly and do not interpret the result as the contribution of each
+member separately.
+
+For a feature-only ablation, bind each candidate to an immutable registered
+FeatureSet that is an allowed subset/order projection of the same artifact.
+The wide DatasetArtifact normally does not need rebuilding. Use
+`$feature-management` to create or discover those FeatureSet versions; do not
+edit an existing FeatureSet in place. If the hypothesis changes source data,
+operator logic, label materialization, row membership, or feature values in
+the artifact, create a new DatasetArtifact and start a separate comparison
+scope instead of calling it a feature ablation.
+
+## Execute the round
+
+1. Create one ExperimentRun with the immutable dataset identity, evaluation
+   contract, baseline candidate and variants. Use
+   [experiment-runs.md](experiment-runs.md) for the JSON shape.
+2. Validate all candidates before submitting any Job. Validation must show each
+   candidate FeatureSet, projected input columns, schema hash and runtime
+   identity. Validation has no training side effects.
+3. Submit only within the user's authorized training scope. Reconcile the
+   ExperimentRun after uncertain responses; never create a replacement run to
+   retry an unknown candidate submission.
+4. Observe every Job and validate its ModelArtifact. A failed or infrastructure
+   Job has no model-quality score and must be reported separately.
+5. Evaluate every successful artifact on the same frozen validation rowset with
+   the same EvaluationConfig. Inspect coverage, required decisions and result
+   hashes; do not compute replacement metrics locally.
+6. Inspect the ExperimentRun comparison on complete, comparable results. Use
+   the baseline as the reference and report absolute and relative metric
+   deltas. For metrics where lower is better, a positive candidate-minus-
+   baseline delta is degradation; follow the MetricDefinition rather than
+   assuming direction.
+
+Example comparison request:
+
+```json
+{
+  "schema_version": "ml_data_platform.evaluation_result_comparison_request/v1",
+  "comparison_type": "model",
+  "result_ids": ["baseline_result", "remove_load_result"],
+  "metrics": ["regression.mae", "regression.rmse"],
+  "sort_direction": "ascending"
+}
+```
+
+Do not rank candidates with different rowsets, labels, horizons, metric
+definitions or incomplete coverage. A candidate that fails because of a
+runtime, image or contract problem is inconclusive about the ablated input.
+
+## Interpret and close the round
+
+Report, for every candidate, the baseline/variant FeatureSet identities, exact
+removed inputs, TrainingRun/Job/ModelArtifact IDs, EvaluationResult IDs,
+coverage, metrics, deltas and failure evidence. A small metric difference is
+not proof that an input is useless; state the observed tolerance and whether
+the experiment had repeated seeds or uncertainty estimates. If the result is
+inconclusive, keep the input undecided rather than deleting it.
+
+Only after validation comparison selects a candidate may the normal held-out
+test procedure in `model-comparison.md` be used. The test result validates the
+locked candidate and must not be used to choose another ablation. Packaging,
+registration and deployment remain separate authorized gates.
+
+The round is complete only when every submitted candidate is accounted for as
+complete, failed, pending, unknown or skipped with a reason. Stop when the
+declared ablation set is covered, the authorized training scope is exhausted,
+or a shared data/runtime defect blocks the round. Do not add an automatic
+feature deletion threshold; business owners decide the practical impact and
+tradeoff after reviewing comparable evidence.

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

@@ -65,6 +65,20 @@ 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.
 
+## Download artifact files
+
+```bash
+ml-platform --profile server download-model-artifact ARTIFACT_ID --out-dir /tmp/model-ARTIFACT_ID [--file runtime.json]
+ml-platform --profile server download-evaluation-result-artifact RESULT_ID --out-dir /tmp/eval-RESULT_ID [--file predictions.parquet]
+```
+
+Both commands download only files indexed by the registry record (all of them
+unless `--file` is repeated), verify each sha256 against that record, and remove
+the output directory on any mismatch. `--project` fails closed when the
+resource belongs to another project. Report the returned `files[].sha256` as
+content evidence; metadata reads alone do not prove file contents. Write
+downloads outside the repository.
+
 ## Read-only preflight
 
 ```bash
@@ -97,10 +111,11 @@ Training Run `task`, `data`, `data.artifact`, `features.feature_set`, `splits`,
 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` governed by the SystemModel
-parameter schema. A typed nested contract such as Chronos-2 `lora_config`
+parameter schema. A typed contract such as Chronos-2 `lora_config` or the
+KMeans/Gaussian Mixture clustering parameters (including `preprocessing`)
 rejects unknown fields; a SystemModel that intentionally advertises
-`additionalProperties` remains extensible. Do not infer one policy from the
-other.
+`additionalProperties` remains extensible. Read `additionalProperties` from
+the exact SystemModel instead of inferring one model's policy from another.
 
 These HTTP checks preserve accepted values and do not rewrite historical stored
 contracts or hashes. Legacy records remain readable. A previously ignored typo