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

• Dialyzer errors can be quite misleading about specifics.
• Small code bases simplify testing and reduce confusion.
• Divide and conquer is (as always) a powerful technique.

Anyway, thanks to everyone for your help!

Test files are just plain elixir scripts, which are executed on demand by the test runner. The only thing different to arbitrary elixir scripts is their folder + naming schema (*_test.exs). They‘re not part of your compiled codebase even when running with MIX_ENV=test, which is why dialyzer doesn‘t act on them.

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}.