@spec candidates(pid(), :tool | :resource, String.t()) :: [definition()]

Returns definitions matching one wire-level tool name or exact resource URI.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec fetch(pid(), primitive(), term()) :: {:ok, definition()} | :error

Returns one normalized definition without copying the complete catalog.

@spec list(pid(), primitive()) :: [definition()]

Returns definitions for one category in deterministic identity order.

@spec register(pid(), primitive(), String.t(), map() | keyword()) ::
  :ok | {:error, term()}

Validates and registers one primitive, rejecting duplicate identities.

@spec register_all(pid(), [registration()]) ::
  {:ok, [{primitive(), String.t(), definition()}]} | {:error, term()}

Validates and registers a batch atomically, returning its normalized definitions.

@spec replace_all(pid(), [registration()]) ::
  {:ok, %{required(primitive()) => %{optional(term()) => definition()}},
   [primitive()]}
  | {:error, term()}

Validates and atomically replaces the complete primitive catalog.

@spec revision(pid()) :: non_neg_integer()

Returns the monotonic catalog revision used for invalidation and recovery.

@spec snapshot(pid()) :: %{
  required(primitive()) => %{optional(term()) => definition()}
}

Returns all normalized definitions grouped by primitive category.

@spec start_link(keyword()) :: GenServer.on_start()

Starts the registry; registration is serialized through this process.