@zhuoyuezs/ml-platform 0.1.1 → 0.1.4

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

@@ -35,6 +35,9 @@ Use this reference for the implemented V1 schemas. Prefer the running CLI and `s
   `project` field in its own JSON spec (it defaults to `default` when omitted).
   So to place an asset in a non-default project, set `"project": "<name>"` in the
   spec before `apply`.
+- For a confirmed non-default target, include that field in every draft
+  Parameter, Operator, Feature, Feature input, FeatureSet, and DatasetManifest;
+  do not rely on Pydantic's `default` fallback during authoring.
 - Reads and filters, by contrast, take the project out-of-band: `list-* --project`
   and the leading project argument of the artifact commands. `apply --project`
   scopes the comparison snapshot that publication is validated against.
@@ -91,6 +94,11 @@ Required shape:
 
 Supported source modes are `direct_column`, `sql`, and `derived`. Prefer `direct_column` for ordinary business parameters.
 
+For `sql`, `source.sql` must contain one statement without a trailing semicolon,
+and named placeholders must be supplied through `source.params`; `start` and
+`end` are reserved runtime window parameters. `source.parameters` is not a
+supported field.
+
 `availability.strategy` 支持 `source_field`、`fixed_delay` 和 `unsupported`。只有一个
 事件时间列时，可以使用经过数据 owner 确认的固定延迟上界，例如
 `{"strategy":"fixed_delay","delay":"PT10M","accuracy":"upper_bound"}`。
@@ -282,6 +290,14 @@ The list must be nonempty, unique, and ordered exactly as consumers expect.
     "horizon": "10min"
   },
   "parameters": [],
+  "parameter_missing_policies": [
+    {
+      "parameter": "hot_blast_pressure",
+      "version": "v1",
+      "project": "default",
+      "policy": "report_only"
+    }
+  ],
   "feature_set": {"name": "pressure_core", "version": "v1"},
   "preprocess": [],
   "output": {
@@ -321,9 +337,13 @@ declared `realtime_fetch` policy contains meaningful defaults and changes the
 manifest hash. Declaring `endpoint_policy` also changes the manifest hash.
 
 Each explicit `parameters` request may set `missing_policy`. A
-`parameter_missing_policies` entry uses the same Parameter `name` and `version`
-but is reserved for Parameters used only through the selected FeatureSet's
-input closure; it must not also appear in `parameters`. The policies are:
+`parameter_missing_policies` entry is reserved for a Parameter used only through
+the selected FeatureSet's input closure; it must not also appear in
+`parameters`. Its exact V1 shape is `{"parameter": "<name>", "version":
+"<version>", "project": "<project>", "policy": "<policy>"}`. Do not use
+the `ParameterRequest` field names `name` or `missing_policy` in this list. For
+a confirmed non-default target, set `project` explicitly instead of relying on
+its `default` fallback. The policies are:
 
 - `report_only`: retain all target rows and report source gaps.
 - `fail_on_requested_range_gap`: fail when a detected gap affects the requested
@@ -424,13 +444,30 @@ near the end of the target range can have its lookback clipped by the range end,
 and a window close to the end can remove most remaining rows.
 
 `target` states which instant the label is aligned to, so reviewing a manifest
-shows the target definition rather than only a Parameter version string.
-`si_time_source` is `weight_time` or `dispatch_time`.
+shows the target definition rather than only a Parameter version string. When
+the target is a Parameter, keep its complete versioned reference **inside**
+`target.parameter`; do not flatten `version` or `project` onto `target`.
+`si_time_source` is `weight_time` or `dispatch_time`. `interpolation` is an
+object with a `method`, never a bare string.
 
 ```json
-"target": {"si_time_source": "weight_time", "offset_minutes": 0}
+"target": {
+  "parameter": {
+    "parameter": "hot_metal_si",
+    "version": "v1",
+    "project": "replace_with_project"
+  },
+  "si_time_source": "weight_time",
+  "offset_minutes": 0,
+  "interpolation": {"method": "linear"}
+}
 ```
 
+Allowed interpolation methods are `none`, `linear`, and `forward_fill`. A
+business phrase such as "allow and report target nulls" belongs in an existing
+Parameter missing policy, Feature configuration, or the semantic review; it is
+not a free-form `target` or DatasetManifest field.
+
 The declaration is checked against the selected Si Parameter, but only for
 `direct_column` reads, which name their time column in the contract. A `sql` or
 `derived` Parameter can apply an offset inside its query text, so those are

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

@@ -67,12 +67,17 @@ 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.
 
-If an Operator requires a forecast contract, declare `input_schema.prediction`
-with `required`, `minimum_horizon`, and `maximum_horizon`. Declare source history
-as `input_schema.history_requirements`, using `anchor: cutoff` for causal windows
-and `anchor: target_time` only for intentional target-aligned formulas. Scope a
-requirement with `output_columns` when only some outputs need it. Include alignment
-slack such as hourly floor boundaries in the declared lookback.
+An Operator requires an explicit forecast contract whenever its formula or code
+uses `context.cutoff_times`, or any `input_schema.history_requirements` entry uses
+`anchor: cutoff`. In that case always declare `input_schema.prediction` with
+`required`, `minimum_horizon`, and `maximum_horizon`. This includes a strict
+nowcast: declare `required=true` and both bounds as `0min`; do not omit the
+section and silently accept the runtime's `default_nowcast` fallback. Declare
+source history as `input_schema.history_requirements`, using `anchor: cutoff`
+for causal windows and `anchor: target_time` only for intentional target-aligned
+formulas. Scope a requirement with `output_columns` when only some outputs need
+it. Include alignment slack such as hourly floor boundaries in the declared
+lookback.
 
 For realtime reads, `history_requirements` is also the per-Parameter fetch
 contract. Do not rely on a package-local lookback map or a single fixed window
@@ -110,7 +115,10 @@ Never infer a rule from a Feature name alone. Require a business decision when a
 
 ## Required Tests
 
-Use deterministic fixtures and cover:
+Use deterministic fixtures and cover each applicable item with a separately
+named test. A broad formula or happy-path test does not substitute for the
+cutoff-before, cutoff-at, cutoff-after, duplicate/missing, empty-history,
+requested-output, event-time-order, or dtype/rounding cases below:
 
 1. expected formula values;
 2. the event immediately before cutoff;

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

@@ -0,0 +1,44 @@
+# Platform Capability Guide
+
+Use this guide to explain what the platform can execute. It is not business
+evidence. A platform default never answers an unresolved business question.
+
+## Public Assets
+
+| Asset | Stores | Use when | Do not use for |
+|---|---|---|---|
+| Project | Namespace and isolation boundary | Every independent business release | A dataset version or a source table |
+| Parameter | One readable source contract and its quality/time semantics | Raw or independently readable source values/events | Rolling means, ratios, trends, model columns |
+| Operator | Versioned deterministic executable code | A formula needs computation over declared inputs | A business definition without confirmed formula |
+| Feature | One immutable output-column contract | One model/input column produced by an Operator | A group of columns or an unnamed formula |
+| FeatureSet | Ordered Feature references | Consumer column order is part of the contract | Copying formulas or creating multiple datasets |
+| DatasetManifest | Dataset mode, time grid, rowsets, policy and FeatureSet reference | A reproducible dataset contract is ready | Filling unknown source or business semantics |
+| DatasetArtifact | Output of an authorized build | Build was explicitly approved and completed | Proving a Catalog is semantically correct |
+
+## Decision Rules
+
+- Parameter answers **what source value is exposed**; Operator/Feature answers
+  **how a confirmed business formula is computed**.
+- FeatureSet order is consumer-facing and must be confirmed; it is not inferred
+  from filesystem order or JSON discovery order.
+- Dataset `time_range`, `prediction`, `rowset_splits`, `abnormal_windows` and
+  `endpoint_policy` are separate contracts. A platform default does not choose
+  a business policy.
+- `apply --dry-run` checks structure, references, package and immutability. It
+  does not prove source correctness, formula correctness or artifact parity.
+- `publish` creates immutable Registry resources. `build` creates an execution
+  Job and must have a separate explicit approval.
+
+## Required Semantic Asset Review
+
+Before writing Catalog JSON, produce a local review table with one row per
+Parameter, Operator, Feature and Dataset field:
+
+```text
+asset_key | business_meaning | source/evidence | confirmed_by | unresolved | proposed_value
+```
+
+Stop before Catalog generation if any required `source/evidence`, formula,
+time boundary, unit, null policy, output dtype, FeatureSet order, read policy,
+or approval field is unresolved. The review table is a proposal for the user;
+it is not a Registry asset and must not contain guessed values.