@opensoha/contracts 0.1.17 → 0.1.19

package/COMPATIBILITY.md

@@ -100,6 +100,11 @@ requires dynamic JSON, add it to the baseline with an intentional review note.
 If a loose boundary is tightened, remove it from the baseline in the same
 change so the contract surface keeps moving toward named schemas.
 
+`CapabilityCall.input` is intentionally dynamic: a continuation references a
+registered capability whose version and input schema are checked by the Gateway.
+The call envelope and task reference are closed schemas; this input map does not
+permit arbitrary HTTP endpoints, scripts, or bypasses of current authorization.
+
 ## Public Cloud Extension Points
 
 `CloudExtensionPoint` OpenAPI DTOs describe only public extension points that
@@ -116,6 +121,23 @@ the Cloud-only exclusion enum.
 
 ## Fixture Policy
 
+### Outpost management compatibility
+
+Outpost management retains the deployed `online/offline/degraded` status values,
+node metadata, endpoint, version and last-contact fields. The shared
+`IdentityResourceStatus` type is preserved for SDK source compatibility; these
+legacy runtime values apply to Outposts, not to other resources' management
+transitions. Management `status` and `version` inputs remain accepted for old
+clients but cannot manufacture runtime observations. New clients use
+`runtimeStatus`, `lastHeartbeatAt`, applied configuration information and the
+explicit `forwardAuthUrl`. A desired configuration version of zero represents
+an unregistered node and must not be displayed as a deployed version.
+
+The two Outpost metadata references in the loose-boundary inventory document an
+existing deployed JSON object surface. They preserve legacy clients and do not
+authorize runtime health, configuration versions or lease expiry; those are
+separately typed and recorded by authenticated runtime operations.
+
 Every JSON Schema owned by this repository must have at least one valid and one
 invalid fixture under `fixtures/json-schema/<contract>/`.
 
@@ -342,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.
@@ -363,3 +410,28 @@ npm run check:consumers
 Local runs skip missing sibling checkouts by default. CI and release candidate
 validation should use `--require-all` or a specific `--consumer <name>` so a
 missing checkout is a failure.
+
+## Capability lifecycle metadata
+
+`execution.checks` adds optional version-pinned references to read-only availability,
+precondition, and assessment capabilities. Discovery filters references using the
+caller-visible catalog before pagination. They are suggestions for explicit plan
+steps, not automatic execution or a replacement for domain admission. No declared
+check means unknown support, not a successful check.
+
+`execution.recoveryMode=original_call` declares read-only receipt lookup by the
+managed goal executor with the exact persisted invocation and current authorization.
+It does not promise rollback or authorize a new write. Consumers without these
+optional fields keep the existing version, idempotency, status, and cancellation
+behavior.
+
+## Contracts-first consumer revisions
+
+`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
@@ -237,3 +238,40 @@ import paths.
 
 This repository is licensed under the Apache License 2.0. See
 [LICENSE](./LICENSE) for the full license text.
+
+### Workbench model preferences
+
+`WorkbenchSendMessageStreamRequest.modelPreferences` selects a public model and
+an optional `auto`, `low`, `medium`, or `high` reasoning effort for internal general
+chat. Preferences persist in session metadata when a message is sent; an empty
+public model follows the global default. External agents and analysis modes manage
+their own models. The workbench catalog exposes only permitted public model names.
+
+Gateway routes may declare `metadata.reasoningEfforts: ["low", "medium", "high"]`
+(or a supported subset). Only OpenAI-wire routes without protocol conversion expose
+these levels; every eligible fallback must support a level for it to be offered.
+Unknown capabilities offer automatic reasoning only. Explicit supported efforts map
+to `reasoning_effort` for chat completions and `reasoning.effort` for Responses.
+
+### Shared native Helm task adapter
+
+`helmrelease/runtime` applies the versioned Helm execution contract through Helm 4.
+Both core Direct and the standalone Agent supply their own authorized action configuration;
+queueing, approvals, secret resolution and chart downloads remain outside this package.
+SDK-only consumers need not import this optional package. Its native revision and recovery
+checks are tested once for both execution modes.
+
+Agent-local authenticated POST endpoints `/api/v1/platform/helm/delivery/prepare`,
+`/api/v1/platform/helm/delivery/preflight` and `/api/v1/platform/helm/delivery/observe` accept `HelmExecutionTaskPayload` and return a
+`data` envelope with the prepared payload or `HelmExecutionTaskResult`, respectively.
+They enforce the configured cluster identity and are read-only; `apply` is accepted
+only by the claimed-task runner. Confidential requests are bounded to 8 MiB,
+rendered manifests plus hooks to 2 MiB and values to 1 MiB, and are never logged.
+
+### Controller-aware Agent execution
+
+Manifest tasks emitted by the controller-aware Core use `manifest_agent_v3.<clusterId>` and require the Agent summary capability `manifest.execution.v3`. New Agents also accept legacy `manifest_agent.<clusterId>` and `manifest_agent_v2.<clusterId>` tasks using the protected executor. Old Agents cannot claim the new provider kind; capability checks alone are not a substitute for this claim boundary during rolling upgrades.
+
+Native YAML/CR writes and workload restart, scale, rollback and image changes use the existing request/response bodies under `/api/v1/platform/ownership-v2`, with the original route suffix. This endpoint family guarantees live external-owner checks for Operator, Argo CD, and Argo Rollouts resources and optimistic identity fencing; ownership conflicts return HTTP 409. Core must not fall back to older mutations after 404/405. Reads retain their existing routes.
+
+`resource/runtime` implements bounded WorkloadCronJob, Argo CD, and Argo Rollouts adapters shared by Direct and Agent. The frozen inventory, operation identity, current generation, resource UID/version, and child-resource evidence determine completion. Blue-green and Traefik canary delivery observe native Service revisions, weights, and complete AnalysisRun metric windows. Promotion only releases manual pauses; analysis failure and cancellation require confirmed stable traffic. Restoring desired configuration uses a new governed operation. Other CRs and traffic plugins are not inferred as supported from a generic Ready condition.

package/auth/catalog_generated.go

@@ -6,8 +6,8 @@ import _ "embed"
 
 const (
 	PermissionCatalogVersion = "2.0.0"
-	PermissionCatalogContentSHA256 = "f744896d362070a1e7cdc1eda89c046bee8132f37c6f323dafdd05644e2dbd3c"
-	PermissionCatalogSHA256 = "354ad414691ff0578d805036bbbe80da28d242d0bbabe4699e490af1b6bd87bb"
+	PermissionCatalogContentSHA256 = "5b4c9eed71c549d61a6fd538db542681cb2932619d66ab031c74fcbaaa0c9867"
+	PermissionCatalogSHA256 = "e1e4bab807f64894c9bbde245394902fb1e82253d5847585102560ea6f853894"
 )
 
 //go:embed permission-catalog.json

package/auth/outpost_headers.go

@@ -0,0 +1,17 @@
+package auth
+
+import "strings"
+
+// IsOutpostIdentityHeader identifies the response headers supported by the v1
+// Outpost protocol. Transport, cookie and internal authentication headers are
+// deliberately excluded, including when returned by a configured claim mapping.
+func IsOutpostIdentityHeader(name string) bool {
+	switch strings.ToLower(strings.TrimSpace(name)) {
+	case "x-auth-request-user", "x-auth-request-email", "x-auth-request-groups",
+		"x-soha-user", "x-soha-user-id", "x-soha-email", "x-soha-roles",
+		"x-soha-teams", "x-soha-groups", "x-soha-projects", "x-soha-tags":
+		return true
+	default:
+		return false
+	}
+}

package/auth/outpost_headers_test.go

@@ -0,0 +1,16 @@
+package auth
+
+import "testing"
+
+func TestOutpostIdentityHeaders(t *testing.T) {
+	for _, name := range []string{"X-Soha-User-ID", "X-Soha-Projects", "X-Soha-Tags", " x-auth-request-email "} {
+		if !IsOutpostIdentityHeader(name) {
+			t.Errorf("supported identity header %q rejected", name)
+		}
+	}
+	for _, name := range []string{"Set-Cookie", "Authorization", "Location", "X-Forwarded-Host", "X-Soha-Outpost-Token", "X-Soha-Session-Token", "X-Auth-Email", "X-Soha-Email\r\nInjected"} {
+		if IsOutpostIdentityHeader(name) {
+			t.Errorf("unsupported header %q accepted", name)
+		}
+	}
+}

package/auth/permission-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "authorization.opensoha.io/v1",
   "catalogVersion": "2.0.0",
-  "contentHash": "sha256:f744896d362070a1e7cdc1eda89c046bee8132f37c6f323dafdd05644e2dbd3c",
+  "contentHash": "sha256:5b4c9eed71c549d61a6fd538db542681cb2932619d66ab031c74fcbaaa0c9867",
   "permissions": [
     {
       "key": "access.directory.create",
@@ -2846,6 +2846,62 @@
       "status": "active",
       "assignable": true
     },
+    {
+      "key": "delivery.deployment-templates.create",
+      "domain": "delivery",
+      "resource": "deployment-templates",
+      "action": "create",
+      "displayName": "创建构建模板",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.deployment-templates.delete",
+      "domain": "delivery",
+      "resource": "deployment-templates",
+      "action": "delete",
+      "displayName": "删除构建模板",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "workspace"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.deployment-templates.update",
+      "domain": "delivery",
+      "resource": "deployment-templates",
+      "action": "update",
+      "displayName": "修改构建模板",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.deployment-templates.view",
+      "domain": "delivery",
+      "resource": "deployment-templates",
+      "action": "view",
+      "displayName": "查看构建模板",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "workspace"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "delivery.execution-tasks.cancel",
       "domain": "delivery",
@@ -3322,6 +3378,126 @@
       "status": "active",
       "assignable": true
     },
+    {
+      "key": "delivery.template-sources.create",
+      "domain": "delivery",
+      "resource": "template-sources",
+      "action": "create",
+      "displayName": "创建交付模板来源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.template-sources.delete",
+      "domain": "delivery",
+      "resource": "template-sources",
+      "action": "delete",
+      "displayName": "移除交付模板来源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.template-sources.sync",
+      "domain": "delivery",
+      "resource": "template-sources",
+      "action": "sync",
+      "displayName": "同步交付模板来源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.template-sources.update",
+      "domain": "delivery",
+      "resource": "template-sources",
+      "action": "update",
+      "displayName": "修改交付模板来源",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.template-sources.view",
+      "domain": "delivery",
+      "resource": "template-sources",
+      "action": "view",
+      "displayName": "查看交付模板来源",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.triggers.create",
+      "domain": "delivery",
+      "resource": "triggers",
+      "action": "create",
+      "displayName": "创建交付触发器",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.triggers.update",
+      "domain": "delivery",
+      "resource": "triggers",
+      "action": "update",
+      "displayName": "修改交付触发器",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "delivery.triggers.view",
+      "domain": "delivery",
+      "resource": "triggers",
+      "action": "view",
+      "displayName": "查看交付触发器",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "delivery.workflow-templates.create",
       "domain": "delivery",
@@ -5030,6 +5206,198 @@
       "status": "active",
       "assignable": true
     },
+    {
+      "key": "network_access.vpn_dashboard.view",
+      "domain": "network_access",
+      "resource": "vpn_dashboard",
+      "action": "view",
+      "displayName": "查看VPN 连接看板",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_profiles.create",
+      "domain": "network_access",
+      "resource": "vpn_profiles",
+      "action": "create",
+      "displayName": "创建VPN 连接方案",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_profiles.delete",
+      "domain": "network_access",
+      "resource": "vpn_profiles",
+      "action": "delete",
+      "displayName": "删除VPN 连接方案",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_profiles.publish",
+      "domain": "network_access",
+      "resource": "vpn_profiles",
+      "action": "publish",
+      "displayName": "发布VPN 连接方案",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_profiles.update",
+      "domain": "network_access",
+      "resource": "vpn_profiles",
+      "action": "update",
+      "displayName": "修改VPN 连接方案",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_profiles.view",
+      "domain": "network_access",
+      "resource": "vpn_profiles",
+      "action": "view",
+      "displayName": "查看VPN 连接方案",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_selection_policies.create",
+      "domain": "network_access",
+      "resource": "vpn_selection_policies",
+      "action": "create",
+      "displayName": "创建VPN 选择策略",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_selection_policies.delete",
+      "domain": "network_access",
+      "resource": "vpn_selection_policies",
+      "action": "delete",
+      "displayName": "删除VPN 选择策略",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_selection_policies.preview",
+      "domain": "network_access",
+      "resource": "vpn_selection_policies",
+      "action": "preview",
+      "displayName": "模拟VPN 选择策略",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_selection_policies.publish",
+      "domain": "network_access",
+      "resource": "vpn_selection_policies",
+      "action": "publish",
+      "displayName": "发布VPN 选择策略",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_selection_policies.update",
+      "domain": "network_access",
+      "resource": "vpn_selection_policies",
+      "action": "update",
+      "displayName": "修改VPN 选择策略",
+      "riskLevel": "mutate",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
+    {
+      "key": "network_access.vpn_selection_policies.view",
+      "domain": "network_access",
+      "resource": "vpn_selection_policies",
+      "action": "view",
+      "displayName": "查看VPN 选择策略",
+      "riskLevel": "read",
+      "scopeKinds": [
+        "tenant",
+        "workspace",
+        "resource"
+      ],
+      "approvalPolicy": "never",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "observe.ai.chat",
       "domain": "observe",
@@ -8784,6 +9152,20 @@
         "platform.network.topology.view"
       ]
     },
+    {
+      "key": "platform.nodes.create",
+      "domain": "platform",
+      "resource": "nodes",
+      "action": "create",
+      "displayName": "创建 Kubernetes Node",
+      "riskLevel": "high",
+      "scopeKinds": [
+        "cluster"
+      ],
+      "approvalPolicy": "eligible",
+      "status": "active",
+      "assignable": true
+    },
     {
       "key": "platform.nodes.delete",
       "domain": "platform",

package/compat/consumer-revisions.json

@@ -0,0 +1,7 @@
+{
+  "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.17",
+  "version": "0.1.19",
   "schemas": {
     "plugins/plugin-manifest.schema.json": {
       "rootRequired": ["id", "name", "publisher", "type", "version"],