Module introspect

hyperactor_mesh

Module introspect 

Source
Expand description

Introspection attr keys — mesh-topology concepts.

These keys are published by HostMeshAgent, ProcAgent, and MeshAdminAgent to describe mesh topology (hosts, procs, root). Actor-runtime keys (status, actor_type, messages_processed, etc.) are declared in hyperactor::introspect.

See hyperactor::introspect for naming convention, invariant labels, and the IntrospectAttr meta-attribute pattern.

§Mesh key invariants (MK-*)

  • MK-1 (metadata completeness): Every mesh-topology introspection key must carry @meta(INTROSPECT = ...) with non-empty name and desc.
  • MK-2 (short-name uniqueness): Covered by test_introspect_short_names_are_globally_unique in hyperactor::introspect (cross-crate).

§Attrs invariants (IA-*)

These govern how IntrospectResult.attrs is built in hyperactor::introspect and how properties is derived via derive_properties.

  • IA-1 (attrs-json): IntrospectResult.attrs is always a valid JSON object string.
  • IA-2 (runtime-precedence): Runtime-owned introspection keys override any same-named keys in published attrs.
  • IA-3 (status-shape): status_reason is present in attrs iff the status string carries a reason.
  • IA-4 (failure-shape): failure_* attrs are present iff effective status is failed.
  • IA-5 (payload-totality): Every IntrospectResult sets attrs – never omitted, never null.

§Attrs view invariants (AV-*)

These govern the typed view layer (*AttrsView structs).

  • AV-1 (view-roundtrip): For each view V, V::from_attrs(&v.to_attrs()) == Ok(v) (modulo documented normalization/defaulting).
  • AV-2 (required-key-strictness): from_attrs fails iff required keys for that view are missing.
  • AV-3 (unknown-key-tolerance): Unknown attrs keys must not affect successful decode outcome. Concretization of IA-6.

§Derive invariants (DP-*)

  • DP-1 (derive-precedence): derive_properties dispatches on node_type first, then falls back to error_code, then status, then unknown. This order is the canonical detection chain.
  • DP-2 (derive-totality-on-parse-failure): derive_properties is total; malformed or incoherent attrs never panic and map to NodeProperties::Error with detail.
  • DP-3 (derive-precedence-stability): derive_properties detection order is stable and explicit: node_type > error_code > status > unknown.
  • DP-4 (error-on-decode-failure): Any view decode or invariant failure maps to a deterministic NodeProperties::Error with a malformed_* code family, without panic.

§Open-row invariant (IA-6)

  • IA-6 (open-row-forward-compat): View decoders ignore unknown attrs keys; only required known keys and local invariants affect decoding outcome. Concretized by AV-3.

Structs§

ErrorAttrsView
Typed view over attrs for an error node.
FailureInfo
Structured failure information for failed actors.
HostAttrsView
Typed view over attrs for a host node.
NodePayload
Uniform response for any node in the mesh topology.
ProcAttrsView
Typed view over attrs for a proc node.
RootAttrsView
Typed view over attrs for a root node.

Enums§

NodeProperties
Node-specific metadata. Externally-tagged enum — the JSON key is the variant name (Root, Host, Proc, Actor, Error).

Statics§

ADDR
Host network address (e.g. “10.0.0.1:8080”).
FAILED_ACTOR_COUNT
Count of failed actors in a proc.
IS_POISONED
Whether this proc is refusing new spawns due to actor failures.
NODE_TYPE
Topology role of this node: “root”, “host”, “proc”, “error”.
NUM_ACTORS
Number of actors in a proc.
NUM_HOSTS
Number of hosts in the mesh (root only).
NUM_PROCS
Number of procs on a host.
PROC_NAME
Human-readable proc name.
STARTED_AT
Timestamp when the mesh was started.
STARTED_BY
Username who started the mesh.
STOPPED_CHILDREN
References of stopped children (proc only).
STOPPED_RETENTION_CAP
Cap on stopped children retention.
SYSTEM_CHILDREN
References of system/infrastructure children.

Functions§

derive_properties
Derive NodeProperties from a JSON-serialized attrs string.
to_node_payload
Convert an internal IntrospectResult into an API-facing NodePayload by deriving properties from attrs. Convert an IntrospectResult to a presentation NodePayload with properties derived from attrs.
to_node_payload_with
Convert an IntrospectResult to a NodePayload, overriding identity and parent for correct tree navigation.