@opensoha/contracts 0.1.18 → 0.1.19

package/COMPATIBILITY.md

@@ -364,6 +364,31 @@ role migration and consumer conformance prove no active dependency.
 
 ## Consumer Adoption
 
+Connection tests and Compute provider health checks return HTTP 200 with
+`ConnectionCheckResultEnvelope` after each fresh probe. Consumers read `healthy`
+and the diagnostic fields directly; no task or task log is created. The Compute
+endpoint still accepts `Idempotency-Key` for request compatibility, but it no
+longer replays stored checks. Operation/audit logs and existing task history are
+preserved. HTTP 202 task envelopes remain documented for older servers. Core,
+Web and CLI must adopt the new HTTP 200 result together. Discovery and asset
+synchronization remain asynchronous. The Go SDK
+`CheckComputeProviderInstanceHealth` method now returns `ConnectionCheckResult`
+instead of `ComputeTaskView`; callers consuming its fields must update with Core
+to preserve the immediate health result and diagnostic details. Upgrade Core
+before these clients. The SDK rejects legacy task responses with a server-upgrade
+error instead of reporting an empty health result; the 202 schema documents older
+server wire behavior and does not promise task polling in the new check method.
+
+Docker port mapping creation reserves control-plane metadata synchronously; it
+does not enqueue `port_reserve` or bind a host port. Existing operation kinds and
+historical records remain compatible. Service log readers use the existing
+project runtime logs API. The service-action API accepts start, stop and restart;
+`logs` returns an invalid-argument error directing callers to the direct project
+log query instead of creating a task. Compute resource actions expose only these
+mutations. Historical `connection_test`, `port_reserve`, and `service_action`
+with action `logs` remain readable, but their operation state is not retryable
+and retry requests are rejected without requeueing or appending task logs.
+
 Recommended adoption flow:
 
 1. Change contracts and fixtures here first.
@@ -402,9 +427,11 @@ behavior.
 
 ## Contracts-first consumer revisions
 
-`compat/consumer-revisions.json` pins a reviewed consumer commit when a contracts
-release introduces APIs implemented by that consumer's pending change. Both CI
-and release use the same commit and run the complete existing consumer checks.
-Unlisted consumers use `main`. Replace the pin with `main` (or remove it) once the
-matching consumer changes reach its default branch; do not skip failed checks to
-resolve a release-order dependency.
+`compat/consumer-revisions.json` pins a reviewed full commit SHA for every consumer
+in the executable matrix. CI and release use `scripts/select-consumer-revision.mjs`;
+missing or invalid revisions fail instead of falling back to `main`. Update a pin
+only with an explicit compatibility reason and successful matrix evidence.
+
+Manual CI may select `consumer_mode=latest` for separate integration evidence.
+This does not rewrite the fixed manifest or replace fixed-combination acceptance.
+Record the actual contracts and consumer commits, not only the selected mode.

package/README.md

@@ -169,6 +169,7 @@ npm run check:consumers -- --consumer soha --require-all
 npm run check:consumers -- --consumer soha-web --require-all
 npm run check:consumers -- --consumer soha-cli --require-all
 npm run check:consumers -- --consumer soha-agent --require-all
+npm run check:consumers -- --consumer soha-skills --require-all
 ```
 
 Go consumers run in a temporary `go.work` that replaces the contracts module

package/compat/consumer-revisions.json

@@ -1,3 +1,7 @@
 {
-  "soha": "d675a708806072a2fee42e3c2c00309091a8cfb9"
+  "soha": "d675a708806072a2fee42e3c2c00309091a8cfb9",
+  "soha-web": "816ec0fb82e6e804f0f66d47d3446a7b5baeabc1",
+  "soha-cli": "1c9b760c986a9c1a5148db55b72ab99d23edd7a3",
+  "soha-agent": "af1efc0b0cd6bb544153429fa28244dd6cc81ac7",
+  "soha-skills": "0345171ee1c9f23ab5d4350767395d0919dfb21c"
 }

package/compat/json-schema-ecosystem-0.1.0.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.18",
+  "version": "0.1.19",
   "schemas": {
     "plugins/plugin-manifest.schema.json": {
       "rootRequired": ["id", "name", "publisher", "type", "version"],

package/compat/openapi-loose-boundaries-0.1.0.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.18",
+  "version": "0.1.19",
   "generatedFrom": "openapi/soha-api.yaml",
   "entries": [
     {

package/fixtures/openapi/ConnectionCheckResult/invalid/missing-health.json

@@ -0,0 +1 @@
+{"status":"healthy","checkedAt":"2026-09-22T00:00:00Z"}

package/fixtures/openapi/ConnectionCheckResult/invalid/task-id.json

@@ -0,0 +1 @@
+{"healthy":true,"status":"healthy","checkedAt":"2026-09-22T00:00:00Z","id":"task-1"}

package/fixtures/openapi/ConnectionCheckResult/valid/failure.json

@@ -0,0 +1 @@
+{"healthy":false,"status":"unavailable","message":"Connection refused","reason":"network","checkedAt":"2026-09-22T00:00:00Z"}

package/fixtures/openapi/ConnectionCheckResult/valid/healthy.json

@@ -0,0 +1 @@
+{"healthy":true,"status":"healthy","checkedAt":"2026-09-22T00:00:00Z"}

package/fixtures/openapi/UpdateBrandingSettingsRequest/invalid/dark-logo-type.json

@@ -0,0 +1,9 @@
+{
+  "appTitle": "Soha",
+  "sidebarTitle": "Soha",
+  "loginLogoUrl": "/logo.svg",
+  "expandedLogoUrl": "/logo.svg",
+  "collapsedLogoUrl": "/logo.svg",
+  "faviconUrl": "/logo.svg",
+  "darkExpandedLogoUrl": true
+}

package/fixtures/openapi/UpdateBrandingSettingsRequest/valid/dark-logos.json

@@ -0,0 +1,10 @@
+{
+  "appTitle": "Soha",
+  "sidebarTitle": "Soha",
+  "loginLogoUrl": "/logo.svg",
+  "expandedLogoUrl": "/logo.svg",
+  "collapsedLogoUrl": "/logo.svg",
+  "faviconUrl": "/logo.svg",
+  "darkExpandedLogoUrl": "/brand-dark.svg",
+  "darkCollapsedLogoUrl": "/mark-dark.svg"
+}

package/gen/go/sohaapi/client.go

@@ -16,7 +16,7 @@ import (
 	"time"
 )
 
-const defaultUserAgent = "opensoha-contracts/0.1.18"
+const defaultUserAgent = "opensoha-contracts/0.1.19"
 
 type Client struct {
 	BaseURL    string
@@ -594,8 +594,16 @@ func (c *Client) GetComputeProviderInstance(ctx context.Context, domain ComputeP
 	return out.Data, nil
 }
 
-func (c *Client) CheckComputeProviderInstanceHealth(ctx context.Context, domain ComputeProviderDomain, providerKey, instanceRef, idempotencyKey string, req ComputeProviderReadRequest) (ComputeTaskView, error) {
-	return c.mutateComputeProviderInstance(ctx, domain, providerKey, instanceRef, "health-checks", idempotencyKey, req)
+func (c *Client) CheckComputeProviderInstanceHealth(ctx context.Context, domain ComputeProviderDomain, providerKey, instanceRef, idempotencyKey string, req ComputeProviderReadRequest) (ConnectionCheckResult, error) {
+	var out ConnectionCheckResultEnvelope
+	path := computeProviderInstancePath(domain, providerKey, instanceRef) + "/health-checks"
+	if err := c.doJSONWithHeaders(ctx, http.MethodPost, path, true, req, &out, idempotencyHeader(idempotencyKey)); err != nil {
+		return ConnectionCheckResult{}, err
+	}
+	if out.Data.CheckedAt.IsZero() || strings.TrimSpace(out.Data.Status) == "" {
+		return ConnectionCheckResult{}, fmt.Errorf("connection health check returned no synchronous result; upgrade the server before using this client")
+	}
+	return out.Data, nil
 }
 
 func (c *Client) DiscoverComputeProviderInstance(ctx context.Context, domain ComputeProviderDomain, providerKey, instanceRef, idempotencyKey string, req ComputeProviderDiscoverRequest) (ComputeTaskView, error) {

package/gen/go/sohaapi/client_test.go

@@ -414,7 +414,7 @@ func TestComputeInventoryClientSurface(t *testing.T) {
 			if key := r.Header.Get("Idempotency-Key"); key != "health-key-1" {
 				t.Fatalf("health Idempotency-Key = %q", key)
 			}
-			writeJSON(t, w, computeTaskEnvelopeFixture("health-task"))
+			writeJSON(t, w, map[string]any{"data": map[string]any{"healthy": true, "status": "healthy", "checkedAt": "2026-09-22T00:00:00Z"}})
 		case 8:
 			assertCommonRequest(t, r, http.MethodPost, "/api/v1/compute/provider-instances/virtualization/pve/connection%2Fone/discoveries")
 			if key := r.Header.Get("Idempotency-Key"); key != "discover-key-1" {
@@ -458,8 +458,8 @@ func TestComputeInventoryClientSurface(t *testing.T) {
 	if _, err := client.GetComputeProviderInstance(ctx, ComputeProviderDomainVirtualization, "pve", "connection/one"); err != nil {
 		t.Fatal(err)
 	}
-	if _, err := client.CheckComputeProviderInstanceHealth(ctx, ComputeProviderDomainVirtualization, "pve", "connection/one", "health-key-1", ComputeProviderReadRequest{ExpectedGeneration: 1}); err != nil {
-		t.Fatal(err)
+	if result, err := client.CheckComputeProviderInstanceHealth(ctx, ComputeProviderDomainVirtualization, "pve", "connection/one", "health-key-1", ComputeProviderReadRequest{ExpectedGeneration: 1}); err != nil || !result.Healthy || result.Status != "healthy" || result.CheckedAt.IsZero() {
+		t.Fatalf("CheckComputeProviderInstanceHealth = %#v, %v", result, err)
 	}
 	if _, err := client.DiscoverComputeProviderInstance(ctx, ComputeProviderDomainVirtualization, "pve", "connection/one", "discover-key-1", ComputeProviderDiscoverRequest{ExpectedGeneration: 1}); err != nil {
 		t.Fatal(err)
@@ -475,6 +475,29 @@ func TestComputeInventoryClientSurface(t *testing.T) {
 	}
 }
 
+func TestComputeProviderHealthPreservesDiagnostics(t *testing.T) {
+	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		writeJSON(t, w, map[string]any{"data": map[string]any{
+			"healthy": false, "status": "degraded", "checkedAt": "2026-09-22T00:00:00Z",
+			"httpStatus": 401, "reason": "authentication_failed", "message": "Credentials rejected", "nextAction": "Update credentials",
+		}})
+	})
+	result, err := client.CheckComputeProviderInstanceHealth(context.Background(), ComputeProviderDomainVirtualization, "pve", "connection-1", "", ComputeProviderReadRequest{})
+	if err != nil || result.Healthy || result.Status != "degraded" || result.HTTPStatus != 401 || result.Reason != "authentication_failed" || result.Message != "Credentials rejected" || result.NextAction != "Update credentials" || result.CheckedAt.IsZero() {
+		t.Fatalf("CheckComputeProviderInstanceHealth = %#v, %v", result, err)
+	}
+}
+
+func TestComputeProviderHealthRejectsLegacyTask(t *testing.T) {
+	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusAccepted)
+		writeJSON(t, w, computeTaskEnvelopeFixture("health-task"))
+	})
+	if _, err := client.CheckComputeProviderInstanceHealth(context.Background(), ComputeProviderDomainVirtualization, "pve", "connection-1", "", ComputeProviderReadRequest{}); err == nil || !strings.Contains(err.Error(), "upgrade the server") {
+		t.Fatalf("legacy task response should require a server upgrade, got %v", err)
+	}
+}
+
 func TestStreamComputeTask(t *testing.T) {
 	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
 		if r.Method != http.MethodGet || r.URL.EscapedPath() != "/api/v1/compute/tasks/virtualization/task%2Fone/stream" {

package/gen/go/sohaapi/types.go

@@ -12775,11 +12775,17 @@ type BrandingAssetUploadEnvelope struct {
 type BrandingSettings struct {
 	AppTitle         string `json:"appTitle"`
 	CollapsedLogoURL string `json:"collapsedLogoUrl"`
-	ExpandedLogoURL  string `json:"expandedLogoUrl"`
-	FaviconURL       string `json:"faviconUrl"`
-	LoginLogoURL     string `json:"loginLogoUrl"`
-	SidebarTitle     string `json:"sidebarTitle"`
-	Slogan           string `json:"slogan,omitempty"`
+
+	// DarkCollapsedLogoURL Optional dark-theme compact logo. Empty or absent uses collapsedLogoUrl.
+	DarkCollapsedLogoURL string `json:"darkCollapsedLogoUrl,omitempty"`
+
+	// DarkExpandedLogoURL Optional dark-theme expanded logo. Empty or absent uses expandedLogoUrl.
+	DarkExpandedLogoURL string `json:"darkExpandedLogoUrl,omitempty"`
+	ExpandedLogoURL     string `json:"expandedLogoUrl"`
+	FaviconURL          string `json:"faviconUrl"`
+	LoginLogoURL        string `json:"loginLogoUrl"`
+	SidebarTitle        string `json:"sidebarTitle"`
+	Slogan              string `json:"slogan,omitempty"`
 }
 
 // BrandingSettingsEnvelope defines model for BrandingSettingsEnvelope.
@@ -14026,6 +14032,23 @@ type ComputeWarning struct {
 	Message string `json:"message,omitempty"`
 }
 
+// ConnectionCheckResult Current connection health from a synchronous probe. This result is not a task and has no task identifier or lifecycle actions.
+type ConnectionCheckResult struct {
+	CheckedAt  time.Time `json:"checkedAt"`
+	Healthy    bool      `json:"healthy"`
+	HTTPStatus int       `json:"httpStatus,omitempty"`
+	Message    string    `json:"message,omitempty"`
+	NextAction string    `json:"nextAction,omitempty"`
+	Reason     string    `json:"reason,omitempty"`
+	Status     string    `json:"status"`
+}
+
+// ConnectionCheckResultEnvelope defines model for ConnectionCheckResultEnvelope.
+type ConnectionCheckResultEnvelope struct {
+	// Data Current connection health from a synchronous probe. This result is not a task and has no task identifier or lifecycle actions.
+	Data ConnectionCheckResult `json:"data"`
+}
+
 // CreatedPersonalAccessToken defines model for CreatedPersonalAccessToken.
 type CreatedPersonalAccessToken struct {
 	Token PersonalAccessToken `json:"token"`
@@ -26761,11 +26784,17 @@ type UpdateAIWorkbenchModelRequest struct {
 type UpdateBrandingSettingsRequest struct {
 	AppTitle         string `json:"appTitle"`
 	CollapsedLogoURL string `json:"collapsedLogoUrl"`
-	ExpandedLogoURL  string `json:"expandedLogoUrl"`
-	FaviconURL       string `json:"faviconUrl"`
-	LoginLogoURL     string `json:"loginLogoUrl"`
-	SidebarTitle     string `json:"sidebarTitle"`
-	Slogan           string `json:"slogan,omitempty"`
+
+	// DarkCollapsedLogoURL Optional dark-theme compact logo. Empty or absent clears the override.
+	DarkCollapsedLogoURL string `json:"darkCollapsedLogoUrl,omitempty"`
+
+	// DarkExpandedLogoURL Optional dark-theme expanded logo. Empty or absent clears the override.
+	DarkExpandedLogoURL string `json:"darkExpandedLogoUrl,omitempty"`
+	ExpandedLogoURL     string `json:"expandedLogoUrl"`
+	FaviconURL          string `json:"faviconUrl"`
+	LoginLogoURL        string `json:"loginLogoUrl"`
+	SidebarTitle        string `json:"sidebarTitle"`
+	Slogan              string `json:"slogan,omitempty"`
 }
 
 // UpdateLoginProvidersSettingsRequest defines model for UpdateLoginProvidersSettingsRequest.

package/gen/ts/sohaapi/index.ts

@@ -1085,6 +1085,7 @@ export interface paths {
         get: operations["getApplication"];
         put: operations["updateApplication"];
         post?: never;
+        /** @description Deletes the application and its owned configuration and history. Does not uninstall cluster workloads. Unfinished delivery tasks or external references prevent deletion. */
         delete: operations["deleteApplication"];
         options?: never;
         head?: never;
@@ -6223,6 +6224,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Requires docker.services.logs. Reads bounded logs directly from the runtime without submitting an operation. */
         post: operations["queryDockerProjectLogs"];
         delete?: never;
         options?: never;
@@ -6239,6 +6241,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Requires docker.services.logs. The same permission is rechecked when opening the stream. */
         post: operations["issueDockerProjectLogStreamTicket"];
         delete?: never;
         options?: never;
@@ -7877,6 +7880,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Enqueue a supported resource mutation. Container service actions are start, stop and restart. Log reads use the direct project log query API; action logs is rejected without creating a task. */
         post: operations["executeComputeResourceAction"];
         delete?: never;
         options?: never;
@@ -7974,6 +7978,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Retry an asynchronous operation when its returned state permits it. Historical connection_test, port_reserve and service_action logs records remain readable but cannot be requeued; use their direct check, metadata or log query APIs instead. */
         post: operations["retryComputeTask"];
         delete?: never;
         options?: never;
@@ -12925,6 +12930,20 @@ export interface components {
             summary?: string;
             resources?: components["schemas"]["ComputeResourceRef"][];
         };
+        /** @description Current connection health from a synchronous probe. This result is not a task and has no task identifier or lifecycle actions. */
+        ConnectionCheckResult: {
+            healthy: boolean;
+            status: string;
+            message?: string;
+            reason?: string;
+            nextAction?: string;
+            httpStatus?: number;
+            /** Format: date-time */
+            checkedAt: string;
+        };
+        ConnectionCheckResultEnvelope: {
+            data: components["schemas"]["ConnectionCheckResult"];
+        };
         ComputeTaskView: {
             id: string;
             domain: components["schemas"]["ComputeTaskDomain"];
@@ -14173,6 +14192,10 @@ export interface components {
             loginLogoUrl: string;
             expandedLogoUrl: string;
             collapsedLogoUrl: string;
+            /** @description Optional dark-theme expanded logo. Empty or absent uses expandedLogoUrl. */
+            darkExpandedLogoUrl?: string;
+            /** @description Optional dark-theme compact logo. Empty or absent uses collapsedLogoUrl. */
+            darkCollapsedLogoUrl?: string;
             faviconUrl: string;
         };
         BrandingSettingsEnvelope: {
@@ -14185,6 +14208,10 @@ export interface components {
             loginLogoUrl: string;
             expandedLogoUrl: string;
             collapsedLogoUrl: string;
+            /** @description Optional dark-theme expanded logo. Empty or absent clears the override. */
+            darkExpandedLogoUrl?: string;
+            /** @description Optional dark-theme compact logo. Empty or absent clears the override. */
+            darkCollapsedLogoUrl?: string;
             faviconUrl: string;
         };
         BrandingAssetUpload: {
@@ -26364,6 +26391,8 @@ export type ComputeTaskResultStatus = components['schemas']['ComputeTaskResultSt
 export type ComputeTaskResult = components['schemas']['ComputeTaskResult'];
 export type ComputeTaskVerificationStatus = components['schemas']['ComputeTaskVerificationStatus'];
 export type ComputeTaskVerification = components['schemas']['ComputeTaskVerification'];
+export type ConnectionCheckResult = components['schemas']['ConnectionCheckResult'];
+export type ConnectionCheckResultEnvelope = components['schemas']['ConnectionCheckResultEnvelope'];
 export type ComputeTaskView = components['schemas']['ComputeTaskView'];
 export type ComputeTaskListEnvelope = components['schemas']['ComputeTaskListEnvelope'];
 export type ComputeTaskEnvelope = components['schemas']['ComputeTaskEnvelope'];
@@ -30247,6 +30276,7 @@ export interface operations {
             };
             403: components["responses"]["Error"];
             404: components["responses"]["Error"];
+            409: components["responses"]["Error"];
         };
     };
     getApplicationDeliveryDetail: {
@@ -34265,7 +34295,16 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Completed connection-test operation. */
+            /** @description Completed synchronous connection check. Each request probes the connection and returns its current health; no task or task log is created. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConnectionCheckResultEnvelope"];
+                };
+            };
+            /** @description Legacy response for a completed connection check, retained for older servers. Read the operation result directly. */
             202: {
                 headers: {
                     [name: string]: unknown;
@@ -43865,7 +43904,16 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Health check accepted as a source-domain task. The request never returns the Provider raw response. */
+            /** @description Completed synchronous health check. Each request probes the connection and returns its current health; no task or task log is created. Idempotency-Key is accepted for request compatibility but does not replay an earlier check. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConnectionCheckResultEnvelope"];
+                };
+            };
+            /** @description Legacy health-check response retained for older servers. The task contains the completed result, never the Provider raw response. */
             202: {
                 headers: {
                     [name: string]: unknown;
@@ -44177,6 +44225,7 @@ export interface operations {
                     "application/json": components["schemas"]["ComputeTaskEnvelope"];
                 };
             };
+            400: components["responses"]["ComputeError"];
             403: components["responses"]["ComputeError"];
             404: components["responses"]["ComputeError"];
             409: components["responses"]["ComputeError"];

package/openapi/soha-api.json

@@ -6981,6 +6981,14 @@
           "collapsedLogoUrl": {
             "type": "string"
           },
+          "darkCollapsedLogoUrl": {
+            "description": "Optional dark-theme compact logo. Empty or absent uses collapsedLogoUrl.",
+            "type": "string"
+          },
+          "darkExpandedLogoUrl": {
+            "description": "Optional dark-theme expanded logo. Empty or absent uses expandedLogoUrl.",
+            "type": "string"
+          },
           "expandedLogoUrl": {
             "type": "string"
           },
@@ -10967,6 +10975,52 @@
         ],
         "type": "object"
       },
+      "ConnectionCheckResult": {
+        "additionalProperties": false,
+        "description": "Current connection health from a synchronous probe. This result is not a task and has no task identifier or lifecycle actions.",
+        "properties": {
+          "checkedAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "healthy": {
+            "type": "boolean"
+          },
+          "httpStatus": {
+            "type": "integer"
+          },
+          "message": {
+            "type": "string"
+          },
+          "nextAction": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "healthy",
+          "status",
+          "checkedAt"
+        ],
+        "type": "object"
+      },
+      "ConnectionCheckResultEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/ConnectionCheckResult"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
       "CreatedPersonalAccessToken": {
         "additionalProperties": false,
         "properties": {
@@ -54718,6 +54772,14 @@
           "collapsedLogoUrl": {
             "type": "string"
           },
+          "darkCollapsedLogoUrl": {
+            "description": "Optional dark-theme compact logo. Empty or absent clears the override.",
+            "type": "string"
+          },
+          "darkExpandedLogoUrl": {
+            "description": "Optional dark-theme expanded logo. Empty or absent clears the override.",
+            "type": "string"
+          },
           "expandedLogoUrl": {
             "type": "string"
           },
@@ -60734,7 +60796,7 @@
   "info": {
     "description": "Public OpenSoha core API contract. This first contract focuses on stable cross-repository boundaries: auth, health, runner-facing control-plane callbacks, AI Gateway, and MCP capability discovery.\n",
     "title": "Soha API",
-    "version": "0.1.18"
+    "version": "0.1.19"
   },
   "openapi": "3.1.0",
   "paths": {
@@ -68992,6 +69054,7 @@
     },
     "/applications/{applicationID}": {
       "delete": {
+        "description": "Deletes the application and its owned configuration and history. Does not uninstall cluster workloads. Unfinished delivery tasks or external references prevent deletion.",
         "operationId": "deleteApplication",
         "parameters": [
           {
@@ -69014,6 +69077,9 @@
           },
           "404": {
             "$ref": "#/components/responses/Error"
+          },
+          "409": {
+            "$ref": "#/components/responses/Error"
           }
         },
         "tags": [
@@ -77566,6 +77632,16 @@
           "required": true
         },
         "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConnectionCheckResultEnvelope"
+                }
+              }
+            },
+            "description": "Completed synchronous health check. Each request probes the connection and returns its current health; no task or task log is created. Idempotency-Key is accepted for request compatibility but does not replay an earlier check."
+          },
           "202": {
             "content": {
               "application/json": {
@@ -77574,7 +77650,7 @@
                 }
               }
             },
-            "description": "Health check accepted as a source-domain task. The request never returns the Provider raw response."
+            "description": "Legacy health-check response retained for older servers. The task contains the completed result, never the Provider raw response."
           },
           "400": {
             "$ref": "#/components/responses/ComputeError"
@@ -77683,6 +77759,7 @@
     },
     "/compute/resources/{domain}/{kind}/{id}/actions/{action}": {
       "post": {
+        "description": "Enqueue a supported resource mutation. Container service actions are start, stop and restart. Log reads use the direct project log query API; action logs is rejected without creating a task.",
         "operationId": "executeComputeResourceAction",
         "parameters": [
           {
@@ -78013,6 +78090,7 @@
     },
     "/compute/tasks/{domain}/{id}/retry": {
       "post": {
+        "description": "Retry an asynchronous operation when its returned state permits it. Historical connection_test, port_reserve and service_action logs records remain readable but cannot be requeued; use their direct check, metadata or log query APIs instead.",
         "operationId": "retryComputeTask",
         "parameters": [
           {
@@ -78046,6 +78124,9 @@
             },
             "description": "Retry delegated to the source domain and returned as a new task with a new immutable Provider snapshot."
           },
+          "400": {
+            "$ref": "#/components/responses/ComputeError"
+          },
           "403": {
             "$ref": "#/components/responses/ComputeError"
           },
@@ -84739,6 +84820,7 @@
     },
     "/docker/projects/{dockerProjectID}/logs/query": {
       "post": {
+        "description": "Requires docker.services.logs. Reads bounded logs directly from the runtime without submitting an operation.",
         "operationId": "queryDockerProjectLogs",
         "parameters": [
           {
@@ -84789,6 +84871,7 @@
     },
     "/docker/projects/{dockerProjectID}/logs/stream-ticket": {
       "post": {
+        "description": "Requires docker.services.logs. The same permission is rechecked when opening the stream.",
         "operationId": "issueDockerProjectLogStreamTicket",
         "parameters": [
           {
@@ -96185,6 +96268,16 @@
           }
         ],
         "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConnectionCheckResultEnvelope"
+                }
+              }
+            },
+            "description": "Completed synchronous connection check. Each request probes the connection and returns its current health; no task or task log is created."
+          },
           "202": {
             "content": {
               "application/json": {
@@ -96193,7 +96286,7 @@
                 }
               }
             },
-            "description": "Completed connection-test operation."
+            "description": "Legacy response for a completed connection check, retained for older servers. Read the operation result directly."
           },
           "403": {
             "$ref": "#/components/responses/Error"

package/openapi/soha-api.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Soha API
-  version: 0.1.18
+  version: 0.1.19
   description: >
     Public OpenSoha core API contract. This first contract focuses on stable
     cross-repository boundaries: auth, health, runner-facing control-plane
@@ -2163,6 +2163,7 @@ paths:
     delete:
       tags: [Applications]
       operationId: deleteApplication
+      description: Deletes the application and its owned configuration and history. Does not uninstall cluster workloads. Unfinished delivery tasks or external references prevent deletion.
       parameters:
         - $ref: "#/components/parameters/ApplicationID"
       responses:
@@ -2176,6 +2177,8 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
   /applications/{applicationID}/detail:
     get:
       tags: [Applications, Delivery]
@@ -5456,8 +5459,13 @@ paths:
       parameters:
         - { name: connectionID, in: path, required: true, schema: { type: string } }
       responses:
+        "200":
+          description: Completed synchronous connection check. Each request probes the connection and returns its current health; no task or task log is created.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ConnectionCheckResultEnvelope" }
         "202":
-          description: Completed connection-test operation.
+          description: Legacy response for a completed connection check, retained for older servers. Read the operation result directly.
           content:
             application/json:
               schema: { $ref: "#/components/schemas/VirtualizationOperationEnvelope" }
@@ -10296,6 +10304,7 @@ paths:
     post:
       tags: [Docker]
       operationId: queryDockerProjectLogs
+      description: Requires docker.services.logs. Reads bounded logs directly from the runtime without submitting an operation.
       parameters:
         - $ref: "#/components/parameters/DockerProjectID"
       requestBody:
@@ -10325,6 +10334,7 @@ paths:
     post:
       tags: [Docker]
       operationId: issueDockerProjectLogStreamTicket
+      description: Requires docker.services.logs. The same permission is rechecked when opening the stream.
       parameters:
         - $ref: "#/components/parameters/DockerProjectID"
       requestBody:
@@ -13681,8 +13691,14 @@ paths:
             schema:
               $ref: "#/components/schemas/ComputeProviderReadRequest"
       responses:
+        "200":
+          description: Completed synchronous health check. Each request probes the connection and returns its current health; no task or task log is created. Idempotency-Key is accepted for request compatibility but does not replay an earlier check.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionCheckResultEnvelope"
         "202":
-          description: Health check accepted as a source-domain task. The request never returns the Provider raw response.
+          description: Legacy health-check response retained for older servers. The task contains the completed result, never the Provider raw response.
           content:
             application/json:
               schema:
@@ -13773,6 +13789,10 @@ paths:
     post:
       tags: [Compute]
       operationId: executeComputeResourceAction
+      description: >-
+        Enqueue a supported resource mutation. Container service actions are start,
+        stop and restart. Log reads use the direct project log query API; action
+        logs is rejected without creating a task.
       parameters:
         - $ref: "#/components/parameters/ComputeDomain"
         - $ref: "#/components/parameters/ComputeResourceKind"
@@ -13952,6 +13972,11 @@ paths:
     post:
       tags: [Compute]
       operationId: retryComputeTask
+      description: >-
+        Retry an asynchronous operation when its returned state permits it.
+        Historical connection_test, port_reserve and service_action logs records
+        remain readable but cannot be requeued; use their direct check, metadata
+        or log query APIs instead.
       parameters:
         - $ref: "#/components/parameters/ComputeTaskDomain"
         - $ref: "#/components/parameters/ComputeTaskID"
@@ -13969,6 +13994,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ComputeTaskEnvelope"
+        "400":
+          $ref: "#/components/responses/ComputeError"
         "403":
           $ref: "#/components/responses/ComputeError"
         "404":
@@ -23379,6 +23406,25 @@ components:
           type: array
           items: { $ref: "#/components/schemas/ComputeResourceRef" }
       additionalProperties: false
+    ConnectionCheckResult:
+      type: object
+      description: Current connection health from a synchronous probe. This result is not a task and has no task identifier or lifecycle actions.
+      required: [healthy, status, checkedAt]
+      properties:
+        healthy: { type: boolean }
+        status: { type: string }
+        message: { type: string }
+        reason: { type: string }
+        nextAction: { type: string }
+        httpStatus: { type: integer }
+        checkedAt: { type: string, format: date-time }
+      additionalProperties: false
+    ConnectionCheckResultEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/ConnectionCheckResult" }
+      additionalProperties: false
     ComputeTaskView:
       type: object
       required: [id, domain, sourceType, sourceId, kind, category, normalizedStatus, rawStatus, resources, attemptCount, cancelable, retryable, availableActions, createdAt]
@@ -25309,6 +25355,12 @@ components:
         loginLogoUrl: { type: string }
         expandedLogoUrl: { type: string }
         collapsedLogoUrl: { type: string }
+        darkExpandedLogoUrl:
+          type: string
+          description: Optional dark-theme expanded logo. Empty or absent uses expandedLogoUrl.
+        darkCollapsedLogoUrl:
+          type: string
+          description: Optional dark-theme compact logo. Empty or absent uses collapsedLogoUrl.
         faviconUrl: { type: string }
       additionalProperties: false
     BrandingSettingsEnvelope:
@@ -25328,6 +25380,12 @@ components:
         loginLogoUrl: { type: string }
         expandedLogoUrl: { type: string }
         collapsedLogoUrl: { type: string }
+        darkExpandedLogoUrl:
+          type: string
+          description: Optional dark-theme expanded logo. Empty or absent clears the override.
+        darkCollapsedLogoUrl:
+          type: string
+          description: Optional dark-theme compact logo. Empty or absent clears the override.
         faviconUrl: { type: string }
       additionalProperties: false
     BrandingAssetUpload:

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.18"
-	YAMLSHA256 = "d614ce858924d94da353c7a9380971a3e80964f3e6c865e8b27108e859500cf4"
-	JSONSHA256 = "a98ea9ad99b6f044ce14e42f37b90b42e28347d53e37c727a04210b076aba960"
+	Version    = "0.1.19"
+	YAMLSHA256 = "a1edda91ecc623423ca1875777dd500f12f239ca1571d7276a23d5e6c00c4c40"
+	JSONSHA256 = "40f61307c9379b1496b43ff31fe8aebd82f1353100fe799f6d1ebbaefb1c3cd3"
 )
 
 //go:embed soha-api.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",