@opensoha/contracts 0.1.25 → 0.1.26

package/COMPATIBILITY.md

@@ -530,3 +530,27 @@ only synchronize their release-version metadata to satisfy their existing
 guards. Candidate matrices use the packed/local contracts source. Consumers
 must still pin the published version and validate the registry/proxy package
 before claiming released-version acceptance.
+
+
+## 0.1.26 delivery workbench contracts
+
+This release candidate adds optional stable Kubernetes resource identities,
+generic root-CR relationships and publication control, immutable template
+versions/adoption previews, migration declarations, and create-only first-release
+initialization. Existing request fields, operation IDs, action enums and client
+methods remain compatible. Published version snapshots and fixed consumer
+revisions are preserved.
+
+Template adoption is configuration, not proof of deployment. Runtime baselines
+require matching original resource UIDs and healthy execution/observation
+receipts. Unknown existing deployments remain blocked; initialization cannot
+adopt existing resources or replay uncertain writes. Migration guides are
+review information and are not executed as scripts.
+
+Core and Agent must implement the matching capability/provider protocols before
+using root-CR or initialization tasks. Old runtimes must reject unsupported
+protocols rather than interpret them as ordinary SSA or Helm updates. Publishing
+this SDK alone does not enable the feature or validate a production deployment.
+Consumers must pin the actually published npm/Go artifacts and validate the
+released combination; local tarballs and provenance policy files do not prove
+registry publication or an npm provenance attestation.

package/README.md

@@ -118,7 +118,7 @@ calling code in the consumer until those APIs are promoted into the supported
 client surface. Redirect-oriented flows such as OIDC provider redirects should
 not use the JSON-only `doJSON` helper until a non-JSON client mode is added.
 
-The Go generator and generated DTO checks run with Go 1.27.2 in CI.
+The Go generator and generated DTO checks run with Go 1.27.3 in CI.
 
 ## Validation
 

package/agent/environment/export.go

@@ -86,6 +86,7 @@ func (w *ExportWriter) Finish(request Request) (ExportResult, error) {
 	if err := binary.Write(w.Writer, binary.BigEndian, uint32(0)); err != nil {
 		return ExportResult{}, err
 	}
+	// #nosec G115 -- ValidateFor bounds all three lease IDs to 128 runes and the remaining receipt fields are fixed or bounded.
 	if err := binary.Write(w.Writer, binary.BigEndian, uint32(len(data))); err != nil {
 		return ExportResult{}, err
 	}

package/agent/environment/protocol_test.go

@@ -16,7 +16,7 @@ func TestRequestFixturesMatchRuntimeBoundary(t *testing.T) {
 		}
 		for _, file := range files {
 			t.Run(kind+"/"+filepath.Base(file), func(t *testing.T) {
-				data, err := os.ReadFile(file)
+				data, err := os.ReadFile(file) // #nosec G304 -- Glob is rooted in repository fixtures with fixed valid/invalid categories.
 				if err != nil {
 					t.Fatal(err)
 				}

package/agent/guest/protocol_test.go

@@ -35,7 +35,7 @@ func TestSchemaFixtures(t *testing.T) {
 			}
 			for _, file := range files {
 				t.Run(name+"/"+kind+"/"+filepath.Base(file), func(t *testing.T) {
-					data, err := os.ReadFile(file)
+					data, err := os.ReadFile(file) // #nosec G304 -- Glob uses only the fixed repository fixture names and valid/invalid categories above.
 					if err != nil {
 						t.Fatal(err)
 					}
@@ -50,7 +50,7 @@ func TestSchemaFixtures(t *testing.T) {
 
 func guestFixture[T any](t *testing.T, name string) T {
 	t.Helper()
-	data, err := os.ReadFile("../../fixtures/json-schema/personal-guest-" + name + "/valid/minimal.json")
+	data, err := os.ReadFile("../../fixtures/json-schema/personal-guest-" + name + "/valid/minimal.json") // #nosec G304 -- All callers pass constant test fixture names, never external input.
 	if err != nil {
 		t.Fatal(err)
 	}

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

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.25",
+  "version": "0.1.26",
   "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.25",
+  "version": "0.1.26",
   "generatedFrom": "openapi/soha-api.yaml",
   "entries": [
     {

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/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/KubernetesPod/invalid/pod-uid.json

@@ -0,0 +1,9 @@
+{
+  "name": "api-0",
+  "namespace": "test",
+  "phase": "Running",
+  "restarts": 0,
+  "uid": "",
+  "readyContainers": "1/1",
+  "ageSeconds": 60
+}

package/fixtures/openapi/KubernetesPod/valid/pod-uid.json

@@ -0,0 +1,9 @@
+{
+  "name": "api-0",
+  "namespace": "test",
+  "phase": "Running",
+  "restarts": 0,
+  "uid": "uid-original",
+  "readyContainers": "1/1",
+  "ageSeconds": 60
+}

package/fixtures/openapi/KubernetesPodDetail/invalid/pod-uid.json

@@ -0,0 +1,6 @@
+{
+  "name": "api-0",
+  "namespace": "test",
+  "phase": "Running",
+  "uid": ""
+}

package/fixtures/openapi/KubernetesPodDetail/valid/pod-uid.json

@@ -0,0 +1,6 @@
+{
+  "name": "api-0",
+  "namespace": "test",
+  "phase": "Running",
+  "uid": "uid-original"
+}