refactor(ratings): drive both stages through the shared executor

[thodson-usgs]

What

Moves get_ratings onto the shared transport machinery: the STAC search's page walk now drives transport.pagination.paginate as a one-item FanOut, and the per-feature RDB downloads fan out over the feature list itself (a plain list satisfies FanOutPlan — ADR 0008 — no adapter class needed). stats.py's one-item fan-out was the template.

Why

Four page walks existed in the package; three went through paginate. The fourth was ratings' hand-rolled synchronous loop, and its per-feature downloads were a serial for-loop of N sequential GETs — so ratings alone had no per-attempt retry, no stall budget, no progress line, no resumable interruption, and no bounded concurrency. Deleting the bespoke loop concentrates pagination in the one home transport already owns.

Behavior changes (deliberate — flagging for review)

1. The failure policy for per-feature downloads is now split by whether retrying could help. Previously every per-feature failure — including a 429 rate limit — was logged at warning level (invisible unless logging was configured) and the rating silently dropped from the result dict. Now:
   • A transient failure (429 / 5xx / timeout / connection drop) is retried per API_USGS_RETRIES and then raised as a resumable interruption. Rate limiting is systematic — once it starts, every remaining download fails — so silently skipping was the old behavior's worst case.
   • A deterministic per-feature failure (a stale catalog entry 404ing, a feature with no data asset, a malformed RDB) is skipped under a new SkippedRatingWarning naming the feature; the rest of the batch is returned. One bad catalog entry shouldn't cost every other site's rating. The warning is visible by default and warnings.filterwarnings("error", category=SkippedRatingWarning) restores strict all-or-nothing.
   • An OSError writing file_path propagates — a local disk problem is not a per-feature condition (the old skip was overbroad here).
   • A site with no published rating (or a nonexistent site) is unchanged: it matches no feature in the search, so it is simply absent from the dict — no warning, no error.
2. A mid-search 429 surfaces as a resumable QuotaExhausted (parity with every other getter) instead of a raw RateLimited. exc.call.resume() finishes the interrupted stage; since get_ratings returns a dict rather than (df, md), the assembled per-feature dict comes from a fresh call — documented in the docstring.
3. Downloads now run concurrently, bounded by API_USGS_CONCURRENT, instead of serially.

Unchanged: the next-link cross-host/credential policy still goes through resolve_next_url (both existing safety tests pass untouched), headers are still evaluated per asset href (test updated to the new seam), and the wire behavior of search parameters is identical.

Testing

• Full offline suite: 786 passed — includes the resumable-search test plus four new failure-policy tests (deterministic 404 warns and skips, keeping the rest of the batch; missing data asset warns and skips; the warning escalates to an error under filterwarnings("error"); a download 429 raises resumable and provably never skips), and a fitness function pinning that ratings can no longer import the executing sync transport helpers (alongside the existing wateruse rule).
• mypy --strict, ruff, xenon, complexipy, lint-imports all pass.

Independent of #367/#368 (branches off main).

🤖 Generated with Claude Code

[thodson-usgs]

Health metrics vs main

Same method as on #367/#368 (pyscn 1.29.0 / radon / xenon / complexipy / import-linter, isolated worktrees, ProjectRoot verified).

pyscn composite: 82/100 (B) — unchanged; all seven sub-scores identical to main. But this is the one of the three branches that moves the complexity averages in the right direction:

	main	this PR
Average cyclomatic complexity	2.377	2.359
Average cognitive complexity	5.893	5.823
Average nesting depth	1.055	1.035
High-risk entries	19	19
Modules	57	57
Resolved dependency edges	140	142
Functions	363	368
Package LOC (non-blank)	13,090	13,140

Where it comes from

get_ratings was the most complex function in the file and the only medium-risk entry among everything these three PRs touch:

get_ratings   cyclomatic 11 (medium) → 9 (low)     cognitive 14 → 11
_search       cyclomatic  5 (low)    → 4 (low)     cognitive  9 →  9

The retry/paging/failure-handling that inflated it now lives behind paginate/FanOut instead of in the adapter. The five new entries (_fetch_rating = 4, _download_all = 2, and three closures at 1) are all low-risk, which is why the file grew ~50 lines while the package's averages fell.

Also up: architecture compliance 87.1% → 87.3% (banded score stays 87), and the +2 dependency edges are transport.pagination / transport.fanout / transport.retry replacing the direct transport.http sync calls — the intended direction under ADR 0006.

Duplication is unchanged at 8.83% (clone groups 5, pairs 50, total clones 25 — identical), so the new fan-out code introduced no clone of the existing wateruse/stats fan-out shapes.

One regression worth naming: waterdata/ratings.py maintainability index 63.3 → 61.3 (still rank A). That is the file growing; the per-function complexity above is the better read of whether it got harder to work on.

Merge gates (xenon, complexipy, lint-imports, mypy --strict): pass. 783 tests pass offline.

Reminder that the behavior changes in the PR description — removed log-and-skip swallow, search 429 becoming a resumable QuotaExhausted, concurrent downloads — are the substantive review surface here; the metrics are the easy part.