@opensoha/contracts 0.1.16 → 0.1.18

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>/`.
 
@@ -281,6 +303,52 @@ rename `operationId`, `operationKind`, `runnerId`, `state`, `occurredAt`,
 `evidence`, `finalState`, or `callback`; must not add new required fields; and
 must not narrow existing lifecycle state names or final status values.
 
+## Network Runtime Protocol
+
+`network/network-runtime-protocol.schema.json` owns messages exchanged by
+network-control, endpoint services and network gateways. The contract carries
+runtime identity, configuration and policy versions, bounded lease grants and
+apply/revoke acknowledgements. It must never carry WireGuard private keys,
+RADIUS shared secrets, passwords, EAP private material or mihomo subscription
+credentials.
+
+For `0.1.x`, patch releases may add optional fields and new message types with
+strict payload definitions. They must not remove or rename `schemaVersion`,
+`messageId`, `messageType`, `producerId`, `runtimeId`, `runtimeKind`,
+`occurredAt`, `expiresAt` or `payload`; must not remove existing message,
+runtime-kind, access-profile or status enum values; and must not loosen unknown
+field rejection. Existing lease identity, subject/device binding, policy
+version and expiry fields must remain required.
+
+NAS authorization and session control use the same versioned envelope. Their
+payloads contain only Soha identity references, bounded standard RADIUS
+attributes and command acknowledgements. Public management bindings map a NAS
+to one registered runtime/site and an access profile to site enforcement
+attributes; neither contract may add RADIUS shared secrets or authentication
+credential material.
+
+WireGuard enrollment carries only a public key. VPN connection authorization
+creates a session-scoped NetworkLease; desired configuration may add a strict
+WireGuard block with overlay addresses, peers, split routes and default-deny
+firewall rules. Private keys never cross this contract. Existing consumers
+must ignore no fields because runtime messages remain closed; therefore a
+consumer advertises `wireguard` only after it supports the full block and its
+configuration version/readback semantics.
+
+## Network Ingest Event
+
+`network/network-ingest-event.schema.json` owns bounded, replayable telemetry
+batches sent to `/api/ingest/v1/**`. Heartbeat, RADIUS Accounting, flow
+aggregate and connection summary payloads remain typed and cannot be treated
+as authorization state.
+
+For `0.1.x`, patch releases may add optional fields, producer kinds and event
+types with strict payload definitions. They must not remove or rename
+`schemaVersion`, `batchId`, `producerId`, `producerKind`, `sentAt`, `events`,
+event `id`, `type`, `sequence`, `occurredAt` or `payload`; must not remove
+existing enum values; must not raise the 1,000-event batch maximum without a
+resource-limit review; and must not introduce an open provider payload object.
+
 ## Permission Catalog
 
 `auth/permission-catalog.json` owns grantable OpenSoha resource/action keys,
@@ -317,3 +385,26 @@ 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 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.

package/README.md

@@ -32,6 +32,8 @@ auth/token-claims.schema.json         Token/JWT claims contract
 auth/permission-catalog.json          Canonical resource/action permission catalog
 auth/permission-catalog.schema.json   Permission definition and migration metadata
 connectors/connector-event-envelope.schema.json  Connector runtime event batch envelope
+network/network-runtime-protocol.schema.json  Network control/runtime message contract
+network/network-ingest-event.schema.json  Bounded heartbeat, Accounting and flow event batches
 gen/go/sohaapi                        Go SDK types for stable cross-repo contracts
 gen/ts/sohaapi                        TypeScript SDK types for stable Web contracts
 ```
@@ -147,6 +149,12 @@ failure.
 
 ## Consumer Matrix
 
+Network runtime schemas and network-access DTOs require `0.1.17` or later;
+they are absent from npm `0.1.16` and Go `v0.1.15`. For unpublished changes,
+use the local consumer matrix below: it packs this checkout for Web and
+supplies an isolated Go workspace. After publishing, update consumer versions
+and lockfiles and verify them without the local override.
+
 The cross-repository consumer gate is:
 
 ```sh
@@ -163,9 +171,10 @@ npm run check:consumers -- --consumer soha-cli --require-all
 npm run check:consumers -- --consumer soha-agent --require-all
 ```
 
-Go consumers run in a temporary `go.work` that includes this checkout, so
-changes are tested against the local contracts module. `soha-web` runs
-`npm ci` and `npm run build` against its `file:../soha-contracts` dependency.
+Go consumers run in a temporary `go.work` that replaces the contracts module
+with this checkout. `soha-web` runs `npm ci`, installs a packed copy of this
+checkout without changing its dependency manifest or lockfile, and builds
+against that package.
 
 Use `--dry-run` to inspect the discovered commands without executing consumer
 builds.
@@ -228,3 +237,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 = "5aa6fa361c2ab8d987415fb1eb93218510deb9359a68212dfe86655dbfaeea5e"
-	PermissionCatalogSHA256 = "01c80a71427e3d7f4898212fb1667405c27f1b798318d9eac86ece8262cd188c"
+	PermissionCatalogContentSHA256 = "5b4c9eed71c549d61a6fd538db542681cb2932619d66ab031c74fcbaaa0c9867"
+	PermissionCatalogSHA256 = "e1e4bab807f64894c9bbde245394902fb1e82253d5847585102560ea6f853894"
 )
 
 //go:embed permission-catalog.json

package/auth/catalog_test.go

@@ -52,6 +52,38 @@ func TestPermissionCatalogIncludesVirtualizationStorageView(t *testing.T) {
 	t.Fatal("virtualization.storage.view is missing")
 }
 
+func TestPermissionCatalogIncludesDeliveryEnvironmentApproval(t *testing.T) {
+	var catalog struct {
+		Permissions []struct {
+			Key            string   `json:"key"`
+			Domain         string   `json:"domain"`
+			Resource       string   `json:"resource"`
+			Action         string   `json:"action"`
+			RiskLevel      string   `json:"riskLevel"`
+			ScopeKinds     []string `json:"scopeKinds"`
+			ApprovalPolicy string   `json:"approvalPolicy"`
+			Status         string   `json:"status"`
+			Assignable     bool     `json:"assignable"`
+		} `json:"permissions"`
+	}
+	if err := json.Unmarshal(PermissionCatalogJSON(), &catalog); err != nil {
+		t.Fatalf("decode permission catalog: %v", err)
+	}
+	for _, permission := range catalog.Permissions {
+		if permission.Key != "delivery.application-environments.approve" {
+			continue
+		}
+		if permission.Domain != "delivery" || permission.Resource != "application-environments" || permission.Action != "approve" ||
+			permission.RiskLevel != "high" || permission.ApprovalPolicy != "eligible" || permission.Status != "active" ||
+			!permission.Assignable || len(permission.ScopeKinds) != 3 || permission.ScopeKinds[0] != "workspace" ||
+			permission.ScopeKinds[1] != "project" || permission.ScopeKinds[2] != "resource" {
+			t.Fatalf("unexpected delivery environment approval permission: %#v", permission)
+		}
+		return
+	}
+	t.Fatal("delivery.application-environments.approve is missing")
+}
+
 func TestPermissionCatalogIncludesIndependentResourceCreationEntry(t *testing.T) {
 	var catalog struct {
 		Permissions []struct {

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)
+		}
+	}
+}