Module client_root 

A native, language-independent client-root capability.

A Hyperactor mesh program has exactly one root client. Rust and Python are alternative bootstrap implementations of that one root, not separate root namespaces; worker ProcAgents host actors but never become client roots.

ClientRootRef is an opaque bearer capability to the root, carried in an actor’s ActorEnvironment and inherited by descendants. Its sole authority is to create or reuse a statically declared, root-owned service through the root ProcAgent’s [EnsureClientRootService] handler.

CROOT invariant registry

• CROOT-1 (singleton binding): the active client bootstrap binds [ClientRootApi] on the program’s one root ProcAgent and stores that exact reference; worker ProcAgents never bind it.
• CROOT-2 (typed API attenuation): ClientRootRef exposes only typed ensure-service authority and no root administration.
• CROOT-3 (single identity): exact name/type/parameter equality returns one cached spawn result; a type or parameter-byte difference for the same name conflicts. The service actor is created under a fresh random instance id, which avoids the predictable collision a name-derived id would create; the create path re-draws the id if it collides with one already present in actor_states.
• CROOT-4 (worker rejection): a worker ProcAgent has no bound client-root handler, so a retyped worker reference reaches an unbound port and cannot create a service.
• CROOT-5 (root ownership): service lifetime belongs to the root ProcAgent, never the requester; a reused reference to a service that has reached a terminal state fails closed rather than returning a dead actor.
• CROOT-6 (validation): a capability absent from the actor environment fails closed — ClientRootRef::from_env returns an error rather than a silent None, before any request is sent.
• CROOT-7 (continuity): each created service receives the same ClientRootRef in its native environment.
• CROOT-8 (runtime neutrality): Rust and Python roots store the same native capability under the same environment key.
• CROOT-9 (map layering): a service’s spawn result and lifecycle live solely in the ProcAgent actor_states registry; the service-identity table records only the (actor type, exact parameter bytes, instance id) a repeat ensure must match. Only ensure writes that table, and only alongside the actor_states entry, so the two never disagree.
• CROOT-10 (attestation boundary): the only explicit attestation restores ActorRef<A> immediately after the erased spawn reply whose requested and recorded actor type was derived from that same A; every other reference is bound or deserialized.
• CROOT-11 (handler resilience): the EnsureClientRootService handler disables undeliverable-return on its reply and always returns Ok(()), reporting every expected failure through the typed reply; a malformed, conflicting, or reply-undeliverable request never faults the root ProcAgent.
• CROOT-12 (crate layering): every client-root type and policy stays in hyperactor_mesh (or a higher composition crate); hyperactor remains a generic attribute carrier with no static mesh dependency.

Structs

ClientRootRef

An opaque bearer capability to the program’s one client root.

ClientRootService

A statically declared, root-owned service: a fixed service name plus a registered actor type A. Callers supply A::Params; there is no caller-supplied runtime actor type or untyped address.

Enums

ClientRootError

A typed failure from a client-root ensure request.

Statics

CLIENT_ROOT

The client-root capability carried in an actor’s environment.