contract: publish atelet↔ateom under pkg/, neutralize names, drop runsc_path

cmd/atecontroller/internal/controllers/workerpool_apply.go

@@ -20,8 +20,8 @@ import (
 	corev1ac "k8s.io/client-go/applyconfigurations/core/v1"
 	metav1ac "k8s.io/client-go/applyconfigurations/meta/v1"
 
-	"github.com/agent-substrate/substrate/internal/ateompath"
 	atev1alpha1 "github.com/agent-substrate/substrate/pkg/api/v1alpha1"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
 )
 
 // buildDeploymentApplyConfig constructs the SSA apply configuration for the

cmd/atecontroller/internal/controllers/workerpool_apply_test.go

@@ -25,8 +25,8 @@ import (
 	corev1ac "k8s.io/client-go/applyconfigurations/core/v1"
 	metav1ac "k8s.io/client-go/applyconfigurations/meta/v1"
 
-	"github.com/agent-substrate/substrate/internal/ateompath"
 	atev1alpha1 "github.com/agent-substrate/substrate/pkg/api/v1alpha1"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
 )
 
 func TestBuildDeploymentApplyConfig(t *testing.T) {

cmd/atelet/main.go

@@ -32,12 +32,12 @@ import (
 	"github.com/agent-substrate/substrate/cmd/atelet/internal/ategcs"
 	"github.com/agent-substrate/substrate/cmd/atelet/internal/memorypullcache"
 	"github.com/agent-substrate/substrate/internal/ateinterceptors"
-	"github.com/agent-substrate/substrate/internal/ateompath"
 	"github.com/agent-substrate/substrate/internal/proto/ateletpb"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
 	"github.com/agent-substrate/substrate/internal/resources"
 	"github.com/agent-substrate/substrate/internal/serverboot"
 	"github.com/agent-substrate/substrate/internal/version"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 	"github.com/aws/aws-sdk-go-v2/config"
 	"github.com/aws/aws-sdk-go-v2/service/s3"
 	"github.com/google/go-containerregistry/pkg/authn"
@@ -249,13 +249,13 @@ func (s *AteomHerder) Run(ctx context.Context, req *ateletpb.RunRequest) (*atele
 		return nil, err
 	}
 
-	// Tell ateom to start the workload. gVisor uses RunscPath; the micro-VM
-	// runtime uses the full RuntimeAssetPaths set.
+	// Tell ateom to start the workload. Every backend reads the assets it needs
+	// from RuntimeAssetPaths (gVisor reads "runsc"; the micro-VM runtime reads its
+	// cloud-hypervisor/kata-* set).
 	if _, err := client.RunWorkload(ctx, &ateompb.RunWorkloadRequest{
 		ActorTemplateNamespace: ns,
 		ActorTemplateName:      tmpl,
 		ActorId:                actorID,
-		RunscPath:              runscPathFor(assetPaths),
 		RuntimeAssetPaths:      assetPaths,
 		Spec:                   buildAteomWorkloadSpec(req.GetSpec()),
 	}); err != nil {
@@ -335,7 +335,6 @@ func (s *AteomHerder) Checkpoint(ctx context.Context, req *ateletpb.CheckpointRe
 		ActorTemplateNamespace: ns,
 		ActorTemplateName:      tmpl,
 		ActorId:                actorID,
-		RunscPath:              runscPathFor(assetPaths),
 		RuntimeAssetPaths:      assetPaths,
 		Spec:                   buildAteomWorkloadSpec(req.GetSpec()),
 	})
@@ -534,7 +533,6 @@ func (s *AteomHerder) Restore(ctx context.Context, req *ateletpb.RestoreRequest)
 		ActorTemplateNamespace: ns,
 		ActorTemplateName:      tmpl,
 		ActorId:                actorID,
-		RunscPath:              runscPathFor(assetPaths),
 		RuntimeAssetPaths:      assetPaths,
 		Spec:                   buildAteomWorkloadSpec(req.GetSpec()),
 	}); err != nil {

cmd/atelet/main_test.go

@@ -26,8 +26,8 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/agent-substrate/substrate/internal/ateompath"
 	"github.com/agent-substrate/substrate/internal/proto/ateletpb"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )
@@ -255,7 +255,7 @@ func TestFetchAssetRejectsBadHash(t *testing.T) {
 	// Invalid (8 chars, not 64) but separator-free, so it resolves to a normal
 	// filename inside the temp StaticFilesDir.
 	const badHash = "deadbeef"
-	if err := os.WriteFile(ateompath.RunSCBinaryPath(badHash), []byte("planted"), 0o755); err != nil {
+	if err := os.WriteFile(ateompath.CachedAssetPath(badHash), []byte("planted"), 0o755); err != nil {
 		t.Fatalf("planting cache file: %v", err)
 	}
 
@@ -313,7 +313,7 @@ func TestFetchAssetStreaming(t *testing.T) {
 		if _, err := s.fetchAsset(context.Background(), assetEntry{URL: url, SHA256: goodHash}); err == nil {
 			t.Fatal("fetchAsset accepted an over-cap asset")
 		}
-		if _, err := os.Stat(ateompath.RunSCBinaryPath(goodHash)); !errors.Is(err, os.ErrNotExist) {
+		if _, err := os.Stat(ateompath.CachedAssetPath(goodHash)); !errors.Is(err, os.ErrNotExist) {
 			t.Errorf("over-cap download left a file at the cache path (stat err = %v)", err)
 		}
 	})
@@ -326,7 +326,7 @@ func TestFetchAssetStreaming(t *testing.T) {
 		if _, err := s.fetchAsset(context.Background(), assetEntry{URL: url, SHA256: wrongHash}); err == nil {
 			t.Fatal("fetchAsset accepted a hash mismatch")
 		}
-		if _, err := os.Stat(ateompath.RunSCBinaryPath(wrongHash)); !errors.Is(err, os.ErrNotExist) {
+		if _, err := os.Stat(ateompath.CachedAssetPath(wrongHash)); !errors.Is(err, os.ErrNotExist) {
 			t.Errorf("mismatched download left a file at the cache path (stat err = %v)", err)
 		}
 	})

cmd/atelet/oci.go

@@ -28,7 +28,7 @@ import (
 	"strings"
 
 	"github.com/agent-substrate/substrate/cmd/atelet/internal/memorypullcache"
-	"github.com/agent-substrate/substrate/internal/ateompath"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
 	"github.com/opencontainers/runtime-spec/specs-go"
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/attribute"

cmd/atelet/sandbox_assets.go

@@ -28,9 +28,9 @@ import (
 	"runtime"
 
 	"github.com/agent-substrate/substrate/cmd/atelet/internal/ategcs"
-	"github.com/agent-substrate/substrate/internal/ateompath"
 	"github.com/agent-substrate/substrate/internal/proto/ateletpb"
 	"github.com/agent-substrate/substrate/internal/resources"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )
@@ -107,19 +107,15 @@ func (s *AteomHerder) ensureSandboxAssets(ctx context.Context, rec *sandboxAsset
 	return paths, nil
 }
 
-// runscPathFor returns the local path of the gVisor "runsc" asset from a fetched
-// asset-path map, or "" if the runtime has none (e.g. micro-VM).
-func runscPathFor(paths map[string]string) string { return paths["runsc"] }
-
 // fetchAsset downloads one content-addressed asset (verifying its sha256) into
 // the shared static-files cache and returns its local path. On a cache hit it
 // returns immediately.
 func (s *AteomHerder) fetchAsset(ctx context.Context, entry assetEntry) (string, error) {
-	if err := resources.ValidateRunscHash(entry.SHA256); err != nil {
+	if err := resources.ValidateAssetHash(entry.SHA256); err != nil {
 		return "", status.Error(codes.InvalidArgument, err.Error())
 	}
 
-	localPath := ateompath.RunSCBinaryPath(entry.SHA256)
+	localPath := ateompath.CachedAssetPath(entry.SHA256)
 	_, err := os.Stat(localPath)
 	if err == nil { // EQUALS nil
 		return localPath, nil

cmd/ateom-gvisor/main.go

@@ -30,11 +30,11 @@ import (
 	"cloud.google.com/go/compute/metadata"
 	"github.com/agent-substrate/substrate/internal/actorlog"
 	"github.com/agent-substrate/substrate/internal/ateinterceptors"
-	"github.com/agent-substrate/substrate/internal/ateompath"
 	"github.com/agent-substrate/substrate/internal/contextlogging"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
 	"github.com/agent-substrate/substrate/internal/serverboot"
 	"github.com/agent-substrate/substrate/internal/version"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 	"github.com/google/nftables"
 	"github.com/google/nftables/binaryutil"
 	"github.com/google/nftables/expr"
@@ -197,7 +197,7 @@ func (s *AteomService) RunWorkload(ctx context.Context, req *ateompb.RunWorkload
 	}()
 
 	rcmd := &runsc{
-		path:                   req.GetRunscPath(),
+		path:                   req.GetRuntimeAssetPaths()["runsc"],
 		actorTemplateNamespace: req.GetActorTemplateNamespace(),
 		actorTemplateName:      req.GetActorTemplateName(),
 		actorID:                req.GetActorId(),
@@ -244,7 +244,7 @@ func (s *AteomService) CheckpointWorkload(ctx context.Context, req *ateompb.Chec
 	//   * After we exit, atelet will tear down OCI bundles and reset the actor directory.
 
 	rcmd := &runsc{
-		path:                   req.GetRunscPath(),
+		path:                   req.GetRuntimeAssetPaths()["runsc"],
 		actorTemplateNamespace: req.GetActorTemplateNamespace(),
 		actorTemplateName:      req.GetActorTemplateName(),
 		actorID:                req.GetActorId(),
@@ -351,7 +351,7 @@ func (s *AteomService) RestoreWorkload(ctx context.Context, req *ateompb.Restore
 	}()
 
 	rcmd := &runsc{
-		path:                   req.GetRunscPath(),
+		path:                   req.GetRuntimeAssetPaths()["runsc"],
 		actorTemplateNamespace: req.GetActorTemplateNamespace(),
 		actorTemplateName:      req.GetActorTemplateName(),
 		actorID:                req.GetActorId(),

cmd/ateom-gvisor/runsc.go

@@ -24,7 +24,7 @@ import (
 	"os"
 	"os/exec"
 
-	"github.com/agent-substrate/substrate/internal/ateompath"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
 )
 
 type runsc struct {

cmd/ateom-microvm/checkpoint.go

@@ -26,8 +26,8 @@ import (
 
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/ch"
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/kata"
-	"github.com/agent-substrate/substrate/internal/ateompath"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 )
 
 // CheckpointWorkload suspends the actor and writes a portable CH snapshot.

cmd/ateom-microvm/main.go

@@ -35,10 +35,10 @@ import (
 	"cloud.google.com/go/compute/metadata"
 	"github.com/agent-substrate/substrate/internal/actorlog"
 	"github.com/agent-substrate/substrate/internal/ateinterceptors"
-	"github.com/agent-substrate/substrate/internal/ateompath"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
 	"github.com/agent-substrate/substrate/internal/serverboot"
 	"github.com/agent-substrate/substrate/internal/version"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 	"github.com/hashicorp/go-reap"
 	"github.com/vishvananda/netns"
 	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"

cmd/ateom-microvm/restore.go

@@ -28,8 +28,8 @@ import (
 
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/ch"
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/kata"
-	"github.com/agent-substrate/substrate/internal/ateompath"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )

cmd/ateom-microvm/run.go

@@ -29,8 +29,8 @@ import (
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/ch"
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/kata"
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/third_party/kata/agentpb"
-	"github.com/agent-substrate/substrate/internal/ateompath"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 	specs "github.com/opencontainers/runtime-spec/specs-go"
 	"golang.org/x/sys/unix"
 	"google.golang.org/grpc/codes"

cmd/ateom-microvm/service_integration_test.go

@@ -30,8 +30,8 @@ import (
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/ch"
 	"github.com/agent-substrate/substrate/cmd/ateom-microvm/internal/kata"
 	"github.com/agent-substrate/substrate/internal/actorlog"
-	"github.com/agent-substrate/substrate/internal/ateompath"
-	"github.com/agent-substrate/substrate/internal/proto/ateompb"
+	"github.com/agent-substrate/substrate/pkg/ateompath"
+	"github.com/agent-substrate/substrate/pkg/proto/ateompb"
 	"github.com/vishvananda/netns"
 )
 

internal/resources/validate.go

@@ -94,19 +94,19 @@ func ValidateContainerNames(names []string) error {
 	return nil
 }
 
-// ValidateRunscHash ensures the runsc SHA-256 hash is exactly 64 hex
-// characters before it is used to build the on-disk binary path
-// (static-files/runsc-<hash>) and, on a cache hit, returned for ateom to
-// execute. Without this, a hash containing path separators or ".." could
-// point the cache-hit early return (and the download target) at an arbitrary
-// binary outside the static-files dir.
-func ValidateRunscHash(sha256Hash string) error {
+// ValidateAssetHash ensures a content-addressed asset's SHA-256 hash is exactly
+// 64 hex characters before it is used to build the on-disk cache path
+// (static-files/runsc-<hash>) and, on a cache hit, returned for ateom to use.
+// Without this, a hash containing path separators or ".." could point the
+// cache-hit early return (and the download target) at an arbitrary file outside
+// the static-files dir.
+func ValidateAssetHash(sha256Hash string) error {
 	if len(sha256Hash) != 64 {
-		return fmt.Errorf("invalid runsc sha256 hash: want 64 hex chars, got %d", len(sha256Hash))
+		return fmt.Errorf("invalid asset sha256 hash: want 64 hex chars, got %d", len(sha256Hash))
 	}
 	// Same decoder atelet's digest comparison uses.
 	if _, err := hex.DecodeString(sha256Hash); err != nil {
-		return fmt.Errorf("invalid runsc sha256 hash %q: must be hex", sha256Hash)
+		return fmt.Errorf("invalid asset sha256 hash %q: must be hex", sha256Hash)
 	}
 	return nil
 }

internal/resources/validate_test.go

@@ -111,7 +111,7 @@ func TestValidateContainerNames(t *testing.T) {
 	}
 }
 
-func TestValidateRunscHash(t *testing.T) {
+func TestValidateAssetHash(t *testing.T) {
 	const valid = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 
 	tests := []struct {
@@ -129,8 +129,8 @@ func TestValidateRunscHash(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			if err := ValidateRunscHash(tt.hash); (err != nil) != tt.wantErr {
-				t.Errorf("ValidateRunscHash(%q) err = %v, wantErr %v", tt.hash, err, tt.wantErr)
+			if err := ValidateAssetHash(tt.hash); (err != nil) != tt.wantErr {
+				t.Errorf("ValidateAssetHash(%q) err = %v, wantErr %v", tt.hash, err, tt.wantErr)
 			}
 		})
 	}

internal/ateompath/ateompath.go → pkg/ateompath/ateompath.go

@@ -26,11 +26,14 @@ const (
 )
 
 var (
-	// StaticFilesDir holds things like downloaded runsc binaries.
+	// StaticFilesDir holds downloaded, content-addressed sandbox assets.
 	StaticFilesDir = filepath.Join(BasePath, "static-files")
 )
 
-func RunSCBinaryPath(sha256 string) string {
+// CachedAssetPath returns the on-disk cache path for a content-addressed
+// sandbox asset, keyed by its SHA-256 hash. The "runsc-" filename prefix is
+// kept for backward compatibility — existing snapshots embed this absolute path.
+func CachedAssetPath(sha256 string) string {
 	return filepath.Join(StaticFilesDir, "runsc-"+sha256)
 }