@opensoha/contracts 0.1.27 → 0.2.0

package/resource/pod_execution_gateway_test.go

@@ -0,0 +1,149 @@
+package resource
+
+import (
+	"encoding/json"
+	contractsopenapi "github.com/opensoha/soha/contracts/openapi"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+func TestGatewayPodTargetPatternsCompileInGo(t *testing.T) {
+	var document struct {
+		Components struct {
+			Schemas map[string]struct {
+				Properties map[string]struct {
+					Pattern string `json:"pattern"`
+				} `json:"properties"`
+			} `json:"schemas"`
+		} `json:"components"`
+	}
+	if err := json.Unmarshal(contractsopenapi.JSON(), &document); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"KubernetesPodArgvToolInput", "KubernetesPodExecutionLookupInput"} {
+		pattern := document.Components.Schemas[name].Properties["clusterId"].Pattern
+		compiled, err := regexp.Compile(pattern)
+		if err != nil || pattern == "" {
+			t.Fatalf("%s cannot be registered in the Go Gateway: %v", name, err)
+		}
+		if !compiled.MatchString("cluster-a") {
+			t.Fatal("valid cluster rejected")
+		}
+		for _, invalid := range []string{"", "with space", "line\nbreak", "nul\x00byte", "c1\u0085control"} {
+			if compiled.MatchString(invalid) {
+				t.Fatalf("%s accepted a disallowed cluster identifier", name)
+			}
+		}
+	}
+	var canonical map[string]any
+	if err := json.Unmarshal(contractsopenapi.JSON(), &canonical); err != nil {
+		t.Fatal(err)
+	}
+	components, ok := canonical["components"].(map[string]any)
+	if !ok {
+		t.Fatal("canonical OpenAPI components are missing")
+	}
+	schemas, ok := components["schemas"].(map[string]any)
+	if !ok {
+		t.Fatal("canonical OpenAPI schemas are missing")
+	}
+	visited := map[string]bool{}
+	var visit func(any)
+	visit = func(value any) {
+		switch item := value.(type) {
+		case map[string]any:
+			if pattern, ok := item["pattern"].(string); ok {
+				if _, err := regexp.Compile(pattern); err != nil {
+					t.Fatalf("transitive Pod input regex is not portable to Gateway: %v", err)
+				}
+			}
+			if ref, ok := item["$ref"].(string); ok {
+				name := strings.TrimPrefix(ref, "#/components/schemas/")
+				if !visited[name] {
+					visited[name] = true
+					visit(schemas[name])
+				}
+			}
+			for _, child := range item {
+				visit(child)
+			}
+		case []any:
+			for _, child := range item {
+				visit(child)
+			}
+		}
+	}
+	visit(schemas["KubernetesPodArgvToolInput"])
+	visit(schemas["KubernetesPodExecutionLookupInput"])
+}
+
+func TestPodGatewayResultStartsWithMetadataOnly(t *testing.T) {
+	receipt := PodExecutionReceipt{ID: "original", Status: "succeeded", OutputAvailable: true, Output: &PodExecutionOutput{Stdout: "PRIVATE_RAW_STDOUT", Stderr: "PRIVATE_RAW_STDERR"}}
+	result := NewPodGatewayResult(receipt)
+	raw, err := json.Marshal(result)
+	if err != nil || result.Receipt.ID != receipt.ID || result.Receipt.Status != receipt.Status || result.Receipt.OutputAvailable || result.Output != nil || result.OutputState != "unavailable" || strings.Contains(string(raw), "PRIVATE_RAW_") {
+		t.Fatal("Gateway metadata constructor copied raw output", err)
+	}
+	if !receipt.OutputAvailable || receipt.Output.Stdout != "PRIVATE_RAW_STDOUT" || receipt.Output.Stderr != "PRIVATE_RAW_STDERR" {
+		t.Fatal("Gateway projection changed original native receipt")
+	}
+}
+
+func TestPodArgvToolInputKeepsReviewedRequestAndCopiesArguments(t *testing.T) {
+	input := PodArgvToolInput{ClusterID: "cluster-a", Namespace: "team-a", PodName: "app.v1", IdempotencyKey: "original-1", Execution: PodArgvInput{ExpectedUID: "reviewed", Container: "main", Argv: []string{"printf", "literal; $(value)"}}}
+	actual, err := input.Normalized()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if actual.ClusterID != input.ClusterID || actual.Namespace != input.Namespace || actual.PodName != input.PodName || actual.IdempotencyKey != input.IdempotencyKey || actual.Execution.ExpectedUID != "reviewed" || actual.Execution.Argv[1] != input.Execution.Argv[1] || actual.Execution.TimeoutSeconds != PodExecDefaultTimeoutSeconds || actual.Execution.MaxOutputBytes != PodExecDefaultOutputBytes {
+		t.Fatal("reviewed intent or runtime defaults changed")
+	}
+	actual.Execution.Argv[0] = "changed"
+	if input.Execution.Argv[0] != "printf" {
+		t.Fatal("normalization retained caller argument storage")
+	}
+	for _, test := range []struct {
+		name string
+		edit func(*PodArgvToolInput)
+	}{
+		{"empty cluster", func(v *PodArgvToolInput) { v.ClusterID = "" }},
+		{"cluster whitespace", func(v *PodArgvToolInput) { v.ClusterID = "cluster a" }},
+		{"cluster BOM", func(v *PodArgvToolInput) { v.ClusterID = "cluster\ufeff" }},
+		{"cluster bound", func(v *PodArgvToolInput) { v.ClusterID = strings.Repeat("集", 257) }},
+		{"wildcard namespace", func(v *PodArgvToolInput) { v.Namespace = "*" }},
+		{"invalid Pod", func(v *PodArgvToolInput) { v.PodName = "app/other" }},
+		{"missing key", func(v *PodArgvToolInput) { v.IdempotencyKey = "" }},
+		{"key whitespace", func(v *PodArgvToolInput) { v.IdempotencyKey = "old key" }},
+		{"key bound", func(v *PodArgvToolInput) { v.IdempotencyKey = strings.Repeat("x", 129) }},
+		{"missing UID", func(v *PodArgvToolInput) { v.Execution.ExpectedUID = "" }},
+		{"missing argv", func(v *PodArgvToolInput) { v.Execution.Argv = nil }},
+		{"bad stdin", func(v *PodArgvToolInput) { v.Execution.StdinBase64 = "not base64" }},
+		{"timeout bound", func(v *PodArgvToolInput) { v.Execution.TimeoutSeconds = 301 }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			copy := input
+			test.edit(&copy)
+			if _, err := copy.Normalized(); err == nil {
+				t.Fatal("invalid original execution accepted")
+			}
+		})
+	}
+}
+
+func TestPodExecutionLookupRequiresExactlyOneOriginalReference(t *testing.T) {
+	input := PodExecutionLookupInput{ClusterID: "cluster-a", Namespace: "team-a", PodName: "app", ExecutionID: "11511151-1151-4151-8151-115111511151"}
+	if input.Validate() != nil {
+		t.Fatal("canonical execution ID rejected")
+	}
+	input.ExecutionID, input.IdempotencyKey = "", "original-1"
+	if input.Validate() != nil {
+		t.Fatal("original execution key rejected")
+	}
+	for _, refs := range [][2]string{{"", ""}, {"11511151-1151-4151-8151-115111511151", "original-1"}, {"11511151-1151-4151-8151-11511151115A", ""}, {"other", ""}, {"", "key\n"}} {
+		input.ExecutionID, input.IdempotencyKey = refs[0], refs[1]
+		if input.Validate() == nil {
+			t.Fatal("invalid or ambiguous original reference accepted")
+		}
+	}
+}

package/resource/pod_execution_test.go

@@ -0,0 +1,48 @@
+package resource
+
+import (
+	"encoding/base64"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestPodArgvNormalizationPreservesLiteralArgumentsAndBoundsSecrets(t *testing.T) {
+	input := PodArgvInput{ExpectedUID: "reviewed", Argv: []string{"printf", "; $(literal)\n", ""}, StdinBase64: base64.StdEncoding.EncodeToString([]byte{0, 1, 255})}
+	normal, err := input.Normalized()
+	if err != nil || !reflect.DeepEqual(normal.Argv, input.Argv) || normal.TimeoutSeconds != 10 || normal.MaxOutputBytes != 65536 || normal.StdinBase64 != input.StdinBase64 {
+		t.Fatalf("normal=%+v err=%v", normal, err)
+	}
+	normal.Argv[0] = "changed"
+	if input.Argv[0] != "printf" {
+		t.Fatal("normalization changed caller arguments")
+	}
+	for name, mutate := range map[string]func(*PodArgvInput){
+		"uid":           func(p *PodArgvInput) { p.ExpectedUID = "bad uid" },
+		"container":     func(p *PodArgvInput) { p.Container = "../other" },
+		"empty":         func(p *PodArgvInput) { p.Argv = nil },
+		"executable":    func(p *PodArgvInput) { p.Argv = []string{" "} },
+		"nul":           func(p *PodArgvInput) { p.Argv = []string{"printf", "PRIVATE_VALUE\x00"} },
+		"argument-size": func(p *PodArgvInput) { p.Argv = []string{strings.Repeat("x", 8193)} },
+		"argument-total": func(p *PodArgvInput) {
+			p.Argv = []string{strings.Repeat("x", 8192), strings.Repeat("x", 8192), strings.Repeat("x", 8192), strings.Repeat("x", 8192), "x"}
+		},
+		"timeout":          func(p *PodArgvInput) { p.TimeoutSeconds = 301 },
+		"negative-timeout": func(p *PodArgvInput) { p.TimeoutSeconds = -1 },
+		"output":           func(p *PodArgvInput) { p.MaxOutputBytes = PodArgvMaxOutputBytes + 1 },
+		"negative-output":  func(p *PodArgvInput) { p.MaxOutputBytes = -1 },
+		"stdin-encoding":   func(p *PodArgvInput) { p.StdinBase64 = "PRIVATE_VALUE!" },
+		"stdin-size": func(p *PodArgvInput) {
+			p.StdinBase64 = base64.StdEncoding.EncodeToString(make([]byte, PodExecMaxStdinBytes+1))
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			value := input
+			mutate(&value)
+			_, err := value.Normalized()
+			if err == nil || strings.Contains(err.Error(), "PRIVATE_VALUE") {
+				t.Fatalf("unsafe validation: %v", err)
+			}
+		})
+	}
+}

package/resource/pod_status_test.go

@@ -0,0 +1,22 @@
+package resource
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestPodContainerStatusKeepsSuccessfulExitAndOldPayloads(t *testing.T) {
+	exitCode := int32(0)
+	encoded, err := json.Marshal(PodView{ContainerStatuses: []PodContainerStatusView{{Name: "migrate", Kind: "init", State: "terminated", ExitCode: &exitCode}}})
+	if err != nil || !strings.Contains(string(encoded), `"exitCode":0`) {
+		t.Fatalf("successful termination was lost: %s, %v", encoded, err)
+	}
+	var old PodView
+	if err := json.Unmarshal([]byte(`{"name":"api","namespace":"apps","phase":"Running","readyContainers":"1/1","restarts":0,"ageSeconds":1}`), &old); err != nil {
+		t.Fatal(err)
+	}
+	if old.QOSClass != "" || len(old.ContainerStatuses) != 0 {
+		t.Fatal("old payload must not invent QoS or container states")
+	}
+}

package/resource/pod_terminal.go

@@ -0,0 +1,188 @@
+package resource
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"time"
+)
+
+const (
+	PodTerminalProtocolVersion            = "1"
+	NativePodTerminalDefaultTimeout int64 = 300
+	NativePodTerminalMaxTimeout     int64 = 900
+	NativePodTerminalMaxOutputBytes int64 = 32 << 20
+	NativePodTerminalMaxInputBytes  int64 = 1 << 20
+	NativeTerminalMaxFrameBytes           = 128 << 10
+	NativeTerminalMaxChunkBytes           = 64 << 10
+	NativeTerminalOutputChunkBytes        = 16 << 10
+	NativePodTerminalTicketHeader         = "X-Soha-Terminal-Ticket"
+	NativeTerminalMaxDimension            = 1000
+)
+
+type PodTerminalInput struct {
+	ExpectedUID    string `json:"expectedUid"`
+	Container      string `json:"container,omitempty"`
+	Shell          string `json:"shell,omitempty"`
+	Width          uint16 `json:"width,omitempty"`
+	Height         uint16 `json:"height,omitempty"`
+	TimeoutSeconds int64  `json:"timeoutSeconds,omitempty"`
+}
+
+func (input PodTerminalInput) Normalized() (PodTerminalInput, error) {
+	if _, err := (PodArgvInput{ExpectedUID: input.ExpectedUID, Container: input.Container, Argv: []string{"terminal"}}).Normalized(); err != nil {
+		return PodTerminalInput{}, err
+	}
+	options, err := (NativeTerminalOptions{Shell: input.Shell, Width: input.Width, Height: input.Height, TimeoutSeconds: input.TimeoutSeconds}).Normalized()
+	if err != nil {
+		return PodTerminalInput{}, err
+	}
+	input.Shell, input.Width, input.Height, input.TimeoutSeconds = options.Shell, options.Width, options.Height, options.TimeoutSeconds
+	return input, nil
+}
+
+type NativeTerminalSize struct {
+	Width  uint16
+	Height uint16
+}
+type NativeTerminalSizeQueue interface {
+	Next(context.Context) *NativeTerminalSize
+}
+
+type PodTerminalResult struct {
+	Status                 string `json:"status"`
+	ExitCode               *int64 `json:"exitCode,omitempty"`
+	InputBytes             int64  `json:"inputBytes"`
+	OutputBytes            int64  `json:"outputBytes"`
+	UIDVerifiedBeforeStart bool   `json:"uidVerifiedBeforeStart"`
+	TargetChanged          bool   `json:"targetChanged"`
+	ReasonCode             string `json:"reasonCode,omitempty"`
+}
+
+func (result PodTerminalResult) Validate() error {
+	if result.InputBytes < 0 || result.InputBytes > NativePodTerminalMaxInputBytes || result.OutputBytes < 0 || result.OutputBytes > NativePodTerminalMaxOutputBytes || result.TargetChanged && result.Status != "unknown" {
+		return fmt.Errorf("invalid terminal result bounds or target")
+	}
+	if result.ExitCode != nil && (*result.ExitCode < 0 || *result.ExitCode > 4294967295) {
+		return fmt.Errorf("invalid terminal exit code")
+	}
+	if !validNativeTerminalReason(result.ReasonCode) {
+		return fmt.Errorf("invalid terminal result reason")
+	}
+	switch result.Status {
+	case "succeeded":
+		if result.ExitCode == nil || *result.ExitCode != 0 || !result.UIDVerifiedBeforeStart {
+			return fmt.Errorf("successful terminal requires a verified target and exit code zero")
+		}
+	case "failed":
+		if result.ExitCode == nil || *result.ExitCode == 0 || !result.UIDVerifiedBeforeStart {
+			return fmt.Errorf("failed terminal requires a verified target and a nonzero exit code")
+		}
+	case "timed_out", "canceled", "transport_lost", "unknown", "input_limit", "output_limit":
+		if result.ExitCode != nil {
+			return fmt.Errorf("uncertain terminal result cannot assert an exit code")
+		}
+	default:
+		return fmt.Errorf("invalid terminal result status")
+	}
+	return nil
+}
+
+type PodTerminalLease struct {
+	ID              string             `json:"id"`
+	Status          string             `json:"status"`
+	ClusterID       string             `json:"clusterId"`
+	Target          PodExecutionTarget `json:"target"`
+	Shell           string             `json:"shell"`
+	CreatedAt       time.Time          `json:"createdAt"`
+	TicketExpiresAt time.Time          `json:"ticketExpiresAt"`
+	DeadlineAt      time.Time          `json:"deadlineAt"`
+	ClosedAt        *time.Time         `json:"closedAt,omitempty"`
+	MaxInputBytes   int64              `json:"maxInputBytes"`
+	MaxOutputBytes  int64              `json:"maxOutputBytes"`
+	Result          *PodTerminalResult `json:"result,omitempty"`
+}
+
+type PodTerminalCreated struct {
+	Session PodTerminalLease `json:"session"`
+	Ticket  string           `json:"ticket"`
+}
+
+// NativeTerminalFrame contains no bearer or ticket. Output is one merged PTY
+// stream. Ready acknowledges the authorized WebSocket, not process readiness.
+type NativeTerminalFrame struct {
+	Type   string             `json:"type"`
+	Data   string             `json:"data,omitempty"`
+	Width  uint16             `json:"width,omitempty"`
+	Height uint16             `json:"height,omitempty"`
+	Result *PodTerminalResult `json:"result,omitempty"`
+	Code   string             `json:"code,omitempty"`
+}
+
+func (frame NativeTerminalFrame) Validate(fromClient bool) error {
+	if fromClient {
+		switch frame.Type {
+		case "input":
+			return frame.validateData()
+		case "resize":
+			if frame.Width > 0 && frame.Width <= NativeTerminalMaxDimension && frame.Height > 0 && frame.Height <= NativeTerminalMaxDimension && frame.Data == "" && frame.Result == nil && frame.Code == "" {
+				return nil
+			}
+		case "eof":
+			if frame.emptyFields() {
+				return nil
+			}
+		}
+	} else {
+		switch frame.Type {
+		case "output":
+			return frame.validateData()
+		case "ready":
+			if frame.emptyFields() {
+				return nil
+			}
+		case "exit":
+			if frame.Data == "" && frame.Width == 0 && frame.Height == 0 && frame.Code == "" && frame.Result != nil {
+				return frame.Result.Validate()
+			}
+		case "error":
+			if frame.Data == "" && frame.Width == 0 && frame.Height == 0 && frame.Result == nil && validNativeTerminalError(frame.Code) {
+				return nil
+			}
+		}
+	}
+	return fmt.Errorf("invalid terminal frame direction or fields")
+}
+
+func (frame NativeTerminalFrame) validateData() error {
+	if frame.Width != 0 || frame.Height != 0 || frame.Result != nil || frame.Code != "" || frame.Data == "" || len(frame.Data) > base64.StdEncoding.EncodedLen(NativeTerminalMaxChunkBytes) {
+		return fmt.Errorf("invalid terminal data frame")
+	}
+	data, err := base64.StdEncoding.Strict().DecodeString(frame.Data)
+	if err != nil || len(data) == 0 || len(data) > NativeTerminalMaxChunkBytes || base64.StdEncoding.EncodeToString(data) != frame.Data {
+		return fmt.Errorf("terminal data must be bounded canonical base64")
+	}
+	return nil
+}
+
+func (frame NativeTerminalFrame) emptyFields() bool {
+	return frame.Data == "" && frame.Width == 0 && frame.Height == 0 && frame.Result == nil && frame.Code == ""
+}
+
+func validNativeTerminalError(code string) bool {
+	switch code {
+	case "invalid_frame", "input_limit", "output_limit", "lease_expired", "authorization_revoked", "target_changed", "transport_lost", "unsupported":
+		return true
+	default:
+		return false
+	}
+}
+
+func validNativeTerminalReason(code string) bool {
+	switch code {
+	case "", "process_exited", "deadline_exceeded", "request_canceled", "transport_lost", "target_changed", "target_verification_unavailable", "input_limit", "output_limit":
+		return true
+	default:
+		return false
+	}
+}

package/resource/pod_terminal_test.go

@@ -0,0 +1,63 @@
+package resource
+
+import (
+	"encoding/base64"
+	"strings"
+	"testing"
+)
+
+func TestNativeTerminalInputBoundsAndDefaults(t *testing.T) {
+	input, err := (PodTerminalInput{ExpectedUID: "reviewed"}).Normalized()
+	if err != nil || input.Shell != "/bin/sh" || input.Width != 80 || input.Height != 24 || input.TimeoutSeconds != 300 {
+		t.Fatalf("defaults=%+v err=%v", input, err)
+	}
+	for name, input := range map[string]PodTerminalInput{
+		"uid": {}, "shell": {ExpectedUID: "uid", Shell: "sh -c id"}, "width": {ExpectedUID: "uid", Width: 1001}, "height": {ExpectedUID: "uid", Height: 65535}, "timeout": {ExpectedUID: "uid", TimeoutSeconds: 901}, "negative": {ExpectedUID: "uid", TimeoutSeconds: -1},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if _, err := input.Normalized(); err == nil {
+				t.Fatal("accepted invalid input")
+			}
+		})
+	}
+}
+
+func TestNativeTerminalFrameDirectionAndBounds(t *testing.T) {
+	zero, one := int64(0), int64(1)
+	valid := PodTerminalResult{Status: "succeeded", ExitCode: &zero, UIDVerifiedBeforeStart: true}
+	for _, test := range []struct {
+		name          string
+		frame         NativeTerminalFrame
+		client, valid bool
+	}{
+		{"binary", NativeTerminalFrame{Type: "input", Data: base64.StdEncoding.EncodeToString([]byte{0, 255})}, true, true},
+		{"direction", NativeTerminalFrame{Type: "input", Data: "AA=="}, false, false},
+		{"resize", NativeTerminalFrame{Type: "resize", Width: 1000, Height: 1000}, true, true},
+		{"resize-over", NativeTerminalFrame{Type: "resize", Width: 1001, Height: 1}, true, false},
+		{"noncanonical", NativeTerminalFrame{Type: "input", Data: "AB=="}, true, false},
+		{"over-budget", NativeTerminalFrame{Type: "input", Data: base64.StdEncoding.EncodeToString(make([]byte, NativeTerminalMaxChunkBytes+1))}, true, false},
+		{"result", NativeTerminalFrame{Type: "exit", Result: &valid}, false, true},
+		{"error", NativeTerminalFrame{Type: "error", Code: "authorization_revoked"}, false, true},
+		{"provider-error", NativeTerminalFrame{Type: "error", Code: "private provider content"}, false, false},
+		{"mixed", NativeTerminalFrame{Type: "ready", Data: "AA=="}, false, false},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			if err := test.frame.Validate(test.client); (err == nil) != test.valid {
+				t.Fatalf("err=%v", err)
+			}
+		})
+	}
+	for name, result := range map[string]PodTerminalResult{
+		"failed-zero":        {Status: "failed", ExitCode: &zero, UIDVerifiedBeforeStart: true},
+		"uncertain-exit":     {Status: "unknown", ExitCode: &one},
+		"unverified-success": {Status: "succeeded", ExitCode: &zero},
+		"target-success":     {Status: "succeeded", ExitCode: &zero, UIDVerifiedBeforeStart: true, TargetChanged: true},
+		"unbounded-reason":   {Status: "unknown", ReasonCode: strings.Repeat("p", 128<<10)},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if err := result.Validate(); err == nil {
+				t.Fatal("accepted contradictory result")
+			}
+		})
+	}
+}

package/resource/presence.go

@@ -0,0 +1,60 @@
+package resource
+
+import (
+	"fmt"
+	"strings"
+	"time"
+	"unicode"
+)
+
+const ResourcePresenceProtocol = "resource-presence-v1"
+
+// ResourcePresence is one complete, current, name-filtered metadata collection
+// snapshot. An absent object is not inferred from an HTTP error. Collection and
+// object versions are opaque and must never be ordered or parsed as numbers.
+type ResourcePresence struct {
+	Protocol                  string     `json:"protocol"`
+	APIVersion                string     `json:"apiVersion"`
+	Resource                  string     `json:"resource"`
+	Kind                      string     `json:"kind"`
+	Namespace                 string     `json:"namespace"`
+	Name                      string     `json:"name"`
+	CollectionResourceVersion string     `json:"collectionResourceVersion"`
+	State                     string     `json:"state"`
+	UID                       string     `json:"uid,omitempty"`
+	ResourceVersion           string     `json:"resourceVersion,omitempty"`
+	DeletionTimestamp         *time.Time `json:"deletionTimestamp,omitempty"`
+}
+
+func (p ResourcePresence) ValidateFor(kind, namespace, name string) error {
+	definition, ok := LookupKubernetesResourceKind(kind)
+	if !ok || !definition.GenericYAML || definition.Kind != kind || definition.Namespaced != (namespace != "") {
+		return fmt.Errorf("unsupported resource presence target")
+	}
+	apiVersion := definition.Version
+	if definition.Group != "" {
+		apiVersion = definition.Group + "/" + definition.Version
+	}
+	if !p.matchesTarget(apiVersion, definition.Resource, kind, namespace, name) || !presenceOpaque(name) || !presenceOpaque(p.CollectionResourceVersion) {
+		return fmt.Errorf("resource presence does not match the original target or collection snapshot")
+	}
+	if p.State != "present" && p.State != "absent" {
+		return fmt.Errorf("explicit resource presence state is required")
+	}
+	if p.State == "present" {
+		if !presenceOpaque(p.UID) || !presenceOpaque(p.ResourceVersion) {
+			return fmt.Errorf("present resource requires an exact UID and version")
+		}
+	} else if p.UID != "" || p.ResourceVersion != "" || p.DeletionTimestamp != nil {
+		return fmt.Errorf("absent resource cannot contain a current object identity")
+	}
+	return nil
+}
+
+func (p ResourcePresence) matchesTarget(apiVersion, resource, kind, namespace, name string) bool {
+	return p.Protocol == ResourcePresenceProtocol && p.APIVersion == apiVersion && p.Resource == resource && p.Kind == kind && p.Namespace == namespace && p.Name == name
+}
+
+func presenceOpaque(value string) bool {
+	return value != "" && len(value) <= 256 && strings.IndexFunc(value, func(r rune) bool { return unicode.IsControl(r) || unicode.IsSpace(r) }) < 0
+}

package/resource/presence_test.go

@@ -0,0 +1,28 @@
+package resource
+
+import "testing"
+
+func TestPresenceRequiresVersionedOriginalGVRAndIdentity(t *testing.T) {
+	base := ResourcePresence{Protocol: ResourcePresenceProtocol, APIVersion: "v1", Resource: "configmaps", Kind: "ConfigMap", Namespace: "team-a", Name: "app", CollectionResourceVersion: "opaque", State: "absent"}
+	if err := base.ValidateFor("ConfigMap", "team-a", "app"); err != nil {
+		t.Fatal(err)
+	}
+	for _, mutate := range []func(*ResourcePresence){
+		func(p *ResourcePresence) { p.Protocol = "" },
+		func(p *ResourcePresence) { p.APIVersion = "apps/v1" },
+		func(p *ResourcePresence) { p.Resource = "secrets" },
+		func(p *ResourcePresence) { p.Kind = "Secret" },
+		func(p *ResourcePresence) { p.Namespace = "other" },
+		func(p *ResourcePresence) { p.Name = "other" },
+		func(p *ResourcePresence) { p.CollectionResourceVersion = "" },
+		func(p *ResourcePresence) { p.UID = "uid" },
+		func(p *ResourcePresence) { p.State = "present" },
+		func(p *ResourcePresence) { p.State = "" },
+	} {
+		changed := base
+		mutate(&changed)
+		if changed.ValidateFor("ConfigMap", "team-a", "app") == nil {
+			t.Fatal("missing protocol, target or identity became a presence proof")
+		}
+	}
+}

package/resource/rbac_graph.go

@@ -0,0 +1,4 @@
+package resource
+
+// RBACResourceGraphFeature identifies Agent support for the RBAC graph roots.
+const RBACResourceGraphFeature = "resource.graph.rbac.v1"

package/resource/rollout_optional_test.go

@@ -0,0 +1,33 @@
+package resource
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestRolloutTemplateMatchDistinguishesUnknownFromMismatch(t *testing.T) {
+	var legacy RolloutHistoryView
+	if err := json.Unmarshal([]byte(`{"name":"revision-a","namespace":"team","revision":"1","replicas":0,"readyReplicas":0}`), &legacy); err != nil {
+		t.Fatal(err)
+	}
+	if legacy.MatchesCurrentTemplate != nil || legacy.PodRevisionHash != "" {
+		t.Fatal("legacy history must not invent template match or Pod hash")
+	}
+	mismatch := false
+	legacy.MatchesCurrentTemplate = &mismatch
+	legacy.PodRevisionHash = "observed-hash"
+	data, err := json.Marshal(legacy)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var wire map[string]any
+	if err := json.Unmarshal(data, &wire); err != nil {
+		t.Fatal(err)
+	}
+	if value, ok := wire["matchesCurrentTemplate"]; !ok || value != false {
+		t.Fatal("confirmed mismatch must survive JSON encoding")
+	}
+	if wire["podRevisionHash"] != "observed-hash" {
+		t.Fatal("observed hash must survive JSON encoding")
+	}
+}

package/resource/root_cr.go

@@ -2,7 +2,7 @@ package resource
 
 import (
 	"fmt"
-	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha/contracts/gen/go/sohaapi"
 	"strings"
 )
 

package/resource/runtime/argocd_observation.go

@@ -7,7 +7,7 @@ import (
 	"reflect"
 	"time"
 
-	contractresource "github.com/opensoha/soha-contracts/resource"
+	contractresource "github.com/opensoha/soha/contracts/resource"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"