feat: cygnet.follow_many — batched FK navigation (N+1 → 1 round-trip)

[Xof]

What

Adds cygnet.follow_many(db, objs, fk_column) — the batched sibling of cygnet.follow. Following an FK for a whole collection previously meant looping follow, one round-trip per object (the classic N+1). follow_many does it in one WHERE pk = ANY($1) query and re-associates the targets back to the inputs.

logs = await cygnet.SELECT(db).FROM(LogTable)
accounts = await cygnet.follow_many(db, logs, LogTable.account_id)
# accounts[i] is logs[i]'s Account — or None if the FK is NULL / row missing.

Why this, and why now

This is the driver-agnostic read-throughput lever. A prior real-PG spike measured that end-to-end read time is ~85–92% driver decode + network round-trip and the positional hydrator already captured the hydration slice — so no faster hydrator (or Rust driver) moves the ceiling. Fewer round-trips is where the win is, and N+1 FK-loading is the most common source of extra round-trips. follow_many is the explicit cure (it fits the "littlest ORM" stance — a helper, not magic lazy-loading).

The whole FK-value list binds as a single array parameter (= ANY($1)), so there's no IN-list length limit and it's plan-cache friendly.

Behavior

• Returns a list aligned to objs (input order); None for a NULL FK or a missing target row.
• Deduplicates FK values into one query; objects sharing a value share the returned instance (a batching artifact — Cygnet has no identity map).
• No query when objs is empty or every FK is None.
• Validation mirrors follow() (FK column, object types), with object-type errors taking precedence (matched to follow).

Tests & verification

• 11 unit tests (FakeDB): alignment, NULL→None, missing→None, dedup/shared-instance, empty + all-None no-query short-circuits, all validation paths, and the error-precedence guarantee.
• 1 real-PG integration test in TestFollowRoundtrip — passed locally on Dockerised PG.
• Full unit suite green (523), ruff + mypy clean.
• Adversarial review found no correctness bugs; its validation-parity finding (FK-check vs type-check ordering) is fixed in this PR and pinned by a test.

Docs

README recipe (features follow_many, plus the underlying = ANY pattern and .stream() note), THEORY synthesis paragraph (round-trips are the read ceiling; batching is the lever), ARCHITECTURE component-map symbol.