@spec child_data_alter() :: atom()

Hook triggered right before the supervisor starts the child process.

This is an alter hook used to modify child process data before it is started.

Data: map() (the child data map, returned modified)

@spec child_pid_updated() :: atom()

Hook triggered right after process has been restarted by local supervisor and the pid has been updated.

Data: %{node: node(), pid: pid()}

@spec child_registered() :: atom()

Hook triggered when a new process is registered in the ProcessHub registry.

Data: %{child_id: child_id(), node_pids: [{node(), pid()}]}

@spec child_unregistered() :: atom()

Hook triggered when a process is unregistered from the ProcessHub registry.

Data: %{child_id: child_id()}

@spec children_forwarded() :: atom()

Hook triggered when children are forwarded to other nodes during migration or when stop requests are redirected to the actual node hosting the child.

Data: %{forwards: [{node(), [map()]}]}

@spec coordinator_shutdown() :: atom()

Hook triggered inside the coordinator terminate/2 function.

Data: %{reason: any()}

Consumed by: :ch_shutdown (ConsistentHashing), :mhs_shutdown (HotSwap), :mcs_shutdown (ColdSwap)

@spec drain_completed() :: atom()

Hook dispatched when a node drain completes, including deadline-forced completion.

Data: %{migrated: non_neg_integer(), forced: non_neg_integer()}

@spec handover_delivered() :: atom()

Hook dispatched when handover states have been delivered to migrated processes.

Data: %{child_ids: [child_id()], target_node: node()}

@spec migration_completed() :: atom()

Hook triggered when the migration handler has finished processing. This does not indicate whether the migration has completed.

Data: %{nodes: [node()], child_specs: [child_spec()]}

@spec migration_deferred() :: atom()

Hook dispatched when children are added to the deferred-migration list because they deferred (or did not answer) a migration consent query.

Data: %{child_ids: [child_id()]}

@spec post_children_start() :: atom()

Hook triggered right after the children of a process are started.

Data: %{children: [%{child_id: cid, pid: pid, result: result, nodes: [node()], child_spec: spec, metadata: map()}]}

Consumed by: :rr_post_start (Replication strategy), :mhs_process_startups (HotSwap), :mcs_process_startups (ColdSwap)

@spec post_node_join() :: atom()

Hook triggered when a new node has joined the hub cluster and after handling the node join event.

Data: %{node: node()}

@spec post_node_leave() :: atom()

Hook triggered when a node has left the hub cluster and after handling the node leave event.

Data: %{node: node()}

@spec post_recovery_replay() :: atom()

Hook dispatched once when the coordinator leaves :recovering (whether via completion or via the :recovery_timeout_ms safety path). Async.

Part of the experimental boot-recovery feature; may change in future releases.

Data: %{hub_id: atom(), child_count: non_neg_integer(), succeeded: non_neg_integer(), failed: non_neg_integer(), reason: atom()}

@spec post_redistribution() :: atom()

Hook triggered after processes are redistributed.

Data: %{event: :node_join | :node_leave, nodes: [node()]}

@spec pre_children_redistribution() :: atom()

Hook triggered before redistribution of children is called.

This is only called with node addition or removal from the cluster.

Data: %{children: list(), event: :node_leave, node: node()}

Consumed by: :rr_post_update (Replication strategy)

@spec pre_children_start() :: atom()

Hook triggered before the children of a process are started.

Data: %{request: request, hub: hub}

Consumed by: :dg_pre_start_handler (Guided distribution strategy)

@spec pre_node_join() :: atom()

Hook triggered when a new node has joined the hub cluster and before handling the node join event.

Data: %{node: node()}

@spec pre_node_leave() :: atom()

Hook triggered when a node has left the hub cluster and before handling the node leave event.

Data: %{node: node()}

@spec pre_recovery_replay() :: atom()

Hook dispatched once when the coordinator enters :recovering, before any start_children is dispatched. Part of the experimental boot-recovery feature; may change in future releases. This hook is dispatched synchronously — the coordinator awaits each registered handler's reply before proceeding, so handlers may block on prerequisite-service readiness.

Handlers should return quickly. Long blocks risk forcing the :recovery_timeout_ms safety path. Crashes inside handlers are caught and logged; replay proceeds regardless.

Data: %{hub_id: atom(), child_count: non_neg_integer()}

@spec pre_redistribution() :: atom()

Hook triggered before processes are redistributed.

Data: %{event: :node_join | :node_leave, nodes: [node()]}

@spec recovery_state_changed() :: atom()

Hook dispatched on every coordinator recovery-lifecycle moment when the hub has opted into :auto_recovery. This is the single observability surface for the lifecycle. Moments:

• :init → :recovering (reason: :marker_absent) — boot enters replay.
• :init → :normal (reason: :marker_present) — boot skips replay.

• :recovering → :normal (reason: :replay_complete | :recovery_timeout).

Part of the experimental boot-recovery feature; may change in future releases.

Data: %{hub_id: atom(), from: atom(), to: atom(), reason: atom(), measurements: map()} where measurements carries the per-moment counts (e.g. cspec_count, succeeded, failed, skipped, elapsed_ms).

@spec scoreboard_updated() :: atom()

Hook dispatched when the centralized load balancer scoreboard is updated.

Data: %{scoreboard: term(), node: node()}