@spec available?() :: boolean()

true se as deps Horde estão compiladas/carregáveis neste runtime.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec distributed_context?() :: boolean()

Gate de ativação do modo distribuído: Horde disponível e nó vivo (Node.alive?()). Sob ExUnit normal (sem :net_kernel) é false, então uma instância distribution: :horde degrada para a árvore local de hoje.

@spec ensure_started(MeliGraph.Config.t()) ::
  {:ok, pid() | :ignore} | {:error, term()}

Garante que a árvore do grafo está iniciada em algum nó do cluster.

Chamado por todos os nós no boot; o Horde.UniformDistribution elege um único dono por name. Os demais recebem {:error, {:already_started, _}}, tratado como sucesso (convergência).

O child id é estável ({MeliGraph.Supervisor, name}) e não inclui o conf — caso contrário nós com on_ready/timeout diferentes gerariam ids distintos e o Horde subiria duas árvores para o mesmo grafo. Contrato: todos os nós chamam start_link com opts idênticos por name.

@spec lookup_owner(atom()) :: {:ok, pid(), MeliGraph.Config.t()} | :error

Descobre o nó dono de um grafo via Horde.Registry.

Retorna {:ok, pid, conf} (com node(pid) = dono) ou :error se a entrada ainda não propagou (a janela de consistência é tratada com retry no Router).

@spec reap_local(pid()) :: :ok

Reapa (encerra) a árvore local pid de uma instância duplicada.

Chamado pelo MeliGraph.Reconciler quando detecta que este nó hospeda uma árvore "zumbi": viva localmente, porém o Horde.Registry (árbitro :unique, forte e convergente) aponta o dono num outro nó vivo. Caminho normal: a duplicata foi posta aqui pelo Horde.DynamicSupervisor numa corrida de boot/split, então terminate_child/2 a remove do supervisor e do CRDT sem reinício (id estável + restart: :transient). Fallback {:error, :not_found}: a árvore não é (mais) um filho do Horde — encerra direto via Supervisor.stop/3.

Idempotente e tolerante a corridas: o pid pode já ter morrido entre a detecção e o reaping, e o Horde.DynamicSupervisor pode estar momentaneamente indisponível (re-tenta no próximo tick).

@spec register_owner(MeliGraph.Config.t()) :: :ok

Registra o processo chamador como dono de conf.name no Horde.Registry, com o %Config{} como metadata.

Chamado pelo ConfigHolder no seu init/1 (no nó dono). Ligar a entrada ao ciclo de vida do ConfigHolder garante que, no failover, quando a árvore cai, o deltacrdt dropa a entrada stale e o novo dono re-registra. Tolera `{:error, {:already_registered, }}` (reentrância benigna).

@spec registry_name() :: module()

Nome fixo do Horde.Registry de descoberta.

@spec supervisor_name() :: module()

Nome fixo do Horde.DynamicSupervisor que hospeda os grafos.