@opensoha/contracts 0.1.25 → 0.1.27

package/go.mod

@@ -1,6 +1,6 @@
 module github.com/opensoha/soha-contracts
 
-go 1.27.2
+go 1.27.3
 
 require (
 	github.com/google/uuid v1.6.0
@@ -12,6 +12,7 @@ require (
 	k8s.io/apimachinery v0.37.1
 	k8s.io/cli-runtime v0.37.1
 	k8s.io/client-go v0.37.1
+	k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3
 	sigs.k8s.io/yaml v1.6.0
 )
 
@@ -121,7 +122,6 @@ require (
 	k8s.io/klog/v2 v2.140.0 // indirect
 	k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad // indirect
 	k8s.io/kubectl v0.37.1 // indirect
-	k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3 // indirect
 	oras.land/oras-go/v2 v2.6.2 // indirect
 	sigs.k8s.io/controller-runtime v0.25.2 // indirect
 	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect

package/helmrelease/delivery.go

@@ -241,6 +241,9 @@ func (r chartBudgetReader) Read(p []byte) (int, error) {
 // Prepare accepts an unfinished render; Execute additionally verifies its digests.
 func ValidateTaskIdentity(input sohaapi.HelmExecutionTaskPayload) error {
 	s := input.Snapshot
+	if IsInitialization(s) && (s.Operation != sohaapi.HelmDeliverySnapshotOperationInstall || s.ExpectedRevision != 0 || s.RollbackRevision != 0 || s.Migration.Blocked || !s.Migration.RequiresApproval || s.Migration.FromVersion != 0 || s.TemplateInputs == nil || s.TemplateInputs.TemplateVersion != s.Migration.ToVersion) {
+		return errors.New("initialization requires an approved create-only first deployment snapshot")
+	}
 	for _, value := range []string{s.DeliveryPlanID, s.TargetID, s.ApplicationID, s.ApplicationEnvironmentID, s.ServiceID, s.ClusterID} {
 		if strings.TrimSpace(value) == "" || len(value) > 512 {
 			return errors.New("helm task identity is incomplete")
@@ -249,7 +252,7 @@ func ValidateTaskIdentity(input sohaapi.HelmExecutionTaskPayload) error {
 	if !input.Action.Valid() || !helmName.MatchString(s.Namespace) || len(s.Namespace) > 63 || !helmName.MatchString(s.ReleaseName) || len(s.ReleaseName) > 53 || s.ExpectedRevision < 0 || s.RollbackRevision < 0 || s.TimeoutSeconds < 0 || s.TimeoutSeconds > 3600 {
 		return errors.New("helm task action, namespace, revision or timeout is invalid")
 	}
-	if len(s.Resources) > 300 {
+	if len(s.Resources) > 300 || len(input.InitializationResources) > 300 {
 		return errors.New("helm task exceeds 300 resources")
 	}
 	if input.Prepared != nil {

package/helmrelease/initialization.go

@@ -0,0 +1,10 @@
+package helmrelease
+
+import "github.com/opensoha/soha-contracts/gen/go/sohaapi"
+
+const InitializationCapability = "helm.initialize.v1"
+const InitializationProviderPrefix = "helm_initialize_v1."
+
+func IsInitialization(snapshot sohaapi.HelmDeliverySnapshot) bool {
+	return snapshot.Migration != nil && snapshot.Migration.Initialization
+}

package/helmrelease/runtime/delivery.go

@@ -28,6 +28,7 @@ import (
 	"k8s.io/apimachinery/pkg/api/meta"
 	"k8s.io/apimachinery/pkg/apis/meta/v1/unstructured"
 	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/types"
 	"k8s.io/client-go/dynamic"
 )
 
@@ -39,6 +40,13 @@ func Prepare(ctx context.Context, cfg *action.Configuration, input sohaapi.HelmE
 	if err != nil {
 		return input, err
 	}
+	if helmrelease.IsInitialization(input.Snapshot) && helmDeliveryAlreadyApplied(current, input.Snapshot) {
+		if err := validateHelmPrepared(cfg, input); err != nil {
+			return input, err
+		}
+		_, err := observeInitializedHelm(ctx, cfg, input, current)
+		return input, err
+	}
 	input.Snapshot.ExpectedRevision = 0
 	input.Snapshot.Operation = sohaapi.HelmDeliverySnapshotOperationInstall
 	if current != nil {
@@ -105,17 +113,22 @@ func Execute(ctx context.Context, cfg *action.Configuration, input sohaapi.HelmE
 		return result, err
 	}
 	if input.Action == sohaapi.Observe {
-		return observeHelmDelivery(ctx, cfg, input.Snapshot, current)
+		return observeInitializedHelm(ctx, cfg, input, current)
 	}
 	if err := validateHelmPrepared(cfg, input); err != nil {
 		return result, err
 	}
 	if helmDeliveryAlreadyApplied(current, input.Snapshot) {
-		return observeHelmDelivery(ctx, cfg, input.Snapshot, current)
+		return observeInitializedHelm(ctx, cfg, input, current)
 	}
 	if err := helmDeliveryRevisionMatches(current, input.Snapshot); err != nil {
 		return result, err
 	}
+	if helmrelease.IsInitialization(input.Snapshot) {
+		if err := requireInitialHelmResourcesAbsent(cfg, input); err != nil {
+			return result, err
+		}
+	}
 	if input.Action == sohaapi.Preflight {
 		result.Ready, result.Status, result.Revision = true, "preflighted", input.Snapshot.ExpectedRevision
 		return result, nil
@@ -136,10 +149,21 @@ func Execute(ctx context.Context, cfg *action.Configuration, input sohaapi.HelmE
 	// Helm's RunWithContext may return while its mutation goroutine is still
 	// running. Once mutation begins, native Timeout bounds it; cancellation is
 	// acknowledged only after Run has returned and the release is inspected.
+	var initialization *initializingHelmClient
+	if helmrelease.IsInitialization(input.Snapshot) {
+		initialization = &initializingHelmClient{Interface: cfg.KubeClient, created: make(map[string]types.UID)}
+		cfg = helmConfigurationWithClient(cfg, initialization)
+	}
 	_, runErr := runHelmDeliveryAction(context.Background(), cfg, input, ch, false)
 	current, err = currentHelmDelivery(cfg, input.Snapshot.ReleaseName, 0)
 	if err == nil && current != nil {
 		result, err = observeHelmDelivery(ctx, cfg, input.Snapshot, current)
+		if err == nil && initialization != nil {
+			err = initialization.validateCreated(result)
+		}
+	}
+	if err != nil || runErr != nil {
+		result.Ready = false
 	}
 	if runErr != nil {
 		return result, fmt.Errorf("%w: Helm execution failed; inspect the recorded revision and resource state", ErrUnavailable)
@@ -150,17 +174,23 @@ func Execute(ctx context.Context, cfg *action.Configuration, input sohaapi.HelmE
 	return result, err
 }
 
+// Build a per-invocation configuration without copying Helm's internal mutex or
+// replacing the caller's client. Dry-run template functions also remain local.
+func helmConfigurationWithClient(original *action.Configuration, client kube.Interface) *action.Configuration {
+	cfg := &action.Configuration{
+		RESTClientGetter: original.RESTClientGetter, Releases: original.Releases,
+		KubeClient: client, RegistryClient: original.RegistryClient,
+		Capabilities: original.Capabilities, HookOutputFunc: original.HookOutputFunc,
+		CustomTemplateFuncs: maps.Clone(original.CustomTemplateFuncs),
+	}
+	cfg.SetLogger(original.Logger().Handler())
+	return cfg
+}
+
 func runHelmDeliveryAction(ctx context.Context, cfg *action.Configuration, input sohaapi.HelmExecutionTaskPayload, ch chart.Charter, dryRun bool) (*helmreleasev1.Release, error) {
 	if dryRun {
 		// Discover real cluster capabilities, but keep template lookup disabled.
-		original := cfg
-		cfg = &action.Configuration{
-			RESTClientGetter: original.RESTClientGetter, Releases: original.Releases,
-			KubeClient: original.KubeClient, RegistryClient: original.RegistryClient,
-			Capabilities: original.Capabilities, HookOutputFunc: original.HookOutputFunc,
-			CustomTemplateFuncs: maps.Clone(original.CustomTemplateFuncs),
-		}
-		cfg.SetLogger(original.Logger().Handler())
+		cfg = helmConfigurationWithClient(cfg, cfg.KubeClient)
 		if cfg.CustomTemplateFuncs == nil {
 			cfg.CustomTemplateFuncs = make(map[string]any)
 		}

package/helmrelease/runtime/delivery_test.go

@@ -39,6 +39,7 @@ type observedHelmKubeClient struct {
 	missing   bool
 	namespace string
 	reads     int
+	uid       string
 }
 
 func (c *observedHelmKubeClient) Build(io.Reader, bool) (kube.ResourceList, error) {
@@ -49,6 +50,9 @@ func (c *observedHelmKubeClient) Build(io.Reader, bool) (kube.ResourceList, erro
 			return &http.Response{StatusCode: http.StatusNotFound, Header: http.Header{"Content-Type": {"application/json"}}, Body: io.NopCloser(strings.NewReader(`{"apiVersion":"v1","kind":"Status","status":"Failure","reason":"NotFound","code":404}`))}, nil
 		}
 		body := object
+		if c.uid != "" {
+			body = strings.Replace(body, `"name":"app"`, `"name":"app","uid":"`+c.uid+`"`, 1)
+		}
 		if c.deleting {
 			body = strings.Replace(body, `"name":"app"`, `"name":"app","deletionTimestamp":"2026-09-12T00:00:00Z"`, 1)
 		}

package/helmrelease/runtime/initialization.go

@@ -0,0 +1,186 @@
+package runtime
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha-contracts/helmrelease"
+	"helm.sh/helm/v4/pkg/action"
+	"helm.sh/helm/v4/pkg/kube"
+	helmreleasev1 "helm.sh/helm/v4/pkg/release/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	kuberesource "k8s.io/cli-runtime/pkg/resource"
+)
+
+func requireInitialHelmResourcesAbsent(cfg *action.Configuration, input sohaapi.HelmExecutionTaskPayload) error {
+	if input.Snapshot.Operation != sohaapi.HelmDeliverySnapshotOperationInstall || input.Snapshot.ExpectedRevision != 0 || input.Snapshot.RollbackRevision != 0 || input.Prepared == nil {
+		return fmt.Errorf("%w: initialization requires a new install", ErrConflict)
+	}
+	for _, document := range append([]string{input.Prepared.Manifest}, input.Prepared.Hooks...) {
+		resources, err := cfg.KubeClient.Build(strings.NewReader(document), false)
+		if err != nil {
+			return err
+		}
+		if err := requireHelmResourcesAbsent(resources); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func requireHelmResourcesAbsent(resources kube.ResourceList) error {
+	for _, resource := range resources {
+		err := resource.Get()
+		if !apierrors.IsNotFound(err) {
+			return fmt.Errorf("%w: initialization resource exists or its absence cannot be verified", ErrConflict)
+		}
+	}
+	return nil
+}
+
+// Helm's ordinary install may adopt correctly labelled existing objects. This
+// client refuses that update path and forces native POSTs, including for hooks.
+// Hook cleanup can delete only UIDs created by this exact native invocation.
+type initializingHelmClient struct {
+	kube.Interface
+	mu      sync.Mutex
+	created map[string]types.UID
+	hooks   map[string]bool
+}
+
+func (c *initializingHelmClient) Create(resources kube.ResourceList, options ...kube.ClientCreateOption) (*kube.Result, error) {
+	if err := requireHelmResourcesAbsent(resources); err != nil {
+		return nil, err
+	}
+	result, err := c.Interface.Create(resources, append(options, kube.ClientCreateOptionServerSideApply(false, false))...)
+	if result != nil {
+		c.mu.Lock()
+		defer c.mu.Unlock()
+		for _, resource := range result.Created {
+			object, accessErr := meta.Accessor(resource.Object)
+			if accessErr == nil && object.GetUID() != "" {
+				key := initialHelmResourceKey(resource)
+				c.created[key] = object.GetUID()
+				if object.GetAnnotations()["helm.sh/hook"] != "" {
+					if c.hooks == nil {
+						c.hooks = make(map[string]bool)
+					}
+					c.hooks[key] = true
+				}
+			}
+		}
+	}
+	return result, err
+}
+
+func (c *initializingHelmClient) Update(kube.ResourceList, kube.ResourceList, ...kube.ClientUpdateOption) (*kube.Result, error) {
+	return nil, fmt.Errorf("%w: initialization cannot update or adopt existing resources", ErrConflict)
+}
+
+func (c *initializingHelmClient) Delete(resources kube.ResourceList, policy metav1.DeletionPropagation) (*kube.Result, []error) {
+	result := &kube.Result{}
+	for _, resource := range resources {
+		if err := c.deleteCreatedHook(resource, policy); err != nil {
+			return result, []error{err}
+		}
+		result.Deleted = append(result.Deleted, resource)
+	}
+	return result, nil
+}
+
+func (c *initializingHelmClient) deleteCreatedHook(resource *kuberesource.Info, policy metav1.DeletionPropagation) error {
+	if err := resource.Get(); err != nil {
+		if apierrors.IsNotFound(err) {
+			return nil
+		}
+		return fmt.Errorf("%w: hook identity cannot be verified", ErrConflict)
+	}
+	object, err := meta.Accessor(resource.Object)
+	if err != nil {
+		return err
+	}
+	c.mu.Lock()
+	uid := c.created[initialHelmResourceKey(resource)]
+	hook := c.hooks[initialHelmResourceKey(resource)]
+	c.mu.Unlock()
+	if !hook || uid == "" || object.GetUID() != uid || object.GetResourceVersion() == "" {
+		return fmt.Errorf("%w: initialization cannot delete a pre-existing or replaced hook", ErrConflict)
+	}
+	version := object.GetResourceVersion()
+	_, err = kuberesource.NewHelper(resource.Client, resource.Mapping).DeleteWithOptions(resource.Namespace, resource.Name, &metav1.DeleteOptions{PropagationPolicy: &policy, Preconditions: &metav1.Preconditions{UID: &uid, ResourceVersion: &version}})
+	return err
+}
+
+func initialInventoryKey(item sohaapi.ManifestResourceInventory) string {
+	group := ""
+	if parts := strings.SplitN(item.APIVersion, "/", 2); len(parts) == 2 {
+		group = parts[0]
+	}
+	return group + "/" + item.Kind + "/" + item.Namespace + "/" + item.Name
+}
+
+// ValidateInitializationResources binds a fresh observation to the durable
+// original apply receipt, never to UIDs first read during recovery.
+func ValidateInitializationResources(observed, original []sohaapi.ManifestResourceInventory) error {
+	if len(original) == 0 || len(observed) != len(original) {
+		return fmt.Errorf("%w: initialization creation receipt is missing or incomplete", ErrConflict)
+	}
+	uids := make(map[string]string, len(original))
+	for _, item := range original {
+		key := initialInventoryKey(item)
+		if item.UID == "" || uids[key] != "" {
+			return fmt.Errorf("%w: invalid initialization receipt", ErrConflict)
+		}
+		uids[key] = item.UID
+	}
+	for _, item := range observed {
+		key := initialInventoryKey(item)
+		if item.UID == "" || uids[key] != item.UID {
+			return fmt.Errorf("%w: initialized resource was replaced", ErrConflict)
+		}
+		delete(uids, key)
+	}
+	return nil
+}
+
+func (c *initializingHelmClient) validateCreated(result sohaapi.HelmExecutionTaskResult) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if len(result.Resources) == 0 {
+		return fmt.Errorf("%w: initialization has no observable resource receipt", ErrConflict)
+	}
+	for _, item := range result.Resources {
+		if item.UID == "" || string(c.created[initialInventoryKey(item)]) != item.UID {
+			return fmt.Errorf("%w: initialized resource creation UID cannot be verified", ErrConflict)
+		}
+	}
+	return nil
+}
+
+func observeInitializedHelm(ctx context.Context, cfg *action.Configuration, input sohaapi.HelmExecutionTaskPayload, current *helmreleasev1.Release) (sohaapi.HelmExecutionTaskResult, error) {
+	result, err := observeHelmDelivery(ctx, cfg, input.Snapshot, current)
+	if err == nil && helmrelease.IsInitialization(input.Snapshot) {
+		err = ValidateInitializationResources(result.Resources, input.InitializationResources)
+	}
+	if err != nil {
+		result.Ready = false
+	}
+	return result, err
+}
+
+func initialHelmResourceKey(resource *kuberesource.Info) string {
+	return resource.Mapping.GroupVersionKind.Group + "/" + resource.Mapping.GroupVersionKind.Kind + "/" + resource.Namespace + "/" + resource.Name
+}
+
+func (c *initializingHelmClient) GetWaiterWithOptions(strategy kube.WaitStrategy, options ...kube.WaitOption) (kube.Waiter, error) {
+	if client, ok := c.Interface.(kube.InterfaceWaitOptions); ok {
+		return client.GetWaiterWithOptions(strategy, options...)
+	}
+	return c.GetWaiter(strategy)
+}

package/helmrelease/runtime/initialization_test.go

@@ -0,0 +1,203 @@
+package runtime
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/opensoha/soha-contracts/gen/go/sohaapi"
+	"github.com/opensoha/soha-contracts/helmrelease"
+	"helm.sh/helm/v4/pkg/action"
+	"helm.sh/helm/v4/pkg/chart/common"
+	"helm.sh/helm/v4/pkg/kube"
+	releasecommon "helm.sh/helm/v4/pkg/release/common"
+	releasev1 "helm.sh/helm/v4/pkg/release/v1"
+	"helm.sh/helm/v4/pkg/storage"
+	"helm.sh/helm/v4/pkg/storage/driver"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	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/types"
+	kuberesource "k8s.io/cli-runtime/pkg/resource"
+	restfake "k8s.io/client-go/rest/fake"
+)
+
+func TestHelmInitializationLeavesCallerConfigurationUntouched(t *testing.T) {
+	client := &observedHelmKubeClient{}
+	original := &action.Configuration{KubeClient: client, Releases: storage.Init(driver.NewMemory()), CustomTemplateFuncs: map[string]any{"caller": "preserved"}}
+	protected := &initializingHelmClient{Interface: client, created: make(map[string]types.UID)}
+	local := helmConfigurationWithClient(original, protected)
+	local.CustomTemplateFuncs["caller"] = "changed"
+	if original.KubeClient != client || original.CustomTemplateFuncs["caller"] != "preserved" {
+		t.Fatal("initialization changed the caller's Kubernetes client or template functions")
+	}
+	if local.KubeClient != protected || local.Releases != original.Releases {
+		t.Fatal("per-invocation configuration lost the protected client or release storage")
+	}
+}
+
+func TestHelmInitializationObserveAndPrepareRecoveryRequireOriginalReceipt(t *testing.T) {
+	client := &observedHelmKubeClient{missing: true}
+	cfg := &action.Configuration{KubeClient: client, Releases: storage.Init(driver.NewMemory()), Capabilities: common.DefaultCapabilities}
+	archive := helmSourceTestArchive(t)
+	input := sohaapi.HelmExecutionTaskPayload{Action: sohaapi.Preflight, Snapshot: sohaapi.HelmDeliverySnapshot{DeliveryPlanID: "first", TargetID: "target", ApplicationID: "app", ApplicationEnvironmentID: "dev", ServiceID: "svc", ClusterID: "cluster", Namespace: "dev", ReleaseName: "app", ChartDigest: helmrelease.SHA256(archive)}, Prepared: &sohaapi.HelmPreparedRelease{ChartArchive: base64.StdEncoding.EncodeToString(archive)}}
+	input, err := Prepare(context.Background(), cfg, input)
+	if err != nil {
+		t.Fatal(err)
+	}
+	input.Snapshot.TemplateInputs = &sohaapi.TemplateVersionReference{TemplateID: "template", TemplateVersion: 3, TemplateDigest: "immutable"}
+	input.Snapshot.Migration = &sohaapi.TemplateMigrationAssessment{Initialization: true, FromVersion: 0, ToVersion: 3, RequiresApproval: true}
+	release := &releasev1.Release{Name: "app", Namespace: "dev", Version: 1, Manifest: input.Prepared.Manifest, Labels: helmDeliveryLabels(input.Snapshot), Info: &releasev1.Info{Status: releasecommon.StatusDeployed}}
+	if err := cfg.Releases.Create(release); err != nil {
+		t.Fatal(err)
+	}
+	client.missing = false
+	client.uid = "created"
+	for _, mode := range []string{"missing", "original", "replaced"} {
+		t.Run(mode, func(t *testing.T) {
+			candidate := input
+			if mode != "missing" {
+				candidate.InitializationResources = []sohaapi.ManifestResourceInventory{{APIVersion: "v1", Kind: "ConfigMap", Namespace: "dev", Name: "app", UID: "created"}}
+			}
+			if mode == "replaced" {
+				client.uid = "replacement"
+			} else {
+				client.uid = "created"
+			}
+			candidate.Action = sohaapi.Observe
+			result, err := Execute(context.Background(), cfg, candidate)
+			if (err == nil) != (mode == "original") || result.Ready != (mode == "original") {
+				t.Fatalf("observation %s: %+v %v", mode, result, err)
+			}
+			candidate.Action = sohaapi.Preflight
+			prepared, err := Prepare(context.Background(), cfg, candidate)
+			if (err == nil) != (mode == "original") {
+				t.Fatalf("recovery %s: %v", mode, err)
+			}
+			if err == nil && (prepared.Snapshot.ExpectedRevision != 0 || prepared.Snapshot.Operation != sohaapi.HelmDeliverySnapshotOperationInstall) {
+				t.Fatal("recovery turned initialization into upgrade")
+			}
+		})
+	}
+}
+
+func TestHelmInitializationReceiptRejectsMissingReplacedAndDuplicateUID(t *testing.T) {
+	original := []sohaapi.ManifestResourceInventory{{APIVersion: "v1", Kind: "ConfigMap", Namespace: "dev", Name: "app", UID: "created"}}
+	if err := ValidateInitializationResources(original, original); err != nil {
+		t.Fatal(err)
+	}
+	for _, mode := range []string{"missing", "replaced", "empty", "duplicate"} {
+		observed, receipt := slices.Clone(original), slices.Clone(original)
+		switch mode {
+		case "missing":
+			receipt = nil
+		case "replaced":
+			observed[0].UID = "replacement"
+		case "empty":
+			receipt[0].UID = ""
+		case "duplicate":
+			receipt = append(receipt, receipt[0])
+			observed = append(observed, observed[0])
+		}
+		if ValidateInitializationResources(observed, receipt) == nil {
+			t.Fatalf("accepted %s receipt", mode)
+		}
+	}
+	guard := &initializingHelmClient{created: map[string]types.UID{"/ConfigMap/dev/app": "created"}}
+	if err := guard.validateCreated(sohaapi.HelmExecutionTaskResult{Resources: original}); err != nil {
+		t.Fatal(err)
+	}
+	original[0].UID = "replacement"
+	if guard.validateCreated(sohaapi.HelmExecutionTaskResult{Resources: original}) == nil {
+		t.Fatal("replacement registered as original creation")
+	}
+}
+
+func TestHelmInitializationPreflightRequiresAbsentResources(t *testing.T) {
+	input := sohaapi.HelmExecutionTaskPayload{Snapshot: sohaapi.HelmDeliverySnapshot{Operation: sohaapi.HelmDeliverySnapshotOperationInstall}, Prepared: &sohaapi.HelmPreparedRelease{Manifest: "manifest"}}
+	for _, missing := range []bool{false, true} {
+		cfg := &action.Configuration{KubeClient: &observedHelmKubeClient{missing: missing}}
+		err := requireInitialHelmResourcesAbsent(cfg, input)
+		if (err == nil) != missing {
+			t.Fatalf("absence=%v: %v", missing, err)
+		}
+	}
+	input.Snapshot.ExpectedRevision = 1
+	if requireInitialHelmResourcesAbsent(&action.Configuration{}, input) == nil {
+		t.Fatal("existing revision accepted as initialization")
+	}
+}
+
+func TestHelmInitializationForcesAtomicCreateAndUIDBoundHookCleanup(t *testing.T) {
+	for _, race := range []bool{false, true} {
+		t.Run(map[bool]string{false: "new", true: "create-race"}[race], func(t *testing.T) {
+			uid := ""
+			methods := []string{}
+			object := `{"apiVersion":"v1","kind":"ConfigMap","metadata":{"name":"app","namespace":"dev","uid":"created","resourceVersion":"7","annotations":{"helm.sh/hook":"post-install"}}}`
+			client := &restfake.RESTClient{GroupVersion: schema.GroupVersion{Version: "v1"}, NegotiatedSerializer: kuberesource.UnstructuredPlusDefaultContentConfig().NegotiatedSerializer, Client: restfake.CreateHTTPClient(func(req *http.Request) (*http.Response, error) {
+				methods = append(methods, req.Method)
+				code, body := http.StatusOK, object
+				switch req.Method {
+				case http.MethodGet:
+					if uid == "" {
+						code, body = http.StatusNotFound, `{"apiVersion":"v1","kind":"Status","status":"Failure","reason":"NotFound","code":404}`
+					} else {
+						body = strings.ReplaceAll(object, "created", uid)
+					}
+				case http.MethodPost:
+					if race {
+						uid = "foreign"
+						code, body = http.StatusConflict, `{"apiVersion":"v1","kind":"Status","status":"Failure","reason":"AlreadyExists","code":409}`
+					} else {
+						uid = "created"
+					}
+				case http.MethodDelete:
+					var options metav1.DeleteOptions
+					if err := json.NewDecoder(req.Body).Decode(&options); err != nil || options.Preconditions == nil || options.Preconditions.UID == nil || *options.Preconditions.UID != "created" || options.Preconditions.ResourceVersion == nil || *options.Preconditions.ResourceVersion != "7" {
+						t.Fatal("hook cleanup lost UID/resourceVersion preconditions", err)
+					}
+					uid = ""
+				default:
+					t.Fatalf("initialization issued unsafe HTTP %s", req.Method)
+				}
+				return &http.Response{StatusCode: code, Header: http.Header{"Content-Type": {"application/json"}}, Body: io.NopCloser(strings.NewReader(body))}, nil
+			})}
+			var desired unstructured.Unstructured
+			if err := json.Unmarshal([]byte(object), &desired); err != nil {
+				t.Fatal(err)
+			}
+			desired.SetUID("")
+			desired.SetResourceVersion("")
+			resources := kube.ResourceList{&kuberesource.Info{Client: client, Namespace: "dev", Name: "app", Object: &desired, Mapping: &meta.RESTMapping{Resource: schema.GroupVersionResource{Version: "v1", Resource: "configmaps"}, GroupVersionKind: schema.GroupVersionKind{Version: "v1", Kind: "ConfigMap"}, Scope: meta.RESTScopeNamespace}}}
+			native := &kube.Client{}
+			native.SetLogger(slog.NewTextHandler(io.Discard, nil))
+			guard := &initializingHelmClient{Interface: native, created: map[string]types.UID{}}
+			_, err := guard.Create(resources, kube.ClientCreateOptionServerSideApply(true, true))
+			if race && !apierrors.IsAlreadyExists(err) || !race && err != nil {
+				t.Fatalf("atomic create race=%v: %v", race, err)
+			}
+			if !reflect.DeepEqual(methods, []string{http.MethodGet, http.MethodGet, http.MethodPost}) {
+				t.Fatalf("native initialization did not use GET/POST only: %v", methods)
+			}
+			if _, err := guard.Update(nil, resources); err == nil {
+				t.Fatal("initialization adopted existing resources through Update")
+			}
+			_, errs := guard.Delete(resources, metav1.DeletePropagationBackground)
+			if (len(errs) == 0) == race {
+				t.Fatalf("hook ownership race=%v: %v", race, errs)
+			}
+			if race && methods[len(methods)-1] != http.MethodGet || !race && methods[len(methods)-1] != http.MethodDelete {
+				t.Fatalf("hook deletion ignored ownership: %v", methods)
+			}
+		})
+	}
+}

package/network/README.md

@@ -57,6 +57,11 @@ for authorization, routing, firewall configuration or accounting.
   reply attribute and require NAS accounting to echo it as `sessionId` when
   available. Session commands repeat the bound `subjectId` and `deviceId` so
   the adapter can target CoA/Disconnect without querying management APIs.
+- Capability `nas-session-accounting-v1` enables the optional command target
+  `stationId`, `accountingSessionId` and `nasPortId`. For EAP-TLS, station identity
+  comes from saved authorization/accounting, never the opaque Soha device ID.
+  A runtime that cannot receive the required target binding must report
+  unsupported rather than send a command to a guessed station.
 - If a requested CoA is unsupported, issue a disconnect command when the NAS
   binding supports it; otherwise fail closed and record the unsupported
   enforcement result.
@@ -166,3 +171,32 @@ for authorization, routing, firewall configuration or accounting.
 Consumers must cover these rules with deterministic tests. Failure is
 fail-closed for control messages and bounded reject/drop-with-counter behavior
 for telemetry.
+
+## Endpoint presence and RADIUS response
+
+- `endpoint.presence.request` goes to
+  `POST /api/network-control/v1/runtimes/{runtimeId}/endpoint:presence` using the
+  enrolled endpoint's control identity and `endpoint-presence-v1` capability.
+  `bootId` identifies the protected service incarnation; a new incarnation
+  starts a new sequence and retires the previous one. A duplicate must not
+  refresh server-side liveness. UI presence never implies a healthy service.
+- `POST /api/network-control/v1/runtimes/{runtimeId}/nas:accounting` uses
+  the enrolled NAS control identity and the existing RADIUS Accounting schema.
+  The control plane checks NAS, subject, station and accounting-session binding
+  against the saved authorization before updating session evidence. The
+  separate ingest submission remains telemetry and cannot change admission.
+- A Stop remains terminal for that Core session. A reused accounting ID,
+  conflicting binding, restart after Start, or missing Start remains unknown.
+  Received time alone cannot refresh an old observation. Accounting evidence
+  cannot authorize access or prove that a VLAN/ACL was applied.
+- Persist response restrictions before delivering NAS commands. A new
+  authentication must observe every active restriction. Policy retirement
+  never removes an existing restriction, and restoration requires current
+  health plus authorization rather than replaying a previous allow decision.
+
+## Dedicated EAP certificates and native profiles
+
+- `eap.certificate.request` uses `POST /api/network-control/v1/runtimes/{runtimeId}/eap:certificate`; `eap.certificate.activate.request` uses the same prefix with `eap:activate`. Both require the endpoint control identity and `eap-profile-v1` plus `radius-eap-tls-v1`. CSR private keys stay on the endpoint. Core binds the subject and device from enrollment and ignores CSR identity extensions.
+- A dedicated EAP issuer signs only client authentication certificates with a `network-eap` URI. EAP certificates cannot authenticate control or ingest requests. Without an issuer, issuance is unavailable. Existing runtime certificates are accepted for legacy EAP only when enrollment explicitly declares `radius-eap-tls-v1`; ordinary control credentials do not imply EAP permission.
+- Issuance is idempotent per runtime/request ID and CSR. Certificates start pending and cannot grant network access. After native installation and readback, activation atomically replaces the old EAP certificate under the parent runtime credential lock. A retired or expired parent invalidates every child. Replaying an older activation cannot revive it.
+- `admission.profiles` is delivered only to `eap-profile-v1` endpoints, with exact EAP server names, CA certificates, subject and the dedicated active EAP certificate fingerprint. Configuration export, installation, 802.1X connection and actual NAS enforcement are separate results.

package/network/network-radius-accounting.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://contracts.opensoha.dev/network/network-radius-accounting.schema.json",
   "title": "OpenSoha FreeRADIUS Accounting Adapter Request",
-  "description": "A strict credential-free request converted by soha-ingest into one canonical radius.accounting event.",
+  "description": "A strict credential-free request converted by soha-ingest into telemetry. When submitted to network-control with an enrolled NAS identity, its NAS and session binding are independently verified before updating admission evidence.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -20,6 +20,9 @@
     "accountingSessionId": { "$ref": "#/$defs/Identifier" },
     "sessionId": { "$ref": "#/$defs/Identifier" },
     "nasId": { "$ref": "#/$defs/Identifier" },
+    "accountingDelaySeconds": { "type": "integer", "minimum": 0, "maximum": 86400 },
+    "observedVlanId": { "type": "integer", "minimum": 1, "maximum": 4094 },
+    "observedFilterId": { "type": "string", "minLength": 1, "maxLength": 128 },
     "nasPortId": { "type": "string", "minLength": 1, "maxLength": 128 },
     "userId": { "$ref": "#/$defs/Identifier" },
     "deviceId": { "$ref": "#/$defs/Identifier" },