feat: split the connection factory into plan + failover loop

[lesnik512]

What & why

Delivers candidate 2 from the architecture review. build_connection_factory was one 79-line closure that entangled pure URL-parse/host-ordering with async connect+failover, and wrote asyncpg.connect(...) twice. This splits it:

• build_connection_plan(url) -> ConnectionPlan — the pure parse phase (no I/O), returning a frozen/slotted ConnectionPlan (connect_args, target_session_attrs, primary_host/primary_port, failover pairs). Internal seam — not in __all__.
• build_connection_factory — a thin loop that builds the plan once and routes both the primary and per-host attempts through a single _connect helper (the one asyncpg.connect call).

Behaviour-preserving: same connect kwargs, same two-stage strategy, same exceptions, same log strings, same parse-once timing, and the same two shuffle lifetimes (bulk order shuffled once at build; failover re-shuffled per connection via _reshuffled).

Wins (in the design vocabulary)

• Pure planning is testable without mocking asyncpg.connect — the bug-prone host/port pairing (zip(strict=True) + shuffle + split) now has direct, mock-free coverage.
• Connect call written once — _connect is the sole call site.
• The loop shrinks to the genuine I/O concern; build_connection_factory's public signature is unchanged.

Changes

• db_retry/connections.py — ConnectionPlan + build_connection_plan + _connect + _reshuffled; factory rewritten as the thin loop.
• tests/test_connection_factory.py — two mock-free plan tests (order-independent pairing/branch assertions); the four loop tests kept (orchestration coverage).
• architecture/connections.md — promoted to the split.
• Full-lane bundle planning/changes/2026-06-26.03-connection-plan-split/.

Verification

• just test (Docker Postgres) → 27 passed, 100% coverage
• just lint-ci → clean; just check-planning → planning: OK
• Built test-first (TDD); executed via subagent-driven-development with per-task spec+quality reviews and an Opus final whole-branch review (Ready to merge: Yes, no Critical/Important).

🤖 Generated with Claude Code