@opensoha/contracts 0.1.24 → 0.1.26

package/delivery/document.schema.json

@@ -177,6 +177,9 @@
           "default": true,
           "type": "boolean"
         },
+        "migrationPolicy": {
+          "$ref": "#/$defs/TemplateMigrationPolicy"
+        },
         "variableSchema": {
           "additionalProperties": {
             "$ref": "#/$defs/DeliveryBuildVariableSchema"
@@ -317,6 +320,9 @@
         "health": {
           "$ref": "#/$defs/DeploymentTemplateHealth"
         },
+        "migrationPolicy": {
+          "$ref": "#/$defs/TemplateMigrationPolicy"
+        },
         "parameterSchema": {
           "$ref": "#/$defs/TemplateParameterSchema"
         },
@@ -804,21 +810,68 @@
       "additionalProperties": false,
       "allOf": [
         {
-          "if": {
+          "else": {
+            "allOf": [
+              {
+                "if": {
+                  "properties": {
+                    "action": {
+                      "enum": [
+                        "build_deploy",
+                        "deploy",
+                        "config_update"
+                      ]
+                    }
+                  }
+                },
+                "then": {
+                  "required": [
+                    "applicationEnvironmentId"
+                  ]
+                }
+              }
+            ],
             "properties": {
-              "action": {
-                "enum": [
-                  "build_deploy",
-                  "deploy",
-                  "config_update"
-                ]
+              "serviceId": {
+                "minLength": 1,
+                "type": "string"
               }
             }
           },
-          "then": {
+          "if": {
             "required": [
-              "applicationEnvironmentId"
+              "templateCandidateId"
             ]
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "helmRevision"
+                  ]
+                },
+                {
+                  "required": [
+                    "buildArgs"
+                  ]
+                },
+                {
+                  "required": [
+                    "repositoryRefs"
+                  ]
+                }
+              ]
+            },
+            "properties": {
+              "action": {
+                "const": "config_update"
+              },
+              "releaseBundleId": {
+                "maxLength": 0,
+                "type": "string"
+              }
+            }
           }
         },
         {
@@ -897,6 +950,10 @@
           "type": "array"
         },
         "serviceId": {
+          "type": "string"
+        },
+        "templateCandidateId": {
+          "maxLength": 256,
           "minLength": 1,
           "type": "string"
         }
@@ -1068,6 +1125,9 @@
         "enabled": {
           "default": true,
           "type": "boolean"
+        },
+        "migrationPolicy": {
+          "$ref": "#/$defs/TemplateMigrationPolicy"
         }
       },
       "required": [
@@ -1376,6 +1436,64 @@
       },
       "type": "object"
     },
+    "TemplateMigrationPolicy": {
+      "additionalProperties": false,
+      "if": {
+        "anyOf": [
+          {
+            "properties": {
+              "sequential": {
+                "const": true
+              }
+            },
+            "required": [
+              "sequential"
+            ]
+          },
+          {
+            "properties": {
+              "irreversible": {
+                "const": true
+              }
+            },
+            "required": [
+              "irreversible"
+            ]
+          }
+        ]
+      },
+      "properties": {
+        "guide": {
+          "description": "Human migration/recovery instructions. Never executed as a script.",
+          "maxLength": 2000,
+          "type": "string"
+        },
+        "irreversible": {
+          "description": "Forward changes require approval; ordinary rollback across this boundary is forbidden.",
+          "type": "boolean"
+        },
+        "sequential": {
+          "description": "Must cross this boundary as adjacent published versions; approval cannot waive it.",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "sequential",
+        "irreversible"
+      ],
+      "then": {
+        "properties": {
+          "guide": {
+            "minLength": 1,
+            "pattern": "\\S"
+          }
+        },
+        "required": [
+          "guide"
+        ]
+      },
+      "type": "object"
+    },
     "TemplateParameterSchema": {
       "additionalProperties": false,
       "description": "Restricted JSON Schema. Objects reject undeclared keys unless mapValues specifies their schema. secret_reference accepts only a namespaced Secret name/key reference, never a plaintext credential. External references and executable expressions are unsupported.",

package/examples/relations_compat_test.go

@@ -0,0 +1,18 @@
+package examples
+
+import (
+	sdk "github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"testing"
+)
+
+func TestRelationAdditionPreservesPublishedEnumNames(t *testing.T) {
+	values := []sdk.PersonalGuestRuntimeInputKind{sdk.Browser, sdk.Docker, sdk.Execute, sdk.FileRead, sdk.FileWrite}
+	for i, want := range []string{"browser", "docker", "execute", "file_read", "file_write"} {
+		if string(values[i]) != want {
+			t.Fatalf("published enum %d changed", i)
+		}
+	}
+	if sdk.JSON != sdk.ExportDeliveryDocumentParamsFormatJSON || sdk.Yaml != sdk.ExportDeliveryDocumentParamsFormatYaml {
+		t.Fatal("published format aliases changed")
+	}
+}

package/fixtures/openapi/DeliveryDocument/invalid/migration-missing-guide-build-template.json

@@ -0,0 +1,30 @@
+{
+  "apiVersion": "delivery.soha.io/v1alpha1",
+  "kind": "BuildTemplate",
+  "metadata": {
+    "name": "node-image"
+  },
+  "spec": {
+    "buildCommands": [
+      "npm ci",
+      "npm run build"
+    ],
+    "variableSchema": {
+      "MODE": {
+        "type": "string",
+        "required": true,
+        "enum": [
+          "production",
+          "development"
+        ]
+      }
+    },
+    "defaultVariables": {
+      "MODE": "production"
+    },
+    "migrationPolicy": {
+      "sequential": true,
+      "irreversible": false
+    }
+  }
+}

package/fixtures/openapi/DeliveryDocument/invalid/migration-missing-guide-deployment-template.json

@@ -0,0 +1,30 @@
+{
+  "apiVersion": "delivery.soha.io/v1alpha1",
+  "kind": "DeploymentTemplate",
+  "metadata": {
+    "name": "http-service"
+  },
+  "spec": {
+    "source": {
+      "renderer": "raw_yaml",
+      "files": [
+        {
+          "path": "config.yaml",
+          "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: example\ndata:\n  mode: prod\n"
+        }
+      ]
+    },
+    "parameterSchema": {
+      "type": "object"
+    },
+    "defaults": {},
+    "health": {
+      "mode": "configuration_only",
+      "timeoutSeconds": 60
+    },
+    "migrationPolicy": {
+      "sequential": true,
+      "irreversible": false
+    }
+  }
+}

package/fixtures/openapi/DeliveryDocument/invalid/migration-missing-guide-workflow-template.json

@@ -0,0 +1,27 @@
+{
+  "apiVersion": "delivery.soha.io/v1alpha1",
+  "kind": "WorkflowTemplate",
+  "metadata": {
+    "name": "build-release",
+    "displayName": "\u8054\u5408\u6784\u5efa\u53d1\u5e03"
+  },
+  "spec": {
+    "definition": {
+      "mode": "delivery_batch",
+      "schemaVersion": 1,
+      "stages": [
+        "build",
+        "plan",
+        "deploy",
+        "health"
+      ],
+      "executionMode": "build_all_then_deploy",
+      "stopOnFailure": true,
+      "maxConcurrency": 4
+    },
+    "migrationPolicy": {
+      "sequential": true,
+      "irreversible": false
+    }
+  }
+}

package/fixtures/openapi/DeliveryDocument/valid/migration-build-template.json

@@ -0,0 +1,31 @@
+{
+  "apiVersion": "delivery.soha.io/v1alpha1",
+  "kind": "BuildTemplate",
+  "metadata": {
+    "name": "node-image"
+  },
+  "spec": {
+    "buildCommands": [
+      "npm ci",
+      "npm run build"
+    ],
+    "variableSchema": {
+      "MODE": {
+        "type": "string",
+        "required": true,
+        "enum": [
+          "production",
+          "development"
+        ]
+      }
+    },
+    "defaultVariables": {
+      "MODE": "production"
+    },
+    "migrationPolicy": {
+      "sequential": true,
+      "irreversible": true,
+      "guide": "Backup, migrate in order, verify; forward repair only."
+    }
+  }
+}

package/fixtures/openapi/DeliveryDocument/valid/migration-deployment-template.json

@@ -0,0 +1,31 @@
+{
+  "apiVersion": "delivery.soha.io/v1alpha1",
+  "kind": "DeploymentTemplate",
+  "metadata": {
+    "name": "http-service"
+  },
+  "spec": {
+    "source": {
+      "renderer": "raw_yaml",
+      "files": [
+        {
+          "path": "config.yaml",
+          "content": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: example\ndata:\n  mode: prod\n"
+        }
+      ]
+    },
+    "parameterSchema": {
+      "type": "object"
+    },
+    "defaults": {},
+    "health": {
+      "mode": "configuration_only",
+      "timeoutSeconds": 60
+    },
+    "migrationPolicy": {
+      "sequential": true,
+      "irreversible": true,
+      "guide": "Backup, migrate in order, verify; forward repair only."
+    }
+  }
+}

package/fixtures/openapi/DeliveryDocument/valid/migration-workflow-template.json

@@ -0,0 +1,28 @@
+{
+  "apiVersion": "delivery.soha.io/v1alpha1",
+  "kind": "WorkflowTemplate",
+  "metadata": {
+    "name": "build-release",
+    "displayName": "\u8054\u5408\u6784\u5efa\u53d1\u5e03"
+  },
+  "spec": {
+    "definition": {
+      "mode": "delivery_batch",
+      "schemaVersion": 1,
+      "stages": [
+        "build",
+        "plan",
+        "deploy",
+        "health"
+      ],
+      "executionMode": "build_all_then_deploy",
+      "stopOnFailure": true,
+      "maxConcurrency": 4
+    },
+    "migrationPolicy": {
+      "sequential": true,
+      "irreversible": true,
+      "guide": "Backup, migrate in order, verify; forward repair only."
+    }
+  }
+}

package/fixtures/openapi/DeliveryPlanInput/invalid/manual-plan.json

@@ -0,0 +1,7 @@
+{
+  "applicationId": "app",
+  "applicationEnvironmentId": "test",
+  "action": "rollback",
+  "source": "manual",
+  "templateCandidateId": "worker-only"
+}

package/fixtures/openapi/DeliveryPlanInput/valid/manual-plan.json

@@ -0,0 +1,6 @@
+{
+  "applicationId": "app",
+  "applicationEnvironmentId": "test",
+  "action": "deploy",
+  "source": "manual"
+}

package/fixtures/openapi/DeliveryTargetInput/invalid/candidate-on-runtime-deploy.json

@@ -0,0 +1,9 @@
+{
+  "id": "adopt1",
+  "applicationId": "retail",
+  "serviceId": "api",
+  "applicationEnvironmentId": "retail-test",
+  "action": "deploy",
+  "releaseBundleId": "bundle",
+  "templateCandidateId": "candidate-1"
+}

package/fixtures/openapi/DeliveryTargetInput/invalid/config-update-missing-service.json

@@ -0,0 +1,7 @@
+{
+  "id": "adopt1",
+  "applicationId": "retail",
+  "serviceId": "",
+  "applicationEnvironmentId": "retail-test",
+  "action": "config_update"
+}

package/fixtures/openapi/DeliveryTargetInput/valid/template-configuration-only.json

@@ -0,0 +1,8 @@
+{
+  "id": "adopt1",
+  "applicationId": "retail",
+  "serviceId": "",
+  "applicationEnvironmentId": "retail-test",
+  "action": "config_update",
+  "templateCandidateId": "candidate-1"
+}

package/fixtures/openapi/DeliveryTargetInput/valid/template-configuration-without-runtime-environment.json

@@ -0,0 +1 @@
+{"id":"adopt-build","applicationId":"retail","serviceId":"","action":"config_update","templateCandidateId":"candidate-1"}

package/fixtures/openapi/KubernetesAgentActionCheck/invalid/unproven-state.json

@@ -0,0 +1,6 @@
+{
+  "action": "platform.nodes.drain",
+  "implementation": "supported",
+  "configured": "maybe",
+  "kubernetesRBAC": "allowed"
+}

package/fixtures/openapi/KubernetesAgentActionCheck/valid/configured-denied.json

@@ -0,0 +1,9 @@
+{
+  "action": "platform.nodes.drain",
+  "implementation": "supported",
+  "configured": "denied",
+  "kubernetesRBAC": "unknown",
+  "scope": "cluster",
+  "checkedAt": "2026-10-19T01:30:00Z",
+  "reasonCode": "self_subject_access_review"
+}

package/fixtures/openapi/KubernetesAgentActionProfile/invalid/wildcard.json

@@ -0,0 +1 @@
+"*"

package/fixtures/openapi/KubernetesAgentActionProfile/valid/workbench.json

@@ -0,0 +1 @@
+"workbench"

package/fixtures/openapi/KubernetesClusterRegistrationRequest/invalid/action-profile.json

@@ -0,0 +1,3 @@
+{
+  "agentActionProfile": "all"
+}

package/fixtures/openapi/KubernetesClusterRegistrationRequest/valid/action-profile.json

@@ -0,0 +1,5 @@
+{
+  "name": "agent",
+  "connectionMode": "agent",
+  "agentActionProfile": "read-only"
+}

package/fixtures/openapi/KubernetesImportCandidateListEnvelope/invalid/source-with-spec.json

@@ -0,0 +1,33 @@
+{
+  "items": [
+    {
+      "clusterId": "test",
+      "namespace": "middleware",
+      "workloadKind": "StatefulSet",
+      "workloadName": "database",
+      "desiredReplicas": 3,
+      "readyReplicas": 3,
+      "relatedResources": [],
+      "source": {
+        "resource": {
+          "clusterId": "test",
+          "apiVersion": "apps/v1",
+          "kind": "StatefulSet",
+          "namespace": "middleware",
+          "name": "database",
+          "scopeMode": "namespace",
+          "uid": "uid-1",
+          "resourceVersion": "42"
+        },
+        "specDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "generation": 3,
+        "observedAt": "2026-10-21T08:00:00Z",
+        "owners": [],
+        "spec": {
+          "password": "must-not-be-in-contract"
+        }
+      }
+    }
+  ],
+  "truncated": false
+}

package/fixtures/openapi/KubernetesImportCandidateListEnvelope/invalid/source-without-uid.json

@@ -0,0 +1,29 @@
+{
+  "items": [
+    {
+      "clusterId": "test",
+      "namespace": "middleware",
+      "workloadKind": "StatefulSet",
+      "workloadName": "database",
+      "desiredReplicas": 3,
+      "readyReplicas": 3,
+      "relatedResources": [],
+      "source": {
+        "resource": {
+          "clusterId": "test",
+          "apiVersion": "apps/v1",
+          "kind": "StatefulSet",
+          "namespace": "middleware",
+          "name": "database",
+          "scopeMode": "namespace",
+          "resourceVersion": "42"
+        },
+        "specDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "generation": 3,
+        "observedAt": "2026-10-21T08:00:00Z",
+        "owners": []
+      }
+    }
+  ],
+  "truncated": false
+}

package/fixtures/openapi/KubernetesImportCandidateListEnvelope/valid/stable-source.json

@@ -0,0 +1,30 @@
+{
+  "items": [
+    {
+      "clusterId": "test",
+      "namespace": "middleware",
+      "workloadKind": "StatefulSet",
+      "workloadName": "database",
+      "desiredReplicas": 3,
+      "readyReplicas": 3,
+      "relatedResources": [],
+      "source": {
+        "resource": {
+          "clusterId": "test",
+          "apiVersion": "apps/v1",
+          "kind": "StatefulSet",
+          "namespace": "middleware",
+          "name": "database",
+          "scopeMode": "namespace",
+          "uid": "uid-1",
+          "resourceVersion": "42"
+        },
+        "specDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "generation": 3,
+        "observedAt": "2026-10-21T08:00:00Z",
+        "owners": []
+      }
+    }
+  ],
+  "truncated": false
+}

package/fixtures/openapi/KubernetesNodeListEnvelope/invalid/condition-status-boolean.json

@@ -0,0 +1,17 @@
+{
+  "items": [
+    {
+      "name": "worker-a",
+      "status": "ready",
+      "unschedulable": true,
+      "podCount": 2,
+      "ageSeconds": 3600,
+      "conditions": [
+        {
+          "type": "Ready",
+          "status": true
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/KubernetesNodeListEnvelope/invalid/taint-effect-missing.json

@@ -0,0 +1,16 @@
+{
+  "items": [
+    {
+      "name": "worker-a",
+      "status": "ready",
+      "unschedulable": true,
+      "podCount": 2,
+      "ageSeconds": 3600,
+      "taints": [
+        {
+          "key": "maintenance"
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/KubernetesNodeListEnvelope/valid/legacy-fields-absent.json

@@ -0,0 +1,11 @@
+{
+  "items": [
+    {
+      "name": "worker-a",
+      "status": "ready",
+      "unschedulable": true,
+      "podCount": 2,
+      "ageSeconds": 3600
+    }
+  ]
+}

package/fixtures/openapi/KubernetesNodeListEnvelope/valid/no-taints.json

@@ -0,0 +1,13 @@
+{
+  "items": [
+    {
+      "name": "worker-a",
+      "status": "ready",
+      "unschedulable": false,
+      "podCount": 2,
+      "ageSeconds": 3600,
+      "taints": [],
+      "conditions": []
+    }
+  ]
+}

package/fixtures/openapi/KubernetesNodeListEnvelope/valid/ready-cordoned-tainted.json

@@ -0,0 +1,28 @@
+{
+  "items": [
+    {
+      "name": "worker-a",
+      "status": "ready",
+      "unschedulable": true,
+      "podCount": 2,
+      "ageSeconds": 3600,
+      "taints": [
+        {
+          "key": "maintenance",
+          "value": "task113",
+          "effect": "NoSchedule"
+        }
+      ],
+      "conditions": [
+        {
+          "type": "Ready",
+          "status": "True"
+        },
+        {
+          "type": "DiskPressure",
+          "status": "True"
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/KubernetesNodeListEnvelope/valid/unknown-fields-null.json

@@ -0,0 +1,13 @@
+{
+  "items": [
+    {
+      "name": "worker-a",
+      "status": "ready",
+      "unschedulable": true,
+      "podCount": 2,
+      "ageSeconds": 3600,
+      "taints": null,
+      "conditions": null
+    }
+  ]
+}