Crate actr_hyper 

actr-hyper

Hyper — Actor platform layer + runtime infrastructure

Positioning

Hyper is the operating system for Actors: it defines boundaries (Sandbox), provides platform primitives, and carries the full runtime infrastructure (transport, routing, lifecycle management).

An Actor cannot open a database on its own, cannot hold its own private key, and cannot claim to be a certain type — everything must go through Hyper’s controlled interfaces.

Responsibilities

Platform Layer (formerly Hyper)

• Package signature verification (binary_hash + MFR signature)
• Actor bootstrap (registers with AIS on behalf of the Actor, obtains credential)
• Storage namespace isolation (independent SQLite space per Actor)
• Cryptographic primitives (Ed25519 sign/verify, Actor does not hold raw private keys)
• Runtime lifecycle management (ActrNode lifecycle for Executor execution bodies)

Runtime Infrastructure (formerly actr-runtime)

• Actor Lifecycle: system init, node start/stop (ActrNode / ActrRef)
• Message Transport: layered architecture (Wire -> Transport -> Gate -> Dispatch)
• Communication Modes: in-process (zero-copy) and cross-process (WebRTC / WebSocket)
• Message Persistence: SQLite-backed Mailbox (ACID guarantees)
• Observability: logging, distributed tracing (OpenTelemetry, optional feature)
• WASM Engine: WASM actor execution (optional feature)

Architecture Layers

┌─────────────────────────────────────────────────────┐
│  Platform (Hyper)                                   │  AIS Bootstrap
│  Sandbox / Verify / Storage / KeyCache              │  Package Verify
├─────────────────────────────────────────────────────┤
│  Lifecycle Management (ActrNode → ActrRef)
├─────────────────────────────────────────────────────┤
│  Layer 3: Inbound Dispatch                          │  DataStreamRegistry
│           (Fast Path Routing)                       │  MediaFrameRegistry
├─────────────────────────────────────────────────────┤
│  Layer 2: Outbound Adapters (internal)             │  HostGate
│           (Message Sending)                         │  PeerGate
├─────────────────────────────────────────────────────┤
│  Layer 1: Transport                                 │  Lane (core abstraction)
│           (Channel Management)                      │  HostTransport
│                                                     │  PeerTransport
├─────────────────────────────────────────────────────┤
│  Layer 0: Wire                                      │  WebRtcGate
│           (Physical Connections)                     │  WebRtcCoordinator
│                                                     │  SignalingClient
└─────────────────────────────────────────────────────┘

Non-Goals

Hyper does not understand business logic, does not perform business-level message routing, and is unaware of business relationships between Actors. The hyper_send/hyper_recv provided in WASM mode are network I/O primitives; routing decisions are made by the ActrNode running inside the WASM.

Re-exports

pub use config::HyperConfig;

pub use error::HyperError;

pub use ais_client::AisClient;

pub use storage::ActorStore;

pub use verify::ChainTrust;

pub use verify::MfrCertCache;

pub use verify::RegistryTrust;

pub use verify::StaticTrust;

pub use verify::TrustProvider;

pub use observability::ObservabilityGuard;

pub use observability::init_observability;

pub use actr_ref::ActrRef;

pub use lifecycle::CredentialState;

pub use lifecycle::NetworkEventHandle;

pub use transport::NetworkError;

pub use transport::NetworkResult;

pub use wire::AuthConfig;

pub use wire::AuthType;

pub use wire::DisconnectReason;

pub use wire::ReconnectConfig;

pub use wire::SignalingClient;

pub use wire::SignalingConfig;

pub use wire::SignalingEvent;

pub use wire::SignalingStats;

pub use workload::HostAbiFn;

pub use workload::HostOperation;

pub use workload::HostOperationResult;

pub use workload::InvocationContext;

Modules

actr_ref

ActrRef - Lightweight reference to a running Actor

ais_client

AIS HTTP client

config

context

Runtime Context Implementation

error

lifecycle

Lifecycle management layer (non-architectural layer)

observability

Observability module for logging and tracing initialization.

prelude

Convenience prelude module

runtime_error

Runtime error re-exports.

storage

transport

Transport Layer 1: Transport layer

verify

Package verification module.

wire

Wire Layer 0: Physical wire layer

workload

Workload runtime abstractions for guest backends.

Structs

Acl

Access Control List. Evaluation: any matching DENY overrides all ALLOWs. Default policy: deny if no rule matches.

ActrId

ActrType

Attached

Compile-time state marker: a package has been verified and attached; AIS credential still pending.

ExponentialBackoff

Exponential backoff iterator

Hyper

Hyper — pre-workload framework infrastructure.

Init

Compile-time state marker: a Node has been born from a Hyper plus a actr_config::RuntimeConfig, but no attachment path has been chosen yet. Transition to Attached via Node::attach or Node::link.

MailboxStats

Mailbox statistics

MediaSample

Media sample data from WebRTC native track

MessageRecord

Message record retrieved from the queue

Node

Node — Hyper wired to a runtime configuration (and optionally a workload).

PackageManifest

Package manifest, parsed from manifest.toml inside .actr package.

Registered

Compile-time state marker: AIS credential has been obtained and injected; ready to start.

ServiceSpec

VerifiedPackage

Result of a successful package verification.

WebRtcConfig

WebRTC configuration

WorkloadPackage

Public .actr package input object consumed by Hyper.

Enums

ActrError

Top-level framework error, returned to all callers.

BinaryKind

Execution backend selected from a verified .actr package target.

Dest

Destination identifier

ErrorKind

Fault domain classification for any framework error.

MediaType

Media type enum

MessagePriority

Message priority

MessageStatus

Message processing status

PlatformError

Unified error type for platform operations

Traits

Classify

Fault-domain classification for error types.

CryptoProvider

Platform-agnostic cryptography provider

KvStore

Platform-agnostic key-value store trait

Mailbox

Mailbox interface - defines core operations for message persistence

NodeState

Sealed trait describing valid Node lifecycle states.

PlatformProvider

Composite platform provider — the three OS-level services a Hyper needs.

Type Aliases

ActorResult

Result type for actor RPC calls.