Update kubectl-ate to use actor name instead of id.

This is a follow up of the API refactor. Now the CLI shows
some common fields (e.g. `create_timestamp`) but also shows
actor *name* instead of *id*.

Author: juli4n

cmd/kubectl-ate/README.md

@@ -83,29 +83,29 @@ kubectl ate get actors -a <atespace>
 # List actors across all atespaces
 kubectl ate get actors -A
 
-# Get a specific actor by ID and output as raw YAML
-kubectl ate get actor <actor-id> --atespace <atespace> -o yaml
+# Get a specific actor by name and output as raw YAML
+kubectl ate get actor <actor-name> --atespace <atespace> -o yaml
 
 # List all physical workers and see which actors are assigned to them
 kubectl ate get workers
 ```
 
-> **Note:** `get actors` requires either `--atespace <name>` / `-a <name>` (one atespace) or `-A`/`--all-atespaces` (all atespaces) — there is no default atespace. Getting a single actor always requires `--atespace`/`-a`, since an actor is addressed by `(atespace, id)`. `-a` (lower-case) scopes to one atespace; `-A` (upper-case) spans all.
+> **Note:** `get actors` requires either `--atespace <name>` / `-a <name>` (one atespace) or `-A`/`--all-atespaces` (all atespaces) — there is no default atespace. Getting a single actor always requires `--atespace`/`-a`, since an actor is addressed by `(atespace, name)`. `-a` (lower-case) scopes to one atespace; `-A` (upper-case) spans all.
 
 > **Note:** Actors and workers are not Kubernetes CRDs — they live in the Substrate control plane (valkey/redis), not `etcd`. `kubectl get actor` and `kubectl get worker` will not return anything; only `kubectl ate get …` queries the control plane. `kubectl get actortemplate` and `kubectl get workerpool` *do* work, because those are CRDs.
 
 #### `kubectl ate get actor` output columns
 
 | Column | Meaning |
 |---|---|
-| `ATESPACE` | The atespace the actor belongs to. Part of the actor's identity; folded into the storage key as `actor:<atespace>:<id>`. |
-| `TEMPLATE NS` | The namespace of the `ActorTemplate` the actor was created from (distinct from `ATESPACE`). |
-| `TEMPLATE` | The `ActorTemplate` name. |
-| `ID` | Actor ID. User-provided for application actors; UUID for the golden actor that each template materialises during `ResumeGoldenActor`. |
+| `ATESPACE` | The atespace the actor belongs to. Part of the actor's identity; folded into the storage key as `actor:<atespace>:<name>`. |
+| `NAME` | The actor's name. User-provided for application actors; UUID for the golden actor that each template materialises during `ResumeGoldenActor`. |
+| `TEMPLATE` | The `ActorTemplate` the actor was created from, as `<namespace>/<name>` (the template namespace is distinct from `ATESPACE`). |
 | `STATUS` | One of `STATUS_RESUMING`, `STATUS_RUNNING`, `STATUS_SUSPENDING`, `STATUS_SUSPENDED`. |
 | `ATEOM POD` | The worker pod (namespace/name) currently hosting the actor. Empty while suspended. |
 | `ATEOM IP` | The pod IP of that worker. Empty while suspended. |
 | `VERSION` | Monotonic integer that increments on every state transition (resume / suspend / checkpoint). Useful for distinguishing snapshots. |
+| `AGE` | Time elapsed since the actor was created. |
 
 #### `kubectl ate get worker` output columns
 
@@ -115,7 +115,7 @@ kubectl ate get workers
 | `POOL` | The `WorkerPool` name. |
 | `POD` | The worker pod name. |
 | `STATUS` | `FREE` (idle, ready to receive an actor) or `ASSIGNED` (currently hosting an actor). |
-| `ASSIGNED ACTOR` | If `STATUS=ASSIGNED`, the actor reference `<namespace>/<template>/<actor-id>`. |
+| `ASSIGNED ACTOR` | If `STATUS=ASSIGNED`, the actor reference `<namespace>/<template>/<actor-name>`. |
 
 ### Atespaces
 
@@ -137,9 +137,16 @@ kubectl ate delete atespace <atespace>
 
 > **Note:** `create actor … -a <atespace>` requires the atespace to already exist, otherwise it fails with `FailedPrecondition`. `delete atespace` only removes an **empty** atespace; delete its actors first (cascade delete is not yet supported).
 
+#### `kubectl ate get atespace` output columns
+
+| Column | Meaning |
+|---|---|
+| `NAME` | The atespace name. Globally unique — atespaces are global-scoped. |
+| `AGE` | Time elapsed since the atespace was created. |
+
 ### Actor Lifecycle
 Manage the execution state of your workloads.
-*(Note: Actors are identified by a user-provided ID, which must be a valid DNS-1123 label)*
+*(Note: Actors are identified by a user-provided name, which must be a valid DNS-1123 label)*
 
 ```bash
 # Create a new actor deriving from a specific ActorTemplate.
@@ -159,7 +166,7 @@ kubectl ate delete actor my-actor -a <atespace>
 
 ### Logs
 
-`kubectl ate logs` requires a resource-type subcommand; running `kubectl ate logs <id>` on its own prints help. The only supported resource type is `actors`:
+`kubectl ate logs` requires a resource-type subcommand; running `kubectl ate logs <actor-name>` on its own prints help. The only supported resource type is `actors`:
 
 ```bash
 # Stream logs for an actor (follows by default; aggregated across worker

cmd/kubectl-ate/internal/cmd/create_actor.go

@@ -28,7 +28,7 @@ var templateFlag string
 var atespaceFlag string
 
 var createActorCmd = &cobra.Command{
-	Use:   "actor [actor-id]",
+	Use:   "actor <actor-name>",
 	Short: "Create an actor",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -39,7 +39,7 @@ var createActorCmd = &cobra.Command{
 		}
 		defer apiClient.Close()
 
-		actorID := args[0]
+		actorName := args[0]
 		parts := strings.Split(templateFlag, "/")
 		if len(parts) != 2 {
 			return fmt.Errorf("malformed --template: %s (expected <namespace>/<name>)", templateFlag)
@@ -49,7 +49,7 @@ var createActorCmd = &cobra.Command{
 			Actor: &ateapipb.Actor{
 				Metadata: &ateapipb.ResourceMetadata{
 					Atespace: atespaceFlag,
-					Name:     actorID,
+					Name:     actorName,
 				},
 				ActorTemplateNamespace: parts[0],
 				ActorTemplateName:      parts[1],

cmd/kubectl-ate/internal/cmd/delete_actor.go

@@ -25,7 +25,7 @@ import (
 var deleteAtespaceFlag string
 
 var deleteActorCmd = &cobra.Command{
-	Use:   "actor [actor-id]",
+	Use:   "actor <actor-name>",
 	Short: "Delete an actor",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -36,15 +36,15 @@ var deleteActorCmd = &cobra.Command{
 		}
 		defer c.Close()
 
-		id := args[0]
+		name := args[0]
 		_, err = c.ControlClient.DeleteActor(ctx, &ateapipb.DeleteActorRequest{
-			Actor: &ateapipb.ObjectRef{Atespace: deleteAtespaceFlag, Name: id},
+			Actor: &ateapipb.ObjectRef{Atespace: deleteAtespaceFlag, Name: name},
 		})
 		if err != nil {
 			return err
 		}
 
-		fmt.Printf("actor %q deleted\n", id)
+		fmt.Printf("actor %q deleted\n", name)
 		return nil
 	},
 }

cmd/kubectl-ate/internal/cmd/get_actors.go

@@ -29,7 +29,7 @@ var (
 )
 
 var getActorsCmd = &cobra.Command{
-	Use:     "actors [actor-id]",
+	Use:     "actors <actor-name>",
 	Aliases: []string{"actor"},
 	Short:   "List all actors or get a specific actor",
 	RunE: func(cmd *cobra.Command, args []string) error {
@@ -44,7 +44,7 @@ var getActorsCmd = &cobra.Command{
 
 		// 2. Handle Get Single Actor
 		if len(args) > 0 {
-			// A single actor is addressed by (atespace, id), so the atespace is
+			// A single actor is addressed by (atespace, name), so the atespace is
 			// mandatory and "all atespaces" is meaningless here.
 			if getActorsAllAtespaces {
 				return fmt.Errorf("-A/--all-atespaces cannot be used when getting a specific actor; pass --atespace")

cmd/kubectl-ate/internal/cmd/logs_actors.go

@@ -42,7 +42,7 @@ var followLogs bool
 var logsAtespaceFlag string
 
 var logsActorsCmd = &cobra.Command{
-	Use:     "actors <actor-id>",
+	Use:     "actors <actor-name>",
 	Aliases: []string{"actor"},
 	Short:   "Stream logs for a specific actor",
 	Args:    cobra.ExactArgs(1),
@@ -90,7 +90,7 @@ type LogsActorRunner struct {
 }
 
 // Run executes the logs command.
-func (r *LogsActorRunner) Run(ctx context.Context, actorID string) error {
+func (r *LogsActorRunner) Run(ctx context.Context, actorName string) error {
 	if r.pollInterval <= 0 {
 		r.pollInterval = 2 * time.Second
 	}
@@ -103,13 +103,13 @@ func (r *LogsActorRunner) Run(ctx context.Context, actorID string) error {
 
 	defer r.apiClient.Close()
 	if r.follow {
-		return r.runFollow(ctx, actorID)
+		return r.runFollow(ctx, actorName)
 	}
-	return r.runOneShot(ctx, actorID)
+	return r.runOneShot(ctx, actorName)
 }
 
-func (r *LogsActorRunner) runOneShot(ctx context.Context, actorID string) error {
-	actor, err := r.apiClient.GetActor(ctx, &ateapipb.GetActorRequest{Actor: &ateapipb.ObjectRef{Atespace: r.atespace, Name: actorID}})
+func (r *LogsActorRunner) runOneShot(ctx context.Context, actorName string) error {
+	actor, err := r.apiClient.GetActor(ctx, &ateapipb.GetActorRequest{Actor: &ateapipb.ObjectRef{Atespace: r.atespace, Name: actorName}})
 	if err != nil {
 		return fmt.Errorf("failed to get actor: %w", err)
 	}
@@ -118,7 +118,7 @@ func (r *LogsActorRunner) runOneShot(ctx context.Context, actorID string) error
 	namespace := actor.GetAteomPodNamespace()
 
 	if podName == "" || namespace == "" || actor.GetStatus() != ateapipb.Actor_STATUS_RUNNING {
-		return fmt.Errorf("actor %s is not currently running on any worker pod", actorID)
+		return fmt.Errorf("actor %s is not currently running on any worker pod", actorName)
 	}
 
 	opts := &corev1.PodLogOptions{
@@ -136,15 +136,15 @@ func (r *LogsActorRunner) runOneShot(ctx context.Context, actorID string) error
 	scanner.Buffer(buf, 1024*1024) // Support up to 1MB lines
 	for scanner.Scan() {
 		line := scanner.Text()
-		filterAndDisplayLogLine(line, actorID, r.stdout)
+		filterAndDisplayLogLine(line, actorName, r.stdout)
 	}
 	if err := scanner.Err(); err != nil {
 		return fmt.Errorf("error reading log stream: %w", err)
 	}
 	return nil
 }
 
-func (r *LogsActorRunner) runFollow(ctx context.Context, actorID string) error {
+func (r *LogsActorRunner) runFollow(ctx context.Context, actorName string) error {
 	var lastWorkerPod string
 	var lastSeenTime time.Time
 
@@ -155,10 +155,10 @@ func (r *LogsActorRunner) runFollow(ctx context.Context, actorID string) error {
 		default:
 		}
 
-		actor, err := r.apiClient.GetActor(ctx, &ateapipb.GetActorRequest{Actor: &ateapipb.ObjectRef{Atespace: r.atespace, Name: actorID}})
+		actor, err := r.apiClient.GetActor(ctx, &ateapipb.GetActorRequest{Actor: &ateapipb.ObjectRef{Atespace: r.atespace, Name: actorName}})
 		if err != nil {
 			if status.Code(err) == codes.NotFound {
-				return fmt.Errorf("actor %s not found: %w", actorID, err)
+				return fmt.Errorf("actor %s not found: %w", actorName, err)
 			}
 			select {
 			case <-ctx.Done():
@@ -206,14 +206,14 @@ func (r *LogsActorRunner) runFollow(ctx context.Context, actorID string) error {
 		}
 
 		var wg sync.WaitGroup
-		r.startMigrationMonitor(streamCtx, streamCancel, &wg, actorID, podName)
+		r.startMigrationMonitor(streamCtx, streamCancel, &wg, actorName, podName)
 
 		scanner := bufio.NewScanner(stream)
 		buf := make([]byte, 0, 64*1024)
 		scanner.Buffer(buf, 1024*1024) // Support up to 1MB lines
 		for scanner.Scan() {
 			line := scanner.Text()
-			logTime, _ := filterAndDisplayLogLine(line, actorID, r.stdout)
+			logTime, _ := filterAndDisplayLogLine(line, actorName, r.stdout)
 			if !logTime.IsZero() {
 				lastSeenTime = logTime
 			}
@@ -249,7 +249,7 @@ func (r *LogsActorRunner) startMigrationMonitor(
 	ctx context.Context,
 	cancel context.CancelFunc,
 	wg *sync.WaitGroup,
-	actorID string,
+	actorName string,
 	currentPod string,
 ) {
 	wg.Add(1)
@@ -262,7 +262,7 @@ func (r *LogsActorRunner) startMigrationMonitor(
 			case <-ctx.Done():
 				return
 			case <-ticker.C:
-				resp, err := r.apiClient.GetActor(ctx, &ateapipb.GetActorRequest{Actor: &ateapipb.ObjectRef{Atespace: r.atespace, Name: actorID}})
+				resp, err := r.apiClient.GetActor(ctx, &ateapipb.GetActorRequest{Actor: &ateapipb.ObjectRef{Atespace: r.atespace, Name: actorName}})
 				if err == nil {
 					act := resp
 					if act.GetStatus() != ateapipb.Actor_STATUS_RUNNING || act.GetAteomPodName() != currentPod {
@@ -278,7 +278,7 @@ func (r *LogsActorRunner) startMigrationMonitor(
 
 func runLogsActor(cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
-	actorID := args[0]
+	actorName := args[0]
 
 	apiClient, err := ateclient.NewClient(ctx, kubeconfig, k8sContext, endpoint, traceEnabled)
 	if err != nil {
@@ -303,10 +303,10 @@ func runLogsActor(cmd *cobra.Command, args []string) error {
 		tickerInterval:    2 * time.Second,
 	}
 
-	return runner.Run(ctx, actorID)
+	return runner.Run(ctx, actorName)
 }
 
-func filterAndDisplayLogLine(line, targetActorID string, w io.Writer) (time.Time, bool) {
+func filterAndDisplayLogLine(line, targetActorName string, w io.Writer) (time.Time, bool) {
 	var m map[string]any
 	dec := json.NewDecoder(strings.NewReader(line))
 	dec.UseNumber()
@@ -323,19 +323,19 @@ func filterAndDisplayLogLine(line, targetActorID string, w io.Writer) (time.Time
 		}
 	}
 
-	var actorID string
+	var actorName string
 	for _, labelKey := range []string{"logging.googleapis.com/labels", "labels"} {
 		if labelsAny, ok := m[labelKey]; ok {
 			if labels, ok := labelsAny.(map[string]any); ok {
-				if id, ok := labels["ate.dev/actor_id"].(string); ok && id != "" {
-					actorID = id
+				if name, ok := labels["ate.dev/actor_name"].(string); ok && name != "" {
+					actorName = name
 					break
 				}
 			}
 		}
 	}
 
-	matched := (actorID != "" && actorID == targetActorID)
+	matched := (actorName != "" && actorName == targetActorName)
 
 	if !matched {
 		return logTime, false