Split :via callbacks into write side and read side

[twinn]

Summary

Post-review cleanup for the metadata/Registry-shaped work, plus ergonomics and type-safety work. Five commits:

1. Split :via callbacks into write side and read side. register_name/unregister_name work in both :duplicate and :unique modes. whereis_name/send (and transitively GenServer.call/cast, Process.whereis, Kernel.send on a via tuple) require keys: :unique and raise ArgumentError otherwise. In :unique mode, whereis_name is strictly local-only — no remote fallback, because per-node uniqueness means each node owns its local holder. This matches the split Elixir's Registry uses — verified against lib/elixir/lib/registry.ex directly this time instead of guessing.

2. Drop PgRegistry.get_members/2, add PgRegistry.lookup_local/2. get_members/2 was vestigial once lookup/2 existed (the bare-pid view is a one-liner: for {pid, _} <- lookup(scope, key), do: pid). lookup_local/2 is a first-class distributed-registry concern with no direct Registry analog — useful for draining a node, per-node metrics, or preferring a local instance. Layering: Pg owns pg vocabulary (get_members, get_local_members, lookup, lookup_local), PgRegistry owns Registry vocabulary (lookup, lookup_local, no get_members).

3. README positioning table: add Horde.Registry. Four-column feature comparison (Registry / :global / Horde.Registry / PgRegistry) plus a ""Which should I use?"" decision table below. Makes the split explicit: Horde owns cluster-wide unique keys, PgRegistry owns cluster-wide duplicate keys. They're complementary, not competitors. Horde's match-spec support was verified against hexdocs before claiming ""yes"" in the table.

4. Add doctests to PgRegistry public API. Spec audit first (both modules are fully spec'd on their public surface — the awk-based scan turned up only second clauses and GenServer callbacks, all covered). Then 13 new doctests across the common API: lookup/2, count/1, update_value/3, keys/2, register/3 (both modes), unregister/2, values/3, match/3, meta/2, register_name/2 (unique), whereis_name/1 (unique). Each uses a unique :doc_* scope atom to avoid cross-test collisions. Enabled via doctest PgRegistry in the test file.

5. Add dialyzer to the project and CI. dialyxir 1.4 as a dev/test dep, project-local PLT under priv/plts/ (gitignored), flags [:error_handling, :unknown, :unmatched_returns] — the strictest commonly-used set. First run caught exactly two unmatched_return warnings in sync_groups/3 and sync_one_group/4 (side-effect helpers returning lists from a for comprehension that nobody cared about). Both fixed by making them return :ok explicitly and pattern-matching at the call sites. CI workflow gains a cached PLT step and mix dialyzer --format github that runs before mix test.

Design decisions worth calling out

• :via split matches Registry. Our behaviour is within a hair of Elixir's: Registry restricts register_name to pid == self(); we allow an arbitrary local pid (inherited from Pg.join/3). Registry's send/2 pattern-matches [{pid, _}] and raises CaseClauseError on multiple entries; our send/2 goes through whereis_name and raises ArgumentError explicitly in :duplicate mode. Both are intentional small improvements, not divergences.

• lookup_local/2 is the one Registry-absent API we're keeping. Registry is single-node, so ""local"" is trivially ""all."" We're distributed, and the local subset is genuinely useful for draining/metrics/preference-for-local patterns. The _local suffix is standard OTP convention (Node.list/0 vs Node.list(:connected), :pg.get_members/2 vs :pg.get_local_members/2, etc.).

• which_groups/1 stays as-is. It's the one remaining pg-flavored name in PgRegistry. Registry has no equivalent (the idiomatic replacement is Registry.select/2 with a match-spec returning keys) and the operation is genuinely useful as a convenience. Leaving it is honest about the fact that distributed registries sometimes want things single-node registries don't.

• Dialyzer flags are deliberately strict. :unmatched_returns is the one people usually disable because of false-positive volume — we enabled it and got exactly two warnings, both legitimate. Future contributors writing side-effect-only helpers will get flagged and have to think about whether the helper should return :ok or whether the return value actually matters.

Test plan

• mix test — 13 doctests + 145 tests, 0 failures
• mix credo — clean
• mix format --check-formatted — clean (styler plugin enabled)
• mix docs — builds without warnings
• mix dialyzer — 0 errors with [:error_handling, :unknown, :unmatched_returns] flags
• CI workflow updated to run mix dialyzer --format github before mix test (format checks + dialyzer fail fast before the slowest step)
• Register/unregister_name work in both modes (new tests for the duplicate-mode path)
• Whereis_name/send raise `ArgumentError` in duplicate mode
• GenServer via integration on :unique scope includes {:already_started, pid} collision
• Horde.Registry positioning verified against hexdocs before claiming ""yes"" for match-spec support

Release note

This PR was split off main after v0.3.0 was tagged and a GitHub release created (though nothing has been published to Hex). The changes here materially affect the semantics that v0.3.0 currently points at:

• whereis_name no longer has silent local-preferred-then-remote fallback
• whereis_name/send now require :unique scopes
• get_members/2 is gone from PgRegistry
• lookup_local/2 is a new PgRegistry function

Recommended release workflow after merging: delete the existing v0.3.0 tag and GitHub release, re-tag against the new tip of main, then publish to Hex for the first time. Nothing depends on the old tag because nothing is on Hex. If you'd rather respect tag immutability, ship this as v0.3.1 — but that publishes a v0.3.0 on Hex that we already know is worse, which seems silly for an unshipped version.