[simoncocking]

Follows #3. Requires a coordinated change in consuming applications — see Migration below.

The problem

List broadcasts sent a shape that was backwards from every other one in the library, and which changed depending on how many items you passed:

PubSub.broadcast([post], :archived)        # => {:archived, post}
PubSub.broadcast([post, other], :archived) # => [{post, :archived}, {other, :archived}]

A single struct sends {event, subject}. A one-element list was special-cased and delegated to the element, so it sent that too. Two elements sent an inverted, per-item form. Whether a consumer saw one shape or the other depended on how many rows a query happened to return.

The cost was paid in every consumer: two handlers per event, kept in step by hand.

The change

One shape, regardless of cardinality:

PubSub.broadcast(posts, :archived)              # => {:archived, posts_on_that_channel}
PubSub.broadcast(posts, :archived, %{by: id})   # => {:archived, posts_on_that_channel, %{by: id}}

The subject sits where it sits for a single struct, with a list in it.

Batching is unchanged, and deliberately so — it is the reason the List implementation exists. Items are still grouped by channel, still one message per channel, still carrying only that channel's items. A receiver still gets everything for its channel in a single message and can batch the work. Only the nesting differs; consumers stop having to Enum.map(&elem(&1, 0)) before they can use it.

Two things the new shape required or exposed

Schema-level handlers would have stopped firing. The Tuple dispatcher unpacks {event, items}, resolves the List implementation for the subject, and calls handle_info/3 — which List inherited as the injected pass-through. Without new clauses, a batch would arrive at the LiveView but never reach any per-struct handler. Any schema that defines one relies on this happening. List.handle_info/3,4 now reduce over the items, calling each struct's own handler. This is the same silent failure mode as the bug fixed in #3, and would have been just as quiet.

{:halt, socket} was being swallowed. List.handle_info/2 took elem(1) of each result and always reported {:cont, socket}, downgrading a handler that had claimed the message. The existing test asserted the downgraded result, so it was encoding the bug; it now asserts the halt.

Event binding

Binding the event once per group rather than once per item looks like it drops a guarantee. It doesn't, and EventIsolationTest pins why.

message is a scalar argument to the call, closed over by the entry builder and applied per group, so only one event value is ever in scope. The old per-item pairing drew on that same single argument — it repeated one value N times rather than establishing anything about any item. What's gone is redundancy, not a guarantee.

Verified by mutation, not by passing: hard-binding the event in broadcast/2 fails 6 of the 12, in handle_info/3 fails 3, in broadcast/3 fails 1.

Channel isolation

ChannelIsolationTest (added in #3) had to have its assertions rewritten for the new nesting, which is exactly when such a guard gets quietly weakened. Re-verified by mutation afterwards, twice:

• broadcasting the whole list to every channel — 5 of 8 fail
• a rotation giving each channel one message of the right size belonging to a different channel — 5 of 8 fail

Only the nesting in the expected values changed, never which items appear under which channel.

Documentation fix

The moduledoc claimed "the defaults always return {:cont, socket}, so unmatched messages fall through safely." That holds only until you override something. A function defined in a use Amplified.PubSub do ... end block replaces the default of that name and arity rather than adding a clause ahead of it, so defining one handle_info/3 removes the catch-all and an unmatched event raises FunctionClauseError in the receiving LiveView.

Overriding does mean owning the whole function, but the failure lands in a process far from the schema that caused it, so it's now a warning admonition with the remedy. Pre-existing behaviour, unchanged — only the docs were wrong. OverrideTest holds it to account, including that the arities are independent: overriding handle_info/3 leaves the handle_info/4 default intact.

Migration

The two handlers collapse into one, and the unwrapping goes away:

# before
def handle_info({:archived, %Post{} = post}, socket), do: archive([post], socket)

def handle_info([{%Post{}, :archived} | _] = list, socket),
  do: list |> Enum.map(&elem(&1, 0)) |> archive(socket)

# after
def handle_info({:archived, [%Post{} | _] = posts}, socket), do: archive(posts, socket)

A handler for a bare struct broadcast (broadcast(post, :archived)) is unaffected and still matches {:archived, %Post{}}. Only broadcasts whose subject is a list or stream change.

Safety net: a caller still constructing [{item, event}, ...] doesn't have those pairs quietly treated as items and rebound to the call's event — extract_tuple/1 passes the tuple through as an item and Tuple.channel/2 raises "No channel for {...}", which is loud and names the call site. Pinned with a test.

Tests

109 passing. Clean under --warnings-as-errors.

Adds EventIsolationTest (12), OverrideTest (4), a Recorder fixture that logs every {id, event} it's dispatched so receive-side assertions are positive rather than inferred, and a Partial fixture holding the override pitfall.

Recorder is a plain defstruct rather than an Ecto.Schema like the older fixtures — it needs nothing Ecto provides, and it's now the one fixture proving use Amplified.PubSub works on a bare struct. Channel derivation is asserted against it.