@zhuoyuezs/ml-platform 0.2.8 → 0.2.10

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

@@ -7,7 +7,7 @@ const { configPath, expandHome, loadApiUrl, normalizeApiUrl, saveApiUrl } = requ
 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 LIFECYCLE_COLLECTIONS = new Set(["training-runs", "training-jobs", "model-artifacts", "evaluation-configs", "evaluation-runs", "evaluation-jobs", "metric-definitions", "executable-packages", "model-packages", "experiment-runs"]);
 const BUSINESS_COMMANDS = new Set([
     ...[...LIFECYCLE_COLLECTIONS].map((name) => `list-${name}`),
     "get-model-runtime-release", "get-training-run", "get-model-artifact", "get-executable-package",
@@ -15,6 +15,9 @@ const BUSINESS_COMMANDS = new Set([
     "version", "create-project", "list-projects", "get-project", "delete-project",
     "get-dataset-contract-file", "validate-evaluation-comparison",
     "configure", "show-config", "health",
+    "data-platform-status", "list-data-platform-connections", "get-data-platform-connection",
+    "list-data-platform-objects", "list-data-platform-mappings", "list-data-platform-query-candidates", "get-data-platform-mapping-revision",
+    "bind-data-platform-parameters", "query-data-platform", "get-data-platform-query", "get-data-platform-snapshot",
     "list-datasource-connections", "list-datasource-namespaces", "list-datasource-objects",
     "list-datasource-fields", "query-datasource-object", "create-datasource-connection",
     "get-datasource-connection", "update-datasource-connection", "delete-datasource-connection",
@@ -25,7 +28,7 @@ const BUSINESS_COMMANDS = new Set([
     "get-parameter", "get-feature", "get-feature-set", "get-operator",
     "delete-parameter", "delete-feature", "delete-feature-set",
     "restore-parameter", "restore-feature", "restore-feature-set",
-    "get-parameter-lifecycle", "get-feature-lifecycle", "get-feature-set-lifecycle",
+    "get-parameter-lifecycle", "get-feature-lifecycle", "get-feature-set-lifecycle", "get-parameter-freshness",
     "list-parameter-references", "list-feature-references", "list-feature-set-references",
     "list-parameter-versions", "list-feature-versions", "list-feature-set-versions", "list-operator-versions",
     "add-parameter", "add-feature", "add-feature-set", "add-operator", "publish-operator",
@@ -34,10 +37,12 @@ const BUSINESS_COMMANDS = new Set([
     "get-job", "wait-job", "retry-job", "cancel-job", "get-dataset-artifact", "download-dataset-artifact", "fetch-inference-data", "fetch-inference-context", "predict-model", "apply",
     "list-foundation-models", "get-foundation-model", "predict-foundation", "predict-foundation-csv",
     "list-system-models", "get-system-model", "register-training-run", "validate-training-run", "submit-training-job", "get-training-job", "retry-training-job", "cancel-training-job",
+    "create-experiment-run", "validate-experiment-run", "submit-experiment-run", "get-experiment-run", "list-experiment-candidates", "reconcile-experiment-run", "cancel-experiment-run",
     "register-evaluation-config", "get-evaluation-config", "register-metric-definition", "get-metric-definition",
     "register-executable-package", "verify-executable-package", "publish-executable-package",
     "validate-evaluation-run", "submit-evaluation", "get-evaluation-run", "get-evaluation-job", "retry-evaluation-job", "cancel-evaluation-job", "list-evaluation-attempts",
     "get-evaluation-result", "get-evaluation-result-metrics", "get-evaluation-result-artifacts", "summarize-evaluation-run", "get-evaluation-summary",
+    "download-model-artifact", "download-evaluation-result-artifact",
     "create-model-package", "get-model-package", "cancel-model-package", "validate-model-artifact", "register-model-artifact",
     "list-business-domains", "list-scenarios", "create-scenario", "put-deployment-metadata",
     "list-deployment-targets", "validate-deployment", "create-deployment", "list-deployments",
@@ -61,6 +66,17 @@ const COMMAND_USAGE = {
     configure: "configure --api-url URL",
     "show-config": "show-config",
     health: "health",
+    "data-platform-status": "data-platform-status",
+    "list-data-platform-connections": "list-data-platform-connections",
+    "get-data-platform-connection": "get-data-platform-connection CONNECTION_ID",
+    "list-data-platform-objects": "list-data-platform-objects CONNECTION_ID",
+    "list-data-platform-mappings": "list-data-platform-mappings [--page N] [--page-size N] [--scope-code CODE]",
+    "list-data-platform-query-candidates": "list-data-platform-query-candidates",
+    "get-data-platform-mapping-revision": "get-data-platform-mapping-revision MAPPING_ID REVISION_ID",
+    "bind-data-platform-parameters": "bind-data-platform-parameters SPEC_JSON",
+    "query-data-platform": "query-data-platform SPEC_JSON",
+    "get-data-platform-query": "get-data-platform-query RUN_ID",
+    "get-data-platform-snapshot": "get-data-platform-snapshot SNAPSHOT_ID [--offset N] [--limit N]",
     "list-datasource-connections": "list-datasource-connections [--limit N] [--cursor CURSOR]",
     "list-datasource-namespaces": "list-datasource-namespaces CONNECTION_ID [--limit N] [--cursor CURSOR]",
     "list-datasource-objects": "list-datasource-objects CONNECTION_ID NAMESPACE_ID [--limit N] [--cursor CURSOR]",
@@ -91,6 +107,7 @@ const COMMAND_USAGE = {
     "restore-feature": "restore-feature NAME VERSION [--project PROJECT] [--actor ACTOR] [--reason TEXT] [--idempotency-key KEY]",
     "restore-feature-set": "restore-feature-set NAME VERSION [--project PROJECT] [--actor ACTOR] [--reason TEXT] [--idempotency-key KEY]",
     "get-parameter-lifecycle": "get-parameter-lifecycle NAME VERSION [--project PROJECT]",
+    "get-parameter-freshness": "get-parameter-freshness NAME VERSION [--project PROJECT] [--lookback DURATION] [--end TIMESTAMP] [--online]",
     "get-feature-lifecycle": "get-feature-lifecycle NAME VERSION [--project PROJECT]",
     "get-feature-set-lifecycle": "get-feature-set-lifecycle NAME VERSION [--project PROJECT]",
     "list-parameter-references": "list-parameter-references NAME VERSION [--project PROJECT] [--direct]",
@@ -159,11 +176,20 @@ const COMMAND_USAGE = {
     "get-evaluation-result": "get-evaluation-result RESULT_ID",
     "get-evaluation-result-metrics": "get-evaluation-result-metrics RESULT_ID",
     "get-evaluation-result-artifacts": "get-evaluation-result-artifacts RESULT_ID",
+    "download-model-artifact": "download-model-artifact ARTIFACT_ID --out-dir PATH [--file NAME] [--project PROJECT] [--force]",
+    "download-evaluation-result-artifact": "download-evaluation-result-artifact RESULT_ID --out-dir PATH [--file NAME] [--project PROJECT] [--force]",
     "summarize-evaluation-run": "summarize-evaluation-run RUN_ID",
     "get-evaluation-summary": "get-evaluation-summary SUMMARY_ID",
     "create-model-package": "create-model-package REQUEST_JSON [--idempotency-key KEY]",
     "get-model-package": "get-model-package PACKAGE_ID [--package-version VERSION]",
     "cancel-model-package": "cancel-model-package PACKAGE_ID [--package-version VERSION]",
+    "create-experiment-run": "create-experiment-run SPEC_JSON",
+    "validate-experiment-run": "validate-experiment-run RUN_ID",
+    "submit-experiment-run": "submit-experiment-run RUN_ID",
+    "get-experiment-run": "get-experiment-run RUN_ID",
+    "list-experiment-candidates": "list-experiment-candidates RUN_ID [--limit N] [--offset N]",
+    "reconcile-experiment-run": "reconcile-experiment-run RUN_ID",
+    "cancel-experiment-run": "cancel-experiment-run RUN_ID",
     "validate-model-artifact": "validate-model-artifact ARTIFACT_ID",
     "register-model-artifact": "register-model-artifact ARTIFACT_ID --evaluation-id EVALUATION_ID",
     "list-business-domains": "list-business-domains",
@@ -173,7 +199,7 @@ const COMMAND_USAGE = {
     "list-deployment-targets": "list-deployment-targets",
     "validate-deployment": "validate-deployment SPEC_JSON --evaluation-id ID",
     "create-deployment": "create-deployment SPEC_JSON --evaluation-id ID",
-    "list-deployments": "list-deployments [--service SERVICE] [--environment ENV] [--package-id ID] [--package-version VERSION] [--model-artifact-id ID] [--state STATE] [--business-domain-id ID] [--scenario-id ID] [-q QUERY] [--limit N] [--offset N]",
+    "list-deployments": "list-deployments [--service TEXT] [--environment ENV] [--package-id ID] [--package-version VERSION] [--model-artifact-id ID] [--state STATE] [--business-domain-id ID] [--scenario-id ID] [-q QUERY] [--sort-by deployment_id|created_at|updated_at] [--sort-order asc|desc] [--limit N] [--offset N]",
     "get-deployment": "get-deployment DEPLOYMENT_ID",
     "wait-deployment": "wait-deployment DEPLOYMENT_ID [--poll-interval SECONDS] [--wait-timeout-seconds SECONDS]",
     "reconcile-deployment": "reconcile-deployment DEPLOYMENT_ID",
@@ -200,10 +226,22 @@ const COMMAND_USAGE = {
     "get-prediction-report-run": "get-prediction-report-run RUN_ID",
     apply: "apply CATALOG_DIRECTORY [--dry-run] [--project PROJECT]",
 };
+const IDEMPOTENCY_HEADER_NOTE = "--idempotency-key is sent as the Idempotency-Key header; the current server does not enforce it, so inspect platform state before retrying an uncertain submission.";
+const BUILD_WAIT_NOTE = "With --wait, a succeeded result adds artifact.manifest_hash: the DatasetArtifact key for get/download-dataset-artifact and training/evaluation dataset bindings. The top-level manifest_hash identifies the submitted manifest and is not an artifact key.";
+// Help-only notes. Keep them out of COMMAND_USAGE, which is also the argv grammar.
+const COMMAND_NOTES = {
+    "download-dataset-artifact": "MANIFEST_HASH is the artifact manifest hash (list-dataset-artifacts, or artifact.manifest_hash from build-registered-dataset --wait), not the registered manifest hash.",
+    "build-dataset": BUILD_WAIT_NOTE,
+    "build-registered-dataset": BUILD_WAIT_NOTE,
+    "wait-job": "A succeeded build Job result adds artifact.manifest_hash, the DatasetArtifact key.",
+    "download-model-artifact": "Downloads every indexed ModelArtifact file, or only each --file NAME, and verifies each sha256 against the registry record. --project fails closed when the artifact belongs to another project.",
+    "download-evaluation-result-artifact": "Downloads every indexed EvaluationResult file (for example predictions.parquet, metrics.json, runtime.json), or only each --file NAME, and verifies each sha256 against the registry record.",
+    ...Object.fromEntries(["create-project", "register-training-run", "submit-training-job", "register-evaluation-config", "submit-evaluation", "create-model-package"].map((name) => [name, IDEMPOTENCY_HEADER_NOTE])),
+};
 function usage(command) {
     const prefix = "ml-platform [--profile server] [--api-url URL] [--request-timeout-seconds SECONDS]";
     if (command)
-        return `usage: ${prefix} ${COMMAND_USAGE[command]}\n`;
+        return `usage: ${prefix} ${COMMAND_USAGE[command]}\n${COMMAND_NOTES[command] ? `\n${COMMAND_NOTES[command]}\n` : ""}`;
     return `usage: ${prefix} COMMAND [ARGS]\n\ncommands:\n  ${[...BUSINESS_COMMANDS].join("\n  ")}\n`;
 }
 function parse(args) {
@@ -363,12 +401,33 @@ async function submitBuild(api, manifest, build) {
     if (build.wait) {
         if (!result || typeof result !== "object" || !result.job_id)
             throw new Error("server build did not return a job_id to wait for");
-        result = await waitForJob(api, String(result.job_id), build.pollInterval, build.waitTimeout);
+        result = withBuildArtifact(await waitForJob(api, String(result.job_id), build.pollInterval, build.waitTimeout));
         if (["failed", "cancelled"].includes(result.status))
             exitCode = 1;
     }
     return { result, exitCode };
 }
+// A build Job's top-level manifest_hash identifies the submitted (registered)
+// manifest. The published DatasetArtifact is keyed by the resolved contract hash,
+// so surface it additively as `artifact` for downloads and dataset bindings.
+function withBuildArtifact(job) {
+    if (!job || typeof job !== "object" || Array.isArray(job) || job.status !== "succeeded")
+        return job;
+    const resolved = job.resolved_manifest;
+    if (!resolved || typeof resolved !== "object" || !resolved.manifest_hash)
+        return job;
+    return {
+        ...job,
+        artifact: {
+            project: resolved.project ?? job.manifest?.project ?? "default",
+            dataset_id: resolved.dataset_id ?? job.manifest?.dataset_id ?? null,
+            dataset_version: resolved.dataset_version ?? job.manifest?.dataset_version ?? null,
+            manifest_hash: resolved.manifest_hash,
+            artifact_uri: resolved.artifact_uri ?? null,
+            row_count: resolved.row_count ?? null,
+        },
+    };
+}
 async function waitForJob(api, jobId, pollInterval, timeoutSeconds) {
     if (!(pollInterval > 0))
         throw new Error("job poll interval must be positive");
@@ -453,6 +512,42 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
     }
     else if (options.command === "health")
         result = await client(options).get("/health");
+    else if (options.command === "data-platform-status")
+        result = await client(options).get("/data-platform/status");
+    else if (options.command === "list-data-platform-connections")
+        result = await client(options).get("/data-platform/connections");
+    else if (options.command === "list-data-platform-query-candidates")
+        result = await client(options).get("/data-platform/query-candidates");
+    else if (["get-data-platform-connection", "list-data-platform-objects"].includes(options.command)) {
+        const id = encodeURIComponent(positional(rest, "connection id"));
+        const suffix = options.command === "list-data-platform-objects" ? "/objects" : "";
+        result = await client(options).get(`/data-platform/connections/${id}${suffix}`);
+    }
+    else if (options.command === "list-data-platform-mappings") {
+        result = await client(options).get("/data-platform/mappings", {
+            page: integer(take(rest, "--page", "1"), "page"),
+            page_size: integer(take(rest, "--page-size", "50"), "page size"),
+            scope_code: take(rest, "--scope-code"),
+        });
+    }
+    else if (options.command === "get-data-platform-mapping-revision") {
+        const mappingId = encodeURIComponent(positional(rest, "mapping id"));
+        const revisionId = encodeURIComponent(positional(rest, "revision id"));
+        result = await client(options).get(`/data-platform/mappings/${mappingId}/revisions/${revisionId}`);
+    }
+    else if (options.command === "bind-data-platform-parameters")
+        result = await client(options).post("/data-platform/parameters", readSpec(positional(rest, "binding spec JSON")));
+    else if (options.command === "query-data-platform")
+        result = await client(options).post("/data-platform/query-runs", readSpec(positional(rest, "query spec JSON")));
+    else if (options.command === "get-data-platform-query")
+        result = await client(options).get(`/data-platform/query-runs/${encodeURIComponent(positional(rest, "run id"))}`);
+    else if (options.command === "get-data-platform-snapshot") {
+        const id = encodeURIComponent(positional(rest, "snapshot id"));
+        result = await client(options).get(`/data-platform/snapshots/${id}/rows`, {
+            offset: integer(take(rest, "--offset", "0"), "offset"),
+            limit: integer(take(rest, "--limit", "200"), "limit"),
+        });
+    }
     else if (options.command === "list-datasource-connections") {
         result = await client(options).get("/datasource-connections", datasourcePageParams(rest));
     }
@@ -559,6 +654,21 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
             actor: take(rest, "--actor") || "anonymous", reason: take(rest, "--reason", ""), idempotency_key: take(rest, "--idempotency-key"),
         });
     }
+    else if (options.command === "get-parameter-freshness") {
+        const name = positional(rest, "parameter name");
+        const version = positional(rest, "parameter version");
+        const project = take(rest, "--project", "default");
+        const params = {};
+        const lookback = take(rest, "--lookback");
+        const end = take(rest, "--end");
+        if (lookback !== undefined)
+            params.lookback = lookback;
+        if (end !== undefined)
+            params.end = end;
+        if (boolean(rest, "--online"))
+            params.online = true;
+        result = await client(options).get(`/parameters/${encodeURIComponent(project)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}/freshness`, params);
+    }
     else if (/^get-(parameter|feature|feature-set)-lifecycle$/.test(options.command)) {
         const name = positional(rest, "resource name");
         const version = positional(rest, "resource version");
@@ -730,7 +840,7 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
         const jobId = positional(rest, "job id");
         const poll = finiteNumber(take(rest, "--poll-interval", 2), "--poll-interval");
         const rawTimeout = take(rest, "--wait-timeout-seconds");
-        result = await waitForJob(client(options), jobId, poll, rawTimeout === undefined ? undefined : finiteNumber(rawTimeout, "--wait-timeout-seconds"));
+        result = withBuildArtifact(await waitForJob(client(options), jobId, poll, rawTimeout === undefined ? undefined : finiteNumber(rawTimeout, "--wait-timeout-seconds")));
         if (["failed", "cancelled"].includes(result.status))
             exitCode = 1;
     }
@@ -868,6 +978,8 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
             business_domain_id: take(rest, "--business-domain-id"),
             scenario_id: take(rest, "--scenario-id"),
             q: take(rest, "--q", take(rest, "-q")),
+            sort_by: take(rest, "--sort-by"),
+            sort_order: take(rest, "--sort-order"),
         };
         boolean(rest, "--all");
         result = await listCollection(client(options), "/deployments", params, rest);
@@ -997,6 +1109,34 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
     else if (options.command === "get-model-runtime-release") {
         result = await client(options).get("/model-runtime-release");
     }
+    else if (options.command === "create-experiment-run") {
+        result = await client(options).post("/experiment-runs", readSpec(positional(rest, "experiment JSON")));
+    }
+    else if (/^(validate|submit|reconcile|cancel)-experiment-run$/.test(options.command)) {
+        const runId = positional(rest, "experiment run id");
+        const action = options.command.split("-")[0];
+        result = await client(options).post(`/experiment-runs/${encodeURIComponent(runId)}/${action}`);
+    }
+    else if (options.command === "get-experiment-run") {
+        result = await client(options).get(`/experiment-runs/${encodeURIComponent(positional(rest, "experiment run id"))}`);
+    }
+    else if (options.command === "list-experiment-candidates") {
+        const runId = positional(rest, "experiment run id");
+        const params = {};
+        const limit = take(rest, "--limit");
+        const offset = take(rest, "--offset");
+        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");
+        }
+        result = await client(options).get(`/experiment-runs/${encodeURIComponent(runId)}/candidates`, params);
+    }
     else if (options.command.startsWith("list-") && LIFECYCLE_COLLECTIONS.has(options.command.slice(5))) {
         const params = {};
         const limit = take(rest, "--limit");
@@ -1074,6 +1214,36 @@ async function runBusinessCli(argv, output = { write: text => process.stdout.wri
         const suffix = options.command.endsWith("-metrics") ? "/metrics" : options.command.endsWith("-artifacts") ? "/artifacts" : "";
         result = await client(options).get(`/evaluation-results/${encodeURIComponent(resultId)}${suffix}`);
     }
+    else if (options.command === "download-model-artifact" || options.command === "download-evaluation-result-artifact") {
+        const model = options.command === "download-model-artifact";
+        const resourceId = positional(rest, model ? "model artifact id" : "evaluation result id");
+        const outDir = take(rest, "--out-dir");
+        const project = take(rest, "--project");
+        const force = boolean(rest, "--force");
+        if (!outDir)
+            throw new Error("--out-dir is required");
+        const files = [];
+        while (rest.includes("--file"))
+            files.push(take(rest, "--file"));
+        const api = client(options);
+        let index;
+        let owner = project;
+        if (model) {
+            const record = await api.get(`/model-artifacts/${encodeURIComponent(resourceId)}`);
+            if (project !== undefined && record.project !== project)
+                throw new Error(`model artifact ${resourceId} belongs to project ${JSON.stringify(record.project)}, not ${JSON.stringify(project)}`);
+            index = record.files;
+            owner = record.project;
+        }
+        else {
+            const listing = await api.get(`/evaluation-results/${encodeURIComponent(resourceId)}/artifacts`);
+            if (!Array.isArray(listing.items))
+                throw new Error("evaluation result artifact listing has no items");
+            index = Object.fromEntries(listing.items.map((item) => [String(item.name), String(item.sha256)]));
+        }
+        const downloaded = await api.downloadLifecycleArtifactFiles(model ? "model-artifacts" : "evaluation-results", resourceId, index, files, resolvedPath(outDir), { force, project });
+        result = { [model ? "model_artifact_id" : "result_id"]: resourceId, ...downloaded, project: owner ?? null };
+    }
     else if (/^(get-evaluation-config|get-metric-definition)$/.test(options.command)) {
         const name = positional(rest, "resource name");
         const version = positional(rest, "resource version");
@@ -1137,7 +1307,7 @@ async function listCollection(api, endpoint, params, rest) {
         throw new Error("offset must be >= 0");
     return api.get(endpoint, { ...params, limit, offset });
 }
-module.exports = { BUSINESS_COMMANDS, fetchAll, listCollection, parse, runBusinessCli, usage, waitForDeployment, waitForJob };
+module.exports = { BUSINESS_COMMANDS, COMMAND_NOTES, withBuildArtifact, fetchAll, listCollection, parse, runBusinessCli, usage, waitForDeployment, waitForJob };
 if (require.main === module) {
     runBusinessCli(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => {
         process.stderr.write(`error: ${error.message}\n`);

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const crypto = require("crypto");
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
@@ -16,14 +17,120 @@ function apiErrorDetail(result, fallback) {
         return result.detail;
     return JSON.stringify(result, null, 2);
 }
+// Render the body of a failed binary download with the same rules as JSON calls,
+// so structured FastAPI `detail` objects never collapse to "[object Object]".
+async function responseErrorDetail(response, signal) {
+    let text = "";
+    try {
+        text = String(await (signal ? abortable(response.text(), signal) : response.text()));
+    }
+    catch (_) { /* fall back to status text */ }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (_) {
+        parsed = undefined;
+    }
+    return apiErrorDetail(parsed, text.trim() || response.statusText || "request failed");
+}
+function safeRelativeArtifactPath(relative) {
+    const normalized = String(relative).replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    if (!normalized || normalized.startsWith("/") || parts.some((part) => part === "" || part === "." || part === "..")) {
+        throw new Error(`artifact path escapes output directory: ${JSON.stringify(String(relative))}`);
+    }
+    return { normalized, parts };
+}
+// Connection-failure policy. A failure is retried only when it happened before
+// any response headers arrived AND either
+//   - the method is idempotent (GET/HEAD): transient connection errors and the
+//     per-attempt timeout are retried with bounded backoff; or
+//   - any method: the TCP connection was never established (connection refused
+//     or connect timeout), which proves no request bytes reached the server.
+// Every other failure of a non-idempotent request (for example a reset after
+// the request was written) is reported once, because the server may already
+// have applied it.
+const IDEMPOTENT_METHODS = new Set(["GET", "HEAD"]);
+const UNSENT_CONNECT_CODES = new Set(["ECONNREFUSED", "UND_ERR_CONNECT_TIMEOUT"]);
+const TRANSIENT_CONNECTION_CODES = new Set([
+    ...UNSENT_CONNECT_CODES, "UND_ERR_SOCKET", "UND_ERR_CLOSED", "ECONNRESET", "EPIPE", "ETIMEDOUT", "ECONNABORTED",
+    "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN", "EAI_AGAIN",
+]);
+const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000];
+// Error codes along the `cause` chain (undici wraps socket errors as
+// `TypeError: fetch failed` with the real error in `cause`; happy-eyeballs
+// connects may report an AggregateError with per-address errors).
+function errorCodes(error, seen = new Set()) {
+    if (!error || typeof error !== "object" || seen.has(error))
+        return [];
+    seen.add(error);
+    const own = typeof error.code === "string" ? [error.code] : [];
+    const nested = Array.isArray(error.errors) ? error.errors.flatMap((item) => errorCodes(item, seen)) : [];
+    return [...own, ...nested, ...errorCodes(error.cause, seen)];
+}
+function describeError(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const details = [];
+    const seen = new Set([error]);
+    let cause = error.cause;
+    while (cause && typeof cause === "object" && !seen.has(cause)) {
+        seen.add(cause);
+        const message = cause.message || (Array.isArray(cause.errors) ? cause.errors.map((item) => item?.message).filter(Boolean).join("; ") : "");
+        details.push([cause.code, message].filter(Boolean).join(": "));
+        cause = cause.cause;
+    }
+    const suffix = details.filter(Boolean);
+    return suffix.length ? `${error.message} (${suffix.join(" <- ")})` : error.message;
+}
+function retryableFailure(method, error, timedOut) {
+    if (IDEMPOTENT_METHODS.has(method))
+        return timedOut || errorCodes(error).some((code) => TRANSIENT_CONNECTION_CODES.has(code));
+    if (timedOut)
+        return false;
+    const codes = errorCodes(error);
+    return codes.length > 0 && codes.every((code) => UNSENT_CONNECT_CODES.has(code));
+}
 class PlatformApiClient {
-    constructor(baseUrl, timeoutSeconds = 30) {
+    constructor(baseUrl, timeoutSeconds = 30, { retryDelaysMs = DEFAULT_RETRY_DELAYS_MS } = {}) {
         this.baseUrl = String(baseUrl).trim().replace(/\/+$/, "");
         if (!/^https?:\/\//.test(this.baseUrl))
             throw new Error("server profile api_url must start with http:// or https://");
         if (!(timeoutSeconds > 0))
             throw new Error("request timeout must be positive");
         this.timeoutMs = timeoutSeconds * 1000;
+        this.retryDelaysMs = [...retryDelaysMs];
+    }
+    // Send one request and return once response headers arrive. The caller owns
+    // the returned per-attempt timeout and must call `done()` after reading the
+    // body. Each request asks for `Connection: close`, so no pooled keep-alive
+    // socket is ever reused after the server (uvicorn closes idle sockets after
+    // 5 s) or a VPN/NAT hop has dropped it.
+    async open(method, url, { headers = {}, body } = {}) {
+        for (let attempt = 0;; attempt += 1) {
+            const controller = new AbortController();
+            let timedOut = false;
+            const timer = setTimeout(() => { timedOut = true; controller.abort(); }, this.timeoutMs);
+            try {
+                const response = await fetch(url, { method, headers: { ...headers, Connection: "close" }, body, signal: controller.signal });
+                return { response, signal: controller.signal, done: () => clearTimeout(timer) };
+            }
+            catch (error) {
+                clearTimeout(timer);
+                const detail = timedOut ? `request timed out after ${this.timeoutMs / 1000}s (${describeError(error)})` : describeError(error);
+                const delay = this.retryDelaysMs[attempt];
+                if (delay !== undefined && retryableFailure(method, error, timedOut)) {
+                    process.stderr.write(`platform API ${method} ${url}: ${detail}; retrying in ${delay}ms (attempt ${attempt + 2}/${this.retryDelaysMs.length + 1})\n`);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                const attempts = attempt ? ` after ${attempt + 1} attempts` : "";
+                const ambiguous = !IDEMPOTENT_METHODS.has(method) && !retryableFailure(method, error, timedOut)
+                    ? "; not retried because the server may have received it; inspect platform state before resubmitting" : "";
+                throw new Error(`platform API request failed: ${method} ${url}: ${detail}${attempts}${ambiguous}`);
+            }
+        }
     }
     url(endpoint, params = {}) {
         const url = new URL(endpoint.replace(/^\//, ""), `${this.baseUrl}/`);
@@ -34,8 +141,6 @@ class PlatformApiClient {
         return url;
     }
     async request(method, endpoint, { params, payload, body, contentType, requestHeaders } = {}) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         const headers = { Accept: "application/json" };
         Object.assign(headers, requestHeaders || {});
         let requestBody = body;
@@ -45,17 +150,17 @@ class PlatformApiClient {
         }
         else if (contentType)
             headers["Content-Type"] = contentType;
-        let response;
+        const { response, done } = await this.open(method, this.url(endpoint, params), { headers, body: requestBody });
+        let text;
         try {
-            response = await fetch(this.url(endpoint, params), { method, headers, body: requestBody, signal: controller.signal });
+            text = await response.text();
         }
         catch (error) {
-            throw new Error(`platform API request failed: ${method} ${this.url(endpoint, params)}: ${error.message}`);
+            throw new Error(`platform API request failed: ${method} ${this.url(endpoint, params)}: reading response: ${describeError(error)}`);
         }
         finally {
-            clearTimeout(timer);
+            done();
         }
-        const text = await response.text();
         let result;
         try {
             result = JSON.parse(text);
@@ -115,20 +220,15 @@ class PlatformApiClient {
             fs.rmSync(target, { recursive: true, force: true });
         }
         fs.mkdirSync(target, { recursive: true });
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
         const temporaryDir = fs.mkdtempSync(path.join(os.tmpdir(), "data-platform-artifact-download-"));
         const temporary = path.join(temporaryDir, "artifact.zip");
-        let response;
+        let done = () => { };
         try {
-            response = await fetch(this.url(`/dataset-artifacts/${encodeURIComponent(project)}/${encodeURIComponent(datasetId)}/${encodeURIComponent(manifestHash)}/download`), { headers: { Accept: "application/zip" }, signal: controller.signal });
+            const opened = await this.open("GET", this.url(`/dataset-artifacts/${encodeURIComponent(project)}/${encodeURIComponent(datasetId)}/${encodeURIComponent(manifestHash)}/download`), { headers: { Accept: "application/zip" } });
+            const { response, signal } = opened;
+            done = opened.done;
             if (!response.ok) {
-                let detail = response.statusText;
-                try {
-                    detail = JSON.parse(await abortable(response.text(), controller.signal))?.detail ?? detail;
-                }
-                catch (_) { /* use status text */ }
-                throw new Error(`artifact download failed: HTTP ${response.status}: ${detail}`);
+                throw new Error(`artifact download failed: HTTP ${response.status}: ${await responseErrorDetail(response, signal)}`);
             }
             const total = contentLength(response);
             let lastReported = -1;
@@ -139,7 +239,7 @@ class PlatformApiClient {
                 }
             };
             report(0);
-            await writeResponseBody(response, temporary, controller.signal, report);
+            await writeResponseBody(response, temporary, signal, report);
             const files = await extractArchive(temporary, target);
             return { dataset_id: datasetId, manifest_hash: manifestHash, output_dir: target, file_count: files.length, files };
         }
@@ -147,10 +247,10 @@ class PlatformApiClient {
             fs.rmSync(target, { recursive: true, force: true });
             if (error instanceof Error && error.message.startsWith("artifact download failed:"))
                 throw error;
-            throw new Error(`artifact download failed: ${error.message}`);
+            throw new Error(`artifact download failed: ${describeError(error)}`);
         }
         finally {
-            clearTimeout(timer);
+            done();
             fs.rmSync(temporaryDir, { recursive: true, force: true });
         }
     }
@@ -183,22 +283,15 @@ class PlatformApiClient {
                 }
                 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);
+                const { response, signal, done } = await this.open("GET", this.url(endpoint), { headers: { Accept: "application/octet-stream" } });
                 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}`);
+                        throw new Error(`artifact file download failed: HTTP ${response.status}: ${await responseErrorDetail(response, signal)}`);
                     }
                     fs.writeFileSync(destination, Buffer.from(await response.arrayBuffer()), { flag: "wx" });
                 }
                 finally {
-                    clearTimeout(timer);
+                    done();
                 }
             }
         }
@@ -208,6 +301,71 @@ class PlatformApiClient {
         }
         return { project, dataset_id: datasetId, manifest_hash: manifestHash, output_dir: targetRoot, file_count: files.length, files: files.sort() };
     }
+    // Download indexed ModelArtifact/EvaluationResult files one by one and verify
+    // each against the sha256 recorded in the registry index before keeping it.
+    async downloadLifecycleArtifactFiles(collection, resourceId, index, relativePaths, outputDir, { force = false, project = undefined } = {}) {
+        if (!["model-artifacts", "evaluation-results"].includes(collection))
+            throw new Error(`unsupported artifact collection: ${collection}`);
+        if (!index || typeof index !== "object" || Array.isArray(index))
+            throw new Error(`${collection} record has no file index`);
+        const available = Object.keys(index).sort();
+        const requested = relativePaths && relativePaths.length ? [...new Set(relativePaths.map((value) => String(value)))] : available;
+        if (!requested.length)
+            throw new Error(`${collection} record indexes no files: ${resourceId}`);
+        const plan = requested.map((relative) => safeRelativeArtifactPath(relative));
+        const missing = plan.filter((item) => !Object.prototype.hasOwnProperty.call(index, item.normalized)).map((item) => item.normalized);
+        if (missing.length)
+            throw new Error(`file is not indexed by ${collection}/${resourceId}: ${missing.join(", ")}; available: ${available.join(", ")}`);
+        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 });
+        const downloaded = [];
+        try {
+            for (const { normalized, parts } of plan) {
+                const destination = path.resolve(targetRoot, ...parts);
+                if (!destination.startsWith(`${targetRoot}${path.sep}`))
+                    throw new Error(`artifact path escapes output directory: ${JSON.stringify(normalized)}`);
+                fs.mkdirSync(path.dirname(destination), { recursive: true });
+                const endpoint = `/${collection}/${encodeURIComponent(resourceId)}/files/${parts.map(encodeURIComponent).join("/")}`;
+                const partial = `${destination}.partial`;
+                let done = () => { };
+                try {
+                    const opened = await this.open("GET", this.url(endpoint, { project }), { headers: { Accept: "application/octet-stream" } });
+                    const { response, signal } = opened;
+                    done = opened.done;
+                    if (!response.ok)
+                        throw new Error(`artifact file download failed: ${normalized}: HTTP ${response.status}: ${await responseErrorDetail(response, signal)}`);
+                    const hash = crypto.createHash("sha256");
+                    let size = 0;
+                    await writeResponseBody(response, partial, signal, () => { }, (chunk) => { hash.update(chunk); size += chunk.length; });
+                    const actual = `sha256:${hash.digest("hex")}`;
+                    const expected = String(index[normalized]);
+                    const served = response.headers?.get?.("x-artifact-sha256");
+                    if (actual !== expected || (served && served !== expected)) {
+                        throw new Error(`artifact file checksum mismatch: ${normalized}: registry ${expected}, downloaded ${actual}${served && served !== expected ? `, server header ${served}` : ""}`);
+                    }
+                    fs.renameSync(partial, destination);
+                    downloaded.push({ name: normalized, sha256: actual, size_bytes: size });
+                }
+                finally {
+                    done();
+                    fs.rmSync(partial, { force: true });
+                }
+            }
+        }
+        catch (error) {
+            fs.rmSync(targetRoot, { recursive: true, force: true });
+            if (error instanceof Error && /^artifact (file|path)/.test(error.message))
+                throw error;
+            throw new Error(`artifact file download failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        downloaded.sort((left, right) => left.name.localeCompare(right.name));
+        return { output_dir: targetRoot, file_count: downloaded.length, verified: true, files: downloaded };
+    }
 }
 function contentLength(response) {
     const raw = response.headers?.get?.("content-length") ?? response.headers?.["content-length"];
@@ -228,13 +386,15 @@ function abortable(value, signal) {
         Promise.resolve(value).then((result) => { cleanup(); resolve(result); }, (error) => { cleanup(); reject(error); });
     });
 }
-async function writeResponseBody(response, outputPath, signal, onProgress) {
+async function writeResponseBody(response, outputPath, signal, onProgress, onChunk = undefined) {
     const handle = fs.openSync(outputPath, "w");
     let received = 0;
     try {
         const write = (value) => {
             const chunk = Buffer.from(value);
             fs.writeSync(handle, chunk);
+            if (onChunk)
+                onChunk(chunk);
             received += chunk.length;
             onProgress(received);
         };