@zhuoyuezs/ml-platform 0.1.4 → 0.1.5

package/CI-ARTIFACT.md

@@ -0,0 +1,21 @@
+# CI npm artifact
+
+每次 `dev`/`main` 分支更新、合并请求或从 GitLab UI 手动运行的 Pipeline 都会生成完整的
+`@zhuoyuezs/ml-platform` tarball。
+GitLab pipeline 的 `npm:ml-platform-release` job 会将 `business-client-js` 放入正式包的
+`runtime/business-client`，并上传已验收的 `.tgz` 与 `.sha256` 文件。
+
+创建与 `npm/ml-platform/package.json` 版本一致的 SemVer tag（例如 `v0.1.5`）后，
+同一个已验收归档会自动发布到 npmjs。发布 job 需要在 GitLab CI/CD Variables 中配置
+受保护且 masked 的 `NPM_TOKEN`；普通分支、手动 Pipeline 和 Merge Request 不会发布 npm。
+
+下载 artifact 后只需要 Node.js 18+：
+
+```bash
+sha256sum -c zhuoyuezs-ml-platform-*.tgz.sha256
+npm install --global ./zhuoyuezs-ml-platform-*.tgz
+ml-platform version
+```
+
+运行已安装的 CLI 不需要 Python、`uv`、Git 仓库或平台源码。`uv` 只在 CI 构建阶段用于
+执行现有的 release staging 脚本。

package/DEVELOPMENT.md

@@ -146,8 +146,9 @@ Host 副本、日志、会话数据、attic、凭证和实验文件。
 - Codex project/user scope 和显式 Skills 目录；
 - 最终归档敏感文件和重复 client 检查。
 
-完成标准：同一个不可变 `.tgz` 通过全部验收，并作为唯一允许发布的输入。没有明确发布授权时，
-仍不执行 npmjs 或其他外部发布。
+完成标准：同一个不可变 `.tgz` 通过全部验收，并作为唯一允许发布的输入。GitLab CI 仅在
+SemVer tag（`vX.Y.Z` 或 `X.Y.Z`）与 `package.json.version` 一致、且配置了 `NPM_TOKEN` 时
+自动执行 npmjs 发布；dev、main 和 Merge Request pipeline 只生成并保存 artifact。
 
 ## 4. package.json
 
@@ -260,9 +261,10 @@ npx @zhuoyuezs/ml-platform@<version> install
 - 不执行 GitHub Release 或其他未授权的外部发布；
 - candidate 验证后不得用相同版本重新构建不同内容。
 
-当前允许使用 npm 账号 2FA 完成人工发布。后续迁移到受控 CI 时，优先使用 npm Trusted
-Publishing 和 OIDC，并在受支持的公开 CI 环境执行 `npm publish --provenance`。本地登录不能
-替代 CI provenance，未建立可信发布工作流前不得宣称包具有对应来源证明。
+受控 GitLab CI 使用 masked/protected 的 `NPM_TOKEN` 临时配置 npm auth，并发布 builder 生成的
+同一个 `.tgz`；token 不写入仓库或归档。本地登录不能替代 CI provenance，当前 token 发布也不
+宣称包具有 provenance 来源证明。后续可迁移到 npm Trusted Publishing 和 OIDC，并在受支持的
+公开 CI 环境执行 `npm publish --provenance`。
 
 ## 9. 参考与取舍
 

package/checksums.json

@@ -2,18 +2,18 @@
   "files": [
     {
       "path": "runtime/business-client/README.md",
-      "sha256": "sha256:4bca6d490a0ac3de54accb8f9f43003cdfb0c187bcf1acefea48728b16001e94",
-      "size_bytes": 1233
+      "sha256": "sha256:72b0cbbb18a7d0f1bca5d97706588fbebcd2781833ae023bae0317be13342601",
+      "size_bytes": 1880
     },
     {
       "path": "runtime/business-client/package-lock.json",
-      "sha256": "sha256:a253eb945f8666779adfbf9e7009c539b450746298f145bbe4d0b2ca5f4cbe35",
+      "sha256": "sha256:d5e7102ec51df3192ae901908f36cf0380aba5a0421b9824877403ab034d6740",
       "size_bytes": 381
     },
     {
       "path": "runtime/business-client/package.json",
-      "sha256": "sha256:bf29516fcbd162fe051f6ea142bd604dead0be99c461bc184a59e7c526766aa4",
-      "size_bytes": 426
+      "sha256": "sha256:b784fa27db6e40f72da11b9bca007155146174bc33edc4511c61d4ea4af93cf1",
+      "size_bytes": 508
     },
     {
       "path": "runtime/business-client/src/catalog.js",
@@ -22,8 +22,8 @@
     },
     {
       "path": "runtime/business-client/src/cli.js",
-      "sha256": "sha256:db25cecb760a2b94ac1433c1d04ab70b429825e78dd1168e72688d8b9a8556be",
-      "size_bytes": 25911
+      "sha256": "sha256:f2634e346a4c5bdc42c81e316791906f809b768a77672e36d29cc51410c010ed",
+      "size_bytes": 29818
     },
     {
       "path": "runtime/business-client/src/config.js",
@@ -32,13 +32,13 @@
     },
     {
       "path": "runtime/business-client/src/http.js",
-      "sha256": "sha256:95ac9342c09605966f055dde2ac5cd67fdf28e8bc877e2233e3c48077ffdd729",
-      "size_bytes": 12429
+      "sha256": "sha256:e515b39f19e7b5e7d6c2388e9cf2d8e2c9fd18b585bb53bd4f8eeeb7412af81c",
+      "size_bytes": 15192
     },
     {
       "path": "skills/feature-management/SKILL.md",
-      "sha256": "sha256:69842537b8df63e58630ca0581575f29f6ec9e97d22c9c2c30b1575270161f6e",
-      "size_bytes": 28100
+      "sha256": "sha256:7b58cc4ff2a7b83a29a6dbf9ad54e9e4a02efd332cd01c5d8fb83020b51ea506",
+      "size_bytes": 29676
     },
     {
       "path": "skills/feature-management/agents/openai.yaml",
@@ -107,8 +107,8 @@
     },
     {
       "path": "skills/feature-management/references/platform-capability-guide.md",
-      "sha256": "sha256:fb606c3637891dab462d5b94004b60a3b8f02eb178aef589716f968c3b87cd5e",
-      "size_bytes": 2627
+      "sha256": "sha256:40d0f43a30688c5852ef09203ec35b4dc2c6b9db4bc7dd26dfae52e12d10e9ee",
+      "size_bytes": 4257
     }
   ],
   "schema_version": "data_platform.ml_platform_checksums/v1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuoyuezs/ml-platform",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "ML 数据平台 business CLI 与 Agent Skills 管理工具",
   "bin": {
     "ml-platform": "scripts/main.js"
@@ -13,10 +13,13 @@
     "release.json",
     "checksums.json",
     "README.md",
-    "DEVELOPMENT.md"
+    "DEVELOPMENT.md",
+    "CI-ARTIFACT.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "api:check": "node ../../scripts/check_api_contract.js",
+    "pack": "npm pack"
   },
   "engines": {
     "node": ">=18"

package/release.json

@@ -13,8 +13,8 @@
     "entrypoint": "src/cli.js",
     "name": "ml-platform",
     "path": "runtime/business-client",
-    "sha256": "sha256:bf935c8c82aa508c26afa4f76dc94dd3d9e23c6e2bb33d797190d548a0c98249",
-    "version": "0.6.0"
+    "sha256": "sha256:b509f9ccdedc4aa5d4d01c77609e4a16020ac6f74c62efc3af861877d897fe94",
+    "version": "0.7.0"
   },
   "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.1.4",
+  "release_version": "0.1.5",
   "runtime_requirements": {
     "node": ">=18",
     "os": [
@@ -37,10 +37,10 @@
   "skills": {
     "feature-management": {
       "path": "skills/feature-management",
-      "requires_cli": ">=0.6.0 <0.7.0",
-      "revision": "0.1.4",
-      "sha256": "sha256:0ae088bcfbb4b9a0fcfa22752bd978b2a34ab033d63af4ebb4f641d3c2ac65fd"
+      "requires_cli": ">=0.7.0 <0.8.0",
+      "revision": "0.1.5",
+      "sha256": "sha256:ea7ef622f10300a3b5ee200adcf10070d18fadfb899d1bf2cc031ef42ffc5c03"
     }
   },
-  "source_commit": "2f92b97d658f16ebc6f2081b07a56365aeced649"
+  "source_commit": "d18a5b535a2a6c41fe4732e8e73739f2728c1e58"
 }

package/runtime/business-client/README.md

@@ -25,3 +25,20 @@ ml-platform build-registered-dataset <dataset_id> <dataset_version> \
 
 `resolve-manifest` 和 `build-dataset <manifest.json>` 仍用于尚未注册的本地契约。Catalog
 normalizer 保留并校验非默认 `project`；`apply --project` 与 Catalog 内项目不一致时拒绝执行。
+
+Registry 资产详情和版本发现使用与 `dev` OpenAPI 一致的命令：
+
+```bash
+ml-platform get-parameter <name> <version> --project <project>
+ml-platform get-feature <name> <version> --project <project>
+ml-platform list-feature-versions <name> --project <project> --all
+ml-platform list-jobs --project <project> --status succeeded --all
+```
+
+仓库中的 `api-spec/latest.json` 从 `origin/dev` 生成。同步或验证契约时运行：
+
+```bash
+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
+```

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

@@ -1,12 +1,12 @@
 {
   "name": "@zhuoyuezs/ml-platform-business-client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@zhuoyuezs/ml-platform-business-client",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "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.6.0",
+  "version": "0.7.0",
   "private": true,
   "description": "JavaScript parity implementation of the ML Platform business client",
   "bin": {
@@ -11,7 +11,9 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "api:check": "node ../scripts/check_api_contract.js",
+    "pack": "npm pack"
   },
   "engines": {
     "node": ">=18"

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

@@ -14,6 +14,8 @@ const BUSINESS_COMMANDS = new Set([
   "configure", "show-config", "health", "list-parameters", "list-operators", "list-features",
   "list-feature-sets", "list-datasets", "get-dataset", "list-jobs", "resolve-manifest",
   "resolve-dataset", "build-dataset", "build-registered-dataset",
+  "get-parameter", "get-feature", "get-feature-set", "get-operator",
+  "list-parameter-versions", "list-feature-versions", "list-feature-set-versions", "list-operator-versions",
   "add-parameter", "add-feature", "add-feature-set", "add-operator", "publish-operator",
   "add-dataset", "update-dataset", "delete-dataset", "list-dataset-artifacts",
   "register-operator", "show-operator-specs", "delete-operator", "run-operator",
@@ -29,11 +31,19 @@ const COMMAND_USAGE = {
   "list-projects": "list-projects",
   "get-project": "get-project NAME",
   "delete-project": "delete-project NAME",
-  "list-parameters": "list-parameters [--project PROJECT] [-q QUERY] [--limit N] [--offset N]",
-  "list-operators": "list-operators [--project PROJECT] [-q QUERY] [--limit N] [--offset N]",
-  "list-features": "list-features [--project PROJECT] [-q QUERY] [--limit N] [--offset N]",
-  "list-feature-sets": "list-feature-sets [--project PROJECT] [-q QUERY] [--limit N] [--offset N]",
-  "list-datasets": "list-datasets [--project PROJECT] [-q QUERY] [--limit N] [--offset N] [--include-deleted]",
+  "list-parameters": "list-parameters [--project PROJECT] [--name NAME] [--version VERSION] [-q QUERY] [--limit N] [--offset N] [--all]",
+  "list-operators": "list-operators [--project PROJECT] [--name NAME] [--version VERSION] [-q QUERY] [--limit N] [--offset N] [--all]",
+  "list-features": "list-features [--project PROJECT] [--name NAME] [--version VERSION] [-q QUERY] [--limit N] [--offset N] [--all]",
+  "list-feature-sets": "list-feature-sets [--project PROJECT] [--name NAME] [--version VERSION] [-q QUERY] [--limit N] [--offset N] [--all]",
+  "list-datasets": "list-datasets [--project PROJECT] [--dataset-id ID] [--dataset-version VERSION] [-q QUERY] [--limit N] [--offset N] [--include-deleted] [--all]",
+  "get-parameter": "get-parameter NAME VERSION [--project PROJECT]",
+  "get-feature": "get-feature NAME VERSION [--project PROJECT]",
+  "get-feature-set": "get-feature-set NAME VERSION [--project PROJECT]",
+  "get-operator": "get-operator NAME VERSION [--project PROJECT]",
+  "list-parameter-versions": "list-parameter-versions NAME [--project PROJECT] [--limit N] [--offset N] [--all]",
+  "list-feature-versions": "list-feature-versions NAME [--project PROJECT] [--limit N] [--offset N] [--all]",
+  "list-feature-set-versions": "list-feature-set-versions NAME [--project PROJECT] [--limit N] [--offset N] [--all]",
+  "list-operator-versions": "list-operator-versions NAME [--project PROJECT] [--limit N] [--offset N] [--all]",
   "add-parameter": "add-parameter SPEC_JSON",
   "add-feature": "add-feature SPEC_JSON",
   "add-feature-set": "add-feature-set SPEC_JSON",
@@ -44,7 +54,7 @@ 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 [-q QUERY] [--limit N] [--offset N]",
+  "list-jobs": "list-jobs [filters] [-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]",
@@ -58,7 +68,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]",
-  "download-dataset-artifact": "download-dataset-artifact DATASET_ID MANIFEST_HASH [--project PROJECT] --out-dir PATH [--force]",
+  "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]",
   apply: "apply CATALOG_DIRECTORY [--dry-run] [--project PROJECT]",
 };
@@ -245,17 +255,39 @@ async function runBusinessCli(argv) {
   } else if (options.command === "get-dataset") {
     const datasetId = positional(rest, "dataset id"); const datasetVersion = positional(rest, "dataset version"); const project = take(rest, "--project", "default");
     result = await registeredDataset(client(options), project, datasetId, datasetVersion, boolean(rest, "--include-deleted"));
-  }
-  else if (options.command.startsWith("list-") && !["list-jobs", "list-dataset-artifacts"].includes(options.command)) {
+  } else if (["get-parameter", "get-feature", "get-feature-set", "get-operator"].includes(options.command)) {
+    const resource = options.command.slice(4);
+    const endpoint = resource === "feature-set" ? "feature-sets" : `${resource}s`;
+    const name = positional(rest, `${resource} name`);
+    const version = positional(rest, `${resource} version`);
+    const project = take(rest, "--project", "default");
+    result = await client(options).get(`/${endpoint}/${encodeURIComponent(project)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`);
+  } else if (["list-parameter-versions", "list-feature-versions", "list-feature-set-versions", "list-operator-versions"].includes(options.command)) {
+    const resource = options.command.replace(/^list-/, "").replace(/-versions$/, "");
+    const endpoint = resource === "feature-set" ? "feature-sets" : `${resource}s`;
+    const name = positional(rest, `${resource} name`);
+    const project = take(rest, "--project", "default");
+    const allPages = boolean(rest, "--all");
+    const rawLimit = take(rest, "--limit"); const rawOffset = take(rest, "--offset");
+    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"].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");
     const query = take(rest, "--q", take(rest, "-q")); const includeDeleted = options.command === "list-datasets" && boolean(rest, "--include-deleted"); const rawLimit = take(rest, "--limit"); const rawOffset = take(rest, "--offset");
-    if (rawLimit !== undefined || rawOffset !== undefined) { 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(endpoints[options.command], { q: query, limit, offset, project, include_deleted: includeDeleted }); }
-    else result = await fetchAll(client(options), endpoints[options.command], { q: query, project, include_deleted: includeDeleted });
+    const allPages = boolean(rest, "--all");
+    if (allPages && (rawLimit !== undefined || rawOffset !== undefined)) throw new Error("--all cannot be combined with --limit or --offset");
+    if (allPages) result = await fetchAll(client(options), endpoints[options.command], { q: query, project, name, version, include_deleted: includeDeleted });
+    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(endpoints[options.command], { q: query, limit, offset, project, name, version, include_deleted: includeDeleted }); }
   } else if (options.command === "list-jobs") {
     const query = take(rest, "--q", take(rest, "-q")); const rawLimit = take(rest, "--limit"); const rawOffset = take(rest, "--offset");
-    if (rawLimit !== undefined || rawOffset !== undefined) { 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("/jobs", { q: query, limit, offset }); }
-    else result = await fetchAll(client(options), "/jobs", { q: query });
+    const filters = {}; for (const field of ["project", "dataset-id", "dataset-version", "manifest-hash", "status", "parent-job-id", "created-from", "created-to", "updated-from", "updated-to"]) filters[field.replaceAll("-", "_")] = take(rest, `--${field}`);
+    const allPages = boolean(rest, "--all");
+    if (allPages && (rawLimit !== undefined || rawOffset !== undefined)) throw new Error("--all cannot be combined with --limit or --offset");
+    if (allPages) result = await fetchAll(client(options), "/jobs", { q: query, ...filters });
+    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("/jobs", { q: query, limit, offset, ...filters }); }
   }
   else if (options.command === "resolve-manifest") {
     const manifest = positional(rest, "manifest");
@@ -314,7 +346,11 @@ async function runBusinessCli(argv) {
   } else if (options.command === "download-dataset-artifact") {
     const dataset = positional(rest, "dataset id"); const hash = positional(rest, "manifest hash"); const project = take(rest, "--project", "default"); const outDir = take(rest, "--out-dir");
     if (!outDir) throw new Error("--out-dir is required");
-    result = await client(options).downloadDatasetArtifact(project, dataset, hash, resolvedPath(outDir), boolean(rest, "--force"));
+    const files = [];
+    while (rest.includes("--file")) files.push(take(rest, "--file"));
+    result = files.length
+      ? await client(options).downloadDatasetArtifactFiles(project, dataset, hash, files, resolvedPath(outDir), boolean(rest, "--force"))
+      : await client(options).downloadDatasetArtifact(project, dataset, hash, resolvedPath(outDir), boolean(rest, "--force"));
   } else if (options.command === "fetch-inference-data") {
     const manifest = positional(rest, "manifest"); const cutoffTime = take(rest, "--cutoff-time"); if (!cutoffTime) throw new Error("--cutoff-time is required");
     const realtime = {}; const maxWorkers = take(rest, "--max-workers"); const maxLag = take(rest, "--max-source-lag-hours"); if (maxWorkers !== undefined) { realtime.max_workers = integer(maxWorkers, "--max-workers"); if (realtime.max_workers < 1) throw new Error("--max-workers must be at least 1"); } if (maxLag !== undefined) { realtime.max_source_lag_hours = finiteNumber(maxLag, "--max-source-lag-hours"); if (realtime.max_source_lag_hours < 0) throw new Error("--max-source-lag-hours must be non-negative"); } if (boolean(rest, "--no-validate-freshness")) realtime.validate_freshness = false; if (boolean(rest, "--allow-missing")) realtime.allow_missing = true;

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

@@ -95,6 +95,52 @@ class PlatformApiClient {
       fs.rmSync(temporaryDir, { recursive: true, force: true });
     }
   }
+
+  async downloadDatasetArtifactFiles(project, datasetId, manifestHash, relativePaths, outputDir, force = false) {
+    const files = [...new Set((relativePaths || []).map((value) => String(value)))];
+    if (!files.length) throw new Error("at least one artifact file is required");
+    for (const relative of files) {
+      const normalized = relative.replace(/\\/g, "/");
+      const parts = normalized.split("/");
+      if (!normalized || normalized.startsWith("/") || normalized.endsWith("/") || parts.includes("..")) {
+        throw new Error(`artifact path escapes output directory: ${JSON.stringify(relative)}`);
+      }
+    }
+    const targetRoot = path.resolve(expandHome(outputDir));
+    if (fs.existsSync(targetRoot) && fs.readdirSync(targetRoot).length) {
+      if (!force) throw new Error(`download output directory is not empty: ${targetRoot}`);
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+    fs.mkdirSync(targetRoot, { recursive: true });
+    try {
+      for (const relative of files) {
+        const normalized = relative.replace(/\\/g, "/");
+        const parts = normalized.split("/");
+        const destination = path.resolve(targetRoot, ...parts);
+        if (!normalized || normalized.startsWith("/") || normalized.endsWith("/")
+          || parts.includes("..") || destination !== targetRoot && !destination.startsWith(`${targetRoot}${path.sep}`)) {
+          throw new Error(`artifact path escapes output directory: ${JSON.stringify(relative)}`);
+        }
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        const endpoint = `/dataset-artifacts/${encodeURIComponent(project)}/${encodeURIComponent(datasetId)}/${encodeURIComponent(manifestHash)}/files/${parts.map(encodeURIComponent).join("/")}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+          const response = await fetch(this.url(endpoint), { headers: { Accept: "application/octet-stream" }, signal: controller.signal });
+          if (!response.ok) {
+            let detail = response.statusText;
+            try { detail = JSON.parse(await response.text())?.detail ?? detail; } catch (_) { /* status text */ }
+            throw new Error(`artifact file download failed: HTTP ${response.status}: ${detail}`);
+          }
+          fs.writeFileSync(destination, Buffer.from(await response.arrayBuffer()), { flag: "wx" });
+        } finally { clearTimeout(timer); }
+      }
+    } catch (error) {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+      throw error;
+    }
+    return { project, dataset_id: datasetId, manifest_hash: manifestHash, output_dir: targetRoot, file_count: files.length, files: files.sort() };
+  }
 }
 
 function contentLength(response) {

package/skills/feature-management/SKILL.md

@@ -14,6 +14,34 @@ Operator ------> Feature -> FeatureSet -> DatasetManifest -> DatasetArtifact
 
 Treat `Recipe` and public `Feature.compute` as removed. Treat `computation_hash` as internal execution metadata, never as a business-managed asset.
 
+## Platform Role And Evidence Boundaries
+
+The ML Platform is a deterministic data-contract and data-delivery platform. It
+registers versioned source Parameters, runs approved deterministic Operators,
+orders single-column Features into FeatureSets, resolves DatasetManifests, and
+materializes batch DatasetArtifacts or serves one causal realtime inference row.
+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
+engineering; provision arbitrary source tables; or administer Kubernetes and
+platform services. Read
+[references/platform-capability-guide.md](references/platform-capability-guide.md)
+when the user needs the detailed platform boundary or evidence-level explanation.
+
+Keep these evidence rules active in every workflow:
+
+- Platform defaults and capabilities are not business evidence.
+- Dry-run, publish, resolve, build, metadata inspection, downloaded-file
+  inspection, and realtime fetch are separate evidence checkpoints; success at
+  one checkpoint does not imply success at the next.
+- `validation.ok=true` does not by itself prove source semantics, causal formula
+  correctness, Parquet contents, or numeric parity.
+- Dry-run, publish, and resolve may not detect a missing source relation. Do not
+  report source-backed success until build/fetch returns the required evidence,
+  and never rename a Parameter or remove fields merely to bypass a failed read.
+
 ## Load The Right Context
 
 1. Resolve the Skill root as the directory containing this `SKILL.md`.

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

@@ -3,6 +3,35 @@
 Use this guide to explain what the platform can execute. It is not business
 evidence. A platform default never answers an unresolved business question.
 
+## Platform In One Paragraph
+
+The platform is a versioned data-contract, registry, execution, and delivery
+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.
+
+The following distinctions are part of the platform contract:
+
+- A `Parameter` is a public source-data contract, not an arbitrary raw table or
+  a model feature.
+- An `Operator` is versioned executable code; a `Feature` is exactly one output
+  column; a `FeatureSet` is the consumer-visible column order.
+- A `DatasetManifest` is a versioned request for time range, read policy,
+  rowsets, missing/endpoint rules, prediction, and one FeatureSet.
+- A `DatasetArtifact` is an output of an authorized build, not evidence that the
+  source contract or business formula was semantically approved.
+- Realtime inference is a causal cutoff read. It must not run a batch build,
+  write Parquet, or publish a DatasetArtifact.
+
+Dry-run and registry resolution are structural evidence. They may not detect a
+missing source relation; source-backed success must be established by the build
+or realtime fetch response. Artifact metadata is separate from downloaded-file
+evidence: schema, column order, file hashes, and numeric parity require the
+complete files.
+
 ## Public Assets
 
 | Asset | Stores | Use when | Do not use for |