@spec default_dir() :: Path.t()

The real registry directory: a local cache under the OS user-cache directory, NOT this package's own priv/plugins/ — archives are downloaded on demand (Capstone.Plugin.Remote.sync!/3) rather than shipped inside the hex package, so this stays a plain path and performs no I/O of its own.

@spec resolve!(atom(), String.t(), String.t(), Path.t()) :: Path.t()

Resolves type to the best matching, non-retired archive in registry_dir.

Filters to type matches, then to archives whose Elixir segment shares major.minor with elixir_version, drops retired filenames, drops any whose capstone segment exceeds capstone_version, then picks the highest surviving capstone segment (ties broken by the sha, purely so this stays a pure function of its inputs and the directory listing).

A filename that does not parse — wrong segment count, or a segment that is not a version — is reported with Mix.shell().info/1 and skipped, never raised on.

Raises Mix.Error, naming type and both versions, when nothing survives.

@spec retire!(String.t(), Path.t()) :: :ok

Retires filename in registry_dir's retired.exs, creating the ledger if it does not exist yet. Idempotent: retiring an already-retired filename changes nothing.