@spec collect_states([ProcessHub.child_id()], non_neg_integer(), list(), atom()) ::
  list()

Generic state collection with configurable response message atom.

ColdSwap uses :coldswap_state, HotSwap uses :hotswap_state.

@spec compute_processable(ProcessHub.Hub.t(), map()) :: {map(), map(), map()}

Computes processable children for migration during topology expansion.

Gets migration candidates, calculates distribution, populates handler.calculated_cids, and categorizes children into %{stop_local: [...], forward_to: [...]}.

Returns {handler, processable, migration_candidates}.

@spec create_migration_requests(
  ProcessHub.Hub.t(),
  %{required(node()) => [{ProcessHub.child_spec(), map()}]},
  ProcessHub.Request.PostAction.t() | nil
) :: [ProcessHub.Request.Handler.StartChildrenRequest.t()]

Creates StartChildrenRequest.for_migration for each node group.

post_action is nil or a PostAction struct.

@spec dispatch_migration_hook(ProcessHub.Hub.t(), [ProcessHub.child_spec()], [node()]) ::
  :ok

Dispatches Hook.migration_completed() if migrated list is non-empty.

@spec group_children_by_node([{ProcessHub.child_spec(), map(), [node()]}]) :: %{
  required(node()) => [{ProcessHub.child_spec(), map()}]
}

Groups [{cspec, meta, target_nodes}] into %{node => [{cspec, meta}]}.

@spec handle_contraction(ProcessHub.Hub.t(), map()) :: map()

Full contraction logic (identical for both strategies).

Uses pre-calculated handler.calculated_cids to start children locally that should now be PRIMARY on the local node.

@spec handle_process_startups(ProcessHub.Hub.t(), list(), atom(), atom()) :: nil

Handles delivery of pre-sent shutdown states when processes start on the target node.

Parameters:

• hub - the hub struct
• cpids - list of %{cid: child_id, pid: pid} structs from process_startups hook
• storage_key - ETS key where shutdown states are stored
• delivery_msg - atom for delivery message (e.g. :coldswap_handover)

@spec handle_shutdown(
  ProcessHub.Hub.t(),
  non_neg_integer(),
  atom(),
  atom(),
  module(),
  String.t()
) :: :ok

Handles graceful shutdown by querying states from all local processes and sending them to target nodes before this node goes down.

Parameters:

• hub - the hub struct
• timeout - state query timeout in ms
• query_msg - atom to send to processes (e.g. :query_cold_handover_state)
• response_msg - atom expected in response (e.g. :coldswap_state)
• callback_mod - module containing handle_storage_update/2 for remote cast
• log_prefix - string for timeout log messages (e.g. "ColdSwap")

@spec handle_storage_update(ProcessHub.Hub.t(), list(), atom()) :: :ok

Stores received shutdown state data on the target node.

Called via GenServer.cast from the shutting-down node.

@spec notify_originating_node(
  ProcessHub.Hub.t(),
  [ProcessHub.Request.Handler.StartChildrenRequest.PostStartData.t()],
  node(),
  [ProcessHub.child_id()],
  module(),
  atom()
) :: :ok

Shared post-action logic on target node.

Filters successfully started children, sends callback to originating node.

@spec send_start_requests(ProcessHub.Hub.t(), [
  ProcessHub.Request.Handler.StartChildrenRequest.t()
]) ::
  :ok

Sends start requests via Dispatcher if non-empty.