Module proc 

Proc is an addressable actor-runtime boundary.

It owns actor lifecycle (spawn, run, terminate), delivers messages to its local actors, and hosts supervision state. A proc is not a network endpoint by itself: it reaches—and is reached by—other procs through a Gateway, its connectivity boundary (see Proc::gateway). Outbound messages for remote destinations flow through that gateway, which delivers locally, forwards to a known peer, or routes onward. A host attaches all of its procs to one shared gateway.

It also stores bounded snapshots of terminated actors for post-mortem introspection.

Client instance invariants (CI-*)

• CI-1 (client status): IntrospectMessage::Query on an introspectable instance returns status: "client" and actor_type: "()" in attrs.
• CI-2 (snapshot on drop): Dropping the returned Instance<()> transitions its status to terminal, causing the introspect task to store a terminated snapshot.

Actor identity invariants (AI-*)

• AI-1 (named-child uid): Each child gets a globally unique random uid. Named children carry a label for display purposes.
• AI-3 (controller ActorAddr uniqueness): Each named child gets a unique uid; the label is informational only.

Flight recorder span invariants (FR-*)

• FR-1 (recording-span route equivalence): Instance::recording_span() returns a span bound to the same actor-local Recording consumed by handler instrumentation and introspection. Events emitted under that span land in the same flight-recorder ring buffer returned by introspect_payload().
• FR-2 (recording-span rootness): Every span returned by Instance::recording_span() is a fresh root span (parent: None). Ambient tracing context does not cause events emitted under that span to route into a parent actor’s flight recorder.
• FR-3 (fresh-handle, stable-destination): Repeated calls to Instance::recording_span() return distinct span handles, but all target the same underlying actor recording.

Queue depth accounting invariants (PD-5*)

• PD-5a: Per-actor queue depth counts accepted handler work not yet dequeued by the actor loop. Accounting increments in HandlerPorts::get’s enqueue closure before the reorder-buffer decision, so this counter includes both in-order messages waiting in work_rx AND out-of-order messages held in the receiver-local reorder buffer. (Reflected at the introspection layer in IO-3 of the introspect module doc.)
• PD-5b: Queue depth is incremented exactly once per accepted message in the enqueue closure of HandlerPorts::get, before the in-order / out-of-order branch.
• PD-5c: Queue depth is decremented exactly once on every dequeue from work_rx (in the actor run loop).
• PD-5d: Queue depth is intended to be non-negative; tests must cover ordered/buffered delivery paths to validate the accounting.
• PD-5e: queue_depth and the OTel ACTOR_MESSAGE_QUEUE_SIZE counter are two consumers of one accounting path. The account_enqueue / account_dequeue helpers update both together so they cannot drift.

Retained queue-pressure invariants (PD-6 through PD-9)

ProcQueueStats holds proc-level retained evidence of queue pressure. These are runtime-driven (not publish-time sampled) so they capture between-publish bursts.

• PD-6: high_water_mark >= running_total eventually. Because running_total is incremented before high_water_mark is updated, a concurrent reader may transiently observe total > high_water_mark. This is a sampling artifact, not an accounting error.
• PD-7: last_nonzero_age_ms() == None iff proc queue depth has never been non-zero since startup. The timestamp is updated on enqueue and on dequeue when the queue remains non-zero, so it reflects the last observed non-zero state.
• PD-8: transient bursts that drain before publish still update both the high-water mark and the last-nonzero state.
• PD-9: last_nonzero_age_ms() is expected to be non-decreasing during quiet periods, but this is not a hard guarantee — the implementation uses SystemTime (wall clock), which can move backward on NTP adjustments. Callers should treat the age as best-effort telemetry, not a monotonic invariant.

Structs

ActorInstance

Structured return type for Proc::actor_instance.

ActorWorkReceiver

Receiver for actor handler work.

Builder

Builder for constructing a Proc with explicit identity and connectivity.

Context

Context for a message currently being handled by an Instance.

GlobalGateway

Builder state that attaches the proc to the process-wide global gateway.

HandlerPorts

A polymorphic dictionary that stores runtime-dispatched handler ports. The interface memoizes the ports so that they are reused. We do not (yet) support stable identifiers across multiple instances of the same actor.

Instance

An actor instance. This is responsible for managing a running actor, including its full lifecycle, supervision, signal management, etc. Instances can represent a managed actor or a “client” actor that has joined the proc.

InstanceCell

InstanceCell contains all of the type-erased, shareable state of an instance. Specifically, InstanceCells form a supervision tree, and is used by ActorHandle to access the underlying instance.

InstanceReceivers

Receivers created by Instance::new that must be threaded to their respective consumers (actor loop, introspect task, etc.).

PrivateGateway

Builder state that creates a private gateway with a custom forwarder.

Proc

A proc instance is the runtime managing a single proc in Hyperactor. It is responsible for spawning actors in the proc, multiplexing messages to/within actors in the proc, and providing fallback routing to external procs.

SharedGateway

Builder state that attaches the proc to a shared gateway.

WeakInstanceCell

A weak version of the InstanceCell. This is used to provide cyclical linkage between actors without creating a strong reference cycle.

WeakProc

A weak reference to a Proc that doesn’t prevent it from being dropped.

WorkCell

Represents a single work item used by the instance to dispatch to actor handles. Specifically, this enables handler polymorphism.

Enums

StatusMessage

Actor status control-plane message.

Constants

LEGACY_LOCAL_PROC_NAME

Legacy singleton proc name used for host-local client actors.

LEGACY_SERVICE_PROC_NAME

Legacy singleton proc name used for host system actors.