plexspaces 0.1.1__py3-none-any.whl

plexspaces/generated/plexspaces/actor/v1/__init__.py

@@ -0,0 +1,3538 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# sources: plexspaces/v1/actors/actor_runtime.proto, plexspaces/v1/actors/types.proto
+# plugin: python-betterproto
+# This file has been @generated
+
+from dataclasses import dataclass
+from datetime import (
+    datetime,
+    timedelta,
+)
+from typing import (
+    TYPE_CHECKING,
+    AsyncIterable,
+    AsyncIterator,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Union,
+)
+
+import betterproto
+import betterproto.lib.google.protobuf as betterproto_lib_google_protobuf
+import grpclib
+from betterproto.grpc.grpclib_server import ServiceBase
+
+from ...common import v1 as __common_v1__
+from ...supervision import v1 as __supervision_v1__
+
+if TYPE_CHECKING:
+    import grpclib.server
+    from betterproto.grpc.grpclib_client import MetadataLike
+    from grpclib.metadata import Deadline
+
+
+class ActorState(betterproto.Enum):
+    """
+    Actor lifecycle states.
+
+     ## Purpose
+     Defines the state machine for actor lifecycle management and supervision.
+
+     ## Why This Exists
+     - Enables supervision to track actor health and make restart decisions
+     - Supports graceful activation/deactivation (Orbit-inspired auto-activation)
+     - Allows migration state tracking for mobile agents
+     - Provides clear state transitions for debugging and monitoring
+
+     ## State Transitions
+     ```
+     CREATING -> ACTIVATING -> ACTIVE -> DEACTIVATING -> INACTIVE
+                            \-> MIGRATING -> ACTIVE (on new node)
+                            \-> FAILED -> (supervisor restarts)
+                            \-> TERMINATED (permanent stop)
+     ```
+
+     ## Design Notes
+     - UNSPECIFIED should never occur in valid states (indicates error)
+     - ACTIVATING/DEACTIVATING enable graceful lifecycle management
+     - MIGRATING supports actor mobility between nodes
+     - FAILED triggers supervisor restart policies
+     - FAILED state includes error message for debugging (see Actor message for error details)
+    """
+
+    UNSPECIFIED = 0
+    CREATING = 1
+    ACTIVE = 2
+    INACTIVE = 3
+    ACTIVATING = 4
+    DEACTIVATING = 5
+    STOPPING = 6
+    MIGRATING = 7
+    FAILED = 8
+    TERMINATED = 9
+
+
+class ExitReason(betterproto.Enum):
+    """
+    Exit reason for actor termination (Erlang/OTP-style)
+
+     ## Purpose
+     Defines why an actor terminated, enabling proper supervision decisions
+     and link/monitor propagation semantics.
+
+     ## Erlang Equivalent
+     Maps to Erlang's exit reasons:
+     - normal: Normal termination (not an error)
+     - shutdown: Graceful shutdown requested
+     - kill: Forcefully killed
+     - {error, Reason}: Error with message
+     - {linked, Pid, Reason}: Linked actor died
+
+     ## Usage
+     - Used in Actor::terminate() and Actor::handle_exit() lifecycle hooks
+     - Propagated to linked actors (if trap_exit=false, causes cascading crash)
+     - Used by supervisors to decide restart policies
+    """
+
+    UNSPECIFIED = 0
+    NORMAL = 1
+    SHUTDOWN = 2
+    KILLED = 3
+    ERROR = 4
+    LINKED = 5
+
+
+class ExitAction(betterproto.Enum):
+    """
+    Exit action when handling EXIT from linked actor
+
+     ## Purpose
+     Determines how an actor responds to EXIT signal from a linked actor.
+     Only relevant when ActorContext.trap_exit = true.
+
+     ## Erlang Equivalent
+     Maps to Erlang's handle_exit behavior:
+     - Propagate: Actor will also terminate (default link behavior)
+     - Handle: Actor continues running (traps the exit)
+    """
+
+    UNSPECIFIED = 0
+    PROPAGATE = 1
+    HANDLE = 2
+
+
+class ActorErrorCode(betterproto.Enum):
+    ACTOR_ERROR_UNSPECIFIED = 0
+    ACTOR_ERROR_NOT_FOUND = 1
+    ACTOR_ERROR_ALREADY_EXISTS = 2
+    ACTOR_ERROR_INVALID_STATE = 3
+    ACTOR_ERROR_TIMEOUT = 4
+    ACTOR_ERROR_TERMINATED = 5
+    ACTOR_ERROR_FACET_ERROR = 6
+    ACTOR_ERROR_MAILBOX_ERROR = 7
+    ACTOR_ERROR_BEHAVIOR_ERROR = 8
+    ACTOR_ERROR_JOURNAL_ERROR = 9
+    ACTOR_ERROR_PLACEMENT_CONFLICT = 10
+
+
+class BehaviorErrorCode(betterproto.Enum):
+    BEHAVIOR_ERROR_UNSPECIFIED = 0
+    BEHAVIOR_ERROR_HANDLER_NOT_FOUND = 1
+    BEHAVIOR_ERROR_UNSUPPORTED_MESSAGE = 2
+    BEHAVIOR_ERROR_TRANSITION_FAILED = 3
+    BEHAVIOR_ERROR_PROCESSING_ERROR = 4
+
+
+class ActorIdErrorCode(betterproto.Enum):
+    ACTOR_ID_ERROR_UNSPECIFIED = 0
+    ACTOR_ID_ERROR_INVALID_NAME = 1
+    ACTOR_ID_ERROR_INVALID_ACTOR_TYPE = 2
+    ACTOR_ID_ERROR_MISSING_FIELD = 3
+    ACTOR_ID_ERROR_INVALID_FORMAT = 4
+
+
+class SupervisorErrorCode(betterproto.Enum):
+    SUPERVISOR_ERROR_UNSPECIFIED = 0
+    SUPERVISOR_ERROR_CHILD_START_FAILED = 1
+    SUPERVISOR_ERROR_MAX_RESTARTS_EXCEEDED = 2
+    SUPERVISOR_ERROR_CHILD_NOT_FOUND = 3
+    SUPERVISOR_ERROR_SHUTDOWN_TIMEOUT = 4
+    SUPERVISOR_ERROR_CONFIG_ERROR = 5
+
+
+class GenServerErrorCode(betterproto.Enum):
+    GEN_SERVER_ERROR_UNSPECIFIED = 0
+    GEN_SERVER_ERROR_SERIALIZATION = 1
+    GEN_SERVER_ERROR_CALL = 2
+    GEN_SERVER_ERROR_CAST = 3
+    GEN_SERVER_ERROR_SPAWN = 4
+
+
+class FsmErrorCode(betterproto.Enum):
+    FSM_ERROR_UNSPECIFIED = 0
+    FSM_ERROR_SERIALIZATION = 1
+    FSM_ERROR_TRANSITION = 2
+    FSM_ERROR_QUERY = 3
+    FSM_ERROR_SPAWN = 4
+
+
+class EventErrorCode(betterproto.Enum):
+    EVENT_ERROR_UNSPECIFIED = 0
+    EVENT_ERROR_SERIALIZATION = 1
+    EVENT_ERROR_EMIT = 2
+    EVENT_ERROR_SPAWN = 3
+
+
+class WorkflowRefErrorCode(betterproto.Enum):
+    WORKFLOW_REF_ERROR_UNSPECIFIED = 0
+    WORKFLOW_REF_ERROR_SERIALIZATION = 1
+    WORKFLOW_REF_ERROR_EXECUTION = 2
+    WORKFLOW_REF_ERROR_SPAWN = 3
+
+
+class VirtualActorErrorCode(betterproto.Enum):
+    VIRTUAL_ACTOR_ERROR_UNSPECIFIED = 0
+    VIRTUAL_ACTOR_ERROR_NOT_FOUND = 1
+    VIRTUAL_ACTOR_ERROR_ACTIVATION_FAILED = 2
+
+
+class PoolServiceErrorCode(betterproto.Enum):
+    POOL_SERVICE_ERROR_UNSPECIFIED = 0
+    POOL_SERVICE_ERROR_POOL_NOT_FOUND = 1
+    POOL_SERVICE_ERROR_CHECKOUT_TIMEOUT = 2
+    POOL_SERVICE_ERROR_POOL_EXHAUSTED = 3
+    POOL_SERVICE_ERROR_CIRCUIT_OPEN = 4
+    POOL_SERVICE_ERROR_POOL_DRAINING = 5
+    POOL_SERVICE_ERROR_INVALID_CONFIG = 6
+    POOL_SERVICE_ERROR_ACTOR_ERROR = 7
+
+
+class PlacementStrategy(betterproto.Enum):
+    """Placement strategy for actor activation (Orleans-inspired)"""
+
+    UNSPECIFIED = 0
+    RANDOM = 1
+    PREFER_LOCAL = 2
+    LOAD_BASED = 3
+    RESOURCE_BASED = 4
+    AFFINITY = 5
+    CUSTOM = 99
+
+
+class LoadBalancingStrategy(betterproto.Enum):
+    LOAD_BALANCING_UNSPECIFIED = 0
+    LOAD_BALANCING_ROUND_ROBIN = 1
+    LOAD_BALANCING_LEAST_LOADED = 2
+    LOAD_BALANCING_RANDOM = 3
+
+
+class PartitionStrategy(betterproto.Enum):
+    """Partition strategy for data-parallel actors"""
+
+    UNSPECIFIED = 0
+    HASH = 1
+    RANGE = 2
+    CONSISTENT_HASH = 3
+    CUSTOM = 99
+
+
+class RebalancePolicy(betterproto.Enum):
+    """Rebalancing policy for data-parallel actors"""
+
+    UNSPECIFIED = 0
+    NONE = 1
+    ON_SCALE = 2
+    LOAD_BASED = 3
+
+
+class ShardGroupState(betterproto.Enum):
+    UNSPECIFIED = 0
+    CREATING = 1
+    ACTIVE = 2
+    REBALANCING = 3
+    DRAINING = 4
+    STOPPING = 5
+    STOPPED = 6
+
+
+class NodePlacementStrategy(betterproto.Enum):
+    """
+    Node placement strategy for ShardGroup creation (leader-worker multi-node).
+     When absent or SAME_NODE, all shards are created on the node that receives the RPC.
+     FROM_REGISTRY uses NodeRegistry.list_nodes (optional cluster filter); NODE_IDS uses explicit list.
+    """
+
+    UNSPECIFIED = 0
+    SAME_NODE = 1
+    FROM_REGISTRY = 2
+    NODE_IDS = 3
+
+
+class ShardGroupAggregationStrategy(betterproto.Enum):
+    """Aggregation strategy for scatter-gather results"""
+
+    SHARD_GROUP_AGGREGATION_UNSPECIFIED = 0
+    SHARD_GROUP_AGGREGATION_CONCAT = 1
+    SHARD_GROUP_AGGREGATION_MERGE = 2
+    SHARD_GROUP_AGGREGATION_FIRST = 3
+    SHARD_GROUP_AGGREGATION_MAJORITY = 4
+
+
+class CollectiveReduction(betterproto.Enum):
+    UNSPECIFIED = 0
+    SUM = 1
+    MIN = 2
+    MAX = 3
+    PRODUCT = 4
+    CONCAT = 5
+    BOOL_AND = 6
+    BOOL_OR = 7
+
+
+class StateMgmtMode(betterproto.Enum):
+    """State management mode (lattice-based data-parallel actors)"""
+
+    UNSPECIFIED = 0
+    TRADITIONAL = 1
+    LATTICE = 2
+
+
+class ConsistencyLevel(betterproto.Enum):
+    """Consistency level for lattice-based actors"""
+
+    UNSPECIFIED = 0
+    EVENTUAL = 1
+    CAUSAL = 2
+    READ_COMMITTED = 3
+    LINEARIZABLE = 4
+
+
+class ActorVisibility(betterproto.Enum):
+    """
+    Request to spawn an actor on a specific remote node (Erlang spawn/4 equivalent)
+
+     ## Purpose
+     Spawns an actor on a specified remote node using pre-deployed actor type.
+     Returns an ActorRef for location-transparent messaging.
+
+     ## Erlang Philosophy
+     In Erlang:
+     ```erlang
+     % Local spawn (current node)
+     Pid = spawn(Module, Function, Args)
+
+     % Remote spawn (specific node)
+     Pid = spawn(Node, Module, Function, Args)
+     ```
+     - Node: Target node (atom, e.g., 'worker@host1')
+     - Module: Pre-compiled module on remote node (e.g., 'gen_server')
+     - Function: Exported function to run (e.g., 'start_link')
+     - Args: Arguments to function (e.g., [initial_state])
+     - Returns: Pid that works for local and remote sends (location transparent)
+
+     ## PlexSpaces Approach
+     ```rust
+     // Local spawn (current node)
+     let actor = node.spawn_actor("worker", state, config).await?;
+
+     // Remote spawn (specific node)
+     let actor_ref = node.spawn_remote("node2", "worker", state, config).await?;
+     ```
+     - target_node_id: Target node (string, e.g., "node2")
+     - actor_type: Pre-deployed actor type on remote node (string, e.g., "worker")
+     - initial_state: Serialized initial state (bytes)
+     - config: Actor configuration
+     - Returns: ActorRef in format "actor_id@node_id" for location-transparent messaging
+
+     ## Key Assumptions (Erlang-Compatible)
+     1. **Code Pre-Deployed**: The actor_type must already exist on the target node
+        - Like Erlang: Module must be loaded on remote node
+        - Use CreateActor first to deploy actor type, or ensure it's in node's registry
+     2. **Location Transparency**: Returned ActorRef works the same for local and remote sends
+        - Like Erlang: Pid works for both local send (Pid ! Msg) and remote send
+        - ActorRef.tell() / ActorRef.ask() automatically routes to correct node
+
+     ## Extensibility for WASM (Future - Week 11-12)
+     Phase 6 will add dynamic WASM deployment support via reserved fields:
+     ```protobuf
+     oneof code_source {
+       string actor_type = 2;        // Pre-deployed type (current)
+       WasmModule wasm_module = 10;  // Deploy WASM on-the-fly (future)
+       string wasm_url = 11;         // Fetch WASM from URL (future)
+     }
+     ```
+     This enables:
+     - **Pre-deployed**: spawn_remote("node2", "worker", ...) - code already on node2
+     - **Dynamic WASM**: spawn_remote_wasm("node2", wasm_bytes, ...) - deploy code + spawn
+     - **URL-based**: spawn_remote_url("node2", "https://cdn/worker.wasm", ...) - fetch + deploy + spawn
+
+     ## Use Cases
+     1. **Distributed Testing**: Spawn Byzantine generals on specific nodes
+        ```rust
+        for (i, node) in nodes.iter().enumerate() {
+            node.spawn_remote(&node.id, "general", state, config).await?;
+        }
+        ```
+     2. **Load Distribution**: Explicitly place workers across cluster
+        ```rust
+        let worker_node = pick_least_loaded_node();
+        worker_node.spawn_remote(&worker_node.id, "worker", state, config).await?;
+        ```
+     3. **Data Locality**: Spawn actor near data source
+        ```rust
+        let db_node = find_node_with_shard(shard_id);
+        db_node.spawn_remote(&db_node.id, "processor", state, config).await?;
+        ```
+     4. **Affinity**: Co-locate related actors on same node
+        ```rust
+        let parent_node = get_actor_node(&parent_id);
+        parent_node.spawn_remote(&parent_node.id, "child", state, config).await?;
+        ```
+
+     ## Comparison to CreateActor
+     | Feature | CreateActor | SpawnActor |
+     |---------|-------------|------------------|
+     | Node selection | Placement strategy / current node | Explicit target node |
+     | Use case | General actor creation | Explicit remote placement |
+     | Fallback | Can fall back to other nodes | Fails if target unavailable |
+     | Erlang equivalent | spawn/3 (local) | spawn/4 (remote) |
+     | Code deployment | Any node can have code | Target node must have code |
+
+     ## Implementation Flow
+     When node1 calls SpawnRemoteActor targeting node2:
+     1. node1 validates target_node_id exists in registry
+     2. node1 sends gRPC SpawnRemoteActor request to node2
+     3. node2 validates actor_type exists in local registry
+     4. node2 spawns actor locally: Actor::spawn(actor_type, state, config)
+     5. node2 returns ActorRef with format "actor-123@node2"
+     6. node1 caches remote ActorRef for future messaging
+     7. Subsequent tell/ask automatically routes via gRPC to node2
+
+     Who may invoke tell/ask on the spawned actor (enforced in ActorRef).
+     UNSPECIFIED is treated as PUBLIC by the runtime.
+    """
+
+    UNSPECIFIED = 0
+    PUBLIC = 1
+    """Any tenant and namespace may message this actor."""
+
+    PROTECTED = 2
+    """
+    Only callers in the same tenant_id may message; namespace may differ within the tenant.
+    """
+
+    PRIVATE = 3
+    """Only callers matching both tenant_id and namespace may message."""
+
+
+class MonitorType(betterproto.Enum):
+    """
+    / Monitor type (distinguishes Monitor from Link)
+    /
+    / ## Purpose
+    / Distinguishes between one-way monitoring (Monitor) and two-way death propagation (Link).
+    / This enables clear API separation and proper handling of each type.
+    /
+    / ## Erlang Philosophy
+    / - **MONITOR**: One-way notification (Erlang `monitor/2`)
+    /   - Supervisor gets notified when actor dies
+    /   - Supervisor does NOT die when actor dies
+    /   - Used for observability, health checks
+    /
+    / - **LINK**: Two-way death propagation (Erlang `link/1`)
+    /   - If actor1 dies, actor2 automatically dies (cascading)
+    /   - If actor2 dies, actor1 automatically dies (cascading)
+    /   - Used for tight coupling, supervision trees
+    /
+    / ## Design Notes
+    / - Monitors remain separate (existing functionality)
+    / - Links enable cascading failures (new functionality)
+    / - Supervision uses links internally (cohesive design)
+    """
+
+    UNSPECIFIED = 0
+    MONITOR = 1
+    """/ One-way monitoring (get notified, don't die)"""
+
+    LINK = 2
+    """/ Two-way link (die together, cascading failures)"""
+
+
+class LifecycleEventType(betterproto.Enum):
+    """Lifecycle event types for filtering"""
+
+    UNSPECIFIED = 0
+    CREATED = 1
+    STARTING = 2
+    ACTIVATED = 3
+    DEACTIVATING = 4
+    DEACTIVATED = 5
+    TERMINATED = 6
+    FAILED = 7
+    MIGRATING = 8
+
+
+class DropPolicy(betterproto.Enum):
+    """Drop policy for buffer overflow (JavaNOW-inspired backpressure)"""
+
+    UNSPECIFIED = 0
+    DROP_OLDEST = 1
+    DROP_NEWEST = 2
+    BLOCK = 3
+
+
+class ActorRefErrorCode(betterproto.Enum):
+    """ActorRef error codes"""
+
+    UNSPECIFIED = 0
+    ACTOR_NOT_FOUND = 1
+    SEND_FAILED = 2
+    MAILBOX_FULL = 3
+    ACTOR_TERMINATED = 4
+    TIMEOUT = 5
+    REMOTE_NOT_IMPLEMENTED = 6
+
+
+class ResourceProfile(betterproto.Enum):
+    """
+    Resource profile for an actor
+     Indicates what type of resources the actor primarily consumes
+    """
+
+    UNSPECIFIED = 0
+    CPU_INTENSIVE = 1
+    MEMORY_INTENSIVE = 2
+    IO_INTENSIVE = 3
+    NETWORK_INTENSIVE = 4
+    BALANCED = 5
+
+
+class ResourceViolationCode(betterproto.Enum):
+    """Resource violation error codes"""
+
+    UNSPECIFIED = 0
+    CPU_EXCEEDED = 1
+    MEMORY_EXCEEDED = 2
+    IO_EXCEEDED = 3
+    NETWORK_EXCEEDED = 4
+
+
+class ActorHealthStatus(betterproto.Enum):
+    """Actor health status"""
+
+    UNSPECIFIED = 0
+    HEALTHY = 1
+    DEGRADED = 2
+    STUCK = 3
+    FAILED = 4
+
+
+@dataclass(eq=False, repr=False)
+class ExitReasonDetails(betterproto.Message):
+    """Exit reason details (for EXIT_REASON_ERROR and EXIT_REASON_LINKED)"""
+
+    error_message: str = betterproto.string_field(1)
+    """Error message (for EXIT_REASON_ERROR)"""
+
+    linked_actor_id: str = betterproto.string_field(2)
+    """Linked actor ID (for EXIT_REASON_LINKED)"""
+
+    linked_reason: "ExitReason" = betterproto.enum_field(3)
+    """Linked actor's exit reason (for EXIT_REASON_LINKED)"""
+
+
+@dataclass(eq=False, repr=False)
+class Actor(betterproto.Message):
+    """
+    Actor instance representation.
+
+     ## Purpose
+     Defines the complete state of a durable actor instance including its
+     identity, lifecycle state, configuration, resource usage, and attached capabilities.
+
+     ## Why This Exists
+     - Actors are the fundamental unit of computation in PlexSpaces (Pillar 2: Erlang/OTP)
+     - Supports durable actors that survive restarts (Pillar 3: Restate durability)
+     - Enables resource-aware scheduling (Quickwit-inspired resource contracts)
+     - Provides facet extensibility (Static vs Dynamic principle)
+     - Tracks metrics for monitoring and health checks
+
+     ## Design Notes
+     - actor_id uses ActorId from common.proto for consistency across services
+     - state tracks lifecycle for supervision and recovery logic
+     - node_id and vm_id support distributed placement and Firecracker isolation
+     - facets enable dynamic capability composition without changing core proto
+     - metrics enable health monitoring and auto-scaling decisions
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    actor_type: str = betterproto.string_field(2)
+    state: "ActorState" = betterproto.enum_field(3)
+    node_id: str = betterproto.string_field(4)
+    vm_id: str = betterproto.string_field(5)
+    actor_state: bytes = betterproto.bytes_field(6)
+    metadata: "__common_v1__.Metadata" = betterproto.message_field(7)
+    config: "ActorConfig" = betterproto.message_field(8)
+    metrics: "ActorMetrics" = betterproto.message_field(9)
+    facets: List["__common_v1__.Facet"] = betterproto.message_field(10)
+    """
+    FACET EXTENSIBILITY: Attached facets provide additional capabilities
+     Examples: virtual_actor, otp_genserver, otp_supervisor, durable_execution, workflow
+    """
+
+    actor_state_schema_version: int = betterproto.uint32_field(12)
+    """
+    Schema version of actor_state serialization for format evolution
+    
+     ## Purpose
+     Enables safe actor state evolution across deployments and restarts.
+     Actors may be inactive for extended periods (days/weeks/months) and must
+     safely load old state when reactivated with newer actor code.
+    
+     ## Why This Exists
+     - Actor state schemas evolve over time (new fields, removed fields, type changes)
+     - Actors persist state to disk via checkpoints (see journaling.proto)
+     - Actors may migrate between nodes with different code versions
+     - Loading incompatible state causes corruption or panics
+     - Prevents data loss during rolling upgrades
+    
+     ## Version Rules
+     - **Version 0** = unversioned (assume version 1, best-effort deserialization)
+     - **Version >= 1** = explicit schema version tracked with actor state
+     - **Same version** (e.g., both v2) → Load directly, no migration needed
+     - **Older version** (state v1, actor v2) → Attempt migration if migration exists, else reject
+     - **Newer version** (state v3, actor v2) → **REJECT** with error (upgrade actor code first)
+    
+     ## Migration Strategy
+     ```
+     Version 1 → 2: Add new field with default value (backward compatible, no migration)
+     Version 2 → 3: Remove deprecated field (backward compatible, no migration)
+     Version 3 → 4: Change field type (BREAKING - requires explicit migration function)
+     Version 4 → 5: Restructure nested fields (BREAKING - requires migration)
+     ```
+    
+     ## Example Usage
+     ```rust
+     // Actor implementation defines current schema version
+     impl CounterActor {
+         const SCHEMA_VERSION: u32 = 2;
+    
+         fn save_state(&self) -> Result<Actor, PersistenceError> {
+             Ok(Actor {
+                 actor_id: self.id.clone(),
+                 actor_state: serialize(&self.internal_state)?,
+                 actor_state_schema_version: Self::SCHEMA_VERSION,
+                 // ... other fields ...
+             })
+         }
+    
+         fn load_state(actor: &Actor) -> Result<Self, PersistenceError> {
+             // Version compatibility check
+             match actor.actor_state_schema_version {
+                 // Same version - direct load
+                 v if v == Self::SCHEMA_VERSION => {
+                     let state: CounterState = deserialize(&actor.actor_state)?;
+                     Ok(Self::from_state(state))
+                 }
+    
+                 // Older version - migrate forward
+                 v if v < Self::SCHEMA_VERSION => {
+                     let migrated = migrate_counter_state(
+                         &actor.actor_state,
+                         v,
+                         Self::SCHEMA_VERSION,
+                     )?;
+                     let state: CounterState = deserialize(&migrated)?;
+                     Ok(Self::from_state(state))
+                 }
+    
+                 // Newer version - reject (cannot load future state)
+                 v => Err(PersistenceError::IncompatibleSchemaVersion {
+                     actor_version: Self::SCHEMA_VERSION,
+                     state_version: v,
+                     message: format!(
+                         "Actor state v{} is newer than actor code v{}. Upgrade actor first.",
+                         v, Self::SCHEMA_VERSION
+                     ),
+                 }),
+             }
+         }
+     }
+     ```
+    
+     ## Integration with Checkpointing
+     This field works in conjunction with `Checkpoint.state_schema_version` from journaling.proto:
+     - **Actor.actor_state_schema_version**: Version of in-memory actor state (current)
+     - **Checkpoint.state_schema_version**: Version of checkpointed actor state (persistent)
+    
+     When creating checkpoint:
+     ```rust
+     let checkpoint = Checkpoint {
+         actor_id: actor.actor_id.clone(),
+         state_data: actor.actor_state.clone(),
+         state_schema_version: actor.actor_state_schema_version,  // Copy version
+         // ...
+     };
+     ```
+    
+     ## See Also
+     - `proto/plexspaces/v1/journaling.proto` - Checkpoint.state_schema_version (lines 241-321)
+     - `docs/SCHEMA_VERSIONING_REVIEW.md` - Complete versioning strategy
+     - Migration registry pattern for centralized v1→v2→v3 transitions
+    """
+
+    error_message: str = betterproto.string_field(13)
+    """
+    Error message when actor is in FAILED state
+    
+     ## Purpose
+     Provides error details when actor.state == ACTOR_STATE_FAILED.
+     Used for debugging, logging, and supervisor restart decisions.
+    
+     ## Usage
+     - Only populated when state == ACTOR_STATE_FAILED
+     - Empty string when state != ACTOR_STATE_FAILED
+     - Contains error message from actor crash or failure
+    """
+
+    namespace: str = betterproto.string_field(14)
+    """
+    Namespace for this actor's data isolation.
+     When actor is part of an application deployment, namespace must match application namespace.
+     Source of truth for namespace is the application (when deploying) or actor creation request.
+    """
+
+    name: str = betterproto.string_field(15)
+    """
+    User-specified actor name. Together with actor_type, namespace, and node_id
+     this forms the structured ActorId.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ActorConfig(betterproto.Message):
+    """Actor configuration"""
+
+    mailbox_timeout: timedelta = betterproto.message_field(1)
+    max_mailbox_size: int = betterproto.uint32_field(2)
+    enable_persistence: bool = betterproto.bool_field(3)
+    checkpoint_interval: timedelta = betterproto.message_field(4)
+    restart_policy: "__common_v1__.RetryPolicy" = betterproto.message_field(5)
+    supervision_strategy: "__supervision_v1__.SupervisionStrategy" = (
+        betterproto.enum_field(6)
+    )
+    properties: Dict[str, "betterproto_lib_google_protobuf.Any"] = (
+        betterproto.map_field(7, betterproto.TYPE_STRING, betterproto.TYPE_MESSAGE)
+    )
+    stateless_worker_config: "StatelessWorkerConfig" = betterproto.message_field(11)
+    """Orleans-inspired stateless worker configuration"""
+
+    data_parallel_config: "DataParallelConfig" = betterproto.message_field(12)
+    """Data-parallel configuration (if part of a shard group)"""
+
+    state_management_mode: "StateMgmtMode" = betterproto.enum_field(13)
+    """State management mode (traditional vs lattice-based)"""
+
+    consistency_level: "ConsistencyLevel" = betterproto.enum_field(14)
+    """Consistency level for lattice-based actors"""
+
+    resource_requirements: "ActorResourceRequirements" = betterproto.message_field(16)
+    """Resource-aware scheduling: Actor resource requirements"""
+
+    actor_groups: List[str] = betterproto.string_field(17)
+    """Shard group IDs (for task routing and co-scheduling)"""
+
+    config_schema_version: int = betterproto.uint32_field(15)
+    """
+    Schema version of properties map for configuration evolution
+    
+     ## Purpose
+     Enables safe evolution of actor configuration across deployments.
+     The `properties` map (field 7) contains opaque configuration that may
+     change as actor types evolve, requiring versioning for compatibility.
+    
+     ## Why This Exists
+     - Actor configuration schemas evolve (new config options, deprecated settings)
+     - Actors may be created with old config and reactivated with new code
+     - Configuration migration needed during rolling upgrades
+     - Prevents invalid configuration causing actor startup failures
+    
+     ## Version Rules
+     - **Version 0** = unversioned (assume version 1)
+     - **Version >= 1** = explicit config schema version
+     - **Same version** → Use config directly
+     - **Older version** → Migrate config forward (e.g., add new defaults, remove deprecated)
+     - **Newer version** → REJECT (upgrade actor code first)
+    
+     ## Example Migration
+     ```rust
+     // Version 1: Simple timeout config
+     properties: {"timeout_ms": 5000}
+    
+     // Version 2: Added retry config (backward compatible)
+     properties: {
+         "timeout_ms": 5000,
+         "max_retries": 3,      // NEW: defaults to 3
+         "retry_backoff_ms": 100 // NEW: defaults to 100ms
+     }
+    
+     // Migration v1→v2: Add defaults for new fields
+     fn migrate_config_v1_to_v2(config: &mut ActorConfig) {
+         config.properties.entry("max_retries").or_insert(Any::from(3u32));
+         config.properties.entry("retry_backoff_ms").or_insert(Any::from(100u32));
+         config.config_schema_version = 2;
+     }
+     ```
+    
+     ## See Also
+     - `Actor.actor_state_schema_version` - For actor state versioning
+     - `docs/SCHEMA_VERSIONING_REVIEW.md` - Complete versioning strategy
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ResourceRequirements(betterproto.Message):
+    """Resource requirements for placement"""
+
+    min_memory_mb: int = betterproto.uint64_field(1)
+    min_cpu_cores: float = betterproto.double_field(2)
+    required_capabilities: List[str] = betterproto.string_field(3)
+    custom_requirements: Dict[str, str] = betterproto.map_field(
+        4, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+
+
+@dataclass(eq=False, repr=False)
+class ActorResourceRequirements(betterproto.Message):
+    """
+    Actor placement for resource-aware scheduling. Single source for labels, affinity, and resources.
+     Scheduler (crates/scheduler) uses placement.required_labels and placement.resource_requirements to select nodes.
+    """
+
+    placement: "NodePlacement" = betterproto.message_field(1)
+    """
+    Unified placement (strategy, required_labels, resource_requirements, preferred/avoid node IDs)
+    """
+
+
+@dataclass(eq=False, repr=False)
+class StatelessWorkerConfig(betterproto.Message):
+    """Stateless worker configuration (Orleans-inspired)"""
+
+    max_instances: int = betterproto.uint32_field(1)
+    """Maximum number of concurrent instances"""
+
+    min_instances: int = betterproto.uint32_field(2)
+    """Minimum number of instances to keep warm"""
+
+    strategy: "LoadBalancingStrategy" = betterproto.enum_field(3)
+    """Load balancing strategy"""
+
+
+@dataclass(eq=False, repr=False)
+class DataParallelConfig(betterproto.Message):
+    """
+    Data-parallel (shard group) strategy; same for all shards in the group.
+     Shard identity is implicit (index in ShardGroup.shard_actor_ids), not stored per-actor.
+    """
+
+    group_id: str = betterproto.string_field(1)
+    """Shard group ID"""
+
+    shard_count: int = betterproto.uint32_field(2)
+    """Number of shards in the group (1 to 1 billion)"""
+
+    partition_strategy: "PartitionStrategy" = betterproto.enum_field(4)
+    """Partitioning strategy"""
+
+    rebalance_policy: "RebalancePolicy" = betterproto.enum_field(5)
+    """Rebalancing policy"""
+
+    placement: "NodePlacement" = betterproto.message_field(6)
+    """
+    Node placement for multi-node leader-worker (same_node, from_registry, node_ids)
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ShardGroup(betterproto.Message):
+    """
+    Shard group: unified config (DataParallelConfig) plus actor refs and state.
+    """
+
+    config: "DataParallelConfig" = betterproto.message_field(1)
+    """
+    Strategy for the group (group_id, shard_count, partition_strategy, rebalance_policy, placement)
+    """
+
+    actor_type: str = betterproto.string_field(2)
+    shard_actor_ids: List[str] = betterproto.string_field(3)
+    state: "ShardGroupState" = betterproto.enum_field(4)
+    created_at: datetime = betterproto.message_field(5)
+    metadata: Dict[str, str] = betterproto.map_field(
+        6, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    rebalance_status: "RebalanceStatus" = betterproto.message_field(7)
+
+
+@dataclass(eq=False, repr=False)
+class RebalanceStatus(betterproto.Message):
+    """Rebalancing status for shard groups"""
+
+    is_rebalancing: bool = betterproto.bool_field(1)
+    """Is currently rebalancing"""
+
+    old_shard_count: int = betterproto.uint32_field(2)
+    """Old shard count (before rebalancing)"""
+
+    new_shard_count: int = betterproto.uint32_field(3)
+    """New shard count (after rebalancing)"""
+
+    progress_percent: float = betterproto.double_field(4)
+    """Progress (0.0 to 100.0)"""
+
+    started_at: datetime = betterproto.message_field(5)
+    """When rebalancing started"""
+
+    estimated_completion: datetime = betterproto.message_field(6)
+    """Estimated completion time"""
+
+
+@dataclass(eq=False, repr=False)
+class NodePlacement(betterproto.Message):
+    """
+    Unified node placement: strategy, affinity, and resource requirements.
+     Replaces PlacementHint, PlacementPreferences, and label/placement fields on ActorResourceRequirements.
+     Scheduler (crates/scheduler) matches nodes using required_labels and resource_requirements.
+    """
+
+    strategy: "NodePlacementStrategy" = betterproto.enum_field(1)
+    cluster: str = betterproto.string_field(2)
+    """
+    For FROM_REGISTRY: optional cluster name filter (empty = all connected nodes)
+    """
+
+    node_ids: List[str] = betterproto.string_field(3)
+    """For NODE_IDS: explicit node IDs to place shards on (round-robin)"""
+
+    required_labels: Dict[str, str] = betterproto.map_field(
+        4, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    Node must match all labels (Kubernetes-inspired). Used by scheduler for node selection.
+    """
+
+    avoid_node_ids: List[str] = betterproto.string_field(5)
+    """Avoid node IDs (anti-affinity; scheduler excludes these)"""
+
+    resource_requirements: "__common_v1__.ResourceSpec" = betterproto.message_field(6)
+    """
+    CPU, memory, disk, GPU requirements. Scheduler filters by NodeCapacity.available.
+    """
+
+    affinity_labels: Dict[str, str] = betterproto.map_field(
+        7, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    Affinity labels (co-location hint; scheduler may prefer nodes with matching labels)
+    """
+
+
+@dataclass(eq=False, repr=False)
+class CreateShardGroupRequest(betterproto.Message):
+    config: "DataParallelConfig" = betterproto.message_field(1)
+    """
+    Group strategy (group_id, shard_count, partition_strategy, rebalance_policy, placement)
+     Use config.placement.required_labels for node placement; scheduler matches nodes by placement.
+    """
+
+    actor_type: str = betterproto.string_field(2)
+    shard_config: "ActorConfig" = betterproto.message_field(3)
+    """
+    Per-shard ActorConfig (optional data_parallel_config here is ignored; use config above)
+    """
+
+    initial_state: bytes = betterproto.bytes_field(4)
+    metadata: Dict[str, str] = betterproto.map_field(
+        5, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+
+
+@dataclass(eq=False, repr=False)
+class CreateShardGroupResponse(betterproto.Message):
+    group: "ShardGroup" = betterproto.message_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class DeleteShardGroupRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    force: bool = betterproto.bool_field(2)
+    shutdown_timeout: timedelta = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class GetShardGroupRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class GetShardGroupResponse(betterproto.Message):
+    group: "ShardGroup" = betterproto.message_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class ListShardGroupsRequest(betterproto.Message):
+    actor_type: str = betterproto.string_field(1)
+    state: "ShardGroupState" = betterproto.enum_field(2)
+    page: "__common_v1__.PageRequest" = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class ListShardGroupsResponse(betterproto.Message):
+    groups: List["ShardGroup"] = betterproto.message_field(1)
+    page: "__common_v1__.PageResponse" = betterproto.message_field(2)
+
+
+@dataclass(eq=False, repr=False)
+class SendToShardRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    partition_key: bytes = betterproto.bytes_field(2)
+    message: "__common_v1__.Message" = betterproto.message_field(3)
+    wait_for_response: bool = betterproto.bool_field(4)
+    timeout: timedelta = betterproto.message_field(5)
+
+
+@dataclass(eq=False, repr=False)
+class SendToShardResponse(betterproto.Message):
+    shard_id: int = betterproto.uint32_field(1)
+    shard_actor_id: str = betterproto.string_field(2)
+    response: "__common_v1__.Message" = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class ScatterGatherRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    query: "__common_v1__.Message" = betterproto.message_field(2)
+    timeout: timedelta = betterproto.message_field(3)
+    aggregation: "ShardGroupAggregationStrategy" = betterproto.enum_field(4)
+    min_responses: int = betterproto.uint32_field(5)
+
+
+@dataclass(eq=False, repr=False)
+class ShardQueryResponse(betterproto.Message):
+    shard_id: int = betterproto.uint32_field(1)
+    shard_actor_id: str = betterproto.string_field(2)
+    response: "__common_v1__.Message" = betterproto.message_field(3)
+    latency: timedelta = betterproto.message_field(4)
+    success: bool = betterproto.bool_field(5)
+    error: str = betterproto.string_field(6)
+
+
+@dataclass(eq=False, repr=False)
+class ScatterGatherStats(betterproto.Message):
+    shards_queried: int = betterproto.uint32_field(1)
+    shards_responded: int = betterproto.uint32_field(2)
+    shards_failed: int = betterproto.uint32_field(3)
+    max_latency: timedelta = betterproto.message_field(4)
+
+
+@dataclass(eq=False, repr=False)
+class ScatterGatherResponse(betterproto.Message):
+    result: "__common_v1__.Message" = betterproto.message_field(1)
+    shard_responses: List["ShardQueryResponse"] = betterproto.message_field(2)
+    stats: "ScatterGatherStats" = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class BulkUpdateShardGroupRequest(betterproto.Message):
+    """
+    Bulk update: send update messages to multiple shards (DPA UpdateFunction)
+     Inspired by NSDI'22 Data-Parallel Actors paper
+    """
+
+    group_id: str = betterproto.string_field(1)
+    """Group to update"""
+
+    updates: Dict[str, "__common_v1__.Message"] = betterproto.map_field(
+        2, betterproto.TYPE_STRING, betterproto.TYPE_MESSAGE
+    )
+    """
+    Update messages: partition_key -> message
+     Messages will be routed to appropriate shards based on partition_key
+    """
+
+    consistency_level: "ConsistencyLevel" = betterproto.enum_field(3)
+    """Consistency level for updates"""
+
+    timeout: timedelta = betterproto.message_field(4)
+    """Timeout for updates"""
+
+    wait_for_responses: bool = betterproto.bool_field(5)
+    """Wait for responses (true = wait for all, false = fire-and-forget)"""
+
+
+@dataclass(eq=False, repr=False)
+class BulkUpdateShardGroupResponse(betterproto.Message):
+    updates_sent: int = betterproto.uint32_field(1)
+    """Number of updates sent"""
+
+    updates_succeeded: int = betterproto.uint32_field(2)
+    """Number of successful updates"""
+
+    updates_failed: int = betterproto.uint32_field(3)
+    """Number of failed updates"""
+
+    shard_stats: List["ShardUpdateStats"] = betterproto.message_field(4)
+    """Per-shard statistics"""
+
+    errors: List[str] = betterproto.string_field(5)
+    """Errors (if any)"""
+
+
+@dataclass(eq=False, repr=False)
+class ShardUpdateStats(betterproto.Message):
+    shard_id: int = betterproto.uint32_field(1)
+    shard_actor_id: str = betterproto.string_field(2)
+    updates_sent: int = betterproto.uint32_field(3)
+    updates_succeeded: int = betterproto.uint32_field(4)
+    updates_failed: int = betterproto.uint32_field(5)
+
+
+@dataclass(eq=False, repr=False)
+class MapShardGroupRequest(betterproto.Message):
+    """
+    Map: apply function to all shards in parallel (DPA Map operator)
+     Inspired by NSDI'22 Data-Parallel Actors paper
+    """
+
+    group_id: str = betterproto.string_field(1)
+    """Group to map over"""
+
+    map_function: "__common_v1__.Message" = betterproto.message_field(2)
+    """Map function message (sent to each shard)"""
+
+    timeout: timedelta = betterproto.message_field(3)
+    """Timeout for map operation"""
+
+    min_responses: int = betterproto.uint32_field(4)
+    """Minimum number of shards that must respond (0 = all required)"""
+
+
+@dataclass(eq=False, repr=False)
+class MapShardGroupResponse(betterproto.Message):
+    shard_results: List["ShardQueryResponse"] = betterproto.message_field(1)
+    """Mapped results from each shard"""
+
+    stats: "ScatterGatherStats" = betterproto.message_field(2)
+    """Statistics"""
+
+
+@dataclass(eq=False, repr=False)
+class CollectiveTargetField(betterproto.Message):
+    value_path: str = betterproto.string_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class BroadcastShardGroupRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    message: "__common_v1__.Message" = betterproto.message_field(2)
+    timeout: timedelta = betterproto.message_field(3)
+    min_acks: int = betterproto.uint32_field(4)
+
+
+@dataclass(eq=False, repr=False)
+class BroadcastShardGroupResponse(betterproto.Message):
+    shard_responses: List["ShardQueryResponse"] = betterproto.message_field(1)
+    stats: "ScatterGatherStats" = betterproto.message_field(2)
+
+
+@dataclass(eq=False, repr=False)
+class ReduceShardGroupRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    map_function: "__common_v1__.Message" = betterproto.message_field(2)
+    timeout: timedelta = betterproto.message_field(3)
+    min_responses: int = betterproto.uint32_field(4)
+    reduction: "CollectiveReduction" = betterproto.enum_field(5)
+    target: "CollectiveTargetField" = betterproto.message_field(6)
+
+
+@dataclass(eq=False, repr=False)
+class ReduceShardGroupResponse(betterproto.Message):
+    result: "__common_v1__.Message" = betterproto.message_field(1)
+    shard_responses: List["ShardQueryResponse"] = betterproto.message_field(2)
+    stats: "ScatterGatherStats" = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class AllReduceShardGroupRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    map_function: "__common_v1__.Message" = betterproto.message_field(2)
+    timeout: timedelta = betterproto.message_field(3)
+    min_responses: int = betterproto.uint32_field(4)
+    reduction: "CollectiveReduction" = betterproto.enum_field(5)
+    target: "CollectiveTargetField" = betterproto.message_field(6)
+
+
+@dataclass(eq=False, repr=False)
+class AllReduceShardGroupResponse(betterproto.Message):
+    result: "__common_v1__.Message" = betterproto.message_field(1)
+    shard_responses: List["ShardQueryResponse"] = betterproto.message_field(2)
+    stats: "ScatterGatherStats" = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class BarrierShardGroupRequest(betterproto.Message):
+    group_id: str = betterproto.string_field(1)
+    barrier_id: str = betterproto.string_field(2)
+    round: int = betterproto.uint64_field(3)
+    timeout: timedelta = betterproto.message_field(4)
+    min_acks: int = betterproto.uint32_field(5)
+
+
+@dataclass(eq=False, repr=False)
+class BarrierShardGroupResponse(betterproto.Message):
+    shard_responses: List["ShardQueryResponse"] = betterproto.message_field(1)
+    stats: "ScatterGatherStats" = betterproto.message_field(2)
+
+
+@dataclass(eq=False, repr=False)
+class ScaleShardGroupRequest(betterproto.Message):
+    """Scale shard group (add/remove shards with rebalancing)"""
+
+    group_id: str = betterproto.string_field(1)
+    """Group to scale"""
+
+    new_shard_count: int = betterproto.uint32_field(2)
+    """New shard count"""
+
+    rebalance_policy: "RebalancePolicy" = betterproto.enum_field(3)
+    """Rebalancing policy"""
+
+    new_shard_config: "ActorConfig" = betterproto.message_field(4)
+    """Configuration for new shards (if scaling up)"""
+
+
+@dataclass(eq=False, repr=False)
+class ScaleShardGroupResponse(betterproto.Message):
+    group: "ShardGroup" = betterproto.message_field(1)
+    """Updated shard group"""
+
+    rebalance_status: "RebalanceStatus" = betterproto.message_field(2)
+    """Rebalancing status"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorMetrics(betterproto.Message):
+    """Actor performance metrics"""
+
+    messages_processed: int = betterproto.uint64_field(1)
+    messages_failed: int = betterproto.uint64_field(2)
+    average_processing_time: timedelta = betterproto.message_field(3)
+    restarts: int = betterproto.uint64_field(4)
+    last_activity: datetime = betterproto.message_field(5)
+    memory_usage_bytes: int = betterproto.uint64_field(6)
+    cpu_usage_percent: float = betterproto.double_field(7)
+
+
+@dataclass(eq=False, repr=False)
+class SpawnActorRequest(betterproto.Message):
+    spec: "ActorSpawnSpec" = betterproto.message_field(1)
+    """
+    Full spawn contract: identity, role, namespace, tenant_id, behavior_kind, args, facets, labels, config, visibility.
+    """
+
+    namespace: str = betterproto.string_field(2)
+    """
+    Optional namespace override for this RPC only.
+     If non-empty, the server merges this into spec.namespace for the spawn operation; if empty, spec.namespace is used.
+    """
+
+    instances_count: int = betterproto.uint32_field(3)
+    """
+    Number of identical replicas to spawn (default: 1 when 0).
+     When > 1, spawns N actors with auto-generated instance names derived from spec.identity.name (prefix pattern).
+    """
+
+
+@dataclass(eq=False, repr=False)
+class SpawnActorResponse(betterproto.Message):
+    """
+    Response from SpawnActor
+
+     ## Purpose
+     Returns reference to newly spawned actor on the node receiving the request.
+
+     ## Design Notes
+     - actor_ref: String in format "actor_id@target_node_id"
+       - Can be used immediately for tell/ask operations
+       - Location transparent - same API as local actors
+       - Example: "actor-abc123@node2"
+     - actor: Full Actor details for inspection
+       - Contains state, config, metrics, etc.
+       - Useful for monitoring and debugging
+    """
+
+    actor_ref: str = betterproto.string_field(1)
+    """
+    Reference to spawned actor (format: "actor_id@node_id")
+     Example: "general-1@node2", "worker-abc@prod-7"
+     Use this for messaging: actor_ref.tell(msg), actor_ref.ask(msg)
+    """
+
+    actor: "Actor" = betterproto.message_field(2)
+    """
+    Full actor details (state, config, metrics)
+     Useful for inspection and monitoring
+    """
+
+
+@dataclass(eq=False, repr=False)
+class SpawnActorsRequest(betterproto.Message):
+    requests: List["SpawnActorRequest"] = betterproto.message_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class SpawnActorResult(betterproto.Message):
+    success: bool = betterproto.bool_field(1)
+    error: str = betterproto.string_field(2)
+    response: "SpawnActorResponse" = betterproto.message_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class SpawnActorsResponse(betterproto.Message):
+    results: List["SpawnActorResult"] = betterproto.message_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class GetActorRequest(betterproto.Message):
+    """Request to get an actor"""
+
+    actor_id: str = betterproto.string_field(1)
+    namespace: str = betterproto.string_field(2)
+    """Namespace for tenant isolation (tenant_id from JWT)"""
+
+
+@dataclass(eq=False, repr=False)
+class GetActorResponse(betterproto.Message):
+    actor: "Actor" = betterproto.message_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class ListActorsRequest(betterproto.Message):
+    """Request to list actors"""
+
+    page_request: "__common_v1__.PageRequest" = betterproto.message_field(1)
+    actor_type: str = betterproto.string_field(2)
+    state: "ActorState" = betterproto.enum_field(3)
+    node_id: str = betterproto.string_field(4)
+    namespace: str = betterproto.string_field(5)
+    """
+    Namespace for tenant isolation (tenant_id from JWT)
+     Only actors in this namespace will be returned
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ListActorsResponse(betterproto.Message):
+    actors: List["Actor"] = betterproto.message_field(1)
+    page_response: "__common_v1__.PageResponse" = betterproto.message_field(2)
+
+
+@dataclass(eq=False, repr=False)
+class SendMessageRequest(betterproto.Message):
+    """Request to send a message via tell semantics"""
+
+    namespace: str = betterproto.string_field(1)
+    """
+    Namespace (extracted from path: /api/v1/actors/{namespace}/{actor_type})
+    """
+
+    actor_type: str = betterproto.string_field(2)
+    """
+    Actor type or actor id to target.
+     If this value contains '@', it is treated as a direct actor id first.
+    """
+
+    http_method: str = betterproto.string_field(3)
+    """Optional HTTP method metadata for gateway-originated requests."""
+
+    payload: bytes = betterproto.bytes_field(4)
+    """Request payload bytes."""
+
+    headers: Dict[str, str] = betterproto.map_field(
+        5, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """Request headers or message metadata."""
+
+    query_params: Dict[str, str] = betterproto.map_field(
+        6, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """Query parameters from HTTP requests."""
+
+    path: str = betterproto.string_field(7)
+    """Full request path for gateway-originated requests."""
+
+    subpath: str = betterproto.string_field(8)
+    """Remaining path segment after actor_type."""
+
+    sender_id: str = betterproto.string_field(9)
+    """Optional sender actor id for remoting and tracing."""
+
+    message_type: str = betterproto.string_field(10)
+    """Optional application or transport message type."""
+
+    correlation_id: str = betterproto.string_field(11)
+    """Optional correlation id preserved for remoting."""
+
+    reply_to: str = betterproto.string_field(12)
+    """Optional reply_to preserved for remoting."""
+
+    message_id: str = betterproto.string_field(13)
+    """Optional client-provided message id."""
+
+    actor_name: str = betterproto.string_field(20)
+    """
+    Optional actor instance name. When set together with actor_type and namespace,
+     the handler constructs the canonical actor ID directly:
+       actor_name//actor_type::namespace@node_id
+     This avoids ambiguous lookups and makes addressing explicit.
+     If empty, falls back to registry lookup by actor_type within the namespace.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class SendMessageResponse(betterproto.Message):
+    success: bool = betterproto.bool_field(1)
+    message_id: str = betterproto.string_field(2)
+    actor_id: str = betterproto.string_field(3)
+    error_message: str = betterproto.string_field(4)
+
+
+@dataclass(eq=False, repr=False)
+class StreamMessageRequest(betterproto.Message):
+    """Request for streaming messages (high-throughput)"""
+
+    message: "__common_v1__.Message" = betterproto.message_field(1)
+    sequence: int = betterproto.uint64_field(2)
+    """Sequence number for ordering (client-generated)"""
+
+
+@dataclass(eq=False, repr=False)
+class StreamMessageResponse(betterproto.Message):
+    """Response for streaming messages"""
+
+    message_id: str = betterproto.string_field(1)
+    sequence: int = betterproto.uint64_field(2)
+    """Acknowledgement of sequence number"""
+
+    status: str = betterproto.string_field(3)
+    """Status: "delivered", "failed", "queued"""
+
+    error: str = betterproto.string_field(4)
+    """Optional error message"""
+
+
+@dataclass(eq=False, repr=False)
+class DeleteActorRequest(betterproto.Message):
+    """Request to delete actor"""
+
+    actor_id: str = betterproto.string_field(1)
+    force: bool = betterproto.bool_field(2)
+    namespace: str = betterproto.string_field(3)
+    """Namespace for tenant isolation (tenant_id from JWT)"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorLifecycleEvent(betterproto.Message):
+    """
+    Actor lifecycle event
+
+     ## Purpose
+     Represents a state transition in an actor's lifecycle. Used for monitoring,
+     observability, and triggering supervision actions.
+
+     ## Architecture Context
+     - Emitted by Actor implementation when state changes occur
+     - Consumed by Node for monitoring callbacks
+     - Consumed by observability systems (metrics, tracing, logging)
+     - Enables location-transparent monitoring (Erlang-style)
+
+     ## Design Decisions
+     - Proto-based for distributed type safety across nodes
+     - event_type as oneof for type-safe event variants
+     - Timestamp for event ordering and time-travel debugging
+     - Extensible for future event types without breaking changes
+
+     ## Usage
+     ```rust
+     // Actor emits event
+     let event = ActorLifecycleEvent {
+         actor_id: "worker@node1".to_string(),
+         timestamp: Some(Timestamp::now()),
+         event_type: Some(actor_lifecycle_event::EventType::Terminated(
+             ActorTerminated { reason: "normal".to_string() }
+         )),
+     };
+     node.handle_lifecycle_event(event).await?;
+     ```
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    """Actor that emitted this event"""
+
+    timestamp: datetime = betterproto.message_field(2)
+    """When event occurred"""
+
+    created: "ActorCreated" = betterproto.message_field(10, group="event_type")
+    starting: "ActorStarting" = betterproto.message_field(11, group="event_type")
+    activated: "ActorActivated" = betterproto.message_field(12, group="event_type")
+    deactivating: "ActorDeactivating" = betterproto.message_field(
+        13, group="event_type"
+    )
+    deactivated: "ActorDeactivated" = betterproto.message_field(14, group="event_type")
+    terminated: "ActorTerminated" = betterproto.message_field(15, group="event_type")
+    failed: "ActorFailed" = betterproto.message_field(16, group="event_type")
+    migrating: "ActorMigrating" = betterproto.message_field(17, group="event_type")
+
+
+@dataclass(eq=False, repr=False)
+class ActorCreated(betterproto.Message):
+    """
+    Actor created (construction complete, not yet started)
+
+     ## Purpose
+     Emitted after Actor::new() completes successfully.
+
+     ## State Transition
+     [none] -> Created
+
+     ## Supervisor Action
+     None (waiting for activation)
+    """
+
+    pass
+
+
+@dataclass(eq=False, repr=False)
+class ActorStarting(betterproto.Message):
+    """
+    Actor starting (spawning message processing task)
+
+     ## Purpose
+     Emitted when Actor::start() is called, before tokio::spawn().
+
+     ## State Transition
+     Created -> Starting
+
+     ## Supervisor Action
+     None (normal startup)
+    """
+
+    pass
+
+
+@dataclass(eq=False, repr=False)
+class ActorActivated(betterproto.Message):
+    """
+    Actor activated (ready to process messages)
+
+     ## Purpose
+     Emitted after actor's message loop starts and on_activate() hook completes.
+
+     ## State Transition
+     Starting -> Activated
+
+     ## Supervisor Action
+     None (actor running normally)
+    """
+
+    pass
+
+
+@dataclass(eq=False, repr=False)
+class ActorDeactivating(betterproto.Message):
+    """
+    Actor deactivating (graceful shutdown initiated)
+
+     ## Purpose
+     Emitted when actor receives shutdown signal or supervisor requests stop.
+
+     ## State Transition
+     Activated -> Deactivating
+
+     ## Supervisor Action
+     None (expected shutdown)
+    """
+
+    reason: str = betterproto.string_field(1)
+    """
+    Why deactivation was initiated
+     Examples: "supervisor_shutdown", "manual_stop", "timeout_idle"
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ActorDeactivated(betterproto.Message):
+    """
+    Actor deactivated (shutdown complete, but not destroyed)
+
+     ## Purpose
+     Emitted after on_deactivate() hook completes. Actor can be reactivated.
+
+     ## State Transition
+     Deactivating -> Deactivated
+
+     ## Supervisor Action
+     None (actor cleanly stopped, can be restarted if needed)
+    """
+
+    reason: str = betterproto.string_field(1)
+    """Why deactivation occurred"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorTerminated(betterproto.Message):
+    """
+    Actor terminated (permanently stopped, not restartable)
+
+     ## Purpose
+     Emitted when actor's task completes normally (loop exits without error).
+     Triggers monitoring callbacks (NotifyActorDown).
+
+     ## State Transition
+     Activated|Deactivating -> Terminated
+
+     ## Supervisor Action
+     - If restart strategy allows, restart actor
+     - Notify all monitors (local + remote via NotifyActorDown RPC)
+
+     ## Design Notes
+     - reason="normal": Graceful shutdown completed
+     - reason="shutdown": Supervisor-initiated shutdown
+     - reason="killed": Forcefully terminated
+    """
+
+    reason: str = betterproto.string_field(1)
+    """
+    Termination reason
+     "normal": Graceful shutdown
+     "shutdown": Supervisor-initiated
+     "killed": Forcefully terminated
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ActorFailed(betterproto.Message):
+    """
+    Actor failed (crashed, needs supervision action)
+
+     ## Purpose
+     Emitted when actor's task panics or returns error. Triggers supervision
+     restart logic and monitoring callbacks.
+
+     ## State Transition
+     Activated -> Failed
+
+     ## Supervisor Action
+     - Apply restart strategy (OneForOne, OneForAll, RestForOne)
+     - Notify all monitors with error details
+     - Increment failure counter for escalation
+
+     ## Design Notes
+     - error: Full panic/error message for debugging
+     - Supervision tree decides whether to restart based on restart strategy
+    """
+
+    error: str = betterproto.string_field(1)
+    """
+    Error/panic message
+     Examples:
+     - "panic: index out of bounds"
+     - "error: timeout waiting for response"
+     - "error: connection refused"
+    """
+
+    stack_trace: str = betterproto.string_field(2)
+    """Optional: Stack trace for debugging"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorMigrating(betterproto.Message):
+    """
+    Actor migrating (moving to different node)
+
+     ## Purpose
+     Emitted when mobile agent starts migration to another node.
+
+     ## State Transition
+     Activated -> Migrating
+
+     ## Supervisor Action
+     - Update actor location in registry
+     - If migration fails, restart on original node
+
+     ## Design Notes
+     - target_node: Destination node address (e.g., "node2")
+     - Future: Add migration_id for tracking migration progress
+    """
+
+    target_node: str = betterproto.string_field(1)
+    """Target node where actor is migrating"""
+
+
+@dataclass(eq=False, repr=False)
+class MonitorActorRequest(betterproto.Message):
+    """
+    Request to monitor an actor (Erlang-style)
+
+     ## Purpose
+     Establishes a monitor from `supervisor_id` to `actor_id` on the **node that hosts
+     `actor_id`**. When that actor terminates, that node runs termination handling and
+     delivers a `__DOWN__` **mailbox message** to `supervisor_id` (same Erlang semantics
+     as `{'DOWN', Ref, process, Pid, Reason}`), routing remotely via `ActorService` when
+     the supervisor lives on another node.
+
+     ## Erlang Philosophy
+     Equivalent to: Ref = erlang:monitor(process, Pid)
+     Works the same for local and remote processes (location transparent).
+
+     ## Design Notes
+     - actor_id: Canonical actor ID for the actor to monitor
+     - supervisor_id: Canonical actor ID of the process that receives `__DOWN__` in its mailbox
+     - supervisor_callback: **Reserved / wire compatibility.** The Rust server implementation
+       does not use this field today; DOWN is sent with `ActorRegistry::tell` to `supervisor_id`.
+       Clients should still populate it per validation (e.g. supervisor node's ActorService URL)
+       for forward compatibility with a possible push-style callback path.
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    supervisor_id: str = betterproto.string_field(2)
+    supervisor_callback: str = betterproto.string_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class MonitorActorResponse(betterproto.Message):
+    """
+    Response to MonitorActor request
+
+     ## Purpose
+     Returns a monitor reference that can be used to demonitor in future.
+
+     ## Erlang Philosophy
+     Equivalent to the Ref returned by erlang:monitor(process, Pid).
+
+     ## Design Notes
+     - monitor_ref: Unique ID for this monitoring link (ULID)
+     - Can be used for future demonitor() operation
+    """
+
+    monitor_ref: str = betterproto.string_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class DemonitorActorRequest(betterproto.Message):
+    """
+    Request to remove a monitor (Erlang demonitor/1 equivalent)
+
+     ## Purpose
+     Cancels a monitor previously established via MonitorActor on the node that hosts
+     the **monitored** actor (`actor_id`). The caller must supply the same `monitor_ref`
+     returned by MonitorActor.
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    supervisor_id: str = betterproto.string_field(2)
+    monitor_ref: str = betterproto.string_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class ActorDownNotification(betterproto.Message):
+    """
+    Notification that a monitored actor has terminated
+
+     ## Purpose
+     Sent by the node hosting the actor to the supervisor when actor terminates.
+     This is an internal message, not typically sent by user code.
+
+     ## Erlang Philosophy
+     Equivalent to receiving: {'DOWN', Ref, process, Pid, Reason}
+     Supervisor receives this asynchronously when monitored actor exits.
+
+     ## Design Notes
+     - actor_id: The actor that terminated
+     - supervisor_id: The supervisor that was monitoring (for routing)
+     - reason: Why actor terminated:
+       - "normal": Graceful shutdown
+       - "shutdown": Supervisor-initiated shutdown
+       - "killed": Forcefully terminated
+       - Error message: Crash reason (e.g., "panic: index out of bounds")
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    supervisor_id: str = betterproto.string_field(2)
+    reason: str = betterproto.string_field(3)
+    monitor_ref: str = betterproto.string_field(4)
+    """
+    Monitor reference ULID correlating with the original monitor() call.
+     Allows the monitoring actor to identify which monitor fired when monitoring multiple actors.
+    """
+
+    is_link_signal: bool = betterproto.bool_field(5)
+    """
+    When true, this notification is a Link EXIT signal (bidirectional death propagation).
+     The receiving node should kill the supervisor_id actor with a Linked exit reason.
+     When false (default), this is a Monitor DOWN notification delivered to the mailbox.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class GetActorStatesRequest(betterproto.Message):
+    """
+    Request to batch-check actor states — used by stale-monitor GC task
+
+     ## Purpose
+     Efficiently checks the lifecycle state of multiple actors in a single RPC call.
+     Used by the background monitor GC task to detect stale monitor entries for actors
+     that no longer exist on their hosting node.
+    """
+
+    actor_ids: List[str] = betterproto.string_field(1)
+    """List of canonical actor IDs to check"""
+
+
+@dataclass(eq=False, repr=False)
+class GetActorStatesResponse(betterproto.Message):
+    """Response for batch actor state check — uses existing ActorState enum"""
+
+    states: Dict[str, "ActorState"] = betterproto.map_field(
+        1, betterproto.TYPE_STRING, betterproto.TYPE_ENUM
+    )
+    """
+    Map of canonical actor_id -> ActorState (uses existing ActorState enum)
+     ACTOR_STATE_UNSPECIFIED / ACTOR_STATE_TERMINATED / not present = actor not found on this node
+    """
+
+
+@dataclass(eq=False, repr=False)
+class ActorLink(betterproto.Message):
+    """
+    / Actor link for two-way death propagation
+    /
+    / ## Purpose
+    / Represents a link between two actors. When one actor dies, the linked actor
+    / automatically dies (cascading failure). This is the foundation for supervision trees.
+    /
+    / ## Erlang Philosophy
+    / Equivalent to Erlang's `link/1` - creates a bidirectional link between processes.
+    / If either process dies abnormally, the other dies too.
+    /
+    / ## Design Notes
+    / - Links are bidirectional (if A links to B, B is linked to A)
+    / - Links propagate death (if A dies, B dies; if B dies, A dies)
+    / - Links are used internally by supervision (parent-child relationships)
+    / - Links can also be created explicitly via API
+    /
+    / ## Example
+    / ```rust
+    / // Link two actors
+    / node.link("actor-1", "actor-2").await?;
+    /
+    / // If actor-1 dies abnormally, actor-2 automatically dies
+    / // If actor-2 dies abnormally, actor-1 automatically dies
+    / ```
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    """/ First actor in the link"""
+
+    linked_actor_id: str = betterproto.string_field(2)
+    """/ Second actor in the link (bidirectional)"""
+
+    created_at: datetime = betterproto.message_field(3)
+    """/ Link creation timestamp (for observability)"""
+
+    metadata: Dict[str, str] = betterproto.map_field(
+        4, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """/ Metadata (optional, for debugging)"""
+
+
+@dataclass(eq=False, repr=False)
+class LinkActorRequest(betterproto.Message):
+    """
+    / Link two actors (Erlang link/1 equivalent)
+    /
+    / ## Purpose
+    / Creates a bidirectional link between two actors. When one actor dies abnormally,
+    / the linked actor automatically dies (cascading failure).
+    /
+    / ## Erlang Philosophy
+    / Equivalent to Erlang's `link(Pid)` - creates bidirectional link.
+    / If either process dies abnormally, the other dies too.
+    /
+    / ## Design Notes
+    / - Links are bidirectional (if A links to B, B is linked to A)
+    / - Links only propagate abnormal deaths (not "normal" shutdowns)
+    / - Links are used internally by supervision (parent-child relationships)
+    / - Links can be created explicitly via this API
+    /
+    / ## Example
+    / ```rust
+    / // Link two actors
+    / node.link("actor-1", "actor-2").await?;
+    /
+    / // If actor-1 dies abnormally, actor-2 automatically dies
+    / // If actor-2 dies abnormally, actor-1 automatically dies
+    / ```
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    linked_actor_id: str = betterproto.string_field(2)
+
+
+@dataclass(eq=False, repr=False)
+class LinkActorResponse(betterproto.Message):
+    """/ Response to LinkActor request"""
+
+    success: bool = betterproto.bool_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class UnlinkActorRequest(betterproto.Message):
+    """
+    / Unlink two actors (Erlang unlink/1 equivalent)
+    /
+    / ## Purpose
+    / Removes the bidirectional link between two actors. After unlinking,
+    / actors can die independently without cascading failures.
+    /
+    / ## Erlang Philosophy
+    / Equivalent to Erlang's `unlink(Pid)` - removes bidirectional link.
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    linked_actor_id: str = betterproto.string_field(2)
+
+
+@dataclass(eq=False, repr=False)
+class UnlinkActorResponse(betterproto.Message):
+    """/ Response to UnlinkActor request"""
+
+    success: bool = betterproto.bool_field(1)
+
+
+@dataclass(eq=False, repr=False)
+class CheckActorExistsRequest(betterproto.Message):
+    """Request to check if actor exists"""
+
+    actor_id: str = betterproto.string_field(1)
+    """Actor ID to check"""
+
+
+@dataclass(eq=False, repr=False)
+class CheckActorExistsResponse(betterproto.Message):
+    """Response to check actor exists request"""
+
+    exists: bool = betterproto.bool_field(1)
+    """Actor exists (virtual or active)"""
+
+    is_active: bool = betterproto.bool_field(2)
+    """Actor is currently active (in memory)"""
+
+    is_virtual: bool = betterproto.bool_field(3)
+    """Actor has VirtualActorFacet (is virtual)"""
+
+
+@dataclass(eq=False, repr=False)
+class AskReplyRequest(betterproto.Message):
+    """
+    Request to ask an actor via HTTP-like interface (FaaS-style)
+
+     ## Purpose
+     Enables ask-style requests to actors via HTTP GET/POST/PUT routes.
+     The tenant_id, namespace, and actor_type are extracted from the HTTP path.
+
+     ## HTTP Method Handling
+     - GET: Query parameters are converted to JSON and stored in payload as string
+     - POST: Request body becomes payload, HTTP headers become headers map
+    """
+
+    namespace: str = betterproto.string_field(1)
+    """
+    Namespace (extracted from path: /api/v1/actors/{namespace}/{actor_type})
+     Can be empty - defaults to empty string if not provided
+     Tenant ID comes from gRPC auth (JWT middleware) or default config, not from request
+    """
+
+    actor_type: str = betterproto.string_field(2)
+    """
+    Actor type (extracted from path: /api/v1/actors/{namespace}/{actor_type})
+     Used to lookup actors via ActorRegistry discover_actors_by_type
+    """
+
+    http_method: str = betterproto.string_field(3)
+    """HTTP method metadata (GET, POST, or PUT)"""
+
+    payload: bytes = betterproto.bytes_field(4)
+    """
+    Request payload
+     For GET: JSON string of query parameters
+     For POST/PUT: Request body bytes
+    """
+
+    headers: Dict[str, str] = betterproto.map_field(
+        5, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    HTTP headers
+     Converted from HTTP request headers
+    """
+
+    query_params: Dict[str, str] = betterproto.map_field(
+        6, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    Query parameters (for GET requests)
+     Converted to JSON and stored in payload
+    """
+
+    path: str = betterproto.string_field(7)
+    """
+    Full HTTP path for the request (optional)
+     Example: "/api/v1/actors/default/counter/custom/path"
+     Allows actors to perform custom routing based on the complete URL
+    """
+
+    subpath: str = betterproto.string_field(8)
+    """
+    Subpath after the actor_type segment (optional)
+     Example: for "/api/v1/actors/default/counter/metrics/latest"
+              subpath = "metrics/latest"
+     This will be used in future for advanced per-actor routing capabilities.
+    """
+
+    sender_id: str = betterproto.string_field(9)
+    """Optional sender actor id for remoting and tracing."""
+
+    message_type: str = betterproto.string_field(10)
+    """Optional transport message type."""
+
+    correlation_id: str = betterproto.string_field(11)
+    """Optional correlation id preserved for remoting."""
+
+    reply_to: str = betterproto.string_field(12)
+    """Optional reply_to preserved for remoting."""
+
+    message_id: str = betterproto.string_field(13)
+    """Optional client-provided message id."""
+
+    timeout: timedelta = betterproto.message_field(14)
+    """
+    Optional timeout for request-reply (ask) operations.
+     Defaults to 5 seconds if not specified. Use for long-running operations like training.
+     HTTP gateway extracts from ?timeout=30 query parameter (in seconds).
+    """
+
+    actor_name: str = betterproto.string_field(20)
+    """
+    Optional actor instance name. When set together with actor_type and namespace,
+     the handler constructs the canonical actor ID directly:
+       actor_name//actor_type::namespace@node_id
+     If empty, falls back to registry lookup by actor_type within the namespace.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class AskReplyResponse(betterproto.Message):
+    """
+    Response from asking an actor
+
+     ## Purpose
+     Returns the result of an actor ask request.
+    """
+
+    success: bool = betterproto.bool_field(1)
+    """Success status"""
+
+    payload: bytes = betterproto.bytes_field(2)
+    """
+    Response payload (for GET/ask requests)
+     Contains the reply message from actor
+    """
+
+    headers: Dict[str, str] = betterproto.map_field(
+        3, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """Response headers (optional metadata)"""
+
+    actor_id: str = betterproto.string_field(4)
+    """Actor ID that was invoked (format: "actor_id@node_id")"""
+
+    error_message: str = betterproto.string_field(5)
+    """Error message (if success is false)"""
+
+
+@dataclass(eq=False, repr=False)
+class LifecycleEventFilter(betterproto.Message):
+    """
+    Lifecycle event filter for subscribers
+
+     ## Purpose
+     Defines what events a subscriber wants to receive. Supports filtering by:
+     - Event types (Created, Terminated, Failed, etc.)
+     - Actor ID patterns (regex)
+     - Node ID patterns (regex)
+     - Custom tags
+
+     ## Examples
+     ```
+     // Prometheus exporter - only care about actor spawn/terminate for counts
+     EventFilter {
+       event_types: [ACTOR_CREATED, ACTOR_TERMINATED, ACTOR_FAILED]
+     }
+
+     // Tracing system - want all events for specific actor group
+     EventFilter {
+       actor_id_pattern: "worker-.*@node1"
+       event_types: [ACTOR_ACTIVATED, ACTOR_DEACTIVATED]
+     }
+
+     // Monitoring dashboard - all critical events across cluster
+     EventFilter {
+       event_types: [ACTOR_FAILED, ACTOR_MIGRATING]
+     }
+     ```
+    """
+
+    subscription_id: str = betterproto.string_field(1)
+    """
+    Subscription ID (ULID, generated by subscriber)
+     Used for unsubscribe and tracking
+    """
+
+    event_types: List["LifecycleEventType"] = betterproto.enum_field(2)
+    """
+    Event types to receive (empty = all types)
+     Maps to ActorLifecycleEvent.event_type oneof
+    """
+
+    actor_id_pattern: str = betterproto.string_field(3)
+    """
+    Actor ID pattern (regex, empty = all actors)
+     Example: "worker-.*@node1" matches all workers on node1
+    """
+
+    node_id_pattern: str = betterproto.string_field(4)
+    """
+    Node ID pattern (regex, empty = all nodes)
+     Example: "prod-.*" matches all production nodes
+    """
+
+    required_tags: Dict[str, str] = betterproto.map_field(
+        5, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    Custom tags filter (AND logic - event must have all tags)
+     Example: {"env": "production", "team": "platform"}
+    """
+
+    buffer_size: int = betterproto.uint32_field(6)
+    """
+    Buffer size for slow subscriber (default: 1000 events)
+     When buffer full, drop_policy determines behavior
+    """
+
+    drop_policy: "DropPolicy" = betterproto.enum_field(7)
+    """Drop policy when buffer full"""
+
+
+@dataclass(eq=False, repr=False)
+class VirtualActorLifecycle(betterproto.Message):
+    """
+    Virtual Actor Lifecycle (Orleans-inspired)
+
+     ## Purpose
+     Tracks activation/deactivation state for virtual actors (actors that exist virtually,
+     activated on-demand). Virtual actors are always addressable but not always in memory.
+
+     ## When Used
+     Only present when actor has VirtualActorFacet attached (opt-in pattern).
+     Regular actors (explicit creation) don't have this lifecycle tracking.
+
+     ## Design Decision
+     Virtual actor lifecycle is tracked separately from core ActorState to maintain
+     simplicity: core actors are explicit, virtual actors are opt-in via facet.
+
+     ## Example
+     ```protobuf
+     Actor {
+       actor_id: "user-123"
+       state: ACTOR_STATE_INACTIVE  // Virtual actor, not in memory
+       facets: [
+         Facet {
+           type: "virtual_actor"
+           config: {
+             "idle_timeout": "5m",
+             "activation_strategy": "lazy"
+           }
+         }
+       ]
+     }
+     ```
+     Virtual Actor Lifecycle Metadata
+
+     ## Purpose
+     Provides metadata about virtual actor activation/deactivation (timestamps, counts, etc.).
+     This is METADATA only - the actual lifecycle state is tracked in Actor.state (ActorState enum).
+
+     ## Design Decision
+     All actors (virtual or not) use the same ActorState enum for state consistency.
+     VirtualActorLifecycle provides additional metadata useful for virtual actors:
+     - Activation timestamps (for monitoring/debugging)
+     - Activation counts (for metrics)
+     - Idle timeout configuration
+     - Pending message counts
+
+     ## Usage
+     - Actor.state: Source of truth for lifecycle state (CREATING, ACTIVE, INACTIVE, etc.)
+     - VirtualActorLifecycle: Optional metadata for virtual actors only
+    """
+
+    last_activated: datetime = betterproto.message_field(1)
+    """Last time actor was activated (loaded into memory)"""
+
+    last_accessed: datetime = betterproto.message_field(2)
+    """Last time actor received a message or performed an operation"""
+
+    idle_timeout: timedelta = betterproto.message_field(3)
+    """Idle timeout before deactivation (from facet config)"""
+
+    activation_count: int = betterproto.uint32_field(4)
+    """Number of times this actor has been activated"""
+
+    is_activating: bool = betterproto.bool_field(5)
+    """Is currently activating (prevents duplicate activations)"""
+
+    pending_message_count: int = betterproto.uint32_field(6)
+    """
+    Messages queued during activation (processed after activation completes)
+     Note: This is a simplified representation - actual queue is in Node
+    """
+
+
+@dataclass(eq=False, repr=False)
+class VirtualActorConfig(betterproto.Message):
+    """
+    Virtual Actor Configuration (for VirtualActorFacet)
+
+     ## Purpose
+     Configuration for virtual actor behavior (activation strategy, idle timeout, etc.)
+
+     ## Usage
+     This config is stored in the VirtualActorFacet's config map:
+     ```protobuf
+     Facet {
+       type: "virtual_actor"
+       config: {
+         "idle_timeout": "5m",
+         "activation_strategy": "lazy"
+       }
+     }
+     ```
+
+     ## Design Decision
+     Config is stored as string map in Facet (simplicity, flexibility).
+     This message is for documentation and type safety in Rust code.
+    """
+
+    activation_strategy: "__common_v1__.ActivationStrategy" = betterproto.enum_field(1)
+    """Activation strategy (from common.proto)"""
+
+    idle_timeout: timedelta = betterproto.message_field(2)
+    """Idle timeout before deactivation"""
+
+    persist_on_deactivation: bool = betterproto.bool_field(3)
+    """Should actor persist state on deactivation?"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorRefError(betterproto.Message):
+    """ActorRef error message"""
+
+    code: "ActorRefErrorCode" = betterproto.enum_field(1)
+    message: str = betterproto.string_field(2)
+    actor_id: str = betterproto.string_field(3)
+
+
+@dataclass(eq=False, repr=False)
+class ResourceContract(betterproto.Message):
+    """
+    Resource contract for an actor
+     Declares resource requirements and limits upfront
+    """
+
+    max_cpu_percent: float = betterproto.float_field(1)
+    """Maximum CPU usage as percentage (0.0 - 100.0)"""
+
+    max_memory_bytes: int = betterproto.uint64_field(2)
+    """Maximum memory usage in bytes"""
+
+    max_io_ops_per_sec: Optional[int] = betterproto.uint32_field(3, optional=True)
+    """Maximum I/O operations per second"""
+
+    guaranteed_bandwidth_mbps: Optional[int] = betterproto.uint32_field(
+        4, optional=True
+    )
+    """Guaranteed network bandwidth in Mbps"""
+
+    max_execution_time: Optional[timedelta] = betterproto.message_field(
+        5, optional=True
+    )
+    """Maximum execution time per message"""
+
+
+@dataclass(eq=False, repr=False)
+class ResourceUsage(betterproto.Message):
+    """Current resource usage of an actor"""
+
+    cpu_percent: float = betterproto.float_field(1)
+    """Current CPU usage percentage"""
+
+    memory_bytes: int = betterproto.uint64_field(2)
+    """Current memory usage in bytes"""
+
+    io_ops_per_sec: int = betterproto.uint32_field(3)
+    """Current I/O operations per second"""
+
+    network_mbps: int = betterproto.uint32_field(4)
+    """Current network bandwidth in Mbps"""
+
+
+@dataclass(eq=False, repr=False)
+class ResourceViolation(betterproto.Message):
+    """Resource violation error message"""
+
+    code: "ResourceViolationCode" = betterproto.enum_field(1)
+    message: str = betterproto.string_field(2)
+    allowed_value: Optional[float] = betterproto.float_field(3, optional=True)
+    """Allowed value (e.g., max_cpu_percent)"""
+
+    actual_value: Optional[float] = betterproto.float_field(4, optional=True)
+    """Actual value (e.g., current cpu_percent)"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorHealth(betterproto.Message):
+    """Actor health message"""
+
+    status: "ActorHealthStatus" = betterproto.enum_field(1)
+    stuck_since: Optional[timedelta] = betterproto.message_field(2, optional=True)
+    """For STUCK status: how long actor has been stuck"""
+
+    failure_reason: Optional[str] = betterproto.string_field(3, optional=True)
+    """For FAILED status: reason for failure"""
+
+
+@dataclass(eq=False, repr=False)
+class ActorSpawnSpec(betterproto.Message):
+    """
+    Complete specification for spawning or reactivating any actor.
+
+     ## Purpose
+     Single source of truth for all information needed to spawn an actor, whether
+     from TOML app-config, SDK annotations, gRPC, or virtual actor reactivation.
+     Replaces the fragmented triple of (init_config_template, initial_state, labels)
+     and the VirtualActorDefinitionRegistration intermediary.
+
+     ## Design
+     - node_id is NOT included: ActorFactory always resolves local_node_id at spawn time.
+     - tenant_id is overridden from JWT at request time if available.
+     - args map is the canonical user-supplied init payload: becomes "args" key in WASM init().
+     - facets carry the full facet declaration (type, config, priority) verbatim from ChildSpec.
+
+     ## Usage
+     - TOML ChildSpec → ActorSpawnSpec via actor_spawn_spec_from_child_spec()
+     - SDK annotations → ActorSpawnSpec built from behavior + declared facets
+     - VirtualActorMetadata stores ActorSpawnSpec as its spec field
+     - ActorBuilder.from_spec() accepts ActorSpawnSpec
+     - ActorFactory.spawn_actor() accepts ActorSpawnSpec
+    """
+
+    identity: "__common_v1__.ActorIdentity" = betterproto.message_field(1)
+    """
+    Instance name + behavior class (namespace and tenant added in fields below).
+    """
+
+    role: str = betterproto.string_field(2)
+    """
+    Role of the actor within its application (e.g. "worker", "leader").
+     Maps 1:1 to ChildSpec.role (TOML `role` field in [[supervisor.children]]).
+     Used by BehaviorRegistry to dispatch the correct spec when multiple children
+     share the same actor_type (behavior class).
+    """
+
+    namespace: str = betterproto.string_field(3)
+    """Namespace for actor isolation (required at spawn time)."""
+
+    tenant_id: str = betterproto.string_field(4)
+    """
+    Tenant ID for multi-tenancy isolation (empty if auth disabled).
+     Overridden from JWT claims at request time when auth is enabled.
+    """
+
+    visibility: "ActorVisibility" = betterproto.enum_field(5)
+    """
+    Tell/ask isolation for cross-tenant/cross-namespace callers (see ActorVisibility).
+     UNSPECIFIED is treated as PUBLIC.
+    """
+
+    behavior_kind: str = betterproto.string_field(6)
+    """
+    OTP-style behavior kind for logging and observability.
+     Examples: "GenServer", "GenEvent", "GenStateMachine", "Workflow".
+    """
+
+    args: Dict[str, str] = betterproto.map_field(
+        7, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    User-supplied initialization arguments.
+     These become the "args" field in the WASM init() payload so TypeScript/Python/Go
+     actors can read them via host.config("initial_count"), etc.
+     Also used by Rust embedded actors as configuration.
+    """
+
+    facets: List["__common_v1__.Facet"] = betterproto.message_field(8)
+    """
+    Facet declarations attached to this actor.
+     Carries virtual_actor, durability, timer, etc. facets verbatim from ChildSpec.
+     ActorFactory instantiates these at spawn time via create_facets_from_config().
+    """
+
+    labels: Dict[str, str] = betterproto.map_field(
+        9, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """Observability labels propagated to metrics and traces."""
+
+    config: "ActorConfig" = betterproto.message_field(10)
+    """
+    Actor runtime configuration (mailbox, restart policy, etc.).
+     Optional — defaults apply when absent.
+    """
+
+    register_in_object_registry: bool = betterproto.bool_field(11)
+    """
+    If true, auto-register this actor in ObjectRegistry on spawn and unregister on stop.
+     Auto-enabled when facets include both "virtual_actor" and "durability".
+    """
+
+    enforce_unique_placement: bool = betterproto.bool_field(12)
+    """
+    If true, enforce unique placement via alias (requires register_in_object_registry=true or auto-enabled).
+     Spawn fails with ACTOR_ERROR_PLACEMENT_CONFLICT if another active instance with same identity exists.
+    """
+
+    placement_strategy: "PlacementStrategy" = betterproto.enum_field(13)
+    """
+    Placement strategy for distributed actor placement (default: PREFER_LOCAL).
+    """
+
+
+class ActorServiceStub(betterproto.ServiceStub):
+    async def spawn_actor(
+        self,
+        spawn_actor_request: "SpawnActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "SpawnActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/SpawnActor",
+            spawn_actor_request,
+            SpawnActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def spawn_actors(
+        self,
+        spawn_actors_request: "SpawnActorsRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "SpawnActorsResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/SpawnActors",
+            spawn_actors_request,
+            SpawnActorsResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def get_actor(
+        self,
+        get_actor_request: "GetActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "GetActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/GetActor",
+            get_actor_request,
+            GetActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def list_actors(
+        self,
+        list_actors_request: "ListActorsRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "ListActorsResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/ListActors",
+            list_actors_request,
+            ListActorsResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def send_message(
+        self,
+        send_message_request: "SendMessageRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "SendMessageResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/SendMessage",
+            send_message_request,
+            SendMessageResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def stream_messages(
+        self,
+        stream_message_request_iterator: Union[
+            AsyncIterable[StreamMessageRequest], Iterable[StreamMessageRequest]
+        ],
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> AsyncIterator[StreamMessageResponse]:
+        async for response in self._stream_stream(
+            "/plexspaces.actor.v1.ActorService/StreamMessages",
+            stream_message_request_iterator,
+            StreamMessageRequest,
+            StreamMessageResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        ):
+            yield response
+
+    async def delete_actor(
+        self,
+        delete_actor_request: "DeleteActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "__common_v1__.Empty":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/DeleteActor",
+            delete_actor_request,
+            __common_v1__.Empty,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def monitor_actor(
+        self,
+        monitor_actor_request: "MonitorActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "MonitorActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/MonitorActor",
+            monitor_actor_request,
+            MonitorActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def demonitor_actor(
+        self,
+        demonitor_actor_request: "DemonitorActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "__common_v1__.Empty":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/DemonitorActor",
+            demonitor_actor_request,
+            __common_v1__.Empty,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def link_actor(
+        self,
+        link_actor_request: "LinkActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "LinkActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/LinkActor",
+            link_actor_request,
+            LinkActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def unlink_actor(
+        self,
+        unlink_actor_request: "UnlinkActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "UnlinkActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/UnlinkActor",
+            unlink_actor_request,
+            UnlinkActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def notify_actor_down(
+        self,
+        actor_down_notification: "ActorDownNotification",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "__common_v1__.Empty":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/NotifyActorDown",
+            actor_down_notification,
+            __common_v1__.Empty,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def check_actor_exists(
+        self,
+        check_actor_exists_request: "CheckActorExistsRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "CheckActorExistsResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/CheckActorExists",
+            check_actor_exists_request,
+            CheckActorExistsResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def get_actor_states(
+        self,
+        get_actor_states_request: "GetActorStatesRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "GetActorStatesResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/GetActorStates",
+            get_actor_states_request,
+            GetActorStatesResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def ask_reply(
+        self,
+        ask_reply_request: "AskReplyRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "AskReplyResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/AskReply",
+            ask_reply_request,
+            AskReplyResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def create_shard_group(
+        self,
+        create_shard_group_request: "CreateShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "CreateShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/CreateShardGroup",
+            create_shard_group_request,
+            CreateShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def delete_shard_group(
+        self,
+        delete_shard_group_request: "DeleteShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "__common_v1__.Empty":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/DeleteShardGroup",
+            delete_shard_group_request,
+            __common_v1__.Empty,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def get_shard_group(
+        self,
+        get_shard_group_request: "GetShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "GetShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/GetShardGroup",
+            get_shard_group_request,
+            GetShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def list_shard_groups(
+        self,
+        list_shard_groups_request: "ListShardGroupsRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "ListShardGroupsResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/ListShardGroups",
+            list_shard_groups_request,
+            ListShardGroupsResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def scale_shard_group(
+        self,
+        scale_shard_group_request: "ScaleShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "ScaleShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/ScaleShardGroup",
+            scale_shard_group_request,
+            ScaleShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def send_to_shard(
+        self,
+        send_to_shard_request: "SendToShardRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "SendToShardResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/SendToShard",
+            send_to_shard_request,
+            SendToShardResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def broadcast_shard_group(
+        self,
+        broadcast_shard_group_request: "BroadcastShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "BroadcastShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/BroadcastShardGroup",
+            broadcast_shard_group_request,
+            BroadcastShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def reduce_shard_group(
+        self,
+        reduce_shard_group_request: "ReduceShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "ReduceShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/ReduceShardGroup",
+            reduce_shard_group_request,
+            ReduceShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def all_reduce_shard_group(
+        self,
+        all_reduce_shard_group_request: "AllReduceShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "AllReduceShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/AllReduceShardGroup",
+            all_reduce_shard_group_request,
+            AllReduceShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def barrier_shard_group(
+        self,
+        barrier_shard_group_request: "BarrierShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "BarrierShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/BarrierShardGroup",
+            barrier_shard_group_request,
+            BarrierShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def scatter_gather(
+        self,
+        scatter_gather_request: "ScatterGatherRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "ScatterGatherResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/ScatterGather",
+            scatter_gather_request,
+            ScatterGatherResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def bulk_update_shard_group(
+        self,
+        bulk_update_shard_group_request: "BulkUpdateShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "BulkUpdateShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/BulkUpdateShardGroup",
+            bulk_update_shard_group_request,
+            BulkUpdateShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def map_shard_group(
+        self,
+        map_shard_group_request: "MapShardGroupRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "MapShardGroupResponse":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.ActorService/MapShardGroup",
+            map_shard_group_request,
+            MapShardGroupResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+
+class LifecycleEventChannelStub(betterproto.ServiceStub):
+    async def subscribe_lifecycle_events(
+        self,
+        lifecycle_event_filter: "LifecycleEventFilter",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> AsyncIterator[ActorLifecycleEvent]:
+        async for response in self._unary_stream(
+            "/plexspaces.actor.v1.LifecycleEventChannel/SubscribeLifecycleEvents",
+            lifecycle_event_filter,
+            ActorLifecycleEvent,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        ):
+            yield response
+
+    async def publish_lifecycle_event(
+        self,
+        actor_lifecycle_event: "ActorLifecycleEvent",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "__common_v1__.Empty":
+        return await self._unary_unary(
+            "/plexspaces.actor.v1.LifecycleEventChannel/PublishLifecycleEvent",
+            actor_lifecycle_event,
+            __common_v1__.Empty,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+
+class ActorServiceBase(ServiceBase):
+
+    async def spawn_actor(
+        self, spawn_actor_request: "SpawnActorRequest"
+    ) -> "SpawnActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def spawn_actors(
+        self, spawn_actors_request: "SpawnActorsRequest"
+    ) -> "SpawnActorsResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def get_actor(
+        self, get_actor_request: "GetActorRequest"
+    ) -> "GetActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def list_actors(
+        self, list_actors_request: "ListActorsRequest"
+    ) -> "ListActorsResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def send_message(
+        self, send_message_request: "SendMessageRequest"
+    ) -> "SendMessageResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def stream_messages(
+        self, stream_message_request_iterator: AsyncIterator[StreamMessageRequest]
+    ) -> AsyncIterator[StreamMessageResponse]:
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+        yield StreamMessageResponse()
+
+    async def delete_actor(
+        self, delete_actor_request: "DeleteActorRequest"
+    ) -> "__common_v1__.Empty":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def monitor_actor(
+        self, monitor_actor_request: "MonitorActorRequest"
+    ) -> "MonitorActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def demonitor_actor(
+        self, demonitor_actor_request: "DemonitorActorRequest"
+    ) -> "__common_v1__.Empty":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def link_actor(
+        self, link_actor_request: "LinkActorRequest"
+    ) -> "LinkActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def unlink_actor(
+        self, unlink_actor_request: "UnlinkActorRequest"
+    ) -> "UnlinkActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def notify_actor_down(
+        self, actor_down_notification: "ActorDownNotification"
+    ) -> "__common_v1__.Empty":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def check_actor_exists(
+        self, check_actor_exists_request: "CheckActorExistsRequest"
+    ) -> "CheckActorExistsResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def get_actor_states(
+        self, get_actor_states_request: "GetActorStatesRequest"
+    ) -> "GetActorStatesResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def ask_reply(
+        self, ask_reply_request: "AskReplyRequest"
+    ) -> "AskReplyResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def create_shard_group(
+        self, create_shard_group_request: "CreateShardGroupRequest"
+    ) -> "CreateShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def delete_shard_group(
+        self, delete_shard_group_request: "DeleteShardGroupRequest"
+    ) -> "__common_v1__.Empty":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def get_shard_group(
+        self, get_shard_group_request: "GetShardGroupRequest"
+    ) -> "GetShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def list_shard_groups(
+        self, list_shard_groups_request: "ListShardGroupsRequest"
+    ) -> "ListShardGroupsResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def scale_shard_group(
+        self, scale_shard_group_request: "ScaleShardGroupRequest"
+    ) -> "ScaleShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def send_to_shard(
+        self, send_to_shard_request: "SendToShardRequest"
+    ) -> "SendToShardResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def broadcast_shard_group(
+        self, broadcast_shard_group_request: "BroadcastShardGroupRequest"
+    ) -> "BroadcastShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def reduce_shard_group(
+        self, reduce_shard_group_request: "ReduceShardGroupRequest"
+    ) -> "ReduceShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def all_reduce_shard_group(
+        self, all_reduce_shard_group_request: "AllReduceShardGroupRequest"
+    ) -> "AllReduceShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def barrier_shard_group(
+        self, barrier_shard_group_request: "BarrierShardGroupRequest"
+    ) -> "BarrierShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def scatter_gather(
+        self, scatter_gather_request: "ScatterGatherRequest"
+    ) -> "ScatterGatherResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def bulk_update_shard_group(
+        self, bulk_update_shard_group_request: "BulkUpdateShardGroupRequest"
+    ) -> "BulkUpdateShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def map_shard_group(
+        self, map_shard_group_request: "MapShardGroupRequest"
+    ) -> "MapShardGroupResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def __rpc_spawn_actor(
+        self, stream: "grpclib.server.Stream[SpawnActorRequest, SpawnActorResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.spawn_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_spawn_actors(
+        self, stream: "grpclib.server.Stream[SpawnActorsRequest, SpawnActorsResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.spawn_actors(request)
+        await stream.send_message(response)
+
+    async def __rpc_get_actor(
+        self, stream: "grpclib.server.Stream[GetActorRequest, GetActorResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.get_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_list_actors(
+        self, stream: "grpclib.server.Stream[ListActorsRequest, ListActorsResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.list_actors(request)
+        await stream.send_message(response)
+
+    async def __rpc_send_message(
+        self, stream: "grpclib.server.Stream[SendMessageRequest, SendMessageResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.send_message(request)
+        await stream.send_message(response)
+
+    async def __rpc_stream_messages(
+        self,
+        stream: "grpclib.server.Stream[StreamMessageRequest, StreamMessageResponse]",
+    ) -> None:
+        request = stream.__aiter__()
+        await self._call_rpc_handler_server_stream(
+            self.stream_messages,
+            stream,
+            request,
+        )
+
+    async def __rpc_delete_actor(
+        self, stream: "grpclib.server.Stream[DeleteActorRequest, __common_v1__.Empty]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.delete_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_monitor_actor(
+        self, stream: "grpclib.server.Stream[MonitorActorRequest, MonitorActorResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.monitor_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_demonitor_actor(
+        self,
+        stream: "grpclib.server.Stream[DemonitorActorRequest, __common_v1__.Empty]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.demonitor_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_link_actor(
+        self, stream: "grpclib.server.Stream[LinkActorRequest, LinkActorResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.link_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_unlink_actor(
+        self, stream: "grpclib.server.Stream[UnlinkActorRequest, UnlinkActorResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.unlink_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_notify_actor_down(
+        self,
+        stream: "grpclib.server.Stream[ActorDownNotification, __common_v1__.Empty]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.notify_actor_down(request)
+        await stream.send_message(response)
+
+    async def __rpc_check_actor_exists(
+        self,
+        stream: "grpclib.server.Stream[CheckActorExistsRequest, CheckActorExistsResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.check_actor_exists(request)
+        await stream.send_message(response)
+
+    async def __rpc_get_actor_states(
+        self,
+        stream: "grpclib.server.Stream[GetActorStatesRequest, GetActorStatesResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.get_actor_states(request)
+        await stream.send_message(response)
+
+    async def __rpc_ask_reply(
+        self, stream: "grpclib.server.Stream[AskReplyRequest, AskReplyResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.ask_reply(request)
+        await stream.send_message(response)
+
+    async def __rpc_create_shard_group(
+        self,
+        stream: "grpclib.server.Stream[CreateShardGroupRequest, CreateShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.create_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_delete_shard_group(
+        self,
+        stream: "grpclib.server.Stream[DeleteShardGroupRequest, __common_v1__.Empty]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.delete_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_get_shard_group(
+        self,
+        stream: "grpclib.server.Stream[GetShardGroupRequest, GetShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.get_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_list_shard_groups(
+        self,
+        stream: "grpclib.server.Stream[ListShardGroupsRequest, ListShardGroupsResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.list_shard_groups(request)
+        await stream.send_message(response)
+
+    async def __rpc_scale_shard_group(
+        self,
+        stream: "grpclib.server.Stream[ScaleShardGroupRequest, ScaleShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.scale_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_send_to_shard(
+        self, stream: "grpclib.server.Stream[SendToShardRequest, SendToShardResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.send_to_shard(request)
+        await stream.send_message(response)
+
+    async def __rpc_broadcast_shard_group(
+        self,
+        stream: "grpclib.server.Stream[BroadcastShardGroupRequest, BroadcastShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.broadcast_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_reduce_shard_group(
+        self,
+        stream: "grpclib.server.Stream[ReduceShardGroupRequest, ReduceShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.reduce_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_all_reduce_shard_group(
+        self,
+        stream: "grpclib.server.Stream[AllReduceShardGroupRequest, AllReduceShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.all_reduce_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_barrier_shard_group(
+        self,
+        stream: "grpclib.server.Stream[BarrierShardGroupRequest, BarrierShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.barrier_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_scatter_gather(
+        self,
+        stream: "grpclib.server.Stream[ScatterGatherRequest, ScatterGatherResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.scatter_gather(request)
+        await stream.send_message(response)
+
+    async def __rpc_bulk_update_shard_group(
+        self,
+        stream: "grpclib.server.Stream[BulkUpdateShardGroupRequest, BulkUpdateShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.bulk_update_shard_group(request)
+        await stream.send_message(response)
+
+    async def __rpc_map_shard_group(
+        self,
+        stream: "grpclib.server.Stream[MapShardGroupRequest, MapShardGroupResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.map_shard_group(request)
+        await stream.send_message(response)
+
+    def __mapping__(self) -> Dict[str, grpclib.const.Handler]:
+        return {
+            "/plexspaces.actor.v1.ActorService/SpawnActor": grpclib.const.Handler(
+                self.__rpc_spawn_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                SpawnActorRequest,
+                SpawnActorResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/SpawnActors": grpclib.const.Handler(
+                self.__rpc_spawn_actors,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                SpawnActorsRequest,
+                SpawnActorsResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/GetActor": grpclib.const.Handler(
+                self.__rpc_get_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                GetActorRequest,
+                GetActorResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/ListActors": grpclib.const.Handler(
+                self.__rpc_list_actors,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ListActorsRequest,
+                ListActorsResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/SendMessage": grpclib.const.Handler(
+                self.__rpc_send_message,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                SendMessageRequest,
+                SendMessageResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/StreamMessages": grpclib.const.Handler(
+                self.__rpc_stream_messages,
+                grpclib.const.Cardinality.STREAM_STREAM,
+                StreamMessageRequest,
+                StreamMessageResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/DeleteActor": grpclib.const.Handler(
+                self.__rpc_delete_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                DeleteActorRequest,
+                __common_v1__.Empty,
+            ),
+            "/plexspaces.actor.v1.ActorService/MonitorActor": grpclib.const.Handler(
+                self.__rpc_monitor_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                MonitorActorRequest,
+                MonitorActorResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/DemonitorActor": grpclib.const.Handler(
+                self.__rpc_demonitor_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                DemonitorActorRequest,
+                __common_v1__.Empty,
+            ),
+            "/plexspaces.actor.v1.ActorService/LinkActor": grpclib.const.Handler(
+                self.__rpc_link_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                LinkActorRequest,
+                LinkActorResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/UnlinkActor": grpclib.const.Handler(
+                self.__rpc_unlink_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                UnlinkActorRequest,
+                UnlinkActorResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/NotifyActorDown": grpclib.const.Handler(
+                self.__rpc_notify_actor_down,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ActorDownNotification,
+                __common_v1__.Empty,
+            ),
+            "/plexspaces.actor.v1.ActorService/CheckActorExists": grpclib.const.Handler(
+                self.__rpc_check_actor_exists,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                CheckActorExistsRequest,
+                CheckActorExistsResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/GetActorStates": grpclib.const.Handler(
+                self.__rpc_get_actor_states,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                GetActorStatesRequest,
+                GetActorStatesResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/AskReply": grpclib.const.Handler(
+                self.__rpc_ask_reply,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                AskReplyRequest,
+                AskReplyResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/CreateShardGroup": grpclib.const.Handler(
+                self.__rpc_create_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                CreateShardGroupRequest,
+                CreateShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/DeleteShardGroup": grpclib.const.Handler(
+                self.__rpc_delete_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                DeleteShardGroupRequest,
+                __common_v1__.Empty,
+            ),
+            "/plexspaces.actor.v1.ActorService/GetShardGroup": grpclib.const.Handler(
+                self.__rpc_get_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                GetShardGroupRequest,
+                GetShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/ListShardGroups": grpclib.const.Handler(
+                self.__rpc_list_shard_groups,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ListShardGroupsRequest,
+                ListShardGroupsResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/ScaleShardGroup": grpclib.const.Handler(
+                self.__rpc_scale_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ScaleShardGroupRequest,
+                ScaleShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/SendToShard": grpclib.const.Handler(
+                self.__rpc_send_to_shard,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                SendToShardRequest,
+                SendToShardResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/BroadcastShardGroup": grpclib.const.Handler(
+                self.__rpc_broadcast_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                BroadcastShardGroupRequest,
+                BroadcastShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/ReduceShardGroup": grpclib.const.Handler(
+                self.__rpc_reduce_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ReduceShardGroupRequest,
+                ReduceShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/AllReduceShardGroup": grpclib.const.Handler(
+                self.__rpc_all_reduce_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                AllReduceShardGroupRequest,
+                AllReduceShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/BarrierShardGroup": grpclib.const.Handler(
+                self.__rpc_barrier_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                BarrierShardGroupRequest,
+                BarrierShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/ScatterGather": grpclib.const.Handler(
+                self.__rpc_scatter_gather,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ScatterGatherRequest,
+                ScatterGatherResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/BulkUpdateShardGroup": grpclib.const.Handler(
+                self.__rpc_bulk_update_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                BulkUpdateShardGroupRequest,
+                BulkUpdateShardGroupResponse,
+            ),
+            "/plexspaces.actor.v1.ActorService/MapShardGroup": grpclib.const.Handler(
+                self.__rpc_map_shard_group,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                MapShardGroupRequest,
+                MapShardGroupResponse,
+            ),
+        }
+
+
+class LifecycleEventChannelBase(ServiceBase):
+
+    async def subscribe_lifecycle_events(
+        self, lifecycle_event_filter: "LifecycleEventFilter"
+    ) -> AsyncIterator[ActorLifecycleEvent]:
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+        yield ActorLifecycleEvent()
+
+    async def publish_lifecycle_event(
+        self, actor_lifecycle_event: "ActorLifecycleEvent"
+    ) -> "__common_v1__.Empty":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def __rpc_subscribe_lifecycle_events(
+        self, stream: "grpclib.server.Stream[LifecycleEventFilter, ActorLifecycleEvent]"
+    ) -> None:
+        request = await stream.recv_message()
+        await self._call_rpc_handler_server_stream(
+            self.subscribe_lifecycle_events,
+            stream,
+            request,
+        )
+
+    async def __rpc_publish_lifecycle_event(
+        self, stream: "grpclib.server.Stream[ActorLifecycleEvent, __common_v1__.Empty]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.publish_lifecycle_event(request)
+        await stream.send_message(response)
+
+    def __mapping__(self) -> Dict[str, grpclib.const.Handler]:
+        return {
+            "/plexspaces.actor.v1.LifecycleEventChannel/SubscribeLifecycleEvents": grpclib.const.Handler(
+                self.__rpc_subscribe_lifecycle_events,
+                grpclib.const.Cardinality.UNARY_STREAM,
+                LifecycleEventFilter,
+                ActorLifecycleEvent,
+            ),
+            "/plexspaces.actor.v1.LifecycleEventChannel/PublishLifecycleEvent": grpclib.const.Handler(
+                self.__rpc_publish_lifecycle_event,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                ActorLifecycleEvent,
+                __common_v1__.Empty,
+            ),
+        }