@spec add_hub_node(:ets.tid(), node()) :: [node()]

Adds a new node to the hub cluster and returns new list of nodes.

@spec announce_boot(ProcessHub.Hub.t(), integer()) :: :ok

Broadcasts this node's boot token to peers so they can reap any bindings left over from a previous incarnation. Sent once on every boot, for every backend.

@spec boot_token() :: integer()

Generates a boot token that is stable for the lifetime of the node and differs across restarts. Broadcast to peers so they can tell a restart from a flap.

@spec broadcast(module(), term()) :: :ok

Sends msg to the locally-registered process module on every cluster node, including the local node.

@spec handle_boot_announcement(ProcessHub.Hub.t(), node(), integer()) :: :ok

Handles a peer's boot announcement: purges the peer's registry bindings the first time a given token is seen (a genuine restart), and does nothing when the token is unchanged (a network flap or a duplicate announcement).

This closes the fast-restart stale-binding gap for every backend — the stale {peer, dead_pid} rows live on the local (peer) node, independent of the restarted node's :registry_backend. Purging is delete-only; the child's re-placement is handled by the normal redistribution path, and any binding wiped by a late announcement is re-asserted by the returning node's next sync.

Handles the node down event by dispatching hooks, removing nodes from cluster state, and triggering the node down update task.

Handles the node up event by dispatching hooks, adding nodes to cluster state, checking partition tolerance for quorum recovery, and triggering the node up update task.

@spec new_node?([node()], node()) :: boolean()

Returns a boolean indicating whether the node exists in the cluster.

@spec nodes(:ets.tid(), [:include_local] | nil) :: [node()]

Returns a list of nodes in the cluster.

@spec promote_to_node(ProcessHub.Hub.t(), node()) :: :ok | {:error, :not_alive}

Promotes the current node to a cluster node.

@spec purge_dead_nodes(ProcessHub.hub_id()) :: [node()]

Purges every node that is not part of the hub's current cluster from the process registry. Returns the list of purged dead nodes.

Delete-only, like purge_node/2; it does not redistribute. Intended for out-of-band reconcile and cold-boot replay sanitisation.

@spec purge_node(ProcessHub.hub_id(), node()) :: [ProcessHub.child_id()]

Removes every process-registry entry that references node, deleting any child entry left with no remaining locations. Returns the affected child_ids.

This is a delete-only dead-node maintenance primitive for the cases the automatic :nodedown purge does not cover — for example {dead_node, pid} rows replayed from a durable registry at cold boot, where no :nodedown event ever fires. It does not redistribute; re-placement is the caller's job.

@spec rem_hub_node(:ets.tid(), node()) :: [node()]

Removes a node from the cluster and returns new list of nodes.