plexspaces 0.1.1__py3-none-any.whl

plexspaces/generated/plexspaces/wasm/v1/__init__.py

@@ -0,0 +1,920 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# sources: plexspaces/v1/wasm/wasm.proto
+# plugin: python-betterproto
+# This file has been @generated
+
+from dataclasses import dataclass
+from datetime import (
+    datetime,
+    timedelta,
+)
+from typing import (
+    TYPE_CHECKING,
+    Dict,
+    List,
+    Optional,
+)
+
+import betterproto
+import grpclib
+from betterproto.grpc.grpclib_server import ServiceBase
+
+from ...common import v1 as __common_v1__
+
+if TYPE_CHECKING:
+    import grpclib.server
+    from betterproto.grpc.grpclib_client import MetadataLike
+    from grpclib.metadata import Deadline
+
+
+class WasmErrorCode(betterproto.Enum):
+    """
+    WASM runtime error codes
+
+     ## Purpose
+     Defines error categories for WASM operations. Used for gRPC status codes
+     and error reporting across language boundaries.
+
+     ## Why This Exists
+     - **Proto-First**: Errors are part of the API contract (not Rust-only)
+     - **Multi-Language**: Error types available in all supported languages (TypeScript, Python SDKs)
+     - **gRPC Compatibility**: Maps to gRPC status codes for proper error handling
+     - **Structured Errors**: Clients can handle specific error types programmatically
+
+     ## Design Notes
+     - Error codes are stable (don't reorder or change values)
+     - New error codes can be added at the end
+     - OK = 0 for consistency with gRPC conventions
+    """
+
+    OK = 0
+    """Success (not an error)"""
+
+    COMPILATION_FAILED = 1
+    """
+    Module compilation failed
+    
+     Causes: Invalid WASM bytecode, unsupported features, syntax errors
+     Recovery: Fix WASM module, use compatible toolchain
+    """
+
+    INSTANTIATION_FAILED = 2
+    """
+    Module instantiation failed
+    
+     Causes: Import resolution errors, initialization errors, memory allocation failure
+     Recovery: Check module dependencies, ensure host functions available
+    """
+
+    RESOURCE_LIMIT_EXCEEDED = 3
+    """
+    Resource limit exceeded (memory, fuel, CPU time)
+    
+     Causes: Actor exceeded memory/fuel/time quota
+     Recovery: Increase limits or optimize actor code
+    """
+
+    CAPABILITY_DENIED = 4
+    """
+    Capability denied (missing permission)
+    
+     Causes: Actor attempted unauthorized operation (filesystem, network, spawn)
+     Recovery: Grant capability or remove unauthorized code
+    """
+
+    HOST_FUNCTION_ERROR = 5
+    """
+    Host function call failed
+    
+     Causes: Host function error (send_message failed, tuplespace_write failed)
+     Recovery: Check host function arguments, retry
+    """
+
+    ACTOR_FUNCTION_ERROR = 6
+    """
+    Actor function call failed
+    
+     Causes: Actor's exported function (init, handle_message) threw error or trapped
+     Recovery: Fix actor code, check logs
+    """
+
+    CACHE_ERROR = 7
+    """
+    Module cache error
+    
+     Causes: Cache lookup failed, eviction error, storage backend error
+     Recovery: Retry, check cache backend health
+    """
+
+    HASH_MISMATCH = 8
+    """
+    Module hash mismatch (integrity check failed)
+    
+     Causes: Module bytes corrupted during transfer, malicious modification
+     Recovery: Re-deploy module, check network integrity
+    """
+
+    MODULE_NOT_FOUND = 9
+    """
+    Module not found
+    
+     Causes: Module not deployed, evicted from cache, wrong name/version
+     Recovery: Deploy module first, check name/version
+    """
+
+    SERIALIZATION_ERROR = 10
+    """
+    Serialization/deserialization error
+    
+     Causes: Invalid protobuf, incompatible schema version
+     Recovery: Check message format, ensure compatible versions
+    """
+
+    WASMTIME_ERROR = 11
+    """
+    Internal wasmtime runtime error
+    
+     Causes: wasmtime internal error, runtime bug
+     Recovery: Check logs, report bug, try different wasmtime version
+    """
+
+
+class DeployWasmModuleRequestPreWarmStrategy(betterproto.Enum):
+    """Pre-warm strategy"""
+
+    NONE = 0
+    """No pre-warming - nodes fetch on-demand (lazy)"""
+
+    ANNOUNCE = 1
+    """Announce to all nodes - they decide whether to pre-fetch"""
+
+    PUSH_ALL = 2
+    """Push to all nodes immediately (eager)"""
+
+    PUSH_TAGGED = 3
+    """Push to subset of nodes (e.g., based on tags)"""
+
+
+@dataclass(eq=False, repr=False)
+class HttpFetchRequest(betterproto.Message):
+    """
+    Outbound HTTP request sent by actor-world host.http-fetch.
+
+     The WIT operation keeps link/method/path as typed arguments and exchanges
+     request metadata/body as protobuf bytes so polyglot SDKs can share one model.
+    """
+
+    headers: Dict[str, str] = betterproto.map_field(
+        1, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    Request headers to merge with service-link defaults and auth headers.
+    """
+
+    body: bytes = betterproto.bytes_field(2)
+    """Raw request body bytes."""
+
+
+@dataclass(eq=False, repr=False)
+class HttpFetchResponse(betterproto.Message):
+    """Outbound HTTP response returned by actor-world host.http-fetch."""
+
+    status: int = betterproto.uint32_field(1)
+    """HTTP status code."""
+
+    headers: Dict[str, str] = betterproto.map_field(
+        2, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """Response headers."""
+
+    body: bytes = betterproto.bytes_field(3)
+    """Raw response body bytes."""
+
+
+@dataclass(eq=False, repr=False)
+class WasmModule(betterproto.Message):
+    """
+    WebAssembly module definition
+
+     ## Purpose
+     Represents a compiled WebAssembly module that can be deployed to nodes
+     and instantiated as actors. Modules are immutable and content-addressed
+     for caching and deduplication.
+
+     ## Why This Exists
+     - Enables dynamic code deployment (like Java classloader)
+     - Content-addressed hash allows efficient caching across nodes
+     - Metadata enables version management and dependency tracking
+     - Separation of code (module) and state (actor instance) enables fast migration
+
+     ## Design Notes
+     - `module_bytes` is the compiled WASM binary (Component Model format)
+     - `module_hash` is SHA-256 for cache lookup and verification
+     - `wit_interface` is optional WIT definition for tooling/debugging
+     - Modules are immutable - updates create new versions with different hashes
+    """
+
+    name: str = betterproto.string_field(1)
+    """
+    Module name (e.g., "counter-actor", "chat-room-actor")
+    
+     Used for human-readable identification and registry lookups.
+    """
+
+    version: str = betterproto.string_field(2)
+    """
+    Module version (semantic versioning: "1.2.3")
+    
+     Enables gradual rollout and rollback of actor code.
+    """
+
+    module_bytes: bytes = betterproto.bytes_field(3)
+    """
+    Compiled WebAssembly Component Model bytes
+    
+     This is the actual WASM binary that will be loaded and instantiated.
+     Must be a valid WASM Component Model module (not legacy WASM).
+    """
+
+    module_hash: str = betterproto.string_field(4)
+    """
+    SHA-256 hash of module_bytes (for content-addressable caching)
+    
+     Format: hex-encoded 64-character string
+     Example: "a1b2c3d4e5f6..."
+    
+     Why content-addressed:
+     - Deduplication: Same module hash = same module, cache once
+     - Verification: Ensure module integrity during distribution
+     - Efficient lookup: Nodes can check cache before downloading
+    """
+
+    wit_interface: str = betterproto.string_field(5)
+    """
+    WIT (WebAssembly Interface Types) interface definition (optional)
+    
+     Human-readable interface for tooling, debugging, and documentation.
+     Not required for runtime (Component Model is self-describing).
+    """
+
+    source_languages: List[str] = betterproto.string_field(6)
+    """
+    Supported languages (e.g., "rust", "javascript", "go")
+    
+     Indicates source language for debugging and tooling.
+    """
+
+    metadata: "__common_v1__.Metadata" = betterproto.message_field(7)
+    """
+    Module metadata (tags, labels, annotations)
+    
+     Examples:
+     - tags: ["production", "stateless", "compute-intensive"]
+     - labels: {"team": "backend", "service": "payment"}
+    """
+
+    created_at: datetime = betterproto.message_field(8)
+    """Upload timestamp (when module was first deployed to registry)"""
+
+    size_bytes: int = betterproto.uint64_field(9)
+    """
+    Module size in bytes (uncompressed)
+    
+     Used for bandwidth estimation and pre-warming decisions.
+    """
+
+    version_number: int = betterproto.uint32_field(10)
+    """Schema version for forward/backward compatibility"""
+
+
+@dataclass(eq=False, repr=False)
+class ResourceLimits(betterproto.Message):
+    """
+    Resource limits for WASM actor instances
+
+     ## Purpose
+     Defines resource constraints for WASM actors to prevent resource exhaustion
+     and ensure fair scheduling. Enforced by wasmtime runtime.
+
+     ## Why This Exists
+     - Memory limits prevent OOM crashes (multi-tenant safety)
+     - Fuel metering prevents infinite loops (gas-style execution limits)
+     - Time limits prevent hung actors
+     - Stack limits prevent stack overflow
+
+     ## Design Notes
+     - Limits are per-instance (each actor has own quota)
+     - Fuel is like Ethereum gas - metered during execution
+     - Defaults chosen for balanced workloads (can override per-actor)
+    """
+
+    max_memory_bytes: int = betterproto.uint64_field(1)
+    """
+    Maximum linear memory size in bytes (default: 16MB)
+    
+     WASM linear memory is contiguous, growable.
+     16MB default balances:
+     - Enough for most actors (2MB-8MB typical)
+     - 64 actors per GB of RAM
+     - 32x more efficient than JavaNow (64MB per actor)
+    """
+
+    max_stack_bytes: int = betterproto.uint64_field(2)
+    """
+    Maximum stack size in bytes (default: 512KB)
+    
+     Stack overflow protection. Most actors use < 100KB.
+    """
+
+    max_fuel: int = betterproto.uint64_field(3)
+    """
+    Maximum fuel units (gas-style execution limit)
+    
+     Fuel is consumed during execution (ops, memory access, calls).
+     Default: 10 billion units = ~1 second CPU time
+     Zero = unlimited (not recommended for untrusted code)
+    """
+
+    max_execution_time: timedelta = betterproto.message_field(4)
+    """
+    Maximum execution time per message (optional)
+    
+     If set, actor handler must complete within this duration.
+     Default: None (rely on fuel metering instead)
+    """
+
+    max_table_elements: int = betterproto.uint32_field(5)
+    """
+    Maximum table elements (for indirect calls)
+    
+     Default: 10,000 (enough for most actors)
+    """
+
+    max_pooled_instances: int = betterproto.uint32_field(6)
+    """
+    Maximum number of instances in instance pool
+    
+     For warm start optimization. Default: 10 per actor type.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class WasmCapabilities(betterproto.Message):
+    """
+    WASI capabilities for WASM actors
+
+     ## Purpose
+     Defines what host resources a WASM actor can access. Based on WASI Preview 2
+     capability-based security model.
+
+     ## Why This Exists
+     - **Principle of Least Privilege**: Actors only get capabilities they need
+     - **Facets Pattern Revival**: JavaNow-inspired capability composition
+     - **Security**: Sandboxed actors cannot access unauthorized resources
+     - **Auditing**: Capabilities are explicit and logged
+
+     ## Design Notes
+     - Capabilities are granted at instantiation time (immutable per instance)
+     - WASI capabilities (filesystem, network, clocks) use WASI standard
+     - PlexSpaces capabilities (tuplespace, actors) are custom host functions
+     - Denied by default (opt-in model)
+    """
+
+    allow_filesystem: bool = betterproto.bool_field(1)
+    """
+    Allow filesystem access (WASI filesystem interface)
+    
+     If true, actor can use WASI file operations (open, read, write).
+     Paths are virtualized (actor cannot access arbitrary host paths).
+    """
+
+    filesystem_root: str = betterproto.string_field(2)
+    """
+    Filesystem root path (if filesystem access allowed)
+    
+     Actor's root is mapped to this host path (chroot-style).
+     Example: "/actors/{actor_id}/data"
+    """
+
+    allow_network: bool = betterproto.bool_field(3)
+    """
+    Allow network access (WASI sockets interface)
+    
+     If true, actor can make outbound network connections.
+     Inbound connections not supported (actors receive messages via mailbox).
+    """
+
+    allow_env: bool = betterproto.bool_field(4)
+    """
+    Allow environment variables (WASI environment interface)
+    
+     If true, actor can read environment variables.
+     Useful for configuration (but TupleSpace config preferred).
+    """
+
+    allow_random: bool = betterproto.bool_field(5)
+    """
+    Allow random number generation (WASI random interface)
+    
+     If true, actor can use cryptographically secure random.
+     Generally safe to allow.
+    """
+
+    allow_clocks: bool = betterproto.bool_field(6)
+    """
+    Allow clock access (WASI clocks interface)
+    
+     If true, actor can read monotonic and wall-clock time.
+     Required for timeouts, timestamps.
+    """
+
+    allow_tuplespace: bool = betterproto.bool_field(7)
+    """
+    Allow TupleSpace operations (PlexSpaces-specific)
+    
+     If true, actor can call host functions: tuplespace_write, tuplespace_read, etc.
+     Most actors need this for coordination.
+    """
+
+    allow_spawn_actors: bool = betterproto.bool_field(8)
+    """
+    Allow actor spawning (PlexSpaces-specific)
+    
+     If true, actor can spawn new actors via spawn_actor host function.
+     Useful for supervisor actors, not needed for leaf actors.
+    """
+
+    allow_send_messages: bool = betterproto.bool_field(9)
+    """
+    Allow message sending (PlexSpaces-specific)
+    
+     If true, actor can send messages to other actors via send_message host function.
+     Almost all actors need this (inter-actor communication).
+    """
+
+    allow_logging: bool = betterproto.bool_field(10)
+    """
+    Allow logging (PlexSpaces-specific)
+    
+     If true, actor can emit logs via log host function.
+     Useful for debugging, not required for production actors.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class WasmConfig(betterproto.Message):
+    """
+    WASM actor configuration
+
+     ## Purpose
+     Combines resource limits and capabilities into a complete configuration
+     for instantiating a WASM actor. Can be templated per actor type.
+
+     ## Why This Exists
+     - **Reusable Profiles**: Define once, apply to many actors
+     - **Security Policies**: Enforce organizational security requirements
+     - **Resource Management**: Prevent resource exhaustion
+
+     ## Design Notes
+     - Can create profiles: "untrusted" (minimal caps), "trusted" (full caps)
+     - Immutable after instantiation (cannot escalate privileges)
+    """
+
+    limits: "ResourceLimits" = betterproto.message_field(1)
+    """Resource limits for this actor"""
+
+    capabilities: "WasmCapabilities" = betterproto.message_field(2)
+    """Capabilities granted to this actor"""
+
+    profile_name: str = betterproto.string_field(3)
+    """
+    Configuration name (e.g., "default", "untrusted", "compute-intensive")
+    
+     Allows reusing configurations across actors.
+    """
+
+    enable_pooling: bool = betterproto.bool_field(4)
+    """
+    Enable instance pooling for warm starts
+    
+     If true, pre-instantiate instances for faster spawning.
+     Trade-off: Memory usage vs latency.
+    """
+
+    enable_aot: bool = betterproto.bool_field(5)
+    """
+    Enable ahead-of-time (AOT) compilation
+    
+     If true, compile module to native code on deployment.
+     Trade-off: Deployment time vs execution speed.
+    """
+
+    durability_enabled: bool = betterproto.bool_field(6)
+    """
+    Enable checkpoint/restore durability (load on init, save on terminate).
+    
+     Off by default for performance. When true, actor state is loaded from
+     journal on init and saved on terminate (Cloudflare Durable Objects pattern).
+    """
+
+    use_instance_pool: bool = betterproto.bool_field(7)
+    """
+    Use pre-instantiated instance pool (InstancePool) when spawning actors.
+    
+     On by default. When true, runtime may checkout from a per-module pool instead
+     of instantiating each time (faster spawn when pool has capacity). Requires
+     deploy-path integration; until then, only engine-level pooling (enable_pooling)
+     is active for HTTP/deploy.
+    """
+
+    max_concurrent_instantiations: int = betterproto.uint32_field(8)
+    """
+    Maximum concurrent instantiations (initial + re-instantiation) when pooling is enabled.
+    
+     Limits total concurrent Wasmtime instantiations to avoid hitting Wasmtime's memory-stripe
+     limit (default 10). Per-actor re-instantiation lock serializes per actor; this global cap
+     prevents N actors from re-instantiating at once. Default: 8 (stays under Wasmtime's limit
+     with headroom). Only used when enable_pooling is true.
+    
+     When 0 or not set, uses code default of 8.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class DeployWasmModuleRequest(betterproto.Message):
+    """
+    Deploy WASM module request
+
+     ## Purpose
+     Uploads a WASM module to the cluster registry and optionally pre-warms
+     nodes by pushing the module to their caches.
+
+     ## Why This Exists
+     - **Hybrid Distribution**: Push announces availability, nodes can pull
+     - **Pre-warming**: Reduce cold start latency by pre-fetching modules
+     - **Version Management**: Deploy new versions without disrupting running actors
+
+     ## Design Notes
+     - Module stored in cluster registry (e.g., S3, Redis, etcd)
+     - Nodes notified of new module (can pre-fetch if heuristics match)
+     - Idempotent: Re-deploying same module (same hash) is no-op
+    """
+
+    module: "WasmModule" = betterproto.message_field(1)
+    """WASM module to deploy"""
+
+    pre_warm: "DeployWasmModuleRequestPreWarmStrategy" = betterproto.enum_field(2)
+    """How to distribute module to nodes"""
+
+    target_node_tags: List[str] = betterproto.string_field(3)
+    """
+    Node tags for PUSH_TAGGED strategy (e.g., ["us-east-1", "production"])
+    """
+
+
+@dataclass(eq=False, repr=False)
+class DeployWasmModuleResponse(betterproto.Message):
+    """Deploy WASM module response"""
+
+    success: bool = betterproto.bool_field(1)
+    """Was deployment successful?"""
+
+    module_hash: str = betterproto.string_field(2)
+    """Module hash (for cache lookup)"""
+
+    nodes_pre_warmed: int = betterproto.uint32_field(3)
+    """Number of nodes that received the module (for pre-warming)"""
+
+    error: "WasmError" = betterproto.message_field(4)
+    """
+    Error details if deployment failed (replaces error_message)
+    
+     If deployment succeeded, this field is not set (code = OK).
+     If deployment failed, code indicates failure reason.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class InstantiateActorRequest(betterproto.Message):
+    """
+    Instantiate WASM actor request
+
+     ## Purpose
+     Creates a new actor instance from a deployed WASM module. The instance
+     is initialized with provided state and configuration.
+
+     ## Why This Exists
+     - **Dynamic Actor Creation**: Spawn actors at runtime (like erlang:spawn)
+     - **State Initialization**: Restore actor from snapshot or start fresh
+     - **Configuration Flexibility**: Each actor can have custom config
+
+     ## Design Notes
+     - Module must be deployed first (or node will fetch on-demand)
+     - Initial state is opaque bytes (actor interprets based on module logic)
+     - Config can override module defaults (e.g., more memory for specific actor)
+    """
+
+    module_ref: str = betterproto.string_field(1)
+    """
+    Module name or hash to instantiate
+    
+     Supports both:
+     - Name: "counter-actor@1.2.3" (fetches from registry)
+     - Hash: "a1b2c3d4..." (direct cache lookup)
+    """
+
+    actor_id: str = betterproto.string_field(2)
+    """
+    Actor ID to assign to this instance
+    
+     Format: ULID for sortability (see CLAUDE.md Core Principle 0)
+    """
+
+    initial_state: bytes = betterproto.bytes_field(3)
+    """
+    Initial state bytes (opaque to runtime)
+    
+     Passed to WASM module's init() function.
+     Can be:
+     - Empty (new actor with default state)
+     - Snapshot (restoring actor from checkpoint)
+     - Migration state (actor moving to new node)
+    """
+
+    config: "WasmConfig" = betterproto.message_field(4)
+    """
+    Configuration overrides (optional)
+    
+     If not provided, uses module's default config or system defaults.
+    """
+
+    target_node_id: str = betterproto.string_field(5)
+    """
+    Node ID to instantiate on (optional)
+    
+     If not provided, scheduler chooses node based on load balancing.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class InstantiateActorResponse(betterproto.Message):
+    """Instantiate WASM actor response"""
+
+    success: bool = betterproto.bool_field(1)
+    """Was instantiation successful?"""
+
+    actor_id: str = betterproto.string_field(2)
+    """Actor ID of instantiated actor"""
+
+    node_id: str = betterproto.string_field(3)
+    """Node ID where actor is running"""
+
+    created_at: datetime = betterproto.message_field(4)
+    """Instance creation time"""
+
+    error: "WasmError" = betterproto.message_field(5)
+    """
+    Error details if instantiation failed (replaces error_message)
+    
+     If instantiation succeeded, this field is not set (code = OK).
+     If instantiation failed, code indicates failure reason.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class MigrateActorRequest(betterproto.Message):
+    """
+    Migrate WASM actor request
+
+     ## Purpose
+     Moves a running actor from one node to another. Only state migrates,
+     code (WASM module) is already cached on destination node.
+
+     ## Why This Exists
+     - **Load Balancing**: Move actors to less loaded nodes
+     - **Node Shutdown**: Drain actors before maintenance
+     - **Locality Optimization**: Move actor closer to data
+
+     ## Design Notes
+     - Explicit migration (user-initiated) - simplest approach (User Decision A8)
+     - Code cached everywhere - only state migrates (10ms vs 500ms)
+     - Atomic migration: Source actor paused until destination ready
+    """
+
+    actor_id: str = betterproto.string_field(1)
+    """Actor ID to migrate"""
+
+    source_node_id: str = betterproto.string_field(2)
+    """Source node ID (current location)"""
+
+    target_node_id: str = betterproto.string_field(3)
+    """Destination node ID (target location)"""
+
+    include_journal: bool = betterproto.bool_field(4)
+    """
+    Include journal entries (for durable actors)
+    
+     If true, migrate journal for replay on destination.
+    """
+
+
+@dataclass(eq=False, repr=False)
+class MigrateActorResponse(betterproto.Message):
+    """Migrate WASM actor response"""
+
+    success: bool = betterproto.bool_field(1)
+    """Was migration successful?"""
+
+    migration_time: timedelta = betterproto.message_field(2)
+    """Migration duration (should be < 10ms for state-only)"""
+
+    state_size_bytes: int = betterproto.uint64_field(3)
+    """Size of state transferred (bytes)"""
+
+    error: "WasmError" = betterproto.message_field(4)
+    """Error details if migration failed"""
+
+
+@dataclass(eq=False, repr=False)
+class WasmError(betterproto.Message):
+    """
+    WASM error details
+
+     ## Purpose
+     Provides structured error information for debugging and error handling.
+     Replaces simple string error messages with typed, actionable error data.
+
+     ## Why This Exists
+     - **Debugging**: Details map provides context (module name, actor ID, stack trace)
+     - **Client Handling**: Clients can programmatically handle specific error codes
+     - **Observability**: Error metrics can be tracked by code
+     - **Hash Mismatch**: Special fields for integrity check failures
+
+     ## Design Notes
+     - Compatible with gRPC Status (code + message + details)
+     - Details map is extensible (add any key-value metadata)
+     - expected_hash/actual_hash only populated for HASH_MISMATCH errors
+
+     ## Examples
+     ```
+     WasmError {
+       code: RESOURCE_LIMIT_EXCEEDED,
+       message: "Memory limit exceeded: 18MB > 16MB",
+       details: {
+         "actor_id": "calc-001@node2",
+         "limit": "16777216",
+         "actual": "18874368",
+         "resource": "memory"
+       }
+     }
+     ```
+    """
+
+    code: "WasmErrorCode" = betterproto.enum_field(1)
+    """Error code category"""
+
+    message: str = betterproto.string_field(2)
+    """
+    Human-readable error message
+    
+     Format: Brief description suitable for logging and user display
+     Example: "Module compilation failed: invalid opcode at offset 0x1234"
+    """
+
+    details: Dict[str, str] = betterproto.map_field(
+        3, betterproto.TYPE_STRING, betterproto.TYPE_STRING
+    )
+    """
+    Additional context for debugging
+    
+     Common keys:
+     - "actor_id": Actor that failed
+     - "module_name": Module that failed
+     - "module_hash": Module hash for integrity errors
+     - "stack_trace": Stack trace if available
+     - "resource": Resource type (memory, fuel, cpu_time)
+     - "limit": Resource limit value
+     - "actual": Actual resource usage
+    """
+
+    expected_hash: str = betterproto.string_field(4)
+    """For HASH_MISMATCH: expected hash (SHA-256 hex)"""
+
+    actual_hash: str = betterproto.string_field(5)
+    """For HASH_MISMATCH: actual hash (SHA-256 hex)"""
+
+
+class WasmRuntimeServiceStub(betterproto.ServiceStub):
+    async def deploy_module(
+        self,
+        deploy_wasm_module_request: "DeployWasmModuleRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "DeployWasmModuleResponse":
+        return await self._unary_unary(
+            "/plexspaces.wasm.v1.WasmRuntimeService/DeployModule",
+            deploy_wasm_module_request,
+            DeployWasmModuleResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def instantiate_actor(
+        self,
+        instantiate_actor_request: "InstantiateActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "InstantiateActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.wasm.v1.WasmRuntimeService/InstantiateActor",
+            instantiate_actor_request,
+            InstantiateActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+    async def migrate_actor(
+        self,
+        migrate_actor_request: "MigrateActorRequest",
+        *,
+        timeout: Optional[float] = None,
+        deadline: Optional["Deadline"] = None,
+        metadata: Optional["MetadataLike"] = None
+    ) -> "MigrateActorResponse":
+        return await self._unary_unary(
+            "/plexspaces.wasm.v1.WasmRuntimeService/MigrateActor",
+            migrate_actor_request,
+            MigrateActorResponse,
+            timeout=timeout,
+            deadline=deadline,
+            metadata=metadata,
+        )
+
+
+class WasmRuntimeServiceBase(ServiceBase):
+
+    async def deploy_module(
+        self, deploy_wasm_module_request: "DeployWasmModuleRequest"
+    ) -> "DeployWasmModuleResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def instantiate_actor(
+        self, instantiate_actor_request: "InstantiateActorRequest"
+    ) -> "InstantiateActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def migrate_actor(
+        self, migrate_actor_request: "MigrateActorRequest"
+    ) -> "MigrateActorResponse":
+        raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
+
+    async def __rpc_deploy_module(
+        self,
+        stream: "grpclib.server.Stream[DeployWasmModuleRequest, DeployWasmModuleResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.deploy_module(request)
+        await stream.send_message(response)
+
+    async def __rpc_instantiate_actor(
+        self,
+        stream: "grpclib.server.Stream[InstantiateActorRequest, InstantiateActorResponse]",
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.instantiate_actor(request)
+        await stream.send_message(response)
+
+    async def __rpc_migrate_actor(
+        self, stream: "grpclib.server.Stream[MigrateActorRequest, MigrateActorResponse]"
+    ) -> None:
+        request = await stream.recv_message()
+        response = await self.migrate_actor(request)
+        await stream.send_message(response)
+
+    def __mapping__(self) -> Dict[str, grpclib.const.Handler]:
+        return {
+            "/plexspaces.wasm.v1.WasmRuntimeService/DeployModule": grpclib.const.Handler(
+                self.__rpc_deploy_module,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                DeployWasmModuleRequest,
+                DeployWasmModuleResponse,
+            ),
+            "/plexspaces.wasm.v1.WasmRuntimeService/InstantiateActor": grpclib.const.Handler(
+                self.__rpc_instantiate_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                InstantiateActorRequest,
+                InstantiateActorResponse,
+            ),
+            "/plexspaces.wasm.v1.WasmRuntimeService/MigrateActor": grpclib.const.Handler(
+                self.__rpc_migrate_actor,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                MigrateActorRequest,
+                MigrateActorResponse,
+            ),
+        }