@opensoha/contracts 0.1.23 → 0.1.25

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.23"
-	YAMLSHA256 = "b919b001e6da4b523d8f30be986bf40453ddd9c5d94126246c8495f1d0e961a3"
-	JSONSHA256 = "bf3e1784f7e9398c9215732407ad4af11c928421805ef2fa7df900dd9a48167c"
+	Version    = "0.1.25"
+	YAMLSHA256 = "5f72e3a41fbf5edf22773a9b85d2841c87c99a0636ad704065b9b1333414bd02"
+	JSONSHA256 = "60341d8b2940687e94a3ed239363761e8e50cf36824fda11f344ba6363a17c04"
 )
 
 //go:embed soha-api.yaml

package/openapi/spec_test.go

@@ -4,6 +4,7 @@ import (
 	"crypto/sha256"
 	"encoding/json"
 	"fmt"
+	"strings"
 	"testing"
 )
 
@@ -36,3 +37,36 @@ func TestEmbeddedSpecsMatchMetadata(t *testing.T) {
 		t.Fatalf("info.version = %q, want %q", document.Info.Version, Version)
 	}
 }
+
+func TestTopologySuccessResponsePreservesDescription(t *testing.T) {
+	var document struct {
+		Paths map[string]struct {
+			Get struct {
+				Responses map[string]map[string]json.RawMessage `json:"responses"`
+			} `json:"get"`
+		} `json:"paths"`
+	}
+	if err := json.Unmarshal(JSON(), &document); err != nil {
+		t.Fatal(err)
+	}
+	response := document.Paths["/clusters/{clusterID}/network/topology"].Get.Responses["200"]
+	if len(response) == 0 {
+		t.Fatal("missing topology success response")
+	}
+	for key := range response {
+		switch key {
+		case "description", "headers", "content", "links":
+		default:
+			if !strings.HasPrefix(key, "x-") {
+				t.Errorf("unexpected topology response field %q", key)
+			}
+		}
+	}
+	var description string
+	if err := json.Unmarshal(response["description"], &description); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(description, "Kubernetes, Gateway API, Traefik and APISIX topology,") {
+		t.Fatalf("topology response description was truncated: %q", description)
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",
@@ -16,7 +16,7 @@
     "check:permissions": "node scripts/generate-permission-catalog.mjs --check",
     "check:version-sync": "node scripts/check-version-sync.mjs",
     "check:consumers": "node scripts/check-consumers.mjs",
-    "validate": "node scripts/validate.mjs",
+    "validate": "node --test scripts/validate-fixtures.checks.mjs && node scripts/validate.mjs",
     "lint:openapi": "node scripts/lint-openapi.mjs",
     "check:openapi-breaking": "node scripts/check-openapi-breaking.mjs",
     "check:openapi-loose-boundaries": "node scripts/check-openapi-loose-boundaries.mjs",
@@ -89,7 +89,23 @@
     "./evaluation/gate-decision.schema.json": "./evaluation/gate-decision.schema.json",
     "./evaluation/feedback-sample.schema.json": "./evaluation/feedback-sample.schema.json",
     "./memory/memory-record.schema.json": "./memory/memory-record.schema.json",
-    "./memory/memory-policy.schema.json": "./memory/memory-policy.schema.json"
+    "./memory/memory-policy.schema.json": "./memory/memory-policy.schema.json",
+    "./agent/personal-environment-request.schema.json": "./agent/personal-environment-request.schema.json",
+    "./agent/personal-environment-result.schema.json": "./agent/personal-environment-result.schema.json",
+    "./agent/personal-environment-preflight-request.schema.json": "./agent/personal-environment-preflight-request.schema.json",
+    "./agent/personal-environment-preflight-result.schema.json": "./agent/personal-environment-preflight-result.schema.json",
+    "./agent/personal-guest-binding.schema.json": "./agent/personal-guest-binding.schema.json",
+    "./agent/personal-guest-enrollment.schema.json": "./agent/personal-guest-enrollment.schema.json",
+    "./agent/personal-guest-heartbeat.schema.json": "./agent/personal-guest-heartbeat.schema.json",
+    "./connectors/connector-action.schema.json": "./connectors/connector-action.schema.json",
+    "./agent/personal-guest-renewal.schema.json": "./agent/personal-guest-renewal.schema.json",
+    "./agent/personal-guest-data-plan.schema.json": "./agent/personal-guest-data-plan.schema.json",
+    "./agent/personal-guest-provisioning.schema.json": "./agent/personal-guest-provisioning.schema.json",
+    "./agent/personal-guest-runtime.schema.json": "./agent/personal-guest-runtime.schema.json",
+    "./agent/personal-guest-runtime-result.schema.json": "./agent/personal-guest-runtime-result.schema.json",
+    "./agent/personal-guest-tools.schema.json": "./agent/personal-guest-tools.schema.json",
+    "./agent/personal-browser-network-request.schema.json": "./agent/personal-browser-network-request.schema.json",
+    "./agent/personal-browser-network-response.schema.json": "./agent/personal-browser-network-response.schema.json"
   },
   "files": [
     "delivery",

package/resource/agent_access.go

@@ -21,3 +21,15 @@ type PrometheusQuery struct {
 	End      int64  `json:"end,omitempty"`
 	Step     int64  `json:"step,omitempty"`
 }
+
+// AgentActionCheck separates binary support, authenticated action policy, and Kubernetes authorization.
+// RBAC scope is cluster-wide; target-specific checks and mutations remain authoritative.
+type AgentActionCheck struct {
+	Action         string `json:"action"`
+	Implementation string `json:"implementation"`
+	Configured     string `json:"configured"`
+	KubernetesRBAC string `json:"kubernetesRBAC"`
+	CheckedAt      string `json:"checkedAt,omitempty"`
+	ReasonCode     string `json:"reasonCode,omitempty"`
+	Scope          string `json:"scope,omitempty"`
+}

package/resource/agent_profiles.go

@@ -0,0 +1,62 @@
+package resource
+
+import "fmt"
+
+// KubernetesAgentProfileActions is an installation preset, never a runtime permission bypass.
+// Legacy preserves installations generated before the workbench profile was introduced.
+func KubernetesAgentProfileActions(profile string) ([]string, error) {
+	switch profile {
+	case "read-only":
+		return []string{"platform.custom_resources.list"}, nil
+	case "workbench":
+		return append([]string(nil), kubernetesWorkbenchActions[:]...), nil
+	case "legacy":
+		actions := make([]string, 0, len(kubernetesWorkbenchActions))
+		for _, action := range kubernetesWorkbenchActions {
+			if action != "platform.helm_releases.install" && action != "platform.helm_releases.values_update" && action != "platform.helm_releases.delete" && action != "platform.helm_releases.rollback" {
+				actions = append(actions, action)
+			}
+		}
+		return actions, nil
+	default:
+		return nil, fmt.Errorf("unknown Kubernetes Agent action profile")
+	}
+}
+
+// KubernetesAgentActions lists implemented platform actions, including separately opted-in CRD deletion.
+func KubernetesAgentActions() []string {
+	actions := make([]string, 0, len(kubernetesWorkbenchActions))
+	for _, action := range kubernetesWorkbenchActions {
+		if action != "runtime.execution_tasks.cancel" {
+			actions = append(actions, action)
+		}
+	}
+	return append(actions, "platform.crds.delete")
+}
+
+var kubernetesWorkbenchActions = [...]string{
+	"platform.nodes.drain",
+	"platform.pods.exec",
+	"platform.deployments.restart",
+	"platform.deployments.scale",
+	"platform.deployments.image",
+	"platform.deployments.rollback",
+	"platform.statefulsets.restart",
+	"platform.statefulsets.scale",
+	"platform.daemonsets.restart",
+	"platform.resources.apply",
+	"platform.resources.create",
+	"platform.resources.delete",
+	"platform.custom_resources.list",
+	"platform.custom_resources.create",
+	"platform.custom_resources.apply",
+	"platform.custom_resources.delete",
+	"platform.port_forwards.create",
+	"platform.port_forwards.tunnel",
+	"platform.port_forwards.delete",
+	"platform.helm_releases.install",
+	"platform.helm_releases.values_update",
+	"platform.helm_releases.delete",
+	"platform.helm_releases.rollback",
+	"runtime.execution_tasks.cancel",
+}

package/resource/agent_profiles_test.go

@@ -0,0 +1,36 @@
+package resource
+
+import (
+	"slices"
+	"testing"
+)
+
+func TestKubernetesAgentProfilesKeepPermissionsExplicit(t *testing.T) {
+	workbench, err := KubernetesAgentProfileActions("workbench")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, action := range []string{"platform.nodes.drain", "platform.resources.apply", "platform.resources.create", "platform.resources.delete", "platform.helm_releases.rollback", "platform.port_forwards.tunnel"} {
+		if !slices.Contains(workbench, action) {
+			t.Fatalf("missing workbench action %s", action)
+		}
+	}
+	if slices.Contains(workbench, "*") || slices.Contains(workbench, "platform.crds.delete") {
+		t.Fatal("workbench must not opt into unrestricted or CRD deletion actions")
+	}
+	legacy, _ := KubernetesAgentProfileActions("legacy")
+	if slices.Contains(legacy, "platform.helm_releases.install") {
+		t.Fatal("legacy installation permissions expanded")
+	}
+	readOnly, _ := KubernetesAgentProfileActions("read-only")
+	if !slices.Equal(readOnly, []string{"platform.custom_resources.list"}) {
+		t.Fatalf("read-only contains writes: %v", readOnly)
+	}
+	if _, err := KubernetesAgentProfileActions("unknown"); err == nil {
+		t.Fatal("unknown profile accepted")
+	}
+	workbench[0] = "changed"
+	if next, _ := KubernetesAgentProfileActions("workbench"); next[0] == "changed" {
+		t.Fatal("profile leaked mutable storage")
+	}
+}

package/resource/kubernetes_kinds.go

@@ -0,0 +1,73 @@
+package resource
+
+import "strings"
+
+// KubernetesResourceKind describes the fixed resource surface shared by both transports.
+// GenericYAML excludes resources whose dedicated lifecycle has stronger authorization.
+type KubernetesResourceKind struct {
+	Kind        string
+	Group       string
+	Version     string
+	Resource    string
+	Namespaced  bool
+	GenericYAML bool
+}
+
+var kubernetesResourceKinds = [...]KubernetesResourceKind{
+	{Kind: "Namespace", Group: "", Version: "v1", Resource: "namespaces", Namespaced: false, GenericYAML: false},
+	{Kind: "Pod", Group: "", Version: "v1", Resource: "pods", Namespaced: true, GenericYAML: true},
+	{Kind: "Node", Group: "", Version: "v1", Resource: "nodes", Namespaced: false, GenericYAML: true},
+	{Kind: "Deployment", Group: "apps", Version: "v1", Resource: "deployments", Namespaced: true, GenericYAML: true},
+	{Kind: "StatefulSet", Group: "apps", Version: "v1", Resource: "statefulsets", Namespaced: true, GenericYAML: true},
+	{Kind: "DaemonSet", Group: "apps", Version: "v1", Resource: "daemonsets", Namespaced: true, GenericYAML: true},
+	{Kind: "ReplicaSet", Group: "apps", Version: "v1", Resource: "replicasets", Namespaced: true, GenericYAML: true},
+	{Kind: "Job", Group: "batch", Version: "v1", Resource: "jobs", Namespaced: true, GenericYAML: true},
+	{Kind: "CronJob", Group: "batch", Version: "v1", Resource: "cronjobs", Namespaced: true, GenericYAML: true},
+	{Kind: "ConfigMap", Group: "", Version: "v1", Resource: "configmaps", Namespaced: true, GenericYAML: true},
+	{Kind: "Secret", Group: "", Version: "v1", Resource: "secrets", Namespaced: true, GenericYAML: true},
+	{Kind: "ServiceAccount", Group: "", Version: "v1", Resource: "serviceaccounts", Namespaced: true, GenericYAML: true},
+	{Kind: "ReplicationController", Group: "", Version: "v1", Resource: "replicationcontrollers", Namespaced: true, GenericYAML: true},
+	{Kind: "Service", Group: "", Version: "v1", Resource: "services", Namespaced: true, GenericYAML: true},
+	{Kind: "PersistentVolumeClaim", Group: "", Version: "v1", Resource: "persistentvolumeclaims", Namespaced: true, GenericYAML: true},
+	{Kind: "PersistentVolume", Group: "", Version: "v1", Resource: "persistentvolumes", Namespaced: false, GenericYAML: true},
+	{Kind: "StorageClass", Group: "storage.k8s.io", Version: "v1", Resource: "storageclasses", Namespaced: false, GenericYAML: true},
+	{Kind: "Role", Group: "rbac.authorization.k8s.io", Version: "v1", Resource: "roles", Namespaced: true, GenericYAML: true},
+	{Kind: "RoleBinding", Group: "rbac.authorization.k8s.io", Version: "v1", Resource: "rolebindings", Namespaced: true, GenericYAML: true},
+	{Kind: "ResourceQuota", Group: "", Version: "v1", Resource: "resourcequotas", Namespaced: true, GenericYAML: true},
+	{Kind: "LimitRange", Group: "", Version: "v1", Resource: "limitranges", Namespaced: true, GenericYAML: true},
+	{Kind: "Lease", Group: "coordination.k8s.io", Version: "v1", Resource: "leases", Namespaced: true, GenericYAML: true},
+	{Kind: "HorizontalPodAutoscaler", Group: "autoscaling", Version: "v2", Resource: "horizontalpodautoscalers", Namespaced: true, GenericYAML: true},
+	{Kind: "PodDisruptionBudget", Group: "policy", Version: "v1", Resource: "poddisruptionbudgets", Namespaced: true, GenericYAML: true},
+	{Kind: "Ingress", Group: "networking.k8s.io", Version: "v1", Resource: "ingresses", Namespaced: true, GenericYAML: true},
+	{Kind: "EndpointSlice", Group: "discovery.k8s.io", Version: "v1", Resource: "endpointslices", Namespaced: true, GenericYAML: true},
+	{Kind: "NetworkPolicy", Group: "networking.k8s.io", Version: "v1", Resource: "networkpolicies", Namespaced: true, GenericYAML: true},
+	{Kind: "IngressClass", Group: "networking.k8s.io", Version: "v1", Resource: "ingressclasses", Namespaced: false, GenericYAML: true},
+	{Kind: "GatewayClass", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "gatewayclasses", Namespaced: false, GenericYAML: true},
+	{Kind: "Gateway", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "gateways", Namespaced: true, GenericYAML: true},
+	{Kind: "HTTPRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "httproutes", Namespaced: true, GenericYAML: true},
+	{Kind: "BackendTLSPolicy", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "backendtlspolicies", Namespaced: true, GenericYAML: true},
+	{Kind: "GRPCRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "grpcroutes", Namespaced: true, GenericYAML: true},
+	{Kind: "ReferenceGrant", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "referencegrants", Namespaced: true, GenericYAML: true},
+	{Kind: "PriorityClass", Group: "scheduling.k8s.io", Version: "v1", Resource: "priorityclasses", Namespaced: false, GenericYAML: true},
+	{Kind: "RuntimeClass", Group: "node.k8s.io", Version: "v1", Resource: "runtimeclasses", Namespaced: false, GenericYAML: true},
+	{Kind: "ClusterRole", Group: "rbac.authorization.k8s.io", Version: "v1", Resource: "clusterroles", Namespaced: false, GenericYAML: true},
+	{Kind: "ClusterRoleBinding", Group: "rbac.authorization.k8s.io", Version: "v1", Resource: "clusterrolebindings", Namespaced: false, GenericYAML: true},
+	{Kind: "CustomResourceDefinition", Group: "apiextensions.k8s.io", Version: "v1", Resource: "customresourcedefinitions", Namespaced: false, GenericYAML: false},
+	{Kind: "WorkloadCronJob", Group: "workloads.soha.io", Version: "v1alpha1", Resource: "workloadcronjobs", Namespaced: true, GenericYAML: false},
+	{Kind: "MutatingWebhookConfiguration", Group: "admissionregistration.k8s.io", Version: "v1", Resource: "mutatingwebhookconfigurations", Namespaced: false, GenericYAML: true},
+	{Kind: "ValidatingWebhookConfiguration", Group: "admissionregistration.k8s.io", Version: "v1", Resource: "validatingwebhookconfigurations", Namespaced: false, GenericYAML: true},
+}
+
+// KubernetesResourceKinds returns a copy so callers cannot alter the shared surface.
+func KubernetesResourceKinds() []KubernetesResourceKind {
+	return append([]KubernetesResourceKind(nil), kubernetesResourceKinds[:]...)
+}
+
+func LookupKubernetesResourceKind(kind string) (KubernetesResourceKind, bool) {
+	for _, definition := range kubernetesResourceKinds {
+		if strings.EqualFold(strings.TrimSpace(kind), definition.Kind) {
+			return definition, true
+		}
+	}
+	return KubernetesResourceKind{}, false
+}

package/resource/kubernetes_kinds_test.go

@@ -0,0 +1,38 @@
+package resource
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestKubernetesResourceKindsAreUniqueAndKeepDedicatedLifecycles(t *testing.T) {
+	seen := map[string]bool{}
+	for _, definition := range KubernetesResourceKinds() {
+		key := strings.ToLower(definition.Kind)
+		if seen[key] || definition.Version == "" || definition.Resource == "" {
+			t.Fatalf("invalid definition: %+v", definition)
+		}
+		seen[key] = true
+		if got, ok := LookupKubernetesResourceKind(" " + key + " "); !ok || got != definition {
+			t.Fatalf("lookup: %+v %v", got, ok)
+		}
+	}
+	for _, kind := range []string{"Namespace", "CustomResourceDefinition", "WorkloadCronJob"} {
+		if definition, ok := LookupKubernetesResourceKind(kind); !ok || definition.GenericYAML {
+			t.Fatalf("%s must retain its dedicated lifecycle", kind)
+		}
+	}
+	for _, kind := range []string{"HorizontalPodAutoscaler", "PodDisruptionBudget"} {
+		if definition, ok := LookupKubernetesResourceKind(kind); !ok || !definition.GenericYAML || !definition.Namespaced {
+			t.Fatalf("missing namespaced YAML surface: %s", kind)
+		}
+	}
+	if _, ok := LookupKubernetesResourceKind("Unknown"); ok {
+		t.Fatal("unknown kind accepted")
+	}
+	definitions := KubernetesResourceKinds()
+	definitions[0].Kind = "changed"
+	if KubernetesResourceKinds()[0].Kind == "changed" {
+		t.Fatal("caller changed the shared registry")
+	}
+}

package/resource/models.go

@@ -14,13 +14,14 @@ const (
 )
 
 type ResourceRef struct {
-	ClusterID  string            `json:"clusterId"`
-	APIVersion string            `json:"apiVersion"`
-	Kind       string            `json:"kind"`
-	Name       string            `json:"name"`
-	Namespace  string            `json:"namespace,omitempty"`
-	ScopeMode  ResourceScopeMode `json:"scopeMode"`
-	UID        string            `json:"uid,omitempty"`
+	ClusterID       string            `json:"clusterId"`
+	APIVersion      string            `json:"apiVersion"`
+	Kind            string            `json:"kind"`
+	Name            string            `json:"name"`
+	Namespace       string            `json:"namespace,omitempty"`
+	ScopeMode       ResourceScopeMode `json:"scopeMode"`
+	UID             string            `json:"uid,omitempty"`
+	ResourceVersion string            `json:"resourceVersion,omitempty"`
 }
 
 type ResourceSearchItem struct {
@@ -897,19 +898,27 @@ type NetworkTopologyTraceView struct {
 }
 
 type NetworkTopologyView struct {
-	ClusterID   string                     `json:"clusterId"`
-	Namespace   string                     `json:"namespace,omitempty"`
-	Source      string                     `json:"source"`
-	GeneratedAt string                     `json:"generatedAt"`
-	Summary     NetworkTopologySummaryView `json:"summary"`
-	Traces      []NetworkTopologyTraceView `json:"traces,omitempty"`
-	Warnings    []string                   `json:"warnings,omitempty"`
+	GraphVersion string                     `json:"graphVersion,omitempty"`
+	Nodes        []NetworkTopologyGraphNode `json:"nodes,omitempty"`
+	Edges        []NetworkTopologyGraphEdge `json:"edges,omitempty"`
+	Coverage     []NetworkTopologyCoverage  `json:"coverage,omitempty"`
+	ObservedAt   string                     `json:"observedAt,omitempty"`
+	Truncated    bool                       `json:"truncated,omitempty"`
+	ClusterID    string                     `json:"clusterId"`
+	Namespace    string                     `json:"namespace,omitempty"`
+	Source       string                     `json:"source"`
+	GeneratedAt  string                     `json:"generatedAt"`
+	Summary      NetworkTopologySummaryView `json:"summary"`
+	Traces       []NetworkTopologyTraceView `json:"traces,omitempty"`
+	Warnings     []string                   `json:"warnings,omitempty"`
 }
 
 type NodeView struct {
 	Name           string                  `json:"name"`
 	Status         string                  `json:"status"`
 	Unschedulable  bool                    `json:"unschedulable"`
+	Taints         []NodeTaintView         `json:"taints"`
+	Conditions     []WorkloadConditionView `json:"conditions"`
 	Roles          []string                `json:"roles,omitempty"`
 	Version        string                  `json:"version,omitempty"`
 	InternalIP     string                  `json:"internalIp,omitempty"`

package/resource/network_topology.go

@@ -0,0 +1,166 @@
+package resource
+
+const (
+	NetworkTopologySnapshotFeature  = "network.topology.snapshot.v1"
+	NetworkTopologyGatewayL4Feature = "network.topology.gateway-l4.v1"
+	NetworkTopologyMaxQueries       = 64
+	NetworkTopologyMaxSourceItems   = 200
+	NetworkTopologyMaxSourceBytes   = 1 << 20
+	NetworkTopologyMaxTotalBytes    = 4 << 20
+	NetworkTopologyMaxObjectBytes   = 64 << 10
+	NetworkTopologyDefaultNodes     = 200
+	NetworkTopologyDefaultEdges     = 400
+	NetworkTopologyMaxNodes         = 500
+	NetworkTopologyMaxEdges         = 1000
+)
+
+type NetworkTopologyGraphNode struct {
+	ID              string                     `json:"id"`
+	Type            string                     `json:"type"`
+	Label           string                     `json:"label"`
+	Provider        string                     `json:"provider"`
+	Protocol        string                     `json:"protocol,omitempty"`
+	ResolutionState string                     `json:"resolutionState"`
+	Resource        *ResourceRef               `json:"resource,omitempty"`
+	Rule            *NetworkTopologyRule       `json:"rule,omitempty"`
+	Properties      []NetworkTopologyProperty  `json:"properties,omitempty"`
+	Conditions      []NetworkTopologyCondition `json:"conditions,omitempty"`
+	Generation      int64                      `json:"generation,omitempty"`
+}
+
+type NetworkTopologyGraphEdge struct {
+	ID              string       `json:"id"`
+	Source          string       `json:"source"`
+	Target          string       `json:"target"`
+	Relation        string       `json:"relation"`
+	ResolutionState string       `json:"resolutionState"`
+	Protocol        string       `json:"protocol,omitempty"`
+	Port            string       `json:"port,omitempty"`
+	Weight          *int64       `json:"weight,omitempty"`
+	TotalWeight     *int64       `json:"totalWeight,omitempty"`
+	MirrorPercent   *float64     `json:"mirrorPercent,omitempty"`
+	RuleRef         string       `json:"ruleRef,omitempty"`
+	SourceRef       *ResourceRef `json:"sourceRef,omitempty"`
+	Note            string       `json:"note,omitempty"`
+}
+
+type NetworkTopologyRule struct {
+	Name         string                   `json:"name,omitempty"`
+	Index        int                      `json:"index"`
+	MatchGroups  [][]NetworkTopologyMatch `json:"matchGroups,omitempty"`
+	MatchSummary string                   `json:"matchSummary,omitempty"`
+	Priority     *int64                   `json:"priority,omitempty"`
+	TLSMode      string                   `json:"tlsMode,omitempty"`
+}
+
+type NetworkTopologyMatch struct {
+	Type     string `json:"type"`
+	Name     string `json:"name,omitempty"`
+	Operator string `json:"operator,omitempty"`
+	Value    string `json:"value,omitempty"`
+}
+
+type NetworkTopologyProperty struct {
+	Name  string `json:"name"`
+	Value string `json:"value"`
+}
+
+type NetworkTopologyCondition struct {
+	Type               string `json:"type"`
+	Status             string `json:"status"`
+	Reason             string `json:"reason,omitempty"`
+	ObservedGeneration *int64 `json:"observedGeneration,omitempty"`
+	LastTransitionTime string `json:"lastTransitionTime,omitempty"`
+}
+
+type NetworkTopologyCoverage struct {
+	Provider       string   `json:"provider"`
+	SourceID       string   `json:"sourceId"`
+	State          string   `json:"state"`
+	Namespace      string   `json:"namespace,omitempty"`
+	SupportedKinds []string `json:"supportedKinds,omitempty"`
+	ReasonCode     string   `json:"reasonCode,omitempty"`
+	CheckedAt      string   `json:"checkedAt,omitempty"`
+	ObservedAt     string   `json:"observedAt,omitempty"`
+	Truncated      bool     `json:"truncated,omitempty"`
+}
+
+// Snapshot queries name a fixed source, never a caller-supplied GVR or field path.
+type NetworkTopologySourceQuery struct {
+	SourceID  string `json:"sourceId"`
+	Namespace string `json:"namespace,omitempty"`
+}
+
+type NetworkTopologySnapshotRequest struct {
+	Queries []NetworkTopologySourceQuery `json:"queries"`
+}
+
+type NetworkTopologySourceObject struct {
+	Resource   ResourceRef `json:"resource"`
+	Generation int64       `json:"generation,omitempty"`
+	// Content contains only the source's contract-allowlisted projection, not an original manifest.
+	Content string `json:"content"`
+}
+
+type NetworkTopologySourceResult struct {
+	Coverage NetworkTopologyCoverage       `json:"coverage"`
+	Objects  []NetworkTopologySourceObject `json:"objects"`
+}
+
+type NetworkTopologySnapshot struct {
+	Version string                        `json:"version"`
+	Sources []NetworkTopologySourceResult `json:"sources"`
+}
+
+type NetworkTopologySourceDefinition struct {
+	ID              string
+	Provider        string
+	FallbackVersion string
+	CRDResourceDefinition
+}
+
+var networkTopologySources = [...]NetworkTopologySourceDefinition{
+	{ID: "kubernetes.services", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "Service", Version: "v1", Resource: "services", Namespaced: true}},
+	{ID: "kubernetes.pods", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "Pod", Version: "v1", Resource: "pods", Namespaced: true}},
+	{ID: "kubernetes.endpointslices", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "EndpointSlice", Group: "discovery.k8s.io", Version: "v1", Resource: "endpointslices", Namespaced: true}},
+	{ID: "kubernetes.ingresses", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "Ingress", Group: "networking.k8s.io", Version: "v1", Resource: "ingresses", Namespaced: true}},
+	{ID: "kubernetes.ingressclasses", Provider: "kubernetes", CRDResourceDefinition: CRDResourceDefinition{Kind: "IngressClass", Group: "networking.k8s.io", Version: "v1", Resource: "ingressclasses"}},
+	{ID: "gateway.gateways", Provider: "gateway", CRDResourceDefinition: CRDResourceDefinition{Kind: "Gateway", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "gateways", Namespaced: true}},
+	{ID: "gateway.gatewayclasses", Provider: "gateway", CRDResourceDefinition: CRDResourceDefinition{Kind: "GatewayClass", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "gatewayclasses"}},
+	{ID: "gateway.httproutes", Provider: "gateway", CRDResourceDefinition: CRDResourceDefinition{Kind: "HTTPRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "httproutes", Namespaced: true}},
+	{ID: "gateway.grpcroutes", Provider: "gateway", CRDResourceDefinition: CRDResourceDefinition{Kind: "GRPCRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "grpcroutes", Namespaced: true}},
+	{ID: "gateway.tcproutes", Provider: "gateway", FallbackVersion: "v1alpha2", CRDResourceDefinition: CRDResourceDefinition{Kind: "TCPRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "tcproutes", Namespaced: true}},
+	{ID: "gateway.tlsroutes", Provider: "gateway", FallbackVersion: "v1alpha2", CRDResourceDefinition: CRDResourceDefinition{Kind: "TLSRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "tlsroutes", Namespaced: true}},
+	{ID: "gateway.udproutes", Provider: "gateway", FallbackVersion: "v1alpha2", CRDResourceDefinition: CRDResourceDefinition{Kind: "UDPRoute", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "udproutes", Namespaced: true}},
+	{ID: "gateway.referencegrants", Provider: "gateway", FallbackVersion: "v1beta1", CRDResourceDefinition: CRDResourceDefinition{Kind: "ReferenceGrant", Group: "gateway.networking.k8s.io", Version: "v1", Resource: "referencegrants", Namespaced: true}},
+	{ID: "traefik.ingressroutes", Provider: "traefik", CRDResourceDefinition: CRDResourceDefinition{Kind: "IngressRoute", Group: "traefik.io", Version: "v1alpha1", Resource: "ingressroutes", Namespaced: true}},
+	{ID: "traefik.ingressroutetcps", Provider: "traefik", CRDResourceDefinition: CRDResourceDefinition{Kind: "IngressRouteTCP", Group: "traefik.io", Version: "v1alpha1", Resource: "ingressroutetcps", Namespaced: true}},
+	{ID: "traefik.ingressrouteudps", Provider: "traefik", CRDResourceDefinition: CRDResourceDefinition{Kind: "IngressRouteUDP", Group: "traefik.io", Version: "v1alpha1", Resource: "ingressrouteudps", Namespaced: true}},
+	{ID: "traefik.traefikservices", Provider: "traefik", CRDResourceDefinition: CRDResourceDefinition{Kind: "TraefikService", Group: "traefik.io", Version: "v1alpha1", Resource: "traefikservices", Namespaced: true}},
+	{ID: "traefik.middlewares", Provider: "traefik", CRDResourceDefinition: CRDResourceDefinition{Kind: "Middleware", Group: "traefik.io", Version: "v1alpha1", Resource: "middlewares", Namespaced: true}},
+	{ID: "traefik.middlewaretcps", Provider: "traefik", CRDResourceDefinition: CRDResourceDefinition{Kind: "MiddlewareTCP", Group: "traefik.io", Version: "v1alpha1", Resource: "middlewaretcps", Namespaced: true}},
+	{ID: "apisix.apisixroutes", Provider: "apisix", CRDResourceDefinition: CRDResourceDefinition{Kind: "ApisixRoute", Group: "apisix.apache.org", Version: "v2", Resource: "apisixroutes", Namespaced: true}},
+	{ID: "apisix.apisixupstreams", Provider: "apisix", CRDResourceDefinition: CRDResourceDefinition{Kind: "ApisixUpstream", Group: "apisix.apache.org", Version: "v2", Resource: "apisixupstreams", Namespaced: true}},
+	{ID: "apisix.apisixtls", Provider: "apisix", CRDResourceDefinition: CRDResourceDefinition{Kind: "ApisixTls", Group: "apisix.apache.org", Version: "v2", Resource: "apisixtls", Namespaced: true}},
+}
+
+func NetworkTopologySources() []NetworkTopologySourceDefinition {
+	return append([]NetworkTopologySourceDefinition(nil), networkTopologySources[:]...)
+}
+
+func IsGatewayL4TopologySource(id string) bool {
+	return id == "gateway.tcproutes" || id == "gateway.tlsroutes" || id == "gateway.udproutes"
+}
+
+func (d NetworkTopologySourceDefinition) RequiresCustomResourceAccess() bool {
+	return d.Provider == "traefik" || d.Provider == "apisix" || IsGatewayL4TopologySource(d.ID)
+}
+
+func LookupNetworkTopologySource(id string) (NetworkTopologySourceDefinition, bool) {
+	for _, definition := range networkTopologySources {
+		if definition.ID == id {
+			return definition, true
+		}
+	}
+	return NetworkTopologySourceDefinition{}, false
+}