@opensoha/contracts 0.1.17 → 0.1.18

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.17"
-	YAMLSHA256 = "43c055eeb546b837a15cdd39bacd5c086d5257bfccc8f9fc137943200e4ea72e"
-	JSONSHA256 = "11f96a23fa4302d4518af62b39446ff48204e97c4b9d07e561d81124c2a5e754"
+	Version    = "0.1.18"
+	YAMLSHA256 = "d614ce858924d94da353c7a9380971a3e80964f3e6c865e8b27108e859500cf4"
+	JSONSHA256 = "a98ea9ad99b6f044ce14e42f37b90b42e28347d53e37c727a04210b076aba960"
 )
 
 //go:embed soha-api.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",
@@ -28,6 +28,7 @@
     "test": "npm run check:version-sync && npm run check:generated && npm run validate && npm run lint:openapi && npm run check:openapi-breaking && npm run check:openapi-loose-boundaries && npm run check:json-schema-compat && npm run typecheck && go test ./..."
   },
   "exports": {
+    "./delivery/document.schema.json": "./delivery/document.schema.json",
     "./gen/ts/sohaapi": "./gen/ts/sohaapi/index.ts",
     "./openapi/soha-api.yaml": "./openapi/soha-api.yaml",
     "./openapi/soha-api.json": "./openapi/soha-api.json",
@@ -90,6 +91,7 @@
     "./memory/memory-policy.schema.json": "./memory/memory-policy.schema.json"
   },
   "files": [
+    "delivery",
     "COMPATIBILITY.md",
     "go.mod",
     "go.sum",

package/resource/manifest_health.go

@@ -0,0 +1,155 @@
+package resource
+
+import "encoding/json"
+
+// ManifestHealth gives Direct and Agent execution the same conservative health
+// interpretation. Successful persistence alone is health evidence only for
+// built-in configuration objects, never for an unknown custom resource.
+func ManifestHealth(object map[string]any) string {
+	if object == nil {
+		return "unknown"
+	}
+	encoded, err := json.Marshal(object)
+	if err != nil {
+		return "unknown"
+	}
+	var item manifestHealthObject
+	if err := json.Unmarshal(encoded, &item); err != nil {
+		return "unknown"
+	}
+	if item.Metadata.DeletionTimestamp != "" {
+		return "degraded"
+	}
+	kind := item.APIVersion + "/" + item.Kind
+	switch kind {
+	case "workloads.soha.io/v1alpha1/WorkloadCronJob":
+		// Ready describes configuration synchronization. Its source and owned
+		// CronJob must also be observed by the runtime before declaring health.
+		if item.conditionHealth(true) == "degraded" {
+			return "degraded"
+		}
+		return "unknown"
+	case "v1/ConfigMap", "v1/Secret", "v1/ServiceAccount", "rbac.authorization.k8s.io/v1/Role", "rbac.authorization.k8s.io/v1/RoleBinding", "networking.k8s.io/v1/NetworkPolicy":
+		return "healthy"
+	case "apps/v1/Deployment", "apps/v1/StatefulSet", "apps/v1/DaemonSet":
+		return item.workloadHealth()
+	case "v1/PersistentVolumeClaim":
+		if item.Status.Phase == "Bound" {
+			return "healthy"
+		}
+		if item.Status.Phase == "Lost" {
+			return "degraded"
+		}
+		return "progressing"
+	case "v1/Service":
+		if item.Spec.Type != "LoadBalancer" || len(item.Status.LoadBalancer.Ingress) > 0 {
+			return "healthy"
+		}
+		return "progressing"
+	case "v1/Pod", "batch/v1/Job":
+		if item.Status.Phase == "Succeeded" {
+			return "healthy"
+		}
+		if item.Status.Phase == "Failed" {
+			return "degraded"
+		}
+		return item.conditionHealth(false)
+	default:
+		return item.conditionHealth(true)
+	}
+}
+
+type manifestHealthObject struct {
+	APIVersion string `json:"apiVersion"`
+	Kind       string `json:"kind"`
+	Metadata   struct {
+		Generation        int64  `json:"generation"`
+		DeletionTimestamp string `json:"deletionTimestamp"`
+	} `json:"metadata"`
+	Spec struct {
+		Replicas       *int64 `json:"replicas"`
+		Type           string `json:"type"`
+		UpdateStrategy struct {
+			RollingUpdate struct {
+				Partition int64 `json:"partition"`
+			} `json:"rollingUpdate"`
+		} `json:"updateStrategy"`
+	} `json:"spec"`
+	Status struct {
+		ObservedGeneration     int64  `json:"observedGeneration"`
+		Replicas               int64  `json:"replicas"`
+		ReadyReplicas          int64  `json:"readyReplicas"`
+		UpdatedReplicas        int64  `json:"updatedReplicas"`
+		AvailableReplicas      int64  `json:"availableReplicas"`
+		DesiredNumberScheduled int64  `json:"desiredNumberScheduled"`
+		UpdatedNumberScheduled int64  `json:"updatedNumberScheduled"`
+		NumberAvailable        int64  `json:"numberAvailable"`
+		Phase                  string `json:"phase"`
+		LoadBalancer           struct {
+			Ingress []json.RawMessage `json:"ingress"`
+		} `json:"loadBalancer"`
+		Conditions []struct {
+			Type               string `json:"type"`
+			Status             string `json:"status"`
+			Reason             string `json:"reason"`
+			ObservedGeneration int64  `json:"observedGeneration"`
+		} `json:"conditions"`
+	} `json:"status"`
+}
+
+func (item manifestHealthObject) workloadHealth() string {
+	if item.Metadata.Generation < 1 || item.Status.ObservedGeneration < item.Metadata.Generation {
+		return "progressing"
+	}
+	if item.conditionHealth(false) == "degraded" {
+		return "degraded"
+	}
+	desired := int64(1)
+	if item.Spec.Replicas != nil {
+		desired = *item.Spec.Replicas
+	}
+	healthy := false
+	switch item.Kind {
+	case "Deployment":
+		healthy = item.Status.UpdatedReplicas == desired && item.Status.Replicas == desired && item.Status.AvailableReplicas >= desired
+	case "StatefulSet":
+		updated := max(int64(0), desired-item.Spec.UpdateStrategy.RollingUpdate.Partition)
+		healthy = item.Status.ReadyReplicas >= desired && item.Status.UpdatedReplicas >= updated
+	case "DaemonSet":
+		healthy = item.Status.UpdatedNumberScheduled == item.Status.DesiredNumberScheduled && item.Status.NumberAvailable >= item.Status.DesiredNumberScheduled
+	}
+	if healthy {
+		return "healthy"
+	}
+	return "progressing"
+}
+
+func (item manifestHealthObject) conditionHealth(requireCurrentGeneration bool) string {
+	result := "progressing"
+	notReady := false
+	if requireCurrentGeneration {
+		result = "unknown"
+	}
+	for _, condition := range item.Status.Conditions {
+		if requireCurrentGeneration && (item.Metadata.Generation < 1 || max(condition.ObservedGeneration, item.Status.ObservedGeneration) < item.Metadata.Generation) {
+			continue
+		}
+		if condition.Status == "True" && (condition.Type == "Failed" || condition.Type == "Degraded" || condition.Type == "ReplicaFailure") {
+			return "degraded"
+		}
+		if condition.Type == "Progressing" && condition.Status == "False" && condition.Reason == "ProgressDeadlineExceeded" {
+			return "degraded"
+		}
+		if condition.Type == "Ready" || condition.Type == "Available" || condition.Type == "Complete" || condition.Type == "Established" {
+			if condition.Status == "True" {
+				result = "healthy"
+			} else {
+				notReady = true
+			}
+		}
+	}
+	if notReady {
+		return "progressing"
+	}
+	return result
+}

package/resource/manifest_health_test.go

@@ -0,0 +1,37 @@
+package resource
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestManifestHealth(t *testing.T) {
+	for _, test := range []struct{ name, object, want string }{
+		{"configuration", `{"apiVersion":"v1","kind":"ConfigMap"}`, "healthy"},
+		{"unknown CR", `{"apiVersion":"example.com/v1","kind":"Database","metadata":{"generation":2}}`, "unknown"},
+		{"custom kind cannot impersonate built-in", `{"apiVersion":"example.com/v1","kind":"ConfigMap"}`, "unknown"},
+		{"unobserved generation", `{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"generation":2},"spec":{"replicas":1},"status":{"observedGeneration":1,"replicas":1,"updatedReplicas":1,"availableReplicas":1,"conditions":[{"type":"Available","status":"True"}]}}`, "progressing"},
+		{"old replicas still available", `{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"generation":2},"spec":{"replicas":1},"status":{"observedGeneration":2,"replicas":2,"updatedReplicas":1,"availableReplicas":2}}`, "progressing"},
+		{"available but not updated", `{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"generation":2},"spec":{"replicas":1},"status":{"observedGeneration":2,"replicas":1,"updatedReplicas":0,"availableReplicas":1}}`, "progressing"},
+		{"deployment converged", `{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"generation":2},"spec":{"replicas":1},"status":{"observedGeneration":2,"replicas":1,"updatedReplicas":1,"availableReplicas":1}}`, "healthy"},
+		{"deployment failed after available", `{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"generation":2},"status":{"observedGeneration":2,"replicas":1,"updatedReplicas":1,"availableReplicas":1,"conditions":[{"type":"Available","status":"True"},{"type":"Progressing","status":"False","reason":"ProgressDeadlineExceeded"}]}}`, "degraded"},
+		{"stale custom ready", `{"apiVersion":"example.com/v1","kind":"Database","metadata":{"generation":2},"status":{"conditions":[{"type":"Ready","status":"True","observedGeneration":1}]}}`, "unknown"},
+		{"current custom ready", `{"apiVersion":"example.com/v1","kind":"Database","metadata":{"generation":2},"status":{"conditions":[{"type":"Ready","status":"True","observedGeneration":2}]}}`, "healthy"},
+		{"conflicting current ready conditions", `{"apiVersion":"example.com/v1","kind":"Database","metadata":{"generation":2},"status":{"observedGeneration":2,"conditions":[{"type":"Available","status":"True"},{"type":"Ready","status":"False"}]}}`, "progressing"},
+		{"current custom failure", `{"apiVersion":"example.com/v1","kind":"Database","metadata":{"generation":2},"status":{"observedGeneration":2,"conditions":[{"type":"Ready","status":"True"},{"type":"Failed","status":"True"}]}}`, "degraded"},
+		{"deleting object", `{"apiVersion":"v1","kind":"ConfigMap","metadata":{"deletionTimestamp":"2026-09-12T00:00:00Z"}}`, "degraded"},
+		{"pod not ready", `{"apiVersion":"v1","kind":"Pod","status":{"phase":"Running","conditions":[{"type":"Ready","status":"False"}]}}`, "progressing"},
+		{"statefulset partition", `{"apiVersion":"apps/v1","kind":"StatefulSet","metadata":{"generation":2},"spec":{"replicas":3,"updateStrategy":{"rollingUpdate":{"partition":2}}},"status":{"observedGeneration":2,"readyReplicas":3,"updatedReplicas":1}}`, "healthy"},
+		{"daemonset rolling", `{"apiVersion":"apps/v1","kind":"DaemonSet","metadata":{"generation":2},"status":{"observedGeneration":2,"desiredNumberScheduled":3,"updatedNumberScheduled":2,"numberAvailable":3}}`, "progressing"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var object map[string]any
+			if err := json.Unmarshal([]byte(test.object), &object); err != nil {
+				t.Fatal(err)
+			}
+			if got := ManifestHealth(object); got != test.want {
+				t.Fatalf("health = %s, want %s", got, test.want)
+			}
+		})
+	}
+}

package/resource/models.go

@@ -1097,6 +1097,10 @@ type CRDView struct {
 }
 
 type CustomResourceView struct {
+	UID            string            `json:"uid,omitempty"`
+	Generation     int64             `json:"generation,omitempty"`
+	DeletingAt     string            `json:"deletingAt,omitempty"`
+	Finalizers     []string          `json:"finalizers,omitempty"`
 	APIVersion     string            `json:"apiVersion,omitempty"`
 	Kind           string            `json:"kind"`
 	Name           string            `json:"name"`
@@ -1107,6 +1111,16 @@ type CustomResourceView struct {
 	AllowedActions []string          `json:"allowedActions,omitempty"`
 }
 
+// CustomResourceYAMLRequest is the Core/Agent custom-resource transport.
+// ExpectedUID fences deletion against replacement after a user viewed the object.
+type CustomResourceYAMLRequest struct {
+	Definition  CRDResourceDefinition `json:"definition"`
+	Namespace   string                `json:"namespace"`
+	Name        string                `json:"name,omitempty"`
+	Content     string                `json:"content,omitempty"`
+	ExpectedUID string                `json:"expectedUid,omitempty"`
+}
+
 type HelmReleaseView struct {
 	Name           string   `json:"name"`
 	Namespace      string   `json:"namespace"`

package/resource/runtime/argocd.go

@@ -0,0 +1,166 @@
+package runtime
+
+import (
+	"encoding/hex"
+	"fmt"
+	"net/url"
+	"path"
+	"reflect"
+	"regexp"
+	"slices"
+	"strings"
+
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+)
+
+const (
+	ArgoOwnerAnnotation     = "delivery.soha.io/argocd-owner"
+	ArgoOperationAnnotation = "delivery.soha.io/argocd-operation"
+)
+
+var argoApplications = schema.GroupVersionResource{Group: "argoproj.io", Version: "v1alpha1", Resource: "applications"}
+var argoImageOverride = regexp.MustCompile(`^(?:([A-Za-z0-9][A-Za-z0-9._:/-]*)=)?([A-Za-z0-9][A-Za-z0-9._:/-]*)@sha256:[a-f0-9]{64}$`)
+
+// ParseArgoImageOverride accepts Kustomize's image@digest and name=image@digest forms.
+func ParseArgoImageOverride(value string) (name, image string, err error) {
+	parts := argoImageOverride.FindStringSubmatch(value)
+	if len(parts) != 3 || strings.LastIndex(parts[2], ":") > strings.LastIndex(parts[2], "/") {
+		return "", "", fmt.Errorf("GitOps image overrides require an immutable image digest without a tag")
+	}
+	name = parts[1]
+	if name == "" {
+		name = parts[2]
+	}
+	_, image, found := strings.Cut(value, "=")
+	if !found {
+		image = value
+	}
+	return name, image, nil
+}
+
+func IsArgoApplication(object *unstructured.Unstructured) bool {
+	return object != nil && object.GetAPIVersion() == "argoproj.io/v1alpha1" && object.GetKind() == "Application"
+}
+
+// ValidateArgoApplication defines the supported, single-namespace GitOps path.
+// AppProject and repository credentials remain administrator-managed in Argo CD.
+func ValidateArgoApplication(object *unstructured.Unstructured) error {
+	if !IsArgoApplication(object) || object.GetNamespace() == "" || object.GetName() == "" {
+		return fmt.Errorf("GitOps requires a namespaced Argo CD Application")
+	}
+	if object.GetDeletionTimestamp() != nil || len(object.GetOwnerReferences()) != 0 || len(object.GetFinalizers()) != 0 {
+		return fmt.Errorf("GitOps Application must be an independent, non-deleting root without cascading deletion")
+	}
+	for key := range object.GetAnnotations() {
+		if strings.HasPrefix(key, "argocd.argoproj.io/") {
+			return fmt.Errorf("GitOps Application must not override controller behavior with annotations")
+		}
+	}
+	spec, _, err := unstructured.NestedMap(object.Object, "spec")
+	if err != nil {
+		return err
+	}
+	if err := argoAllowedFields(spec, "project", "source", "destination", "syncPolicy"); err != nil {
+		return err
+	}
+	if argoString(object, "spec", "project") == "" || argoString(object, "spec", "project") == "default" {
+		return fmt.Errorf("GitOps requires a dedicated restricted AppProject")
+	}
+	destination, _, err := unstructured.NestedStringMap(object.Object, "spec", "destination")
+	if err != nil || len(destination) != 2 || destination["namespace"] != object.GetNamespace() || destination["server"] != "https://kubernetes.default.svc" {
+		return fmt.Errorf("GitOps destination must be this cluster and the Application namespace")
+	}
+	source, _, err := unstructured.NestedMap(object.Object, "spec", "source")
+	if err != nil {
+		return err
+	}
+	if err := argoAllowedFields(source, "repoURL", "targetRevision", "path", "kustomize"); err != nil {
+		return err
+	}
+	revision := argoString(object, "spec", "source", "targetRevision")
+	if decoded, err := hex.DecodeString(revision); err != nil || len(decoded) != 20 && len(decoded) != 32 {
+		return fmt.Errorf("GitOps targetRevision must be a full immutable Git commit")
+	}
+	repository, err := url.Parse(argoString(object, "spec", "source", "repoURL"))
+	if err != nil || repository.Host == "" || repository.User != nil || repository.RawQuery != "" || repository.Fragment != "" || (repository.Scheme != "https" && repository.Scheme != "http" && repository.Scheme != "ssh") {
+		return fmt.Errorf("GitOps repository must be an HTTP(S) or SSH URL without embedded credentials")
+	}
+	directory := argoString(object, "spec", "source", "path")
+	if directory == "" || path.IsAbs(directory) || path.Clean(directory) != directory || directory == ".." || strings.HasPrefix(directory, "../") || strings.Contains(directory, "\\") {
+		return fmt.Errorf("GitOps path must stay within the pinned repository")
+	}
+	kustomize, _, err := unstructured.NestedMap(object.Object, "spec", "source", "kustomize")
+	if err != nil {
+		return err
+	}
+	if err := argoAllowedFields(kustomize, "images", "namespace"); err != nil {
+		return err
+	}
+	if argoString(object, "spec", "source", "kustomize", "namespace") != object.GetNamespace() {
+		return fmt.Errorf("GitOps Kustomize namespace must be explicitly fixed to the delivery namespace")
+	}
+	images, _, err := unstructured.NestedStringSlice(object.Object, "spec", "source", "kustomize", "images")
+	if err != nil || len(images) == 0 || len(images) > 16 {
+		return fmt.Errorf("GitOps requires 1 to 16 fixed Kustomize image overrides")
+	}
+	imageNames := map[string]bool{}
+	for _, image := range images {
+		name, _, err := ParseArgoImageOverride(image)
+		if err != nil {
+			return err
+		}
+		if imageNames[name] {
+			return fmt.Errorf("GitOps image overrides must use unique image names")
+		}
+		imageNames[name] = true
+	}
+	policy, _, err := unstructured.NestedMap(object.Object, "spec", "syncPolicy")
+	if err != nil {
+		return err
+	}
+	if err := argoAllowedFields(policy, "syncOptions"); err != nil {
+		return err
+	}
+	options, _, err := unstructured.NestedStringSlice(object.Object, "spec", "syncPolicy", "syncOptions")
+	if err != nil || !reflect.DeepEqual(options, []string{"FailOnSharedResource=true"}) {
+		return fmt.Errorf("GitOps requires manual sync and FailOnSharedResource=true")
+	}
+	return nil
+}
+
+func argoAllowedFields(object map[string]any, allowed ...string) error {
+	for key := range object {
+		if !slices.Contains(allowed, key) {
+			return fmt.Errorf("unsupported GitOps field %q", key)
+		}
+	}
+	return nil
+}
+
+func argoString(object *unstructured.Unstructured, fields ...string) string {
+	value, _, _ := unstructured.NestedString(object.Object, fields...)
+	return value
+}
+
+func argoOperationID(object *unstructured.Unstructured, fields ...string) string {
+	items, _, _ := unstructured.NestedSlice(object.Object, append(fields, "info")...)
+	for _, raw := range items {
+		item, _ := raw.(map[string]any)
+		if item["name"] == ArgoOperationAnnotation {
+			value, _ := item["value"].(string)
+			return value
+		}
+	}
+	return ""
+}
+
+var argoResourceTypes = map[string]schema.GroupVersionResource{
+	"apps/Deployment":        {Group: "apps", Version: "v1", Resource: "deployments"},
+	"apps/StatefulSet":       {Group: "apps", Version: "v1", Resource: "statefulsets"},
+	"/Service":               {Version: "v1", Resource: "services"},
+	"/ConfigMap":             {Version: "v1", Resource: "configmaps"},
+	"/Secret":                {Version: "v1", Resource: "secrets"},
+	"/ServiceAccount":        {Version: "v1", Resource: "serviceaccounts"},
+	"/PersistentVolumeClaim": {Version: "v1", Resource: "persistentvolumeclaims"},
+}

package/resource/runtime/argocd_integration_test.go

@@ -0,0 +1,142 @@
+package runtime
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/url"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/apimachinery/pkg/util/wait"
+	"k8s.io/client-go/dynamic"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/tools/clientcmd"
+)
+
+func TestArgoCDWithKubernetes(t *testing.T) {
+	kubeconfig := os.Getenv("SOHA_ARGOCD_TEST_KUBECONFIG")
+	if kubeconfig == "" {
+		t.Skip("set explicit loopback kubeconfig and SOHA_ARGOCD_TEST_STATE for the private GitOps fixture")
+	}
+	config, err := clientcmd.BuildConfigFromFlags("", kubeconfig)
+	operatorRequire(t, err)
+	endpoint, err := url.Parse(config.Host)
+	if err != nil || endpoint.Hostname() != "127.0.0.1" {
+		t.Fatal("only the loopback fixture cluster is supported")
+	}
+	config.Timeout = 15 * time.Second
+	client, err := dynamic.NewForConfig(config)
+	operatorRequire(t, err)
+	kube, err := kubernetes.NewForConfig(config)
+	operatorRequire(t, err)
+	data, err := os.ReadFile(os.Getenv("SOHA_ARGOCD_TEST_STATE"))
+	operatorRequire(t, err)
+	var state map[string]json.RawMessage
+	operatorRequire(t, json.Unmarshal(data, &state))
+	value := func(key string) string {
+		var value string
+		operatorRequire(t, json.Unmarshal(state[key], &value))
+		return value
+	}
+	namespace, name := "soha-workflow-r6-gitops", "r6-gitops-runtime"
+	app := &unstructured.Unstructured{Object: map[string]any{"apiVersion": "argoproj.io/v1alpha1", "kind": "Application", "metadata": map[string]any{"name": name, "namespace": namespace}, "spec": map[string]any{"project": "r6-gitops", "source": map[string]any{"repoURL": value("repositoryURL"), "path": ".", "targetRevision": value("v1"), "kustomize": map[string]any{"namespace": namespace, "images": []any{"app=" + value("image")}}}, "destination": map[string]any{"server": "https://kubernetes.default.svc", "namespace": namespace}, "syncPolicy": map[string]any{"syncOptions": []any{"FailOnSharedResource=true"}}}}}
+	children := func(version string) []*unstructured.Unstructured {
+		var documents map[string][]*unstructured.Unstructured
+		operatorRequire(t, json.Unmarshal(state["documents"], &documents))
+		if len(documents[version]) != 2 {
+			t.Fatal("frozen fixture requires two source-derived child documents")
+		}
+		return documents[version]
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+	resources := client.Resource(argoApplications).Namespace(namespace)
+	options := metav1.PatchOptions{FieldManager: "soha-r6-gitops-integration"}
+	id := uuid.NewString()
+	preflight := options
+	preflight.DryRun = []string{metav1.DryRunAll}
+	_, err = ApplyArgoApplication(ctx, client, app, children("v1"), preflight, id+":preflight")
+	operatorRequire(t, err)
+	if _, err = resources.Get(ctx, name, metav1.GetOptions{}); !apierrors.IsNotFound(err) {
+		t.Fatal("preflight created an Application or fixture already exists")
+	}
+	t.Cleanup(func() {
+		if t.Failed() {
+			t.Log("failed fixture retained for diagnosis in its isolated namespace")
+			return
+		}
+		cleanup, stop := context.WithTimeout(context.Background(), 15*time.Second)
+		defer stop()
+		_ = resources.Delete(cleanup, name, metav1.DeleteOptions{})
+		for _, gvr := range []schema.GroupVersionResource{{Group: "apps", Version: "v1", Resource: "deployments"}, {Version: "v1", Resource: "services"}} {
+			_ = client.Resource(gvr).Namespace(namespace).Delete(cleanup, "r6-gitops-http", metav1.DeleteOptions{})
+		}
+	})
+	apply := func(version, operation string) {
+		operatorRequire(t, unstructured.SetNestedField(app.Object, value(version), "spec", "source", "targetRevision"))
+		live, err := ApplyArgoApplication(ctx, client, app, children(version), options, id+operation)
+		if err != nil {
+			var status any
+			if live != nil {
+				status = live.Object["status"]
+			}
+			t.Fatalf("sync %s: %v; status=%v", version, err, status)
+		}
+		err = wait.PollUntilContextTimeout(ctx, time.Second, 45*time.Second, true, func(ctx context.Context) (bool, error) {
+			live, err := resources.Get(ctx, name, metav1.GetOptions{})
+			if err != nil {
+				return false, err
+			}
+			observed, err := ObserveArgoApplication(ctx, client, app, live, children(version), options.FieldManager)
+			if err != nil {
+				return false, err
+			}
+			return observed.Health == "healthy" && observed.OperationID == id+operation && observed.Revision == value(version), nil
+		})
+		operatorRequire(t, err)
+		body, err := kube.CoreV1().RESTClient().Get().Namespace(namespace).Resource("services").Name("r6-gitops-http:8080").SubResource("proxy").DoRaw(ctx)
+		if err != nil || strings.TrimSpace(string(body)) != "gitops-"+version {
+			t.Fatalf("actual HTTP %s: %q %v", version, body, err)
+		}
+		t.Logf("Argo operation %s applied commit %s with owned, healthy resources and actual HTTP %s", operation, value(version), version)
+	}
+	apply("v1", ":deploy")
+	apply("v2", ":upgrade")
+	apply("v1", ":rollback")
+	operatorRequire(t, unstructured.SetNestedField(app.Object, value("hold"), "spec", "source", "targetRevision"))
+	stopping, stop := context.WithCancel(ctx)
+	observedHold := make(chan error, 1)
+	go func() {
+		err := wait.PollUntilContextTimeout(ctx, time.Second, 45*time.Second, true, func(ctx context.Context) (bool, error) {
+			live, err := resources.Get(ctx, name, metav1.GetOptions{})
+			if err != nil {
+				return false, err
+			}
+			return argoOperationID(live, "status", "operationState", "operation") == id+":cancel" && argoString(live, "status", "operationState", "phase") == "Running", nil
+		})
+		observedHold <- err
+		stop()
+	}()
+	live, err := ApplyArgoApplication(stopping, client, app, children("hold"), options, id+":cancel")
+	operatorRequire(t, <-observedHold)
+	if !errors.Is(err, context.Canceled) || live == nil || argoOperationActive(live) {
+		t.Fatalf("cancel was not confirmed: %v", err)
+	}
+	t.Log("controller confirmed cancellation; restoring through a new operation")
+	apply("v1", ":restore")
+	// The direct writer cannot adopt a resource managed by Argo CD, even with force.
+	deployment, err := client.Resource(schema.GroupVersionResource{Group: "apps", Version: "v1", Resource: "deployments"}).Namespace(namespace).Get(ctx, "r6-gitops-http", metav1.GetOptions{})
+	operatorRequire(t, err)
+	if ValidateDirectManifestOwner(deployment) == nil {
+		t.Fatal("direct writer accepted Argo CD-owned resource")
+	}
+	t.Logf("real Argo CD GitOps lifecycle passed for %s/%s", namespace, name)
+}