@opensoha/contracts 0.1.27 → 0.1.29

package/COMPATIBILITY.md

@@ -62,9 +62,10 @@ Release order for `0.1.x`:
 3. Run `npm test`, `npm pack --dry-run`, `npm run release:artifacts`, and
    the consumer matrix.
 4. Create tag `v<version>`.
-5. Let the release workflow publish npm when `NPM_TOKEN` is configured and
-   create the GitHub release with the npm tarball, `.sha256` checksum, and
-   release manifest attached.
+5. Let the release workflow stage the npm package with `NPM_TOKEN`. After a
+   maintainer approves the stage with 2FA, dispatch recovery for the same tag.
+   The workflow verifies the public npm package and Go tag before attaching
+   the tarball, checksums, and release manifest to the GitHub release.
 
 ## Compatibility Baseline
 

package/README.md

@@ -232,17 +232,16 @@ the tarball checksum, manifest metadata, packed `package.json`, every exported
 package entrypoint, both OpenAPI artifact hashes, the SBOM identity and
 checksum, the provenance policy and checksum, and the consumer matrix summary.
 
-The tag workflow runs `npm test`, `npm pack --dry-run`, the strict consumer
-matrix, requires `NPM_TOKEN`, publishes npm with provenance, verifies the npm
-package and Go module tag after publish, and attaches the tarball, checksum,
-SBOM, SBOM checksum, provenance policy, provenance policy checksum, manifest,
-and consumer matrix to the GitHub release. It then downloads the published
-release assets and runs `release:verify` against the downloaded tarball.
+The tag workflow runs `npm test`, `npm pack --dry-run`, and the strict consumer
+matrix, then uses `NPM_TOKEN` to stage the npm tarball with provenance. A
+maintainer approves the stage on npmjs.com with 2FA. Dispatch the release
+workflow with the same tag and `publish_mode=recover` after approval. Recovery
+verifies the public npm package and Go module tag, attaches the release
+artifacts to GitHub, and verifies the downloaded tarball.
 
 The local release manifest records the provenance policy expected from the tag
-workflow. It does not prove a remote npm registry attestation by itself; that
-evidence is produced and checked only after the tag workflow publishes with
-`npm publish --provenance`.
+workflow. Verify the registry attestation's artifact digest and source revision
+after approval makes the package public.
 
 During private staging, consumers intentionally use sibling repository
 checkouts, `go.work` / `replace` entries, and `file:../soha-contracts` package

package/compat/consumer-revisions.json

@@ -1,5 +1,5 @@
 {
-  "soha": "57bfa94873ff2825bccc6312842859011c1ec23a",
+  "soha": "59e929046927eecf1977bc50a446fd5d823d1d31",
   "soha-web": "447cbe5358802ef40d86ac67b7b59c5afe9c846a",
   "soha-app": "0c3c76c373246f7d2218b48f68b89bf3097f777b",
   "soha-cli": "1c9b760c986a9c1a5148db55b72ab99d23edd7a3",

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

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

package/fixtures/openapi/KubernetesClusterRegistrationRequest/invalid/metric-cluster-value-length.json

@@ -0,0 +1,3 @@
+{
+  "prometheusClusterLabelValue": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+}

package/fixtures/openapi/KubernetesClusterRegistrationRequest/invalid/metric-cluster-value-type.json

@@ -0,0 +1,3 @@
+{
+  "prometheusClusterLabelValue": 7
+}

package/fixtures/openapi/KubernetesClusterRegistrationRequest/valid/metric-cluster-alias.json

@@ -0,0 +1,5 @@
+{
+  "name": "example",
+  "prometheusClusterLabel": "cluster",
+  "prometheusClusterLabelValue": "middleware-prod"
+}

package/fixtures/openapi/KubernetesClusterRegistrationRequest/valid/metric-cluster-reset.json

@@ -0,0 +1,3 @@
+{
+  "prometheusClusterLabelValue": ""
+}

package/fixtures/openapi/KubernetesHelmReleaseValuesUpdateInput/invalid/revision-overflow.json

@@ -0,0 +1,4 @@
+{
+  "content": "{}\n",
+  "expectedRevision": 2147483647
+}

package/fixtures/openapi/KubernetesHelmReleaseValuesUpdateInput/valid/legacy.json

@@ -0,0 +1,3 @@
+{
+  "content": "{}\n"
+}

package/fixtures/openapi/KubernetesHelmReleaseValuesUpdateInput/valid/observed-revision.json

@@ -0,0 +1,4 @@
+{
+  "content": "replicaCount: 2\n",
+  "expectedRevision": 4
+}

package/fixtures/openapi/KubernetesJobDetail/invalid/execution-observation.json

@@ -0,0 +1,23 @@
+{
+  "name": "task117-demo-failed",
+  "namespace": "task117-jobs-demo",
+  "completions": 1,
+  "completionTarget": 1,
+  "parallelism": 1,
+  "succeeded": 0,
+  "failed": 1,
+  "active": 0,
+  "suspend": false,
+  "backoffLimit": -1,
+  "activeDeadlineSeconds": 3600,
+  "ttlSecondsAfterFinished": 604800,
+  "startTime": "2026-11-01T02:00:00Z",
+  "conditions": [
+    {
+      "type": "Failed",
+      "status": "True",
+      "reason": "BackoffLimitExceeded",
+      "lastTransitionTime": "2026-11-01T02:00:20Z"
+    }
+  ]
+}

package/fixtures/openapi/KubernetesJobDetail/valid/execution-observation.json

@@ -0,0 +1,23 @@
+{
+  "name": "task117-demo-failed",
+  "namespace": "task117-jobs-demo",
+  "completions": 1,
+  "completionTarget": 1,
+  "parallelism": 1,
+  "succeeded": 0,
+  "failed": 1,
+  "active": 0,
+  "suspend": false,
+  "backoffLimit": 0,
+  "activeDeadlineSeconds": 3600,
+  "ttlSecondsAfterFinished": 604800,
+  "startTime": "2026-11-01T02:00:00Z",
+  "conditions": [
+    {
+      "type": "Failed",
+      "status": "True",
+      "reason": "BackoffLimitExceeded",
+      "lastTransitionTime": "2026-11-01T02:00:20Z"
+    }
+  ]
+}

package/fixtures/openapi/KubernetesNode/invalid/labels.json

@@ -0,0 +1,10 @@
+{
+  "name": "worker-a",
+  "status": "Ready",
+  "unschedulable": false,
+  "podCount": 0,
+  "ageSeconds": 0,
+  "labels": {
+    "pool": 1
+  }
+}

package/fixtures/openapi/KubernetesNode/valid/labels.json

@@ -0,0 +1,11 @@
+{
+  "name": "worker-a",
+  "status": "Ready",
+  "unschedulable": false,
+  "podCount": 0,
+  "ageSeconds": 0,
+  "labels": {
+    "node-role.kubernetes.io/worker": "",
+    "pool": "gpu"
+  }
+}

package/fixtures/openapi/KubernetesPodListEnvelope/invalid/empty-uid.json

@@ -0,0 +1,13 @@
+{
+  "items": [
+    {
+      "name": "api",
+      "namespace": "apps",
+      "uid": "",
+      "phase": "Running",
+      "readyContainers": "1/1",
+      "restarts": 0,
+      "ageSeconds": 60
+    }
+  ]
+}

package/fixtures/openapi/KubernetesPodListEnvelope/invalid/invalid-container-state.json

@@ -0,0 +1,20 @@
+{
+  "items": [
+    {
+      "name": "api",
+      "namespace": "apps",
+      "phase": "Running",
+      "readyContainers": "1/1",
+      "restarts": 0,
+      "ageSeconds": 60,
+      "containerStatuses": [
+        {
+          "name": "api",
+          "ready": true,
+          "state": "healthy",
+          "kind": "container"
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/KubernetesPodListEnvelope/invalid/missing-container-ready.json

@@ -0,0 +1,19 @@
+{
+  "items": [
+    {
+      "name": "api",
+      "namespace": "apps",
+      "phase": "Pending",
+      "readyContainers": "0/1",
+      "restarts": 0,
+      "ageSeconds": 60,
+      "containerStatuses": [
+        {
+          "name": "api",
+          "state": "unknown",
+          "kind": "container"
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/KubernetesPodListEnvelope/valid/container-statuses.json

@@ -0,0 +1,67 @@
+{
+  "items": [
+    {
+      "name": "api",
+      "namespace": "apps",
+      "phase": "Running",
+      "readyContainers": "1/3",
+      "restarts": 2,
+      "ageSeconds": 60,
+      "qosClass": "Burstable",
+      "containerStatuses": [
+        {
+          "name": "migrate",
+          "kind": "init",
+          "ready": false,
+          "state": "terminated",
+          "reason": "Completed",
+          "exitCode": 0
+        },
+        {
+          "name": "proxy-init",
+          "kind": "sidecar",
+          "ready": true,
+          "state": "running"
+        },
+        {
+          "name": "api",
+          "ready": true,
+          "state": "running",
+          "kind": "container"
+        },
+        {
+          "name": "proxy",
+          "ready": false,
+          "state": "waiting",
+          "reason": "CrashLoopBackOff",
+          "kind": "container"
+        },
+        {
+          "name": "worker",
+          "ready": false,
+          "state": "unknown",
+          "kind": "container"
+        }
+      ]
+    },
+    {
+      "name": "job",
+      "namespace": "apps",
+      "phase": "Succeeded",
+      "readyContainers": "0/1",
+      "restarts": 0,
+      "ageSeconds": 30,
+      "qosClass": "BestEffort",
+      "containerStatuses": [
+        {
+          "name": "job",
+          "ready": false,
+          "state": "terminated",
+          "reason": "Completed",
+          "exitCode": 0,
+          "kind": "container"
+        }
+      ]
+    }
+  ]
+}

package/fixtures/openapi/KubernetesPodListEnvelope/valid/running-pod.json

@@ -3,6 +3,7 @@
     {
       "name": "api-7c8d9f",
       "namespace": "production",
+      "uid": "97cb3639-ff9d-4633-a70b-70c8149d6f4a",
       "phase": "Running",
       "nodeName": "worker-1",
       "podIp": "10.42.1.8",

package/fixtures/openapi/KubernetesPrometheusDetail/invalid/metric-cluster-value-type.json

@@ -0,0 +1,4 @@
+{
+  "hasBearerToken": false,
+  "clusterLabelValue": 7
+}

package/fixtures/openapi/KubernetesPrometheusDetail/valid/metric-cluster-alias.json

@@ -0,0 +1,5 @@
+{
+  "hasBearerToken": false,
+  "clusterLabel": "cluster",
+  "clusterLabelValue": "middleware-prod"
+}

package/fixtures/openapi/KubernetesResourceGraphEnvelope/invalid/network-edge-source-payload.json

@@ -0,0 +1,73 @@
+{
+  "data": {
+    "clusterId": "cluster-a",
+    "namespace": "team-a",
+    "generatedAt": "2026-08-23T08:00:00Z",
+    "rootId": "apps/v1:Deployment:team-a/api",
+    "nodes": [
+      {
+        "id": "apps/v1:Deployment:team-a/api",
+        "resource": {
+          "clusterId": "cluster-a",
+          "apiVersion": "apps/v1",
+          "kind": "Deployment",
+          "name": "api",
+          "namespace": "team-a",
+          "scopeMode": "namespace",
+          "data": {
+            "privateKey": "forbidden"
+          }
+        },
+        "status": "healthy"
+      },
+      {
+        "id": "v1:Pod:team-a/api-1",
+        "resource": {
+          "clusterId": "cluster-a",
+          "apiVersion": "v1",
+          "kind": "Pod",
+          "name": "api-1",
+          "namespace": "team-a",
+          "scopeMode": "namespace"
+        },
+        "status": "Running"
+      }
+    ],
+    "edges": [
+      {
+        "id": "owns:deployment-api:pod-api-1",
+        "sourceId": "apps/v1:Deployment:team-a/api",
+        "targetId": "v1:Pod:team-a/api-1",
+        "relation": "owns",
+        "resolutionState": "resolved",
+        "protocol": "HTTPS",
+        "port": "443",
+        "sectionName": "https",
+        "fieldPath": "spec.parentRefs[0]",
+        "note": "Declared listener attachment; controller execution unverified",
+        "sourceRef": {
+          "clusterId": "cluster-a",
+          "apiVersion": "apps/v1",
+          "kind": "Deployment",
+          "name": "api",
+          "namespace": "team-a",
+          "scopeMode": "namespace",
+          "data": {
+            "privateKey": "forbidden"
+          }
+        }
+      }
+    ],
+    "evidence": [
+      {
+        "id": "event/team-a/api-1-scheduled",
+        "type": "kubernetes-event",
+        "severity": "info",
+        "summary": "Pod scheduled",
+        "observedAt": "2026-08-23T07:59:58Z",
+        "resourceId": "v1:Pod:team-a/api-1"
+      }
+    ],
+    "warnings": []
+  }
+}

package/fixtures/openapi/KubernetesResourceGraphEnvelope/valid/network-edge-facts.json

@@ -0,0 +1,67 @@
+{
+  "data": {
+    "clusterId": "cluster-a",
+    "namespace": "team-a",
+    "generatedAt": "2026-08-23T08:00:00Z",
+    "rootId": "apps/v1:Deployment:team-a/api",
+    "nodes": [
+      {
+        "id": "apps/v1:Deployment:team-a/api",
+        "resource": {
+          "clusterId": "cluster-a",
+          "apiVersion": "apps/v1",
+          "kind": "Deployment",
+          "name": "api",
+          "namespace": "team-a",
+          "scopeMode": "namespace"
+        },
+        "status": "healthy"
+      },
+      {
+        "id": "v1:Pod:team-a/api-1",
+        "resource": {
+          "clusterId": "cluster-a",
+          "apiVersion": "v1",
+          "kind": "Pod",
+          "name": "api-1",
+          "namespace": "team-a",
+          "scopeMode": "namespace"
+        },
+        "status": "Running"
+      }
+    ],
+    "edges": [
+      {
+        "id": "owns:deployment-api:pod-api-1",
+        "sourceId": "apps/v1:Deployment:team-a/api",
+        "targetId": "v1:Pod:team-a/api-1",
+        "relation": "owns",
+        "resolutionState": "resolved",
+        "protocol": "HTTPS",
+        "port": "443",
+        "sectionName": "https",
+        "fieldPath": "spec.parentRefs[0]",
+        "note": "Declared listener attachment; controller execution unverified",
+        "sourceRef": {
+          "clusterId": "cluster-a",
+          "apiVersion": "apps/v1",
+          "kind": "Deployment",
+          "name": "api",
+          "namespace": "team-a",
+          "scopeMode": "namespace"
+        }
+      }
+    ],
+    "evidence": [
+      {
+        "id": "event/team-a/api-1-scheduled",
+        "type": "kubernetes-event",
+        "severity": "info",
+        "summary": "Pod scheduled",
+        "observedAt": "2026-08-23T07:59:58Z",
+        "resourceId": "v1:Pod:team-a/api-1"
+      }
+    ],
+    "warnings": []
+  }
+}

package/fixtures/openapi/KubernetesSecretCertificate/invalid/secret-data.json

@@ -0,0 +1 @@
+{"name":"demo-tls","namespace":"demo","status":"available","data":{"tls.key":"forbidden"}}

package/fixtures/openapi/KubernetesSecretCertificate/invalid/status.json

@@ -0,0 +1 @@
+{"name":"demo-tls","namespace":"demo","status":"healthy"}

package/fixtures/openapi/KubernetesSecretCertificate/valid/available.json

@@ -0,0 +1 @@
+{"name":"demo-tls","namespace":"demo","status":"available","notBefore":"2026-11-02T08:00:00Z","notAfter":"2026-12-02T08:00:00Z","selfSigned":true}

package/fixtures/openapi/KubernetesSecretCertificate/valid/missing.json

@@ -0,0 +1 @@
+{"name":"demo-tls","namespace":"demo","status":"missing"}

package/gen/go/sohaapi/client.go

@@ -16,7 +16,7 @@ import (
 	"time"
 )
 
-const defaultUserAgent = "opensoha-contracts/0.1.27"
+const defaultUserAgent = "opensoha-contracts/0.1.29"
 
 type Client struct {
 	BaseURL    string

package/gen/go/sohaapi/client_test.go

@@ -50,6 +50,19 @@ func TestRuntimeAndWorkbenchLegacyEnumConstants(t *testing.T) {
 	}
 }
 
+func TestPersonalAgentAccessDecisionPublishedConstants(t *testing.T) {
+	statuses := map[PersonalAgentAccessDecisionStatus]string{
+		PersonalAgentAccessDecisionStatusApproved: "approved",
+		PersonalAgentAccessDecisionStatusRejected: "rejected",
+		PersonalAgentAccessDecisionStatusRevoked:  "revoked",
+	}
+	for status, want := range statuses {
+		if string(status) != want || !status.Valid() {
+			t.Fatalf("PersonalAgentAccessDecisionStatus %q is not the compatible value %q", status, want)
+		}
+	}
+}
+
 func TestObservabilityCredentialKeyLegacyTypes(t *testing.T) {
 	dataSource := ObservabilityDataSource{
 		CredentialKeys: []ObservabilityDataSourceCredentialKeys{

package/gen/go/sohaapi/kubernetes_workload_optional_test.go

@@ -0,0 +1,40 @@
+package sohaapi
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestWorkloadAndCertificateSDKKeepExplicitZeroValues(t *testing.T) {
+	for _, tc := range []struct {
+		name, input string
+		destination any
+	}{
+		{"rollout", `{"matchesCurrentTemplate":false}`, new(KubernetesDeploymentRollout)},
+		{"job", `{"completionTarget":0,"suspend":false}`, new(KubernetesJob)},
+		{"job detail", `{"completionTarget":0,"suspend":false,"backoffLimit":0,"activeDeadlineSeconds":0,"ttlSecondsAfterFinished":0}`, new(KubernetesJobDetail)},
+		{"certificate", `{"selfSigned":false}`, new(KubernetesSecretCertificate)},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if err := json.Unmarshal([]byte(tc.input), tc.destination); err != nil {
+				t.Fatal(err)
+			}
+			encoded, err := json.Marshal(tc.destination)
+			if err != nil {
+				t.Fatal(err)
+			}
+			var before, after map[string]json.RawMessage
+			if err := json.Unmarshal([]byte(tc.input), &before); err != nil {
+				t.Fatal(err)
+			}
+			if err := json.Unmarshal(encoded, &after); err != nil {
+				t.Fatal(err)
+			}
+			for key, value := range before {
+				if string(after[key]) != string(value) {
+					t.Errorf("%s = %s, want %s", key, after[key], value)
+				}
+			}
+		})
+	}
+}

package/gen/go/sohaapi/pod_status_compat_test.go

@@ -0,0 +1,36 @@
+package sohaapi
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestReasoningEffortNamesRemainCompatibleWithPodStatusEnums(t *testing.T) {
+	values := []WorkbenchModelOptionReasoningEfforts{WorkbenchModelOptionReasoningEffortsHigh, WorkbenchModelOptionReasoningEffortsMedium, WorkbenchModelOptionReasoningEffortsLow}
+	for index, want := range []string{"high", "medium", "low"} {
+		if string(values[index]) != want || !values[index].Valid() {
+			t.Fatalf("reasoning effort %d = %q, want %q", index, values[index], want)
+		}
+	}
+	if High != MarketplaceAdvisorySeverityHigh {
+		t.Fatal("legacy advisory High changed")
+	}
+}
+
+func TestPodStatusSDKKeepsZeroExitCode(t *testing.T) {
+	code := int32(0)
+	encoded, err := json.Marshal(KubernetesPodContainerStatus{ExitCode: &code})
+	if err != nil || !strings.Contains(string(encoded), `"exitCode":0`) {
+		t.Fatalf("successful termination was lost: %s, %v", encoded, err)
+	}
+}
+
+func TestPersonalEnvironmentBackendNamesRemainCompatibleWithPodStatusEnums(t *testing.T) {
+	values := []PersonalEnvironmentTemplateBackend{Container, VM}
+	for index, want := range []string{"container", "vm"} {
+		if string(values[index]) != want || !values[index].Valid() {
+			t.Fatalf("backend %d = %q, want %q", index, values[index], want)
+		}
+	}
+}