@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 declared_parked() :: atom()

Alarm-grade hook dispatched when a hub's declared list is missing or corrupt while durable evidence of declared children exists and no remote manifest copy could restore it. The hub's reconcile is parked — no child is started or stopped by it — until an operator intervenes.

Part of the experimental declared-children feature; may change in future releases.

Data: %{hub_id: atom(), reason: atom()}

@spec declared_tiebreak() :: atom()

Hook dispatched when two declared-list copies carry the same version with different content and the deterministic tiebreak (lexicographically lowest mutating node) resolves them. Reachable only when both partition sides mutated the list under a non-locking partition strategy.

Part of the experimental declared-children feature; may change in future releases.

Data: %{hub_id: atom(), version: pos_integer(), kept_mutated_by: node(), discarded_mutated_by: node()}

@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 manifest_ship_failed() :: atom()

Hook dispatched when shipping the declared list to the configured remote manifest adapter fails. The originating command already committed locally; the shipper retries with backoff.

Part of the experimental declared-children feature; may change in future releases.

Data: %{hub_id: atom(), version: pos_integer(), error: term(), attempt: pos_integer()}

@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 per coordinator lifetime, after the first orphan reconcile round completes (whether or not it started anything). 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 per coordinator lifetime, before the first orphan reconcile round issues any start. 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; the per-handler budget is bounded by :reconcile_interval_ms. Crashes inside handlers are caught and logged; the round proceeds regardless. Subsequent rounds do not re-fire it — per-round observability is reconcile_round/0.

Data: %{hub_id: atom(), child_count: non_neg_integer()} where child_count is the durable candidate count for the round.

@spec pre_redistribution() :: atom()

Hook triggered before processes are redistributed.

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

@spec reconcile_duplicate() :: atom()

Hook dispatched by the node that stops its own instance of a child observed running on more than one node. The instance on the child's ring owner is kept; when no observed instance is on the owner, the lexicographically lowest node name is kept.

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

Data: %{hub_id: atom(), child_id: term(), instance_count: pos_integer(), kept_node: node(), stopped_nodes: [node()]}

@spec reconcile_round() :: atom()

Hook dispatched at the end of every orphan reconcile round, including rounds that find nothing — a silent reconcile stays distinguishable from a stalled one.

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

Data: %{hub_id: atom(), first_round: boolean(), measurements: map()} where measurements is %{candidates, orphans, started, skipped_pending, duplicates, elapsed_ms}.

@spec recovery_state_changed() :: atom()

Hook dispatched on every coordinator :recovery_state transition when the hub has opted into :auto_recovery. The only transition is :recovering → :normal (reason: :reconcile_complete), fired when the first orphan reconcile round completes.

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 first round's counts (candidates, orphans, started, duplicates, elapsed_ms).

@spec scoreboard_updated() :: atom()

Hook dispatched when the centralized load balancer scoreboard is updated.

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