Maybe. The problem with MapSet imo is less how opaque types work though, it’s that MapSet is not actually meant to be a full opaque type.

MapSets being a struct is a stable contract. Only all the other keys on the map are considered implementation details. That’s a usecase dialyzer is not able to handle – partial opaqueness in maps per key. If MapSets would be a opaque datastructure in the sense dialyzer treats it then you’d never see any documentation matching on it being a struct in the first place or any other reference to it’s underlying datatype.

E.g. I’d never check if a tid is a valid ets tid. I don’t even know what to check it by. I just use it as one and if it blows up it might have not been.

It seems like this is a known limitation of Dialyzer

What I said about pattern-matching on a struct that is defined as an opaque type is correct in theory, but in practice it seems that Dialyzer does not follow this logic correctly in certain situations.

To be precise: An opaque type hides even the fact whether something is a struct or not. (The Erlang/Dialyzer type system, which Elixir inherited, does not treat structs differently from maps.) Thus the pattern match is not strictly allowed. This makes the MapSet.t type impossible to use in combination with any pattern-match.

Personally I’d keep the runtime check (because it is enforced rather than opt-in), and change the @spec to use %MapSet{optional(any) => any()} instead.

This is a good question. The pattern match you are doing, on %MapSet{}, is indeed the correct way to ensure that only MapSet-structs can be passed to the function. It is OK to patternmatch on it. It is only wrong to match on any particular fields the struct may or may not have (as these may change in future versions without warning).
This is the same for all opaque structs (and in this case mentioned explicitly at the end of the module’s documentation as well.)

Furthermore, your spec, using MapSet.t(any), is correct. It is an opaque type (so you’re not supposed to depend on its details), but internally it also is the same as a %MapSet{}-struct.

I’m not immediately seeing where the problem of Dialyzer comes from. What you could try, is to just use the type MapSet.t() instead of MapSet.t(any). It means the same, but maybe it confuses Dialyzer less in this situation?