[BUG]: LocatedHeaderDir is mutable, so callers can poison the cached header-directory lookup

Start at the LocatedHeaderDir definition and the locate_nvidia_header_directory() and find_nvidia_header_directory() entry points. Compare the implementation with _static_libs/find_static_lib.py and _static_libs/find_bitcode_lib.py, then run the cuda.pathfinder tests. Done means the result is immutable and hashable without changing the lookup behavior.

Component

cuda.pathfinder

What happened?

locate_nvidia_header_directory() is @functools.cache-backed and returns LocatedHeaderDir, which is a plain (mutable) dataclass. The cache hands every caller the same object, so a write to abs_path on a returned instance changes what every later lookup of that libname returns for the rest of the process, including through the find_nvidia_header_directory() wrapper.

LocatedHeaderDir is also the only one of the three public Located* return types that behaves this way: LocatedStaticLib (_static_libs/find_static_lib.py) and LocatedBitcodeLib (_static_libs/find_bitcode_lib.py) are both @dataclass(frozen=True). As a side effect of not being frozen, LocatedHeaderDir is also unhashable, so it cannot be put in a set or used as a dict key the way its two siblings can.

Reproduction

from cuda.pathfinder import locate_nvidia_header_directory, find_nvidia_header_directory

first = locate_nvidia_header_directory("cudart")
print(first.abs_path)                                # e.g. /usr/local/cuda/include

first.abs_path = "/somewhere/else"                   # caller "normalizes" the result in place

print(locate_nvidia_header_directory("cudart").abs_path)  # /somewhere/else
print(find_nvidia_header_directory("cudart"))             # /somewhere/else

>>> LocatedHeaderDir.__dataclass_params__.frozen, LocatedHeaderDir.__hash__ is not None
(False, False)
>>> LocatedStaticLib.__dataclass_params__.frozen, LocatedStaticLib.__hash__ is not None
(True, True)
>>> LocatedBitcodeLib.__dataclass_params__.frozen, LocatedBitcodeLib.__hash__ is not None
(True, True)

Suggested fix

Make LocatedHeaderDir @dataclass(frozen=True) so it matches the other two public Located* types. The __post_init__ path normalization then needs object.__setattr__. Nothing inside cuda_pathfinder or its tests mutates a LocatedHeaderDir, so this is contained to the public type's contract.