From what I’ve got, the only place payload is not a map is when the first element of the tuple is :error (e.g. {:error, "File string contains annoying codepoints."}).
Then dialyzer is telling that not(is_map(payload)) will never match, as Toml.decode/1 returns {:ok, map}.
As noted above, I tried commenting out the not(is_map(payload)) clause and it just fails on the Enum.empty?(payload) clause. So something else is borked…
I rewrote it as this:
@spec filter({atom, any}, String.t()) :: map
defp filter({:error, payload}, trim_path) do
IO.puts("\nIgnored: " <> trim_path)
IO.puts("Because: " <> inspect(payload))
%{}
end
defp filter({_status, payload}, trim_path) do
payload
end
And dialyzer still failed:
apps/info_toml/lib/info_toml/parser.ex:86:pattern_match_cov
The pattern
{__status, _payload}, _trim_path
can never match since previous clauses completely cover the type
{:error, binary()}, binary()
This means dialyzer considers it will always return {:error, "..."}, so never succeed with an {:ok, map}. 
Then it’s probably a bug in the toml library. If someone runs dialyzer there is it without warnings or errors?
In an effort to follow your advice, I extracted the module into a separate Mix project and ran Dialyzer on it. This reproduced the problem, so I started trimming out various parts of my code.
Although I haven’t found the bug yet, it appears to be in my own code, rather than the Toml library. I’ll report back once I know more…
After trying a few versions, I discovered bugs in a couple of @spec lines, further down in my code. For example:
@spec parse_h1(s, atom) :: map|{atom, s}
when s: String.t
should have been:
@spec parse_h1(s, atom) :: {atom, map|s}
when s: String.t
I think the main lessons from this are that
Anyway, thanks to everyone for your help!