refactor(client): route cancel_timer/fetch_unprocessed through the client seam

[lesnik512]

What

Moves cancel_timer and fetch_unprocessed off the broker's inline SQL and onto the AbstractOutboxClient seam, so the client is the single owner of outbox-table SQL. The broker methods become thin delegations.

From the architecture-deepening review (candidate #3). Previously table/column knowledge was split three ways — producer (insert+NOTIFY), client (lease/DLQ), and broker-inline (delete(t) / select(*t.c) on self._outbox_table). Now it lives behind one seam.

Changes

• client.py — two new methods on AbstractOutboxClient + OutboxClient impls (SQL + both input guards moved verbatim). fetch_unprocessed co-locates with _row_to_message.
• Guards in the client adapters (design decision) — the broker delegation is a pure passthrough, matching how publish validates. Real client raises TypeError/ValueError; fake ignores session (del session) and mirrors the limit guard. A directly-constructed OutboxClient now enforces the contract itself.
• broker.py — both methods reduced to return await self.client.<method>(...); drops the delete/select/_row_to_message imports.
• testing.py — FakeOutboxClient gains fetch_unprocessed and an aligned cancel_timer; the _build_fake_cancel_timer/_build_fake_fetch_unprocessed builders + their two mock.patch.object lines are deleted — the test broker already swaps in the fake as broker.client, so delegation reaches it. (publish/publish_batch stay patched — they drive sync dispatch.)

Behavior change (deliberate)

The test broker's session arg goes from runtime-optional (the deleted patch defaulted it to None) to required-but-ignored, matching the client signature. This aligns runtime with what was always true at the type level (old test calls carried # ty: ignore[missing-argument]) and with the documented public signature (docs/usage/timers.md). No documented usage omitted session.

Promotion

architecture/test-broker.md + docs/usage/testing.md updated (the two methods delegate through the swapped fake client; session required). Lightweight change file added.

Verification

• just test — 599 passed, Postgres 17, coverage 100.00%
• just lint — ruff + ty clean
• just check-planning — OK
• mkdocs build --strict — clean

🤖 Generated with Claude Code