Module proc 

Proc is an addressable actor-runtime boundary.

It owns actor lifecycle (spawn, run, terminate), routes messages to local actors, forwards messages for remote destinations, and hosts supervision state.

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 work items enqueued for handler execution but not yet received from work_rx.
• PD-5b: Queue depth is incremented exactly once on every enqueue into the actor work queue (in HandlerPorts::get).
• 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.

AttachRequest

Sentinel message sent by an attach client as its first MessageEnvelope. Hosts use this to distinguish attach requests from regular inbound MessageEnvelope connections.

AttachRx

Rx<MessageEnvelope> adapter that unwraps Host2Client::Envelope from a duplex receiver.

BootstrapAssignment

Identity assignment sent by a host as the first message on a duplex attach connection. The child reads this to learn its ProcAddr.

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

Host2Client

Wire protocol for the host -> client direction on a duplex attach connection.

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.